refactor reasoning detail conversion

Author: ajac-zero

docs/models/openrouter.md

@@ -2,10 +2,10 @@
 
 ## Install
 
-To use `OpenRouterModel`, you need to either install `pydantic-ai`, or install `pydantic-ai-slim` with the `openai` optional group:
+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[openai]"
+pip/uv-add "pydantic-ai-slim[openrouter]"
 ```
 
 ## Configuration
@@ -36,16 +36,19 @@ agent = Agent(model)
 ...
 ```
 
-You can set the `x_title` and `http_referer` parameters in the provider to enable [app attribution](https://openrouter.ai/docs/app-attribution):
+## 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',
-    http_referer='https://your-app.com',
-    x_title='Your App',
+    app_url='https://your-app.com',
+    app_title='Your App',
 ),
 ...
 ```

pydantic_ai_slim/pydantic_ai/messages.py

@@ -1042,6 +1042,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/openai.py

@@ -708,7 +708,7 @@ def _get_web_search_options(self, model_request_parameters: ModelRequestParamete
                 )
 
     @dataclass
-    class _MapModelResposeContext:
+    class _MapModelResponseContext:
         """Context object for mapping a `ModelResponse` to OpenAI chat completion parameters.
 
         This class is designed to be subclassed to add new fields for custom logic,
@@ -739,15 +739,15 @@ def into_message_param(self) -> chat.ChatCompletionAssistantMessageParam:
                 message_param['tool_calls'] = self.tool_calls
             return message_param
 
-    def _map_response_text_part(self, ctx: _MapModelResposeContext, item: TextPart) -> None:
+    def _map_response_text_part(self, ctx: _MapModelResponseContext, item: TextPart) -> None:
         """Maps a `TextPart` to the response context.
 
         This method serves as a hook that can be overridden by subclasses
         to implement custom logic for handling text parts.
         """
         ctx.texts.append(item.content)
 
-    def _map_response_thinking_part(self, ctx: _MapModelResposeContext, item: ThinkingPart) -> None:
+    def _map_response_thinking_part(self, ctx: _MapModelResponseContext, item: ThinkingPart) -> None:
         """Maps a `ThinkingPart` to the response context.
 
         This method serves as a hook that can be overridden by subclasses
@@ -759,7 +759,7 @@ def _map_response_thinking_part(self, ctx: _MapModelResposeContext, item: Thinki
         start_tag, end_tag = self.profile.thinking_tags
         ctx.texts.append('\n'.join([start_tag, item.content, end_tag]))
 
-    def _map_response_tool_call_part(self, ctx: _MapModelResposeContext, item: ToolCallPart) -> None:
+    def _map_response_tool_call_part(self, ctx: _MapModelResponseContext, item: ToolCallPart) -> None:
         """Maps a `ToolCallPart` to the response context.
 
         This method serves as a hook that can be overridden by subclasses
@@ -768,7 +768,7 @@ def _map_response_tool_call_part(self, ctx: _MapModelResposeContext, item: ToolC
         ctx.tool_calls.append(self._map_tool_call(item))
 
     def _map_response_builtin_part(
-        self, ctx: _MapModelResposeContext, item: BuiltinToolCallPart | BuiltinToolReturnPart
+        self, ctx: _MapModelResponseContext, item: BuiltinToolCallPart | BuiltinToolReturnPart
     ) -> None:
         """Maps a built-in tool call or return part to the response context.
 
@@ -778,7 +778,7 @@ def _map_response_builtin_part(
         # OpenAI doesn't return built-in tool calls
         pass
 
-    def _map_response_file_part(self, ctx: _MapModelResposeContext, item: FilePart) -> None:
+    def _map_response_file_part(self, ctx: _MapModelResponseContext, item: FilePart) -> None:
         """Maps a `FilePart` to the response context.
 
         This method serves as a hook that can be overridden by subclasses
@@ -792,7 +792,7 @@ def _map_model_response(self, message: ModelResponse) -> chat.ChatCompletionMess
 
         Subclasses of `OpenAIChatModel` may override this method to provide their own mapping logic.
         """
-        ctx = self._MapModelResposeContext()
+        ctx = self._MapModelResponseContext()
         for item in message.parts:
             if isinstance(item, TextPart):
                 self._map_response_text_part(ctx, item)

pydantic_ai_slim/pydantic_ai/models/openrouter.py

@@ -1,10 +1,10 @@
 from __future__ import annotations as _annotations
 
 from collections.abc import Iterable
-from dataclasses import dataclass, field
-from typing import Any, Literal, cast
+from dataclasses import asdict, dataclass, field
+from typing import Annotated, Any, Literal, cast
 
-from pydantic import BaseModel
+from pydantic import AliasChoices, BaseModel, Field, TypeAdapter
 from typing_extensions import TypedDict, assert_never, override
 
 from ..exceptions import ModelHTTPError, UnexpectedModelBehavior
@@ -246,95 +246,69 @@ class _BaseReasoningDetail(BaseModel, frozen=True):
     id: str | None = None
     format: Literal['unknown', 'openai-responses-v1', 'anthropic-claude-v1', 'xai-responses-v1'] | None
     index: int | None
-    type: Literal['reasoning.text', 'reasoning.summary', 'reasoning.encrypted']
 
 
 class _ReasoningSummary(_BaseReasoningDetail, frozen=True):
     """Represents a high-level summary of the reasoning process."""
 
     type: Literal['reasoning.summary']
-    summary: str
+    summary: str = Field(validation_alias=AliasChoices('summary', 'content'))
 
 
 class _ReasoningEncrypted(_BaseReasoningDetail, frozen=True):
     """Represents encrypted reasoning data."""
 
     type: Literal['reasoning.encrypted']
-    data: str
+    data: str = Field(validation_alias=AliasChoices('data', 'signature'))
 
 
 class _ReasoningText(_BaseReasoningDetail, frozen=True):
     """Represents raw text reasoning."""
 
     type: Literal['reasoning.text']
-    text: str
+    text: str = Field(validation_alias=AliasChoices('text', 'content'))
     signature: str | None = None
 
 
-_OpenRouterReasoningDetail = _ReasoningSummary | _ReasoningEncrypted | _ReasoningText
+_OpenRouterReasoningDetail = Annotated[
+    _ReasoningSummary | _ReasoningEncrypted | _ReasoningText, Field(discriminator='type')
+]
+_openrouter_reasoning_detail_adapter: TypeAdapter[_OpenRouterReasoningDetail] = TypeAdapter(_OpenRouterReasoningDetail)
 
 
 def _from_reasoning_detail(reasoning: _OpenRouterReasoningDetail) -> ThinkingPart:
     provider_name = 'openrouter'
-    reasoning_id = reasoning.model_dump_json(include={'id', 'format', 'index', 'type'})
+    provider_details = reasoning.model_dump(include={'format', 'index', 'type'})
     if isinstance(reasoning, _ReasoningText):
         return ThinkingPart(
-            id=reasoning_id,
+            id=reasoning.id,
             content=reasoning.text,
             signature=reasoning.signature,
             provider_name=provider_name,
+            provider_details=provider_details,
         )
     elif isinstance(reasoning, _ReasoningSummary):
         return ThinkingPart(
-            id=reasoning_id,
-            content=reasoning.summary,
-            provider_name=provider_name,
+            id=reasoning.id, content=reasoning.summary, provider_name=provider_name, provider_details=provider_details
         )
     elif isinstance(reasoning, _ReasoningEncrypted):
         return ThinkingPart(
-            id=reasoning_id,
+            id=reasoning.id,
             content='',
             signature=reasoning.data,
             provider_name=provider_name,
+            provider_details=provider_details,
         )
     else:
         assert_never(reasoning)
 
 
 def _into_reasoning_detail(thinking_part: ThinkingPart) -> _OpenRouterReasoningDetail:
-    if thinking_part.id is None:  # pragma: lax no cover
-        raise UnexpectedModelBehavior('OpenRouter thinking part has no ID')
-
-    data = _BaseReasoningDetail.model_validate_json(thinking_part.id)
-
-    if data.type == 'reasoning.text':
-        return _ReasoningText(
-            type=data.type,
-            id=data.id,
-            format=data.format,
-            index=data.index,
-            text=thinking_part.content,
-            signature=thinking_part.signature,
-        )
-    elif data.type == 'reasoning.summary':
-        return _ReasoningSummary(
-            type=data.type,
-            id=data.id,
-            format=data.format,
-            index=data.index,
-            summary=thinking_part.content,
-        )
-    elif data.type == 'reasoning.encrypted':
-        assert thinking_part.signature is not None
-        return _ReasoningEncrypted(
-            type=data.type,
-            id=data.id,
-            format=data.format,
-            index=data.index,
-            data=thinking_part.signature,
-        )
-    else:
-        assert_never(data.type)
+    if thinking_part.provider_details is None:  # pragma: lax no cover
+        raise UnexpectedModelBehavior('OpenRouter thinking part has no provider_details')
+    thinking_part_dict = asdict(thinking_part)
+    thinking_part_dict.update(thinking_part_dict.pop('provider_details'))
+    return _openrouter_reasoning_detail_adapter.validate_python(thinking_part_dict)
 
 
 class _OpenRouterCompletionMessage(chat.ChatCompletionMessage):
@@ -363,7 +337,8 @@ class _OpenRouterChoice(chat_completion.Choice):
     """A wrapped chat completion message with OpenRouter specific attributes."""
 
 
-class _OpenRouterCostDetails(BaseModel):
+@dataclass
+class _OpenRouterCostDetails:
     """OpenRouter specific cost details."""
 
     upstream_inference_cost: int | None = None
@@ -417,7 +392,7 @@ def _map_openrouter_provider_details(
     provider_details: dict[str, Any] = {}
 
     provider_details['downstream_provider'] = response.provider
-    provider_details['native_finish_reason'] = response.choices[0].native_finish_reason
+    provider_details['finish_reason'] = response.choices[0].native_finish_reason
 
     if usage := response.usage:
         if cost := usage.cost:
@@ -517,7 +492,7 @@ def _process_provider_details(self, response: chat.ChatCompletion) -> dict[str,
         return provider_details
 
     @dataclass
-    class _MapModelResposeContext(OpenAIChatModel._MapModelResposeContext):  # type: ignore[reportPrivateUsage]
+    class _MapModelResponseContext(OpenAIChatModel._MapModelResponseContext):  # type: ignore[reportPrivateUsage]
         reasoning_details: list[dict[str, Any]] = field(default_factory=list)
 
         def into_message_param(self) -> chat.ChatCompletionAssistantMessageParam:
@@ -527,8 +502,8 @@ def into_message_param(self) -> chat.ChatCompletionAssistantMessageParam:
             return message_param
 
     @override
-    def _map_response_thinking_part(self, ctx: OpenAIChatModel._MapModelResposeContext, item: ThinkingPart) -> None:
-        assert isinstance(ctx, self._MapModelResposeContext)
+    def _map_response_thinking_part(self, ctx: OpenAIChatModel._MapModelResponseContext, item: ThinkingPart) -> None:
+        assert isinstance(ctx, self._MapModelResponseContext)
         if item.provider_name == self.system:
             ctx.reasoning_details.append(_into_reasoning_detail(item).model_dump())
         elif content := item.content:  # pragma: lax no cover

pydantic_ai_slim/pydantic_ai/providers/openrouter.py

@@ -82,10 +82,10 @@ def __init__(self, *, api_key: str) -> None: ...
     def __init__(self, *, api_key: str, http_client: httpx.AsyncClient) -> None: ...
 
     @overload
-    def __init__(self, *, api_key: str, http_referer: str, x_title: str) -> None: ...
+    def __init__(self, *, api_key: str, app_url: str, app_title: str) -> None: ...
 
     @overload
-    def __init__(self, *, api_key: str, http_referer: str, x_title: str, http_client: httpx.AsyncClient) -> None: ...
+    def __init__(self, *, api_key: str, app_url: str, app_title: str, http_client: httpx.AsyncClient) -> None: ...
 
     @overload
     def __init__(self, *, http_client: httpx.AsyncClient) -> None: ...
@@ -97,8 +97,8 @@ def __init__(
         self,
         *,
         api_key: str | None = None,
-        http_referer: str | None = None,
-        x_title: str | None = None,
+        app_url: str | None = None,
+        app_title: str | None = None,
         openai_client: AsyncOpenAI | None = None,
         http_client: httpx.AsyncClient | None = None,
     ) -> None:
@@ -107,10 +107,10 @@ def __init__(
         Args:
             api_key: OpenRouter API key. Falls back to ``OPENROUTER_API_KEY``
                 when omitted and required unless ``openai_client`` is provided.
-            http_referer: Optional attribution header, falling back to
-                ``OPENROUTER_HTTP_REFERER``.
-            x_title: Optional attribution header, falling back to
-                ``OPENROUTER_X_TITLE``.
+            app_url: Optional url for app attribution. Falls back to
+                ``OPENROUTER_APP_URL`` when omitted.
+            app_title: Optional title for app attribution. Falls back to
+                ``OPENROUTER_APP_TITLE`` when omitted.
             openai_client: Existing ``AsyncOpenAI`` client to reuse instead of
                 creating one internally.
             http_client: Custom ``httpx.AsyncClient`` to pass into the
@@ -128,9 +128,9 @@ def __init__(
             )
 
         attribution_headers: dict[str, str] = {}
-        if http_referer := http_referer or os.getenv('OPENROUTER_HTTP_REFERER'):
+        if http_referer := app_url or os.getenv('OPENROUTER_APP_URL'):
             attribution_headers['HTTP-Referer'] = http_referer
-        if x_title := x_title or os.getenv('OPENROUTER_X_TITLE'):
+        if x_title := app_title or os.getenv('OPENROUTER_APP_TITLE'):
             attribution_headers['X-Title'] = x_title
 
         if openai_client is not None:

pydantic_ai_slim/pyproject.toml

@@ -73,6 +73,7 @@ vertexai = ["google-auth>=2.36.0", "requests>=2.32.2"]
 google = ["google-genai>=1.51.0"]
 anthropic = ["anthropic>=0.70.0"]
 groq = ["groq>=0.25.0"]
+openrouter = ["openai>=2.8.0"]
 mistral = ["mistralai>=1.9.10"]
 bedrock = ["boto3>=1.40.14"]
 huggingface = ["huggingface-hub[inference]>=0.33.5"]

tests/models/test_openrouter.py

@@ -74,7 +74,7 @@ async def test_openrouter_with_native_options(allow_model_requests: None, openro
     )
     assert response.provider_details is not None
     assert response.provider_details['downstream_provider'] == 'xAI'
-    assert response.provider_details['native_finish_reason'] == 'stop'
+    assert response.provider_details['finish_reason'] == 'stop'
 
 
 async def test_openrouter_stream_with_native_options(allow_model_requests: None, openrouter_api_key: str) -> None:
@@ -95,9 +95,7 @@ async def test_openrouter_stream_with_native_options(allow_model_requests: None,
 
         _ = [chunk async for chunk in stream]
 
-        assert stream.provider_details == snapshot(
-            {'finish_reason': 'stop', 'downstream_provider': 'xAI', 'native_finish_reason': 'completed'}
-        )
+        assert stream.provider_details == snapshot({'finish_reason': 'completed', 'downstream_provider': 'xAI'})
         assert stream.finish_reason == snapshot('stop')
 
 
@@ -113,7 +111,7 @@ async def test_openrouter_stream_with_reasoning(allow_model_requests: None, open
         assert thinking_event_start.part == snapshot(
             ThinkingPart(
                 content='',
-                id='{"id":"rs_0aa4f2c435e6d1dc0169082486816c8193a029b5fc4ef1764f","format":"openai-responses-v1","index":0,"type":"reasoning.encrypted"}',
+                id='rs_0aa4f2c435e6d1dc0169082486816c8193a029b5fc4ef1764f',
                 provider_name='openrouter',
             )
         )
@@ -123,7 +121,7 @@ async def test_openrouter_stream_with_reasoning(allow_model_requests: None, open
         assert thinking_event_end.part == snapshot(
             ThinkingPart(
                 content='',
-                id='{"id":"rs_0aa4f2c435e6d1dc0169082486816c8193a029b5fc4ef1764f","format":"openai-responses-v1","index":0,"type":"reasoning.encrypted"}',
+                id='rs_0aa4f2c435e6d1dc0169082486816c8193a029b5fc4ef1764f',
                 provider_name='openrouter',
             )
         )
@@ -206,7 +204,7 @@ async def test_openrouter_with_reasoning(allow_model_requests: None, openrouter_
 
     thinking_part = response.parts[0]
     assert isinstance(thinking_part, ThinkingPart)
-    assert thinking_part.id == snapshot('{"id":null,"format":"unknown","index":0,"type":"reasoning.text"}')
+    assert thinking_part.id == snapshot(None)
     assert thinking_part.content is not None
     assert thinking_part.signature is None
 

tests/providers/test_openrouter.py

@@ -45,7 +45,7 @@ def test_openrouter_provider():
 
 
 def test_openrouter_provider_with_app_attribution():
-    provider = OpenRouterProvider(api_key='api-key', http_referer='test.com', x_title='test')
+    provider = OpenRouterProvider(api_key='api-key', app_url='test.com', app_title='test')
     assert provider.name == 'openrouter'
     assert provider.base_url == 'https://openrouter.ai/api/v1'
     assert isinstance(provider.client, openai.AsyncOpenAI)