langchain-core 0.4.0.dev0__py3-none-any.whl → 1.0.0__py3-none-any.whl

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
-    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.
+
     """
 
     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)."""
 
 
 class FunctionMessageChunk(FunctionMessage, BaseMessageChunk):
@@ -37,8 +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,56 +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.
 
-    HumanMessages 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))
-
+        ```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.
+    type: Literal["human"] = "human"
+    """The type of the message (used for serialization)."""
 
-    At the moment, this is ignored by most models. Usage is discouraged.
-    Defaults to False.
-    """
+    @overload
+    def __init__(
+        self,
+        content: str | list[str | dict],
+        **kwargs: Any,
+    ) -> None: ...
 
-    type: Literal["human"] = "human"
-    """The type of the message (used for serialization). Defaults to "human"."""
+    @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 HumanMessageChunk(HumanMessage, BaseMessageChunk):
@@ -60,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,10 +20,11 @@ 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.
+
         """
         if kwargs.pop("content", None):
             msg = "RemoveMessage does not support 'content' field."

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). Defaults to "system"."""
+    """The type of the message (used for serialization)."""
 
+    @overload
     def __init__(
-        self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
-    ) -> None:
-        """Pass in content as positional arg.
+        self,
+        content: str | list[str | dict],
+        **kwargs: Any,
+    ) -> None: ...
 
-        Args:
-               content: The string contents of the message.
-               kwargs: Additional fields to pass to the message.
-        """
-        super().__init__(content=content, **kwargs)
+    @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: str | list[str | dict] | None = None,
+        content_blocks: list[types.ContentBlock] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """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,5 +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,75 +1,73 @@
 """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 override
+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_blocks import InvalidToolCall as InvalidToolCall
-from langchain_core.messages.content_blocks import ToolCall as ToolCall
-from langchain_core.messages.content_blocks import ToolCallChunk as ToolCallChunk
+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`.
+
     """
 
 
 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
+    `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
-
-        .. code-block:: python
-
-            from langchain_core.messages import ToolMessage
+    Example: A `ToolMessage` representing a result of `42` from a tool call with id
 
-            ToolMessage(content='42', tool_call_id='call_Jja7J89XsjrOLA5r!MEOW!SL')
+    ```python
+    from langchain_core.messages import ToolMessage
 
+    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.
+    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
+    ```python
+    from langchain_core.messages import ToolMessage
 
-        .. code-block:: python
+    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..."},
+    }
 
-            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.
 
-    """  # 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)."""
 
     artifact: Any = None
     """Artifact of the Tool execution which is not meant to be sent to the model.
@@ -78,19 +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
@@ -99,6 +93,7 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
 
         Args:
             values: The model arguments.
+
         """
         content = values["content"]
         if isinstance(content, tuple):
@@ -136,16 +131,43 @@ class ToolMessage(BaseMessage, ToolOutputMixin):
             values["tool_call_id"] = str(tool_call_id)
         return values
 
+    @overload
     def __init__(
-        self, content: Union[str, list[Union[str, dict]]], **kwargs: Any
+        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: str | list[str | dict] | None = None,
+        content_blocks: list[types.ContentBlock] | None = None,
+        **kwargs: Any,
     ) -> None:
-        """Create a 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):
@@ -180,11 +202,38 @@ class ToolMessageChunk(ToolMessage, BaseMessageChunk):
         return super().__add__(other)
 
 
+class ToolCall(TypedDict):
+    """Represents an AI's request to call a tool.
+
+    Example:
+        ```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'`.
+
+    """
+
+    name: str
+    """The name of the tool to be called."""
+    args: dict[str, Any]
+    """The arguments to the tool call."""
+    id: str | None
+    """An identifier associated with the tool call.
+
+    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"]]
+
+
 def tool_call(
     *,
     name: str,
     args: dict[str, Any],
-    id: Optional[str],
+    id: str | None,
 ) -> ToolCall:
     """Create a tool call.
 
@@ -192,16 +241,49 @@ 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")
 
 
+class ToolCallChunk(TypedDict):
+    """A chunk of a tool call (yielded when streaming).
+
+    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.
+
+    Example:
+    ```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: str | None
+    """The name of the tool to be called."""
+    args: str | None
+    """The arguments to the tool call."""
+    id: str | None
+    """An identifier associated with the tool call."""
+    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.
 
@@ -210,6 +292,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"
@@ -218,10 +303,10 @@ def tool_call_chunk(
 
 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.
 
@@ -230,6 +315,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"
@@ -239,7 +327,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:
@@ -267,7 +362,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: