Ensure openrouter_reasoning model setting is sent to API (#3545)

Co-authored-by: zhaobin <[email protected]>
Co-authored-by: Douwe Maan <[email protected]>

Author: 3 people

docs/api/models/openrouter.md

@@ -0,0 +1,7 @@
+# `pydantic_ai.models.openrouter`
+
+## Setup
+
+For details on how to set up authentication with this model, see [model configuration for OpenRouter](../../models/openrouter.md).
+
+::: pydantic_ai.models.openrouter

docs/models/openrouter.md

@@ -52,3 +52,24 @@ provider=OpenRouterProvider(
 ),
 ...
 ```
+
+## Model Settings
+
+You can customize model behavior using [`OpenRouterModelSettings`][pydantic_ai.models.openrouter.OpenRouterModelSettings]:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel, OpenRouterModelSettings
+
+settings = OpenRouterModelSettings(
+    openrouter_reasoning={
+        'effort': 'high',
+    },
+    openrouter_usage={
+        'include': True,
+    }
+)
+model = OpenRouterModel('openai/gpt-5')
+agent = Agent(model, model_settings=settings)
+...
+```

docs/thinking.md

@@ -144,6 +144,20 @@ agent = Agent(model, model_settings=settings)
 ...
 ```
 
+## OpenRouter
+
+To enable thinking, use the [`OpenRouterModelSettings.openrouter_reasoning`][pydantic_ai.models.openrouter.OpenRouterModelSettings.openrouter_reasoning] [model setting](agents.md#model-run-settings).
+
+```python {title="openrouter_thinking_part.py"}
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel, OpenRouterModelSettings
+
+model = OpenRouterModel('openai/gpt-5')
+settings = OpenRouterModelSettings(openrouter_reasoning={'effort': 'high'})
+agent = Agent(model, model_settings=settings)
+...
+```
+
 ## Mistral
 
 Thinking is supported by the `magistral` family of models. It does not need to be specifically enabled.

mkdocs.yml

@@ -143,22 +143,23 @@ nav:
           - api/format_prompt.md
           - api/direct.md
           - api/ext.md
-          - api/models/base.md
-          - api/models/openai.md
           - api/models/anthropic.md
+          - api/models/base.md
           - api/models/bedrock.md
           - api/models/cohere.md
+          - api/models/fallback.md
+          - api/models/function.md
           - api/models/google.md
           - api/models/groq.md
           - api/models/huggingface.md
           - api/models/instrumented.md
+          - api/models/mcp-sampling.md
           - api/models/mistral.md
+          - api/models/openai.md
+          - api/models/openrouter.md
           - api/models/outlines.md
           - api/models/test.md
-          - api/models/function.md
-          - api/models/fallback.md
           - api/models/wrapper.md
-          - api/models/mcp-sampling.md
           - api/profiles.md
           - api/providers.md
           - api/retries.md

pydantic_ai_slim/pydantic_ai/models/openrouter.py

@@ -125,14 +125,14 @@ class _OpenRouterMaxPrice(TypedDict, total=False):
 See [the OpenRouter API](https://openrouter.ai/docs/api-reference/list-available-providers) for a full list.
 """
 
-_Transforms = Literal['middle-out']
+OpenRouterTransforms = Literal['middle-out']
 """Available messages transforms for OpenRouter models with limited token windows.
 
 Currently only supports 'middle-out', but is expected to grow in the future.
 """
 
 
-class _OpenRouterProviderConfig(TypedDict, total=False):
+class OpenRouterProviderConfig(TypedDict, total=False):
     """Represents the 'Provider' object from the OpenRouter API."""
 
     order: list[OpenRouterProviderName]
@@ -166,7 +166,7 @@ class _OpenRouterProviderConfig(TypedDict, total=False):
     """The maximum pricing you want to pay for this request. [See details](https://openrouter.ai/docs/features/provider-routing#max-price)"""
 
 
-class _OpenRouterReasoning(TypedDict, total=False):
+class OpenRouterReasoning(TypedDict, total=False):
     """Configuration for reasoning tokens in OpenRouter requests.
 
     Reasoning tokens allow models to show their step-by-step thinking process.
@@ -187,7 +187,7 @@ class _OpenRouterReasoning(TypedDict, total=False):
     """Whether to enable reasoning with default parameters. Default is inferred from effort or max_tokens."""
 
 
-class _OpenRouterUsageConfig(TypedDict, total=False):
+class OpenRouterUsageConfig(TypedDict, total=False):
     """Configuration for OpenRouter usage."""
 
     include: bool
@@ -204,7 +204,7 @@ class OpenRouterModelSettings(ModelSettings, total=False):
     These models will be tried, in order, if the main model returns an error. [See details](https://openrouter.ai/docs/features/model-routing#the-models-parameter)
     """
 
-    openrouter_provider: _OpenRouterProviderConfig
+    openrouter_provider: OpenRouterProviderConfig
     """OpenRouter routes requests to the best available providers for your model. By default, requests are load balanced across the top providers to maximize uptime.
 
     You can customize how your requests are routed using the provider object. [See more](https://openrouter.ai/docs/features/provider-routing)"""
@@ -214,19 +214,19 @@ class OpenRouterModelSettings(ModelSettings, total=False):
 
     Create and manage presets through the OpenRouter web application to control provider routing, model selection, system prompts, and other parameters, then reference them in OpenRouter API requests. [See more](https://openrouter.ai/docs/features/presets)"""
 
-    openrouter_transforms: list[_Transforms]
+    openrouter_transforms: list[OpenRouterTransforms]
     """To help with prompts that exceed the maximum context size of a model.
 
     Transforms work by removing or truncating messages from the middle of the prompt, until the prompt fits within the model's context window. [See more](https://openrouter.ai/docs/features/message-transforms)
     """
 
-    openrouter_reasoning: _OpenRouterReasoning
+    openrouter_reasoning: OpenRouterReasoning
     """To control the reasoning tokens in the request.
 
     The reasoning config object consolidates settings for controlling reasoning strength across different models. [See more](https://openrouter.ai/docs/use-cases/reasoning-tokens)
     """
 
-    openrouter_usage: _OpenRouterUsageConfig
+    openrouter_usage: OpenRouterUsageConfig
     """To control the usage of the model.
 
     The usage config object consolidates settings for enabling detailed usage information. [See more](https://openrouter.ai/docs/use-cases/usage-accounting)
@@ -452,6 +452,8 @@ def _openrouter_settings_to_openai_settings(model_settings: OpenRouterModelSetti
         extra_body['preset'] = preset
     if transforms := model_settings.pop('openrouter_transforms', None):
         extra_body['transforms'] = transforms
+    if reasoning := model_settings.pop('openrouter_reasoning', None):
+        extra_body['reasoning'] = reasoning
     if usage := model_settings.pop('openrouter_usage', None):
         extra_body['usage'] = usage
 

tests/models/test_openrouter.py

@@ -101,7 +101,11 @@ async def test_openrouter_stream_with_native_options(allow_model_requests: None,
 
 async def test_openrouter_stream_with_reasoning(allow_model_requests: None, openrouter_api_key: str) -> None:
     provider = OpenRouterProvider(api_key=openrouter_api_key)
-    model = OpenRouterModel('openai/o3', provider=provider)
+    model = OpenRouterModel(
+        'openai/o3',
+        provider=provider,
+        settings=OpenRouterModelSettings(openrouter_reasoning={'effort': 'high'}),
+    )
 
     async with model_request_stream(model, [ModelRequest.user_text_prompt('Who are you')]) as stream:
         chunks = [chunk async for chunk in stream]