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

langchain_core/_api/beta_decorator.py

@@ -174,6 +174,7 @@ def beta(
             def finalize(_wrapper: Callable[..., Any], new_doc: str) -> Any:
                 """Finalize the property."""
                 return property(fget=_fget, fset=_fset, fdel=_fdel, doc=new_doc)
+
         else:
             _name = _name or obj.__qualname__
             if not _obj_type:
@@ -226,17 +227,17 @@ def warn_beta(
 ) -> None:
     """Display a standardized beta annotation.
 
-    Arguments:
-        message : str, optional
+    Args:
+        message:
             Override the default beta message. The
             %(name)s, %(obj_type)s, %(addendum)s
             format specifiers will be replaced by the
             values of the respective arguments passed to this function.
-        name : str, optional
+        name:
             The name of the annotated object.
-        obj_type : str, optional
+        obj_type:
             The object type being annotated.
-        addendum : str, optional
+        addendum:
             Additional text appended directly to the final message.
     """
     if not message:

langchain_core/_api/deprecation.py

@@ -431,35 +431,35 @@ def warn_deprecated(
 ) -> None:
     """Display a standardized deprecation.
 
-    Arguments:
-        since : str
+    Args:
+        since:
             The release at which this API became deprecated.
-        message : str, optional
+        message:
             Override the default deprecation message. The %(since)s,
             %(name)s, %(alternative)s, %(obj_type)s, %(addendum)s,
             and %(removal)s format specifiers will be replaced by the
             values of the respective arguments passed to this function.
-        name : str, optional
+        name:
             The name of the deprecated object.
-        alternative : str, optional
+        alternative:
             An alternative API that the user may use in place of the
             deprecated API. The deprecation warning will tell the user
             about this alternative if provided.
-        alternative_import: str, optional
+        alternative_import:
             An alternative import that the user may use instead.
-        pending : bool, optional
+        pending:
             If True, uses a PendingDeprecationWarning instead of a
             DeprecationWarning. Cannot be used together with removal.
-        obj_type : str, optional
+        obj_type:
             The object type being deprecated.
-        addendum : str, optional
+        addendum:
             Additional text appended directly to the final message.
-        removal : str, optional
+        removal:
             The expected removal version. With the default (an empty
             string), a removal version is automatically computed from
             since. Set to other Falsy values to not schedule a removal
             date. Cannot be used together with pending.
-        package: str, optional
+        package:
             The package of the deprecated object.
     """
     if not pending:

langchain_core/callbacks/base.py

@@ -71,7 +71,9 @@ class LLMManagerMixin:
         parent_run_id: Optional[UUID] = None,
         **kwargs: Any,
     ) -> Any:
-        """Run on new LLM token. Only available when streaming is enabled.
+        """Run on new output token. Only available when streaming is enabled.
+
+        For both chat models and non-chat models (legacy LLMs).
 
         Args:
             token (str): The new token.
@@ -243,7 +245,7 @@ class CallbackManagerMixin:
     ) -> Any:
         """Run when LLM starts running.
 
-        .. ATTENTION::
+        .. warning::
             This method is called for non-chat models (regular LLMs). If you're
             implementing a handler for a chat model, you should use
             ``on_chat_model_start`` instead.
@@ -271,8 +273,9 @@ class CallbackManagerMixin:
     ) -> Any:
         """Run when a chat model starts running.
 
-        **ATTENTION**: This method is called for chat models. If you're implementing
-        a handler for a non-chat model, you should use ``on_llm_start`` instead.
+        .. warning::
+            This method is called for chat models. If you're implementing a handler for
+            a non-chat model, you should use ``on_llm_start`` instead.
 
         Args:
             serialized (dict[str, Any]): The serialized chat model.
@@ -489,9 +492,9 @@ class AsyncCallbackHandler(BaseCallbackHandler):
         metadata: Optional[dict[str, Any]] = None,
         **kwargs: Any,
     ) -> None:
-        """Run when LLM starts running.
+        """Run when the model starts running.
 
-        .. ATTENTION::
+        .. warning::
             This method is called for non-chat models (regular LLMs). If you're
             implementing a handler for a chat model, you should use
             ``on_chat_model_start`` instead.
@@ -519,8 +522,9 @@ class AsyncCallbackHandler(BaseCallbackHandler):
     ) -> Any:
         """Run when a chat model starts running.
 
-        **ATTENTION**: This method is called for chat models. If you're implementing
-        a handler for a non-chat model, you should use ``on_llm_start`` instead.
+        .. warning::
+            This method is called for chat models. If you're implementing a handler for
+            a non-chat model, you should use ``on_llm_start`` instead.
 
         Args:
             serialized (dict[str, Any]): The serialized chat model.
@@ -546,7 +550,9 @@ class AsyncCallbackHandler(BaseCallbackHandler):
         tags: Optional[list[str]] = None,
         **kwargs: Any,
     ) -> None:
-        """Run on new LLM token. Only available when streaming is enabled.
+        """Run on new output token. Only available when streaming is enabled.
+
+        For both chat models and non-chat models (legacy LLMs).
 
         Args:
             token (str): The new token.
@@ -567,7 +573,7 @@ class AsyncCallbackHandler(BaseCallbackHandler):
         tags: Optional[list[str]] = None,
         **kwargs: Any,
     ) -> None:
-        """Run when LLM ends running.
+        """Run when the model ends running.
 
         Args:
             response (LLMResult): The response which was generated.
@@ -867,7 +873,7 @@ class AsyncCallbackHandler(BaseCallbackHandler):
         metadata: Optional[dict[str, Any]] = None,
         **kwargs: Any,
     ) -> None:
-        """Override to define a handler for a custom event.
+        """Override to define a handler for custom events.
 
         Args:
             name: The name of the custom event.

langchain_core/callbacks/manager.py

@@ -92,7 +92,7 @@ def trace_as_chain_group(
         metadata (dict[str, Any], optional): The metadata to apply to all runs.
             Defaults to None.
 
-    .. note:
+    .. note::
         Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in
         LangSmith.
 
@@ -179,7 +179,7 @@ async def atrace_as_chain_group(
     Yields:
         The async callback manager for the chain group.
 
-    .. note:
+    .. note::
         Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in
         LangSmith.
 

langchain_core/callbacks/usage.py

@@ -32,7 +32,7 @@ class UsageMetadataCallbackHandler(BaseCallbackHandler):
             result_2 = llm_2.invoke("Hello", config={"callbacks": [callback]})
             callback.usage_metadata
 
-        .. code-block:: none
+        .. code-block::
 
             {'gpt-4o-mini-2024-07-18': {'input_tokens': 8,
               'output_tokens': 10,
@@ -119,7 +119,7 @@ def get_usage_metadata_callback(
                 llm_2.invoke("Hello")
                 print(cb.usage_metadata)
 
-        .. code-block:: none
+        .. code-block::
 
             {'gpt-4o-mini-2024-07-18': {'input_tokens': 8,
               'output_tokens': 10,

langchain_core/chat_history.py

@@ -65,33 +65,43 @@ class BaseChatMessageHistory(ABC):
 
         .. code-block:: python
 
+            import json
+            import os
+            from langchain_core.messages import messages_from_dict, message_to_dict
+
+
             class FileChatMessageHistory(BaseChatMessageHistory):
                 storage_path: str
                 session_id: str
 
                 @property
-                def messages(self):
-                    with open(
-                        os.path.join(storage_path, session_id),
-                        "r",
-                        encoding="utf-8",
-                    ) as f:
-                        messages = json.loads(f.read())
-                    return messages_from_dict(messages)
+                def messages(self) -> list[BaseMessage]:
+                    try:
+                        with open(
+                            os.path.join(self.storage_path, self.session_id),
+                            "r",
+                            encoding="utf-8",
+                        ) as f:
+                            messages_data = json.load(f)
+                        return messages_from_dict(messages_data)
+                    except FileNotFoundError:
+                        return []
 
                 def add_messages(self, messages: Sequence[BaseMessage]) -> None:
                     all_messages = list(self.messages)  # Existing messages
                     all_messages.extend(messages)  # Add new messages
 
                     serialized = [message_to_dict(message) for message in all_messages]
-                    # Can be further optimized by only writing new messages
-                    # using append mode.
-                    with open(os.path.join(storage_path, session_id), "w") as f:
-                        json.dump(messages, f)
-
-                def clear(self):
-                    with open(os.path.join(storage_path, session_id), "w") as f:
-                        f.write("[]")
+                    file_path = os.path.join(self.storage_path, self.session_id)
+                    os.makedirs(os.path.dirname(file_path), exist_ok=True)
+                    with open(file_path, "w", encoding="utf-8") as f:
+                        json.dump(serialized, f)
+
+                def clear(self) -> None:
+                    file_path = os.path.join(self.storage_path, self.session_id)
+                    os.makedirs(os.path.dirname(file_path), exist_ok=True)
+                    with open(file_path, "w", encoding="utf-8") as f:
+                        json.dump([], f)
 
     """
 

langchain_core/document_loaders/langsmith.py

@@ -31,7 +31,7 @@ class LangSmithLoader(BaseLoader):
             for doc in loader.lazy_load():
                 docs.append(doc)
 
-        .. code-block:: pycon
+        .. code-block:: python
 
             # -> [Document("...", metadata={"inputs": {...}, "outputs": {...}, ...}), ...]
 

langchain_core/indexing/api.py

@@ -56,7 +56,7 @@ def _warn_about_sha1() -> None:
             "that map to the same fingerprint. If this matters in your "
             "threat model, switch to a stronger algorithm such "
             "as 'blake2b', 'sha256', or 'sha512' by specifying "
-            " `key_encoder` parameter in the the `index` or `aindex` function. ",
+            " `key_encoder` parameter in the `index` or `aindex` function. ",
             category=UserWarning,
             stacklevel=2,
         )
@@ -296,7 +296,11 @@ def index(
     For the time being, documents are indexed using their hashes, and users
     are not able to specify the uid of the document.
 
-    Important:
+    .. versionchanged:: 0.3.25
+        Added ``scoped_full`` cleanup mode.
+
+    .. important::
+
         * In full mode, the loader should be returning
           the entire dataset, and not just a subset of the dataset.
           Otherwise, the auto_cleanup will remove documents that it is not
@@ -309,7 +313,7 @@ def index(
           chunks, and we index them using a batch size of 5, we'll have 3 batches
           all with the same source id. In general, to avoid doing too much
           redundant work select as big a batch size as possible.
-        * The `scoped_full` mode is suitable if determining an appropriate batch size
+        * The ``scoped_full`` mode is suitable if determining an appropriate batch size
           is challenging or if your data loader cannot return the entire dataset at
           once. This mode keeps track of source IDs in memory, which should be fine
           for most use cases. If your dataset is large (10M+ docs), you will likely
@@ -378,10 +382,6 @@ def index(
         TypeError: If ``vectorstore`` is not a VectorStore or a DocumentIndex.
         AssertionError: If ``source_id`` is None when cleanup mode is incremental.
             (should be unreachable code).
-
-    .. version_modified:: 0.3.25
-
-        * Added `scoped_full` cleanup mode.
     """
     # Behavior is deprecated, but we keep it for backwards compatibility.
     # # Warn only once per process.
@@ -636,26 +636,30 @@ async def aindex(
     documents were deleted, which documents should be skipped.
 
     For the time being, documents are indexed using their hashes, and users
-     are not able to specify the uid of the document.
-
-    Important:
-       * In full mode, the loader should be returning
-         the entire dataset, and not just a subset of the dataset.
-         Otherwise, the auto_cleanup will remove documents that it is not
-         supposed to.
-       * In incremental mode, if documents associated with a particular
-         source id appear across different batches, the indexing API
-         will do some redundant work. This will still result in the
-         correct end state of the index, but will unfortunately not be
-         100% efficient. For example, if a given document is split into 15
-         chunks, and we index them using a batch size of 5, we'll have 3 batches
-         all with the same source id. In general, to avoid doing too much
-         redundant work select as big a batch size as possible.
-       * The `scoped_full` mode is suitable if determining an appropriate batch size
-         is challenging or if your data loader cannot return the entire dataset at
-         once. This mode keeps track of source IDs in memory, which should be fine
-         for most use cases. If your dataset is large (10M+ docs), you will likely
-         need to parallelize the indexing process regardless.
+    are not able to specify the uid of the document.
+
+    .. versionchanged:: 0.3.25
+        Added ``scoped_full`` cleanup mode.
+
+    .. important::
+
+        * In full mode, the loader should be returning
+          the entire dataset, and not just a subset of the dataset.
+          Otherwise, the auto_cleanup will remove documents that it is not
+          supposed to.
+        * In incremental mode, if documents associated with a particular
+          source id appear across different batches, the indexing API
+          will do some redundant work. This will still result in the
+          correct end state of the index, but will unfortunately not be
+          100% efficient. For example, if a given document is split into 15
+          chunks, and we index them using a batch size of 5, we'll have 3 batches
+          all with the same source id. In general, to avoid doing too much
+          redundant work select as big a batch size as possible.
+        * The ``scoped_full`` mode is suitable if determining an appropriate batch size
+          is challenging or if your data loader cannot return the entire dataset at
+          once. This mode keeps track of source IDs in memory, which should be fine
+          for most use cases. If your dataset is large (10M+ docs), you will likely
+          need to parallelize the indexing process regardless.
 
     Args:
         docs_source: Data loader or iterable of documents to index.
@@ -720,10 +724,6 @@ async def aindex(
         TypeError: If ``vector_store`` is not a VectorStore or DocumentIndex.
         AssertionError: If ``source_id_key`` is None when cleanup mode is
             incremental or ``scoped_full`` (should be unreachable).
-
-    .. version_modified:: 0.3.25
-
-        * Added `scoped_full` cleanup mode.
     """
     # Behavior is deprecated, but we keep it for backwards compatibility.
     # # Warn only once per process.

langchain_core/language_models/chat_models.py

@@ -471,7 +471,7 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], ABC):
         **kwargs: Any,
     ) -> Iterator[BaseMessageChunk]:
         if not self._should_stream(async_api=False, **{**kwargs, "stream": True}):
-            # model doesn't implement streaming, so use default implementation
+            # Model doesn't implement streaming, so use default implementation
             yield cast(
                 "BaseMessageChunk",
                 self.invoke(input, config=config, stop=stop, **kwargs),
@@ -720,7 +720,9 @@ class BaseChatModel(BaseLanguageModel[BaseMessage], 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

langchain_core/language_models/fake_chat_models.py

@@ -19,7 +19,7 @@ from langchain_core.runnables import RunnableConfig
 
 
 class FakeMessagesListChatModel(BaseChatModel):
-    """Fake ChatModel for testing purposes."""
+    """Fake ``ChatModel`` for testing purposes."""
 
     responses: list[BaseMessage]
     """List of responses to **cycle** through in order."""
@@ -212,10 +212,11 @@ class GenericFakeChatModel(BaseChatModel):
     """Generic fake chat model that can be used to test the chat model interface.
 
     * Chat model should be usable in both sync and async tests
-    * Invokes on_llm_new_token to allow for testing of callback related code for new
+    * Invokes ``on_llm_new_token`` to allow for testing of callback related code for new
       tokens.
     * Includes logic to break messages into message chunk to facilitate testing of
       streaming.
+
     """
 
     messages: Iterator[Union[AIMessage, str]]
@@ -230,6 +231,7 @@ class GenericFakeChatModel(BaseChatModel):
     .. warning::
         Streaming is not implemented yet. We should try to implement it in the future by
         delegating to invoke and then breaking the resulting output into message chunks.
+
     """
 
     @override
@@ -351,6 +353,7 @@ class ParrotFakeChatModel(BaseChatModel):
     """Generic fake chat model that can be used to test the chat model interface.
 
     * Chat model should be usable in both sync and async tests
+
     """
 
     @override

langchain_core/language_models/llms.py

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

langchain_core/load/serializable.py

@@ -111,7 +111,7 @@ class Serializable(BaseModel, ABC):
 
     # 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

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
 
             {
@@ -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."""
@@ -311,7 +320,10 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):
         """Initialize tool calls from tool call chunks.
 
         Returns:
-            This ``AIMessageChunk``.
+            The values with tool calls initialized.
+
+        Raises:
+            ValueError: If the tool call chunks are malformed.
         """
         if not self.tool_call_chunks:
             if self.tool_calls:
@@ -522,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