langchain-core 1.0.0a2__py3-none-any.whl → 1.0.0a3__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}"
 
@@ -1430,10 +1466,10 @@ class BaseLLM(BaseLanguageModel[str], ABC):
         prompt_dict = self.dict()
 
         if save_path.suffix == ".json":
-            with save_path.open("w") as f:
+            with save_path.open("w", encoding="utf-8") as f:
                 json.dump(prompt_dict, f, indent=4)
         elif save_path.suffix.endswith((".yaml", ".yml")):
-            with save_path.open("w") as f:
+            with save_path.open("w", encoding="utf-8") as f:
                 yaml.dump(prompt_dict, f, default_flow_style=False)
         else:
             msg = f"{save_path} must be json or yaml"
@@ -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,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/__init__.py

@@ -48,6 +48,7 @@ if TYPE_CHECKING:
         DataContentBlock,
         FileContentBlock,
         ImageContentBlock,
+        InvalidToolCall,
         NonStandardAnnotation,
         NonStandardContentBlock,
         PlainTextContentBlock,
@@ -63,7 +64,6 @@ if TYPE_CHECKING:
     from langchain_core.messages.modifier import RemoveMessage
     from langchain_core.messages.system import SystemMessage, SystemMessageChunk
     from langchain_core.messages.tool import (
-        InvalidToolCall,
         ToolCall,
         ToolCallChunk,
         ToolMessage,

langchain_core/messages/ai.py

@@ -4,10 +4,10 @@ import json
 import logging
 import operator
 from collections.abc import Sequence
-from typing import Any, Literal, Optional, Union, cast
+from typing import Any, Literal, Optional, Union, cast, overload
 
 from pydantic import model_validator
-from typing_extensions import NotRequired, Self, TypedDict, overload, override
+from typing_extensions import NotRequired, Self, TypedDict, override
 
 from langchain_core.messages import content as types
 from langchain_core.messages.base import (
@@ -15,8 +15,8 @@ from langchain_core.messages.base import (
     BaseMessageChunk,
     merge_content,
 )
+from langchain_core.messages.content import InvalidToolCall
 from langchain_core.messages.tool import (
-    InvalidToolCall,
     ToolCall,
     ToolCallChunk,
     default_tool_chunk_parser,
@@ -118,7 +118,7 @@ class UsageMetadata(TypedDict):
                 "output_token_details": {
                     "audio": 10,
                     "reasoning": 200,
-                }
+                },
             }
 
     .. versionchanged:: 0.3.9
@@ -155,12 +155,6 @@ class AIMessage(BaseMessage):
     (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] = []
     """If provided, tool calls associated with the message."""
     invalid_tool_calls: list[InvalidToolCall] = []
@@ -227,7 +221,9 @@ class AIMessage(BaseMessage):
 
         model_provider = self.response_metadata.get("model_provider")
         if model_provider:
-            from langchain_core.messages.block_translators import get_translator
+            from langchain_core.messages.block_translators import (  # noqa: PLC0415
+                get_translator,
+            )
 
             translator = get_translator(model_provider)
             if translator:
@@ -386,7 +382,9 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
 
         model_provider = self.response_metadata.get("model_provider")
         if model_provider:
-            from langchain_core.messages.block_translators import get_translator
+            from langchain_core.messages.block_translators import (  # noqa: PLC0415
+                get_translator,
+            )
 
             translator = get_translator(model_provider)
             if translator:
@@ -425,14 +423,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:
@@ -473,10 +465,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(
@@ -542,11 +531,16 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
 def add_ai_message_chunks(
     left: AIMessageChunk, *others: AIMessageChunk
 ) -> AIMessageChunk:
-    """Add multiple AIMessageChunks together."""
-    if any(left.example != o.example for o in others):
-        msg = "Cannot concatenate AIMessageChunks with different example values."
-        raise ValueError(msg)
+    """Add multiple ``AIMessageChunk``s together.
+
+    Args:
+        left: The first ``AIMessageChunk``.
+        *others: Other ``AIMessageChunk``s to add.
+
+    Returns:
+        The resulting ``AIMessageChunk``.
 
+    """
     content = merge_content(left.content, *(o.content for o in others))
     additional_kwargs = merge_dicts(
         left.additional_kwargs, *(o.additional_kwargs for o in others)
@@ -608,7 +602,6 @@ def add_ai_message_chunks(
     )
 
     return left.__class__(
-        example=left.example,
         content=content,
         additional_kwargs=additional_kwargs,
         tool_call_chunks=tool_call_chunks,
@@ -633,13 +626,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)
@@ -653,9 +646,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)
@@ -690,13 +690,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)
@@ -710,9 +710,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

@@ -150,7 +150,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"]
 
@@ -179,14 +180,14 @@ class BaseMessage(Serializable):
         .. versionadded:: 1.0.0
 
         """  # noqa: E501
-        from langchain_core.messages import content as types
-        from langchain_core.messages.block_translators.anthropic import (
+        from langchain_core.messages import content as types  # noqa: PLC0415
+        from langchain_core.messages.block_translators.anthropic import (  # noqa: PLC0415
             _convert_to_v1_from_anthropic_input,
         )
-        from langchain_core.messages.block_translators.langchain_v0 import (
+        from langchain_core.messages.block_translators.langchain_v0 import (  # noqa: PLC0415
             _convert_v0_multimodal_input_to_v1,
         )
-        from langchain_core.messages.block_translators.openai import (
+        from langchain_core.messages.block_translators.openai import (  # noqa: PLC0415
             _convert_to_v1_from_chat_completions_input,
         )
 
@@ -246,8 +247,16 @@ class BaseMessage(Serializable):
         return TextAccessor(text_value)
 
     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