langchain-core 0.4.0.dev0__py3-none-any.whl → 1.0.0__py3-none-any.whl

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

@@ -8,14 +8,11 @@ from types import TracebackType
 from typing import (
     Any,
     Generic,
-    Optional,
+    Literal,
     TypeVar,
-    Union,
     overload,
 )
 
-from typing_extensions import Literal
-
 T = TypeVar("T")
 
 
@@ -27,11 +24,11 @@ class NoLock:
 
     def __exit__(
         self,
-        exc_type: Optional[type[BaseException]],
-        exc_val: Optional[BaseException],
-        exc_tb: Optional[TracebackType],
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
     ) -> Literal[False]:
-        """Exception not handled."""
+        """Return False (exception not suppressed)."""
         return False
 
 
@@ -43,10 +40,10 @@ def tee_peer(
     peers: list[deque[T]],
     lock: AbstractContextManager[Any],
 ) -> Generator[T, None, None]:
-    """An individual iterator of a :py:func:`~.tee`.
+    """An individual iterator of a `.tee`.
 
     This function is a generator that yields items from the shared iterator
-    ``iterator``. It buffers items until the least advanced iterator has
+    `iterator`. It buffers items until the least advanced iterator has
     yielded them as well. The buffer is shared with all other peers.
 
     Args:
@@ -92,39 +89,39 @@ def tee_peer(
 
 
 class Tee(Generic[T]):
-    """Create ``n`` separate asynchronous iterators over ``iterable``.
+    """Create `n` separate asynchronous iterators over `iterable`.
 
-    This splits a single ``iterable`` into multiple iterators, each providing
+    This splits a single `iterable` into multiple iterators, each providing
     the same items in the same order.
     All child iterators may advance separately but share the same items
-    from ``iterable`` -- when the most advanced iterator retrieves an item,
+    from `iterable` -- when the most advanced iterator retrieves an item,
     it is buffered until the least advanced iterator has yielded it as well.
-    A ``tee`` works lazily and can handle an infinite ``iterable``, provided
+    A `tee` works lazily and can handle an infinite `iterable`, provided
     that all iterators advance.
 
-    .. code-block:: python3
-
-        async def derivative(sensor_data):
-            previous, current = a.tee(sensor_data, n=2)
-            await a.anext(previous)  # advance one iterator
-            return a.map(operator.sub, previous, current)
-
-    Unlike :py:func:`itertools.tee`, :py:func:`~.tee` returns a custom type instead
-    of a :py:class:`tuple`. Like a tuple, it can be indexed, iterated and unpacked
-    to get the child iterators. In addition, its :py:meth:`~.tee.aclose` method
-    immediately closes all children, and it can be used in an ``async with`` context
+    ```python
+    async def derivative(sensor_data):
+        previous, current = a.tee(sensor_data, n=2)
+        await a.anext(previous)  # advance one iterator
+        return a.map(operator.sub, previous, current)
+    ```
+
+    Unlike `itertools.tee`, `.tee` returns a custom type instead
+    of a :py`tuple`. Like a tuple, it can be indexed, iterated and unpacked
+    to get the child iterators. In addition, its `.tee.aclose` method
+    immediately closes all children, and it can be used in an `async with` context
     for the same effect.
 
-    If ``iterable`` is an iterator and read elsewhere, ``tee`` will *not*
-    provide these items. Also, ``tee`` must internally buffer each item until the
+    If `iterable` is an iterator and read elsewhere, `tee` will *not*
+    provide these items. Also, `tee` must internally buffer each item until the
     last iterator has yielded it; if the most and least advanced iterator differ
-    by most data, using a :py:class:`list` is more efficient (but not lazy).
+    by most data, using a :py`list` is more efficient (but not lazy).
 
-    If the underlying iterable is concurrency safe (``anext`` may be awaited
+    If the underlying iterable is concurrency safe (`anext` may be awaited
     concurrently) the resulting iterators are concurrency safe as well. Otherwise,
     the iterators are safe if there is only ever one single "most advanced" iterator.
-    To enforce sequential use of ``anext``, provide a ``lock``
-    - e.g. an :py:class:`asyncio.Lock` instance in an :py:mod:`asyncio` application -
+    To enforce sequential use of `anext`, provide a `lock`
+    - e.g. an :py`asyncio.Lock` instance in an :py:mod:`asyncio` application -
     and access is automatically synchronised.
 
     """
@@ -134,15 +131,15 @@ class Tee(Generic[T]):
         iterable: Iterator[T],
         n: int = 2,
         *,
-        lock: Optional[AbstractContextManager[Any]] = None,
+        lock: AbstractContextManager[Any] | None = None,
     ):
-        """Create a ``tee``.
+        """Create a `tee`.
 
         Args:
             iterable: The iterable to split.
-            n: The number of iterators to create. Defaults to 2.
+            n: The number of iterators to create.
             lock: The lock to synchronise access to the shared buffers.
-                Defaults to None.
+
         """
         self._iterator = iter(iterable)
         self._buffers: list[deque[T]] = [deque() for _ in range(n)]
@@ -166,14 +163,16 @@ class Tee(Generic[T]):
     @overload
     def __getitem__(self, item: slice) -> tuple[Iterator[T], ...]: ...
 
-    def __getitem__(
-        self, item: Union[int, slice]
-    ) -> Union[Iterator[T], tuple[Iterator[T], ...]]:
+    def __getitem__(self, item: int | slice) -> Iterator[T] | tuple[Iterator[T], ...]:
         """Return the child iterator(s) at the given index or slice."""
         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]":
@@ -182,11 +181,15 @@ class Tee(Generic[T]):
 
     def __exit__(
         self,
-        exc_type: Optional[type[BaseException]],
-        exc_val: Optional[BaseException],
-        exc_tb: Optional[TracebackType],
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
     ) -> Literal[False]:
-        """Close all child iterators."""
+        """Close all child iterators.
+
+        Returns:
+            False (exception not suppressed).
+        """
         self.close()
         return False
 
@@ -200,11 +203,11 @@ class Tee(Generic[T]):
 safetee = Tee
 
 
-def batch_iterate(size: Optional[int], iterable: Iterable[T]) -> Iterator[list[T]]:
+def batch_iterate(size: int | None, iterable: Iterable[T]) -> Iterator[list[T]]:
     """Utility batching function.
 
     Args:
-        size: The size of the batch. If None, returns a single batch.
+        size: The size of the batch. If `None`, returns a single batch.
         iterable: The iterable to batch.
 
     Yields:

langchain_core/utils/json.py

@@ -4,7 +4,8 @@ from __future__ import annotations
 
 import json
 import re
-from typing import Any, Callable
+from collections.abc import Callable
+from typing import Any
 
 from langchain_core.exceptions import OutputParserException
 
@@ -19,13 +20,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: 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()
@@ -47,7 +51,7 @@ def parse_partial_json(s: str, *, strict: bool = False) -> Any:
 
     Args:
         s: The JSON string to parse.
-        strict: Whether to use strict parsing. Defaults to False.
+        strict: Whether to use strict parsing.
 
     Returns:
         The parsed JSON object as a Python dictionary.
@@ -98,7 +102,7 @@ def parse_partial_json(s: str, *, strict: bool = False) -> Any:
     # If we're still inside a string at the end of processing,
     # we need to close the string.
     if is_inside_string:
-        if escaped:  # Remoe unterminated escape character
+        if escaped:  # Remove unterminated escape character
             new_chars.pop()
         new_chars.append('"')
 
@@ -187,6 +191,12 @@ def parse_and_check_json_markdown(text: str, expected_keys: list[str]) -> dict:
     except json.JSONDecodeError as e:
         msg = f"Got invalid JSON object. Error: {e}"
         raise OutputParserException(msg) from e
+    if not isinstance(json_obj, dict):
+        error_message = (
+            f"Expected JSON object (dict), but got: {type(json_obj).__name__}. "
+        )
+        raise OutputParserException(error_message, llm_output=text)
+
     for key in expected_keys:
         if key not in json_obj:
             msg = (

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
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
 
-def _retrieve_ref(path: str, schema: dict) -> dict:
+def _retrieve_ref(path: str, schema: dict) -> 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: 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)
@@ -36,58 +39,119 @@ def _retrieve_ref(path: str, schema: dict) -> dict:
     return deepcopy(out)
 
 
+def _process_dict_properties(
+    properties: dict[str, Any],
+    full_schema: dict[str, Any],
+    processed_refs: set[str],
+    skip_keys: Sequence[str],
+    *,
+    shallow_refs: bool,
+) -> dict[str, Any]:
+    """Process dictionary properties, recursing into nested structures."""
+    result: dict[str, Any] = {}
+    for key, value in properties.items():
+        if key in skip_keys:
+            # Skip recursion for specified keys, just copy the value as-is
+            result[key] = deepcopy(value)
+        elif isinstance(value, (dict, list)):
+            # Recursively process nested objects and arrays
+            result[key] = _dereference_refs_helper(
+                value, full_schema, processed_refs, skip_keys, shallow_refs
+            )
+        else:
+            # Copy primitive values directly
+            result[key] = value
+    return result
+
+
 def _dereference_refs_helper(
     obj: Any,
     full_schema: dict[str, Any],
-    processed_refs: Optional[set[str]],
+    processed_refs: set[str] | None,
     skip_keys: Sequence[str],
     shallow_refs: bool,  # noqa: FBT001
 ) -> Any:
-    """Inline every pure {'$ref':...}.
+    """Dereference JSON Schema $ref objects, handling both pure and mixed references.
 
-    But:
-    - if shallow_refs=True: only break cycles, do not inline nested refs
-    - if shallow_refs=False: deep-inline all nested refs
+    This function processes JSON Schema objects containing $ref properties by resolving
+    the references and merging any additional properties. It handles:
 
-    Also skip recursion under any key in skip_keys.
+    - Pure $ref objects: {"$ref": "#/path/to/definition"}
+    - Mixed $ref objects: {"$ref": "#/path", "title": "Custom Title", ...}
+    - Circular references by breaking cycles and preserving non-ref properties
+
+    Args:
+        obj: The object to process (can be dict, list, or primitive)
+        full_schema: The complete schema containing all definitions
+        processed_refs: Set tracking currently processing refs (for cycle detection)
+        skip_keys: Keys under which to skip recursion
+        shallow_refs: If `True`, only break cycles; if False, deep-inline all refs
+
+    Returns:
+        The object with $ref properties resolved and merged with other properties.
     """
     if processed_refs is None:
         processed_refs = set()
 
-    # 1) Pure $ref node?
-    if isinstance(obj, dict) and "$ref" in set(obj.keys()):
+    # Case 1: Object contains a $ref property (pure or mixed with additional properties)
+    if isinstance(obj, dict) and "$ref" in obj:
         ref_path = obj["$ref"]
-        # cycle?
+        additional_properties = {
+            key: value for key, value in obj.items() if key != "$ref"
+        }
+
+        # Detect circular reference: if we're already processing this $ref,
+        # return only the additional properties to break the cycle
         if ref_path in processed_refs:
-            return {}
-        processed_refs.add(ref_path)
+            return _process_dict_properties(
+                additional_properties,
+                full_schema,
+                processed_refs,
+                skip_keys,
+                shallow_refs=shallow_refs,
+            )
 
-        # grab + copy the target
-        target = deepcopy(_retrieve_ref(ref_path, full_schema))
+        # Mark this reference as being processed (for cycle detection)
+        processed_refs.add(ref_path)
 
-        # deep inlining: recurse into everything
-        result = _dereference_refs_helper(
-            target, full_schema, processed_refs, skip_keys, shallow_refs
+        # Fetch and recursively resolve the referenced object
+        referenced_object = deepcopy(_retrieve_ref(ref_path, full_schema))
+        resolved_reference = _dereference_refs_helper(
+            referenced_object, full_schema, processed_refs, skip_keys, shallow_refs
         )
 
+        # Clean up: remove from processing set before returning
         processed_refs.remove(ref_path)
-        return result
 
-    # 2) Not a pure-$ref: recurse, skipping any keys in skip_keys
+        # Pure $ref case: no additional properties, return resolved reference directly
+        if not additional_properties:
+            return resolved_reference
+
+        # Mixed $ref case: merge resolved reference with additional properties
+        # Additional properties take precedence over resolved properties
+        merged_result = {}
+        if isinstance(resolved_reference, dict):
+            merged_result.update(resolved_reference)
+
+        # Process additional properties and merge them (they override resolved ones)
+        processed_additional = _process_dict_properties(
+            additional_properties,
+            full_schema,
+            processed_refs,
+            skip_keys,
+            shallow_refs=shallow_refs,
+        )
+        merged_result.update(processed_additional)
+
+        return merged_result
+
+    # Case 2: Regular dictionary without $ref - process all properties
     if isinstance(obj, dict):
-        out: dict[str, Any] = {}
-        for k, v in obj.items():
-            if k in skip_keys:
-                # do not recurse under this key
-                out[k] = deepcopy(v)
-            elif isinstance(v, (dict, list)):
-                out[k] = _dereference_refs_helper(
-                    v, full_schema, processed_refs, skip_keys, shallow_refs
-                )
-            else:
-                out[k] = v
-        return out
+        return _process_dict_properties(
+            obj, full_schema, processed_refs, skip_keys, shallow_refs=shallow_refs
+        )
 
+    # Case 3: List - recursively process each item
     if isinstance(obj, list):
         return [
             _dereference_refs_helper(
@@ -96,25 +160,77 @@ def _dereference_refs_helper(
             for item in obj
         ]
 
+    # Case 4: Primitive value (string, number, boolean, null) - return unchanged
     return obj
 
 
 def dereference_refs(
     schema_obj: dict,
     *,
-    full_schema: Optional[dict] = None,
-    skip_keys: Optional[Sequence[str]] = None,
+    full_schema: dict | None = None,
+    skip_keys: Sequence[str] | None = None,
 ) -> dict:
-    """Try to substitute $refs in JSON Schema.
+    """Resolve and inline JSON Schema $ref references in a schema object.
+
+    This function processes a JSON Schema and resolves all $ref references by replacing
+    them with the actual referenced content. It handles both simple references and
+    complex cases like circular references and mixed $ref objects that contain
+    additional properties alongside the $ref.
 
     Args:
-      schema_obj: The fragment to dereference.
-      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.
-        - If provided (even as an empty list), we will recurse under every key and
-            deep-inline all refs.
+        schema_obj: The JSON Schema object or fragment to process. This can be a
+            complete schema or just a portion of one.
+        full_schema: The complete schema containing all definitions that $refs might
+            point to. If not provided, defaults to schema_obj (useful when the
+            schema is self-contained).
+        skip_keys: Controls recursion behavior and reference resolution depth:
+            - If `None` (Default): Only recurse under '$defs' and use shallow reference
+              resolution (break cycles but don't deep-inline nested refs)
+            - If provided (even as []): Recurse under all keys and use deep reference
+              resolution (fully inline all nested references)
+
+    Returns:
+        A new dictionary with all $ref references resolved and inlined. The original
+        schema_obj is not modified.
+
+    Examples:
+        Basic reference resolution:
+        >>> schema = {
+        ...     "type": "object",
+        ...     "properties": {"name": {"$ref": "#/$defs/string_type"}},
+        ...     "$defs": {"string_type": {"type": "string"}},
+        ... }
+        >>> result = dereference_refs(schema)
+        >>> result["properties"]["name"]  # {"type": "string"}
+
+        Mixed $ref with additional properties:
+        >>> schema = {
+        ...     "properties": {
+        ...         "name": {"$ref": "#/$defs/base", "description": "User name"}
+        ...     },
+        ...     "$defs": {"base": {"type": "string", "minLength": 1}},
+        ... }
+        >>> result = dereference_refs(schema)
+        >>> result["properties"]["name"]
+        # {"type": "string", "minLength": 1, "description": "User name"}
+
+        Handling circular references:
+        >>> schema = {
+        ...     "properties": {"user": {"$ref": "#/$defs/User"}},
+        ...     "$defs": {
+        ...         "User": {
+        ...             "type": "object",
+        ...             "properties": {"friend": {"$ref": "#/$defs/User"}},
+        ...         }
+        ...     },
+        ... }
+        >>> result = dereference_refs(schema)  # Won't cause infinite recursion
+
+    Note:
+        - Circular references are handled gracefully by breaking cycles
+        - Mixed $ref objects (with both $ref and other properties) are supported
+        - Additional properties in mixed $refs override resolved properties
+        - The $defs section is preserved in the output by default
     """
     full = full_schema or schema_obj
     keys_to_skip = list(skip_keys) if skip_keys is not None else ["$defs"]

langchain_core/utils/mustache.py

@@ -12,18 +12,16 @@ from typing import (
     TYPE_CHECKING,
     Any,
     Literal,
-    Optional,
-    Union,
     cast,
 )
 
 if TYPE_CHECKING:
-    from typing_extensions import TypeAlias
+    from typing import TypeAlias
 
 logger = logging.getLogger(__name__)
 
 
-Scopes: TypeAlias = list[Union[Literal[False, 0], Mapping[str, Any]]]
+Scopes: TypeAlias = list[Literal[False, 0] | Mapping[str, Any]]
 
 
 # Globals
@@ -48,7 +46,7 @@ def grab_literal(template: str, l_del: str) -> tuple[str, str]:
         l_del: The left delimiter.
 
     Returns:
-        tuple[str, str]: The literal and the template.
+        The literal and the template.
     """
     global _CURRENT_LINE
 
@@ -78,11 +76,11 @@ def l_sa_check(
         is_standalone: Whether the tag is standalone.
 
     Returns:
-        bool: Whether the tag could be a standalone.
+        Whether the tag could be a standalone.
     """
     # If there is a newline, or the previous tag was a standalone
     if literal.find("\n") != -1 or is_standalone:
-        padding = literal.split("\n")[-1]
+        padding = literal.rsplit("\n", maxsplit=1)[-1]
 
         # If all the characters since the last newline are spaces
         # Then the next tag could be a standalone
@@ -104,7 +102,7 @@ def r_sa_check(
         is_standalone: Whether the tag is standalone.
 
     Returns:
-        bool: Whether the tag could be a standalone.
+        Whether the tag could be a standalone.
     """
     # Check right side if we might be a standalone
     if is_standalone and tag_type not in {"variable", "no escape"}:
@@ -126,7 +124,7 @@ def parse_tag(template: str, l_del: str, r_del: str) -> tuple[tuple[str, str], s
         r_del: The right delimiter.
 
     Returns:
-        tuple[tuple[str, str], str]: The tag and the template.
+        The tag and the template.
 
     Raises:
         ChevronError: If the tag is unclosed.
@@ -214,17 +212,22 @@ def tokenize(
         def_rdel: The default right delimiter
             ("}}" by default, as in spec compliant mustache)
 
-    Returns:
-        A generator of mustache tags in the form of a tuple (tag_type, tag_key)
-            Where tag_type is one of:
-             * literal
-             * section
-             * inverted section
-             * end
-             * partial
-             * no escape
-            And tag_key is either the key or in the case of a literal tag,
-            the literal itself.
+    Yields:
+        Mustache tags in the form of a tuple (tag_type, tag_key)
+        where tag_type is one of:
+
+        * literal
+        * section
+        * inverted section
+        * end
+        * partial
+        * no escape
+
+        and tag_key is either the key or in the case of a literal tag,
+        the literal itself.
+
+    Raises:
+        ChevronError: If there is a syntax error in the template.
     """
     global _CURRENT_LINE, _LAST_TAG_LINE
     _CURRENT_LINE = 1
@@ -326,7 +329,7 @@ def tokenize(
 
 
 def _html_escape(string: str) -> str:
-    """HTML escape all of these " & < >."""
+    """Return the HTML-escaped string with these characters escaped: `" & < >`."""
     html_codes = {
         '"': "&quot;",
         "<": "&lt;",
@@ -349,7 +352,7 @@ def _get_key(
     def_ldel: str,
     def_rdel: str,
 ) -> Any:
-    """Get a key from the current scope."""
+    """Return a key from the current scope."""
     # If the key is a dot
     if key == ".":
         # Then just return the current scope
@@ -407,7 +410,11 @@ def _get_key(
 
 
 def _get_partial(name: str, partials_dict: Mapping[str, str]) -> str:
-    """Load a partial."""
+    """Load a partial.
+
+    Returns:
+        The partial.
+    """
     try:
         # Maybe the partial is in the dictionary
         return partials_dict[name]
@@ -424,13 +431,13 @@ EMPTY_DICT: MappingProxyType[str, str] = MappingProxyType({})
 
 
 def render(
-    template: Union[str, list[tuple[str, str]]] = "",
+    template: str | list[tuple[str, str]] = "",
     data: Mapping[str, Any] = EMPTY_DICT,
     partials_dict: Mapping[str, str] = EMPTY_DICT,
     padding: str = "",
     def_ldel: str = "{{",
     def_rdel: str = "}}",
-    scopes: Optional[Scopes] = None,
+    scopes: Scopes | None = None,
     warn: bool = False,  # noqa: FBT001,FBT002
     keep: bool = False,  # noqa: FBT001,FBT002
 ) -> str: