langchain-aws¶
Note
This package ref has not yet been fully migrated to v1.
Reference docs
This page contains reference documentation for AWS. See the docs for conceptual guides, tutorials, and examples on using AWS modules.
| FUNCTION | DESCRIPTION |
|---|---|
create_neptune_opencypher_qa_chain | Chain for question-answering against a Neptune graph |
create_neptune_sparql_qa_chain | Chain for question-answering against a Neptune graph |
Bases: BaseChatModel, BedrockBase
A chat model that uses the Bedrock API.
| METHOD | DESCRIPTION |
|---|---|
get_name | Get the name of the |
get_input_schema | Get a Pydantic model that can be used to validate input to the |
get_input_jsonschema | Get a JSON schema that represents the input to the |
get_output_schema | Get a Pydantic model that can be used to validate output to the |
get_output_jsonschema | Get a JSON schema that represents the output of the |
config_schema | The type of config this |
get_config_jsonschema | Get a JSON schema that represents the config of the |
get_graph | Return a graph representation of this |
get_prompts | Return a list of prompts used by this |
__or__ | Runnable "or" operator. |
__ror__ | Runnable "reverse-or" operator. |
pipe | Pipe |
pick | Pick keys from the output |
assign | Assigns new fields to the |
invoke | Transform a single input into an output. |
ainvoke | Transform a single input into an output. |
batch | Default implementation runs invoke in parallel using a thread pool executor. |
batch_as_completed | Run |
abatch | Default implementation runs |
abatch_as_completed | Run |
stream | Default implementation of |
astream | Default implementation of |
astream_log | Stream all output from a |
astream_events | Generate a stream of events. |
transform | Transform inputs to outputs. |
atransform | Transform inputs to outputs. |
bind | Bind arguments to a |
with_config | Bind config to a |
with_listeners | Bind lifecycle listeners to a |
with_alisteners | Bind async lifecycle listeners to a |
with_types | Bind input and output types to a |
with_retry | Create a new |
map | Return a new |
with_fallbacks | Add fallbacks to a |
as_tool | Create a |
__init__ | |
lc_id | Return a unique identifier for this class for serialization purposes. |
to_json | Serialize the |
to_json_not_implemented | Serialize a "not implemented" object. |
configurable_fields | Configure particular |
configurable_alternatives | Configure alternatives for |
set_verbose | If verbose is |
generate_prompt | Pass a sequence of prompts to the model and return model generations. |
agenerate_prompt | Asynchronously pass a sequence of prompts and return model generations. |
validate_environment | Validate that AWS credentials to and python package exists in environment. |
generate | Pass a sequence of prompts to the model and return model generations. |
agenerate | Asynchronously pass a sequence of prompts to a model and return generations. |
dict | Return a dictionary of the LLM. |
is_lc_serializable | Return whether this model can be serialized by Langchain. |
get_lc_namespace | Get the namespace of the langchain object. |
build_extra | Build extra kwargs from additional params that were passed in. |
get_num_tokens_from_messages | Get the number of tokens in the messages. |
get_num_tokens | Get the number of tokens present in the text. |
get_token_ids | Return the ordered IDs of the tokens in a text. |
set_system_prompt_with_tools | Workaround to bind. Sets the system prompt with tools |
bind_tools | Bind tool-like objects to this chat model. |
with_structured_output | Model wrapper that returns outputs formatted to match the given schema. |
class-attribute instance-attribute ¶
name: str | None = None The name of the Runnable. Used for debugging and tracing.
property ¶
The type of input this Runnable accepts specified as a Pydantic model.
property ¶
Output schema.
The type of output this Runnable produces specified as a Pydantic model.
property ¶
config_specs: list[ConfigurableFieldSpec] List configurable fields for this Runnable.
property ¶
A map of constructor argument names to secret ids.
For example, {"openai_api_key": "OPENAI_API_KEY"}
class-attribute instance-attribute ¶
Whether to cache the response.
- If
True, will use the global cache. - If
False, will not use a cache - If
None, will use the global cache if it's set, otherwise no cache. - If instance of
BaseCache, will use the provided cache.
Caching is not currently supported for streaming methods of models.
class-attribute instance-attribute ¶
Whether to print out response text.
class-attribute instance-attribute ¶
callbacks: Callbacks = Field(default=None, exclude=True) Callbacks to add to the run trace.
class-attribute instance-attribute ¶
Tags to add to the run trace.
class-attribute instance-attribute ¶
Metadata to add to the run trace.
class-attribute instance-attribute ¶
Optional encoder to use for counting tokens.
class-attribute instance-attribute ¶
The bedrock runtime client for making data plane API calls
class-attribute instance-attribute ¶
The bedrock client for making control plane API calls
class-attribute instance-attribute ¶
The aws region e.g., us-west-2. Falls back to AWS_REGION or AWS_DEFAULT_REGION env variable or region specified in ~/.aws/config in case it is not provided here.
class-attribute instance-attribute ¶
The name of the profile in the ~/.aws/credentials or ~/.aws/config files, which has either access keys or role information specified.
If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
class-attribute instance-attribute ¶
aws_access_key_id: SecretStr | None = Field( default_factory=secret_from_env("AWS_ACCESS_KEY_ID", default=None) ) AWS access key id.
If provided, aws_secret_access_key must also be provided.
If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_ACCESS_KEY_ID environment variable.
class-attribute instance-attribute ¶
aws_secret_access_key: SecretStr | None = Field( default_factory=secret_from_env("AWS_SECRET_ACCESS_KEY", default=None) ) AWS secret_access_key.
If provided, aws_access_key_id must also be provided.
If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_SECRET_ACCESS_KEY environment variable.
class-attribute instance-attribute ¶
aws_session_token: SecretStr | None = Field( default_factory=secret_from_env("AWS_SESSION_TOKEN", default=None) ) AWS session token.
If provided, aws_access_key_id and aws_secret_access_key must also be provided.
Not required unless using temporary credentials.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_SESSION_TOKEN environment variable.
class-attribute instance-attribute ¶
config: Any = None An optional botocore.config.Config instance to pass to the client.
class-attribute instance-attribute ¶
provider: str | None = None The model provider, e.g., 'amazon', 'cohere', 'ai21', etc. When not supplied, provider is extracted from the first part of the model_id e.g. 'amazon' in 'amazon.titan-text-express-v1'. This value should be provided for model IDs that do not have the provider in them, e.g., custom and provisioned models that have an ARN associated with them.
class-attribute instance-attribute ¶
Id of the model to call, e.g., 'amazon.titan-text-express-v1', this is equivalent to the modelId property in the list-foundation-models api. For custom and provisioned models, an ARN value is expected.
class-attribute instance-attribute ¶
An optional field to pass the base model id. If provided, this will be used over the value of model_id to identify the base model.
class-attribute instance-attribute ¶
Keyword arguments to pass to the model.
class-attribute instance-attribute ¶
endpoint_url: str | None = None Needed if you don't want to default to 'us-east-1' endpoint
class-attribute instance-attribute ¶
streaming: bool = False Whether to stream the results.
class-attribute instance-attribute ¶
guardrails: Mapping[str, Any] | None = { "trace": None, "guardrailIdentifier": None, "guardrailVersion": None, } An optional dictionary to configure guardrails for Bedrock.
This field guardrails consists of two keys: 'guardrailId' and 'guardrailVersion', which should be strings, but are initialized to None.
It's used to determine if specific guardrails are enabled and properly set.
Type
Optional[Mapping[str, str]]: A mapping with 'guardrailId' and 'guardrailVersion' keys.
Example
To enable tracing for guardrails, set the 'trace' key to True and pass a callback handler to the 'run_manager' parameter of the 'generate', '_call' methods.
Example
https://python.langchain.com/docs/concepts/callbacks/ for more information on callback handlers.
class BedrockAsyncCallbackHandler(AsyncCallbackHandler): async def on_llm_error( self, error: BaseException, **kwargs: Any, ) -> Any: reason = kwargs.get("reason") if reason == "GUARDRAIL_INTERVENED": ...Logic to handle guardrail intervention...
class-attribute instance-attribute ¶
rate_limiter: BaseRateLimiter | None = Field(default=None, exclude=True) An optional rate limiter to use for limiting the number of requests.
class-attribute instance-attribute ¶
Whether to disable streaming for this model.
If streaming is bypassed, then stream/astream/astream_events will defer to invoke/ainvoke.
- If
True, will always bypass streaming case. - If
'tool_calling', will bypass streaming case only when the model is called with atoolskeyword argument. In other words, LangChain will automatically switch to non-streaming behavior (invoke) only when the tools argument is provided. This offers the best of both worlds. - If
False(Default), will always use streaming case if available.
The main reason for this flag is that code might be written using stream and a user may want to swap out a given model for another model whose the implementation does not properly support streaming.
class-attribute instance-attribute ¶
Version of AIMessage output format to store in message content.
AIMessage.content_blocks will lazily parse the contents of content into a standard format. This flag can be used to additionally store the standard format in message content, e.g., for serialization purposes.
Supported values:
'v0': provider-specific format in content (can lazily-parse withcontent_blocks)'v1': standardized format in content (consistent withcontent_blocks)
Partner packages (e.g., langchain-openai) can also use this field to roll out new content formats in a backward-compatible way.
Added in langchain-core 1.0
class-attribute instance-attribute ¶
profile: ModelProfile | None = Field(default=None, exclude=True) Profile detailing model capabilities.
Beta feature
This is a beta feature. The format of model profiles is subject to change.
If not specified, automatically loaded from the provider package on initialization if data is available.
Example profile data includes context window sizes, supported modalities, or support for tool calling, structured output, and other features.
Added in langchain-core 1.1
class-attribute instance-attribute ¶
beta_use_converse_api: bool = False Use the new Bedrock converse API which provides a standardized interface to all Bedrock models. Support still in beta. See ChatBedrockConverse docs for more.
class-attribute instance-attribute ¶
Stop sequence inference parameter from new Bedrock converse API providing a sequence of characters that causes a model to stop generating a response. See https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_InferenceConfiguration.html for more.
property ¶
List of attribute names that should be included in the serialized kwargs.
These attributes must be accepted by the constructor.
Default is an empty dictionary.
get_input_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate input to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate input. |
get_input_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the input to the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the input to the |
Example
Added in langchain-core 0.3.0
get_output_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate output to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate output. |
get_output_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the output of the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the output of the |
Example
Added in langchain-core 0.3.0
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.
| PARAMETER | DESCRIPTION |
|---|---|
include | A list of fields to include in the config schema. |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate config. |
get_graph(config: RunnableConfig | None = None) -> Graph Return a graph representation of this Runnable.
get_prompts(config: RunnableConfig | None = None) -> list[BasePromptTemplate] Return a list of prompts used by this Runnable.
__or__( other: Runnable[Any, Other] | Callable[[Iterator[Any]], Iterator[Other]] | Callable[[AsyncIterator[Any]], AsyncIterator[Other]] | Callable[[Any], Other] | Mapping[str, Runnable[Any, Other] | Callable[[Any], Other] | Any], ) -> RunnableSerializable[Input, Other] Runnable "or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
__ror__( other: Runnable[Other, Any] | Callable[[Iterator[Other]], Iterator[Any]] | Callable[[AsyncIterator[Other]], AsyncIterator[Any]] | Callable[[Other], Any] | Mapping[str, Runnable[Other, Any] | Callable[[Other], Any] | Any], ) -> RunnableSerializable[Other, Output] Runnable "reverse-or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Other, Output] | A new |
pipe( *others: Runnable[Any, Other] | Callable[[Any], Other], name: str | None = None ) -> RunnableSerializable[Input, Other] Pipe Runnable objects.
Compose this Runnable with Runnable-like objects to make a RunnableSequence.
Equivalent to RunnableSequence(self, *others) or self | others[0] | ...
Example
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] | PARAMETER | DESCRIPTION |
|---|---|
*others | Other TYPE: |
name | An optional name for the resulting TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
Pick keys from the output dict of this Runnable.
Pick a single key
import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) chain = RunnableMap(str=as_str, json=as_json) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3]} json_only_chain = chain.pick("json") json_only_chain.invoke("[1, 2, 3]") # -> [1, 2, 3] Pick a list of keys
from typing import Any import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) def as_bytes(x: Any) -> bytes: return bytes(x, "utf-8") chain = RunnableMap( str=as_str, json=as_json, bytes=RunnableLambda(as_bytes) ) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3], "bytes": b"[1, 2, 3]"} json_and_bytes_chain = chain.pick(["json", "bytes"]) json_and_bytes_chain.invoke("[1, 2, 3]") # -> {"json": [1, 2, 3], "bytes": b"[1, 2, 3]"} | PARAMETER | DESCRIPTION |
|---|---|
keys | A key or list of keys to pick from the output dict. |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | a new |
assign( **kwargs: Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any] | Mapping[str, Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any]], ) -> RunnableSerializable[Any, Any] Assigns new fields to the dict output of this Runnable.
from langchain_core.language_models.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}" ) model = FakeStreamingListLLM(responses=["foo-lish"]) chain: Runnable = prompt | model | {"str": StrOutputParser()} chain_with_assign = chain.assign(hello=itemgetter("str") | model) print(chain_with_assign.input_schema.model_json_schema()) # {'title': 'PromptInput', 'type': 'object', 'properties': {'question': {'title': 'Question', 'type': 'string'}}} print(chain_with_assign.output_schema.model_json_schema()) # {'title': 'RunnableSequenceOutput', 'type': 'object', 'properties': {'str': {'title': 'Str', 'type': 'string'}, 'hello': {'title': 'Hello', 'type': 'string'}}} | PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A mapping of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | A new |
invoke( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> AIMessage Transform a single input into an output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
ainvoke( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> AIMessage Transform a single input into an output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Output | The output of the |
batch( inputs: list[Input], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> 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 must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
batch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> Iterator[tuple[int, Output | Exception]] Run invoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
tuple[int, Output | Exception] | Tuples of the index of the input and the output from the |
async ¶
abatch( inputs: list[Input], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> list[Output] Default implementation runs ainvoke in parallel using asyncio.gather.
The default implementation of batch works well for IO bound runnables.
Subclasses must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
async ¶
abatch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> AsyncIterator[tuple[int, Output | Exception]] Run ainvoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[tuple[int, Output | Exception]] | A tuple of the index of the input and the output from the |
stream( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> Iterator[AIMessageChunk] Default implementation of stream, which calls invoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
astream( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> AsyncIterator[AIMessageChunk] Default implementation of astream, which calls ainvoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
async ¶
astream_log( input: Any, config: RunnableConfig | None = None, *, diff: bool = True, with_streamed_output_list: bool = True, include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> 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.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
diff | Whether to yield diffs between each step or the current state. TYPE: |
with_streamed_output_list | Whether to yield the TYPE: |
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 TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[RunLogPatch] | AsyncIterator[RunLog] | A |
async ¶
astream_events( input: Any, config: RunnableConfig | None = None, *, version: Literal["v1", "v2"] = "v2", include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> AsyncIterator[StreamEvent] Generate a stream of events.
Use to create an iterator over StreamEvent that provide real-time information about the progress of the Runnable, including StreamEvent from intermediate results.
A StreamEvent is a dictionary with the following schema:
event: Event names are of the format:on_[runnable_type]_(start|stream|end).name: The name of theRunnablethat generated the event.run_id: Randomly generated ID associated with the given execution of theRunnablethat emitted the event. A childRunnablethat gets invoked as part of the execution of a parentRunnableis assigned its own unique ID.parent_ids: The IDs of the parent runnables that generated the event. The rootRunnablewill 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: The tags of theRunnablethat generated the event.metadata: The metadata of theRunnablethat generated the event.data: The data associated with the event. The contents of this field depend on the type of event. See the table below for more details.
Below is a table that illustrates some events 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.
Note
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:
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:
prompt:
template = ChatPromptTemplate.from_messages( [ ("system", "You are Cat Agent 007"), ("human", "{question}"), ] ).with_config({"run_name": "my_template", "tags": ["my_template"]}) Example
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": [], }, ] 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) | PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
version | The version of the schema to use, either Users should use
No default will be assigned until the API is stabilized. custom events will only be surfaced in TYPE: |
include_names | Only include events from |
include_types | Only include events from |
include_tags | Only include events from |
exclude_names | Exclude events from |
exclude_types | Exclude events from |
exclude_tags | Exclude events from |
**kwargs | Additional keyword arguments to pass to the These will be passed to TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[StreamEvent] | An async stream of |
| RAISES | DESCRIPTION |
|---|---|
NotImplementedError | If the version is not |
transform( input: Iterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None ) -> Iterator[Output] Transform inputs to outputs.
Default implementation of transform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
atransform( input: AsyncIterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None, ) -> AsyncIterator[Output] Transform inputs to outputs.
Default implementation of atransform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An async iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
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.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | The arguments to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_ollama import ChatOllama from langchain_core.output_parsers import StrOutputParser model = ChatOllama(model="llama3.1") # Without bind chain = model | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two three four five.' # With bind chain = model.bind(stop=["three"]) | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two'
with_config( config: RunnableConfig | None = None, **kwargs: Any ) -> Runnable[Input, Output] Bind config to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | The config to bind to the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_listeners( *, on_start: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_end: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_error: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, ) -> Runnable[Input, Output] Bind lifecycle listeners to a Runnable, returning a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called before the TYPE: |
on_end | Called after the TYPE: |
on_error | Called if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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)
with_alisteners( *, on_start: AsyncListener | None = None, on_end: AsyncListener | None = None, on_error: AsyncListener | None = None, ) -> Runnable[Input, Output] Bind async lifecycle listeners to a Runnable.
Returns a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called asynchronously before the TYPE: |
on_end | Called asynchronously after the TYPE: |
on_error | Called asynchronously if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_core.runnables import RunnableLambda, Runnable from datetime import datetime, timezone import time import asyncio def format_t(timestamp: float) -> str: return datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat() 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 2025-03-01T07:05:22.875378+00:00 # on start callback starts at 2025-03-01T07:05:22.875495+00:00 # on start callback ends at 2025-03-01T07:05:25.878862+00:00 # on start callback ends at 2025-03-01T07:05:25.878947+00:00 # Runnable[2s]: starts at 2025-03-01T07:05:25.879392+00:00 # Runnable[3s]: starts at 2025-03-01T07:05:25.879804+00:00 # Runnable[2s]: ends at 2025-03-01T07:05:27.881998+00:00 # on end callback starts at 2025-03-01T07:05:27.882360+00:00 # Runnable[3s]: ends at 2025-03-01T07:05:28.881737+00:00 # on end callback starts at 2025-03-01T07:05:28.882428+00:00 # on end callback ends at 2025-03-01T07:05:29.883893+00:00 # on end callback ends at 2025-03-01T07:05:30.884831+00:00
with_types( *, input_type: type[Input] | None = None, output_type: type[Output] | None = None ) -> Runnable[Input, Output] Bind input and output types to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
input_type | The input type to bind to the TYPE: |
output_type | The output type to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_retry( *, retry_if_exception_type: tuple[type[BaseException], ...] = (Exception,), wait_exponential_jitter: bool = True, exponential_jitter_params: ExponentialJitterParams | None = None, stop_after_attempt: int = 3, ) -> Runnable[Input, Output] Create a new Runnable that retries the original Runnable on exceptions.
| PARAMETER | DESCRIPTION |
|---|---|
retry_if_exception_type | A tuple of exception types to retry on. TYPE: |
wait_exponential_jitter | Whether to add jitter to the wait time between retries. TYPE: |
stop_after_attempt | The maximum number of attempts to make before giving up. TYPE: |
exponential_jitter_params | Parameters for TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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
with_fallbacks( fallbacks: Sequence[Runnable[Input, Output]], *, exceptions_to_handle: tuple[type[BaseException], ...] = (Exception,), exception_key: str | None = None, ) -> RunnableWithFallbacks[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.
| PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
Example
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 | PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
as_tool( args_schema: type[BaseModel] | None = None, *, name: str | None = None, description: str | None = None, arg_types: dict[str, type] | None = 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.
| PARAMETER | DESCRIPTION |
|---|---|
args_schema | The schema for the tool. |
name | The name of the tool. TYPE: |
description | The description of the tool. TYPE: |
arg_types | A dictionary of argument names to types. |
| RETURNS | DESCRIPTION |
|---|---|
BaseTool | A |
TypedDict input
dict input, specifying schema via args_schema
from typing import Any from pydantic 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
classmethod ¶
Return a unique identifier for this class for serialization purposes.
The unique identifier is a list of strings that describes the path to the object.
For example, for the class langchain.llms.openai.OpenAI, the id is ["langchain", "llms", "openai", "OpenAI"].
Serialize the Runnable to JSON.
| RETURNS | DESCRIPTION |
|---|---|
SerializedConstructor | SerializedNotImplemented | A JSON-serializable representation of the |
Serialize a "not implemented" object.
| RETURNS | DESCRIPTION |
|---|---|
SerializedNotImplemented |
|
configurable_fields( **kwargs: AnyConfigurableField, ) -> RunnableSerializable[Input, Output] Configure particular Runnable fields at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A dictionary of TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If a configuration key is not found in the |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
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, )
configurable_alternatives( which: ConfigurableField, *, default_key: str = "default", prefix_keys: bool = False, **kwargs: Runnable[Input, Output] | Callable[[], Runnable[Input, Output]], ) -> RunnableSerializable[Input, Output] Configure alternatives for Runnable objects that can be set at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
which | The TYPE: |
default_key | The default key to use if no alternative is selected. TYPE: |
prefix_keys | Whether to prefix the keys with the TYPE: |
**kwargs | A dictionary of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
from langchain_anthropic import ChatAnthropic from langchain_core.runnables.utils import ConfigurableField from langchain_openai import ChatOpenAI model = ChatAnthropic( model_name="claude-sonnet-4-5-20250929" ).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 )
generate_prompt( prompts: list[PromptValue], stop: list[str] | None = None, callbacks: Callbacks = None, **kwargs: Any, ) -> LLMResult Pass a sequence of prompts to the model and return model generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
prompts | List of A TYPE: |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
async ¶
agenerate_prompt( prompts: list[PromptValue], stop: list[str] | None = None, callbacks: Callbacks = None, **kwargs: Any, ) -> LLMResult Asynchronously pass a sequence of prompts and return model generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
prompts | List of A TYPE: |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
validate_environment() -> Self Validate that AWS credentials to and python package exists in environment.
generate( messages: list[list[BaseMessage]], stop: list[str] | None = None, callbacks: Callbacks = None, *, tags: list[str] | None = None, metadata: dict[str, Any] | None = None, run_name: str | None = None, run_id: UUID | None = None, **kwargs: Any, ) -> LLMResult Pass a sequence of prompts to the model and return model generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
messages | List of list of messages. TYPE: |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
tags | The tags to apply. |
metadata | The metadata to apply. |
run_name | The name of the run. TYPE: |
run_id | The ID of the run. TYPE: |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
async ¶
agenerate( messages: list[list[BaseMessage]], stop: list[str] | None = None, callbacks: Callbacks = None, *, tags: list[str] | None = None, metadata: dict[str, Any] | None = None, run_name: str | None = None, run_id: UUID | None = None, **kwargs: Any, ) -> LLMResult Asynchronously pass a sequence of prompts to a model and return generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
messages | List of list of messages. TYPE: |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
tags | The tags to apply. |
metadata | The metadata to apply. |
run_name | The name of the run. TYPE: |
run_id | The ID of the run. TYPE: |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
classmethod ¶
is_lc_serializable() -> bool Return whether this model can be serialized by Langchain.
classmethod ¶
classmethod ¶
Build extra kwargs from additional params that were passed in.
get_num_tokens_from_messages( messages: list[BaseMessage], tools: Sequence | None = None ) -> int Get the number of tokens in the messages.
Useful for checking if an input fits in a model's context window.
This should be overridden by model-specific implementations to provide accurate token counts via model-specific tokenizers.
Note
- The base implementation of
get_num_tokens_from_messagesignores tool schemas. - The base implementation of
get_num_tokens_from_messagesadds additional prefixes to messages in represent user roles, which will add to the overall token count. Model-specific implementations may choose to handle this differently.
| PARAMETER | DESCRIPTION |
|---|---|
messages | The message inputs to tokenize. TYPE: |
tools | If provided, sequence of dict, TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
int | The sum of the number of tokens across the messages. |
Get the number of tokens present in the text.
Useful for checking if an input fits in a model's context window.
This should be overridden by model-specific implementations to provide accurate token counts via model-specific tokenizers.
| PARAMETER | DESCRIPTION |
|---|---|
text | The string input to tokenize. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
int | The integer number of tokens in the text. |
set_system_prompt_with_tools(xml_tools_system_prompt: str) -> None Workaround to bind. Sets the system prompt with tools
bind_tools( tools: Sequence[dict[str, Any] | TypeBaseModel | Callable | BaseTool], *, tool_choice: dict | str | Literal["auto", "none"] | bool | None = None, **kwargs: Any, ) -> Runnable[LanguageModelInput, AIMessage] Bind tool-like objects to this chat model.
Assumes model has a tool calling API.
| PARAMETER | DESCRIPTION |
|---|---|
tools | A list of tool definitions to bind to this chat model. Can be a dictionary, pydantic model, callable, or BaseTool. Pydantic models, callables, and BaseTools will be automatically converted to their schema dictionary representation. TYPE: |
tool_choice | Which tool to require the model to call. Must be the name of the single provided function or "auto" to automatically determine which function to call (if any), or a dict of the form: {"type": "function", "function": {"name": < TYPE: |
**kwargs | Any additional parameters to pass to the Runnable constructor. TYPE: |
with_structured_output( schema: dict[str, Any] | TypeBaseModel | Type, *, include_raw: bool = False, **kwargs: Any, ) -> Runnable[LanguageModelInput, dict | BaseModel] Model wrapper that returns outputs formatted to match the given schema.
| PARAMETER | DESCRIPTION |
|---|---|
schema | The output schema as a dict or a Pydantic class. If a Pydantic class then the model output will be an object of that class. If a dict then the model output will be a dict. With a Pydantic class the returned attributes will be validated, whereas with a dict they will not be. |
include_raw | If If an error occurs during model output parsing it will be raised. If If an error occurs during output parsing it will be caught and returned as well. The final output is always a TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[LanguageModelInput, dict | BaseModel] | A Runnable that takes any ChatModel input. The output type depends on |
Runnable[LanguageModelInput, dict | BaseModel] | include_raw and schema. |
Runnable[LanguageModelInput, dict | BaseModel] | If include_raw is True then output is a dict with keys: raw: BaseMessage, parsed: Optional[_DictOrPydantic], parsing_error: Optional[BaseException], |
Runnable[LanguageModelInput, dict | BaseModel] | If include_raw is False and schema is a Dict then the runnable outputs a Dict. |
Runnable[LanguageModelInput, dict | BaseModel] | If include_raw is False and schema is a Type[BaseModel] then the runnable |
Runnable[LanguageModelInput, dict | BaseModel] | outputs a BaseModel. |
Pydantic schema (include_raw=False):
from langchain_aws.chat_models.bedrock import ChatBedrock from pydantic import BaseModel class AnswerWithJustification(BaseModel): '''An answer to the user question along with justification for the answer.''' answer: str justification: str llm = ChatBedrock( model_id="anthropic.claude-3-sonnet-20240229-v1:0", model_kwargs={"temperature": 0.001}, ) # type: ignore[call-arg] structured_model = model.with_structured_output(AnswerWithJustification) structured_model.invoke("What weighs more a pound of bricks or a pound of feathers") # -> AnswerWithJustification( # answer='They weigh the same', # justification='Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.' # ) Pydantic schema (include_raw=True):
from langchain_aws.chat_models.bedrock import ChatBedrock from pydantic import BaseModel class AnswerWithJustification(BaseModel): '''An answer to the user question along with justification for the answer.''' answer: str justification: str model = ChatBedrock( model_id="anthropic.claude-3-sonnet-20240229-v1:0", model_kwargs={"temperature": 0.001}, ) # type: ignore[call-arg] structured_model = model.with_structured_output(AnswerWithJustification, include_raw=True) structured_model.invoke("What weighs more a pound of bricks or a pound of feathers") # -> { # 'raw': AIMessage(content='', additional_kwargs={'tool_calls': [{'id': 'call_Ao02pnFYXD6GN1yzc0uXPsvF', 'function': {'arguments': '{"answer":"They weigh the same.","justification":"Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ."}', 'name': 'AnswerWithJustification'}, 'type': 'function'}]}), # 'parsed': AnswerWithJustification(answer='They weigh the same.', justification='Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.'), # 'parsing_error': None # } Dict schema (include_raw=False):
from langchain_aws.chat_models.bedrock import ChatBedrock schema = { "name": "AnswerWithJustification", "description": "An answer to the user question along with justification for the answer.", "input_schema": { "type": "object", "properties": { "answer": {"type": "string"}, "justification": {"type": "string"}, }, "required": ["answer", "justification"] } } model = ChatBedrock( model_id="anthropic.claude-3-sonnet-20240229-v1:0", model_kwargs={"temperature": 0.001}, ) # type: ignore[call-arg] structured_model = model.with_structured_output(schema) structured_model.invoke("What weighs more a pound of bricks or a pound of feathers") # -> { # 'answer': 'They weigh the same', # 'justification': 'Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume and density of the two substances differ.' # }
Bases: BaseChatModel
Bedrock chat model integration built on the Bedrock converse API.
This implementation will eventually replace the existing ChatBedrock implementation once the Bedrock converse API has feature parity with older Bedrock API. Specifically the converse API does not yet support custom Bedrock models.
Setup
To use Amazon Bedrock make sure you've gone through all the steps described here: https://docs.aws.amazon.com/bedrock/latest/userguide/setting-up.html
Once that's completed, install the LangChain integration:
Key init args — completion params: model: str Name of BedrockConverse model to use. temperature: float Sampling temperature. max_tokens: Optional[int] Max number of tokens to generate.
Key init args — client params: region_name: Optional[str] AWS region to use, e.g. 'us-west-2'. base_url: Optional[str] Bedrock endpoint to use. Needed if you don't want to default to us-east- 1 endpoint. credentials_profile_name: Optional[str] The name of the profile in the ~/.aws/credentials or ~/.aws/config files.
See full list of supported init args and their descriptions in the params section.
Instantiate
Invoke
messages = [ ("system", "You are a helpful translator. Translate the user sentence to French."), ("human", "I love programming."), ] model.invoke(messages) AIMessage(content=[{'type': 'text', 'text': "J'aime la programmation."}], response_metadata={'ResponseMetadata': {'RequestId': '9ef1e313-a4c1-4f79-b631-171f658d3c0e', 'HTTPStatusCode': 200, 'HTTPHeaders': {'date': 'Sat, 15 Jun 2024 01:19:24 GMT', 'content-type': 'application/json', 'content-length': '205', 'connection': 'keep-alive', 'x-amzn-requestid': '9ef1e313-a4c1-4f79-b631-171f658d3c0e'}, 'RetryAttempts': 0}, 'stopReason': 'end_turn', 'metrics': {'latencyMs': 609}}, id='run-754e152b-2b41-4784-9538-d40d71a5c3bc-0', usage_metadata={'input_tokens': 25, 'output_tokens': 11, 'total_tokens': 36}) Stream
AIMessageChunk(content=[], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117') AIMessageChunk(content=[{'type': 'text', 'text': 'J', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117') AIMessageChunk(content=[{'text': "'", 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117') AIMessageChunk(content=[{'text': 'a', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117') AIMessageChunk(content=[{'text': 'ime', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117') AIMessageChunk(content=[{'text': ' la', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117') AIMessageChunk(content=[{'text': ' programm', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117') AIMessageChunk(content=[{'text': 'ation', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117') AIMessageChunk(content=[{'text': '.', 'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117') AIMessageChunk(content=[{'index': 0}], id='run-da3c2606-4792-440a-ac66-72e0d1f6d117') AIMessageChunk(content=[], response_metadata={'stopReason': 'end_turn'}, id='run-da3c2606-4792-440a-ac66-72e0d1f6d117') AIMessageChunk(content=[], response_metadata={'metrics': {'latencyMs': 581}}, id='run-da3c2606-4792-440a-ac66-72e0d1f6d117', usage_metadata={'input_tokens': 25, 'output_tokens': 11, 'total_tokens': 36}) Tool calling
from pydantic import BaseModel, Field class GetWeather(BaseModel): '''Get the current weather in a given location''' location: str = Field(..., description="The city and state, e.g. San Francisco, CA") class GetPopulation(BaseModel): '''Get the current population in a given location''' location: str = Field(..., description="The city and state, e.g. San Francisco, CA") model_with_tools = model.bind_tools([GetWeather, GetPopulation]) ai_msg = model_with_tools.invoke("Which city is hotter today and which is bigger: LA or NY?") ai_msg.tool_calls [{'name': 'GetWeather', 'args': {'location': 'Los Angeles, CA'}, 'id': 'tooluse_Mspi2igUTQygp-xbX6XGVw'}, {'name': 'GetWeather', 'args': {'location': 'New York, NY'}, 'id': 'tooluse_tOPHiDhvR2m0xF5_5tyqWg'}, {'name': 'GetPopulation', 'args': {'location': 'Los Angeles, CA'}, 'id': 'tooluse__gcY_klbSC-GqB-bF_pxNg'}, {'name': 'GetPopulation', 'args': {'location': 'New York, NY'}, 'id': 'tooluse_-1HSoGX0TQCSaIg7cdFy8Q'}] See ChatBedrockConverse.bind_tools() method for more.
Structured output
from typing import Optional from pydantic import BaseModel, Field class Joke(BaseModel): '''Joke to tell user.''' setup: str = Field(description="The setup of the joke") punchline: str = Field(description="The punchline to the joke") rating: Optional[int] = Field(description="How funny the joke is, from 1 to 10") structured_model = model.with_structured_output(Joke) structured_model.invoke("Tell me a joke about cats") Joke(setup='What do you call a cat that gets all dressed up?', punchline='A purrfessional!', rating=7) See ChatBedrockConverse.with_structured_output() for more.
Extended thinking
Some models, such as Claude 3.7 Sonnet, support an extended thinking feature that outputs the step-by-step reasoning process that led to an answer.
To use it, specify the thinking parameter when initializing ChatBedrockConverse as shown below.
You will need to specify a token budget to use this feature. See usage example:
from langchain_aws import ChatBedrockConverse thinking_params= { "thinking": { "type": "enabled", "budget_tokens": 2000 } } model = ChatBedrockConverse( model="us.anthropic.claude-3-7-sonnet-20250219-v1:0", max_tokens=5000, region_name="us-west-2", additional_model_request_fields=thinking_params, ) response = model.invoke("What is the cube root of 50.653?") print(response.content) Image input
import base64 import httpx from langchain_core.messages import HumanMessage image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg" image_data = base64.b64encode(httpx.get(image_url).content).decode("utf-8") message = HumanMessage( content=[ {"type": "text", "text": "describe the weather in this image"}, { "type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": image_data}, }, ], ) ai_msg = model.invoke([message]) ai_msg.content [{'type': 'text', 'text': 'The image depicts a sunny day with a partly cloudy sky. The sky is a brilliant blue color with scattered white clouds drifting across. The lighting and cloud patterns suggest pleasant, mild weather conditions. The scene shows an open grassy field or meadow, indicating warm temperatures conducive for vegetation growth. Overall, the weather portrayed in this scenic outdoor image appears to be sunny with some clouds, likely representing a nice, comfortable day.'}] Token usage
Response metadata
```python {'ResponseMetadata': {'RequestId': '776a2a26-5946-45ae-859e-82dc5f12017c', 'HTTPStatusCode': 200, 'HTTPHeaders': {'date': 'Mon, 17 Jun 2024 01:37:05 GMT', 'content-type': 'application/json', 'content-length': '206', 'connection': 'keep-alive', 'x-amzn-requestid': '776a2a26-5946-45ae-859e-82dc5f12017c'}, 'RetryAttempts': 0}, 'stopReason': 'end_turn', 'metrics': {'latencyMs': 1290}} ``` | METHOD | DESCRIPTION |
|---|---|
get_name | Get the name of the |
get_input_schema | Get a Pydantic model that can be used to validate input to the |
get_input_jsonschema | Get a JSON schema that represents the input to the |
get_output_schema | Get a Pydantic model that can be used to validate output to the |
get_output_jsonschema | Get a JSON schema that represents the output of the |
config_schema | The type of config this |
get_config_jsonschema | Get a JSON schema that represents the config of the |
get_graph | Return a graph representation of this |
get_prompts | Return a list of prompts used by this |
__or__ | Runnable "or" operator. |
__ror__ | Runnable "reverse-or" operator. |
pipe | Pipe |
pick | Pick keys from the output |
assign | Assigns new fields to the |
invoke | Transform a single input into an output. |
ainvoke | Transform a single input into an output. |
batch | Default implementation runs invoke in parallel using a thread pool executor. |
batch_as_completed | Run |
abatch | Default implementation runs |
abatch_as_completed | Run |
stream | Default implementation of |
astream | Default implementation of |
astream_log | Stream all output from a |
astream_events | Generate a stream of events. |
transform | Transform inputs to outputs. |
atransform | Transform inputs to outputs. |
bind | Bind arguments to a |
with_config | Bind config to a |
with_listeners | Bind lifecycle listeners to a |
with_alisteners | Bind async lifecycle listeners to a |
with_types | Bind input and output types to a |
with_retry | Create a new |
map | Return a new |
with_fallbacks | Add fallbacks to a |
as_tool | Create a |
__init__ | |
lc_id | Return a unique identifier for this class for serialization purposes. |
to_json | Serialize the |
to_json_not_implemented | Serialize a "not implemented" object. |
configurable_fields | Configure particular |
configurable_alternatives | Configure alternatives for |
set_verbose | If verbose is |
generate_prompt | Pass a sequence of prompts to the model and return model generations. |
agenerate_prompt | Asynchronously pass a sequence of prompts and return model generations. |
get_token_ids | Return the ordered IDs of the tokens in a text. |
get_num_tokens | Get the number of tokens present in the text. |
generate | Pass a sequence of prompts to the model and return model generations. |
agenerate | Asynchronously pass a sequence of prompts to a model and return generations. |
dict | Return a dictionary of the LLM. |
create_cache_point | Create a prompt caching configuration for Bedrock. |
build_extra | Build extra kwargs from additional params that were passed in. |
validate_environment | Validate that AWS credentials to and python package exists in environment. |
bind_tools | Bind tools to the model. |
with_structured_output | Model wrapper that returns outputs formatted to match the given schema. |
is_lc_serializable | Is this class serializable? |
get_lc_namespace | Get the namespace of the LangChain object. |
get_num_tokens_from_messages | Get the number of tokens in the messages using AWS Bedrock count_tokens API. |
class-attribute instance-attribute ¶
name: str | None = None The name of the Runnable. Used for debugging and tracing.
property ¶
The type of input this Runnable accepts specified as a Pydantic model.
property ¶
Output schema.
The type of output this Runnable produces specified as a Pydantic model.
property ¶
config_specs: list[ConfigurableFieldSpec] List configurable fields for this Runnable.
property ¶
lc_attributes: dict List of attribute names that should be included in the serialized kwargs.
These attributes must be accepted by the constructor.
Default is an empty dictionary.
class-attribute instance-attribute ¶
Whether to cache the response.
- If
True, will use the global cache. - If
False, will not use a cache - If
None, will use the global cache if it's set, otherwise no cache. - If instance of
BaseCache, will use the provided cache.
Caching is not currently supported for streaming methods of models.
class-attribute instance-attribute ¶
Whether to print out response text.
class-attribute instance-attribute ¶
callbacks: Callbacks = Field(default=None, exclude=True) Callbacks to add to the run trace.
class-attribute instance-attribute ¶
Tags to add to the run trace.
class-attribute instance-attribute ¶
Metadata to add to the run trace.
class-attribute instance-attribute ¶
Optional encoder to use for counting tokens.
class-attribute instance-attribute ¶
rate_limiter: BaseRateLimiter | None = Field(default=None, exclude=True) An optional rate limiter to use for limiting the number of requests.
class-attribute instance-attribute ¶
Whether to disable streaming for this model.
If streaming is bypassed, then stream/astream/astream_events will defer to invoke/ainvoke.
- If
True, will always bypass streaming case. - If
'tool_calling', will bypass streaming case only when the model is called with atoolskeyword argument. In other words, LangChain will automatically switch to non-streaming behavior (invoke) only when the tools argument is provided. This offers the best of both worlds. - If
False(Default), will always use streaming case if available.
The main reason for this flag is that code might be written using stream and a user may want to swap out a given model for another model whose the implementation does not properly support streaming.
class-attribute instance-attribute ¶
Version of AIMessage output format to store in message content.
AIMessage.content_blocks will lazily parse the contents of content into a standard format. This flag can be used to additionally store the standard format in message content, e.g., for serialization purposes.
Supported values:
'v0': provider-specific format in content (can lazily-parse withcontent_blocks)'v1': standardized format in content (consistent withcontent_blocks)
Partner packages (e.g., langchain-openai) can also use this field to roll out new content formats in a backward-compatible way.
Added in langchain-core 1.0
class-attribute instance-attribute ¶
profile: ModelProfile | None = Field(default=None, exclude=True) Profile detailing model capabilities.
Beta feature
This is a beta feature. The format of model profiles is subject to change.
If not specified, automatically loaded from the provider package on initialization if data is available.
Example profile data includes context window sizes, supported modalities, or support for tool calling, structured output, and other features.
Added in langchain-core 1.1
class-attribute instance-attribute ¶
The bedrock runtime client for making data plane API calls
class-attribute instance-attribute ¶
The bedrock client for making control plane API calls
class-attribute instance-attribute ¶
ID of the model to call.
e.g., "anthropic.claude-3-sonnet-20240229-v1:0". This is equivalent to the modelID property in the list-foundation-models api. For custom and provisioned models, an ARN value is expected. See https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html#model-ids-arns for a list of all supported built-in models.
class-attribute instance-attribute ¶
An optional field to pass the base model id. If provided, this will be used over the value of model_id to identify the base model.
class-attribute instance-attribute ¶
Optional list of system prompts for the LLM.
Each entry can be either
- a simple string (for straightforward text-based system prompts), or
- a dictionary matching the Converse API system message schema, allowing inclusion of additional fields like
guardContent,cachePoint, etc.
Example
system = [ "a simple system prompt", { "text": "another system prompt", "guardContent": {"text": {"text": "string"}}, "cachePoint": {"type": "default"} }, ]
String inputs will be internally converted to the appropriate message format, while dict entries will be passed through as-is. Any invalid formats will be rejected by the Converse API.
class-attribute instance-attribute ¶
max_tokens: int | None = None Max tokens to generate.
class-attribute instance-attribute ¶
Stop generation if any of these substrings occurs.
class-attribute instance-attribute ¶
temperature: float | None = None Sampling temperature. Must be 0 to 1.
class-attribute instance-attribute ¶
top_p: float | None = None The percentage of most-likely candidates that are considered for the next token.
Must be 0 to 1.
For example, if you choose a value of 0.8 for topP, the model selects from the top 80% of the probability distribution of tokens that could be next in the sequence.
class-attribute instance-attribute ¶
region_name: str | None = None The aws region, e.g., us-west-2.
Falls back to AWS_REGION or AWS_DEFAULT_REGION env variable or region specified in ~/.aws/config in case it is not provided here.
class-attribute instance-attribute ¶
The name of the profile in the ~/.aws/credentials or ~/.aws/config files.
Profile should either have access keys or role information specified. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
class-attribute instance-attribute ¶
aws_access_key_id: SecretStr | None = Field( default_factory=secret_from_env("AWS_ACCESS_KEY_ID", default=None) ) AWS access key id.
If provided, aws_secret_access_key must also be provided. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from 'AWS_ACCESS_KEY_ID' environment variable.
class-attribute instance-attribute ¶
aws_secret_access_key: SecretStr | None = Field( default_factory=secret_from_env("AWS_SECRET_ACCESS_KEY", default=None) ) AWS secret_access_key.
If provided, aws_access_key_id must also be provided. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from 'AWS_SECRET_ACCESS_KEY' environment variable.
class-attribute instance-attribute ¶
aws_session_token: SecretStr | None = Field( default_factory=secret_from_env("AWS_SESSION_TOKEN", default=None) ) AWS session token.
If provided, aws_access_key_id and aws_secret_access_key must also be provided. Not required unless using temporary credentials. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from 'AWS_SESSION_TOKEN' environment variable.
class-attribute instance-attribute ¶
provider: str = '' The model provider, e.g., amazon, cohere, ai21, etc.
When not supplied, provider is extracted from the first part of the model_id, e.g. 'amazon' in 'amazon.titan-text-express-v1'. This value should be provided for model IDs that do not have the provider in them, like custom and provisioned models that have an ARN associated with them.
class-attribute instance-attribute ¶
Needed if you don't want to default to us-east-1 endpoint
class-attribute instance-attribute ¶
config: Any = None An optional botocore.config.Config instance to pass to the client.
class-attribute instance-attribute ¶
Configuration information for a guardrail that you want to use in the request.
class-attribute instance-attribute ¶
Additional inference parameters that the model supports.
Parameters beyond the base set of inference parameters that Converse supports in the inferenceConfig field.
class-attribute instance-attribute ¶
Additional model parameters field paths to return in the response.
Converse returns the requested fields as a JSON Pointer object in the additionalModelResponseFields field. The following is example JSON for additionalModelResponseFieldPaths.
class-attribute instance-attribute ¶
Which types of tool_choice values the model supports.
Inferred if not specified. Inferred as ('auto', 'any', 'tool') if a 'claude-3' model is used, ('auto', 'any') if a 'mistral-large' model is used, ('auto') if a 'nova' model is used, empty otherwise.
class-attribute instance-attribute ¶
Key-Value pairs that you can use to filter invocation logs.
class-attribute instance-attribute ¶
guard_last_turn_only: bool = False Boolean flag for applying the guardrail to only the last turn.
class-attribute instance-attribute ¶
Raw Bedrock message blocks that can be passed in.
LangChain will relay them unchanged, enabling any combination of content block types. This is useful for custom guardrail wrapping.
property ¶
A map of constructor argument names to secret ids.
For example, {"openai_api_key": "OPENAI_API_KEY"}
get_input_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate input to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate input. |
get_input_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the input to the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the input to the |
Example
Added in langchain-core 0.3.0
get_output_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate output to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate output. |
get_output_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the output of the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the output of the |
Example
Added in langchain-core 0.3.0
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.
| PARAMETER | DESCRIPTION |
|---|---|
include | A list of fields to include in the config schema. |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate config. |
get_graph(config: RunnableConfig | None = None) -> Graph Return a graph representation of this Runnable.
get_prompts(config: RunnableConfig | None = None) -> list[BasePromptTemplate] Return a list of prompts used by this Runnable.
__or__( other: Runnable[Any, Other] | Callable[[Iterator[Any]], Iterator[Other]] | Callable[[AsyncIterator[Any]], AsyncIterator[Other]] | Callable[[Any], Other] | Mapping[str, Runnable[Any, Other] | Callable[[Any], Other] | Any], ) -> RunnableSerializable[Input, Other] Runnable "or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
__ror__( other: Runnable[Other, Any] | Callable[[Iterator[Other]], Iterator[Any]] | Callable[[AsyncIterator[Other]], AsyncIterator[Any]] | Callable[[Other], Any] | Mapping[str, Runnable[Other, Any] | Callable[[Other], Any] | Any], ) -> RunnableSerializable[Other, Output] Runnable "reverse-or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Other, Output] | A new |
pipe( *others: Runnable[Any, Other] | Callable[[Any], Other], name: str | None = None ) -> RunnableSerializable[Input, Other] Pipe Runnable objects.
Compose this Runnable with Runnable-like objects to make a RunnableSequence.
Equivalent to RunnableSequence(self, *others) or self | others[0] | ...
Example
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] | PARAMETER | DESCRIPTION |
|---|---|
*others | Other TYPE: |
name | An optional name for the resulting TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
Pick keys from the output dict of this Runnable.
Pick a single key
import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) chain = RunnableMap(str=as_str, json=as_json) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3]} json_only_chain = chain.pick("json") json_only_chain.invoke("[1, 2, 3]") # -> [1, 2, 3] Pick a list of keys
from typing import Any import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) def as_bytes(x: Any) -> bytes: return bytes(x, "utf-8") chain = RunnableMap( str=as_str, json=as_json, bytes=RunnableLambda(as_bytes) ) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3], "bytes": b"[1, 2, 3]"} json_and_bytes_chain = chain.pick(["json", "bytes"]) json_and_bytes_chain.invoke("[1, 2, 3]") # -> {"json": [1, 2, 3], "bytes": b"[1, 2, 3]"} | PARAMETER | DESCRIPTION |
|---|---|
keys | A key or list of keys to pick from the output dict. |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | a new |
assign( **kwargs: Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any] | Mapping[str, Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any]], ) -> RunnableSerializable[Any, Any] Assigns new fields to the dict output of this Runnable.
from langchain_core.language_models.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}" ) model = FakeStreamingListLLM(responses=["foo-lish"]) chain: Runnable = prompt | model | {"str": StrOutputParser()} chain_with_assign = chain.assign(hello=itemgetter("str") | model) print(chain_with_assign.input_schema.model_json_schema()) # {'title': 'PromptInput', 'type': 'object', 'properties': {'question': {'title': 'Question', 'type': 'string'}}} print(chain_with_assign.output_schema.model_json_schema()) # {'title': 'RunnableSequenceOutput', 'type': 'object', 'properties': {'str': {'title': 'Str', 'type': 'string'}, 'hello': {'title': 'Hello', 'type': 'string'}}} | PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A mapping of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | A new |
invoke( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> AIMessage Transform a single input into an output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
ainvoke( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> AIMessage Transform a single input into an output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Output | The output of the |
batch( inputs: list[Input], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> 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 must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
batch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> Iterator[tuple[int, Output | Exception]] Run invoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
tuple[int, Output | Exception] | Tuples of the index of the input and the output from the |
async ¶
abatch( inputs: list[Input], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> list[Output] Default implementation runs ainvoke in parallel using asyncio.gather.
The default implementation of batch works well for IO bound runnables.
Subclasses must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
async ¶
abatch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> AsyncIterator[tuple[int, Output | Exception]] Run ainvoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[tuple[int, Output | Exception]] | A tuple of the index of the input and the output from the |
stream( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> Iterator[AIMessageChunk] Default implementation of stream, which calls invoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
astream( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> AsyncIterator[AIMessageChunk] Default implementation of astream, which calls ainvoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
async ¶
astream_log( input: Any, config: RunnableConfig | None = None, *, diff: bool = True, with_streamed_output_list: bool = True, include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> 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.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
diff | Whether to yield diffs between each step or the current state. TYPE: |
with_streamed_output_list | Whether to yield the TYPE: |
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 TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[RunLogPatch] | AsyncIterator[RunLog] | A |
async ¶
astream_events( input: Any, config: RunnableConfig | None = None, *, version: Literal["v1", "v2"] = "v2", include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> AsyncIterator[StreamEvent] Generate a stream of events.
Use to create an iterator over StreamEvent that provide real-time information about the progress of the Runnable, including StreamEvent from intermediate results.
A StreamEvent is a dictionary with the following schema:
event: Event names are of the format:on_[runnable_type]_(start|stream|end).name: The name of theRunnablethat generated the event.run_id: Randomly generated ID associated with the given execution of theRunnablethat emitted the event. A childRunnablethat gets invoked as part of the execution of a parentRunnableis assigned its own unique ID.parent_ids: The IDs of the parent runnables that generated the event. The rootRunnablewill 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: The tags of theRunnablethat generated the event.metadata: The metadata of theRunnablethat generated the event.data: The data associated with the event. The contents of this field depend on the type of event. See the table below for more details.
Below is a table that illustrates some events 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.
Note
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:
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:
prompt:
template = ChatPromptTemplate.from_messages( [ ("system", "You are Cat Agent 007"), ("human", "{question}"), ] ).with_config({"run_name": "my_template", "tags": ["my_template"]}) Example
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": [], }, ] 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) | PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
version | The version of the schema to use, either Users should use
No default will be assigned until the API is stabilized. custom events will only be surfaced in TYPE: |
include_names | Only include events from |
include_types | Only include events from |
include_tags | Only include events from |
exclude_names | Exclude events from |
exclude_types | Exclude events from |
exclude_tags | Exclude events from |
**kwargs | Additional keyword arguments to pass to the These will be passed to TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[StreamEvent] | An async stream of |
| RAISES | DESCRIPTION |
|---|---|
NotImplementedError | If the version is not |
transform( input: Iterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None ) -> Iterator[Output] Transform inputs to outputs.
Default implementation of transform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
atransform( input: AsyncIterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None, ) -> AsyncIterator[Output] Transform inputs to outputs.
Default implementation of atransform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An async iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
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.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | The arguments to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_ollama import ChatOllama from langchain_core.output_parsers import StrOutputParser model = ChatOllama(model="llama3.1") # Without bind chain = model | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two three four five.' # With bind chain = model.bind(stop=["three"]) | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two'
with_config( config: RunnableConfig | None = None, **kwargs: Any ) -> Runnable[Input, Output] Bind config to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | The config to bind to the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_listeners( *, on_start: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_end: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_error: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, ) -> Runnable[Input, Output] Bind lifecycle listeners to a Runnable, returning a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called before the TYPE: |
on_end | Called after the TYPE: |
on_error | Called if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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)
with_alisteners( *, on_start: AsyncListener | None = None, on_end: AsyncListener | None = None, on_error: AsyncListener | None = None, ) -> Runnable[Input, Output] Bind async lifecycle listeners to a Runnable.
Returns a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called asynchronously before the TYPE: |
on_end | Called asynchronously after the TYPE: |
on_error | Called asynchronously if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_core.runnables import RunnableLambda, Runnable from datetime import datetime, timezone import time import asyncio def format_t(timestamp: float) -> str: return datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat() 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 2025-03-01T07:05:22.875378+00:00 # on start callback starts at 2025-03-01T07:05:22.875495+00:00 # on start callback ends at 2025-03-01T07:05:25.878862+00:00 # on start callback ends at 2025-03-01T07:05:25.878947+00:00 # Runnable[2s]: starts at 2025-03-01T07:05:25.879392+00:00 # Runnable[3s]: starts at 2025-03-01T07:05:25.879804+00:00 # Runnable[2s]: ends at 2025-03-01T07:05:27.881998+00:00 # on end callback starts at 2025-03-01T07:05:27.882360+00:00 # Runnable[3s]: ends at 2025-03-01T07:05:28.881737+00:00 # on end callback starts at 2025-03-01T07:05:28.882428+00:00 # on end callback ends at 2025-03-01T07:05:29.883893+00:00 # on end callback ends at 2025-03-01T07:05:30.884831+00:00
with_types( *, input_type: type[Input] | None = None, output_type: type[Output] | None = None ) -> Runnable[Input, Output] Bind input and output types to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
input_type | The input type to bind to the TYPE: |
output_type | The output type to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_retry( *, retry_if_exception_type: tuple[type[BaseException], ...] = (Exception,), wait_exponential_jitter: bool = True, exponential_jitter_params: ExponentialJitterParams | None = None, stop_after_attempt: int = 3, ) -> Runnable[Input, Output] Create a new Runnable that retries the original Runnable on exceptions.
| PARAMETER | DESCRIPTION |
|---|---|
retry_if_exception_type | A tuple of exception types to retry on. TYPE: |
wait_exponential_jitter | Whether to add jitter to the wait time between retries. TYPE: |
stop_after_attempt | The maximum number of attempts to make before giving up. TYPE: |
exponential_jitter_params | Parameters for TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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
with_fallbacks( fallbacks: Sequence[Runnable[Input, Output]], *, exceptions_to_handle: tuple[type[BaseException], ...] = (Exception,), exception_key: str | None = None, ) -> RunnableWithFallbacks[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.
| PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
Example
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 | PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
as_tool( args_schema: type[BaseModel] | None = None, *, name: str | None = None, description: str | None = None, arg_types: dict[str, type] | None = 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.
| PARAMETER | DESCRIPTION |
|---|---|
args_schema | The schema for the tool. |
name | The name of the tool. TYPE: |
description | The description of the tool. TYPE: |
arg_types | A dictionary of argument names to types. |
| RETURNS | DESCRIPTION |
|---|---|
BaseTool | A |
TypedDict input
dict input, specifying schema via args_schema
from typing import Any from pydantic 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
classmethod ¶
Return a unique identifier for this class for serialization purposes.
The unique identifier is a list of strings that describes the path to the object.
For example, for the class langchain.llms.openai.OpenAI, the id is ["langchain", "llms", "openai", "OpenAI"].
Serialize the Runnable to JSON.
| RETURNS | DESCRIPTION |
|---|---|
SerializedConstructor | SerializedNotImplemented | A JSON-serializable representation of the |
Serialize a "not implemented" object.
| RETURNS | DESCRIPTION |
|---|---|
SerializedNotImplemented |
|
configurable_fields( **kwargs: AnyConfigurableField, ) -> RunnableSerializable[Input, Output] Configure particular Runnable fields at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A dictionary of TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If a configuration key is not found in the |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
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, )
configurable_alternatives( which: ConfigurableField, *, default_key: str = "default", prefix_keys: bool = False, **kwargs: Runnable[Input, Output] | Callable[[], Runnable[Input, Output]], ) -> RunnableSerializable[Input, Output] Configure alternatives for Runnable objects that can be set at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
which | The TYPE: |
default_key | The default key to use if no alternative is selected. TYPE: |
prefix_keys | Whether to prefix the keys with the TYPE: |
**kwargs | A dictionary of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
from langchain_anthropic import ChatAnthropic from langchain_core.runnables.utils import ConfigurableField from langchain_openai import ChatOpenAI model = ChatAnthropic( model_name="claude-sonnet-4-5-20250929" ).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 )
generate_prompt( prompts: list[PromptValue], stop: list[str] | None = None, callbacks: Callbacks = None, **kwargs: Any, ) -> LLMResult Pass a sequence of prompts to the model and return model generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
prompts | List of A TYPE: |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
async ¶
agenerate_prompt( prompts: list[PromptValue], stop: list[str] | None = None, callbacks: Callbacks = None, **kwargs: Any, ) -> LLMResult Asynchronously pass a sequence of prompts and return model generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
prompts | List of A TYPE: |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
Get the number of tokens present in the text.
Useful for checking if an input fits in a model's context window.
This should be overridden by model-specific implementations to provide accurate token counts via model-specific tokenizers.
| PARAMETER | DESCRIPTION |
|---|---|
text | The string input to tokenize. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
int | The integer number of tokens in the text. |
generate( messages: list[list[BaseMessage]], stop: list[str] | None = None, callbacks: Callbacks = None, *, tags: list[str] | None = None, metadata: dict[str, Any] | None = None, run_name: str | None = None, run_id: UUID | None = None, **kwargs: Any, ) -> LLMResult Pass a sequence of prompts to the model and return model generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
messages | List of list of messages. TYPE: |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
tags | The tags to apply. |
metadata | The metadata to apply. |
run_name | The name of the run. TYPE: |
run_id | The ID of the run. TYPE: |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
async ¶
agenerate( messages: list[list[BaseMessage]], stop: list[str] | None = None, callbacks: Callbacks = None, *, tags: list[str] | None = None, metadata: dict[str, Any] | None = None, run_name: str | None = None, run_id: UUID | None = None, **kwargs: Any, ) -> LLMResult Asynchronously pass a sequence of prompts to a model and return generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
messages | List of list of messages. TYPE: |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
tags | The tags to apply. |
metadata | The metadata to apply. |
run_name | The name of the run. TYPE: |
run_id | The ID of the run. TYPE: |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
classmethod ¶
Create a prompt caching configuration for Bedrock. Args: cache_type: Type of cache point. Default is "default". Returns: Dictionary containing prompt caching configuration.
classmethod ¶
Build extra kwargs from additional params that were passed in.
validate_environment() -> Self Validate that AWS credentials to and python package exists in environment.
bind_tools( tools: Sequence[dict[str, Any] | TypeBaseModel | Callable | BaseTool], *, tool_choice: dict | str | Literal["auto", "any"] | None = None, **kwargs: Any, ) -> Runnable[LanguageModelInput, AIMessage] Bind tools to the model.
| PARAMETER | DESCRIPTION |
|---|---|
tools | Sequence of tools to bind to the model. |
tool_choice | The tool to use. If "any" then any tool can be used. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[LanguageModelInput, AIMessage] | A Runnable that returns a message. |
with_structured_output( schema: _DictOrPydanticClass, *, include_raw: bool = False, **kwargs: Any ) -> Runnable[LanguageModelInput, dict | BaseModel] Model wrapper that returns outputs formatted to match the given schema.
| PARAMETER | DESCRIPTION |
|---|---|
schema | The output schema. Can be passed in as:
If See |
include_raw | If If an error occurs during model output parsing it will be raised. If If an error occurs during output parsing it will be caught and returned as well. The final output is always a TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If there are any unsupported |
NotImplementedError | If the model does not implement |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[LanguageModelInput, Dict | BaseModel] | A If
|
Example: Pydantic schema (include_raw=False):
from pydantic import BaseModel class AnswerWithJustification(BaseModel): '''An answer to the user question along with justification for the answer.''' answer: str justification: str model = ChatModel(model="model-name", temperature=0) structured_model = model.with_structured_output(AnswerWithJustification) structured_model.invoke( "What weighs more a pound of bricks or a pound of feathers" ) # -> AnswerWithJustification( # answer='They weigh the same', # justification='Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.' # ) Example: Pydantic schema (include_raw=True):
from pydantic import BaseModel class AnswerWithJustification(BaseModel): '''An answer to the user question along with justification for the answer.''' answer: str justification: str model = ChatModel(model="model-name", temperature=0) structured_model = model.with_structured_output( AnswerWithJustification, include_raw=True ) structured_model.invoke( "What weighs more a pound of bricks or a pound of feathers" ) # -> { # 'raw': AIMessage(content='', additional_kwargs={'tool_calls': [{'id': 'call_Ao02pnFYXD6GN1yzc0uXPsvF', 'function': {'arguments': '{"answer":"They weigh the same.","justification":"Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ."}', 'name': 'AnswerWithJustification'}, 'type': 'function'}]}), # 'parsed': AnswerWithJustification(answer='They weigh the same.', justification='Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume or density of the objects may differ.'), # 'parsing_error': None # } Example: dict schema (include_raw=False):
from pydantic import BaseModel from langchain_core.utils.function_calling import convert_to_openai_tool class AnswerWithJustification(BaseModel): '''An answer to the user question along with justification for the answer.''' answer: str justification: str dict_schema = convert_to_openai_tool(AnswerWithJustification) model = ChatModel(model="model-name", temperature=0) structured_model = model.with_structured_output(dict_schema) structured_model.invoke( "What weighs more a pound of bricks or a pound of feathers" ) # -> { # 'answer': 'They weigh the same', # 'justification': 'Both a pound of bricks and a pound of feathers weigh one pound. The weight is the same, but the volume and density of the two substances differ.' # } Behavior changed in langchain-core 0.2.26
Added support for TypedDict class.
classmethod ¶
is_lc_serializable() -> bool Is this class serializable?
By design, even if a class inherits from Serializable, it is not serializable by default. This is to prevent accidental serialization of objects that should not be serialized.
| RETURNS | DESCRIPTION |
|---|---|
bool | Whether the class is serializable. Default is |
classmethod ¶
get_num_tokens_from_messages( messages: list[BaseMessage], tools: Sequence | None = None ) -> int Get the number of tokens in the messages using AWS Bedrock count_tokens API.
This method uses AWS Bedrock's count_tokens API which provides accurate token counting for supported models before inference. Falls back to the base implementation for unsupported models.
| PARAMETER | DESCRIPTION |
|---|---|
messages | The message inputs to tokenize. TYPE: |
tools | Tool schemas (ignored, unsupported by count_tokens API). TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
int | The number of input tokens in the messages. |
Bases: BaseDocumentCompressor
Document compressor that uses AWS Bedrock Rerank API.
| METHOD | DESCRIPTION |
|---|---|
acompress_documents | Async compress retrieved documents given the query context. |
initialize_client | Initialize the AWS Bedrock client. |
rerank | Returns an ordered list of documents based on their relevance to the query. |
compress_documents | Compress documents using Bedrock's rerank API. |
class-attribute instance-attribute ¶
Bedrock client to use for compressing documents.
class-attribute instance-attribute ¶
region_name: str | None = None The aws region, e.g., us-west-2.
Falls back to AWS_REGION or AWS_DEFAULT_REGION env variable or region specified in ~/.aws/config in case it is not provided here.
class-attribute instance-attribute ¶
credentials_profile_name: str | None = Field( default_factory=from_env("AWS_PROFILE", default=None) ) AWS profile for authentication, optional.
class-attribute instance-attribute ¶
aws_access_key_id: SecretStr | None = Field( default_factory=secret_from_env("AWS_ACCESS_KEY_ID", default=None) ) AWS access key id.
If provided, aws_secret_access_key must also be provided. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_ACCESS_KEY_ID environment variable.
class-attribute instance-attribute ¶
aws_secret_access_key: SecretStr | None = Field( default_factory=secret_from_env("AWS_SECRET_ACCESS_KEY", default=None) ) AWS secret_access_key.
If provided, aws_access_key_id must also be provided. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_SECRET_ACCESS_KEY environment variable.
class-attribute instance-attribute ¶
aws_session_token: SecretStr | None = Field( default_factory=secret_from_env("AWS_SESSION_TOKEN", default=None) ) AWS session token.
If provided, aws_access_key_id and aws_secret_access_key must also be provided. Not required unless using temporary credentials.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_SESSION_TOKEN environment variable.
class-attribute instance-attribute ¶
Needed if you don't want to default to us-east-1 endpoint
class-attribute instance-attribute ¶
config: Any = None An optional botocore.config.Config instance to pass to the client.
async ¶
acompress_documents( documents: Sequence[Document], query: str, callbacks: Callbacks | None = None ) -> Sequence[Document] Async compress retrieved documents given the query context.
| PARAMETER | DESCRIPTION |
|---|---|
documents | The retrieved |
query | The query context. TYPE: |
callbacks | Optional TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Sequence[Document] | The compressed documents. |
classmethod ¶
Initialize the AWS Bedrock client.
rerank( documents: Sequence[str | Document | dict], query: str, top_n: int | None = None, additional_model_request_fields: dict[str, Any] | None = None, ) -> list[dict[str, Any]] Returns an ordered list of documents based on their relevance to the query.
| PARAMETER | DESCRIPTION |
|---|---|
query | The query to use for reranking. TYPE: |
documents | A sequence of documents to rerank. |
top_n | The number of top-ranked results to return. Defaults to self.top_n. TYPE: |
additional_model_request_fields | Additional fields to pass to the model. |
| RETURNS | DESCRIPTION |
|---|---|
list[dict[str, Any]] | A list of ranked documents with relevance scores. |
compress_documents( documents: Sequence[Document], query: str, callbacks: Callbacks | None = None ) -> Sequence[Document] Compress documents using Bedrock's rerank API.
| PARAMETER | DESCRIPTION |
|---|---|
documents | A sequence of documents to compress. |
query | The query to use for compressing the documents. TYPE: |
callbacks | Callbacks to run during the compression process. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Sequence[Document] | A sequence of compressed documents. |
Bases: BaseModel, Embeddings
Bedrock embedding models.
To authenticate, the AWS client uses the following methods to automatically load credentials: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If a specific credential profile should be used, you must pass the name of the profile from the ~/.aws/credentials file that is to be used.
Make sure the credentials / roles used have the required policies to access the Bedrock service.
| METHOD | DESCRIPTION |
|---|---|
validate_environment | Validate that AWS credentials to and python package exists in environment. |
embed_documents | Compute doc embeddings using a Bedrock model. |
embed_query | Compute query embeddings using a Bedrock model. |
aembed_query | Asynchronous compute query embeddings using a Bedrock model. |
aembed_documents | Asynchronous compute doc embeddings using a Bedrock model. |
class-attribute instance-attribute ¶
Bedrock client.
class-attribute instance-attribute ¶
region_name: str | None = None The aws region e.g., us-west-2.
Falls back to AWS_REGION/AWS_DEFAULT_REGION env variable or region specified in ~/.aws/config in case it is not provided here.
class-attribute instance-attribute ¶
credentials_profile_name: str | None = None The name of the profile in the ~/.aws/credentials or ~/.aws/config files, which has either access keys or role information specified. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
class-attribute instance-attribute ¶
aws_access_key_id: SecretStr | None = Field( default_factory=secret_from_env("AWS_ACCESS_KEY_ID", default=None) ) AWS access key id.
If provided, aws_secret_access_key must also be provided. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_ACCESS_KEY_ID environment variable.
class-attribute instance-attribute ¶
aws_secret_access_key: SecretStr | None = Field( default_factory=secret_from_env("AWS_SECRET_ACCESS_KEY", default=None) ) AWS secret_access_key.
If provided, aws_access_key_id must also be provided. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_SECRET_ACCESS_KEY environment variable.
class-attribute instance-attribute ¶
aws_session_token: SecretStr | None = Field( default_factory=secret_from_env("AWS_SESSION_TOKEN", default=None) ) AWS session token.
If provided, aws_access_key_id and aws_secret_access_key must also be provided.
Not required unless using temporary credentials.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_SESSION_TOKEN environment variable.
class-attribute instance-attribute ¶
model_id: str = 'amazon.titan-embed-text-v1' Id of the model to call, e.g., 'amazon.titan-embed-text-v1', this is equivalent to the modelId property in the list-foundation-models api
class-attribute instance-attribute ¶
model_kwargs: dict | None = None Keyword arguments to pass to the model.
class-attribute instance-attribute ¶
provider: str | None = None Name of the provider, e.g., amazon, cohere, etc.. If not specified, the provider will be inferred from the model_id.
class-attribute instance-attribute ¶
endpoint_url: str | None = None Needed if you don't want to default to 'us-east-1' endpoint
class-attribute instance-attribute ¶
normalize: bool = False Whether the embeddings should be normalized to unit vectors
class-attribute instance-attribute ¶
config: Any = None An optional botocore.config.Config instance to pass to the client.
validate_environment() -> Self Validate that AWS credentials to and python package exists in environment.
async ¶
Bases: BaseNeptuneGraph
Neptune Analytics wrapper for graph operations.
| PARAMETER | DESCRIPTION |
|---|---|
client | optional boto3 Neptune client TYPE: |
credentials_profile_name | optional AWS profile name TYPE: |
region_name | optional AWS region, e.g., us-west-2 TYPE: |
graph_identifier | the graph identifier for a Neptune Analytics graph TYPE: |
Security note: Make sure that the database connection uses credentials that are narrowly-scoped to only include necessary permissions. Failure to do so may result in data corruption or loss, since the calling code may attempt commands that would result in deletion, mutation of data if appropriately prompted or reading sensitive data if such data is present in the database. The best way to guard against such negative outcomes is to (as appropriate) limit the permissions granted to the credentials used with this tool.
See https://docs.langchain.com/oss/python/security-policy for more information. | METHOD | DESCRIPTION |
|---|---|
__init__ | Create a new Neptune Analytics graph wrapper instance. |
query | Query Neptune database. |
__init__( graph_identifier: str, client: Any = None, credentials_profile_name: str | None = None, region_name: str | None = None, aws_access_key_id: SecretStr | None = None, aws_secret_access_key: SecretStr | None = None, aws_session_token: SecretStr | None = None, endpoint_url: str | None = None, config: Config | None = None, property_descriptions: dict[tuple[str, str], str] | None = None, ) -> None Create a new Neptune Analytics graph wrapper instance.
Bases: BaseNeptuneGraph
Neptune wrapper for graph operations.
| PARAMETER | DESCRIPTION |
|---|---|
host | endpoint for the database instance TYPE: |
port | port number for the database instance, default is 8182 TYPE: |
use_https | whether to use secure connection, default is True TYPE: |
client | optional boto3 Neptune client TYPE: |
credentials_profile_name | optional AWS profile name TYPE: |
region_name | optional AWS region, e.g., us-west-2 TYPE: |
sign | whether to sign the request payload, default is True TYPE: |
aws_access_key_id | optional AWS access key ID TYPE: |
aws_secret_access_key | optional AWS secret access key TYPE: |
aws_session_token | optional AWS session token TYPE: |
endpoint_url | optional custom endpoint URL TYPE: |
config | optional botocore Config object TYPE: |
Security note: Make sure that the database connection uses credentials that are narrowly-scoped to only include necessary permissions. Failure to do so may result in data corruption or loss, since the calling code may attempt commands that would result in deletion, mutation of data if appropriately prompted or reading sensitive data if such data is present in the database. The best way to guard against such negative outcomes is to (as appropriate) limit the permissions granted to the credentials used with this tool.
See https://docs.langchain.com/oss/python/security-policy for more information. | METHOD | DESCRIPTION |
|---|---|
__init__ | Create a new Neptune graph wrapper instance. |
query | Query Neptune database. |
__init__( host: str, port: int = 8182, use_https: bool = True, client: Any = None, credentials_profile_name: str | None = None, region_name: str | None = None, sign: bool = True, aws_access_key_id: SecretStr | None = None, aws_secret_access_key: SecretStr | None = None, aws_session_token: SecretStr | None = None, endpoint_url: str | None = None, config: Config | None = None, property_descriptions: dict[tuple[str, str], str] | None = None, ) -> None Create a new Neptune graph wrapper instance.
Bases: LLM, BedrockBase
Bedrock models.
To authenticate, the AWS client uses the following methods to automatically load credentials: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If a specific credential profile should be used, you must pass the name of the profile from the ~/.aws/credentials file that is to be used.
Make sure the credentials / roles used have the required policies to access the Bedrock service.
| METHOD | DESCRIPTION |
|---|---|
get_name | Get the name of the |
get_input_schema | Get a Pydantic model that can be used to validate input to the |
get_input_jsonschema | Get a JSON schema that represents the input to the |
get_output_schema | Get a Pydantic model that can be used to validate output to the |
get_output_jsonschema | Get a JSON schema that represents the output of the |
config_schema | The type of config this |
get_config_jsonschema | Get a JSON schema that represents the config of the |
get_graph | Return a graph representation of this |
get_prompts | Return a list of prompts used by this |
__or__ | Runnable "or" operator. |
__ror__ | Runnable "reverse-or" operator. |
pipe | Pipe |
pick | Pick keys from the output |
assign | Assigns new fields to the |
invoke | Transform a single input into an output. |
ainvoke | Transform a single input into an output. |
batch | Default implementation runs invoke in parallel using a thread pool executor. |
batch_as_completed | Run |
abatch | Default implementation runs |
abatch_as_completed | Run |
stream | Default implementation of |
astream | Default implementation of |
astream_log | Stream all output from a |
astream_events | Generate a stream of events. |
transform | Transform inputs to outputs. |
atransform | Transform inputs to outputs. |
bind | Bind arguments to a |
with_config | Bind config to a |
with_listeners | Bind lifecycle listeners to a |
with_alisteners | Bind async lifecycle listeners to a |
with_types | Bind input and output types to a |
with_retry | Create a new |
map | Return a new |
with_fallbacks | Add fallbacks to a |
as_tool | Create a |
__init__ | |
lc_id | Return a unique identifier for this class for serialization purposes. |
to_json | Serialize the |
to_json_not_implemented | Serialize a "not implemented" object. |
configurable_fields | Configure particular |
configurable_alternatives | Configure alternatives for |
set_verbose | If verbose is |
generate_prompt | Pass a sequence of prompts to the model and return model generations. |
agenerate_prompt | Asynchronously pass a sequence of prompts and return model generations. |
with_structured_output | Not implemented on this class. |
get_num_tokens_from_messages | Get the number of tokens in the messages. |
validate_environment | Validate that AWS credentials to and python package exists in environment. |
generate | Pass a sequence of prompts to a model and return generations. |
agenerate | Asynchronously pass a sequence of prompts to a model and return generations. |
__str__ | Return a string representation of the object for printing. |
dict | Return a dictionary of the LLM. |
save | Save the LLM. |
is_lc_serializable | Return whether this model can be serialized by Langchain. |
get_lc_namespace | Get the namespace of the langchain object. |
get_num_tokens | Get the number of tokens present in the text. |
get_token_ids | Return the ordered IDs of the tokens in a text. |
class-attribute instance-attribute ¶
name: str | None = None The name of the Runnable. Used for debugging and tracing.
property ¶
The type of input this Runnable accepts specified as a Pydantic model.
property ¶
Output schema.
The type of output this Runnable produces specified as a Pydantic model.
property ¶
config_specs: list[ConfigurableFieldSpec] List configurable fields for this Runnable.
property ¶
A map of constructor argument names to secret ids.
For example, {"openai_api_key": "OPENAI_API_KEY"}
class-attribute instance-attribute ¶
Whether to cache the response.
- If
True, will use the global cache. - If
False, will not use a cache - If
None, will use the global cache if it's set, otherwise no cache. - If instance of
BaseCache, will use the provided cache.
Caching is not currently supported for streaming methods of models.
class-attribute instance-attribute ¶
Whether to print out response text.
class-attribute instance-attribute ¶
callbacks: Callbacks = Field(default=None, exclude=True) Callbacks to add to the run trace.
class-attribute instance-attribute ¶
Tags to add to the run trace.
class-attribute instance-attribute ¶
Metadata to add to the run trace.
class-attribute instance-attribute ¶
Optional encoder to use for counting tokens.
class-attribute instance-attribute ¶
The bedrock runtime client for making data plane API calls
class-attribute instance-attribute ¶
The bedrock client for making control plane API calls
class-attribute instance-attribute ¶
The aws region e.g., us-west-2. Falls back to AWS_REGION or AWS_DEFAULT_REGION env variable or region specified in ~/.aws/config in case it is not provided here.
class-attribute instance-attribute ¶
The name of the profile in the ~/.aws/credentials or ~/.aws/config files, which has either access keys or role information specified.
If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
class-attribute instance-attribute ¶
aws_access_key_id: SecretStr | None = Field( default_factory=secret_from_env("AWS_ACCESS_KEY_ID", default=None) ) AWS access key id.
If provided, aws_secret_access_key must also be provided.
If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_ACCESS_KEY_ID environment variable.
class-attribute instance-attribute ¶
aws_secret_access_key: SecretStr | None = Field( default_factory=secret_from_env("AWS_SECRET_ACCESS_KEY", default=None) ) AWS secret_access_key.
If provided, aws_access_key_id must also be provided.
If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_SECRET_ACCESS_KEY environment variable.
class-attribute instance-attribute ¶
aws_session_token: SecretStr | None = Field( default_factory=secret_from_env("AWS_SESSION_TOKEN", default=None) ) AWS session token.
If provided, aws_access_key_id and aws_secret_access_key must also be provided.
Not required unless using temporary credentials.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_SESSION_TOKEN environment variable.
class-attribute instance-attribute ¶
config: Any = None An optional botocore.config.Config instance to pass to the client.
class-attribute instance-attribute ¶
provider: str | None = None The model provider, e.g., 'amazon', 'cohere', 'ai21', etc. When not supplied, provider is extracted from the first part of the model_id e.g. 'amazon' in 'amazon.titan-text-express-v1'. This value should be provided for model IDs that do not have the provider in them, e.g., custom and provisioned models that have an ARN associated with them.
class-attribute instance-attribute ¶
Id of the model to call, e.g., 'amazon.titan-text-express-v1', this is equivalent to the modelId property in the list-foundation-models api. For custom and provisioned models, an ARN value is expected.
class-attribute instance-attribute ¶
An optional field to pass the base model id. If provided, this will be used over the value of model_id to identify the base model.
class-attribute instance-attribute ¶
Keyword arguments to pass to the model.
class-attribute instance-attribute ¶
endpoint_url: str | None = None Needed if you don't want to default to 'us-east-1' endpoint
class-attribute instance-attribute ¶
streaming: bool = False Whether to stream the results.
class-attribute instance-attribute ¶
guardrails: Mapping[str, Any] | None = { "trace": None, "guardrailIdentifier": None, "guardrailVersion": None, } An optional dictionary to configure guardrails for Bedrock.
This field guardrails consists of two keys: 'guardrailId' and 'guardrailVersion', which should be strings, but are initialized to None.
It's used to determine if specific guardrails are enabled and properly set.
Type
Optional[Mapping[str, str]]: A mapping with 'guardrailId' and 'guardrailVersion' keys.
Example
To enable tracing for guardrails, set the 'trace' key to True and pass a callback handler to the 'run_manager' parameter of the 'generate', '_call' methods.
Example
https://python.langchain.com/docs/concepts/callbacks/ for more information on callback handlers.
class BedrockAsyncCallbackHandler(AsyncCallbackHandler): async def on_llm_error( self, error: BaseException, **kwargs: Any, ) -> Any: reason = kwargs.get("reason") if reason == "GUARDRAIL_INTERVENED": ...Logic to handle guardrail intervention...
property ¶
List of attribute names that should be included in the serialized kwargs.
These attributes must be accepted by the constructor.
Default is an empty dictionary.
get_input_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate input to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate input. |
get_input_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the input to the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the input to the |
Example
Added in langchain-core 0.3.0
get_output_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate output to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate output. |
get_output_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the output of the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the output of the |
Example
Added in langchain-core 0.3.0
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.
| PARAMETER | DESCRIPTION |
|---|---|
include | A list of fields to include in the config schema. |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate config. |
get_graph(config: RunnableConfig | None = None) -> Graph Return a graph representation of this Runnable.
get_prompts(config: RunnableConfig | None = None) -> list[BasePromptTemplate] Return a list of prompts used by this Runnable.
__or__( other: Runnable[Any, Other] | Callable[[Iterator[Any]], Iterator[Other]] | Callable[[AsyncIterator[Any]], AsyncIterator[Other]] | Callable[[Any], Other] | Mapping[str, Runnable[Any, Other] | Callable[[Any], Other] | Any], ) -> RunnableSerializable[Input, Other] Runnable "or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
__ror__( other: Runnable[Other, Any] | Callable[[Iterator[Other]], Iterator[Any]] | Callable[[AsyncIterator[Other]], AsyncIterator[Any]] | Callable[[Other], Any] | Mapping[str, Runnable[Other, Any] | Callable[[Other], Any] | Any], ) -> RunnableSerializable[Other, Output] Runnable "reverse-or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Other, Output] | A new |
pipe( *others: Runnable[Any, Other] | Callable[[Any], Other], name: str | None = None ) -> RunnableSerializable[Input, Other] Pipe Runnable objects.
Compose this Runnable with Runnable-like objects to make a RunnableSequence.
Equivalent to RunnableSequence(self, *others) or self | others[0] | ...
Example
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] | PARAMETER | DESCRIPTION |
|---|---|
*others | Other TYPE: |
name | An optional name for the resulting TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
Pick keys from the output dict of this Runnable.
Pick a single key
import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) chain = RunnableMap(str=as_str, json=as_json) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3]} json_only_chain = chain.pick("json") json_only_chain.invoke("[1, 2, 3]") # -> [1, 2, 3] Pick a list of keys
from typing import Any import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) def as_bytes(x: Any) -> bytes: return bytes(x, "utf-8") chain = RunnableMap( str=as_str, json=as_json, bytes=RunnableLambda(as_bytes) ) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3], "bytes": b"[1, 2, 3]"} json_and_bytes_chain = chain.pick(["json", "bytes"]) json_and_bytes_chain.invoke("[1, 2, 3]") # -> {"json": [1, 2, 3], "bytes": b"[1, 2, 3]"} | PARAMETER | DESCRIPTION |
|---|---|
keys | A key or list of keys to pick from the output dict. |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | a new |
assign( **kwargs: Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any] | Mapping[str, Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any]], ) -> RunnableSerializable[Any, Any] Assigns new fields to the dict output of this Runnable.
from langchain_core.language_models.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}" ) model = FakeStreamingListLLM(responses=["foo-lish"]) chain: Runnable = prompt | model | {"str": StrOutputParser()} chain_with_assign = chain.assign(hello=itemgetter("str") | model) print(chain_with_assign.input_schema.model_json_schema()) # {'title': 'PromptInput', 'type': 'object', 'properties': {'question': {'title': 'Question', 'type': 'string'}}} print(chain_with_assign.output_schema.model_json_schema()) # {'title': 'RunnableSequenceOutput', 'type': 'object', 'properties': {'str': {'title': 'Str', 'type': 'string'}, 'hello': {'title': 'Hello', 'type': 'string'}}} | PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A mapping of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | A new |
invoke( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> str Transform a single input into an output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
ainvoke( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> str Transform a single input into an output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Output | The output of the |
batch( inputs: list[LanguageModelInput], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any, ) -> list[str] Default implementation runs invoke in parallel using a thread pool executor.
The default implementation of batch works well for IO bound runnables.
Subclasses must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
batch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> Iterator[tuple[int, Output | Exception]] Run invoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
tuple[int, Output | Exception] | Tuples of the index of the input and the output from the |
async ¶
abatch( inputs: list[LanguageModelInput], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any, ) -> list[str] Default implementation runs ainvoke in parallel using asyncio.gather.
The default implementation of batch works well for IO bound runnables.
Subclasses must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
async ¶
abatch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> AsyncIterator[tuple[int, Output | Exception]] Run ainvoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[tuple[int, Output | Exception]] | A tuple of the index of the input and the output from the |
stream( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> Iterator[str] Default implementation of stream, which calls invoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
astream( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> AsyncIterator[str] Default implementation of astream, which calls ainvoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
async ¶
astream_log( input: Any, config: RunnableConfig | None = None, *, diff: bool = True, with_streamed_output_list: bool = True, include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> 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.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
diff | Whether to yield diffs between each step or the current state. TYPE: |
with_streamed_output_list | Whether to yield the TYPE: |
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 TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[RunLogPatch] | AsyncIterator[RunLog] | A |
async ¶
astream_events( input: Any, config: RunnableConfig | None = None, *, version: Literal["v1", "v2"] = "v2", include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> AsyncIterator[StreamEvent] Generate a stream of events.
Use to create an iterator over StreamEvent that provide real-time information about the progress of the Runnable, including StreamEvent from intermediate results.
A StreamEvent is a dictionary with the following schema:
event: Event names are of the format:on_[runnable_type]_(start|stream|end).name: The name of theRunnablethat generated the event.run_id: Randomly generated ID associated with the given execution of theRunnablethat emitted the event. A childRunnablethat gets invoked as part of the execution of a parentRunnableis assigned its own unique ID.parent_ids: The IDs of the parent runnables that generated the event. The rootRunnablewill 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: The tags of theRunnablethat generated the event.metadata: The metadata of theRunnablethat generated the event.data: The data associated with the event. The contents of this field depend on the type of event. See the table below for more details.
Below is a table that illustrates some events 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.
Note
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:
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:
prompt:
template = ChatPromptTemplate.from_messages( [ ("system", "You are Cat Agent 007"), ("human", "{question}"), ] ).with_config({"run_name": "my_template", "tags": ["my_template"]}) Example
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": [], }, ] 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) | PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
version | The version of the schema to use, either Users should use
No default will be assigned until the API is stabilized. custom events will only be surfaced in TYPE: |
include_names | Only include events from |
include_types | Only include events from |
include_tags | Only include events from |
exclude_names | Exclude events from |
exclude_types | Exclude events from |
exclude_tags | Exclude events from |
**kwargs | Additional keyword arguments to pass to the These will be passed to TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[StreamEvent] | An async stream of |
| RAISES | DESCRIPTION |
|---|---|
NotImplementedError | If the version is not |
transform( input: Iterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None ) -> Iterator[Output] Transform inputs to outputs.
Default implementation of transform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
atransform( input: AsyncIterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None, ) -> AsyncIterator[Output] Transform inputs to outputs.
Default implementation of atransform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An async iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
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.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | The arguments to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_ollama import ChatOllama from langchain_core.output_parsers import StrOutputParser model = ChatOllama(model="llama3.1") # Without bind chain = model | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two three four five.' # With bind chain = model.bind(stop=["three"]) | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two'
with_config( config: RunnableConfig | None = None, **kwargs: Any ) -> Runnable[Input, Output] Bind config to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | The config to bind to the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_listeners( *, on_start: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_end: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_error: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, ) -> Runnable[Input, Output] Bind lifecycle listeners to a Runnable, returning a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called before the TYPE: |
on_end | Called after the TYPE: |
on_error | Called if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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)
with_alisteners( *, on_start: AsyncListener | None = None, on_end: AsyncListener | None = None, on_error: AsyncListener | None = None, ) -> Runnable[Input, Output] Bind async lifecycle listeners to a Runnable.
Returns a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called asynchronously before the TYPE: |
on_end | Called asynchronously after the TYPE: |
on_error | Called asynchronously if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_core.runnables import RunnableLambda, Runnable from datetime import datetime, timezone import time import asyncio def format_t(timestamp: float) -> str: return datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat() 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 2025-03-01T07:05:22.875378+00:00 # on start callback starts at 2025-03-01T07:05:22.875495+00:00 # on start callback ends at 2025-03-01T07:05:25.878862+00:00 # on start callback ends at 2025-03-01T07:05:25.878947+00:00 # Runnable[2s]: starts at 2025-03-01T07:05:25.879392+00:00 # Runnable[3s]: starts at 2025-03-01T07:05:25.879804+00:00 # Runnable[2s]: ends at 2025-03-01T07:05:27.881998+00:00 # on end callback starts at 2025-03-01T07:05:27.882360+00:00 # Runnable[3s]: ends at 2025-03-01T07:05:28.881737+00:00 # on end callback starts at 2025-03-01T07:05:28.882428+00:00 # on end callback ends at 2025-03-01T07:05:29.883893+00:00 # on end callback ends at 2025-03-01T07:05:30.884831+00:00
with_types( *, input_type: type[Input] | None = None, output_type: type[Output] | None = None ) -> Runnable[Input, Output] Bind input and output types to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
input_type | The input type to bind to the TYPE: |
output_type | The output type to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_retry( *, retry_if_exception_type: tuple[type[BaseException], ...] = (Exception,), wait_exponential_jitter: bool = True, exponential_jitter_params: ExponentialJitterParams | None = None, stop_after_attempt: int = 3, ) -> Runnable[Input, Output] Create a new Runnable that retries the original Runnable on exceptions.
| PARAMETER | DESCRIPTION |
|---|---|
retry_if_exception_type | A tuple of exception types to retry on. TYPE: |
wait_exponential_jitter | Whether to add jitter to the wait time between retries. TYPE: |
stop_after_attempt | The maximum number of attempts to make before giving up. TYPE: |
exponential_jitter_params | Parameters for TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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
with_fallbacks( fallbacks: Sequence[Runnable[Input, Output]], *, exceptions_to_handle: tuple[type[BaseException], ...] = (Exception,), exception_key: str | None = None, ) -> RunnableWithFallbacks[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.
| PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
Example
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 | PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
as_tool( args_schema: type[BaseModel] | None = None, *, name: str | None = None, description: str | None = None, arg_types: dict[str, type] | None = 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.
| PARAMETER | DESCRIPTION |
|---|---|
args_schema | The schema for the tool. |
name | The name of the tool. TYPE: |
description | The description of the tool. TYPE: |
arg_types | A dictionary of argument names to types. |
| RETURNS | DESCRIPTION |
|---|---|
BaseTool | A |
TypedDict input
dict input, specifying schema via args_schema
from typing import Any from pydantic 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
classmethod ¶
Return a unique identifier for this class for serialization purposes.
The unique identifier is a list of strings that describes the path to the object.
For example, for the class langchain.llms.openai.OpenAI, the id is ["langchain", "llms", "openai", "OpenAI"].
Serialize the Runnable to JSON.
| RETURNS | DESCRIPTION |
|---|---|
SerializedConstructor | SerializedNotImplemented | A JSON-serializable representation of the |
Serialize a "not implemented" object.
| RETURNS | DESCRIPTION |
|---|---|
SerializedNotImplemented |
|
configurable_fields( **kwargs: AnyConfigurableField, ) -> RunnableSerializable[Input, Output] Configure particular Runnable fields at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A dictionary of TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If a configuration key is not found in the |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
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, )
configurable_alternatives( which: ConfigurableField, *, default_key: str = "default", prefix_keys: bool = False, **kwargs: Runnable[Input, Output] | Callable[[], Runnable[Input, Output]], ) -> RunnableSerializable[Input, Output] Configure alternatives for Runnable objects that can be set at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
which | The TYPE: |
default_key | The default key to use if no alternative is selected. TYPE: |
prefix_keys | Whether to prefix the keys with the TYPE: |
**kwargs | A dictionary of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
from langchain_anthropic import ChatAnthropic from langchain_core.runnables.utils import ConfigurableField from langchain_openai import ChatOpenAI model = ChatAnthropic( model_name="claude-sonnet-4-5-20250929" ).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 )
generate_prompt( prompts: list[PromptValue], stop: list[str] | None = None, callbacks: Callbacks | list[Callbacks] | None = None, **kwargs: Any, ) -> LLMResult Pass a sequence of prompts to the model and return model generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
prompts | List of A TYPE: |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
async ¶
agenerate_prompt( prompts: list[PromptValue], stop: list[str] | None = None, callbacks: Callbacks | list[Callbacks] | None = None, **kwargs: Any, ) -> LLMResult Asynchronously pass a sequence of prompts and return model generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
prompts | List of A TYPE: |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
with_structured_output( schema: dict | type, **kwargs: Any ) -> Runnable[LanguageModelInput, dict | BaseModel] Not implemented on this class.
get_num_tokens_from_messages( messages: list[BaseMessage], tools: Sequence | None = None ) -> int Get the number of tokens in the messages.
Useful for checking if an input fits in a model's context window.
This should be overridden by model-specific implementations to provide accurate token counts via model-specific tokenizers.
Note
- The base implementation of
get_num_tokens_from_messagesignores tool schemas. - The base implementation of
get_num_tokens_from_messagesadds additional prefixes to messages in represent user roles, which will add to the overall token count. Model-specific implementations may choose to handle this differently.
| PARAMETER | DESCRIPTION |
|---|---|
messages | The message inputs to tokenize. TYPE: |
tools | If provided, sequence of dict, TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
int | The sum of the number of tokens across the messages. |
validate_environment() -> Self Validate that AWS credentials to and python package exists in environment.
generate( prompts: list[str], stop: list[str] | None = None, callbacks: Callbacks | list[Callbacks] | None = None, *, tags: list[str] | list[list[str]] | None = None, metadata: dict[str, Any] | list[dict[str, Any]] | None = None, run_name: str | list[str] | None = None, run_id: UUID | list[UUID | None] | None = None, **kwargs: Any, ) -> LLMResult Pass a sequence of prompts to a model and return generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
prompts | List of string prompts. |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
tags | List of tags to associate with each prompt. If provided, the length of the list must match the length of the prompts list. |
metadata | List of metadata dictionaries to associate with each prompt. If provided, the length of the list must match the length of the prompts list. TYPE: |
run_name | List of run names to associate with each prompt. If provided, the length of the list must match the length of the prompts list. |
run_id | List of run IDs to associate with each prompt. If provided, the length of the list must match the length of the prompts list. |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If prompts is not a list. |
ValueError | If the length of |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
async ¶
agenerate( prompts: list[str], stop: list[str] | None = None, callbacks: Callbacks | list[Callbacks] | None = None, *, tags: list[str] | list[list[str]] | None = None, metadata: dict[str, Any] | list[dict[str, Any]] | None = None, run_name: str | list[str] | None = None, run_id: UUID | list[UUID | None] | None = None, **kwargs: Any, ) -> LLMResult Asynchronously pass a sequence of prompts to a model and return generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
prompts | List of string prompts. |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
tags | List of tags to associate with each prompt. If provided, the length of the list must match the length of the prompts list. |
metadata | List of metadata dictionaries to associate with each prompt. If provided, the length of the list must match the length of the prompts list. TYPE: |
run_name | List of run names to associate with each prompt. If provided, the length of the list must match the length of the prompts list. |
run_id | List of run IDs to associate with each prompt. If provided, the length of the list must match the length of the prompts list. |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If the length of |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
Save the LLM.
| PARAMETER | DESCRIPTION |
|---|---|
file_path | Path to file to save the LLM to. |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If the file path is not a string or Path object. |
classmethod ¶
is_lc_serializable() -> bool Return whether this model can be serialized by Langchain.
classmethod ¶
Get the number of tokens present in the text.
Useful for checking if an input fits in a model's context window.
This should be overridden by model-specific implementations to provide accurate token counts via model-specific tokenizers.
| PARAMETER | DESCRIPTION |
|---|---|
text | The string input to tokenize. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
int | The integer number of tokens in the text. |
Bases: LLM
Sagemaker Inference Endpoint models.
To use, you must supply the endpoint name from your deployed Sagemaker model & the region where it is deployed.
To authenticate, the AWS client uses the following methods to automatically load credentials: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If a specific credential profile should be used, you must pass the name of the profile from the ~/.aws/credentials file that is to be used.
Make sure the credentials / roles used have the required policies to access the Sagemaker endpoint.
See: https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html
| METHOD | DESCRIPTION |
|---|---|
get_name | Get the name of the |
get_input_schema | Get a Pydantic model that can be used to validate input to the |
get_input_jsonschema | Get a JSON schema that represents the input to the |
get_output_schema | Get a Pydantic model that can be used to validate output to the |
get_output_jsonschema | Get a JSON schema that represents the output of the |
config_schema | The type of config this |
get_config_jsonschema | Get a JSON schema that represents the config of the |
get_graph | Return a graph representation of this |
get_prompts | Return a list of prompts used by this |
__or__ | Runnable "or" operator. |
__ror__ | Runnable "reverse-or" operator. |
pipe | Pipe |
pick | Pick keys from the output |
assign | Assigns new fields to the |
invoke | Transform a single input into an output. |
ainvoke | Transform a single input into an output. |
batch | Default implementation runs invoke in parallel using a thread pool executor. |
batch_as_completed | Run |
abatch | Default implementation runs |
abatch_as_completed | Run |
stream | Default implementation of |
astream | Default implementation of |
astream_log | Stream all output from a |
astream_events | Generate a stream of events. |
transform | Transform inputs to outputs. |
atransform | Transform inputs to outputs. |
bind | Bind arguments to a |
with_config | Bind config to a |
with_listeners | Bind lifecycle listeners to a |
with_alisteners | Bind async lifecycle listeners to a |
with_types | Bind input and output types to a |
with_retry | Create a new |
map | Return a new |
with_fallbacks | Add fallbacks to a |
as_tool | Create a |
__init__ | |
is_lc_serializable | Is this class serializable? |
get_lc_namespace | Get the namespace of the LangChain object. |
lc_id | Return a unique identifier for this class for serialization purposes. |
to_json | Serialize the |
to_json_not_implemented | Serialize a "not implemented" object. |
configurable_fields | Configure particular |
configurable_alternatives | Configure alternatives for |
set_verbose | If verbose is |
generate_prompt | Pass a sequence of prompts to the model and return model generations. |
agenerate_prompt | Asynchronously pass a sequence of prompts and return model generations. |
with_structured_output | Not implemented on this class. |
get_token_ids | Return the ordered IDs of the tokens in a text. |
get_num_tokens | Get the number of tokens present in the text. |
get_num_tokens_from_messages | Get the number of tokens in the messages. |
generate | Pass a sequence of prompts to a model and return generations. |
agenerate | Asynchronously pass a sequence of prompts to a model and return generations. |
__str__ | Return a string representation of the object for printing. |
dict | Return a dictionary of the LLM. |
save | Save the LLM. |
validate_environment | Dont do anything if client provided externally |
class-attribute instance-attribute ¶
name: str | None = None The name of the Runnable. Used for debugging and tracing.
property ¶
The type of input this Runnable accepts specified as a Pydantic model.
property ¶
Output schema.
The type of output this Runnable produces specified as a Pydantic model.
property ¶
config_specs: list[ConfigurableFieldSpec] List configurable fields for this Runnable.
property ¶
A map of constructor argument names to secret ids.
For example, {"openai_api_key": "OPENAI_API_KEY"}
property ¶
lc_attributes: dict List of attribute names that should be included in the serialized kwargs.
These attributes must be accepted by the constructor.
Default is an empty dictionary.
class-attribute instance-attribute ¶
Whether to cache the response.
- If
True, will use the global cache. - If
False, will not use a cache - If
None, will use the global cache if it's set, otherwise no cache. - If instance of
BaseCache, will use the provided cache.
Caching is not currently supported for streaming methods of models.
class-attribute instance-attribute ¶
Whether to print out response text.
class-attribute instance-attribute ¶
callbacks: Callbacks = Field(default=None, exclude=True) Callbacks to add to the run trace.
class-attribute instance-attribute ¶
Tags to add to the run trace.
class-attribute instance-attribute ¶
Metadata to add to the run trace.
class-attribute instance-attribute ¶
Optional encoder to use for counting tokens.
class-attribute instance-attribute ¶
endpoint_name: str = '' The name of the endpoint from the deployed Sagemaker model.
Must be unique within an AWS Region.
class-attribute instance-attribute ¶
inference_component_name: str | None = None Optional name of the inference component to invoke if specified with endpoint name.
class-attribute instance-attribute ¶
region_name: str = '' The aws region where the Sagemaker model is deployed, eg. 'us-west-2'.
class-attribute instance-attribute ¶
credentials_profile_name: str | None = None The name of the profile in the ~/.aws/credentials or ~/.aws/config files, which has either access keys or role information specified.
If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
class-attribute instance-attribute ¶
aws_access_key_id: SecretStr | None = Field( default_factory=secret_from_env("AWS_ACCESS_KEY_ID", default=None) ) AWS access key id.
If provided, aws_secret_access_key must also be provided. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from 'AWS_ACCESS_KEY_ID' environment variable.
class-attribute instance-attribute ¶
aws_secret_access_key: SecretStr | None = Field( default_factory=secret_from_env("AWS_SECRET_ACCESS_KEY", default=None) ) AWS secret_access_key.
If provided, aws_access_key_id must also be provided.
If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_SECRET_ACCESS_KEY environment variable.
class-attribute instance-attribute ¶
aws_session_token: SecretStr | None = Field( default_factory=secret_from_env("AWS_SESSION_TOKEN", default=None) ) AWS session token.
If provided, aws_access_key_id and aws_secret_access_key must also be provided.
Not required unless using temporary credentials.
See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
If not provided, will be read from AWS_SESSION_TOKEN environment variable.
class-attribute instance-attribute ¶
config: Any = None An optional botocore.config.Config instance to pass to the client.
class-attribute instance-attribute ¶
endpoint_url: str | None = None Needed if you don't want to default to 'us-east-1' endpoint
instance-attribute ¶
The content handler class that provides an input and output transform functions to handle formats between LLM and the endpoint.
class-attribute instance-attribute ¶
streaming: bool = False Whether to stream the results.
class-attribute instance-attribute ¶
model_kwargs: dict | None = None Keyword arguments to pass to the model.
class-attribute instance-attribute ¶
endpoint_kwargs: dict | None = None Optional attributes passed to the invoke_endpoint function. See boto3 docs for more info.
get_input_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate input to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate input. |
get_input_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the input to the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the input to the |
Example
Added in langchain-core 0.3.0
get_output_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate output to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate output. |
get_output_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the output of the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the output of the |
Example
Added in langchain-core 0.3.0
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.
| PARAMETER | DESCRIPTION |
|---|---|
include | A list of fields to include in the config schema. |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate config. |
get_graph(config: RunnableConfig | None = None) -> Graph Return a graph representation of this Runnable.
get_prompts(config: RunnableConfig | None = None) -> list[BasePromptTemplate] Return a list of prompts used by this Runnable.
__or__( other: Runnable[Any, Other] | Callable[[Iterator[Any]], Iterator[Other]] | Callable[[AsyncIterator[Any]], AsyncIterator[Other]] | Callable[[Any], Other] | Mapping[str, Runnable[Any, Other] | Callable[[Any], Other] | Any], ) -> RunnableSerializable[Input, Other] Runnable "or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
__ror__( other: Runnable[Other, Any] | Callable[[Iterator[Other]], Iterator[Any]] | Callable[[AsyncIterator[Other]], AsyncIterator[Any]] | Callable[[Other], Any] | Mapping[str, Runnable[Other, Any] | Callable[[Other], Any] | Any], ) -> RunnableSerializable[Other, Output] Runnable "reverse-or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Other, Output] | A new |
pipe( *others: Runnable[Any, Other] | Callable[[Any], Other], name: str | None = None ) -> RunnableSerializable[Input, Other] Pipe Runnable objects.
Compose this Runnable with Runnable-like objects to make a RunnableSequence.
Equivalent to RunnableSequence(self, *others) or self | others[0] | ...
Example
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] | PARAMETER | DESCRIPTION |
|---|---|
*others | Other TYPE: |
name | An optional name for the resulting TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
Pick keys from the output dict of this Runnable.
Pick a single key
import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) chain = RunnableMap(str=as_str, json=as_json) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3]} json_only_chain = chain.pick("json") json_only_chain.invoke("[1, 2, 3]") # -> [1, 2, 3] Pick a list of keys
from typing import Any import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) def as_bytes(x: Any) -> bytes: return bytes(x, "utf-8") chain = RunnableMap( str=as_str, json=as_json, bytes=RunnableLambda(as_bytes) ) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3], "bytes": b"[1, 2, 3]"} json_and_bytes_chain = chain.pick(["json", "bytes"]) json_and_bytes_chain.invoke("[1, 2, 3]") # -> {"json": [1, 2, 3], "bytes": b"[1, 2, 3]"} | PARAMETER | DESCRIPTION |
|---|---|
keys | A key or list of keys to pick from the output dict. |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | a new |
assign( **kwargs: Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any] | Mapping[str, Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any]], ) -> RunnableSerializable[Any, Any] Assigns new fields to the dict output of this Runnable.
from langchain_core.language_models.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}" ) model = FakeStreamingListLLM(responses=["foo-lish"]) chain: Runnable = prompt | model | {"str": StrOutputParser()} chain_with_assign = chain.assign(hello=itemgetter("str") | model) print(chain_with_assign.input_schema.model_json_schema()) # {'title': 'PromptInput', 'type': 'object', 'properties': {'question': {'title': 'Question', 'type': 'string'}}} print(chain_with_assign.output_schema.model_json_schema()) # {'title': 'RunnableSequenceOutput', 'type': 'object', 'properties': {'str': {'title': 'Str', 'type': 'string'}, 'hello': {'title': 'Hello', 'type': 'string'}}} | PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A mapping of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | A new |
invoke( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> str Transform a single input into an output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
ainvoke( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> str Transform a single input into an output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Output | The output of the |
batch( inputs: list[LanguageModelInput], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any, ) -> list[str] Default implementation runs invoke in parallel using a thread pool executor.
The default implementation of batch works well for IO bound runnables.
Subclasses must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
batch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> Iterator[tuple[int, Output | Exception]] Run invoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
tuple[int, Output | Exception] | Tuples of the index of the input and the output from the |
async ¶
abatch( inputs: list[LanguageModelInput], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any, ) -> list[str] Default implementation runs ainvoke in parallel using asyncio.gather.
The default implementation of batch works well for IO bound runnables.
Subclasses must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
async ¶
abatch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> AsyncIterator[tuple[int, Output | Exception]] Run ainvoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[tuple[int, Output | Exception]] | A tuple of the index of the input and the output from the |
stream( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> Iterator[str] Default implementation of stream, which calls invoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
astream( input: LanguageModelInput, config: RunnableConfig | None = None, *, stop: list[str] | None = None, **kwargs: Any, ) -> AsyncIterator[str] Default implementation of astream, which calls ainvoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
async ¶
astream_log( input: Any, config: RunnableConfig | None = None, *, diff: bool = True, with_streamed_output_list: bool = True, include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> 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.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
diff | Whether to yield diffs between each step or the current state. TYPE: |
with_streamed_output_list | Whether to yield the TYPE: |
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 TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[RunLogPatch] | AsyncIterator[RunLog] | A |
async ¶
astream_events( input: Any, config: RunnableConfig | None = None, *, version: Literal["v1", "v2"] = "v2", include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> AsyncIterator[StreamEvent] Generate a stream of events.
Use to create an iterator over StreamEvent that provide real-time information about the progress of the Runnable, including StreamEvent from intermediate results.
A StreamEvent is a dictionary with the following schema:
event: Event names are of the format:on_[runnable_type]_(start|stream|end).name: The name of theRunnablethat generated the event.run_id: Randomly generated ID associated with the given execution of theRunnablethat emitted the event. A childRunnablethat gets invoked as part of the execution of a parentRunnableis assigned its own unique ID.parent_ids: The IDs of the parent runnables that generated the event. The rootRunnablewill 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: The tags of theRunnablethat generated the event.metadata: The metadata of theRunnablethat generated the event.data: The data associated with the event. The contents of this field depend on the type of event. See the table below for more details.
Below is a table that illustrates some events 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.
Note
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:
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:
prompt:
template = ChatPromptTemplate.from_messages( [ ("system", "You are Cat Agent 007"), ("human", "{question}"), ] ).with_config({"run_name": "my_template", "tags": ["my_template"]}) Example
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": [], }, ] 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) | PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
version | The version of the schema to use, either Users should use
No default will be assigned until the API is stabilized. custom events will only be surfaced in TYPE: |
include_names | Only include events from |
include_types | Only include events from |
include_tags | Only include events from |
exclude_names | Exclude events from |
exclude_types | Exclude events from |
exclude_tags | Exclude events from |
**kwargs | Additional keyword arguments to pass to the These will be passed to TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[StreamEvent] | An async stream of |
| RAISES | DESCRIPTION |
|---|---|
NotImplementedError | If the version is not |
transform( input: Iterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None ) -> Iterator[Output] Transform inputs to outputs.
Default implementation of transform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
atransform( input: AsyncIterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None, ) -> AsyncIterator[Output] Transform inputs to outputs.
Default implementation of atransform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An async iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
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.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | The arguments to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_ollama import ChatOllama from langchain_core.output_parsers import StrOutputParser model = ChatOllama(model="llama3.1") # Without bind chain = model | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two three four five.' # With bind chain = model.bind(stop=["three"]) | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two'
with_config( config: RunnableConfig | None = None, **kwargs: Any ) -> Runnable[Input, Output] Bind config to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | The config to bind to the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_listeners( *, on_start: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_end: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_error: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, ) -> Runnable[Input, Output] Bind lifecycle listeners to a Runnable, returning a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called before the TYPE: |
on_end | Called after the TYPE: |
on_error | Called if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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)
with_alisteners( *, on_start: AsyncListener | None = None, on_end: AsyncListener | None = None, on_error: AsyncListener | None = None, ) -> Runnable[Input, Output] Bind async lifecycle listeners to a Runnable.
Returns a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called asynchronously before the TYPE: |
on_end | Called asynchronously after the TYPE: |
on_error | Called asynchronously if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_core.runnables import RunnableLambda, Runnable from datetime import datetime, timezone import time import asyncio def format_t(timestamp: float) -> str: return datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat() 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 2025-03-01T07:05:22.875378+00:00 # on start callback starts at 2025-03-01T07:05:22.875495+00:00 # on start callback ends at 2025-03-01T07:05:25.878862+00:00 # on start callback ends at 2025-03-01T07:05:25.878947+00:00 # Runnable[2s]: starts at 2025-03-01T07:05:25.879392+00:00 # Runnable[3s]: starts at 2025-03-01T07:05:25.879804+00:00 # Runnable[2s]: ends at 2025-03-01T07:05:27.881998+00:00 # on end callback starts at 2025-03-01T07:05:27.882360+00:00 # Runnable[3s]: ends at 2025-03-01T07:05:28.881737+00:00 # on end callback starts at 2025-03-01T07:05:28.882428+00:00 # on end callback ends at 2025-03-01T07:05:29.883893+00:00 # on end callback ends at 2025-03-01T07:05:30.884831+00:00
with_types( *, input_type: type[Input] | None = None, output_type: type[Output] | None = None ) -> Runnable[Input, Output] Bind input and output types to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
input_type | The input type to bind to the TYPE: |
output_type | The output type to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_retry( *, retry_if_exception_type: tuple[type[BaseException], ...] = (Exception,), wait_exponential_jitter: bool = True, exponential_jitter_params: ExponentialJitterParams | None = None, stop_after_attempt: int = 3, ) -> Runnable[Input, Output] Create a new Runnable that retries the original Runnable on exceptions.
| PARAMETER | DESCRIPTION |
|---|---|
retry_if_exception_type | A tuple of exception types to retry on. TYPE: |
wait_exponential_jitter | Whether to add jitter to the wait time between retries. TYPE: |
stop_after_attempt | The maximum number of attempts to make before giving up. TYPE: |
exponential_jitter_params | Parameters for TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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
with_fallbacks( fallbacks: Sequence[Runnable[Input, Output]], *, exceptions_to_handle: tuple[type[BaseException], ...] = (Exception,), exception_key: str | None = None, ) -> RunnableWithFallbacks[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.
| PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
Example
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 | PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
as_tool( args_schema: type[BaseModel] | None = None, *, name: str | None = None, description: str | None = None, arg_types: dict[str, type] | None = 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.
| PARAMETER | DESCRIPTION |
|---|---|
args_schema | The schema for the tool. |
name | The name of the tool. TYPE: |
description | The description of the tool. TYPE: |
arg_types | A dictionary of argument names to types. |
| RETURNS | DESCRIPTION |
|---|---|
BaseTool | A |
TypedDict input
dict input, specifying schema via args_schema
from typing import Any from pydantic 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
classmethod ¶
is_lc_serializable() -> bool Is this class serializable?
By design, even if a class inherits from Serializable, it is not serializable by default. This is to prevent accidental serialization of objects that should not be serialized.
| RETURNS | DESCRIPTION |
|---|---|
bool | Whether the class is serializable. Default is |
classmethod ¶
classmethod ¶
Return a unique identifier for this class for serialization purposes.
The unique identifier is a list of strings that describes the path to the object.
For example, for the class langchain.llms.openai.OpenAI, the id is ["langchain", "llms", "openai", "OpenAI"].
Serialize the Runnable to JSON.
| RETURNS | DESCRIPTION |
|---|---|
SerializedConstructor | SerializedNotImplemented | A JSON-serializable representation of the |
Serialize a "not implemented" object.
| RETURNS | DESCRIPTION |
|---|---|
SerializedNotImplemented |
|
configurable_fields( **kwargs: AnyConfigurableField, ) -> RunnableSerializable[Input, Output] Configure particular Runnable fields at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A dictionary of TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If a configuration key is not found in the |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
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, )
configurable_alternatives( which: ConfigurableField, *, default_key: str = "default", prefix_keys: bool = False, **kwargs: Runnable[Input, Output] | Callable[[], Runnable[Input, Output]], ) -> RunnableSerializable[Input, Output] Configure alternatives for Runnable objects that can be set at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
which | The TYPE: |
default_key | The default key to use if no alternative is selected. TYPE: |
prefix_keys | Whether to prefix the keys with the TYPE: |
**kwargs | A dictionary of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
from langchain_anthropic import ChatAnthropic from langchain_core.runnables.utils import ConfigurableField from langchain_openai import ChatOpenAI model = ChatAnthropic( model_name="claude-sonnet-4-5-20250929" ).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 )
generate_prompt( prompts: list[PromptValue], stop: list[str] | None = None, callbacks: Callbacks | list[Callbacks] | None = None, **kwargs: Any, ) -> LLMResult Pass a sequence of prompts to the model and return model generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
prompts | List of A TYPE: |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
async ¶
agenerate_prompt( prompts: list[PromptValue], stop: list[str] | None = None, callbacks: Callbacks | list[Callbacks] | None = None, **kwargs: Any, ) -> LLMResult Asynchronously pass a sequence of prompts and return model generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
prompts | List of A TYPE: |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
with_structured_output( schema: dict | type, **kwargs: Any ) -> Runnable[LanguageModelInput, dict | BaseModel] Not implemented on this class.
Get the number of tokens present in the text.
Useful for checking if an input fits in a model's context window.
This should be overridden by model-specific implementations to provide accurate token counts via model-specific tokenizers.
| PARAMETER | DESCRIPTION |
|---|---|
text | The string input to tokenize. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
int | The integer number of tokens in the text. |
get_num_tokens_from_messages( messages: list[BaseMessage], tools: Sequence | None = None ) -> int Get the number of tokens in the messages.
Useful for checking if an input fits in a model's context window.
This should be overridden by model-specific implementations to provide accurate token counts via model-specific tokenizers.
Note
- The base implementation of
get_num_tokens_from_messagesignores tool schemas. - The base implementation of
get_num_tokens_from_messagesadds additional prefixes to messages in represent user roles, which will add to the overall token count. Model-specific implementations may choose to handle this differently.
| PARAMETER | DESCRIPTION |
|---|---|
messages | The message inputs to tokenize. TYPE: |
tools | If provided, sequence of dict, TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
int | The sum of the number of tokens across the messages. |
generate( prompts: list[str], stop: list[str] | None = None, callbacks: Callbacks | list[Callbacks] | None = None, *, tags: list[str] | list[list[str]] | None = None, metadata: dict[str, Any] | list[dict[str, Any]] | None = None, run_name: str | list[str] | None = None, run_id: UUID | list[UUID | None] | None = None, **kwargs: Any, ) -> LLMResult Pass a sequence of prompts to a model and return generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
prompts | List of string prompts. |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
tags | List of tags to associate with each prompt. If provided, the length of the list must match the length of the prompts list. |
metadata | List of metadata dictionaries to associate with each prompt. If provided, the length of the list must match the length of the prompts list. TYPE: |
run_name | List of run names to associate with each prompt. If provided, the length of the list must match the length of the prompts list. |
run_id | List of run IDs to associate with each prompt. If provided, the length of the list must match the length of the prompts list. |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If prompts is not a list. |
ValueError | If the length of |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
async ¶
agenerate( prompts: list[str], stop: list[str] | None = None, callbacks: Callbacks | list[Callbacks] | None = None, *, tags: list[str] | list[list[str]] | None = None, metadata: dict[str, Any] | list[dict[str, Any]] | None = None, run_name: str | list[str] | None = None, run_id: UUID | list[UUID | None] | None = None, **kwargs: Any, ) -> LLMResult Asynchronously pass a sequence of prompts to a model and return generations.
This method should make use of batched calls for models that expose a batched API.
Use this method when you want to:
- Take advantage of batched calls,
- Need more output from the model than just the top generated value,
- Are building chains that are agnostic to the underlying language model type (e.g., pure text completion models vs chat models).
| PARAMETER | DESCRIPTION |
|---|---|
prompts | List of string prompts. |
stop | Stop words to use when generating. Model output is cut off at the first occurrence of any of these substrings. |
callbacks |
Used for executing additional functionality, such as logging or streaming, throughout generation. TYPE: |
tags | List of tags to associate with each prompt. If provided, the length of the list must match the length of the prompts list. |
metadata | List of metadata dictionaries to associate with each prompt. If provided, the length of the list must match the length of the prompts list. TYPE: |
run_name | List of run names to associate with each prompt. If provided, the length of the list must match the length of the prompts list. |
run_id | List of run IDs to associate with each prompt. If provided, the length of the list must match the length of the prompts list. |
**kwargs | Arbitrary additional keyword arguments. These are usually passed to the model provider API call. TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If the length of |
| RETURNS | DESCRIPTION |
|---|---|
LLMResult | An |
Save the LLM.
| PARAMETER | DESCRIPTION |
|---|---|
file_path | Path to file to save the LLM to. |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If the file path is not a string or Path object. |
Bases: BaseRetriever
Amazon Kendra Index retriever.
| ATTRIBUTE | DESCRIPTION |
|---|---|
index_id | Kendra index id TYPE: |
region_name | The aws region e.g., TYPE: |
credentials_profile_name | The name of the profile in the TYPE: |
aws_access_key_id | AWS access key id. If provided, See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html If not provided, will be read from TYPE: |
aws_secret_access_key | AWS secret_access_key. If provided, See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html If not provided, will be read from TYPE: |
aws_session_token | AWS session token. If provided, See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html If not provided, will be read from TYPE: |
endpoint_url | Needed if you don't want to default to TYPE: |
config | An optional TYPE: |
top_k | No of results to return TYPE: |
attribute_filter | Additional filtering of results based on metadata TYPE: |
page_content_formatter | generates the Document page_content allowing access to all result item attributes. By default, it uses the item's title and excerpt. |
client | boto3 client for Kendra TYPE: |
user_context | Provides information about the user context See: https://docs.aws.amazon.com/kendra/latest/APIReference TYPE: |
| METHOD | DESCRIPTION |
|---|---|
get_name | Get the name of the |
get_input_schema | Get a Pydantic model that can be used to validate input to the |
get_input_jsonschema | Get a JSON schema that represents the input to the |
get_output_schema | Get a Pydantic model that can be used to validate output to the |
get_output_jsonschema | Get a JSON schema that represents the output of the |
config_schema | The type of config this |
get_config_jsonschema | Get a JSON schema that represents the config of the |
get_graph | Return a graph representation of this |
get_prompts | Return a list of prompts used by this |
__or__ | Runnable "or" operator. |
__ror__ | Runnable "reverse-or" operator. |
pipe | Pipe |
pick | Pick keys from the output |
assign | Assigns new fields to the |
invoke | Invoke the retriever to get relevant documents. |
ainvoke | Asynchronously invoke the retriever to get relevant documents. |
batch | Default implementation runs invoke in parallel using a thread pool executor. |
batch_as_completed | Run |
abatch | Default implementation runs |
abatch_as_completed | Run |
stream | Default implementation of |
astream | Default implementation of |
astream_log | Stream all output from a |
astream_events | Generate a stream of events. |
transform | Transform inputs to outputs. |
atransform | Transform inputs to outputs. |
bind | Bind arguments to a |
with_config | Bind config to a |
with_listeners | Bind lifecycle listeners to a |
with_alisteners | Bind async lifecycle listeners to a |
with_types | Bind input and output types to a |
with_retry | Create a new |
map | Return a new |
with_fallbacks | Add fallbacks to a |
as_tool | Create a |
__init__ | |
is_lc_serializable | Is this class serializable? |
get_lc_namespace | Get the namespace of the LangChain object. |
lc_id | Return a unique identifier for this class for serialization purposes. |
to_json | Serialize the |
to_json_not_implemented | Serialize a "not implemented" object. |
configurable_fields | Configure particular |
configurable_alternatives | Configure alternatives for |
class-attribute instance-attribute ¶
name: str | None = None The name of the Runnable. Used for debugging and tracing.
property ¶
InputType: type[Input] Input type.
The type of input this Runnable accepts specified as a type annotation.
| RAISES | DESCRIPTION |
|---|---|
TypeError | If the input type cannot be inferred. |
property ¶
OutputType: type[Output] Output Type.
The type of output this Runnable produces specified as a type annotation.
| RAISES | DESCRIPTION |
|---|---|
TypeError | If the output type cannot be inferred. |
property ¶
The type of input this Runnable accepts specified as a Pydantic model.
property ¶
Output schema.
The type of output this Runnable produces specified as a Pydantic model.
property ¶
config_specs: list[ConfigurableFieldSpec] List configurable fields for this Runnable.
property ¶
A map of constructor argument names to secret ids.
For example, {"openai_api_key": "OPENAI_API_KEY"}
property ¶
lc_attributes: dict List of attribute names that should be included in the serialized kwargs.
These attributes must be accepted by the constructor.
Default is an empty dictionary.
class-attribute instance-attribute ¶
Optional list of tags associated with the retriever.
These tags will be associated with each call to this retriever, and passed as arguments to the handlers defined in callbacks.
You can use these to eg identify a specific instance of a retriever with its use case.
class-attribute instance-attribute ¶
Optional metadata associated with the retriever.
This metadata will be associated with each call to this retriever, and passed as arguments to the handlers defined in callbacks.
You can use these to eg identify a specific instance of a retriever with its use case.
get_input_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate input to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate input. |
get_input_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the input to the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the input to the |
Example
Added in langchain-core 0.3.0
get_output_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate output to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate output. |
get_output_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the output of the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the output of the |
Example
Added in langchain-core 0.3.0
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.
| PARAMETER | DESCRIPTION |
|---|---|
include | A list of fields to include in the config schema. |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate config. |
get_graph(config: RunnableConfig | None = None) -> Graph Return a graph representation of this Runnable.
get_prompts(config: RunnableConfig | None = None) -> list[BasePromptTemplate] Return a list of prompts used by this Runnable.
__or__( other: Runnable[Any, Other] | Callable[[Iterator[Any]], Iterator[Other]] | Callable[[AsyncIterator[Any]], AsyncIterator[Other]] | Callable[[Any], Other] | Mapping[str, Runnable[Any, Other] | Callable[[Any], Other] | Any], ) -> RunnableSerializable[Input, Other] Runnable "or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
__ror__( other: Runnable[Other, Any] | Callable[[Iterator[Other]], Iterator[Any]] | Callable[[AsyncIterator[Other]], AsyncIterator[Any]] | Callable[[Other], Any] | Mapping[str, Runnable[Other, Any] | Callable[[Other], Any] | Any], ) -> RunnableSerializable[Other, Output] Runnable "reverse-or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Other, Output] | A new |
pipe( *others: Runnable[Any, Other] | Callable[[Any], Other], name: str | None = None ) -> RunnableSerializable[Input, Other] Pipe Runnable objects.
Compose this Runnable with Runnable-like objects to make a RunnableSequence.
Equivalent to RunnableSequence(self, *others) or self | others[0] | ...
Example
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] | PARAMETER | DESCRIPTION |
|---|---|
*others | Other TYPE: |
name | An optional name for the resulting TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
Pick keys from the output dict of this Runnable.
Pick a single key
import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) chain = RunnableMap(str=as_str, json=as_json) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3]} json_only_chain = chain.pick("json") json_only_chain.invoke("[1, 2, 3]") # -> [1, 2, 3] Pick a list of keys
from typing import Any import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) def as_bytes(x: Any) -> bytes: return bytes(x, "utf-8") chain = RunnableMap( str=as_str, json=as_json, bytes=RunnableLambda(as_bytes) ) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3], "bytes": b"[1, 2, 3]"} json_and_bytes_chain = chain.pick(["json", "bytes"]) json_and_bytes_chain.invoke("[1, 2, 3]") # -> {"json": [1, 2, 3], "bytes": b"[1, 2, 3]"} | PARAMETER | DESCRIPTION |
|---|---|
keys | A key or list of keys to pick from the output dict. |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | a new |
assign( **kwargs: Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any] | Mapping[str, Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any]], ) -> RunnableSerializable[Any, Any] Assigns new fields to the dict output of this Runnable.
from langchain_core.language_models.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}" ) model = FakeStreamingListLLM(responses=["foo-lish"]) chain: Runnable = prompt | model | {"str": StrOutputParser()} chain_with_assign = chain.assign(hello=itemgetter("str") | model) print(chain_with_assign.input_schema.model_json_schema()) # {'title': 'PromptInput', 'type': 'object', 'properties': {'question': {'title': 'Question', 'type': 'string'}}} print(chain_with_assign.output_schema.model_json_schema()) # {'title': 'RunnableSequenceOutput', 'type': 'object', 'properties': {'str': {'title': 'Str', 'type': 'string'}, 'hello': {'title': 'Hello', 'type': 'string'}}} | PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A mapping of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | A new |
invoke( input: str, config: RunnableConfig | None = None, **kwargs: Any ) -> list[Document] Invoke the retriever to get relevant documents.
Main entry point for synchronous retriever invocations.
| PARAMETER | DESCRIPTION |
|---|---|
input | The query string. TYPE: |
config | Configuration for the retriever. TYPE: |
**kwargs | Additional arguments to pass to the retriever. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of relevant documents. |
Examples:
async ¶
ainvoke( input: str, config: RunnableConfig | None = None, **kwargs: Any ) -> list[Document] Asynchronously invoke the retriever to get relevant documents.
Main entry point for asynchronous retriever invocations.
| PARAMETER | DESCRIPTION |
|---|---|
input | The query string. TYPE: |
config | Configuration for the retriever. TYPE: |
**kwargs | Additional arguments to pass to the retriever. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of relevant documents. |
Examples:
batch( inputs: list[Input], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> 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 must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
batch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> Iterator[tuple[int, Output | Exception]] Run invoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
tuple[int, Output | Exception] | Tuples of the index of the input and the output from the |
async ¶
abatch( inputs: list[Input], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> list[Output] Default implementation runs ainvoke in parallel using asyncio.gather.
The default implementation of batch works well for IO bound runnables.
Subclasses must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
async ¶
abatch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> AsyncIterator[tuple[int, Output | Exception]] Run ainvoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[tuple[int, Output | Exception]] | A tuple of the index of the input and the output from the |
stream( input: Input, config: RunnableConfig | None = None, **kwargs: Any | None ) -> Iterator[Output] Default implementation of stream, which calls invoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
astream( input: Input, config: RunnableConfig | None = None, **kwargs: Any | None ) -> AsyncIterator[Output] Default implementation of astream, which calls ainvoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
async ¶
astream_log( input: Any, config: RunnableConfig | None = None, *, diff: bool = True, with_streamed_output_list: bool = True, include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> 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.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
diff | Whether to yield diffs between each step or the current state. TYPE: |
with_streamed_output_list | Whether to yield the TYPE: |
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 TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[RunLogPatch] | AsyncIterator[RunLog] | A |
async ¶
astream_events( input: Any, config: RunnableConfig | None = None, *, version: Literal["v1", "v2"] = "v2", include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> AsyncIterator[StreamEvent] Generate a stream of events.
Use to create an iterator over StreamEvent that provide real-time information about the progress of the Runnable, including StreamEvent from intermediate results.
A StreamEvent is a dictionary with the following schema:
event: Event names are of the format:on_[runnable_type]_(start|stream|end).name: The name of theRunnablethat generated the event.run_id: Randomly generated ID associated with the given execution of theRunnablethat emitted the event. A childRunnablethat gets invoked as part of the execution of a parentRunnableis assigned its own unique ID.parent_ids: The IDs of the parent runnables that generated the event. The rootRunnablewill 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: The tags of theRunnablethat generated the event.metadata: The metadata of theRunnablethat generated the event.data: The data associated with the event. The contents of this field depend on the type of event. See the table below for more details.
Below is a table that illustrates some events 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.
Note
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:
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:
prompt:
template = ChatPromptTemplate.from_messages( [ ("system", "You are Cat Agent 007"), ("human", "{question}"), ] ).with_config({"run_name": "my_template", "tags": ["my_template"]}) Example
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": [], }, ] 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) | PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
version | The version of the schema to use, either Users should use
No default will be assigned until the API is stabilized. custom events will only be surfaced in TYPE: |
include_names | Only include events from |
include_types | Only include events from |
include_tags | Only include events from |
exclude_names | Exclude events from |
exclude_types | Exclude events from |
exclude_tags | Exclude events from |
**kwargs | Additional keyword arguments to pass to the These will be passed to TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[StreamEvent] | An async stream of |
| RAISES | DESCRIPTION |
|---|---|
NotImplementedError | If the version is not |
transform( input: Iterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None ) -> Iterator[Output] Transform inputs to outputs.
Default implementation of transform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
atransform( input: AsyncIterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None, ) -> AsyncIterator[Output] Transform inputs to outputs.
Default implementation of atransform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An async iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
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.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | The arguments to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_ollama import ChatOllama from langchain_core.output_parsers import StrOutputParser model = ChatOllama(model="llama3.1") # Without bind chain = model | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two three four five.' # With bind chain = model.bind(stop=["three"]) | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two'
with_config( config: RunnableConfig | None = None, **kwargs: Any ) -> Runnable[Input, Output] Bind config to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | The config to bind to the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_listeners( *, on_start: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_end: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_error: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, ) -> Runnable[Input, Output] Bind lifecycle listeners to a Runnable, returning a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called before the TYPE: |
on_end | Called after the TYPE: |
on_error | Called if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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)
with_alisteners( *, on_start: AsyncListener | None = None, on_end: AsyncListener | None = None, on_error: AsyncListener | None = None, ) -> Runnable[Input, Output] Bind async lifecycle listeners to a Runnable.
Returns a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called asynchronously before the TYPE: |
on_end | Called asynchronously after the TYPE: |
on_error | Called asynchronously if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_core.runnables import RunnableLambda, Runnable from datetime import datetime, timezone import time import asyncio def format_t(timestamp: float) -> str: return datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat() 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 2025-03-01T07:05:22.875378+00:00 # on start callback starts at 2025-03-01T07:05:22.875495+00:00 # on start callback ends at 2025-03-01T07:05:25.878862+00:00 # on start callback ends at 2025-03-01T07:05:25.878947+00:00 # Runnable[2s]: starts at 2025-03-01T07:05:25.879392+00:00 # Runnable[3s]: starts at 2025-03-01T07:05:25.879804+00:00 # Runnable[2s]: ends at 2025-03-01T07:05:27.881998+00:00 # on end callback starts at 2025-03-01T07:05:27.882360+00:00 # Runnable[3s]: ends at 2025-03-01T07:05:28.881737+00:00 # on end callback starts at 2025-03-01T07:05:28.882428+00:00 # on end callback ends at 2025-03-01T07:05:29.883893+00:00 # on end callback ends at 2025-03-01T07:05:30.884831+00:00
with_types( *, input_type: type[Input] | None = None, output_type: type[Output] | None = None ) -> Runnable[Input, Output] Bind input and output types to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
input_type | The input type to bind to the TYPE: |
output_type | The output type to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_retry( *, retry_if_exception_type: tuple[type[BaseException], ...] = (Exception,), wait_exponential_jitter: bool = True, exponential_jitter_params: ExponentialJitterParams | None = None, stop_after_attempt: int = 3, ) -> Runnable[Input, Output] Create a new Runnable that retries the original Runnable on exceptions.
| PARAMETER | DESCRIPTION |
|---|---|
retry_if_exception_type | A tuple of exception types to retry on. TYPE: |
wait_exponential_jitter | Whether to add jitter to the wait time between retries. TYPE: |
stop_after_attempt | The maximum number of attempts to make before giving up. TYPE: |
exponential_jitter_params | Parameters for TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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
with_fallbacks( fallbacks: Sequence[Runnable[Input, Output]], *, exceptions_to_handle: tuple[type[BaseException], ...] = (Exception,), exception_key: str | None = None, ) -> RunnableWithFallbacks[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.
| PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
Example
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 | PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
as_tool( args_schema: type[BaseModel] | None = None, *, name: str | None = None, description: str | None = None, arg_types: dict[str, type] | None = 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.
| PARAMETER | DESCRIPTION |
|---|---|
args_schema | The schema for the tool. |
name | The name of the tool. TYPE: |
description | The description of the tool. TYPE: |
arg_types | A dictionary of argument names to types. |
| RETURNS | DESCRIPTION |
|---|---|
BaseTool | A |
TypedDict input
dict input, specifying schema via args_schema
from typing import Any from pydantic 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
classmethod ¶
is_lc_serializable() -> bool Is this class serializable?
By design, even if a class inherits from Serializable, it is not serializable by default. This is to prevent accidental serialization of objects that should not be serialized.
| RETURNS | DESCRIPTION |
|---|---|
bool | Whether the class is serializable. Default is |
classmethod ¶
classmethod ¶
Return a unique identifier for this class for serialization purposes.
The unique identifier is a list of strings that describes the path to the object.
For example, for the class langchain.llms.openai.OpenAI, the id is ["langchain", "llms", "openai", "OpenAI"].
Serialize the Runnable to JSON.
| RETURNS | DESCRIPTION |
|---|---|
SerializedConstructor | SerializedNotImplemented | A JSON-serializable representation of the |
Serialize a "not implemented" object.
| RETURNS | DESCRIPTION |
|---|---|
SerializedNotImplemented |
|
configurable_fields( **kwargs: AnyConfigurableField, ) -> RunnableSerializable[Input, Output] Configure particular Runnable fields at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A dictionary of TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If a configuration key is not found in the |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
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, )
configurable_alternatives( which: ConfigurableField, *, default_key: str = "default", prefix_keys: bool = False, **kwargs: Runnable[Input, Output] | Callable[[], Runnable[Input, Output]], ) -> RunnableSerializable[Input, Output] Configure alternatives for Runnable objects that can be set at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
which | The TYPE: |
default_key | The default key to use if no alternative is selected. TYPE: |
prefix_keys | Whether to prefix the keys with the TYPE: |
**kwargs | A dictionary of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
from langchain_anthropic import ChatAnthropic from langchain_core.runnables.utils import ConfigurableField from langchain_openai import ChatOpenAI model = ChatAnthropic( model_name="claude-sonnet-4-5-20250929" ).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 )
Bases: BaseRetriever
Amazon Bedrock Knowledge Bases retrieval.
See https://aws.amazon.com/bedrock/knowledge-bases for more info.
| ATTRIBUTE | DESCRIPTION |
|---|---|
knowledge_base_id | Knowledge Base ID. TYPE: |
region_name | The aws region e.g., TYPE: |
credentials_profile_name | The name of the profile in the TYPE: |
aws_access_key_id | AWS access key id. If provided, TYPE: |
aws_secret_access_key | AWS TYPE: |
aws_session_token | AWS session token. If provided, TYPE: |
endpoint_url | Needed if you don't want to default to TYPE: |
config | An optional TYPE: |
client | boto3 client for bedrock agent runtime. TYPE: |
guardrail_config | Configuration information for a guardrail that you want to use in the request. |
retrieval_config | Optional configuration for retrieval specified as a Python object (RetrievalConfig) or as a dictionary. |
min_score_confidence | Minimum score confidence threshold for filtering results (0.0 to 1.0). TYPE: |
Example
| METHOD | DESCRIPTION |
|---|---|
get_name | Get the name of the |
get_input_schema | Get a Pydantic model that can be used to validate input to the |
get_input_jsonschema | Get a JSON schema that represents the input to the |
get_output_schema | Get a Pydantic model that can be used to validate output to the |
get_output_jsonschema | Get a JSON schema that represents the output of the |
config_schema | The type of config this |
get_config_jsonschema | Get a JSON schema that represents the config of the |
get_graph | Return a graph representation of this |
get_prompts | Return a list of prompts used by this |
__or__ | Runnable "or" operator. |
__ror__ | Runnable "reverse-or" operator. |
pipe | Pipe |
pick | Pick keys from the output |
assign | Assigns new fields to the |
invoke | Invoke the retriever to get relevant documents. |
ainvoke | Asynchronously invoke the retriever to get relevant documents. |
batch | Default implementation runs invoke in parallel using a thread pool executor. |
batch_as_completed | Run |
abatch | Default implementation runs |
abatch_as_completed | Run |
stream | Default implementation of |
astream | Default implementation of |
astream_log | Stream all output from a |
astream_events | Generate a stream of events. |
transform | Transform inputs to outputs. |
atransform | Transform inputs to outputs. |
bind | Bind arguments to a |
with_config | Bind config to a |
with_listeners | Bind lifecycle listeners to a |
with_alisteners | Bind async lifecycle listeners to a |
with_types | Bind input and output types to a |
with_retry | Create a new |
map | Return a new |
with_fallbacks | Add fallbacks to a |
as_tool | Create a |
__init__ | |
is_lc_serializable | Is this class serializable? |
get_lc_namespace | Get the namespace of the LangChain object. |
lc_id | Return a unique identifier for this class for serialization purposes. |
to_json | Serialize the |
to_json_not_implemented | Serialize a "not implemented" object. |
configurable_fields | Configure particular |
configurable_alternatives | Configure alternatives for |
class-attribute instance-attribute ¶
name: str | None = None The name of the Runnable. Used for debugging and tracing.
property ¶
InputType: type[Input] Input type.
The type of input this Runnable accepts specified as a type annotation.
| RAISES | DESCRIPTION |
|---|---|
TypeError | If the input type cannot be inferred. |
property ¶
OutputType: type[Output] Output Type.
The type of output this Runnable produces specified as a type annotation.
| RAISES | DESCRIPTION |
|---|---|
TypeError | If the output type cannot be inferred. |
property ¶
The type of input this Runnable accepts specified as a Pydantic model.
property ¶
Output schema.
The type of output this Runnable produces specified as a Pydantic model.
property ¶
config_specs: list[ConfigurableFieldSpec] List configurable fields for this Runnable.
property ¶
A map of constructor argument names to secret ids.
For example, {"openai_api_key": "OPENAI_API_KEY"}
property ¶
lc_attributes: dict List of attribute names that should be included in the serialized kwargs.
These attributes must be accepted by the constructor.
Default is an empty dictionary.
class-attribute instance-attribute ¶
Optional list of tags associated with the retriever.
These tags will be associated with each call to this retriever, and passed as arguments to the handlers defined in callbacks.
You can use these to eg identify a specific instance of a retriever with its use case.
class-attribute instance-attribute ¶
Optional metadata associated with the retriever.
This metadata will be associated with each call to this retriever, and passed as arguments to the handlers defined in callbacks.
You can use these to eg identify a specific instance of a retriever with its use case.
get_input_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate input to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate input. |
get_input_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the input to the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the input to the |
Example
Added in langchain-core 0.3.0
get_output_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate output to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate output. |
get_output_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the output of the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the output of the |
Example
Added in langchain-core 0.3.0
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.
| PARAMETER | DESCRIPTION |
|---|---|
include | A list of fields to include in the config schema. |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate config. |
get_graph(config: RunnableConfig | None = None) -> Graph Return a graph representation of this Runnable.
get_prompts(config: RunnableConfig | None = None) -> list[BasePromptTemplate] Return a list of prompts used by this Runnable.
__or__( other: Runnable[Any, Other] | Callable[[Iterator[Any]], Iterator[Other]] | Callable[[AsyncIterator[Any]], AsyncIterator[Other]] | Callable[[Any], Other] | Mapping[str, Runnable[Any, Other] | Callable[[Any], Other] | Any], ) -> RunnableSerializable[Input, Other] Runnable "or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
__ror__( other: Runnable[Other, Any] | Callable[[Iterator[Other]], Iterator[Any]] | Callable[[AsyncIterator[Other]], AsyncIterator[Any]] | Callable[[Other], Any] | Mapping[str, Runnable[Other, Any] | Callable[[Other], Any] | Any], ) -> RunnableSerializable[Other, Output] Runnable "reverse-or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Other, Output] | A new |
pipe( *others: Runnable[Any, Other] | Callable[[Any], Other], name: str | None = None ) -> RunnableSerializable[Input, Other] Pipe Runnable objects.
Compose this Runnable with Runnable-like objects to make a RunnableSequence.
Equivalent to RunnableSequence(self, *others) or self | others[0] | ...
Example
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] | PARAMETER | DESCRIPTION |
|---|---|
*others | Other TYPE: |
name | An optional name for the resulting TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
Pick keys from the output dict of this Runnable.
Pick a single key
import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) chain = RunnableMap(str=as_str, json=as_json) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3]} json_only_chain = chain.pick("json") json_only_chain.invoke("[1, 2, 3]") # -> [1, 2, 3] Pick a list of keys
from typing import Any import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) def as_bytes(x: Any) -> bytes: return bytes(x, "utf-8") chain = RunnableMap( str=as_str, json=as_json, bytes=RunnableLambda(as_bytes) ) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3], "bytes": b"[1, 2, 3]"} json_and_bytes_chain = chain.pick(["json", "bytes"]) json_and_bytes_chain.invoke("[1, 2, 3]") # -> {"json": [1, 2, 3], "bytes": b"[1, 2, 3]"} | PARAMETER | DESCRIPTION |
|---|---|
keys | A key or list of keys to pick from the output dict. |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | a new |
assign( **kwargs: Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any] | Mapping[str, Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any]], ) -> RunnableSerializable[Any, Any] Assigns new fields to the dict output of this Runnable.
from langchain_core.language_models.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}" ) model = FakeStreamingListLLM(responses=["foo-lish"]) chain: Runnable = prompt | model | {"str": StrOutputParser()} chain_with_assign = chain.assign(hello=itemgetter("str") | model) print(chain_with_assign.input_schema.model_json_schema()) # {'title': 'PromptInput', 'type': 'object', 'properties': {'question': {'title': 'Question', 'type': 'string'}}} print(chain_with_assign.output_schema.model_json_schema()) # {'title': 'RunnableSequenceOutput', 'type': 'object', 'properties': {'str': {'title': 'Str', 'type': 'string'}, 'hello': {'title': 'Hello', 'type': 'string'}}} | PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A mapping of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | A new |
invoke( input: str, config: RunnableConfig | None = None, **kwargs: Any ) -> list[Document] Invoke the retriever to get relevant documents.
Main entry point for synchronous retriever invocations.
| PARAMETER | DESCRIPTION |
|---|---|
input | The query string. TYPE: |
config | Configuration for the retriever. TYPE: |
**kwargs | Additional arguments to pass to the retriever. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of relevant documents. |
Examples:
async ¶
ainvoke( input: str, config: RunnableConfig | None = None, **kwargs: Any ) -> list[Document] Asynchronously invoke the retriever to get relevant documents.
Main entry point for asynchronous retriever invocations.
| PARAMETER | DESCRIPTION |
|---|---|
input | The query string. TYPE: |
config | Configuration for the retriever. TYPE: |
**kwargs | Additional arguments to pass to the retriever. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of relevant documents. |
Examples:
batch( inputs: list[Input], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> 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 must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
batch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> Iterator[tuple[int, Output | Exception]] Run invoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
tuple[int, Output | Exception] | Tuples of the index of the input and the output from the |
async ¶
abatch( inputs: list[Input], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> list[Output] Default implementation runs ainvoke in parallel using asyncio.gather.
The default implementation of batch works well for IO bound runnables.
Subclasses must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
async ¶
abatch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> AsyncIterator[tuple[int, Output | Exception]] Run ainvoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[tuple[int, Output | Exception]] | A tuple of the index of the input and the output from the |
stream( input: Input, config: RunnableConfig | None = None, **kwargs: Any | None ) -> Iterator[Output] Default implementation of stream, which calls invoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
astream( input: Input, config: RunnableConfig | None = None, **kwargs: Any | None ) -> AsyncIterator[Output] Default implementation of astream, which calls ainvoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
async ¶
astream_log( input: Any, config: RunnableConfig | None = None, *, diff: bool = True, with_streamed_output_list: bool = True, include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> 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.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
diff | Whether to yield diffs between each step or the current state. TYPE: |
with_streamed_output_list | Whether to yield the TYPE: |
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 TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[RunLogPatch] | AsyncIterator[RunLog] | A |
async ¶
astream_events( input: Any, config: RunnableConfig | None = None, *, version: Literal["v1", "v2"] = "v2", include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> AsyncIterator[StreamEvent] Generate a stream of events.
Use to create an iterator over StreamEvent that provide real-time information about the progress of the Runnable, including StreamEvent from intermediate results.
A StreamEvent is a dictionary with the following schema:
event: Event names are of the format:on_[runnable_type]_(start|stream|end).name: The name of theRunnablethat generated the event.run_id: Randomly generated ID associated with the given execution of theRunnablethat emitted the event. A childRunnablethat gets invoked as part of the execution of a parentRunnableis assigned its own unique ID.parent_ids: The IDs of the parent runnables that generated the event. The rootRunnablewill 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: The tags of theRunnablethat generated the event.metadata: The metadata of theRunnablethat generated the event.data: The data associated with the event. The contents of this field depend on the type of event. See the table below for more details.
Below is a table that illustrates some events 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.
Note
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:
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:
prompt:
template = ChatPromptTemplate.from_messages( [ ("system", "You are Cat Agent 007"), ("human", "{question}"), ] ).with_config({"run_name": "my_template", "tags": ["my_template"]}) Example
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": [], }, ] 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) | PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
version | The version of the schema to use, either Users should use
No default will be assigned until the API is stabilized. custom events will only be surfaced in TYPE: |
include_names | Only include events from |
include_types | Only include events from |
include_tags | Only include events from |
exclude_names | Exclude events from |
exclude_types | Exclude events from |
exclude_tags | Exclude events from |
**kwargs | Additional keyword arguments to pass to the These will be passed to TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[StreamEvent] | An async stream of |
| RAISES | DESCRIPTION |
|---|---|
NotImplementedError | If the version is not |
transform( input: Iterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None ) -> Iterator[Output] Transform inputs to outputs.
Default implementation of transform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
atransform( input: AsyncIterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None, ) -> AsyncIterator[Output] Transform inputs to outputs.
Default implementation of atransform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An async iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
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.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | The arguments to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_ollama import ChatOllama from langchain_core.output_parsers import StrOutputParser model = ChatOllama(model="llama3.1") # Without bind chain = model | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two three four five.' # With bind chain = model.bind(stop=["three"]) | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two'
with_config( config: RunnableConfig | None = None, **kwargs: Any ) -> Runnable[Input, Output] Bind config to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | The config to bind to the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_listeners( *, on_start: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_end: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_error: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, ) -> Runnable[Input, Output] Bind lifecycle listeners to a Runnable, returning a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called before the TYPE: |
on_end | Called after the TYPE: |
on_error | Called if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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)
with_alisteners( *, on_start: AsyncListener | None = None, on_end: AsyncListener | None = None, on_error: AsyncListener | None = None, ) -> Runnable[Input, Output] Bind async lifecycle listeners to a Runnable.
Returns a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called asynchronously before the TYPE: |
on_end | Called asynchronously after the TYPE: |
on_error | Called asynchronously if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_core.runnables import RunnableLambda, Runnable from datetime import datetime, timezone import time import asyncio def format_t(timestamp: float) -> str: return datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat() 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 2025-03-01T07:05:22.875378+00:00 # on start callback starts at 2025-03-01T07:05:22.875495+00:00 # on start callback ends at 2025-03-01T07:05:25.878862+00:00 # on start callback ends at 2025-03-01T07:05:25.878947+00:00 # Runnable[2s]: starts at 2025-03-01T07:05:25.879392+00:00 # Runnable[3s]: starts at 2025-03-01T07:05:25.879804+00:00 # Runnable[2s]: ends at 2025-03-01T07:05:27.881998+00:00 # on end callback starts at 2025-03-01T07:05:27.882360+00:00 # Runnable[3s]: ends at 2025-03-01T07:05:28.881737+00:00 # on end callback starts at 2025-03-01T07:05:28.882428+00:00 # on end callback ends at 2025-03-01T07:05:29.883893+00:00 # on end callback ends at 2025-03-01T07:05:30.884831+00:00
with_types( *, input_type: type[Input] | None = None, output_type: type[Output] | None = None ) -> Runnable[Input, Output] Bind input and output types to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
input_type | The input type to bind to the TYPE: |
output_type | The output type to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_retry( *, retry_if_exception_type: tuple[type[BaseException], ...] = (Exception,), wait_exponential_jitter: bool = True, exponential_jitter_params: ExponentialJitterParams | None = None, stop_after_attempt: int = 3, ) -> Runnable[Input, Output] Create a new Runnable that retries the original Runnable on exceptions.
| PARAMETER | DESCRIPTION |
|---|---|
retry_if_exception_type | A tuple of exception types to retry on. TYPE: |
wait_exponential_jitter | Whether to add jitter to the wait time between retries. TYPE: |
stop_after_attempt | The maximum number of attempts to make before giving up. TYPE: |
exponential_jitter_params | Parameters for TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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
with_fallbacks( fallbacks: Sequence[Runnable[Input, Output]], *, exceptions_to_handle: tuple[type[BaseException], ...] = (Exception,), exception_key: str | None = None, ) -> RunnableWithFallbacks[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.
| PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
Example
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 | PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
as_tool( args_schema: type[BaseModel] | None = None, *, name: str | None = None, description: str | None = None, arg_types: dict[str, type] | None = 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.
| PARAMETER | DESCRIPTION |
|---|---|
args_schema | The schema for the tool. |
name | The name of the tool. TYPE: |
description | The description of the tool. TYPE: |
arg_types | A dictionary of argument names to types. |
| RETURNS | DESCRIPTION |
|---|---|
BaseTool | A |
TypedDict input
dict input, specifying schema via args_schema
from typing import Any from pydantic 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
classmethod ¶
is_lc_serializable() -> bool Is this class serializable?
By design, even if a class inherits from Serializable, it is not serializable by default. This is to prevent accidental serialization of objects that should not be serialized.
| RETURNS | DESCRIPTION |
|---|---|
bool | Whether the class is serializable. Default is |
classmethod ¶
classmethod ¶
Return a unique identifier for this class for serialization purposes.
The unique identifier is a list of strings that describes the path to the object.
For example, for the class langchain.llms.openai.OpenAI, the id is ["langchain", "llms", "openai", "OpenAI"].
Serialize the Runnable to JSON.
| RETURNS | DESCRIPTION |
|---|---|
SerializedConstructor | SerializedNotImplemented | A JSON-serializable representation of the |
Serialize a "not implemented" object.
| RETURNS | DESCRIPTION |
|---|---|
SerializedNotImplemented |
|
configurable_fields( **kwargs: AnyConfigurableField, ) -> RunnableSerializable[Input, Output] Configure particular Runnable fields at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A dictionary of TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If a configuration key is not found in the |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
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, )
configurable_alternatives( which: ConfigurableField, *, default_key: str = "default", prefix_keys: bool = False, **kwargs: Runnable[Input, Output] | Callable[[], Runnable[Input, Output]], ) -> RunnableSerializable[Input, Output] Configure alternatives for Runnable objects that can be set at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
which | The TYPE: |
default_key | The default key to use if no alternative is selected. TYPE: |
prefix_keys | Whether to prefix the keys with the TYPE: |
**kwargs | A dictionary of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
from langchain_anthropic import ChatAnthropic from langchain_core.runnables.utils import ConfigurableField from langchain_openai import ChatOpenAI model = ChatAnthropic( model_name="claude-sonnet-4-5-20250929" ).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 )
Bases: VectorStoreRetriever
AmazonS3VectorsRetriever is a retriever for Amazon S3 Vectors.
Examples:
from langchain_aws.vectorstores import AmazonS3Vectors vector_store = AmazonS3Vectors(...) retriever = vector_store.as_retriever() | METHOD | DESCRIPTION |
|---|---|
get_name | Get the name of the |
get_input_schema | Get a Pydantic model that can be used to validate input to the |
get_input_jsonschema | Get a JSON schema that represents the input to the |
get_output_schema | Get a Pydantic model that can be used to validate output to the |
get_output_jsonschema | Get a JSON schema that represents the output of the |
config_schema | The type of config this |
get_config_jsonschema | Get a JSON schema that represents the config of the |
get_graph | Return a graph representation of this |
get_prompts | Return a list of prompts used by this |
__or__ | Runnable "or" operator. |
__ror__ | Runnable "reverse-or" operator. |
pipe | Pipe |
pick | Pick keys from the output |
assign | Assigns new fields to the |
invoke | Invoke the retriever to get relevant documents. |
ainvoke | Asynchronously invoke the retriever to get relevant documents. |
batch | Default implementation runs invoke in parallel using a thread pool executor. |
batch_as_completed | Run |
abatch | Default implementation runs |
abatch_as_completed | Run |
stream | Default implementation of |
astream | Default implementation of |
astream_log | Stream all output from a |
astream_events | Generate a stream of events. |
transform | Transform inputs to outputs. |
atransform | Transform inputs to outputs. |
bind | Bind arguments to a |
with_config | Bind config to a |
with_listeners | Bind lifecycle listeners to a |
with_alisteners | Bind async lifecycle listeners to a |
with_types | Bind input and output types to a |
with_retry | Create a new |
map | Return a new |
with_fallbacks | Add fallbacks to a |
as_tool | Create a |
__init__ | |
is_lc_serializable | Is this class serializable? |
get_lc_namespace | Get the namespace of the LangChain object. |
lc_id | Return a unique identifier for this class for serialization purposes. |
to_json | Serialize the |
to_json_not_implemented | Serialize a "not implemented" object. |
configurable_fields | Configure particular |
configurable_alternatives | Configure alternatives for |
validate_search_type | Validate search type. |
add_documents | Add documents to the |
aadd_documents | Async add documents to the |
class-attribute instance-attribute ¶
name: str | None = None The name of the Runnable. Used for debugging and tracing.
property ¶
InputType: type[Input] Input type.
The type of input this Runnable accepts specified as a type annotation.
| RAISES | DESCRIPTION |
|---|---|
TypeError | If the input type cannot be inferred. |
property ¶
OutputType: type[Output] Output Type.
The type of output this Runnable produces specified as a type annotation.
| RAISES | DESCRIPTION |
|---|---|
TypeError | If the output type cannot be inferred. |
property ¶
The type of input this Runnable accepts specified as a Pydantic model.
property ¶
Output schema.
The type of output this Runnable produces specified as a Pydantic model.
property ¶
config_specs: list[ConfigurableFieldSpec] List configurable fields for this Runnable.
property ¶
A map of constructor argument names to secret ids.
For example, {"openai_api_key": "OPENAI_API_KEY"}
property ¶
lc_attributes: dict List of attribute names that should be included in the serialized kwargs.
These attributes must be accepted by the constructor.
Default is an empty dictionary.
class-attribute instance-attribute ¶
Optional list of tags associated with the retriever.
These tags will be associated with each call to this retriever, and passed as arguments to the handlers defined in callbacks.
You can use these to eg identify a specific instance of a retriever with its use case.
class-attribute instance-attribute ¶
Optional metadata associated with the retriever.
This metadata will be associated with each call to this retriever, and passed as arguments to the handlers defined in callbacks.
You can use these to eg identify a specific instance of a retriever with its use case.
class-attribute instance-attribute ¶
search_type: str = 'similarity' Type of search to perform.
class-attribute instance-attribute ¶
Keyword arguments to pass to the search function.
get_input_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate input to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate input. |
get_input_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the input to the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the input to the |
Example
Added in langchain-core 0.3.0
get_output_schema(config: RunnableConfig | None = None) -> type[BaseModel] Get a Pydantic model that can be used to validate output to the Runnable.
Runnable objects 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.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate output. |
get_output_jsonschema(config: RunnableConfig | None = None) -> dict[str, Any] Get a JSON schema that represents the output of the Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | A config to use when generating the schema. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any] | A JSON schema that represents the output of the |
Example
Added in langchain-core 0.3.0
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.
| PARAMETER | DESCRIPTION |
|---|---|
include | A list of fields to include in the config schema. |
| RETURNS | DESCRIPTION |
|---|---|
type[BaseModel] | A Pydantic model that can be used to validate config. |
get_graph(config: RunnableConfig | None = None) -> Graph Return a graph representation of this Runnable.
get_prompts(config: RunnableConfig | None = None) -> list[BasePromptTemplate] Return a list of prompts used by this Runnable.
__or__( other: Runnable[Any, Other] | Callable[[Iterator[Any]], Iterator[Other]] | Callable[[AsyncIterator[Any]], AsyncIterator[Other]] | Callable[[Any], Other] | Mapping[str, Runnable[Any, Other] | Callable[[Any], Other] | Any], ) -> RunnableSerializable[Input, Other] Runnable "or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
__ror__( other: Runnable[Other, Any] | Callable[[Iterator[Other]], Iterator[Any]] | Callable[[AsyncIterator[Other]], AsyncIterator[Any]] | Callable[[Other], Any] | Mapping[str, Runnable[Other, Any] | Callable[[Other], Any] | Any], ) -> RunnableSerializable[Other, Output] Runnable "reverse-or" operator.
Compose this Runnable with another object to create a RunnableSequence.
| PARAMETER | DESCRIPTION |
|---|---|
other | Another TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Other, Output] | A new |
pipe( *others: Runnable[Any, Other] | Callable[[Any], Other], name: str | None = None ) -> RunnableSerializable[Input, Other] Pipe Runnable objects.
Compose this Runnable with Runnable-like objects to make a RunnableSequence.
Equivalent to RunnableSequence(self, *others) or self | others[0] | ...
Example
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] | PARAMETER | DESCRIPTION |
|---|---|
*others | Other TYPE: |
name | An optional name for the resulting TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Other] | A new |
Pick keys from the output dict of this Runnable.
Pick a single key
import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) chain = RunnableMap(str=as_str, json=as_json) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3]} json_only_chain = chain.pick("json") json_only_chain.invoke("[1, 2, 3]") # -> [1, 2, 3] Pick a list of keys
from typing import Any import json from langchain_core.runnables import RunnableLambda, RunnableMap as_str = RunnableLambda(str) as_json = RunnableLambda(json.loads) def as_bytes(x: Any) -> bytes: return bytes(x, "utf-8") chain = RunnableMap( str=as_str, json=as_json, bytes=RunnableLambda(as_bytes) ) chain.invoke("[1, 2, 3]") # -> {"str": "[1, 2, 3]", "json": [1, 2, 3], "bytes": b"[1, 2, 3]"} json_and_bytes_chain = chain.pick(["json", "bytes"]) json_and_bytes_chain.invoke("[1, 2, 3]") # -> {"json": [1, 2, 3], "bytes": b"[1, 2, 3]"} | PARAMETER | DESCRIPTION |
|---|---|
keys | A key or list of keys to pick from the output dict. |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | a new |
assign( **kwargs: Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any] | Mapping[str, Runnable[dict[str, Any], Any] | Callable[[dict[str, Any]], Any]], ) -> RunnableSerializable[Any, Any] Assigns new fields to the dict output of this Runnable.
from langchain_core.language_models.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}" ) model = FakeStreamingListLLM(responses=["foo-lish"]) chain: Runnable = prompt | model | {"str": StrOutputParser()} chain_with_assign = chain.assign(hello=itemgetter("str") | model) print(chain_with_assign.input_schema.model_json_schema()) # {'title': 'PromptInput', 'type': 'object', 'properties': {'question': {'title': 'Question', 'type': 'string'}}} print(chain_with_assign.output_schema.model_json_schema()) # {'title': 'RunnableSequenceOutput', 'type': 'object', 'properties': {'str': {'title': 'Str', 'type': 'string'}, 'hello': {'title': 'Hello', 'type': 'string'}}} | PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A mapping of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Any, Any] | A new |
invoke( input: str, config: RunnableConfig | None = None, **kwargs: Any ) -> list[Document] Invoke the retriever to get relevant documents.
Main entry point for synchronous retriever invocations.
| PARAMETER | DESCRIPTION |
|---|---|
input | The query string. TYPE: |
config | Configuration for the retriever. TYPE: |
**kwargs | Additional arguments to pass to the retriever. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of relevant documents. |
Examples:
async ¶
ainvoke( input: str, config: RunnableConfig | None = None, **kwargs: Any ) -> list[Document] Asynchronously invoke the retriever to get relevant documents.
Main entry point for asynchronous retriever invocations.
| PARAMETER | DESCRIPTION |
|---|---|
input | The query string. TYPE: |
config | Configuration for the retriever. TYPE: |
**kwargs | Additional arguments to pass to the retriever. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of relevant documents. |
Examples:
batch( inputs: list[Input], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> 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 must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
batch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> Iterator[tuple[int, Output | Exception]] Run invoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
tuple[int, Output | Exception] | Tuples of the index of the input and the output from the |
async ¶
abatch( inputs: list[Input], config: RunnableConfig | list[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> list[Output] Default implementation runs ainvoke in parallel using asyncio.gather.
The default implementation of batch works well for IO bound runnables.
Subclasses must override this method if they can batch more efficiently; e.g., if the underlying Runnable uses an API which supports a batch mode.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Output] | A list of outputs from the |
async ¶
abatch_as_completed( inputs: Sequence[Input], config: RunnableConfig | Sequence[RunnableConfig] | None = None, *, return_exceptions: bool = False, **kwargs: Any | None, ) -> AsyncIterator[tuple[int, Output | Exception]] Run ainvoke in parallel on a list of inputs.
Yields results as they complete.
| PARAMETER | DESCRIPTION |
|---|---|
inputs | A list of inputs to the TYPE: |
config | A config to use when invoking the The config supports standard keys like Please refer to TYPE: |
return_exceptions | Whether to return exceptions instead of raising them. TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[tuple[int, Output | Exception]] | A tuple of the index of the input and the output from the |
stream( input: Input, config: RunnableConfig | None = None, **kwargs: Any | None ) -> Iterator[Output] Default implementation of stream, which calls invoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
astream( input: Input, config: RunnableConfig | None = None, **kwargs: Any | None ) -> AsyncIterator[Output] Default implementation of astream, which calls ainvoke.
Subclasses must override this method if they support streaming output.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
async ¶
astream_log( input: Any, config: RunnableConfig | None = None, *, diff: bool = True, with_streamed_output_list: bool = True, include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> 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.
| PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
diff | Whether to yield diffs between each step or the current state. TYPE: |
with_streamed_output_list | Whether to yield the TYPE: |
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 TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[RunLogPatch] | AsyncIterator[RunLog] | A |
async ¶
astream_events( input: Any, config: RunnableConfig | None = None, *, version: Literal["v1", "v2"] = "v2", include_names: Sequence[str] | None = None, include_types: Sequence[str] | None = None, include_tags: Sequence[str] | None = None, exclude_names: Sequence[str] | None = None, exclude_types: Sequence[str] | None = None, exclude_tags: Sequence[str] | None = None, **kwargs: Any, ) -> AsyncIterator[StreamEvent] Generate a stream of events.
Use to create an iterator over StreamEvent that provide real-time information about the progress of the Runnable, including StreamEvent from intermediate results.
A StreamEvent is a dictionary with the following schema:
event: Event names are of the format:on_[runnable_type]_(start|stream|end).name: The name of theRunnablethat generated the event.run_id: Randomly generated ID associated with the given execution of theRunnablethat emitted the event. A childRunnablethat gets invoked as part of the execution of a parentRunnableis assigned its own unique ID.parent_ids: The IDs of the parent runnables that generated the event. The rootRunnablewill 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: The tags of theRunnablethat generated the event.metadata: The metadata of theRunnablethat generated the event.data: The data associated with the event. The contents of this field depend on the type of event. See the table below for more details.
Below is a table that illustrates some events 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.
Note
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:
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:
prompt:
template = ChatPromptTemplate.from_messages( [ ("system", "You are Cat Agent 007"), ("human", "{question}"), ] ).with_config({"run_name": "my_template", "tags": ["my_template"]}) Example
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": [], }, ] 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) | PARAMETER | DESCRIPTION |
|---|---|
input | The input to the TYPE: |
config | The config to use for the TYPE: |
version | The version of the schema to use, either Users should use
No default will be assigned until the API is stabilized. custom events will only be surfaced in TYPE: |
include_names | Only include events from |
include_types | Only include events from |
include_tags | Only include events from |
exclude_names | Exclude events from |
exclude_types | Exclude events from |
exclude_tags | Exclude events from |
**kwargs | Additional keyword arguments to pass to the These will be passed to TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[StreamEvent] | An async stream of |
| RAISES | DESCRIPTION |
|---|---|
NotImplementedError | If the version is not |
transform( input: Iterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None ) -> Iterator[Output] Transform inputs to outputs.
Default implementation of transform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
Output | The output of the |
async ¶
atransform( input: AsyncIterator[Input], config: RunnableConfig | None = None, **kwargs: Any | None, ) -> AsyncIterator[Output] Transform inputs to outputs.
Default implementation of atransform, which buffers input and calls astream.
Subclasses must override this method if they can start producing output while input is still being generated.
| PARAMETER | DESCRIPTION |
|---|---|
input | An async iterator of inputs to the TYPE: |
config | The config to use for the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| YIELDS | DESCRIPTION |
|---|---|
AsyncIterator[Output] | The output of the |
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.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | The arguments to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_ollama import ChatOllama from langchain_core.output_parsers import StrOutputParser model = ChatOllama(model="llama3.1") # Without bind chain = model | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two three four five.' # With bind chain = model.bind(stop=["three"]) | StrOutputParser() chain.invoke("Repeat quoted words exactly: 'One two three four five.'") # Output is 'One two'
with_config( config: RunnableConfig | None = None, **kwargs: Any ) -> Runnable[Input, Output] Bind config to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
config | The config to bind to the TYPE: |
**kwargs | Additional keyword arguments to pass to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_listeners( *, on_start: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_end: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, on_error: Callable[[Run], None] | Callable[[Run, RunnableConfig], None] | None = None, ) -> Runnable[Input, Output] Bind lifecycle listeners to a Runnable, returning a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called before the TYPE: |
on_end | Called after the TYPE: |
on_error | Called if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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)
with_alisteners( *, on_start: AsyncListener | None = None, on_end: AsyncListener | None = None, on_error: AsyncListener | None = None, ) -> Runnable[Input, Output] Bind async lifecycle listeners to a Runnable.
Returns a new Runnable.
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.
| PARAMETER | DESCRIPTION |
|---|---|
on_start | Called asynchronously before the TYPE: |
on_end | Called asynchronously after the TYPE: |
on_error | Called asynchronously if the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
from langchain_core.runnables import RunnableLambda, Runnable from datetime import datetime, timezone import time import asyncio def format_t(timestamp: float) -> str: return datetime.fromtimestamp(timestamp, tz=timezone.utc).isoformat() 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 2025-03-01T07:05:22.875378+00:00 # on start callback starts at 2025-03-01T07:05:22.875495+00:00 # on start callback ends at 2025-03-01T07:05:25.878862+00:00 # on start callback ends at 2025-03-01T07:05:25.878947+00:00 # Runnable[2s]: starts at 2025-03-01T07:05:25.879392+00:00 # Runnable[3s]: starts at 2025-03-01T07:05:25.879804+00:00 # Runnable[2s]: ends at 2025-03-01T07:05:27.881998+00:00 # on end callback starts at 2025-03-01T07:05:27.882360+00:00 # Runnable[3s]: ends at 2025-03-01T07:05:28.881737+00:00 # on end callback starts at 2025-03-01T07:05:28.882428+00:00 # on end callback ends at 2025-03-01T07:05:29.883893+00:00 # on end callback ends at 2025-03-01T07:05:30.884831+00:00
with_types( *, input_type: type[Input] | None = None, output_type: type[Output] | None = None ) -> Runnable[Input, Output] Bind input and output types to a Runnable, returning a new Runnable.
| PARAMETER | DESCRIPTION |
|---|---|
input_type | The input type to bind to the TYPE: |
output_type | The output type to bind to the TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
with_retry( *, retry_if_exception_type: tuple[type[BaseException], ...] = (Exception,), wait_exponential_jitter: bool = True, exponential_jitter_params: ExponentialJitterParams | None = None, stop_after_attempt: int = 3, ) -> Runnable[Input, Output] Create a new Runnable that retries the original Runnable on exceptions.
| PARAMETER | DESCRIPTION |
|---|---|
retry_if_exception_type | A tuple of exception types to retry on. TYPE: |
wait_exponential_jitter | Whether to add jitter to the wait time between retries. TYPE: |
stop_after_attempt | The maximum number of attempts to make before giving up. TYPE: |
exponential_jitter_params | Parameters for TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Runnable[Input, Output] | A new |
Example
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
with_fallbacks( fallbacks: Sequence[Runnable[Input, Output]], *, exceptions_to_handle: tuple[type[BaseException], ...] = (Exception,), exception_key: str | None = None, ) -> RunnableWithFallbacks[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.
| PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
Example
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 | PARAMETER | DESCRIPTION |
|---|---|
fallbacks | A sequence of runnables to try if the original |
exceptions_to_handle | A tuple of exception types to handle. TYPE: |
exception_key | If If If used, the base TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableWithFallbacks[Input, Output] | A new |
as_tool( args_schema: type[BaseModel] | None = None, *, name: str | None = None, description: str | None = None, arg_types: dict[str, type] | None = 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.
| PARAMETER | DESCRIPTION |
|---|---|
args_schema | The schema for the tool. |
name | The name of the tool. TYPE: |
description | The description of the tool. TYPE: |
arg_types | A dictionary of argument names to types. |
| RETURNS | DESCRIPTION |
|---|---|
BaseTool | A |
TypedDict input
dict input, specifying schema via args_schema
from typing import Any from pydantic 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
classmethod ¶
is_lc_serializable() -> bool Is this class serializable?
By design, even if a class inherits from Serializable, it is not serializable by default. This is to prevent accidental serialization of objects that should not be serialized.
| RETURNS | DESCRIPTION |
|---|---|
bool | Whether the class is serializable. Default is |
classmethod ¶
classmethod ¶
Return a unique identifier for this class for serialization purposes.
The unique identifier is a list of strings that describes the path to the object.
For example, for the class langchain.llms.openai.OpenAI, the id is ["langchain", "llms", "openai", "OpenAI"].
Serialize the Runnable to JSON.
| RETURNS | DESCRIPTION |
|---|---|
SerializedConstructor | SerializedNotImplemented | A JSON-serializable representation of the |
Serialize a "not implemented" object.
| RETURNS | DESCRIPTION |
|---|---|
SerializedNotImplemented |
|
configurable_fields( **kwargs: AnyConfigurableField, ) -> RunnableSerializable[Input, Output] Configure particular Runnable fields at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | A dictionary of TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If a configuration key is not found in the |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
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, )
configurable_alternatives( which: ConfigurableField, *, default_key: str = "default", prefix_keys: bool = False, **kwargs: Runnable[Input, Output] | Callable[[], Runnable[Input, Output]], ) -> RunnableSerializable[Input, Output] Configure alternatives for Runnable objects that can be set at runtime.
| PARAMETER | DESCRIPTION |
|---|---|
which | The TYPE: |
default_key | The default key to use if no alternative is selected. TYPE: |
prefix_keys | Whether to prefix the keys with the TYPE: |
**kwargs | A dictionary of keys to TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RunnableSerializable[Input, Output] | A new |
Example
from langchain_anthropic import ChatAnthropic from langchain_core.runnables.utils import ConfigurableField from langchain_openai import ChatOpenAI model = ChatAnthropic( model_name="claude-sonnet-4-5-20250929" ).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 ) classmethod ¶
Validate search type.
| PARAMETER | DESCRIPTION |
|---|---|
values | Values to validate. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Any | Validated values. |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If |
ValueError | If |
async ¶
Bases: BaseCache
Cache that uses MemoryDB as a vector-store backend.
| METHOD | DESCRIPTION |
|---|---|
alookup | Async look up based on |
aupdate | Async update cache based on |
aclear | Async clear cache that can take additional keyword arguments. |
__init__ | Initialize by passing in the |
clear | Clear semantic cache for a given llm_string. |
lookup | Look up based on prompt and llm_string. |
update | Update cache based on prompt and llm_string. |
async ¶
Async look up based on prompt and llm_string.
A cache implementation is expected to generate a key from the 2-tuple of prompt and llm_string (e.g., by concatenating them with a delimiter).
| PARAMETER | DESCRIPTION |
|---|---|
prompt | A string representation of the prompt. In the case of a chat model, the prompt is a non-trivial serialization of the prompt into the language model. TYPE: |
llm_string | A string representation of the LLM configuration. This is used to capture the invocation parameters of the LLM (e.g., model name, temperature, stop tokens, max tokens, etc.). These invocation parameters are serialized into a string representation. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
RETURN_VAL_TYPE | None | On a cache miss, return |
RETURN_VAL_TYPE | None | The cached value is a list of |
async ¶
Async update cache based on prompt and llm_string.
The prompt and llm_string are used to generate a key for the cache. The key should match that of the look up method.
| PARAMETER | DESCRIPTION |
|---|---|
prompt | A string representation of the prompt. In the case of a chat model, the prompt is a non-trivial serialization of the prompt into the language model. TYPE: |
llm_string | A string representation of the LLM configuration. This is used to capture the invocation parameters of the LLM (e.g., model name, temperature, stop tokens, max tokens, etc.). These invocation parameters are serialized into a string representation. TYPE: |
return_val | The value to be cached. The value is a list of TYPE: |
async ¶
aclear(**kwargs: Any) -> None Async clear cache that can take additional keyword arguments.
__init__(redis_url: str, embedding: Embeddings, score_threshold: float = 0.2) Initialize by passing in the init GPTCache func
| PARAMETER | DESCRIPTION |
|---|---|
redis_url | URL to connect to MemoryDB. TYPE: |
embedding | Embedding provider for semantic encoding and search. TYPE: |
score_threshold | TYPE: |
Example: ```python from langchain_core.globals import set_llm_cache
from langchain_aws.cache import InMemorySemanticCache set_llm_cache(InMemorySemanticCache( redis_url="redis://localhost:6379", embedding=OpenAIEmbeddings() )) ```
Look up based on prompt and llm_string.
Bases: VectorStore
InMemoryVectorStore vector database.
To use, you should have the redis python package installed for AWS MemoryDB:
```bash pip install redis ``` Once running, you can connect to the MemoryDB server with the following url schemas: - redis://
Examples:
The following examples show various ways to use the Redis VectorStore with LangChain.
For all the following examples assume we have the following imports
Initialize, create index, and load Documents:
from langchain_aws.vectorstores import InMemoryVectorStore rds = InMemoryVectorStore.from_documents( documents, # a list of Document objects from loaders or created embeddings, # an Embeddings object redis_url="redis://cluster_endpoint:6379", ) Initialize, create index, and load Documents with metadata:
rds = InMemoryVectorStore.from_texts( texts, # a list of strings metadata, # a list of metadata dicts embeddings, # an Embeddings object redis_url="redis://cluster_endpoint:6379", ) Initialize, create index, and load Documents with metadata and return keys
```python rds, keys = InMemoryVectorStore.from_texts_return_keys( texts, # a list of strings metadata, # a list of metadata dicts embeddings, # an Embeddings object redis_url="redis://cluster_endpoint:6379", ) ``` For use cases where the index needs to stay alive, you can initialize with an index name such that it's easier to reference later
```python rds = InMemoryVectorStore.from_texts( texts, # a list of strings metadata, # a list of metadata dicts embeddings, # an Embeddings object index_name="my-index", redis_url="redis://cluster_endpoint:6379", ) ``` Initialize and connect to an existing index (from above)
```python # must pass in schema and key_prefix from another index existing_rds = InMemoryVectorStore.from_existing_index( embeddings, # an Embeddings object index_name="my-index", schema=rds.schema, # schema dumped from another index key_prefix=rds.key_prefix, # key prefix from another index redis_url="redis://username:password@cluster_endpoint:6379", ) ``` Advanced examples:
Custom vector schema can be supplied to change the way that MemoryDB creates the underlying vector schema. This is useful for production use cases where you want to optimize the vector schema for your use case. ex. using HNSW instead of FLAT (knn) which is the default
```python vector_schema = { "algorithm": "HNSW" } rds = InMemoryVectorStore.from_texts( texts, # a list of strings metadata, # a list of metadata dicts embeddings, # an Embeddings object vector_schema=vector_schema, redis_url="redis://cluster_endpoint:6379", ) ``` Custom index schema can be supplied to change the way that the metadata is indexed. This is useful for you would like to use the hybrid querying (filtering) capability of MemoryDB.
By default, this implementation will automatically generate the index schema according to the following rules: - All strings are indexed as text fields - All numbers are indexed as numeric fields - All lists of strings are indexed as tag fields (joined by langchain_aws.vectorstores.inmemorydb.constants.INMEMORYDB_TAG_SEPARATOR) - All None values are not indexed but still stored in MemoryDB these are not retrievable through the interface here, but the raw MemoryDB client can be used to retrieve them. - All other types are not indexed
To override these rules, you can pass in a custom index schema like the following
```yaml tag: - name: credit_score text: - name: user - name: job ``` Typically, the credit_score field would be a text field since it's a string, however, we can override this behavior by specifying the field type as shown with the yaml config (can also be a dictionary) above and the code below.
```python rds = InMemoryVectorStore.from_texts( texts, # a list of strings metadata, # a list of metadata dicts embeddings, # an Embeddings object index_schema="path/to/index_schema.yaml", # can also be a dictionary redis_url="redis://cluster_endpoint:6379", ) ``` When connecting to an existing index where a custom schema has been applied, it's important to pass in the same schema to the from_existing_index method. Otherwise, the schema for newly added samples will be incorrect and metadata will not be returned.
| METHOD | DESCRIPTION |
|---|---|
get_by_ids | Get documents by their IDs. |
aget_by_ids | Async get documents by their IDs. |
adelete | Async delete by vector ID or other criteria. |
aadd_texts | Async run more texts through the embeddings and add to the |
add_documents | Add or update documents in the |
aadd_documents | Async run more documents through the embeddings and add to the |
search | Return docs most similar to query using a specified search type. |
asearch | Async return docs most similar to query using a specified search type. |
asimilarity_search_with_score | Async run similarity search with distance. |
similarity_search_with_relevance_scores | Return docs and relevance scores in the range |
asimilarity_search_with_relevance_scores | Async return docs and relevance scores in the range |
asimilarity_search | Async return docs most similar to query. |
asimilarity_search_by_vector | Async return docs most similar to embedding vector. |
amax_marginal_relevance_search | Async return docs selected using the maximal marginal relevance. |
max_marginal_relevance_search_by_vector | Return docs selected using the maximal marginal relevance. |
amax_marginal_relevance_search_by_vector | Async return docs selected using the maximal marginal relevance. |
from_documents | Return |
afrom_documents | Async return |
afrom_texts | Async return |
__init__ | Initialize MemoryDB vector store with necessary components. |
from_texts_return_keys | Create a InMemoryVectorStore vectorstore from raw documents. |
from_texts | Create a InMemoryVectorStore vectorstore from a list of texts. |
from_existing_index | Connect to an existing InMemoryVectorStore index. |
write_schema | Write the schema to a yaml file. |
delete | Delete a InMemoryVectorStore entry. |
drop_index | Drop a InMemoryVectorStore search index. |
add_texts | Add more texts to the |
as_retriever | Return |
similarity_search_with_score | Run similarity search with vector distance. |
similarity_search | Run similarity search |
similarity_search_by_vector | Run similarity search between a query vector and the indexed vectors. |
max_marginal_relevance_search | Return docs selected using the maximal marginal relevance. |
Get documents by their IDs.
The returned documents are expected to have the ID field set to the ID of the document in the vector store.
Fewer documents may be returned than requested if some IDs are not found or if there are duplicated IDs.
Users should not assume that the order of the returned documents matches the order of the input IDs. Instead, users should rely on the ID field of the returned documents.
This method should NOT raise exceptions if no documents are found for some IDs.
| PARAMETER | DESCRIPTION |
|---|---|
ids | List of IDs to retrieve. |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
async ¶
Async get documents by their IDs.
The returned documents are expected to have the ID field set to the ID of the document in the vector store.
Fewer documents may be returned than requested if some IDs are not found or if there are duplicated IDs.
Users should not assume that the order of the returned documents matches the order of the input IDs. Instead, users should rely on the ID field of the returned documents.
This method should NOT raise exceptions if no documents are found for some IDs.
| PARAMETER | DESCRIPTION |
|---|---|
ids | List of IDs to retrieve. |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
async ¶
Async delete by vector ID or other criteria.
| PARAMETER | DESCRIPTION |
|---|---|
ids | List of IDs to delete. If |
**kwargs | Other keyword arguments that subclasses might use. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
bool | None |
|
async ¶
aadd_texts( texts: Iterable[str], metadatas: list[dict] | None = None, *, ids: list[str] | None = None, **kwargs: Any, ) -> list[str] Async run more texts through the embeddings and add to the VectorStore.
| PARAMETER | DESCRIPTION |
|---|---|
texts | Iterable of strings to add to the |
metadatas | Optional list of metadatas associated with the texts. |
ids | Optional list |
**kwargs |
TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[str] | List of IDs from adding the texts into the |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If the number of metadatas does not match the number of texts. |
ValueError | If the number of IDs does not match the number of texts. |
Add or update documents in the VectorStore.
| PARAMETER | DESCRIPTION |
|---|---|
documents | Documents to add to the |
**kwargs | Additional keyword arguments. If kwargs contains IDs and documents contain ids, the IDs in the kwargs will receive precedence. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[str] | List of IDs of the added texts. |
async ¶
Return docs most similar to query using a specified search type.
| PARAMETER | DESCRIPTION |
|---|---|
query | Input text. TYPE: |
search_type | Type of search to perform. Can be TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If |
async ¶
Async return docs most similar to query using a specified search type.
| PARAMETER | DESCRIPTION |
|---|---|
query | Input text. TYPE: |
search_type | Type of search to perform. Can be TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If |
async ¶
similarity_search_with_relevance_scores( query: str, k: int = 4, **kwargs: Any ) -> list[tuple[Document, float]] Return docs and relevance scores in the range [0, 1].
0 is dissimilar, 1 is most similar.
| PARAMETER | DESCRIPTION |
|---|---|
query | Input text. TYPE: |
k | Number of TYPE: |
**kwargs | kwargs to be passed to similarity search. Should include TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[tuple[Document, float]] | List of tuples of |
async ¶
asimilarity_search_with_relevance_scores( query: str, k: int = 4, **kwargs: Any ) -> list[tuple[Document, float]] Async return docs and relevance scores in the range [0, 1].
0 is dissimilar, 1 is most similar.
| PARAMETER | DESCRIPTION |
|---|---|
query | Input text. TYPE: |
k | Number of TYPE: |
**kwargs | kwargs to be passed to similarity search. Should include TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[tuple[Document, float]] | List of tuples of |
async ¶
Async return docs most similar to query.
| PARAMETER | DESCRIPTION |
|---|---|
query | Input text. TYPE: |
k | Number of TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
async ¶
Async return docs most similar to embedding vector.
| PARAMETER | DESCRIPTION |
|---|---|
embedding | Embedding to look up documents similar to. |
k | Number of TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
async ¶
amax_marginal_relevance_search( query: str, k: int = 4, fetch_k: int = 20, lambda_mult: float = 0.5, **kwargs: Any ) -> list[Document] Async return docs selected using the maximal marginal relevance.
Maximal marginal relevance optimizes for similarity to query AND diversity among selected documents.
| PARAMETER | DESCRIPTION |
|---|---|
query | Text to look up documents similar to. TYPE: |
k | Number of TYPE: |
fetch_k | Number of TYPE: |
lambda_mult | Number between TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
max_marginal_relevance_search_by_vector( embedding: list[float], k: int = 4, fetch_k: int = 20, lambda_mult: float = 0.5, **kwargs: Any, ) -> list[Document] Return docs selected using the maximal marginal relevance.
Maximal marginal relevance optimizes for similarity to query AND diversity among selected documents.
| PARAMETER | DESCRIPTION |
|---|---|
embedding | Embedding to look up documents similar to. |
k | Number of TYPE: |
fetch_k | Number of TYPE: |
lambda_mult | Number between TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
async ¶
amax_marginal_relevance_search_by_vector( embedding: list[float], k: int = 4, fetch_k: int = 20, lambda_mult: float = 0.5, **kwargs: Any, ) -> list[Document] Async return docs selected using the maximal marginal relevance.
Maximal marginal relevance optimizes for similarity to query AND diversity among selected documents.
| PARAMETER | DESCRIPTION |
|---|---|
embedding | Embedding to look up documents similar to. |
k | Number of TYPE: |
fetch_k | Number of TYPE: |
lambda_mult | Number between TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
classmethod ¶
from_documents(documents: list[Document], embedding: Embeddings, **kwargs: Any) -> Self Return VectorStore initialized from documents and embeddings.
| PARAMETER | DESCRIPTION |
|---|---|
documents | List of |
embedding | Embedding function to use. TYPE: |
**kwargs | Additional keyword arguments. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Self |
|
async classmethod ¶
afrom_documents( documents: list[Document], embedding: Embeddings, **kwargs: Any ) -> Self Async return VectorStore initialized from documents and embeddings.
| PARAMETER | DESCRIPTION |
|---|---|
documents | List of |
embedding | Embedding function to use. TYPE: |
**kwargs | Additional keyword arguments. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Self |
|
async classmethod ¶
afrom_texts( texts: list[str], embedding: Embeddings, metadatas: list[dict] | None = None, *, ids: list[str] | None = None, **kwargs: Any, ) -> Self Async return VectorStore initialized from texts and embeddings.
| PARAMETER | DESCRIPTION |
|---|---|
texts | Texts to add to the |
embedding | Embedding function to use. TYPE: |
metadatas | Optional list of metadatas associated with the texts. |
ids | Optional list of IDs associated with the texts. |
**kwargs | Additional keyword arguments. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Self |
|
__init__( redis_url: str, index_name: str, embedding: Embeddings, index_schema: dict[str, ListOfDict] | str | PathLike | None = None, vector_schema: dict[str, str | int] | None = None, relevance_score_fn: Callable[[float], float] | None = None, key_prefix: str | None = None, **kwargs: Any, ) Initialize MemoryDB vector store with necessary components.
classmethod ¶
from_texts_return_keys( texts: list[str], embedding: Embeddings, metadatas: list[dict] | None = None, index_name: str | None = None, index_schema: dict[str, ListOfDict] | str | PathLike | None = None, vector_schema: dict[str, str | int] | None = None, **kwargs: Any, ) -> tuple[InMemoryVectorStore, list[str]] Create a InMemoryVectorStore vectorstore from raw documents.
This is a user-friendly interface that
- Embeds documents.
- Creates a new InMemoryVectorStore index if it doesn't already exist
- Adds the documents to the newly created InMemoryVectorStore index.
- Returns the keys of the newly created documents once stored.
This method will generate schema based on the metadata passed in if the index_schema is not defined. If the index_schema is defined, it will compare against the generated schema and warn if there are differences. If you are purposefully defining the schema for the metadata, then you can ignore that warning.
To examine the schema options, initialize an instance of this class and print out the schema using the `InMemoryVectorStore.schema`` property. This will include the content and content_vector classes which are always present in the langchain schema.
Example
| PARAMETER | DESCRIPTION |
|---|---|
texts | List of texts to add to the |
embedding | Embeddings to use for the TYPE: |
metadatas | Optional list of metadata dicts to add to the |
index_name | Optional name of the index to create or add to. TYPE: |
index_schema | Optional fields to index within the metadata. Overrides generated schema. TYPE: |
vector_schema | Optional vector schema to use. |
**kwargs | Additional keyword arguments to pass to the Redis client. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
tuple[InMemoryVectorStore, list[str]] | Tuple[InMemoryVectorStore, List[str]]: Tuple of the InMemoryVectorStore instance and the keys of the newly created documents. |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If the number of metadatas does not match the number of texts. |
classmethod ¶
from_texts( texts: list[str], embedding: Embeddings, metadatas: list[dict] | None = None, index_name: str | None = None, index_schema: dict[str, ListOfDict] | str | PathLike | None = None, vector_schema: dict[str, str | int] | None = None, **kwargs: Any, ) -> InMemoryVectorStore Create a InMemoryVectorStore vectorstore from a list of texts.
This is a user-friendly interface that
- Embeds documents.
- Creates a new InMemoryVectorStore index if it doesn't already exist
- Adds the documents to the newly created InMemoryVectorStore index.
This method will generate schema based on the metadata passed in if the index_schema is not defined. If the index_schema is defined, it will compare against the generated schema and warn if there are differences. If you are purposefully defining the schema for the metadata, then you can ignore that warning.
To examine the schema options, initialize an instance of this class and print out the schema using the `InMemoryVectorStore.schema`` property. This will include the content and content_vector classes which are always present in the langchain schema.
| PARAMETER | DESCRIPTION |
|---|---|
texts | List of texts to add to the |
embedding | Embedding model class (i.e. OpenAIEmbeddings) for embedding queries. TYPE: |
metadatas | Optional list of metadata dicts to add to the |
index_name | Optional name of the index to create or add to. TYPE: |
index_schema | Optional fields to index within the metadata. Overrides generated schema. TYPE: |
vector_schema | Optional vector schema to use. |
**kwargs | Additional keyword arguments to pass to the InMemoryVectorStore client. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
InMemoryVectorStore | InMemoryVectorStore VectorStore instance. TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If the number of metadatas does not match the number of texts. |
ImportError | If the redis python package is not installed. |
classmethod ¶
from_existing_index( embedding: Embeddings, index_name: str, schema: dict[str, ListOfDict] | str | PathLike | dict[str, ListOfDict], key_prefix: str | None = None, **kwargs: Any, ) -> InMemoryVectorStore Connect to an existing InMemoryVectorStore index.
Example
from langchain_aws.vectorstores import InMemoryVectorStore embeddings = OpenAIEmbeddings() # must pass in schema and key_prefix from another index existing_rds = InMemoryVectorStore.from_existing_index( embeddings, index_name="my-index", schema=rds.schema, # schema dumped from another index key_prefix=rds.key_prefix, # key prefix from another index redis_url="redis://username:password@cluster_endpoint:6379", ) | PARAMETER | DESCRIPTION |
|---|---|
embedding | Embedding model class (i.e. OpenAIEmbeddings) for embedding queries. TYPE: |
index_name | Name of the index to connect to. TYPE: |
schema | Schema of the index and the vector schema. Can be a dict, or path to yaml file. TYPE: |
key_prefix | Prefix to use for all keys in InMemoryVectorStore associated with this index. TYPE: |
**kwargs | Additional keyword arguments to pass to the Redis client. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
InMemoryVectorStore | InMemoryVectorStore VectorStore instance. TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If the index does not exist. |
ImportError | If the redis python package is not installed. |
staticmethod ¶
Delete a InMemoryVectorStore entry.
| PARAMETER | DESCRIPTION |
|---|---|
ids | List of IDs (keys in redis) to delete. |
**kwargs | Additional keyword arguments. Supports TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
bool | Whether or not the deletions were successful. TYPE: |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If the redis python package is not installed. |
ValueError | If the IDs (keys in redis) are not provided. |
staticmethod ¶
add_texts( texts: Iterable[str], metadatas: list[dict] | None = None, embeddings: list[list[float]] | None = None, batch_size: int = 1000, clean_metadata: bool = True, **kwargs: Any, ) -> list[str] Add more texts to the VectorStore.
| PARAMETER | DESCRIPTION |
|---|---|
texts | Iterable of strings/text to add to the |
metadatas | Optional list of metadatas. |
embeddings | Optional pre-generated embeddings. |
batch_size | Batch size to use for writes. TYPE: |
**kwargs | Additional keyword arguments. Supports TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[str] | List of IDs added to the |
as_retriever(**kwargs: Any) -> InMemoryVectorStoreRetriever Return VectorStoreRetriever initialized from this VectorStore.
| PARAMETER | DESCRIPTION |
|---|---|
**kwargs | Keyword arguments to pass to the search function. Can include:
TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
VectorStoreRetriever | Retriever class for |
Examples:
# Retrieve more documents with higher diversity # Useful if your dataset has many similar documents docsearch.as_retriever( search_type="mmr", search_kwargs={"k": 6, "lambda_mult": 0.25} ) # Fetch more documents for the MMR algorithm to consider # But only return the top 5 docsearch.as_retriever(search_type="mmr", search_kwargs={"k": 5, "fetch_k": 50}) # Only retrieve documents that have a relevance score # Above a certain threshold docsearch.as_retriever( search_type="similarity_score_threshold", search_kwargs={"score_threshold": 0.8}, ) # Only get the single most similar document from the dataset docsearch.as_retriever(search_kwargs={"k": 1}) # Use a filter to only retrieve documents from a specific paper docsearch.as_retriever( search_kwargs={"filter": {"paper_title": "GPT-4 Technical Report"}} )
similarity_search_with_score( query: str, k: int = 4, filter: InMemoryDBFilterExpression | None = None, return_metadata: bool = True, **kwargs: Any, ) -> list[tuple[Document, float]] Run similarity search with vector distance.
The "scores" returned from this function are the raw vector distances from the query vector. For similarity scores, use similarity_search_with_relevance_scores.
| PARAMETER | DESCRIPTION |
|---|---|
query | The query text for which to find similar documents. TYPE: |
k | The number of documents to return. Default is 4. TYPE: |
filter | Optional metadata filter. TYPE: |
return_metadata | Whether to return metadata. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[tuple[Document, float]] | List[Tuple[Document, float]]: A list of documents that are most similar to the query with the distance for each document. |
similarity_search( query: str, k: int = 4, filter: InMemoryDBFilterExpression | None = None, return_metadata: bool = True, distance_threshold: float | None = None, **kwargs: Any, ) -> list[Document] Run similarity search
| PARAMETER | DESCRIPTION |
|---|---|
query | The query text for which to find similar documents. TYPE: |
k | The number of documents to return. Default is 4. TYPE: |
filter | Optional metadata filter. TYPE: |
return_metadata | Whether to return metadata. TYPE: |
distance_threshold | Maximum vector distance between selected documents and the query vector. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List[Document]: A list of documents that are most similar to the query text. |
similarity_search_by_vector( embedding: list[float], k: int = 4, filter: InMemoryDBFilterExpression | None = None, return_metadata: bool = True, distance_threshold: float | None = None, **kwargs: Any, ) -> list[Document] Run similarity search between a query vector and the indexed vectors.
| PARAMETER | DESCRIPTION |
|---|---|
embedding | The query vector for which to find similar documents. |
k | The number of documents to return. Default is 4. TYPE: |
filter | Optional metadata filter. TYPE: |
return_metadata | Whether to return metadata. TYPE: |
distance_threshold | Maximum vector distance between selected documents and the query vector. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List[Document]: A list of documents that are most similar to the query text. |
max_marginal_relevance_search( query: str, k: int = 4, fetch_k: int = 20, lambda_mult: float = 0.5, filter: InMemoryDBFilterExpression | None = None, return_metadata: bool = True, distance_threshold: float | None = None, **kwargs: Any, ) -> list[Document] Return docs selected using the maximal marginal relevance.
Maximal marginal relevance optimizes for similarity to query AND diversity among selected documents.
| PARAMETER | DESCRIPTION |
|---|---|
query | Text to look up documents similar to. TYPE: |
k | Number of Documents to return. Defaults to 4. TYPE: |
fetch_k | Number of TYPE: |
lambda_mult | Number between TYPE: |
filter | Optional metadata filter. TYPE: |
return_metadata | Whether to return metadata. TYPE: |
distance_threshold | Maximum vector distance between selected documents and the query vector. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List[Document]: A list of Documents selected by maximal marginal relevance. |
Bases: VectorStore
S3Vectors is Amazon S3 Vectors database.
To use, you MUST first manually create a S3 vector bucket. There is no need to create a vector index. See: https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-getting-started.html
Pay attention to s3 vectors limitations and restrictions. By default, metadata for s3 vectors includes page_content and metadata for the Document. See: https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-limitations.html
Examples:
The following examples show various ways to use the AmazonS3Vectors with LangChain.
For all the following examples assume we have the following:
```python from langchain_aws.embeddings import BedrockEmbeddings from langchain_aws.vectorstores.s3_vectors import AmazonS3Vectors embedding = BedrockEmbeddings() ``` Initialize, create vector index if it does not exist, and add texts:
```python vector_store = AmazonS3Vectors.from_texts( ["hello", "developer", "wife"], vector_bucket_name="<vector bucket name>", index_name="<vector index name>", embedding=embedding, ) ``` Initialize, create vector index if it does not exist, and add Documents:
from langchain_core.documents import Document vector_store = AmazonS3Vectors( vector_bucket_name="<vector bucket name>", index_name="<vector index name>", embedding=embedding, ) vector_store.add_documents( [ Document("Star Wars", id="key1", metadata={"genre": "scifi"}), Document("Jurassic Park", id="key2", metadata={"genre": "scifi"}), Document("Finding Nemo", id="key3", metadata={"genre": "family"}), ] ) Search with score(distance) and metadata filter:
vector_store.similarity_search_with_score( "adventures in space", filter={"genre": {"$eq": "family"}} ) | METHOD | DESCRIPTION |
|---|---|
aget_by_ids | Async get documents by their IDs. |
adelete | Async delete by vector ID or other criteria. |
aadd_texts | Async run more texts through the embeddings and add to the |
add_documents | Add or update documents in the |
aadd_documents | Async run more documents through the embeddings and add to the |
search | Return docs most similar to query using a specified search type. |
asearch | Async return docs most similar to query using a specified search type. |
asimilarity_search_with_score | Async run similarity search with distance. |
similarity_search_with_relevance_scores | Return docs and relevance scores in the range |
asimilarity_search_with_relevance_scores | Async return docs and relevance scores in the range |
asimilarity_search | Async return docs most similar to query. |
asimilarity_search_by_vector | Async return docs most similar to embedding vector. |
max_marginal_relevance_search | Return docs selected using the maximal marginal relevance. |
amax_marginal_relevance_search | Async return docs selected using the maximal marginal relevance. |
max_marginal_relevance_search_by_vector | Return docs selected using the maximal marginal relevance. |
amax_marginal_relevance_search_by_vector | Async return docs selected using the maximal marginal relevance. |
from_documents | Return |
afrom_documents | Async return |
afrom_texts | Async return |
__init__ | Create a AmazonS3Vectors. |
add_texts | Add more texts to the |
delete | Delete by vector ID or delete index. |
get_by_ids | Get documents by their IDs. |
similarity_search | Return docs most similar to query. |
similarity_search_with_score | Run similarity search with score(distance). |
similarity_search_by_vector | Return docs most similar to embedding vector. |
as_retriever | Return AmazonS3VectorsRetriever initialized from this AmazonS3Vectors. |
from_texts | Return AmazonS3Vectors initialized from texts and embeddings. |
async ¶
Async get documents by their IDs.
The returned documents are expected to have the ID field set to the ID of the document in the vector store.
Fewer documents may be returned than requested if some IDs are not found or if there are duplicated IDs.
Users should not assume that the order of the returned documents matches the order of the input IDs. Instead, users should rely on the ID field of the returned documents.
This method should NOT raise exceptions if no documents are found for some IDs.
| PARAMETER | DESCRIPTION |
|---|---|
ids | List of IDs to retrieve. |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
async ¶
Async delete by vector ID or other criteria.
| PARAMETER | DESCRIPTION |
|---|---|
ids | List of IDs to delete. If |
**kwargs | Other keyword arguments that subclasses might use. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
bool | None |
|
async ¶
aadd_texts( texts: Iterable[str], metadatas: list[dict] | None = None, *, ids: list[str] | None = None, **kwargs: Any, ) -> list[str] Async run more texts through the embeddings and add to the VectorStore.
| PARAMETER | DESCRIPTION |
|---|---|
texts | Iterable of strings to add to the |
metadatas | Optional list of metadatas associated with the texts. |
ids | Optional list |
**kwargs |
TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[str] | List of IDs from adding the texts into the |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If the number of metadatas does not match the number of texts. |
ValueError | If the number of IDs does not match the number of texts. |
Add or update documents in the VectorStore.
| PARAMETER | DESCRIPTION |
|---|---|
documents | Documents to add to the |
**kwargs | Additional keyword arguments. If kwargs contains IDs and documents contain ids, the IDs in the kwargs will receive precedence. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[str] | List of IDs of the added texts. |
async ¶
Return docs most similar to query using a specified search type.
| PARAMETER | DESCRIPTION |
|---|---|
query | Input text. TYPE: |
search_type | Type of search to perform. Can be TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If |
async ¶
Async return docs most similar to query using a specified search type.
| PARAMETER | DESCRIPTION |
|---|---|
query | Input text. TYPE: |
search_type | Type of search to perform. Can be TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
| RAISES | DESCRIPTION |
|---|---|
ValueError | If |
async ¶
similarity_search_with_relevance_scores( query: str, k: int = 4, **kwargs: Any ) -> list[tuple[Document, float]] Return docs and relevance scores in the range [0, 1].
0 is dissimilar, 1 is most similar.
| PARAMETER | DESCRIPTION |
|---|---|
query | Input text. TYPE: |
k | Number of TYPE: |
**kwargs | kwargs to be passed to similarity search. Should include TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[tuple[Document, float]] | List of tuples of |
async ¶
asimilarity_search_with_relevance_scores( query: str, k: int = 4, **kwargs: Any ) -> list[tuple[Document, float]] Async return docs and relevance scores in the range [0, 1].
0 is dissimilar, 1 is most similar.
| PARAMETER | DESCRIPTION |
|---|---|
query | Input text. TYPE: |
k | Number of TYPE: |
**kwargs | kwargs to be passed to similarity search. Should include TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[tuple[Document, float]] | List of tuples of |
async ¶
Async return docs most similar to query.
| PARAMETER | DESCRIPTION |
|---|---|
query | Input text. TYPE: |
k | Number of TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
async ¶
Async return docs most similar to embedding vector.
| PARAMETER | DESCRIPTION |
|---|---|
embedding | Embedding to look up documents similar to. |
k | Number of TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
max_marginal_relevance_search( query: str, k: int = 4, fetch_k: int = 20, lambda_mult: float = 0.5, **kwargs: Any ) -> list[Document] Return docs selected using the maximal marginal relevance.
Maximal marginal relevance optimizes for similarity to query AND diversity among selected documents.
| PARAMETER | DESCRIPTION |
|---|---|
query | Text to look up documents similar to. TYPE: |
k | Number of TYPE: |
fetch_k | Number of TYPE: |
lambda_mult | Number between TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
async ¶
amax_marginal_relevance_search( query: str, k: int = 4, fetch_k: int = 20, lambda_mult: float = 0.5, **kwargs: Any ) -> list[Document] Async return docs selected using the maximal marginal relevance.
Maximal marginal relevance optimizes for similarity to query AND diversity among selected documents.
| PARAMETER | DESCRIPTION |
|---|---|
query | Text to look up documents similar to. TYPE: |
k | Number of TYPE: |
fetch_k | Number of TYPE: |
lambda_mult | Number between TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
max_marginal_relevance_search_by_vector( embedding: list[float], k: int = 4, fetch_k: int = 20, lambda_mult: float = 0.5, **kwargs: Any, ) -> list[Document] Return docs selected using the maximal marginal relevance.
Maximal marginal relevance optimizes for similarity to query AND diversity among selected documents.
| PARAMETER | DESCRIPTION |
|---|---|
embedding | Embedding to look up documents similar to. |
k | Number of TYPE: |
fetch_k | Number of TYPE: |
lambda_mult | Number between TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
async ¶
amax_marginal_relevance_search_by_vector( embedding: list[float], k: int = 4, fetch_k: int = 20, lambda_mult: float = 0.5, **kwargs: Any, ) -> list[Document] Async return docs selected using the maximal marginal relevance.
Maximal marginal relevance optimizes for similarity to query AND diversity among selected documents.
| PARAMETER | DESCRIPTION |
|---|---|
embedding | Embedding to look up documents similar to. |
k | Number of TYPE: |
fetch_k | Number of TYPE: |
lambda_mult | Number between TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
classmethod ¶
from_documents(documents: list[Document], embedding: Embeddings, **kwargs: Any) -> Self Return VectorStore initialized from documents and embeddings.
| PARAMETER | DESCRIPTION |
|---|---|
documents | List of |
embedding | Embedding function to use. TYPE: |
**kwargs | Additional keyword arguments. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Self |
|
async classmethod ¶
afrom_documents( documents: list[Document], embedding: Embeddings, **kwargs: Any ) -> Self Async return VectorStore initialized from documents and embeddings.
| PARAMETER | DESCRIPTION |
|---|---|
documents | List of |
embedding | Embedding function to use. TYPE: |
**kwargs | Additional keyword arguments. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Self |
|
async classmethod ¶
afrom_texts( texts: list[str], embedding: Embeddings, metadatas: list[dict] | None = None, *, ids: list[str] | None = None, **kwargs: Any, ) -> Self Async return VectorStore initialized from texts and embeddings.
| PARAMETER | DESCRIPTION |
|---|---|
texts | Texts to add to the |
embedding | Embedding function to use. TYPE: |
metadatas | Optional list of metadatas associated with the texts. |
ids | Optional list of IDs associated with the texts. |
**kwargs | Additional keyword arguments. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
Self |
|
__init__( *, vector_bucket_name: str, index_name: str, data_type: Literal["float32"] = "float32", distance_metric: Literal["euclidean", "cosine"] = "cosine", non_filterable_metadata_keys: list[str] | None = None, page_content_metadata_key: str | None = "_page_content", create_index_if_not_exist: bool = True, relevance_score_fn: Callable[[float], float] | None = None, embedding: Embeddings | None = None, region_name: str | None = None, credentials_profile_name: str | None = None, aws_access_key_id: str | None = None, aws_secret_access_key: str | None = None, aws_session_token: str | None = None, endpoint_url: str | None = None, config: Any = None, client: Any = None, **kwargs: Any, ) Create a AmazonS3Vectors.
| PARAMETER | DESCRIPTION |
|---|---|
vector_bucket_name | The name of an existing S3 vector bucket TYPE: |
index_name | The name of the S3 vector index. The index names must be 3 to 63 characters long, start and end with a letter or number, and contain only lowercase letters, numbers, hyphens and dots. TYPE: |
data_type | The data type of the vectors to be inserted into the vector index. Default is "float32". TYPE: |
distance_metric | The distance metric to be used for similarity search. Default is "cosine". TYPE: |
non_filterable_metadata_keys | Non-filterable metadata keys |
page_content_metadata_key | Key of metadata to store page_content in Document. If None, embedding page_content but stored as an empty string. Default is TYPE: |
create_index_if_not_exist | Automatically create vector index if it does not exist. Default is True. TYPE: |
relevance_score_fn | The 'correct' relevance function. |
embedding | Embedding function to use. TYPE: |
region_name | The aws region where the Sagemaker model is deployed, eg. TYPE: |
credentials_profile_name | The name of the profile in the ~/.aws/credentials or ~/.aws/config files, which has either access keys or role information specified. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html TYPE: |
aws_access_key_id | AWS access key id. If provided, aws_secret_access_key must also be provided. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html If not provided, will be read from TYPE: |
aws_secret_access_key | AWS secret_access_key. If provided, aws_access_key_id must also be provided. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html If not provided, will be read from TYPE: |
aws_session_token | AWS session token. If provided, aws_access_key_id and aws_secret_access_key must also be provided. Not required unless using temporary credentials. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html If not provided, will be read from TYPE: |
endpoint_url | Needed if you don't want to default to us-east-1 endpoint TYPE: |
config | An optional TYPE: |
client | Boto3 client for s3vectors TYPE: |
kwargs | Additional keyword arguments. TYPE: |
add_texts( texts: Iterable[str], metadatas: list[dict] | None = None, *, ids: list[str] | None = None, batch_size: int = 200, **kwargs: Any, ) -> list[str] Add more texts to the VectorStore.
| PARAMETER | DESCRIPTION |
|---|---|
texts | Iterable of strings/text to add to the |
metadatas | Optional list of metadatas. |
ids | Optional list of IDs associated with the texts. |
batch_size | Batch size for TYPE: |
kwargs | Additional keyword arguments. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[str] | List of IDs added to the |
Delete by vector ID or delete index.
| PARAMETER | DESCRIPTION |
|---|---|
ids | List of IDs to delete vectors. If |
batch_size | Batch size for TYPE: |
**kwargs | Additional keyword arguments. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
bool | None | Always |
similarity_search( query: str, k: int = 4, *, filter: dict | None = None, **kwargs: Any ) -> list[Document] Return docs most similar to query.
| PARAMETER | DESCRIPTION |
|---|---|
query | Input text. TYPE: |
k | Number of Documents to return. Defaults to 4. TYPE: |
filter | Metadata filter to apply during the query. See: https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-metadata-filtering.html TYPE: |
**kwargs | Arguments to pass to the search method. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
similarity_search_with_score( query: str, k: int = 4, *, filter: dict | None = None, **kwargs: Any ) -> list[tuple[Document, float]] Run similarity search with score(distance).
| PARAMETER | DESCRIPTION |
|---|---|
query | Input text. TYPE: |
k | Number of Documents to return. Defaults to 4. TYPE: |
filter | Metadata filter to apply during the query. See: https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-metadata-filtering.html TYPE: |
**kwargs | Additional keyword arguments. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[tuple[Document, float]] | List of Tuples of (doc, distance). |
similarity_search_by_vector( embedding: list[float], k: int = 4, *, filter: dict | None = None, **kwargs: Any ) -> list[Document] Return docs most similar to embedding vector.
| PARAMETER | DESCRIPTION |
|---|---|
embedding | Embedding to look up documents similar to. |
k | Number of Documents to return. Defaults to 4. TYPE: |
filter | Metadata filter to apply during the query. See: https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-metadata-filtering.html TYPE: |
**kwargs | Additional keyword arguments. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
list[Document] | List of |
as_retriever(**kwargs: Any) -> AmazonS3VectorsRetriever Return AmazonS3VectorsRetriever initialized from this AmazonS3Vectors.
classmethod ¶
from_texts( texts: list[str], embedding: Embeddings, metadatas: list[dict] | None = None, *, ids: list[str] | None = None, vector_bucket_name: str, index_name: str, data_type: Literal["float32"] = "float32", distance_metric: Literal["euclidean", "cosine"] = "cosine", non_filterable_metadata_keys: list[str] | None = None, page_content_metadata_key: str | None = "_page_content", create_index_if_not_exist: bool = True, relevance_score_fn: Callable[[float], float] | None = None, region_name: str | None = None, credentials_profile_name: str | None = None, aws_access_key_id: str | None = None, aws_secret_access_key: str | None = None, aws_session_token: str | None = None, endpoint_url: str | None = None, config: Any = None, client: Any = None, **kwargs: Any, ) -> AmazonS3Vectors Return AmazonS3Vectors initialized from texts and embeddings.
| PARAMETER | DESCRIPTION |
|---|---|
texts | Texts to add to the |
embedding | Embedding function to use. TYPE: |
metadatas | Optional list of metadatas associated with the texts. Default is None. |
ids | Optional list of IDs associated with the texts. |
vector_bucket_name | The name of an existing S3 vector bucket TYPE: |
index_name | The name of the S3 vector index. The index names must be 3 to 63 characters long, start and end with a letter or number, and contain only lowercase letters, numbers, hyphens and dots. TYPE: |
data_type | The data type of the vectors to be inserted into the vector index. Default is "float32". TYPE: |
distance_metric | The distance metric to be used for similarity search. Default is "cosine". TYPE: |
non_filterable_metadata_keys | Non-filterable metadata keys |
page_content_metadata_key | Key of metadata to store page_content in Document. If None, embedding page_content but stored as an empty string. Default is "_page_content". TYPE: |
create_index_if_not_exist | Automatically create vector index if it does not exist. Default is True. TYPE: |
relevance_score_fn | The 'correct' relevance function. |
region_name | The aws region where the Sagemaker model is deployed, eg. TYPE: |
credentials_profile_name | The name of the profile in the ~/.aws/credentials or ~/.aws/config files, which has either access keys or role information specified. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html TYPE: |
aws_access_key_id | AWS access key id. If provided, aws_secret_access_key must also be provided. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html If not provided, will be read from TYPE: |
aws_secret_access_key | AWS secret_access_key. If provided, aws_access_key_id must also be provided. If not specified, the default credential profile or, if on an EC2 instance, credentials from IMDS will be used. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html If not provided, will be read from TYPE: |
aws_session_token | AWS session token. If provided, aws_access_key_id and aws_secret_access_key must also be provided. Not required unless using temporary credentials. See: https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html If not provided, will be read from TYPE: |
endpoint_url | Needed if you don't want to default to us-east-1 endpoint TYPE: |
config | An optional TYPE: |
client | Boto3 client for s3vectors TYPE: |
kwargs | Arguments to pass to AmazonS3Vectors. TYPE: |
| RETURNS | DESCRIPTION |
|---|---|
AmazonS3Vectors | AmazonS3Vectors initialized from texts and embeddings. |
create_neptune_opencypher_qa_chain( llm: BaseLanguageModel, graph: BaseNeptuneGraph, qa_prompt: BasePromptTemplate = CYPHER_QA_PROMPT, cypher_prompt: BasePromptTemplate | None = None, return_intermediate_steps: bool = False, return_direct: bool = False, extra_instructions: str | None = None, allow_dangerous_requests: bool = False, ) -> Runnable Chain for question-answering against a Neptune graph by generating openCypher statements.
Security note: Make sure that the database connection uses credentials that are narrowly-scoped to only include necessary permissions. Failure to do so may result in data corruption or loss, since the calling code may attempt commands that would result in deletion, mutation of data if appropriately prompted or reading sensitive data if such data is present in the database. The best way to guard against such negative outcomes is to (as appropriate) limit the permissions granted to the credentials used with this tool.
See https://docs.langchain.com/oss/python/security-policy for more information.
create_neptune_sparql_qa_chain( llm: BaseLanguageModel, graph: NeptuneRdfGraph, qa_prompt: BasePromptTemplate = SPARQL_QA_PROMPT, sparql_prompt: BasePromptTemplate | None = None, return_intermediate_steps: bool = False, return_direct: bool = False, extra_instructions: str | None = None, allow_dangerous_requests: bool = False, examples: str | None = None, ) -> Runnable[Any, dict] Chain for question-answering against a Neptune graph by generating SPARQL statements.
Security note: Make sure that the database connection uses credentials that are narrowly-scoped to only include necessary permissions. Failure to do so may result in data corruption or loss, since the calling code may attempt commands that would result in deletion, mutation of data if appropriately prompted or reading sensitive data if such data is present in the database. The best way to guard against such negative outcomes is to (as appropriate) limit the permissions granted to the credentials used with this tool.
See https://docs.langchain.com/oss/python/security-policy for more information.