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

langchain_core/messages/block_translators/__init__.py

@@ -53,26 +53,28 @@ def _register_translators() -> None:
     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 (
+    from langchain_core.messages.block_translators.anthropic import (  # noqa: PLC0415
         _register_anthropic_translator,
     )
-    from langchain_core.messages.block_translators.bedrock import (
+    from langchain_core.messages.block_translators.bedrock import (  # noqa: PLC0415
         _register_bedrock_translator,
     )
-    from langchain_core.messages.block_translators.bedrock_converse import (
+    from langchain_core.messages.block_translators.bedrock_converse import (  # noqa: PLC0415
         _register_bedrock_converse_translator,
     )
-    from langchain_core.messages.block_translators.google_genai import (
+    from langchain_core.messages.block_translators.google_genai import (  # noqa: PLC0415
         _register_google_genai_translator,
     )
-    from langchain_core.messages.block_translators.google_vertexai import (
+    from langchain_core.messages.block_translators.google_vertexai import (  # noqa: PLC0415
         _register_google_vertexai_translator,
     )
-    from langchain_core.messages.block_translators.groq import _register_groq_translator
-    from langchain_core.messages.block_translators.ollama import (
+    from langchain_core.messages.block_translators.groq import (  # noqa: PLC0415
+        _register_groq_translator,
+    )
+    from langchain_core.messages.block_translators.ollama import (  # noqa: PLC0415
         _register_ollama_translator,
     )
-    from langchain_core.messages.block_translators.openai import (
+    from langchain_core.messages.block_translators.openai import (  # noqa: PLC0415
         _register_openai_translator,
     )
 

langchain_core/messages/block_translators/anthropic.py

@@ -443,7 +443,9 @@ def _register_anthropic_translator() -> None:
 
     Run automatically when the module is imported.
     """
-    from langchain_core.messages.block_translators import register_translator
+    from langchain_core.messages.block_translators import (  # noqa: PLC0415
+        register_translator,
+    )
 
     register_translator("anthropic", translate_content, translate_content_chunk)
 

langchain_core/messages/block_translators/bedrock.py

@@ -37,7 +37,9 @@ def _register_bedrock_translator() -> None:
 
     Run automatically when the module is imported.
     """
-    from langchain_core.messages.block_translators import register_translator
+    from langchain_core.messages.block_translators import (  # noqa: PLC0415
+        register_translator,
+    )
 
     register_translator("bedrock", translate_content, translate_content_chunk)
 

langchain_core/messages/block_translators/bedrock_converse.py

@@ -39,7 +39,9 @@ def _register_bedrock_converse_translator() -> None:
 
     Run automatically when the module is imported.
     """
-    from langchain_core.messages.block_translators import register_translator
+    from langchain_core.messages.block_translators import (  # noqa: PLC0415
+        register_translator,
+    )
 
     register_translator("bedrock_converse", translate_content, translate_content_chunk)
 

langchain_core/messages/block_translators/google_genai.py

@@ -37,7 +37,9 @@ def _register_google_genai_translator() -> None:
 
     Run automatically when the module is imported.
     """
-    from langchain_core.messages.block_translators import register_translator
+    from langchain_core.messages.block_translators import (  # noqa: PLC0415
+        register_translator,
+    )
 
     register_translator("google_genai", translate_content, translate_content_chunk)
 

langchain_core/messages/block_translators/google_vertexai.py

@@ -39,7 +39,9 @@ def _register_google_vertexai_translator() -> None:
 
     Run automatically when the module is imported.
     """
-    from langchain_core.messages.block_translators import register_translator
+    from langchain_core.messages.block_translators import (  # noqa: PLC0415
+        register_translator,
+    )
 
     register_translator("google_vertexai", translate_content, translate_content_chunk)
 

langchain_core/messages/block_translators/groq.py

@@ -37,7 +37,9 @@ def _register_groq_translator() -> None:
 
     Run automatically when the module is imported.
     """
-    from langchain_core.messages.block_translators import register_translator
+    from langchain_core.messages.block_translators import (  # noqa: PLC0415
+        register_translator,
+    )
 
     register_translator("groq", translate_content, translate_content_chunk)
 

langchain_core/messages/block_translators/ollama.py

@@ -37,7 +37,9 @@ def _register_ollama_translator() -> None:
 
     Run automatically when the module is imported.
     """
-    from langchain_core.messages.block_translators import register_translator
+    from langchain_core.messages.block_translators import (  # noqa: PLC0415
+        register_translator,
+    )
 
     register_translator("ollama", translate_content, translate_content_chunk)
 

langchain_core/messages/block_translators/openai.py

@@ -5,11 +5,11 @@ from __future__ import annotations
 import json
 import warnings
 from collections.abc import Iterable
-from typing import TYPE_CHECKING, Any, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, Literal, Optional, Union, cast
 
 from langchain_core.language_models._utils import (
-    _is_openai_data_block,
     _parse_data_uri,
+    is_openai_data_block,
 )
 from langchain_core.messages import content as types
 
@@ -42,15 +42,32 @@ def convert_to_openai_image_block(block: dict[str, Any]) -> dict:
     raise ValueError(error_message)
 
 
-def convert_to_openai_data_block(block: dict) -> dict:
-    """Format standard data content block to format expected by OpenAI."""
+def convert_to_openai_data_block(
+    block: dict, api: Literal["chat/completions", "responses"] = "chat/completions"
+) -> dict:
+    """Format standard data content block to format expected by OpenAI.
+
+    "Standard data content block" can include old-style LangChain v0 blocks
+    (URLContentBlock, Base64ContentBlock, IDContentBlock) or new ones.
+    """
     if block["type"] == "image":
-        formatted_block = convert_to_openai_image_block(block)
+        chat_completions_block = convert_to_openai_image_block(block)
+        if api == "responses":
+            formatted_block = {
+                "type": "input_image",
+                "image_url": chat_completions_block["image_url"]["url"],
+            }
+            if chat_completions_block["image_url"].get("detail"):
+                formatted_block["detail"] = chat_completions_block["image_url"][
+                    "detail"
+                ]
+        else:
+            formatted_block = chat_completions_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": "...", ...}
+        if block.get("source_type") == "base64" or "base64" in block:
+            # Handle v0 format (Base64CB): {"source_type": "base64", "data": "...", ...}
+            # Handle v1 format (IDCB): {"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"):
@@ -61,20 +78,31 @@ def convert_to_openai_data_block(block: dict) -> dict:
                 # Backward compat
                 file["filename"] = extras["filename"]
             else:
+                # Can't infer filename
                 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'}",
+                    "OpenAI may require a filename for file uploads. Specify a filename"
+                    " in the content block, e.g.: {'type': 'file', 'mime_type': "
+                    "'...', 'base64': '...', 'filename': 'my-file.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": "...", ...}
+            if api == "responses":
+                formatted_block = {"type": "input_file", **formatted_block["file"]}
+        elif block.get("source_type") == "id" or "file_id" in block:
+            # Handle v0 format (IDContentBlock): {"source_type": "id", "id": "...", ...}
+            # Handle v1 format (IDCB): {"file_id": "...", ...}
             file_id = block["id"] if "source_type" in block else block["file_id"]
             formatted_block = {"type": "file", "file": {"file_id": file_id}}
+            if api == "responses":
+                formatted_block = {"type": "input_file", **formatted_block["file"]}
+        elif "url" in block:  # Intentionally do not check for source_type="url"
+            if api == "chat/completions":
+                error_msg = "OpenAI Chat Completions does not support file URLs."
+                raise ValueError(error_msg)
+            # Only supported by Responses API; return in that format
+            formatted_block = {"type": "input_file", "file_url": block["url"]}
         else:
-            error_msg = "Keys base64 or file_id required for file blocks."
+            error_msg = "Keys base64, url, or file_id required for file blocks."
             raise ValueError(error_msg)
 
     elif block["type"] == "audio":
@@ -136,7 +164,7 @@ def _convert_to_v1_from_chat_completions_input(
     Returns:
         Updated list with OpenAI blocks converted to v1 format.
     """
-    from langchain_core.messages import content as types
+    from langchain_core.messages import content as types  # noqa: PLC0415
 
     converted_blocks = []
     unpacked_blocks: list[dict[str, Any]] = [
@@ -150,7 +178,7 @@ def _convert_to_v1_from_chat_completions_input(
             "image_url",
             "input_audio",
             "file",
-        } and _is_openai_data_block(block):
+        } and is_openai_data_block(block):
             converted_block = _convert_openai_format_to_data_block(block)
             # If conversion succeeded, use it; otherwise keep as non_standard
             if (
@@ -232,7 +260,7 @@ _FUNCTION_CALL_IDS_MAP_KEY = "__openai_function_call_ids__"
 
 def _convert_from_v03_ai_message(message: AIMessage) -> AIMessage:
     """Convert v0 AIMessage into ``output_version="responses/v1"`` format."""
-    from langchain_core.messages import AIMessageChunk
+    from langchain_core.messages import AIMessageChunk  # noqa: PLC0415
 
     # Only update ChatOpenAI v0.3 AIMessages
     is_chatopenai_v03 = (
@@ -650,7 +678,7 @@ def _convert_to_v1_from_responses(message: AIMessage) -> list[types.ContentBlock
                 ] = None
                 call_id = block.get("call_id", "")
 
-                from langchain_core.messages import AIMessageChunk
+                from langchain_core.messages import AIMessageChunk  # noqa: PLC0415
 
                 if (
                     isinstance(message, AIMessageChunk)
@@ -790,7 +818,9 @@ def _register_openai_translator() -> None:
 
     Run automatically when the module is imported.
     """
-    from langchain_core.messages.block_translators import register_translator
+    from langchain_core.messages.block_translators import (  # noqa: PLC0415
+        register_translator,
+    )
 
     register_translator("openai", translate_content, translate_content_chunk)
 

langchain_core/messages/content.py

@@ -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",
@@ -261,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".
@@ -316,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)]
 
     """
 
@@ -919,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):
@@ -935,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.
@@ -948,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
@@ -962,6 +970,8 @@ 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
 
 

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: