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

langchain_core/utils/pydantic.py

@@ -5,16 +5,14 @@ from __future__ import annotations
 import inspect
 import textwrap
 import warnings
+from collections.abc import Callable
 from contextlib import nullcontext
 from functools import lru_cache, wraps
 from types import GenericAlias
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
-    Optional,
     TypeVar,
-    Union,
     cast,
     overload,
 )
@@ -57,6 +55,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 +75,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 +99,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 +117,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))
 
@@ -114,10 +129,10 @@ def pre_init(func: Callable) -> Any:
     """Decorator to run a function before model initialization.
 
     Args:
-        func (Callable): The function to run before model initialization.
+        func: The function to run before model initialization.
 
     Returns:
-        Any: The decorated function.
+        The decorated function.
     """
     with warnings.catch_warnings():
         warnings.filterwarnings(action="ignore", category=PydanticDeprecationWarning)
@@ -125,17 +140,17 @@ 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.
 
             Args:
-                cls (Type[BaseModel]): The model class.
-                values (dict[str, Any]): The values to initialize the model with.
+                cls: The model class.
+                values: The values to initialize the model with.
 
             Returns:
-                dict[str, Any]: The values to initialize the model with.
+                The values to initialize the model with.
             """
             # Insert default values
             fields = cls.model_fields
@@ -188,10 +203,10 @@ def _create_subset_model_v1(
     model: type[BaseModelV1],
     field_names: list,
     *,
-    descriptions: Optional[dict] = None,
-    fn_description: Optional[str] = None,
+    descriptions: dict | None = None,
+    fn_description: str | None = None,
 ) -> type[BaseModel]:
-    """Create a pydantic model with only a subset of model's fields."""
+    """Create a Pydantic model with only a subset of model's fields."""
     fields = {}
 
     for field_name in field_names:
@@ -201,7 +216,7 @@ def _create_subset_model_v1(
             # this isn't perfect but should work for most functions
             field.outer_type_
             if field.required and not field.allow_none
-            else Optional[field.outer_type_]
+            else field.outer_type_ | None
         )
         if descriptions and field_name in descriptions:
             field.field_info.description = descriptions[field_name]
@@ -217,10 +232,10 @@ def _create_subset_model_v2(
     model: type[BaseModel],
     field_names: list[str],
     *,
-    descriptions: Optional[dict] = None,
-    fn_description: Optional[str] = None,
+    descriptions: dict | None = None,
+    fn_description: str | None = None,
 ) -> type[BaseModel]:
-    """Create a pydantic model with a subset of the model fields."""
+    """Create a Pydantic model with a subset of the model fields."""
     descriptions_ = descriptions or {}
     fields = {}
     for field_name in field_names:
@@ -259,10 +274,14 @@ def _create_subset_model(
     model: TypeBaseModel,
     field_names: list[str],
     *,
-    descriptions: Optional[dict] = None,
-    fn_description: Optional[str] = None,
+    descriptions: dict | None = None,
+    fn_description: str | None = 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,
@@ -297,15 +316,23 @@ 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
+    model: type[BaseModel | BaseModelV1] | BaseModel | BaseModelV1,
+) -> dict[str, FieldInfoV2] | dict[str, ModelField]:
+    """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)
 
 
@@ -319,7 +346,7 @@ NO_DEFAULT = object()
 def _create_root_model(
     name: str,
     type_: Any,
-    module_name: Optional[str] = None,
+    module_name: str | None = None,
     default_: object = NO_DEFAULT,
 ) -> type[BaseModel]:
     """Create a base class."""
@@ -384,7 +411,7 @@ def _create_root_model_cached(
     model_name: str,
     type_: Any,
     *,
-    module_name: Optional[str] = None,
+    module_name: str | None = None,
     default_: object = NO_DEFAULT,
 ) -> type[BaseModel]:
     return _create_root_model(
@@ -407,13 +434,13 @@ def _create_model_cached(
 
 def create_model(
     model_name: str,
-    module_name: Optional[str] = None,
+    module_name: str | None = None,
     /,
     **field_definitions: Any,
 ) -> type[BaseModel]:
-    """Create a pydantic model with the given field definitions.
+    """Create a Pydantic model with the given field definitions.
 
-    Please use create_model_v2 instead of this function.
+    Please use `create_model_v2` instead of this function.
 
     Args:
         model_name: The name of the model.
@@ -422,7 +449,7 @@ def create_model(
         **field_definitions: The field definitions for the model.
 
     Returns:
-        Type[BaseModel]: The created model.
+        The created model.
     """
     kwargs = {}
     if "__root__" in field_definitions:
@@ -480,11 +507,11 @@ def _remap_field_definitions(field_definitions: dict[str, Any]) -> dict[str, Any
 def create_model_v2(
     model_name: str,
     *,
-    module_name: Optional[str] = None,
-    field_definitions: Optional[dict[str, Any]] = None,
-    root: Optional[Any] = None,
+    module_name: str | None = None,
+    field_definitions: dict[str, Any] | None = None,
+    root: Any | None = None,
 ) -> type[BaseModel]:
-    """Create a pydantic model with the given field definitions.
+    """Create a Pydantic model with the given field definitions.
 
     Attention:
         Please do not use outside of langchain packages. This API
@@ -495,10 +522,10 @@ def create_model_v2(
         module_name: The name of the module where the model is defined.
             This is used by Pydantic to resolve any forward references.
         field_definitions: The field definitions for the model.
-        root: Type for a root model (RootModel)
+        root: Type for a root model (`RootModel`)
 
     Returns:
-        Type[BaseModel]: The created model.
+        The created model.
     """
     field_definitions = field_definitions or {}
 

langchain_core/utils/strings.py

@@ -10,7 +10,7 @@ def stringify_value(val: Any) -> str:
         val: The value to stringify.
 
     Returns:
-        str: The stringified value.
+        The stringified value.
     """
     if isinstance(val, str):
         return val
@@ -28,7 +28,7 @@ def stringify_dict(data: dict) -> str:
         data: The dictionary to stringify.
 
     Returns:
-        str: The stringified dictionary.
+        The stringified dictionary.
     """
     text = ""
     for key, value in data.items():
@@ -43,7 +43,7 @@ def comma_list(items: list[Any]) -> str:
         items: The list to convert.
 
     Returns:
-        str: The comma-separated string.
+        The comma-separated string.
     """
     return ", ".join(str(item) for item in items)
 
@@ -57,10 +57,10 @@ def sanitize_for_postgres(text: str, replacement: str = "") -> str:
 
     Args:
         text: The text to sanitize.
-        replacement: String to replace NUL bytes with. Defaults to empty string.
+        replacement: String to replace NUL bytes with.
 
     Returns:
-        str: The sanitized text with NUL bytes removed or replaced.
+        The sanitized text with NUL bytes removed or replaced.
 
     Example:
         >>> sanitize_for_postgres("Hello\\x00world")

langchain_core/utils/usage.py

@@ -1,6 +1,6 @@
 """Usage utilities."""
 
-from typing import Callable
+from collections.abc import Callable
 
 
 def _dict_int_op(

langchain_core/utils/utils.py

@@ -6,9 +6,10 @@ import functools
 import importlib
 import os
 import warnings
-from collections.abc import Iterator, Sequence
+from collections.abc import Callable, Iterator, Sequence
 from importlib.metadata import version
-from typing import Any, Callable, Optional, Union, overload
+from typing import Any, overload
+from uuid import uuid4
 
 from packaging.version import parse
 from pydantic import SecretStr
@@ -21,17 +22,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.
+        *arg_groups: 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.
+        Decorator that validates the specified keyword args
+        are mutually exclusive.
     """
 
     def decorator(func: Callable) -> Callable:
@@ -62,7 +60,7 @@ def raise_for_status_with_text(response: Response) -> None:
     """Raise an error with the response text.
 
     Args:
-        response (Response): The response to check for errors.
+        response: The response to check for errors.
 
     Raises:
         ValueError: If the response has an error status code.
@@ -81,11 +79,13 @@ def mock_now(dt_value: datetime.datetime) -> Iterator[type]:
         dt_value: The datetime value to use for datetime.now().
 
     Yields:
-        datetime.datetime: The mocked datetime class.
+        The mocked datetime class.
 
     Example:
-    with mock_now(datetime.datetime(2011, 2, 3, 10, 11)):
-        assert datetime.datetime.now() == datetime.datetime(2011, 2, 3, 10, 11)
+        ```python
+        with mock_now(datetime.datetime(2011, 2, 3, 10, 11)):
+            assert datetime.datetime.now() == datetime.datetime(2011, 2, 3, 10, 11)
+        ```
     """
 
     class MockDateTime(datetime.datetime):
@@ -93,7 +93,7 @@ def mock_now(dt_value: datetime.datetime) -> Iterator[type]:
 
         @classmethod
         @override
-        def now(cls, tz: Union[datetime.tzinfo, None] = None) -> "MockDateTime":
+        def now(cls, tz: datetime.tzinfo | None = None) -> "MockDateTime":
             # Create a copy of dt_value.
             return MockDateTime(
                 dt_value.year,
@@ -115,21 +115,19 @@ def mock_now(dt_value: datetime.datetime) -> Iterator[type]:
 
 
 def guard_import(
-    module_name: str, *, pip_name: Optional[str] = None, package: Optional[str] = None
+    module_name: str, *, pip_name: str | None = None, package: str | None = None
 ) -> Any:
     """Dynamically import a module.
 
     Raise an exception if the module is not installed.
 
     Args:
-        module_name (str): The name of the module to import.
-        pip_name (str, optional): The name of the module to install with pip.
-            Defaults to None.
-        package (str, optional): The package to import the module from.
-            Defaults to None.
+        module_name: The name of the module to import.
+        pip_name: The name of the module to install with pip.
+        package: The package to import the module from.
 
     Returns:
-        Any: The imported module.
+        The imported module.
 
     Raises:
         ImportError: If the module is not installed.
@@ -137,7 +135,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}`."
@@ -148,23 +146,20 @@ def guard_import(
 
 def check_package_version(
     package: str,
-    lt_version: Optional[str] = None,
-    lte_version: Optional[str] = None,
-    gt_version: Optional[str] = None,
-    gte_version: Optional[str] = None,
+    lt_version: str | None = None,
+    lte_version: str | None = None,
+    gt_version: str | None = None,
+    gte_version: str | None = None,
 ) -> None:
     """Check the version of a package.
 
     Args:
-        package (str): The name of the package.
-        lt_version (str, optional): The version must be less than this.
-            Defaults to None.
-        lte_version (str, optional): The version must be less than or equal to this.
-            Defaults to None.
-        gt_version (str, optional): The version must be greater than this.
-            Defaults to None.
-        gte_version (str, optional): The version must be greater than or equal to this.
-            Defaults to None.
+        package: The name of the package.
+        lt_version: The version must be less than this.
+        lte_version: The version must be less than or equal to this.
+        gt_version: The version must be greater than this.
+        gte_version: The version must be greater than or equal to this.
+
 
     Raises:
         ValueError: If the package version does not meet the requirements.
@@ -203,7 +198,7 @@ def get_pydantic_field_names(pydantic_cls: Any) -> set[str]:
         pydantic_cls: Pydantic class.
 
     Returns:
-        set[str]: Field names.
+        Field names.
     """
     all_required_field_names = set()
     if is_pydantic_v1_subclass(pydantic_cls):
@@ -223,14 +218,14 @@ 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.
         all_required_field_names: All required field names for the pydantic class.
 
     Returns:
-        dict[str, Any]: Extra kwargs.
+        Extra kwargs.
 
     Raises:
         ValueError: If a field is specified in both values and extra_kwargs.
@@ -278,7 +273,7 @@ def build_extra_kwargs(
         all_required_field_names: All required field names for the pydantic class.
 
     Returns:
-        dict[str, Any]: Extra kwargs.
+        Extra kwargs.
 
     Raises:
         ValueError: If a field is specified in both values and extra_kwargs.
@@ -308,14 +303,14 @@ def build_extra_kwargs(
     return extra_kwargs
 
 
-def convert_to_secret_str(value: Union[SecretStr, str]) -> SecretStr:
+def convert_to_secret_str(value: SecretStr | str) -> SecretStr:
     """Convert a string to a SecretStr if needed.
 
     Args:
-        value (Union[SecretStr, str]): The value to convert.
+        value: The value to convert.
 
     Returns:
-        SecretStr: The SecretStr value.
+        The SecretStr value.
     """
     if isinstance(value, SecretStr):
         return value
@@ -347,29 +342,29 @@ def from_env(key: str, /, *, error_message: str) -> Callable[[], str]: ...
 
 @overload
 def from_env(
-    key: Union[str, Sequence[str]], /, *, default: str, error_message: Optional[str]
+    key: str | Sequence[str], /, *, default: str, error_message: str | None
 ) -> Callable[[], str]: ...
 
 
 @overload
 def from_env(
-    key: str, /, *, default: None, error_message: Optional[str]
-) -> Callable[[], Optional[str]]: ...
+    key: str, /, *, default: None, error_message: str | None
+) -> Callable[[], str | None]: ...
 
 
 @overload
 def from_env(
-    key: Union[str, Sequence[str]], /, *, default: None
-) -> Callable[[], Optional[str]]: ...
+    key: str | Sequence[str], /, *, default: None
+) -> Callable[[], str | None]: ...
 
 
 def from_env(
-    key: Union[str, Sequence[str]],
+    key: str | Sequence[str],
     /,
     *,
-    default: Union[str, _NoDefaultType, None] = _NoDefault,
-    error_message: Optional[str] = None,
-) -> Union[Callable[[], str], Callable[[], Optional[str]]]:
+    default: str | _NoDefaultType | None = _NoDefault,
+    error_message: str | None = None,
+) -> Callable[[], str] | Callable[[], str | None]:
     """Create a factory method that gets a value from an environment variable.
 
     Args:
@@ -381,10 +376,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."""
+    def get_from_env_fn() -> str | None:
+        """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:
@@ -407,7 +413,7 @@ def from_env(
 
 
 @overload
-def secret_from_env(key: Union[str, Sequence[str]], /) -> Callable[[], SecretStr]: ...
+def secret_from_env(key: str | Sequence[str], /) -> Callable[[], SecretStr]: ...
 
 
 @overload
@@ -416,8 +422,8 @@ def secret_from_env(key: str, /, *, default: str) -> Callable[[], SecretStr]: ..
 
 @overload
 def secret_from_env(
-    key: Union[str, Sequence[str]], /, *, default: None
-) -> Callable[[], Optional[SecretStr]]: ...
+    key: str | Sequence[str], /, *, default: None
+) -> Callable[[], SecretStr | None]: ...
 
 
 @overload
@@ -425,12 +431,12 @@ def secret_from_env(key: str, /, *, error_message: str) -> Callable[[], SecretSt
 
 
 def secret_from_env(
-    key: Union[str, Sequence[str]],
+    key: str | Sequence[str],
     /,
     *,
-    default: Union[str, _NoDefaultType, None] = _NoDefault,
-    error_message: Optional[str] = None,
-) -> Union[Callable[[], Optional[SecretStr]], Callable[[], SecretStr]]:
+    default: str | _NoDefaultType | None = _NoDefault,
+    error_message: str | None = None,
+) -> Callable[[], SecretStr | None] | Callable[[], SecretStr]:
     """Secret from env.
 
     Args:
@@ -444,8 +450,16 @@ def secret_from_env(
         factory method that will look up the secret from the environment.
     """
 
-    def get_secret_from_env() -> Optional[SecretStr]:
-        """Get a value from an environment variable."""
+    def get_secret_from_env() -> SecretStr | None:
+        """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:
@@ -466,3 +480,31 @@ def secret_from_env(
         raise ValueError(msg)
 
     return get_secret_from_env
+
+
+LC_AUTO_PREFIX = "lc_"
+"""LangChain auto-generated ID prefix for messages and content blocks."""
+
+LC_ID_PREFIX = "lc_run-"
+"""Internal tracing/callback system identifier.
+
+Used for:
+- Tracing. Every LangChain operation (LLM call, chain execution, tool use, etc.)
+  gets a unique run_id (UUID)
+- Enables tracking parent-child relationships between operations
+"""
+
+
+def ensure_id(id_val: str | None) -> str:
+    """Ensure the ID is a valid string, generating a new UUID if not provided.
+
+    Auto-generated UUIDs are prefixed by `'lc_'` to indicate they are
+    LangChain-generated IDs.
+
+    Args:
+        id_val: Optional string ID value to validate.
+
+    Returns:
+        A string ID, either the validated provided value or a newly generated UUID4.
+    """
+    return id_val or f"{LC_AUTO_PREFIX}{uuid4()}"