langchain-core 0.3.75__py3-none-any.whl → 1.0.0a1__py3-none-any.whl

langchain_core/messages/ai.py

@@ -3,11 +3,13 @@
 import json
 import logging
 import operator
+from collections.abc import Sequence
 from typing import Any, Literal, Optional, Union, cast
 
 from pydantic import model_validator
-from typing_extensions import NotRequired, Self, TypedDict, override
+from typing_extensions import NotRequired, Self, TypedDict, overload, override
 
+from langchain_core.messages import content as types
 from langchain_core.messages.base import (
     BaseMessage,
     BaseMessageChunk,
@@ -20,25 +22,17 @@ from langchain_core.messages.tool import (
     default_tool_chunk_parser,
     default_tool_parser,
 )
-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.messages.tool import (
-    tool_call_chunk as create_tool_call_chunk,
-)
+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.messages.tool import tool_call_chunk as create_tool_call_chunk
 from langchain_core.utils._merge import merge_dicts, merge_lists
 from langchain_core.utils.json import parse_partial_json
 from langchain_core.utils.usage import _dict_int_op
+from langchain_core.utils.utils import LC_AUTO_PREFIX, LC_ID_PREFIX
 
 logger = logging.getLogger(__name__)
 
 
-_LC_ID_PREFIX = "run-"
-
-
 class InputTokenDetails(TypedDict, total=False):
     """Breakdown of input token counts.
 
@@ -180,16 +174,42 @@ class AIMessage(BaseMessage):
     type: Literal["ai"] = "ai"
     """The type of the message (used for deserialization). Defaults to "ai"."""
 
+    @overload
+    def __init__(
+        self,
+        content: Union[str, list[Union[str, dict]]],
+        **kwargs: Any,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        content: Optional[Union[str, list[Union[str, dict]]]] = None,
+        content_blocks: Optional[list[types.ContentBlock]] = None,
+        **kwargs: Any,
+    ) -> None: ...
+
     def __init__(
-        self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
+        self,
+        content: Optional[Union[str, list[Union[str, dict]]]] = None,
+        content_blocks: Optional[list[types.ContentBlock]] = None,
+        **kwargs: Any,
     ) -> None:
-        """Pass in content as positional arg.
+        """Specify ``content`` as positional arg or ``content_blocks`` for typing."""
+        if content_blocks is not None:
+            # If there are tool calls in content_blocks, but not in tool_calls, add them
+            content_tool_calls = [
+                block for block in content_blocks if block.get("type") == "tool_call"
+            ]
+            if content_tool_calls and "tool_calls" not in kwargs:
+                kwargs["tool_calls"] = content_tool_calls
 
-        Args:
-            content: The content of the message.
-            kwargs: Additional arguments to pass to the parent class.
-        """
-        super().__init__(content=content, **kwargs)
+            super().__init__(
+                content=cast("Union[str, list[Union[str, dict]]]", content_blocks),
+                **kwargs,
+            )
+        else:
+            super().__init__(content=content, **kwargs)
 
     @property
     def lc_attributes(self) -> dict:
@@ -199,6 +219,49 @@ class AIMessage(BaseMessage):
             "invalid_tool_calls": self.invalid_tool_calls,
         }
 
+    @property
+    def content_blocks(self) -> list[types.ContentBlock]:
+        """Return content blocks of the message."""
+        if self.response_metadata.get("output_version") == "v1":
+            return cast("list[types.ContentBlock]", self.content)
+
+        model_provider = self.response_metadata.get("model_provider")
+        if model_provider:
+            from langchain_core.messages.block_translators import get_translator
+
+            translator = get_translator(model_provider)
+            if translator:
+                try:
+                    return translator["translate_content"](self)
+                except NotImplementedError:
+                    pass
+
+        # Otherwise, use best-effort parsing
+        blocks = super().content_blocks
+
+        if self.tool_calls:
+            # Add from tool_calls if missing from content
+            content_tool_call_ids = {
+                block.get("id")
+                for block in self.content
+                if isinstance(block, dict) and block.get("type") == "tool_call"
+            }
+            for tool_call in self.tool_calls:
+                if (id_ := tool_call.get("id")) and id_ not in content_tool_call_ids:
+                    tool_call_block: types.ToolCall = {
+                        "type": "tool_call",
+                        "id": id_,
+                        "name": tool_call["name"],
+                        "args": tool_call["args"],
+                    }
+                    if "index" in tool_call:
+                        tool_call_block["index"] = tool_call["index"]  # type: ignore[typeddict-item]
+                    if "extras" in tool_call:
+                        tool_call_block["extras"] = tool_call["extras"]  # type: ignore[typeddict-item]
+                    blocks.append(tool_call_block)
+
+        return blocks
+
     # TODO: remove this logic if possible, reducing breaking nature of changes
     @model_validator(mode="before")
     @classmethod
@@ -227,7 +290,9 @@ class AIMessage(BaseMessage):
         # Ensure "type" is properly set on all tool call-like dicts.
         if tool_calls := values.get("tool_calls"):
             values["tool_calls"] = [
-                create_tool_call(**{k: v for k, v in tc.items() if k != "type"})
+                create_tool_call(
+                    **{k: v for k, v in tc.items() if k not in ("type", "extras")}
+                )
                 for tc in tool_calls
             ]
         if invalid_tool_calls := values.get("invalid_tool_calls"):
@@ -298,6 +363,13 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
     tool_call_chunks: list[ToolCallChunk] = []
     """If provided, tool call chunks associated with the message."""
 
+    chunk_position: Optional[Literal["last"]] = None
+    """Optional span represented by an aggregated AIMessageChunk.
+
+    If a chunk with ``chunk_position="last"`` is aggregated into a stream,
+    ``tool_call_chunks`` in message content will be parsed into ``tool_calls``.
+    """
+
     @property
     def lc_attributes(self) -> dict:
         """Attrs to be serialized even if they are derived from other init args."""
@@ -306,6 +378,49 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
             "invalid_tool_calls": self.invalid_tool_calls,
         }
 
+    @property
+    def content_blocks(self) -> list[types.ContentBlock]:
+        """Return content blocks of the message."""
+        if self.response_metadata.get("output_version") == "v1":
+            return cast("list[types.ContentBlock]", self.content)
+
+        model_provider = self.response_metadata.get("model_provider")
+        if model_provider:
+            from langchain_core.messages.block_translators import get_translator
+
+            translator = get_translator(model_provider)
+            if translator:
+                try:
+                    return translator["translate_content_chunk"](self)
+                except NotImplementedError:
+                    pass
+
+        # Otherwise, use best-effort parsing
+        blocks = super().content_blocks
+
+        if (
+            self.tool_call_chunks
+            and not self.content
+            and self.chunk_position != "last"  # keep tool_calls if aggregated
+        ):
+            blocks = [
+                block
+                for block in blocks
+                if block["type"] not in ("tool_call", "invalid_tool_call")
+            ]
+            for tool_call_chunk in self.tool_call_chunks:
+                tc: types.ToolCallChunk = {
+                    "type": "tool_call_chunk",
+                    "id": tool_call_chunk.get("id"),
+                    "name": tool_call_chunk.get("name"),
+                    "args": tool_call_chunk.get("args"),
+                }
+                if (idx := tool_call_chunk.get("index")) is not None:
+                    tc["index"] = idx
+                blocks.append(tc)
+
+        return blocks
+
     @model_validator(mode="after")
     def init_tool_calls(self) -> Self:
         """Initialize tool calls from tool call chunks.
@@ -376,10 +491,45 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
                 add_chunk_to_invalid_tool_calls(chunk)
         self.tool_calls = tool_calls
         self.invalid_tool_calls = invalid_tool_calls
+
+        if (
+            self.chunk_position == "last"
+            and self.tool_call_chunks
+            and self.response_metadata.get("output_version") == "v1"
+            and isinstance(self.content, list)
+        ):
+            id_to_tc: dict[str, types.ToolCall] = {
+                cast("str", tc.get("id")): {
+                    "type": "tool_call",
+                    "name": tc["name"],
+                    "args": tc["args"],
+                    "id": tc.get("id"),
+                }
+                for tc in self.tool_calls
+                if "id" in tc
+            }
+            for idx, block in enumerate(self.content):
+                if (
+                    isinstance(block, dict)
+                    and block.get("type") == "tool_call_chunk"
+                    and (call_id := block.get("id"))
+                    and call_id in id_to_tc
+                ):
+                    self.content[idx] = cast("dict[str, Any]", id_to_tc[call_id])
+
         return self
 
+    @overload  # type: ignore[override]  # summing BaseMessages gives ChatPromptTemplate
+    def __add__(self, other: "AIMessageChunk") -> "AIMessageChunk": ...
+
+    @overload
+    def __add__(self, other: Sequence["AIMessageChunk"]) -> "AIMessageChunk": ...
+
+    @overload
+    def __add__(self, other: Any) -> BaseMessageChunk: ...
+
     @override
-    def __add__(self, other: Any) -> BaseMessageChunk:  # type: ignore[override]
+    def __add__(self, other: Any) -> BaseMessageChunk:
         if isinstance(other, AIMessageChunk):
             return add_ai_message_chunks(self, other)
         if isinstance(other, (list, tuple)) and all(
@@ -431,17 +581,31 @@ def add_ai_message_chunks(
 
     chunk_id = None
     candidates = [left.id] + [o.id for o in others]
-    # first pass: pick the first non-run-* id
+    # 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):
+        if (
+            id_
+            and not id_.startswith(LC_ID_PREFIX)
+            and not id_.startswith(LC_AUTO_PREFIX)
+        ):
             chunk_id = id_
             break
     else:
-        # second pass: no provider-assigned id found, just take the first non-null
+        # second pass: prefer lc_run-* ids over lc_* ids
         for id_ in candidates:
-            if id_:
+            if id_ and id_.startswith(LC_ID_PREFIX):
                 chunk_id = id_
                 break
+        else:
+            # third pass: take any remaining id (auto-generated lc_* 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
+    )
 
     return left.__class__(
         example=left.example,
@@ -451,6 +615,7 @@ def add_ai_message_chunks(
         response_metadata=response_metadata,
         usage_metadata=usage_metadata,
         id=chunk_id,
+        chunk_position=chunk_position,
     )
 
 

langchain_core/messages/base.py

@@ -2,11 +2,14 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, Optional, Union, cast, overload
 
 from pydantic import ConfigDict, Field
+from typing_extensions import Self
 
+from langchain_core._api.deprecation import warn_deprecated
 from langchain_core.load.serializable import Serializable
+from langchain_core.messages import content as types
 from langchain_core.utils import get_bolded_text
 from langchain_core.utils._merge import merge_dicts, merge_lists
 from langchain_core.utils.interactive_env import is_interactive_env
@@ -17,6 +20,52 @@ if TYPE_CHECKING:
     from langchain_core.prompts.chat import ChatPromptTemplate
 
 
+class TextAccessor(str):
+    """String-like object that supports both property and method access patterns.
+
+    Exists to maintain backward compatibility while transitioning from method-based to
+    property-based text access in message objects. In LangChain <v1.0, message text was
+    accessed via ``.text()`` method calls. In v1.0=<, the preferred pattern is property
+    access via ``.text``.
+
+    Rather than breaking existing code immediately, ``TextAccessor`` allows both
+    patterns:
+    - Modern property access: ``message.text`` (returns string directly)
+    - Legacy method access: ``message.text()`` (callable, emits deprecation warning)
+
+    """
+
+    __slots__ = ()
+
+    def __new__(cls, value: str) -> Self:
+        """Create new TextAccessor instance."""
+        return str.__new__(cls, value)
+
+    def __call__(self) -> str:
+        """Enable method-style text access for backward compatibility.
+
+        This method exists solely to support legacy code that calls ``.text()``
+        as a method. New code should use property access (``.text``) instead.
+
+        .. deprecated:: 1.0.0
+            Calling ``.text()`` as a method is deprecated. Use ``.text`` as a property
+            instead. This method will be removed in 2.0.0.
+
+        Returns:
+            The string content, identical to property access.
+
+        """
+        warn_deprecated(
+            since="1.0.0",
+            message=(
+                "Calling .text() as a method is deprecated. "
+                "Use .text as a property instead (e.g., message.text)."
+            ),
+            removal="2.0.0",
+        )
+        return str(self)
+
+
 class BaseMessage(Serializable):
     """Base abstract message class.
 
@@ -61,15 +110,32 @@ class BaseMessage(Serializable):
         extra="allow",
     )
 
+    @overload
     def __init__(
-        self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
-    ) -> None:
-        """Pass in content as positional arg.
+        self,
+        content: Union[str, list[Union[str, dict]]],
+        **kwargs: Any,
+    ) -> None: ...
 
-        Args:
-            content: The string contents of the message.
-        """
-        super().__init__(content=content, **kwargs)
+    @overload
+    def __init__(
+        self,
+        content: Optional[Union[str, list[Union[str, dict]]]] = None,
+        content_blocks: Optional[list[types.ContentBlock]] = None,
+        **kwargs: Any,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        content: Optional[Union[str, list[Union[str, dict]]]] = None,
+        content_blocks: Optional[list[types.ContentBlock]] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Specify ``content`` as positional arg or ``content_blocks`` for typing."""
+        if content_blocks is not None:
+            super().__init__(content=content_blocks, **kwargs)
+        else:
+            super().__init__(content=content, **kwargs)
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
@@ -88,25 +154,96 @@ class BaseMessage(Serializable):
         """
         return ["langchain", "schema", "messages"]
 
-    def text(self) -> str:
-        """Get the text content of the message.
+    @property
+    def content_blocks(self) -> list[types.ContentBlock]:
+        r"""Return ``content`` as a list of standardized :class:`~langchain_core.messages.content.ContentBlock`\s.
+
+        .. important::
+
+            To use this property correctly, the corresponding ``ChatModel`` must support
+            ``message_version='v1'`` or higher (and it must be set):
+
+            .. code-block:: python
+
+                from langchain.chat_models import init_chat_model
+                llm = init_chat_model("...", message_version="v1")
+
+                # or
+
+                from langchain-openai import ChatOpenAI
+                llm = ChatOpenAI(model="gpt-4o", message_version="v1")
+
+            Otherwise, the property will perform best-effort parsing to standard types,
+            though some content may be misinterpreted.
+
+        .. versionadded:: 1.0.0
+
+        """  # noqa: E501
+        from langchain_core.messages import content as types
+        from langchain_core.messages.block_translators.anthropic import (
+            _convert_to_v1_from_anthropic_input,
+        )
+        from langchain_core.messages.block_translators.langchain_v0 import (
+            _convert_v0_multimodal_input_to_v1,
+        )
+        from langchain_core.messages.block_translators.openai import (
+            _convert_to_v1_from_chat_completions_input,
+        )
+
+        blocks: list[types.ContentBlock] = []
+
+        # First pass: convert to standard blocks
+        content = (
+            [self.content]
+            if isinstance(self.content, str) and self.content
+            else self.content
+        )
+        for item in content:
+            if isinstance(item, str):
+                blocks.append({"type": "text", "text": item})
+            elif isinstance(item, dict):
+                item_type = item.get("type")
+                if item_type not in types.KNOWN_BLOCK_TYPES:
+                    blocks.append({"type": "non_standard", "value": item})
+                else:
+                    blocks.append(cast("types.ContentBlock", item))
+
+        # Subsequent passes: attempt to unpack non-standard blocks
+        for parsing_step in [
+            _convert_v0_multimodal_input_to_v1,
+            _convert_to_v1_from_chat_completions_input,
+            _convert_to_v1_from_anthropic_input,
+        ]:
+            blocks = parsing_step(blocks)
+        return blocks
+
+    @property
+    def text(self) -> TextAccessor:
+        """Get the text content of the message as a string.
+
+        Can be used as both property (``message.text``) and method (``message.text()``).
+
+        .. deprecated:: 1.0.0
+            Calling ``.text()`` as a method is deprecated. Use ``.text`` as a property
+            instead. This method will be removed in 2.0.0.
 
         Returns:
             The text content of the message.
         """
         if isinstance(self.content, str):
-            return self.content
-
-        # must be a list
-        blocks = [
-            block
-            for block in self.content
-            if isinstance(block, str)
-            or (block.get("type") == "text" and isinstance(block.get("text"), str))
-        ]
-        return "".join(
-            block if isinstance(block, str) else block["text"] for block in blocks
-        )
+            text_value = self.content
+        else:
+            # must be a list
+            blocks = [
+                block
+                for block in self.content
+                if isinstance(block, str)
+                or (block.get("type") == "text" and isinstance(block.get("text"), str))
+            ]
+            text_value = "".join(
+                block if isinstance(block, str) else block["text"] for block in blocks
+            )
+        return TextAccessor(text_value)
 
     def __add__(self, other: Any) -> ChatPromptTemplate:
         """Concatenate this message with another message."""
@@ -152,7 +289,9 @@ def merge_content(
     Returns:
         The merged content.
     """
-    merged = first_content
+    merged: Union[str, list[Union[str, dict]]]
+    merged = "" if first_content is None else first_content
+
     for content in contents:
         # If current is a string
         if isinstance(merged, str):
@@ -173,8 +312,8 @@ def merge_content(
         # If second content is an empty string, treat as a no-op
         elif content == "":
             pass
-        else:
-            # Otherwise, add the second content as a new element of the list
+        # Otherwise, add the second content as a new element of the list
+        elif merged:
             merged.append(content)
     return merged
 

langchain_core/messages/block_translators/__init__.py

@@ -0,0 +1,89 @@
+"""Derivations of standard content blocks from provider content."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable
+
+if TYPE_CHECKING:
+    from langchain_core.messages import AIMessage, AIMessageChunk
+    from langchain_core.messages import content as types
+
+# Provider to translator mapping
+PROVIDER_TRANSLATORS: dict[str, dict[str, Callable[..., list[types.ContentBlock]]]] = {}
+
+
+def register_translator(
+    provider: str,
+    translate_content: Callable[[AIMessage], list[types.ContentBlock]],
+    translate_content_chunk: Callable[[AIMessageChunk], list[types.ContentBlock]],
+) -> None:
+    """Register content translators for a provider.
+
+    Args:
+        provider: The model provider name (e.g. ``'openai'``, ``'anthropic'``).
+        translate_content: Function to translate ``AIMessage`` content.
+        translate_content_chunk: Function to translate ``AIMessageChunk`` content.
+    """
+    PROVIDER_TRANSLATORS[provider] = {
+        "translate_content": translate_content,
+        "translate_content_chunk": translate_content_chunk,
+    }
+
+
+def get_translator(
+    provider: str,
+) -> dict[str, Callable[..., list[types.ContentBlock]]] | None:
+    """Get the translator functions for a provider.
+
+    Args:
+        provider: The model provider name.
+
+    Returns:
+        Dictionary with ``'translate_content'`` and ``'translate_content_chunk'``
+        functions, or None if no translator is registered for the provider.
+    """
+    return PROVIDER_TRANSLATORS.get(provider)
+
+
+def _register_translators() -> None:
+    """Register all translators in langchain-core.
+
+    A unit test ensures all modules in ``block_translators`` are represented here.
+
+    For translators implemented outside langchain-core, they can be registered by
+    calling ``register_translator`` from within the integration package.
+    """
+    from langchain_core.messages.block_translators.anthropic import (
+        _register_anthropic_translator,
+    )
+    from langchain_core.messages.block_translators.bedrock import (
+        _register_bedrock_translator,
+    )
+    from langchain_core.messages.block_translators.bedrock_converse import (
+        _register_bedrock_converse_translator,
+    )
+    from langchain_core.messages.block_translators.google_genai import (
+        _register_google_genai_translator,
+    )
+    from langchain_core.messages.block_translators.google_vertexai import (
+        _register_google_vertexai_translator,
+    )
+    from langchain_core.messages.block_translators.groq import _register_groq_translator
+    from langchain_core.messages.block_translators.ollama import (
+        _register_ollama_translator,
+    )
+    from langchain_core.messages.block_translators.openai import (
+        _register_openai_translator,
+    )
+
+    _register_bedrock_translator()
+    _register_bedrock_converse_translator()
+    _register_anthropic_translator()
+    _register_google_genai_translator()
+    _register_google_vertexai_translator()
+    _register_groq_translator()
+    _register_ollama_translator()
+    _register_openai_translator()
+
+
+_register_translators()