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

langchain_core/tracers/core.py

@@ -71,7 +71,7 @@ class _TracerCore(ABC):
                   for streaming events.
                 - 'original+chat' is a format that is the same as 'original'
                   except it does NOT raise an attribute error on_chat_model_start
-            kwargs: Additional keyword arguments that will be passed to
+            **kwargs: Additional keyword arguments that will be passed to
                 the superclass.
         """
         super().__init__(**kwargs)
@@ -82,7 +82,7 @@ class _TracerCore(ABC):
         """Map of run ID to (trace_id, dotted_order). Cleared when tracer GCed."""
 
     @abstractmethod
-    def _persist_run(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:
+    def _persist_run(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:
         """Persist a run."""
 
     @staticmethod
@@ -108,7 +108,7 @@ class _TracerCore(ABC):
         except:  # noqa: E722
             return msg
 
-    def _start_trace(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # type: ignore[return]
+    def _start_trace(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # type: ignore[return]
         current_dotted_order = run.start_time.strftime("%Y%m%dT%H%M%S%fZ") + str(run.id)
         if run.parent_run_id:
             if parent := self.order_map.get(run.parent_run_id):
@@ -531,27 +531,43 @@ class _TracerCore(ABC):
         return retrieval_run
 
     def __deepcopy__(self, memo: dict) -> _TracerCore:
-        """Deepcopy the tracer."""
+        """Return self deepcopied."""
         return self
 
     def __copy__(self) -> _TracerCore:
-        """Copy the tracer."""
+        """Return self copied."""
         return self
 
-    def _end_trace(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """End a trace for a run."""
+    def _end_trace(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """End a trace for a run.
+
+        Args:
+            run: The run.
+        """
         return None
 
-    def _on_run_create(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process a run upon creation."""
+    def _on_run_create(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process a run upon creation.
+
+        Args:
+            run: The created run.
+        """
         return None
 
-    def _on_run_update(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process a run upon update."""
+    def _on_run_update(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process a run upon update.
+
+        Args:
+            run: The updated run.
+        """
         return None
 
-    def _on_llm_start(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the LLM Run upon start."""
+    def _on_llm_start(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the LLM Run upon start.
+
+        Args:
+            run: The LLM run.
+        """
         return None
 
     def _on_llm_new_token(
@@ -559,54 +575,108 @@ class _TracerCore(ABC):
         run: Run,  # noqa: ARG002
         token: str,  # noqa: ARG002
         chunk: Optional[Union[GenerationChunk, ChatGenerationChunk]],  # noqa: ARG002
-    ) -> Union[None, Coroutine[Any, Any, None]]:
-        """Process new LLM token."""
+    ) -> Union[Coroutine[Any, Any, None], None]:
+        """Process new LLM token.
+
+        Args:
+            run: The LLM run.
+            token: The new token.
+            chunk: Optional chunk.
+        """
         return None
 
-    def _on_llm_end(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the LLM Run."""
+    def _on_llm_end(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the LLM Run.
+
+        Args:
+            run: The LLM run.
+        """
         return None
 
-    def _on_llm_error(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the LLM Run upon error."""
+    def _on_llm_error(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the LLM Run upon error.
+
+        Args:
+            run: The LLM run.
+        """
         return None
 
-    def _on_chain_start(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Chain Run upon start."""
+    def _on_chain_start(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Chain Run upon start.
+
+        Args:
+            run: The chain run.
+        """
         return None
 
-    def _on_chain_end(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Chain Run."""
+    def _on_chain_end(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Chain Run.
+
+        Args:
+            run: The chain run.
+        """
         return None
 
-    def _on_chain_error(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Chain Run upon error."""
+    def _on_chain_error(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Chain Run upon error.
+
+        Args:
+            run: The chain run.
+        """
         return None
 
-    def _on_tool_start(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Tool Run upon start."""
+    def _on_tool_start(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Tool Run upon start.
+
+        Args:
+            run: The tool run.
+        """
         return None
 
-    def _on_tool_end(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Tool Run."""
+    def _on_tool_end(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Tool Run.
+
+        Args:
+            run: The tool run.
+        """
         return None
 
-    def _on_tool_error(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Tool Run upon error."""
+    def _on_tool_error(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Tool Run upon error.
+
+        Args:
+            run: The tool run.
+        """
         return None
 
-    def _on_chat_model_start(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Chat Model Run upon start."""
+    def _on_chat_model_start(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Chat Model Run upon start.
+
+        Args:
+            run: The chat model run.
+        """
         return None
 
-    def _on_retriever_start(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Retriever Run upon start."""
+    def _on_retriever_start(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Retriever Run upon start.
+
+        Args:
+            run: The retriever run.
+        """
         return None
 
-    def _on_retriever_end(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Retriever Run."""
+    def _on_retriever_end(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Retriever Run.
+
+        Args:
+            run: The retriever run.
+        """
         return None
 
-    def _on_retriever_error(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Retriever Run upon error."""
+    def _on_retriever_error(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Retriever Run upon error.
+
+        Args:
+            run: The retriever run.
+        """
         return None

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(
@@ -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] = {}
@@ -636,7 +654,11 @@ 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.
+
+        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 = (
@@ -718,7 +740,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 +752,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 +773,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 +852,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 +950,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."
     )