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

langchain_core/callbacks/manager.py

@@ -28,8 +28,18 @@ from langchain_core.callbacks.base import (
     ToolManagerMixin,
 )
 from langchain_core.callbacks.stdout import StdOutCallbackHandler
+from langchain_core.globals import get_debug
 from langchain_core.messages import BaseMessage, get_buffer_string
+from langchain_core.tracers.context import (
+    _configure_hooks,
+    _get_trace_callbacks,
+    _get_tracer_project,
+    _tracing_v2_is_enabled,
+    tracing_v2_callback_var,
+)
+from langchain_core.tracers.langchain import LangChainTracer
 from langchain_core.tracers.schemas import Run
+from langchain_core.tracers.stdout import ConsoleCallbackHandler
 from langchain_core.utils.env import env_var_is_set
 
 if TYPE_CHECKING:
@@ -46,8 +56,6 @@ logger = logging.getLogger(__name__)
 
 
 def _get_debug() -> bool:
-    from langchain_core.globals import get_debug
-
     return get_debug()
 
 
@@ -84,24 +92,25 @@ def trace_as_chain_group(
         metadata (dict[str, Any], optional): The metadata to apply to all runs.
             Defaults to None.
 
-    .. note:
-        Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in LangSmith.
+    .. note::
+        Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in
+        LangSmith.
 
-    Returns:
-        CallbackManagerForChainGroup: The callback manager for the chain group.
+    Yields:
+        The callback manager for the chain group.
 
     Example:
         .. code-block:: python
 
             llm_input = "Foo"
-            with trace_as_chain_group("group_name", inputs={"input": llm_input}) as manager:
+            with trace_as_chain_group(
+                "group_name", inputs={"input": llm_input}
+            ) as manager:
                 # Use the callback manager for the chain group
                 res = llm.invoke(llm_input, {"callbacks": manager})
                 manager.on_chain_end({"output": res})
 
-    """  # noqa: E501
-    from langchain_core.tracers.context import _get_trace_callbacks
-
+    """
     cb = _get_trace_callbacks(
         project_name, example_id, callback_manager=callback_manager
     )
@@ -153,8 +162,8 @@ async def atrace_as_chain_group(
 
     Args:
         group_name (str): The name of the chain group.
-        callback_manager (AsyncCallbackManager, optional): The async callback manager to use,
-            which manages tracing and other callback behavior. Defaults to None.
+        callback_manager (AsyncCallbackManager, optional): The async callback manager
+            to use, which manages tracing and other callback behavior. Defaults to None.
         inputs (dict[str, Any], optional): The inputs to the chain group.
             Defaults to None.
         project_name (str, optional): The name of the project.
@@ -167,24 +176,25 @@ async def atrace_as_chain_group(
         metadata (dict[str, Any], optional): The metadata to apply to all runs.
             Defaults to None.
 
-    Returns:
-        AsyncCallbackManager: The async callback manager for the chain group.
+    Yields:
+        The async callback manager for the chain group.
 
-    .. note:
-        Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in LangSmith.
+    .. note::
+        Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in
+        LangSmith.
 
     Example:
         .. code-block:: python
 
             llm_input = "Foo"
-            async with atrace_as_chain_group("group_name", inputs={"input": llm_input}) as manager:
+            async with atrace_as_chain_group(
+                "group_name", inputs={"input": llm_input}
+            ) as manager:
                 # Use the async callback manager for the chain group
                 res = await llm.ainvoke(llm_input, {"callbacks": manager})
                 await manager.on_chain_end({"output": res})
 
-    """  # noqa: E501
-    from langchain_core.tracers.context import _get_trace_callbacks
-
+    """
     cb = _get_trace_callbacks(
         project_name, example_id, callback_manager=callback_manager
     )
@@ -513,15 +523,12 @@ class RunManager(BaseRunManager):
         self,
         text: str,
         **kwargs: Any,
-    ) -> Any:
+    ) -> None:
         """Run when a text is received.
 
         Args:
             text (str): The received text.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
         """
         if not self.handlers:
             return
@@ -601,16 +608,12 @@ class AsyncRunManager(BaseRunManager, ABC):
         self,
         text: str,
         **kwargs: Any,
-    ) -> Any:
+    ) -> None:
         """Run when a text is received.
 
         Args:
             text (str): The received text.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -908,16 +911,12 @@ class CallbackManagerForChainRun(ParentRunManager, ChainManagerMixin):
             **kwargs,
         )
 
-    def on_agent_action(self, action: AgentAction, **kwargs: Any) -> Any:
+    def on_agent_action(self, action: AgentAction, **kwargs: Any) -> None:
         """Run when agent action is received.
 
         Args:
             action (AgentAction): The agent action.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -932,16 +931,12 @@ class CallbackManagerForChainRun(ParentRunManager, ChainManagerMixin):
             **kwargs,
         )
 
-    def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> Any:
+    def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> None:
         """Run when agent finish is received.
 
         Args:
             finish (AgentFinish): The agent finish.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -1027,16 +1022,12 @@ class AsyncCallbackManagerForChainRun(AsyncParentRunManager, ChainManagerMixin):
             **kwargs,
         )
 
-    async def on_agent_action(self, action: AgentAction, **kwargs: Any) -> Any:
+    async def on_agent_action(self, action: AgentAction, **kwargs: Any) -> None:
         """Run when agent action is received.
 
         Args:
             action (AgentAction): The agent action.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -1051,16 +1042,12 @@ class AsyncCallbackManagerForChainRun(AsyncParentRunManager, ChainManagerMixin):
             **kwargs,
         )
 
-    async def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> Any:
+    async def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> None:
         """Run when agent finish is received.
 
         Args:
             finish (AgentFinish): The agent finish.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -1556,6 +1543,8 @@ class CallbackManager(BaseCallbackManager):
             parent_run_id (UUID, optional): The ID of the parent run. Defaults to None.
             **kwargs (Any): Additional keyword arguments.
 
+        Returns:
+            The callback manager for the retriever run.
         """
         if run_id is None:
             run_id = uuid.uuid4()
@@ -1602,6 +1591,9 @@ class CallbackManager(BaseCallbackManager):
             data: The data for the adhoc event.
             run_id: The ID of the run. Defaults to None.
 
+        Raises:
+            ValueError: If additional keyword arguments are passed.
+
         .. versionadded:: 0.2.14
 
         """
@@ -1704,8 +1696,8 @@ class CallbackManagerForChainGroup(CallbackManager):
         self.parent_run_manager = parent_run_manager
         self.ended = False
 
+    @override
     def copy(self) -> CallbackManagerForChainGroup:
-        """Copy the callback manager."""
         return self.__class__(
             handlers=self.handlers.copy(),
             inheritable_handlers=self.inheritable_handlers.copy(),
@@ -1734,11 +1726,18 @@ class CallbackManagerForChainGroup(CallbackManager):
 
             .. code-block:: python
 
-                from langchain_core.callbacks.manager import CallbackManager, trace_as_chain_group
+                from langchain_core.callbacks.manager import (
+                    CallbackManager,
+                    trace_as_chain_group,
+                )
                 from langchain_core.callbacks.stdout import StdOutCallbackHandler
 
-                manager = CallbackManager(handlers=[StdOutCallbackHandler()], tags=["tag2"])
-                with trace_as_chain_group("My Group Name", tags=["tag1"]) as group_manager:
+                manager = CallbackManager(
+                    handlers=[StdOutCallbackHandler()], tags=["tag2"]
+                )
+                with trace_as_chain_group(
+                    "My Group Name", tags=["tag1"]
+                ) as group_manager:
                     merged_manager = group_manager.merge(manager)
                     print(type(merged_manager))
                     # <class 'langchain_core.callbacks.manager.CallbackManagerForChainGroup'>
@@ -2086,6 +2085,9 @@ class AsyncCallbackManager(BaseCallbackManager):
             data: The data for the adhoc event.
             run_id: The ID of the run. Defaults to None.
 
+        Raises:
+            ValueError: If additional keyword arguments are passed.
+
         .. versionadded:: 0.2.14
         """
         if not self.handlers:
@@ -2236,7 +2238,7 @@ class AsyncCallbackManagerForChainGroup(AsyncCallbackManager):
         self.ended = False
 
     def copy(self) -> AsyncCallbackManagerForChainGroup:
-        """Copy the async callback manager."""
+        """Return a copy the async callback manager."""
         return self.__class__(
             handlers=self.handlers.copy(),
             inheritable_handlers=self.inheritable_handlers.copy(),
@@ -2258,18 +2260,25 @@ class AsyncCallbackManagerForChainGroup(AsyncCallbackManager):
         from the current object.
 
         Returns:
-            AsyncCallbackManagerForChainGroup: A copy of the current AsyncCallbackManagerForChainGroup
-                with the handlers, tags, etc. of the other callback manager merged in.
+            A copy of the current AsyncCallbackManagerForChainGroup
+            with the handlers, tags, etc. of the other callback manager merged in.
 
         Example: Merging two callback managers.
 
             .. code-block:: python
 
-                from langchain_core.callbacks.manager import CallbackManager, atrace_as_chain_group
+                from langchain_core.callbacks.manager import (
+                    CallbackManager,
+                    atrace_as_chain_group,
+                )
                 from langchain_core.callbacks.stdout import StdOutCallbackHandler
 
-                manager = CallbackManager(handlers=[StdOutCallbackHandler()], tags=["tag2"])
-                async with atrace_as_chain_group("My Group Name", tags=["tag1"]) as group_manager:
+                manager = CallbackManager(
+                    handlers=[StdOutCallbackHandler()], tags=["tag2"]
+                )
+                async with atrace_as_chain_group(
+                    "My Group Name", tags=["tag1"]
+                ) as group_manager:
                     merged_manager = group_manager.merge(manager)
                     print(type(merged_manager))
                     # <class 'langchain_core.callbacks.manager.AsyncCallbackManagerForChainGroup'>
@@ -2365,16 +2374,12 @@ def _configure(
         local_metadata (Optional[dict[str, Any]], optional): The local metadata.
             Defaults to None.
 
+    Raises:
+        RuntimeError: If `LANGCHAIN_TRACING` is set but `LANGCHAIN_TRACING_V2` is not.
+
     Returns:
         T: The configured callback manager.
     """
-    from langchain_core.tracers.context import (
-        _configure_hooks,
-        _get_tracer_project,
-        _tracing_v2_is_enabled,
-        tracing_v2_callback_var,
-    )
-
     tracing_context = get_tracing_context()
     tracing_metadata = tracing_context["metadata"]
     tracing_tags = tracing_context["tags"]
@@ -2451,9 +2456,6 @@ def _configure(
     tracer_project = _get_tracer_project()
     debug = _get_debug()
     if verbose or debug or tracing_v2_enabled_:
-        from langchain_core.tracers.langchain import LangChainTracer
-        from langchain_core.tracers.stdout import ConsoleCallbackHandler
-
         if verbose and not any(
             isinstance(handler, StdOutCallbackHandler)
             for handler in callback_manager.handlers
@@ -2537,6 +2539,10 @@ async def adispatch_custom_event(
               this is not enforced.
         config: Optional config object. Mirrors the async API but not strictly needed.
 
+    Raises:
+        RuntimeError: If there is no parent run ID available to associate
+            the event with.
+
     Example:
 
         .. code-block:: python
@@ -2618,7 +2624,8 @@ async def adispatch_custom_event(
     .. versionadded:: 0.2.15
 
     """
-    from langchain_core.runnables.config import (
+    # Import locally to prevent circular imports.
+    from langchain_core.runnables.config import (  # noqa: PLC0415
         ensure_config,
         get_async_callback_manager_for_config,
     )
@@ -2658,6 +2665,10 @@ def dispatch_custom_event(
               this is not enforced.
         config: Optional config object. Mirrors the async API but not strictly needed.
 
+    Raises:
+        RuntimeError: If there is no parent run ID available to associate
+            the event with.
+
     Example:
 
         .. code-block:: python
@@ -2689,7 +2700,8 @@ def dispatch_custom_event(
     .. versionadded:: 0.2.15
 
     """
-    from langchain_core.runnables.config import (
+    # Import locally to prevent circular imports.
+    from langchain_core.runnables.config import (  # noqa: PLC0415
         ensure_config,
         get_callback_manager_for_config,
     )

langchain_core/callbacks/usage.py

@@ -12,6 +12,7 @@ from langchain_core.callbacks import BaseCallbackHandler
 from langchain_core.messages import AIMessage
 from langchain_core.messages.ai import UsageMetadata, add_usage
 from langchain_core.outputs import ChatGeneration, LLMResult
+from langchain_core.tracers.context import register_configure_hook
 
 
 class UsageMetadataCallbackHandler(BaseCallbackHandler):
@@ -31,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,
@@ -101,6 +102,9 @@ def get_usage_metadata_callback(
         name (str): The name of the context variable. Defaults to
             ``'usage_metadata_callback'``.
 
+    Yields:
+        The usage metadata callback.
+
     Example:
         .. code-block:: python
 
@@ -115,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,
@@ -130,8 +134,6 @@ def get_usage_metadata_callback(
     .. versionadded:: 0.3.49
 
     """
-    from langchain_core.tracers.context import register_configure_hook
-
     usage_metadata_callback_var: ContextVar[Optional[UsageMetadataCallbackHandler]] = (
         ContextVar(name, default=None)
     )

langchain_core/chat_history.py

@@ -27,6 +27,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
@@ -64,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)
+                    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):
-                    with open(os.path.join(storage_path, session_id), "w") as f:
-                        f.write("[]")
+                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)
 
     """
 
@@ -109,9 +120,10 @@ 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:
@@ -187,8 +199,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 +207,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:

langchain_core/document_loaders/base.py

@@ -15,6 +15,13 @@ if TYPE_CHECKING:
     from langchain_core.documents import Document
     from langchain_core.documents.base import Blob
 
+try:
+    from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+    _HAS_TEXT_SPLITTERS = True
+except ImportError:
+    _HAS_TEXT_SPLITTERS = False
+
 
 class BaseLoader(ABC):  # noqa: B024
     """Interface for Document Loader.
@@ -28,11 +35,19 @@ class BaseLoader(ABC):  # noqa: B024
     # Sub-classes should not implement this method directly. Instead, they
     # should implement the lazy load method.
     def load(self) -> list[Document]:
-        """Load data into Document objects."""
+        """Load data into Document objects.
+
+        Returns:
+            the documents.
+        """
         return list(self.lazy_load())
 
     async def aload(self) -> list[Document]:
-        """Load data into Document objects."""
+        """Load data into Document objects.
+
+        Returns:
+            the documents.
+        """
         return [document async for document in self.alazy_load()]
 
     def load_and_split(
@@ -44,21 +59,23 @@ class BaseLoader(ABC):  # noqa: B024
 
         Args:
             text_splitter: TextSplitter instance to use for splitting documents.
-              Defaults to RecursiveCharacterTextSplitter.
+                Defaults to RecursiveCharacterTextSplitter.
+
+        Raises:
+            ImportError: If langchain-text-splitters is not installed
+                and no text_splitter is provided.
 
         Returns:
             List of Documents.
         """
         if text_splitter is None:
-            try:
-                from langchain_text_splitters import RecursiveCharacterTextSplitter
-            except ImportError as e:
+            if not _HAS_TEXT_SPLITTERS:
                 msg = (
                     "Unable to import from langchain_text_splitters. Please specify "
                     "text_splitter or install langchain_text_splitters with "
                     "`pip install -U langchain-text-splitters`."
                 )
-                raise ImportError(msg) from e
+                raise ImportError(msg)
 
             text_splitter_: TextSplitter = RecursiveCharacterTextSplitter()
         else:
@@ -69,14 +86,22 @@ class BaseLoader(ABC):  # noqa: B024
     # Attention: This method will be upgraded into an abstractmethod once it's
     #            implemented in all the existing subclasses.
     def lazy_load(self) -> Iterator[Document]:
-        """A lazy loader for Documents."""
+        """A lazy loader for Documents.
+
+        Yields:
+            the documents.
+        """
         if type(self).load != BaseLoader.load:
             return iter(self.load())
         msg = f"{self.__class__.__name__} does not implement lazy_load()"
         raise NotImplementedError(msg)
 
     async def alazy_load(self) -> AsyncIterator[Document]:
-        """A lazy loader for Documents."""
+        """A lazy loader for Documents.
+
+        Yields:
+            the documents.
+        """
         iterator = await run_in_executor(None, self.lazy_load)
         done = object()
         while True:

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": {...}, ...}), ...]
 
@@ -84,6 +84,9 @@ class LangSmithLoader(BaseLoader):
             client: LangSmith Client. If not provided will be initialized from below args.
             client_kwargs: Keyword args to pass to LangSmith client init. Should only be
                 specified if ``client`` isn't.
+
+        Raises:
+            ValueError: If both ``client`` and ``client_kwargs`` are provided.
         """  # noqa: E501
         if client and client_kwargs:
             raise ValueError