langchain-core 1.2.0__tar.gz → 1.2.5__tar.gz

{langchain_core-1.2.0 → langchain_core-1.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-core
-Version: 1.2.0
+Version: 1.2.5
 Summary: Building applications with LLMs through composability
 Project-URL: Homepage, https://docs.langchain.com/
 Project-URL: Documentation, https://reference.langchain.com/python/langchain_core/

{langchain_core-1.2.0 → langchain_core-1.2.5}/langchain_core/_api/deprecation.py

@@ -28,6 +28,27 @@ from pydantic.v1.fields import FieldInfo as FieldInfoV1
 from langchain_core._api.internal import is_caller_internal
 
 
+def _build_deprecation_message(
+    *,
+    alternative: str = "",
+    alternative_import: str = "",
+) -> str:
+    """Build a simple deprecation message for `__deprecated__` attribute.
+
+    Args:
+        alternative: An alternative API name.
+        alternative_import: A fully qualified import path for the alternative.
+
+    Returns:
+        A deprecation message string for IDE/type checker display.
+    """
+    if alternative_import:
+        return f"Use {alternative_import} instead."
+    if alternative:
+        return f"Use {alternative} instead."
+    return "Deprecated."
+
+
 class LangChainDeprecationWarning(DeprecationWarning):
     """A class for issuing deprecation warnings for LangChain users."""
 
@@ -81,60 +102,57 @@ def deprecated(
 ) -> Callable[[T], T]:
     """Decorator to mark a function, a class, or a property as deprecated.
 
-    When deprecating a classmethod, a staticmethod, or a property, the
-    `@deprecated` decorator should go *under* `@classmethod` and
-    `@staticmethod` (i.e., `deprecated` should directly decorate the
-    underlying callable), but *over* `@property`.
+    When deprecating a classmethod, a staticmethod, or a property, the `@deprecated`
+    decorator should go *under* `@classmethod` and `@staticmethod` (i.e., `deprecated`
+    should directly decorate the underlying callable), but *over* `@property`.
 
-    When deprecating a class `C` intended to be used as a base class in a
-    multiple inheritance hierarchy, `C` *must* define an `__init__` method
-    (if `C` instead inherited its `__init__` from its own base class, then
-    `@deprecated` would mess up `__init__` inheritance when installing its
-    own (deprecation-emitting) `C.__init__`).
+    When deprecating a class `C` intended to be used as a base class in a multiple
+    inheritance hierarchy, `C` *must* define an `__init__` method (if `C` instead
+    inherited its `__init__` from its own base class, then `@deprecated` would mess up
+    `__init__` inheritance when installing its own (deprecation-emitting) `C.__init__`).
 
-    Parameters are the same as for `warn_deprecated`, except that *obj_type*
-    defaults to 'class' if decorating a class, 'attribute' if decorating a
-    property, and 'function' otherwise.
+    Parameters are the same as for `warn_deprecated`, except that *obj_type* defaults to
+    'class' if decorating a class, 'attribute' if decorating a property, and 'function'
+    otherwise.
 
     Args:
-        since:
-            The release at which this API became deprecated.
-        message:
-            Override the default deprecation message. The %(since)s,
-            %(name)s, %(alternative)s, %(obj_type)s, %(addendum)s,
-            and %(removal)s format specifiers will be replaced by the
+        since: The release at which this API became deprecated.
+        message: Override the default deprecation message.
+
+            The `%(since)s`, `%(name)s`, `%(alternative)s`, `%(obj_type)s`,
+            `%(addendum)s`, and `%(removal)s` format specifiers will be replaced by the
             values of the respective arguments passed to this function.
-        name:
-            The name of the deprecated object.
-        alternative:
-            An alternative API that the user may use in place of the
-            deprecated API. The deprecation warning will tell the user
-            about this alternative if provided.
-        alternative_import:
-            An alternative import that the user may use instead.
-        pending:
-            If `True`, uses a `PendingDeprecationWarning` instead of a
-            DeprecationWarning. Cannot be used together with removal.
-        obj_type:
-            The object type being deprecated.
-        addendum:
-            Additional text appended directly to the final message.
-        removal:
-            The expected removal version. With the default (an empty
-            string), a removal version is automatically computed from
-            since. Set to other Falsy values to not schedule a removal
-            date. Cannot be used together with pending.
-        package:
-            The package of the deprecated object.
+        name: The name of the deprecated object.
+        alternative: An alternative API that the user may use in place of the deprecated
+            API.
+
+            The deprecation warning will tell the user about this alternative if
+            provided.
+        alternative_import: An alternative import that the user may use instead.
+        pending: If `True`, uses a `PendingDeprecationWarning` instead of a
+            `DeprecationWarning`.
+
+            Cannot be used together with removal.
+        obj_type: The object type being deprecated.
+        addendum: Additional text appended directly to the final message.
+        removal: The expected removal version.
+
+            With the default (an empty string), a removal version is automatically
+            computed from since. Set to other Falsy values to not schedule a removal
+            date.
+
+            Cannot be used together with pending.
+        package: The package of the deprecated object.
 
     Returns:
         A decorator to mark a function or class as deprecated.
 
-    ```python
-    @deprecated("1.4.0")
-    def the_function_to_deprecate():
-        pass
-    ```
+    Example:
+        ```python
+        @deprecated("1.4.0")
+        def the_function_to_deprecate():
+            pass
+        ```
     """
     _validate_deprecation_params(
         removal, alternative, alternative_import, pending=pending
@@ -223,6 +241,11 @@ def deprecated(
                 obj.__init__ = functools.wraps(obj.__init__)(  # type: ignore[misc]
                     warn_if_direct_instance
                 )
+                # Set __deprecated__ for PEP 702 (IDE/type checker support)
+                obj.__deprecated__ = _build_deprecation_message(  # type: ignore[attr-defined]
+                    alternative=alternative,
+                    alternative_import=alternative_import,
+                )
                 return obj
 
         elif isinstance(obj, FieldInfoV1):
@@ -315,12 +338,15 @@ def deprecated(
 
             def finalize(wrapper: Callable[..., Any], new_doc: str) -> T:  # noqa: ARG001
                 """Finalize the property."""
-                return cast(
-                    "T",
-                    _DeprecatedProperty(
-                        fget=obj.fget, fset=obj.fset, fdel=obj.fdel, doc=new_doc
-                    ),
+                prop = _DeprecatedProperty(
+                    fget=obj.fget, fset=obj.fset, fdel=obj.fdel, doc=new_doc
                 )
+                # Set __deprecated__ for PEP 702 (IDE/type checker support)
+                prop.__deprecated__ = _build_deprecation_message(  # type: ignore[attr-defined]
+                    alternative=alternative,
+                    alternative_import=alternative_import,
+                )
+                return cast("T", prop)
 
         else:
             _name = _name or cast("type | Callable", obj).__qualname__
@@ -343,6 +369,11 @@ def deprecated(
                 """
                 wrapper = functools.wraps(wrapped)(wrapper)
                 wrapper.__doc__ = new_doc
+                # Set __deprecated__ for PEP 702 (IDE/type checker support)
+                wrapper.__deprecated__ = _build_deprecation_message(  # type: ignore[attr-defined]
+                    alternative=alternative,
+                    alternative_import=alternative_import,
+                )
                 return cast("T", wrapper)
 
         old_doc = inspect.cleandoc(old_doc or "").strip("\n")
@@ -398,7 +429,7 @@ def deprecated(
 
 @contextlib.contextmanager
 def suppress_langchain_deprecation_warning() -> Generator[None, None, None]:
-    """Context manager to suppress LangChainDeprecationWarning."""
+    """Context manager to suppress `LangChainDeprecationWarning`."""
     with warnings.catch_warnings():
         warnings.simplefilter("ignore", LangChainDeprecationWarning)
         warnings.simplefilter("ignore", LangChainPendingDeprecationWarning)
@@ -421,35 +452,33 @@ def warn_deprecated(
     """Display a standardized deprecation.
 
     Args:
-        since:
-            The release at which this API became deprecated.
-        message:
-            Override the default deprecation message. The %(since)s,
-            %(name)s, %(alternative)s, %(obj_type)s, %(addendum)s,
-            and %(removal)s format specifiers will be replaced by the
+        since: The release at which this API became deprecated.
+        message: Override the default deprecation message.
+
+            The `%(since)s`, `%(name)s`, `%(alternative)s`, `%(obj_type)s`,
+            `%(addendum)s`, and `%(removal)s` format specifiers will be replaced by the
             values of the respective arguments passed to this function.
-        name:
-            The name of the deprecated object.
-        alternative:
-            An alternative API that the user may use in place of the
-            deprecated API. The deprecation warning will tell the user
-            about this alternative if provided.
-        alternative_import:
-            An alternative import that the user may use instead.
-        pending:
-            If `True`, uses a `PendingDeprecationWarning` instead of a
-            DeprecationWarning. Cannot be used together with removal.
-        obj_type:
-            The object type being deprecated.
-        addendum:
-            Additional text appended directly to the final message.
-        removal:
-            The expected removal version. With the default (an empty
-            string), a removal version is automatically computed from
-            since. Set to other Falsy values to not schedule a removal
-            date. Cannot be used together with pending.
-        package:
-            The package of the deprecated object.
+        name: The name of the deprecated object.
+        alternative: An alternative API that the user may use in place of the
+            deprecated API.
+
+            The deprecation warning will tell the user about this alternative if
+            provided.
+        alternative_import: An alternative import that the user may use instead.
+        pending: If `True`, uses a `PendingDeprecationWarning` instead of a
+            `DeprecationWarning`.
+
+            Cannot be used together with removal.
+        obj_type: The object type being deprecated.
+        addendum: Additional text appended directly to the final message.
+        removal: The expected removal version.
+
+            With the default (an empty string), a removal version is automatically
+            computed from since. Set to other Falsy values to not schedule a removal
+            date.
+
+            Cannot be used together with pending.
+        package: The package of the deprecated object.
     """
     if not pending:
         if not removal:
@@ -534,8 +563,8 @@ def rename_parameter(
     """Decorator indicating that parameter *old* of *func* is renamed to *new*.
 
     The actual implementation of *func* should use *new*, not *old*. If *old* is passed
-    to *func*, a DeprecationWarning is emitted, and its value is used, even if *new* is
-    also passed by keyword.
+    to *func*, a `DeprecationWarning` is emitted, and its value is used, even if *new*
+    is also passed by keyword.
 
     Args:
         since: The version in which the parameter was renamed.

{langchain_core-1.2.0 → langchain_core-1.2.5}/langchain_core/example_selectors/length_based.py

@@ -11,7 +11,7 @@ from langchain_core.prompts.prompt import PromptTemplate
 
 
 def _get_length_based(text: str) -> int:
-    return len(re.split("\n| ", text))
+    return len(re.split(r"\n| ", text))
 
 
 class LengthBasedExampleSelector(BaseExampleSelector, BaseModel):

{langchain_core-1.2.0 → langchain_core-1.2.5}/langchain_core/language_models/chat_models.py

@@ -547,7 +547,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
                         ):
                             if block["type"] != index_type:
                                 index_type = block["type"]
-                                index = index + 1
+                                index += 1
                             if "index" not in block:
                                 block["index"] = index
                     run_manager.on_llm_new_token(
@@ -679,7 +679,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
                     ):
                         if block["type"] != index_type:
                             index_type = block["type"]
-                            index = index + 1
+                            index += 1
                         if "index" not in block:
                             block["index"] = index
                 await run_manager.on_llm_new_token(
@@ -730,7 +730,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
 
     # --- Custom methods ---
 
-    def _combine_llm_outputs(self, llm_outputs: list[dict | None]) -> dict:  # noqa: ARG002
+    def _combine_llm_outputs(self, _llm_outputs: list[dict | None], /) -> dict:
         return {}
 
     def _convert_cached_generations(self, cache_val: list) -> list[ChatGeneration]:
@@ -1187,7 +1187,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
                     ):
                         if block["type"] != index_type:
                             index_type = block["type"]
-                            index = index + 1
+                            index += 1
                         if "index" not in block:
                             block["index"] = index
                 if run_manager:
@@ -1305,7 +1305,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC):
                     ):
                         if block["type"] != index_type:
                             index_type = block["type"]
-                            index = index + 1
+                            index += 1
                         if "index" not in block:
                             block["index"] = index
                 if run_manager:

{langchain_core-1.2.0 → langchain_core-1.2.5}/langchain_core/load/__init__.py

@@ -6,7 +6,7 @@ from langchain_core._import_utils import import_attr
 
 if TYPE_CHECKING:
     from langchain_core.load.dump import dumpd, dumps
-    from langchain_core.load.load import loads
+    from langchain_core.load.load import InitValidator, loads
     from langchain_core.load.serializable import Serializable
 
 # Unfortunately, we have to eagerly import load from langchain_core/load/load.py
@@ -15,11 +15,19 @@ if TYPE_CHECKING:
 # the `from langchain_core.load.load import load` absolute import should also work.
 from langchain_core.load.load import load
 
-__all__ = ("Serializable", "dumpd", "dumps", "load", "loads")
+__all__ = (
+    "InitValidator",
+    "Serializable",
+    "dumpd",
+    "dumps",
+    "load",
+    "loads",
+)
 
 _dynamic_imports = {
     "dumpd": "dump",
     "dumps": "dump",
+    "InitValidator": "load",
     "loads": "load",
     "Serializable": "serializable",
 }

langchain_core-1.2.5/langchain_core/load/_validation.py

@@ -0,0 +1,176 @@
+"""Validation utilities for LangChain serialization.
+
+Provides escape-based protection against injection attacks in serialized objects. The
+approach uses an allowlist design: only dicts explicitly produced by
+`Serializable.to_json()` are treated as LC objects during deserialization.
+
+## How escaping works
+
+During serialization, plain dicts (user data) that contain an `'lc'` key are wrapped:
+
+```python
+{"lc": 1, ...}  # user data that looks like LC object
+# becomes:
+{"__lc_escaped__": {"lc": 1, ...}}
+```
+
+During deserialization, escaped dicts are unwrapped and returned as plain dicts,
+NOT instantiated as LC objects.
+"""
+
+from typing import Any
+
+_LC_ESCAPED_KEY = "__lc_escaped__"
+"""Sentinel key used to mark escaped user dicts during serialization.
+
+When a plain dict contains 'lc' key (which could be confused with LC objects),
+we wrap it as {"__lc_escaped__": {...original...}}.
+"""
+
+
+def _needs_escaping(obj: dict[str, Any]) -> bool:
+    """Check if a dict needs escaping to prevent confusion with LC objects.
+
+    A dict needs escaping if:
+
+    1. It has an `'lc'` key (could be confused with LC serialization format)
+    2. It has only the escape key (would be mistaken for an escaped dict)
+    """
+    return "lc" in obj or (len(obj) == 1 and _LC_ESCAPED_KEY in obj)
+
+
+def _escape_dict(obj: dict[str, Any]) -> dict[str, Any]:
+    """Wrap a dict in the escape marker.
+
+    Example:
+        ```python
+        {"key": "value"}  # becomes {"__lc_escaped__": {"key": "value"}}
+        ```
+    """
+    return {_LC_ESCAPED_KEY: obj}
+
+
+def _is_escaped_dict(obj: dict[str, Any]) -> bool:
+    """Check if a dict is an escaped user dict.
+
+    Example:
+        ```python
+        {"__lc_escaped__": {...}}  # is an escaped dict
+        ```
+    """
+    return len(obj) == 1 and _LC_ESCAPED_KEY in obj
+
+
+def _serialize_value(obj: Any) -> Any:
+    """Serialize a value with escaping of user dicts.
+
+    Called recursively on kwarg values to escape any plain dicts that could be confused
+    with LC objects.
+
+    Args:
+        obj: The value to serialize.
+
+    Returns:
+        The serialized value with user dicts escaped as needed.
+    """
+    from langchain_core.load.serializable import (  # noqa: PLC0415
+        Serializable,
+        to_json_not_implemented,
+    )
+
+    if isinstance(obj, Serializable):
+        # This is an LC object - serialize it properly (not escaped)
+        return _serialize_lc_object(obj)
+    if isinstance(obj, dict):
+        if not all(isinstance(k, (str, int, float, bool, type(None))) for k in obj):
+            # if keys are not json serializable
+            return to_json_not_implemented(obj)
+        # Check if dict needs escaping BEFORE recursing into values.
+        # If it needs escaping, wrap it as-is - the contents are user data that
+        # will be returned as-is during deserialization (no instantiation).
+        # This prevents re-escaping of already-escaped nested content.
+        if _needs_escaping(obj):
+            return _escape_dict(obj)
+        # Safe dict (no 'lc' key) - recurse into values
+        return {k: _serialize_value(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_serialize_value(item) for item in obj]
+    if isinstance(obj, (str, int, float, bool, type(None))):
+        return obj
+
+    # Non-JSON-serializable object (datetime, custom objects, etc.)
+    return to_json_not_implemented(obj)
+
+
+def _is_lc_secret(obj: Any) -> bool:
+    """Check if an object is a LangChain secret marker."""
+    expected_num_keys = 3
+    return (
+        isinstance(obj, dict)
+        and obj.get("lc") == 1
+        and obj.get("type") == "secret"
+        and "id" in obj
+        and len(obj) == expected_num_keys
+    )
+
+
+def _serialize_lc_object(obj: Any) -> dict[str, Any]:
+    """Serialize a `Serializable` object with escaping of user data in kwargs.
+
+    Args:
+        obj: The `Serializable` object to serialize.
+
+    Returns:
+        The serialized dict with user data in kwargs escaped as needed.
+
+    Note:
+        Kwargs values are processed with `_serialize_value` to escape user data (like
+        metadata) that contains `'lc'` keys. Secret fields (from `lc_secrets`) are
+        skipped because `to_json()` replaces their values with secret markers.
+    """
+    from langchain_core.load.serializable import Serializable  # noqa: PLC0415
+
+    if not isinstance(obj, Serializable):
+        msg = f"Expected Serializable, got {type(obj)}"
+        raise TypeError(msg)
+
+    serialized: dict[str, Any] = dict(obj.to_json())
+
+    # Process kwargs to escape user data that could be confused with LC objects
+    # Skip secret fields - to_json() already converted them to secret markers
+    if serialized.get("type") == "constructor" and "kwargs" in serialized:
+        serialized["kwargs"] = {
+            k: v if _is_lc_secret(v) else _serialize_value(v)
+            for k, v in serialized["kwargs"].items()
+        }
+
+    return serialized
+
+
+def _unescape_value(obj: Any) -> Any:
+    """Unescape a value, processing escape markers in dict values and lists.
+
+    When an escaped dict is encountered (`{"__lc_escaped__": ...}`), it's
+    unwrapped and the contents are returned AS-IS (no further processing).
+    The contents represent user data that should not be modified.
+
+    For regular dicts and lists, we recurse to find any nested escape markers.
+
+    Args:
+        obj: The value to unescape.
+
+    Returns:
+        The unescaped value.
+    """
+    if isinstance(obj, dict):
+        if _is_escaped_dict(obj):
+            # Unwrap and return the user data as-is (no further unescaping).
+            # The contents are user data that may contain more escape keys,
+            # but those are part of the user's actual data.
+            return obj[_LC_ESCAPED_KEY]
+
+        # Regular dict - recurse into values to find nested escape markers
+        return {k: _unescape_value(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_unescape_value(item) for item in obj]
+    return obj

langchain_core-1.2.5/langchain_core/load/dump.py

@@ -0,0 +1,120 @@
+"""Serialize LangChain objects to JSON.
+
+Provides `dumps` (to JSON string) and `dumpd` (to dict) for serializing
+`Serializable` objects.
+
+## Escaping
+
+During serialization, plain dicts (user data) that contain an `'lc'` key are escaped
+by wrapping them: `{"__lc_escaped__": {...original...}}`. This prevents injection
+attacks where malicious data could trick the deserializer into instantiating
+arbitrary classes. The escape marker is removed during deserialization.
+
+This is an allowlist approach: only dicts explicitly produced by
+`Serializable.to_json()` are treated as LC objects; everything else is escaped if it
+could be confused with the LC format.
+"""
+
+import json
+from typing import Any
+
+from pydantic import BaseModel
+
+from langchain_core.load._validation import _serialize_value
+from langchain_core.load.serializable import Serializable, to_json_not_implemented
+from langchain_core.messages import AIMessage
+from langchain_core.outputs import ChatGeneration
+
+
+def default(obj: Any) -> Any:
+    """Return a default value for an object.
+
+    Args:
+        obj: The object to serialize to json if it is a Serializable object.
+
+    Returns:
+        A JSON serializable object or a SerializedNotImplemented object.
+    """
+    if isinstance(obj, Serializable):
+        return obj.to_json()
+    return to_json_not_implemented(obj)
+
+
+def _dump_pydantic_models(obj: Any) -> Any:
+    """Convert nested Pydantic models to dicts for JSON serialization.
+
+    Handles the special case where a `ChatGeneration` contains an `AIMessage`
+    with a parsed Pydantic model in `additional_kwargs["parsed"]`. Since
+    Pydantic models aren't directly JSON serializable, this converts them to
+    dicts.
+
+    Args:
+        obj: The object to process.
+
+    Returns:
+        A copy of the object with nested Pydantic models converted to dicts, or
+            the original object unchanged if no conversion was needed.
+    """
+    if (
+        isinstance(obj, ChatGeneration)
+        and isinstance(obj.message, AIMessage)
+        and (parsed := obj.message.additional_kwargs.get("parsed"))
+        and isinstance(parsed, BaseModel)
+    ):
+        obj_copy = obj.model_copy(deep=True)
+        obj_copy.message.additional_kwargs["parsed"] = parsed.model_dump()
+        return obj_copy
+    return obj
+
+
+def dumps(obj: Any, *, pretty: bool = False, **kwargs: Any) -> str:
+    """Return a JSON string representation of an object.
+
+    Note:
+        Plain dicts containing an `'lc'` key are automatically escaped to prevent
+        confusion with LC serialization format. The escape marker is removed during
+        deserialization.
+
+    Args:
+        obj: The object to dump.
+        pretty: Whether to pretty print the json.
+
+            If `True`, the json will be indented by either 2 spaces or the amount
+            provided in the `indent` kwarg.
+        **kwargs: Additional arguments to pass to `json.dumps`
+
+    Returns:
+        A JSON string representation of the object.
+
+    Raises:
+        ValueError: If `default` is passed as a kwarg.
+    """
+    if "default" in kwargs:
+        msg = "`default` should not be passed to dumps"
+        raise ValueError(msg)
+
+    obj = _dump_pydantic_models(obj)
+    serialized = _serialize_value(obj)
+
+    if pretty:
+        indent = kwargs.pop("indent", 2)
+        return json.dumps(serialized, indent=indent, **kwargs)
+    return json.dumps(serialized, **kwargs)
+
+
+def dumpd(obj: Any) -> Any:
+    """Return a dict representation of an object.
+
+    Note:
+        Plain dicts containing an `'lc'` key are automatically escaped to prevent
+        confusion with LC serialization format. The escape marker is removed during
+        deserialization.
+
+    Args:
+        obj: The object to dump.
+
+    Returns:
+        Dictionary that can be serialized to json using `json.dumps`.
+    """
+    obj = _dump_pydantic_models(obj)
+    return _serialize_value(obj)