langchain-core 1.0.0a1__py3-none-any.whl → 1.0.0a3__py3-none-any.whl

langchain_core/messages/content.py

@@ -83,7 +83,7 @@ The module defines several types of content blocks, including:
 
 - ``TextContentBlock``: Standard text output.
 - ``Citation``: For annotations that link text output to a source document.
-- ``ToolCallContentBlock``: For function calling.
+- ``ToolCall``: For function calling.
 - ``ReasoningContentBlock``: To capture a model's thought process.
 - Multimodal data:
     - ``ImageContentBlock``
@@ -99,8 +99,8 @@ The module defines several types of content blocks, including:
     # Direct construction:
     from langchain_core.messages.content import TextContentBlock, ImageContentBlock
 
-    multimodal_message: AIMessage(content_blocks=
-        [
+    multimodal_message: AIMessage(
+        content_blocks=[
             TextContentBlock(type="text", text="What is shown in this image?"),
             ImageContentBlock(
                 type="image",
@@ -113,8 +113,8 @@ The module defines several types of content blocks, including:
     # Using factories:
     from langchain_core.messages.content import create_text_block, create_image_block
 
-    multimodal_message: AIMessage(content=
-        [
+    multimodal_message: AIMessage(
+        content=[
             create_text_block("What is shown in this image?"),
             create_image_block(
                 url="https://www.langchain.com/images/brand/langchain_logo_text_w_white.png",
@@ -129,10 +129,9 @@ Factory functions offer benefits such as:
 
 """
 
-import warnings
 from typing import Any, Literal, Optional, Union, get_args, get_type_hints
 
-from typing_extensions import NotRequired, TypedDict, TypeGuard
+from typing_extensions import NotRequired, TypedDict
 
 from langchain_core.utils.utils import ensure_id
 
@@ -262,11 +261,7 @@ class ToolCall(TypedDict):
 
         .. code-block:: python
 
-            {
-                "name": "foo",
-                "args": {"a": 1},
-                "id": "123"
-            }
+            {"name": "foo", "args": {"a": 1}, "id": "123"}
 
         This represents a request to call the tool named "foo" with arguments {"a": 1}
         and an identifier of "123".
@@ -317,12 +312,12 @@ class ToolCallChunk(TypedDict):
     .. code-block:: python
 
         left_chunks = [ToolCallChunk(name="foo", args='{"a":', index=0)]
-        right_chunks = [ToolCallChunk(name=None, args='1}', index=0)]
+        right_chunks = [ToolCallChunk(name=None, args="1}", index=0)]
 
         (
             AIMessageChunk(content="", tool_call_chunks=left_chunks)
             + AIMessageChunk(content="", tool_call_chunks=right_chunks)
-        ).tool_call_chunks == [ToolCallChunk(name='foo', args='{"a":1}', index=0)]
+        ).tool_call_chunks == [ToolCallChunk(name="foo", args='{"a":1}', index=0)]
 
     """
 
@@ -834,7 +829,7 @@ class NonStandardContentBlock(TypedDict):
     The purpose of this block should be to simply hold a provider-specific payload.
     If a provider's non-standard output includes reasoning and tool calls, it should be
     the adapter's job to parse that payload and emit the corresponding standard
-    ``ReasoningContentBlock`` and ``ToolCallContentBlocks``.
+    ``ReasoningContentBlock`` and ``ToolCalls``.
 
     Has no ``extras`` field, as provider-specific data should be included in the
     ``value`` field.
@@ -920,7 +915,15 @@ KNOWN_BLOCK_TYPES = {
 
 
 def _get_data_content_block_types() -> tuple[str, ...]:
-    """Get type literals from DataContentBlock union members dynamically."""
+    """Get type literals from DataContentBlock union members dynamically.
+
+    Example: ("image", "video", "audio", "text-plain", "file")
+
+    Note that old style multimodal blocks type literals with new style blocks.
+    Speficially, "image", "audio", and "file".
+
+    See the docstring of `_normalize_messages` in `language_models._utils` for details.
+    """
     data_block_types = []
 
     for block_type in get_args(DataContentBlock):
@@ -936,7 +939,9 @@ def _get_data_content_block_types() -> tuple[str, ...]:
 
 
 def is_data_content_block(block: dict) -> bool:
-    """Check if the provided content block is a standard v1 data content block.
+    """Check if the provided content block is a data content block.
+
+    Returns for both v0 (old-style) and v1 (new-style) multimodal data blocks.
 
     Args:
         block: The content block to check.
@@ -949,6 +954,8 @@ def is_data_content_block(block: dict) -> bool:
         return False
 
     if any(key in block for key in ("url", "base64", "file_id", "text")):
+        # Type is valid and at least one data field is present
+        # (Accepts old-style image and audio URLContentBlock)
         return True
 
     # Verify data presence based on source type
@@ -963,116 +970,11 @@ def is_data_content_block(block: dict) -> bool:
         ):
             return True
 
+    # Type may be valid, but no data fields are present
+    # (required case since each is optional and we have no validation)
     return False
 
 
-def is_tool_call_block(block: ContentBlock) -> TypeGuard[ToolCall]:
-    """Type guard to check if a content block is a ``ToolCall``."""
-    return block.get("type") == "tool_call"
-
-
-def is_tool_call_chunk(block: ContentBlock) -> TypeGuard[ToolCallChunk]:
-    """Type guard to check if a content block is a ``ToolCallChunk``."""
-    return block.get("type") == "tool_call_chunk"
-
-
-def is_text_block(block: ContentBlock) -> TypeGuard[TextContentBlock]:
-    """Type guard to check if a content block is a ``TextContentBlock``."""
-    return block.get("type") == "text"
-
-
-def is_reasoning_block(block: ContentBlock) -> TypeGuard[ReasoningContentBlock]:
-    """Type guard to check if a content block is a ``ReasoningContentBlock``."""
-    return block.get("type") == "reasoning"
-
-
-def is_invalid_tool_call_block(
-    block: ContentBlock,
-) -> TypeGuard[InvalidToolCall]:
-    """Type guard to check if a content block is an ``InvalidToolCall``."""
-    return block.get("type") == "invalid_tool_call"
-
-
-def convert_to_openai_image_block(block: dict[str, Any]) -> dict:
-    """Convert ``ImageContentBlock`` to format expected by OpenAI Chat Completions."""
-    if "url" in block:
-        return {
-            "type": "image_url",
-            "image_url": {
-                "url": block["url"],
-            },
-        }
-    if "base64" in block or block.get("source_type") == "base64":
-        if "mime_type" not in block:
-            error_message = "mime_type key is required for base64 data."
-            raise ValueError(error_message)
-        mime_type = block["mime_type"]
-        base64_data = block["data"] if "data" in block else block["base64"]
-        return {
-            "type": "image_url",
-            "image_url": {
-                "url": f"data:{mime_type};base64,{base64_data}",
-            },
-        }
-    error_message = "Unsupported source type. Only 'url' and 'base64' are supported."
-    raise ValueError(error_message)
-
-
-def convert_to_openai_data_block(block: dict) -> dict:
-    """Format standard data content block to format expected by OpenAI."""
-    if block["type"] == "image":
-        formatted_block = convert_to_openai_image_block(block)
-
-    elif block["type"] == "file":
-        if "base64" in block or block.get("source_type") == "base64":
-            # Handle v0 format: {"source_type": "base64", "data": "...", ...}
-            # Handle v1 format: {"base64": "...", ...}
-            base64_data = block["data"] if "source_type" in block else block["base64"]
-            file = {"file_data": f"data:{block['mime_type']};base64,{base64_data}"}
-            if filename := block.get("filename"):
-                file["filename"] = filename
-            elif (extras := block.get("extras")) and ("filename" in extras):
-                file["filename"] = extras["filename"]
-            elif (extras := block.get("metadata")) and ("filename" in extras):
-                # Backward compat
-                file["filename"] = extras["filename"]
-            else:
-                warnings.warn(
-                    "OpenAI may require a filename for file inputs. Specify a filename "
-                    "in the content block: {'type': 'file', 'mime_type': "
-                    "'application/pdf', 'base64': '...', 'filename': 'my-pdf'}",
-                    stacklevel=1,
-                )
-            formatted_block = {"type": "file", "file": file}
-        elif "file_id" in block or block.get("source_type") == "id":
-            # Handle v0 format: {"source_type": "id", "id": "...", ...}
-            # Handle v1 format: {"file_id": "...", ...}
-            file_id = block["id"] if "source_type" in block else block["file_id"]
-            formatted_block = {"type": "file", "file": {"file_id": file_id}}
-        else:
-            error_msg = "Keys base64 or file_id required for file blocks."
-            raise ValueError(error_msg)
-
-    elif block["type"] == "audio":
-        if "base64" in block or block.get("source_type") == "base64":
-            # Handle v0 format: {"source_type": "base64", "data": "...", ...}
-            # Handle v1 format: {"base64": "...", ...}
-            base64_data = block["data"] if "source_type" in block else block["base64"]
-            audio_format = block["mime_type"].split("/")[-1]
-            formatted_block = {
-                "type": "input_audio",
-                "input_audio": {"data": base64_data, "format": audio_format},
-            }
-        else:
-            error_msg = "Key base64 is required for audio blocks."
-            raise ValueError(error_msg)
-    else:
-        error_msg = f"Block of type {block['type']} is not supported."
-        raise ValueError(error_msg)
-
-    return formatted_block
-
-
 def create_text_block(
     text: str,
     *,

langchain_core/messages/human.py

@@ -18,12 +18,8 @@ class HumanMessage(BaseMessage):
             from langchain_core.messages import HumanMessage, SystemMessage
 
             messages = [
-                SystemMessage(
-                    content="You are a helpful assistant! Your name is Bob."
-                ),
-                HumanMessage(
-                    content="What is your name?"
-                )
+                SystemMessage(content="You are a helpful assistant! Your name is Bob."),
+                HumanMessage(content="What is your name?"),
             ]
 
             # Instantiate a chat model and invoke it with the messages
@@ -32,13 +28,6 @@ class HumanMessage(BaseMessage):
 
     """
 
-    example: bool = False
-    """Use to denote that a message is part of an example conversation.
-
-    At the moment, this is ignored by most models. Usage is discouraged.
-    Defaults to False.
-    """
-
     type: Literal["human"] = "human"
     """The type of the message (used for serialization). Defaults to "human"."""
 

langchain_core/messages/system.py

@@ -19,12 +19,8 @@ class SystemMessage(BaseMessage):
             from langchain_core.messages import HumanMessage, SystemMessage
 
             messages = [
-                SystemMessage(
-                    content="You are a helpful assistant! Your name is Bob."
-                ),
-                HumanMessage(
-                    content="What is your name?"
-                )
+                SystemMessage(content="You are a helpful assistant! Your name is Bob."),
+                HumanMessage(content="What is your name?"),
             ]
 
             # Define a chat model and invoke it with the messages

langchain_core/messages/tool.py

@@ -9,7 +9,7 @@ from typing_extensions import NotRequired, TypedDict, override
 
 from langchain_core.messages import content as types
 from langchain_core.messages.base import BaseMessage, BaseMessageChunk, merge_content
-from langchain_core.messages.content import InvalidToolCall as InvalidToolCall
+from langchain_core.messages.content import InvalidToolCall
 from langchain_core.utils._merge import merge_dicts, merge_obj
 
 
@@ -34,7 +34,7 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
 
             from langchain_core.messages import ToolMessage
 
-            ToolMessage(content='42', tool_call_id='call_Jja7J89XsjrOLA5r!MEOW!SL')
+            ToolMessage(content="42", tool_call_id="call_Jja7J89XsjrOLA5r!MEOW!SL")
 
 
     Example: A ToolMessage where only part of the tool output is sent to the model
@@ -47,7 +47,8 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
             from langchain_core.messages import ToolMessage
 
             tool_output = {
-                "stdout": "From the graph we can see that the correlation between x and y is ...",
+                "stdout": "From the graph we can see that the correlation between "
+                "x and y is ...",
                 "stderr": None,
                 "artifacts": {"type": "image", "base64_data": "/9j/4gIcSU..."},
             }
@@ -55,14 +56,14 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
             ToolMessage(
                 content=tool_output["stdout"],
                 artifact=tool_output,
-                tool_call_id='call_Jja7J89XsjrOLA5r!MEOW!SL',
+                tool_call_id="call_Jja7J89XsjrOLA5r!MEOW!SL",
             )
 
     The tool_call_id field is used to associate the tool call request with the
     tool call response. This is useful in situations where a chat model is able
     to request multiple tool calls in parallel.
 
-    """  # noqa: E501
+    """
 
     tool_call_id: str
     """Tool call that this message is responding to."""
@@ -205,11 +206,7 @@ class ToolCall(TypedDict):
 
         .. code-block:: python
 
-            {
-                "name": "foo",
-                "args": {"a": 1},
-                "id": "123"
-            }
+            {"name": "foo", "args": {"a": 1}, "id": "123"}
 
         This represents a request to call the tool named "foo" with arguments {"a": 1}
         and an identifier of "123".
@@ -241,6 +238,9 @@ def tool_call(
         name: The name of the tool to be called.
         args: The arguments to the tool call.
         id: An identifier associated with the tool call.
+
+    Returns:
+        The created tool call.
     """
     return ToolCall(name=name, args=args, id=id, type="tool_call")
 
@@ -257,12 +257,12 @@ class ToolCallChunk(TypedDict):
     .. code-block:: python
 
         left_chunks = [ToolCallChunk(name="foo", args='{"a":', index=0)]
-        right_chunks = [ToolCallChunk(name=None, args='1}', index=0)]
+        right_chunks = [ToolCallChunk(name=None, args="1}", index=0)]
 
         (
             AIMessageChunk(content="", tool_call_chunks=left_chunks)
             + AIMessageChunk(content="", tool_call_chunks=right_chunks)
-        ).tool_call_chunks == [ToolCallChunk(name='foo', args='{"a":1}', index=0)]
+        ).tool_call_chunks == [ToolCallChunk(name="foo", args='{"a":1}', index=0)]
 
     """
 
@@ -291,6 +291,9 @@ def tool_call_chunk(
         args: The arguments to the tool call.
         id: An identifier associated with the tool call.
         index: The index of the tool call in a sequence.
+
+    Returns:
+        The created tool call chunk.
     """
     return ToolCallChunk(
         name=name, args=args, id=id, index=index, type="tool_call_chunk"
@@ -311,6 +314,9 @@ def invalid_tool_call(
         args: The arguments to the tool call.
         id: An identifier associated with the tool call.
         error: An error message associated with the tool call.
+
+    Returns:
+        The created invalid tool call.
     """
     return InvalidToolCall(
         name=name, args=args, id=id, error=error, type="invalid_tool_call"
@@ -320,7 +326,14 @@ def invalid_tool_call(
 def default_tool_parser(
     raw_tool_calls: list[dict],
 ) -> tuple[list[ToolCall], list[InvalidToolCall]]:
-    """Best-effort parsing of tools."""
+    """Best-effort parsing of tools.
+
+    Args:
+        raw_tool_calls: List of raw tool call dicts to parse.
+
+    Returns:
+        A list of tool calls and invalid tool calls.
+    """
     tool_calls = []
     invalid_tool_calls = []
     for raw_tool_call in raw_tool_calls:
@@ -348,7 +361,14 @@ def default_tool_parser(
 
 
 def default_tool_chunk_parser(raw_tool_calls: list[dict]) -> list[ToolCallChunk]:
-    """Best-effort parsing of tool chunks."""
+    """Best-effort parsing of tool chunks.
+
+    Args:
+        raw_tool_calls: List of raw tool call dicts to parse.
+
+    Returns:
+        List of parsed ToolCallChunk objects.
+    """
     tool_call_chunks = []
     for tool_call in raw_tool_calls:
         if "function" not in tool_call: