fix: #885

Author: fatelei

pydantic_ai_slim/pydantic_ai/messages.py

@@ -52,6 +52,18 @@
 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',
+    'timeout',
+    'cancelled',
+    'error',
+    'other',
+]
+
 
 @dataclass(repr=False)
 class SystemPromptPart:
@@ -1032,6 +1044,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', 'timeout', 'cancelled', 'error', 'other'.
+    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]: