langchain-core 1.0.0a4__py3-none-any.whl → 1.0.0a5__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,
@@ -195,24 +216,34 @@ 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.
+        # The block is left as non-standard if conversion fails.
         for parsing_step in [
             _convert_v0_multimodal_input_to_v1,
             _convert_to_v1_from_chat_completions_input,
@@ -234,6 +265,7 @@ class BaseMessage(Serializable):
 
         Returns:
             The text content of the message.
+
         """
         if isinstance(self.content, str):
             text_value = self.content
@@ -277,6 +309,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 +329,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 +386,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 +437,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 +448,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 +466,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
 

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]] = [