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

langchain_core/__init__.py

@@ -1,4 +1,4 @@
-"""``langchain-core`` defines the base abstractions for the LangChain ecosystem.
+"""`langchain-core` defines the base abstractions for the LangChain ecosystem.
 
 The interfaces for core components like chat models, LLMs, vector stores, retrievers,
 and more are defined here. The universal invocation protocol (Runnables) along with

langchain_core/_api/__init__.py

@@ -2,11 +2,10 @@
 
 This module is only relevant for LangChain developers, not for users.
 
-.. warning::
-
-    This module and its submodules are for internal use only.  Do not use them
-    in your own code.  We may change the API at any time with no warning.
+!!! warning
 
+    This module and its submodules are for internal use only. Do not use them in your
+    own code.  We may change the API at any time with no warning.
 """
 
 from typing import TYPE_CHECKING

langchain_core/_api/beta_decorator.py

@@ -4,18 +4,18 @@ This module was loosely adapted from matplotlibs _api/deprecation.py module:
 
 https://github.com/matplotlib/matplotlib/blob/main/lib/matplotlib/_api/deprecation.py
 
-.. warning::
+!!! warning
 
-    This module is for internal use only.  Do not use it in your own code.
-    We may change the API at any time with no warning.
+    This module is for internal use only. Do not use it in your own code. We may change
+    the API at any time with no warning.
 """
 
 import contextlib
 import functools
 import inspect
 import warnings
-from collections.abc import Generator
-from typing import Any, Callable, TypeVar, Union, cast
+from collections.abc import Callable, Generator
+from typing import Any, TypeVar, cast
 
 from langchain_core._api.internal import is_caller_internal
 
@@ -27,7 +27,7 @@ class LangChainBetaWarning(DeprecationWarning):
 # PUBLIC API
 
 
-T = TypeVar("T", bound=Union[Callable[..., Any], type])
+T = TypeVar("T", bound=Callable[..., Any] | type)
 
 
 def beta(
@@ -40,40 +40,37 @@ def beta(
     """Decorator to mark a function, a class, or a property as beta.
 
     When marking a classmethod, a staticmethod, or a property, the
-    ``@beta`` decorator should go *under* ``@classmethod`` and
-    ``@staticmethod`` (i.e., `beta` should directly decorate the
-    underlying callable), but *over* ``@property``.
+    `@beta` decorator should go *under* `@classmethod` and
+    `@staticmethod` (i.e., `beta` should directly decorate the
+    underlying callable), but *over* `@property`.
 
-    When marking 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
-    ``@beta`` would mess up ``__init__`` inheritance when installing its
-    own (annotation-emitting) ``C.__init__``).
+    When marking 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
+    `@beta` would mess up `__init__` inheritance when installing its
+    own (annotation-emitting) `C.__init__`).
 
     Args:
-        message : str, optional
+        message:
             Override the default beta 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 : str, optional
+        name:
             The name of the beta object.
-        obj_type : str, optional
+        obj_type:
             The object type being beta.
-        addendum : str, optional
+        addendum:
             Additional text appended directly to the final message.
 
     Returns:
         A decorator which can be used to mark functions or classes as beta.
 
-    Examples:
-
-        .. code-block:: python
-
-            @beta
-            def the_function_to_annotate():
-                pass
-
+    ```python
+    @beta
+    def the_function_to_annotate():
+        pass
+    ```
     """
 
     def beta(

langchain_core/_api/deprecation.py

@@ -4,28 +4,26 @@ This module was adapted from matplotlibs _api/deprecation.py module:
 
 https://github.com/matplotlib/matplotlib/blob/main/lib/matplotlib/_api/deprecation.py
 
-.. warning::
+!!! warning
 
-    This module is for internal use only.  Do not use it in your own code.
-    We may change the API at any time with no warning.
+    This module is for internal use only. Do not use it in your own code. We may change
+    the API at any time with no warning.
 """
 
 import contextlib
 import functools
 import inspect
 import warnings
-from collections.abc import Generator
+from collections.abc import Callable, Generator
 from typing import (
     Any,
-    Callable,
+    ParamSpec,
     TypeVar,
-    Union,
     cast,
 )
 
 from pydantic.fields import FieldInfo
 from pydantic.v1.fields import FieldInfo as FieldInfoV1
-from typing_extensions import ParamSpec
 
 from langchain_core._api.internal import is_caller_internal
 
@@ -42,7 +40,7 @@ class LangChainPendingDeprecationWarning(PendingDeprecationWarning):
 
 
 # Last Any should be FieldInfoV1 but this leads to circular imports
-T = TypeVar("T", bound=Union[type, Callable[..., Any], Any])
+T = TypeVar("T", bound=type | Callable[..., Any] | Any)
 
 
 def _validate_deprecation_params(
@@ -84,62 +82,59 @@ def deprecated(
     """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``.
+    `@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.
 
     Args:
-        since : str
+        since:
             The release at which this API became deprecated.
-        message : str, optional
+        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 : str, optional
+        name:
             The name of the deprecated object.
-        alternative : str, optional
+        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: str, optional
+        alternative_import:
             An alternative import that the user may use instead.
-        pending : bool, optional
-            If True, uses a PendingDeprecationWarning instead of a
+        pending:
+            If `True`, uses a `PendingDeprecationWarning` instead of a
             DeprecationWarning. Cannot be used together with removal.
-        obj_type : str, optional
+        obj_type:
             The object type being deprecated.
-        addendum : str, optional
+        addendum:
             Additional text appended directly to the final message.
-        removal : str, optional
+        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: str, optional
+        package:
             The package of the deprecated object.
 
     Returns:
         A decorator to mark a function or class as deprecated.
 
-    Examples:
-
-        .. code-block:: python
-
-            @deprecated("1.4.0")
-            def the_function_to_deprecate():
-                pass
-
+    ```python
+    @deprecated("1.4.0")
+    def the_function_to_deprecate():
+        pass
+    ```
     """
     _validate_deprecation_params(
         removal, alternative, alternative_import, pending=pending
@@ -276,7 +271,7 @@ def deprecated(
             if not _obj_type:
                 _obj_type = "attribute"
             wrapped = None
-            _name = _name or cast("Union[type, Callable]", obj.fget).__qualname__
+            _name = _name or cast("type | Callable", obj.fget).__qualname__
             old_doc = obj.__doc__
 
             class _DeprecatedProperty(property):
@@ -284,19 +279,17 @@ def deprecated(
 
                 def __init__(
                     self,
-                    fget: Union[Callable[[Any], Any], None] = None,
-                    fset: Union[Callable[[Any, Any], None], None] = None,
-                    fdel: Union[Callable[[Any], None], None] = None,
-                    doc: Union[str, None] = None,
+                    fget: Callable[[Any], Any] | None = None,
+                    fset: Callable[[Any, Any], None] | None = None,
+                    fdel: Callable[[Any], None] | None = None,
+                    doc: str | None = None,
                 ) -> None:
                     super().__init__(fget, fset, fdel, doc)
                     self.__orig_fget = fget
                     self.__orig_fset = fset
                     self.__orig_fdel = fdel
 
-                def __get__(
-                    self, instance: Any, owner: Union[type, None] = None
-                ) -> Any:
+                def __get__(self, instance: Any, owner: type | None = None) -> Any:
                     if instance is not None or owner is not None:
                         emit_warning()
                     if self.fget is None:
@@ -315,7 +308,7 @@ def deprecated(
                     if self.fdel is not None:
                         self.fdel(instance)
 
-                def __set_name__(self, owner: Union[type, None], set_name: str) -> None:
+                def __set_name__(self, owner: type | None, set_name: str) -> None:
                     nonlocal _name
                     if _name == "<lambda>":
                         _name = set_name
@@ -330,7 +323,7 @@ def deprecated(
                 )
 
         else:
-            _name = _name or cast("Union[type, Callable]", obj).__qualname__
+            _name = _name or cast("type | Callable", obj).__qualname__
             if not _obj_type:
                 # edge case: when a function is within another function
                 # within a test, this will call it a "method" not a "function"
@@ -363,24 +356,20 @@ def deprecated(
             _alternative
             and _alternative.rsplit(".", maxsplit=1)[-1].lower()
             == _alternative.rsplit(".", maxsplit=1)[-1]
-        ):
-            _alternative = f":meth:`~{_alternative}`"
-        elif _alternative:
-            _alternative = f":class:`~{_alternative}`"
+        ) or _alternative:
+            _alternative = f"`{_alternative}`"
 
         if (
             _alternative_import
             and _alternative_import.rsplit(".", maxsplit=1)[-1].lower()
             == _alternative_import.rsplit(".", maxsplit=1)[-1]
-        ):
-            _alternative_import = f":meth:`~{_alternative_import}`"
-        elif _alternative_import:
-            _alternative_import = f":class:`~{_alternative_import}`"
+        ) or _alternative_import:
+            _alternative_import = f"`{_alternative_import}`"
 
         components = [
             _message,
             f"Use {_alternative} instead." if _alternative else "",
-            f"Use ``{_alternative_import}`` instead." if _alternative_import else "",
+            f"Use `{_alternative_import}` instead." if _alternative_import else "",
             _addendum,
         ]
         details = " ".join([component.strip() for component in components if component])
@@ -395,7 +384,7 @@ def deprecated(
         else:
             removal_str = ""
         new_doc = f"""\
-.. deprecated:: {since} {details} {removal_str}
+!!! deprecated "{since} {details} {removal_str}"
 
 {old_doc}\
 """
@@ -448,7 +437,7 @@ def warn_deprecated(
         alternative_import:
             An alternative import that the user may use instead.
         pending:
-            If True, uses a PendingDeprecationWarning instead of a
+            If `True`, uses a `PendingDeprecationWarning` instead of a
             DeprecationWarning. Cannot be used together with removal.
         obj_type:
             The object type being deprecated.
@@ -544,9 +533,9 @@ def rename_parameter(
 ) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]:
     """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.
+    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.
 
     Args:
         since: The version in which the parameter was renamed.
@@ -558,12 +547,10 @@ def rename_parameter(
         A decorator indicating that a parameter was renamed.
 
     Example:
-
-        .. code-block:: python
-
-            @_api.rename_parameter("3.1", "bad_name", "good_name")
-            def func(good_name): ...
-
+        ```python
+        @_api.rename_parameter("3.1", "bad_name", "good_name")
+        def func(good_name): ...
+        ```
     """
 
     def decorator(f: Callable[_P, _R]) -> Callable[_P, _R]:

langchain_core/_api/path.py

@@ -1,6 +1,5 @@
 import os
 from pathlib import Path
-from typing import Optional, Union
 
 HERE = Path(__file__).parent
 
@@ -9,9 +8,7 @@ PACKAGE_DIR = HERE.parent
 SEPARATOR = os.sep
 
 
-def get_relative_path(
-    file: Union[Path, str], *, relative_to: Path = PACKAGE_DIR
-) -> str:
+def get_relative_path(file: Path | str, *, relative_to: Path = PACKAGE_DIR) -> str:
     """Get the path of the file as a relative path to the package directory.
 
     Args:
@@ -27,9 +24,9 @@ def get_relative_path(
 
 
 def as_import_path(
-    file: Union[Path, str],
+    file: Path | str,
     *,
-    suffix: Optional[str] = None,
+    suffix: str | None = None,
     relative_to: Path = PACKAGE_DIR,
 ) -> str:
     """Path of the file as a LangChain import exclude langchain top namespace.

langchain_core/_import_utils.py

@@ -1,11 +1,10 @@
 from importlib import import_module
-from typing import Union
 
 
 def import_attr(
     attr_name: str,
-    module_name: Union[str, None],
-    package: Union[str, None],
+    module_name: str | None,
+    package: str | None,
 ) -> object:
     """Import an attribute from a module located in a package.
 
@@ -14,7 +13,7 @@ def import_attr(
 
     Args:
         attr_name: The name of the attribute to import.
-        module_name: The name of the module to import from. If None, the attribute
+        module_name: The name of the module to import from. If `None`, the attribute
             is imported from the package itself.
         package: The name of the package where the module is located.
 

langchain_core/agents.py

@@ -1,24 +1,26 @@
 """Schema definitions for representing agent actions, observations, and return values.
 
-**ATTENTION** The schema definitions are provided for backwards compatibility.
+!!! warning
+    The schema definitions are provided for backwards compatibility.
 
-    New agents should be built using the langgraph library
-    (https://github.com/langchain-ai/langgraph)), which provides a simpler
-    and more flexible way to define agents.
+!!! warning
+    New agents should be built using the
+    [langgraph library](https://github.com/langchain-ai/langgraph), which provides a
+    simpler and more flexible way to define agents.
 
-    Please see the migration guide for information on how to migrate existing
-    agents to modern langgraph agents:
-    https://python.langchain.com/docs/how_to/migrate_agent/
+    Please see the
+    [migration guide](https://python.langchain.com/docs/how_to/migrate_agent/) for
+    information on how to migrate existing agents to modern langgraph agents.
 
 Agents use language models to choose a sequence of actions to take.
 
 A basic agent works in the following manner:
 
 1. Given a prompt an agent uses an LLM to request an action to take
-   (e.g., a tool to run).
+    (e.g., a tool to run).
 2. The agent executes the action (e.g., runs the tool), and receives an observation.
 3. The agent returns the observation to the LLM, which can then be used to generate
-   the next action.
+    the next action.
 4. When the agent reaches a stopping condition, it returns a final return value.
 
 The schemas for the agents themselves are defined in langchain.agents.agent.
@@ -28,7 +30,7 @@ from __future__ import annotations
 
 import json
 from collections.abc import Sequence
-from typing import Any, Literal, Union
+from typing import Any, Literal
 
 from langchain_core.load.serializable import Serializable
 from langchain_core.messages import (
@@ -48,7 +50,7 @@ class AgentAction(Serializable):
 
     tool: str
     """The name of the Tool to execute."""
-    tool_input: Union[str, dict]
+    tool_input: str | dict
     """The input to pass in to the Tool."""
     log: str
     """Additional information to log about the action.
@@ -61,9 +63,7 @@ class AgentAction(Serializable):
     type: Literal["AgentAction"] = "AgentAction"
 
     # Override init to support instantiation by position for backward compat.
-    def __init__(
-        self, tool: str, tool_input: Union[str, dict], log: str, **kwargs: Any
-    ):
+    def __init__(self, tool: str, tool_input: str | dict, log: str, **kwargs: Any):
         """Create an AgentAction.
 
         Args:
@@ -84,10 +84,10 @@ class AgentAction(Serializable):
 
     @classmethod
     def get_lc_namespace(cls) -> list[str]:
-        """Get the namespace of the langchain object.
+        """Get the namespace of the LangChain object.
 
         Returns:
-            ``["langchain", "schema", "agent"]``
+            `["langchain", "schema", "agent"]`
         """
         return ["langchain", "schema", "agent"]
 
@@ -112,7 +112,7 @@ class AgentActionMessageLog(AgentAction):
     if (tool, tool_input) cannot be used to fully recreate the LLM
     prediction, and you need that LLM prediction (for future agent iteration).
     Compared to `log`, this is useful when the underlying LLM is a
-    ChatModel (and therefore returns messages rather than a string)."""
+    chat model (and therefore returns messages rather than a string)."""
     # Ignoring type because we're overriding the type from AgentAction.
     # And this is the correct thing to do in this case.
     # The type literal is used for serialization purposes.
@@ -161,10 +161,10 @@ class AgentFinish(Serializable):
 
     @classmethod
     def get_lc_namespace(cls) -> list[str]:
-        """Get the namespace of the langchain object.
+        """Get the namespace of the LangChain object.
 
         Returns:
-            ``["langchain", "schema", "agent"]``
+            `["langchain", "schema", "agent"]`
         """
         return ["langchain", "schema", "agent"]