Merge branch 'main' into 3225

Author: g-eoj

docs/agents.md

@@ -708,7 +708,7 @@ print(result_sync.output)
 The final request uses `temperature=0.0` (run-time), `max_tokens=500` (from model), demonstrating how settings merge with run-time taking precedence.
 
 !!! note "Model Settings Support"
-    Model-level settings are supported by all concrete model implementations (OpenAI, Anthropic, Google, etc.). Wrapper models like `FallbackModel`, `WrapperModel`, and `InstrumentedModel` don't have their own settings - they use the settings of their underlying models.
+    Model-level settings are supported by all concrete model implementations (OpenAI, Anthropic, Google, etc.). Wrapper models like [`FallbackModel`](models/overview.md#fallback-model), [`WrapperModel`][pydantic_ai.models.wrapper.WrapperModel], and [`InstrumentedModel`][pydantic_ai.models.instrumented.InstrumentedModel] don't have their own settings - they use the settings of their underlying models.
 
 ### Model specific settings
 

docs/models/overview.md

@@ -87,8 +87,7 @@ in sequence until one successfully returns a result. Under the hood, Pydantic AI
 from one model to the next if the current model returns a 4xx or 5xx status code.
 
 !!! note
-
-   The provider SDKs on which Models are based (like OpenAI, Anthropic, etc.) often have built-in retry logic that can delay the `FallbackModel` from activating.
+    The provider SDKs on which Models are based (like OpenAI, Anthropic, etc.) often have built-in retry logic that can delay the `FallbackModel` from activating.
 
     When using `FallbackModel`, it's recommended to disable provider SDK retries to ensure immediate fallback, for example by setting `max_retries=0` on a [custom OpenAI client](openai.md#custom-openai-client).
 
@@ -173,7 +172,9 @@ In the year 2157, Captain Maya Chen piloted her spacecraft through the vast expa
 
 In this example, if the OpenAI model fails, the agent will automatically fall back to the Anthropic model with its own configured settings. The `FallbackModel` itself doesn't have settings - it uses the individual settings of whichever model successfully handles the request.
 
-In this next example, we demonstrate the exception-handling capabilities of `FallbackModel`.
+### Exception Handling
+
+The next example demonstrates the exception-handling capabilities of `FallbackModel`.
 If all models fail, a [`FallbackExceptionGroup`][pydantic_ai.exceptions.FallbackExceptionGroup] is raised, which
 contains all the exceptions encountered during the `run` execution.
 
@@ -230,3 +231,6 @@ By default, the `FallbackModel` only moves on to the next model if the current m
 [`ModelAPIError`][pydantic_ai.exceptions.ModelAPIError], which includes
 [`ModelHTTPError`][pydantic_ai.exceptions.ModelHTTPError]. You can customize this behavior by
 passing a custom `fallback_on` argument to the `FallbackModel` constructor.
+
+!!! note
+    Validation errors (from [structured output](../output.md#structured-output) or [tool parameters](../tools.md)) do **not** trigger fallback. These errors use the [retry mechanism](../agents.md#reflection-and-self-correction) instead, which re-prompts the same model to try again. This is intentional: validation errors stem from the non-deterministic nature of LLMs and may succeed on retry, whereas API errors (4xx/5xx) generally indicate issues that won't resolve by retrying the same request.

pydantic_ai_slim/pydantic_ai/models/openrouter.py

@@ -2,9 +2,9 @@
 
 from collections.abc import Iterable
 from dataclasses import dataclass, field
-from typing import Any, Literal, cast
+from typing import Annotated, Any, Literal, TypeAlias, cast
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Discriminator
 from typing_extensions import TypedDict, assert_never, override
 
 from ..exceptions import ModelHTTPError
@@ -22,9 +22,13 @@
 try:
     from openai import APIError, AsyncOpenAI
     from openai.types import chat, completion_usage
-    from openai.types.chat import chat_completion, chat_completion_chunk
+    from openai.types.chat import chat_completion, chat_completion_chunk, chat_completion_message_function_tool_call
 
-    from .openai import OpenAIChatModel, OpenAIChatModelSettings, OpenAIStreamedResponse
+    from .openai import (
+        OpenAIChatModel,
+        OpenAIChatModelSettings,
+        OpenAIStreamedResponse,
+    )
 except ImportError as _import_error:
     raise ImportError(
         'Please install `openai` to use the OpenRouter model, '
@@ -341,6 +345,27 @@ def _into_reasoning_detail(thinking_part: ThinkingPart) -> _OpenRouterReasoningD
         assert_never(data.type)
 
 
+class _OpenRouterFunction(chat_completion_message_function_tool_call.Function):
+    arguments: str | None  # type: ignore[reportIncompatibleVariableOverride]
+    """
+    The arguments to call the function with, as generated by the model in JSON
+    format. Note that the model does not always generate valid JSON, and may
+    hallucinate parameters not defined by your function schema. Validate the
+    arguments in your code before calling your function.
+    """
+
+
+class _OpenRouterChatCompletionMessageFunctionToolCall(chat.ChatCompletionMessageFunctionToolCall):
+    function: _OpenRouterFunction  # type: ignore[reportIncompatibleVariableOverride]
+    """The function that the model called."""
+
+
+_OpenRouterChatCompletionMessageToolCallUnion: TypeAlias = Annotated[
+    _OpenRouterChatCompletionMessageFunctionToolCall | chat.ChatCompletionMessageCustomToolCall,
+    Discriminator(discriminator='type'),
+]
+
+
 class _OpenRouterCompletionMessage(chat.ChatCompletionMessage):
     """Wrapped chat completion message with OpenRouter specific attributes."""
 
@@ -350,6 +375,9 @@ class _OpenRouterCompletionMessage(chat.ChatCompletionMessage):
     reasoning_details: list[_OpenRouterReasoningDetail] | None = None
     """The reasoning details associated with the message, if any."""
 
+    tool_calls: list[_OpenRouterChatCompletionMessageToolCallUnion] | None = None  # type: ignore[reportIncompatibleVariableOverride]
+    """The tool calls generated by the model, such as function calls."""
+
 
 class _OpenRouterChoice(chat_completion.Choice):
     """Wraps OpenAI chat completion choice with OpenRouter specific attributes."""

pydantic_ai_slim/pydantic_ai/providers/deepseek.py

@@ -44,7 +44,9 @@ def model_profile(self, model_name: str) -> ModelProfile | None:
         # we need to maintain that behavior unless json_schema_transformer is set explicitly.
         # This was not the case when using a DeepSeek model with another model class (e.g. BedrockConverseModel or GroqModel),
         # so we won't do this in `deepseek_model_profile` unless we learn it's always needed.
-        return OpenAIModelProfile(json_schema_transformer=OpenAIJsonSchemaTransformer).update(profile)
+        return OpenAIModelProfile(
+            json_schema_transformer=OpenAIJsonSchemaTransformer, supports_json_object_output=True
+        ).update(profile)
 
     @overload
     def __init__(self) -> None: ...

tests/models/cassettes/test_openrouter/test_openrouter_tool_optional_parameters.yaml

@@ -0,0 +1,86 @@
+interactions:
+- request:
+    headers:
+      accept:
+      - application/json
+      accept-encoding:
+      - gzip, deflate
+      connection:
+      - keep-alive
+      content-length:
+      - '362'
+      content-type:
+      - application/json
+      host:
+      - openrouter.ai
+    method: POST
+    parsed_body:
+      messages:
+      - content: Can you find me any education content?
+        role: user
+      model: anthropic/claude-sonnet-4.5
+      stream: false
+      tool_choice: auto
+      tools:
+      - function:
+          description: ''
+          name: find_education_content
+          parameters:
+            properties:
+              title:
+                anyOf:
+                - type: string
+                - type: 'null'
+                default: null
+            type: object
+        type: function
+    uri: https://openrouter.ai/api/v1/chat/completions
+  response:
+    headers:
+      access-control-allow-origin:
+      - '*'
+      connection:
+      - keep-alive
+      content-length:
+      - '611'
+      content-type:
+      - application/json
+      permissions-policy:
+      - payment=(self "https://checkout.stripe.com" "https://connect-js.stripe.com" "https://js.stripe.com" "https://*.js.stripe.com"
+        "https://hooks.stripe.com")
+      referrer-policy:
+      - no-referrer, strict-origin-when-cross-origin
+      transfer-encoding:
+      - chunked
+      vary:
+      - Accept-Encoding
+    parsed_body:
+      choices:
+      - finish_reason: tool_calls
+        index: 0
+        logprobs: null
+        message:
+          content: I'll search for education content for you.
+          reasoning: null
+          refusal: null
+          role: assistant
+          tool_calls:
+          - function:
+              name: find_education_content
+            id: toolu_vrtx_015QAXScZzRDPttiPoc34AdD
+            index: 0
+            type: function
+        native_finish_reason: tool_calls
+      created: 1764308342
+      id: gen-1764308342-FInFdBZR9TF8jmnOwZGZ
+      model: anthropic/claude-sonnet-4.5
+      object: chat.completion
+      provider: Google
+      usage:
+        completion_tokens: 48
+        prompt_tokens: 568
+        total_tokens: 616
+    status:
+      code: 200
+      message: OK
+version: 1

tests/models/test_openrouter.py

@@ -358,3 +358,51 @@ async def test_openrouter_map_messages_reasoning(allow_model_requests: None, ope
             }
         ]
     )
+
+
+async def test_openrouter_tool_optional_parameters(allow_model_requests: None, openrouter_api_key: str) -> None:
+    provider = OpenRouterProvider(api_key=openrouter_api_key)
+
+    class FindEducationContentFilters(BaseModel):
+        title: str | None = None
+
+    model = OpenRouterModel('anthropic/claude-sonnet-4.5', provider=provider)
+    response = await model_request(
+        model,
+        [ModelRequest.user_text_prompt('Can you find me any education content?')],
+        model_request_parameters=ModelRequestParameters(
+            function_tools=[
+                ToolDefinition(
+                    name='find_education_content',
+                    description='',
+                    parameters_json_schema=FindEducationContentFilters.model_json_schema(),
+                )
+            ],
+            allow_text_output=True,  # Allow model to either use tools or respond directly
+        ),
+    )
+
+    assert len(response.parts) == 2
+
+    tool_call_part = response.parts[1]
+    assert isinstance(tool_call_part, ToolCallPart)
+    assert tool_call_part.tool_call_id == snapshot('toolu_vrtx_015QAXScZzRDPttiPoc34AdD')
+    assert tool_call_part.tool_name == 'find_education_content'
+    assert tool_call_part.args == snapshot(None)
+
+    mapped_messages = await model._map_messages([response], None)  # type: ignore[reportPrivateUsage]
+    tool_call_message = mapped_messages[0]
+    assert tool_call_message['role'] == 'assistant'
+    assert tool_call_message.get('content') == snapshot("I'll search for education content for you.")
+    assert tool_call_message.get('tool_calls') == snapshot(
+        [
+            {
+                'id': 'toolu_vrtx_015QAXScZzRDPttiPoc34AdD',
+                'type': 'function',
+                'function': {
+                    'name': 'find_education_content',
+                    'arguments': '{}',
+                },
+            }
+        ]
+    )