langchain-core 0.3.79__py3-none-any.whl → 1.0.0__py3-none-any.whl

langchain_core/messages/function.py

@@ -15,11 +15,11 @@ 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
-    tool call response. This is useful in situations where a chat model is able
+    The `tool_call_id` field is used to associate the tool call request with the
+    tool call response. Useful in situations where a chat model is able
     to request multiple tool calls in parallel.
 
     """
@@ -28,7 +28,7 @@ class FunctionMessage(BaseMessage):
     """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)."""
 
 
 class FunctionMessageChunk(FunctionMessage, BaseMessageChunk):
@@ -38,11 +38,7 @@ class FunctionMessageChunk(FunctionMessage, BaseMessageChunk):
     # to make sure that the chunk variant can be discriminated from the
     # non-chunk variant.
     type: Literal["FunctionMessageChunk"] = "FunctionMessageChunk"  # type: ignore[assignment]
-    """The type of the message (used for serialization).
-
-    Defaults to ``'FunctionMessageChunk'``.
-
-    """
+    """The type of the message (used for serialization)."""
 
     @override
     def __add__(self, other: Any) -> BaseMessageChunk:  # type: ignore[override]

langchain_core/messages/human.py

@@ -1,59 +1,63 @@
 """Human message."""
 
-from typing import Any, Literal, Union
+from typing import Any, Literal, cast, overload
 
+from langchain_core.messages import content as types
 from langchain_core.messages.base import BaseMessage, BaseMessageChunk
 
 
 class HumanMessage(BaseMessage):
-    """Message from a human.
+    """Message from the user.
 
-    ``HumanMessage``s are messages that are passed in from a human to the model.
+    A `HumanMessage` is a message that is passed in from a user to the model.
 
     Example:
-
-        .. code-block:: python
-
-            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?"),
-            ]
-
-            # Instantiate a chat model and invoke it with the messages
-            model = ...
-            print(model.invoke(messages))
-
-    """
-
-    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.
-
+        ```python
+        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?"),
+        ]
+
+        # Instantiate a chat model and invoke it with the messages
+        model = ...
+        print(model.invoke(messages))
+        ```
     """
 
     type: Literal["human"] = "human"
-    """The type of the message (used for serialization).
+    """The type of the message (used for serialization)."""
 
-    Defaults to ``'human'``.
+    @overload
+    def __init__(
+        self,
+        content: str | list[str | dict],
+        **kwargs: Any,
+    ) -> None: ...
 
-    """
+    @overload
+    def __init__(
+        self,
+        content: str | list[str | dict] | None = None,
+        content_blocks: list[types.ContentBlock] | None = None,
+        **kwargs: Any,
+    ) -> None: ...
 
     def __init__(
         self,
-        content: Union[str, list[Union[str, dict]]],
+        content: str | list[str | dict] | None = None,
+        content_blocks: list[types.ContentBlock] | None = None,
         **kwargs: Any,
     ) -> None:
-        """Initialize ``HumanMessage``.
-
-        Args:
-            content: The string contents of the message.
-            kwargs: Additional fields to pass to the message.
-        """
-        super().__init__(content=content, **kwargs)
+        """Specify `content` as positional arg or `content_blocks` for typing."""
+        if content_blocks is not None:
+            super().__init__(
+                content=cast("str | list[str | dict]", content_blocks),
+                **kwargs,
+            )
+        else:
+            super().__init__(content=content, **kwargs)
 
 
 class HumanMessageChunk(HumanMessage, BaseMessageChunk):
@@ -63,5 +67,4 @@ class HumanMessageChunk(HumanMessage, BaseMessageChunk):
     # to make sure that the chunk variant can be discriminated from the
     # non-chunk variant.
     type: Literal["HumanMessageChunk"] = "HumanMessageChunk"  # type: ignore[assignment]
-    """The type of the message (used for serialization).
-    Defaults to "HumanMessageChunk"."""
+    """The type of the message (used for serialization)."""

langchain_core/messages/modifier.py

@@ -9,7 +9,7 @@ class RemoveMessage(BaseMessage):
     """Message responsible for deleting other messages."""
 
     type: Literal["remove"] = "remove"
-    """The type of the message (used for serialization). Defaults to "remove"."""
+    """The type of the message (used for serialization)."""
 
     def __init__(
         self,
@@ -20,7 +20,7 @@ class RemoveMessage(BaseMessage):
 
         Args:
             id: The ID of the message to remove.
-            kwargs: Additional fields to pass to the message.
+            **kwargs: Additional fields to pass to the message.
 
         Raises:
             ValueError: If the 'content' field is passed in kwargs.

langchain_core/messages/system.py

@@ -1,7 +1,8 @@
 """System message."""
 
-from typing import Any, Literal, Union
+from typing import Any, Literal, cast, overload
 
+from langchain_core.messages import content as types
 from langchain_core.messages.base import BaseMessage, BaseMessageChunk
 
 
@@ -12,38 +13,51 @@ class SystemMessage(BaseMessage):
     of input messages.
 
     Example:
+        ```python
+        from langchain_core.messages import HumanMessage, SystemMessage
 
-        .. code-block:: python
-
-            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?"),
-            ]
-
-            # Define a chat model and invoke it with the messages
-            print(model.invoke(messages))
+        messages = [
+            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
+        print(model.invoke(messages))
+        ```
     """
 
     type: Literal["system"] = "system"
-    """The type of the message (used for serialization).
+    """The type of the message (used for serialization)."""
 
-    Defaults to ``'system'``.
+    @overload
+    def __init__(
+        self,
+        content: str | list[str | dict],
+        **kwargs: Any,
+    ) -> None: ...
 
-    """
+    @overload
+    def __init__(
+        self,
+        content: str | list[str | dict] | None = None,
+        content_blocks: list[types.ContentBlock] | None = None,
+        **kwargs: Any,
+    ) -> None: ...
 
     def __init__(
-        self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
+        self,
+        content: str | list[str | dict] | None = None,
+        content_blocks: list[types.ContentBlock] | None = None,
+        **kwargs: Any,
     ) -> None:
-        """Pass in content as positional arg.
-
-        Args:
-               content: The string contents of the message.
-               kwargs: Additional fields to pass to the message.
-        """
-        super().__init__(content=content, **kwargs)
+        """Specify `content` as positional arg or `content_blocks` for typing."""
+        if content_blocks is not None:
+            super().__init__(
+                content=cast("str | list[str | dict]", content_blocks),
+                **kwargs,
+            )
+        else:
+            super().__init__(content=content, **kwargs)
 
 
 class SystemMessageChunk(SystemMessage, BaseMessageChunk):
@@ -53,8 +67,4 @@ class SystemMessageChunk(SystemMessage, BaseMessageChunk):
     # to make sure that the chunk variant can be discriminated from the
     # non-chunk variant.
     type: Literal["SystemMessageChunk"] = "SystemMessageChunk"  # type: ignore[assignment]
-    """The type of the message (used for serialization).
-
-    Defaults to ``'SystemMessageChunk'``.
-
-    """
+    """The type of the message (used for serialization)."""

langchain_core/messages/tool.py

@@ -1,22 +1,24 @@
 """Messages for tools."""
 
 import json
-from typing import Any, Literal, Optional, Union
+from typing import Any, Literal, cast, overload
 from uuid import UUID
 
 from pydantic import Field, model_validator
 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
 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`.
 
     """
 
@@ -24,42 +26,39 @@ class ToolOutputMixin:
 class ToolMessage(BaseMessage, ToolOutputMixin):
     """Message for passing the result of executing a tool back to a model.
 
-    ``ToolMessage``s contain the result of a tool invocation. Typically, the result
-    is encoded inside the ``content`` field.
+    `ToolMessage` objects 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
+    ```python
+    from langchain_core.messages import ToolMessage
 
-            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
+    and the full output is passed in to artifact.
 
+    ```python
+    from langchain_core.messages import ToolMessage
 
-    Example: A ``ToolMessage`` where only part of the tool output is sent to the model
-        and the full output is passed in to artifact.
+    tool_output = {
+        "stdout": "From the graph we can see that the correlation between "
+        "x and y is ...",
+        "stderr": None,
+        "artifacts": {"type": "image", "base64_data": "/9j/4gIcSU..."},
+    }
 
-        .. versionadded:: 0.2.17
-
-        .. code-block:: python
-
-            from langchain_core.messages import ToolMessage
-
-            tool_output = {
-                "stdout": "From the graph we can see that the correlation between "
-                "x and y is ...",
-                "stderr": None,
-                "artifacts": {"type": "image", "base64_data": "/9j/4gIcSU..."},
-            }
-
-            ToolMessage(
-                content=tool_output["stdout"],
-                artifact=tool_output,
-                tool_call_id="call_Jja7J89XsjrOLA5r!MEOW!SL",
-            )
+    ToolMessage(
+        content=tool_output["stdout"],
+        artifact=tool_output,
+        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
+    The `tool_call_id` field is used to associate the tool call request with the
+    tool call response. Useful in situations where a chat model is able
     to request multiple tool calls in parallel.
 
     """
@@ -68,11 +67,7 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
     """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)."""
 
     artifact: Any = None
     """Artifact of the Tool execution which is not meant to be sent to the model.
@@ -81,21 +76,15 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
     a subset of the full tool output is being passed as message content but the full
     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
-
-    """
+    """Status of the tool invocation."""
 
     additional_kwargs: dict = Field(default_factory=dict, repr=False)
-    """Currently inherited from BaseMessage, but not used."""
+    """Currently inherited from `BaseMessage`, but not used."""
     response_metadata: dict = Field(default_factory=dict, repr=False)
-    """Currently inherited from BaseMessage, but not used."""
+    """Currently inherited from `BaseMessage`, but not used."""
 
     @model_validator(mode="before")
     @classmethod
@@ -142,18 +131,43 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
             values["tool_call_id"] = str(tool_call_id)
         return values
 
+    @overload
+    def __init__(
+        self,
+        content: str | list[str | dict],
+        **kwargs: Any,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self,
+        content: str | list[str | dict] | None = None,
+        content_blocks: list[types.ContentBlock] | None = None,
+        **kwargs: Any,
+    ) -> None: ...
+
     def __init__(
         self,
-        content: Union[str, list[Union[str, dict]]],
+        content: str | list[str | dict] | None = None,
+        content_blocks: list[types.ContentBlock] | None = None,
         **kwargs: Any,
     ) -> None:
-        """Initialize ``ToolMessage``.
+        """Initialize a `ToolMessage`.
+
+        Specify `content` as positional arg or `content_blocks` for typing.
 
         Args:
-            content: The string contents of the message.
+            content: The contents of the message.
+            content_blocks: Typed standard content.
             **kwargs: Additional fields.
         """
-        super().__init__(content=content, **kwargs)
+        if content_blocks is not None:
+            super().__init__(
+                content=cast("str | list[str | dict]", content_blocks),
+                **kwargs,
+            )
+        else:
+            super().__init__(content=content, **kwargs)
 
 
 class ToolMessageChunk(ToolMessage, BaseMessageChunk):
@@ -189,16 +203,15 @@ class ToolMessageChunk(ToolMessage, BaseMessageChunk):
 
 
 class ToolCall(TypedDict):
-    """Represents a request to call a tool.
+    """Represents an AI's request to call a tool.
 
     Example:
+        ```python
+        {"name": "foo", "args": {"a": 1}, "id": "123"}
+        ```
 
-        .. code-block:: python
-
-            {"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'`.
 
     """
 
@@ -206,7 +219,7 @@ class ToolCall(TypedDict):
     """The name of the tool to be called."""
     args: dict[str, Any]
     """The arguments to the tool call."""
-    id: Optional[str]
+    id: str | None
     """An identifier associated with the tool call.
 
     An identifier is needed to associate a tool call request with a tool
@@ -220,7 +233,7 @@ def tool_call(
     *,
     name: str,
     args: dict[str, Any],
-    id: Optional[str],
+    id: str | None,
 ) -> ToolCall:
     """Create a tool call.
 
@@ -236,43 +249,41 @@ def tool_call(
 
 
 class ToolCallChunk(TypedDict):
-    """A chunk of a tool call (e.g., as part of a stream).
+    """A chunk of a tool call (yielded when streaming).
 
-    When merging ``ToolCallChunk``s (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)]
-
-        (
-            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)]
-
+    ```python
+    left_chunks = [ToolCallChunk(name="foo", args='{"a":', 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)]
+    ```
     """
 
-    name: Optional[str]
+    name: str | None
     """The name of the tool to be called."""
-    args: Optional[str]
+    args: str | None
     """The arguments to the tool call."""
-    id: Optional[str]
+    id: str | None
     """An identifier associated with the tool call."""
-    index: Optional[int]
+    index: int | None
     """The index of the tool call in a sequence."""
     type: NotRequired[Literal["tool_call_chunk"]]
 
 
 def tool_call_chunk(
     *,
-    name: Optional[str] = None,
-    args: Optional[str] = None,
-    id: Optional[str] = None,
-    index: Optional[int] = None,
+    name: str | None = None,
+    args: str | None = None,
+    id: str | None = None,
+    index: int | None = None,
 ) -> ToolCallChunk:
     """Create a tool call chunk.
 
@@ -290,30 +301,12 @@ 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
-    (e.g., invalid JSON arguments.)
-    """
-
-    name: Optional[str]
-    """The name of the tool to be called."""
-    args: Optional[str]
-    """The arguments to the tool call."""
-    id: Optional[str]
-    """An identifier associated with the tool call."""
-    error: Optional[str]
-    """An error message associated with the tool call."""
-    type: NotRequired[Literal["invalid_tool_call"]]
-
-
 def invalid_tool_call(
     *,
-    name: Optional[str] = None,
-    args: Optional[str] = None,
-    id: Optional[str] = None,
-    error: Optional[str] = None,
+    name: str | None = None,
+    args: str | None = None,
+    id: str | None = None,
+    error: str | None = None,
 ) -> InvalidToolCall:
     """Create an invalid tool call.