The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
core: docstrings `messages` (#23788)
Leonid Ganeline30fdc2dbe70a
diff --git a/libs/core/langchain_core/messages/ai.py b/libs/core/langchain_core/messages/ai.pyindex 1311549e9c..693d4545db 100644--- a/libs/core/langchain_core/messages/ai.py+++ b/libs/core/langchain_core/messages/ai.py@@ -73,17 +73,27 @@ class AIMessage(BaseMessage):"""type: Literal["ai"] = "ai"- """The type of the message (used for deserialization)."""+ """The type of the message (used for deserialization). Defaults to "ai"."""def __init__(self, content: Union[str, List[Union[str, Dict]]], **kwargs: Any) -> None:- """Pass in content as positional arg."""+ """Pass in content as positional arg.++ Args:+ content: The content of the message.+ **kwargs: Additional arguments to pass to the parent class.+ """super().__init__(content=content, **kwargs)@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.++ Returns:+ The namespace of the langchain object.+ Defaults to ["langchain", "schema", "messages"].+ """return ["langchain", "schema", "messages"]@property@@ -117,7 +127,15 @@ class AIMessage(BaseMessage):return valuesdef pretty_repr(self, html: bool = False) -> str:- """Return a pretty representation of the message."""+ """Return a pretty representation of the message.++ Args:+ html: Whether to return an HTML-formatted string.+ Defaults to False.++ Returns:+ A pretty representation of the message.+ """base = super().pretty_repr(html=html)lines = []@@ -157,14 +175,21 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):# Ignoring mypy re-assignment here since we're overriding the value# to make sure that the chunk variant can be discriminated from the# non-chunk variant.- type: Literal["AIMessageChunk"] = "AIMessageChunk" # type: ignore[assignment]+ type: Literal["AIMessageChunk"] = "AIMessageChunk" # type: ignore+ """The type of the message (used for deserialization).+ Defaults to "AIMessageChunk"."""tool_call_chunks: List[ToolCallChunk] = []"""If provided, tool call chunks associated with the message."""@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.++ Returns:+ The namespace of the langchain object.+ Defaults to ["langchain", "schema", "messages"].+ """return ["langchain", "schema", "messages"]@property@@ -177,6 +202,17 @@ class AIMessageChunk(AIMessage, BaseMessageChunk):@root_validator(pre=False, skip_on_failure=True)def init_tool_calls(cls, values: dict) -> dict:+ """Initialize tool calls from tool call chunks.++ Args:+ values: The values to validate.++ Returns:+ The values with tool calls initialized.++ Raises:+ ValueError: If the tool call chunks are malformed.+ """if not values["tool_call_chunks"]:if values["tool_calls"]:values["tool_call_chunks"] = [diff --git a/libs/core/langchain_core/messages/base.py b/libs/core/langchain_core/messages/base.pyindex 117a0358c3..d187d4a20b 100644--- a/libs/core/langchain_core/messages/base.py+++ b/libs/core/langchain_core/messages/base.py@@ -57,17 +57,29 @@ class BaseMessage(Serializable):def __init__(self, content: Union[str, List[Union[str, Dict]]], **kwargs: Any) -> None:- """Pass in content as positional arg."""+ """Pass in content as positional arg.++ Args:+ content: The string contents of the message.+ **kwargs: Additional fields to pass to the+ """super().__init__(content=content, **kwargs)@classmethoddef is_lc_serializable(cls) -> bool:- """Return whether this class is serializable."""+ """Return whether this class is serializable. This is used to determine+ whether the class should be included in the langchain schema.++ Returns:+ True if the class is serializable, False otherwise.+ """return True@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.+ Default is ["langchain", "schema", "messages"].+ """return ["langchain", "schema", "messages"]def __add__(self, other: Any) -> ChatPromptTemplate:@@ -78,6 +90,15 @@ class BaseMessage(Serializable):return prompt + otherdef pretty_repr(self, html: bool = False) -> str:+ """Get a pretty representation of the message.++ Args:+ html: Whether to format the message as HTML. If True, the message will be+ formatted with HTML tags. Default is False.++ Returns:+ A pretty representation of the message.+ """title = get_msg_title_repr(self.type.title() + " Message", bold=html)# TODO: handle non-string content.if self.name is not None:@@ -95,8 +116,8 @@ def merge_content("""Merge two message contents.Args:- first_content: The first content.- second_content: The second content.+ first_content: The first content. Can be a string or a list.+ second_content: The second content. Can be a string or a list.Returns:The merged content.@@ -133,7 +154,9 @@ class BaseMessageChunk(BaseMessage):@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.+ Default is ["langchain", "schema", "messages"].+ """return ["langchain", "schema", "messages"]def __add__(self, other: Any) -> BaseMessageChunk: # type: ignore@@ -142,6 +165,16 @@ class BaseMessageChunk(BaseMessage):This functionality is useful to combine message chunks yielded froma streaming model into a complete message.+ Args:+ other: Another message chunk to concatenate with this one.++ Returns:+ A new message chunk that is the concatenation of this message chunk+ and the other message chunk.++ Raises:+ TypeError: If the other object is not a message chunk.+For example,`AIMessageChunk(content="Hello") + AIMessageChunk(content=" World")`@@ -177,7 +210,8 @@ def message_to_dict(message: BaseMessage) -> dict:message: Message to convert.Returns:- Message as a dict.+ Message as a dict. The dict will have a "type" key with the message type+ and a "data" key with the message data as a dict."""return {"type": message.type, "data": message.dict()}@@ -199,7 +233,7 @@ def get_msg_title_repr(title: str, *, bold: bool = False) -> str:Args:title: The title.- bold: Whether to bold the title.+ bold: Whether to bold the title. Default is False.Returns:The title representation.diff --git a/libs/core/langchain_core/messages/chat.py b/libs/core/langchain_core/messages/chat.pyindex 59e36f004f..dbbe05a2b8 100644--- a/libs/core/langchain_core/messages/chat.py+++ b/libs/core/langchain_core/messages/chat.py@@ -15,11 +15,13 @@ class ChatMessage(BaseMessage):"""The speaker / role of the Message."""type: Literal["chat"] = "chat"- """The type of the message (used during serialization)."""+ """The type of the message (used during serialization). Defaults to "chat"."""@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.+ Default is ["langchain", "schema", "messages"].+ """return ["langchain", "schema", "messages"]@@ -33,11 +35,14 @@ class ChatMessageChunk(ChatMessage, BaseMessageChunk):# to make sure that the chunk variant can be discriminated from the# non-chunk variant.type: Literal["ChatMessageChunk"] = "ChatMessageChunk" # type: ignore- """The type of the message (used during serialization)."""+ """The type of the message (used during serialization).+ Defaults to "ChatMessageChunk"."""@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.+ Default is ["langchain", "schema", "messages"].+ """return ["langchain", "schema", "messages"]def __add__(self, other: Any) -> BaseMessageChunk: # type: ignorediff --git a/libs/core/langchain_core/messages/function.py b/libs/core/langchain_core/messages/function.pyindex 21a910470a..5625a3214d 100644--- a/libs/core/langchain_core/messages/function.py+++ b/libs/core/langchain_core/messages/function.py@@ -23,11 +23,12 @@ class FunctionMessage(BaseMessage):"""The name of the function that was executed."""type: Literal["function"] = "function"- """The type of the message (used for serialization)."""+ """The type of the message (used for serialization). Defaults to "function"."""@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.+ Default is ["langchain", "schema", "messages"]."""return ["langchain", "schema", "messages"]@@ -41,10 +42,13 @@ class FunctionMessageChunk(FunctionMessage, BaseMessageChunk):# to make sure that the chunk variant can be discriminated from the# non-chunk variant.type: Literal["FunctionMessageChunk"] = "FunctionMessageChunk" # type: ignore[assignment]+ """The type of the message (used for serialization).+ Defaults to "FunctionMessageChunk"."""@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.+ Default is ["langchain", "schema", "messages"]."""return ["langchain", "schema", "messages"]def __add__(self, other: Any) -> BaseMessageChunk: # type: ignorediff --git a/libs/core/langchain_core/messages/human.py b/libs/core/langchain_core/messages/human.pyindex 1c930e5dc9..18b37e4c04 100644--- a/libs/core/langchain_core/messages/human.py+++ b/libs/core/langchain_core/messages/human.py@@ -32,19 +32,27 @@ class HumanMessage(BaseMessage):"""Use to denote that a message is part of an example conversation.At the moment, this is ignored by most models. Usage is discouraged.+ Defaults to False."""type: Literal["human"] = "human"+ """The type of the message (used for serialization). Defaults to "human"."""@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.+ Default is ["langchain", "schema", "messages"]."""return ["langchain", "schema", "messages"]def __init__(self, content: Union[str, List[Union[str, Dict]]], **kwargs: Any) -> None:- """Pass in content as positional arg."""+ """Pass in content as positional arg.++ Args:+ content: The string contents of the message.+ **kwargs: Additional fields to pass to the message.+ """super().__init__(content=content, **kwargs)@@ -58,8 +66,11 @@ class HumanMessageChunk(HumanMessage, BaseMessageChunk):# to make sure that the chunk variant can be discriminated from the# non-chunk variant.type: Literal["HumanMessageChunk"] = "HumanMessageChunk" # type: ignore[assignment]+ """The type of the message (used for serialization).+ Defaults to "HumanMessageChunk"."""@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.+ Default is ["langchain", "schema", "messages"]."""return ["langchain", "schema", "messages"]diff --git a/libs/core/langchain_core/messages/modifier.py b/libs/core/langchain_core/messages/modifier.pyindex 3ea753892d..7eff055aa0 100644--- a/libs/core/langchain_core/messages/modifier.py+++ b/libs/core/langchain_core/messages/modifier.py@@ -9,8 +9,18 @@ class RemoveMessage(BaseMessage):"""Message responsible for deleting other messages."""type: Literal["remove"] = "remove"+ """The type of the message (used for serialization). Defaults to "remove"."""def __init__(self, id: str, **kwargs: Any) -> None:+ """Create a RemoveMessage.++ Args:+ id: The ID of the message to remove.+ **kwargs: Additional fields to pass to the message.++ Raises:+ ValueError: If the 'content' field is passed in kwargs.+ """if kwargs.pop("content", None):raise ValueError("RemoveMessage does not support 'content' field.")@@ -18,7 +28,8 @@ class RemoveMessage(BaseMessage):@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.+ Default is ["langchain", "schema", "messages"]."""return ["langchain", "schema", "messages"]diff --git a/libs/core/langchain_core/messages/system.py b/libs/core/langchain_core/messages/system.pyindex a2ab0adf98..3e3255a999 100644--- a/libs/core/langchain_core/messages/system.py+++ b/libs/core/langchain_core/messages/system.py@@ -30,16 +30,23 @@ class SystemMessage(BaseMessage):"""type: Literal["system"] = "system"+ """The type of the message (used for serialization). Defaults to "system"."""@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.+ Default is ["langchain", "schema", "messages"]."""return ["langchain", "schema", "messages"]def __init__(self, content: Union[str, List[Union[str, Dict]]], **kwargs: Any) -> None:- """Pass in content as positional arg."""+ """Pass in content as positional arg.++ Args:+ content: The string contents of the message.+ **kwargs: Additional fields to pass to the message.+ """super().__init__(content=content, **kwargs)@@ -53,8 +60,11 @@ class SystemMessageChunk(SystemMessage, BaseMessageChunk):# to make sure that the chunk variant can be discriminated from the# non-chunk variant.type: Literal["SystemMessageChunk"] = "SystemMessageChunk" # type: ignore[assignment]+ """The type of the message (used for serialization).+ Defaults to "SystemMessageChunk"."""@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.+ Default is ["langchain", "schema", "messages"]."""return ["langchain", "schema", "messages"]diff --git a/libs/core/langchain_core/messages/tool.py b/libs/core/langchain_core/messages/tool.pyindex 9d91e97aab..9855f743ef 100644--- a/libs/core/langchain_core/messages/tool.py+++ b/libs/core/langchain_core/messages/tool.py@@ -37,16 +37,23 @@ class ToolMessage(BaseMessage):# """Whether the tool errored."""type: Literal["tool"] = "tool"+ """The type of the message (used for serialization). Defaults to "tool"."""@classmethoddef get_lc_namespace(cls) -> List[str]:- """Get the namespace of the langchain object."""+ """Get the namespace of the langchain object.+ Default is ["langchain", "schema", "messages"]."""return ["langchain", "schema", "messages"]def __init__(self, content: Union[str, List[Union[str, Dict]]], **kwargs: Any) -> None:- """Pass in content as positional arg."""+ """Pass in content as positional arg.++ Args:+ content: The string contents of the message.+ **kwargs: Additional fields to pass to the message+ """super().__init__(content=content, **kwargs)diff --git a/libs/core/langchain_core/messages/utils.py b/libs/core/langchain_core/messages/utils.pyindex edda11d155..ce04ec8a86 100644--- a/libs/core/langchain_core/messages/utils.py+++ b/libs/core/langchain_core/messages/utils.py@@ -6,6 +6,7 @@ Some examples of what you can do with these functions include:* Convert messages from dicts to Message objects (deserialization)* Filter messages from a list of messages based on name, type or id etc."""+from __future__ import annotationsimport inspect@@ -53,11 +54,15 @@ def get_buffer_string(Args:messages: Messages to be converted to strings.human_prefix: The prefix to prepend to contents of HumanMessages.- ai_prefix: THe prefix to prepend to contents of AIMessages.+ Default is "Human".+ ai_prefix: THe prefix to prepend to contents of AIMessages. Default is "AI".Returns:A single string concatenation of all input messages.+ Raises:+ ValueError: If an unsupported message type is encountered.+Example:.. code-block:: python@@ -173,11 +178,20 @@ def _create_message_from_message_type("""Create a message from a message type and content string.Args:- message_type: str the type of the message (e.g., "human", "ai", etc.)- content: str the content string.+ message_type: (str) the type of the message (e.g., "human", "ai", etc.).+ content: (str) the content string.+ name: (str) the name of the message. Default is None.+ tool_call_id: (str) the tool call id. Default is None.+ tool_calls: (List[Dict[str, Any]]) the tool calls. Default is None.+ id: (str) the id of the message. Default is None.+ **additional_kwargs: (Dict[str, Any]) additional keyword arguments.Returns:a message of the appropriate type.++ Raises:+ ValueError: if the message type is not one of "human", "user", "ai",+ "assistant", "system", "function", or "tool"."""kwargs: Dict[str, Any] = {}if name is not None:@@ -203,7 +217,7 @@ def _create_message_from_message_type(else:raise ValueError(f"Unexpected message type: {message_type}. Use one of 'human',"- f" 'user', 'ai', 'assistant', or 'system'."+ f" 'user', 'ai', 'assistant', 'function', 'tool', or 'system'.")return message@@ -220,10 +234,14 @@ def _convert_to_message(message: MessageLikeRepresentation) -> BaseMessage:- string: shorthand for ("human", template); e.g., "{user_input}"Args:- message: a representation of a message in one of the supported formats+ message: a representation of a message in one of the supported formats.Returns:- an instance of a message or a message template+ an instance of a message or a message template.++ Raises:+ NotImplementedError: if the message type is not supported.+ ValueError: if the message dict does not contain the required keys."""if isinstance(message, BaseMessage):_message = message@@ -315,16 +333,16 @@ def filter_messages(Args:messages: Sequence Message-like objects to filter.- include_names: Message names to include.- exclude_names: Messages names to exclude.+ include_names: Message names to include. Default is None.+ exclude_names: Messages names to exclude. Default is None.include_types: Message types to include. Can be specified as string names (e.g."system", "human", "ai", ...) or as BaseMessage classes (e.g.- SystemMessage, HumanMessage, AIMessage, ...).+ SystemMessage, HumanMessage, AIMessage, ...). Default is None.exclude_types: Message types to exclude. Can be specified as string names (e.g."system", "human", "ai", ...) or as BaseMessage classes (e.g.- SystemMessage, HumanMessage, AIMessage, ...).- include_ids: Message IDs to include.- exclude_ids: Message IDs to exclude.+ SystemMessage, HumanMessage, AIMessage, ...). Default is None.+ include_ids: Message IDs to include. Default is None.+ exclude_ids: Message IDs to exclude. Default is None.Returns:A list of Messages that meets at least one of the incl_* conditions and none@@ -509,10 +527,12 @@ def trim_messages(strategy: Strategy for trimming.- "first": Keep the first <= n_count tokens of the messages.- "last": Keep the last <= n_count tokens of the messages.+ Default is "last".allow_partial: Whether to split a message if only part of the message can beincluded. If ``strategy="last"`` then the last partial contents of a messageare included. If ``strategy="first"`` then the first partial contents of amessage are included.+ Default is False.end_on: The message type to end on. If specified then every message after thelast occurrence of this type is ignored. If ``strategy=="last"`` then thisis done before we attempt to get the last ``max_tokens``. If@@ -520,6 +540,7 @@ def trim_messages(``max_tokens``. Can be specified as string names (e.g. "system", "human","ai", ...) or as BaseMessage classes (e.g. SystemMessage, HumanMessage,AIMessage, ...). Can be a single type or a list of types.+ Default is None.start_on: The message type to start on. Should only be specified if``strategy="last"``. If specified then every message beforethe first occurrence of this type is ignored. This is done after we trim@@ -528,8 +549,10 @@ def trim_messages(specified as string names (e.g. "system", "human", "ai", ...) or asBaseMessage classes (e.g. SystemMessage, HumanMessage, AIMessage, ...). Canbe a single type or a list of types.+ Default is None.include_system: Whether to keep the SystemMessage if there is one at index 0.Should only be specified if ``strategy="last"``.+ Default is False.text_splitter: Function or ``langchain_text_splitters.TextSplitter`` forsplitting the string contents of a message. Only used if``allow_partial=True``. If ``strategy="last"`` then the last split tokens