Resolve review suggestions.

Author: ZeroAurora

docs/thinking.md

@@ -11,12 +11,10 @@ See the sections below for how to enable thinking for each provider.
 When using the [`OpenAIChatModel`][pydantic_ai.models.openai.OpenAIChatModel], text output inside `<think>` tags are converted to [`ThinkingPart`][pydantic_ai.messages.ThinkingPart] objects.
 You can customize the tags using the [`thinking_tags`][pydantic_ai.profiles.ModelProfile.thinking_tags] field on the [model profile](models/openai.md#model-profile).
 
-Some providers might also support native thinking parts that are not delimited by tags. Instead, they are sent and received as separate fields in the API. You can configure the fields with [`openai_chat_custom_reasoning_field`][pydantic_ai.profiles.openai.OpenAIModelProfile.openai_chat_custom_reasoning_field].
+Some [OpenAI-compatible model providers](models/openai.md#openai-compatible-models) might also support native thinking parts that are not delimited by tags. Instead, they are sent and received as separate, custom fields in the API. Typically, if you are calling the model via the `<provider>:<model>` shorthand, Pydantic AI handles it for you. Nonetheless, you can still configure the fields with [`openai_chat_custom_reasoning_field`][pydantic_ai.profiles.openai.OpenAIModelProfile.openai_chat_custom_reasoning_field].
 
 If your provider recommends to send back these custom fields not changed, for caching or interleaved thinking benefits, you can also achieve this with [`openai_chat_include_reasoning_in_request`][pydantic_ai.profiles.openai.OpenAIModelProfile.openai_chat_include_reasoning_in_request].
 
-And finally, if your provider generates reasoning parts in a somewhat complex `reasoning_details` field, you might want to look into [`OpenRouterModel`][pydantic_ai.models.openrouter.OpenRouterModel] which has built-in support for parsing such fields.
-
 ### OpenAI Responses
 
 The [`OpenAIResponsesModel`][pydantic_ai.models.openai.OpenAIResponsesModel] can generate native thinking parts.

pydantic_ai_slim/pydantic_ai/models/openai.py

@@ -633,24 +633,24 @@ def _process_thinking(self, message: chat.ChatCompletionMessage) -> list[Thinkin
         This method may be overridden by subclasses of `OpenAIChatModel` to apply custom mappings.
         """
         profile = OpenAIModelProfile.from_profile(self.profile)
-        custom_field = profile.openai_chat_custom_reasoning_field
+        custom_field = profile.openai_chat_custom_reasoning_field or ''
         items: list[ThinkingPart] = []
 
         # Prefer the configured custom reasoning field, if present in profile.
-        if custom_field:
-            reasoning = getattr(message, custom_field, None)
+        # Fall back to built-in fields if no custom field result was found.
+
+        # The `reasoning_content` field is typically present in DeepSeek and Moonshot models.
+        # https://api-docs.deepseek.com/guides/reasoning_model
+
+        # The `reasoning` field is typically present in gpt-oss via Ollama and OpenRouter.
+        # - https://cookbook.openai.com/articles/gpt-oss/handle-raw-cot#chat-completions-api
+        # - https://openrouter.ai/docs/use-cases/reasoning-tokens#basic-usage-with-reasoning-tokens
+        for field_name in (custom_field, 'reasoning', 'reasoning_content'):
+            reasoning: str | None = getattr(message, field_name, None)
             if reasoning:  # pragma: no branch
-                items.append(ThinkingPart(id=custom_field, content=reasoning, provider_name=self.system))
+                items.append(ThinkingPart(id=field_name, content=reasoning, provider_name=self.system))
                 return items
 
-        # Fall back to built-in fields if no custom field result was found.
-        # This behavior is for backward compatibility with older models/profiles.
-        for fallback_field in ('reasoning', 'reasoning_content'):
-            reasoning = getattr(message, fallback_field, None)
-            if reasoning:
-                items.append(ThinkingPart(id=fallback_field, content=reasoning, provider_name=self.system))
-                break
-
         return items or None
 
     async def _process_streamed_response(
@@ -759,10 +759,10 @@ def _into_message_param(self) -> chat.ChatCompletionAssistantMessageParam:
             message_param = chat.ChatCompletionAssistantMessageParam(role='assistant')
             # Note: model responses from this model should only have one text item, so the following
             # shouldn't merge multiple texts into one unless you switch models between runs:
-            if profile.openai_chat_include_reasoning_in_request == 'separated' and self.thinkings:
+            if profile.openai_chat_send_back_thinking_parts == 'custom_field' and self.thinkings:
                 field = profile.openai_chat_custom_reasoning_field
                 if field:  # pragma: no branch (handled by profile validation)
-                    message_param[field] = '\n\n'.join(self.thinkings)  # pyright: ignore[reportGeneralTypeIssues]
+                    message_param[field] = '\n\n'.join(self.thinkings)
             if self.texts:
                 message_param['content'] = '\n\n'.join(self.texts)
             else:
@@ -786,11 +786,11 @@ def _map_response_thinking_part(self, item: ThinkingPart) -> None:
             to implement custom logic for handling thinking parts.
             """
             profile = OpenAIModelProfile.from_profile(self._model.profile)
-            include_method = profile.openai_chat_include_reasoning_in_request
-            if include_method == 'combined':
+            include_method = profile.openai_chat_send_back_thinking_parts
+            if include_method == 'thinking_tags':
                 start_tag, end_tag = self._model.profile.thinking_tags
                 self.texts.append('\n'.join([start_tag, item.content, end_tag]))
-            elif include_method == 'separated':
+            elif include_method == 'custom_field':
                 self.thinkings.append(item.content)
 
         def _map_response_tool_call_part(self, item: ToolCallPart) -> None:
@@ -1885,24 +1885,22 @@ def _map_thinking_delta(self, choice: chat_completion_chunk.Choice) -> Iterable[
         custom_field = profile.openai_chat_custom_reasoning_field
 
         # Prefer the configured custom reasoning field, if present in profile.
-        if custom_field:
-            reasoning = getattr(choice.delta, custom_field, None)
-            if reasoning:
-                yield self._parts_manager.handle_thinking_delta(
-                    vendor_part_id=custom_field,
-                    id=custom_field,
-                    content=reasoning,
-                    provider_name=self.provider_name,
-                )
-
         # Fall back to built-in fields if no custom field result was found.
-        # This behavior is for backward compatibility with older models/profiles.
-        for fallback_field in ('reasoning', 'reasoning_content'):
-            reasoning = getattr(choice.delta, fallback_field, None)
-            if reasoning:
+
+        # The `reasoning_content` field is typically present in DeepSeek and Moonshot models.
+        # https://api-docs.deepseek.com/guides/reasoning_model
+
+        # The `reasoning` field is typically present in gpt-oss via Ollama and OpenRouter.
+        # - https://cookbook.openai.com/articles/gpt-oss/handle-raw-cot#chat-completions-api
+        # - https://openrouter.ai/docs/use-cases/reasoning-tokens#basic-usage-with-reasoning-tokens
+        for field_name in (custom_field, 'reasoning', 'reasoning_content'):
+            if not field_name:
+                continue
+            reasoning: str | None = getattr(choice.delta, field_name, None)
+            if reasoning:  # pragma: no branch
                 yield self._parts_manager.handle_thinking_delta(
-                    vendor_part_id=fallback_field,
-                    id=fallback_field,
+                    vendor_part_id=field_name,
+                    id=field_name,
                     content=reasoning,
                     provider_name=self.provider_name,
                 )

pydantic_ai_slim/pydantic_ai/profiles/deepseek.py

@@ -1,13 +1,8 @@
 from __future__ import annotations as _annotations
 
-from .openai import OpenAIModelProfile
+from . import ModelProfile
 
 
-def deepseek_model_profile(model_name: str) -> OpenAIModelProfile | None:
+def deepseek_model_profile(model_name: str) -> ModelProfile | None:
     """Get the model profile for a DeepSeek model."""
-    return OpenAIModelProfile(
-        ignore_streamed_leading_whitespace='r1' in model_name,
-        openai_chat_custom_reasoning_field='reasoning_content',
-        # For compatibility with existing behavior. May want to change later.
-        openai_chat_include_reasoning_in_request='combined',
-    )
+    return ModelProfile(ignore_streamed_leading_whitespace='r1' in model_name)

pydantic_ai_slim/pydantic_ai/profiles/moonshotai.py

@@ -1,12 +1,8 @@
 from __future__ import annotations as _annotations
 
-from .openai import OpenAIModelProfile
+from . import ModelProfile
 
 
-def moonshotai_model_profile(model_name: str) -> OpenAIModelProfile | None:
+def moonshotai_model_profile(model_name: str) -> ModelProfile | None:
     """Get the model profile for a MoonshotAI model."""
-    return OpenAIModelProfile(
-        ignore_streamed_leading_whitespace=True,
-        openai_chat_custom_reasoning_field='reasoning_content',
-        openai_chat_include_reasoning_in_request='separated',
-    )
+    return ModelProfile(ignore_streamed_leading_whitespace=True)

pydantic_ai_slim/pydantic_ai/profiles/openai.py

@@ -7,10 +7,9 @@
 from typing import Any, Literal
 
 from .._json_schema import JsonSchema, JsonSchemaTransformer
+from ..exceptions import UserError
 from . import ModelProfile
 
-OpenAICustomReasoningField = Literal['reasoning', 'reasoning_content']
-OpenAIIncludeReasoningInRequest = Literal['combined', 'separated', 'none']
 OpenAISystemPromptRole = Literal['system', 'developer', 'user']
 
 
@@ -21,26 +20,25 @@ class OpenAIModelProfile(ModelProfile):
     ALL FIELDS MUST BE `openai_` PREFIXED SO YOU CAN MERGE THEM WITH OTHER MODELS.
     """
 
-    openai_chat_custom_reasoning_field: OpenAICustomReasoningField | None = None
+    openai_chat_custom_reasoning_field: str | None = None
     """Non-standard field name used by some providers for model reasoning content in Chat Completions API responses.
 
     Plenty of providers use custom field names for reasoning content. Ollama and newer versions of vLLM use `reasoning`,
     while DeepSeek, older vLLM and some others use `reasoning_content`.
 
-    Notice that the reasoning field configured here is currently limited to `str` type content. If your provider is using
-    complex `reasoning_details` (like newer OpenRouter API), you may want to look into `OpenRouterModel` instead.
+    Notice that the reasoning field configured here is currently limited to `str` type content.
 
-    If `openai_chat_include_reasoning_in_request` is set to `'separated'`, this field must be set to a non-None value."""
+    If `openai_chat_send_back_thinking_parts` is set to `'custom_field'`, this field must be set to a non-None value."""
 
-    openai_chat_include_reasoning_in_request: OpenAIIncludeReasoningInRequest = 'combined'
+    openai_chat_send_back_thinking_parts: Literal['thinking_tags', 'custom_field', False] = 'thinking_tags'
     """Whether the model includes reasoning content in requests.
 
     This can be:
-    * `'combined'` (default): The reasoning content is included in the main `content` field, enclosed within thinking tags.
-    * `'separated'`: The reasoning content is included in a separate field specified by `openai_chat_custom_reasoning_field`.
-    * `'none'`: No reasoning content is sent in the request.
+    * `'thinking_tags'` (default): The reasoning content is included in the main `content` field, enclosed within thinking tags.
+    * `'custom_field'`: The reasoning content is included in a separate field specified by `openai_chat_custom_reasoning_field`.
+    * `False`: No reasoning content is sent in the request.
 
-    Defaults to `'combined'` for compatibility reasons."""
+    Defaults to `'thinking_tags'` for compatibility reasons."""
 
     openai_supports_strict_tool_definition: bool = True
     """This can be set by a provider or user if the OpenAI-"compatible" API doesn't support strict tool definitions."""
@@ -81,9 +79,9 @@ def __post_init__(self):  # pragma: no cover
                 'Use `openai_unsupported_model_settings` instead.',
                 DeprecationWarning,
             )
-        if self.openai_chat_include_reasoning_in_request == 'separated' and not self.openai_chat_custom_reasoning_field:
-            raise ValueError(
-                'If `openai_chat_include_reasoning_in_request` is "separated", '
+        if self.openai_chat_send_back_thinking_parts == 'custom_field' and not self.openai_chat_custom_reasoning_field:
+            raise UserError(
+                'If `openai_chat_include_reasoning_in_request` is "custom_field", '
                 '`openai_chat_custom_reasoning_field` must be set to a non-None value.'
             )
 

pydantic_ai_slim/pydantic_ai/providers/deepseek.py

@@ -44,7 +44,13 @@ 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,
+            openai_chat_custom_reasoning_field='reasoning_content',
+            # DeepSeek recommends against sending back unchanged reasoning parts in requests.
+            # The following is for compatibility with existing behavior. May want to change later.
+            openai_chat_send_back_thinking_parts='thinking_tags',
+        ).update(profile)
 
     @overload
     def __init__(self) -> None: ...

pydantic_ai_slim/pydantic_ai/providers/moonshotai.py

@@ -57,6 +57,8 @@ def model_profile(self, model_name: str) -> ModelProfile | None:
             json_schema_transformer=OpenAIJsonSchemaTransformer,
             openai_supports_tool_choice_required=False,
             supports_json_object_output=True,
+            openai_chat_custom_reasoning_field='reasoning_content',
+            openai_chat_send_back_thinking_parts='thinking_tags',
         ).update(profile)
 
     @overload

pydantic_ai_slim/pydantic_ai/providers/ollama.py

@@ -62,7 +62,11 @@ def model_profile(self, model_name: str) -> ModelProfile | None:
 
         # As OllamaProvider is always used with OpenAIChatModel, which used to unconditionally use OpenAIJsonSchemaTransformer,
         # we need to maintain that behavior unless json_schema_transformer is set explicitly
-        return OpenAIModelProfile(json_schema_transformer=OpenAIJsonSchemaTransformer).update(profile)
+        return OpenAIModelProfile(
+            json_schema_transformer=OpenAIJsonSchemaTransformer,
+            openai_chat_custom_reasoning_field='reasoning',
+            openai_chat_send_back_thinking_parts='thinking_tags',
+        ).update(profile)
 
     def __init__(
         self,

tests/models/test_openai.py

@@ -3118,7 +3118,7 @@ async def test_cache_point_filtering_responses_model():
     assert msg['content'][1]['text'] == 'text after'  # type: ignore[reportUnknownArgumentType]
 
 
-async def test_openai_custom_reasoning_field_sending_back_combined(allow_model_requests: None):
+async def test_openai_custom_reasoning_field_sending_back_in_thinking_tags(allow_model_requests: None):
     c = completion_message(
         ChatCompletionMessage.model_construct(content='response', reasoning_content='reasoning', role='assistant')
     )
@@ -3127,7 +3127,7 @@ async def test_openai_custom_reasoning_field_sending_back_combined(allow_model_r
         provider=OpenAIProvider(openai_client=MockOpenAI.create_mock(c)),
         profile=OpenAIModelProfile(
             openai_chat_custom_reasoning_field='reasoning_content',
-            openai_chat_include_reasoning_in_request='combined',
+            openai_chat_send_back_thinking_parts='thinking_tags',
         ),
     )
     settings = ModelSettings()
@@ -3147,7 +3147,7 @@ async def test_openai_custom_reasoning_field_sending_back_combined(allow_model_r
     )
 
 
-async def test_openai_custom_reasoning_field_sending_back_separated(allow_model_requests: None):
+async def test_openai_custom_reasoning_field_sending_back_in_custom_field(allow_model_requests: None):
     c = completion_message(
         ChatCompletionMessage.model_construct(content='response', reasoning_content='reasoning', role='assistant')
     )
@@ -3156,7 +3156,7 @@ async def test_openai_custom_reasoning_field_sending_back_separated(allow_model_
         provider=OpenAIProvider(openai_client=MockOpenAI.create_mock(c)),
         profile=OpenAIModelProfile(
             openai_chat_custom_reasoning_field='reasoning_content',
-            openai_chat_include_reasoning_in_request='separated',
+            openai_chat_send_back_thinking_parts='custom_field',
         ),
     )
     settings = ModelSettings()
@@ -3176,7 +3176,7 @@ async def test_openai_custom_reasoning_field_not_sending(allow_model_requests: N
         provider=OpenAIProvider(openai_client=MockOpenAI.create_mock(c)),
         profile=OpenAIModelProfile(
             openai_chat_custom_reasoning_field='reasoning_content',
-            openai_chat_include_reasoning_in_request='none',
+            openai_chat_send_back_thinking_parts=False,
         ),
     )
     settings = ModelSettings()
@@ -3187,14 +3187,14 @@ async def test_openai_custom_reasoning_field_not_sending(allow_model_requests: N
     )
 
 
-async def test_openai_embedded_reasoning(allow_model_requests: None):
+async def test_openai_reasoning_in_thinking_tags(allow_model_requests: None):
     c = completion_message(
         ChatCompletionMessage.model_construct(content='<think>reasoning</think>response', role='assistant')
     )
     m = OpenAIChatModel(
         'foobar',
         provider=OpenAIProvider(openai_client=MockOpenAI.create_mock(c)),
-        profile=OpenAIModelProfile(),
+        profile=OpenAIModelProfile(openai_chat_send_back_thinking_parts='thinking_tags'),
     )
     settings = ModelSettings()
     params = ModelRequestParameters()