[docs]classRunnable(Generic[Input,Output],ABC):"""A unit of work that can be invoked, batched, streamed, transformed and composed. Key Methods =========== - **invoke/ainvoke**: Transforms a single input into an output. - **batch/abatch**: Efficiently transforms multiple inputs into outputs. - **stream/astream**: Streams output from a single input as it's produced. - **astream_log**: Streams output and selected intermediate results from an input. Built-in optimizations: - **Batch**: By default, batch runs invoke() in parallel using a thread pool executor. Override to optimize batching. - **Async**: Methods with "a" suffix are asynchronous. By default, they execute the sync counterpart using asyncio's thread pool. Override for native async. All methods accept an optional config argument, which can be used to configure execution, add tags and metadata for tracing and debugging etc. Runnables expose schematic information about their input, output and config via the input_schema property, the output_schema property and config_schema method. LCEL and Composition ==================== The LangChain Expression Language (LCEL) is a declarative way to compose Runnables into chains. Any chain constructed this way will automatically have sync, async, batch, and streaming support. The main composition primitives are RunnableSequence and RunnableParallel. **RunnableSequence** invokes a series of runnables sequentially, with one Runnable's output serving as the next's input. Construct using the `|` operator or by passing a list of runnables to RunnableSequence. **RunnableParallel** invokes runnables concurrently, providing the same input to each. Construct it using a dict literal within a sequence or by passing a dict to RunnableParallel. For example, .. code-block:: python from langchain_core.runnables import RunnableLambda # A RunnableSequence constructed using the `|` operator sequence = RunnableLambda(lambda x: x + 1) | RunnableLambda(lambda x: x * 2) sequence.invoke(1) # 4 sequence.batch([1, 2, 3]) # [4, 6, 8] # A sequence that contains a RunnableParallel constructed using a dict literal sequence = RunnableLambda(lambda x: x + 1) | { 'mul_2': RunnableLambda(lambda x: x * 2), 'mul_5': RunnableLambda(lambda x: x * 5) } sequence.invoke(1) # {'mul_2': 4, 'mul_5': 10} Standard Methods ================ All Runnables expose additional methods that can be used to modify their behavior (e.g., add a retry policy, add lifecycle listeners, make them configurable, etc.). These methods will work on any Runnable, including Runnable chains constructed by composing other Runnables. See the individual methods for details. For example, .. code-block:: python from langchain_core.runnables import RunnableLambda import random def add_one(x: int) -> int: return x + 1 def buggy_double(y: int) -> int: '''Buggy code that will fail 70% of the time''' if random.random() > 0.3: print('This code failed, and will probably be retried!') # noqa: T201 raise ValueError('Triggered buggy code') return y * 2 sequence = ( RunnableLambda(add_one) | RunnableLambda(buggy_double).with_retry( # Retry on failure stop_after_attempt=10, wait_exponential_jitter=False ) ) print(sequence.input_schema.schema()) # Show inferred input schema print(sequence.output_schema.schema()) # Show inferred output schema print(sequence.invoke(2)) # invoke the sequence (note the retry above!!) Debugging and tracing ===================== As the chains get longer, it can be useful to be able to see intermediate results to debug and trace the chain. You can set the global debug flag to True to enable debug output for all chains: .. code-block:: python from langchain_core.globals import set_debug set_debug(True) Alternatively, you can pass existing or custom callbacks to any given chain: .. code-block:: python from langchain_core.tracers import ConsoleCallbackHandler chain.invoke( ..., config={'callbacks': [ConsoleCallbackHandler()]} ) For a UI (and much more) checkout LangSmith: https://docs.smith.langchain.com/ """# noqa: E501name:Optional[str]=None"""The name of the Runnable. Used for debugging and tracing."""
[docs]defget_name(self,suffix:Optional[str]=None,*,name:Optional[str]=None)->str:"""Get the name of the Runnable."""name=nameorself.nameorself.__class__.__name__ifsuffix:ifname[0].isupper():returnname+suffix.title()else:returnname+"_"+suffix.lower()else:returnname
@propertydefInputType(self)->Type[Input]:"""The type of input this Runnable accepts specified as a type annotation."""forclsinself.__class__.__orig_bases__:# type: ignore[attr-defined]type_args=get_args(cls)iftype_argsandlen(type_args)==2:returntype_args[0]raiseTypeError(f"Runnable {self.get_name()} doesn't have an inferable InputType. ""Override the InputType property to specify the input type.")@propertydefOutputType(self)->Type[Output]:"""The type of output this Runnable produces specified as a type annotation."""forclsinself.__class__.__orig_bases__:# type: ignore[attr-defined]type_args=get_args(cls)iftype_argsandlen(type_args)==2:returntype_args[1]raiseTypeError(f"Runnable {self.get_name()} doesn't have an inferable OutputType. ""Override the OutputType property to specify the output type.")@propertydefinput_schema(self)->Type[BaseModel]:"""The type of input this Runnable accepts specified as a pydantic model."""returnself.get_input_schema()
[docs]defget_input_schema(self,config:Optional[RunnableConfig]=None)->Type[BaseModel]:"""Get a pydantic model that can be used to validate input to the Runnable. Runnables that leverage the configurable_fields and configurable_alternatives methods will have a dynamic input schema that depends on which configuration the Runnable is invoked with. This method allows to get an input schema for a specific configuration. Args: config: A config to use when generating the schema. Returns: A pydantic model that can be used to validate input. """root_type=self.InputTypeifinspect.isclass(root_type)andis_basemodel_subclass(root_type):returnroot_typereturncreate_model(self.get_name("Input"),__root__=(root_type,None),)
@propertydefoutput_schema(self)->Type[BaseModel]:"""The type of output this Runnable produces specified as a pydantic model."""returnself.get_output_schema()
[docs]defget_output_schema(self,config:Optional[RunnableConfig]=None)->Type[BaseModel]:"""Get a pydantic model that can be used to validate output to the Runnable. Runnables that leverage the configurable_fields and configurable_alternatives methods will have a dynamic output schema that depends on which configuration the Runnable is invoked with. This method allows to get an output schema for a specific configuration. Args: config: A config to use when generating the schema. Returns: A pydantic model that can be used to validate output. """root_type=self.OutputTypeifinspect.isclass(root_type)andis_basemodel_subclass(root_type):returnroot_typereturncreate_model(self.get_name("Output"),__root__=(root_type,None),)
@propertydefconfig_specs(self)->List[ConfigurableFieldSpec]:"""List configurable fields for this Runnable."""return[]
[docs]defconfig_schema(self,*,include:Optional[Sequence[str]]=None)->Type[BaseModel]:"""The type of config this Runnable accepts specified as a pydantic model. To mark a field as configurable, see the `configurable_fields` and `configurable_alternatives` methods. Args: include: A list of fields to include in the config schema. Returns: A pydantic model that can be used to validate config. """include=includeor[]config_specs=self.config_specsconfigurable=(create_model(# type: ignore[call-overload]"Configurable",**{spec.id:(spec.annotation,Field(spec.default,title=spec.name,description=spec.description),)forspecinconfig_specs},)ifconfig_specselseNone)returncreate_model(# type: ignore[call-overload]self.get_name("Config"),**({"configurable":(configurable,None)}ifconfigurableelse{}),**{field_name:(field_type,None)forfield_name,field_typeinRunnableConfig.__annotations__.items()iffield_namein[iforiinincludeifi!="configurable"]},)
[docs]defget_graph(self,config:Optional[RunnableConfig]=None)->Graph:"""Return a graph representation of this Runnable."""fromlangchain_core.runnables.graphimportGraphgraph=Graph()try:input_node=graph.add_node(self.get_input_schema(config))exceptTypeError:input_node=graph.add_node(create_model(self.get_name("Input")))runnable_node=graph.add_node(self,metadata=config.get("metadata")ifconfigelseNone)try:output_node=graph.add_node(self.get_output_schema(config))exceptTypeError:output_node=graph.add_node(create_model(self.get_name("Output")))graph.add_edge(input_node,runnable_node)graph.add_edge(runnable_node,output_node)returngraph
[docs]defget_prompts(self,config:Optional[RunnableConfig]=None)->List[BasePromptTemplate]:"""Return a list of prompts used by this Runnable."""fromlangchain_core.prompts.baseimportBasePromptTemplateprompts=[]for_,nodeinself.get_graph(config=config).nodes.items():ifisinstance(node.data,BasePromptTemplate):prompts.append(node.data)returnprompts
def__or__(self,other:Union[Runnable[Any,Other],Callable[[Any],Other],Callable[[Iterator[Any]],Iterator[Other]],Mapping[str,Union[Runnable[Any,Other],Callable[[Any],Other],Any]],],)->RunnableSerializable[Input,Other]:"""Compose this Runnable with another object to create a RunnableSequence."""returnRunnableSequence(self,coerce_to_runnable(other))def__ror__(self,other:Union[Runnable[Other,Any],Callable[[Other],Any],Callable[[Iterator[Other]],Iterator[Any]],Mapping[str,Union[Runnable[Other,Any],Callable[[Other],Any],Any]],],)->RunnableSerializable[Other,Output]:"""Compose this Runnable with another object to create a RunnableSequence."""returnRunnableSequence(coerce_to_runnable(other),self)
[docs]defpipe(self,*others:Union[Runnable[Any,Other],Callable[[Any],Other]],name:Optional[str]=None,)->RunnableSerializable[Input,Other]:"""Compose this Runnable with Runnable-like objects to make a RunnableSequence. Equivalent to `RunnableSequence(self, *others)` or `self | others[0] | ...` Example: .. code-block:: python from langchain_core.runnables import RunnableLambda def add_one(x: int) -> int: return x + 1 def mul_two(x: int) -> int: return x * 2 runnable_1 = RunnableLambda(add_one) runnable_2 = RunnableLambda(mul_two) sequence = runnable_1.pipe(runnable_2) # Or equivalently: # sequence = runnable_1 | runnable_2 # sequence = RunnableSequence(first=runnable_1, last=runnable_2) sequence.invoke(1) await sequence.ainvoke(1) # -> 4 sequence.batch([1, 2, 3]) await sequence.abatch([1, 2, 3]) # -> [4, 6, 8] """returnRunnableSequence(self,*others,name=name)
[docs]defassign(self,**kwargs:Union[Runnable[Dict[str,Any],Any],Callable[[Dict[str,Any]],Any],Mapping[str,Union[Runnable[Dict[str,Any],Any],Callable[[Dict[str,Any]],Any]],],],)->RunnableSerializable[Any,Any]:"""Assigns new fields to the dict output of this Runnable. Returns a new Runnable. .. code-block:: python from langchain_community.llms.fake import FakeStreamingListLLM from langchain_core.output_parsers import StrOutputParser from langchain_core.prompts import SystemMessagePromptTemplate from langchain_core.runnables import Runnable from operator import itemgetter prompt = ( SystemMessagePromptTemplate.from_template("You are a nice assistant.") + "{question}" ) llm = FakeStreamingListLLM(responses=["foo-lish"]) chain: Runnable = prompt | llm | {"str": StrOutputParser()} chain_with_assign = chain.assign(hello=itemgetter("str") | llm) print(chain_with_assign.input_schema.schema()) # {'title': 'PromptInput', 'type': 'object', 'properties': {'question': {'title': 'Question', 'type': 'string'}}} print(chain_with_assign.output_schema.schema()) # {'title': 'RunnableSequenceOutput', 'type': 'object', 'properties': {'str': {'title': 'Str', 'type': 'string'}, 'hello': {'title': 'Hello', 'type': 'string'}}} """fromlangchain_core.runnables.passthroughimportRunnableAssignreturnself|RunnableAssign(RunnableParallel(kwargs))
""" --- Public API --- """
[docs]@abstractmethoddefinvoke(self,input:Input,config:Optional[RunnableConfig]=None)->Output:"""Transform a single input into an output. Override to implement. Args: input: The input to the Runnable. config: A config to use when invoking the Runnable. The config supports standard keys like 'tags', 'metadata' for tracing purposes, 'max_concurrency' for controlling how much work to do in parallel, and other keys. Please refer to the RunnableConfig for more details. Returns: The output of the Runnable. """
[docs]asyncdefainvoke(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Any)->Output:"""Default implementation of ainvoke, calls invoke from a thread. The default implementation allows usage of async code even if the Runnable did not implement a native async version of invoke. Subclasses should override this method if they can run asynchronously. """returnawaitrun_in_executor(config,self.invoke,input,config,**kwargs)
[docs]defbatch(self,inputs:List[Input],config:Optional[Union[RunnableConfig,List[RunnableConfig]]]=None,*,return_exceptions:bool=False,**kwargs:Optional[Any],)->List[Output]:"""Default implementation runs invoke in parallel using a thread pool executor. The default implementation of batch works well for IO bound runnables. Subclasses should override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode. """ifnotinputs:return[]configs=get_config_list(config,len(inputs))definvoke(input:Input,config:RunnableConfig)->Union[Output,Exception]:ifreturn_exceptions:try:returnself.invoke(input,config,**kwargs)exceptExceptionase:returneelse:returnself.invoke(input,config,**kwargs)# If there's only one input, don't bother with the executoriflen(inputs)==1:returncast(List[Output],[invoke(inputs[0],configs[0])])withget_executor_for_config(configs[0])asexecutor:returncast(List[Output],list(executor.map(invoke,inputs,configs)))
[docs]defbatch_as_completed(self,inputs:Sequence[Input],config:Optional[Union[RunnableConfig,Sequence[RunnableConfig]]]=None,*,return_exceptions:bool=False,**kwargs:Optional[Any],)->Iterator[Tuple[int,Union[Output,Exception]]]:"""Run invoke in parallel on a list of inputs, yielding results as they complete."""ifnotinputs:returnconfigs=get_config_list(config,len(inputs))definvoke(i:int,input:Input,config:RunnableConfig)->Tuple[int,Union[Output,Exception]]:ifreturn_exceptions:try:out:Union[Output,Exception]=self.invoke(input,config,**kwargs)exceptExceptionase:out=eelse:out=self.invoke(input,config,**kwargs)return(i,out)iflen(inputs)==1:yieldinvoke(0,inputs[0],configs[0])returnwithget_executor_for_config(configs[0])asexecutor:futures={executor.submit(invoke,i,input,config)fori,(input,config)inenumerate(zip(inputs,configs))}try:whilefutures:done,futures=wait(futures,return_when=FIRST_COMPLETED)whiledone:yielddone.pop().result()finally:forfutureinfutures:future.cancel()
[docs]asyncdefabatch(self,inputs:List[Input],config:Optional[Union[RunnableConfig,List[RunnableConfig]]]=None,*,return_exceptions:bool=False,**kwargs:Optional[Any],)->List[Output]:"""Default implementation runs ainvoke in parallel using asyncio.gather. The default implementation of batch works well for IO bound runnables. Subclasses should override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode. Args: inputs: A list of inputs to the Runnable. config: A config to use when invoking the Runnable. The config supports standard keys like 'tags', 'metadata' for tracing purposes, 'max_concurrency' for controlling how much work to do in parallel, and other keys. Please refer to the RunnableConfig for more details. Defaults to None. return_exceptions: Whether to return exceptions instead of raising them. Defaults to False. kwargs: Additional keyword arguments to pass to the Runnable. Returns: A list of outputs from the Runnable. """ifnotinputs:return[]configs=get_config_list(config,len(inputs))asyncdefainvoke(input:Input,config:RunnableConfig)->Union[Output,Exception]:ifreturn_exceptions:try:returnawaitself.ainvoke(input,config,**kwargs)exceptExceptionase:returneelse:returnawaitself.ainvoke(input,config,**kwargs)coros=map(ainvoke,inputs,configs)returnawaitgather_with_concurrency(configs[0].get("max_concurrency"),*coros)
[docs]asyncdefabatch_as_completed(self,inputs:Sequence[Input],config:Optional[Union[RunnableConfig,Sequence[RunnableConfig]]]=None,*,return_exceptions:bool=False,**kwargs:Optional[Any],)->AsyncIterator[Tuple[int,Union[Output,Exception]]]:"""Run ainvoke in parallel on a list of inputs, yielding results as they complete. Args: inputs: A list of inputs to the Runnable. config: A config to use when invoking the Runnable. The config supports standard keys like 'tags', 'metadata' for tracing purposes, 'max_concurrency' for controlling how much work to do in parallel, and other keys. Please refer to the RunnableConfig for more details. Defaults to None. Defaults to None. return_exceptions: Whether to return exceptions instead of raising them. Defaults to False. kwargs: Additional keyword arguments to pass to the Runnable. Yields: A tuple of the index of the input and the output from the Runnable. """ifnotinputs:returnconfigs=get_config_list(config,len(inputs))asyncdefainvoke(i:int,input:Input,config:RunnableConfig)->Tuple[int,Union[Output,Exception]]:ifreturn_exceptions:try:out:Union[Output,Exception]=awaitself.ainvoke(input,config,**kwargs)exceptExceptionase:out=eelse:out=awaitself.ainvoke(input,config,**kwargs)return(i,out)coros=map(ainvoke,range(len(inputs)),inputs,configs)forcoroinasyncio.as_completed(coros):yieldawaitcoro
[docs]defstream(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->Iterator[Output]:""" Default implementation of stream, which calls invoke. Subclasses should override this method if they support streaming output. Args: input: The input to the Runnable. config: The config to use for the Runnable. Defaults to None. kwargs: Additional keyword arguments to pass to the Runnable. Yields: The output of the Runnable. """yieldself.invoke(input,config,**kwargs)
[docs]asyncdefastream(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->AsyncIterator[Output]:""" Default implementation of astream, which calls ainvoke. Subclasses should override this method if they support streaming output. Args: input: The input to the Runnable. config: The config to use for the Runnable. Defaults to None. kwargs: Additional keyword arguments to pass to the Runnable. Yields: The output of the Runnable. """yieldawaitself.ainvoke(input,config,**kwargs)
[docs]asyncdefastream_log(self,input:Any,config:Optional[RunnableConfig]=None,*,diff:bool=True,with_streamed_output_list:bool=True,include_names:Optional[Sequence[str]]=None,include_types:Optional[Sequence[str]]=None,include_tags:Optional[Sequence[str]]=None,exclude_names:Optional[Sequence[str]]=None,exclude_types:Optional[Sequence[str]]=None,exclude_tags:Optional[Sequence[str]]=None,**kwargs:Any,)->Union[AsyncIterator[RunLogPatch],AsyncIterator[RunLog]]:""" Stream all output from a Runnable, as reported to the callback system. This includes all inner runs of LLMs, Retrievers, Tools, etc. Output is streamed as Log objects, which include a list of Jsonpatch ops that describe how the state of the run has changed in each step, and the final state of the run. The Jsonpatch ops can be applied in order to construct state. Args: input: The input to the Runnable. config: The config to use for the Runnable. diff: Whether to yield diffs between each step or the current state. with_streamed_output_list: Whether to yield the streamed_output list. include_names: Only include logs with these names. include_types: Only include logs with these types. include_tags: Only include logs with these tags. exclude_names: Exclude logs with these names. exclude_types: Exclude logs with these types. exclude_tags: Exclude logs with these tags. kwargs: Additional keyword arguments to pass to the Runnable. Yields: A RunLogPatch or RunLog object. """fromlangchain_core.tracers.log_streamimport(LogStreamCallbackHandler,_astream_log_implementation,)stream=LogStreamCallbackHandler(auto_close=False,include_names=include_names,include_types=include_types,include_tags=include_tags,exclude_names=exclude_names,exclude_types=exclude_types,exclude_tags=exclude_tags,_schema_format="original",)# Mypy isn't resolving the overloads here# Likely an issue b/c `self` is being passed through# and it's can't map it to Runnable[Input,Output]?asyncforitemin_astream_log_implementation(# type: ignoreself,input,config,diff=diff,stream=stream,with_streamed_output_list=with_streamed_output_list,**kwargs,):yielditem
[docs]@beta_decorator.beta(message="This API is in beta and may change in the future.")asyncdefastream_events(self,input:Any,config:Optional[RunnableConfig]=None,*,version:Literal["v1","v2"],include_names:Optional[Sequence[str]]=None,include_types:Optional[Sequence[str]]=None,include_tags:Optional[Sequence[str]]=None,exclude_names:Optional[Sequence[str]]=None,exclude_types:Optional[Sequence[str]]=None,exclude_tags:Optional[Sequence[str]]=None,**kwargs:Any,)->AsyncIterator[StreamEvent]:"""Generate a stream of events. Use to create an iterator over StreamEvents that provide real-time information about the progress of the Runnable, including StreamEvents from intermediate results. A StreamEvent is a dictionary with the following schema: - ``event``: **str** - Event names are of the format: on_[runnable_type]_(start|stream|end). - ``name``: **str** - The name of the Runnable that generated the event. - ``run_id``: **str** - randomly generated ID associated with the given execution of the Runnable that emitted the event. A child Runnable that gets invoked as part of the execution of a parent Runnable is assigned its own unique ID. - ``parent_ids``: **List[str]** - The IDs of the parent runnables that generated the event. The root Runnable will have an empty list. The order of the parent IDs is from the root to the immediate parent. Only available for v2 version of the API. The v1 version of the API will return an empty list. - ``tags``: **Optional[List[str]]** - The tags of the Runnable that generated the event. - ``metadata``: **Optional[Dict[str, Any]]** - The metadata of the Runnable that generated the event. - ``data``: **Dict[str, Any]** Below is a table that illustrates some evens that might be emitted by various chains. Metadata fields have been omitted from the table for brevity. Chain definitions have been included after the table. **ATTENTION** This reference table is for the V2 version of the schema. +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | event | name | chunk | input | output | +======================+==================+=================================+===============================================+=================================================+ | on_chat_model_start | [model name] | | {"messages": [[SystemMessage, HumanMessage]]} | | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_chat_model_stream | [model name] | AIMessageChunk(content="hello") | | | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_chat_model_end | [model name] | | {"messages": [[SystemMessage, HumanMessage]]} | AIMessageChunk(content="hello world") | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_llm_start | [model name] | | {'input': 'hello'} | | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_llm_stream | [model name] | 'Hello' | | | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_llm_end | [model name] | | 'Hello human!' | | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_chain_start | format_docs | | | | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_chain_stream | format_docs | "hello world!, goodbye world!" | | | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_chain_end | format_docs | | [Document(...)] | "hello world!, goodbye world!" | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_tool_start | some_tool | | {"x": 1, "y": "2"} | | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_tool_end | some_tool | | | {"x": 1, "y": "2"} | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_retriever_start | [retriever name] | | {"query": "hello"} | | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_retriever_end | [retriever name] | | {"query": "hello"} | [Document(...), ..] | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_prompt_start | [template_name] | | {"question": "hello"} | | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ | on_prompt_end | [template_name] | | {"question": "hello"} | ChatPromptValue(messages: [SystemMessage, ...]) | +----------------------+------------------+---------------------------------+-----------------------------------------------+-------------------------------------------------+ In addition to the standard events, users can also dispatch custom events (see example below). Custom events will be only be surfaced with in the `v2` version of the API! A custom event has following format: +-----------+------+-----------------------------------------------------------------------------------------------------------+ | Attribute | Type | Description | +===========+======+===========================================================================================================+ | name | str | A user defined name for the event. | +-----------+------+-----------------------------------------------------------------------------------------------------------+ | data | Any | The data associated with the event. This can be anything, though we suggest making it JSON serializable. | +-----------+------+-----------------------------------------------------------------------------------------------------------+ Here are declarations associated with the standard events shown above: `format_docs`: .. code-block:: python def format_docs(docs: List[Document]) -> str: '''Format the docs.''' return ", ".join([doc.page_content for doc in docs]) format_docs = RunnableLambda(format_docs) `some_tool`: .. code-block:: python @tool def some_tool(x: int, y: str) -> dict: '''Some_tool.''' return {"x": x, "y": y} `prompt`: .. code-block:: python template = ChatPromptTemplate.from_messages( [("system", "You are Cat Agent 007"), ("human", "{question}")] ).with_config({"run_name": "my_template", "tags": ["my_template"]}) Example: .. code-block:: python from langchain_core.runnables import RunnableLambda async def reverse(s: str) -> str: return s[::-1] chain = RunnableLambda(func=reverse) events = [ event async for event in chain.astream_events("hello", version="v2") ] # will produce the following events (run_id, and parent_ids # has been omitted for brevity): [ { "data": {"input": "hello"}, "event": "on_chain_start", "metadata": {}, "name": "reverse", "tags": [], }, { "data": {"chunk": "olleh"}, "event": "on_chain_stream", "metadata": {}, "name": "reverse", "tags": [], }, { "data": {"output": "olleh"}, "event": "on_chain_end", "metadata": {}, "name": "reverse", "tags": [], }, ] Example: Dispatch Custom Event .. code-block:: python from langchain_core.callbacks.manager import ( adispatch_custom_event, ) from langchain_core.runnables import RunnableLambda, RunnableConfig import asyncio async def slow_thing(some_input: str, config: RunnableConfig) -> str: \"\"\"Do something that takes a long time.\"\"\" await asyncio.sleep(1) # Placeholder for some slow operation await adispatch_custom_event( "progress_event", {"message": "Finished step 1 of 3"}, config=config # Must be included for python < 3.10 ) await asyncio.sleep(1) # Placeholder for some slow operation await adispatch_custom_event( "progress_event", {"message": "Finished step 2 of 3"}, config=config # Must be included for python < 3.10 ) await asyncio.sleep(1) # Placeholder for some slow operation return "Done" slow_thing = RunnableLambda(slow_thing) async for event in slow_thing.astream_events("some_input", version="v2"): print(event) Args: input: The input to the Runnable. config: The config to use for the Runnable. version: The version of the schema to use either `v2` or `v1`. Users should use `v2`. `v1` is for backwards compatibility and will be deprecated in 0.4.0. No default will be assigned until the API is stabilized. custom events will only be surfaced in `v2`. include_names: Only include events from runnables with matching names. include_types: Only include events from runnables with matching types. include_tags: Only include events from runnables with matching tags. exclude_names: Exclude events from runnables with matching names. exclude_types: Exclude events from runnables with matching types. exclude_tags: Exclude events from runnables with matching tags. kwargs: Additional keyword arguments to pass to the Runnable. These will be passed to astream_log as this implementation of astream_events is built on top of astream_log. Yields: An async stream of StreamEvents. Raises: NotImplementedError: If the version is not `v1` or `v2`. """# noqa: E501fromlangchain_core.tracers.event_streamimport(_astream_events_implementation_v1,_astream_events_implementation_v2,)ifversion=="v2":event_stream=_astream_events_implementation_v2(self,input,config=config,include_names=include_names,include_types=include_types,include_tags=include_tags,exclude_names=exclude_names,exclude_types=exclude_types,exclude_tags=exclude_tags,**kwargs,)elifversion=="v1":# First implementation, built on top of astream_log API# This implementation will be deprecated as of 0.2.0event_stream=_astream_events_implementation_v1(self,input,config=config,include_names=include_names,include_types=include_types,include_tags=include_tags,exclude_names=exclude_names,exclude_types=exclude_types,exclude_tags=exclude_tags,**kwargs,)else:raiseNotImplementedError('Only versions "v1" and "v2" of the schema is currently supported.')asyncwithaclosing(event_stream):asyncforeventinevent_stream:yieldevent
[docs]deftransform(self,input:Iterator[Input],config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->Iterator[Output]:""" Default implementation of transform, which buffers input and then calls stream. Subclasses should override this method if they can start producing output while input is still being generated. Args: input: An iterator of inputs to the Runnable. config: The config to use for the Runnable. Defaults to None. kwargs: Additional keyword arguments to pass to the Runnable. Yields: The output of the Runnable. """final:Inputgot_first_val=Falseforichunkininput:# The default implementation of transform is to buffer input and# then call stream.# It'll attempt to gather all input into a single chunk using# the `+` operator.# If the input is not addable, then we'll assume that we can# only operate on the last chunk,# and we'll iterate until we get to the last chunk.ifnotgot_first_val:final=ichunkgot_first_val=Trueelse:try:final=final+ichunk# type: ignore[operator]exceptTypeError:final=ichunkifgot_first_val:yield fromself.stream(final,config,**kwargs)
[docs]asyncdefatransform(self,input:AsyncIterator[Input],config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->AsyncIterator[Output]:""" Default implementation of atransform, which buffers input and calls astream. Subclasses should override this method if they can start producing output while input is still being generated. Args: input: An async iterator of inputs to the Runnable. config: The config to use for the Runnable. Defaults to None. kwargs: Additional keyword arguments to pass to the Runnable. Yields: The output of the Runnable. """final:Inputgot_first_val=Falseasyncforichunkininput:# The default implementation of transform is to buffer input and# then call stream.# It'll attempt to gather all input into a single chunk using# the `+` operator.# If the input is not addable, then we'll assume that we can# only operate on the last chunk,# and we'll iterate until we get to the last chunk.ifnotgot_first_val:final=ichunkgot_first_val=Trueelse:try:final=final+ichunk# type: ignore[operator]exceptTypeError:final=ichunkifgot_first_val:asyncforoutputinself.astream(final,config,**kwargs):yieldoutput
[docs]defbind(self,**kwargs:Any)->Runnable[Input,Output]:""" Bind arguments to a Runnable, returning a new Runnable. Useful when a Runnable in a chain requires an argument that is not in the output of the previous Runnable or included in the user input. Args: kwargs: The arguments to bind to the Runnable. Returns: A new Runnable with the arguments bound. Example: .. code-block:: python from langchain_community.chat_models import ChatOllama from langchain_core.output_parsers import StrOutputParser llm = ChatOllama(model='llama2') # Without bind. chain = ( llm | StrOutputParser() ) chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two three four five.' # With bind. chain = ( llm.bind(stop=["three"]) | StrOutputParser() ) chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two' """returnRunnableBinding(bound=self,kwargs=kwargs,config={})
[docs]defwith_config(self,config:Optional[RunnableConfig]=None,# Sadly Unpack is not well-supported by mypy so this will have to be untyped**kwargs:Any,)->Runnable[Input,Output]:""" Bind config to a Runnable, returning a new Runnable. Args: config: The config to bind to the Runnable. kwargs: Additional keyword arguments to pass to the Runnable. Returns: A new Runnable with the config bound. """returnRunnableBinding(bound=self,config=cast(RunnableConfig,{**(configor{}),**kwargs},),# type: ignore[misc]kwargs={},)
[docs]defwith_listeners(self,*,on_start:Optional[Union[Callable[[Run],None],Callable[[Run,RunnableConfig],None]]]=None,on_end:Optional[Union[Callable[[Run],None],Callable[[Run,RunnableConfig],None]]]=None,on_error:Optional[Union[Callable[[Run],None],Callable[[Run,RunnableConfig],None]]]=None,)->Runnable[Input,Output]:""" Bind lifecycle listeners to a Runnable, returning a new Runnable. on_start: Called before the Runnable starts running, with the Run object. on_end: Called after the Runnable finishes running, with the Run object. on_error: Called if the Runnable throws an error, with the Run object. The Run object contains information about the run, including its id, type, input, output, error, start_time, end_time, and any tags or metadata added to the run. Args: on_start: Called before the Runnable starts running. Defaults to None. on_end: Called after the Runnable finishes running. Defaults to None. on_error: Called if the Runnable throws an error. Defaults to None. Returns: A new Runnable with the listeners bound. Example: .. code-block:: python from langchain_core.runnables import RunnableLambda from langchain_core.tracers.schemas import Run import time def test_runnable(time_to_sleep : int): time.sleep(time_to_sleep) def fn_start(run_obj: Run): print("start_time:", run_obj.start_time) def fn_end(run_obj: Run): print("end_time:", run_obj.end_time) chain = RunnableLambda(test_runnable).with_listeners( on_start=fn_start, on_end=fn_end ) chain.invoke(2) """fromlangchain_core.tracers.root_listenersimportRootListenersTracerreturnRunnableBinding(bound=self,config_factories=[lambdaconfig:{"callbacks":[RootListenersTracer(config=config,on_start=on_start,on_end=on_end,on_error=on_error,)],}],)
[docs]defwith_alisteners(self,*,on_start:Optional[AsyncListener]=None,on_end:Optional[AsyncListener]=None,on_error:Optional[AsyncListener]=None,)->Runnable[Input,Output]:""" Bind asynchronous lifecycle listeners to a Runnable, returning a new Runnable. on_start: Asynchronously called before the Runnable starts running. on_end: Asynchronously called after the Runnable finishes running. on_error: Asynchronously called if the Runnable throws an error. The Run object contains information about the run, including its id, type, input, output, error, start_time, end_time, and any tags or metadata added to the run. Args: on_start: Asynchronously called before the Runnable starts running. Defaults to None. on_end: Asynchronously called after the Runnable finishes running. Defaults to None. on_error: Asynchronously called if the Runnable throws an error. Defaults to None. Returns: A new Runnable with the listeners bound. Example: .. code-block:: python from langchain_core.runnables import RunnableLambda import time async def test_runnable(time_to_sleep : int): print(f"Runnable[{time_to_sleep}s]: starts at {format_t(time.time())}") await asyncio.sleep(time_to_sleep) print(f"Runnable[{time_to_sleep}s]: ends at {format_t(time.time())}") async def fn_start(run_obj : Runnable): print(f"on start callback starts at {format_t(time.time())} await asyncio.sleep(3) print(f"on start callback ends at {format_t(time.time())}") async def fn_end(run_obj : Runnable): print(f"on end callback starts at {format_t(time.time())} await asyncio.sleep(2) print(f"on end callback ends at {format_t(time.time())}") runnable = RunnableLambda(test_runnable).with_alisteners( on_start=fn_start, on_end=fn_end ) async def concurrent_runs(): await asyncio.gather(runnable.ainvoke(2), runnable.ainvoke(3)) asyncio.run(concurrent_runs()) Result: on start callback starts at 2024-05-16T14:20:29.637053+00:00 on start callback starts at 2024-05-16T14:20:29.637150+00:00 on start callback ends at 2024-05-16T14:20:32.638305+00:00 on start callback ends at 2024-05-16T14:20:32.638383+00:00 Runnable[3s]: starts at 2024-05-16T14:20:32.638849+00:00 Runnable[5s]: starts at 2024-05-16T14:20:32.638999+00:00 Runnable[3s]: ends at 2024-05-16T14:20:35.640016+00:00 on end callback starts at 2024-05-16T14:20:35.640534+00:00 Runnable[5s]: ends at 2024-05-16T14:20:37.640169+00:00 on end callback starts at 2024-05-16T14:20:37.640574+00:00 on end callback ends at 2024-05-16T14:20:37.640654+00:00 on end callback ends at 2024-05-16T14:20:39.641751+00:00 """fromlangchain_core.tracers.root_listenersimportAsyncRootListenersTracerreturnRunnableBinding(bound=self,config_factories=[lambdaconfig:{"callbacks":[AsyncRootListenersTracer(config=config,on_start=on_start,on_end=on_end,on_error=on_error,)],}],)
[docs]defwith_types(self,*,input_type:Optional[Type[Input]]=None,output_type:Optional[Type[Output]]=None,)->Runnable[Input,Output]:""" Bind input and output types to a Runnable, returning a new Runnable. Args: input_type: The input type to bind to the Runnable. Defaults to None. output_type: The output type to bind to the Runnable. Defaults to None. Returns: A new Runnable with the types bound. """returnRunnableBinding(bound=self,custom_input_type=input_type,custom_output_type=output_type,kwargs={},)
[docs]defwith_retry(self,*,retry_if_exception_type:Tuple[Type[BaseException],...]=(Exception,),wait_exponential_jitter:bool=True,stop_after_attempt:int=3,)->Runnable[Input,Output]:"""Create a new Runnable that retries the original Runnable on exceptions. Args: retry_if_exception_type: A tuple of exception types to retry on. Defaults to (Exception,). wait_exponential_jitter: Whether to add jitter to the wait time between retries. Defaults to True. stop_after_attempt: The maximum number of attempts to make before giving up. Defaults to 3. Returns: A new Runnable that retries the original Runnable on exceptions. Example: .. code-block:: python from langchain_core.runnables import RunnableLambda count = 0 def _lambda(x: int) -> None: global count count = count + 1 if x == 1: raise ValueError("x is 1") else: pass runnable = RunnableLambda(_lambda) try: runnable.with_retry( stop_after_attempt=2, retry_if_exception_type=(ValueError,), ).invoke(1) except ValueError: pass assert (count == 2) Args: retry_if_exception_type: A tuple of exception types to retry on wait_exponential_jitter: Whether to add jitter to the wait time between retries stop_after_attempt: The maximum number of attempts to make before giving up Returns: A new Runnable that retries the original Runnable on exceptions. """fromlangchain_core.runnables.retryimportRunnableRetryreturnRunnableRetry(bound=self,kwargs={},config={},retry_exception_types=retry_if_exception_type,wait_exponential_jitter=wait_exponential_jitter,max_attempt_number=stop_after_attempt,)
[docs]defmap(self)->Runnable[List[Input],List[Output]]:""" Return a new Runnable that maps a list of inputs to a list of outputs, by calling invoke() with each input. Returns: A new Runnable that maps a list of inputs to a list of outputs. Example: .. code-block:: python from langchain_core.runnables import RunnableLambda def _lambda(x: int) -> int: return x + 1 runnable = RunnableLambda(_lambda) print(runnable.map().invoke([1, 2, 3])) # [2, 3, 4] """returnRunnableEach(bound=self)
[docs]defwith_fallbacks(self,fallbacks:Sequence[Runnable[Input,Output]],*,exceptions_to_handle:Tuple[Type[BaseException],...]=(Exception,),exception_key:Optional[str]=None,)->RunnableWithFallbacksT[Input,Output]:"""Add fallbacks to a Runnable, returning a new Runnable. The new Runnable will try the original Runnable, and then each fallback in order, upon failures. Args: fallbacks: A sequence of runnables to try if the original Runnable fails. exceptions_to_handle: A tuple of exception types to handle. Defaults to (Exception,). exception_key: If string is specified then handled exceptions will be passed to fallbacks as part of the input under the specified key. If None, exceptions will not be passed to fallbacks. If used, the base Runnable and its fallbacks must accept a dictionary as input. Defaults to None. Returns: A new Runnable that will try the original Runnable, and then each fallback in order, upon failures. Example: .. code-block:: python from typing import Iterator from langchain_core.runnables import RunnableGenerator def _generate_immediate_error(input: Iterator) -> Iterator[str]: raise ValueError() yield "" def _generate(input: Iterator) -> Iterator[str]: yield from "foo bar" runnable = RunnableGenerator(_generate_immediate_error).with_fallbacks( [RunnableGenerator(_generate)] ) print(''.join(runnable.stream({}))) #foo bar Args: fallbacks: A sequence of runnables to try if the original Runnable fails. exceptions_to_handle: A tuple of exception types to handle. exception_key: If string is specified then handled exceptions will be passed to fallbacks as part of the input under the specified key. If None, exceptions will not be passed to fallbacks. If used, the base Runnable and its fallbacks must accept a dictionary as input. Returns: A new Runnable that will try the original Runnable, and then each fallback in order, upon failures. """fromlangchain_core.runnables.fallbacksimportRunnableWithFallbacksreturnRunnableWithFallbacks(runnable=self,fallbacks=fallbacks,exceptions_to_handle=exceptions_to_handle,exception_key=exception_key,)
""" --- Helper methods for Subclasses --- """def_call_with_config(self,func:Union[Callable[[Input],Output],Callable[[Input,CallbackManagerForChainRun],Output],Callable[[Input,CallbackManagerForChainRun,RunnableConfig],Output],],input:Input,config:Optional[RunnableConfig],run_type:Optional[str]=None,serialized:Optional[Dict[str,Any]]=None,**kwargs:Optional[Any],)->Output:"""Helper method to transform an Input value to an Output value, with callbacks. Use this method to implement invoke() in subclasses."""config=ensure_config(config)callback_manager=get_callback_manager_for_config(config)run_manager=callback_manager.on_chain_start(serialized,input,run_type=run_type,name=config.get("run_name")orself.get_name(),run_id=config.pop("run_id",None),)try:child_config=patch_config(config,callbacks=run_manager.get_child())context=copy_context()context.run(_set_config_context,child_config)output=cast(Output,context.run(call_func_with_variable_args,# type: ignore[arg-type]func,# type: ignore[arg-type]input,# type: ignore[arg-type]config,run_manager,**kwargs,),)exceptBaseExceptionase:run_manager.on_chain_error(e)raiseelse:run_manager.on_chain_end(output)returnoutputasyncdef_acall_with_config(self,func:Union[Callable[[Input],Awaitable[Output]],Callable[[Input,AsyncCallbackManagerForChainRun],Awaitable[Output]],Callable[[Input,AsyncCallbackManagerForChainRun,RunnableConfig],Awaitable[Output],],],input:Input,config:Optional[RunnableConfig],run_type:Optional[str]=None,serialized:Optional[Dict[str,Any]]=None,**kwargs:Optional[Any],)->Output:"""Helper method to transform an Input value to an Output value, with callbacks. Use this method to implement ainvoke() in subclasses."""config=ensure_config(config)callback_manager=get_async_callback_manager_for_config(config)run_manager=awaitcallback_manager.on_chain_start(serialized,input,run_type=run_type,name=config.get("run_name")orself.get_name(),run_id=config.pop("run_id",None),)try:child_config=patch_config(config,callbacks=run_manager.get_child())context=copy_context()context.run(_set_config_context,child_config)coro=acall_func_with_variable_args(func,input,config,run_manager,**kwargs)ifasyncio_accepts_context():output:Output=awaitasyncio.create_task(coro,context=context)# type: ignoreelse:output=awaitcoroexceptBaseExceptionase:awaitrun_manager.on_chain_error(e)raiseelse:awaitrun_manager.on_chain_end(output)returnoutputdef_batch_with_config(self,func:Union[Callable[[List[Input]],List[Union[Exception,Output]]],Callable[[List[Input],List[CallbackManagerForChainRun]],List[Union[Exception,Output]],],Callable[[List[Input],List[CallbackManagerForChainRun],List[RunnableConfig]],List[Union[Exception,Output]],],],input:List[Input],config:Optional[Union[RunnableConfig,List[RunnableConfig]]]=None,*,return_exceptions:bool=False,run_type:Optional[str]=None,**kwargs:Optional[Any],)->List[Output]:"""Helper method to transform an Input value to an Output value, with callbacks. Use this method to implement invoke() in subclasses."""ifnotinput:return[]configs=get_config_list(config,len(input))callback_managers=[get_callback_manager_for_config(c)forcinconfigs]run_managers=[callback_manager.on_chain_start(None,input,run_type=run_type,name=config.get("run_name")orself.get_name(),run_id=config.pop("run_id",None),)forcallback_manager,input,configinzip(callback_managers,input,configs)]try:ifaccepts_config(func):kwargs["config"]=[patch_config(c,callbacks=rm.get_child())forc,rminzip(configs,run_managers)]ifaccepts_run_manager(func):kwargs["run_manager"]=run_managersoutput=func(input,**kwargs)# type: ignore[call-arg]exceptBaseExceptionase:forrun_managerinrun_managers:run_manager.on_chain_error(e)ifreturn_exceptions:returncast(List[Output],[efor_ininput])else:raiseelse:first_exception:Optional[Exception]=Noneforrun_manager,outinzip(run_managers,output):ifisinstance(out,Exception):first_exception=first_exceptionoroutrun_manager.on_chain_error(out)else:run_manager.on_chain_end(out)ifreturn_exceptionsorfirst_exceptionisNone:returncast(List[Output],output)else:raisefirst_exceptionasyncdef_abatch_with_config(self,func:Union[Callable[[List[Input]],Awaitable[List[Union[Exception,Output]]]],Callable[[List[Input],List[AsyncCallbackManagerForChainRun]],Awaitable[List[Union[Exception,Output]]],],Callable[[List[Input],List[AsyncCallbackManagerForChainRun],List[RunnableConfig],],Awaitable[List[Union[Exception,Output]]],],],input:List[Input],config:Optional[Union[RunnableConfig,List[RunnableConfig]]]=None,*,return_exceptions:bool=False,run_type:Optional[str]=None,**kwargs:Optional[Any],)->List[Output]:"""Helper method to transform an Input value to an Output value, with callbacks. Use this method to implement invoke() in subclasses."""ifnotinput:return[]configs=get_config_list(config,len(input))callback_managers=[get_async_callback_manager_for_config(c)forcinconfigs]run_managers:List[AsyncCallbackManagerForChainRun]=awaitasyncio.gather(*(callback_manager.on_chain_start(None,input,run_type=run_type,name=config.get("run_name")orself.get_name(),run_id=config.pop("run_id",None),)forcallback_manager,input,configinzip(callback_managers,input,configs)))try:ifaccepts_config(func):kwargs["config"]=[patch_config(c,callbacks=rm.get_child())forc,rminzip(configs,run_managers)]ifaccepts_run_manager(func):kwargs["run_manager"]=run_managersoutput=awaitfunc(input,**kwargs)# type: ignore[call-arg]exceptBaseExceptionase:awaitasyncio.gather(*(run_manager.on_chain_error(e)forrun_managerinrun_managers))ifreturn_exceptions:returncast(List[Output],[efor_ininput])else:raiseelse:first_exception:Optional[Exception]=Nonecoros:List[Awaitable[None]]=[]forrun_manager,outinzip(run_managers,output):ifisinstance(out,Exception):first_exception=first_exceptionoroutcoros.append(run_manager.on_chain_error(out))else:coros.append(run_manager.on_chain_end(out))awaitasyncio.gather(*coros)ifreturn_exceptionsorfirst_exceptionisNone:returncast(List[Output],output)else:raisefirst_exceptiondef_transform_stream_with_config(self,input:Iterator[Input],transformer:Union[Callable[[Iterator[Input]],Iterator[Output]],Callable[[Iterator[Input],CallbackManagerForChainRun],Iterator[Output]],Callable[[Iterator[Input],CallbackManagerForChainRun,RunnableConfig,],Iterator[Output],],],config:Optional[RunnableConfig],run_type:Optional[str]=None,**kwargs:Optional[Any],)->Iterator[Output]:"""Helper method to transform an Iterator of Input values into an Iterator of Output values, with callbacks. Use this to implement `stream()` or `transform()` in Runnable subclasses."""# Mixin that is used by both astream log and astream events implementationfromlangchain_core.tracers._streamingimport_StreamingCallbackHandler# tee the input so we can iterate over it twiceinput_for_tracing,input_for_transform=tee(input,2)# Start the input iterator to ensure the input Runnable starts before this onefinal_input:Optional[Input]=next(input_for_tracing,None)final_input_supported=Truefinal_output:Optional[Output]=Nonefinal_output_supported=Trueconfig=ensure_config(config)callback_manager=get_callback_manager_for_config(config)run_manager=callback_manager.on_chain_start(None,{"input":""},run_type=run_type,name=config.get("run_name")orself.get_name(),run_id=config.pop("run_id",None),)try:child_config=patch_config(config,callbacks=run_manager.get_child())ifaccepts_config(transformer):kwargs["config"]=child_configifaccepts_run_manager(transformer):kwargs["run_manager"]=run_managercontext=copy_context()context.run(_set_config_context,child_config)iterator=context.run(transformer,input_for_transform,**kwargs)# type: ignore[arg-type]ifstream_handler:=next((cast(_StreamingCallbackHandler,h)forhinrun_manager.handlers# instance check OK here, it's a mixinifisinstance(h,_StreamingCallbackHandler)# type: ignore[misc]),None,):# populates streamed_output in astream_log() output if needediterator=stream_handler.tap_output_iter(run_manager.run_id,iterator)try:whileTrue:chunk:Output=context.run(next,iterator)# type: ignoreyieldchunkiffinal_output_supported:iffinal_outputisNone:final_output=chunkelse:try:final_output=final_output+chunk# type: ignoreexceptTypeError:final_output=chunkfinal_output_supported=Falseelse:final_output=chunkexcept(StopIteration,GeneratorExit):passforichunkininput_for_tracing:iffinal_input_supported:iffinal_inputisNone:final_input=ichunkelse:try:final_input=final_input+ichunk# type: ignoreexceptTypeError:final_input=ichunkfinal_input_supported=Falseelse:final_input=ichunkexceptBaseExceptionase:run_manager.on_chain_error(e,inputs=final_input)raiseelse:run_manager.on_chain_end(final_output,inputs=final_input)asyncdef_atransform_stream_with_config(self,input:AsyncIterator[Input],transformer:Union[Callable[[AsyncIterator[Input]],AsyncIterator[Output]],Callable[[AsyncIterator[Input],AsyncCallbackManagerForChainRun],AsyncIterator[Output],],Callable[[AsyncIterator[Input],AsyncCallbackManagerForChainRun,RunnableConfig,],AsyncIterator[Output],],],config:Optional[RunnableConfig],run_type:Optional[str]=None,**kwargs:Optional[Any],)->AsyncIterator[Output]:"""Helper method to transform an Async Iterator of Input values into an Async Iterator of Output values, with callbacks. Use this to implement `astream()` or `atransform()` in Runnable subclasses."""# Mixin that is used by both astream log and astream events implementationfromlangchain_core.tracers._streamingimport_StreamingCallbackHandler# tee the input so we can iterate over it twiceinput_for_tracing,input_for_transform=atee(input,2)# Start the input iterator to ensure the input Runnable starts before this onefinal_input:Optional[Input]=awaitpy_anext(input_for_tracing,None)final_input_supported=Truefinal_output:Optional[Output]=Nonefinal_output_supported=Trueconfig=ensure_config(config)callback_manager=get_async_callback_manager_for_config(config)run_manager=awaitcallback_manager.on_chain_start(None,{"input":""},run_type=run_type,name=config.get("run_name")orself.get_name(),run_id=config.pop("run_id",None),)iterator_=Nonetry:child_config=patch_config(config,callbacks=run_manager.get_child())ifaccepts_config(transformer):kwargs["config"]=child_configifaccepts_run_manager(transformer):kwargs["run_manager"]=run_managercontext=copy_context()context.run(_set_config_context,child_config)iterator_=context.run(transformer,input_for_transform,**kwargs)# type: ignore[arg-type]ifstream_handler:=next((cast(_StreamingCallbackHandler,h)forhinrun_manager.handlers# instance check OK here, it's a mixinifisinstance(h,_StreamingCallbackHandler)# type: ignore[misc]),None,):# populates streamed_output in astream_log() output if needediterator=stream_handler.tap_output_aiter(run_manager.run_id,iterator_)else:iterator=iterator_try:whileTrue:ifasyncio_accepts_context():chunk:Output=awaitasyncio.create_task(# type: ignore[call-arg]py_anext(iterator),# type: ignore[arg-type]context=context,)else:chunk=cast(Output,awaitpy_anext(iterator))yieldchunkiffinal_output_supported:iffinal_outputisNone:final_output=chunkelse:try:final_output=final_output+chunk# type: ignoreexceptTypeError:final_output=chunkfinal_output_supported=Falseelse:final_output=chunkexceptStopAsyncIteration:passasyncforichunkininput_for_tracing:iffinal_input_supported:iffinal_inputisNone:final_input=ichunkelse:try:final_input=final_input+ichunk# type: ignore[operator]exceptTypeError:final_input=ichunkfinal_input_supported=Falseelse:final_input=ichunkexceptBaseExceptionase:awaitrun_manager.on_chain_error(e,inputs=final_input)raiseelse:awaitrun_manager.on_chain_end(final_output,inputs=final_input)finally:ifiterator_isnotNoneandhasattr(iterator_,"aclose"):awaititerator_.aclose()
[docs]@beta_decorator.beta(message="This API is in beta and may change in the future.")defas_tool(self,args_schema:Optional[Type[BaseModel]]=None,*,name:Optional[str]=None,description:Optional[str]=None,arg_types:Optional[Dict[str,Type]]=None,)->BaseTool:"""Create a BaseTool from a Runnable. ``as_tool`` will instantiate a BaseTool with a name, description, and ``args_schema`` from a Runnable. Where possible, schemas are inferred from ``runnable.get_input_schema``. Alternatively (e.g., if the Runnable takes a dict as input and the specific dict keys are not typed), the schema can be specified directly with ``args_schema``. You can also pass ``arg_types`` to just specify the required arguments and their types. Args: args_schema: The schema for the tool. Defaults to None. name: The name of the tool. Defaults to None. description: The description of the tool. Defaults to None. arg_types: A dictionary of argument names to types. Defaults to None. Returns: A BaseTool instance. Typed dict input: .. code-block:: python from typing import List from typing_extensions import TypedDict from langchain_core.runnables import RunnableLambda class Args(TypedDict): a: int b: List[int] def f(x: Args) -> str: return str(x["a"] * max(x["b"])) runnable = RunnableLambda(f) as_tool = runnable.as_tool() as_tool.invoke({"a": 3, "b": [1, 2]}) ``dict`` input, specifying schema via ``args_schema``: .. code-block:: python from typing import Any, Dict, List from langchain_core.pydantic_v1 import BaseModel, Field from langchain_core.runnables import RunnableLambda def f(x: Dict[str, Any]) -> str: return str(x["a"] * max(x["b"])) class FSchema(BaseModel): \"\"\"Apply a function to an integer and list of integers.\"\"\" a: int = Field(..., description="Integer") b: List[int] = Field(..., description="List of ints") runnable = RunnableLambda(f) as_tool = runnable.as_tool(FSchema) as_tool.invoke({"a": 3, "b": [1, 2]}) ``dict`` input, specifying schema via ``arg_types``: .. code-block:: python from typing import Any, Dict, List from langchain_core.runnables import RunnableLambda def f(x: Dict[str, Any]) -> str: return str(x["a"] * max(x["b"])) runnable = RunnableLambda(f) as_tool = runnable.as_tool(arg_types={"a": int, "b": List[int]}) as_tool.invoke({"a": 3, "b": [1, 2]}) String input: .. code-block:: python from langchain_core.runnables import RunnableLambda def f(x: str) -> str: return x + "a" def g(x: str) -> str: return x + "z" runnable = RunnableLambda(f) | g as_tool = runnable.as_tool() as_tool.invoke("b") .. versionadded:: 0.2.14 """# Avoid circular importfromlangchain_core.toolsimportconvert_runnable_to_toolreturnconvert_runnable_to_tool(self,args_schema=args_schema,name=name,description=description,arg_types=arg_types,)
[docs]classRunnableSerializable(Serializable,Runnable[Input,Output]):"""Runnable that can be serialized to JSON."""name:Optional[str]=None"""The name of the Runnable. Used for debugging and tracing."""
[docs]defto_json(self)->Union[SerializedConstructor,SerializedNotImplemented]:"""Serialize the Runnable to JSON. Returns: A JSON-serializable representation of the Runnable. """dumped=super().to_json()try:dumped["name"]=self.get_name()exceptException:passreturndumped
[docs]defconfigurable_fields(self,**kwargs:AnyConfigurableField)->RunnableSerializable[Input,Output]:"""Configure particular Runnable fields at runtime. Args: **kwargs: A dictionary of ConfigurableField instances to configure. Returns: A new Runnable with the fields configured. .. code-block:: python from langchain_core.runnables import ConfigurableField from langchain_openai import ChatOpenAI model = ChatOpenAI(max_tokens=20).configurable_fields( max_tokens=ConfigurableField( id="output_token_number", name="Max tokens in the output", description="The maximum number of tokens in the output", ) ) # max_tokens = 20 print( "max_tokens_20: ", model.invoke("tell me something about chess").content ) # max_tokens = 200 print("max_tokens_200: ", model.with_config( configurable={"output_token_number": 200} ).invoke("tell me something about chess").content ) """fromlangchain_core.runnables.configurableimportRunnableConfigurableFieldsforkeyinkwargs:ifkeynotinself.__fields__:raiseValueError(f"Configuration key {key} not found in {self}: "f"available keys are {self.__fields__.keys()}")returnRunnableConfigurableFields(default=self,fields=kwargs)
[docs]defconfigurable_alternatives(self,which:ConfigurableField,*,default_key:str="default",prefix_keys:bool=False,**kwargs:Union[Runnable[Input,Output],Callable[[],Runnable[Input,Output]]],)->RunnableSerializable[Input,Output]:"""Configure alternatives for Runnables that can be set at runtime. Args: which: The ConfigurableField instance that will be used to select the alternative. default_key: The default key to use if no alternative is selected. Defaults to "default". prefix_keys: Whether to prefix the keys with the ConfigurableField id. Defaults to False. **kwargs: A dictionary of keys to Runnable instances or callables that return Runnable instances. Returns: A new Runnable with the alternatives configured. .. code-block:: python from langchain_anthropic import ChatAnthropic from langchain_core.runnables.utils import ConfigurableField from langchain_openai import ChatOpenAI model = ChatAnthropic( model_name="claude-3-sonnet-20240229" ).configurable_alternatives( ConfigurableField(id="llm"), default_key="anthropic", openai=ChatOpenAI() ) # uses the default model ChatAnthropic print(model.invoke("which organization created you?").content) # uses ChatOpenAI print( model.with_config( configurable={"llm": "openai"} ).invoke("which organization created you?").content ) """fromlangchain_core.runnables.configurableimport(RunnableConfigurableAlternatives,)returnRunnableConfigurableAlternatives(which=which,default=self,alternatives=kwargs,default_key=default_key,prefix_keys=prefix_keys,)
def_seq_input_schema(steps:List[Runnable[Any,Any]],config:Optional[RunnableConfig])->Type[BaseModel]:fromlangchain_core.runnables.passthroughimportRunnableAssign,RunnablePickfirst=steps[0]iflen(steps)==1:returnfirst.get_input_schema(config)elifisinstance(first,RunnableAssign):next_input_schema=_seq_input_schema(steps[1:],config)ifnotnext_input_schema.__custom_root_type__:# it's a dict as expectedreturncreate_model(# type: ignore[call-overload]"RunnableSequenceInput",**{k:(v.annotation,v.default)fork,vinnext_input_schema.__fields__.items()ifknotinfirst.mapper.steps__},)elifisinstance(first,RunnablePick):return_seq_input_schema(steps[1:],config)returnfirst.get_input_schema(config)def_seq_output_schema(steps:List[Runnable[Any,Any]],config:Optional[RunnableConfig])->Type[BaseModel]:fromlangchain_core.runnables.passthroughimportRunnableAssign,RunnablePicklast=steps[-1]iflen(steps)==1:returnlast.get_input_schema(config)elifisinstance(last,RunnableAssign):mapper_output_schema=last.mapper.get_output_schema(config)prev_output_schema=_seq_output_schema(steps[:-1],config)ifnotprev_output_schema.__custom_root_type__:# it's a dict as expectedreturncreate_model(# type: ignore[call-overload]"RunnableSequenceOutput",**{**{k:(v.annotation,v.default)fork,vinprev_output_schema.__fields__.items()},**{k:(v.annotation,v.default)fork,vinmapper_output_schema.__fields__.items()},},)elifisinstance(last,RunnablePick):prev_output_schema=_seq_output_schema(steps[:-1],config)ifnotprev_output_schema.__custom_root_type__:# it's a dict as expectedifisinstance(last.keys,list):returncreate_model(# type: ignore[call-overload]"RunnableSequenceOutput",**{k:(v.annotation,v.default)fork,vinprev_output_schema.__fields__.items()ifkinlast.keys},)else:field=prev_output_schema.__fields__[last.keys]returncreate_model(# type: ignore[call-overload]"RunnableSequenceOutput",__root__=(field.annotation,field.default),)returnlast.get_output_schema(config)
[docs]classRunnableSequence(RunnableSerializable[Input,Output]):"""Sequence of Runnables, where the output of each is the input of the next. **RunnableSequence** is the most important composition operator in LangChain as it is used in virtually every chain. A RunnableSequence can be instantiated directly or more commonly by using the `|` operator where either the left or right operands (or both) must be a Runnable. Any RunnableSequence automatically supports sync, async, batch. The default implementations of `batch` and `abatch` utilize threadpools and asyncio gather and will be faster than naive invocation of invoke or ainvoke for IO bound Runnables. Batching is implemented by invoking the batch method on each component of the RunnableSequence in order. A RunnableSequence preserves the streaming properties of its components, so if all components of the sequence implement a `transform` method -- which is the method that implements the logic to map a streaming input to a streaming output -- then the sequence will be able to stream input to output! If any component of the sequence does not implement transform then the streaming will only begin after this component is run. If there are multiple blocking components, streaming begins after the last one. Please note: RunnableLambdas do not support `transform` by default! So if you need to use a RunnableLambdas be careful about where you place them in a RunnableSequence (if you need to use the .stream()/.astream() methods). If you need arbitrary logic and need streaming, you can subclass Runnable, and implement `transform` for whatever logic you need. Here is a simple example that uses simple functions to illustrate the use of RunnableSequence: .. code-block:: python from langchain_core.runnables import RunnableLambda def add_one(x: int) -> int: return x + 1 def mul_two(x: int) -> int: return x * 2 runnable_1 = RunnableLambda(add_one) runnable_2 = RunnableLambda(mul_two) sequence = runnable_1 | runnable_2 # Or equivalently: # sequence = RunnableSequence(first=runnable_1, last=runnable_2) sequence.invoke(1) await sequence.ainvoke(1) sequence.batch([1, 2, 3]) await sequence.abatch([1, 2, 3]) Here's an example that uses streams JSON output generated by an LLM: .. code-block:: python from langchain_core.output_parsers.json import SimpleJsonOutputParser from langchain_openai import ChatOpenAI prompt = PromptTemplate.from_template( 'In JSON format, give me a list of {topic} and their ' 'corresponding names in French, Spanish and in a ' 'Cat Language.' ) model = ChatOpenAI() chain = prompt | model | SimpleJsonOutputParser() async for chunk in chain.astream({'topic': 'colors'}): print('-') # noqa: T201 print(chunk, sep='', flush=True) # noqa: T201 """# The steps are broken into first, middle and last, solely for type checking# purposes. It allows specifying the `Input` on the first type, the `Output` of# the last type.first:Runnable[Input,Any]"""The first Runnable in the sequence."""middle:List[Runnable[Any,Any]]=Field(default_factory=list)"""The middle Runnables in the sequence."""last:Runnable[Any,Output]"""The last Runnable in the sequence."""def__init__(self,*steps:RunnableLike,name:Optional[str]=None,first:Optional[Runnable[Any,Any]]=None,middle:Optional[List[Runnable[Any,Any]]]=None,last:Optional[Runnable[Any,Any]]=None,)->None:"""Create a new RunnableSequence. Args: steps: The steps to include in the sequence. name: The name of the Runnable. Defaults to None. first: The first Runnable in the sequence. Defaults to None. middle: The middle Runnables in the sequence. Defaults to None. last: The last Runnable in the sequence. Defaults to None. Raises: ValueError: If the sequence has less than 2 steps. """steps_flat:List[Runnable]=[]ifnotsteps:iffirstisnotNoneandlastisnotNone:steps_flat=[first]+(middleor[])+[last]forstepinsteps:ifisinstance(step,RunnableSequence):steps_flat.extend(step.steps)else:steps_flat.append(coerce_to_runnable(step))iflen(steps_flat)<2:raiseValueError(f"RunnableSequence must have at least 2 steps, got {len(steps_flat)}")super().__init__(# type: ignore[call-arg]first=steps_flat[0],middle=list(steps_flat[1:-1]),last=steps_flat[-1],name=name,)@classmethoddefget_lc_namespace(cls)->List[str]:"""Get the namespace of the langchain object."""return["langchain","schema","runnable"]@propertydefsteps(self)->List[Runnable[Any,Any]]:"""All the Runnables that make up the sequence in order. Returns: A list of Runnables. """return[self.first]+self.middle+[self.last]@classmethoddefis_lc_serializable(cls)->bool:"""Check if the object is serializable. Returns: True if the object is serializable, False otherwise. Defaults to True. """returnTrueclassConfig:arbitrary_types_allowed=True@propertydefInputType(self)->Type[Input]:"""The type of the input to the Runnable."""returnself.first.InputType@propertydefOutputType(self)->Type[Output]:"""The type of the output of the Runnable."""returnself.last.OutputTypedefget_input_schema(self,config:Optional[RunnableConfig]=None)->Type[BaseModel]:"""Get the input schema of the Runnable. Args: config: The config to use. Defaults to None. Returns: The input schema of the Runnable. """return_seq_input_schema(self.steps,config)defget_output_schema(self,config:Optional[RunnableConfig]=None)->Type[BaseModel]:"""Get the output schema of the Runnable. Args: config: The config to use. Defaults to None. Returns: The output schema of the Runnable. """return_seq_output_schema(self.steps,config)@propertydefconfig_specs(self)->List[ConfigurableFieldSpec]:"""Get the config specs of the Runnable. Returns: The config specs of the Runnable. """fromlangchain_core.beta.runnables.contextimport(CONTEXT_CONFIG_PREFIX,_key_from_id,)# get all specsall_specs=[(spec,idx)foridx,stepinenumerate(self.steps)forspecinstep.config_specs]# calculate context dependenciesspecs_by_pos=groupby([tupfortupinall_specsiftup[0].id.startswith(CONTEXT_CONFIG_PREFIX)],lambdax:x[1],)next_deps:Set[str]=set()deps_by_pos:Dict[int,Set[str]]={}forpos,specsinspecs_by_pos:deps_by_pos[pos]=next_depsnext_deps=next_deps|{spec[0].idforspecinspecs}# assign context dependenciesforpos,(spec,idx)inenumerate(all_specs):ifspec.id.startswith(CONTEXT_CONFIG_PREFIX):all_specs[pos]=(ConfigurableFieldSpec(id=spec.id,annotation=spec.annotation,name=spec.name,default=spec.default,description=spec.description,is_shared=spec.is_shared,dependencies=[dfordindeps_by_pos[idx]if_key_from_id(d)!=_key_from_id(spec.id)]+(spec.dependenciesor[]),),idx,)returnget_unique_config_specs(specforspec,_inall_specs)defget_graph(self,config:Optional[RunnableConfig]=None)->Graph:"""Get the graph representation of the Runnable. Args: config: The config to use. Defaults to None. Returns: The graph representation of the Runnable. Raises: ValueError: If a Runnable has no first or last node. """fromlangchain_core.runnables.graphimportGraphgraph=Graph()forstepinself.steps:current_last_node=graph.last_node()step_graph=step.get_graph(config)ifstepisnotself.first:step_graph.trim_first_node()ifstepisnotself.last:step_graph.trim_last_node()step_first_node,_=graph.extend(step_graph)ifnotstep_first_node:raiseValueError(f"Runnable {step} has no first node")ifcurrent_last_node:graph.add_edge(current_last_node,step_first_node)returngraphdef__repr__(self)->str:return"\n| ".join(repr(s)ifi==0elseindent_lines_after_first(repr(s),"| ")fori,sinenumerate(self.steps))def__or__(self,other:Union[Runnable[Any,Other],Callable[[Any],Other],Callable[[Iterator[Any]],Iterator[Other]],Mapping[str,Union[Runnable[Any,Other],Callable[[Any],Other],Any]],],)->RunnableSerializable[Input,Other]:ifisinstance(other,RunnableSequence):returnRunnableSequence(self.first,*self.middle,self.last,other.first,*other.middle,other.last,name=self.nameorother.name,)else:returnRunnableSequence(self.first,*self.middle,self.last,coerce_to_runnable(other),name=self.name,)def__ror__(self,other:Union[Runnable[Other,Any],Callable[[Other],Any],Callable[[Iterator[Other]],Iterator[Any]],Mapping[str,Union[Runnable[Other,Any],Callable[[Other],Any],Any]],],)->RunnableSerializable[Other,Output]:ifisinstance(other,RunnableSequence):returnRunnableSequence(other.first,*other.middle,other.last,self.first,*self.middle,self.last,name=other.nameorself.name,)else:returnRunnableSequence(coerce_to_runnable(other),self.first,*self.middle,self.last,name=self.name,)
[docs]definvoke(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Any)->Output:fromlangchain_core.beta.runnables.contextimportconfig_with_context# setup callbacks and contextconfig=config_with_context(ensure_config(config),self.steps)callback_manager=get_callback_manager_for_config(config)# start the root runrun_manager=callback_manager.on_chain_start(None,input,name=config.get("run_name")orself.get_name(),run_id=config.pop("run_id",None),)# invoke all steps in sequencetry:fori,stepinenumerate(self.steps):# mark each step as a child runconfig=patch_config(config,callbacks=run_manager.get_child(f"seq:step:{i+1}"))context=copy_context()context.run(_set_config_context,config)ifi==0:input=context.run(step.invoke,input,config,**kwargs)else:input=context.run(step.invoke,input,config)# finish the root runexceptBaseExceptionase:run_manager.on_chain_error(e)raiseelse:run_manager.on_chain_end(input)returncast(Output,input)
[docs]asyncdefainvoke(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->Output:fromlangchain_core.beta.runnables.contextimportaconfig_with_context# setup callbacks and contextconfig=aconfig_with_context(ensure_config(config),self.steps)callback_manager=get_async_callback_manager_for_config(config)# start the root runrun_manager=awaitcallback_manager.on_chain_start(None,input,name=config.get("run_name")orself.get_name(),run_id=config.pop("run_id",None),)# invoke all steps in sequencetry:fori,stepinenumerate(self.steps):# mark each step as a child runconfig=patch_config(config,callbacks=run_manager.get_child(f"seq:step:{i+1}"))context=copy_context()context.run(_set_config_context,config)ifi==0:part=functools.partial(step.ainvoke,input,config,**kwargs)else:part=functools.partial(step.ainvoke,input,config)ifasyncio_accepts_context():input=awaitasyncio.create_task(part(),context=context)# type: ignoreelse:input=awaitasyncio.create_task(part())# finish the root runexceptBaseExceptionase:awaitrun_manager.on_chain_error(e)raiseelse:awaitrun_manager.on_chain_end(input)returncast(Output,input)
[docs]defbatch(self,inputs:List[Input],config:Optional[Union[RunnableConfig,List[RunnableConfig]]]=None,*,return_exceptions:bool=False,**kwargs:Optional[Any],)->List[Output]:fromlangchain_core.beta.runnables.contextimportconfig_with_contextfromlangchain_core.callbacks.managerimportCallbackManagerifnotinputs:return[]# setup callbacks and contextconfigs=[config_with_context(c,self.steps)forcinget_config_list(config,len(inputs))]callback_managers=[CallbackManager.configure(inheritable_callbacks=config.get("callbacks"),local_callbacks=None,verbose=False,inheritable_tags=config.get("tags"),local_tags=None,inheritable_metadata=config.get("metadata"),local_metadata=None,)forconfiginconfigs]# start the root runs, one per inputrun_managers=[cm.on_chain_start(None,input,name=config.get("run_name")orself.get_name(),run_id=config.pop("run_id",None),)forcm,input,configinzip(callback_managers,inputs,configs)]# invoketry:ifreturn_exceptions:# Track which inputs (by index) failed so far# If an input has failed it will be present in this map,# and the value will be the exception that was raised.failed_inputs_map:Dict[int,Exception]={}forstepidx,stepinenumerate(self.steps):# Assemble the original indexes of the remaining inputs# (i.e. the ones that haven't failed yet)remaining_idxs=[iforiinrange(len(configs))ifinotinfailed_inputs_map]# Invoke the step on the remaining inputsinputs=step.batch([inpfori,inpinzip(remaining_idxs,inputs)ifinotinfailed_inputs_map],[# each step a child run of the corresponding root runpatch_config(config,callbacks=rm.get_child(f"seq:step:{stepidx+1}"))fori,(rm,config)inenumerate(zip(run_managers,configs))ifinotinfailed_inputs_map],return_exceptions=return_exceptions,**(kwargsifstepidx==0else{}),)# If an input failed, add it to the mapfori,inpinzip(remaining_idxs,inputs):ifisinstance(inp,Exception):failed_inputs_map[i]=inpinputs=[inpforinpininputsifnotisinstance(inp,Exception)]# If all inputs have failed, stop processingiflen(failed_inputs_map)==len(configs):break# Reassemble the outputs, inserting Exceptions for failed inputsinputs_copy=inputs.copy()inputs=[]foriinrange(len(configs)):ifiinfailed_inputs_map:inputs.append(cast(Input,failed_inputs_map[i]))else:inputs.append(inputs_copy.pop(0))else:fori,stepinenumerate(self.steps):inputs=step.batch(inputs,[# each step a child run of the corresponding root runpatch_config(config,callbacks=rm.get_child(f"seq:step:{i+1}"))forrm,configinzip(run_managers,configs)],return_exceptions=return_exceptions,**(kwargsifi==0else{}),)# finish the root runsexceptBaseExceptionase:forrminrun_managers:rm.on_chain_error(e)ifreturn_exceptions:returncast(List[Output],[efor_ininputs])else:raiseelse:first_exception:Optional[Exception]=Noneforrun_manager,outinzip(run_managers,inputs):ifisinstance(out,Exception):first_exception=first_exceptionoroutrun_manager.on_chain_error(out)else:run_manager.on_chain_end(out)ifreturn_exceptionsorfirst_exceptionisNone:returncast(List[Output],inputs)else:raisefirst_exception
[docs]asyncdefabatch(self,inputs:List[Input],config:Optional[Union[RunnableConfig,List[RunnableConfig]]]=None,*,return_exceptions:bool=False,**kwargs:Optional[Any],)->List[Output]:fromlangchain_core.beta.runnables.contextimportaconfig_with_contextfromlangchain_core.callbacks.managerimportAsyncCallbackManagerifnotinputs:return[]# setup callbacks and contextconfigs=[aconfig_with_context(c,self.steps)forcinget_config_list(config,len(inputs))]callback_managers=[AsyncCallbackManager.configure(inheritable_callbacks=config.get("callbacks"),local_callbacks=None,verbose=False,inheritable_tags=config.get("tags"),local_tags=None,inheritable_metadata=config.get("metadata"),local_metadata=None,)forconfiginconfigs]# start the root runs, one per inputrun_managers:List[AsyncCallbackManagerForChainRun]=awaitasyncio.gather(*(cm.on_chain_start(None,input,name=config.get("run_name")orself.get_name(),run_id=config.pop("run_id",None),)forcm,input,configinzip(callback_managers,inputs,configs)))# invoke .batch() on each step# this uses batching optimizations in Runnable subclasses, like LLMtry:ifreturn_exceptions:# Track which inputs (by index) failed so far# If an input has failed it will be present in this map,# and the value will be the exception that was raised.failed_inputs_map:Dict[int,Exception]={}forstepidx,stepinenumerate(self.steps):# Assemble the original indexes of the remaining inputs# (i.e. the ones that haven't failed yet)remaining_idxs=[iforiinrange(len(configs))ifinotinfailed_inputs_map]# Invoke the step on the remaining inputsinputs=awaitstep.abatch([inpfori,inpinzip(remaining_idxs,inputs)ifinotinfailed_inputs_map],[# each step a child run of the corresponding root runpatch_config(config,callbacks=rm.get_child(f"seq:step:{stepidx+1}"))fori,(rm,config)inenumerate(zip(run_managers,configs))ifinotinfailed_inputs_map],return_exceptions=return_exceptions,**(kwargsifstepidx==0else{}),)# If an input failed, add it to the mapfori,inpinzip(remaining_idxs,inputs):ifisinstance(inp,Exception):failed_inputs_map[i]=inpinputs=[inpforinpininputsifnotisinstance(inp,Exception)]# If all inputs have failed, stop processingiflen(failed_inputs_map)==len(configs):break# Reassemble the outputs, inserting Exceptions for failed inputsinputs_copy=inputs.copy()inputs=[]foriinrange(len(configs)):ifiinfailed_inputs_map:inputs.append(cast(Input,failed_inputs_map[i]))else:inputs.append(inputs_copy.pop(0))else:fori,stepinenumerate(self.steps):inputs=awaitstep.abatch(inputs,[# each step a child run of the corresponding root runpatch_config(config,callbacks=rm.get_child(f"seq:step:{i+1}"))forrm,configinzip(run_managers,configs)],return_exceptions=return_exceptions,**(kwargsifi==0else{}),)# finish the root runsexceptBaseExceptionase:awaitasyncio.gather(*(rm.on_chain_error(e)forrminrun_managers))ifreturn_exceptions:returncast(List[Output],[efor_ininputs])else:raiseelse:first_exception:Optional[Exception]=Nonecoros:List[Awaitable[None]]=[]forrun_manager,outinzip(run_managers,inputs):ifisinstance(out,Exception):first_exception=first_exceptionoroutcoros.append(run_manager.on_chain_error(out))else:coros.append(run_manager.on_chain_end(out))awaitasyncio.gather(*coros)ifreturn_exceptionsorfirst_exceptionisNone:returncast(List[Output],inputs)else:raisefirst_exception
def_transform(self,input:Iterator[Input],run_manager:CallbackManagerForChainRun,config:RunnableConfig,**kwargs:Any,)->Iterator[Output]:fromlangchain_core.beta.runnables.contextimportconfig_with_contextsteps=[self.first]+self.middle+[self.last]config=config_with_context(config,self.steps)# transform the input stream of each step with the next# steps that don't natively support transforming an input stream will# buffer input in memory until all available, and then start emitting outputfinal_pipeline=cast(Iterator[Output],input)foridx,stepinenumerate(steps):config=patch_config(config,callbacks=run_manager.get_child(f"seq:step:{idx+1}"))ifidx==0:final_pipeline=step.transform(final_pipeline,config,**kwargs)else:final_pipeline=step.transform(final_pipeline,config)yield fromfinal_pipelineasyncdef_atransform(self,input:AsyncIterator[Input],run_manager:AsyncCallbackManagerForChainRun,config:RunnableConfig,**kwargs:Any,)->AsyncIterator[Output]:fromlangchain_core.beta.runnables.contextimportaconfig_with_contextsteps=[self.first]+self.middle+[self.last]config=aconfig_with_context(config,self.steps)# stream the last steps# transform the input stream of each step with the next# steps that don't natively support transforming an input stream will# buffer input in memory until all available, and then start emitting outputfinal_pipeline=cast(AsyncIterator[Output],input)foridx,stepinenumerate(steps):config=patch_config(config,callbacks=run_manager.get_child(f"seq:step:{idx+1}"),)ifidx==0:final_pipeline=step.atransform(final_pipeline,config,**kwargs)else:final_pipeline=step.atransform(final_pipeline,config)asyncforoutputinfinal_pipeline:yieldoutputdeftransform(self,input:Iterator[Input],config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->Iterator[Output]:yield fromself._transform_stream_with_config(input,self._transform,patch_config(config,run_name=(configor{}).get("run_name")orself.name),**kwargs,)
[docs]classRunnableParallel(RunnableSerializable[Input,Dict[str,Any]]):"""Runnable that runs a mapping of Runnables in parallel, and returns a mapping of their outputs. RunnableParallel is one of the two main composition primitives for the LCEL, alongside RunnableSequence. It invokes Runnables concurrently, providing the same input to each. A RunnableParallel can be instantiated directly or by using a dict literal within a sequence. Here is a simple example that uses functions to illustrate the use of RunnableParallel: .. code-block:: python from langchain_core.runnables import RunnableLambda def add_one(x: int) -> int: return x + 1 def mul_two(x: int) -> int: return x * 2 def mul_three(x: int) -> int: return x * 3 runnable_1 = RunnableLambda(add_one) runnable_2 = RunnableLambda(mul_two) runnable_3 = RunnableLambda(mul_three) sequence = runnable_1 | { # this dict is coerced to a RunnableParallel "mul_two": runnable_2, "mul_three": runnable_3, } # Or equivalently: # sequence = runnable_1 | RunnableParallel( # {"mul_two": runnable_2, "mul_three": runnable_3} # ) # Also equivalently: # sequence = runnable_1 | RunnableParallel( # mul_two=runnable_2, # mul_three=runnable_3, # ) sequence.invoke(1) await sequence.ainvoke(1) sequence.batch([1, 2, 3]) await sequence.abatch([1, 2, 3]) RunnableParallel makes it easy to run Runnables in parallel. In the below example, we simultaneously stream output from two different Runnables: .. code-block:: python from langchain_core.prompts import ChatPromptTemplate from langchain_core.runnables import RunnableParallel from langchain_openai import ChatOpenAI model = ChatOpenAI() joke_chain = ( ChatPromptTemplate.from_template("tell me a joke about {topic}") | model ) poem_chain = ( ChatPromptTemplate.from_template("write a 2-line poem about {topic}") | model ) runnable = RunnableParallel(joke=joke_chain, poem=poem_chain) # Display stream output = {key: "" for key, _ in runnable.output_schema()} for chunk in runnable.stream({"topic": "bear"}): for key in chunk: output[key] = output[key] + chunk[key].content print(output) # noqa: T201 """steps__:Mapping[str,Runnable[Input,Any]]def__init__(self,steps__:Optional[Mapping[str,Union[Runnable[Input,Any],Callable[[Input],Any],Mapping[str,Union[Runnable[Input,Any],Callable[[Input],Any]]],],]]=None,**kwargs:Union[Runnable[Input,Any],Callable[[Input],Any],Mapping[str,Union[Runnable[Input,Any],Callable[[Input],Any]]],],)->None:merged={**steps__}ifsteps__isnotNoneelse{}merged.update(kwargs)super().__init__(# type: ignore[call-arg]steps__={key:coerce_to_runnable(r)forkey,rinmerged.items()})@classmethoddefis_lc_serializable(cls)->bool:returnTrue@classmethoddefget_lc_namespace(cls)->List[str]:"""Get the namespace of the langchain object."""return["langchain","schema","runnable"]classConfig:arbitrary_types_allowed=Truedefget_name(self,suffix:Optional[str]=None,*,name:Optional[str]=None)->str:"""Get the name of the Runnable. Args: suffix: The suffix to use. Defaults to None. name: The name to use. Defaults to None. Returns: The name of the Runnable. """name=nameorself.nameorf"RunnableParallel<{','.join(self.steps__.keys())}>"returnsuper().get_name(suffix,name=name)@propertydefInputType(self)->Any:"""The type of the input to the Runnable."""forstepinself.steps__.values():ifstep.InputType:returnstep.InputTypereturnAnydefget_input_schema(self,config:Optional[RunnableConfig]=None)->Type[BaseModel]:"""Get the input schema of the Runnable. Args: config: The config to use. Defaults to None. Returns: The input schema of the Runnable. """ifall(s.get_input_schema(config).schema().get("type","object")=="object"forsinself.steps__.values()):# This is correct, but pydantic typings/mypy don't think so.returncreate_model(# type: ignore[call-overload]self.get_name("Input"),**{k:(v.annotation,v.default)forstepinself.steps__.values()fork,vinstep.get_input_schema(config).__fields__.items()ifk!="__root__"},)returnsuper().get_input_schema(config)defget_output_schema(self,config:Optional[RunnableConfig]=None)->Type[BaseModel]:"""Get the output schema of the Runnable. Args: config: The config to use. Defaults to None. Returns: The output schema of the Runnable. """# This is correct, but pydantic typings/mypy don't think so.returncreate_model(# type: ignore[call-overload]self.get_name("Output"),**{k:(v.OutputType,None)fork,vinself.steps__.items()},)@propertydefconfig_specs(self)->List[ConfigurableFieldSpec]:"""Get the config specs of the Runnable. Returns: The config specs of the Runnable. """returnget_unique_config_specs(specforstepinself.steps__.values()forspecinstep.config_specs)defget_graph(self,config:Optional[RunnableConfig]=None)->Graph:"""Get the graph representation of the Runnable. Args: config: The config to use. Defaults to None. Returns: The graph representation of the Runnable. Raises: ValueError: If a Runnable has no first or last node. """fromlangchain_core.runnables.graphimportGraphgraph=Graph()input_node=graph.add_node(self.get_input_schema(config))output_node=graph.add_node(self.get_output_schema(config))forstepinself.steps__.values():step_graph=step.get_graph()step_graph.trim_first_node()step_graph.trim_last_node()ifnotstep_graph:graph.add_edge(input_node,output_node)else:step_first_node,step_last_node=graph.extend(step_graph)ifnotstep_first_node:raiseValueError(f"Runnable {step} has no first node")ifnotstep_last_node:raiseValueError(f"Runnable {step} has no last node")graph.add_edge(input_node,step_first_node)graph.add_edge(step_last_node,output_node)returngraphdef__repr__(self)->str:map_for_repr=",\n ".join(f"{k}: {indent_lines_after_first(repr(v),' '+k+': ')}"fork,vinself.steps__.items())return"{\n "+map_for_repr+"\n}"
[docs]definvoke(self,input:Input,config:Optional[RunnableConfig]=None)->Dict[str,Any]:fromlangchain_core.callbacks.managerimportCallbackManager# setup callbacksconfig=ensure_config(config)callback_manager=CallbackManager.configure(inheritable_callbacks=config.get("callbacks"),local_callbacks=None,verbose=False,inheritable_tags=config.get("tags"),local_tags=None,inheritable_metadata=config.get("metadata"),local_metadata=None,)# start the root runrun_manager=callback_manager.on_chain_start(None,input,name=config.get("run_name")orself.get_name(),run_id=config.pop("run_id",None),)def_invoke_step(step:Runnable[Input,Any],input:Input,config:RunnableConfig,key:str)->Any:child_config=patch_config(config,# mark each step as a child runcallbacks=run_manager.get_child(f"map:key:{key}"),)context=copy_context()context.run(_set_config_context,child_config)returncontext.run(step.invoke,input,child_config,)# gather results from all stepstry:# copy to avoid issues from the caller mutating the steps during invoke()steps=dict(self.steps__)withget_executor_for_config(config)asexecutor:futures=[executor.submit(_invoke_step,step,input,config,key)forkey,stepinsteps.items()]output={key:future.result()forkey,futureinzip(steps,futures)}# finish the root runexceptBaseExceptionase:run_manager.on_chain_error(e)raiseelse:run_manager.on_chain_end(output)returnoutput
[docs]asyncdefainvoke(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->Dict[str,Any]:# setup callbacksconfig=ensure_config(config)callback_manager=get_async_callback_manager_for_config(config)# start the root runrun_manager=awaitcallback_manager.on_chain_start(None,input,name=config.get("run_name")orself.get_name(),run_id=config.pop("run_id",None),)asyncdef_ainvoke_step(step:Runnable[Input,Any],input:Input,config:RunnableConfig,key:str)->Any:child_config=patch_config(config,callbacks=run_manager.get_child(f"map:key:{key}"),)context=copy_context()context.run(_set_config_context,child_config)ifasyncio_accepts_context():returnawaitasyncio.create_task(# type: ignorestep.ainvoke(input,child_config),context=context)else:returnawaitasyncio.create_task(step.ainvoke(input,child_config))# gather results from all stepstry:# copy to avoid issues from the caller mutating the steps during invoke()steps=dict(self.steps__)results=awaitasyncio.gather(*(_ainvoke_step(step,input,# mark each step as a child runconfig,key,)forkey,stepinsteps.items()))output={key:valueforkey,valueinzip(steps,results)}# finish the root runexceptBaseExceptionase:awaitrun_manager.on_chain_error(e)raiseelse:awaitrun_manager.on_chain_end(output)returnoutput
def_transform(self,input:Iterator[Input],run_manager:CallbackManagerForChainRun,config:RunnableConfig,)->Iterator[AddableDict]:# Shallow copy steps to ignore mutations while in progresssteps=dict(self.steps__)# Each step gets a copy of the input iterator,# which is consumed in parallel in a separate thread.input_copies=list(safetee(input,len(steps),lock=threading.Lock()))withget_executor_for_config(config)asexecutor:# Create the transform() generator for each stepnamed_generators=[(name,step.transform(input_copies.pop(),patch_config(config,callbacks=run_manager.get_child(f"map:key:{name}")),),)forname,stepinsteps.items()]# Start the first iteration of each generatorfutures={executor.submit(next,generator):(step_name,generator)forstep_name,generatorinnamed_generators}# Yield chunks from each as they become available,# and start the next iteration of that generator that yielded it.# When all generators are exhausted, stop.whilefutures:completed_futures,_=wait(futures,return_when=FIRST_COMPLETED)forfutureincompleted_futures:(step_name,generator)=futures.pop(future)try:chunk=AddableDict({step_name:future.result()})yieldchunkfutures[executor.submit(next,generator)]=(step_name,generator,)exceptStopIteration:passdeftransform(self,input:Iterator[Input],config:Optional[RunnableConfig]=None,**kwargs:Any,)->Iterator[Dict[str,Any]]:yield fromself._transform_stream_with_config(input,self._transform,config,**kwargs)
asyncdef_atransform(self,input:AsyncIterator[Input],run_manager:AsyncCallbackManagerForChainRun,config:RunnableConfig,)->AsyncIterator[AddableDict]:# Shallow copy steps to ignore mutations while in progresssteps=dict(self.steps__)# Each step gets a copy of the input iterator,# which is consumed in parallel in a separate thread.input_copies=list(atee(input,len(steps),lock=asyncio.Lock()))# Create the transform() generator for each stepnamed_generators=[(name,step.atransform(input_copies.pop(),patch_config(config,callbacks=run_manager.get_child(f"map:key:{name}")),),)forname,stepinsteps.items()]# Wrap in a coroutine to satisfy linterasyncdefget_next_chunk(generator:AsyncIterator)->Optional[Output]:returnawaitpy_anext(generator)# Start the first iteration of each generatortasks={asyncio.create_task(get_next_chunk(generator)):(step_name,generator)forstep_name,generatorinnamed_generators}# Yield chunks from each as they become available,# and start the next iteration of the generator that yielded it.# When all generators are exhausted, stop.whiletasks:completed_tasks,_=awaitasyncio.wait(tasks,return_when=asyncio.FIRST_COMPLETED)fortaskincompleted_tasks:(step_name,generator)=tasks.pop(task)try:chunk=AddableDict({step_name:task.result()})yieldchunknew_task=asyncio.create_task(get_next_chunk(generator))tasks[new_task]=(step_name,generator)exceptStopAsyncIteration:passasyncdefatransform(self,input:AsyncIterator[Input],config:Optional[RunnableConfig]=None,**kwargs:Any,)->AsyncIterator[Dict[str,Any]]:asyncforchunkinself._atransform_stream_with_config(input,self._atransform,config,**kwargs):yieldchunk
# We support both namesRunnableMap=RunnableParallel
[docs]classRunnableGenerator(Runnable[Input,Output]):"""Runnable that runs a generator function. RunnableGenerators can be instantiated directly or by using a generator within a sequence. RunnableGenerators can be used to implement custom behavior, such as custom output parsers, while preserving streaming capabilities. Given a generator function with a signature Iterator[A] -> Iterator[B], wrapping it in a RunnableGenerator allows it to emit output chunks as soon as they are streamed in from the previous step. Note that if a generator function has a signature A -> Iterator[B], such that it requires its input from the previous step to be completed before emitting chunks (e.g., most LLMs need the entire prompt available to start generating), it can instead be wrapped in a RunnableLambda. Here is an example to show the basic mechanics of a RunnableGenerator: .. code-block:: python from typing import Any, AsyncIterator, Iterator from langchain_core.runnables import RunnableGenerator def gen(input: Iterator[Any]) -> Iterator[str]: for token in ["Have", " a", " nice", " day"]: yield token runnable = RunnableGenerator(gen) runnable.invoke(None) # "Have a nice day" list(runnable.stream(None)) # ["Have", " a", " nice", " day"] runnable.batch([None, None]) # ["Have a nice day", "Have a nice day"] # Async version: async def agen(input: AsyncIterator[Any]) -> AsyncIterator[str]: for token in ["Have", " a", " nice", " day"]: yield token runnable = RunnableGenerator(agen) await runnable.ainvoke(None) # "Have a nice day" [p async for p in runnable.astream(None)] # ["Have", " a", " nice", " day"] RunnableGenerator makes it easy to implement custom behavior within a streaming context. Below we show an example: .. code-block:: python from langchain_core.prompts import ChatPromptTemplate from langchain_core.runnables import RunnableGenerator, RunnableLambda from langchain_openai import ChatOpenAI from langchain_core.output_parsers import StrOutputParser model = ChatOpenAI() chant_chain = ( ChatPromptTemplate.from_template("Give me a 3 word chant about {topic}") | model | StrOutputParser() ) def character_generator(input: Iterator[str]) -> Iterator[str]: for token in input: if "," in token or "." in token: yield "👏" + token else: yield token runnable = chant_chain | character_generator assert type(runnable.last) is RunnableGenerator "".join(runnable.stream({"topic": "waste"})) # Reduce👏, Reuse👏, Recycle👏. # Note that RunnableLambda can be used to delay streaming of one step in a # sequence until the previous step is finished: def reverse_generator(input: str) -> Iterator[str]: # Yield characters of input in reverse order. for character in input[::-1]: yield character runnable = chant_chain | RunnableLambda(reverse_generator) "".join(runnable.stream({"topic": "waste"})) # ".elcycer ,esuer ,ecudeR" """def__init__(self,transform:Union[Callable[[Iterator[Input]],Iterator[Output]],Callable[[AsyncIterator[Input]],AsyncIterator[Output]],],atransform:Optional[Callable[[AsyncIterator[Input]],AsyncIterator[Output]]]=None,)->None:"""Initialize a RunnableGenerator. Args: transform: The transform function. atransform: The async transform function. Defaults to None. Raises: TypeError: If the transform is not a generator function. """ifatransformisnotNone:self._atransform=atransformfunc_for_name:Callable=atransformifis_async_generator(transform):self._atransform=transform# type: ignore[assignment]func_for_name=transformelifinspect.isgeneratorfunction(transform):self._transform=transformfunc_for_name=transformelse:raiseTypeError("Expected a generator function type for `transform`."f"Instead got an unsupported type: {type(transform)}")try:self.name=func_for_name.__name__exceptAttributeError:pass@propertydefInputType(self)->Any:func=getattr(self,"_transform",None)orself._atransformtry:params=inspect.signature(func).parametersfirst_param=next(iter(params.values()),None)iffirst_paramandfirst_param.annotation!=inspect.Parameter.empty:returngetattr(first_param.annotation,"__args__",(Any,))[0]else:returnAnyexceptValueError:returnAny@propertydefOutputType(self)->Any:func=getattr(self,"_transform",None)orself._atransformtry:sig=inspect.signature(func)return(getattr(sig.return_annotation,"__args__",(Any,))[0]ifsig.return_annotation!=inspect.Signature.emptyelseAny)exceptValueError:returnAnydef__eq__(self,other:Any)->bool:ifisinstance(other,RunnableGenerator):ifhasattr(self,"_transform")andhasattr(other,"_transform"):returnself._transform==other._transformelifhasattr(self,"_atransform")andhasattr(other,"_atransform"):returnself._atransform==other._atransformelse:returnFalseelse:returnFalsedef__repr__(self)->str:returnf"RunnableGenerator({self.name})"deftransform(self,input:Iterator[Input],config:Optional[RunnableConfig]=None,**kwargs:Any,)->Iterator[Output]:ifnothasattr(self,"_transform"):raiseNotImplementedError(f"{repr(self)} only supports async methods.")returnself._transform_stream_with_config(input,self._transform,# type: ignore[arg-type]config,**kwargs,# type: ignore[arg-type])defstream(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Any,)->Iterator[Output]:returnself.transform(iter([input]),config,**kwargs)definvoke(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Any)->Output:final=Noneforoutputinself.stream(input,config,**kwargs):iffinalisNone:final=outputelse:final=final+outputreturncast(Output,final)defatransform(self,input:AsyncIterator[Input],config:Optional[RunnableConfig]=None,**kwargs:Any,)->AsyncIterator[Output]:ifnothasattr(self,"_atransform"):raiseNotImplementedError(f"{repr(self)} only supports sync methods.")returnself._atransform_stream_with_config(input,self._atransform,config,**kwargs)defastream(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Any,)->AsyncIterator[Output]:asyncdefinput_aiter()->AsyncIterator[Input]:yieldinputreturnself.atransform(input_aiter(),config,**kwargs)asyncdefainvoke(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Any)->Output:final=Noneasyncforoutputinself.astream(input,config,**kwargs):iffinalisNone:final=outputelse:final=final+outputreturncast(Output,final)
[docs]classRunnableLambda(Runnable[Input,Output]):"""RunnableLambda converts a python callable into a Runnable. Wrapping a callable in a RunnableLambda makes the callable usable within either a sync or async context. RunnableLambda can be composed as any other Runnable and provides seamless integration with LangChain tracing. ``RunnableLambda`` is best suited for code that does not need to support streaming. If you need to support streaming (i.e., be able to operate on chunks of inputs and yield chunks of outputs), use ``RunnableGenerator`` instead. Note that if a ``RunnableLambda`` returns an instance of ``Runnable``, that instance is invoked (or streamed) during execution. Examples: .. code-block:: python # This is a RunnableLambda from langchain_core.runnables import RunnableLambda def add_one(x: int) -> int: return x + 1 runnable = RunnableLambda(add_one) runnable.invoke(1) # returns 2 runnable.batch([1, 2, 3]) # returns [2, 3, 4] # Async is supported by default by delegating to the sync implementation await runnable.ainvoke(1) # returns 2 await runnable.abatch([1, 2, 3]) # returns [2, 3, 4] # Alternatively, can provide both synd and sync implementations async def add_one_async(x: int) -> int: return x + 1 runnable = RunnableLambda(add_one, afunc=add_one_async) runnable.invoke(1) # Uses add_one await runnable.ainvoke(1) # Uses add_one_async """def__init__(self,func:Union[Union[Callable[[Input],Output],Callable[[Input],Iterator[Output]],Callable[[Input,RunnableConfig],Output],Callable[[Input,CallbackManagerForChainRun],Output],Callable[[Input,CallbackManagerForChainRun,RunnableConfig],Output],],Union[Callable[[Input],Awaitable[Output]],Callable[[Input],AsyncIterator[Output]],Callable[[Input,RunnableConfig],Awaitable[Output]],Callable[[Input,AsyncCallbackManagerForChainRun],Awaitable[Output]],Callable[[Input,AsyncCallbackManagerForChainRun,RunnableConfig],Awaitable[Output],],],],afunc:Optional[Union[Callable[[Input],Awaitable[Output]],Callable[[Input],AsyncIterator[Output]],Callable[[Input,RunnableConfig],Awaitable[Output]],Callable[[Input,AsyncCallbackManagerForChainRun],Awaitable[Output]],Callable[[Input,AsyncCallbackManagerForChainRun,RunnableConfig],Awaitable[Output],],]]=None,name:Optional[str]=None,)->None:"""Create a RunnableLambda from a callable, and async callable or both. Accepts both sync and async variants to allow providing efficient implementations for sync and async execution. Args: func: Either sync or async callable afunc: An async callable that takes an input and returns an output. Defaults to None. name: The name of the Runnable. Defaults to None. Raises: TypeError: If the func is not a callable type. TypeError: If both func and afunc are provided. """ifafuncisnotNone:self.afunc=afuncfunc_for_name:Callable=afuncifis_async_callable(func)oris_async_generator(func):ifafuncisnotNone:raiseTypeError("Func was provided as a coroutine function, but afunc was ""also provided. If providing both, func should be a regular ""function to avoid ambiguity.")self.afunc=funcfunc_for_name=funcelifcallable(func):self.func=cast(Callable[[Input],Output],func)func_for_name=funcelse:raiseTypeError("Expected a callable type for `func`."f"Instead got an unsupported type: {type(func)}")try:ifnameisnotNone:self.name=nameeliffunc_for_name.__name__!="<lambda>":self.name=func_for_name.__name__exceptAttributeError:pass@propertydefInputType(self)->Any:"""The type of the input to this Runnable."""func=getattr(self,"func",None)orself.afunctry:params=inspect.signature(func).parametersfirst_param=next(iter(params.values()),None)iffirst_paramandfirst_param.annotation!=inspect.Parameter.empty:returnfirst_param.annotationelse:returnAnyexceptValueError:returnAnydefget_input_schema(self,config:Optional[RunnableConfig]=None)->Type[BaseModel]:"""The pydantic schema for the input to this Runnable. Args: config: The config to use. Defaults to None. Returns: The input schema for this Runnable. """func=getattr(self,"func",None)orself.afuncifisinstance(func,itemgetter):# This is terrible, but afaict it's not possible to access _items# on itemgetter objects, so we have to parse the repritems=str(func).replace("operator.itemgetter(","")[:-1].split(", ")ifall(item[0]=="'"anditem[-1]=="'"andlen(item)>2foriteminitems):# It's a dict, lolreturncreate_model(self.get_name("Input"),**{item[1:-1]:(Any,None)foriteminitems},# type: ignore)else:returncreate_model(self.get_name("Input"),__root__=(List[Any],None),)ifself.InputType!=Any:returnsuper().get_input_schema(config)ifdict_keys:=get_function_first_arg_dict_keys(func):returncreate_model(self.get_name("Input"),**{key:(Any,None)forkeyindict_keys},# type: ignore)returnsuper().get_input_schema(config)@propertydefOutputType(self)->Any:"""The type of the output of this Runnable as a type annotation. Returns: The type of the output of this Runnable. """func=getattr(self,"func",None)orself.afunctry:sig=inspect.signature(func)ifsig.return_annotation!=inspect.Signature.empty:# unwrap iterator typesifgetattr(sig.return_annotation,"__origin__",None)in(collections.abc.Iterator,collections.abc.AsyncIterator,):returngetattr(sig.return_annotation,"__args__",(Any,))[0]returnsig.return_annotationelse:returnAnyexceptValueError:returnAny@propertydefdeps(self)->List[Runnable]:"""The dependencies of this Runnable. Returns: The dependencies of this Runnable. If the function has nonlocal variables that are Runnables, they are considered dependencies. """ifhasattr(self,"func"):objects=get_function_nonlocals(self.func)elifhasattr(self,"afunc"):objects=get_function_nonlocals(self.afunc)else:objects=[]deps:List[Runnable]=[]forobjinobjects:ifisinstance(obj,Runnable):deps.append(obj)elifisinstance(getattr(obj,"__self__",None),Runnable):deps.append(obj.__self__)returndeps@propertydefconfig_specs(self)->List[ConfigurableFieldSpec]:returnget_unique_config_specs(specfordepinself.depsforspecindep.config_specs)defget_graph(self,config:RunnableConfig|None=None)->Graph:ifdeps:=self.deps:graph=Graph()input_node=graph.add_node(self.get_input_schema(config))output_node=graph.add_node(self.get_output_schema(config))fordepindeps:dep_graph=dep.get_graph()dep_graph.trim_first_node()dep_graph.trim_last_node()ifnotdep_graph:graph.add_edge(input_node,output_node)else:dep_first_node,dep_last_node=graph.extend(dep_graph)ifnotdep_first_node:raiseValueError(f"Runnable {dep} has no first node")ifnotdep_last_node:raiseValueError(f"Runnable {dep} has no last node")graph.add_edge(input_node,dep_first_node)graph.add_edge(dep_last_node,output_node)else:graph=super().get_graph(config)returngraphdef__eq__(self,other:Any)->bool:ifisinstance(other,RunnableLambda):ifhasattr(self,"func")andhasattr(other,"func"):returnself.func==other.funcelifhasattr(self,"afunc")andhasattr(other,"afunc"):returnself.afunc==other.afuncelse:returnFalseelse:returnFalsedef__repr__(self)->str:"""A string representation of this Runnable."""ifhasattr(self,"func")andisinstance(self.func,itemgetter):returnf"RunnableLambda({str(self.func)[len('operator.'):]})"elifhasattr(self,"func"):returnf"RunnableLambda({get_lambda_source(self.func)or'...'})"elifhasattr(self,"afunc"):returnf"RunnableLambda(afunc={get_lambda_source(self.afunc)or'...'})"else:return"RunnableLambda(...)"def_invoke(self,input:Input,run_manager:CallbackManagerForChainRun,config:RunnableConfig,**kwargs:Any,)->Output:ifinspect.isgeneratorfunction(self.func):output:Optional[Output]=Noneforchunkincall_func_with_variable_args(cast(Callable[[Input],Iterator[Output]],self.func),input,config,run_manager,**kwargs,):ifoutputisNone:output=chunkelse:try:output=output+chunk# type: ignore[operator]exceptTypeError:output=chunkelse:output=call_func_with_variable_args(self.func,input,config,run_manager,**kwargs)# If the output is a Runnable, invoke itifisinstance(output,Runnable):recursion_limit=config["recursion_limit"]ifrecursion_limit<=0:raiseRecursionError(f"Recursion limit reached when invoking {self} with input {input}.")output=output.invoke(input,patch_config(config,callbacks=run_manager.get_child(),recursion_limit=recursion_limit-1,),)returncast(Output,output)asyncdef_ainvoke(self,input:Input,run_manager:AsyncCallbackManagerForChainRun,config:RunnableConfig,**kwargs:Any,)->Output:ifhasattr(self,"afunc"):afunc=self.afuncelse:ifinspect.isgeneratorfunction(self.func):deffunc(input:Input,run_manager:AsyncCallbackManagerForChainRun,config:RunnableConfig,**kwargs:Any,)->Output:output:Optional[Output]=Noneforchunkincall_func_with_variable_args(cast(Callable[[Input],Iterator[Output]],self.func),input,config,run_manager.get_sync(),**kwargs,):ifoutputisNone:output=chunkelse:try:output=output+chunk# type: ignore[operator]exceptTypeError:output=chunkreturncast(Output,output)else:deffunc(input:Input,run_manager:AsyncCallbackManagerForChainRun,config:RunnableConfig,**kwargs:Any,)->Output:returncall_func_with_variable_args(self.func,input,config,run_manager.get_sync(),**kwargs)@wraps(func)asyncdeff(*args,**kwargs):# type: ignore[no-untyped-def]returnawaitrun_in_executor(config,func,*args,**kwargs)afunc=fifis_async_generator(afunc):output:Optional[Output]=Noneasyncwithaclosing(cast(AsyncGenerator[Any,Any],acall_func_with_variable_args(cast(Callable,afunc),input,config,run_manager,**kwargs,),))asstream:asyncforchunkincast(AsyncIterator[Output],stream,):ifoutputisNone:output=chunkelse:try:output=output+chunk# type: ignore[operator]exceptTypeError:output=chunkelse:output=awaitacall_func_with_variable_args(cast(Callable,afunc),input,config,run_manager,**kwargs)# If the output is a Runnable, invoke itifisinstance(output,Runnable):recursion_limit=config["recursion_limit"]ifrecursion_limit<=0:raiseRecursionError(f"Recursion limit reached when invoking {self} with input {input}.")output=awaitoutput.ainvoke(input,patch_config(config,callbacks=run_manager.get_child(),recursion_limit=recursion_limit-1,),)returncast(Output,output)def_config(self,config:Optional[RunnableConfig],callable:Callable[...,Any])->RunnableConfig:returnensure_config(config)definvoke(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->Output:"""Invoke this Runnable synchronously. Args: input: The input to this Runnable. config: The config to use. Defaults to None. kwargs: Additional keyword arguments. Returns: The output of this Runnable. Raises: TypeError: If the Runnable is a coroutine function. """ifhasattr(self,"func"):returnself._call_with_config(self._invoke,input,self._config(config,self.func),**kwargs,)else:raiseTypeError("Cannot invoke a coroutine function synchronously.""Use `ainvoke` instead.")asyncdefainvoke(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->Output:"""Invoke this Runnable asynchronously. Args: input: The input to this Runnable. config: The config to use. Defaults to None. kwargs: Additional keyword arguments. Returns: The output of this Runnable. """the_func=self.afuncifhasattr(self,"afunc")elseself.funcreturnawaitself._acall_with_config(self._ainvoke,input,self._config(config,the_func),**kwargs,)def_transform(self,input:Iterator[Input],run_manager:CallbackManagerForChainRun,config:RunnableConfig,**kwargs:Any,)->Iterator[Output]:final:Inputgot_first_val=Falseforichunkininput:# By definitions, RunnableLambdas consume all input before emitting output.# If the input is not addable, then we'll assume that we can# only operate on the last chunk.# So we'll iterate until we get to the last chunk!ifnotgot_first_val:final=ichunkgot_first_val=Trueelse:try:final=final+ichunk# type: ignore[operator]exceptTypeError:final=ichunkifinspect.isgeneratorfunction(self.func):output:Optional[Output]=Noneforchunkincall_func_with_variable_args(self.func,cast(Input,final),config,run_manager,**kwargs):yieldchunkifoutputisNone:output=chunkelse:try:output=output+chunkexceptTypeError:output=chunkelse:output=call_func_with_variable_args(self.func,cast(Input,final),config,run_manager,**kwargs)# If the output is a Runnable, use its stream outputifisinstance(output,Runnable):recursion_limit=config["recursion_limit"]ifrecursion_limit<=0:raiseRecursionError(f"Recursion limit reached when invoking "f"{self} with input {final}.")forchunkinoutput.stream(final,patch_config(config,callbacks=run_manager.get_child(),recursion_limit=recursion_limit-1,),):yieldchunkelifnotinspect.isgeneratorfunction(self.func):# Otherwise, just yield ityieldcast(Output,output)deftransform(self,input:Iterator[Input],config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->Iterator[Output]:ifhasattr(self,"func"):yield fromself._transform_stream_with_config(input,self._transform,self._config(config,self.func),**kwargs,)else:raiseTypeError("Cannot stream a coroutine function synchronously.""Use `astream` instead.")defstream(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->Iterator[Output]:returnself.transform(iter([input]),config,**kwargs)asyncdef_atransform(self,input:AsyncIterator[Input],run_manager:AsyncCallbackManagerForChainRun,config:RunnableConfig,**kwargs:Any,)->AsyncIterator[Output]:final:Inputgot_first_val=Falseasyncforichunkininput:# By definitions, RunnableLambdas consume all input before emitting output.# If the input is not addable, then we'll assume that we can# only operate on the last chunk.# So we'll iterate until we get to the last chunk!ifnotgot_first_val:final=ichunkgot_first_val=Trueelse:try:final=final+ichunk# type: ignore[operator]exceptTypeError:final=ichunkifhasattr(self,"afunc"):afunc=self.afuncelse:ifinspect.isgeneratorfunction(self.func):raiseTypeError("Cannot stream from a generator function asynchronously.""Use .stream() instead.")deffunc(input:Input,run_manager:AsyncCallbackManagerForChainRun,config:RunnableConfig,**kwargs:Any,)->Output:returncall_func_with_variable_args(self.func,input,config,run_manager.get_sync(),**kwargs)@wraps(func)asyncdeff(*args,**kwargs):# type: ignore[no-untyped-def]returnawaitrun_in_executor(config,func,*args,**kwargs)afunc=fifis_async_generator(afunc):output:Optional[Output]=Noneasyncforchunkincast(AsyncIterator[Output],acall_func_with_variable_args(cast(Callable,afunc),cast(Input,final),config,run_manager,**kwargs,),):yieldchunkifoutputisNone:output=chunkelse:try:output=output+chunk# type: ignore[operator]exceptTypeError:output=chunkelse:output=awaitacall_func_with_variable_args(cast(Callable,afunc),cast(Input,final),config,run_manager,**kwargs)# If the output is a Runnable, use its astream outputifisinstance(output,Runnable):recursion_limit=config["recursion_limit"]ifrecursion_limit<=0:raiseRecursionError(f"Recursion limit reached when invoking "f"{self} with input {final}.")asyncforchunkinoutput.astream(final,patch_config(config,callbacks=run_manager.get_child(),recursion_limit=recursion_limit-1,),):yieldchunkelifnotis_async_generator(afunc):# Otherwise, just yield ityieldcast(Output,output)asyncdefatransform(self,input:AsyncIterator[Input],config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->AsyncIterator[Output]:asyncforoutputinself._atransform_stream_with_config(input,self._atransform,self._config(config,self.afuncifhasattr(self,"afunc")elseself.func),**kwargs,):yieldoutputasyncdefastream(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->AsyncIterator[Output]:asyncdefinput_aiter()->AsyncIterator[Input]:yieldinputasyncforchunkinself.atransform(input_aiter(),config,**kwargs):yieldchunk
[docs]classRunnableEachBase(RunnableSerializable[List[Input],List[Output]]):"""Runnable that delegates calls to another Runnable with each element of the input sequence. Use only if creating a new RunnableEach subclass with different __init__ args. See documentation for RunnableEach for more details. """bound:Runnable[Input,Output]classConfig:arbitrary_types_allowed=True@propertydefInputType(self)->Any:returnList[self.bound.InputType]# type: ignore[name-defined]defget_input_schema(self,config:Optional[RunnableConfig]=None)->Type[BaseModel]:returncreate_model(self.get_name("Input"),__root__=(List[self.bound.get_input_schema(config)],# type: ignoreNone,),)@propertydefOutputType(self)->Type[List[Output]]:returnList[self.bound.OutputType]# type: ignore[name-defined]defget_output_schema(self,config:Optional[RunnableConfig]=None)->Type[BaseModel]:schema=self.bound.get_output_schema(config)returncreate_model(self.get_name("Output"),__root__=(List[schema],# type: ignoreNone,),)@propertydefconfig_specs(self)->List[ConfigurableFieldSpec]:returnself.bound.config_specsdefget_graph(self,config:Optional[RunnableConfig]=None)->Graph:returnself.bound.get_graph(config)@classmethoddefis_lc_serializable(cls)->bool:returnTrue@classmethoddefget_lc_namespace(cls)->List[str]:"""Get the namespace of the langchain object."""return["langchain","schema","runnable"]def_invoke(self,inputs:List[Input],run_manager:CallbackManagerForChainRun,config:RunnableConfig,**kwargs:Any,)->List[Output]:configs=[patch_config(config,callbacks=run_manager.get_child())for_ininputs]returnself.bound.batch(inputs,configs,**kwargs)
[docs]asyncdefastream_events(self,input:Input,config:Optional[RunnableConfig]=None,**kwargs:Optional[Any],)->AsyncIterator[StreamEvent]:for_inrange(1):raiseNotImplementedError("RunnableEach does not support astream_events yet.")yield
[docs]classRunnableEach(RunnableEachBase[Input,Output]):"""Runnable that delegates calls to another Runnable with each element of the input sequence. It allows you to call multiple inputs with the bounded Runnable. RunnableEach makes it easy to run multiple inputs for the Runnable. In the below example, we associate and run three inputs with a Runnable: .. code-block:: python from langchain_core.runnables.base import RunnableEach from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser prompt = ChatPromptTemplate.from_template("Tell me a short joke about {topic}") model = ChatOpenAI() output_parser = StrOutputParser() runnable = prompt | model | output_parser runnable_each = RunnableEach(bound=runnable) output = runnable_each.invoke([{'topic':'Computer Science'}, {'topic':'Art'}, {'topic':'Biology'}]) print(output) # noqa: T201 """@classmethoddefget_lc_namespace(cls)->List[str]:"""Get the namespace of the langchain object."""return["langchain","schema","runnable"]defget_name(self,suffix:Optional[str]=None,*,name:Optional[str]=None)->str:name=nameorself.nameorf"RunnableEach<{self.bound.get_name()}>"returnsuper().get_name(suffix,name=name)defbind(self,**kwargs:Any)->RunnableEach[Input,Output]:returnRunnableEach(bound=self.bound.bind(**kwargs))defwith_config(self,config:Optional[RunnableConfig]=None,**kwargs:Any)->RunnableEach[Input,Output]:returnRunnableEach(bound=self.bound.with_config(config,**kwargs))defwith_listeners(self,*,on_start:Optional[Union[Callable[[Run],None],Callable[[Run,RunnableConfig],None]]]=None,on_end:Optional[Union[Callable[[Run],None],Callable[[Run,RunnableConfig],None]]]=None,on_error:Optional[Union[Callable[[Run],None],Callable[[Run,RunnableConfig],None]]]=None,)->RunnableEach[Input,Output]:"""Bind lifecycle listeners to a Runnable, returning a new Runnable. Args: on_start: Called before the Runnable starts running, with the Run object. Defaults to None. on_end: Called after the Runnable finishes running, with the Run object. Defaults to None. on_error: Called if the Runnable throws an error, with the Run object. Defaults to None. Returns: A new Runnable with the listeners bound. The Run object contains information about the run, including its id, type, input, output, error, start_time, end_time, and any tags or metadata added to the run. """returnRunnableEach(bound=self.bound.with_listeners(on_start=on_start,on_end=on_end,on_error=on_error))defwith_alisteners(self,*,on_start:Optional[AsyncListener]=None,on_end:Optional[AsyncListener]=None,on_error:Optional[AsyncListener]=None,)->RunnableEach[Input,Output]:"""Bind async lifecycle listeners to a Runnable, returning a new Runnable. Args: on_start: Called asynchronously before the Runnable starts running, with the Run object. Defaults to None. on_end: Called asynchronously after the Runnable finishes running, with the Run object. Defaults to None. on_error: Called asynchronously if the Runnable throws an error, with the Run object. Defaults to None. Returns: A new Runnable with the listeners bound. The Run object contains information about the run, including its id, type, input, output, error, start_time, end_time, and any tags or metadata added to the run. """returnRunnableEach(bound=self.bound.with_alisteners(on_start=on_start,on_end=on_end,on_error=on_error))
[docs]classRunnableBindingBase(RunnableSerializable[Input,Output]):"""Runnable that delegates calls to another Runnable with a set of kwargs. Use only if creating a new RunnableBinding subclass with different __init__ args. See documentation for RunnableBinding for more details. """bound:Runnable[Input,Output]"""The underlying Runnable that this Runnable delegates to."""kwargs:Mapping[str,Any]=Field(default_factory=dict)"""kwargs to pass to the underlying Runnable when running. For example, when the Runnable binding is invoked the underlying Runnable will be invoked with the same input but with these additional kwargs. """config:RunnableConfig=Field(default_factory=dict)"""The config to bind to the underlying Runnable."""config_factories:List[Callable[[RunnableConfig],RunnableConfig]]=Field(default_factory=list)"""The config factories to bind to the underlying Runnable."""# Union[Type[Input], BaseModel] + things like List[str]custom_input_type:Optional[Any]=None"""Override the input type of the underlying Runnable with a custom type. The type can be a pydantic model, or a type annotation (e.g., `List[str]`). """# Union[Type[Output], BaseModel] + things like List[str]custom_output_type:Optional[Any]=None"""Override the output type of the underlying Runnable with a custom type. The type can be a pydantic model, or a type annotation (e.g., `List[str]`). """classConfig:arbitrary_types_allowed=Truedef__init__(self,*,bound:Runnable[Input,Output],kwargs:Optional[Mapping[str,Any]]=None,config:Optional[RunnableConfig]=None,config_factories:Optional[List[Callable[[RunnableConfig],RunnableConfig]]]=None,custom_input_type:Optional[Union[Type[Input],BaseModel]]=None,custom_output_type:Optional[Union[Type[Output],BaseModel]]=None,**other_kwargs:Any,)->None:"""Create a RunnableBinding from a Runnable and kwargs. Args: bound: The underlying Runnable that this Runnable delegates calls to. kwargs: optional kwargs to pass to the underlying Runnable, when running the underlying Runnable (e.g., via `invoke`, `batch`, `transform`, or `stream` or async variants) Defaults to None. config: optional config to bind to the underlying Runnable. Defaults to None. config_factories: optional list of config factories to apply to the config before binding to the underlying Runnable. Defaults to None. custom_input_type: Specify to override the input type of the underlying Runnable with a custom type. Defaults to None. custom_output_type: Specify to override the output type of the underlying Runnable with a custom type. Defaults to None. **other_kwargs: Unpacked into the base class. """super().__init__(# type: ignore[call-arg]bound=bound,kwargs=kwargsor{},config=configor{},config_factories=config_factoriesor[],custom_input_type=custom_input_type,custom_output_type=custom_output_type,**other_kwargs,)# if we don't explicitly set config to the TypedDict here,# the pydantic init above will strip out any of the "extra"# fields even though total=False on the typed dict.self.config=configor{}defget_name(self,suffix:Optional[str]=None,*,name:Optional[str]=None)->str:returnself.bound.get_name(suffix,name=name)@propertydefInputType(self)->Type[Input]:return(cast(Type[Input],self.custom_input_type)ifself.custom_input_typeisnotNoneelseself.bound.InputType)@propertydefOutputType(self)->Type[Output]:return(cast(Type[Output],self.custom_output_type)ifself.custom_output_typeisnotNoneelseself.bound.OutputType)defget_input_schema(self,config:Optional[RunnableConfig]=None)->Type[BaseModel]:ifself.custom_input_typeisnotNone:returnsuper().get_input_schema(config)returnself.bound.get_input_schema(merge_configs(self.config,config))defget_output_schema(self,config:Optional[RunnableConfig]=None)->Type[BaseModel]:ifself.custom_output_typeisnotNone:returnsuper().get_output_schema(config)returnself.bound.get_output_schema(merge_configs(self.config,config))@propertydefconfig_specs(self)->List[ConfigurableFieldSpec]:returnself.bound.config_specsdefget_graph(self,config:Optional[RunnableConfig]=None)->Graph:returnself.bound.get_graph(self._merge_configs(config))@classmethoddefis_lc_serializable(cls)->bool:returnTrue@classmethoddefget_lc_namespace(cls)->List[str]:"""Get the namespace of the langchain object."""return["langchain","schema","runnable"]def_merge_configs(self,*configs:Optional[RunnableConfig])->RunnableConfig:config=merge_configs(self.config,*configs)returnmerge_configs(config,*(f(config)forfinself.config_factories))
[docs]classRunnableBinding(RunnableBindingBase[Input,Output]):"""Wrap a Runnable with additional functionality. A RunnableBinding can be thought of as a "runnable decorator" that preserves the essential features of Runnable; i.e., batching, streaming, and async support, while adding additional functionality. Any class that inherits from Runnable can be bound to a `RunnableBinding`. Runnables expose a standard set of methods for creating `RunnableBindings` or sub-classes of `RunnableBindings` (e.g., `RunnableRetry`, `RunnableWithFallbacks`) that add additional functionality. These methods include: - ``bind``: Bind kwargs to pass to the underlying Runnable when running it. - ``with_config``: Bind config to pass to the underlying Runnable when running it. - ``with_listeners``: Bind lifecycle listeners to the underlying Runnable. - ``with_types``: Override the input and output types of the underlying Runnable. - ``with_retry``: Bind a retry policy to the underlying Runnable. - ``with_fallbacks``: Bind a fallback policy to the underlying Runnable. Example: `bind`: Bind kwargs to pass to the underlying Runnable when running it. .. code-block:: python # Create a Runnable binding that invokes the ChatModel with the # additional kwarg `stop=['-']` when running it. from langchain_community.chat_models import ChatOpenAI model = ChatOpenAI() model.invoke('Say "Parrot-MAGIC"', stop=['-']) # Should return `Parrot` # Using it the easy way via `bind` method which returns a new # RunnableBinding runnable_binding = model.bind(stop=['-']) runnable_binding.invoke('Say "Parrot-MAGIC"') # Should return `Parrot` Can also be done by instantiating a RunnableBinding directly (not recommended): .. code-block:: python from langchain_core.runnables import RunnableBinding runnable_binding = RunnableBinding( bound=model, kwargs={'stop': ['-']} # <-- Note the additional kwargs ) runnable_binding.invoke('Say "Parrot-MAGIC"') # Should return `Parrot` """@classmethoddefget_lc_namespace(cls)->List[str]:"""Get the namespace of the langchain object."""return["langchain","schema","runnable"]defbind(self,**kwargs:Any)->Runnable[Input,Output]:"""Bind additional kwargs to a Runnable, returning a new Runnable. Args: **kwargs: The kwargs to bind to the Runnable. Returns: A new Runnable with the same type and config as the original, but with the additional kwargs bound. """returnself.__class__(bound=self.bound,config=self.config,kwargs={**self.kwargs,**kwargs},custom_input_type=self.custom_input_type,custom_output_type=self.custom_output_type,)defwith_config(self,config:Optional[RunnableConfig]=None,# Sadly Unpack is not well supported by mypy so this will have to be untyped**kwargs:Any,)->Runnable[Input,Output]:returnself.__class__(bound=self.bound,kwargs=self.kwargs,config=cast(RunnableConfig,{**self.config,**(configor{}),**kwargs}),custom_input_type=self.custom_input_type,custom_output_type=self.custom_output_type,)defwith_listeners(self,*,on_start:Optional[Union[Callable[[Run],None],Callable[[Run,RunnableConfig],None]]]=None,on_end:Optional[Union[Callable[[Run],None],Callable[[Run,RunnableConfig],None]]]=None,on_error:Optional[Union[Callable[[Run],None],Callable[[Run,RunnableConfig],None]]]=None,)->Runnable[Input,Output]:"""Bind lifecycle listeners to a Runnable, returning a new Runnable. Args: on_start: Called before the Runnable starts running, with the Run object. Defaults to None. on_end: Called after the Runnable finishes running, with the Run object. Defaults to None. on_error: Called if the Runnable throws an error, with the Run object. Defaults to None. Returns: The Runnable object contains information about the run, including its id, type, input, output, error, start_time, end_time, and any tags or metadata added to the run. """fromlangchain_core.tracers.root_listenersimportRootListenersTracerreturnself.__class__(bound=self.bound,kwargs=self.kwargs,config=self.config,config_factories=[lambdaconfig:{"callbacks":[RootListenersTracer(config=config,on_start=on_start,on_end=on_end,on_error=on_error,)],}],custom_input_type=self.custom_input_type,custom_output_type=self.custom_output_type,)defwith_types(self,input_type:Optional[Union[Type[Input],BaseModel]]=None,output_type:Optional[Union[Type[Output],BaseModel]]=None,)->Runnable[Input,Output]:returnself.__class__(bound=self.bound,kwargs=self.kwargs,config=self.config,custom_input_type=(input_typeifinput_typeisnotNoneelseself.custom_input_type),custom_output_type=(output_typeifoutput_typeisnotNoneelseself.custom_output_type),)defwith_retry(self,**kwargs:Any)->Runnable[Input,Output]:returnself.__class__(bound=self.bound.with_retry(**kwargs),kwargs=self.kwargs,config=self.config,)def__getattr__(self,name:str)->Any:attr=getattr(self.bound,name)ifcallable(attr)and(config_param:=inspect.signature(attr).parameters.get("config")):ifconfig_param.kind==inspect.Parameter.KEYWORD_ONLY:@wraps(attr)defwrapper(*args:Any,**kwargs:Any)->Any:returnattr(*args,config=merge_configs(self.config,kwargs.pop("config",None)),**kwargs,)returnwrapperelifconfig_param.kind==inspect.Parameter.POSITIONAL_OR_KEYWORD:idx=list(inspect.signature(attr).parameters).index("config")@wraps(attr)defwrapper(*args:Any,**kwargs:Any)->Any:iflen(args)>=idx+1:argsl=list(args)argsl[idx]=merge_configs(self.config,argsl[idx])returnattr(*argsl,**kwargs)else:returnattr(*args,config=merge_configs(self.config,kwargs.pop("config",None)),**kwargs,)returnwrapperreturnattr
[docs]defcoerce_to_runnable(thing:RunnableLike)->Runnable[Input,Output]:"""Coerce a Runnable-like object into a Runnable. Args: thing: A Runnable-like object. Returns: A Runnable. Raises: TypeError: If the object is not Runnable-like. """ifisinstance(thing,Runnable):returnthingelifis_async_generator(thing)orinspect.isgeneratorfunction(thing):returnRunnableGenerator(thing)elifcallable(thing):returnRunnableLambda(cast(Callable[[Input],Output],thing))elifisinstance(thing,dict):returncast(Runnable[Input,Output],RunnableParallel(thing))else:raiseTypeError(f"Expected a Runnable, callable or dict."f"Instead got an unsupported type: {type(thing)}")
[docs]defchain(func:Union[Callable[[Input],Output],Callable[[Input],Iterator[Output]],Callable[[Input],Coroutine[Any,Any,Output]],Callable[[Input],AsyncIterator[Output]],],)->Runnable[Input,Output]:"""Decorate a function to make it a Runnable. Sets the name of the Runnable to the name of the function. Any runnables called by the function will be traced as dependencies. Args: func: A callable. Returns: A Runnable. Example: .. code-block:: python from langchain_core.runnables import chain from langchain_core.prompts import PromptTemplate from langchain_openai import OpenAI @chain def my_func(fields): prompt = PromptTemplate("Hello, {name}!") llm = OpenAI() formatted = prompt.invoke(**fields) for chunk in llm.stream(formatted): yield chunk """returnRunnableLambda(func)