pydantic-ai-slim 0.8.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

pydantic_ai/messages.py

@@ -1,24 +1,22 @@
 from __future__ import annotations as _annotations
 
 import base64
+import hashlib
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
-from dataclasses import dataclass, field, replace
+from dataclasses import KW_ONLY, dataclass, field, replace
 from datetime import datetime
 from mimetypes import guess_type
-from typing import TYPE_CHECKING, Annotated, Any, Literal, Union, cast, overload
+from typing import TYPE_CHECKING, Annotated, Any, Literal, TypeAlias, cast, overload
 
 import pydantic
 import pydantic_core
 from genai_prices import calc_price, types as genai_types
 from opentelemetry._events import Event  # pyright: ignore[reportPrivateImportUsage]
-from typing_extensions import TypeAlias, deprecated
+from typing_extensions import deprecated
 
 from . import _otel_messages, _utils
-from ._utils import (
-    generate_tool_call_id as _generate_tool_call_id,
-    now_utc as _now_utc,
-)
+from ._utils import generate_tool_call_id as _generate_tool_call_id, now_utc as _now_utc
 from .exceptions import UnexpectedModelBehavior
 from .usage import RequestUsage
 
@@ -65,6 +63,8 @@ class SystemPromptPart:
     content: str
     """The content of the prompt."""
 
+    _: KW_ONLY
+
     timestamp: datetime = field(default_factory=_now_utc)
     """The timestamp of the prompt."""
 
@@ -89,6 +89,13 @@ class SystemPromptPart:
     __repr__ = _utils.dataclasses_no_defaults_repr
 
 
+def _multi_modal_content_identifier(identifier: str | bytes) -> str:
+    """Generate stable identifier for multi-modal content to help LLM in finding a specific file in tool call responses."""
+    if isinstance(identifier, str):
+        identifier = identifier.encode('utf-8')
+    return hashlib.sha1(identifier).hexdigest()[:6]
+
+
 @dataclass(init=False, repr=False)
 class FileUrl(ABC):
     """Abstract base class for any URL-based file."""
@@ -96,6 +103,8 @@ class FileUrl(ABC):
     url: str
     """The URL of the file."""
 
+    _: KW_ONLY
+
     force_download: bool = False
     """If the model supports it:
 
@@ -114,17 +123,31 @@ class FileUrl(ABC):
         compare=False, default=None
     )
 
+    identifier: str | None = None
+    """The identifier of the file, such as a unique ID. generating one from the url if not explicitly set
+
+    This identifier can be provided to the model in a message to allow it to refer to this file in a tool call argument,
+    and the tool can look up the file in question by iterating over the message history and finding the matching `FileUrl`.
+
+    This identifier is only automatically passed to the model when the `FileUrl` is returned by a tool.
+    If you're passing the `FileUrl` as a user message, it's up to you to include a separate text part with the identifier,
+    e.g. "This is file <identifier>:" preceding the `FileUrl`.
+    """
+
     def __init__(
         self,
         url: str,
+        *,
         force_download: bool = False,
         vendor_metadata: dict[str, Any] | None = None,
         media_type: str | None = None,
+        identifier: str | None = None,
     ) -> None:
         self.url = url
-        self.vendor_metadata = vendor_metadata
         self.force_download = force_download
+        self.vendor_metadata = vendor_metadata
         self._media_type = media_type
+        self.identifier = identifier or _multi_modal_content_identifier(url)
 
     @pydantic.computed_field
     @property
@@ -153,17 +176,20 @@ class VideoUrl(FileUrl):
     url: str
     """The URL of the video."""
 
+    _: KW_ONLY
+
     kind: Literal['video-url'] = 'video-url'
     """Type identifier, this is available on all parts as a discriminator."""
 
     def __init__(
         self,
         url: str,
+        *,
         force_download: bool = False,
         vendor_metadata: dict[str, Any] | None = None,
         media_type: str | None = None,
         kind: Literal['video-url'] = 'video-url',
-        *,
+        identifier: str | None = None,
         # Required for inline-snapshot which expects all dataclass `__init__` methods to take all field names as kwargs.
         _media_type: str | None = None,
     ) -> None:
@@ -172,6 +198,7 @@ class VideoUrl(FileUrl):
             force_download=force_download,
             vendor_metadata=vendor_metadata,
             media_type=media_type or _media_type,
+            identifier=identifier,
         )
         self.kind = kind
 
@@ -224,17 +251,20 @@ class AudioUrl(FileUrl):
     url: str
     """The URL of the audio file."""
 
+    _: KW_ONLY
+
     kind: Literal['audio-url'] = 'audio-url'
     """Type identifier, this is available on all parts as a discriminator."""
 
     def __init__(
         self,
         url: str,
+        *,
         force_download: bool = False,
         vendor_metadata: dict[str, Any] | None = None,
         media_type: str | None = None,
         kind: Literal['audio-url'] = 'audio-url',
-        *,
+        identifier: str | None = None,
         # Required for inline-snapshot which expects all dataclass `__init__` methods to take all field names as kwargs.
         _media_type: str | None = None,
     ) -> None:
@@ -243,6 +273,7 @@ class AudioUrl(FileUrl):
             force_download=force_download,
             vendor_metadata=vendor_metadata,
             media_type=media_type or _media_type,
+            identifier=identifier,
         )
         self.kind = kind
 
@@ -282,17 +313,20 @@ class ImageUrl(FileUrl):
     url: str
     """The URL of the image."""
 
+    _: KW_ONLY
+
     kind: Literal['image-url'] = 'image-url'
     """Type identifier, this is available on all parts as a discriminator."""
 
     def __init__(
         self,
         url: str,
+        *,
         force_download: bool = False,
         vendor_metadata: dict[str, Any] | None = None,
         media_type: str | None = None,
         kind: Literal['image-url'] = 'image-url',
-        *,
+        identifier: str | None = None,
         # Required for inline-snapshot which expects all dataclass `__init__` methods to take all field names as kwargs.
         _media_type: str | None = None,
     ) -> None:
@@ -301,6 +335,7 @@ class ImageUrl(FileUrl):
             force_download=force_download,
             vendor_metadata=vendor_metadata,
             media_type=media_type or _media_type,
+            identifier=identifier,
         )
         self.kind = kind
 
@@ -335,17 +370,20 @@ class DocumentUrl(FileUrl):
     url: str
     """The URL of the document."""
 
+    _: KW_ONLY
+
     kind: Literal['document-url'] = 'document-url'
     """Type identifier, this is available on all parts as a discriminator."""
 
     def __init__(
         self,
         url: str,
+        *,
         force_download: bool = False,
         vendor_metadata: dict[str, Any] | None = None,
         media_type: str | None = None,
         kind: Literal['document-url'] = 'document-url',
-        *,
+        identifier: str | None = None,
         # Required for inline-snapshot which expects all dataclass `__init__` methods to take all field names as kwargs.
         _media_type: str | None = None,
     ) -> None:
@@ -354,6 +392,7 @@ class DocumentUrl(FileUrl):
             force_download=force_download,
             vendor_metadata=vendor_metadata,
             media_type=media_type or _media_type,
+            identifier=identifier,
         )
         self.kind = kind
 
@@ -396,22 +435,26 @@ class DocumentUrl(FileUrl):
             raise ValueError(f'Unknown document media type: {media_type}') from e
 
 
-@dataclass(repr=False)
+@dataclass(init=False, repr=False)
 class BinaryContent:
     """Binary content, e.g. an audio or image file."""
 
     data: bytes
     """The binary data."""
 
+    _: KW_ONLY
+
     media_type: AudioMediaType | ImageMediaType | DocumentMediaType | str
     """The media type of the binary data."""
 
-    identifier: str | None = None
-    """Identifier for the binary content, such as a URL or unique ID.
-
-    This identifier can be provided to the model in a message to allow it to refer to this file in a tool call argument, and the tool can look up the file in question by iterating over the message history and finding the matching `BinaryContent`.
+    identifier: str
+    """Identifier for the binary content, such as a unique ID. generating one from the data if not explicitly set
+    This identifier can be provided to the model in a message to allow it to refer to this file in a tool call argument,
+    and the tool can look up the file in question by iterating over the message history and finding the matching `BinaryContent`.
 
-    This identifier is only automatically passed to the model when the `BinaryContent` is returned by a tool. If you're passing the `BinaryContent` as a user message, it's up to you to include a separate text part with the identifier, e.g. "This is file <identifier>:" preceding the `BinaryContent`.
+    This identifier is only automatically passed to the model when the `BinaryContent` is returned by a tool.
+    If you're passing the `BinaryContent` as a user message, it's up to you to include a separate text part with the identifier,
+    e.g. "This is file <identifier>:" preceding the `BinaryContent`.
     """
 
     vendor_metadata: dict[str, Any] | None = None
@@ -424,6 +467,21 @@ class BinaryContent:
     kind: Literal['binary'] = 'binary'
     """Type identifier, this is available on all parts as a discriminator."""
 
+    def __init__(
+        self,
+        data: bytes,
+        *,
+        media_type: AudioMediaType | ImageMediaType | DocumentMediaType | str,
+        identifier: str | None = None,
+        vendor_metadata: dict[str, Any] | None = None,
+        kind: Literal['binary'] = 'binary',
+    ) -> None:
+        self.data = data
+        self.media_type = media_type
+        self.identifier = identifier or _multi_modal_content_identifier(data)
+        self.vendor_metadata = vendor_metadata
+        self.kind = kind
+
     @property
     def is_audio(self) -> bool:
         """Return `True` if the media type is an audio type."""
@@ -462,7 +520,8 @@ class BinaryContent:
     __repr__ = _utils.dataclasses_no_defaults_repr
 
 
-UserContent: TypeAlias = 'str | ImageUrl | AudioUrl | DocumentUrl | VideoUrl | BinaryContent'
+MultiModalContent = ImageUrl | AudioUrl | DocumentUrl | VideoUrl | BinaryContent
+UserContent: TypeAlias = str | MultiModalContent
 
 
 @dataclass(repr=False)
@@ -478,17 +537,19 @@ class ToolReturn:
     return_value: Any
     """The return value to be used in the tool response."""
 
+    _: KW_ONLY
+
     content: str | Sequence[UserContent] | None = None
     """The content to be sent to the model as a UserPromptPart."""
 
     metadata: Any = None
     """Additional data that can be accessed programmatically by the application but is not sent to the LLM."""
 
+    kind: Literal['tool-return'] = 'tool-return'
+
     __repr__ = _utils.dataclasses_no_defaults_repr
 
 
-# Ideally this would be a Union of types, but Python 3.9 requires it to be a string, and strings don't work with `isinstance``.
-MultiModalContentTypes = (ImageUrl, AudioUrl, DocumentUrl, VideoUrl, BinaryContent)
 _document_format_lookup: dict[str, DocumentFormat] = {
     'application/pdf': 'pdf',
     'text/plain': 'txt',
@@ -536,6 +597,8 @@ class UserPromptPart:
     content: str | Sequence[UserContent]
     """The content of the prompt."""
 
+    _: KW_ONLY
+
     timestamp: datetime = field(default_factory=_now_utc)
     """The timestamp of the prompt."""
 
@@ -562,7 +625,7 @@ class UserPromptPart:
                 parts.append(
                     _otel_messages.TextPart(type='text', **({'content': part} if settings.include_content else {}))
                 )
-            elif isinstance(part, (ImageUrl, AudioUrl, DocumentUrl, VideoUrl)):
+            elif isinstance(part, ImageUrl | AudioUrl | DocumentUrl | VideoUrl):
                 parts.append(
                     _otel_messages.MediaUrlPart(
                         type=part.kind,
@@ -599,6 +662,8 @@ class BaseToolReturnPart:
     tool_call_id: str
     """The tool call identifier, this is used by some models including OpenAI."""
 
+    _: KW_ONLY
+
     metadata: Any = None
     """Additional data that can be accessed programmatically by the application but is not sent to the LLM."""
 
@@ -654,6 +719,8 @@ class BaseToolReturnPart:
 class ToolReturnPart(BaseToolReturnPart):
     """A tool return message, this encodes the result of running a tool."""
 
+    _: KW_ONLY
+
     part_kind: Literal['tool-return'] = 'tool-return'
     """Part type identifier, this is available on all parts as a discriminator."""
 
@@ -662,6 +729,8 @@ class ToolReturnPart(BaseToolReturnPart):
 class BuiltinToolReturnPart(BaseToolReturnPart):
     """A tool return message from a built-in tool."""
 
+    _: KW_ONLY
+
     provider_name: str | None = None
     """The name of the provider that generated the response."""
 
@@ -695,6 +764,8 @@ class RetryPromptPart:
     error details.
     """
 
+    _: KW_ONLY
+
     tool_name: str | None = None
     """The name of the tool that was called, if any."""
 
@@ -753,7 +824,7 @@ class RetryPromptPart:
 
 
 ModelRequestPart = Annotated[
-    Union[SystemPromptPart, UserPromptPart, ToolReturnPart, RetryPromptPart], pydantic.Discriminator('part_kind')
+    SystemPromptPart | UserPromptPart | ToolReturnPart | RetryPromptPart, pydantic.Discriminator('part_kind')
 ]
 """A message part sent by Pydantic AI to a model."""
 
@@ -762,9 +833,11 @@ ModelRequestPart = Annotated[
 class ModelRequest:
     """A request generated by Pydantic AI and sent to a model, e.g. a message from the Pydantic AI app to the model."""
 
-    parts: list[ModelRequestPart]
+    parts: Sequence[ModelRequestPart]
     """The parts of the user message."""
 
+    _: KW_ONLY
+
     instructions: str | None = None
     """The instructions for the model."""
 
@@ -786,6 +859,8 @@ class TextPart:
     content: str
     """The text content of the response."""
 
+    _: KW_ONLY
+
     part_kind: Literal['text'] = 'text'
     """Part type identifier, this is available on all parts as a discriminator."""
 
@@ -803,6 +878,8 @@ class ThinkingPart:
     content: str
     """The thinking content of the response."""
 
+    _: KW_ONLY
+
     id: str | None = None
     """The identifier of the thinking part."""
 
@@ -881,6 +958,8 @@ class BaseToolCallPart:
 class ToolCallPart(BaseToolCallPart):
     """A tool call from a model."""
 
+    _: KW_ONLY
+
     part_kind: Literal['tool-call'] = 'tool-call'
     """Part type identifier, this is available on all parts as a discriminator."""
 
@@ -889,6 +968,8 @@ class ToolCallPart(BaseToolCallPart):
 class BuiltinToolCallPart(BaseToolCallPart):
     """A tool call to a built-in tool."""
 
+    _: KW_ONLY
+
     provider_name: str | None = None
     """The name of the provider that generated the response."""
 
@@ -897,7 +978,7 @@ class BuiltinToolCallPart(BaseToolCallPart):
 
 
 ModelResponsePart = Annotated[
-    Union[TextPart, ToolCallPart, BuiltinToolCallPart, BuiltinToolReturnPart, ThinkingPart],
+    TextPart | ToolCallPart | BuiltinToolCallPart | BuiltinToolReturnPart | ThinkingPart,
     pydantic.Discriminator('part_kind'),
 ]
 """A message part returned by a model."""
@@ -907,9 +988,11 @@ ModelResponsePart = Annotated[
 class ModelResponse:
     """A response from a model, e.g. a message from the model to the Pydantic AI app."""
 
-    parts: list[ModelResponsePart]
+    parts: Sequence[ModelResponsePart]
     """The parts of the model message."""
 
+    _: KW_ONLY
+
     usage: RequestUsage = field(default_factory=RequestUsage)
     """Usage information for the request.
 
@@ -931,18 +1014,30 @@ class ModelResponse:
     provider_name: str | None = None
     """The name of the LLM provider that generated the response."""
 
-    provider_details: dict[str, Any] | None = field(default=None)
+    provider_details: Annotated[
+        dict[str, Any] | None,
+        # `vendor_details` is deprecated, but we still want to support deserializing model responses stored in a DB before the name was changed
+        pydantic.Field(validation_alias=pydantic.AliasChoices('provider_details', 'vendor_details')),
+    ] = None
     """Additional provider-specific details in a serializable format.
 
     This allows storing selected vendor-specific data that isn't mapped to standard ModelResponse fields.
     For OpenAI models, this may include 'logprobs', 'finish_reason', etc.
     """
 
-    provider_request_id: str | None = None
+    provider_response_id: Annotated[
+        str | None,
+        # `vendor_id` is deprecated, but we still want to support deserializing model responses stored in a DB before the name was changed
+        pydantic.Field(validation_alias=pydantic.AliasChoices('provider_response_id', 'vendor_id')),
+    ] = None
     """request ID as specified by the model provider. This can be used to track the specific request to the model."""
 
-    def price(self) -> genai_types.PriceCalculation:
-        """Calculate the price of the usage.
+    @deprecated('`price` is deprecated, use `cost` instead')
+    def price(self) -> genai_types.PriceCalculation:  # pragma: no cover
+        return self.cost()
+
+    def cost(self) -> genai_types.PriceCalculation:
+        """Calculate the cost of the usage.
 
         Uses [`genai-prices`](https://github.com/pydantic/genai-prices).
         """
@@ -970,14 +1065,14 @@ class ModelResponse:
                 body.setdefault('tool_calls', []).append(
                     {
                         'id': part.tool_call_id,
-                        'type': 'function',  # TODO https://github.com/pydantic/pydantic-ai/issues/888
+                        'type': 'function',
                         'function': {
                             'name': part.tool_name,
                             **({'arguments': part.args} if settings.include_content else {}),
                         },
                     }
                 )
-            elif isinstance(part, (TextPart, ThinkingPart)):
+            elif isinstance(part, TextPart | ThinkingPart):
                 kind = part.part_kind
                 body.setdefault('content', []).append(
                     {'kind': kind, **({'text': part.content} if settings.include_content else {})}
@@ -1026,14 +1121,19 @@ class ModelResponse:
         return self.provider_details
 
     @property
-    @deprecated('`vendor_id` is deprecated, use `provider_request_id` instead')
+    @deprecated('`vendor_id` is deprecated, use `provider_response_id` instead')
     def vendor_id(self) -> str | None:
-        return self.provider_request_id
+        return self.provider_response_id
+
+    @property
+    @deprecated('`provider_request_id` is deprecated, use `provider_response_id` instead')
+    def provider_request_id(self) -> str | None:
+        return self.provider_response_id
 
     __repr__ = _utils.dataclasses_no_defaults_repr
 
 
-ModelMessage = Annotated[Union[ModelRequest, ModelResponse], pydantic.Discriminator('kind')]
+ModelMessage = Annotated[ModelRequest | ModelResponse, pydantic.Discriminator('kind')]
 """Any message sent to or returned by a model."""
 
 ModelMessagesTypeAdapter = pydantic.TypeAdapter(
@@ -1049,6 +1149,8 @@ class TextPartDelta:
     content_delta: str
     """The incremental text content to add to the existing `TextPart` content."""
 
+    _: KW_ONLY
+
     part_delta_kind: Literal['text'] = 'text'
     """Part delta type identifier, used as a discriminator."""
 
@@ -1071,7 +1173,7 @@ class TextPartDelta:
     __repr__ = _utils.dataclasses_no_defaults_repr
 
 
-@dataclass(repr=False)
+@dataclass(repr=False, kw_only=True)
 class ThinkingPartDelta:
     """A partial update (delta) for a `ThinkingPart` to append new thinking content."""
 
@@ -1123,7 +1225,7 @@ class ThinkingPartDelta:
     __repr__ = _utils.dataclasses_no_defaults_repr
 
 
-@dataclass(repr=False)
+@dataclass(repr=False, kw_only=True)
 class ToolCallPartDelta:
     """A partial update (delta) for a `ToolCallPart` to modify tool name, arguments, or tool call ID."""
 
@@ -1243,12 +1345,12 @@ class ToolCallPartDelta:
 
 
 ModelResponsePartDelta = Annotated[
-    Union[TextPartDelta, ThinkingPartDelta, ToolCallPartDelta], pydantic.Discriminator('part_delta_kind')
+    TextPartDelta | ThinkingPartDelta | ToolCallPartDelta, pydantic.Discriminator('part_delta_kind')
 ]
 """A partial update (delta) for any model response part."""
 
 
-@dataclass(repr=False)
+@dataclass(repr=False, kw_only=True)
 class PartStartEvent:
     """An event indicating that a new part has started.
 
@@ -1268,7 +1370,7 @@ class PartStartEvent:
     __repr__ = _utils.dataclasses_no_defaults_repr
 
 
-@dataclass(repr=False)
+@dataclass(repr=False, kw_only=True)
 class PartDeltaEvent:
     """An event indicating a delta update for an existing part."""
 
@@ -1284,7 +1386,7 @@ class PartDeltaEvent:
     __repr__ = _utils.dataclasses_no_defaults_repr
 
 
-@dataclass(repr=False)
+@dataclass(repr=False, kw_only=True)
 class FinalResultEvent:
     """An event indicating the response to the current model request matches the output schema and will produce a result."""
 
@@ -1299,7 +1401,7 @@ class FinalResultEvent:
 
 
 ModelResponseStreamEvent = Annotated[
-    Union[PartStartEvent, PartDeltaEvent, FinalResultEvent], pydantic.Discriminator('event_kind')
+    PartStartEvent | PartDeltaEvent | FinalResultEvent, pydantic.Discriminator('event_kind')
 ]
 """An event in the model response stream, starting a new part, applying a delta to an existing one, or indicating the final result."""
 
@@ -1310,6 +1412,9 @@ class FunctionToolCallEvent:
 
     part: ToolCallPart
     """The (function) tool call to make."""
+
+    _: KW_ONLY
+
     event_kind: Literal['function_tool_call'] = 'function_tool_call'
     """Event type identifier, used as a discriminator."""
 
@@ -1333,6 +1438,9 @@ class FunctionToolResultEvent:
 
     result: ToolReturnPart | RetryPromptPart
     """The result of the call to the function tool."""
+
+    _: KW_ONLY
+
     event_kind: Literal['function_tool_result'] = 'function_tool_result'
     """Event type identifier, used as a discriminator."""
 
@@ -1351,6 +1459,8 @@ class BuiltinToolCallEvent:
     part: BuiltinToolCallPart
     """The built-in tool call to make."""
 
+    _: KW_ONLY
+
     event_kind: Literal['builtin_tool_call'] = 'builtin_tool_call'
     """Event type identifier, used as a discriminator."""
 
@@ -1362,15 +1472,17 @@ class BuiltinToolResultEvent:
     result: BuiltinToolReturnPart
     """The result of the call to the built-in tool."""
 
+    _: KW_ONLY
+
     event_kind: Literal['builtin_tool_result'] = 'builtin_tool_result'
     """Event type identifier, used as a discriminator."""
 
 
 HandleResponseEvent = Annotated[
-    Union[FunctionToolCallEvent, FunctionToolResultEvent, BuiltinToolCallEvent, BuiltinToolResultEvent],
+    FunctionToolCallEvent | FunctionToolResultEvent | BuiltinToolCallEvent | BuiltinToolResultEvent,
     pydantic.Discriminator('event_kind'),
 ]
 """An event yielded when handling a model response, indicating tool calls and results."""
 
-AgentStreamEvent = Annotated[Union[ModelResponseStreamEvent, HandleResponseEvent], pydantic.Discriminator('event_kind')]
+AgentStreamEvent = Annotated[ModelResponseStreamEvent | HandleResponseEvent, pydantic.Discriminator('event_kind')]
 """An event in the agent stream: model response stream events and response-handling events."""