Auto-enable Anthropic Files API beta when messages contain `UploadedFile` by gaurav0107 · Pull Request #5815 · pydantic/pydantic-ai

gaurav0107 · 2026-06-06T13:26:02Z

Closes AnthropicModel should auto-enable Files API beta for UploadedFile requests #5806

Summary

AnthropicModel now auto-attaches the files-api-2025-04-14 beta header
when the outgoing request (or count_tokens estimate) contains an
Anthropic UploadedFile. Previously users had to opt in via
anthropic_betas or extra_headers even though the adapter already
serializes UploadedFile to a source.type='file' content block that
requires the beta — easy to miss, and the request 400s without it.

Changes

pydantic_ai_slim/pydantic_ai/models/anthropic.py:
- Add module-level _ANTHROPIC_FILES_API_BETA = 'files-api-2025-04-14' constant.
- Add AnthropicModel._messages_use_anthropic_uploaded_file(messages) helper that walks the normalized messages and returns True iff any UserPromptPart content item or ToolReturnPart.content_items item is an UploadedFile whose provider_name matches self.system.
- In _messages_create and _messages_count_tokens, conditionally add the beta after the existing native-tool betas are merged.
Gating on provider_name == self.system (not unconditional) so compatible/proxy providers that reject the Anthropic beta header keep working. User-set betas continue to merge.
Tests in tests/models/test_anthropic.py covering text, image, tool-return, count-tokens, no-file (regression guard), foreign provider_name, and user-set-beta-preservation paths. Each test docstring explains why it's a unit test rather than VCR (cassette matchers don't pin the request betas kwarg, so a regression that drops the auto-beta would still match an existing cassette and pass green).

Checklist

Any AI generated code has been reviewed line-by-line by the human PR author, who stands by it.
No breaking changes in accordance with the version policy.
PR title is fit for the release changelog.

…ile` `AnthropicModel` already serializes Anthropic `UploadedFile` parts to content blocks with `source.type='file'`, but the corresponding `anthropic-beta: files-api-2025-04-14` header was only attached when users opted in via `anthropic_betas` or `extra_headers`. Without the beta the request 400s — the adapter constructed a valid wire shape but omitted the header that authorizes it. Auto-attach the beta on `_messages_create` and `_messages_count_tokens` when the normalized messages contain an `UploadedFile` whose `provider_name` matches `self.system`. Gated on actual presence (not unconditional) so compatible/proxy providers that reject the Anthropic beta header keep working. The user-supplied path keeps merging. Closes pydantic#5806

gaurav0107 · 2026-06-10T03:49:01Z

The single failing CI job, test on 3.10 (lowest-versions), failed with 4 setup errors in tests/test_embeddings.py::TestSentenceTransformers — all of them OSError: We couldn't connect to 'https://huggingface.co' to load the files while downloading the sentence-transformer model. All 7599 actual tests passed; only the HuggingFace fixture setup errored out.

This is a transient network flake unrelated to the diff (which only touches pydantic_ai_slim/pydantic_ai/models/anthropic.py and tests/models/test_anthropic.py). Could a maintainer please rerun the failed job? I don't have permission to trigger reruns on this fork PR.

…iles

DouweM · 2026-07-06T23:08:20Z

@adtyavrdhn Please have a look here

The auto-attached `files-api-2025-04-14` beta makes Anthropic `file` sources valid inside `tool_result` blocks too, verified with a live request. - docs/input.md: drop the manual beta-header workaround, it is now automatic. - test_multimodal_tool_returns.py: remove the stale Anthropic uploaded_file error overrides and re-record the four cassettes as success; refresh the uploaded file IDs (old ones 404). - test_anthropic.py: drop the redundant tool-return unit test now backstopped by the re-recorded integration cassettes.

coderabbitai · 2026-07-07T05:08:37Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: fa062824-48b0-40b7-8ba4-d5a7055152bb

📥 Commits

Reviewing files that changed from the base of the PR and between 10a4fe1 and 306c758.

📒 Files selected for processing (1)

pydantic_ai_slim/pydantic_ai/models/anthropic.py

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

pydantic/logfire (manual)
pydantic/pydantic-ai (manual)
pydantic/pydantic (auto-detected)

🚧 Files skipped from review as they are similar to previous changes (1)

pydantic_ai_slim/pydantic_ai/models/anthropic.py

📝 Walkthrough

Walkthrough

This PR makes AnthropicModel automatically add the files-api-2025-04-14 beta when normalized messages contain Anthropic-hosted UploadedFile content. The behavior applies to message creation and token counting, preserves user-provided betas, updates documentation and regression tests, and refreshes multimodal test fixtures.

Possibly related PRs

pydantic/pydantic-ai#4338: Also adds automatic Anthropic Files API beta handling for provider-owned uploaded content.
pydantic/pydantic-ai#5480: Also changes beta propagation in Anthropic token-counting requests.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: auto-enabling the Anthropic Files API beta for UploadedFile requests.
Description check	✅ Passed	The description matches the template with a linked issue, summary, changes, and checklist items, and is sufficiently complete.
Linked Issues check	✅ Passed	The code and tests implement the requested auto-beta behavior for Anthropic UploadedFile requests in message creation and token counting.
Out of Scope Changes check	✅ Passed	The docs, tests, and cassette updates support the same Files API beta change and do not appear unrelated to the issue.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

🧹 Nitpick comments (1)

tests/models/test_anthropic.py (1)
3007-3034: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Private-method test access, but justified.

This test reaches into _messages_use_anthropic_uploaded_file directly, which conflicts with the "test through public APIs" guideline. The docstring explains why: going through agent.run() would hit the mapper's UserError before the mock client is ever invoked, so there's no other way to observe the gate's return value for this negative case. No change requested.

As per coding guidelines, "Test through public APIs, not private methods or helpers prefixed with _."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/models/test_anthropic.py` around lines 3007 - 3034, No code change is
needed here: keep the test’s direct assertion against
AnthropicModel._messages_use_anthropic_uploaded_file, since agent.run() would
hit the existing UserError before this gate can be observed. Preserve the
current docstring rationale so the exception to the “test through public APIs”
guideline is clear and the intent remains obvious to future readers.
Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/models/test_anthropic.py`:
- Around line 3007-3034: No code change is needed here: keep the test’s direct
assertion against AnthropicModel._messages_use_anthropic_uploaded_file, since
agent.run() would hit the existing UserError before this gate can be observed.
Preserve the current docstring rationale so the exception to the “test through
public APIs” guideline is clear and the intent remains obvious to future
readers.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e25696fd-b1c6-41ea-ac48-cd9f51cdb07a

📥 Commits

Reviewing files that changed from the base of the PR and between 1e8adad and 17d12dd.

📒 Files selected for processing (8)

docs/input.md
pydantic_ai_slim/pydantic_ai/models/anthropic.py
tests/models/cassettes/test_multimodal_tool_returns/test_multimodal_tool_return_matrix[direct-uploaded_file-document-anthropic].yaml
tests/models/cassettes/test_multimodal_tool_returns/test_multimodal_tool_return_matrix[direct-uploaded_file-image-anthropic].yaml
tests/models/cassettes/test_multimodal_tool_returns/test_multimodal_tool_return_matrix[tool_return_content-uploaded_file-document-anthropic].yaml
tests/models/cassettes/test_multimodal_tool_returns/test_multimodal_tool_return_matrix[tool_return_content-uploaded_file-image-anthropic].yaml
tests/models/test_anthropic.py
tests/models/test_multimodal_tool_returns.py

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

pydantic/logfire (manual)
pydantic/pydantic-ai (manual)
pydantic/pydantic (auto-detected)

The tool-return branch of `_messages_use_anthropic_uploaded_file` called `content_items(mode='str')`, which JSON-serializes non-file items only for them to be discarded. Detection only needs the `UploadedFile` items, which `mode='raw'` returns untouched, so use that.

The tool-return path had no test that survives cassette masking: VCR matches on URL only, so a regression dropping the auto-beta on a tool-returned `UploadedFile` would replay green. Drive a tool returning an `UploadedFile` through `agent.run` and assert the `betas` kwarg on the post-tool request (and its absence on the pre-tool request).

The document, image, and no-file cases were three near-identical `agent.run` + assert-betas tests. Fold them into one parametrized test keyed on (content, expect_beta). The foreign-provider, user-beta-merge, count-tokens, and tool-return tests exercise different entry points, so they stay separate.

The constant name plus the helper docstring already convey it; the four-line comment was redundant.

`.get('betas') or []` infers as `Any | list[Unknown]`, which pyright rejects (reportUnknownVariableType). Restore the explicit `list[str]` annotation the pre-parametrization negative test had.

github-actions Bot added size: M Medium PR (101-500 weighted lines) bug Report that something isn't working, or PR implementing a fix labels Jun 6, 2026

pydanty Bot mentioned this pull request Jun 15, 2026

AnthropicModel should auto-enable Files API beta for UploadedFile requests #5806

Closed

Merge branch 'main' into fix/5806-anthropicmodel-should-auto-enable-f…

ad9ec01

…iles

DouweM assigned adtyavrdhn Jul 6, 2026

coderabbitai Bot reviewed Jul 7, 2026

View reviewed changes

coderabbitai Bot approved these changes Jul 7, 2026

View reviewed changes

adtyavrdhn added 5 commits July 7, 2026 11:07

Drop verbose comment on Files API beta constant

90e1dc8

The constant name plus the helper docstring already convey it; the four-line comment was redundant.

Annotate betas list to satisfy pyright

10a4fe1

`.get('betas') or []` infers as `Any | list[Unknown]`, which pyright rejects (reportUnknownVariableType). Restore the explicit `list[str]` annotation the pre-parametrization negative test had.

adtyavrdhn reviewed Jul 7, 2026

View reviewed changes

Comment thread pydantic_ai_slim/pydantic_ai/models/anthropic.py Outdated

Fold Files API beta detection into _get_betas_and_extra_headers

306c758

adtyavrdhn approved these changes Jul 10, 2026

View reviewed changes

adtyavrdhn merged commit e873dd2 into pydantic:main Jul 10, 2026
138 of 145 checks passed

Navigation Menu

Auto-enable Anthropic Files API beta when messages contain `UploadedFile` - #5815

Auto-enable Anthropic Files API beta when messages contain `UploadedFile`#5815
adtyavrdhn merged 9 commits into
pydantic:mainfrom
gaurav0107:fix/5806-anthropicmodel-should-auto-enable-files

gaurav0107 commented Jun 6, 2026

Uh oh!

gaurav0107 commented Jun 10, 2026

Uh oh!

DouweM commented Jul 6, 2026

Uh oh!

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

Walkthrough

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

gaurav0107 commented Jun 6, 2026

Summary

Changes

Checklist

Uh oh!

gaurav0107 commented Jun 10, 2026

Uh oh!

DouweM commented Jul 6, 2026

Uh oh!

coderabbitai Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading