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

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:
@@ -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)
@@ -671,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"
@@ -681,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.",
@@ -696,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)]

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

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))
 
@@ -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,7 +320,14 @@ 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."""
+    """Return the field names of a Pydantic model.
+
+    Args:
+        model: The Pydantic model or instance.
+
+    Raises:
+        TypeError: If the model is not a Pydantic model.
+    """
     if hasattr(model, "model_fields"):
         return model.model_fields
 

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}`."
@@ -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"}}
             )
 
         """