langchain-core 0.3.71__py3-none-any.whl → 0.4.0.dev0__py3-none-any.whl

langchain_core/v1/messages.py

@@ -0,0 +1,755 @@
+"""LangChain v1.0.0 message format.
+
+Each message has content that may be comprised of content blocks, defined under
+``langchain_core.messages.content_blocks``.
+"""
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional, Union, cast, get_args
+
+from pydantic import BaseModel
+from typing_extensions import TypedDict
+
+import langchain_core.messages.content_blocks as types
+from langchain_core.messages.ai import (
+    _LC_AUTO_PREFIX,
+    _LC_ID_PREFIX,
+    UsageMetadata,
+    add_usage,
+)
+from langchain_core.messages.base import merge_content
+from langchain_core.messages.tool import ToolOutputMixin
+from langchain_core.messages.tool import invalid_tool_call as create_invalid_tool_call
+from langchain_core.messages.tool import tool_call as create_tool_call
+from langchain_core.utils._merge import merge_dicts
+from langchain_core.utils.json import parse_partial_json
+
+
+def _ensure_id(id_val: Optional[str]) -> str:
+    """Ensure the ID is a valid string, generating a new UUID if not provided.
+
+    Auto-generated UUIDs are prefixed by ``'lc_'`` to indicate they are
+    LangChain-generated IDs.
+
+    Args:
+        id_val: Optional string ID value to validate.
+
+    Returns:
+        A valid string ID, either the provided value or a new UUID.
+    """
+    return id_val or str(f"{_LC_AUTO_PREFIX}{uuid.uuid4()}")
+
+
+class ResponseMetadata(TypedDict, total=False):
+    """Metadata about the response from the AI provider.
+
+    Contains additional information returned by the provider, such as
+    response headers, service tiers, log probabilities, system fingerprints, etc.
+
+    Extra keys are permitted from what is typed here (via `total=False`), allowing
+    for provider-specific metadata to be included without breaking the type
+    definition.
+    """
+
+    model_provider: str
+    """Name and version of the provider that created the message (e.g., openai)."""
+
+    model_name: str
+    """Name of the model that generated the message."""
+
+
+@dataclass
+class AIMessage:
+    """A message generated by an AI assistant.
+
+    Represents a response from an AI model, including text content, tool calls,
+    and metadata about the generation process.
+
+    Attributes:
+        id: Unique identifier for the message.
+        type: Message type identifier, always "ai".
+        name: Optional human-readable name for the message.
+        lc_version: Encoding version for the message.
+        content: List of content blocks containing the message data.
+        tool_calls: Optional list of tool calls made by the AI.
+        invalid_tool_calls: Optional list of tool calls that failed validation.
+        usage: Optional dictionary containing usage statistics.
+    """
+
+    type: Literal["ai"] = "ai"
+    """The type of the message. Must be a string that is unique to the message type.
+
+    The purpose of this field is to allow for easy identification of the message type
+    when deserializing messages.
+    """
+
+    name: Optional[str] = None
+    """An optional name for the message.
+
+    This can be used to provide a human-readable name for the message.
+
+    Usage of this field is optional, and whether it's used or not is up to the
+    model implementation.
+    """
+
+    id: Optional[str] = None
+    """Unique identifier for the message.
+
+    If the provider assigns a meaningful ID, it should be used here. Otherwise, a
+    LangChain-generated ID will be used.
+    """
+
+    lc_version: str = "v1"
+    """Encoding version for the message. Used for serialization."""
+
+    content: list[types.ContentBlock] = field(default_factory=list)
+    """Message content as a list of content blocks."""
+
+    usage_metadata: Optional[UsageMetadata] = None
+    """If provided, usage metadata for a message, such as token counts."""
+
+    response_metadata: ResponseMetadata = field(
+        default_factory=lambda: ResponseMetadata()
+    )
+    """Metadata about the response.
+
+    This field should include non-standard data returned by the provider, such as
+    response headers, service tiers, or log probabilities.
+    """
+
+    parsed: Optional[Union[dict[str, Any], BaseModel]] = None
+    """Auto-parsed message contents, if applicable."""
+
+    def __init__(
+        self,
+        content: Union[str, list[types.ContentBlock]],
+        id: Optional[str] = None,
+        name: Optional[str] = None,
+        lc_version: str = "v1",
+        response_metadata: Optional[ResponseMetadata] = None,
+        usage_metadata: Optional[UsageMetadata] = None,
+        tool_calls: Optional[list[types.ToolCall]] = None,
+        invalid_tool_calls: Optional[list[types.InvalidToolCall]] = None,
+        parsed: Optional[Union[dict[str, Any], BaseModel]] = None,
+    ):
+        """Initialize an AI message.
+
+        Args:
+            content: Message content as string or list of content blocks.
+            id: Optional unique identifier for the message.
+            name: Optional human-readable name for the message.
+            lc_version: Encoding version for the message.
+            response_metadata: Optional metadata about the response.
+            usage_metadata: Optional metadata about token usage.
+            tool_calls: Optional list of tool calls made by the AI. Tool calls should
+                generally be included in message content. If passed on init, they will
+                be added to the content list.
+            invalid_tool_calls: Optional list of tool calls that failed validation.
+            parsed: Optional auto-parsed message contents, if applicable.
+        """
+        if isinstance(content, str):
+            self.content = [{"type": "text", "text": content}]
+        else:
+            self.content = content
+
+        self.id = _ensure_id(id)
+        self.name = name
+        self.lc_version = lc_version
+        self.usage_metadata = usage_metadata
+        self.parsed = parsed
+        if response_metadata is None:
+            self.response_metadata = {}
+        else:
+            self.response_metadata = response_metadata
+
+        # Add tool calls to content if provided on init
+        if tool_calls:
+            content_tool_calls = {
+                block["id"]
+                for block in self.content
+                if block["type"] == "tool_call" and "id" in block
+            }
+            for tool_call in tool_calls:
+                if "id" in tool_call and tool_call["id"] in content_tool_calls:
+                    continue
+                self.content.append(tool_call)
+        if invalid_tool_calls:
+            content_tool_calls = {
+                block["id"]
+                for block in self.content
+                if block["type"] == "invalid_tool_call" and "id" in block
+            }
+            for invalid_tool_call in invalid_tool_calls:
+                if (
+                    "id" in invalid_tool_call
+                    and invalid_tool_call["id"] in content_tool_calls
+                ):
+                    continue
+                self.content.append(invalid_tool_call)
+        self._tool_calls = [
+            block for block in self.content if block["type"] == "tool_call"
+        ]
+        self._invalid_tool_calls = [
+            block for block in self.content if block["type"] == "invalid_tool_call"
+        ]
+
+    @property
+    def text(self) -> str:
+        """Extract all text content from the AI message as a string."""
+        text_blocks = [block for block in self.content if block["type"] == "text"]
+        return "".join(block["text"] for block in text_blocks)
+
+    @property
+    def tool_calls(self) -> list[types.ToolCall]:
+        """Get the tool calls made by the AI."""
+        if not self._tool_calls:
+            self._tool_calls = [
+                block for block in self.content if block["type"] == "tool_call"
+            ]
+        return self._tool_calls
+
+    @tool_calls.setter
+    def tool_calls(self, value: list[types.ToolCall]) -> None:
+        """Set the tool calls for the AI message."""
+        self._tool_calls = value
+
+    @property
+    def invalid_tool_calls(self) -> list[types.InvalidToolCall]:
+        """Get the invalid tool calls made by the AI."""
+        if not self._invalid_tool_calls:
+            self._invalid_tool_calls = [
+                block for block in self.content if block["type"] == "invalid_tool_call"
+            ]
+        return self._invalid_tool_calls
+
+
+@dataclass
+class AIMessageChunk(AIMessage):
+    """A partial chunk of an AI message during streaming.
+
+    Represents a portion of an AI response that is delivered incrementally
+    during streaming generation. Contains partial content and metadata.
+
+    Attributes:
+        id: Unique identifier for the message chunk.
+        type: Message type identifier, always "ai_chunk".
+        name: Optional human-readable name for the message.
+        content: List of content blocks containing partial message data.
+        tool_call_chunks: Optional list of partial tool call data.
+        usage_metadata: Optional metadata about token usage and costs.
+    """
+
+    type: Literal["ai_chunk"] = "ai_chunk"  # type: ignore[assignment]
+    """The type of the message. Must be a string that is unique to the message type.
+
+    The purpose of this field is to allow for easy identification of the message type
+    when deserializing messages.
+    """
+
+    def __init__(
+        self,
+        content: Union[str, list[types.ContentBlock]],
+        *,
+        id: Optional[str] = None,
+        name: Optional[str] = None,
+        lc_version: str = "v1",
+        response_metadata: Optional[ResponseMetadata] = None,
+        usage_metadata: Optional[UsageMetadata] = None,
+        tool_call_chunks: Optional[list[types.ToolCallChunk]] = None,
+        parsed: Optional[Union[dict[str, Any], BaseModel]] = None,
+        chunk_position: Optional[Literal["last"]] = None,
+    ):
+        """Initialize an AI message.
+
+        Args:
+            content: Message content as string or list of content blocks.
+            id: Optional unique identifier for the message.
+            name: Optional human-readable name for the message.
+            lc_version: Encoding version for the message.
+            response_metadata: Optional metadata about the response.
+            usage_metadata: Optional metadata about token usage.
+            tool_call_chunks: Optional list of partial tool call data.
+            parsed: Optional auto-parsed message contents, if applicable.
+            chunk_position: Optional position of the chunk in the stream. If "last",
+                tool calls will be parsed when aggregated into a stream.
+        """
+        if isinstance(content, str):
+            self.content = [{"type": "text", "text": content, "index": 0}]
+        else:
+            self.content = content
+
+        self.id = _ensure_id(id)
+        self.name = name
+        self.lc_version = lc_version
+        self.usage_metadata = usage_metadata
+        self.parsed = parsed
+        self.chunk_position = chunk_position
+        if response_metadata is None:
+            self.response_metadata = {}
+        else:
+            self.response_metadata = response_metadata
+
+        if tool_call_chunks:
+            content_tool_call_chunks = {
+                block["id"]
+                for block in self.content
+                if block.get("type") == "tool_call_chunk" and "id" in block
+            }
+            for chunk in tool_call_chunks:
+                if "id" in chunk and chunk["id"] in content_tool_call_chunks:
+                    continue
+                self.content.append(chunk)
+        self._tool_call_chunks = [
+            block for block in self.content if block.get("type") == "tool_call_chunk"
+        ]
+
+        self._tool_calls: list[types.ToolCall] = []
+        self._invalid_tool_calls: list[types.InvalidToolCall] = []
+
+    @property
+    def tool_call_chunks(self) -> list[types.ToolCallChunk]:
+        """Get the tool calls made by the AI."""
+        if not self._tool_call_chunks:
+            self._tool_call_chunks = [
+                block
+                for block in self.content
+                if block.get("type") == "tool_call_chunk"
+            ]
+        return cast("list[types.ToolCallChunk]", self._tool_call_chunks)
+
+    @property
+    def tool_calls(self) -> list[types.ToolCall]:
+        """Get the tool calls made by the AI."""
+        if not self._tool_calls:
+            parsed_content = _init_tool_calls(self.content)
+            self._tool_calls = [
+                block for block in parsed_content if block["type"] == "tool_call"
+            ]
+            self._invalid_tool_calls = [
+                block
+                for block in parsed_content
+                if block["type"] == "invalid_tool_call"
+            ]
+        return self._tool_calls
+
+    @tool_calls.setter
+    def tool_calls(self, value: list[types.ToolCall]) -> None:
+        """Set the tool calls for the AI message."""
+        self._tool_calls = value
+
+    @property
+    def invalid_tool_calls(self) -> list[types.InvalidToolCall]:
+        """Get the invalid tool calls made by the AI."""
+        if not self._invalid_tool_calls:
+            parsed_content = _init_tool_calls(self.content)
+            self._tool_calls = [
+                block for block in parsed_content if block["type"] == "tool_call"
+            ]
+            self._invalid_tool_calls = [
+                block
+                for block in parsed_content
+                if block["type"] == "invalid_tool_call"
+            ]
+        return self._invalid_tool_calls
+
+    def __add__(self, other: Any) -> "AIMessageChunk":
+        """Add AIMessageChunk to this one."""
+        if isinstance(other, AIMessageChunk):
+            return add_ai_message_chunks(self, other)
+        if isinstance(other, (list, tuple)) and all(
+            isinstance(o, AIMessageChunk) for o in other
+        ):
+            return add_ai_message_chunks(self, *other)
+        error_msg = "Can only add AIMessageChunk or sequence of AIMessageChunk."
+        raise NotImplementedError(error_msg)
+
+    def to_message(self) -> "AIMessage":
+        """Convert this AIMessageChunk to an AIMessage."""
+        return AIMessage(
+            content=_init_tool_calls(self.content),
+            id=self.id,
+            name=self.name,
+            lc_version=self.lc_version,
+            response_metadata=self.response_metadata,
+            usage_metadata=self.usage_metadata,
+            parsed=self.parsed,
+        )
+
+
+def _init_tool_calls(content: list[types.ContentBlock]) -> list[types.ContentBlock]:
+    """Parse tool call chunks in content into tool calls."""
+    new_content = []
+    for block in content:
+        if block.get("type") != "tool_call_chunk":
+            new_content.append(block)
+            continue
+        try:
+            args_ = (
+                parse_partial_json(cast("str", block.get("args") or ""))
+                if block.get("args")
+                else {}
+            )
+            if isinstance(args_, dict):
+                new_content.append(
+                    create_tool_call(
+                        name=cast("str", block.get("name") or ""),
+                        args=args_,
+                        id=cast("str", block.get("id", "")),
+                    )
+                )
+            else:
+                new_content.append(
+                    create_invalid_tool_call(
+                        name=cast("str", block.get("name", "")),
+                        args=cast("str", block.get("args", "")),
+                        id=cast("str", block.get("id", "")),
+                        error=None,
+                    )
+                )
+        except Exception:
+            new_content.append(
+                create_invalid_tool_call(
+                    name=cast("str", block.get("name", "")),
+                    args=cast("str", block.get("args", "")),
+                    id=cast("str", block.get("id", "")),
+                    error=None,
+                )
+            )
+    return new_content
+
+
+def add_ai_message_chunks(
+    left: AIMessageChunk, *others: AIMessageChunk
+) -> AIMessageChunk:
+    """Add multiple AIMessageChunks together."""
+    if not others:
+        return left
+    content = cast(
+        "list[types.ContentBlock]",
+        merge_content(
+            cast("list[str | dict[Any, Any]]", left.content),
+            *(cast("list[str | dict[Any, Any]]", o.content) for o in others),
+        ),
+    )
+    response_metadata = merge_dicts(
+        cast("dict", left.response_metadata),
+        *(cast("dict", o.response_metadata) for o in others),
+    )
+
+    # Token usage
+    if left.usage_metadata or any(o.usage_metadata is not None for o in others):
+        usage_metadata: Optional[UsageMetadata] = left.usage_metadata
+        for other in others:
+            usage_metadata = add_usage(usage_metadata, other.usage_metadata)
+    else:
+        usage_metadata = None
+
+    # Parsed
+    # 'parsed' always represents an aggregation not an incremental value, so the last
+    # non-null value is kept.
+    parsed = None
+    for m in reversed([left, *others]):
+        if m.parsed is not None:
+            parsed = m.parsed
+            break
+
+    chunk_id = None
+    candidates = [left.id] + [o.id for o in others]
+    # first pass: pick the first provider-assigned id (non-`run-*` and non-`lc_*`)
+    for id_ in candidates:
+        if (
+            id_
+            and not id_.startswith(_LC_ID_PREFIX)
+            and not id_.startswith(_LC_AUTO_PREFIX)
+        ):
+            chunk_id = id_
+            break
+    else:
+        # second pass: prefer lc_* ids over run-* ids
+        for id_ in candidates:
+            if id_ and id_.startswith(_LC_AUTO_PREFIX):
+                chunk_id = id_
+                break
+        else:
+            # third pass: take any remaining id (run-* ids)
+            for id_ in candidates:
+                if id_:
+                    chunk_id = id_
+                    break
+
+    chunk_position: Optional[Literal["last"]] = (
+        "last" if any(x.chunk_position == "last" for x in [left, *others]) else None
+    )
+    if chunk_position == "last":
+        content = _init_tool_calls(content)
+
+    return left.__class__(
+        content=content,
+        response_metadata=cast("ResponseMetadata", response_metadata),
+        usage_metadata=usage_metadata,
+        parsed=parsed,
+        id=chunk_id,
+        chunk_position=chunk_position,
+    )
+
+
+@dataclass
+class HumanMessage:
+    """A message from a human user.
+
+    Represents input from a human user in a conversation, containing text
+    or other content types like images.
+
+    Attributes:
+        id: Unique identifier for the message.
+        content: List of content blocks containing the user's input.
+        name: Optional human-readable name for the message.
+        type: Message type identifier, always "human".
+    """
+
+    id: str
+    """Used for serialization.
+
+    If the provider assigns a meaningful ID, it should be used here. Otherwise, a
+    LangChain-generated ID will be used.
+    """
+
+    content: list[types.ContentBlock]
+    """Message content as a list of content blocks."""
+
+    type: Literal["human"] = "human"
+    """The type of the message. Must be a string that is unique to the message type.
+
+    The purpose of this field is to allow for easy identification of the message type
+    when deserializing messages.
+    """
+
+    name: Optional[str] = None
+    """An optional name for the message.
+
+    This can be used to provide a human-readable name for the message.
+
+    Usage of this field is optional, and whether it's used or not is up to the
+    model implementation.
+    """
+
+    def __init__(
+        self,
+        content: Union[str, list[types.ContentBlock]],
+        *,
+        id: Optional[str] = None,
+        name: Optional[str] = None,
+    ):
+        """Initialize a human message.
+
+        Args:
+            content: Message content as string or list of content blocks.
+            id: Optional unique identifier for the message.
+            name: Optional human-readable name for the message.
+        """
+        self.id = _ensure_id(id)
+        if isinstance(content, str):
+            self.content = [{"type": "text", "text": content}]
+        else:
+            self.content = content
+        self.name = name
+
+    def text(self) -> str:
+        """Extract all text content from the message.
+
+        Returns:
+            Concatenated string of all text blocks in the message.
+        """
+        return "".join(
+            block["text"] for block in self.content if block["type"] == "text"
+        )
+
+
+@dataclass
+class SystemMessage:
+    """A system message containing instructions or context.
+
+    Represents system-level instructions or context that guides the AI's
+    behavior and understanding of the conversation.
+
+    Attributes:
+        id: Unique identifier for the message.
+        content: List of content blocks containing system instructions.
+        type: Message type identifier, always "system".
+    """
+
+    id: str
+    """Used for serialization.
+
+    If the provider assigns a meaningful ID, it should be used here. Otherwise, a
+    LangChain-generated ID will be used.
+    """
+
+    content: list[types.ContentBlock]
+    """Message content as a list of content blocks."""
+
+    type: Literal["system"] = "system"
+    """The type of the message. Must be a string that is unique to the message type.
+
+    The purpose of this field is to allow for easy identification of the message type
+    when deserializing messages.
+    """
+
+    name: Optional[str] = None
+    """An optional name for the message.
+
+    This can be used to provide a human-readable name for the message.
+
+    Usage of this field is optional, and whether it's used or not is up to the
+    model implementation.
+    """
+
+    custom_role: Optional[str] = None
+    """If provided, a custom role for the system message.
+
+    Example: ``"developer"``.
+
+    Integration packages may use this field to assign the system message role if it
+    contains a recognized value.
+    """
+
+    def __init__(
+        self,
+        content: Union[str, list[types.ContentBlock]],
+        *,
+        id: Optional[str] = None,
+        custom_role: Optional[str] = None,
+        name: Optional[str] = None,
+    ):
+        """Initialize a human message.
+
+        Args:
+            content: Message content as string or list of content blocks.
+            id: Optional unique identifier for the message.
+            custom_role: If provided, a custom role for the system message.
+            name: Optional human-readable name for the message.
+        """
+        self.id = _ensure_id(id)
+        if isinstance(content, str):
+            self.content = [{"type": "text", "text": content}]
+        else:
+            self.content = content
+        self.custom_role = custom_role
+        self.name = name
+
+    def text(self) -> str:
+        """Extract all text content from the system message."""
+        return "".join(
+            block["text"] for block in self.content if block["type"] == "text"
+        )
+
+
+@dataclass
+class ToolMessage(ToolOutputMixin):
+    """A message containing the result of a tool execution.
+
+    Represents the output from executing a tool or function call,
+    including the result data and execution status.
+
+    Attributes:
+        id: Unique identifier for the message.
+        tool_call_id: ID of the tool call this message responds to.
+        content: The result content from tool execution.
+        artifact: Optional app-side payload not intended for the model.
+        status: Execution status ("success" or "error").
+        type: Message type identifier, always "tool".
+    """
+
+    id: str
+    """Used for serialization."""
+
+    tool_call_id: str
+    """ID of the tool call this message responds to.
+
+    This should match the ID of the tool call that this message is responding to.
+    """
+
+    content: list[types.ContentBlock]
+    """Message content as a list of content blocks."""
+
+    type: Literal["tool"] = "tool"
+    """The type of the message. Must be a string that is unique to the message type.
+
+    The purpose of this field is to allow for easy identification of the message type
+    when deserializing messages.
+    """
+
+    artifact: Optional[Any] = None
+    """App-side payload not for the model."""
+
+    name: Optional[str] = None
+    """An optional name for the message.
+
+    This can be used to provide a human-readable name for the message.
+
+    Usage of this field is optional, and whether it's used or not is up to the
+    model implementation.
+    """
+
+    status: Literal["success", "error"] = "success"
+    """Execution status of the tool call.
+
+    Indicates whether the tool call was successful or encountered an error.
+    Defaults to "success".
+    """
+
+    def __init__(
+        self,
+        content: Union[str, list[types.ContentBlock]],
+        tool_call_id: str,
+        *,
+        id: Optional[str] = None,
+        name: Optional[str] = None,
+        artifact: Optional[Any] = None,
+        status: Literal["success", "error"] = "success",
+    ):
+        """Initialize a human message.
+
+        Args:
+            content: Message content as string or list of content blocks.
+            tool_call_id: ID of the tool call this message responds to.
+            id: Optional unique identifier for the message.
+            name: Optional human-readable name for the message.
+            artifact: Optional app-side payload not intended for the model.
+            status: Execution status ("success" or "error").
+        """
+        self.id = _ensure_id(id)
+        self.tool_call_id = tool_call_id
+        if isinstance(content, str):
+            self.content = [{"type": "text", "text": content}]
+        else:
+            self.content = content
+        self.name = name
+        self.artifact = artifact
+        self.status = status
+
+    @property
+    def text(self) -> str:
+        """Extract all text content from the tool message."""
+        return "".join(
+            block["text"] for block in self.content if block["type"] == "text"
+        )
+
+    def __post_init__(self) -> None:
+        """Initialize computed fields after dataclass creation.
+
+        Ensures the tool message has a valid ID.
+        """
+        self.id = _ensure_id(self.id)
+
+
+# Alias for a message type that can be any of the defined message types
+MessageV1 = Union[
+    AIMessage,
+    AIMessageChunk,
+    HumanMessage,
+    SystemMessage,
+    ToolMessage,
+]
+MessageV1Types = get_args(MessageV1)