langchain-core 1.0.0a1__py3-none-any.whl → 1.0.0a3__py3-none-any.whl

langchain_core/tracers/event_stream.py

@@ -9,21 +9,23 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Optional,
+    TypedDict,
     TypeVar,
     Union,
     cast,
 )
 from uuid import UUID, uuid4
 
-from typing_extensions import NotRequired, TypedDict, override
+from typing_extensions import NotRequired, override
 
-from langchain_core.callbacks.base import AsyncCallbackHandler
+from langchain_core.callbacks.base import AsyncCallbackHandler, BaseCallbackManager
 from langchain_core.messages import AIMessageChunk, BaseMessage, BaseMessageChunk
 from langchain_core.outputs import (
     ChatGenerationChunk,
     GenerationChunk,
     LLMResult,
 )
+from langchain_core.runnables import ensure_config
 from langchain_core.runnables.schema import (
     CustomStreamEvent,
     EventData,
@@ -36,6 +38,11 @@ from langchain_core.runnables.utils import (
     _RootEventFilter,
 )
 from langchain_core.tracers._streaming import _StreamingCallbackHandler
+from langchain_core.tracers.log_stream import (
+    LogStreamCallbackHandler,
+    RunLog,
+    _astream_log_implementation,
+)
 from langchain_core.tracers.memory_stream import _MemoryStream
 from langchain_core.utils.aiter import aclosing, py_anext
 
@@ -53,22 +60,20 @@ class RunInfo(TypedDict):
     """Information about a run.
 
     This is used to keep track of the metadata associated with a run.
-
-    Parameters:
-        name: The name of the run.
-        tags: The tags associated with the run.
-        metadata: The metadata associated with the run.
-        run_type: The type of the run.
-        inputs: The inputs to the run.
-        parent_run_id: The ID of the parent run.
     """
 
     name: str
+    """The name of the run."""
     tags: list[str]
+    """The tags associated with the run."""
     metadata: dict[str, Any]
+    """The metadata associated with the run."""
     run_type: str
+    """The type of the run."""
     inputs: NotRequired[Any]
+    """The inputs to the run."""
     parent_run_id: Optional[UUID]
+    """The ID of the parent run."""
 
 
 def _assign_name(name: Optional[str], serialized: Optional[dict[str, Any]]) -> str:
@@ -155,7 +160,11 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
             self.send_stream.send_nowait(event)
 
     def __aiter__(self) -> AsyncIterator[Any]:
-        """Iterate over the receive stream."""
+        """Iterate over the receive stream.
+
+        Returns:
+            An async iterator over the receive stream.
+        """
         return self.receive_stream.__aiter__()
 
     async def tap_output_aiter(
@@ -215,7 +224,7 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
                 yield chunk
 
     def tap_output_iter(self, run_id: UUID, output: Iterator[T]) -> Iterator[T]:
-        """Tap the output aiter.
+        """Tap the output iter.
 
         Args:
             run_id: The ID of the run.
@@ -306,7 +315,7 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
         name: Optional[str] = None,
         **kwargs: Any,
     ) -> None:
-        """Start a trace for an LLM run."""
+        """Start a trace for a chat model run."""
         name_ = _assign_name(name, serialized)
         run_type = "chat_model"
 
@@ -348,7 +357,7 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
         name: Optional[str] = None,
         **kwargs: Any,
     ) -> None:
-        """Start a trace for an LLM run."""
+        """Start a trace for a (non-chat model) LLM run."""
         name_ = _assign_name(name, serialized)
         run_type = "llm"
 
@@ -412,7 +421,10 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
         parent_run_id: Optional[UUID] = 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).
+        """
         run_info = self.run_map.get(run_id)
         chunk_: Union[GenerationChunk, BaseMessageChunk]
 
@@ -458,9 +470,15 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
     async def on_llm_end(
         self, response: LLMResult, *, run_id: UUID, **kwargs: Any
     ) -> None:
-        """End a trace for an LLM run."""
+        """End a trace for a model run.
+
+        For both chat models and non-chat models (legacy LLMs).
+
+        Raises:
+            ValueError: If the run type is not ``'llm'`` or ``'chat_model'``.
+        """
         run_info = self.run_map.pop(run_id)
-        inputs_ = run_info["inputs"]
+        inputs_ = run_info.get("inputs")
 
         generations: Union[list[list[GenerationChunk]], list[list[ChatGenerationChunk]]]
         output: Union[dict, BaseMessage] = {}
@@ -592,6 +610,28 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
             run_type,
         )
 
+    def _get_tool_run_info_with_inputs(self, run_id: UUID) -> tuple[RunInfo, Any]:
+        """Get run info for a tool and extract inputs, with validation.
+
+        Args:
+            run_id: The run ID of the tool.
+
+        Returns:
+            A tuple of (run_info, inputs).
+
+        Raises:
+            AssertionError: If the run ID is a tool call and does not have inputs.
+        """
+        run_info = self.run_map.pop(run_id)
+        if "inputs" not in run_info:
+            msg = (
+                f"Run ID {run_id} is a tool call and is expected to have "
+                f"inputs associated with it."
+            )
+            raise AssertionError(msg)
+        inputs = run_info["inputs"]
+        return run_info, inputs
+
     @override
     async def on_tool_start(
         self,
@@ -634,17 +674,43 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
             "tool",
         )
 
+    @override
+    async def on_tool_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[list[str]] = None,
+        **kwargs: Any,
+    ) -> None:
+        """Run when tool errors."""
+        run_info, inputs = self._get_tool_run_info_with_inputs(run_id)
+
+        self._send(
+            {
+                "event": "on_tool_error",
+                "data": {
+                    "error": error,
+                    "input": inputs,
+                },
+                "run_id": str(run_id),
+                "name": run_info["name"],
+                "tags": run_info["tags"],
+                "metadata": run_info["metadata"],
+                "parent_ids": self._get_parent_ids(run_id),
+            },
+            "tool",
+        )
+
     @override
     async def on_tool_end(self, output: Any, *, run_id: UUID, **kwargs: Any) -> None:
-        """End a trace for a tool run."""
-        run_info = self.run_map.pop(run_id)
-        if "inputs" not in run_info:
-            msg = (
-                f"Run ID {run_id} is a tool call and is expected to have "
-                f"inputs associated with it."
-            )
-            raise AssertionError(msg)
-        inputs = run_info["inputs"]
+        """End a trace for a tool run.
+
+        Raises:
+            AssertionError: If the run ID is a tool call and does not have inputs
+        """
+        run_info, inputs = self._get_tool_run_info_with_inputs(run_id)
 
         self._send(
             {
@@ -718,7 +784,7 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
                 "event": "on_retriever_end",
                 "data": {
                     "output": documents,
-                    "input": run_info["inputs"],
+                    "input": run_info.get("inputs"),
                 },
                 "run_id": str(run_id),
                 "name": run_info["name"],
@@ -730,11 +796,11 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
         )
 
     def __deepcopy__(self, memo: dict) -> _AstreamEventsCallbackHandler:
-        """Deepcopy the tracer."""
+        """Return self."""
         return self
 
     def __copy__(self) -> _AstreamEventsCallbackHandler:
-        """Copy the tracer."""
+        """Return self."""
         return self
 
 
@@ -751,14 +817,6 @@ async def _astream_events_implementation_v1(
     exclude_tags: Optional[Sequence[str]] = None,
     **kwargs: Any,
 ) -> AsyncIterator[StandardStreamEvent]:
-    from langchain_core.runnables import ensure_config
-    from langchain_core.runnables.utils import _RootEventFilter
-    from langchain_core.tracers.log_stream import (
-        LogStreamCallbackHandler,
-        RunLog,
-        _astream_log_implementation,
-    )
-
     stream = LogStreamCallbackHandler(
         auto_close=False,
         include_names=include_names,
@@ -838,12 +896,12 @@ async def _astream_events_implementation_v1(
                 # Usually they will NOT be available for components that operate
                 # on streams, since those components stream the input and
                 # don't know its final value until the end of the stream.
-                inputs = log_entry["inputs"]
+                inputs = log_entry.get("inputs")
                 if inputs is not None:
                     data["input"] = inputs
 
             if event_type == "end":
-                inputs = log_entry["inputs"]
+                inputs = log_entry.get("inputs")
                 if inputs is not None:
                     data["input"] = inputs
 
@@ -936,9 +994,6 @@ async def _astream_events_implementation_v2(
     **kwargs: Any,
 ) -> AsyncIterator[StandardStreamEvent]:
     """Implementation of the astream events API for V2 runnables."""
-    from langchain_core.callbacks.base import BaseCallbackManager
-    from langchain_core.runnables import ensure_config
-
     event_streamer = _AstreamEventsCallbackHandler(
         include_names=include_names,
         include_types=include_types,

langchain_core/tracers/langchain.py

@@ -8,7 +8,7 @@ from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any, Optional, Union
 from uuid import UUID
 
-from langsmith import Client
+from langsmith import Client, get_tracing_context
 from langsmith import run_trees as rt
 from langsmith import utils as ls_utils
 from tenacity import (
@@ -53,7 +53,11 @@ def wait_for_all_tracers() -> None:
 
 
 def get_client() -> Client:
-    """Get the client."""
+    """Get the client.
+
+    Returns:
+        The LangSmith client.
+    """
     return rt.get_cached_client()
 
 
@@ -109,6 +113,8 @@ class LangChainTracer(BaseTracer):
         super()._start_trace(run)
         if run.ls_client is None:
             run.ls_client = self.client
+        if get_tracing_context().get("enabled") is False:
+            run.extra["__disabled"] = True
 
     def on_chat_model_start(
         self,
@@ -201,6 +207,8 @@ class LangChainTracer(BaseTracer):
 
     def _persist_run_single(self, run: Run) -> None:
         """Persist a run."""
+        if run.extra.get("__disabled"):
+            return
         try:
             run.extra["runtime"] = get_runtime_environment()
             run.tags = self._get_tags(run)
@@ -214,6 +222,8 @@ class LangChainTracer(BaseTracer):
 
     def _update_run_single(self, run: Run) -> None:
         """Update a run."""
+        if run.extra.get("__disabled"):
+            return
         try:
             run.patch(exclude_inputs=run.extra.get("inputs_is_truthy", False))
         except Exception as e:
@@ -235,7 +245,6 @@ class LangChainTracer(BaseTracer):
         chunk: Optional[Union[GenerationChunk, ChatGenerationChunk]] = None,
         parent_run_id: Optional[UUID] = None,
     ) -> Run:
-        """Append token event to LLM run and return the run."""
         run_id_str = str(run_id)
         if run_id_str not in self.run_has_token_event_map:
             self.run_has_token_event_map[run_id_str] = True

langchain_core/tracers/langchain_v1.py

@@ -7,7 +7,11 @@ from typing import Any
 
 
 def get_headers(*args: Any, **kwargs: Any) -> Any:  # noqa: ARG001
-    """Throw an error because this has been replaced by get_headers."""
+    """Throw an error because this has been replaced by get_headers.
+
+    Raises:
+        RuntimeError: Always, because this function is deprecated.
+    """
     msg = (
         "get_headers for LangChainTracerV1 is no longer supported. "
         "Please use LangChainTracer instead."
@@ -16,7 +20,11 @@ def get_headers(*args: Any, **kwargs: Any) -> Any:  # noqa: ARG001
 
 
 def LangChainTracerV1(*args: Any, **kwargs: Any) -> Any:  # noqa: N802,ARG001
-    """Throw an error because this has been replaced by LangChainTracer."""
+    """Throw an error because this has been replaced by ``LangChainTracer``.
+
+    Raises:
+        RuntimeError: Always, because this class is deprecated.
+    """
     msg = (
         "LangChainTracerV1 is no longer supported. Please use LangChainTracer instead."
     )

langchain_core/tracers/log_stream.py

@@ -7,6 +7,7 @@ import contextlib
 import copy
 import threading
 from collections import defaultdict
+from pprint import pformat
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -20,10 +21,11 @@ from typing import (
 import jsonpatch  # type: ignore[import-untyped]
 from typing_extensions import NotRequired, TypedDict, override
 
+from langchain_core.callbacks.base import BaseCallbackManager
 from langchain_core.load import dumps
 from langchain_core.load.load import load
 from langchain_core.outputs import ChatGenerationChunk, GenerationChunk
-from langchain_core.runnables import Runnable, RunnableConfig, ensure_config
+from langchain_core.runnables import RunnableConfig, ensure_config
 from langchain_core.tracers._streaming import _StreamingCallbackHandler
 from langchain_core.tracers.base import BaseTracer
 from langchain_core.tracers.memory_stream import _MemoryStream
@@ -32,6 +34,7 @@ if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Iterator, Sequence
     from uuid import UUID
 
+    from langchain_core.runnables import Runnable
     from langchain_core.runnables.utils import Input, Output
     from langchain_core.tracers.schemas import Run
 
@@ -110,7 +113,17 @@ class RunLogPatch:
         self.ops = list(ops)
 
     def __add__(self, other: Union[RunLogPatch, Any]) -> RunLog:
-        """Combine two RunLogPatch instances."""
+        """Combine two ``RunLogPatch`` instances.
+
+        Args:
+            other: The other ``RunLogPatch`` to combine with.
+
+        Raises:
+            TypeError: If the other object is not a ``RunLogPatch``.
+
+        Returns:
+            A new ``RunLog`` representing the combination of the two.
+        """
         if type(other) is RunLogPatch:
             ops = self.ops + other.ops
             state = jsonpatch.apply_patch(None, copy.deepcopy(ops))
@@ -121,8 +134,6 @@ class RunLogPatch:
 
     @override
     def __repr__(self) -> str:
-        from pprint import pformat
-
         # 1:-1 to get rid of the [] around the list
         return f"RunLogPatch({pformat(self.ops)[1:-1]})"
 
@@ -150,7 +161,17 @@ class RunLog(RunLogPatch):
         self.state = state
 
     def __add__(self, other: Union[RunLogPatch, Any]) -> RunLog:
-        """Combine two RunLogs."""
+        """Combine two ``RunLog``s.
+
+        Args:
+            other: The other ``RunLog`` or ``RunLogPatch`` to combine with.
+
+        Raises:
+            TypeError: If the other object is not a ``RunLog`` or ``RunLogPatch``.
+
+        Returns:
+            A new ``RunLog`` representing the combination of the two.
+        """
         if type(other) is RunLogPatch:
             ops = self.ops + other.ops
             state = jsonpatch.apply_patch(self.state, other.ops)
@@ -161,13 +182,18 @@ class RunLog(RunLogPatch):
 
     @override
     def __repr__(self) -> str:
-        from pprint import pformat
-
         return f"RunLog({pformat(self.state)})"
 
     @override
     def __eq__(self, other: object) -> bool:
-        """Check if two RunLogs are equal."""
+        """Check if two ``RunLog``s are equal.
+
+        Args:
+            other: The other ``RunLog`` to compare to.
+
+        Returns:
+            True if the ``RunLog``s are equal, False otherwise.
+        """
         # First compare that the state is the same
         if not isinstance(other, RunLog):
             return False
@@ -250,7 +276,11 @@ class LogStreamCallbackHandler(BaseTracer, _StreamingCallbackHandler):
         self.root_id: Optional[UUID] = None
 
     def __aiter__(self) -> AsyncIterator[RunLogPatch]:
-        """Iterate over the stream of run logs."""
+        """Iterate over the stream of run logs.
+
+        Returns:
+            An async iterator over the run log patches.
+        """
         return self.receive_stream.__aiter__()
 
     def send(self, *ops: dict[str, Any]) -> bool:
@@ -623,15 +653,24 @@ async def _astream_log_implementation(
 
     The implementation has been factored out (at least temporarily) as both
     astream_log and astream_events relies on it.
-    """
-    import jsonpatch
-
-    from langchain_core.callbacks.base import BaseCallbackManager
-    from langchain_core.tracers.log_stream import (
-        RunLog,
-        RunLogPatch,
-    )
 
+    Args:
+        runnable: The runnable to run in streaming mode.
+        value: The input to the runnable.
+        config: The config to pass to the runnable.
+        stream: The stream to send the run logs to.
+        diff: Whether to yield run log patches (True) or full run logs (False).
+        with_streamed_output_list: Whether to include a list of all streamed
+            outputs in each patch. If False, only the final output will be included
+            in the patches.
+        **kwargs: Additional keyword arguments to pass to the runnable.
+
+    Raises:
+        ValueError: If the callbacks in the config are of an unexpected type.
+
+    Yields:
+        The run log patches or states, depending on the value of ``diff``.
+    """
     # Assign the stream handler to the config
     config = ensure_config(config)
     callbacks = config.get("callbacks")

langchain_core/tracers/root_listeners.py

@@ -21,18 +21,10 @@ AsyncListener = Union[
 
 
 class RootListenersTracer(BaseTracer):
-    """Tracer that calls listeners on run start, end, and error.
-
-    Parameters:
-        log_missing_parent: Whether to log a warning if the parent is missing.
-            Default is False.
-        config: The runnable config.
-        on_start: The listener to call on run start.
-        on_end: The listener to call on run end.
-        on_error: The listener to call on run error.
-    """
+    """Tracer that calls listeners on run start, end, and error."""
 
     log_missing_parent = False
+    """Whether to log a warning if the parent is missing. Default is False."""
 
     def __init__(
         self,
@@ -84,18 +76,10 @@ class RootListenersTracer(BaseTracer):
 
 
 class AsyncRootListenersTracer(AsyncBaseTracer):
-    """Async Tracer that calls listeners on run start, end, and error.
-
-    Parameters:
-        log_missing_parent: Whether to log a warning if the parent is missing.
-            Default is False.
-        config: The runnable config.
-        on_start: The listener to call on run start.
-        on_end: The listener to call on run end.
-        on_error: The listener to call on run error.
-    """
+    """Async Tracer that calls listeners on run start, end, and error."""
 
     log_missing_parent = False
+    """Whether to log a warning if the parent is missing. Default is False."""
 
     def __init__(
         self,

langchain_core/tracers/run_collector.py

@@ -11,12 +11,6 @@ class RunCollectorCallbackHandler(BaseTracer):
     """Tracer that collects all nested runs in a list.
 
     This tracer is useful for inspection and evaluation purposes.
-
-    Parameters
-    ----------
-    name : str, default="run-collector_callback_handler"
-    example_id : Optional[Union[UUID, str]], default=None
-        The ID of the example being traced. It can be either a UUID or a string.
     """
 
     name: str = "run-collector_callback_handler"
@@ -26,12 +20,10 @@ class RunCollectorCallbackHandler(BaseTracer):
     ) -> None:
         """Initialize the RunCollectorCallbackHandler.
 
-        Parameters
-        ----------
-        example_id : Optional[Union[UUID, str]], default=None
-            The ID of the example being traced. It can be either a UUID or a string.
-        **kwargs : Any
-            Additional keyword arguments
+        Args:
+            example_id: The ID of the example being traced. (default: None).
+                It can be either a UUID or a string.
+            **kwargs: Additional keyword arguments.
         """
         super().__init__(**kwargs)
         self.example_id = (
@@ -42,10 +34,8 @@ class RunCollectorCallbackHandler(BaseTracer):
     def _persist_run(self, run: Run) -> None:
         """Persist a run by adding it to the traced_runs list.
 
-        Parameters
-        ----------
-        run : Run
-            The run to be persisted.
+        Args:
+            run: The run to be persisted.
         """
         run_ = run.copy()
         run_.reference_example_id = self.example_id

langchain_core/tracers/schemas.py

@@ -18,7 +18,11 @@ from langchain_core._api import deprecated
 
 @deprecated("0.1.0", alternative="Use string instead.", removal="1.0")
 def RunTypeEnum() -> type[RunTypeEnumDep]:  # noqa: N802
-    """RunTypeEnum."""
+    """``RunTypeEnum``.
+
+    Returns:
+        The ``RunTypeEnum`` class.
+    """
     warnings.warn(
         "RunTypeEnum is deprecated. Please directly use a string instead"
         " (e.g. 'llm', 'chain', 'tool').",

langchain_core/utils/aiter.py

@@ -37,7 +37,7 @@ _no_default = object()
 # before 3.10, the builtin anext() was not available
 def py_anext(
     iterator: AsyncIterator[T], default: Union[T, Any] = _no_default
-) -> Awaitable[Union[T, None, Any]]:
+) -> Awaitable[Union[T, Any, None]]:
     """Pure-Python implementation of anext() for testing purposes.
 
     Closely matches the builtin anext() C implementation.
@@ -94,7 +94,7 @@ class NoLock:
         exc_val: Optional[BaseException],
         exc_tb: Optional[TracebackType],
     ) -> bool:
-        """Exception not handled."""
+        """Return False, exception not suppressed."""
         return False
 
 
@@ -236,7 +236,11 @@ class Tee(Generic[T]):
         return self._children[item]
 
     def __iter__(self) -> Iterator[AsyncIterator[T]]:
-        """Iterate over the child iterators."""
+        """Iterate over the child iterators.
+
+        Yields:
+            The child iterators.
+        """
         yield from self._children
 
     async def __aenter__(self) -> "Tee[T]":
@@ -249,7 +253,11 @@ class Tee(Generic[T]):
         exc_val: Optional[BaseException],
         exc_tb: Optional[TracebackType],
     ) -> bool:
-        """Close all child iterators."""
+        """Close all child iterators.
+
+        Returns:
+            False, exceptions not suppressed.
+        """
         await self.aclose()
         return False
 
@@ -318,8 +326,8 @@ async def abatch_iterate(
         size: The size of the batch.
         iterable: The async iterable to batch.
 
-    Returns:
-        An async iterator over the batches.
+    Yields:
+        The batches.
     """
     batch: list[T] = []
     async for element in iterable:

langchain_core/utils/env.py

@@ -39,6 +39,9 @@ def get_from_dict_or_env(
             in the dictionary.
         default: The default value to return if the key is not in the dictionary
             or the environment. Defaults to None.
+
+    Returns:
+        The dict value or the environment variable value.
     """
     if isinstance(key, (list, tuple)):
         for k in key: