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

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
@@ -176,7 +202,7 @@ class RunLog(RunLogPatch):
         # Then compare that the ops are the same
         return super().__eq__(other)
 
-    __hash__ = None  # type: ignore[assignment]
+    __hash__ = None
 
 
 T = TypeVar("T")
@@ -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:

langchain_core/utils/function_calling.py

@@ -21,8 +21,10 @@ from typing import (
 
 from pydantic import BaseModel
 from pydantic.v1 import BaseModel as BaseModelV1
+from pydantic.v1 import Field, create_model
 from typing_extensions import TypedDict, get_args, get_origin, is_typeddict
 
+import langchain_core
 from langchain_core._api import beta, deprecated
 from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, ToolMessage
 from langchain_core.utils.json_schema import dereference_refs
@@ -146,6 +148,9 @@ def _convert_pydantic_to_openai_function(
             of the schema will be used.
         rm_titles: Whether to remove titles from the schema. Defaults to True.
 
+    Raises:
+        TypeError: If the model is not a Pydantic model.
+
     Returns:
         The function description.
     """
@@ -217,10 +222,8 @@ def _convert_python_function_to_openai_function(
     Returns:
         The OpenAI function description.
     """
-    from langchain_core.tools.base import create_schema_from_function
-
     func_name = _get_python_function_name(function)
-    model = create_schema_from_function(
+    model = langchain_core.tools.base.create_schema_from_function(
         func_name,
         function,
         filter_args=(),
@@ -261,9 +264,6 @@ def _convert_any_typed_dicts_to_pydantic(
     visited: dict,
     depth: int = 0,
 ) -> type:
-    from pydantic.v1 import Field as Field_v1
-    from pydantic.v1 import create_model as create_model_v1
-
     if type_ in visited:
         return visited[type_]
     if depth >= _MAX_TYPED_DICT_RECURSION:
@@ -277,7 +277,7 @@ def _convert_any_typed_dicts_to_pydantic(
         )
         fields: dict = {}
         for arg, arg_type in annotations_.items():
-            if get_origin(arg_type) is Annotated:
+            if get_origin(arg_type) is Annotated:  # type: ignore[comparison-overlap]
                 annotated_args = get_args(arg_type)
                 new_arg_type = _convert_any_typed_dicts_to_pydantic(
                     annotated_args[0], depth=depth + 1, visited=visited
@@ -294,7 +294,7 @@ def _convert_any_typed_dicts_to_pydantic(
                     raise ValueError(msg)
                 if arg_desc := arg_descriptions.get(arg):
                     field_kwargs["description"] = arg_desc
-                fields[arg] = (new_arg_type, Field_v1(**field_kwargs))
+                fields[arg] = (new_arg_type, Field(**field_kwargs))
             else:
                 new_arg_type = _convert_any_typed_dicts_to_pydantic(
                     arg_type, depth=depth + 1, visited=visited
@@ -302,8 +302,8 @@ def _convert_any_typed_dicts_to_pydantic(
                 field_kwargs = {"default": ...}
                 if arg_desc := arg_descriptions.get(arg):
                     field_kwargs["description"] = arg_desc
-                fields[arg] = (new_arg_type, Field_v1(**field_kwargs))
-        model = create_model_v1(typed_dict.__name__, **fields)
+                fields[arg] = (new_arg_type, Field(**field_kwargs))
+        model = create_model(typed_dict.__name__, **fields)
         model.__doc__ = description
         visited[typed_dict] = model
         return model
@@ -323,12 +323,15 @@ def _format_tool_to_openai_function(tool: BaseTool) -> FunctionDescription:
     Args:
         tool: The tool to format.
 
+    Raises:
+        ValueError: If the tool call schema is not supported.
+
     Returns:
         The function description.
     """
-    from langchain_core.tools import simple
-
-    is_simple_oai_tool = isinstance(tool, simple.Tool) and not tool.args_schema
+    is_simple_oai_tool = (
+        isinstance(tool, langchain_core.tools.simple.Tool) and not tool.args_schema
+    )
     if tool.tool_call_schema and not is_simple_oai_tool:
         if isinstance(tool.tool_call_schema, dict):
             return _convert_json_schema_to_openai_function(
@@ -429,8 +432,6 @@ def convert_to_openai_function(
         'description' and 'parameters' keys are now optional. Only 'name' is
         required and guaranteed to be part of the output.
     """
-    from langchain_core.tools import BaseTool
-
     # an Anthropic format tool
     if isinstance(function, dict) and all(
         k in function for k in ("name", "input_schema")
@@ -470,7 +471,7 @@ def convert_to_openai_function(
         oai_function = cast(
             "dict", _convert_typed_dict_to_openai_function(cast("type", function))
         )
-    elif isinstance(function, BaseTool):
+    elif isinstance(function, langchain_core.tools.base.BaseTool):
         oai_function = cast("dict", _format_tool_to_openai_function(function))
     elif callable(function):
         oai_function = cast(
@@ -515,6 +516,7 @@ _WellKnownOpenAITools = (
     "mcp",
     "image_generation",
     "web_search_preview",
+    "web_search",
 )
 
 
@@ -575,7 +577,8 @@ def convert_to_openai_tool(
 
         Added support for OpenAI's image generation built-in tool.
     """
-    from langchain_core.tools import Tool
+    # Import locally to prevent circular import
+    from langchain_core.tools import Tool  # noqa: PLC0415
 
     if isinstance(tool, dict):
         if tool.get("type") in _WellKnownOpenAITools:
@@ -601,7 +604,20 @@ def convert_to_json_schema(
     *,
     strict: Optional[bool] = None,
 ) -> dict[str, Any]:
-    """Convert a schema representation to a JSON schema."""
+    """Convert a schema representation to a JSON schema.
+
+    Args:
+        schema: The schema to convert.
+        strict: If True, model output is guaranteed to exactly match the JSON Schema
+            provided in the function definition. If None, ``strict`` argument will not
+            be included in function definition.
+
+    Raises:
+        ValueError: If the input is not a valid OpenAI-format tool.
+
+    Returns:
+        A JSON schema representation of the input schema.
+    """
     openai_tool = convert_to_openai_tool(schema, strict=strict)
     if (
         not isinstance(openai_tool, dict)
@@ -627,7 +643,7 @@ def convert_to_json_schema(
 
 @beta()
 def tool_example_to_messages(
-    input: str,  # noqa: A002
+    input: str,
     tool_calls: list[BaseModel],
     tool_outputs: Optional[list[str]] = None,
     *,
@@ -640,15 +656,16 @@ def tool_example_to_messages(
 
     The list of messages per example by default corresponds to:
 
-    1) HumanMessage: contains the content from which content should be extracted.
-    2) AIMessage: contains the extracted information from the model
-    3) ToolMessage: contains confirmation to the model that the model requested a tool
-       correctly.
+    1. ``HumanMessage``: contains the content from which content should be extracted.
+    2. ``AIMessage``: contains the extracted information from the model
+    3. ``ToolMessage``: contains confirmation to the model that the model requested a
+       tool correctly.
 
-    If `ai_response` is specified, there will be a final AIMessage with that response.
+    If ``ai_response`` is specified, there will be a final ``AIMessage`` with that
+    response.
 
-    The ToolMessage is required because some chat models are hyper-optimized for agents
-    rather than for an extraction use case.
+    The ``ToolMessage`` is required because some chat models are hyper-optimized for
+    agents rather than for an extraction use case.
 
     Arguments:
         input: string, the user input
@@ -657,7 +674,7 @@ def tool_example_to_messages(
         tool_outputs: Optional[list[str]], a list of tool call outputs.
             Does not need to be provided. If not provided, a placeholder value
             will be inserted. Defaults to None.
-        ai_response: Optional[str], if provided, content for a final AIMessage.
+        ai_response: Optional[str], if provided, content for a final ``AIMessage``.
 
     Returns:
         A list of messages
@@ -670,8 +687,10 @@ def tool_example_to_messages(
             from pydantic import BaseModel, Field
             from langchain_openai import ChatOpenAI
 
+
             class Person(BaseModel):
                 '''Information about a person.'''
+
                 name: Optional[str] = Field(..., description="The name of the person")
                 hair_color: Optional[str] = Field(
                     ..., description="The color of the person's hair if known"
@@ -680,6 +699,7 @@ def tool_example_to_messages(
                     ..., description="Height in METERS"
                 )
 
+
             examples = [
                 (
                     "The ocean is vast and blue. It's more than 20,000 feet deep.",
@@ -695,9 +715,7 @@ def tool_example_to_messages(
             messages = []
 
             for txt, tool_call in examples:
-                messages.extend(
-                    tool_example_to_messages(txt, [tool_call])
-                )
+                messages.extend(tool_example_to_messages(txt, [tool_call]))
 
     """
     messages: list[BaseMessage] = [HumanMessage(content=input)]
@@ -739,6 +757,7 @@ def _parse_google_docstring(
     """Parse the function and argument descriptions from the docstring of a function.
 
     Assumes the function docstring follows Google Python style guide.
+
     """
     if docstring:
         docstring_blocks = docstring.split("\n\n")

langchain_core/utils/interactive_env.py

@@ -1,8 +1,12 @@
 """Utilities for working with interactive environments."""
 
+import sys
+
 
 def is_interactive_env() -> bool:
-    """Determine if running within IPython or Jupyter."""
-    import sys
+    """Determine if running within IPython or Jupyter.
 
+    Returns:
+        True if running in an interactive environment, False otherwise.
+    """
     return hasattr(sys, "ps2")

langchain_core/utils/iter.py

@@ -31,7 +31,7 @@ class NoLock:
         exc_val: Optional[BaseException],
         exc_tb: Optional[TracebackType],
     ) -> Literal[False]:
-        """Exception not handled."""
+        """Return False (exception not suppressed)."""
         return False
 
 
@@ -173,7 +173,11 @@ class Tee(Generic[T]):
         return self._children[item]
 
     def __iter__(self) -> Iterator[Iterator[T]]:
-        """Return an iterator over the child iterators."""
+        """Return an iterator over the child iterators.
+
+        Yields:
+            The child iterators.
+        """
         yield from self._children
 
     def __enter__(self) -> "Tee[T]":
@@ -186,7 +190,11 @@ class Tee(Generic[T]):
         exc_val: Optional[BaseException],
         exc_tb: Optional[TracebackType],
     ) -> Literal[False]:
-        """Close all child iterators."""
+        """Close all child iterators.
+
+        Returns:
+            False (exception not suppressed).
+        """
         self.close()
         return False
 

langchain_core/utils/json.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import json
 import re
-from typing import Any, Callable
+from typing import Any, Callable, Union
 
 from langchain_core.exceptions import OutputParserException
 
@@ -19,13 +19,16 @@ def _replace_new_line(match: re.Match[str]) -> str:
     return match.group(1) + value + match.group(3)
 
 
-def _custom_parser(multiline_string: str) -> str:
+def _custom_parser(multiline_string: Union[str, bytes, bytearray]) -> str:
     r"""Custom parser for multiline strings.
 
     The LLM response for `action_input` may be a multiline
     string containing unescaped newlines, tabs or quotes. This function
     replaces those characters with their escaped counterparts.
     (newlines in JSON must be double-escaped: `\\n`).
+
+    Returns:
+        The modified string with escaped newlines, tabs and quotes.
     """
     if isinstance(multiline_string, (bytes, bytearray)):
         multiline_string = multiline_string.decode()

langchain_core/utils/json_schema.py

@@ -3,13 +3,13 @@
 from __future__ import annotations
 
 from copy import deepcopy
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any, Optional, Union
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
 
-def _retrieve_ref(path: str, schema: dict) -> dict:
+def _retrieve_ref(path: str, schema: dict) -> Union[list, dict]:
     components = path.split("/")
     if components[0] != "#":
         msg = (
@@ -17,9 +17,12 @@ def _retrieve_ref(path: str, schema: dict) -> dict:
             "with #."
         )
         raise ValueError(msg)
-    out = schema
+    out: Union[list, dict] = schema
     for component in components[1:]:
         if component in out:
+            if isinstance(out, list):
+                msg = f"Reference '{path}' not found."
+                raise KeyError(msg)
             out = out[component]
         elif component.isdigit():
             index = int(component)
@@ -46,10 +49,14 @@ def _dereference_refs_helper(
     """Inline every pure {'$ref':...}.
 
     But:
+
     - if shallow_refs=True: only break cycles, do not inline nested refs
     - if shallow_refs=False: deep-inline all nested refs
 
     Also skip recursion under any key in skip_keys.
+
+    Returns:
+        The object with refs dereferenced.
     """
     if processed_refs is None:
         processed_refs = set()
@@ -112,9 +119,12 @@ def dereference_refs(
       full_schema: The complete schema (defaults to schema_obj).
       skip_keys:
         - If None (the default), we skip recursion under '$defs' *and* only
-            shallow-inline refs.
+          shallow-inline refs.
         - If provided (even as an empty list), we will recurse under every key and
-            deep-inline all refs.
+          deep-inline all refs.
+
+    Returns:
+        The schema with refs dereferenced.
     """
     full = full_schema or schema_obj
     keys_to_skip = list(skip_keys) if skip_keys is not None else ["$defs"]