langchain-core 1.0.0a6__py3-none-any.whl → 1.0.4__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,23 +4,21 @@ 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,
 )
 
@@ -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,24 @@
 """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
+    [`langchain` library](https://pypi.org/project/langchain/), 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/
+    See docs on [building agents](https://docs.langchain.com/oss/python/langchain/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 +28,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,46 +48,46 @@ 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.
-    This log can be used in a few ways. First, it can be used to audit
-    what exactly the LLM predicted to lead to this (tool, tool_input).
-    Second, it can be used in future iterations to show the LLMs prior
-    thoughts. This is useful when (tool, tool_input) does not contain
-    full information about the LLM prediction (for example, any `thought`
-    before the tool/tool_input)."""
+
+    This log can be used in a few ways. First, it can be used to audit what exactly the
+    LLM predicted to lead to this `(tool, tool_input)`.
+
+    Second, it can be used in future iterations to show the LLMs prior thoughts. This is
+    useful when `(tool, tool_input)` does not contain full information about the LLM
+    prediction (for example, any `thought` before the tool/tool_input).
+    """
     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
-    ):
-        """Create an AgentAction.
+    def __init__(self, tool: str, tool_input: str | dict, log: str, **kwargs: Any):
+        """Create an `AgentAction`.
 
         Args:
             tool: The name of the tool to execute.
-            tool_input: The input to pass in to the Tool.
+            tool_input: The input to pass in to the `Tool`.
             log: Additional information to log about the action.
         """
         super().__init__(tool=tool, tool_input=tool_input, log=log, **kwargs)
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """AgentAction is serializable.
+        """`AgentAction` is serializable.
 
         Returns:
-            True
+            `True`
         """
         return True
 
     @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"]
 
@@ -100,19 +100,23 @@ class AgentAction(Serializable):
 class AgentActionMessageLog(AgentAction):
     """Representation of an action to be executed by an agent.
 
-    This is similar to AgentAction, but includes a message log consisting of
-    chat messages. This is useful when working with ChatModels, and is used
-    to reconstruct conversation history from the agent's perspective.
+    This is similar to `AgentAction`, but includes a message log consisting of
+    chat messages.
+
+    This is useful when working with `ChatModels`, and is used to reconstruct
+    conversation history from the agent's perspective.
     """
 
     message_log: Sequence[BaseMessage]
-    """Similar to log, this can be used to pass along extra
-    information about what exact messages were predicted by the LLM
-    before parsing out the (tool, tool_input). This is again useful
-    if (tool, tool_input) cannot be used to fully recreate the LLM
-    prediction, and you need that LLM prediction (for future agent iteration).
+    """Similar to log, this can be used to pass along extra information about what exact
+    messages were predicted by the LLM before parsing out the `(tool, tool_input)`.
+
+    This is again useful 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.
@@ -120,12 +124,12 @@ class AgentActionMessageLog(AgentAction):
 
 
 class AgentStep(Serializable):
-    """Result of running an AgentAction."""
+    """Result of running an `AgentAction`."""
 
     action: AgentAction
-    """The AgentAction that was executed."""
+    """The `AgentAction` that was executed."""
     observation: Any
-    """The result of the AgentAction."""
+    """The result of the `AgentAction`."""
 
     @property
     def messages(self) -> Sequence[BaseMessage]:
@@ -134,19 +138,22 @@ class AgentStep(Serializable):
 
 
 class AgentFinish(Serializable):
-    """Final return value of an ActionAgent.
+    """Final return value of an `ActionAgent`.
 
-    Agents return an AgentFinish when they have reached a stopping condition.
+    Agents return an `AgentFinish` when they have reached a stopping condition.
     """
 
     return_values: dict
     """Dictionary of return values."""
     log: str
     """Additional information to log about the return value.
+
     This is used to pass along the full LLM prediction, not just the parsed out
-    return value. For example, if the full LLM prediction was
-    `Final Answer: 2` you may want to just return `2` as a return value, but pass
-    along the full string as a `log` (for debugging or observability purposes).
+    return value.
+
+    For example, if the full LLM prediction was `Final Answer: 2` you may want to just
+    return `2` as a return value, but pass along the full string as a `log` (for
+    debugging or observability purposes).
     """
     type: Literal["AgentFinish"] = "AgentFinish"
 
@@ -156,15 +163,15 @@ class AgentFinish(Serializable):
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """Return True as this class is serializable."""
+        """Return `True` as this class is serializable."""
         return True
 
     @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"]
 
@@ -204,7 +211,7 @@ def _convert_agent_observation_to_messages(
         observation: Observation to convert to a message.
 
     Returns:
-        AIMessage that corresponds to the original tool invocation.
+        `AIMessage` that corresponds to the original tool invocation.
     """
     if isinstance(agent_action, AgentActionMessageLog):
         return [_create_function_message(agent_action, observation)]
@@ -227,7 +234,7 @@ def _create_function_message(
         observation: the result of the tool invocation.
 
     Returns:
-        FunctionMessage that corresponds to the original tool invocation.
+        `FunctionMessage` that corresponds to the original tool invocation.
     """
     if not isinstance(observation, str):
         try: