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

langchain_core/runnables/retry.py

@@ -3,9 +3,7 @@
 from typing import (
     TYPE_CHECKING,
     Any,
-    Optional,
     TypeVar,
-    Union,
     cast,
 )
 
@@ -35,7 +33,7 @@ U = TypeVar("U")
 
 
 class ExponentialJitterParams(TypedDict, total=False):
-    """Parameters for ``tenacity.wait_exponential_jitter``."""
+    """Parameters for `tenacity.wait_exponential_jitter`."""
 
     initial: float
     """Initial wait."""
@@ -62,36 +60,34 @@ class RunnableRetry(RunnableBindingBase[Input, Output]):  # type: ignore[no-rede
     Example:
     Here's an example that uses a RunnableLambda to raise an exception
 
-        .. code-block:: python
+        ```python
+        import time
 
-            import time
 
+        def foo(input) -> None:
+            '''Fake function that raises an exception.'''
+            raise ValueError(f"Invoking foo failed. At time {time.time()}")
 
-            def foo(input) -> None:
-                '''Fake function that raises an exception.'''
-                raise ValueError(f"Invoking foo failed. At time {time.time()}")
 
+        runnable = RunnableLambda(foo)
 
-            runnable = RunnableLambda(foo)
-
-            runnable_with_retries = runnable.with_retry(
-                retry_if_exception_type=(ValueError,),  # Retry only on ValueError
-                wait_exponential_jitter=True,  # Add jitter to the exponential backoff
-                stop_after_attempt=2,  # Try twice
-                exponential_jitter_params={
-                    "initial": 2
-                },  # if desired, customize backoff
-            )
+        runnable_with_retries = runnable.with_retry(
+            retry_if_exception_type=(ValueError,),  # Retry only on ValueError
+            wait_exponential_jitter=True,  # Add jitter to the exponential backoff
+            stop_after_attempt=2,  # Try twice
+            exponential_jitter_params={"initial": 2},  # if desired, customize backoff
+        )
 
-            # The method invocation above is equivalent to the longer form below:
+        # The method invocation above is equivalent to the longer form below:
 
-            runnable_with_retries = RunnableRetry(
-                bound=runnable,
-                retry_exception_types=(ValueError,),
-                max_attempt_number=2,
-                wait_exponential_jitter=True,
-                exponential_jitter_params={"initial": 2},
-            )
+        runnable_with_retries = RunnableRetry(
+            bound=runnable,
+            retry_exception_types=(ValueError,),
+            max_attempt_number=2,
+            wait_exponential_jitter=True,
+            exponential_jitter_params={"initial": 2},
+        )
+        ```
 
     This logic can be used to retry any Runnable, including a chain of Runnables,
     but in general it's best practice to keep the scope of the retry as small as
@@ -99,22 +95,20 @@ class RunnableRetry(RunnableBindingBase[Input, Output]):  # type: ignore[no-rede
     the Runnable that is likely to fail, not the entire chain.
 
     Example:
+        ```python
+        from langchain_core.chat_models import ChatOpenAI
+        from langchain_core.prompts import PromptTemplate
 
-        .. code-block:: python
-
-            from langchain_core.chat_models import ChatOpenAI
-            from langchain_core.prompts import PromptTemplate
-
-            template = PromptTemplate.from_template("tell me a joke about {topic}.")
-            model = ChatOpenAI(temperature=0.5)
-
-            # Good
-            chain = template | model.with_retry()
+        template = PromptTemplate.from_template("tell me a joke about {topic}.")
+        model = ChatOpenAI(temperature=0.5)
 
-            # Bad
-            chain = template | model
-            retryable_chain = chain.with_retry()
+        # Good
+        chain = template | model.with_retry()
 
+        # Bad
+        chain = template | model
+        retryable_chain = chain.with_retry()
+        ```
     """
 
     retry_exception_types: tuple[type[BaseException], ...] = (Exception,)
@@ -130,9 +124,9 @@ class RunnableRetry(RunnableBindingBase[Input, Output]):  # type: ignore[no-rede
     wait_exponential_jitter: bool = True
     """Whether to add jitter to the exponential backoff."""
 
-    exponential_jitter_params: Optional[ExponentialJitterParams] = None
-    """Parameters for ``tenacity.wait_exponential_jitter``. Namely: ``initial``,
-    ``max``, ``exp_base``, and ``jitter`` (all float values).
+    exponential_jitter_params: ExponentialJitterParams | None = None
+    """Parameters for `tenacity.wait_exponential_jitter`. Namely: `initial`,
+    `max`, `exp_base`, and `jitter` (all `float` values).
     """
 
     max_attempt_number: int = 3
@@ -178,7 +172,8 @@ class RunnableRetry(RunnableBindingBase[Input, Output]):  # type: ignore[no-rede
         retry_state: RetryCallState,
     ) -> list[RunnableConfig]:
         return [
-            self._patch_config(c, rm, retry_state) for c, rm in zip(config, run_manager)
+            self._patch_config(c, rm, retry_state)
+            for c, rm in zip(config, run_manager, strict=False)
         ]
 
     def _invoke(
@@ -201,7 +196,7 @@ class RunnableRetry(RunnableBindingBase[Input, Output]):  # type: ignore[no-rede
 
     @override
     def invoke(
-        self, input: Input, config: Optional[RunnableConfig] = None, **kwargs: Any
+        self, input: Input, config: RunnableConfig | None = None, **kwargs: Any
     ) -> Output:
         return self._call_with_config(self._invoke, input, config, **kwargs)
 
@@ -225,7 +220,7 @@ class RunnableRetry(RunnableBindingBase[Input, Output]):  # type: ignore[no-rede
 
     @override
     async def ainvoke(
-        self, input: Input, config: Optional[RunnableConfig] = None, **kwargs: Any
+        self, input: Input, config: RunnableConfig | None = None, **kwargs: Any
     ) -> Output:
         return await self._acall_with_config(self._ainvoke, input, config, **kwargs)
 
@@ -235,7 +230,7 @@ class RunnableRetry(RunnableBindingBase[Input, Output]):  # type: ignore[no-rede
         run_manager: list["CallbackManagerForChainRun"],
         config: list[RunnableConfig],
         **kwargs: Any,
-    ) -> list[Union[Output, Exception]]:
+    ) -> list[Output | Exception]:
         results_map: dict[int, Output] = {}
 
         not_set: list[Output] = []
@@ -284,7 +279,7 @@ class RunnableRetry(RunnableBindingBase[Input, Output]):  # type: ignore[no-rede
             if result is not_set:
                 result = cast("list[Output]", [e] * len(inputs))
 
-        outputs: list[Union[Output, Exception]] = []
+        outputs: list[Output | Exception] = []
         for idx in range(len(inputs)):
             if idx in results_map:
                 outputs.append(results_map[idx])
@@ -296,7 +291,7 @@ class RunnableRetry(RunnableBindingBase[Input, Output]):  # type: ignore[no-rede
     def batch(
         self,
         inputs: list[Input],
-        config: Optional[Union[RunnableConfig, list[RunnableConfig]]] = None,
+        config: RunnableConfig | list[RunnableConfig] | None = None,
         *,
         return_exceptions: bool = False,
         **kwargs: Any,
@@ -311,7 +306,7 @@ class RunnableRetry(RunnableBindingBase[Input, Output]):  # type: ignore[no-rede
         run_manager: list["AsyncCallbackManagerForChainRun"],
         config: list[RunnableConfig],
         **kwargs: Any,
-    ) -> list[Union[Output, Exception]]:
+    ) -> list[Output | Exception]:
         results_map: dict[int, Output] = {}
 
         not_set: list[Output] = []
@@ -359,7 +354,7 @@ class RunnableRetry(RunnableBindingBase[Input, Output]):  # type: ignore[no-rede
             if result is not_set:
                 result = cast("list[Output]", [e] * len(inputs))
 
-        outputs: list[Union[Output, Exception]] = []
+        outputs: list[Output | Exception] = []
         for idx in range(len(inputs)):
             if idx in results_map:
                 outputs.append(results_map[idx])
@@ -371,7 +366,7 @@ class RunnableRetry(RunnableBindingBase[Input, Output]):  # type: ignore[no-rede
     async def abatch(
         self,
         inputs: list[Input],
-        config: Optional[Union[RunnableConfig, list[RunnableConfig]]] = None,
+        config: RunnableConfig | list[RunnableConfig] | None = None,
         *,
         return_exceptions: bool = False,
         **kwargs: Any,

langchain_core/runnables/router.py

@@ -2,13 +2,10 @@
 
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Callable, Mapping
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
-    Optional,
-    Union,
     cast,
 )
 
@@ -52,18 +49,16 @@ class RouterRunnable(RunnableSerializable[RouterInput, Output]):
     Returns the output of the selected Runnable.
 
     Example:
+        ```python
+        from langchain_core.runnables.router import RouterRunnable
+        from langchain_core.runnables import RunnableLambda
 
-        .. code-block:: python
-
-            from langchain_core.runnables.router import RouterRunnable
-            from langchain_core.runnables import RunnableLambda
-
-            add = RunnableLambda(func=lambda x: x + 1)
-            square = RunnableLambda(func=lambda x: x**2)
-
-            router = RouterRunnable(runnables={"add": add, "square": square})
-            router.invoke({"key": "square", "input": 3})
+        add = RunnableLambda(func=lambda x: x + 1)
+        square = RunnableLambda(func=lambda x: x**2)
 
+        router = RouterRunnable(runnables={"add": add, "square": square})
+        router.invoke({"key": "square", "input": 3})
+        ```
     """
 
     runnables: Mapping[str, Runnable[Any, Output]]
@@ -77,7 +72,7 @@ class RouterRunnable(RunnableSerializable[RouterInput, Output]):
 
     def __init__(
         self,
-        runnables: Mapping[str, Union[Runnable[Any, Output], Callable[[Any], Output]]],
+        runnables: Mapping[str, Runnable[Any, Output] | Callable[[Any], Output]],
     ) -> None:
         """Create a RouterRunnable.
 
@@ -101,16 +96,16 @@ class RouterRunnable(RunnableSerializable[RouterInput, Output]):
     @classmethod
     @override
     def get_lc_namespace(cls) -> list[str]:
-        """Get the namespace of the langchain object.
+        """Get the namespace of the LangChain object.
 
         Returns:
-            ``["langchain", "schema", "runnable"]``
+            `["langchain", "schema", "runnable"]`
         """
         return ["langchain", "schema", "runnable"]
 
     @override
     def invoke(
-        self, input: RouterInput, config: Optional[RunnableConfig] = None, **kwargs: Any
+        self, input: RouterInput, config: RunnableConfig | None = None, **kwargs: Any
     ) -> Output:
         key = input["key"]
         actual_input = input["input"]
@@ -125,8 +120,8 @@ class RouterRunnable(RunnableSerializable[RouterInput, Output]):
     async def ainvoke(
         self,
         input: RouterInput,
-        config: Optional[RunnableConfig] = None,
-        **kwargs: Optional[Any],
+        config: RunnableConfig | None = None,
+        **kwargs: Any | None,
     ) -> Output:
         key = input["key"]
         actual_input = input["input"]
@@ -141,10 +136,10 @@ class RouterRunnable(RunnableSerializable[RouterInput, Output]):
     def batch(
         self,
         inputs: list[RouterInput],
-        config: Optional[Union[RunnableConfig, list[RunnableConfig]]] = None,
+        config: RunnableConfig | list[RunnableConfig] | None = None,
         *,
         return_exceptions: bool = False,
-        **kwargs: Optional[Any],
+        **kwargs: Any | None,
     ) -> list[Output]:
         if not inputs:
             return []
@@ -157,7 +152,7 @@ class RouterRunnable(RunnableSerializable[RouterInput, Output]):
 
         def invoke(
             runnable: Runnable, input_: Input, config: RunnableConfig
-        ) -> Union[Output, Exception]:
+        ) -> Output | Exception:
             if return_exceptions:
                 try:
                     return runnable.invoke(input_, config, **kwargs)
@@ -178,10 +173,10 @@ class RouterRunnable(RunnableSerializable[RouterInput, Output]):
     async def abatch(
         self,
         inputs: list[RouterInput],
-        config: Optional[Union[RunnableConfig, list[RunnableConfig]]] = None,
+        config: RunnableConfig | list[RunnableConfig] | None = None,
         *,
         return_exceptions: bool = False,
-        **kwargs: Optional[Any],
+        **kwargs: Any | None,
     ) -> list[Output]:
         if not inputs:
             return []
@@ -194,7 +189,7 @@ class RouterRunnable(RunnableSerializable[RouterInput, Output]):
 
         async def ainvoke(
             runnable: Runnable, input_: Input, config: RunnableConfig
-        ) -> Union[Output, Exception]:
+        ) -> Output | Exception:
             if return_exceptions:
                 try:
                     return await runnable.ainvoke(input_, config, **kwargs)
@@ -214,8 +209,8 @@ class RouterRunnable(RunnableSerializable[RouterInput, Output]):
     def stream(
         self,
         input: RouterInput,
-        config: Optional[RunnableConfig] = None,
-        **kwargs: Optional[Any],
+        config: RunnableConfig | None = None,
+        **kwargs: Any | None,
     ) -> Iterator[Output]:
         key = input["key"]
         actual_input = input["input"]
@@ -230,8 +225,8 @@ class RouterRunnable(RunnableSerializable[RouterInput, Output]):
     async def astream(
         self,
         input: RouterInput,
-        config: Optional[RunnableConfig] = None,
-        **kwargs: Optional[Any],
+        config: RunnableConfig | None = None,
+        **kwargs: Any | None,
     ) -> AsyncIterator[Output]:
         key = input["key"]
         actual_input = input["input"]

langchain_core/runnables/schema.py

@@ -1,8 +1,8 @@
-"""Module contains typedefs that are used with Runnables."""
+"""Module contains typedefs that are used with `Runnable` objects."""
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Literal, Union
+from typing import TYPE_CHECKING, Any, Literal
 
 from typing_extensions import NotRequired, TypedDict
 
@@ -14,120 +14,125 @@ class EventData(TypedDict, total=False):
     """Data associated with a streaming event."""
 
     input: Any
-    """The input passed to the Runnable that generated the event.
+    """The input passed to the `Runnable` that generated the event.
 
-    Inputs will sometimes be available at the *START* of the Runnable, and
-    sometimes at the *END* of the Runnable.
+    Inputs will sometimes be available at the *START* of the `Runnable`, and
+    sometimes at the *END* of the `Runnable`.
 
-    If a Runnable is able to stream its inputs, then its input by definition
-    won't be known until the *END* of the Runnable when it has finished streaming
+    If a `Runnable` is able to stream its inputs, then its input by definition
+    won't be known until the *END* of the `Runnable` when it has finished streaming
     its inputs.
     """
+    error: NotRequired[BaseException]
+    """The error that occurred during the execution of the `Runnable`.
+
+    This field is only available if the `Runnable` raised an exception.
+
+    !!! version-added "Added in version 1.0.0"
+    """
     output: Any
-    """The output of the Runnable that generated the event.
+    """The output of the `Runnable` that generated the event.
 
-    Outputs will only be available at the *END* of the Runnable.
+    Outputs will only be available at the *END* of the `Runnable`.
 
-    For most Runnables, this field can be inferred from the `chunk` field,
-    though there might be some exceptions for special cased Runnables (e.g., like
+    For most `Runnable` objects, this field can be inferred from the `chunk` field,
+    though there might be some exceptions for special a cased `Runnable` (e.g., like
     chat models), which may return more information.
     """
     chunk: Any
     """A streaming chunk from the output that generated the event.
 
     chunks support addition in general, and adding them up should result
-    in the output of the Runnable that generated the event.
+    in the output of the `Runnable` that generated the event.
     """
 
 
 class BaseStreamEvent(TypedDict):
     """Streaming event.
 
-    Schema of a streaming event which is produced from the astream_events method.
+    Schema of a streaming event which is produced from the `astream_events` method.
 
     Example:
-
-        .. code-block:: python
-
-            from langchain_core.runnables import RunnableLambda
-
-
-            async def reverse(s: str) -> str:
-                return s[::-1]
-
-
-            chain = RunnableLambda(func=reverse)
-
-            events = [event async for event in chain.astream_events("hello")]
-
-            # will produce the following events
-            # (where some fields have been omitted for brevity):
-            [
-                {
-                    "data": {"input": "hello"},
-                    "event": "on_chain_start",
-                    "metadata": {},
-                    "name": "reverse",
-                    "tags": [],
-                },
-                {
-                    "data": {"chunk": "olleh"},
-                    "event": "on_chain_stream",
-                    "metadata": {},
-                    "name": "reverse",
-                    "tags": [],
-                },
-                {
-                    "data": {"output": "olleh"},
-                    "event": "on_chain_end",
-                    "metadata": {},
-                    "name": "reverse",
-                    "tags": [],
-                },
-            ]
-
+        ```python
+        from langchain_core.runnables import RunnableLambda
+
+
+        async def reverse(s: str) -> str:
+            return s[::-1]
+
+
+        chain = RunnableLambda(func=reverse)
+
+        events = [event async for event in chain.astream_events("hello")]
+
+        # Will produce the following events
+        # (where some fields have been omitted for brevity):
+        [
+            {
+                "data": {"input": "hello"},
+                "event": "on_chain_start",
+                "metadata": {},
+                "name": "reverse",
+                "tags": [],
+            },
+            {
+                "data": {"chunk": "olleh"},
+                "event": "on_chain_stream",
+                "metadata": {},
+                "name": "reverse",
+                "tags": [],
+            },
+            {
+                "data": {"output": "olleh"},
+                "event": "on_chain_end",
+                "metadata": {},
+                "name": "reverse",
+                "tags": [],
+            },
+        ]
+        ```
     """
 
     event: str
-    """Event names are of the format: on_[runnable_type]_(start|stream|end).
+    """Event names are of the format: `on_[runnable_type]_(start|stream|end)`.
 
     Runnable types are one of:
 
     - **llm** - used by non chat models
     - **chat_model** - used by chat models
-    - **prompt** --  e.g., ChatPromptTemplate
-    - **tool** -- from tools defined via @tool decorator or inheriting
-        from Tool/BaseTool
-    - **chain** - most Runnables are of this type
+    - **prompt** --  e.g., `ChatPromptTemplate`
+    - **tool** -- from tools defined via `@tool` decorator or inheriting
+        from `Tool`/`BaseTool`
+    - **chain** - most `Runnable` objects are of this type
 
     Further, the events are categorized as one of:
 
-    - **start** - when the Runnable starts
-    - **stream** - when the Runnable is streaming
-    - **end* - when the Runnable ends
+    - **start** - when the `Runnable` starts
+    - **stream** - when the `Runnable` is streaming
+    - **end* - when the `Runnable` ends
 
     start, stream and end are associated with slightly different `data` payload.
 
     Please see the documentation for `EventData` for more details.
     """
     run_id: str
-    """An randomly generated ID to keep track of the execution of the given Runnable.
+    """An randomly generated ID to keep track of the execution of the given `Runnable`.
 
-    Each child Runnable that gets invoked as part of the execution of a parent Runnable
-    is assigned its own unique ID.
+    Each child `Runnable` that gets invoked as part of the execution of a parent
+    `Runnable` is assigned its own unique ID.
     """
     tags: NotRequired[list[str]]
-    """Tags associated with the Runnable that generated this event.
+    """Tags associated with the `Runnable` that generated this event.
 
-    Tags are always inherited from parent Runnables.
+    Tags are always inherited from parent `Runnable` objects.
 
-    Tags can either be bound to a Runnable using `.with_config({"tags":  ["hello"]})`
+    Tags can either be bound to a `Runnable` using `.with_config({"tags":  ["hello"]})`
     or passed at run time using `.astream_events(..., {"tags": ["hello"]})`.
     """
     metadata: NotRequired[dict[str, Any]]
-    """Metadata associated with the Runnable that generated this event.
+    """Metadata associated with the `Runnable` that generated this event.
 
-    Metadata can either be bound to a Runnable using
+    Metadata can either be bound to a `Runnable` using
 
         `.with_config({"metadata": { "foo": "bar" }})`
 
@@ -141,8 +146,8 @@ class BaseStreamEvent(TypedDict):
 
     Root Events will have an empty list.
 
-    For example, if a Runnable A calls Runnable B, then the event generated by Runnable
-    B will have Runnable A's ID in the parent_ids field.
+    For example, if a `Runnable` A calls `Runnable` B, then the event generated by
+    `Runnable` B will have `Runnable` A's ID in the `parent_ids` field.
 
     The order of the parent IDs is from the root parent to the immediate parent.
 
@@ -159,13 +164,13 @@ class StandardStreamEvent(BaseStreamEvent):
     The contents of the event data depend on the event type.
     """
     name: str
-    """The name of the Runnable that generated the event."""
+    """The name of the `Runnable` that generated the event."""
 
 
 class CustomStreamEvent(BaseStreamEvent):
     """Custom stream event created by the user.
 
-    .. versionadded:: 0.2.15
+    !!! version-added "Added in version 0.2.15"
     """
 
     # Overwrite the event field to be more specific.
@@ -177,4 +182,4 @@ class CustomStreamEvent(BaseStreamEvent):
     """The data associated with the event. Free form and can be anything."""
 
 
-StreamEvent = Union[StandardStreamEvent, CustomStreamEvent]
+StreamEvent = StandardStreamEvent | CustomStreamEvent