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

langchain_core/language_models/llms.py

@@ -131,6 +131,7 @@ def create_base_retry_decorator(
 
 def _resolve_cache(*, cache: Union[BaseCache, bool, None]) -> Optional[BaseCache]:
     """Resolve the cache."""
+    llm_cache: Optional[BaseCache]
     if isinstance(cache, BaseCache):
         llm_cache = cache
     elif cache is None:
@@ -356,7 +357,9 @@ class BaseLLM(BaseLanguageModel[str], ABC):
             ls_params["ls_stop"] = stop
 
         # model
-        if hasattr(self, "model") and isinstance(self.model, str):
+        if "model" in kwargs and isinstance(kwargs["model"], str):
+            ls_params["ls_model_name"] = kwargs["model"]
+        elif hasattr(self, "model") and isinstance(self.model, str):
             ls_params["ls_model_name"] = self.model
         elif hasattr(self, "model_name") and isinstance(self.model_name, str):
             ls_params["ls_model_name"] = self.model_name
@@ -663,7 +666,18 @@ class BaseLLM(BaseLanguageModel[str], ABC):
         run_manager: Optional[CallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> LLMResult:
-        """Run the LLM on the given prompts."""
+        """Run the LLM on the given prompts.
+
+        Args:
+            prompts: The prompts to generate from.
+            stop: Stop words to use when generating. Model output is cut off at the
+                first occurrence of any of the stop substrings.
+                If stop tokens are not supported consider raising NotImplementedError.
+            run_manager: Callback manager for the run.
+
+        Returns:
+            The LLM result.
+        """
 
     async def _agenerate(
         self,
@@ -672,7 +686,18 @@ class BaseLLM(BaseLanguageModel[str], ABC):
         run_manager: Optional[AsyncCallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> LLMResult:
-        """Run the LLM on the given prompts."""
+        """Run the LLM on the given prompts.
+
+        Args:
+            prompts: The prompts to generate from.
+            stop: Stop words to use when generating. Model output is cut off at the
+                first occurrence of any of the stop substrings.
+                If stop tokens are not supported consider raising NotImplementedError.
+            run_manager: Callback manager for the run.
+
+        Returns:
+            The LLM result.
+        """
         return await run_in_executor(
             None,
             self._generate,
@@ -705,8 +730,8 @@ class BaseLLM(BaseLanguageModel[str], ABC):
             **kwargs: Arbitrary additional keyword arguments. These are usually passed
                 to the model provider API call.
 
-        Returns:
-            An iterator of GenerationChunks.
+        Yields:
+            Generation chunks.
         """
         raise NotImplementedError
 
@@ -731,8 +756,8 @@ class BaseLLM(BaseLanguageModel[str], ABC):
             **kwargs: Arbitrary additional keyword arguments. These are usually passed
                 to the model provider API call.
 
-        Returns:
-            An async iterator of GenerationChunks.
+        Yields:
+            Generation chunks.
         """
         iterator = await run_in_executor(
             None,
@@ -830,10 +855,11 @@ class BaseLLM(BaseLanguageModel[str], ABC):
         API.
 
         Use this method when you want to:
-            1. take advantage of batched calls,
-            2. need more output from the model than just the top generated value,
-            3. are building chains that are agnostic to the underlying language model
-                type (e.g., pure text completion models vs chat models).
+
+        1. Take advantage of batched calls,
+        2. Need more output from the model than just the top generated value,
+        3. Are building chains that are agnostic to the underlying language model
+           type (e.g., pure text completion models vs chat models).
 
         Args:
             prompts: List of string prompts.
@@ -853,6 +879,11 @@ class BaseLLM(BaseLanguageModel[str], ABC):
             **kwargs: Arbitrary additional keyword arguments. These are usually passed
                 to the model provider API call.
 
+        Raises:
+            ValueError: If prompts is not a list.
+            ValueError: If the length of ``callbacks``, ``tags``, ``metadata``, or
+                ``run_name`` (if provided) does not match the length of prompts.
+
         Returns:
             An LLMResult, which contains a list of candidate Generations for each input
                 prompt and additional model provider-specific output.
@@ -1090,10 +1121,11 @@ class BaseLLM(BaseLanguageModel[str], ABC):
         API.
 
         Use this method when you want to:
-            1. take advantage of batched calls,
-            2. need more output from the model than just the top generated value,
-            3. are building chains that are agnostic to the underlying language model
-                type (e.g., pure text completion models vs chat models).
+
+        1. Take advantage of batched calls,
+        2. Need more output from the model than just the top generated value,
+        3. Are building chains that are agnostic to the underlying language model
+           type (e.g., pure text completion models vs chat models).
 
         Args:
             prompts: List of string prompts.
@@ -1113,6 +1145,10 @@ class BaseLLM(BaseLanguageModel[str], ABC):
             **kwargs: Arbitrary additional keyword arguments. These are usually passed
                 to the model provider API call.
 
+        Raises:
+            ValueError: If the length of ``callbacks``, ``tags``, ``metadata``, or
+                ``run_name`` (if provided) does not match the length of prompts.
+
         Returns:
             An LLMResult, which contains a list of candidate Generations for each input
                 prompt and additional model provider-specific output.
@@ -1388,7 +1424,7 @@ class BaseLLM(BaseLanguageModel[str], ABC):
         return AIMessage(content=content)
 
     def __str__(self) -> str:
-        """Get a string representation of the object for printing."""
+        """Return a string representation of the object for printing."""
         cls_name = f"\033[1m{self.__class__.__name__}\033[0m"
         return f"{cls_name}\nParams: {self._identifying_params}"
 
@@ -1536,7 +1572,6 @@ class LLM(BaseLLM):
         run_manager: Optional[CallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> LLMResult:
-        """Run the LLM on the given prompt and input."""
         # TODO: add caching here.
         generations = []
         new_arg_supported = inspect.signature(self._call).parameters.get("run_manager")
@@ -1556,7 +1591,6 @@ class LLM(BaseLLM):
         run_manager: Optional[AsyncCallbackManagerForLLMRun] = None,
         **kwargs: Any,
     ) -> LLMResult:
-        """Async run the LLM on the given prompt and input."""
         generations = []
         new_arg_supported = inspect.signature(self._acall).parameters.get("run_manager")
         for prompt in prompts:

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)

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,24 +94,24 @@ 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.
     def __init__(self, *args: Any, **kwargs: Any) -> None:
-        """"""  # noqa: D419
+        """"""  # noqa: D419  # Intentional blank docstring
         super().__init__(*args, **kwargs)
 
     @classmethod
@@ -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

@@ -45,7 +45,6 @@ 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
 
             {
@@ -72,6 +71,7 @@ class InputTokenDetails(TypedDict, total=False):
 
     Since there was a cache hit, the tokens were read from the cache. More precisely,
     the model state given these tokens was read from the cache.
+
     """
 
 
@@ -81,7 +81,6 @@ 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
 
             {
@@ -100,6 +99,7 @@ class OutputTokenDetails(TypedDict, total=False):
 
     Tokens generated by the model in a chain of thought process (i.e. by OpenAI's o1
     models) that are not returned as part of model output.
+
     """
 
 
@@ -109,7 +109,6 @@ class UsageMetadata(TypedDict):
     This is a standard representation of token usage that is consistent across models.
 
     Example:
-
         .. code-block:: python
 
             {
@@ -124,7 +123,7 @@ class UsageMetadata(TypedDict):
                 "output_token_details": {
                     "audio": 10,
                     "reasoning": 200,
-                }
+                },
             }
 
     .. versionchanged:: 0.3.9
@@ -148,6 +147,7 @@ class UsageMetadata(TypedDict):
     """Breakdown of output token counts.
 
     Does *not* need to sum to full output token count. Does *not* need to have all keys.
+
     """
 
 
@@ -159,12 +159,14 @@ class AIMessage(BaseMessage):
     This message represents the output of the model and consists of both
     the raw output as returned by the model together standardized fields
     (e.g., tool calls, usage metadata) added by the LangChain framework.
+
     """
 
     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.
+
     """
 
     tool_calls: list[ToolCall] = []
@@ -175,15 +177,18 @@ class AIMessage(BaseMessage):
     """If provided, usage metadata for a message, such as token counts.
 
     This is a standard representation of token usage that is consistent across models.
+
     """
 
     type: Literal["ai"] = "ai"
-    """The type of the message (used for deserialization). Defaults to "ai"."""
+    """The type of the message (used for deserialization). Defaults to ``'ai'``."""
 
     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 ``AIMessage``.
 
         Args:
             content: The content of the message.
@@ -254,6 +259,7 @@ class AIMessage(BaseMessage):
 
         Returns:
             A pretty representation of the message.
+
         """
         base = super().pretty_repr(html=html)
         lines = []
@@ -293,7 +299,10 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
     # non-chunk variant.
     type: Literal["AIMessageChunk"] = "AIMessageChunk"  # type: ignore[assignment]
     """The type of the message (used for deserialization).
-    Defaults to "AIMessageChunk"."""
+
+    Defaults to ``AIMessageChunk``.
+
+    """
 
     tool_call_chunks: list[ToolCallChunk] = []
     """If provided, tool call chunks associated with the message."""
@@ -310,9 +319,6 @@ 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.
 
@@ -358,10 +364,7 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
 
         for chunk in self.tool_call_chunks:
             try:
-                if chunk["args"] is not None and chunk["args"] != "":
-                    args_ = parse_partial_json(chunk["args"])
-                else:
-                    args_ = {}
+                args_ = parse_partial_json(chunk["args"]) if chunk["args"] else {}
                 if isinstance(args_, dict):
                     tool_calls.append(
                         create_tool_call(
@@ -392,7 +395,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)
@@ -468,13 +483,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)
@@ -488,9 +503,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)
@@ -512,9 +534,9 @@ def add_usage(
 def subtract_usage(
     left: Optional[UsageMetadata], right: Optional[UsageMetadata]
 ) -> 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
@@ -525,13 +547,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)
@@ -545,9 +567,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)