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

langchain_core/tracers/evaluation.py

@@ -38,24 +38,27 @@ class EvaluatorCallbackHandler(BaseTracer):
     """Tracer that runs a run evaluator whenever a run is persisted.
 
     Attributes:
-        example_id : Union[UUID, None]
-            The example ID associated with the runs.
         client : Client
             The LangSmith client instance used for evaluating the runs.
-        evaluators : Sequence[RunEvaluator]
-            The sequence of run evaluators to be executed.
-        executor : ThreadPoolExecutor
-            The thread pool executor used for running the evaluators.
-        futures : set[Future]
-            The set of futures representing the running evaluators.
-        skip_unfinished : bool
-            Whether to skip runs that are not finished or raised
-            an error.
-        project_name : Optional[str]
-            The LangSmith project name to be organize eval chain runs under.
     """
 
     name: str = "evaluator_callback_handler"
+    example_id: Optional[UUID] = None
+    """The example ID associated with the runs."""
+    client: langsmith.Client
+    """The LangSmith client instance used for evaluating the runs."""
+    evaluators: Sequence[langsmith.RunEvaluator] = ()
+    """The sequence of run evaluators to be executed."""
+    executor: Optional[ThreadPoolExecutor] = None
+    """The thread pool executor used for running the evaluators."""
+    futures: weakref.WeakSet[Future] = weakref.WeakSet()
+    """The set of futures representing the running evaluators."""
+    skip_unfinished: bool = True
+    """Whether to skip runs that are not finished or raised an error."""
+    project_name: Optional[str] = None
+    """The LangSmith project name to be organize eval chain runs under."""
+    logged_eval_results: dict[tuple[str, str], list[EvaluationResult]]
+    lock: threading.Lock
 
     def __init__(
         self,
@@ -91,7 +94,7 @@ class EvaluatorCallbackHandler(BaseTracer):
         self.client = client or langchain_tracer.get_client()
         self.evaluators = evaluators
         if max_concurrency is None:
-            self.executor: Optional[ThreadPoolExecutor] = _get_executor()
+            self.executor = _get_executor()
         elif max_concurrency > 0:
             self.executor = ThreadPoolExecutor(max_workers=max_concurrency)
             weakref.finalize(
@@ -100,10 +103,10 @@ class EvaluatorCallbackHandler(BaseTracer):
             )
         else:
             self.executor = None
-        self.futures: weakref.WeakSet[Future] = weakref.WeakSet()
+        self.futures = weakref.WeakSet()
         self.skip_unfinished = skip_unfinished
         self.project_name = project_name
-        self.logged_eval_results: dict[tuple[str, str], list[EvaluationResult]] = {}
+        self.logged_eval_results = {}
         self.lock = threading.Lock()
         _TRACERS.add(self)
 
@@ -111,12 +114,8 @@ class EvaluatorCallbackHandler(BaseTracer):
         """Evaluate the run in the project.
 
         Args:
-        ----------
-        run : Run
-            The run to be evaluated.
-        evaluator : RunEvaluator
-            The evaluator to use for evaluating the run.
-
+            run: The run to be evaluated.
+            evaluator: The evaluator to use for evaluating the run.
         """
         try:
             if self.project_name is None:
@@ -202,10 +201,7 @@ class EvaluatorCallbackHandler(BaseTracer):
         """Run the evaluator on the run.
 
         Args:
-        ----------
-        run : Run
-            The run to be evaluated.
-
+            run: The run to be evaluated.
         """
         if self.skip_unfinished and not run.outputs:
             logger.debug("Skipping unfinished run %s", run.id)

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(
@@ -412,7 +421,6 @@ 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_info = self.run_map.get(run_id)
         chunk_: Union[GenerationChunk, BaseMessageChunk]
 
@@ -458,7 +466,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 an LLM run.
+
+        Args:
+            response (LLMResult): The response which was generated.
+            run_id (UUID): The run ID. This is the ID of the current run.
+
+        Raises:
+            ValueError: If the run type is not ``'llm'`` or ``'chat_model'``.
+        """
         run_info = self.run_map.pop(run_id)
         inputs_ = run_info["inputs"]
 
@@ -636,7 +652,15 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
 
     @override
     async def on_tool_end(self, output: Any, *, run_id: UUID, **kwargs: Any) -> None:
-        """End a trace for a tool run."""
+        """End a trace for a tool run.
+
+        Args:
+            output: The output of the tool.
+            run_id: The run ID. This is the ID of the current run.
+
+        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 = (
@@ -730,11 +754,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 +775,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,
@@ -936,9 +952,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: