Add dedicated OpenRouterModel with support for thinking and more (#3089)

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

Author: ajac-zero

docs/models/openai.md

@@ -233,7 +233,7 @@ agent = Agent(model)
 ```
 
 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 `OpenAIChatModel` explicitly. Similarly, you can pass the provider name as a string to the `provider` argument on `OpenAIChatModel` instead of building instantiating the provider class explicitly.
+When a provider has its own provider class, you can use the `Agent("<provider>:<model>")` shorthand, e.g. `Agent("deepseek:deepseek-chat")` or `Agent("moonshotai:kimi-k2-0711-preview")`, instead of building the `OpenAIChatModel` explicitly. Similarly, you can pass the provider name as a string to the `provider` argument on `OpenAIChatModel` instead of building instantiating the provider class explicitly.
 
 #### Model Profile
 
@@ -385,34 +385,6 @@ agent = Agent(model)
 ...
 ```
 
-### OpenRouter
-
-To use [OpenRouter](https://openrouter.ai), first create an API key at [openrouter.ai/keys](https://openrouter.ai/keys).
-
-You can set the `OPENROUTER_API_KEY` environment variable and use [`OpenRouterProvider`][pydantic_ai.providers.openrouter.OpenRouterProvider] by name:
-
-```python
-from pydantic_ai import Agent
-
-agent = Agent('openrouter:anthropic/claude-3.5-sonnet')
-...
-```
-
-Or initialise the model and provider directly:
-
-```python
-from pydantic_ai import Agent
-from pydantic_ai.models.openai import OpenAIChatModel
-from pydantic_ai.providers.openrouter import OpenRouterProvider
-
-model = OpenAIChatModel(
-    'anthropic/claude-3.5-sonnet',
-    provider=OpenRouterProvider(api_key='your-openrouter-api-key'),
-)
-agent = Agent(model)
-...
-```
-
 ### Vercel AI Gateway
 
 To use [Vercel's AI Gateway](https://vercel.com/docs/ai-gateway), first follow the [documentation](https://vercel.com/docs/ai-gateway) instructions on obtaining an API key or OIDC token.

docs/models/openrouter.md

@@ -0,0 +1,54 @@
+# OpenRouter
+
+## Install
+
+To use `OpenRouterModel`, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `openrouter` optional group:
+
+```bash
+pip/uv-add "pydantic-ai-slim[openrouter]"
+```
+
+## Configuration
+
+To use [OpenRouter](https://openrouter.ai), first create an API key at [openrouter.ai/keys](https://openrouter.ai/keys).
+
+You can set the `OPENROUTER_API_KEY` environment variable and use [`OpenRouterProvider`][pydantic_ai.providers.openrouter.OpenRouterProvider] by name:
+
+```python
+from pydantic_ai import Agent
+
+agent = Agent('openrouter:anthropic/claude-3.5-sonnet')
+...
+```
+
+Or initialise the model and provider directly:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai.models.openrouter import OpenRouterModel
+from pydantic_ai.providers.openrouter import OpenRouterProvider
+
+model = OpenRouterModel(
+    'anthropic/claude-3.5-sonnet',
+    provider=OpenRouterProvider(api_key='your-openrouter-api-key'),
+)
+agent = Agent(model)
+...
+```
+
+## App Attribution
+
+OpenRouter has an [app attribution](https://openrouter.ai/docs/app-attribution) feature to track your application in their public ranking and analytics.
+
+You can pass in an `app_url` and `app_title` when initializing the provider to enable app attribution.
+
+```python
+from pydantic_ai.providers.openrouter import OpenRouterProvider
+
+provider=OpenRouterProvider(
+    api_key='your-openrouter-api-key',
+    app_url='https://your-app.com',
+    app_title='Your App',
+),
+...
+```

mkdocs.yml

@@ -31,6 +31,7 @@ nav:
           - models/google.md
           - models/bedrock.md
           - models/cohere.md
+          - models/openrouter.md
           - models/groq.md
           - models/mistral.md
           - models/huggingface.md

pydantic_ai_slim/pydantic_ai/messages.py

@@ -1063,6 +1063,12 @@ class ThinkingPart:
     part_kind: Literal['thinking'] = 'thinking'
     """Part type identifier, this is available on all parts as a discriminator."""
 
+    provider_details: dict[str, Any] | None = None
+    """Additional provider-specific details in a serializable format.
+
+    This allows storing selected vendor-specific data that isn't mapped to standard ThinkingPart fields.
+    """
+
     def has_content(self) -> bool:
         """Return `True` if the thinking content is non-empty."""
         return bool(self.content)

pydantic_ai_slim/pydantic_ai/models/__init__.py

@@ -807,7 +807,6 @@ def infer_model(  # noqa: C901
         'heroku',
         'moonshotai',
         'ollama',
-        'openrouter',
         'together',
         'vercel',
         'litellm',
@@ -838,6 +837,10 @@ def infer_model(  # noqa: C901
         from .cohere import CohereModel
 
         return CohereModel(model_name, provider=provider)
+    elif model_kind == 'openrouter':
+        from .openrouter import OpenRouterModel
+
+        return OpenRouterModel(model_name, provider=provider)
     elif model_kind == 'mistral':
         from .mistral import MistralModel