langchain-core 1.0.0a5__py3-none-any.whl → 1.0.3__py3-none-any.whl

langchain_core/runnables/graph.py

@@ -4,17 +4,15 @@ 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 (
     TYPE_CHECKING,
     Any,
-    Callable,
     NamedTuple,
-    Optional,
     Protocol,
     TypedDict,
-    Union,
     overload,
 )
 from uuid import UUID, uuid4
@@ -54,7 +52,7 @@ def is_uuid(value: str) -> bool:
         value: The string to check.
 
     Returns:
-        True if the string is a valid UUID, False otherwise.
+        `True` if the string is a valid UUID, `False` otherwise.
     """
     try:
         UUID(value)
@@ -70,19 +68,17 @@ class Edge(NamedTuple):
     """The source node id."""
     target: str
     """The target node id."""
-    data: Optional[Stringifiable] = None
-    """Optional data associated with the edge. Defaults to None."""
+    data: Stringifiable | None = None
+    """Optional data associated with the edge. """
     conditional: bool = False
-    """Whether the edge is conditional. Defaults to False."""
+    """Whether the edge is conditional."""
 
-    def copy(
-        self, *, source: Optional[str] = None, target: Optional[str] = None
-    ) -> Edge:
+    def copy(self, *, source: str | None = None, target: str | None = None) -> Edge:
         """Return a copy of the edge with optional new source and target nodes.
 
         Args:
-            source: The new source node id. Defaults to None.
-            target: The new target node id. Defaults to None.
+            source: The new source node id.
+            target: The new target node id.
 
         Returns:
             A copy of the edge with the new source and target nodes.
@@ -102,22 +98,22 @@ class Node(NamedTuple):
     """The unique identifier of the node."""
     name: str
     """The name of the node."""
-    data: Union[type[BaseModel], RunnableType, None]
+    data: type[BaseModel] | RunnableType | None
     """The data of the node."""
-    metadata: Optional[dict[str, Any]]
-    """Optional metadata for the node. Defaults to None."""
+    metadata: dict[str, Any] | None
+    """Optional metadata for the node. """
 
     def copy(
         self,
         *,
-        id: Optional[str] = None,
-        name: Optional[str] = None,
+        id: str | None = None,
+        name: str | None = None,
     ) -> Node:
         """Return a copy of the node with optional new id and name.
 
         Args:
-            id: The new node id. Defaults to None.
-            name: The new node name. Defaults to None.
+            id: The new node id.
+            name: The new node name.
 
         Returns:
             A copy of the node with the new id and name.
@@ -135,8 +131,8 @@ class Branch(NamedTuple):
 
     condition: Callable[..., str]
     """A callable that returns a string representation of the condition."""
-    ends: Optional[dict[str, str]]
-    """Optional dictionary of end node ids for the branches. Defaults to None."""
+    ends: dict[str, str] | None
+    """Optional dictionary of end node IDs for the branches. """
 
 
 class CurveStyle(Enum):
@@ -161,9 +157,9 @@ class NodeStyles:
     """Schema for Hexadecimal color codes for different node types.
 
     Args:
-        default: The default color code. Defaults to "fill:#f2f0ff,line-height:1.2".
-        first: The color code for the first node. Defaults to "fill-opacity:0".
-        last: The color code for the last node. Defaults to "fill:#bfb6fc".
+        default: The default color code.
+        first: The color code for the first node.
+        last: The color code for the last node.
     """
 
     default: str = "fill:#f2f0ff,line-height:1.2"
@@ -182,7 +178,7 @@ class MermaidDrawMethod(Enum):
 
 def node_data_str(
     id: str,
-    data: Union[type[BaseModel], RunnableType, None],
+    data: type[BaseModel] | RunnableType | None,
 ) -> str:
     """Convert the data of a node to a string.
 
@@ -201,13 +197,13 @@ def node_data_str(
 
 def node_data_json(
     node: Node, *, with_schemas: bool = False
-) -> dict[str, Union[str, dict[str, Any]]]:
+) -> dict[str, str | dict[str, Any]]:
     """Convert the data of a node to a JSON-serializable format.
 
     Args:
-        node: The node to convert.
-        with_schemas: Whether to include the schema of the data if
-            it is a Pydantic model. Defaults to False.
+        node: The `Node` to convert.
+        with_schemas: Whether to include the schema of the data if it is a Pydantic
+            model.
 
     Returns:
         A dictionary with the type of the data and the data itself.
@@ -271,7 +267,7 @@ class Graph:
 
         Args:
             with_schemas: Whether to include the schemas of the nodes if they are
-                Pydantic models. Defaults to False.
+                Pydantic models.
 
         Returns:
             A dictionary with the nodes and edges of the graph.
@@ -316,17 +312,17 @@ class Graph:
 
     def add_node(
         self,
-        data: Union[type[BaseModel], RunnableType, None],
-        id: Optional[str] = None,
+        data: type[BaseModel] | RunnableType | None,
+        id: str | None = None,
         *,
-        metadata: Optional[dict[str, Any]] = None,
+        metadata: dict[str, Any] | None = None,
     ) -> Node:
         """Add a node to the graph and return it.
 
         Args:
             data: The data of the node.
-            id: The id of the node. Defaults to None.
-            metadata: Optional metadata for the node. Defaults to None.
+            id: The id of the node.
+            metadata: Optional metadata for the node.
 
         Returns:
             The node that was added to the graph.
@@ -357,7 +353,7 @@ class Graph:
         self,
         source: Node,
         target: Node,
-        data: Optional[Stringifiable] = None,
+        data: Stringifiable | None = None,
         conditional: bool = False,  # noqa: FBT001,FBT002
     ) -> Edge:
         """Add an edge to the graph and return it.
@@ -365,8 +361,8 @@ class Graph:
         Args:
             source: The source node of the edge.
             target: The target node of the edge.
-            data: Optional data associated with the edge. Defaults to None.
-            conditional: Whether the edge is conditional. Defaults to False.
+            data: Optional data associated with the edge.
+            conditional: Whether the edge is conditional.
 
         Returns:
             The edge that was added to the graph.
@@ -388,14 +384,14 @@ class Graph:
 
     def extend(
         self, graph: Graph, *, prefix: str = ""
-    ) -> tuple[Optional[Node], Optional[Node]]:
+    ) -> tuple[Node | None, Node | None]:
         """Add all nodes and edges from another graph.
 
         Note this doesn't check for duplicates, nor does it connect the graphs.
 
         Args:
             graph: The graph to add.
-            prefix: The prefix to add to the node ids. Defaults to "".
+            prefix: The prefix to add to the node ids.
 
         Returns:
             A tuple of the first and last nodes of the subgraph.
@@ -459,10 +455,10 @@ class Graph:
             ],
         )
 
-    def first_node(self) -> Optional[Node]:
+    def first_node(self) -> Node | None:
         """Find the single node that is not a target of any edge.
 
-        If there is no such node, or there are multiple, return None.
+        If there is no such node, or there are multiple, return `None`.
         When drawing the graph, this node would be the origin.
 
         Returns:
@@ -471,10 +467,10 @@ class Graph:
         """
         return _first_node(self)
 
-    def last_node(self) -> Optional[Node]:
+    def last_node(self) -> Node | None:
         """Find the single node that is not a source of any edge.
 
-        If there is no such node, or there are multiple, return None.
+        If there is no such node, or there are multiple, return `None`.
         When drawing the graph, this node would be the destination.
 
         Returns:
@@ -531,31 +527,32 @@ class Graph:
     def draw_png(
         self,
         output_file_path: str,
-        fontname: Optional[str] = None,
-        labels: Optional[LabelsDict] = None,
+        fontname: str | None = None,
+        labels: LabelsDict | None = None,
     ) -> None: ...
 
     @overload
     def draw_png(
         self,
         output_file_path: None,
-        fontname: Optional[str] = None,
-        labels: Optional[LabelsDict] = None,
+        fontname: str | None = None,
+        labels: LabelsDict | None = None,
     ) -> bytes: ...
 
     def draw_png(
         self,
-        output_file_path: Optional[str] = None,
-        fontname: Optional[str] = None,
-        labels: Optional[LabelsDict] = None,
-    ) -> Union[bytes, None]:
+        output_file_path: str | None = None,
+        fontname: str | None = None,
+        labels: LabelsDict | None = None,
+    ) -> bytes | None:
         """Draw the graph as a PNG image.
 
         Args:
-            output_file_path: The path to save the image to. If None, the image
-                is not saved. Defaults to None.
-            fontname: The name of the font to use. Defaults to None.
-            labels: Optional labels for nodes and edges in the graph. Defaults to None.
+            output_file_path: The path to save the image to. If `None`, the image
+                is not saved.
+            fontname: The name of the font to use.
+            labels: Optional labels for nodes and edges in the graph. Defaults to
+                `None`.
 
         Returns:
             The PNG image as bytes if output_file_path is None, None otherwise.
@@ -581,37 +578,34 @@ class Graph:
         *,
         with_styles: bool = True,
         curve_style: CurveStyle = CurveStyle.LINEAR,
-        node_colors: Optional[NodeStyles] = None,
+        node_colors: NodeStyles | None = None,
         wrap_label_n_words: int = 9,
-        frontmatter_config: Optional[dict[str, Any]] = None,
+        frontmatter_config: dict[str, Any] | None = None,
     ) -> str:
         """Draw the graph as a Mermaid syntax string.
 
         Args:
-            with_styles: Whether to include styles in the syntax. Defaults to True.
-            curve_style: The style of the edges. Defaults to CurveStyle.LINEAR.
-            node_colors: The colors of the nodes. Defaults to NodeStyles().
+            with_styles: Whether to include styles in the syntax.
+            curve_style: The style of the edges.
+            node_colors: The colors of the nodes.
             wrap_label_n_words: The number of words to wrap the node labels at.
-                Defaults to 9.
-            frontmatter_config (dict[str, Any], optional): Mermaid frontmatter config.
+            frontmatter_config: Mermaid frontmatter config.
                 Can be used to customize theme and styles. Will be converted to YAML and
-                added to the beginning of the mermaid graph. Defaults to None.
+                added to the beginning of the mermaid graph.
 
                 See more here: https://mermaid.js.org/config/configuration.html.
 
                 Example config:
 
-                .. code-block:: python
-
+                ```python
                 {
                     "config": {
                         "theme": "neutral",
                         "look": "handDrawn",
-                        "themeVariables": { "primaryColor": "#e2e2e2"},
+                        "themeVariables": {"primaryColor": "#e2e2e2"},
                     }
                 }
-
-
+                ```
         Returns:
             The Mermaid syntax string.
         """
@@ -638,53 +632,49 @@ class Graph:
         self,
         *,
         curve_style: CurveStyle = CurveStyle.LINEAR,
-        node_colors: Optional[NodeStyles] = None,
+        node_colors: NodeStyles | None = None,
         wrap_label_n_words: int = 9,
-        output_file_path: Optional[str] = None,
+        output_file_path: str | None = None,
         draw_method: MermaidDrawMethod = MermaidDrawMethod.API,
         background_color: str = "white",
         padding: int = 10,
         max_retries: int = 1,
         retry_delay: float = 1.0,
-        frontmatter_config: Optional[dict[str, Any]] = None,
-        base_url: Optional[str] = None,
+        frontmatter_config: dict[str, Any] | None = None,
+        base_url: str | None = None,
     ) -> bytes:
         """Draw the graph as a PNG image using Mermaid.
 
         Args:
-            curve_style: The style of the edges. Defaults to CurveStyle.LINEAR.
-            node_colors: The colors of the nodes. Defaults to NodeStyles().
+            curve_style: The style of the edges.
+            node_colors: The colors of the nodes.
             wrap_label_n_words: The number of words to wrap the node labels at.
-                Defaults to 9.
-            output_file_path: The path to save the image to. If None, the image
-                is not saved. Defaults to None.
+            output_file_path: The path to save the image to. If `None`, the image
+                is not saved.
             draw_method: The method to use to draw the graph.
-                Defaults to MermaidDrawMethod.API.
-            background_color: The color of the background. Defaults to "white".
-            padding: The padding around the graph. Defaults to 10.
-            max_retries: The maximum number of retries (MermaidDrawMethod.API).
-                Defaults to 1.
-            retry_delay: The delay between retries (MermaidDrawMethod.API).
-                Defaults to 1.0.
-            frontmatter_config (dict[str, Any], optional): Mermaid frontmatter config.
+            background_color: The color of the background.
+            padding: The padding around the graph.
+            max_retries: The maximum number of retries (`MermaidDrawMethod.API`).
+            retry_delay: The delay between retries (`MermaidDrawMethod.API`).
+            frontmatter_config: Mermaid frontmatter config.
                 Can be used to customize theme and styles. Will be converted to YAML and
-                added to the beginning of the mermaid graph. Defaults to None.
+                added to the beginning of the mermaid graph.
 
                 See more here: https://mermaid.js.org/config/configuration.html.
 
                 Example config:
 
-                .. code-block:: python
-
+                ```python
                 {
                     "config": {
                         "theme": "neutral",
                         "look": "handDrawn",
-                        "themeVariables": { "primaryColor": "#e2e2e2"},
+                        "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.
@@ -713,11 +703,13 @@ class Graph:
         )
 
 
-def _first_node(graph: Graph, exclude: Sequence[str] = ()) -> Optional[Node]:
+def _first_node(graph: Graph, exclude: Sequence[str] = ()) -> Node | None:
     """Find the single node that is not a target of any edge.
 
-    Exclude nodes/sources with ids in the exclude list.
-    If there is no such node, or there are multiple, return None.
+    Exclude nodes/sources with IDs in the exclude list.
+
+    If there is no such node, or there are multiple, return `None`.
+
     When drawing the graph, this node would be the origin.
     """
     targets = {edge.target for edge in graph.edges if edge.source not in exclude}
@@ -729,11 +721,13 @@ def _first_node(graph: Graph, exclude: Sequence[str] = ()) -> Optional[Node]:
     return found[0] if len(found) == 1 else None
 
 
-def _last_node(graph: Graph, exclude: Sequence[str] = ()) -> Optional[Node]:
+def _last_node(graph: Graph, exclude: Sequence[str] = ()) -> Node | None:
     """Find the single node that is not a source of any edge.
 
-    Exclude nodes/targets with ids in the exclude list.
-    If there is no such node, or there are multiple, return None.
+    Exclude nodes/targets with IDs in the exclude list.
+
+    If there is no such node, or there are multiple, return `None`.
+
     When drawing the graph, this node would be the destination.
     """
     sources = {edge.source for edge in graph.edges if edge.target not in exclude}

langchain_core/runnables/graph_ascii.py

@@ -62,8 +62,8 @@ class AsciiCanvas:
         """Create an ASCII canvas.
 
         Args:
-            cols: number of columns in the canvas. Should be ``> 1``.
-            lines: number of lines in the canvas. Should be ``> 1``.
+            cols: number of columns in the canvas. Should be `> 1`.
+            lines: number of lines in the canvas. Should be `> 1`.
 
         Raises:
             ValueError: if canvas dimensions are invalid.
@@ -90,9 +90,9 @@ class AsciiCanvas:
         """Create a point on ASCII canvas.
 
         Args:
-            x: x coordinate. Should be ``>= 0`` and ``<`` number of columns in
+            x: x coordinate. Should be `>= 0` and `<` number of columns in
                 the canvas.
-            y: y coordinate. Should be ``>= 0`` an ``<`` number of lines in the
+            y: y coordinate. Should be `>= 0` an `<` number of lines in the
                 canvas.
             char: character to place in the specified point on the
                 canvas.
@@ -117,11 +117,11 @@ class AsciiCanvas:
         """Create a line on ASCII canvas.
 
         Args:
-            x0 (int): x coordinate where the line should start.
-            y0 (int): y coordinate where the line should start.
-            x1 (int): x coordinate where the line should end.
-            y1 (int): y coordinate where the line should end.
-            char (str): character to draw the line with.
+            x0: x coordinate where the line should start.
+            y0: y coordinate where the line should start.
+            x1: x coordinate where the line should end.
+            y1: y coordinate where the line should end.
+            char: character to draw the line with.
         """
         if x0 > x1:
             x1, x0 = x0, x1
@@ -149,9 +149,9 @@ class AsciiCanvas:
         """Print a text on ASCII canvas.
 
         Args:
-            x (int): x coordinate where the text should start.
-            y (int): y coordinate where the text should start.
-            text (str): string that should be printed.
+            x: x coordinate where the text should start.
+            y: y coordinate where the text should start.
+            text: string that should be printed.
         """
         for i, char in enumerate(text):
             self.point(x + i, y, char)
@@ -160,10 +160,10 @@ class AsciiCanvas:
         """Create a box on ASCII canvas.
 
         Args:
-            x0 (int): x coordinate of the box corner.
-            y0 (int): y coordinate of the box corner.
-            width (int): box width.
-            height (int): box height.
+            x0: x coordinate of the box corner.
+            y0: y coordinate of the box corner.
+            width: box width.
+            height: box height.
         """
         if width <= 1 or height <= 1:
             msg = "Box dimensions should be > 1"
@@ -255,21 +255,20 @@ def draw_ascii(vertices: Mapping[str, str], edges: Sequence[LangEdge]) -> str:
         ASCII representation
 
     Example:
+        ```python
+        from langchain_core.runnables.graph_ascii import draw_ascii
 
-        .. code-block:: python
+        vertices = {1: "1", 2: "2", 3: "3", 4: "4"}
+        edges = [
+            (source, target, None, None)
+            for source, target in [(1, 2), (2, 3), (2, 4), (1, 4)]
+        ]
 
-            from langchain_core.runnables.graph_ascii import draw_ascii
 
-            vertices = {1: "1", 2: "2", 3: "3", 4: "4"}
-            edges = [
-                (source, target, None, None)
-                for source, target in [(1, 2), (2, 3), (2, 4), (1, 4)]
-            ]
+        print(draw_ascii(vertices, edges))
+        ```
 
-
-            print(draw_ascii(vertices, edges))
-
-        .. code-block::
+        ```txt
 
                  +---+
                  | 1 |
@@ -286,7 +285,7 @@ def draw_ascii(vertices: Mapping[str, str], edges: Sequence[LangEdge]) -> str:
             +---+     +---+
             | 3 |     | 4 |
             +---+     +---+
-
+        ```
     """
     # NOTE: coordinates might me negative, so we need to shift
     # everything to the positive plane before we actually draw it.