langchain-core 1.0.0a4__py3-none-any.whl → 1.0.0a6__py3-none-any.whl

langchain_core/messages/base.py

@@ -20,6 +20,31 @@ if TYPE_CHECKING:
     from langchain_core.prompts.chat import ChatPromptTemplate
 
 
+def _extract_reasoning_from_additional_kwargs(
+    message: BaseMessage,
+) -> Optional[types.ReasoningContentBlock]:
+    """Extract `reasoning_content` from `additional_kwargs`.
+
+    Handles reasoning content stored in various formats:
+    - `additional_kwargs["reasoning_content"]` (string) - Ollama, DeepSeek, XAI, Groq
+
+    Args:
+        message: The message to extract reasoning from.
+
+    Returns:
+        A `ReasoningContentBlock` if reasoning content is found, None otherwise.
+    """
+    from langchain_core.messages.content import create_reasoning_block  # noqa: PLC0415
+
+    additional_kwargs = getattr(message, "additional_kwargs", {})
+
+    reasoning_content = additional_kwargs.get("reasoning_content")
+    if reasoning_content is not None and isinstance(reasoning_content, str):
+        return create_reasoning_block(reasoning=reasoning_content)
+
+    return None
+
+
 class TextAccessor(str):
     """String-like object that supports both property and method access patterns.
 
@@ -69,7 +94,7 @@ class TextAccessor(str):
 class BaseMessage(Serializable):
     """Base abstract message class.
 
-    Messages are the inputs and outputs of ChatModels.
+    Messages are the inputs and outputs of ``ChatModel``s.
     """
 
     content: Union[str, list[Union[str, dict]]]
@@ -80,17 +105,18 @@ class BaseMessage(Serializable):
 
     For example, for a message from an AI, this could include tool calls as
     encoded by the model provider.
+
     """
 
     response_metadata: dict = Field(default_factory=dict)
-    """Response metadata. For example: response headers, logprobs, token counts, model
-    name."""
+    """Examples: response headers, logprobs, token counts, model name."""
 
     type: str
     """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
@@ -100,11 +126,15 @@ class BaseMessage(Serializable):
 
     Usage of this field is optional, and whether it's used or not is up to the
     model implementation.
+
     """
 
     id: Optional[str] = Field(default=None, coerce_numbers_to_str=True)
-    """An optional unique identifier for the message. This should ideally be
-    provided by the provider/model which created the message."""
+    """An optional unique identifier for the message.
+
+    This should ideally be provided by the provider/model which created the message.
+
+    """
 
     model_config = ConfigDict(
         extra="allow",
@@ -131,7 +161,15 @@ class BaseMessage(Serializable):
         content_blocks: Optional[list[types.ContentBlock]] = None,
         **kwargs: Any,
     ) -> None:
-        """Specify ``content`` as positional arg or ``content_blocks`` for typing."""
+        """Initialize ``BaseMessage``.
+
+        Specify ``content`` as positional arg or ``content_blocks`` for typing.
+
+        Args:
+            content: The string contents of the message.
+            content_blocks: Typed standard content.
+            kwargs: Additional arguments to pass to the parent class.
+        """
         if content_blocks is not None:
             super().__init__(content=content_blocks, **kwargs)
         else:
@@ -139,7 +177,7 @@ class BaseMessage(Serializable):
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """BaseMessage is serializable.
+        """``BaseMessage`` is serializable.
 
         Returns:
             True
@@ -157,29 +195,12 @@ class BaseMessage(Serializable):
 
     @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.
+        r"""Load content blocks from the message content.
 
         .. versionadded:: 1.0.0
 
-        """  # noqa: E501
+        """
+        # Needed here to avoid circular import, as these classes import BaseMessages
         from langchain_core.messages import content as types  # noqa: PLC0415
         from langchain_core.messages.block_translators.anthropic import (  # noqa: PLC0415
             _convert_to_v1_from_anthropic_input,
@@ -187,6 +208,9 @@ class BaseMessage(Serializable):
         from langchain_core.messages.block_translators.bedrock_converse import (  # noqa: PLC0415
             _convert_to_v1_from_converse_input,
         )
+        from langchain_core.messages.block_translators.google_genai import (  # noqa: PLC0415
+            _convert_to_v1_from_genai_input,
+        )
         from langchain_core.messages.block_translators.langchain_v0 import (  # noqa: PLC0415
             _convert_v0_multimodal_input_to_v1,
         )
@@ -195,28 +219,39 @@ class BaseMessage(Serializable):
         )
 
         blocks: list[types.ContentBlock] = []
-
-        # First pass: convert to standard blocks
         content = (
+            # Transpose string content to list, otherwise assumed to be list
             [self.content]
             if isinstance(self.content, str) and self.content
             else self.content
         )
         for item in content:
             if isinstance(item, str):
+                # Plain string content is treated as a text block
                 blocks.append({"type": "text", "text": item})
             elif isinstance(item, dict):
                 item_type = item.get("type")
                 if item_type not in types.KNOWN_BLOCK_TYPES:
+                    # Handle all provider-specific or None type blocks as non-standard -
+                    # we'll come back to these later
                     blocks.append({"type": "non_standard", "value": item})
                 else:
+                    # Guard against v0 blocks that share the same `type` keys
+                    if "source_type" in item:
+                        blocks.append({"type": "non_standard", "value": item})
+                        continue
+
+                    # This can't be a v0 block (since they require `source_type`),
+                    # so it's a known v1 block type
                     blocks.append(cast("types.ContentBlock", item))
 
-        # Subsequent passes: attempt to unpack non-standard blocks
+        # Subsequent passes: attempt to unpack non-standard blocks.
+        # This is the last stop - if we can't parse it here, it is left as non-standard
         for parsing_step in [
             _convert_v0_multimodal_input_to_v1,
             _convert_to_v1_from_chat_completions_input,
             _convert_to_v1_from_anthropic_input,
+            _convert_to_v1_from_genai_input,
             _convert_to_v1_from_converse_input,
         ]:
             blocks = parsing_step(blocks)
@@ -234,6 +269,7 @@ class BaseMessage(Serializable):
 
         Returns:
             The text content of the message.
+
         """
         if isinstance(self.content, str):
             text_value = self.content
@@ -277,6 +313,7 @@ class BaseMessage(Serializable):
 
         Returns:
             A pretty representation of the message.
+
         """
         title = get_msg_title_repr(self.type.title() + " Message", bold=html)
         # TODO: handle non-string content.
@@ -296,11 +333,12 @@ def merge_content(
     """Merge multiple message contents.
 
     Args:
-        first_content: The first content. Can be a string or a list.
-        contents: The other contents. Can be a string or a list.
+        first_content: The first ``content``. Can be a string or a list.
+        contents: The other ``content``s. Can be a string or a list.
 
     Returns:
         The merged content.
+
     """
     merged: Union[str, list[Union[str, dict]]]
     merged = "" if first_content is None else first_content
@@ -352,9 +390,10 @@ class BaseMessageChunk(BaseMessage):
 
         For example,
 
-        `AIMessageChunk(content="Hello") + AIMessageChunk(content=" World")`
+        ``AIMessageChunk(content="Hello") + AIMessageChunk(content=" World")``
+
+        will give ``AIMessageChunk(content="Hello World")``
 
-        will give `AIMessageChunk(content="Hello World")`
         """
         if isinstance(other, BaseMessageChunk):
             # If both are (subclasses of) BaseMessageChunk,
@@ -402,8 +441,9 @@ def message_to_dict(message: BaseMessage) -> dict:
         message: Message to convert.
 
     Returns:
-        Message as a dict. The dict will have a "type" key with the message type
-        and a "data" key with the message data as a dict.
+        Message as a dict. The dict will have a ``type`` key with the message type
+        and a ``data`` key with the message data as a dict.
+
     """
     return {"type": message.type, "data": message.model_dump()}
 
@@ -412,10 +452,11 @@ def messages_to_dict(messages: Sequence[BaseMessage]) -> list[dict]:
     """Convert a sequence of Messages to a list of dictionaries.
 
     Args:
-        messages: Sequence of messages (as BaseMessages) to convert.
+        messages: Sequence of messages (as ``BaseMessage``s) to convert.
 
     Returns:
         List of messages as dicts.
+
     """
     return [message_to_dict(m) for m in messages]
 
@@ -429,6 +470,7 @@ def get_msg_title_repr(title: str, *, bold: bool = False) -> str:
 
     Returns:
         The title representation.
+
     """
     padded = " " + title + " "
     sep_len = (80 - len(padded)) // 2

langchain_core/messages/block_translators/__init__.py

@@ -1,4 +1,14 @@
-"""Derivations of standard content blocks from provider content."""
+"""Derivations of standard content blocks from provider content.
+
+``AIMessage`` will first attempt to use a provider-specific translator if
+``model_provider`` is set in ``response_metadata`` on the message. Consequently, each
+provider translator must handle all possible content response types from the provider,
+including text.
+
+If no provider is set, or if the provider does not have a registered translator,
+``AIMessage`` will fall back to best-effort parsing of the content into blocks using
+the implementation in ``BaseMessage``.
+"""
 
 from __future__ import annotations
 
@@ -10,6 +20,18 @@ if TYPE_CHECKING:
 
 # Provider to translator mapping
 PROVIDER_TRANSLATORS: dict[str, dict[str, Callable[..., list[types.ContentBlock]]]] = {}
+"""Map model provider names to translator functions.
+
+The dictionary maps provider names (e.g. ``'openai'``, ``'anthropic'``) to another
+dictionary with two keys:
+- ``'translate_content'``: Function to translate ``AIMessage`` content.
+- ``'translate_content_chunk'``: Function to translate ``AIMessageChunk`` content.
+
+When calling `.content_blocks` on an ``AIMessage`` or ``AIMessageChunk``, if
+``model_provider`` is set in ``response_metadata``, the corresponding translator
+functions will be used to parse the content into blocks. Otherwise, best-effort parsing
+in ``BaseMessage`` will be used.
+"""
 
 
 def register_translator(
@@ -17,7 +39,7 @@ def register_translator(
     translate_content: Callable[[AIMessage], list[types.ContentBlock]],
     translate_content_chunk: Callable[[AIMessageChunk], list[types.ContentBlock]],
 ) -> None:
-    """Register content translators for a provider.
+    """Register content translators for a provider in `PROVIDER_TRANSLATORS`.
 
     Args:
         provider: The model provider name (e.g. ``'openai'``, ``'anthropic'``).
@@ -40,7 +62,8 @@ def get_translator(
 
     Returns:
         Dictionary with ``'translate_content'`` and ``'translate_content_chunk'``
-        functions, or None if no translator is registered for the provider.
+        functions, or None if no translator is registered for the provider. In such
+        case, best-effort parsing in ``BaseMessage`` will be used.
     """
     return PROVIDER_TRANSLATORS.get(provider)
 

langchain_core/messages/block_translators/anthropic.py

@@ -29,7 +29,21 @@ def _populate_extras(
 def _convert_to_v1_from_anthropic_input(
     content: list[types.ContentBlock],
 ) -> list[types.ContentBlock]:
-    """Attempt to unpack non-standard blocks."""
+    """Convert Anthropic format blocks to v1 format.
+
+    During the `.content_blocks` parsing process, we wrap blocks not recognized as a v1
+    block as a ``'non_standard'`` block with the original block stored in the ``value``
+    field. This function attempts to unpack those blocks and convert any blocks that
+    might be Anthropic format to v1 ContentBlocks.
+
+    If conversion fails, the block is left as a ``'non_standard'`` block.
+
+    Args:
+        content: List of content blocks to process.
+
+    Returns:
+        Updated list with Anthropic blocks converted to v1 format.
+    """
 
     def _iter_blocks() -> Iterable[types.ContentBlock]:
         blocks: list[dict[str, Any]] = [
@@ -270,159 +284,160 @@ def _convert_to_v1_from_anthropic(message: AIMessage) -> list[types.ContentBlock
                         tool_call_block["index"] = block["index"]
                     yield tool_call_block
 
-            elif (
-                block_type == "input_json_delta"
-                and isinstance(message, AIMessageChunk)
-                and len(message.tool_call_chunks) == 1
+            elif block_type == "input_json_delta" and isinstance(
+                message, AIMessageChunk
             ):
-                tool_call_chunk = (
-                    message.tool_call_chunks[0].copy()  # type: ignore[assignment]
-                )
-                if "type" not in tool_call_chunk:
-                    tool_call_chunk["type"] = "tool_call_chunk"
-                yield tool_call_chunk
+                if len(message.tool_call_chunks) == 1:
+                    tool_call_chunk = (
+                        message.tool_call_chunks[0].copy()  # type: ignore[assignment]
+                    )
+                    if "type" not in tool_call_chunk:
+                        tool_call_chunk["type"] = "tool_call_chunk"
+                    yield tool_call_chunk
 
-            elif block_type == "server_tool_use":
-                if block.get("name") == "web_search":
-                    web_search_call: types.WebSearchCall = {"type": "web_search_call"}
+                else:
+                    server_tool_call_chunk: types.ServerToolCallChunk = {
+                        "type": "server_tool_call_chunk",
+                        "args": block.get("partial_json", ""),
+                    }
+                    if "index" in block:
+                        server_tool_call_chunk["index"] = block["index"]
+                    yield server_tool_call_chunk
 
-                    if query := block.get("input", {}).get("query"):
-                        web_search_call["query"] = query
+            elif block_type == "server_tool_use":
+                if block.get("name") == "code_execution":
+                    server_tool_use_name = "code_interpreter"
+                else:
+                    server_tool_use_name = block.get("name", "")
+                if (
+                    isinstance(message, AIMessageChunk)
+                    and block.get("input") == {}
+                    and "partial_json" not in block
+                    and message.chunk_position != "last"
+                ):
+                    # First chunk in a stream
+                    server_tool_call_chunk = {
+                        "type": "server_tool_call_chunk",
+                        "name": server_tool_use_name,
+                        "args": "",
+                        "id": block.get("id", ""),
+                    }
+                    if "index" in block:
+                        server_tool_call_chunk["index"] = block["index"]
+                    known_fields = {"type", "name", "input", "id", "index"}
+                    _populate_extras(server_tool_call_chunk, block, known_fields)
+                    yield server_tool_call_chunk
+                else:
+                    server_tool_call: types.ServerToolCall = {
+                        "type": "server_tool_call",
+                        "name": server_tool_use_name,
+                        "args": block.get("input", {}),
+                        "id": block.get("id", ""),
+                    }
 
-                    elif block.get("input") == {} and "partial_json" in block:
+                    if block.get("input") == {} and "partial_json" in block:
                         try:
                             input_ = json.loads(block["partial_json"])
-                            if isinstance(input_, dict) and "query" in input_:
-                                web_search_call["query"] = input_["query"]
+                            if isinstance(input_, dict):
+                                server_tool_call["args"] = input_
                         except json.JSONDecodeError:
                             pass
 
-                    if "id" in block:
-                        web_search_call["id"] = block["id"]
                     if "index" in block:
-                        web_search_call["index"] = block["index"]
-                    known_fields = {"type", "name", "input", "id", "index"}
-                    for key, value in block.items():
-                        if key not in known_fields:
-                            if "extras" not in web_search_call:
-                                web_search_call["extras"] = {}
-                            web_search_call["extras"][key] = value
-                    yield web_search_call
-
-                elif block.get("name") == "code_execution":
-                    code_interpreter_call: types.CodeInterpreterCall = {
-                        "type": "code_interpreter_call"
+                        server_tool_call["index"] = block["index"]
+                    known_fields = {
+                        "type",
+                        "name",
+                        "input",
+                        "partial_json",
+                        "id",
+                        "index",
                     }
+                    _populate_extras(server_tool_call, block, known_fields)
 
-                    if code := block.get("input", {}).get("code"):
-                        code_interpreter_call["code"] = code
+                    yield server_tool_call
+
+            elif block_type == "mcp_tool_use":
+                if (
+                    isinstance(message, AIMessageChunk)
+                    and block.get("input") == {}
+                    and "partial_json" not in block
+                    and message.chunk_position != "last"
+                ):
+                    # First chunk in a stream
+                    server_tool_call_chunk = {
+                        "type": "server_tool_call_chunk",
+                        "name": "remote_mcp",
+                        "args": "",
+                        "id": block.get("id", ""),
+                    }
+                    if "name" in block:
+                        server_tool_call_chunk["extras"] = {"tool_name": block["name"]}
+                    known_fields = {"type", "name", "input", "id", "index"}
+                    _populate_extras(server_tool_call_chunk, block, known_fields)
+                    if "index" in block:
+                        server_tool_call_chunk["index"] = block["index"]
+                    yield server_tool_call_chunk
+                else:
+                    server_tool_call = {
+                        "type": "server_tool_call",
+                        "name": "remote_mcp",
+                        "args": block.get("input", {}),
+                        "id": block.get("id", ""),
+                    }
 
-                    elif block.get("input") == {} and "partial_json" in block:
+                    if block.get("input") == {} and "partial_json" in block:
                         try:
                             input_ = json.loads(block["partial_json"])
-                            if isinstance(input_, dict) and "code" in input_:
-                                code_interpreter_call["code"] = input_["code"]
+                            if isinstance(input_, dict):
+                                server_tool_call["args"] = input_
                         except json.JSONDecodeError:
                             pass
 
-                    if "id" in block:
-                        code_interpreter_call["id"] = block["id"]
+                    if "name" in block:
+                        server_tool_call["extras"] = {"tool_name": block["name"]}
+                    known_fields = {
+                        "type",
+                        "name",
+                        "input",
+                        "partial_json",
+                        "id",
+                        "index",
+                    }
+                    _populate_extras(server_tool_call, block, known_fields)
                     if "index" in block:
-                        code_interpreter_call["index"] = block["index"]
-                    known_fields = {"type", "name", "input", "id", "index"}
-                    for key, value in block.items():
-                        if key not in known_fields:
-                            if "extras" not in code_interpreter_call:
-                                code_interpreter_call["extras"] = {}
-                            code_interpreter_call["extras"][key] = value
-                    yield code_interpreter_call
+                        server_tool_call["index"] = block["index"]
 
-                else:
-                    new_block: types.NonStandardContentBlock = {
-                        "type": "non_standard",
-                        "value": block,
-                    }
-                    if "index" in new_block["value"]:
-                        new_block["index"] = new_block["value"].pop("index")
-                    yield new_block
-
-            elif block_type == "web_search_tool_result":
-                web_search_result: types.WebSearchResult = {"type": "web_search_result"}
-                if "tool_use_id" in block:
-                    web_search_result["id"] = block["tool_use_id"]
-                if "index" in block:
-                    web_search_result["index"] = block["index"]
-
-                if web_search_result_content := block.get("content", []):
-                    if "extras" not in web_search_result:
-                        web_search_result["extras"] = {}
-                    urls = []
-                    extra_content = []
-                    for result_content in web_search_result_content:
-                        if isinstance(result_content, dict):
-                            if "url" in result_content:
-                                urls.append(result_content["url"])
-                            extra_content.append(result_content)
-                    web_search_result["extras"]["content"] = extra_content
-                    if urls:
-                        web_search_result["urls"] = urls
-                yield web_search_result
-
-            elif block_type == "code_execution_tool_result":
-                code_interpreter_result: types.CodeInterpreterResult = {
-                    "type": "code_interpreter_result",
-                    "output": [],
-                }
-                if "tool_use_id" in block:
-                    code_interpreter_result["id"] = block["tool_use_id"]
-                if "index" in block:
-                    code_interpreter_result["index"] = block["index"]
+                    yield server_tool_call
 
-                code_interpreter_output: types.CodeInterpreterOutput = {
-                    "type": "code_interpreter_output"
+            elif block_type and block_type.endswith("_tool_result"):
+                server_tool_result: types.ServerToolResult = {
+                    "type": "server_tool_result",
+                    "tool_call_id": block.get("tool_use_id", ""),
+                    "status": "success",
+                    "extras": {"block_type": block_type},
                 }
+                if output := block.get("content", []):
+                    server_tool_result["output"] = output
+                    if isinstance(output, dict) and output.get(
+                        "error_code"  # web_search, code_interpreter
+                    ):
+                        server_tool_result["status"] = "error"
+                if block.get("is_error"):  # mcp_tool_result
+                    server_tool_result["status"] = "error"
+                if "index" in block:
+                    server_tool_result["index"] = block["index"]
 
-                code_execution_content = block.get("content", {})
-                if code_execution_content.get("type") == "code_execution_result":
-                    if "return_code" in code_execution_content:
-                        code_interpreter_output["return_code"] = code_execution_content[
-                            "return_code"
-                        ]
-                    if "stdout" in code_execution_content:
-                        code_interpreter_output["stdout"] = code_execution_content[
-                            "stdout"
-                        ]
-                    if stderr := code_execution_content.get("stderr"):
-                        code_interpreter_output["stderr"] = stderr
-                    if (
-                        output := code_interpreter_output.get("content")
-                    ) and isinstance(output, list):
-                        if "extras" not in code_interpreter_result:
-                            code_interpreter_result["extras"] = {}
-                        code_interpreter_result["extras"]["content"] = output
-                        for output_block in output:
-                            if "file_id" in output_block:
-                                if "file_ids" not in code_interpreter_output:
-                                    code_interpreter_output["file_ids"] = []
-                                code_interpreter_output["file_ids"].append(
-                                    output_block["file_id"]
-                                )
-                    code_interpreter_result["output"].append(code_interpreter_output)
-
-                elif (
-                    code_execution_content.get("type")
-                    == "code_execution_tool_result_error"
-                ):
-                    if "extras" not in code_interpreter_result:
-                        code_interpreter_result["extras"] = {}
-                    code_interpreter_result["extras"]["error_code"] = (
-                        code_execution_content.get("error_code")
-                    )
+                known_fields = {"type", "tool_use_id", "content", "is_error", "index"}
+                _populate_extras(server_tool_result, block, known_fields)
 
-                yield code_interpreter_result
+                yield server_tool_result
 
             else:
-                new_block = {"type": "non_standard", "value": block}
+                new_block: types.NonStandardContentBlock = {
+                    "type": "non_standard",
+                    "value": block,
+                }
                 if "index" in new_block["value"]:
                     new_block["index"] = new_block["value"].pop("index")
                 yield new_block

langchain_core/messages/block_translators/bedrock_converse.py

@@ -33,7 +33,21 @@ def _populate_extras(
 def _convert_to_v1_from_converse_input(
     content: list[types.ContentBlock],
 ) -> list[types.ContentBlock]:
-    """Attempt to unpack non-standard blocks."""
+    """Convert Bedrock Converse format blocks to v1 format.
+
+    During the `.content_blocks` parsing process, we wrap blocks not recognized as a v1
+    block as a ``'non_standard'`` block with the original block stored in the ``value``
+    field. This function attempts to unpack those blocks and convert any blocks that
+    might be Converse format to v1 ContentBlocks.
+
+    If conversion fails, the block is left as a ``'non_standard'`` block.
+
+    Args:
+        content: List of content blocks to process.
+
+    Returns:
+        Updated list with Converse blocks converted to v1 format.
+    """
 
     def _iter_blocks() -> Iterable[types.ContentBlock]:
         blocks: list[dict[str, Any]] = [