langchain-core 1.0.0a8__py3-none-any.whl → 1.0.0rc1__py3-none-any.whl

langchain_core/load/serializable.py

@@ -25,16 +25,16 @@ class BaseSerialized(TypedDict):
     id: list[str]
     """The unique identifier of the object."""
     name: NotRequired[str]
-    """The name of the object. Optional."""
+    """The name of the object."""
     graph: NotRequired[dict[str, Any]]
-    """The graph of the object. Optional."""
+    """The graph of the object."""
 
 
 class SerializedConstructor(BaseSerialized):
     """Serialized constructor."""
 
     type: Literal["constructor"]
-    """The type of the object. Must be ``'constructor'``."""
+    """The type of the object. Must be `'constructor'`."""
     kwargs: dict[str, Any]
     """The constructor arguments."""
 
@@ -43,16 +43,16 @@ class SerializedSecret(BaseSerialized):
     """Serialized secret."""
 
     type: Literal["secret"]
-    """The type of the object. Must be ``'secret'``."""
+    """The type of the object. Must be `'secret'`."""
 
 
 class SerializedNotImplemented(BaseSerialized):
     """Serialized not implemented."""
 
     type: Literal["not_implemented"]
-    """The type of the object. Must be ``'not_implemented'``."""
+    """The type of the object. Must be `'not_implemented'`."""
     repr: str | None
-    """The representation of the object. Optional."""
+    """The representation of the object."""
 
 
 def try_neq_default(value: Any, key: str, model: BaseModel) -> bool:
@@ -61,7 +61,7 @@ def try_neq_default(value: Any, key: str, model: BaseModel) -> bool:
     Args:
         value: The value.
         key: The key.
-        model: The pydantic model.
+        model: The Pydantic model.
 
     Returns:
         Whether the value is different from the default.
@@ -92,19 +92,19 @@ class Serializable(BaseModel, ABC):
 
     It relies on the following methods and properties:
 
-    - ``is_lc_serializable``: Is this class serializable?
-      By design, even if a class inherits from Serializable, it is not serializable by
-      default. This is to prevent accidental serialization of objects that should not
-      be serialized.
-    - ``get_lc_namespace``: Get the namespace of the langchain object.
-      During deserialization, this namespace is used to identify
-      the correct class to instantiate.
-      Please see the ``Reviver`` class in ``langchain_core.load.load`` for more details.
-      During deserialization an additional mapping is handle
-      classes that have moved or been renamed across package versions.
-    - ``lc_secrets``: A map of constructor argument names to secret ids.
-    - ``lc_attributes``: List of additional attribute names that should be included
-      as part of the serialized representation.
+    - `is_lc_serializable`: Is this class serializable?
+        By design, even if a class inherits from `Serializable`, it is not serializable
+        by default. This is to prevent accidental serialization of objects that should
+        not be serialized.
+    - `get_lc_namespace`: Get the namespace of the langchain object.
+        During deserialization, this namespace is used to identify
+        the correct class to instantiate.
+        Please see the `Reviver` class in `langchain_core.load.load` for more details.
+        During deserialization an additional mapping is handle classes that have moved
+        or been renamed across package versions.
+    - `lc_secrets`: A map of constructor argument names to secret ids.
+    - `lc_attributes`: List of additional attribute names that should be included
+        as part of the serialized representation.
     """
 
     # Remove default BaseModel init docstring.
@@ -116,12 +116,12 @@ class Serializable(BaseModel, ABC):
     def is_lc_serializable(cls) -> bool:
         """Is this class serializable?
 
-        By design, even if a class inherits from Serializable, it is not serializable by
-        default. This is to prevent accidental serialization of objects that should not
-        be serialized.
+        By design, even if a class inherits from `Serializable`, it is not serializable
+        by default. This is to prevent accidental serialization of objects that should
+        not be serialized.
 
         Returns:
-            Whether the class is serializable. Default is False.
+            Whether the class is serializable. Default is `False`.
         """
         return False
 
@@ -133,7 +133,7 @@ class Serializable(BaseModel, ABC):
         namespace is ["langchain", "llms", "openai"]
 
         Returns:
-            The namespace as a list of strings.
+            The namespace.
         """
         return cls.__module__.split(".")
 
@@ -141,8 +141,7 @@ class Serializable(BaseModel, ABC):
     def lc_secrets(self) -> dict[str, str]:
         """A map of constructor argument names to secret ids.
 
-        For example,
-            {"openai_api_key": "OPENAI_API_KEY"}
+        For example, `{"openai_api_key": "OPENAI_API_KEY"}`
         """
         return {}
 
@@ -151,6 +150,7 @@ class Serializable(BaseModel, ABC):
         """List of attribute names that should be included in the serialized kwargs.
 
         These attributes must be accepted by the constructor.
+
         Default is an empty dictionary.
         """
         return {}
@@ -161,8 +161,9 @@ class Serializable(BaseModel, ABC):
 
         The unique identifier is a list of strings that describes the path
         to the object.
+
         For example, for the class `langchain.llms.openai.OpenAI`, the id is
-        ["langchain", "llms", "openai", "OpenAI"].
+        `["langchain", "llms", "openai", "OpenAI"]`.
         """
         # Pydantic generics change the class name. So we need to do the following
         if (
@@ -193,7 +194,7 @@ class Serializable(BaseModel, ABC):
             ValueError: If the class has deprecated attributes.
 
         Returns:
-            A json serializable object or a SerializedNotImplemented object.
+            A json serializable object or a `SerializedNotImplemented` object.
         """
         if not self.is_lc_serializable():
             return self.to_json_not_implemented()
@@ -268,7 +269,7 @@ class Serializable(BaseModel, ABC):
         """Serialize a "not implemented" object.
 
         Returns:
-            SerializedNotImplemented.
+            `SerializedNotImplemented`.
         """
         return to_json_not_implemented(self)
 
@@ -283,8 +284,8 @@ def _is_field_useful(inst: Serializable, key: str, value: Any) -> bool:
 
     Returns:
         Whether the field is useful. If the field is required, it is useful.
-        If the field is not required, it is useful if the value is not None.
-        If the field is not required and the value is None, it is useful if the
+        If the field is not required, it is useful if the value is not `None`.
+        If the field is not required and the value is `None`, it is useful if the
         default value is different from the value.
     """
     field = type(inst).model_fields.get(key)
@@ -343,10 +344,10 @@ def to_json_not_implemented(obj: object) -> SerializedNotImplemented:
     """Serialize a "not implemented" object.
 
     Args:
-        obj: object to serialize.
+        obj: Object to serialize.
 
     Returns:
-        SerializedNotImplemented
+        `SerializedNotImplemented`
     """
     id_: list[str] = []
     try:

langchain_core/messages/__init__.py

@@ -1,19 +1,4 @@
-"""**Messages** are objects used in prompts and chat conversations.
-
-**Class hierarchy:**
-
-.. code-block::
-
-    BaseMessage --> SystemMessage, AIMessage, HumanMessage, ChatMessage, FunctionMessage, ToolMessage
-                --> BaseMessageChunk --> SystemMessageChunk, AIMessageChunk, HumanMessageChunk, ChatMessageChunk, FunctionMessageChunk, ToolMessageChunk
-
-**Main helpers:**
-
-.. code-block::
-
-    ChatPromptTemplate
-
-"""  # noqa: E501
+"""**Messages** are objects used in prompts and chat conversations."""
 
 from typing import TYPE_CHECKING
 

langchain_core/messages/ai.py

@@ -40,13 +40,13 @@ class InputTokenDetails(TypedDict, total=False):
     Does *not* need to sum to full input token count. Does *not* need to have all keys.
 
     Example:
-        .. code-block:: python
-
-            {
-                "audio": 10,
-                "cache_creation": 200,
-                "cache_read": 100,
-            }
+        ```python
+        {
+            "audio": 10,
+            "cache_creation": 200,
+            "cache_read": 100,
+        }
+        ```
 
     !!! version-added "Added in version 0.3.9"
 
@@ -76,12 +76,12 @@ class OutputTokenDetails(TypedDict, total=False):
     Does *not* need to sum to full output token count. Does *not* need to have all keys.
 
     Example:
-        .. code-block:: python
-
-            {
-                "audio": 10,
-                "reasoning": 200,
-            }
+        ```python
+        {
+            "audio": 10,
+            "reasoning": 200,
+        }
+        ```
 
     !!! version-added "Added in version 0.3.9"
 
@@ -104,25 +104,25 @@ class UsageMetadata(TypedDict):
     This is a standard representation of token usage that is consistent across models.
 
     Example:
-        .. code-block:: python
-
-            {
-                "input_tokens": 350,
-                "output_tokens": 240,
-                "total_tokens": 590,
-                "input_token_details": {
-                    "audio": 10,
-                    "cache_creation": 200,
-                    "cache_read": 100,
-                },
-                "output_token_details": {
-                    "audio": 10,
-                    "reasoning": 200,
-                },
-            }
+        ```python
+        {
+            "input_tokens": 350,
+            "output_tokens": 240,
+            "total_tokens": 590,
+            "input_token_details": {
+                "audio": 10,
+                "cache_creation": 200,
+                "cache_read": 100,
+            },
+            "output_token_details": {
+                "audio": 10,
+                "reasoning": 200,
+            },
+        }
+        ```
 
     !!! warning "Behavior changed in 0.3.9"
-        Added ``input_token_details`` and ``output_token_details``.
+        Added `input_token_details` and `output_token_details`.
 
     """
 
@@ -191,14 +191,14 @@ class AIMessage(BaseMessage):
         content_blocks: list[types.ContentBlock] | None = None,
         **kwargs: Any,
     ) -> None:
-        """Initialize ``AIMessage``.
+        """Initialize `AIMessage`.
 
-        Specify ``content`` as positional arg or ``content_blocks`` for typing.
+        Specify `content` as positional arg or `content_blocks` for typing.
 
         Args:
             content: The content of the message.
             content_blocks: Typed standard content.
-            kwargs: Additional arguments to pass to the parent class.
+            **kwargs: Additional arguments to pass to the parent class.
         """
         if content_blocks is not None:
             # If there are tool calls in content_blocks, but not in tool_calls, add them
@@ -229,7 +229,7 @@ class AIMessage(BaseMessage):
 
         If the message has a known model provider, use the provider-specific translator
         first before falling back to best-effort parsing. For details, see the property
-        on ``BaseMessage``.
+        on `BaseMessage`.
         """
         if self.response_metadata.get("output_version") == "v1":
             return cast("list[types.ContentBlock]", self.content)
@@ -335,7 +335,7 @@ class AIMessage(BaseMessage):
 
         Args:
             html: Whether to return an HTML-formatted string.
-                 Defaults to False.
+                Defaults to `False`.
 
         Returns:
             A pretty representation of the message.
@@ -380,7 +380,7 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
     type: Literal["AIMessageChunk"] = "AIMessageChunk"  # type: ignore[assignment]
     """The type of the message (used for deserialization).
 
-    Defaults to ``AIMessageChunk``.
+    Defaults to `AIMessageChunk`.
 
     """
 
@@ -390,8 +390,8 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
     chunk_position: Literal["last"] | None = None
     """Optional span represented by an aggregated AIMessageChunk.
 
-    If a chunk with ``chunk_position="last"`` is aggregated into a stream,
-    ``tool_call_chunks`` in message content will be parsed into ``tool_calls``.
+    If a chunk with `chunk_position="last"` is aggregated into a stream,
+    `tool_call_chunks` in message content will be parsed into `tool_calls`.
     """
 
     @property
@@ -545,6 +545,9 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
                     and call_id in id_to_tc
                 ):
                     self.content[idx] = cast("dict[str, Any]", id_to_tc[call_id])
+                    if "extras" in block:
+                        # mypy does not account for instance check for dict above
+                        self.content[idx]["extras"] = block["extras"]  # type: ignore[index]
 
         return self
 
@@ -596,14 +599,14 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
 def add_ai_message_chunks(
     left: AIMessageChunk, *others: AIMessageChunk
 ) -> AIMessageChunk:
-    """Add multiple ``AIMessageChunk``s together.
+    """Add multiple `AIMessageChunk`s together.
 
     Args:
-        left: The first ``AIMessageChunk``.
-        *others: Other ``AIMessageChunk``s to add.
+        left: The first `AIMessageChunk`.
+        *others: Other `AIMessageChunk`s to add.
 
     Returns:
-        The resulting ``AIMessageChunk``.
+        The resulting `AIMessageChunk`.
 
     """
     content = merge_content(left.content, *(o.content for o in others))
@@ -681,43 +684,42 @@ def add_usage(left: UsageMetadata | None, right: UsageMetadata | None) -> UsageM
     """Recursively add two UsageMetadata objects.
 
     Example:
-        .. code-block:: python
-
-            from langchain_core.messages.ai import add_usage
-
-            left = UsageMetadata(
-                input_tokens=5,
-                output_tokens=0,
-                total_tokens=5,
-                input_token_details=InputTokenDetails(cache_read=3),
-            )
-            right = UsageMetadata(
-                input_tokens=0,
-                output_tokens=10,
-                total_tokens=10,
-                output_token_details=OutputTokenDetails(reasoning=4),
-            )
+        ```python
+        from langchain_core.messages.ai import add_usage
+
+        left = UsageMetadata(
+            input_tokens=5,
+            output_tokens=0,
+            total_tokens=5,
+            input_token_details=InputTokenDetails(cache_read=3),
+        )
+        right = UsageMetadata(
+            input_tokens=0,
+            output_tokens=10,
+            total_tokens=10,
+            output_token_details=OutputTokenDetails(reasoning=4),
+        )
 
-            add_usage(left, right)
+        add_usage(left, right)
+        ```
 
         results in
 
-        .. code-block:: python
-
-            UsageMetadata(
-                input_tokens=5,
-                output_tokens=10,
-                total_tokens=15,
-                input_token_details=InputTokenDetails(cache_read=3),
-                output_token_details=OutputTokenDetails(reasoning=4),
-            )
-
+        ```python
+        UsageMetadata(
+            input_tokens=5,
+            output_tokens=10,
+            total_tokens=15,
+            input_token_details=InputTokenDetails(cache_read=3),
+            output_token_details=OutputTokenDetails(reasoning=4),
+        )
+        ```
     Args:
-        left: The first ``UsageMetadata`` object.
-        right: The second ``UsageMetadata`` object.
+        left: The first `UsageMetadata` object.
+        right: The second `UsageMetadata` object.
 
     Returns:
-        The sum of the two ``UsageMetadata`` objects.
+        The sum of the two `UsageMetadata` objects.
 
     """
     if not (left or right):
@@ -740,48 +742,47 @@ def add_usage(left: UsageMetadata | None, right: UsageMetadata | None) -> UsageM
 def subtract_usage(
     left: UsageMetadata | None, right: UsageMetadata | None
 ) -> UsageMetadata:
-    """Recursively subtract two ``UsageMetadata`` objects.
+    """Recursively subtract two `UsageMetadata` objects.
 
-    Token counts cannot be negative so the actual operation is ``max(left - right, 0)``.
+    Token counts cannot be negative so the actual operation is `max(left - right, 0)`.
 
     Example:
-        .. code-block:: python
-
-            from langchain_core.messages.ai import subtract_usage
-
-            left = UsageMetadata(
-                input_tokens=5,
-                output_tokens=10,
-                total_tokens=15,
-                input_token_details=InputTokenDetails(cache_read=4),
-            )
-            right = UsageMetadata(
-                input_tokens=3,
-                output_tokens=8,
-                total_tokens=11,
-                output_token_details=OutputTokenDetails(reasoning=4),
-            )
+        ```python
+        from langchain_core.messages.ai import subtract_usage
+
+        left = UsageMetadata(
+            input_tokens=5,
+            output_tokens=10,
+            total_tokens=15,
+            input_token_details=InputTokenDetails(cache_read=4),
+        )
+        right = UsageMetadata(
+            input_tokens=3,
+            output_tokens=8,
+            total_tokens=11,
+            output_token_details=OutputTokenDetails(reasoning=4),
+        )
 
-            subtract_usage(left, right)
+        subtract_usage(left, right)
+        ```
 
         results in
 
-        .. code-block:: python
-
-            UsageMetadata(
-                input_tokens=2,
-                output_tokens=2,
-                total_tokens=4,
-                input_token_details=InputTokenDetails(cache_read=4),
-                output_token_details=OutputTokenDetails(reasoning=0),
-            )
-
+        ```python
+        UsageMetadata(
+            input_tokens=2,
+            output_tokens=2,
+            total_tokens=4,
+            input_token_details=InputTokenDetails(cache_read=4),
+            output_token_details=OutputTokenDetails(reasoning=0),
+        )
+        ```
     Args:
-        left: The first ``UsageMetadata`` object.
-        right: The second ``UsageMetadata`` object.
+        left: The first `UsageMetadata` object.
+        right: The second `UsageMetadata` object.
 
     Returns:
-        The resulting ``UsageMetadata`` after subtraction.
+        The resulting `UsageMetadata` after subtraction.
 
     """
     if not (left or right):

langchain_core/messages/base.py

@@ -48,13 +48,13 @@ class TextAccessor(str):
 
     Exists to maintain backward compatibility while transitioning from method-based to
     property-based text access in message objects. In LangChain <v1.0, message text was
-    accessed via ``.text()`` method calls. In v1.0=<, the preferred pattern is property
-    access via ``.text``.
+    accessed via `.text()` method calls. In v1.0=<, the preferred pattern is property
+    access via `.text`.
 
-    Rather than breaking existing code immediately, ``TextAccessor`` allows both
+    Rather than breaking existing code immediately, `TextAccessor` allows both
     patterns:
-    - Modern property access: ``message.text`` (returns string directly)
-    - Legacy method access: ``message.text()`` (callable, emits deprecation warning)
+    - Modern property access: `message.text` (returns string directly)
+    - Legacy method access: `message.text()` (callable, emits deprecation warning)
 
     """
 
@@ -67,12 +67,12 @@ class TextAccessor(str):
     def __call__(self) -> str:
         """Enable method-style text access for backward compatibility.
 
-        This method exists solely to support legacy code that calls ``.text()``
-        as a method. New code should use property access (``.text``) instead.
+        This method exists solely to support legacy code that calls `.text()`
+        as a method. New code should use property access (`.text`) instead.
 
         !!! deprecated
-            As of `langchain-core` 1.0.0, calling ``.text()`` as a method is deprecated.
-            Use ``.text`` as a property instead. This method will be removed in 2.0.0.
+            As of `langchain-core` 1.0.0, calling `.text()` as a method is deprecated.
+            Use `.text` as a property instead. This method will be removed in 2.0.0.
 
         Returns:
             The string content, identical to property access.
@@ -92,7 +92,7 @@ class TextAccessor(str):
 class BaseMessage(Serializable):
     """Base abstract message class.
 
-    Messages are the inputs and outputs of a ``ChatModel``.
+    Messages are the inputs and outputs of a `ChatModel`.
     """
 
     content: str | list[str | dict]
@@ -159,14 +159,14 @@ class BaseMessage(Serializable):
         content_blocks: list[types.ContentBlock] | None = None,
         **kwargs: Any,
     ) -> None:
-        """Initialize ``BaseMessage``.
+        """Initialize `BaseMessage`.
 
-        Specify ``content`` as positional arg or ``content_blocks`` for typing.
+        Specify `content` as positional arg or `content_blocks` for typing.
 
         Args:
             content: The string contents of the message.
             content_blocks: Typed standard content.
-            kwargs: Additional arguments to pass to the parent class.
+            **kwargs: Additional arguments to pass to the parent class.
         """
         if content_blocks is not None:
             super().__init__(content=content_blocks, **kwargs)
@@ -175,7 +175,7 @@ class BaseMessage(Serializable):
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """``BaseMessage`` is serializable.
+        """`BaseMessage` is serializable.
 
         Returns:
             True
@@ -187,7 +187,7 @@ class BaseMessage(Serializable):
         """Get the namespace of the langchain object.
 
         Returns:
-            ``["langchain", "schema", "messages"]``
+            `["langchain", "schema", "messages"]`
         """
         return ["langchain", "schema", "messages"]
 
@@ -259,11 +259,11 @@ class BaseMessage(Serializable):
     def text(self) -> TextAccessor:
         """Get the text content of the message as a string.
 
-        Can be used as both property (``message.text``) and method (``message.text()``).
+        Can be used as both property (`message.text`) and method (`message.text()`).
 
         !!! deprecated
-            As of langchain-core 1.0.0, calling ``.text()`` as a method is deprecated.
-            Use ``.text`` as a property instead. This method will be removed in 2.0.0.
+            As of langchain-core 1.0.0, calling `.text()` as a method is deprecated.
+            Use `.text` as a property instead. This method will be removed in 2.0.0.
 
         Returns:
             The text content of the message.
@@ -306,7 +306,7 @@ class BaseMessage(Serializable):
         """Get a pretty representation of the message.
 
         Args:
-            html: Whether to format the message as HTML. If True, the message will be
+            html: Whether to format the message as HTML. If `True`, the message will be
                 formatted with HTML tags. Default is False.
 
         Returns:
@@ -331,8 +331,8 @@ def merge_content(
     """Merge multiple message contents.
 
     Args:
-        first_content: The first ``content``. Can be a string or a list.
-        contents: The other ``content``s. 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.
@@ -388,9 +388,9 @@ 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):
@@ -439,8 +439,8 @@ 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()}
@@ -450,7 +450,7 @@ 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 ``BaseMessage``s) to convert.
+        messages: Sequence of messages (as `BaseMessage`s) to convert.
 
     Returns:
         List of messages as dicts.