langchain-core 0.3.79__py3-none-any.whl → 1.0.0__py3-none-any.whl

langchain_core/callbacks/stdout.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any
 
 from typing_extensions import override
 
@@ -16,11 +16,11 @@ if TYPE_CHECKING:
 class StdOutCallbackHandler(BaseCallbackHandler):
     """Callback Handler that prints to std out."""
 
-    def __init__(self, color: Optional[str] = None) -> None:
+    def __init__(self, color: str | None = None) -> None:
         """Initialize callback handler.
 
         Args:
-            color: The color to use for the text. Defaults to None.
+            color: The color to use for the text.
         """
         self.color = color
 
@@ -31,9 +31,9 @@ class StdOutCallbackHandler(BaseCallbackHandler):
         """Print out that we are entering a chain.
 
         Args:
-            serialized (dict[str, Any]): The serialized chain.
-            inputs (dict[str, Any]): The inputs to the chain.
-            **kwargs (Any): Additional keyword arguments.
+            serialized: The serialized chain.
+            inputs: The inputs to the chain.
+            **kwargs: Additional keyword arguments.
         """
         if "name" in kwargs:
             name = kwargs["name"]
@@ -48,21 +48,21 @@ class StdOutCallbackHandler(BaseCallbackHandler):
         """Print out that we finished a chain.
 
         Args:
-            outputs (dict[str, Any]): The outputs of the chain.
-            **kwargs (Any): Additional keyword arguments.
+            outputs: The outputs of the chain.
+            **kwargs: Additional keyword arguments.
         """
         print("\n\033[1m> Finished chain.\033[0m")  # noqa: T201
 
     @override
     def on_agent_action(
-        self, action: AgentAction, color: Optional[str] = None, **kwargs: Any
+        self, action: AgentAction, color: str | None = None, **kwargs: Any
     ) -> Any:
         """Run on agent action.
 
         Args:
-            action (AgentAction): The agent action.
-            color (Optional[str]): The color to use for the text. Defaults to None.
-            **kwargs (Any): Additional keyword arguments.
+            action: The agent action.
+            color: The color to use for the text.
+            **kwargs: Additional keyword arguments.
         """
         print_text(action.log, color=color or self.color)
 
@@ -70,20 +70,19 @@ class StdOutCallbackHandler(BaseCallbackHandler):
     def on_tool_end(
         self,
         output: Any,
-        color: Optional[str] = None,
-        observation_prefix: Optional[str] = None,
-        llm_prefix: Optional[str] = None,
+        color: str | None = None,
+        observation_prefix: str | None = None,
+        llm_prefix: str | None = None,
         **kwargs: Any,
     ) -> None:
         """If not the final action, print out observation.
 
         Args:
-            output (Any): The output to print.
-            color (Optional[str]): The color to use for the text. Defaults to None.
-            observation_prefix (Optional[str]): The observation prefix.
-                Defaults to None.
-            llm_prefix (Optional[str]): The LLM prefix. Defaults to None.
-            **kwargs (Any): Additional keyword arguments.
+            output: The output to print.
+            color: The color to use for the text.
+            observation_prefix: The observation prefix.
+            llm_prefix: The LLM prefix.
+            **kwargs: Additional keyword arguments.
         """
         output = str(output)
         if observation_prefix is not None:
@@ -96,29 +95,29 @@ class StdOutCallbackHandler(BaseCallbackHandler):
     def on_text(
         self,
         text: str,
-        color: Optional[str] = None,
+        color: str | None = None,
         end: str = "",
         **kwargs: Any,
     ) -> None:
         """Run when the agent ends.
 
         Args:
-            text (str): The text to print.
-            color (Optional[str]): The color to use for the text. Defaults to None.
-            end (str): The end character to use. Defaults to "".
-            **kwargs (Any): Additional keyword arguments.
+            text: The text to print.
+            color: The color to use for the text.
+            end: The end character to use.
+            **kwargs: Additional keyword arguments.
         """
         print_text(text, color=color or self.color, end=end)
 
     @override
     def on_agent_finish(
-        self, finish: AgentFinish, color: Optional[str] = None, **kwargs: Any
+        self, finish: AgentFinish, color: str | None = None, **kwargs: Any
     ) -> None:
         """Run on the agent end.
 
         Args:
-            finish (AgentFinish): The agent finish.
-            color (Optional[str]): The color to use for the text. Defaults to None.
-            **kwargs (Any): Additional keyword arguments.
+            finish: The agent finish.
+            color: The color to use for the text.
+            **kwargs: Additional keyword arguments.
         """
         print_text(finish.log, color=color or self.color, end="\n")

langchain_core/callbacks/streaming_stdout.py

@@ -24,9 +24,9 @@ class StreamingStdOutCallbackHandler(BaseCallbackHandler):
         """Run when LLM starts running.
 
         Args:
-            serialized (dict[str, Any]): The serialized LLM.
-            prompts (list[str]): The prompts to run.
-            **kwargs (Any): Additional keyword arguments.
+            serialized: The serialized LLM.
+            prompts: The prompts to run.
+            **kwargs: Additional keyword arguments.
         """
 
     def on_chat_model_start(
@@ -38,9 +38,9 @@ class StreamingStdOutCallbackHandler(BaseCallbackHandler):
         """Run when LLM starts running.
 
         Args:
-            serialized (dict[str, Any]): The serialized LLM.
-            messages (list[list[BaseMessage]]): The messages to run.
-            **kwargs (Any): Additional keyword arguments.
+            serialized: The serialized LLM.
+            messages: The messages to run.
+            **kwargs: Additional keyword arguments.
         """
 
     @override
@@ -48,8 +48,8 @@ class StreamingStdOutCallbackHandler(BaseCallbackHandler):
         """Run on new LLM token. Only available when streaming is enabled.
 
         Args:
-            token (str): The new token.
-            **kwargs (Any): Additional keyword arguments.
+            token: The new token.
+            **kwargs: Additional keyword arguments.
         """
         sys.stdout.write(token)
         sys.stdout.flush()
@@ -58,16 +58,16 @@ class StreamingStdOutCallbackHandler(BaseCallbackHandler):
         """Run when LLM ends running.
 
         Args:
-            response (LLMResult): The response from the LLM.
-            **kwargs (Any): Additional keyword arguments.
+            response: The response from the LLM.
+            **kwargs: Additional keyword arguments.
         """
 
     def on_llm_error(self, error: BaseException, **kwargs: Any) -> None:
         """Run when LLM errors.
 
         Args:
-            error (BaseException): The error that occurred.
-            **kwargs (Any): Additional keyword arguments.
+            error: The error that occurred.
+            **kwargs: Additional keyword arguments.
         """
 
     def on_chain_start(
@@ -76,25 +76,25 @@ class StreamingStdOutCallbackHandler(BaseCallbackHandler):
         """Run when a chain starts running.
 
         Args:
-            serialized (dict[str, Any]): The serialized chain.
-            inputs (dict[str, Any]): The inputs to the chain.
-            **kwargs (Any): Additional keyword arguments.
+            serialized: The serialized chain.
+            inputs: The inputs to the chain.
+            **kwargs: Additional keyword arguments.
         """
 
     def on_chain_end(self, outputs: dict[str, Any], **kwargs: Any) -> None:
         """Run when a chain ends running.
 
         Args:
-            outputs (dict[str, Any]): The outputs of the chain.
-            **kwargs (Any): Additional keyword arguments.
+            outputs: The outputs of the chain.
+            **kwargs: Additional keyword arguments.
         """
 
     def on_chain_error(self, error: BaseException, **kwargs: Any) -> None:
         """Run when chain errors.
 
         Args:
-            error (BaseException): The error that occurred.
-            **kwargs (Any): Additional keyword arguments.
+            error: The error that occurred.
+            **kwargs: Additional keyword arguments.
         """
 
     def on_tool_start(
@@ -103,47 +103,47 @@ class StreamingStdOutCallbackHandler(BaseCallbackHandler):
         """Run when the tool starts running.
 
         Args:
-            serialized (dict[str, Any]): The serialized tool.
-            input_str (str): The input string.
-            **kwargs (Any): Additional keyword arguments.
+            serialized: The serialized tool.
+            input_str: The input string.
+            **kwargs: Additional keyword arguments.
         """
 
     def on_agent_action(self, action: AgentAction, **kwargs: Any) -> Any:
         """Run on agent action.
 
         Args:
-            action (AgentAction): The agent action.
-            **kwargs (Any): Additional keyword arguments.
+            action: The agent action.
+            **kwargs: Additional keyword arguments.
         """
 
     def on_tool_end(self, output: Any, **kwargs: Any) -> None:
         """Run when tool ends running.
 
         Args:
-            output (Any): The output of the tool.
-            **kwargs (Any): Additional keyword arguments.
+            output: The output of the tool.
+            **kwargs: Additional keyword arguments.
         """
 
     def on_tool_error(self, error: BaseException, **kwargs: Any) -> None:
         """Run when tool errors.
 
         Args:
-            error (BaseException): The error that occurred.
-            **kwargs (Any): Additional keyword arguments.
+            error: The error that occurred.
+            **kwargs: Additional keyword arguments.
         """
 
     def on_text(self, text: str, **kwargs: Any) -> None:
         """Run on an arbitrary text.
 
         Args:
-            text (str): The text to print.
-            **kwargs (Any): Additional keyword arguments.
+            text: The text to print.
+            **kwargs: Additional keyword arguments.
         """
 
     def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> None:
         """Run on the agent end.
 
         Args:
-            finish (AgentFinish): The agent finish.
-            **kwargs (Any): Additional keyword arguments.
+            finish: The agent finish.
+            **kwargs: Additional keyword arguments.
         """

langchain_core/callbacks/usage.py

@@ -4,7 +4,7 @@ import threading
 from collections.abc import Generator
 from contextlib import contextmanager
 from contextvars import ContextVar
-from typing import Any, Optional
+from typing import Any
 
 from typing_extensions import override
 
@@ -19,32 +19,31 @@ class UsageMetadataCallbackHandler(BaseCallbackHandler):
     """Callback Handler that tracks AIMessage.usage_metadata.
 
     Example:
-        .. code-block:: python
-
-            from langchain.chat_models import init_chat_model
-            from langchain_core.callbacks import UsageMetadataCallbackHandler
-
-            llm_1 = init_chat_model(model="openai:gpt-4o-mini")
-            llm_2 = init_chat_model(model="anthropic:claude-3-5-haiku-latest")
-
-            callback = UsageMetadataCallbackHandler()
-            result_1 = llm_1.invoke("Hello", config={"callbacks": [callback]})
-            result_2 = llm_2.invoke("Hello", config={"callbacks": [callback]})
-            callback.usage_metadata
-
-        .. code-block::
-
-            {'gpt-4o-mini-2024-07-18': {'input_tokens': 8,
-              'output_tokens': 10,
-              'total_tokens': 18,
-              'input_token_details': {'audio': 0, 'cache_read': 0},
-              'output_token_details': {'audio': 0, 'reasoning': 0}},
-             'claude-3-5-haiku-20241022': {'input_tokens': 8,
-              'output_tokens': 21,
-              'total_tokens': 29,
-              'input_token_details': {'cache_read': 0, 'cache_creation': 0}}}
-
-    .. versionadded:: 0.3.49
+        ```python
+        from langchain.chat_models import init_chat_model
+        from langchain_core.callbacks import UsageMetadataCallbackHandler
+
+        llm_1 = init_chat_model(model="openai:gpt-4o-mini")
+        llm_2 = init_chat_model(model="anthropic:claude-3-5-haiku-latest")
+
+        callback = UsageMetadataCallbackHandler()
+        result_1 = llm_1.invoke("Hello", config={"callbacks": [callback]})
+        result_2 = llm_2.invoke("Hello", config={"callbacks": [callback]})
+        callback.usage_metadata
+        ```
+        ```txt
+        {'gpt-4o-mini-2024-07-18': {'input_tokens': 8,
+          'output_tokens': 10,
+          'total_tokens': 18,
+          'input_token_details': {'audio': 0, 'cache_read': 0},
+          'output_token_details': {'audio': 0, 'reasoning': 0}},
+         'claude-3-5-haiku-20241022': {'input_tokens': 8,
+          'output_tokens': 21,
+          'total_tokens': 29,
+          'input_token_details': {'cache_read': 0, 'cache_creation': 0}}}
+        ```
+
+    !!! version-added "Added in version 0.3.49"
 
     """
 
@@ -96,45 +95,49 @@ def get_usage_metadata_callback(
     """Get usage metadata callback.
 
     Get context manager for tracking usage metadata across chat model calls using
-    ``AIMessage.usage_metadata``.
+    `AIMessage.usage_metadata`.
 
     Args:
-        name (str): The name of the context variable. Defaults to
-            ``'usage_metadata_callback'``.
+        name: The name of the context variable.
 
     Yields:
         The usage metadata callback.
 
     Example:
-        .. code-block:: python
-
-            from langchain.chat_models import init_chat_model
-            from langchain_core.callbacks import get_usage_metadata_callback
-
-            llm_1 = init_chat_model(model="openai:gpt-4o-mini")
-            llm_2 = init_chat_model(model="anthropic:claude-3-5-haiku-latest")
-
-            with get_usage_metadata_callback() as cb:
-                llm_1.invoke("Hello")
-                llm_2.invoke("Hello")
-                print(cb.usage_metadata)
-
-        .. code-block::
-
-            {'gpt-4o-mini-2024-07-18': {'input_tokens': 8,
-              'output_tokens': 10,
-              'total_tokens': 18,
-              'input_token_details': {'audio': 0, 'cache_read': 0},
-              'output_token_details': {'audio': 0, 'reasoning': 0}},
-             'claude-3-5-haiku-20241022': {'input_tokens': 8,
-              'output_tokens': 21,
-              'total_tokens': 29,
-              'input_token_details': {'cache_read': 0, 'cache_creation': 0}}}
-
-    .. versionadded:: 0.3.49
+        ```python
+        from langchain.chat_models import init_chat_model
+        from langchain_core.callbacks import get_usage_metadata_callback
+
+        llm_1 = init_chat_model(model="openai:gpt-4o-mini")
+        llm_2 = init_chat_model(model="anthropic:claude-3-5-haiku-latest")
+
+        with get_usage_metadata_callback() as cb:
+            llm_1.invoke("Hello")
+            llm_2.invoke("Hello")
+            print(cb.usage_metadata)
+        ```
+        ```txt
+        {
+            "gpt-4o-mini-2024-07-18": {
+                "input_tokens": 8,
+                "output_tokens": 10,
+                "total_tokens": 18,
+                "input_token_details": {"audio": 0, "cache_read": 0},
+                "output_token_details": {"audio": 0, "reasoning": 0},
+            },
+            "claude-3-5-haiku-20241022": {
+                "input_tokens": 8,
+                "output_tokens": 21,
+                "total_tokens": 29,
+                "input_token_details": {"cache_read": 0, "cache_creation": 0},
+            },
+        }
+        ```
+
+    !!! version-added "Added in version 0.3.49"
 
     """
-    usage_metadata_callback_var: ContextVar[Optional[UsageMetadataCallbackHandler]] = (
+    usage_metadata_callback_var: ContextVar[UsageMetadataCallbackHandler | None] = (
         ContextVar(name, default=None)
     )
     register_configure_hook(usage_metadata_callback_var, inheritable=True)

langchain_core/chat_history.py

@@ -1,23 +1,9 @@
-"""**Chat message history** stores a history of the message interactions in a chat.
-
-**Class hierarchy:**
-
-.. code-block::
-
-    BaseChatMessageHistory --> <name>ChatMessageHistory  # Examples: FileChatMessageHistory, PostgresChatMessageHistory
-
-**Main helpers:**
-
-.. code-block::
-
-    AIMessage, HumanMessage, BaseMessage
-
-"""  # noqa: E501
+"""**Chat message history** stores a history of the message interactions in a chat."""
 
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Union
+from typing import TYPE_CHECKING
 
 from pydantic import BaseModel, Field
 
@@ -63,46 +49,45 @@ class BaseChatMessageHistory(ABC):
 
     Example: Shows a default implementation.
 
-        .. 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) -> 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]
-                    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)
-
+        ```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) -> 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]
+                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)
+        ```
     """
 
     messages: list[BaseMessage]
@@ -126,11 +111,11 @@ class BaseChatMessageHistory(ABC):
         """
         return await run_in_executor(None, lambda: self.messages)
 
-    def add_user_message(self, message: Union[HumanMessage, str]) -> None:
+    def add_user_message(self, message: HumanMessage | str) -> None:
         """Convenience method for adding a human message string to the store.
 
-        .. note::
-            This is a convenience method. Code should favor the bulk ``add_messages``
+        !!! note
+            This is a convenience method. Code should favor the bulk `add_messages`
             interface instead to save on round-trips to the persistence layer.
 
         This method may be deprecated in a future release.
@@ -143,11 +128,11 @@ class BaseChatMessageHistory(ABC):
         else:
             self.add_message(HumanMessage(content=message))
 
-    def add_ai_message(self, message: Union[AIMessage, str]) -> None:
+    def add_ai_message(self, message: AIMessage | str) -> None:
         """Convenience method for adding an AI message string to the store.
 
-        .. note::
-            This is a convenience method. Code should favor the bulk ``add_messages``
+        !!! note
+            This is a convenience method. Code should favor the bulk `add_messages`
             interface instead to save on round-trips to the persistence layer.
 
         This method may be deprecated in a future release.
@@ -168,7 +153,7 @@ class BaseChatMessageHistory(ABC):
 
         Raises:
             NotImplementedError: If the sub-class has not implemented an efficient
-                add_messages method.
+                `add_messages` method.
         """
         if type(self).add_messages != BaseChatMessageHistory.add_messages:
             # This means that the sub-class has implemented an efficient add_messages