langchain-core 0.4.0.dev0__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

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import sys
-from typing import TYPE_CHECKING, Any, Union
+from typing import TYPE_CHECKING, Any
 
 from typing_extensions import override
 
@@ -13,7 +13,6 @@ if TYPE_CHECKING:
     from langchain_core.agents import AgentAction, AgentFinish
     from langchain_core.messages import BaseMessage
     from langchain_core.outputs import LLMResult
-    from langchain_core.v1.messages import AIMessage, MessageV1
 
 
 class StreamingStdOutCallbackHandler(BaseCallbackHandler):
@@ -25,23 +24,23 @@ 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(
         self,
         serialized: dict[str, Any],
-        messages: Union[list[list[BaseMessage]], list[MessageV1]],
+        messages: list[list[BaseMessage]],
         **kwargs: Any,
     ) -> None:
         """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
@@ -49,26 +48,26 @@ 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()
 
-    def on_llm_end(self, response: Union[LLMResult, AIMessage], **kwargs: Any) -> None:
+    def on_llm_end(self, response: LLMResult, **kwargs: Any) -> None:
         """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(
@@ -77,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(
@@ -104,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,48 +4,46 @@ import threading
 from collections.abc import Generator
 from contextlib import contextmanager
 from contextvars import ContextVar
-from typing import Any, Optional, Union
+from typing import Any
 
 from typing_extensions import override
 
 from langchain_core.callbacks import BaseCallbackHandler
 from langchain_core.messages import AIMessage
 from langchain_core.messages.ai import UsageMetadata, add_usage
-from langchain_core.messages.utils import convert_from_v1_message
 from langchain_core.outputs import ChatGeneration, LLMResult
-from langchain_core.v1.messages import AIMessage as AIMessageV1
+from langchain_core.tracers.context import register_configure_hook
 
 
 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:: none
-
-            {'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"
 
     """
 
@@ -60,17 +58,9 @@ class UsageMetadataCallbackHandler(BaseCallbackHandler):
         return str(self.usage_metadata)
 
     @override
-    def on_llm_end(
-        self, response: Union[LLMResult, AIMessageV1], **kwargs: Any
-    ) -> None:
+    def on_llm_end(self, response: LLMResult, **kwargs: Any) -> None:
         """Collect token usage."""
         # Check for usage_metadata (langchain-core >= 0.2.2)
-        if isinstance(response, AIMessageV1):
-            response = LLMResult(
-                generations=[
-                    [ChatGeneration(message=convert_from_v1_message(response))]
-                ]
-            )
         try:
             generation = response.generations[0][0]
         except IndexError:
@@ -105,44 +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'``.
-
-    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)
+        name: The name of the context variable.
 
-        .. code-block:: none
+    Yields:
+        The usage metadata callback.
 
-            {'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
+    Example:
+        ```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"
 
     """
-    from langchain_core.tracers.context import register_configure_hook
-
-    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
 
@@ -27,6 +13,7 @@ from langchain_core.messages import (
     HumanMessage,
     get_buffer_string,
 )
+from langchain_core.runnables.config import run_in_executor
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -62,36 +49,45 @@ class BaseChatMessageHistory(ABC):
 
     Example: Shows a default implementation.
 
-        .. code-block:: python
+        ```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
+        class FileChatMessageHistory(BaseChatMessageHistory):
+            storage_path: str
+            session_id: str
 
-                @property
-                def messages(self):
+            @property
+            def messages(self) -> list[BaseMessage]:
+                try:
                     with open(
-                        os.path.join(storage_path, session_id),
+                        os.path.join(self.storage_path, self.session_id),
                         "r",
                         encoding="utf-8",
                     ) as f:
-                        messages = json.loads(f.read())
-                    return messages_from_dict(messages)
-
-                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("[]")
-
+                        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]
@@ -109,17 +105,18 @@ class BaseChatMessageHistory(ABC):
 
         In general, fetching messages may involve IO to the underlying
         persistence layer.
-        """
-        from langchain_core.runnables.config import run_in_executor
 
+        Returns:
+            The messages.
+        """
         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.
 
-        Please note that this is a convenience method. Code should favor the
-        bulk add_messages interface instead to save on round-trips to the underlying
-        persistence layer.
+        !!! 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.
 
@@ -131,12 +128,12 @@ 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.
 
-        Please note that this is a convenience method. Code should favor the bulk
-        add_messages interface instead to save on round-trips to the underlying
-        persistence layer.
+        !!! 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.
 
@@ -156,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
@@ -187,8 +184,6 @@ class BaseChatMessageHistory(ABC):
         Args:
             messages: A sequence of BaseMessage objects to store.
         """
-        from langchain_core.runnables.config import run_in_executor
-
         await run_in_executor(None, self.add_messages, messages)
 
     @abstractmethod
@@ -197,8 +192,6 @@ class BaseChatMessageHistory(ABC):
 
     async def aclear(self) -> None:
         """Async remove all messages from the store."""
-        from langchain_core.runnables.config import run_in_executor
-
         await run_in_executor(None, self.clear)
 
     def __str__(self) -> str: