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

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

@@ -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]

langchain_core/utils/pydantic.py

@@ -57,6 +57,9 @@ def get_pydantic_major_version() -> int:
     """DEPRECATED - Get the major version of Pydantic.
 
     Use PYDANTIC_VERSION.major instead.
+
+    Returns:
+        The major version of Pydantic.
     """
     return PYDANTIC_VERSION.major
 
@@ -74,12 +77,20 @@ TBaseModel = TypeVar("TBaseModel", bound=PydanticBaseModel)
 
 
 def is_pydantic_v1_subclass(cls: type) -> bool:
-    """Check if the installed Pydantic version is 1.x-like."""
+    """Check if the given class is Pydantic v1-like.
+
+    Returns:
+        True if the given class is a subclass of Pydantic ``BaseModel`` 1.x.
+    """
     return issubclass(cls, BaseModelV1)
 
 
 def is_pydantic_v2_subclass(cls: type) -> bool:
-    """Check if the installed Pydantic version is 1.x-like."""
+    """Check if the given class is Pydantic v2-like.
+
+    Returns:
+        True if the given class is a subclass of Pydantic BaseModel 2.x.
+    """
     return issubclass(cls, BaseModel)
 
 
@@ -90,6 +101,9 @@ def is_basemodel_subclass(cls: type) -> bool:
 
     * pydantic.BaseModel in Pydantic 2.x
     * pydantic.v1.BaseModel in Pydantic 2.x
+
+    Returns:
+        True if the given class is a subclass of Pydantic ``BaseModel``.
     """
     # Before we can use issubclass on the cls we need to check if it is a class
     if not inspect.isclass(cls) or isinstance(cls, GenericAlias):
@@ -105,6 +119,9 @@ def is_basemodel_instance(obj: Any) -> bool:
 
     * pydantic.BaseModel in Pydantic 2.x
     * pydantic.v1.BaseModel in Pydantic 2.x
+
+    Returns:
+        True if the given class is an instance of Pydantic ``BaseModel``.
     """
     return isinstance(obj, (BaseModel, BaseModelV1))
 
@@ -125,7 +142,7 @@ def pre_init(func: Callable) -> Any:
         # Ideally we would use @model_validator(mode="before") but this would change the
         # order of the validators. See https://github.com/pydantic/pydantic/discussions/7434.
         # So we keep root_validator for backward compatibility.
-        @root_validator(pre=True)
+        @root_validator(pre=True)  # type: ignore[deprecated]
         @wraps(func)
         def wrapper(cls: type[BaseModel], values: dict[str, Any]) -> dict[str, Any]:
             """Decorator to run a function before model initialization.
@@ -262,7 +279,11 @@ def _create_subset_model(
     descriptions: Optional[dict] = None,
     fn_description: Optional[str] = None,
 ) -> type[BaseModel]:
-    """Create subset model using the same pydantic version as the input model."""
+    """Create subset model using the same pydantic version as the input model.
+
+    Returns:
+        The created subset model.
+    """
     if issubclass(model, BaseModelV1):
         return _create_subset_model_v1(
             name,
@@ -299,13 +320,21 @@ def get_fields(model: BaseModelV1) -> dict[str, ModelField]: ...
 def get_fields(
     model: Union[type[Union[BaseModel, BaseModelV1]], BaseModel, BaseModelV1],
 ) -> Union[dict[str, FieldInfoV2], dict[str, ModelField]]:
-    """Get the field names of a Pydantic model."""
-    if hasattr(model, "model_fields"):
-        return model.model_fields
+    """Return the field names of a Pydantic model.
 
-    if hasattr(model, "__fields__"):
+    Args:
+        model: The Pydantic model or instance.
+
+    Raises:
+        TypeError: If the model is not a Pydantic model.
+    """
+    if not isinstance(model, type):
+        model = type(model)
+    if issubclass(model, BaseModel):
+        return model.model_fields
+    if issubclass(model, BaseModelV1):
         return model.__fields__
-    msg = f"Expected a Pydantic model. Got {type(model)}"
+    msg = f"Expected a Pydantic model. Got {model}"
     raise TypeError(msg)
 
 

langchain_core/utils/utils.py

@@ -21,17 +21,14 @@ from langchain_core.utils.pydantic import (
 
 
 def xor_args(*arg_groups: tuple[str, ...]) -> Callable:
-    """Validate specified keyword args are mutually exclusive.".
+    """Validate specified keyword args are mutually exclusive.
 
     Args:
         *arg_groups (tuple[str, ...]): Groups of mutually exclusive keyword args.
 
     Returns:
         Callable: Decorator that validates the specified keyword args
-            are mutually exclusive
-
-    Raises:
-        ValueError: If more than one arg in a group is defined.
+            are mutually exclusive.
     """
 
     def decorator(func: Callable) -> Callable:
@@ -137,7 +134,7 @@ def guard_import(
     try:
         module = importlib.import_module(module_name, package)
     except (ImportError, ModuleNotFoundError) as e:
-        pip_name = pip_name or module_name.split(".")[0].replace("_", "-")
+        pip_name = pip_name or module_name.split(".", maxsplit=1)[0].replace("_", "-")
         msg = (
             f"Could not import {module_name} python package. "
             f"Please install it with `pip install {pip_name}`."
@@ -223,7 +220,7 @@ def _build_model_kwargs(
     values: dict[str, Any],
     all_required_field_names: set[str],
 ) -> dict[str, Any]:
-    """Build "model_kwargs" param from Pydanitc constructor values.
+    """Build "model_kwargs" param from Pydantic constructor values.
 
     Args:
         values: All init args passed in by user.
@@ -381,10 +378,21 @@ def from_env(
         error_message: the error message which will be raised if the key is not found
             and no default value is provided.
             This will be raised as a ValueError.
+
+    Returns:
+        factory method that will look up the value from the environment.
     """
 
     def get_from_env_fn() -> Optional[str]:
-        """Get a value from an environment variable."""
+        """Get a value from an environment variable.
+
+        Raises:
+            ValueError: If the environment variable is not set and no default is
+                provided.
+
+        Returns:
+            The value from the environment.
+        """
         if isinstance(key, (list, tuple)):
             for k in key:
                 if k in os.environ:
@@ -445,7 +453,15 @@ def secret_from_env(
     """
 
     def get_secret_from_env() -> Optional[SecretStr]:
-        """Get a value from an environment variable."""
+        """Get a value from an environment variable.
+
+        Raises:
+            ValueError: If the environment variable is not set and no default is
+                provided.
+
+        Returns:
+            The secret from the environment.
+        """
         if isinstance(key, (list, tuple)):
             for k in key:
                 if k in os.environ:

langchain_core/vectorstores/base.py

@@ -38,6 +38,7 @@ from typing import (
 from pydantic import ConfigDict, Field, model_validator
 from typing_extensions import Self, override
 
+from langchain_core.documents import Document
 from langchain_core.embeddings import Embeddings
 from langchain_core.retrievers import BaseRetriever, LangSmithRetrieverParams
 from langchain_core.runnables.config import run_in_executor
@@ -49,7 +50,6 @@ if TYPE_CHECKING:
         AsyncCallbackManagerForRetrieverRun,
         CallbackManagerForRetrieverRun,
     )
-    from langchain_core.documents import Document
 
 logger = logging.getLogger(__name__)
 
@@ -85,9 +85,6 @@ class VectorStore(ABC):
             ValueError: If the number of ids does not match the number of texts.
         """
         if type(self).add_documents != VectorStore.add_documents:
-            # Import document in local scope to avoid circular imports
-            from langchain_core.documents import Document
-
             # This condition is triggered if the subclass has provided
             # an implementation of the upsert method.
             # The existing add_texts
@@ -234,9 +231,6 @@ class VectorStore(ABC):
             # For backward compatibility
             kwargs["ids"] = ids
         if type(self).aadd_documents != VectorStore.aadd_documents:
-            # Import document in local scope to avoid circular imports
-            from langchain_core.documents import Document
-
             # This condition is triggered if the subclass has provided
             # an implementation of the upsert method.
             # The existing add_texts
@@ -270,9 +264,6 @@ class VectorStore(ABC):
 
         Returns:
             List of IDs of the added texts.
-
-        Raises:
-            ValueError: If the number of ids does not match the number of documents.
         """
         if type(self).add_texts != VectorStore.add_texts:
             if "ids" not in kwargs:
@@ -303,9 +294,6 @@ class VectorStore(ABC):
 
         Returns:
             List of IDs of the added texts.
-
-        Raises:
-            ValueError: If the number of IDs does not match the number of documents.
         """
         # If the async method has been overridden, we'll use that.
         if type(self).aadd_texts != VectorStore.aadd_texts:
@@ -435,6 +423,7 @@ class VectorStore(ABC):
         """The 'correct' relevance function.
 
         may differ depending on a few things, including:
+
         - the distance / similarity metric used by the VectorStore
         - the scale of your embeddings (OpenAI's are unit normed. Many others are not!)
         - embedding dimensionality
@@ -969,30 +958,28 @@ class VectorStore(ABC):
             # Retrieve more documents with higher diversity
             # Useful if your dataset has many similar documents
             docsearch.as_retriever(
-                search_type="mmr",
-                search_kwargs={'k': 6, 'lambda_mult': 0.25}
+                search_type="mmr", search_kwargs={"k": 6, "lambda_mult": 0.25}
             )
 
             # Fetch more documents for the MMR algorithm to consider
             # But only return the top 5
             docsearch.as_retriever(
-                search_type="mmr",
-                search_kwargs={'k': 5, 'fetch_k': 50}
+                search_type="mmr", search_kwargs={"k": 5, "fetch_k": 50}
             )
 
             # Only retrieve documents that have a relevance score
             # Above a certain threshold
             docsearch.as_retriever(
                 search_type="similarity_score_threshold",
-                search_kwargs={'score_threshold': 0.8}
+                search_kwargs={"score_threshold": 0.8},
             )
 
             # Only get the single most similar document from the dataset
-            docsearch.as_retriever(search_kwargs={'k': 1})
+            docsearch.as_retriever(search_kwargs={"k": 1})
 
             # Use a filter to only retrieve documents from a specific paper
             docsearch.as_retriever(
-                search_kwargs={'filter': {'paper_title':'GPT-4 Technical Report'}}
+                search_kwargs={"filter": {"paper_title": "GPT-4 Technical Report"}}
             )
 
         """