feat: Add content_document_file(), content_document_url(), and other file improvements

[cpsievert]

You can now hand a text, Markdown, CSV, or code file to a chat the same way you already hand it an image or a PDF:

import chatlas as ctl

chat = ctl.ChatAnthropic()
chat.chat(
    ctl.content_document_file("q3-revenue.csv"),
    "Which region grew fastest?",
)

Previously the only way to do this was to inline the file yourself:

chat.chat(f"Which region grew fastest?\n\n{open('q3-revenue.csv').read()}")

That works, but it throws away three things the providers give you for free when the file arrives as a document rather than as prompt text: the filename (so the model can refer to it, and so multi-file prompts stay distinguishable), eligibility for Anthropic's citations, and OpenAI's spreadsheet preprocessing — it parses up to the first 1,000 rows per sheet and attaches generated header/summary metadata instead of dumping raw cells into the context.

content_document_url() does the same for a remote file, without downloading it when the provider can fetch it itself.

What each provider accepts

Document support varies more than image support does, so these helpers send what the provider can take and raise a specific, actionable error otherwise — rather than letting the API reject the request.

Input	ChatOpenAI()	ChatOpenAICompletions()	ChatAnthropic()	ChatGoogle()
.txt, .md, code files	✅	✅	✅ (sent as text/plain)	✅
.csv, .tsv, .json, .xml, .html	✅	✅	✅ (sent as text/plain)	✅
.docx, .xlsx, .doc, .xls, .rtf, .odt	✅	✅	❌ error: convert first	❌ error: convert first
Document from a URL	✅ URL passed through	⬇️ downloaded	⬇️ downloaded	⬇️ downloaded
PDF from a URL	✅ URL passed through	⬇️ downloaded	✅ URL passed through	⬇️ downloaded
image/heic, image/heif	❌ error: convert first	❌ error: convert first	❌ error: convert first	✅

The last two rows are the other two changes in this PR:

PDF URLs are no longer downloaded when the provider can fetch them itself. content_pdf_url() used to eagerly pull the bytes even though Anthropic accepts source: {type: "url"} and the OpenAI Responses API accepts file_url. That spent bandwidth and pushed requests toward Anthropic's 32 MB and OpenAI's 50 MB payload ceilings for nothing. Providers that genuinely need bytes now fetch on first use and cache the result on the content object, so a file reused across turns downloads once. Resolves the long-standing TODO in _content_pdf.py.

HEIC/HEIF images work on Gemini, which supports them natively — useful since it's what iPhones produce by default. Resizing them needs the optional pillow-heif package, and its absence now says so instead of failing obscurely.

Docs also now explain when to use content_*_file() versus chat.files.upload(), which previously read as a pure size tradeoff. The constraints that actually matter: uploads work on only three providers, and a ContentUploaded is a provider-scoped id rather than data, so a chat containing one can't be replayed elsewhere.

Notes for review

ContentPDF.data is now Optional[bytes]. A PDF may be a URL whose bytes haven't been fetched. Runtime behavior is unchanged and a validator enforces that at least one of data/url is set, but downstream type checkers will see the change. Every read site goes through a shared ensure_bytes() helper that returns non-optional bytes or raises naming the URL. _content_expand.py and _inspect.py are touched only as fallout from this.

Anthropic gets text/plain regardless of the real MIME type. Its document block has exactly one text-ish source variant (PlainTextSourceParam, whose media_type is literally "text/plain"), so any genuinely-decodable format is coerced to that on the way out while ContentDocument.mime_type keeps the accurate value for providers that want it. Binary formats get a "convert this first" error instead of a raw UnicodeDecodeError.

Why per-modality content classes instead of one generic ContentFile. Anthropic's DocumentBlockParam.source is a real union: PlainTextSourceParam wants decoded UTF-8, Base64PDFSourceParam wants base64, and URLPDFSourceParam is PDF-only with no text equivalent. Unifying would have meant a pile of mutually-exclusive nullable fields. ellmer keeps them separate too, though it has no document/audio/video content at all, so it hasn't had to answer this question.

Narrowing is done with TypeIs, not cast. Two places asserted a narrowing the type system could prove: Anthropic's media_type and content_image_url()'s membership check. Note that TypeGuard cannot express either, since it only narrows the true branch — an if is_heic_heif(x): raise guard needs the negative branch narrowed, which is what TypeIs adds. check_image_content_type_supported() returns the narrowed type rather than None, matching the raise-or-return shape of ensure_bytes().

Binary formats are labelled explicitly. .rtf/.doc/.odt/.xls would otherwise fall through the text/plain default and reach Gemini as binary bytes labelled as text. They now map to the MIME types Python's own mimetypes reports, and the Google rejection set covers all six binary formats. .ppt/.pptx are deliberately excluded — OpenAI's file-input docs don't list them.

Verified: pyright clean, ruff clean, 226 tests passing across the content and provider-dispatch suites.

ellmer parity

All three changes here are new capability, not ports — ellmer has none of them today:

	ellmer today
Text/CSV/code documents	No constructor exists. content_image_* and content_pdf_* are the only file inputs; ContentText is a plain string.
PDF URL passthrough	content_pdf_url() downloads via httr2::req_perform() and base64-encodes. Anthropic gets source: {type: "base64"}, OpenAI gets file_data, Gemini gets inlineData — no provider ever sees a URL.
HEIC/HEIF	Not supported; docs say "PNG, JPEG, WebP, and non-animated GIF".

If ellmer wants parity:

1. Add ContentDocument + content_document_file()/content_document_url(). An S7 class alongside ContentPDF with a mime_type property, and the same per-provider dispatch in as_json(): text/plain coercion for Anthropic, real MIME type for OpenAI and Gemini, "convert first" errors for the binary office formats on Anthropic and Gemini. google_upload()'s existing MIME table (R/provider-google-upload.R:178-224) is a reasonable starting point for extension mapping.
2. Split PDF source from PDF bytes. This is the ContentPDFRemote TODO already sitting in R/content-pdf.R:34-36 — the same TODO chatlas inherited and this PR removes. content_pdf_url() keeps the URL, Anthropic and OpenAI Responses send it as-is, and Gemini/Completions fetch lazily. R's copy-on-modify semantics make the caching half harder than in Python: chatlas mutates content.data in place so a reused PDF downloads once, which in ellmer needs either an environment/R7 mutable field or a memoised fetch keyed on URL.
3. Accept image/heic / image/heif in content_image_file()'s extension map (R/content-image.R:74-86), pass them through on Gemini, and error with a convert-to list elsewhere. This one is harder there than here: resize defaults to "low" in ellmer (not "none"), and every value but "none" routes through magick::image_read() (R/content-image.R:62, 93-95). So the default path needs ImageMagick built with an HEIC delegate — a system-library condition, not a pip install pillow-heif — which makes the unhappy path both the common case and one a package can't fix for the user.

No ellmer issues track any of this (searched document, text file, csv, pdf url, heic), so these would be new.

Landing order

Part of a three-PR set (documents, audio, video). All three touch ContentTypeEnum, ContentUnion, and create_content(), so whichever lands first forces a trivial rebase of the others. This one should go first — it establishes the content-model shape and the shared ensure_bytes() helper the other two build alongside.