langchain-core 0.3.76__py3-none-any.whl → 0.3.77__py3-none-any.whl

langchain_core/messages/utils.py

@@ -5,6 +5,7 @@ Some examples of what you can do with these functions include:
 * Convert messages to strings (serialization)
 * 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 annotations
@@ -91,13 +92,14 @@ AnyMessage = Annotated[
 def get_buffer_string(
     messages: Sequence[BaseMessage], human_prefix: str = "Human", ai_prefix: str = "AI"
 ) -> str:
-    r"""Convert a sequence of Messages to strings and concatenate them into one string.
+    r"""Convert a sequence of messages to strings and concatenate them into one string.
 
     Args:
         messages: Messages to be converted to strings.
-        human_prefix: The prefix to prepend to contents of HumanMessages.
-            Default is "Human".
-        ai_prefix: THe prefix to prepend to contents of AIMessages. Default is "AI".
+        human_prefix: The prefix to prepend to contents of ``HumanMessage``s.
+            Default is ``'Human'``.
+        ai_prefix: The prefix to prepend to contents of ``AIMessage``. Default is
+            ``'AI'``.
 
     Returns:
         A single string concatenation of all input messages.
@@ -176,19 +178,20 @@ def _message_from_dict(message: dict) -> BaseMessage:
 
 
 def messages_from_dict(messages: Sequence[dict]) -> list[BaseMessage]:
-    """Convert a sequence of messages from dicts to Message objects.
+    """Convert a sequence of messages from dicts to ``Message`` objects.
 
     Args:
         messages: Sequence of messages (as dicts) to convert.
 
     Returns:
         list of messages (BaseMessages).
+
     """
     return [_message_from_dict(m) for m in messages]
 
 
 def message_chunk_to_message(chunk: BaseMessage) -> BaseMessage:
-    """Convert a message chunk to a message.
+    """Convert a message chunk to a ``Message``.
 
     Args:
         chunk: Message chunk to convert.
@@ -221,10 +224,10 @@ def _create_message_from_message_type(
     id: Optional[str] = None,
     **additional_kwargs: Any,
 ) -> BaseMessage:
-    """Create a message from a message type and content string.
+    """Create a message from a ``Message`` type and content string.
 
     Args:
-        message_type: (str) the type of the message (e.g., "human", "ai", etc.).
+        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.
@@ -236,8 +239,9 @@ def _create_message_from_message_type(
         a message of the appropriate type.
 
     Raises:
-        ValueError: if the message type is not one of "human", "user", "ai",
-            "assistant", "function", "tool", "system", or "developer".
+        ValueError: if the message type is not one of ``'human'``, ``'user'``, ``'ai'``,
+            ``'assistant'``, ``'function'``, ``'tool'``, ``'system'``, or
+            ``'developer'``.
     """
     kwargs: dict[str, Any] = {}
     if name is not None:
@@ -286,6 +290,9 @@ def _create_message_from_message_type(
         message = FunctionMessage(content=content, **kwargs)
     elif message_type == "tool":
         artifact = kwargs.get("additional_kwargs", {}).pop("artifact", None)
+        status = kwargs.get("additional_kwargs", {}).pop("status", None)
+        if status is not None:
+            kwargs["status"] = status
         message = ToolMessage(content=content, artifact=artifact, **kwargs)
     elif message_type == "remove":
         message = RemoveMessage(**kwargs)
@@ -300,15 +307,15 @@ def _create_message_from_message_type(
 
 
 def _convert_to_message(message: MessageLikeRepresentation) -> BaseMessage:
-    """Instantiate a message from a variety of message formats.
+    """Instantiate a ``Message`` from a variety of message formats.
 
     The message format can be one of the following:
 
-    - BaseMessagePromptTemplate
-    - BaseMessage
-    - 2-tuple of (role string, template); e.g., ("human", "{user_input}")
+    - ``BaseMessagePromptTemplate``
+    - ``BaseMessage``
+    - 2-tuple of (role string, template); e.g., (``'human'``, ``'{user_input}'``)
     - dict: a message dict with role and content keys
-    - string: shorthand for ("human", template); e.g., "{user_input}"
+    - string: shorthand for (``'human'``, template); e.g., ``'{user_input}'``
 
     Args:
         message: a representation of a message in one of the supported formats.
@@ -319,6 +326,7 @@ def _convert_to_message(message: MessageLikeRepresentation) -> BaseMessage:
     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
@@ -364,6 +372,7 @@ def convert_to_messages(
 
     Returns:
         list of messages (BaseMessages).
+
     """
     # Import here to avoid circular imports
     from langchain_core.prompt_values import PromptValue  # noqa: PLC0415
@@ -414,36 +423,36 @@ def filter_messages(
     exclude_ids: Optional[Sequence[str]] = None,
     exclude_tool_calls: Optional[Sequence[str] | bool] = None,
 ) -> list[BaseMessage]:
-    """Filter messages based on name, type or id.
+    """Filter messages based on ``name``, ``type`` or ``id``.
 
     Args:
         messages: Sequence Message-like objects to filter.
         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, ...). 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, ...). 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``, ...).
+            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``, ...).
+            Default is None.
         include_ids: Message IDs to include. Default is None.
         exclude_ids: Message IDs to exclude. Default is None.
         exclude_tool_calls: Tool call IDs to exclude. Default is None.
             Can be one of the following:
-
-            - ``True``: Each ``AIMessages`` with tool calls and all ``ToolMessages``
-              will be excluded.
+            - ``True``: all ``AIMessage``s with tool calls and all
+              ``ToolMessage``s will be excluded.
             - a sequence of tool call IDs to exclude:
-
-              - ToolMessages with the corresponding tool call ID will be excluded.
-              - The ``tool_calls`` in the AIMessage will be updated to exclude matching
-                tool calls.
-                If all tool_calls are filtered from an AIMessage,
-                the whole message is excluded.
+              - ``ToolMessage``s with the corresponding tool call ID will be
+                excluded.
+              - The ``tool_calls`` in the AIMessage will be updated to exclude
+                matching tool calls. If all ``tool_calls`` are filtered from an
+                AIMessage, the whole message is excluded.
 
     Returns:
-        A list of Messages that meets at least one of the incl_* conditions and none
-        of the excl_* conditions. If not incl_* conditions are specified then
+        A list of Messages that meets at least one of the ``incl_*`` conditions and none
+        of the ``excl_*`` conditions. If not ``incl_*`` conditions are specified then
         anything that is not explicitly excluded will be included.
 
     Raises:
@@ -555,13 +564,14 @@ def merge_message_runs(
 ) -> list[BaseMessage]:
     r"""Merge consecutive Messages of the same type.
 
-    **NOTE**: ToolMessages are not merged, as each has a distinct tool call id that
-    can't be merged.
+    .. note::
+        ToolMessages are not merged, as each has a distinct tool call id that can't be
+        merged.
 
     Args:
         messages: Sequence Message-like objects to merge.
         chunk_separator: Specify the string to be inserted between message chunks.
-        Default is "\n".
+        Default is ``'\n'``.
 
     Returns:
         list of BaseMessages with consecutive runs of message types merged into single
@@ -702,8 +712,8 @@ def trim_messages(
 ) -> list[BaseMessage]:
     r"""Trim messages to be below a token count.
 
-    trim_messages can be used to reduce the size of a chat history to a specified token
-    count or specified message count.
+    ``trim_messages`` can be used to reduce the size of a chat history to a specified
+    token count or specified message count.
 
     In either case, if passing the trimmed chat history back into a chat model
     directly, the resulting chat history should usually satisfy the following
@@ -711,13 +721,13 @@ def trim_messages(
 
     1. The resulting chat history should be valid. Most chat models expect that chat
        history starts with either (1) a ``HumanMessage`` or (2) a ``SystemMessage``
-       followed by a ``HumanMessage``. To achieve this, set ``start_on="human"``.
+       followed by a ``HumanMessage``. To achieve this, set ``start_on='human'``.
        In addition, generally a ``ToolMessage`` can only appear after an ``AIMessage``
        that involved a tool call.
        Please see the following link for more information about messages:
        https://python.langchain.com/docs/concepts/#messages
     2. It includes recent messages and drops old messages in the chat history.
-       To achieve this set the ``strategy="last"``.
+       To achieve this set the ``strategy='last'``.
     3. Usually, the new chat history should include the ``SystemMessage`` if it
        was present in the original chat history since the ``SystemMessage`` includes
        special instructions to the chat model. The ``SystemMessage`` is almost always
@@ -731,67 +741,67 @@ def trim_messages(
     Args:
         messages: Sequence of Message-like objects to trim.
         max_tokens: Max token count of trimmed messages.
-        token_counter: Function or llm for counting tokens in a BaseMessage or a list of
-            BaseMessage. If a BaseLanguageModel is passed in then
-            BaseLanguageModel.get_num_tokens_from_messages() will be used.
-            Set to `len` to count the number of **messages** in the chat history.
+        token_counter: Function or llm for counting tokens in a ``BaseMessage`` or a
+            list of ``BaseMessage``. If a ``BaseLanguageModel`` is passed in then
+            ``BaseLanguageModel.get_num_tokens_from_messages()`` will be used.
+            Set to ``len`` to count the number of **messages** in the chat history.
 
             .. note::
-                Use `count_tokens_approximately` to get fast, approximate token counts.
-                This is recommended for using `trim_messages` on the hot path, where
+                Use ``count_tokens_approximately`` to get fast, approximate token
+                counts.
+                This is recommended for using ``trim_messages`` on the hot path, where
                 exact token counting is not necessary.
 
         strategy: Strategy for trimming.
-
-            - "first": Keep the first <= n_count tokens of the messages.
-            - "last": Keep the last <= n_count tokens of the messages.
-
+            - ``'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 be
-            included. If ``strategy="last"`` then the last partial contents of a message
-            are included. If ``strategy="first"`` then the first partial contents of a
+            included. If ``strategy='last'`` then the last partial contents of a message
+            are included. If ``strategy='first'`` then the first partial contents of a
             message are included.
             Default is False.
         end_on: The message type to end on. If specified then every message after the
-            last occurrence of this type is ignored. If ``strategy=="last"`` then this
+            last occurrence of this type is ignored. If ``strategy='last'`` then this
             is done before we attempt to get the last ``max_tokens``. If
-            ``strategy=="first"`` then this is done after we get the first
-            ``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.
+            ``strategy='first'`` then this is done after we get the first
+            ``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 before
+            ``strategy='last'``. If specified then every message before
             the first occurrence of this type is ignored. This is done after we trim
             the initial messages to the last ``max_tokens``. Does not
-            apply to a SystemMessage at index 0 if ``include_system=True``. 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.
+            apply to a ``SystemMessage`` at index 0 if ``include_system=True``. 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.
         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`` for
             splitting the string contents of a message. Only used if
-            ``allow_partial=True``. If ``strategy="last"`` then the last split tokens
-            from a partial message will be included. if ``strategy=="first"`` then the
+            ``allow_partial=True``. If ``strategy='last'`` then the last split tokens
+            from a partial message will be included. if ``strategy='first'`` then the
             first split tokens from a partial message will be included. Token splitter
             assumes that separators are kept, so that split contents can be directly
             concatenated to recreate the original text. Defaults to splitting on
             newlines.
 
     Returns:
-        list of trimmed BaseMessages.
+        list of trimmed ``BaseMessage``.
 
     Raises:
         ValueError: if two incompatible arguments are specified or an unrecognized
             ``strategy`` is specified.
 
     Example:
-        Trim chat history based on token count, keeping the SystemMessage if
-        present, and ensuring that the chat history starts with a HumanMessage (
-        or a SystemMessage followed by a HumanMessage).
+        Trim chat history based on token count, keeping the ``SystemMessage`` if
+        present, and ensuring that the chat history starts with a ``HumanMessage`` (
+        or a ``SystemMessage`` followed by a ``HumanMessage``).
 
         .. code-block:: python
 
@@ -846,9 +856,9 @@ def trim_messages(
                 HumanMessage(content="what do you call a speechless parrot"),
             ]
 
-        Trim chat history based on the message count, keeping the SystemMessage if
-        present, and ensuring that the chat history starts with a HumanMessage (
-        or a SystemMessage followed by a HumanMessage).
+        Trim chat history based on the message count, keeping the ``SystemMessage`` if
+        present, and ensuring that the chat history starts with a ``HumanMessage`` (
+        or a ``SystemMessage`` followed by a ``HumanMessage``).
 
             trim_messages(
                 messages,
@@ -1037,17 +1047,16 @@ def convert_to_openai_messages(
         messages: Message-like object or iterable of objects whose contents are
             in OpenAI, Anthropic, Bedrock Converse, or VertexAI formats.
         text_format: How to format string or text block contents:
-
-            - ``'string'``:
-              If a message has a string content, this is left as a string. If
-              a message has content blocks that are all of type 'text', these are
-              joined with a newline to make a single string. If a message has
-              content blocks and at least one isn't of type 'text', then
-              all blocks are left as dicts.
-            - ``'block'``:
-              If a message has a string content, this is turned into a list
-              with a single content block of type 'text'. If a message has content
-              blocks these are left as is.
+                - ``'string'``:
+                    If a message has a string content, this is left as a string. If
+                    a message has content blocks that are all of type ``'text'``, these
+                    are joined with a newline to make a single string. If a message has
+                    content blocks and at least one isn't of type ``'text'``, then
+                    all blocks are left as dicts.
+                - ``'block'``:
+                    If a message has a string content, this is turned into a list
+                    with a single content block of type ``'text'``. If a message has
+                    content blocks these are left as is.
 
     Raises:
         ValueError: if an unrecognized ``text_format`` is specified, or if a message
@@ -1376,7 +1385,7 @@ def convert_to_openai_messages(
                             },
                         }
                     )
-                elif block.get("type") == "thinking":
+                elif block.get("type") in ["thinking", "reasoning"]:
                     content.append(block)
                 else:
                     err = (

langchain_core/outputs/chat_generation.py

@@ -15,14 +15,14 @@ from langchain_core.utils._merge import merge_dicts
 class ChatGeneration(Generation):
     """A single chat generation output.
 
-    A subclass of Generation that represents the response from a chat model
+    A subclass of ``Generation`` that represents the response from a chat model
     that generates chat messages.
 
-    The `message` attribute is a structured representation of the chat message.
-    Most of the time, the message will be of type `AIMessage`.
+    The ``message`` attribute is a structured representation of the chat message.
+    Most of the time, the message will be of type ``AIMessage``.
 
     Users working with chat models will usually access information via either
-    `AIMessage` (returned from runnable interfaces) or `LLMResult` (available
+    ``AIMessage`` (returned from runnable interfaces) or ``LLMResult`` (available
     via callbacks).
     """
 
@@ -31,6 +31,7 @@ class ChatGeneration(Generation):
 
     .. warning::
         SHOULD NOT BE SET DIRECTLY!
+
     """
     message: BaseMessage
     """The message output by the chat model."""
@@ -47,6 +48,9 @@ class ChatGeneration(Generation):
 
         Returns:
             The values of the object with the text attribute set.
+
+        Raises:
+            ValueError: If the message is not a string or a list.
         """
         text = ""
         if isinstance(self.message.content, str):
@@ -66,9 +70,9 @@ class ChatGeneration(Generation):
 
 
 class ChatGenerationChunk(ChatGeneration):
-    """ChatGeneration chunk.
+    """``ChatGeneration`` chunk.
 
-    ChatGeneration chunks can be concatenated with other ChatGeneration chunks.
+    ``ChatGeneration`` chunks can be concatenated with other ``ChatGeneration`` chunks.
     """
 
     message: BaseMessageChunk

langchain_core/prompt_values.py

@@ -113,8 +113,12 @@ class ImageURL(TypedDict, total=False):
     """Image URL."""
 
     detail: Literal["auto", "low", "high"]
-    """Specifies the detail level of the image. Defaults to "auto".
-    Can be "auto", "low", or "high"."""
+    """Specifies the detail level of the image. Defaults to ``'auto'``.
+    Can be ``'auto'``, ``'low'``, or ``'high'``.
+
+    This follows OpenAI's Chat Completion API's image URL format.
+
+    """
 
     url: str
     """Either a URL of the image or the base64 encoded image data."""

langchain_core/prompts/chat.py

@@ -262,7 +262,7 @@ class BaseStringMessagePromptTemplate(BaseMessagePromptTemplate, ABC):
     def from_template_file(
         cls,
         template_file: Union[str, Path],
-        input_variables: list[str],
+        input_variables: list[str],  # noqa: ARG003  # Deprecated
         **kwargs: Any,
     ) -> Self:
         """Create a class from a template file.
@@ -275,7 +275,7 @@ class BaseStringMessagePromptTemplate(BaseMessagePromptTemplate, ABC):
         Returns:
             A new instance of this class.
         """
-        prompt = PromptTemplate.from_file(template_file, input_variables)
+        prompt = PromptTemplate.from_file(template_file)
         return cls(prompt=prompt, **kwargs)
 
     @abstractmethod
@@ -813,7 +813,10 @@ class ChatPromptTemplate(BaseChatPromptTemplate):
             )
 
             prompt_value = template.invoke(
-                {"name": "Bob", "user_input": "What is your name?"}
+                {
+                    "name": "Bob",
+                    "user_input": "What is your name?",
+                }
             )
             # Output:
             # ChatPromptValue(

langchain_core/prompts/few_shot.py

@@ -281,7 +281,10 @@ class FewShotChatMessagePromptTemplate(
             ]
 
             example_prompt = ChatPromptTemplate.from_messages(
-                [("human", "What is {input}?"), ("ai", "{output}")]
+                [
+                    ("human", "What is {input}?"),
+                    ("ai", "{output}"),
+                ]
             )
 
             few_shot_prompt = FewShotChatMessagePromptTemplate(

langchain_core/runnables/base.py

@@ -884,18 +884,18 @@ class Runnable(ABC, Generic[Input, Output]):
         e.g., if the underlying ``Runnable`` uses an API which supports a batch mode.
 
         Args:
-             inputs: A list of inputs to the ``Runnable``.
-             config: A config to use when invoking the ``Runnable``.
-                 The config supports standard keys like ``'tags'``, ``'metadata'`` for
-                 tracing purposes, ``'max_concurrency'`` for controlling how much work
-                 to do in parallel, and other keys. Please refer to the
-                 ``RunnableConfig`` for more details. Defaults to None.
-             return_exceptions: Whether to return exceptions instead of raising them.
-                 Defaults to False.
-             **kwargs: Additional keyword arguments to pass to the ``Runnable``.
+            inputs: A list of inputs to the ``Runnable``.
+            config: A config to use when invoking the ``Runnable``. The config supports
+                standard keys like ``'tags'``, ``'metadata'`` for
+                tracing purposes, ``'max_concurrency'`` for controlling how much work
+                to do in parallel, and other keys. Please refer to the
+                ``RunnableConfig`` for more details. Defaults to None.
+            return_exceptions: Whether to return exceptions instead of raising them.
+                Defaults to False.
+            **kwargs: Additional keyword arguments to pass to the ``Runnable``.
 
         Returns:
-             A list of outputs from the ``Runnable``.
+            A list of outputs from the ``Runnable``.
 
         """
         if not inputs:
@@ -1397,7 +1397,10 @@ class Runnable(ABC, Generic[Input, Output]):
         .. code-block:: python
 
             template = ChatPromptTemplate.from_messages(
-                [("system", "You are Cat Agent 007"), ("human", "{question}")]
+                [
+                    ("system", "You are Cat Agent 007"),
+                    ("human", "{question}"),
+                ]
             ).with_config({"run_name": "my_template", "tags": ["my_template"]})
 
 
@@ -2531,8 +2534,6 @@ class Runnable(ABC, Generic[Input, Output]):
             name: The name of the tool. Defaults to None.
             description: The description of the tool. Defaults to None.
             arg_types: A dictionary of argument names to types. Defaults to None.
-            message_version: Version of ``ToolMessage`` to return given
-            :class:`~langchain_core.messages.content_blocks.ToolCall` input.
 
         Returns:
             A ``BaseTool`` instance.

langchain_core/runnables/graph.py

@@ -614,7 +614,6 @@ class Graph:
 
         Returns:
             The Mermaid syntax string.
-
         """
         # Import locally to prevent circular import
         from langchain_core.runnables.graph_mermaid import draw_mermaid  # noqa: PLC0415
@@ -648,6 +647,7 @@ class Graph:
         max_retries: int = 1,
         retry_delay: float = 1.0,
         frontmatter_config: Optional[dict[str, Any]] = None,
+        base_url: Optional[str] = None,
     ) -> bytes:
         """Draw the graph as a PNG image using Mermaid.
 
@@ -683,6 +683,8 @@ class Graph:
                         "themeVariables": { "primaryColor": "#e2e2e2"},
                     }
                 }
+            base_url: The base URL of the Mermaid server for rendering via API.
+                Defaults to None.
 
         Returns:
             The PNG image as bytes.
@@ -707,6 +709,7 @@ class Graph:
             padding=padding,
             max_retries=max_retries,
             retry_delay=retry_delay,
+            base_url=base_url,
         )
 
 

langchain_core/runnables/graph_ascii.py

@@ -269,7 +269,7 @@ def draw_ascii(vertices: Mapping[str, str], edges: Sequence[LangEdge]) -> str:
 
             print(draw_ascii(vertices, edges))
 
-        .. code-block:: none
+        .. code-block::
 
                  +---+
                  | 1 |