fix: #885

Author: fatelei

pydantic_ai_slim/pydantic_ai/messages.py

@@ -52,6 +52,16 @@
 DocumentFormat: TypeAlias = Literal['csv', 'doc', 'docx', 'html', 'md', 'pdf', 'txt', 'xls', 'xlsx']
 VideoFormat: TypeAlias = Literal['mkv', 'mov', 'mp4', 'webm', 'flv', 'mpeg', 'mpg', 'wmv', 'three_gp']
 
+# OpenTelemetry GenAI finish reasons used for gen_ai.response.finish_reasons
+# See mappings in provider implementations (e.g., OpenAI/Google) for how vendor reasons map here.
+OtelFinishReason: TypeAlias = Literal[
+    'stop',
+    'length',
+    'content_filter',
+    'tool_call',
+    'error',
+]
+
 
 @dataclass(repr=False)
 class SystemPromptPart:
@@ -1032,6 +1042,13 @@ class ModelResponse:
     ] = None
     """request ID as specified by the model provider. This can be used to track the specific request to the model."""
 
+    finish_reason: OtelFinishReason | None = None
+    """Reason the model finished generating the response, normalized to OTEL values.
+
+    Allowed values: 'stop', 'length', 'content_filter', 'tool_call', 'error'.
+    Used to populate gen_ai.response.finish_reasons in OpenTelemetry.
+    """
+
     @deprecated('`price` is deprecated, use `cost` instead')
     def price(self) -> genai_types.PriceCalculation:  # pragma: no cover
         return self.cost()

pydantic_ai_slim/pydantic_ai/models/__init__.py

@@ -32,6 +32,7 @@
     ModelRequest,
     ModelResponse,
     ModelResponseStreamEvent,
+    OtelFinishReason,
     PartStartEvent,
     TextPart,
     ToolCallPart,
@@ -554,6 +555,8 @@ class StreamedResponse(ABC):
     model_request_parameters: ModelRequestParameters
 
     final_result_event: FinalResultEvent | None = field(default=None, init=False)
+    provider_response_id: str | None = field(default=None, init=False)
+    finish_reason: OtelFinishReason | None = field(default=None, init=False)
 
     _parts_manager: ModelResponsePartsManager = field(default_factory=ModelResponsePartsManager, init=False)
     _event_iterator: AsyncIterator[ModelResponseStreamEvent] | None = field(default=None, init=False)
@@ -609,6 +612,8 @@ def get(self) -> ModelResponse:
             timestamp=self.timestamp,
             usage=self.usage(),
             provider_name=self.provider_name,
+            provider_response_id=self.provider_response_id,
+            finish_reason=self.finish_reason,
         )
 
     def usage(self) -> RequestUsage:

pydantic_ai_slim/pydantic_ai/models/anthropic.py

@@ -27,6 +27,7 @@
     ModelResponse,
     ModelResponsePart,
     ModelResponseStreamEvent,
+    OtelFinishReason,
     RetryPromptPart,
     SystemPromptPart,
     TextPart,
@@ -42,6 +43,26 @@
 from ..tools import ToolDefinition
 from . import Model, ModelRequestParameters, StreamedResponse, check_allow_model_requests, download_item, get_user_agent
 
+
+def _map_anthropic_finish_reason(raw: str | None) -> OtelFinishReason | None:
+    """Map Anthropic stop_reason to OTEL finish reasons.
+
+    Known Anthropic values include: 'end_turn', 'max_tokens', 'stop_sequence', 'tool_use',
+    as well as 'content_filtered' or 'safety' when content is filtered.
+    """
+    if raw is None:
+        return None
+    if raw in ('end_turn', 'stop_sequence'):
+        return 'stop'
+    if raw == 'max_tokens':
+        return 'length'
+    if raw in ('content_filtered', 'safety'):
+        return 'content_filter'
+    if raw == 'tool_use':
+        return 'other'
+    return None
+
+
 try:
     from anthropic import NOT_GIVEN, APIStatusError, AsyncStream
     from anthropic.types.beta import (
@@ -326,12 +347,19 @@ def _process_response(self, response: BetaMessage) -> ModelResponse:
                     )
                 )
 
+        # Map finish_reason from Anthropic stop_reason
+        raw_finish: str | None = response.stop_reason
+        mapped_finish: OtelFinishReason | None = _map_anthropic_finish_reason(raw_finish)
+        provider_details: dict[str, Any] | None = {'finish_reason': raw_finish} if raw_finish is not None else None
+
         return ModelResponse(
             parts=items,
             usage=_map_usage(response),
             model_name=response.model,
             provider_response_id=response.id,
             provider_name=self._provider.name,
+            finish_reason=mapped_finish,
+            provider_details=provider_details,
         )
 
     async def _process_streamed_response(
@@ -583,6 +611,13 @@ async def _get_event_iterator(self) -> AsyncIterator[ModelResponseStreamEvent]:
         async for event in self._response:
             if isinstance(event, BetaRawMessageStartEvent):
                 self._usage = _map_usage(event)
+                # Capture provider response id from start event
+                try:
+                    if self.provider_response_id is None:
+                        self.provider_response_id = getattr(event.message, 'id', None)
+                except Exception:
+                    pass
+                pass
 
             elif isinstance(event, BetaRawContentBlockStartEvent):
                 current_block = event.content_block
@@ -648,6 +683,13 @@ async def _get_event_iterator(self) -> AsyncIterator[ModelResponseStreamEvent]:
                 self._usage = _map_usage(event)
 
             elif isinstance(event, BetaRawContentBlockStopEvent | BetaRawMessageStopEvent):  # pragma: no branch
+                # Capture mapped finish reason on message stop
+                try:
+                    raw_reason = getattr(getattr(event, 'message', None), 'stop_reason', None)
+                    if self.finish_reason is None and raw_reason is not None:
+                        self.finish_reason = _map_anthropic_finish_reason(raw_reason)
+                except Exception:
+                    pass
                 current_block = None
 
     @property

pydantic_ai_slim/pydantic_ai/models/google.py

@@ -384,6 +384,42 @@ async def _build_content_and_config(
         )
         return contents, config
 
+    @staticmethod
+    def _map_finish_reason_to_otel(raw: str | None) -> str | None:
+        """Map provider-specific finish reasons to OpenTelemetry gen_ai.response.finish_reasons values.
+
+        Only returns a value if it matches a known OTEL value; otherwise returns None.
+        """
+        if raw is None:
+            return None
+        upper = raw.upper()
+        # Known mappings for Google Gemini
+        if upper == 'STOP':
+            return 'stop'
+        if upper in {'MAX_TOKENS', 'MAX_OUTPUT_TOKENS'}:
+            return 'length'
+        if upper in {'SAFETY', 'BLOCKLIST', 'PROHIBITED_CONTENT', 'SPII'}:
+            return 'content_filter'
+        # Unknown or provider-specific value — do not set
+        return None
+
+    def _finish_reason_details(
+        self, finish_reason: Any, vendor_id: str | None
+    ) -> tuple[dict[str, Any] | None, str | None]:
+        """Build provider_details and mapped OTEL finish_reason from a provider finish reason.
+
+        Returns a tuple of (provider_details, mapped_finish_reason).
+        """
+        details: dict[str, Any] = {}
+        mapped_finish_reason: str | None = None
+        if finish_reason is not None:
+            raw_finish_reason = getattr(finish_reason, 'value', str(finish_reason))
+            details['finish_reason'] = raw_finish_reason
+            mapped_finish_reason = self._map_finish_reason_to_otel(raw_finish_reason)
+        if vendor_id:
+            details['provider_response_id'] = vendor_id
+        return (details or None), mapped_finish_reason
+
     def _process_response(self, response: GenerateContentResponse) -> ModelResponse:
         if not response.candidates or len(response.candidates) != 1:
             raise UnexpectedModelBehavior('Expected exactly one candidate in Gemini response')  # pragma: no cover
@@ -397,10 +433,7 @@ def _process_response(self, response: GenerateContentResponse) -> ModelResponse:
                 )  # pragma: no cover
         parts = candidate.content.parts or []
         vendor_id = response.response_id or None
-        vendor_details: dict[str, Any] | None = None
-        finish_reason = candidate.finish_reason
-        if finish_reason:  # pragma: no branch
-            vendor_details = {'finish_reason': finish_reason.value}
+        vendor_details, mapped_finish_reason = self._finish_reason_details(candidate.finish_reason, vendor_id)
         usage = _metadata_as_usage(response)
         return _process_response_from_parts(
             parts,
@@ -409,6 +442,7 @@ def _process_response(self, response: GenerateContentResponse) -> ModelResponse:
             usage,
             vendor_id=vendor_id,
             vendor_details=vendor_details,
+            finish_reason=mapped_finish_reason,
         )
 
     async def _process_streamed_response(
@@ -543,6 +577,11 @@ async def _get_event_iterator(self) -> AsyncIterator[ModelResponseStreamEvent]:
 
             assert chunk.candidates is not None
             candidate = chunk.candidates[0]
+
+            # Capture mapped finish_reason if provided by the candidate
+            if self.finish_reason is None and candidate.finish_reason is not None:
+                raw_fr = getattr(candidate.finish_reason, 'value', str(candidate.finish_reason))
+                self.finish_reason = GoogleModel._map_finish_reason_to_otel(raw_fr)
             if candidate.content is None or candidate.content.parts is None:
                 if candidate.finish_reason == 'STOP':  # pragma: no cover
                     # Normal completion - skip this chunk
@@ -625,6 +664,7 @@ def _process_response_from_parts(
     usage: usage.RequestUsage,
     vendor_id: str | None,
     vendor_details: dict[str, Any] | None = None,
+    finish_reason: str | None = None,
 ) -> ModelResponse:
     items: list[ModelResponsePart] = []
     for part in parts:
@@ -665,6 +705,7 @@ def _process_response_from_parts(
         provider_response_id=vendor_id,
         provider_details=vendor_details,
         provider_name=provider_name,
+        finish_reason=finish_reason,
     )
 
 

pydantic_ai_slim/pydantic_ai/models/instrumented.py

@@ -271,6 +271,11 @@ def handle_messages(self, input_messages: list[ModelMessage], response: ModelRes
                     }
                 ),
             }
+            # Also set finish reason and response ID as span attributes (v2 format)
+            if response.provider_response_id is not None:
+                attributes['gen_ai.response.id'] = response.provider_response_id
+            if response.finish_reason is not None:
+                attributes['gen_ai.response.finish_reasons'] = [response.finish_reason]
             span.set_attributes(attributes)
 
     def system_instructions_attributes(self, instructions: str | None) -> dict[str, str]:

pydantic_ai_slim/pydantic_ai/models/openai.py

@@ -30,6 +30,7 @@
     ModelResponse,
     ModelResponsePart,
     ModelResponseStreamEvent,
+    OtelFinishReason,
     RetryPromptPart,
     SystemPromptPart,
     TextPart,
@@ -493,6 +494,12 @@ def _process_response(self, response: chat.ChatCompletion | str) -> ModelRespons
                 ],
             }
 
+        # Map finish_reason to OTEL and include raw in provider details
+        mapped_finish_reason = _map_openai_chat_finish_reason(choice.finish_reason)
+        if vendor_details is None:
+            vendor_details = {}
+        vendor_details['finish_reason'] = choice.finish_reason
+
         if choice.message.content is not None:
             items.extend(split_content_into_text_and_thinking(choice.message.content, self.profile.thinking_tags))
         if choice.message.tool_calls is not None:
@@ -515,6 +522,7 @@ def _process_response(self, response: chat.ChatCompletion | str) -> ModelRespons
             provider_details=vendor_details,
             provider_response_id=response.id,
             provider_name=self._provider.name,
+            finish_reason=mapped_finish_reason,
         )
 
     async def _process_streamed_response(
@@ -718,6 +726,53 @@ async def _map_user_prompt(part: UserPromptPart) -> chat.ChatCompletionUserMessa
         return chat.ChatCompletionUserMessageParam(role='user', content=content)
 
 
+def _map_openai_responses_finish_reason(
+    status: str | None, incomplete_reason: str | None
+) -> tuple[str | None, OtelFinishReason | None]:
+    """Map OpenAI Responses status/incomplete_details to (raw, OTEL-mapped) finish reasons.
+
+    Raw holds provider data for provider_details, while the mapped value is used for ModelResponse.finish_reason
+    to comply with gen_ai.response.finish_reasons.
+    """
+    if status is None:
+        return None, None
+
+    # Incomplete: use the reason for more specific mapping
+    if status == 'incomplete':
+        raw = incomplete_reason or status
+        if incomplete_reason == 'max_output_tokens':
+            return raw, 'length'
+        if incomplete_reason == 'content_filter':
+            return raw, 'content_filter'
+        if incomplete_reason == 'timeout':
+            return raw, 'error'
+        # Unknown reason for incomplete — do not set mapped value
+        return raw, None
+
+    # Completed/cancelled/failed map to stop/error
+    if status == 'completed':
+        return status, 'stop'
+    if status == 'cancelled':
+        return status, 'error'
+    if status == 'failed':
+        return status, 'error'
+
+    # Unknown/other statuses -> keep raw, do not set mapped
+    return status, None
+
+
+OPENAI_CHAT_FINISH_MAP: dict[str, OtelFinishReason] = {
+    'stop': 'stop',
+    'length': 'length',
+    'content_filter': 'content_filter',
+    'tool_calls': 'tool_call',
+}
+
+
+def _map_openai_chat_finish_reason(raw: str | None) -> OtelFinishReason | None:
+    return OPENAI_CHAT_FINISH_MAP.get(raw) if raw else None
+
+
 @deprecated(
     '`OpenAIModel` was renamed to `OpenAIChatModel` to clearly distinguish it from `OpenAIResponsesModel` which '
     "uses OpenAI's newer Responses API. Use that unless you're using an OpenAI Chat Completions-compatible API, or "
@@ -823,13 +878,25 @@ def _process_response(self, response: responses.Response) -> ModelResponse:
                         items.append(TextPart(content.text))
             elif item.type == 'function_call':
                 items.append(ToolCallPart(item.name, item.arguments, tool_call_id=item.call_id))
+
+        # Map OpenAI Responses status/incomplete_details to OTEL-compliant finish_reasons
+        details = response.incomplete_details
+        incomplete_reason = details.reason if details else None
+        raw_finish, mapped_finish = _map_openai_responses_finish_reason(response.status, incomplete_reason)
+
+        provider_details: dict[str, Any] | None = None
+        if raw_finish is not None:
+            provider_details = {'finish_reason': raw_finish}
+
         return ModelResponse(
             parts=items,
             usage=_map_usage(response),
             model_name=response.model,
             provider_response_id=response.id,
             timestamp=timestamp,
             provider_name=self._provider.name,
+            finish_reason=mapped_finish,
+            provider_details=provider_details,
         )
 
     async def _process_streamed_response(
@@ -1169,6 +1236,10 @@ async def _get_event_iterator(self) -> AsyncIterator[ModelResponseStreamEvent]:
         async for chunk in self._response:
             self._usage += _map_usage(chunk)
 
+            # Capture the response ID from the chunk
+            if chunk.id and self.provider_response_id is None:
+                self.provider_response_id = chunk.id
+
             try:
                 choice = chunk.choices[0]
             except IndexError:
@@ -1177,6 +1248,9 @@ async def _get_event_iterator(self) -> AsyncIterator[ModelResponseStreamEvent]:
             # When using Azure OpenAI and an async content filter is enabled, the openai SDK can return None deltas.
             if choice.delta is None:  # pyright: ignore[reportUnnecessaryComparison]
                 continue
+            # Capture the finish_reason when it becomes available (mapped to OTEL)
+            if choice.finish_reason:
+                self.finish_reason = _map_openai_chat_finish_reason(choice.finish_reason)
 
             # Handle the text part of the response
             content = choice.delta.content
@@ -1236,6 +1310,14 @@ async def _get_event_iterator(self) -> AsyncIterator[ModelResponseStreamEvent]:
             # NOTE: You can inspect the builtin tools used checking the `ResponseCompletedEvent`.
             if isinstance(chunk, responses.ResponseCompletedEvent):
                 self._usage += _map_usage(chunk.response)
+                # Capture id and mapped finish_reason from completed response
+                if chunk.response.id and self.provider_response_id is None:
+                    self.provider_response_id = chunk.response.id
+                if self.finish_reason is None:
+                    details = chunk.response.incomplete_details
+                    incomplete_reason = details.reason if details else None
+                    _, mapped = _map_openai_responses_finish_reason(chunk.response.status, incomplete_reason)
+                    self.finish_reason = mapped
 
             elif isinstance(chunk, responses.ResponseContentPartAddedEvent):
                 pass  # there's nothing we need to do here
@@ -1244,7 +1326,9 @@ async def _get_event_iterator(self) -> AsyncIterator[ModelResponseStreamEvent]:
                 pass  # there's nothing we need to do here
 
             elif isinstance(chunk, responses.ResponseCreatedEvent):
-                pass  # there's nothing we need to do here
+                # Capture id from created response
+                if chunk.response.id and self.provider_response_id is None:
+                    self.provider_response_id = chunk.response.id
 
             elif isinstance(chunk, responses.ResponseFailedEvent):  # pragma: no cover
                 self._usage += _map_usage(chunk.response)