langchain-core 0.3.75__py3-none-any.whl → 0.3.76__py3-none-any.whl

langchain_core/_api/beta_decorator.py

@@ -63,6 +63,9 @@ def beta(
         addendum : str, optional
             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
@@ -153,50 +156,24 @@ def beta(
             _name = _name or obj.fget.__qualname__
             old_doc = obj.__doc__
 
-            class _BetaProperty(property):
-                """A beta property."""
-
-                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,
-                ) -> None:
-                    super().__init__(fget, fset, fdel, doc)
-                    self.__orig_fget = fget
-                    self.__orig_fset = fset
-                    self.__orig_fdel = fdel
-                    self.__doc__ = doc
-
-                def __get__(
-                    self, instance: Any, owner: Union[type, None] = None
-                ) -> Any:
-                    if instance is not None or owner is not None:
-                        emit_warning()
-                    return self.fget(instance)
-
-                def __set__(self, instance: Any, value: Any) -> None:
-                    if instance is not None:
-                        emit_warning()
-                    return self.fset(instance, value)
+            def _fget(instance: Any) -> Any:
+                if instance is not None:
+                    emit_warning()
+                return obj.fget(instance)
 
-                def __delete__(self, instance: Any) -> None:
-                    if instance is not None:
-                        emit_warning()
-                    return self.fdel(instance)
+            def _fset(instance: Any, value: Any) -> None:
+                if instance is not None:
+                    emit_warning()
+                obj.fset(instance, value)
 
-                def __set_name__(self, owner: Union[type, None], set_name: str) -> None:
-                    nonlocal _name
-                    if _name == "<lambda>":
-                        _name = set_name
+            def _fdel(instance: Any) -> None:
+                if instance is not None:
+                    emit_warning()
+                obj.fdel(instance)
 
-            def finalize(wrapper: Callable[..., Any], new_doc: str) -> Any:  # noqa: ARG001
+            def finalize(_wrapper: Callable[..., Any], new_doc: str) -> Any:
                 """Finalize the property."""
-                return _BetaProperty(
-                    fget=obj.fget, fset=obj.fset, fdel=obj.fdel, doc=new_doc
-                )
-
+                return property(fget=_fget, fset=_fset, fdel=_fdel, doc=new_doc)
         else:
             _name = _name or obj.__qualname__
             if not _obj_type:

langchain_core/_api/deprecation.py

@@ -129,11 +129,14 @@ def deprecated(
         package: str, optional
             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')
+            @deprecated("1.4.0")
             def the_function_to_deprecate():
                 pass
 
@@ -358,7 +361,8 @@ def deprecated(
         # Modify the docstring to include a deprecation notice.
         if (
             _alternative
-            and _alternative.split(".")[-1].lower() == _alternative.split(".")[-1]
+            and _alternative.rsplit(".", maxsplit=1)[-1].lower()
+            == _alternative.rsplit(".", maxsplit=1)[-1]
         ):
             _alternative = f":meth:`~{_alternative}`"
         elif _alternative:
@@ -366,8 +370,8 @@ def deprecated(
 
         if (
             _alternative_import
-            and _alternative_import.split(".")[-1].lower()
-            == _alternative_import.split(".")[-1]
+            and _alternative_import.rsplit(".", maxsplit=1)[-1].lower()
+            == _alternative_import.rsplit(".", maxsplit=1)[-1]
         ):
             _alternative_import = f":meth:`~{_alternative_import}`"
         elif _alternative_import:
@@ -471,7 +475,7 @@ def warn_deprecated(
     if not message:
         message = ""
         package_ = (
-            package or name.split(".")[0].replace("_", "-")
+            package or name.split(".", maxsplit=1)[0].replace("_", "-")
             if "." in name
             else "LangChain"
         )
@@ -490,7 +494,7 @@ def warn_deprecated(
                 message += f" and will be removed {removal}"
 
         if alternative_import:
-            alt_package = alternative_import.split(".")[0].replace("_", "-")
+            alt_package = alternative_import.split(".", maxsplit=1)[0].replace("_", "-")
             if alt_package == package_:
                 message += f". Use {alternative_import} instead."
             else:
@@ -544,6 +548,15 @@ def rename_parameter(
     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.
+        removal: The version in which the old parameter will be removed.
+        old: The old parameter name.
+        new: The new parameter name.
+
+    Returns:
+        A decorator indicating that a parameter was renamed.
+
     Example:
 
         .. code-block:: python

langchain_core/_api/path.py

@@ -12,7 +12,15 @@ SEPARATOR = os.sep
 def get_relative_path(
     file: Union[Path, str], *, relative_to: Path = PACKAGE_DIR
 ) -> str:
-    """Get the path of the file as a relative path to the package directory."""
+    """Get the path of the file as a relative path to the package directory.
+
+    Args:
+        file: The file path to convert.
+        relative_to: The base path to make the file path relative to.
+
+    Returns:
+        The relative path as a string.
+    """
     if isinstance(file, str):
         file = Path(file)
     return str(file.relative_to(relative_to))
@@ -24,7 +32,16 @@ def as_import_path(
     suffix: Optional[str] = None,
     relative_to: Path = PACKAGE_DIR,
 ) -> str:
-    """Path of the file as a LangChain import exclude langchain top namespace."""
+    """Path of the file as a LangChain import exclude langchain top namespace.
+
+    Args:
+        file: The file path to convert.
+        suffix: An optional suffix to append to the import path.
+        relative_to: The base path to make the file path relative to.
+
+    Returns:
+        The import path as a string.
+    """
     if isinstance(file, str):
         file = Path(file)
     path = get_relative_path(file, relative_to=relative_to)

langchain_core/_import_utils.py

@@ -17,6 +17,13 @@ def import_attr(
         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.
+
+    Raises:
+        ImportError: If the module cannot be found.
+        AttributeError: If the attribute does not exist in the module or package.
+
+    Returns:
+        The imported attribute.
     """
     if module_name == "__module__" or module_name is None:
         try:

langchain_core/agents.py

@@ -14,13 +14,15 @@ 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).
+1. Given a prompt an agent uses an LLM to request an action to take
+   (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.
+3. The agent returns the observation to the LLM, which can then be used to generate
+   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.
-"""  # noqa: E501
+"""
 
 from __future__ import annotations
 
@@ -84,7 +86,8 @@ class AgentAction(Serializable):
     def get_lc_namespace(cls) -> list[str]:
         """Get the namespace of the langchain object.
 
-        Default is ["langchain", "schema", "agent"].
+        Returns:
+            ``["langchain", "schema", "agent"]``
         """
         return ["langchain", "schema", "agent"]
 
@@ -153,14 +156,15 @@ class AgentFinish(Serializable):
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """Return whether or not the 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.
 
-        Default namespace is ["langchain", "schema", "agent"].
+        Returns:
+            ``["langchain", "schema", "agent"]``
         """
         return ["langchain", "schema", "agent"]
 

langchain_core/beta/runnables/context.py

@@ -344,8 +344,7 @@ class Context:
             chain = (
                 Context.setter("input")
                 | {
-                    "context": RunnablePassthrough()
-                            | Context.setter("context"),
+                    "context": RunnablePassthrough() | Context.setter("context"),
                     "question": RunnablePassthrough(),
                 }
                 | PromptTemplate.from_template("{context} {question}")

langchain_core/callbacks/base.py

@@ -922,7 +922,7 @@ class BaseCallbackManager(CallbackManagerMixin):
         self.inheritable_metadata = inheritable_metadata or {}
 
     def copy(self) -> Self:
-        """Copy the callback manager."""
+        """Return a copy of the callback manager."""
         return self.__class__(
             handlers=self.handlers.copy(),
             inheritable_handlers=self.inheritable_handlers.copy(),
@@ -947,11 +947,18 @@ class BaseCallbackManager(CallbackManagerMixin):
 
             .. code-block:: python
 
-                from langchain_core.callbacks.manager import CallbackManager, trace_as_chain_group
+                from langchain_core.callbacks.manager import (
+                    CallbackManager,
+                    trace_as_chain_group,
+                )
                 from langchain_core.callbacks.stdout import StdOutCallbackHandler
 
-                manager = CallbackManager(handlers=[StdOutCallbackHandler()], tags=["tag2"])
-                with trace_as_chain_group("My Group Name", tags=["tag1"]) as group_manager:
+                manager = CallbackManager(
+                    handlers=[StdOutCallbackHandler()], tags=["tag2"]
+                )
+                with trace_as_chain_group(
+                    "My Group Name", tags=["tag1"]
+                ) as group_manager:
                     merged_manager = group_manager.merge(manager)
                     print(merged_manager.handlers)
                     # [

langchain_core/callbacks/manager.py

@@ -28,8 +28,18 @@ from langchain_core.callbacks.base import (
     ToolManagerMixin,
 )
 from langchain_core.callbacks.stdout import StdOutCallbackHandler
+from langchain_core.globals import get_debug
 from langchain_core.messages import BaseMessage, get_buffer_string
+from langchain_core.tracers.context import (
+    _configure_hooks,
+    _get_trace_callbacks,
+    _get_tracer_project,
+    _tracing_v2_is_enabled,
+    tracing_v2_callback_var,
+)
+from langchain_core.tracers.langchain import LangChainTracer
 from langchain_core.tracers.schemas import Run
+from langchain_core.tracers.stdout import ConsoleCallbackHandler
 from langchain_core.utils.env import env_var_is_set
 
 if TYPE_CHECKING:
@@ -46,8 +56,6 @@ logger = logging.getLogger(__name__)
 
 
 def _get_debug() -> bool:
-    from langchain_core.globals import get_debug
-
     return get_debug()
 
 
@@ -85,23 +93,24 @@ def trace_as_chain_group(
             Defaults to None.
 
     .. note:
-        Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in LangSmith.
+        Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in
+        LangSmith.
 
-    Returns:
-        CallbackManagerForChainGroup: The callback manager for the chain group.
+    Yields:
+        The callback manager for the chain group.
 
     Example:
         .. code-block:: python
 
             llm_input = "Foo"
-            with trace_as_chain_group("group_name", inputs={"input": llm_input}) as manager:
+            with trace_as_chain_group(
+                "group_name", inputs={"input": llm_input}
+            ) as manager:
                 # Use the callback manager for the chain group
                 res = llm.invoke(llm_input, {"callbacks": manager})
                 manager.on_chain_end({"output": res})
 
-    """  # noqa: E501
-    from langchain_core.tracers.context import _get_trace_callbacks
-
+    """
     cb = _get_trace_callbacks(
         project_name, example_id, callback_manager=callback_manager
     )
@@ -153,8 +162,8 @@ async def atrace_as_chain_group(
 
     Args:
         group_name (str): The name of the chain group.
-        callback_manager (AsyncCallbackManager, optional): The async callback manager to use,
-            which manages tracing and other callback behavior. Defaults to None.
+        callback_manager (AsyncCallbackManager, optional): The async callback manager
+            to use, which manages tracing and other callback behavior. Defaults to None.
         inputs (dict[str, Any], optional): The inputs to the chain group.
             Defaults to None.
         project_name (str, optional): The name of the project.
@@ -167,24 +176,25 @@ async def atrace_as_chain_group(
         metadata (dict[str, Any], optional): The metadata to apply to all runs.
             Defaults to None.
 
-    Returns:
-        AsyncCallbackManager: The async callback manager for the chain group.
+    Yields:
+        The async callback manager for the chain group.
 
     .. note:
-        Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in LangSmith.
+        Must have ``LANGCHAIN_TRACING_V2`` env var set to true to see the trace in
+        LangSmith.
 
     Example:
         .. code-block:: python
 
             llm_input = "Foo"
-            async with atrace_as_chain_group("group_name", inputs={"input": llm_input}) as manager:
+            async with atrace_as_chain_group(
+                "group_name", inputs={"input": llm_input}
+            ) as manager:
                 # Use the async callback manager for the chain group
                 res = await llm.ainvoke(llm_input, {"callbacks": manager})
                 await manager.on_chain_end({"output": res})
 
-    """  # noqa: E501
-    from langchain_core.tracers.context import _get_trace_callbacks
-
+    """
     cb = _get_trace_callbacks(
         project_name, example_id, callback_manager=callback_manager
     )
@@ -513,15 +523,12 @@ class RunManager(BaseRunManager):
         self,
         text: str,
         **kwargs: Any,
-    ) -> Any:
+    ) -> None:
         """Run when a text is received.
 
         Args:
             text (str): The received text.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
         """
         if not self.handlers:
             return
@@ -601,16 +608,12 @@ class AsyncRunManager(BaseRunManager, ABC):
         self,
         text: str,
         **kwargs: Any,
-    ) -> Any:
+    ) -> None:
         """Run when a text is received.
 
         Args:
             text (str): The received text.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -908,16 +911,12 @@ class CallbackManagerForChainRun(ParentRunManager, ChainManagerMixin):
             **kwargs,
         )
 
-    def on_agent_action(self, action: AgentAction, **kwargs: Any) -> Any:
+    def on_agent_action(self, action: AgentAction, **kwargs: Any) -> None:
         """Run when agent action is received.
 
         Args:
             action (AgentAction): The agent action.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -932,16 +931,12 @@ class CallbackManagerForChainRun(ParentRunManager, ChainManagerMixin):
             **kwargs,
         )
 
-    def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> Any:
+    def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> None:
         """Run when agent finish is received.
 
         Args:
             finish (AgentFinish): The agent finish.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -1027,16 +1022,12 @@ class AsyncCallbackManagerForChainRun(AsyncParentRunManager, ChainManagerMixin):
             **kwargs,
         )
 
-    async def on_agent_action(self, action: AgentAction, **kwargs: Any) -> Any:
+    async def on_agent_action(self, action: AgentAction, **kwargs: Any) -> None:
         """Run when agent action is received.
 
         Args:
             action (AgentAction): The agent action.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -1051,16 +1042,12 @@ class AsyncCallbackManagerForChainRun(AsyncParentRunManager, ChainManagerMixin):
             **kwargs,
         )
 
-    async def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> Any:
+    async def on_agent_finish(self, finish: AgentFinish, **kwargs: Any) -> None:
         """Run when agent finish is received.
 
         Args:
             finish (AgentFinish): The agent finish.
             **kwargs (Any): Additional keyword arguments.
-
-        Returns:
-            Any: The result of the callback.
-
         """
         if not self.handlers:
             return
@@ -1556,6 +1543,8 @@ class CallbackManager(BaseCallbackManager):
             parent_run_id (UUID, optional): The ID of the parent run. Defaults to None.
             **kwargs (Any): Additional keyword arguments.
 
+        Returns:
+            The callback manager for the retriever run.
         """
         if run_id is None:
             run_id = uuid.uuid4()
@@ -1602,6 +1591,9 @@ class CallbackManager(BaseCallbackManager):
             data: The data for the adhoc event.
             run_id: The ID of the run. Defaults to None.
 
+        Raises:
+            ValueError: If additional keyword arguments are passed.
+
         .. versionadded:: 0.2.14
 
         """
@@ -1704,8 +1696,8 @@ class CallbackManagerForChainGroup(CallbackManager):
         self.parent_run_manager = parent_run_manager
         self.ended = False
 
+    @override
     def copy(self) -> CallbackManagerForChainGroup:
-        """Copy the callback manager."""
         return self.__class__(
             handlers=self.handlers.copy(),
             inheritable_handlers=self.inheritable_handlers.copy(),
@@ -1734,11 +1726,18 @@ class CallbackManagerForChainGroup(CallbackManager):
 
             .. code-block:: python
 
-                from langchain_core.callbacks.manager import CallbackManager, trace_as_chain_group
+                from langchain_core.callbacks.manager import (
+                    CallbackManager,
+                    trace_as_chain_group,
+                )
                 from langchain_core.callbacks.stdout import StdOutCallbackHandler
 
-                manager = CallbackManager(handlers=[StdOutCallbackHandler()], tags=["tag2"])
-                with trace_as_chain_group("My Group Name", tags=["tag1"]) as group_manager:
+                manager = CallbackManager(
+                    handlers=[StdOutCallbackHandler()], tags=["tag2"]
+                )
+                with trace_as_chain_group(
+                    "My Group Name", tags=["tag1"]
+                ) as group_manager:
                     merged_manager = group_manager.merge(manager)
                     print(type(merged_manager))
                     # <class 'langchain_core.callbacks.manager.CallbackManagerForChainGroup'>
@@ -2086,6 +2085,9 @@ class AsyncCallbackManager(BaseCallbackManager):
             data: The data for the adhoc event.
             run_id: The ID of the run. Defaults to None.
 
+        Raises:
+            ValueError: If additional keyword arguments are passed.
+
         .. versionadded:: 0.2.14
         """
         if not self.handlers:
@@ -2236,7 +2238,7 @@ class AsyncCallbackManagerForChainGroup(AsyncCallbackManager):
         self.ended = False
 
     def copy(self) -> AsyncCallbackManagerForChainGroup:
-        """Copy the async callback manager."""
+        """Return a copy the async callback manager."""
         return self.__class__(
             handlers=self.handlers.copy(),
             inheritable_handlers=self.inheritable_handlers.copy(),
@@ -2258,18 +2260,25 @@ class AsyncCallbackManagerForChainGroup(AsyncCallbackManager):
         from the current object.
 
         Returns:
-            AsyncCallbackManagerForChainGroup: A copy of the current AsyncCallbackManagerForChainGroup
-                with the handlers, tags, etc. of the other callback manager merged in.
+            A copy of the current AsyncCallbackManagerForChainGroup
+            with the handlers, tags, etc. of the other callback manager merged in.
 
         Example: Merging two callback managers.
 
             .. code-block:: python
 
-                from langchain_core.callbacks.manager import CallbackManager, atrace_as_chain_group
+                from langchain_core.callbacks.manager import (
+                    CallbackManager,
+                    atrace_as_chain_group,
+                )
                 from langchain_core.callbacks.stdout import StdOutCallbackHandler
 
-                manager = CallbackManager(handlers=[StdOutCallbackHandler()], tags=["tag2"])
-                async with atrace_as_chain_group("My Group Name", tags=["tag1"]) as group_manager:
+                manager = CallbackManager(
+                    handlers=[StdOutCallbackHandler()], tags=["tag2"]
+                )
+                async with atrace_as_chain_group(
+                    "My Group Name", tags=["tag1"]
+                ) as group_manager:
                     merged_manager = group_manager.merge(manager)
                     print(type(merged_manager))
                     # <class 'langchain_core.callbacks.manager.AsyncCallbackManagerForChainGroup'>
@@ -2365,16 +2374,12 @@ def _configure(
         local_metadata (Optional[dict[str, Any]], optional): The local metadata.
             Defaults to None.
 
+    Raises:
+        RuntimeError: If `LANGCHAIN_TRACING` is set but `LANGCHAIN_TRACING_V2` is not.
+
     Returns:
         T: The configured callback manager.
     """
-    from langchain_core.tracers.context import (
-        _configure_hooks,
-        _get_tracer_project,
-        _tracing_v2_is_enabled,
-        tracing_v2_callback_var,
-    )
-
     tracing_context = get_tracing_context()
     tracing_metadata = tracing_context["metadata"]
     tracing_tags = tracing_context["tags"]
@@ -2451,9 +2456,6 @@ def _configure(
     tracer_project = _get_tracer_project()
     debug = _get_debug()
     if verbose or debug or tracing_v2_enabled_:
-        from langchain_core.tracers.langchain import LangChainTracer
-        from langchain_core.tracers.stdout import ConsoleCallbackHandler
-
         if verbose and not any(
             isinstance(handler, StdOutCallbackHandler)
             for handler in callback_manager.handlers
@@ -2537,6 +2539,10 @@ async def adispatch_custom_event(
               this is not enforced.
         config: Optional config object. Mirrors the async API but not strictly needed.
 
+    Raises:
+        RuntimeError: If there is no parent run ID available to associate
+            the event with.
+
     Example:
 
         .. code-block:: python
@@ -2618,7 +2624,8 @@ async def adispatch_custom_event(
     .. versionadded:: 0.2.15
 
     """
-    from langchain_core.runnables.config import (
+    # Import locally to prevent circular imports.
+    from langchain_core.runnables.config import (  # noqa: PLC0415
         ensure_config,
         get_async_callback_manager_for_config,
     )
@@ -2658,6 +2665,10 @@ def dispatch_custom_event(
               this is not enforced.
         config: Optional config object. Mirrors the async API but not strictly needed.
 
+    Raises:
+        RuntimeError: If there is no parent run ID available to associate
+            the event with.
+
     Example:
 
         .. code-block:: python
@@ -2689,7 +2700,8 @@ def dispatch_custom_event(
     .. versionadded:: 0.2.15
 
     """
-    from langchain_core.runnables.config import (
+    # Import locally to prevent circular imports.
+    from langchain_core.runnables.config import (  # noqa: PLC0415
         ensure_config,
         get_callback_manager_for_config,
     )