libs/core/langchain_core/runnables/base.py PYTHON 6,713 lines View on github.com → Search inside
File is large — showing lines 1–2,000 of 6,713.
1"""Base classes and utilities for `Runnable` objects."""23from __future__ import annotations45import asyncio6import collections7import contextlib8import functools9import inspect10import threading11from abc import ABC, abstractmethod12from collections.abc import (13    AsyncGenerator,14    AsyncIterator,15    Awaitable,16    Callable,17    Coroutine,18    Iterator,19    Mapping,20    Sequence,21)22from concurrent.futures import FIRST_COMPLETED, wait23from functools import wraps24from itertools import tee25from operator import itemgetter26from types import GenericAlias27from typing import (28    TYPE_CHECKING,29    Any,30    Generic,31    Literal,32    Protocol,33    TypeVar,34    cast,35    get_args,36    get_type_hints,37    overload,38)3940from pydantic import BaseModel, ConfigDict, Field, RootModel41from pydantic.fields import FieldInfo42from typing_extensions import override4344from langchain_core._api import beta_decorator45from langchain_core._api.deprecation import warn_deprecated46from langchain_core.callbacks.manager import AsyncCallbackManager, CallbackManager47from langchain_core.load.serializable import (48    Serializable,49    SerializedConstructor,50    SerializedNotImplemented,51)52from langchain_core.messages import AIMessageChunk53from langchain_core.runnables.config import (54    RunnableConfig,55    acall_func_with_variable_args,56    call_func_with_variable_args,57    ensure_config,58    get_async_callback_manager_for_config,59    get_callback_manager_for_config,60    get_config_list,61    get_executor_for_config,62    merge_configs,63    patch_config,64    run_in_executor,65    set_config_context,66)67from langchain_core.runnables.utils import (68    AddableDict,69    AnyConfigurableField,70    ConfigurableField,71    ConfigurableFieldSpec,72    Input,73    Output,74    accepts_config,75    accepts_run_manager,76    coro_with_context,77    gated_coro,78    gather_with_concurrency,79    get_function_first_arg_dict_keys,80    get_function_nonlocals,81    get_lambda_source,82    get_unique_config_specs,83    indent_lines_after_first,84    is_async_callable,85    is_async_generator,86)87from langchain_core.tracers._streaming import _StreamingCallbackHandler88from langchain_core.tracers.event_stream import (89    _astream_events_implementation_v1,90    _astream_events_implementation_v2,91)92from langchain_core.tracers.log_stream import (93    LogStreamCallbackHandler,94    _astream_log_implementation,95)96from langchain_core.tracers.root_listeners import (97    AsyncRootListenersTracer,98    RootListenersTracer,99)100from langchain_core.utils._signature import _signature_parameters101from langchain_core.utils.aiter import aclosing, atee102from langchain_core.utils.iter import safetee103from langchain_core.utils.pydantic import (104    TypeBaseModel,105    create_model_v2,106    get_fields,107    model_json_schema,108)109110if TYPE_CHECKING:111    from pydantic.v1.fields import ModelField112113    from langchain_core.callbacks.manager import (114        AsyncCallbackManagerForChainRun,115        CallbackManagerForChainRun,116    )117    from langchain_core.prompts.base import BasePromptTemplate118    from langchain_core.runnables.fallbacks import (119        RunnableWithFallbacks as RunnableWithFallbacksT,120    )121    from langchain_core.runnables.graph import Graph122    from langchain_core.runnables.retry import ExponentialJitterParams123    from langchain_core.runnables.schema import StreamEvent124    from langchain_core.tools import BaseTool125    from langchain_core.tracers.log_stream import RunLog, RunLogPatch126    from langchain_core.tracers.root_listeners import AsyncListener127    from langchain_core.tracers.schemas import Run128129130Other = TypeVar("Other")131132_RUNNABLE_GENERIC_NUM_ARGS = 2  # Input and Output133134135class _ChunkAccumulator:136    """Adds up streamed chunks with `+`, as if one at a time.137138    Leading `AIMessageChunk`s are kept until the value is read, then merged in one139    addition: every `AIMessageChunk` addition re-parses the tool call arguments140    received so far, so adding them one at a time is quadratic in a tool call's141    length. If that addition raises, they are added one at a time after all.142143    A chunk that can't be added replaces the value. After that, with144    `stop_after_unaddable`, every later chunk replaces it too.145    """146147    def __init__(self, *, stop_after_unaddable: bool) -> None:148        self._value: Any = None149        self._addable = True150        self._stop_after_unaddable = stop_after_unaddable151        self._message_chunks: list[AIMessageChunk] = []152153    @property154    def value(self) -> Any:155        self._flush()156        return self._value157158    def value_for_error(self) -> Any:159        """Return `value`, or what was merged so far if merging raises.160161        For error handlers, so a failed merge can't replace the error being162        reported.163        """164        try:165            return self.value166        except Exception:167            return self._value168169    def add(self, chunk: Any) -> None:170        if self._value is None and self._addable and isinstance(chunk, AIMessageChunk):171            self._message_chunks.append(chunk)172        else:173            self._flush()174            self._add(chunk)175176    def _flush(self) -> None:177        if not self._message_chunks:178            return179        chunks, self._message_chunks = self._message_chunks, []180        try:181            self._value = chunks[0] + chunks[1:] if len(chunks) > 1 else chunks[0]182        except TypeError:183            for chunk in chunks:184                self._add(chunk)185186    def _add(self, chunk: Any) -> None:187        if self._value is None or not self._addable:188            self._value = chunk189            return190        try:191            self._value = self._value + chunk192        except TypeError:193            self._value = chunk194            self._addable = not self._stop_after_unaddable195196197class Runnable(ABC, Generic[Input, Output]):198    """A unit of work that can be invoked, batched, streamed, transformed and composed.199200    Key Methods201    ===========202203    - `invoke`/`ainvoke`: Transforms a single input into an output.204    - `batch`/`abatch`: Efficiently transforms multiple inputs into outputs.205    - `stream`/`astream`: Streams output from a single input as it's produced.206    - `astream_log`: Streams output and selected intermediate results from an207        input.208209    Built-in optimizations:210211    - **Batch**: By default, batch runs invoke() in parallel using a thread pool212        executor. Override to optimize batching.213214    - **Async**: Methods with `'a'` prefix are asynchronous. By default, they execute215        the sync counterpart using asyncio's thread pool.216        Override for native async.217218    All methods accept an optional config argument, which can be used to configure219    execution, add tags and metadata for tracing and debugging etc.220221    Runnables expose schematic information about their input, output and config via222    the `input_schema` property, the `output_schema` property and `config_schema`223    method.224225    Composition226    ===========227228    Runnable objects can be composed together to create chains in a declarative way.229230    Any chain constructed this way will automatically have sync, async, batch, and231    streaming support.232233    The main composition primitives are `RunnableSequence` and `RunnableParallel`.234235    **`RunnableSequence`** invokes a series of runnables sequentially, with236    one Runnable's output serving as the next's input. Construct using237    the `|` operator or by passing a list of runnables to `RunnableSequence`.238239    **`RunnableParallel`** invokes runnables concurrently, providing the same input240    to each. Construct it using a dict literal within a sequence or by passing a241    dict to `RunnableParallel`.242243244    For example,245246    ```python247    from langchain_core.runnables import RunnableLambda248249    # A RunnableSequence constructed using the `|` operator250    sequence = RunnableLambda(lambda x: x + 1) | RunnableLambda(lambda x: x * 2)251    sequence.invoke(1)  # 4252    sequence.batch([1, 2, 3])  # [4, 6, 8]253254255    # A sequence that contains a RunnableParallel constructed using a dict literal256    sequence = RunnableLambda(lambda x: x + 1) | {257        "mul_2": RunnableLambda(lambda x: x * 2),258        "mul_5": RunnableLambda(lambda x: x * 5),259    }260    sequence.invoke(1)  # {'mul_2': 4, 'mul_5': 10}261    ```262263    Standard Methods264    ================265266    All `Runnable`s expose additional methods that can be used to modify their267    behavior (e.g., add a retry policy, add lifecycle listeners, make them268    configurable, etc.).269270    These methods will work on any `Runnable`, including `Runnable` chains271    constructed by composing other `Runnable`s.272    See the individual methods for details.273274    For example,275276    ```python277    from langchain_core.runnables import RunnableLambda278279    import random280281    def add_one(x: int) -> int:282        return x + 1283284285    def buggy_double(y: int) -> int:286        \"\"\"Buggy code that will fail 70% of the time\"\"\"287        if random.random() > 0.3:288            print('This code failed, and will probably be retried!')  # noqa: T201289            raise ValueError('Triggered buggy code')290        return y * 2291292    sequence = (293        RunnableLambda(add_one) |294        RunnableLambda(buggy_double).with_retry( # Retry on failure295            stop_after_attempt=10,296            wait_exponential_jitter=False297        )298    )299300    print(sequence.input_schema.model_json_schema()) # Show inferred input schema301    print(sequence.output_schema.model_json_schema()) # Show inferred output schema302    print(sequence.invoke(2)) # invoke the sequence (note the retry above!!)303    ```304305    Debugging and tracing306    =====================307308    As the chains get longer, it can be useful to be able to see intermediate results309    to debug and trace the chain.310311    You can set the global debug flag to True to enable debug output for all chains:312313    ```python314    from langchain_core.globals import set_debug315316    set_debug(True)317    ```318319    Alternatively, you can pass existing or custom callbacks to any given chain:320321    ```python322    from langchain_core.tracers import ConsoleCallbackHandler323324    chain.invoke(..., config={"callbacks": [ConsoleCallbackHandler()]})325    ```326327    For a UI (and much more) checkout [LangSmith](https://docs.langchain.com/langsmith/home).328329    """330331    name: str | None332    """The name of the `Runnable`. Used for debugging and tracing."""333334    def get_name(self, suffix: str | None = None, *, name: str | None = None) -> str:335        """Get the name of the `Runnable`.336337        Args:338            suffix: An optional suffix to append to the name.339            name: An optional name to use instead of the `Runnable`'s name.340341        Returns:342            The name of the `Runnable`.343        """344        if name:345            name_ = name346        elif hasattr(self, "name") and self.name:347            name_ = self.name348        else:349            # Here we handle a case where the runnable subclass is also a pydantic350            # model.351            cls = self.__class__352            # Then it's a pydantic sub-class, and we have to check353            # whether it's a generic, and if so recover the original name.354            if (355                hasattr(356                    cls,357                    "__pydantic_generic_metadata__",358                )359                and "origin" in cls.__pydantic_generic_metadata__360                and cls.__pydantic_generic_metadata__["origin"] is not None361            ):362                name_ = cls.__pydantic_generic_metadata__["origin"].__name__363            else:364                name_ = cls.__name__365366        if suffix:367            if name_[0].isupper():368                return name_ + suffix.title()369            return name_ + "_" + suffix.lower()370        return name_371372    @property373    def InputType(self) -> type[Input]:  # noqa: N802374        """Input type.375376        The type of input this `Runnable` accepts specified as a type annotation.377378        Raises:379            TypeError: If the input type cannot be inferred.380        """381        # First loop through all parent classes and if any of them is382        # a Pydantic model, we will pick up the generic parameterization383        # from that model via the __pydantic_generic_metadata__ attribute.384        for base in self.__class__.mro():385            if hasattr(base, "__pydantic_generic_metadata__"):386                metadata = base.__pydantic_generic_metadata__387                if (388                    "args" in metadata389                    and len(metadata["args"]) == _RUNNABLE_GENERIC_NUM_ARGS390                ):391                    return cast("type[Input]", metadata["args"][0])392393        # If we didn't find a Pydantic model in the parent classes,394        # then loop through __orig_bases__. This corresponds to395        # Runnables that are not pydantic models.396        for cls in self.__class__.__orig_bases__:  # type: ignore[attr-defined]397            type_args = get_args(cls)398            if type_args and len(type_args) == _RUNNABLE_GENERIC_NUM_ARGS:399                return cast("type[Input]", type_args[0])400401        msg = (402            f"Runnable {self.get_name()} doesn't have an inferable InputType. "403            "Override the InputType property to specify the input type."404        )405        raise TypeError(msg)406407    @property408    def OutputType(self) -> type[Output]:  # noqa: N802409        """Output Type.410411        The type of output this `Runnable` produces specified as a type annotation.412413        Raises:414            TypeError: If the output type cannot be inferred.415        """416        # First loop through bases -- this will help generic417        # any pydantic models.418        for base in self.__class__.mro():419            if hasattr(base, "__pydantic_generic_metadata__"):420                metadata = base.__pydantic_generic_metadata__421                if (422                    "args" in metadata423                    and len(metadata["args"]) == _RUNNABLE_GENERIC_NUM_ARGS424                ):425                    return cast("type[Output]", metadata["args"][1])426427        for cls in self.__class__.__orig_bases__:  # type: ignore[attr-defined]428            type_args = get_args(cls)429            if type_args and len(type_args) == _RUNNABLE_GENERIC_NUM_ARGS:430                return cast("type[Output]", type_args[1])431432        msg = (433            f"Runnable {self.get_name()} doesn't have an inferable OutputType. "434            "Override the OutputType property to specify the output type."435        )436        raise TypeError(msg)437438    @property439    def input_schema(self) -> TypeBaseModel:440        """The type of input this `Runnable` accepts specified as a Pydantic model."""441        return self.get_input_schema()442443    def get_input_schema(444        self,445        config: RunnableConfig | None = None,446    ) -> TypeBaseModel:447        """Get a Pydantic model that can be used to validate input to the `Runnable`.448449        `Runnable` objects that leverage the `configurable_fields` and450        `configurable_alternatives` methods will have a dynamic input schema that451        depends on which configuration the `Runnable` is invoked with.452453        This method allows to get an input schema for a specific configuration.454455        Args:456            config: A config to use when generating the schema.457458        Returns:459            A Pydantic model that can be used to validate input.460        """461        _ = config462        root_type = self.InputType463464        if (465            inspect.isclass(root_type)466            and not isinstance(root_type, GenericAlias)467            and issubclass(root_type, BaseModel)468        ):469            return root_type470471        return create_model_v2(472            self.get_name("Input"),473            root=root_type,474            # create model needs access to appropriate type annotations to be475            # able to construct the Pydantic model.476            # When we create the model, we pass information about the namespace477            # where the model is being created, so the type annotations can478            # be resolved correctly as well.479            # self.__class__.__module__ handles the case when the Runnable is480            # being sub-classed in a different module.481            module_name=self.__class__.__module__,482        )483484    def get_input_jsonschema(485        self, config: RunnableConfig | None = None486    ) -> dict[str, Any]:487        """Get a JSON schema that represents the input to the `Runnable`.488489        Args:490            config: A config to use when generating the schema.491492        Returns:493            A JSON schema that represents the input to the `Runnable`.494495        Example:496            ```python497            from langchain_core.runnables import RunnableLambda498499500            def add_one(x: int) -> int:501                return x + 1502503504            runnable = RunnableLambda(add_one)505506            print(runnable.get_input_jsonschema())507            ```508509        !!! version-added "Added in `langchain-core` 0.3.0"510511        """512        return model_json_schema(self.get_input_schema(config))513514    @property515    def output_schema(self) -> TypeBaseModel:516        """Output schema.517518        The type of output this `Runnable` produces specified as a Pydantic model.519        """520        return self.get_output_schema()521522    def get_output_schema(523        self,524        config: RunnableConfig | None = None,525    ) -> TypeBaseModel:526        """Get a Pydantic model that can be used to validate output to the `Runnable`.527528        `Runnable` objects that leverage the `configurable_fields` and529        `configurable_alternatives` methods will have a dynamic output schema that530        depends on which configuration the `Runnable` is invoked with.531532        This method allows to get an output schema for a specific configuration.533534        Args:535            config: A config to use when generating the schema.536537        Returns:538            A Pydantic model that can be used to validate output.539        """540        _ = config541        root_type = self.OutputType542543        if (544            inspect.isclass(root_type)545            and not isinstance(root_type, GenericAlias)546            and issubclass(root_type, BaseModel)547        ):548            return root_type549550        return create_model_v2(551            self.get_name("Output"),552            root=root_type,553            # create model needs access to appropriate type annotations to be554            # able to construct the Pydantic model.555            # When we create the model, we pass information about the namespace556            # where the model is being created, so the type annotations can557            # be resolved correctly as well.558            # self.__class__.__module__ handles the case when the Runnable is559            # being sub-classed in a different module.560            module_name=self.__class__.__module__,561        )562563    def get_output_jsonschema(564        self, config: RunnableConfig | None = None565    ) -> dict[str, Any]:566        """Get a JSON schema that represents the output of the `Runnable`.567568        Args:569            config: A config to use when generating the schema.570571        Returns:572            A JSON schema that represents the output of the `Runnable`.573574        Example:575            ```python576            from langchain_core.runnables import RunnableLambda577578579            def add_one(x: int) -> int:580                return x + 1581582583            runnable = RunnableLambda(add_one)584585            print(runnable.get_output_jsonschema())586            ```587588        !!! version-added "Added in `langchain-core` 0.3.0"589590        """591        return model_json_schema(self.get_output_schema(config))592593    @property594    def config_specs(self) -> list[ConfigurableFieldSpec]:595        """List configurable fields for this `Runnable`."""596        return []597598    def config_schema(self, *, include: Sequence[str] | None = None) -> type[BaseModel]:599        """The type of config this `Runnable` accepts specified as a Pydantic model.600601        To mark a field as configurable, see the `configurable_fields`602        and `configurable_alternatives` methods.603604        Args:605            include: A list of fields to include in the config schema.606607        Returns:608            A Pydantic model that can be used to validate config.609610        """611        include = include or []612        config_specs = self.config_specs613        configurable = (614            create_model_v2(615                "Configurable",616                field_definitions={617                    spec.id: (618                        spec.annotation,619                        Field(620                            spec.default, title=spec.name, description=spec.description621                        ),622                    )623                    for spec in config_specs624                },625            )626            if config_specs627            else None628        )629630        # Many need to create a typed dict instead to implement NotRequired!631        all_fields = {632            **({"configurable": (configurable, None)} if configurable else {}),633            **{634                field_name: (field_type, None)635                for field_name, field_type in get_type_hints(RunnableConfig).items()636                if field_name in [i for i in include if i != "configurable"]637            },638        }639        return create_model_v2(self.get_name("Config"), field_definitions=all_fields)640641    def get_config_jsonschema(642        self, *, include: Sequence[str] | None = None643    ) -> dict[str, Any]:644        """Get a JSON schema that represents the config of the `Runnable`.645646        Args:647            include: A list of fields to include in the config schema.648649        Returns:650            A JSON schema that represents the config of the `Runnable`.651652        !!! version-added "Added in `langchain-core` 0.3.0"653654        """655        return self.config_schema(include=include).model_json_schema()656657    def get_graph(self, config: RunnableConfig | None = None) -> Graph:658        """Return a graph representation of this `Runnable`."""659        # Import locally to prevent circular import660        from langchain_core.runnables.graph import Graph  # noqa: PLC0415661662        graph = Graph()663        try:664            input_node = graph.add_node(self.get_input_schema(config))665        except TypeError:666            input_node = graph.add_node(create_model_v2(self.get_name("Input")))667        runnable_node = graph.add_node(668            self, metadata=config.get("metadata") if config else None669        )670        try:671            output_node = graph.add_node(self.get_output_schema(config))672        except TypeError:673            output_node = graph.add_node(create_model_v2(self.get_name("Output")))674        graph.add_edge(input_node, runnable_node)675        graph.add_edge(runnable_node, output_node)676        return graph677678    def get_prompts(679        self, config: RunnableConfig | None = None680    ) -> list[BasePromptTemplate[Any]]:681        """Return a list of prompts used by this `Runnable`."""682        # Import locally to prevent circular import683        from langchain_core.prompts.base import BasePromptTemplate  # noqa: PLC0415684685        return [686            node.data687            for node in self.get_graph(config=config).nodes.values()688            if isinstance(node.data, BasePromptTemplate)689        ]690691    @overload692    def __or__(693        self, other: Mapping[str, Any]694    ) -> RunnableSerializable[Input, dict[str, Any]]: ...695696    @overload697    def __or__(698        self,699        other: Callable[[Output], Runnable[Output, Other]]700        | Callable[[Output], Awaitable[Runnable[Output, Other]]],701    ) -> RunnableSerializable[Input, Other]: ...702703    @overload704    def __or__(705        self,706        other: Runnable[Output, Other]707        | Callable[[Iterator[Output]], Iterator[Other]]708        | Callable[[AsyncIterator[Output]], AsyncIterator[Other]]709        | Callable[[Output], Other],710    ) -> RunnableSerializable[Input, Other]: ...711712    def __or__(713        self,714        other: Runnable[Output, Other]715        | Callable[[Iterator[Output]], Iterator[Other]]716        | Callable[[AsyncIterator[Output]], AsyncIterator[Other]]717        | Callable[[Output], Other]718        | Mapping[str, Runnable[Output, Any] | Callable[[Output], Any] | Any],719    ) -> RunnableSerializable[Input, Any]:720        """Runnable "or" operator.721722        Compose this `Runnable` with another object to create a723        `RunnableSequence`.724725        Args:726            other: Another `Runnable` or a `Runnable`-like object.727728        Returns:729            A new `Runnable`.730731        Raises:732            TypeError: If `other` cannot be coerced to a `Runnable`. This method does733                not return `NotImplemented`, to avoid delegating LCEL composition to734                unrelated reflected `|` implementations. To interoperate, implement735                `Runnable`, make the object callable, or define `__or__` on the left.736        """737        return RunnableSequence(self, coerce_to_runnable(other))738739    @overload740    def __ror__(741        self,742        other: Mapping[str, Any],743    ) -> RunnableSerializable[Any, Output]: ...744745    @overload746    def __ror__(747        self,748        other: Callable[[Other], Runnable[Other, Input]]749        | Callable[[Other], Awaitable[Runnable[Other, Input]]],750    ) -> RunnableSerializable[Other, Output]: ...751752    @overload753    def __ror__(754        self,755        other: Runnable[Other, Input]756        | Callable[[Iterator[Other]], Iterator[Input]]757        | Callable[[AsyncIterator[Other]], AsyncIterator[Input]]758        | Callable[[Other], Input],759    ) -> RunnableSerializable[Other, Output]: ...760761    def __ror__(762        self,763        other: Runnable[Other, Input]764        | Callable[[Iterator[Other]], Iterator[Input]]765        | Callable[[AsyncIterator[Other]], AsyncIterator[Input]]766        | Callable[[Other], Any]767        | Mapping[str, Runnable[Other, Input] | Callable[[Other], Any] | Any],768    ) -> RunnableSerializable[Any, Output]:769        """Runnable "reverse-or" operator.770771        Compose this `Runnable` with another object to create a772        `RunnableSequence`.773774        Args:775            other: Another `Runnable` or a `Runnable`-like object.776777        Returns:778            A new `Runnable`.779780        Raises:781            TypeError: If `other` cannot be coerced to a `Runnable`. This method does782                not return `NotImplemented`, to avoid delegating LCEL composition to783                unrelated reflected `|` implementations. To interoperate, implement784                `Runnable`, make the object callable, or define `__or__` on the left.785        """786        return RunnableSequence(coerce_to_runnable(other), self)787788    def pipe(789        self,790        *others: Runnable[Any, Other] | Callable[[Any], Other],791        name: str | None = None,792    ) -> RunnableSerializable[Input, Other]:793        """Pipe `Runnable` objects.794795        Compose this `Runnable` with `Runnable`-like objects to make a796        `RunnableSequence`.797798        Equivalent to `RunnableSequence(self, *others)` or `self | others[0] | ...`799800        Example:801            ```python802            from langchain_core.runnables import RunnableLambda803804805            def add_one(x: int) -> int:806                return x + 1807808809            def mul_two(x: int) -> int:810                return x * 2811812813            runnable_1 = RunnableLambda(add_one)814            runnable_2 = RunnableLambda(mul_two)815            sequence = runnable_1.pipe(runnable_2)816            # Or equivalently:817            # sequence = runnable_1 | runnable_2818            # sequence = RunnableSequence(first=runnable_1, last=runnable_2)819            sequence.invoke(1)820            await sequence.ainvoke(1)821            # -> 4822823            sequence.batch([1, 2, 3])824            await sequence.abatch([1, 2, 3])825            # -> [4, 6, 8]826            ```827828        Args:829            *others: Other `Runnable` or `Runnable`-like objects to compose830            name: An optional name for the resulting `RunnableSequence`.831832        Returns:833            A new `Runnable`.834        """835        return RunnableSequence(self, *others, name=name)836837    def pick(self, keys: str | list[str]) -> RunnableSerializable[Any, Any]:838        """Pick keys from the output `dict` of this `Runnable`.839840        !!! example "Pick a single key"841842            ```python843            import json844845            from langchain_core.runnables import RunnableLambda, RunnableMap846847            as_str = RunnableLambda(str)848            as_json = RunnableLambda(json.loads)849            chain = RunnableMap(str=as_str, json=as_json)850851            chain.invoke("[1, 2, 3]")852            # -> {"str": "[1, 2, 3]", "json": [1, 2, 3]}853854            json_only_chain = chain.pick("json")855            json_only_chain.invoke("[1, 2, 3]")856            # -> [1, 2, 3]857            ```858859        !!! example "Pick a list of keys"860861            ```python862            from typing import Any863864            import json865866            from langchain_core.runnables import RunnableLambda, RunnableMap867868            as_str = RunnableLambda(str)869            as_json = RunnableLambda(json.loads)870871872            def as_bytes(x: Any) -> bytes:873                return bytes(x, "utf-8")874875876            chain = RunnableMap(877                str=as_str, json=as_json, bytes=RunnableLambda(as_bytes)878            )879880            chain.invoke("[1, 2, 3]")881            # -> {"str": "[1, 2, 3]", "json": [1, 2, 3], "bytes": b"[1, 2, 3]"}882883            json_and_bytes_chain = chain.pick(["json", "bytes"])884            json_and_bytes_chain.invoke("[1, 2, 3]")885            # -> {"json": [1, 2, 3], "bytes": b"[1, 2, 3]"}886            ```887888        Args:889            keys: A key or list of keys to pick from the output dict.890891        Returns:892            a new `Runnable`.893894        """895        # Import locally to prevent circular import896        from langchain_core.runnables.passthrough import RunnablePick  # noqa: PLC0415897898        return self | RunnablePick(keys)  # type: ignore[operator, no-any-return]899900    def assign(901        self,902        **kwargs: Runnable[dict[str, Any], Any]903        | Callable[[dict[str, Any]], Any]904        | Mapping[str, Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any]],905    ) -> RunnableSerializable[Any, Any]:906        """Assigns new fields to the `dict` output of this `Runnable`.907908        ```python909        from langchain_core.language_models.fake import FakeStreamingListLLM910        from langchain_core.output_parsers import StrOutputParser911        from langchain_core.prompts import SystemMessagePromptTemplate912        from langchain_core.runnables import Runnable913        from operator import itemgetter914915        prompt = (916            SystemMessagePromptTemplate.from_template("You are a nice assistant.")917            + "{question}"918        )919        model = FakeStreamingListLLM(responses=["foo-lish"])920921        chain: Runnable = prompt | model | {"str": StrOutputParser()}922923        chain_with_assign = chain.assign(hello=itemgetter("str") | model)924925        print(chain_with_assign.input_schema.model_json_schema())926        # {'title': 'PromptInput', 'type': 'object', 'properties':927        {'question': {'title': 'Question', 'type': 'string'}}}928        print(chain_with_assign.output_schema.model_json_schema())929        # {'title': 'RunnableSequenceOutput', 'type': 'object', 'properties':930        {'str': {'title': 'Str',931        'type': 'string'}, 'hello': {'title': 'Hello', 'type': 'string'}}}932        ```933934        Args:935            **kwargs: A mapping of keys to `Runnable` or `Runnable`-like objects936                that will be invoked with the entire output dict of this `Runnable`.937938        Returns:939            A new `Runnable`.940941        """942        # Import locally to prevent circular import943        from langchain_core.runnables.passthrough import RunnableAssign  # noqa: PLC0415944945        return self | RunnableAssign(RunnableParallel[dict[str, Any]](kwargs))  # type: ignore[operator, no-any-return]946947    """ --- Public API --- """948949    @abstractmethod950    def invoke(951        self,952        input: Input,953        config: RunnableConfig | None = None,954        **kwargs: Any,955    ) -> Output:956        """Transform a single input into an output.957958        Args:959            input: The input to the `Runnable`.960            config: A config to use when invoking the `Runnable`.961962                The config supports standard keys like `'tags'`, `'metadata'` for963                tracing purposes, `'max_concurrency'` for controlling how much work to964                do in parallel, and other keys.965966                Please refer to `RunnableConfig` for more details.967968        Returns:969            The output of the `Runnable`.970        """971972    async def ainvoke(973        self,974        input: Input,975        config: RunnableConfig | None = None,976        **kwargs: Any,977    ) -> Output:978        """Transform a single input into an output.979980        Args:981            input: The input to the `Runnable`.982            config: A config to use when invoking the `Runnable`.983984                The config supports standard keys like `'tags'`, `'metadata'` for985                tracing purposes, `'max_concurrency'` for controlling how much work to986                do in parallel, and other keys.987988                Please refer to `RunnableConfig` for more details.989990        Returns:991            The output of the `Runnable`.992        """993        return await run_in_executor(config, self.invoke, input, config, **kwargs)994995    def batch(996        self,997        inputs: list[Input],998        config: RunnableConfig | list[RunnableConfig] | None = None,999        *,1000        return_exceptions: bool = False,1001        **kwargs: Any | None,1002    ) -> list[Output]:1003        """Default implementation runs invoke in parallel using a thread pool executor.10041005        The default implementation of batch works well for IO bound runnables.10061007        Subclasses must override this method if they can batch more efficiently;1008        e.g., if the underlying `Runnable` uses an API which supports a batch mode.10091010        Args:1011            inputs: A list of inputs to the `Runnable`.1012            config: A config to use when invoking the `Runnable`. The config supports1013                standard keys like `'tags'`, `'metadata'` for1014                tracing purposes, `'max_concurrency'` for controlling how much work1015                to do in parallel, and other keys.10161017                Please refer to `RunnableConfig` for more details.1018            return_exceptions: Whether to return exceptions instead of raising them.1019            **kwargs: Additional keyword arguments to pass to the `Runnable`.10201021        Returns:1022            A list of outputs from the `Runnable`.1023        """1024        if not inputs:1025            return []10261027        configs = get_config_list(config, len(inputs))10281029        def invoke(input_: Input, config: RunnableConfig) -> Output | Exception:1030            if return_exceptions:1031                try:1032                    return self.invoke(input_, config, **kwargs)1033                except Exception as e:1034                    return e1035            else:1036                return self.invoke(input_, config, **kwargs)10371038        # If there's only one input, don't bother with the executor1039        if len(inputs) == 1:1040            return cast("list[Output]", [invoke(inputs[0], configs[0])])10411042        with get_executor_for_config(configs[0]) as executor:1043            return cast("list[Output]", list(executor.map(invoke, inputs, configs)))10441045    @overload1046    def batch_as_completed(1047        self,1048        inputs: Sequence[Input],1049        config: RunnableConfig | Sequence[RunnableConfig] | None = None,1050        *,1051        return_exceptions: Literal[False] = False,1052        **kwargs: Any,1053    ) -> Iterator[tuple[int, Output]]: ...10541055    @overload1056    def batch_as_completed(1057        self,1058        inputs: Sequence[Input],1059        config: RunnableConfig | Sequence[RunnableConfig] | None = None,1060        *,1061        return_exceptions: Literal[True],1062        **kwargs: Any,1063    ) -> Iterator[tuple[int, Output | Exception]]: ...10641065    def batch_as_completed(1066        self,1067        inputs: Sequence[Input],1068        config: RunnableConfig | Sequence[RunnableConfig] | None = None,1069        *,1070        return_exceptions: bool = False,1071        **kwargs: Any | None,1072    ) -> Iterator[tuple[int, Output | Exception]]:1073        """Run `invoke` in parallel on a list of inputs.10741075        Yields results as they complete.10761077        Args:1078            inputs: A list of inputs to the `Runnable`.1079            config: A config to use when invoking the `Runnable`.10801081                The config supports standard keys like `'tags'`, `'metadata'` for1082                tracing purposes, `'max_concurrency'` for controlling how much work to1083                do in parallel, and other keys.10841085                Please refer to `RunnableConfig` for more details.1086            return_exceptions: Whether to return exceptions instead of raising them.1087            **kwargs: Additional keyword arguments to pass to the `Runnable`.10881089        Yields:1090            Tuples of the index of the input and the output from the `Runnable`.10911092        """1093        if not inputs:1094            return10951096        configs = get_config_list(config, len(inputs))10971098        def invoke(1099            i: int, input_: Input, config: RunnableConfig1100        ) -> tuple[int, Output | Exception]:1101            if return_exceptions:1102                try:1103                    out: Output | Exception = self.invoke(input_, config, **kwargs)1104                except Exception as e:1105                    out = e1106            else:1107                out = self.invoke(input_, config, **kwargs)11081109            return (i, out)11101111        if len(inputs) == 1:1112            yield invoke(0, inputs[0], configs[0])1113            return11141115        with get_executor_for_config(configs[0]) as executor:1116            futures = {1117                executor.submit(invoke, i, input_, config)1118                for i, (input_, config) in enumerate(zip(inputs, configs, strict=False))1119            }11201121            try:1122                while futures:1123                    done, futures = wait(futures, return_when=FIRST_COMPLETED)1124                    while done:1125                        yield done.pop().result()1126            finally:1127                for future in futures:1128                    future.cancel()11291130    async def abatch(1131        self,1132        inputs: list[Input],1133        config: RunnableConfig | list[RunnableConfig] | None = None,1134        *,1135        return_exceptions: bool = False,1136        **kwargs: Any | None,1137    ) -> list[Output]:1138        """Default implementation runs `ainvoke` in parallel using `asyncio.gather`.11391140        The default implementation of `batch` works well for IO bound runnables.11411142        Subclasses must override this method if they can batch more efficiently;1143        e.g., if the underlying `Runnable` uses an API which supports a batch mode.11441145        Args:1146            inputs: A list of inputs to the `Runnable`.1147            config: A config to use when invoking the `Runnable`.11481149                The config supports standard keys like `'tags'`, `'metadata'` for1150                tracing purposes, `'max_concurrency'` for controlling how much work to1151                do in parallel, and other keys.11521153                Please refer to `RunnableConfig` for more details.1154            return_exceptions: Whether to return exceptions instead of raising them.1155            **kwargs: Additional keyword arguments to pass to the `Runnable`.11561157        Returns:1158            A list of outputs from the `Runnable`.11591160        """1161        if not inputs:1162            return []11631164        configs = get_config_list(config, len(inputs))11651166        async def ainvoke(value: Input, config: RunnableConfig) -> Output | Exception:1167            if return_exceptions:1168                try:1169                    return await self.ainvoke(value, config, **kwargs)1170                except Exception as e:1171                    return e1172            else:1173                return await self.ainvoke(value, config, **kwargs)11741175        coros = map(ainvoke, inputs, configs)1176        return await gather_with_concurrency(configs[0].get("max_concurrency"), *coros)11771178    @overload1179    def abatch_as_completed(1180        self,1181        inputs: Sequence[Input],1182        config: RunnableConfig | Sequence[RunnableConfig] | None = None,1183        *,1184        return_exceptions: Literal[False] = False,1185        **kwargs: Any | None,1186    ) -> AsyncIterator[tuple[int, Output]]: ...11871188    @overload1189    def abatch_as_completed(1190        self,1191        inputs: Sequence[Input],1192        config: RunnableConfig | Sequence[RunnableConfig] | None = None,1193        *,1194        return_exceptions: Literal[True],1195        **kwargs: Any | None,1196    ) -> AsyncIterator[tuple[int, Output | Exception]]: ...11971198    async def abatch_as_completed(1199        self,1200        inputs: Sequence[Input],1201        config: RunnableConfig | Sequence[RunnableConfig] | None = None,1202        *,1203        return_exceptions: bool = False,1204        **kwargs: Any | None,1205    ) -> AsyncIterator[tuple[int, Output | Exception]]:1206        """Run `ainvoke` in parallel on a list of inputs.12071208        Yields results as they complete.12091210        Args:1211            inputs: A list of inputs to the `Runnable`.1212            config: A config to use when invoking the `Runnable`.12131214                The config supports standard keys like `'tags'`, `'metadata'` for1215                tracing purposes, `'max_concurrency'` for controlling how much work to1216                do in parallel, and other keys.12171218                Please refer to `RunnableConfig` for more details.1219            return_exceptions: Whether to return exceptions instead of raising them.1220            **kwargs: Additional keyword arguments to pass to the `Runnable`.12211222        Yields:1223            A tuple of the index of the input and the output from the `Runnable`.12241225        """1226        if not inputs:1227            return12281229        configs = get_config_list(config, len(inputs))1230        # Get max_concurrency from first config, defaulting to None (unlimited)1231        max_concurrency = configs[0].get("max_concurrency") if configs else None1232        semaphore = asyncio.Semaphore(max_concurrency) if max_concurrency else None12331234        async def ainvoke_task(1235            i: int, input_: Input, config: RunnableConfig1236        ) -> tuple[int, Output | Exception]:1237            if return_exceptions:1238                try:1239                    out: Output | Exception = await self.ainvoke(1240                        input_, config, **kwargs1241                    )1242                except Exception as e:1243                    out = e1244            else:1245                out = await self.ainvoke(input_, config, **kwargs)1246            return (i, out)12471248        coros = [1249            gated_coro(semaphore, ainvoke_task(i, input_, config))1250            if semaphore1251            else ainvoke_task(i, input_, config)1252            for i, (input_, config) in enumerate(zip(inputs, configs, strict=False))1253        ]12541255        for coro in asyncio.as_completed(coros):1256            yield await coro12571258    def stream(1259        self,1260        input: Input,1261        config: RunnableConfig | None = None,1262        **kwargs: Any | None,1263    ) -> Iterator[Output]:1264        """Default implementation of `stream`, which calls `invoke`.12651266        Subclasses must override this method if they support streaming output.12671268        Args:1269            input: The input to the `Runnable`.1270            config: The config to use for the `Runnable`.1271            **kwargs: Additional keyword arguments to pass to the `Runnable`.12721273        Yields:1274            The output of the `Runnable`.12751276        """1277        yield self.invoke(input, config, **kwargs)12781279    async def astream(1280        self,1281        input: Input,1282        config: RunnableConfig | None = None,1283        **kwargs: Any | None,1284    ) -> AsyncIterator[Output]:1285        """Default implementation of `astream`, which calls `ainvoke`.12861287        Subclasses must override this method if they support streaming output.12881289        Args:1290            input: The input to the `Runnable`.1291            config: The config to use for the `Runnable`.1292            **kwargs: Additional keyword arguments to pass to the `Runnable`.12931294        Yields:1295            The output of the `Runnable`.12961297        """1298        yield await self.ainvoke(input, config, **kwargs)12991300    @overload1301    def astream_log(1302        self,1303        input: Any,1304        config: RunnableConfig | None = None,1305        *,1306        diff: Literal[True] = True,1307        with_streamed_output_list: bool = True,1308        include_names: Sequence[str] | None = None,1309        include_types: Sequence[str] | None = None,1310        include_tags: Sequence[str] | None = None,1311        exclude_names: Sequence[str] | None = None,1312        exclude_types: Sequence[str] | None = None,1313        exclude_tags: Sequence[str] | None = None,1314        **kwargs: Any,1315    ) -> AsyncIterator[RunLogPatch]: ...13161317    @overload1318    def astream_log(1319        self,1320        input: Any,1321        config: RunnableConfig | None = None,1322        *,1323        diff: Literal[False],1324        with_streamed_output_list: bool = True,1325        include_names: Sequence[str] | None = None,1326        include_types: Sequence[str] | None = None,1327        include_tags: Sequence[str] | None = None,1328        exclude_names: Sequence[str] | None = None,1329        exclude_types: Sequence[str] | None = None,1330        exclude_tags: Sequence[str] | None = None,1331        **kwargs: Any,1332    ) -> AsyncIterator[RunLog]: ...13331334    async def astream_log(1335        self,1336        input: Any,1337        config: RunnableConfig | None = None,1338        *,1339        diff: bool = True,1340        with_streamed_output_list: bool = True,1341        include_names: Sequence[str] | None = None,1342        include_types: Sequence[str] | None = None,1343        include_tags: Sequence[str] | None = None,1344        exclude_names: Sequence[str] | None = None,1345        exclude_types: Sequence[str] | None = None,1346        exclude_tags: Sequence[str] | None = None,1347        **kwargs: Any,1348    ) -> AsyncIterator[RunLogPatch] | AsyncIterator[RunLog]:1349        """Stream all output from a `Runnable`, as reported to the callback system.13501351        This includes all inner runs of LLMs, Retrievers, Tools, etc.13521353        Output is streamed as Log objects, which include a list of1354        Jsonpatch ops that describe how the state of the run has changed in each1355        step, and the final state of the run.13561357        The Jsonpatch ops can be applied in order to construct state.13581359        Args:1360            input: The input to the `Runnable`.1361            config: The config to use for the `Runnable`.1362            diff: Whether to yield diffs between each step or the current state.1363            with_streamed_output_list: Whether to yield the `streamed_output` list.1364            include_names: Only include logs with these names.1365            include_types: Only include logs with these types.1366            include_tags: Only include logs with these tags.1367            exclude_names: Exclude logs with these names.1368            exclude_types: Exclude logs with these types.1369            exclude_tags: Exclude logs with these tags.1370            **kwargs: Additional keyword arguments to pass to the `Runnable`.13711372        Yields:1373            A `RunLogPatch` or `RunLog` object.13741375        """1376        warn_deprecated(1377            since="1.3.3",1378            message=("astream_log is deprecated. Use astream instead."),1379            removal="2.0.0",1380        )1381        stream = LogStreamCallbackHandler(1382            auto_close=False,1383            include_names=include_names,1384            include_types=include_types,1385            include_tags=include_tags,1386            exclude_names=exclude_names,1387            exclude_types=exclude_types,1388            exclude_tags=exclude_tags,1389            _schema_format="original",1390        )13911392        # Mypy isn't resolving the overloads here1393        # Likely an issue b/c `self` is being passed through1394        # and it's can't map it to Runnable[Input,Output]?1395        async for item in _astream_log_implementation(  # type: ignore[call-overload]1396            self,1397            input,1398            config,1399            diff=diff,1400            stream=stream,1401            with_streamed_output_list=with_streamed_output_list,1402            **kwargs,1403        ):1404            yield item14051406    @overload1407    def astream_events(1408        self,1409        input: Any,1410        config: RunnableConfig | None = None,1411        *,1412        version: Literal["v1", "v2"] = "v2",1413        include_names: Sequence[str] | None = None,1414        include_types: Sequence[str] | None = None,1415        include_tags: Sequence[str] | None = None,1416        exclude_names: Sequence[str] | None = None,1417        exclude_types: Sequence[str] | None = None,1418        exclude_tags: Sequence[str] | None = None,1419        **kwargs: Any,1420    ) -> AsyncIterator[StreamEvent]: ...14211422    @overload1423    def astream_events(1424        self,1425        input: Any,1426        config: RunnableConfig | None = None,1427        *,1428        version: Literal["v3"],1429        **kwargs: Any,1430    ) -> Awaitable[Any]: ...14311432    def astream_events(1433        self,1434        input: Any,1435        config: RunnableConfig | None = None,1436        *,1437        version: Literal["v1", "v2", "v3"] = "v2",1438        include_names: Sequence[str] | None = None,1439        include_types: Sequence[str] | None = None,1440        include_tags: Sequence[str] | None = None,1441        exclude_names: Sequence[str] | None = None,1442        exclude_types: Sequence[str] | None = None,1443        exclude_tags: Sequence[str] | None = None,1444        **kwargs: Any,1445    ) -> AsyncIterator[StreamEvent] | Awaitable[Any]:1446        """Generate a stream of events.14471448        Use to create an iterator over `StreamEvent` that provide real-time information1449        about the progress of the `Runnable`, including `StreamEvent` from intermediate1450        results.14511452        A `StreamEvent` is a dictionary with the following schema:14531454        - `event`: Event names are of the format:1455            `on_[runnable_type]_(start|stream|end)`.1456        - `name`: The name of the `Runnable` that generated the event.1457        - `run_id`: Randomly generated ID associated with the given execution of the1458            `Runnable` that emitted the event. A child `Runnable` that gets invoked as1459            part of the execution of a parent `Runnable` is assigned its own unique ID.1460        - `parent_ids`: The IDs of the parent runnables that generated the event. The1461            root `Runnable` will have an empty list. The order of the parent IDs is from1462            the root to the immediate parent. Only available for v2 version of the API.1463            The v1 version of the API will return an empty list.1464        - `tags`: The tags of the `Runnable` that generated the event.1465        - `metadata`: The metadata of the `Runnable` that generated the event.1466        - `data`: The data associated with the event. The contents of this field1467            depend on the type of event. See the table below for more details.14681469        Below is a table that illustrates some events that might be emitted by various1470        chains. Metadata fields have been omitted from the table for brevity.1471        Chain definitions have been included after the table.14721473        !!! note1474            This reference table is for the v2 version of the schema.14751476        | event                  | name                 | chunk                               | input                                             | output                                              |1477        | ---------------------- | -------------------- | ----------------------------------- | ------------------------------------------------- | --------------------------------------------------- |1478        | `on_chat_model_start`  | `'[model name]'`     |                                     | `{"messages": [[SystemMessage, HumanMessage]]}`   |                                                     |1479        | `on_chat_model_stream` | `'[model name]'`     | `AIMessageChunk(content="hello")`   |                                                   |                                                     |1480        | `on_chat_model_end`    | `'[model name]'`     |                                     | `{"messages": [[SystemMessage, HumanMessage]]}`   | `AIMessageChunk(content="hello world")`             |1481        | `on_llm_start`         | `'[model name]'`     |                                     | `{'input': 'hello'}`                              |                                                     |1482        | `on_llm_stream`        | `'[model name]'`     | `'Hello' `                          |                                                   |                                                     |1483        | `on_llm_end`           | `'[model name]'`     |                                     | `'Hello human!'`                                  |                                                     |1484        | `on_chain_start`       | `'format_docs'`      |                                     |                                                   |                                                     |1485        | `on_chain_stream`      | `'format_docs'`      | `'hello world!, goodbye world!'`    |                                                   |                                                     |1486        | `on_chain_end`         | `'format_docs'`      |                                     | `[Document(...)]`                                 | `'hello world!, goodbye world!'`                    |1487        | `on_tool_start`        | `'some_tool'`        |                                     | `{"x": 1, "y": "2"}`                              |                                                     |1488        | `on_tool_end`          | `'some_tool'`        |                                     |                                                   | `{"x": 1, "y": "2"}`                                |1489        | `on_retriever_start`   | `'[retriever name]'` |                                     | `{"query": "hello"}`                              |                                                     |1490        | `on_retriever_end`     | `'[retriever name]'` |                                     | `{"query": "hello"}`                              | `[Document(...), ..]`                               |1491        | `on_prompt_start`      | `'[template_name]'`  |                                     | `{"question": "hello"}`                           |                                                     |1492        | `on_prompt_end`        | `'[template_name]'`  |                                     | `{"question": "hello"}`                           | `ChatPromptValue(messages: [SystemMessage, ...])`   |14931494        In addition to the standard events, users can also dispatch custom events (see example below).14951496        Custom events will be only be surfaced with in the v2 version of the API!14971498        A custom event has following format:14991500        | Attribute   | Type   | Description                                                                                               |1501        | ----------- | ------ | --------------------------------------------------------------------------------------------------------- |1502        | `name`      | `str`  | A user defined name for the event.                                                                        |1503        | `data`      | `Any`  | The data associated with the event. This can be anything, though we suggest making it JSON serializable.  |15041505        Here are declarations associated with the standard events shown above:15061507        `format_docs`:15081509        ```python1510        def format_docs(docs: list[Document]) -> str:1511            '''Format the docs.'''1512            return ", ".join([doc.page_content for doc in docs])151315141515        format_docs = RunnableLambda(format_docs)1516        ```15171518        `some_tool`:15191520        ```python1521        @tool1522        def some_tool(x: int, y: str) -> dict:1523            '''Some_tool.'''1524            return {"x": x, "y": y}1525        ```15261527        `prompt`:15281529        ```python1530        template = ChatPromptTemplate.from_messages(1531            [1532                ("system", "You are Cat Agent 007"),1533                ("human", "{question}"),1534            ]1535        ).with_config({"run_name": "my_template", "tags": ["my_template"]})1536        ```15371538        !!! example15391540            ```python1541            from langchain_core.runnables import RunnableLambda154215431544            async def reverse(s: str) -> str:1545                return s[::-1]154615471548            chain = RunnableLambda(func=reverse)15491550            events = [1551                event async for event in chain.astream_events("hello", version="v2")1552            ]15531554            # Will produce the following events1555            # (run_id, and parent_ids has been omitted for brevity):1556            [1557                {1558                    "data": {"input": "hello"},1559                    "event": "on_chain_start",1560                    "metadata": {},1561                    "name": "reverse",1562                    "tags": [],1563                },1564                {1565                    "data": {"chunk": "olleh"},1566                    "event": "on_chain_stream",1567                    "metadata": {},1568                    "name": "reverse",1569                    "tags": [],1570                },1571                {1572                    "data": {"output": "olleh"},1573                    "event": "on_chain_end",1574                    "metadata": {},1575                    "name": "reverse",1576                    "tags": [],1577                },1578            ]1579            ```15801581        ```python title="Dispatch custom event"1582        from langchain_core.callbacks.manager import (1583            adispatch_custom_event,1584        )1585        from langchain_core.runnables import RunnableLambda, RunnableConfig1586        import asyncio158715881589        async def slow_thing(some_input: str, config: RunnableConfig) -> str:1590            \"\"\"Do something that takes a long time.\"\"\"1591            await asyncio.sleep(1) # Placeholder for some slow operation1592            await adispatch_custom_event(1593                "progress_event",1594                {"message": "Finished step 1 of 3"},1595                config=config1596            )1597            await asyncio.sleep(1) # Placeholder for some slow operation1598            await adispatch_custom_event(1599                "progress_event",1600                {"message": "Finished step 2 of 3"},1601                config=config1602            )1603            await asyncio.sleep(1) # Placeholder for some slow operation1604            return "Done"16051606        slow_thing = RunnableLambda(slow_thing)16071608        async for event in slow_thing.astream_events("some_input", version="v2"):1609            print(event)1610        ```16111612        Args:1613            input: The input to the `Runnable`.1614            config: The config to use for the `Runnable`.1615            version: The version of the schema to use. One of `'v1'`, `'v2'`,1616                or `'v3'`.16171618                Most callers should use `'v2'` (the default), which yields1619                `StreamEvent` dicts and supports custom events.16201621                `'v3'` selects the typed, content-block-centric streaming1622                protocol and is only supported on `Runnable` subclasses that1623                implement it (currently `BaseChatModel` and1624                `langgraph.CompiledGraph`); on a generic `Runnable` it raises1625                `NotImplementedError`. The `'v3'` API is in beta and may1626                change. See the subclass override (e.g.1627                `BaseChatModel.astream_events`) for the v3 return shape.16281629                `'v1'` is retained for backwards compatibility and will be1630                deprecated in `0.4.0`. Custom events are only surfaced in1631                `'v2'` / `'v3'`.1632            include_names: Only include events from `Runnable` objects with matching names.1633            include_types: Only include events from `Runnable` objects with matching types.1634            include_tags: Only include events from `Runnable` objects with matching tags.1635            exclude_names: Exclude events from `Runnable` objects with matching names.1636            exclude_types: Exclude events from `Runnable` objects with matching types.1637            exclude_tags: Exclude events from `Runnable` objects with matching tags.1638            **kwargs: Additional keyword arguments to pass to the `Runnable`.16391640        Yields:1641            An async stream of `StreamEvent`.16421643        Raises:1644            NotImplementedError: If the version is not `'v1'`, `'v2'`, or `'v3'`, or1645                if `'v3'` is requested on a `Runnable` that does not implement the v31646                streaming protocol.16471648        """  # noqa: E5011649        if version == "v3":1650            return self._astream_events_v3_unsupported()1651        return self._astream_events_v1_v2(1652            input,1653            config=config,1654            version=version,1655            include_names=include_names,1656            include_types=include_types,1657            include_tags=include_tags,1658            exclude_names=exclude_names,1659            exclude_types=exclude_types,1660            exclude_tags=exclude_tags,1661            **kwargs,1662        )16631664    async def _astream_events_v3_unsupported(self) -> Any:1665        """Coroutine that raises when v3 isn't implemented on this Runnable.16661667        Lets the public `astream_events(version="v3")` return an awaitable1668        whose error surfaces on `await`, matching the v3 contract on1669        subclasses that do implement the protocol.1670        """1671        msg = (1672            "astream_events(version='v3') is only supported on Runnable "1673            "subclasses that implement the v3 streaming protocol "1674            "(BaseChatModel, CompiledGraph). "1675            f"Got: {type(self).__name__}"1676        )1677        raise NotImplementedError(msg)16781679    async def _astream_events_v1_v2(1680        self,1681        input: Any,1682        config: RunnableConfig | None = None,1683        *,1684        version: Literal["v1", "v2"] = "v2",1685        include_names: Sequence[str] | None = None,1686        include_types: Sequence[str] | None = None,1687        include_tags: Sequence[str] | None = None,1688        exclude_names: Sequence[str] | None = None,1689        exclude_types: Sequence[str] | None = None,1690        exclude_tags: Sequence[str] | None = None,1691        **kwargs: Any,1692    ) -> AsyncIterator[StreamEvent]:1693        if version == "v2":1694            event_stream = _astream_events_implementation_v2(1695                self,1696                input,1697                config=config,1698                include_names=include_names,1699                include_types=include_types,1700                include_tags=include_tags,1701                exclude_names=exclude_names,1702                exclude_types=exclude_types,1703                exclude_tags=exclude_tags,1704                **kwargs,1705            )1706        elif version == "v1":1707            warn_deprecated(1708                since="1.3.3",1709                message=(1710                    "astream_events version='v1' is deprecated. "1711                    "Use version='v2' or astream instead."1712                ),1713                removal="2.0.0",1714            )1715            # First implementation, built on top of astream_log API1716            # This implementation will be deprecated as of 0.2.01717            event_stream = _astream_events_implementation_v1(1718                self,1719                input,1720                config=config,1721                include_names=include_names,1722                include_types=include_types,1723                include_tags=include_tags,1724                exclude_names=exclude_names,1725                exclude_types=exclude_types,1726                exclude_tags=exclude_tags,1727                **kwargs,1728            )1729        else:1730            msg = f"Unsupported version: {version!r}. Expected 'v1', 'v2', or 'v3'."  # type: ignore[unreachable]1731            raise NotImplementedError(msg)17321733        async with aclosing(event_stream):1734            async for event in event_stream:1735                yield event17361737    @overload1738    def stream_events(1739        self,1740        input: Any,1741        config: RunnableConfig | None = None,1742        *,1743        version: Literal["v1", "v2"] = "v2",1744        include_names: Sequence[str] | None = None,1745        include_types: Sequence[str] | None = None,1746        include_tags: Sequence[str] | None = None,1747        exclude_names: Sequence[str] | None = None,1748        exclude_types: Sequence[str] | None = None,1749        exclude_tags: Sequence[str] | None = None,1750        **kwargs: Any,1751    ) -> Iterator[StreamEvent]: ...17521753    @overload1754    def stream_events(1755        self,1756        input: Any,1757        config: RunnableConfig | None = None,1758        *,1759        version: Literal["v3"],1760        **kwargs: Any,1761    ) -> Iterator[Any]: ...17621763    def stream_events(1764        self,1765        input: Any,1766        config: RunnableConfig | None = None,1767        *,1768        version: Literal["v1", "v2", "v3"] = "v2",1769        include_names: Sequence[str] | None = None,1770        include_types: Sequence[str] | None = None,1771        include_tags: Sequence[str] | None = None,1772        exclude_names: Sequence[str] | None = None,1773        exclude_types: Sequence[str] | None = None,1774        exclude_tags: Sequence[str] | None = None,1775        **kwargs: Any,1776    ) -> Iterator[StreamEvent] | Iterator[Any]:1777        """Generate a stream of events synchronously.17781779        Synchronous counterpart to `astream_events`. For `version='v3'`, subclasses1780        that implement the v3 streaming protocol (`BaseChatModel`, `CompiledGraph`)1781        override this method. All other versions and base-class calls raise1782        `NotImplementedError`.17831784        Args:1785            input: The input to the `Runnable`.1786            config: The config to use for the `Runnable`.1787            version: The version of the schema to use. `'v3'` requires a subclass1788                that implements the v3 streaming protocol. `'v1'` and `'v2'` are not1789                supported on the sync path.1790            include_names: Only include events from `Runnable` objects with matching1791                names.1792            include_types: Only include events from `Runnable` objects with matching1793                types.1794            include_tags: Only include events from `Runnable` objects with matching1795                tags.1796            exclude_names: Exclude events from `Runnable` objects with matching names.1797            exclude_types: Exclude events from `Runnable` objects with matching types.1798            exclude_tags: Exclude events from `Runnable` objects with matching tags.1799            **kwargs: Additional keyword arguments to pass to the `Runnable`.18001801        Raises:1802            NotImplementedError: Always. Subclasses override this method for supported1803                versions.18041805        """1806        # Base impl always raises; consume args so they don't trip ARG002.1807        del input, config, include_names, include_types, include_tags1808        del exclude_names, exclude_types, exclude_tags, kwargs1809        if version == "v3":1810            msg = (1811                "stream_events(version='v3') is only supported on Runnable subclasses "1812                "that implement the v3 streaming protocol "1813                "(BaseChatModel, CompiledGraph). "1814                f"Got: {type(self).__name__}"1815            )1816            raise NotImplementedError(msg)1817        msg = (1818            f"stream_events(version={version!r}) is not supported. "1819            "Use astream_events() for v1/v2, or stream_events(version='v3') "1820            "on a supported subclass."1821        )1822        raise NotImplementedError(msg)18231824    def transform(1825        self,1826        input: Iterator[Input],1827        config: RunnableConfig | None = None,1828        **kwargs: Any | None,1829    ) -> Iterator[Output]:1830        """Transform inputs to outputs.18311832        Default implementation of transform, which buffers input and calls `astream`.18331834        Subclasses must override this method if they can start producing output while1835        input is still being generated.18361837        Args:1838            input: An iterator of inputs to the `Runnable`.1839            config: The config to use for the `Runnable`.1840            **kwargs: Additional keyword arguments to pass to the `Runnable`.18411842        Yields:1843            The output of the `Runnable`.18441845        """1846        accumulated = _ChunkAccumulator(stop_after_unaddable=False)1847        got_first_val = False18481849        for ichunk in input:1850            # The default implementation of transform is to buffer input and1851            # then call stream.1852            # It'll attempt to gather all input into a single chunk using1853            # the `+` operator.1854            # If the input is not addable, then we'll assume that we can1855            # only operate on the last chunk,1856            # and we'll iterate until we get to the last chunk.1857            accumulated.add(ichunk)1858            got_first_val = True18591860        if got_first_val:1861            yield from self.stream(accumulated.value, config, **kwargs)18621863    async def atransform(1864        self,1865        input: AsyncIterator[Input],1866        config: RunnableConfig | None = None,1867        **kwargs: Any | None,1868    ) -> AsyncIterator[Output]:1869        """Transform inputs to outputs.18701871        Default implementation of atransform, which buffers input and calls `astream`.18721873        Subclasses must override this method if they can start producing output while1874        input is still being generated.18751876        Args:1877            input: An async iterator of inputs to the `Runnable`.1878            config: The config to use for the `Runnable`.1879            **kwargs: Additional keyword arguments to pass to the `Runnable`.18801881        Yields:1882            The output of the `Runnable`.18831884        """1885        accumulated = _ChunkAccumulator(stop_after_unaddable=False)1886        got_first_val = False18871888        async for ichunk in input:1889            # The default implementation of transform is to buffer input and1890            # then call stream.1891            # It'll attempt to gather all input into a single chunk using1892            # the `+` operator.1893            # If the input is not addable, then we'll assume that we can1894            # only operate on the last chunk,1895            # and we'll iterate until we get to the last chunk.1896            accumulated.add(ichunk)1897            got_first_val = True18981899        if got_first_val:1900            async for output in self.astream(accumulated.value, config, **kwargs):1901                yield output19021903    def bind(self, **kwargs: Any) -> Runnable[Input, Output]:1904        """Bind arguments to a `Runnable`, returning a new `Runnable`.19051906        Useful when a `Runnable` in a chain requires an argument that is not1907        in the output of the previous `Runnable` or included in the user input.19081909        Args:1910            **kwargs: The arguments to bind to the `Runnable`.19111912        Returns:1913            A new `Runnable` with the arguments bound.19141915        Example:1916            ```python1917            from langchain_ollama import ChatOllama1918            from langchain_core.output_parsers import StrOutputParser19191920            model = ChatOllama(model="llama3.1")19211922            # Without bind1923            chain = model | StrOutputParser()19241925            chain.invoke("Repeat quoted words exactly: 'One two three four five.'")1926            # Output is 'One two three four five.'19271928            # With bind1929            chain = model.bind(stop=["three"]) | StrOutputParser()19301931            chain.invoke("Repeat quoted words exactly: 'One two three four five.'")1932            # Output is 'One two'1933            ```1934        """1935        return RunnableBinding(bound=self, kwargs=kwargs, config={})19361937    def with_config(1938        self,1939        config: RunnableConfig | None = None,1940        # Sadly Unpack is not well-supported by mypy so this will have to be untyped1941        **kwargs: Any,1942    ) -> Runnable[Input, Output]:1943        """Bind config to a `Runnable`, returning a new `Runnable`.19441945        Args:1946            config: The config to bind to the `Runnable`.1947            **kwargs: Additional keyword arguments to pass to the `Runnable`.19481949        Returns:1950            A new `Runnable` with the config bound.19511952        """1953        return RunnableBinding(1954            bound=self,1955            config=cast(1956                "RunnableConfig",1957                {**(config or {}), **kwargs},1958            ),1959            kwargs={},1960        )19611962    def with_listeners(1963        self,1964        *,1965        on_start: Callable[[Run], None]1966        | Callable[[Run, RunnableConfig], None]1967        | None = None,1968        on_end: Callable[[Run], None]1969        | Callable[[Run, RunnableConfig], None]1970        | None = None,1971        on_error: Callable[[Run], None]1972        | Callable[[Run, RunnableConfig], None]1973        | None = None,1974    ) -> Runnable[Input, Output]:1975        """Bind lifecycle listeners to a `Runnable`, returning a new `Runnable`.19761977        The Run object contains information about the run, including its `id`,1978        `type`, `input`, `output`, `error`, `start_time`, `end_time`, and1979        any tags or metadata added to the run.19801981        Args:1982            on_start: Called before the `Runnable` starts running, with the `Run`1983                object.1984            on_end: Called after the `Runnable` finishes running, with the `Run`1985                object.1986            on_error: Called if the `Runnable` throws an error, with the `Run`1987                object.19881989        Returns:1990            A new `Runnable` with the listeners bound.19911992        Example:1993            ```python1994            from langchain_core.runnables import RunnableLambda1995            from langchain_core.tracers.schemas import Run19961997            import time199819992000            def test_runnable(time_to_sleep: int):

Findings

✓ No findings reported for this file.

Get this view in your editor

Same data, no extra tab — call code_get_file + code_get_findings over MCP from Claude/Cursor/Copilot.

Generated by searchcode.com · powered by code_get_file + code_get_findings