langchain-core 0.3.79__py3-none-any.whl → 1.0.0__py3-none-any.whl

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
@@ -24,11 +25,11 @@ def xor_args(*arg_groups: tuple[str, ...]) -> Callable:
     """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.
+        Decorator that validates the specified keyword args
+        are mutually exclusive.
     """
 
     def decorator(func: Callable) -> Callable:
@@ -59,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.
@@ -78,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):
@@ -90,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,
@@ -112,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.
@@ -145,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.
@@ -200,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):
@@ -227,7 +225,7 @@ def _build_model_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.
@@ -275,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.
@@ -305,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
@@ -344,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:
@@ -383,7 +381,7 @@ def from_env(
         factory method that will look up the value from the environment.
     """
 
-    def get_from_env_fn() -> Optional[str]:
+    def get_from_env_fn() -> str | None:
         """Get a value from an environment variable.
 
         Raises:
@@ -415,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
@@ -424,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
@@ -433,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:
@@ -452,7 +450,7 @@ def secret_from_env(
         factory method that will look up the secret from the environment.
     """
 
-    def get_secret_from_env() -> Optional[SecretStr]:
+    def get_secret_from_env() -> SecretStr | None:
         """Get a value from an environment variable.
 
         Raises:
@@ -482,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()}"