merge

Author: Kludex

docs/api/profiles.md

@@ -0,0 +1,21 @@
+# `pydantic_ai.profiles`
+
+::: pydantic_ai.profiles.ModelProfile
+
+::: pydantic_ai.profiles.openai
+
+::: pydantic_ai.profiles.anthropic
+
+::: pydantic_ai.profiles.google
+
+::: pydantic_ai.profiles.meta
+
+::: pydantic_ai.profiles.amazon
+
+::: pydantic_ai.profiles.deepseek
+
+::: pydantic_ai.profiles.grok
+
+::: pydantic_ai.profiles.mistral
+
+::: pydantic_ai.profiles.qwen

docs/api/providers.md

@@ -19,3 +19,9 @@
 ::: pydantic_ai.providers.cohere
 
 ::: pydantic_ai.providers.mistral
+
+::: pydantic_ai.providers.fireworks
+
+::: pydantic_ai.providers.grok
+
+::: pydantic_ai.providers.together

docs/evals.md

@@ -333,16 +333,16 @@ dataset = Dataset(
 
 
 async def double_number(input_value: int) -> int:
-    """Function that simulates work by sleeping for a second before returning double the input."""
+    """Function that simulates work by sleeping for a tenth of a second before returning double the input."""
     await asyncio.sleep(0.1)  # Simulate work
     return input_value * 2
 
 
 # Run evaluation with unlimited concurrency
 t0 = time.time()
 report_default = dataset.evaluate_sync(double_number)
-print(f'Evaluation took less than 0.3s: {time.time() - t0 < 0.3}')
-#> Evaluation took less than 0.3s: True
+print(f'Evaluation took less than 0.5s: {time.time() - t0 < 0.5}')
+#> Evaluation took less than 0.5s: True
 
 report_default.print(include_input=True, include_output=True, include_durations=False)  # (1)!
 """

docs/models/google.md

@@ -80,7 +80,10 @@ from pydantic_ai import Agent
 from pydantic_ai.models.google import GoogleModel
 from pydantic_ai.providers.google import GoogleProvider
 
-credentials = service_account.Credentials.from_service_account_file('path/to/service-account.json')
+credentials = service_account.Credentials.from_service_account_file(
+    'path/to/service-account.json',
+    scopes=['https://www.googleapis.com/auth/cloud-platform'],
+)
 provider = GoogleProvider(credentials=credentials)
 model = GoogleModel('gemini-1.5-flash', provider=provider)
 agent = Agent(model)

docs/models/index.md

@@ -3,21 +3,21 @@
 PydanticAI is model-agnostic and has built-in support for multiple model providers:
 
 * [OpenAI](openai.md)
-* [DeepSeek](openai.md#openai-compatible-models)
 * [Anthropic](anthropic.md)
 * [Gemini](gemini.md) (via two different APIs: Generative Language API and VertexAI API)
-* [Ollama](openai.md#ollama)
 * [Groq](groq.md)
 * [Mistral](mistral.md)
 * [Cohere](cohere.md)
 * [Bedrock](bedrock.md)
 
 ## OpenAI-compatible Providers
 
-Many models are compatible with the OpenAI API, and can be used with `OpenAIModel` in PydanticAI:
+In addition, many providers are compatible with the OpenAI API, and can be used with `OpenAIModel` in PydanticAI:
 
-* [OpenRouter](openai.md#openrouter)
+* [DeepSeek](openai.md#deepseek)
 * [Grok (xAI)](openai.md#grok-xai)
+* [Ollama](openai.md#ollama)
+* [OpenRouter](openai.md#openrouter)
 * [Perplexity](openai.md#perplexity)
 * [Fireworks AI](openai.md#fireworks-ai)
 * [Together AI](openai.md#together-ai)
@@ -40,27 +40,33 @@ PydanticAI uses a few key terms to describe how it interacts with different LLMs
     roughly in the format `<VendorSdk>Model`, for example, we have `OpenAIModel`, `AnthropicModel`, `GeminiModel`,
     etc. When using a Model class, you specify the actual LLM model name (e.g., `gpt-4o`,
     `claude-3-5-sonnet-latest`, `gemini-1.5-flash`) as a parameter.
-* **Provider**: This refers to Model-specific classes which handle the authentication and connections
+* **Provider**: This refers to provider-specific classes which handle the authentication and connections
     to an LLM vendor. Passing a non-default _Provider_ as a parameter to a Model is how you can ensure
     that your agent will make requests to a specific endpoint, or make use of a specific approach to
     authentication (e.g., you can use Vertex-specific auth with the `GeminiModel` by way of the `VertexProvider`).
     In particular, this is how you can make use of an AI gateway, or an LLM vendor that offers API compatibility
     with the vendor SDK used by an existing Model (such as `OpenAIModel`).
+* **Profile**: This refers to a description of how requests to a specific model or family of models need to be
+    constructed to get the best results, independent of the model and provider classes used.
+    For example, different models have different restrictions on the JSON schemas that can be used for tools,
+    and the same schema transformer needs to be used for Gemini models whether you're using `GoogleModel`
+    with model name `gemini-2.5-pro-preview`, or `OpenAIModel` with `OpenRouterProvider` and model name `google/gemini-2.5-pro-preview`.
 
-In short, you select a specific model name (like `gpt-4o`), PydanticAI uses the appropriate Model class (like `OpenAIModel`), and the provider handles the connection and authentication to the underlying service.
+When you instantiate an [`Agent`][pydantic_ai.Agent] with just a name formatted as `<provider>:<model>`, e.g. `openai:gpt-4o` or `openrouter:google/gemini-2.5-pro-preview`,
+PydanticAI will automatically select the appropriate model class, provider, and profile.
+If you want to use a different provider or profile, you can instantiate a model class directly and pass in `provider` and/or `profile` arguments.
 
 ## Custom Models
 
-To implement support for models not already supported, you will need to subclass the [`Model`][pydantic_ai.models.Model] abstract base class.
-
-For streaming, you'll also need to implement the following abstract base class:
-
-* [`StreamedResponse`][pydantic_ai.models.StreamedResponse]
+To implement support for a model API that's not already supported, you will need to subclass the [`Model`][pydantic_ai.models.Model] abstract base class.
+For streaming, you'll also need to implement the [`StreamedResponse`][pydantic_ai.models.StreamedResponse] abstract base class.
 
 The best place to start is to review the source code for existing implementations, e.g. [`OpenAIModel`](https://github.com/pydantic/pydantic-ai/blob/main/pydantic_ai_slim/pydantic_ai/models/openai.py).
 
 For details on when we'll accept contributions adding new models to PydanticAI, see the [contributing guidelines](../contributing.md#new-model-rules).
 
+If a model API is compatible with the OpenAI API, you do not need a custom model class and can provide your own [custom provider](openai.md#openai-compatible-models) instead.
+
 <!-- TODO(Marcelo): We need to create a section in the docs about reliability. -->
 ## Fallback Model
 

docs/models/openai.md

@@ -2,15 +2,15 @@
 
 ## Install
 
-To use OpenAI models, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `openai` optional group:
+To use OpenAI models or OpenAI-compatible APIs, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `openai` optional group:
 
 ```bash
 pip/uv-add "pydantic-ai-slim[openai]"
 ```
 
 ## Configuration
 
-To use `OpenAIModel` through their main API, go to [platform.openai.com](https://platform.openai.com/) and follow your nose until you find the place to generate an API key.
+To use `OpenAIModel` with the OpenAI API, go to [platform.openai.com](https://platform.openai.com/) and follow your nose until you find the place to generate an API key.
 
 ## Environment variable
 
@@ -130,7 +130,7 @@ You can learn more about the differences between the Responses API and Chat Comp
 
 ## OpenAI-compatible Models
 
-Many models are compatible with the OpenAI API, and can be used with `OpenAIModel` in PydanticAI.
+Many providers and models are compatible with the OpenAI API, and can be used with `OpenAIModel` in PydanticAI.
 Before getting started, check the [installation and configuration](#install) instructions above.
 
 To use another OpenAI-compatible API, you can make use of the `base_url` and `api_key` arguments from `OpenAIProvider`:
@@ -150,7 +150,40 @@ agent = Agent(model)
 ...
 ```
 
-You can also use the `provider` argument with a custom provider class like the `DeepSeekProvider`:
+Various providers also have their own provider classes so that you don't need to specify the base URL yourself and you can use the standard `<PROVIDER>_API_KEY` environment variable to set the API key.
+When a provider has its own provider class, you can use the `Agent("<provider>:<model>")` shorthand, e.g. `Agent("deepseek:deepseek-chat")` or `Agent("openrouter:google/gemini-2.5-pro-preview")`, instead of building the `OpenAIModel` explicitly. Similarly, you can pass the provider name as a string to the `provider` argument on `OpenAIModel` instead of building instantiating the provider class explicitly.
+
+#### Model Profile
+
+Sometimes, the provider or model you're using will have slightly different requirements than OpenAI's API or models, like having different restrictions on JSON schemas for tool definitions, or not supporting tool definitions to be marked as strict.
+
+When using an alternative provider class provided by PydanticAI, an appropriate model profile is typically selected automatically based on the model name.
+If the model you're using is not working correctly out of the box, you can tweak various aspects of how model requests are constructed by providing your own [`ModelProfile`][pydantic_ai.profiles.ModelProfile] (for behaviors shared among all model classes) or [`OpenAIModelProfile`][pydantic_ai.profiles.openai.OpenAIModelProfile] (for behaviors specific to `OpenAIModel`):
+
+```py
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIModel
+from pydantic_ai.profiles._json_schema import InlineDefsJsonSchemaTransformer
+from pydantic_ai.profiles.openai import OpenAIModelProfile
+from pydantic_ai.providers.openai import OpenAIProvider
+
+model = OpenAIModel(
+    'model_name',
+    provider=OpenAIProvider(
+        base_url='https://<openai-compatible-api-endpoint>.com', api_key='your-api-key'
+    ),
+    profile=OpenAIModelProfile(
+        json_schema_transformer=InlineDefsJsonSchemaTransformer,  # Supported by any model class on a plain ModelProfile
+        openai_supports_strict_tool_definition=False  # Supported by OpenAIModel only, requires OpenAIModelProfile
+    )
+)
+agent = Agent(model)
+```
+
+### DeepSeek
+
+To use the [DeepSeek](https://deepseek.com) provider, first create an API key by following the [Quick Start guide](https://api-docs.deepseek.com/).
+Once you have the API key, you can use it with the `DeepSeekProvider`:
 
 ```python
 from pydantic_ai import Agent
@@ -285,7 +318,7 @@ agent = Agent(model)
 
 To use [OpenRouter](https://openrouter.ai), first create an API key at [openrouter.ai/keys](https://openrouter.ai/keys).
 
-Once you have the API key, you can use it with the `OpenAIProvider`:
+Once you have the API key, you can use it with the `OpenRouterProvider`:
 
 ```python
 from pydantic_ai import Agent
@@ -303,16 +336,16 @@ agent = Agent(model)
 ### Grok (xAI)
 
 Go to [xAI API Console](https://console.x.ai/) and create an API key.
-Once you have the API key, you can use it with the `OpenAIProvider`:
+Once you have the API key, you can use it with the `GrokProvider`:
 
 ```python
 from pydantic_ai import Agent
 from pydantic_ai.models.openai import OpenAIModel
-from pydantic_ai.providers.openai import OpenAIProvider
+from pydantic_ai.providers.grok import GrokProvider
 
 model = OpenAIModel(
     'grok-2-1212',
-    provider=OpenAIProvider(base_url='https://api.x.ai/v1', api_key='your-xai-api-key'),
+    provider=GrokProvider(api_key='your-xai-api-key'),
 )
 agent = Agent(model)
 ...
@@ -342,19 +375,16 @@ agent = Agent(model)
 ### Fireworks AI
 
 Go to [Fireworks.AI](https://fireworks.ai/) and create an API key in your account settings.
-Once you have the API key, you can use it with the `OpenAIProvider`:
+Once you have the API key, you can use it with the `FireworksProvider`:
 
 ```python
 from pydantic_ai import Agent
 from pydantic_ai.models.openai import OpenAIModel
-from pydantic_ai.providers.openai import OpenAIProvider
+from pydantic_ai.providers.fireworks import FireworksProvider
 
 model = OpenAIModel(
     'accounts/fireworks/models/qwq-32b',  # model library available at https://fireworks.ai/models
-    provider=OpenAIProvider(
-        base_url='https://api.fireworks.ai/inference/v1',
-        api_key='your-fireworks-api-key',
-    ),
+    provider=FireworksProvider(api_key='your-fireworks-api-key'),
 )
 agent = Agent(model)
 ...
@@ -363,19 +393,16 @@ agent = Agent(model)
 ### Together AI
 
 Go to [Together.ai](https://www.together.ai/) and create an API key in your account settings.
-Once you have the API key, you can use it with the `OpenAIProvider`:
+Once you have the API key, you can use it with the `TogetherProvider`:
 
 ```python
 from pydantic_ai import Agent
 from pydantic_ai.models.openai import OpenAIModel
-from pydantic_ai.providers.openai import OpenAIProvider
+from pydantic_ai.providers.together import TogetherProvider
 
 model = OpenAIModel(
     'meta-llama/Llama-3.3-70B-Instruct-Turbo-Free',  # model library available at https://www.together.ai/models
-    provider=OpenAIProvider(
-        base_url='https://api.together.xyz/v1',
-        api_key='your-together-api-key',
-    ),
+    provider=TogetherProvider(api_key='your-together-api-key'),
 )
 agent = Agent(model)
 ...

examples/pydantic_ai_examples/weather_agent_gradio.py

@@ -33,16 +33,12 @@ async def stream_from_agent(prompt: str, chatbot: list[dict], past_messages: lis
         for message in result.new_messages():
             for call in message.parts:
                 if isinstance(call, ToolCallPart):
-                    call_args = (
-                        call.args.args_json
-                        if hasattr(call.args, 'args_json')
-                        else json.dumps(call.args.args_dict)
-                    )
+                    call_args = call.args_as_json_str()
                     metadata = {
                         'title': f'🛠️ Using {TOOL_TO_DISPLAY_NAME[call.tool_name]}',
                     }
                     if call.tool_call_id is not None:
-                        metadata['id'] = {call.tool_call_id}
+                        metadata['id'] = call.tool_call_id
 
                     gr_message = {
                         'role': 'assistant',

mkdocs.yml

@@ -85,6 +85,7 @@ nav:
       - api/models/function.md
       - api/models/fallback.md
       - api/models/wrapper.md
+      - api/profiles.md
       - api/providers.md
       - api/pydantic_graph/graph.md
       - api/pydantic_graph/nodes.md

pydantic_ai_slim/pydantic_ai/_output.py

@@ -407,7 +407,7 @@ async def process(
             if wrap_validation_errors:
                 m = _messages.RetryPromptPart(
                     tool_name=tool_call.tool_name,
-                    content=e.errors(include_url=False),
+                    content=e.errors(include_url=False, include_context=False),
                     tool_call_id=tool_call.tool_call_id,
                 )
                 raise ToolRetryError(m) from e

pydantic_ai_slim/pydantic_ai/messages.py

@@ -375,7 +375,7 @@ def model_response_object(self) -> dict[str, Any]:
         """Return a dictionary representation of the content, wrapping non-dict types appropriately."""
         # gemini supports JSON dict return values, but no other JSON types, hence we wrap anything else in a dict
         if isinstance(self.content, dict):
-            return tool_return_ta.dump_python(self.content, mode='json')  # pyright: ignore[reportUnknownMemberType]  # pragma: no cover
+            return tool_return_ta.dump_python(self.content, mode='json')  # pyright: ignore[reportUnknownMemberType]
         else:
             return {'return_value': tool_return_ta.dump_python(self.content, mode='json')}