The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
core[patch]: docstrings `agents` (#23502)
Leonid Ganeline2c9b84c3a86b
diff --git a/libs/core/langchain_core/agents.py b/libs/core/langchain_core/agents.pyindex cfe0396dac..5cc757925c 100644--- a/libs/core/langchain_core/agents.py+++ b/libs/core/langchain_core/agents.py@@ -5,10 +5,10 @@New agents should be built using the langgraph library(https://github.com/langchain-ai/langgraph)), which provides a simplerand more flexible way to define agents.-- Please see the migration guide for information on how to migrate existing- agents to modern langgraph agents:- https://python.langchain.com/v0.2/docs/how_to/migrate_agent/++ Please see the migration guide for information on how to migrate existing+ agents to modern langgraph agents:+ https://python.langchain.com/v0.2/docs/how_to/migrate_agent/Agents use language models to choose a sequence of actions to take.@@ -21,6 +21,7 @@ A basic agent works in the following manner:The schemas for the agents themselves are defined in langchain.agents.agent.""" # noqa: E501+from __future__ import annotationsimport json@@ -193,9 +194,11 @@ def _create_function_message(agent_action: AgentAction, observation: Any) -> FunctionMessage:"""Convert agent action and observation into a function message.+Args:agent_action: the tool invocation request from the agentobservation: the result of the tool invocation+Returns:FunctionMessage that corresponds to the original tool invocation"""diff --git a/libs/core/langchain_core/caches.py b/libs/core/langchain_core/caches.pyindex 2e37e028cd..8b9f63be47 100644--- a/libs/core/langchain_core/caches.py+++ b/libs/core/langchain_core/caches.py@@ -19,6 +19,7 @@ Cache directly competes with Memory. See documentation for Pros and Cons.BaseCache --> <name>Cache # Examples: InMemoryCache, RedisCache, GPTCache"""+from __future__ import annotationsfrom abc import ABC, abstractmethod@@ -31,7 +32,7 @@ RETURN_VAL_TYPE = Sequence[Generation]class BaseCache(ABC):- """This interfaces provides a caching layer for LLMs and Chat models.+ """Interface for a caching layer for LLMs and Chat models.The cache interface consists of the following methods:@@ -73,7 +74,7 @@ class BaseCache(ABC):"""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.+ The key should match that of the lookup method.Args:prompt: a string representation of the prompt.@@ -93,7 +94,7 @@ class BaseCache(ABC):"""Clear cache that can take additional keyword arguments."""async def alookup(self, prompt: str, llm_string: str) -> Optional[RETURN_VAL_TYPE]:- """Look up based on prompt and llm_string.+ """Async look up based on prompt and llm_string.A cache implementation is expected to generate a key from the 2-tupleof prompt and llm_string (e.g., by concatenating them with a delimiter).@@ -117,7 +118,7 @@ class BaseCache(ABC):async def aupdate(self, prompt: str, llm_string: str, return_val: RETURN_VAL_TYPE) -> None:- """Update cache based on prompt and llm_string.+ """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.@@ -137,7 +138,7 @@ class BaseCache(ABC):return await run_in_executor(None, self.update, prompt, llm_string, return_val)async def aclear(self, **kwargs: Any) -> None:- """Clear cache that can take additional keyword arguments."""+ """Async clear cache that can take additional keyword arguments."""return await run_in_executor(None, self.clear, **kwargs)@@ -149,11 +150,30 @@ class InMemoryCache(BaseCache):self._cache: Dict[Tuple[str, str], RETURN_VAL_TYPE] = {}def lookup(self, prompt: str, llm_string: str) -> Optional[RETURN_VAL_TYPE]:- """Look up based on prompt and llm_string."""+ """Look up based on prompt and llm_string.++ Args:+ 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.+ llm_string: A string representation of the LLM configuration.++ Returns:+ On a cache miss, return None. On a cache hit, return the cached value.+ """return self._cache.get((prompt, llm_string), None)def update(self, prompt: str, llm_string: str, return_val: RETURN_VAL_TYPE) -> None:- """Update cache based on prompt and llm_string."""+ """Update cache based on prompt and llm_string.++ Args:+ 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.+ llm_string: A string representation of the LLM configuration.+ return_val: The value to be cached. The value is a list of Generations+ (or subclasses).+ """self._cache[(prompt, llm_string)] = return_valdef clear(self, **kwargs: Any) -> None:@@ -161,15 +181,34 @@ class InMemoryCache(BaseCache):self._cache = {}async def alookup(self, prompt: str, llm_string: str) -> Optional[RETURN_VAL_TYPE]:- """Look up based on prompt and llm_string."""+ """Async look up based on prompt and llm_string.++ Args:+ 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.+ llm_string: A string representation of the LLM configuration.++ Returns:+ On a cache miss, return None. On a cache hit, return the cached value.+ """return self.lookup(prompt, llm_string)async def aupdate(self, prompt: str, llm_string: str, return_val: RETURN_VAL_TYPE) -> None:- """Update cache based on prompt and llm_string."""+ """Async update cache based on prompt and llm_string.++ Args:+ 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.+ llm_string: A string representation of the LLM configuration.+ return_val: The value to be cached. The value is a list of Generations+ (or subclasses).+ """self.update(prompt, llm_string, return_val)async def aclear(self, **kwargs: Any) -> None:- """Clear cache."""+ """Async clear cache."""self.clear()diff --git a/libs/core/langchain_core/exceptions.py b/libs/core/langchain_core/exceptions.pyindex 05c36a9a90..b6006a1514 100644--- a/libs/core/langchain_core/exceptions.py+++ b/libs/core/langchain_core/exceptions.py@@ -1,4 +1,5 @@-"""Custom **exceptions** for LangChain. """+"""Custom **exceptions** for LangChain."""+from typing import Any, Optional@@ -18,7 +19,7 @@ class OutputParserException(ValueError, LangChainException):available to catch and handle in ways to fix the parsing error, while othererrors will be raised.- Args:+ Parameters:error: The error that's being re-raised or an error message.observation: String explanation of error which can be passed to amodel to try and remediate the issue.diff --git a/libs/core/langchain_core/globals.py b/libs/core/langchain_core/globals.pyindex 89963f4dac..580efb5051 100644--- a/libs/core/langchain_core/globals.py+++ b/libs/core/langchain_core/globals.py@@ -1,5 +1,6 @@# flake8: noqa"""Global values and configuration that apply to all of LangChain."""+import warningsfrom typing import TYPE_CHECKING, Optional@@ -135,7 +136,11 @@ def get_debug() -> bool:def set_llm_cache(value: Optional["BaseCache"]) -> None:- """Set a new LLM cache, overwriting the previous value, if any."""+ """Set a new LLM cache, overwriting the previous value, if any.++ Args:+ value: The new LLM cache to use. If `None`, the LLM cache is disabled.+ """try:import langchain # type: ignore[import]diff --git a/libs/core/langchain_core/memory.py b/libs/core/langchain_core/memory.pyindex f7960cc309..160f481b91 100644--- a/libs/core/langchain_core/memory.py+++ b/libs/core/langchain_core/memory.py@@ -7,6 +7,7 @@BaseMemory --> <name>Memory --> <name>Memory # Examples: BaseChatMemory -> MotorheadMemory""" # noqa: E501+from __future__ import annotationsfrom abc import ABC, abstractmethod@@ -58,20 +59,37 @@ class BaseMemory(Serializable, ABC):@abstractmethoddef load_memory_variables(self, inputs: Dict[str, Any]) -> Dict[str, Any]:- """Return key-value pairs given the text input to the chain."""+ """Return key-value pairs given the text input to the chain.++ Args:+ inputs: The inputs to the chain."""async def aload_memory_variables(self, inputs: Dict[str, Any]) -> Dict[str, Any]:- """Return key-value pairs given the text input to the chain."""+ """Async return key-value pairs given the text input to the chain.++ Args:+ inputs: The inputs to the chain.+ """return await run_in_executor(None, self.load_memory_variables, inputs)@abstractmethoddef save_context(self, inputs: Dict[str, Any], outputs: Dict[str, str]) -> None:- """Save the context of this chain run to memory."""+ """Save the context of this chain run to memory.++ Args:+ inputs: The inputs to the chain.+ outputs: The outputs of the chain.+ """async def asave_context(self, inputs: Dict[str, Any], outputs: Dict[str, str]) -> None:- """Save the context of this chain run to memory."""+ """Async save the context of this chain run to memory.++ Args:+ inputs: The inputs to the chain.+ outputs: The outputs of the chain.+ """await run_in_executor(None, self.save_context, inputs, outputs)@abstractmethod@@ -79,5 +97,5 @@ class BaseMemory(Serializable, ABC):"""Clear memory contents."""async def aclear(self) -> None:- """Clear memory contents."""+ """Async clear memory contents."""await run_in_executor(None, self.clear)diff --git a/libs/core/langchain_core/prompt_values.py b/libs/core/langchain_core/prompt_values.pyindex a3ad813cd5..996116ee44 100644--- a/libs/core/langchain_core/prompt_values.py+++ b/libs/core/langchain_core/prompt_values.py@@ -3,6 +3,7 @@Prompt values are used to represent different pieces of prompts.They can be used to represent text, images, or chat message pieces."""+from __future__ import annotationsfrom abc import ABC, abstractmethod@@ -103,15 +104,15 @@ class ImagePromptValue(PromptValue):"""Image prompt value."""image_url: ImageURL- """Prompt image."""+ """Image URL."""type: Literal["ImagePromptValue"] = "ImagePromptValue"def to_string(self) -> str:- """Return prompt as string."""+ """Return prompt (image URL) as string."""return self.image_url["url"]def to_messages(self) -> List[BaseMessage]:- """Return prompt as messages."""+ """Return prompt (image URL) as messages."""return [HumanMessage(content=[cast(dict, self.image_url)])]@@ -120,6 +121,7 @@ class ChatPromptValueConcrete(ChatPromptValue):For use in external schemas."""messages: Sequence[AnyMessage]+ """Sequence of messages."""type: Literal["ChatPromptValueConcrete"] = "ChatPromptValueConcrete"diff --git a/libs/core/langchain_core/retrievers.py b/libs/core/langchain_core/retrievers.pyindex c42311a442..bd4fcbbad3 100644--- a/libs/core/langchain_core/retrievers.py+++ b/libs/core/langchain_core/retrievers.py@@ -18,6 +18,7 @@ the backbone of a retriever, but there are other types of retrievers as well.Document, Serializable, Callbacks,CallbackManagerForRetrieverRun, AsyncCallbackManagerForRetrieverRun"""+from __future__ import annotationsimport warnings@@ -119,14 +120,14 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):_new_arg_supported: bool = False_expects_other_args: bool = Falsetags: Optional[List[str]] = None- """Optional list of tags associated with the retriever. Defaults to None+ """Optional list of tags associated with the retriever. Defaults to None.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 itsuse case."""metadata: Optional[Dict[str, Any]] = None- """Optional metadata associated with the retriever. Defaults to None+ """Optional metadata associated with the retriever. Defaults to None.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@@ -289,9 +290,10 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):self, query: str, *, run_manager: CallbackManagerForRetrieverRun) -> List[Document]:"""Get documents relevant to a query.+Args:query: String to find relevant documents for- run_manager: The callbacks handler to use+ run_manager: The callback handler to useReturns:List of relevant documents"""@@ -300,9 +302,10 @@ class BaseRetriever(RunnableSerializable[RetrieverInput, RetrieverOutput], ABC):self, query: str, *, run_manager: AsyncCallbackManagerForRetrieverRun) -> List[Document]:"""Asynchronously get documents relevant to a query.+Args:query: String to find relevant documents for- run_manager: The callbacks handler to use+ run_manager: The callback handler to useReturns:List of relevant documents"""diff --git a/libs/core/langchain_core/stores.py b/libs/core/langchain_core/stores.pyindex 96a9829619..3d692170ed 100644--- a/libs/core/langchain_core/stores.py+++ b/libs/core/langchain_core/stores.py@@ -5,6 +5,7 @@ to a simple key-value interface.The primary goal of these storages is to support implementation of caching."""+from abc import ABC, abstractmethodfrom typing import (Any,@@ -95,7 +96,7 @@ class BaseStore(Generic[K, V], ABC):"""async def amget(self, keys: Sequence[K]) -> List[Optional[V]]:- """Get the values associated with the given keys.+ """Async get the values associated with the given keys.Args:keys (Sequence[K]): A sequence of keys.@@ -115,7 +116,7 @@ class BaseStore(Generic[K, V], ABC):"""async def amset(self, key_value_pairs: Sequence[Tuple[K, V]]) -> None:- """Set the values for the given keys.+ """Async set the values for the given keys.Args:key_value_pairs (Sequence[Tuple[K, V]]): A sequence of key-value pairs.@@ -131,7 +132,7 @@ class BaseStore(Generic[K, V], ABC):"""async def amdelete(self, keys: Sequence[K]) -> None:- """Delete the given keys and their associated values.+ """Async delete the given keys and their associated values.Args:keys (Sequence[K]): A sequence of keys to delete.@@ -147,7 +148,7 @@ class BaseStore(Generic[K, V], ABC):Args:prefix (str): The prefix to match.- Returns:+ Yields:Iterator[K | str]: An iterator over keys that match the given prefix.This method is allowed to return an iterator over either K or str@@ -157,12 +158,12 @@ class BaseStore(Generic[K, V], ABC):async def ayield_keys(self, *, prefix: Optional[str] = None) -> Union[AsyncIterator[K], AsyncIterator[str]]:- """Get an iterator over keys that match the given prefix.+ """Async get an iterator over keys that match the given prefix.Args:prefix (str): The prefix to match.- Returns:+ Yields:Iterator[K | str]: An iterator over keys that match the given prefix.This method is allowed to return an iterator over either K or str@@ -200,7 +201,7 @@ class InMemoryBaseStore(BaseStore[str, V], Generic[V]):return [self.store.get(key) for key in keys]async def amget(self, keys: Sequence[str]) -> List[Optional[V]]:- """Get the values associated with the given keys.+ """Async get the values associated with the given keys.Args:keys (Sequence[str]): A sequence of keys.@@ -224,7 +225,7 @@ class InMemoryBaseStore(BaseStore[str, V], Generic[V]):self.store[key] = valueasync def amset(self, key_value_pairs: Sequence[Tuple[str, V]]) -> None:- """Set the values for the given keys.+ """Async set the values for the given keys.Args:key_value_pairs (Sequence[Tuple[str, V]]): A sequence of key-value pairs.@@ -245,7 +246,7 @@ class InMemoryBaseStore(BaseStore[str, V], Generic[V]):del self.store[key]async def amdelete(self, keys: Sequence[str]) -> None:- """Delete the given keys and their associated values.+ """Async delete the given keys and their associated values.Args:keys (Sequence[str]): A sequence of keys to delete.@@ -258,7 +259,7 @@ class InMemoryBaseStore(BaseStore[str, V], Generic[V]):Args:prefix (str, optional): The prefix to match. Defaults to None.- Returns:+ Yields:Iterator[str]: An iterator over keys that match the given prefix."""if prefix is None:@@ -269,12 +270,12 @@ class InMemoryBaseStore(BaseStore[str, V], Generic[V]):yield keyasync def ayield_keys(self, prefix: Optional[str] = None) -> AsyncIterator[str]:- """Get an async iterator over keys that match the given prefix.+ """Async get an async iterator over keys that match the given prefix.Args:prefix (str, optional): The prefix to match. Defaults to None.- Returns:+ Yields:AsyncIterator[str]: An async iterator over keys that match the given prefix."""if prefix is None: