langchain-core 1.0.3__py3-none-any.whl → 1.0.5__py3-none-any.whl

langchain_core/runnables/fallbacks.py

@@ -35,20 +35,20 @@ if TYPE_CHECKING:
 
 
 class RunnableWithFallbacks(RunnableSerializable[Input, Output]):
-    """Runnable that can fallback to other Runnables if it fails.
+    """`Runnable` that can fallback to other `Runnable`s if it fails.
 
     External APIs (e.g., APIs for a language model) may at times experience
     degraded performance or even downtime.
 
-    In these cases, it can be useful to have a fallback Runnable that can be
-    used in place of the original Runnable (e.g., fallback to another LLM provider).
+    In these cases, it can be useful to have a fallback `Runnable` that can be
+    used in place of the original `Runnable` (e.g., fallback to another LLM provider).
 
-    Fallbacks can be defined at the level of a single Runnable, or at the level
-    of a chain of Runnables. Fallbacks are tried in order until one succeeds or
+    Fallbacks can be defined at the level of a single `Runnable`, or at the level
+    of a chain of `Runnable`s. Fallbacks are tried in order until one succeeds or
     all fail.
 
     While you can instantiate a `RunnableWithFallbacks` directly, it is usually
-    more convenient to use the `with_fallbacks` method on a Runnable.
+    more convenient to use the `with_fallbacks` method on a `Runnable`.
 
     Example:
         ```python
@@ -87,7 +87,7 @@ class RunnableWithFallbacks(RunnableSerializable[Input, Output]):
     """
 
     runnable: Runnable[Input, Output]
-    """The Runnable to run first."""
+    """The `Runnable` to run first."""
     fallbacks: Sequence[Runnable[Input, Output]]
     """A sequence of fallbacks to try."""
     exceptions_to_handle: tuple[type[BaseException], ...] = (Exception,)
@@ -97,9 +97,12 @@ class RunnableWithFallbacks(RunnableSerializable[Input, Output]):
     """
     exception_key: str | None = None
     """If `string` is specified then handled exceptions will be passed to fallbacks as
-        part of the input under the specified key. If `None`, exceptions
-        will not be passed to fallbacks. If used, the base Runnable and its fallbacks
-        must accept a dictionary as input."""
+    part of the input under the specified key.
+
+    If `None`, exceptions will not be passed to fallbacks.
+
+    If used, the base `Runnable` and its fallbacks must accept a dictionary as input.
+    """
 
     model_config = ConfigDict(
         arbitrary_types_allowed=True,
@@ -137,7 +140,7 @@ class RunnableWithFallbacks(RunnableSerializable[Input, Output]):
     @classmethod
     @override
     def is_lc_serializable(cls) -> bool:
-        """Return True as this class is serializable."""
+        """Return `True` as this class is serializable."""
         return True
 
     @classmethod
@@ -152,10 +155,10 @@ class RunnableWithFallbacks(RunnableSerializable[Input, Output]):
 
     @property
     def runnables(self) -> Iterator[Runnable[Input, Output]]:
-        """Iterator over the Runnable and its fallbacks.
+        """Iterator over the `Runnable` and its fallbacks.
 
         Yields:
-            The Runnable then its fallbacks.
+            The `Runnable` then its fallbacks.
         """
         yield self.runnable
         yield from self.fallbacks
@@ -589,14 +592,14 @@ class RunnableWithFallbacks(RunnableSerializable[Input, Output]):
         await run_manager.on_chain_end(output)
 
     def __getattr__(self, name: str) -> Any:
-        """Get an attribute from the wrapped Runnable and its fallbacks.
+        """Get an attribute from the wrapped `Runnable` and its fallbacks.
 
         Returns:
-            If the attribute is anything other than a method that outputs a Runnable,
-            returns getattr(self.runnable, name). If the attribute is a method that
-            does return a new Runnable (e.g. model.bind_tools([...]) outputs a new
-            RunnableBinding) then self.runnable and each of the runnables in
-            self.fallbacks is replaced with getattr(x, name).
+            If the attribute is anything other than a method that outputs a `Runnable`,
+            returns `getattr(self.runnable, name)`. If the attribute is a method that
+            does return a new `Runnable` (e.g. `model.bind_tools([...])` outputs a new
+            `RunnableBinding`) then `self.runnable` and each of the runnables in
+            `self.fallbacks` is replaced with `getattr(x, name)`.
 
         Example:
             ```python
@@ -618,7 +621,6 @@ class RunnableWithFallbacks(RunnableSerializable[Input, Output]):
                 runnable=RunnableBinding(bound=ChatOpenAI(...), kwargs={"tools": [...]}),
                 fallbacks=[RunnableBinding(bound=ChatAnthropic(...), kwargs={"tools": [...]})],
             )
-
             ```
         """  # noqa: E501
         attr = getattr(self.runnable, name)

langchain_core/runnables/graph.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import inspect
 from collections import defaultdict
-from collections.abc import Callable
 from dataclasses import dataclass, field
 from enum import Enum
 from typing import (
@@ -22,7 +21,7 @@ from langchain_core.runnables.base import Runnable, RunnableSerializable
 from langchain_core.utils.pydantic import _IgnoreUnserializable, is_basemodel_subclass
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Callable, Sequence
 
     from pydantic import BaseModel
 

langchain_core/runnables/graph_ascii.py

@@ -7,7 +7,6 @@ from __future__ import annotations
 
 import math
 import os
-from collections.abc import Mapping, Sequence
 from typing import TYPE_CHECKING, Any
 
 try:
@@ -20,6 +19,8 @@ except ImportError:
     _HAS_GRANDALF = False
 
 if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
     from langchain_core.runnables.graph import Edge as LangEdge
 
 

langchain_core/runnables/graph_mermaid.py

@@ -454,7 +454,10 @@ def _render_mermaid_using_api(
                 return img_bytes
 
             # If we get a server error (5xx), retry
-            if 500 <= response.status_code < 600 and attempt < max_retries:
+            if (
+                requests.codes.internal_server_error <= response.status_code
+                and attempt < max_retries
+            ):
                 # Exponential backoff with jitter
                 sleep_time = retry_delay * (2**attempt) * (0.5 + 0.5 * random.random())  # noqa: S311 not used for crypto
                 time.sleep(sleep_time)

langchain_core/runnables/graph_png.py

@@ -1,5 +1,6 @@
 """Helper class to draw a state graph into a PNG file."""
 
+from itertools import groupby
 from typing import Any
 
 from langchain_core.runnables.graph import Graph, LabelsDict
@@ -141,6 +142,7 @@ class PngDrawer:
         # Add nodes, conditional edges, and edges to the graph
         self.add_nodes(viz, graph)
         self.add_edges(viz, graph)
+        self.add_subgraph(viz, [node.split(":") for node in graph.nodes])
 
         # Update entrypoint and END styles
         self.update_styles(viz, graph)
@@ -161,6 +163,32 @@ class PngDrawer:
         for node in graph.nodes:
             self.add_node(viz, node)
 
+    def add_subgraph(
+        self,
+        viz: Any,
+        nodes: list[list[str]],
+        parent_prefix: list[str] | None = None,
+    ) -> None:
+        """Add subgraphs to the graph.
+
+        Args:
+            viz: The graphviz object.
+            nodes: The nodes to add.
+            parent_prefix: The prefix of the parent subgraph.
+        """
+        for prefix, grouped in groupby(
+            [node[:] for node in sorted(nodes)],
+            key=lambda x: x.pop(0),
+        ):
+            current_prefix = (parent_prefix or []) + [prefix]
+            grouped_nodes = list(grouped)
+            if len(grouped_nodes) > 1:
+                subgraph = viz.add_subgraph(
+                    [":".join(current_prefix + node) for node in grouped_nodes],
+                    name="cluster_" + ":".join(current_prefix),
+                )
+                self.add_subgraph(subgraph, grouped_nodes, current_prefix)
+
     def add_edges(self, viz: Any, graph: Graph) -> None:
         """Add edges to the graph.
 

langchain_core/runnables/history.py

@@ -36,23 +36,23 @@ GetSessionHistoryCallable = Callable[..., BaseChatMessageHistory]
 
 
 class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
-    """Runnable that manages chat message history for another Runnable.
+    """`Runnable` that manages chat message history for another `Runnable`.
 
     A chat message history is a sequence of messages that represent a conversation.
 
-    RunnableWithMessageHistory wraps another Runnable and manages the chat message
+    `RunnableWithMessageHistory` wraps another `Runnable` and manages the chat message
     history for it; it is responsible for reading and updating the chat message
     history.
 
-    The formats supported for the inputs and outputs of the wrapped Runnable
+    The formats supported for the inputs and outputs of the wrapped `Runnable`
     are described below.
 
-    RunnableWithMessageHistory must always be called with a config that contains
+    `RunnableWithMessageHistory` must always be called with a config that contains
     the appropriate parameters for the chat message history factory.
 
-    By default, the Runnable is expected to take a single configuration parameter
+    By default, the `Runnable` is expected to take a single configuration parameter
     called `session_id` which is a string. This parameter is used to create a new
-    or look up an existing chat message history that matches the given session_id.
+    or look up an existing chat message history that matches the given `session_id`.
 
     In this case, the invocation would look like this:
 
@@ -117,12 +117,12 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
 
         ```
 
-    Example where the wrapped Runnable takes a dictionary input:
+    Example where the wrapped `Runnable` takes a dictionary input:
 
         ```python
         from typing import Optional
 
-        from langchain_community.chat_models import ChatAnthropic
+        from langchain_anthropic import ChatAnthropic
         from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
         from langchain_core.runnables.history import RunnableWithMessageHistory
 
@@ -166,7 +166,7 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
         print(store)  # noqa: T201
         ```
 
-    Example where the session factory takes two keys, user_id and conversation id):
+    Example where the session factory takes two keys (`user_id` and `conversation_id`):
 
         ```python
         store = {}
@@ -223,21 +223,28 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
     """
 
     get_session_history: GetSessionHistoryCallable
-    """Function that returns a new BaseChatMessageHistory.
+    """Function that returns a new `BaseChatMessageHistory`.
+
     This function should either take a single positional argument `session_id` of type
-    string and return a corresponding chat message history instance"""
+    string and return a corresponding chat message history instance
+    """
     input_messages_key: str | None = None
-    """Must be specified if the base runnable accepts a dict as input.
-    The key in the input dict that contains the messages."""
+    """Must be specified if the base `Runnable` accepts a `dict` as input.
+    The key in the input `dict` that contains the messages.
+    """
     output_messages_key: str | None = None
-    """Must be specified if the base Runnable returns a dict as output.
-    The key in the output dict that contains the messages."""
+    """Must be specified if the base `Runnable` returns a `dict` as output.
+    The key in the output `dict` that contains the messages.
+    """
     history_messages_key: str | None = None
-    """Must be specified if the base runnable accepts a dict as input and expects a
-    separate key for historical messages."""
+    """Must be specified if the base `Runnable` accepts a `dict` as input and expects a
+    separate key for historical messages.
+    """
     history_factory_config: Sequence[ConfigurableFieldSpec]
     """Configure fields that should be passed to the chat history factory.
-    See `ConfigurableFieldSpec` for more details."""
+
+    See `ConfigurableFieldSpec` for more details.
+    """
 
     def __init__(
         self,
@@ -254,15 +261,16 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
         history_factory_config: Sequence[ConfigurableFieldSpec] | None = None,
         **kwargs: Any,
     ) -> None:
-        """Initialize RunnableWithMessageHistory.
+        """Initialize `RunnableWithMessageHistory`.
 
         Args:
-            runnable: The base Runnable to be wrapped.
+            runnable: The base `Runnable` to be wrapped.
+
                 Must take as input one of:
 
                 1. A list of `BaseMessage`
-                2. A dict with one key for all messages
-                3. A dict with one key for the current input string/message(s) and
+                2. A `dict` with one key for all messages
+                3. A `dict` with one key for the current input string/message(s) and
                     a separate key for historical messages. If the input key points
                     to a string, it will be treated as a `HumanMessage` in history.
 
@@ -270,13 +278,15 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
 
                 1. A string which can be treated as an `AIMessage`
                 2. A `BaseMessage` or sequence of `BaseMessage`
-                3. A dict with a key for a `BaseMessage` or sequence of
+                3. A `dict` with a key for a `BaseMessage` or sequence of
                     `BaseMessage`
 
-            get_session_history: Function that returns a new BaseChatMessageHistory.
+            get_session_history: Function that returns a new `BaseChatMessageHistory`.
+
                 This function should either take a single positional argument
                 `session_id` of type string and return a corresponding
                 chat message history instance.
+
                 ```python
                 def get_session_history(
                     session_id: str, *, user_id: str | None = None
@@ -295,16 +305,17 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
                 ) -> BaseChatMessageHistory: ...
                 ```
 
-            input_messages_key: Must be specified if the base runnable accepts a dict
+            input_messages_key: Must be specified if the base runnable accepts a `dict`
                 as input.
-            output_messages_key: Must be specified if the base runnable returns a dict
+            output_messages_key: Must be specified if the base runnable returns a `dict`
                 as output.
-            history_messages_key: Must be specified if the base runnable accepts a dict
-                as input and expects a separate key for historical messages.
+            history_messages_key: Must be specified if the base runnable accepts a
+                `dict` as input and expects a separate key for historical messages.
             history_factory_config: Configure fields that should be passed to the
                 chat history factory. See `ConfigurableFieldSpec` for more details.
-                Specifying these allows you to pass multiple config keys
-                into the get_session_history factory.
+
+                Specifying these allows you to pass multiple config keys into the
+                `get_session_history` factory.
             **kwargs: Arbitrary additional kwargs to pass to parent class
                 `RunnableBindingBase` init.
 
@@ -364,7 +375,7 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
     @property
     @override
     def config_specs(self) -> list[ConfigurableFieldSpec]:
-        """Get the configuration specs for the RunnableWithMessageHistory."""
+        """Get the configuration specs for the `RunnableWithMessageHistory`."""
         return get_unique_config_specs(
             super().config_specs + list(self.history_factory_config)
         )
@@ -606,6 +617,6 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
 
 
 def _get_parameter_names(callable_: GetSessionHistoryCallable) -> list[str]:
-    """Get the parameter names of the callable."""
+    """Get the parameter names of the `Callable`."""
     sig = inspect.signature(callable_)
     return list(sig.parameters.keys())

langchain_core/runnables/passthrough.py

@@ -51,10 +51,10 @@ def identity(x: Other) -> Other:
     """Identity function.
 
     Args:
-        x: input.
+        x: Input.
 
     Returns:
-        output.
+        Output.
     """
     return x
 
@@ -63,10 +63,10 @@ async def aidentity(x: Other) -> Other:
     """Async identity function.
 
     Args:
-        x: input.
+        x: Input.
 
     Returns:
-        output.
+        Output.
     """
     return x
 
@@ -74,11 +74,11 @@ async def aidentity(x: Other) -> Other:
 class RunnablePassthrough(RunnableSerializable[Other, Other]):
     """Runnable to passthrough inputs unchanged or with additional keys.
 
-    This Runnable behaves almost like the identity function, except that it
+    This `Runnable` behaves almost like the identity function, except that it
     can be configured to add additional keys to the output, if the input is a
     dict.
 
-    The examples below demonstrate this Runnable works using a few simple
+    The examples below demonstrate this `Runnable` works using a few simple
     chains. The chains rely on simple lambdas to make the examples easy to execute
     and experiment with.
 
@@ -164,7 +164,7 @@ class RunnablePassthrough(RunnableSerializable[Other, Other]):
         input_type: type[Other] | None = None,
         **kwargs: Any,
     ) -> None:
-        """Create e RunnablePassthrough.
+        """Create a `RunnablePassthrough`.
 
         Args:
             func: Function to be called with the input.
@@ -180,7 +180,7 @@ class RunnablePassthrough(RunnableSerializable[Other, Other]):
     @classmethod
     @override
     def is_lc_serializable(cls) -> bool:
-        """Return True as this class is serializable."""
+        """Return `True` as this class is serializable."""
         return True
 
     @classmethod
@@ -213,11 +213,11 @@ class RunnablePassthrough(RunnableSerializable[Other, Other]):
         """Merge the Dict input with the output produced by the mapping argument.
 
         Args:
-            **kwargs: Runnable, Callable or a Mapping from keys to Runnables
-                or Callables.
+            **kwargs: `Runnable`, `Callable` or a `Mapping` from keys to `Runnable`
+                objects or `Callable`s.
 
         Returns:
-            A Runnable that merges the Dict input with the output produced by the
+            A `Runnable` that merges the `dict` input with the output produced by the
             mapping argument.
         """
         return RunnableAssign(RunnableParallel[dict[str, Any]](kwargs))
@@ -350,7 +350,7 @@ _graph_passthrough: RunnablePassthrough = RunnablePassthrough()
 
 
 class RunnableAssign(RunnableSerializable[dict[str, Any], dict[str, Any]]):
-    """Runnable that assigns key-value pairs to dict[str, Any] inputs.
+    """Runnable that assigns key-value pairs to `dict[str, Any]` inputs.
 
     The `RunnableAssign` class takes input dictionaries and, through a
     `RunnableParallel` instance, applies transformations, then combines
@@ -392,7 +392,7 @@ class RunnableAssign(RunnableSerializable[dict[str, Any], dict[str, Any]]):
     mapper: RunnableParallel
 
     def __init__(self, mapper: RunnableParallel[dict[str, Any]], **kwargs: Any) -> None:
-        """Create a RunnableAssign.
+        """Create a `RunnableAssign`.
 
         Args:
             mapper: A `RunnableParallel` instance that will be used to transform the
@@ -403,7 +403,7 @@ class RunnableAssign(RunnableSerializable[dict[str, Any], dict[str, Any]]):
     @classmethod
     @override
     def is_lc_serializable(cls) -> bool:
-        """Return True as this class is serializable."""
+        """Return `True` as this class is serializable."""
         return True
 
     @classmethod
@@ -668,13 +668,19 @@ class RunnableAssign(RunnableSerializable[dict[str, Any], dict[str, Any]]):
             yield chunk
 
 
-class RunnablePick(RunnableSerializable[dict[str, Any], dict[str, Any]]):
-    """Runnable that picks keys from dict[str, Any] inputs.
+class RunnablePick(RunnableSerializable[dict[str, Any], Any]):
+    """`Runnable` that picks keys from `dict[str, Any]` inputs.
 
-    RunnablePick class represents a Runnable that selectively picks keys from a
+    `RunnablePick` class represents a `Runnable` that selectively picks keys from a
     dictionary input. It allows you to specify one or more keys to extract
-    from the input dictionary. It returns a new dictionary containing only
-    the selected keys.
+    from the input dictionary.
+
+    !!! note "Return Type Behavior"
+        The return type depends on the `keys` parameter:
+
+        - When `keys` is a `str`: Returns the single value associated with that key
+        - When `keys` is a `list`: Returns a dictionary containing only the selected
+            keys
 
     Example:
         ```python
@@ -687,18 +693,22 @@ class RunnablePick(RunnableSerializable[dict[str, Any], dict[str, Any]]):
             "country": "USA",
         }
 
-        runnable = RunnablePick(keys=["name", "age"])
-
-        output_data = runnable.invoke(input_data)
+        # Single key - returns the value directly
+        runnable_single = RunnablePick(keys="name")
+        result_single = runnable_single.invoke(input_data)
+        print(result_single)  # Output: "John"
 
-        print(output_data)  # Output: {'name': 'John', 'age': 30}
+        # Multiple keys - returns a dictionary
+        runnable_multiple = RunnablePick(keys=["name", "age"])
+        result_multiple = runnable_multiple.invoke(input_data)
+        print(result_multiple)  # Output: {'name': 'John', 'age': 30}
         ```
     """
 
     keys: str | list[str]
 
     def __init__(self, keys: str | list[str], **kwargs: Any) -> None:
-        """Create a RunnablePick.
+        """Create a `RunnablePick`.
 
         Args:
             keys: A single key or a list of keys to pick from the input dictionary.
@@ -708,7 +718,7 @@ class RunnablePick(RunnableSerializable[dict[str, Any], dict[str, Any]]):
     @classmethod
     @override
     def is_lc_serializable(cls) -> bool:
-        """Return True as this class is serializable."""
+        """Return `True` as this class is serializable."""
         return True
 
     @classmethod

langchain_core/runnables/router.py

@@ -40,11 +40,11 @@ class RouterInput(TypedDict):
     key: str
     """The key to route on."""
     input: Any
-    """The input to pass to the selected Runnable."""
+    """The input to pass to the selected `Runnable`."""
 
 
 class RouterRunnable(RunnableSerializable[RouterInput, Output]):
-    """Runnable that routes to a set of Runnables based on Input['key'].
+    """`Runnable` that routes to a set of `Runnable` based on `Input['key']`.
 
     Returns the output of the selected Runnable.
 
@@ -74,10 +74,10 @@ class RouterRunnable(RunnableSerializable[RouterInput, Output]):
         self,
         runnables: Mapping[str, Runnable[Any, Output] | Callable[[Any], Output]],
     ) -> None:
-        """Create a RouterRunnable.
+        """Create a `RouterRunnable`.
 
         Args:
-            runnables: A mapping of keys to Runnables.
+            runnables: A mapping of keys to `Runnable` objects.
         """
         super().__init__(
             runnables={key: coerce_to_runnable(r) for key, r in runnables.items()}
@@ -90,7 +90,7 @@ class RouterRunnable(RunnableSerializable[RouterInput, Output]):
     @classmethod
     @override
     def is_lc_serializable(cls) -> bool:
-        """Return True as this class is serializable."""
+        """Return `True` as this class is serializable."""
         return True
 
     @classmethod

langchain_core/runnables/schema.py

@@ -28,7 +28,7 @@ class EventData(TypedDict, total=False):
 
     This field is only available if the `Runnable` raised an exception.
 
-    !!! version-added "Added in version 1.0.0"
+    !!! version-added "Added in `langchain-core` 1.0.0"
     """
     output: Any
     """The output of the `Runnable` that generated the event.

langchain_core/runnables/utils.py

@@ -7,8 +7,7 @@ import asyncio
 import inspect
 import sys
 import textwrap
-from collections.abc import Callable, Mapping, Sequence
-from contextvars import Context
+from collections.abc import Mapping, Sequence
 from functools import lru_cache
 from inspect import signature
 from itertools import groupby
@@ -31,9 +30,11 @@ if TYPE_CHECKING:
         AsyncIterable,
         AsyncIterator,
         Awaitable,
+        Callable,
         Coroutine,
         Iterable,
     )
+    from contextvars import Context
 
     from langchain_core.runnables.schema import StreamEvent
 

langchain_core/sys_info.py

@@ -125,9 +125,11 @@ def print_sys_info(*, additional_pkgs: Sequence[str] = ()) -> None:
         for dep in sub_dependencies:
             try:
                 dep_version = metadata.version(dep)
-                print(f"> {dep}: {dep_version}")
             except Exception:
-                print(f"> {dep}: Installed. No version info available.")
+                dep_version = None
+
+            if dep_version is not None:
+                print(f"> {dep}: {dep_version}")
 
 
 if __name__ == "__main__":