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

langchain_core/utils/function_calling.py

@@ -17,12 +17,17 @@ from typing import (
     Optional,
     Union,
     cast,
+    get_args,
+    get_origin,
 )
 
 from pydantic import BaseModel
 from pydantic.v1 import BaseModel as BaseModelV1
-from typing_extensions import TypedDict, get_args, get_origin, is_typeddict
+from pydantic.v1 import Field as Field_v1
+from pydantic.v1 import create_model as create_model_v1
+from typing_extensions import TypedDict, 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 +151,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 +225,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 +267,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:
@@ -323,12 +326,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 +435,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 +474,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 +519,7 @@ _WellKnownOpenAITools = (
     "mcp",
     "image_generation",
     "web_search_preview",
+    "web_search",
 )
 
 
@@ -575,7 +580,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 +607,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)
@@ -671,8 +690,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"
@@ -681,6 +702,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.",
@@ -696,9 +718,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)]
@@ -816,8 +836,14 @@ def _recursive_set_additional_properties_false(
     if isinstance(schema, dict):
         # Check if 'required' is a key at the current level or if the schema is empty,
         # in which case additionalProperties still needs to be specified.
-        if "required" in schema or (
-            "properties" in schema and not schema["properties"]
+        if (
+            "required" in schema
+            or ("properties" in schema and not schema["properties"])
+            # Since Pydantic 2.11, it will always add `additionalProperties: True`
+            # for arbitrary dictionary schemas
+            # See: https://pydantic.dev/articles/pydantic-v2-11-release#changes
+            # If it is already set to True, we need override it to False
+            or "additionalProperties" in schema
         ):
             schema["additionalProperties"] = False
 

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,13 @@ from types import TracebackType
 from typing import (
     Any,
     Generic,
+    Literal,
     Optional,
     TypeVar,
     Union,
     overload,
 )
 
-from typing_extensions import Literal
-
 T = TypeVar("T")
 
 
@@ -31,7 +30,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 +172,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 +189,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()
@@ -98,7 +101,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 +190,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, 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)
@@ -36,6 +39,31 @@ 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],
@@ -43,51 +71,87 @@ def _dereference_refs_helper(
     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,6 +160,7 @@ def _dereference_refs_helper(
             for item in obj
         ]
 
+    # Case 4: Primitive value (string, number, boolean, null) - return unchanged
     return obj
 
 
@@ -105,16 +170,67 @@ def dereference_refs(
     full_schema: Optional[dict] = None,
     skip_keys: Optional[Sequence[str]] = 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/loading.py

@@ -19,7 +19,11 @@ def try_load_from_hub(
     *args: Any,  # noqa: ARG001
     **kwargs: Any,  # noqa: ARG001
 ) -> Any:
-    """[DEPRECATED] Try to load from the old Hub."""
+    """[DEPRECATED] Try to load from the old Hub.
+
+    Returns:
+        None always, indicating that we shouldn't load from the old hub.
+    """
     warnings.warn(
         "Loading from the deprecated github-based Hub is no longer supported. "
         "Please use the new LangChain Hub at https://smith.langchain.com/hub instead.",

langchain_core/utils/mustache.py

@@ -18,7 +18,7 @@ from typing import (
 )
 
 if TYPE_CHECKING:
-    from typing_extensions import TypeAlias
+    from typing import TypeAlias
 
 logger = logging.getLogger(__name__)
 
@@ -82,7 +82,7 @@ def l_sa_check(
     """
     # 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
@@ -214,17 +214,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 +331,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 +354,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 +412,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]