bug: Warn about Azure OpenAI completions file-incompatibility by dsfaccini · Pull Request #4048 · pydantic/pydantic-ai

dsfaccini · 2026-01-20T20:39:20Z

Closes AzureOpenAI models don't support files #4035

Pre-Review 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.
Linting and type checking pass per make format and make typecheck.
PR title is fit for the release changelog.

Pre-Merge Checklist

New tests for any fix or new behavior, maintaining 100% coverage.
Updated documentation for new features and behaviors, including docstrings for API docs.

docs/input.md

dsfaccini · 2026-01-20T20:42:27Z

docs/input.md

-A model API may be unable to download a file (e.g., because of crawling or access restrictions) even if it supports file URLs. For example, [`GoogleModel`][pydantic_ai.models.google.GoogleModel] on Vertex AI limits YouTube video URLs to one URL per request. In such cases, you can instruct Pydantic AI to download the file content locally and send that instead of the URL by setting `force_download` on the URL object:
+??? warning "`DocumentUrl` and `BinaryContent` documents are not supported when using `AzureProvider` with `OpenAIChatModel`."
+    Use [`OpenAIResponsesModel`][pydantic_ai.models.openai.OpenAIResponsesModel] with [`AzureProvider`][pydantic_ai.providers.azure.AzureProvider] instead:


I don't think we need an example here, but I want to make sure the Azure doc (currently section on the OpenAI page) explains (in a generic way) that it can be used with the Responses API as well, and that that's actually recommend over OpenAIChatModel. Can you add it there instead please?

for sure, TODO

moved to azure, I'm thinking we should simply replace the default example with responses and leave the chat one in a second tab?
Edit: also can I remove those trailing ... from examples?

pydantic_ai_slim/pydantic_ai/profiles/openai.py

github-actions · 2026-01-20T20:49:26Z

Docs Preview

commit:	`f882fe8`
Preview URL:	https://9307b50e-pydantic-ai-previews.pydantic.workers.dev

pydantic_ai_slim/pydantic_ai/profiles/openai.py

docs/input.md

DouweM · 2026-01-21T17:00:38Z

docs/input.md

 | [`BedrockConverseModel`][pydantic_ai.models.bedrock.BedrockConverseModel] | S3 URLs (`s3://`) | `ImageUrl`, `DocumentUrl`, `VideoUrl` | `AudioUrl` |

-A model API may be unable to download a file (e.g., because of crawling or access restrictions) even if it supports file URLs. For example, [`GoogleModel`][pydantic_ai.models.google.GoogleModel] on Vertex AI limits YouTube video URLs to one URL per request. In such cases, you can instruct Pydantic AI to download the file content locally and send that instead of the URL by setting `force_download` on the URL object:
+??? warning "`DocumentUrl` and `BinaryContent` documents are not supported when using `AzureProvider` with `OpenAIChatModel`."


I'd rather add a Notes column to the table, like we have on the builtin tools doc, where we can state on the OpenAIChatModel row that Azure doesn't support it, and any other notes for provider-specific support (I believe there are some profile flags for specific providers that enable file types that are not supported by OpenAI itself)

looking at my screen I'm not liking the idea of a fifth column

Instead of adding a fifth column, what about mentioning the Azure case under "Unsupported", and then linking to the section that explains the responses workaround?

DouweM · 2026-01-21T17:01:51Z

docs/input.md

-A model API may be unable to download a file (e.g., because of crawling or access restrictions) even if it supports file URLs. For example, [`GoogleModel`][pydantic_ai.models.google.GoogleModel] on Vertex AI limits YouTube video URLs to one URL per request. In such cases, you can instruct Pydantic AI to download the file content locally and send that instead of the URL by setting `force_download` on the URL object:
+??? warning "`DocumentUrl` and `BinaryContent` documents are not supported when using `AzureProvider` with `OpenAIChatModel`."
+    Use [`OpenAIResponsesModel`][pydantic_ai.models.openai.OpenAIResponsesModel] with [`AzureProvider`][pydantic_ai.providers.azure.AzureProvider] instead:


I don't think we need an example here, but I want to make sure the Azure doc (currently section on the OpenAI page) explains (in a generic way) that it can be used with the Responses API as well, and that that's actually recommend over OpenAIChatModel. Can you add it there instead please?

greptile-apps

_{No files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps

_{No files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

pydantic_ai_slim/pydantic_ai/models/openai.py

docs/models/openai.md

DouweM · 2026-02-05T19:54:15Z

tests/models/test_openai.py

    )


+async def test_yaml_document_as_binary_content_input(allow_model_requests: None, openai_api_key: str):


Why did we need these new tests?

The YAML VCR tests (test_yaml_document_as_binary_content_input, test_x_yaml_document_as_binary_content_input, test_yaml_document_url_input) cover the YAML text-like media type handling added in this PR (the new application/yaml and application/x-yaml branches in _is_text_like_media_type).

test_is_text_like_media_type is a unit test for branch coverage of _is_text_like_media_type.

test_video_url_not_supported replaces a pragma: no cover that was on the VideoUrl raise — now that branch is tested directly.

These tests cover YAML media-type edge cases I discovered while investigating how Azure handles different file types. They validate pre-existing behavior that was untested, ensuring the content-type classification works correctly for YAML variants (application/x-yaml, text/yaml, etc). Happy to split them out if you prefer, but they're directly related to the file handling work in this PR.

OK that makes sense, happy to have them here then

devin-ai-integration

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.

- Rename `openai_chat_supports_file_input` → `openai_chat_supports_document_input` - Rename `_raise_file_input_not_supported_error` → `_raise_document_input_not_supported_error` - Update docstrings and comments to say "document" instead of "file" - Remove duplicated paragraph in docs/models/openai.md - Replace warning box with footnote in docs/input.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The test was failing in CI because SSRF protection resolves raw.githubusercontent.com to an IP, causing VCR host matcher to fail. Adding disable_ssrf_protection_for_vcr fixture fixes this, consistent with all other URL-downloading VCR tests. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Covers previously uncovered lines 1233 and 1259 in openai.py: - Azure + DocumentUrl → Azure-specific error (L1233 + L1255) - Generic provider + DocumentUrl → generic error (L1233 + L1259) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-02-16T19:11:56Z

tests/models/test_openai.py

    )


+async def test_yaml_document_as_binary_content_input(allow_model_requests: None, openai_api_key: str):


As DouweM already noted, these YAML tests (test_yaml_document_as_binary_content_input, test_x_yaml_document_as_binary_content_input, test_yaml_document_url_input) test pre-existing YAML media type handling that's already on main — they don't cover any new behavior introduced by this PR. They also bring along ~1100 lines of cassette recordings. Unless there's a specific reason to add them here (e.g. they were missing and this is a good opportunity), they'd be better suited for a separate PR to keep this one focused on the Azure document input limitation.

… version Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

devin-ai-integration

Devin Review found 0 new potential issues.

View 6 additional findings in Devin Review.

.claude/skills/gh-cli-best-practices/fetch-comment

DouweM · 2026-03-04T23:17:45Z

tests/models/test_openai.py

    )


+async def test_yaml_document_as_binary_content_input(allow_model_requests: None, openai_api_key: str):


OK that makes sense, happy to have them here then

pydantic_ai_slim/pydantic_ai/profiles/openai.py

docs/input.md

github-actions · 2026-03-19T14:14:54Z

This PR is stale, and will be closed in 7 days if no reply is received.

…upport # Conflicts: # pydantic_ai_slim/pydantic_ai/models/openai.py # tests/models/test_openai.py # tests/test_examples.py

devin-ai-integration

Devin Review found 2 new potential issues.

View 5 additional findings in Devin Review.

devin-ai-integration · 2026-03-19T18:41:44Z

pydantic_ai_slim/pydantic_ai/models/openai.py

🚩 Potential bypass of document support check when openai_chat_supports_file_urls=True

In _map_document_url_item at pydantic_ai_slim/pydantic_ai/models/openai.py:1245, the first branch checks not item.force_download and profile.openai_chat_supports_file_urls and returns a File content part directly WITHOUT checking openai_chat_supports_document_input. If a provider were configured with openai_chat_supports_file_urls=True AND openai_chat_supports_document_input=False, the document support check would be bypassed. Currently no provider has this combination (only OpenRouter sets openai_chat_supports_file_urls=True, and it supports documents), so this is not a practical issue today. But it's a latent inconsistency that could matter if a new provider is added with this combination.

(Refers to line 1245)

Was this helpful? React with 👍 or 👎 to provide feedback.

IMO the openai_chat_supports_file_urls flag inherently implies the provider supports documents, so I don't think we need to explicitly handle the combination

for future reference, if we found these inconsistencies, having a single dataclass that uses property to validate combinations would be a better approach than checking multiple flags, since adding a check branch here would bloat this out further

docs/models/openai.md

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

devin-ai-integration

Devin Review found 0 new potential issues.

View 7 additional findings in Devin Review.

devin-ai-integration

Devin Review found 0 new potential issues.

View 7 additional findings in Devin Review.

warn about azure openai completions file incompatibility

e37b0bc

dsfaccini added bug Report that something isn't working, or PR implementing a fix media azure labels Jan 20, 2026

dsfaccini mentioned this pull request Jan 20, 2026

AzureOpenAI models don't support files #4035

Open

2 tasks

dsfaccini commented Jan 20, 2026

View reviewed changes

docs/input.md Show resolved Hide resolved

dsfaccini commented Jan 20, 2026

View reviewed changes

pydantic_ai_slim/pydantic_ai/profiles/openai.py Outdated Show resolved Hide resolved

fix exampels

91808ff

DouweM requested changes Jan 21, 2026

View reviewed changes

DouweM self-assigned this Jan 21, 2026

DouweM added the awaiting author revision label Jan 21, 2026

move example over to azure

7cdf685

greptile-apps bot reviewed Jan 23, 2026

View reviewed changes

fix link

e6d4f06

greptile-apps bot reviewed Jan 23, 2026

View reviewed changes

dsfaccini added 5 commits January 23, 2026 13:08

add test for coverage

9e0a102

add test for coverage

5c45e72

coverage

cb6aa6b

fix test

17c6c25

coverage

63d7e6d

dsfaccini force-pushed the review-azure-file-support branch from a01c883 to 63d7e6d Compare January 26, 2026 15:48

dsfaccini added 2 commits January 26, 2026 11:21

Merge branch 'main' into review-azure-file-support

91b8337

Merge branch 'main' into review-azure-file-support

a20068c

DouweM requested changes Feb 5, 2026

View reviewed changes

pydantic deleted a comment from greptile-apps bot Feb 5, 2026

Merge branch 'main' into review-azure-file-support

098f5ec

devin-ai-integration bot reviewed Feb 5, 2026

View reviewed changes

github-actions bot added the size: S Small PR (≤100 weighted lines) label Feb 15, 2026

dsfaccini and others added 4 commits February 15, 2026 09:48

Re-record test_yaml_document_url_input cassette

61e4324

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Merge branch 'main' into review-azure-file-support

67c8371

github-actions bot added size: M Medium PR (101-500 weighted lines) and removed size: S Small PR (≤100 weighted lines) labels Feb 15, 2026

DouweM added the auto-review label Feb 16, 2026

This comment was marked as resolved.

Sign in to view

github-actions bot reviewed Feb 16, 2026

View reviewed changes

This comment was marked as resolved.

Sign in to view

github-actions bot removed the auto-review label Feb 16, 2026

address review feedback: remove symlink, fix docs table, update model…

b663951

… version Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

devin-ai-integration bot reviewed Feb 27, 2026

View reviewed changes

DouweM requested changes Mar 4, 2026

View reviewed changes

github-actions bot added the Stale label Mar 19, 2026

dsfaccini removed Stale awaiting author revision labels Mar 19, 2026

Merge remote-tracking branch 'upstream/main' into review-azure-file-s…

aff00f3

…upport # Conflicts: # pydantic_ai_slim/pydantic_ai/models/openai.py # tests/models/test_openai.py # tests/test_examples.py

devin-ai-integration bot reviewed Mar 19, 2026

View reviewed changes

dsfaccini and others added 2 commits March 19, 2026 13:43

Update docs/models/openai.md

22d356d

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

remove unnecessary backticks

a10f9f1

This comment was marked as resolved.

Sign in to view

devin-ai-integration bot reviewed Mar 19, 2026

View reviewed changes

prepush review

f882fe8

devin-ai-integration bot reviewed Mar 26, 2026

View reviewed changes

		)


		async def test_yaml_document_as_binary_content_input(allow_model_requests: None, openai_api_key: str):

Conversation

dsfaccini commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-Review Checklist

Pre-Merge Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsfaccini Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Jan 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Docs Preview

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dsfaccini Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

✅ Devin Review: No Issues Found

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

github-actions bot Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Mar 19, 2026

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

dsfaccini commented Jan 20, 2026 •

edited

Loading

dsfaccini Jan 23, 2026 •

edited

Loading

github-actions bot commented Jan 20, 2026 •

edited

Loading

dsfaccini Jan 22, 2026 •

edited

Loading