langchain-core 0.3.75__py3-none-any.whl → 0.3.77__py3-none-any.whl

langchain_core/messages/base.py

@@ -20,7 +20,7 @@ if TYPE_CHECKING:
 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]]]
@@ -31,17 +31,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
@@ -51,20 +52,26 @@ 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",
     )
 
     def __init__(
-        self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
+        self,
+        content: Union[str, list[Union[str, dict]]],
+        **kwargs: Any,
     ) -> None:
-        """Pass in content as positional arg.
+        """Initialize ``BaseMessage``.
 
         Args:
             content: The string contents of the message.
@@ -73,7 +80,7 @@ class BaseMessage(Serializable):
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """BaseMessage is serializable.
+        """``BaseMessage`` is serializable.
 
         Returns:
             True
@@ -84,15 +91,17 @@ class BaseMessage(Serializable):
     def get_lc_namespace(cls) -> list[str]:
         """Get the namespace of the langchain object.
 
-        Default is ["langchain", "schema", "messages"].
+        Returns:
+            ``["langchain", "schema", "messages"]``
         """
         return ["langchain", "schema", "messages"]
 
     def text(self) -> str:
-        """Get the text content of the message.
+        """Get the text ``content`` of the message.
 
         Returns:
             The text content of the message.
+
         """
         if isinstance(self.content, str):
             return self.content
@@ -109,8 +118,16 @@ class BaseMessage(Serializable):
         )
 
     def __add__(self, other: Any) -> ChatPromptTemplate:
-        """Concatenate this message with another message."""
-        from langchain_core.prompts.chat import ChatPromptTemplate
+        """Concatenate this message with another message.
+
+        Args:
+            other: Another message to concatenate with this one.
+
+        Returns:
+            A ChatPromptTemplate containing both messages.
+        """
+        # Import locally to prevent circular imports.
+        from langchain_core.prompts.chat import ChatPromptTemplate  # noqa: PLC0415
 
         prompt = ChatPromptTemplate(messages=[self])
         return prompt + other
@@ -127,6 +144,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.
@@ -146,11 +164,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 = first_content
     for content in contents:
@@ -171,9 +190,7 @@ def merge_content(
         elif merged and isinstance(merged[-1], str):
             merged[-1] += content
         # If second content is an empty string, treat as a no-op
-        elif content == "":
-            pass
-        else:
+        elif content:
             # Otherwise, add the second content as a new element of the list
             merged.append(content)
     return merged
@@ -200,9 +217,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,
@@ -250,8 +268,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()}
 
@@ -260,10 +279,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]
 
@@ -277,6 +297,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/chat.py

@@ -30,7 +30,10 @@ class ChatMessageChunk(ChatMessage, BaseMessageChunk):
     # non-chunk variant.
     type: Literal["ChatMessageChunk"] = "ChatMessageChunk"  # type: ignore[assignment]
     """The type of the message (used during serialization).
-    Defaults to "ChatMessageChunk"."""
+
+    Defaults to ``'ChatMessageChunk'``.
+
+    """
 
     @override
     def __add__(self, other: Any) -> BaseMessageChunk:  # type: ignore[override]

langchain_core/messages/content_blocks.py

@@ -88,7 +88,18 @@ def is_data_content_block(
 
 
 def convert_to_openai_image_block(content_block: dict[str, Any]) -> dict:
-    """Convert image content block to format expected by OpenAI Chat Completions API."""
+    """Convert image content block to format expected by OpenAI Chat Completions API.
+
+    Args:
+        content_block: The content block to convert.
+
+    Raises:
+        ValueError: If the source type is not supported or if ``mime_type`` is missing
+            for base64 data.
+
+    Returns:
+        A dictionary formatted for OpenAI's API.
+    """
     if content_block["source_type"] == "url":
         return {
             "type": "image_url",
@@ -112,7 +123,17 @@ def convert_to_openai_image_block(content_block: dict[str, Any]) -> dict:
 
 
 def convert_to_openai_data_block(block: dict) -> dict:
-    """Format standard data content block to format expected by OpenAI."""
+    """Format standard data content block to format expected by OpenAI.
+
+    Args:
+        block: A data content block.
+
+    Raises:
+        ValueError: If the block type or source type is not supported.
+
+    Returns:
+        A dictionary formatted for OpenAI's API.
+    """
     if block["type"] == "image":
         formatted_block = convert_to_openai_image_block(block)
 

langchain_core/messages/function.py

@@ -15,19 +15,20 @@ from langchain_core.utils._merge import merge_dicts
 class FunctionMessage(BaseMessage):
     """Message for passing the result of executing a tool back to a model.
 
-    FunctionMessage are an older version of the ToolMessage schema, and
-    do not contain the tool_call_id field.
+    ``FunctionMessage`` are an older version of the ``ToolMessage`` schema, and
+    do not contain the ``tool_call_id`` field.
 
-    The tool_call_id field is used to associate the tool call request with the
+    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.
+
     """
 
     name: str
     """The name of the function that was executed."""
 
     type: Literal["function"] = "function"
-    """The type of the message (used for serialization). Defaults to "function"."""
+    """The type of the message (used for serialization). Defaults to ``'function'``."""
 
 
 class FunctionMessageChunk(FunctionMessage, BaseMessageChunk):
@@ -38,7 +39,10 @@ class FunctionMessageChunk(FunctionMessage, BaseMessageChunk):
     # non-chunk variant.
     type: Literal["FunctionMessageChunk"] = "FunctionMessageChunk"  # type: ignore[assignment]
     """The type of the message (used for serialization).
-    Defaults to "FunctionMessageChunk"."""
+
+    Defaults to ``'FunctionMessageChunk'``.
+
+    """
 
     @override
     def __add__(self, other: Any) -> BaseMessageChunk:  # type: ignore[override]

langchain_core/messages/human.py

@@ -8,7 +8,7 @@ from langchain_core.messages.base import BaseMessage, BaseMessageChunk
 class HumanMessage(BaseMessage):
     """Message from a human.
 
-    HumanMessages are messages that are passed in from a human to the model.
+    ``HumanMessage``s are messages that are passed in from a human to the model.
 
     Example:
 
@@ -17,12 +17,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
@@ -36,15 +32,22 @@ class HumanMessage(BaseMessage):
 
     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"."""
+    """The type of the message (used for serialization).
+
+    Defaults to ``'human'``.
+
+    """
 
     def __init__(
-        self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
+        self,
+        content: Union[str, list[Union[str, dict]]],
+        **kwargs: Any,
     ) -> None:
-        """Pass in content as positional arg.
+        """Initialize ``HumanMessage``.
 
         Args:
             content: The string contents of the message.

langchain_core/messages/modifier.py

@@ -24,6 +24,7 @@ class RemoveMessage(BaseMessage):
 
         Raises:
             ValueError: If the 'content' field is passed in kwargs.
+
         """
         if kwargs.pop("content", None):
             msg = "RemoveMessage does not support 'content' field."

langchain_core/messages/system.py

@@ -18,12 +18,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
@@ -32,7 +28,11 @@ class SystemMessage(BaseMessage):
     """
 
     type: Literal["system"] = "system"
-    """The type of the message (used for serialization). Defaults to "system"."""
+    """The type of the message (used for serialization).
+
+    Defaults to ``'system'``.
+
+    """
 
     def __init__(
         self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
@@ -54,4 +54,7 @@ class SystemMessageChunk(SystemMessage, BaseMessageChunk):
     # non-chunk variant.
     type: Literal["SystemMessageChunk"] = "SystemMessageChunk"  # type: ignore[assignment]
     """The type of the message (used for serialization).
-    Defaults to "SystemMessageChunk"."""
+
+    Defaults to ``'SystemMessageChunk'``.
+
+    """

langchain_core/messages/tool.py

@@ -14,28 +14,29 @@ from langchain_core.utils._merge import merge_dicts, merge_obj
 class ToolOutputMixin:
     """Mixin for objects that tools can return directly.
 
-    If a custom BaseTool is invoked with a ToolCall and the output of custom code is
-    not an instance of ToolOutputMixin, the output will automatically be coerced to a
-    string and wrapped in a ToolMessage.
+    If a custom BaseTool is invoked with a ``ToolCall`` and the output of custom code is
+    not an instance of ``ToolOutputMixin``, the output will automatically be coerced to
+    a string and wrapped in a ``ToolMessage``.
+
     """
 
 
 class ToolMessage(BaseMessage, ToolOutputMixin):
     """Message for passing the result of executing a tool back to a model.
 
-    ToolMessages contain the result of a tool invocation. Typically, the result
-    is encoded inside the `content` field.
+    ``ToolMessage``s contain the result of a tool invocation. Typically, the result
+    is encoded inside the ``content`` field.
 
-    Example: A ToolMessage representing a result of 42 from a tool call with id
+    Example: A ``ToolMessage`` representing a result of ``42`` from a tool call with id
 
         .. code-block:: python
 
             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
+    Example: A ``ToolMessage`` where only part of the tool output is sent to the model
         and the full output is passed in to artifact.
 
         .. versionadded:: 0.2.17
@@ -45,7 +46,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..."},
             }
@@ -53,20 +55,24 @@ 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
+    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."""
 
     type: Literal["tool"] = "tool"
-    """The type of the message (used for serialization). Defaults to "tool"."""
+    """The type of the message (used for serialization).
+
+    Defaults to ``'tool'``.
+
+    """
 
     artifact: Any = None
     """Artifact of the Tool execution which is not meant to be sent to the model.
@@ -76,12 +82,14 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
     output is needed in other parts of the code.
 
     .. versionadded:: 0.2.17
+
     """
 
     status: Literal["success", "error"] = "success"
     """Status of the tool invocation.
 
     .. versionadded:: 0.2.24
+
     """
 
     additional_kwargs: dict = Field(default_factory=dict, repr=False)
@@ -96,6 +104,7 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
 
         Args:
             values: The model arguments.
+
         """
         content = values["content"]
         if isinstance(content, tuple):
@@ -134,9 +143,11 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
         return values
 
     def __init__(
-        self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
+        self,
+        content: Union[str, list[Union[str, dict]]],
+        **kwargs: Any,
     ) -> None:
-        """Create a ToolMessage.
+        """Initialize ``ToolMessage``.
 
         Args:
             content: The string contents of the message.
@@ -184,14 +195,10 @@ 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".
+        This represents a request to call the tool named ``'foo'`` with arguments
+        ``{"a": 1}`` and an identifier of ``'123'``.
 
     """
 
@@ -204,6 +211,7 @@ class ToolCall(TypedDict):
 
     An identifier is needed to associate a tool call request with a tool
     call result in events when multiple concurrent tool calls are made.
+
     """
     type: NotRequired[Literal["tool_call"]]
 
@@ -220,6 +228,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")
 
@@ -227,21 +238,21 @@ def tool_call(
 class ToolCallChunk(TypedDict):
     """A chunk of a tool call (e.g., as part of a stream).
 
-    When merging ToolCallChunks (e.g., via AIMessageChunk.__add__),
+    When merging ``ToolCallChunk``s (e.g., via ``AIMessageChunk.__add__``),
     all string attributes are concatenated. Chunks are only merged if their
-    values of `index` are equal and not None.
+    values of ``index`` are equal and not None.
 
     Example:
 
     .. 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)]
 
     """
 
@@ -270,6 +281,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"
@@ -279,7 +293,7 @@ def tool_call_chunk(
 class InvalidToolCall(TypedDict):
     """Allowance for errors made by LLM.
 
-    Here we add an `error` key to surface errors made during generation
+    Here we add an ``error`` key to surface errors made during generation
     (e.g., invalid JSON arguments.)
     """
 
@@ -308,6 +322,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"
@@ -317,7 +334,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:
@@ -345,7 +369,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: