langchain-core 0.3.74__py3-none-any.whl → 0.3.76__py3-none-any.whl

langchain_core/load/dump.py

@@ -6,6 +6,8 @@ from typing import Any
 from pydantic import BaseModel
 
 from langchain_core.load.serializable import Serializable, to_json_not_implemented
+from langchain_core.messages import AIMessage
+from langchain_core.outputs import ChatGeneration
 
 
 def default(obj: Any) -> Any:
@@ -23,9 +25,6 @@ def default(obj: Any) -> Any:
 
 
 def _dump_pydantic_models(obj: Any) -> Any:
-    from langchain_core.messages import AIMessage
-    from langchain_core.outputs import ChatGeneration
-
     if (
         isinstance(obj, ChatGeneration)
         and isinstance(obj.message, AIMessage)
@@ -73,10 +72,9 @@ def dumps(obj: Any, *, pretty: bool = False, **kwargs: Any) -> str:
 def dumpd(obj: Any) -> Any:
     """Return a dict representation of an object.
 
-    Note:
-        Unfortunately this function is not as efficient as it could be
-        because it first dumps the object to a json string and then loads it
-        back into a dictionary.
+    .. note::
+        Unfortunately this function is not as efficient as it could be because it first
+        dumps the object to a json string and then loads it back into a dictionary.
 
     Args:
         obj: The object to dump.

langchain_core/load/load.py

@@ -95,7 +95,21 @@ class Reviver:
         self.ignore_unserializable_fields = ignore_unserializable_fields
 
     def __call__(self, value: dict[str, Any]) -> Any:
-        """Revive the value."""
+        """Revive the value.
+
+        Args:
+            value: The value to revive.
+
+        Returns:
+            The revived value.
+
+        Raises:
+            ValueError: If the namespace is invalid.
+            ValueError: If trying to deserialize something that cannot
+                be deserialized in the current version of langchain-core.
+            NotImplementedError: If the object is not implemented and
+                ``ignore_unserializable_fields`` is False.
+        """
         if (
             value.get("lc") == 1
             and value.get("type") == "secret"

langchain_core/load/serializable.py

@@ -20,53 +20,41 @@ logger = logging.getLogger(__name__)
 
 
 class BaseSerialized(TypedDict):
-    """Base class for serialized objects.
-
-    Parameters:
-        lc: The version of the serialization format.
-        id: The unique identifier of the object.
-        name: The name of the object. Optional.
-        graph: The graph of the object. Optional.
-    """
+    """Base class for serialized objects."""
 
     lc: int
+    """The version of the serialization format."""
     id: list[str]
+    """The unique identifier of the object."""
     name: NotRequired[str]
+    """The name of the object. Optional."""
     graph: NotRequired[dict[str, Any]]
+    """The graph of the object. Optional."""
 
 
 class SerializedConstructor(BaseSerialized):
-    """Serialized constructor.
-
-    Parameters:
-        type: The type of the object. Must be "constructor".
-        kwargs: The constructor arguments.
-    """
+    """Serialized constructor."""
 
     type: Literal["constructor"]
+    """The type of the object. Must be ``'constructor'``."""
     kwargs: dict[str, Any]
+    """The constructor arguments."""
 
 
 class SerializedSecret(BaseSerialized):
-    """Serialized secret.
-
-    Parameters:
-        type: The type of the object. Must be "secret".
-    """
+    """Serialized secret."""
 
     type: Literal["secret"]
+    """The type of the object. Must be ``'secret'``."""
 
 
 class SerializedNotImplemented(BaseSerialized):
-    """Serialized not implemented.
-
-    Parameters:
-        type: The type of the object. Must be "not_implemented".
-        repr: The representation of the object. Optional.
-    """
+    """Serialized not implemented."""
 
     type: Literal["not_implemented"]
+    """The type of the object. Must be ``'not_implemented'``."""
     repr: Optional[str]
+    """The representation of the object. Optional."""
 
 
 def try_neq_default(value: Any, key: str, model: BaseModel) -> bool:
@@ -79,9 +67,6 @@ def try_neq_default(value: Any, key: str, model: BaseModel) -> bool:
 
     Returns:
         Whether the value is different from the default.
-
-    Raises:
-        Exception: If the key is not in the model.
     """
     field = type(model).model_fields[key]
     return _try_neq_default(value, field)
@@ -109,19 +94,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.
@@ -148,6 +133,9 @@ class Serializable(BaseModel, ABC):
 
         For example, if the class is `langchain.llms.openai.OpenAI`, then the
         namespace is ["langchain", "llms", "openai"]
+
+        Returns:
+            The namespace as a list of strings.
         """
         return cls.__module__.split(".")
 
@@ -171,7 +159,7 @@ class Serializable(BaseModel, ABC):
 
     @classmethod
     def lc_id(cls) -> list[str]:
-        """A unique identifier for this class for serialization purposes.
+        """Return a unique identifier for this class for serialization purposes.
 
         The unique identifier is a list of strings that describes the path
         to the object.
@@ -203,6 +191,9 @@ class Serializable(BaseModel, ABC):
     def to_json(self) -> Union[SerializedConstructor, SerializedNotImplemented]:
         """Serialize the object to JSON.
 
+        Raises:
+            ValueError: If the class has deprecated attributes.
+
         Returns:
             A json serializable object or a SerializedNotImplemented object.
         """
@@ -276,7 +267,11 @@ class Serializable(BaseModel, ABC):
         }
 
     def to_json_not_implemented(self) -> SerializedNotImplemented:
-        """Serialize a "not implemented" object."""
+        """Serialize a "not implemented" object.
+
+        Returns:
+            SerializedNotImplemented.
+        """
         return to_json_not_implemented(self)
 
 

langchain_core/memory.py

@@ -45,16 +45,20 @@ class BaseMemory(Serializable, ABC):
                 def memory_variables(self) -> list[str]:
                     return list(self.memories.keys())
 
-                def load_memory_variables(self, inputs: dict[str, Any]) -> dict[str, str]:
+                def load_memory_variables(
+                    self, inputs: dict[str, Any]
+                ) -> dict[str, str]:
                     return self.memories
 
-                def save_context(self, inputs: dict[str, Any], outputs: dict[str, str]) -> None:
+                def save_context(
+                    self, inputs: dict[str, Any], outputs: dict[str, str]
+                ) -> None:
                     pass
 
                 def clear(self) -> None:
                     pass
 
-    """  # noqa: E501
+    """
 
     model_config = ConfigDict(
         arbitrary_types_allowed=True,

langchain_core/messages/ai.py

@@ -124,7 +124,7 @@ class UsageMetadata(TypedDict):
                 "output_token_details": {
                     "audio": 10,
                     "reasoning": 200,
-                }
+                },
             }
 
     .. versionchanged:: 0.3.9
@@ -310,14 +310,8 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
     def init_tool_calls(self) -> Self:
         """Initialize tool calls from tool call chunks.
 
-        Args:
-            values: The values to validate.
-
         Returns:
-            The values with tool calls initialized.
-
-        Raises:
-            ValueError: If the tool call chunks are malformed.
+            This ``AIMessageChunk``.
         """
         if not self.tool_call_chunks:
             if self.tool_calls:
@@ -358,7 +352,7 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
 
         for chunk in self.tool_call_chunks:
             try:
-                args_ = parse_partial_json(chunk["args"]) if chunk["args"] != "" else {}  # type: ignore[arg-type]
+                args_ = parse_partial_json(chunk["args"]) if chunk["args"] else {}
                 if isinstance(args_, dict):
                     tool_calls.append(
                         create_tool_call(
@@ -389,7 +383,19 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
 def add_ai_message_chunks(
     left: AIMessageChunk, *others: AIMessageChunk
 ) -> AIMessageChunk:
-    """Add multiple AIMessageChunks together."""
+    """Add multiple ``AIMessageChunk``s together.
+
+    Args:
+        left: The first ``AIMessageChunk``.
+        *others: Other ``AIMessageChunk``s to add.
+
+    Raises:
+        ValueError: If the example values of the chunks are not the same.
+
+    Returns:
+        The resulting ``AIMessageChunk``.
+
+    """
     if any(left.example != o.example for o in others):
         msg = "Cannot concatenate AIMessageChunks with different example values."
         raise ValueError(msg)
@@ -465,13 +471,13 @@ def add_usage(
                 input_tokens=5,
                 output_tokens=0,
                 total_tokens=5,
-                input_token_details=InputTokenDetails(cache_read=3)
+                input_token_details=InputTokenDetails(cache_read=3),
             )
             right = UsageMetadata(
                 input_tokens=0,
                 output_tokens=10,
                 total_tokens=10,
-                output_token_details=OutputTokenDetails(reasoning=4)
+                output_token_details=OutputTokenDetails(reasoning=4),
             )
 
             add_usage(left, right)
@@ -485,9 +491,16 @@ def add_usage(
                 output_tokens=10,
                 total_tokens=15,
                 input_token_details=InputTokenDetails(cache_read=3),
-                output_token_details=OutputTokenDetails(reasoning=4)
+                output_token_details=OutputTokenDetails(reasoning=4),
             )
 
+    Args:
+        left: The first ``UsageMetadata`` object.
+        right: The second ``UsageMetadata`` object.
+
+    Returns:
+        The sum of the two ``UsageMetadata`` objects.
+
     """
     if not (left or right):
         return UsageMetadata(input_tokens=0, output_tokens=0, total_tokens=0)
@@ -522,13 +535,13 @@ def subtract_usage(
                 input_tokens=5,
                 output_tokens=10,
                 total_tokens=15,
-                input_token_details=InputTokenDetails(cache_read=4)
+                input_token_details=InputTokenDetails(cache_read=4),
             )
             right = UsageMetadata(
                 input_tokens=3,
                 output_tokens=8,
                 total_tokens=11,
-                output_token_details=OutputTokenDetails(reasoning=4)
+                output_token_details=OutputTokenDetails(reasoning=4),
             )
 
             subtract_usage(left, right)
@@ -542,9 +555,16 @@ def subtract_usage(
                 output_tokens=2,
                 total_tokens=4,
                 input_token_details=InputTokenDetails(cache_read=4),
-                output_token_details=OutputTokenDetails(reasoning=0)
+                output_token_details=OutputTokenDetails(reasoning=0),
             )
 
+    Args:
+        left: The first ``UsageMetadata`` object.
+        right: The second ``UsageMetadata`` object.
+
+    Returns:
+        The resulting ``UsageMetadata`` after subtraction.
+
     """
     if not (left or right):
         return UsageMetadata(input_tokens=0, output_tokens=0, total_tokens=0)

langchain_core/messages/base.py

@@ -84,7 +84,8 @@ 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"]
 
@@ -109,8 +110,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
@@ -171,9 +180,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

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/human.py

@@ -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

langchain_core/messages/modifier.py

@@ -13,7 +13,7 @@ class RemoveMessage(BaseMessage):
 
     def __init__(
         self,
-        id: str,  # noqa: A002
+        id: str,
         **kwargs: Any,
     ) -> None:
         """Create a RemoveMessage.

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

langchain_core/messages/tool.py

@@ -32,7 +32,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
@@ -45,7 +45,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,14 +54,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."""
@@ -184,11 +185,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".
@@ -212,7 +209,7 @@ def tool_call(
     *,
     name: str,
     args: dict[str, Any],
-    id: Optional[str],  # noqa: A002
+    id: Optional[str],
 ) -> ToolCall:
     """Create a tool call.
 
@@ -220,6 +217,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")
 
@@ -236,12 +236,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)]
 
     """
 
@@ -260,7 +260,7 @@ def tool_call_chunk(
     *,
     name: Optional[str] = None,
     args: Optional[str] = None,
-    id: Optional[str] = None,  # noqa: A002
+    id: Optional[str] = None,
     index: Optional[int] = None,
 ) -> ToolCallChunk:
     """Create a tool call chunk.
@@ -270,6 +270,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"
@@ -298,7 +301,7 @@ def invalid_tool_call(
     *,
     name: Optional[str] = None,
     args: Optional[str] = None,
-    id: Optional[str] = None,  # noqa: A002
+    id: Optional[str] = None,
     error: Optional[str] = None,
 ) -> InvalidToolCall:
     """Create an invalid tool call.
@@ -308,6 +311,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 +323,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 +358,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: