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.