langchain-core 1.0.0a1__py3-none-any.whl → 1.0.0a3__py3-none-any.whl

langchain_core/runnables/graph_ascii.py

@@ -3,12 +3,24 @@
 Adapted from https://github.com/iterative/dvc/blob/main/dvc/dagascii.py.
 """
 
+from __future__ import annotations
+
 import math
 import os
 from collections.abc import Mapping, Sequence
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+try:
+    from grandalf.graphs import Edge, Graph, Vertex  # type: ignore[import-untyped]
+    from grandalf.layouts import SugiyamaLayout  # type: ignore[import-untyped]
+    from grandalf.routing import route_with_lines  # type: ignore[import-untyped]
 
-from langchain_core.runnables.graph import Edge as LangEdge
+    _HAS_GRANDALF = True
+except ImportError:
+    _HAS_GRANDALF = False
+
+if TYPE_CHECKING:
+    from langchain_core.runnables.graph import Edge as LangEdge
 
 
 class VertexViewer:
@@ -50,8 +62,11 @@ class AsciiCanvas:
         """Create an ASCII canvas.
 
         Args:
-            cols (int): number of columns in the canvas. Should be > 1.
-            lines (int): 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.
         """
         if cols <= 1 or lines <= 1:
             msg = "Canvas dimensions should be > 1"
@@ -63,7 +78,11 @@ class AsciiCanvas:
         self.canvas = [[" "] * cols for line in range(lines)]
 
     def draw(self) -> str:
-        """Draws ASCII canvas on the screen."""
+        """Draws ASCII canvas on the screen.
+
+        Returns:
+            The ASCII canvas string.
+        """
         lines = map("".join, self.canvas)
         return os.linesep.join(lines)
 
@@ -71,12 +90,16 @@ class AsciiCanvas:
         """Create a point on ASCII canvas.
 
         Args:
-            x (int): x coordinate. Should be >= 0 and < number of columns in
+            x: x coordinate. Should be ``>= 0`` and ``<`` number of columns in
                 the canvas.
-            y (int): 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 (str): character to place in the specified point on the
+            char: character to place in the specified point on the
                 canvas.
+
+        Raises:
+            ValueError: if char is not a single character or if
+                coordinates are out of bounds.
         """
         if len(char) != 1:
             msg = "char should be a single character"
@@ -174,13 +197,9 @@ class _EdgeViewer:
 def _build_sugiyama_layout(
     vertices: Mapping[str, str], edges: Sequence[LangEdge]
 ) -> Any:
-    try:
-        from grandalf.graphs import Edge, Graph, Vertex  # type: ignore[import-untyped]
-        from grandalf.layouts import SugiyamaLayout  # type: ignore[import-untyped]
-        from grandalf.routing import route_with_lines  # type: ignore[import-untyped]
-    except ImportError as exc:
+    if not _HAS_GRANDALF:
         msg = "Install grandalf to draw graphs: `pip install grandalf`."
-        raise ImportError(msg) from exc
+        raise ImportError(msg)
 
     #
     # Just a reminder about naming conventions:
@@ -225,11 +244,15 @@ def draw_ascii(vertices: Mapping[str, str], edges: Sequence[LangEdge]) -> str:
     """Build a DAG and draw it in ASCII.
 
     Args:
-        vertices (list): list of graph vertices.
-        edges (list): list of graph edges.
+        vertices: list of graph vertices.
+        edges: list of graph edges.
+
+    Raises:
+        ValueError: if the canvas dimensions are invalid or if
+            edge coordinates are invalid.
 
     Returns:
-        str: ASCII representation
+        ASCII representation
 
     Example:
 

langchain_core/runnables/graph_mermaid.py

@@ -1,24 +1,43 @@
 """Mermaid graph drawing utilities."""
 
+from __future__ import annotations
+
 import asyncio
 import base64
 import random
 import re
+import string
 import time
 from dataclasses import asdict
 from pathlib import Path
-from typing import Any, Literal, Optional
+from typing import TYPE_CHECKING, Any, Literal, Optional
 
 import yaml
 
 from langchain_core.runnables.graph import (
     CurveStyle,
-    Edge,
     MermaidDrawMethod,
-    Node,
     NodeStyles,
 )
 
+if TYPE_CHECKING:
+    from langchain_core.runnables.graph import Edge, Node
+
+
+try:
+    import requests
+
+    _HAS_REQUESTS = True
+except ImportError:
+    _HAS_REQUESTS = False
+
+try:
+    from pyppeteer import launch  # type: ignore[import-not-found]
+
+    _HAS_PYPPETEER = True
+except ImportError:
+    _HAS_PYPPETEER = False
+
 MARKDOWN_SPECIAL_CHARS = "*_`"
 
 
@@ -130,7 +149,7 @@ def draw_mermaid(
                 + "</em></small>"
             )
         node_label = format_dict.get(key, format_dict[default_class_label]).format(
-            _escape_node_label(key), label
+            _to_safe_id(key), label
         )
         return f"{indent}{node_label}\n"
 
@@ -155,7 +174,7 @@ def draw_mermaid(
         nonlocal mermaid_graph
         self_loop = len(edges) == 1 and edges[0].source == edges[0].target
         if prefix and not self_loop:
-            subgraph = prefix.split(":")[-1]
+            subgraph = prefix.rsplit(":", maxsplit=1)[-1]
             if subgraph in seen_subgraphs:
                 msg = (
                     f"Found duplicate subgraph '{subgraph}' -- this likely means that "
@@ -193,8 +212,7 @@ def draw_mermaid(
                 edge_label = " -.-> " if edge.conditional else " --> "
 
             mermaid_graph += (
-                f"\t{_escape_node_label(source)}{edge_label}"
-                f"{_escape_node_label(target)};\n"
+                f"\t{_to_safe_id(source)}{edge_label}{_to_safe_id(target)};\n"
             )
 
         # Recursively add nested subgraphs
@@ -214,7 +232,7 @@ def draw_mermaid(
 
     # Add remaining subgraphs with edges
     for prefix, edges_ in edge_groups.items():
-        if ":" in prefix or prefix == "":
+        if not prefix or ":" in prefix:
             continue
         add_subgraph(edges_, prefix)
         seen_subgraphs.add(prefix)
@@ -238,9 +256,18 @@ def draw_mermaid(
     return mermaid_graph
 
 
-def _escape_node_label(node_label: str) -> str:
-    """Escapes the node label for Mermaid syntax."""
-    return re.sub(r"[^a-zA-Z-_0-9]", "_", node_label)
+def _to_safe_id(label: str) -> str:
+    """Convert a string into a Mermaid-compatible node id.
+
+    Keep [a-zA-Z0-9_-] characters unchanged.
+    Map every other character -> backslash + lowercase hex codepoint.
+
+    Result is guaranteed to be unique and Mermaid-compatible,
+    so nodes with special characters always render correctly.
+    """
+    allowed = string.ascii_letters + string.digits + "_-"
+    out = [ch if ch in allowed else "\\" + format(ord(ch), "x") for ch in label]
+    return "".join(out)
 
 
 def _generate_mermaid_graph_styles(node_colors: NodeStyles) -> str:
@@ -259,6 +286,7 @@ def draw_mermaid_png(
     padding: int = 10,
     max_retries: int = 1,
     retry_delay: float = 1.0,
+    base_url: Optional[str] = None,
 ) -> bytes:
     """Draws a Mermaid graph as PNG using provided syntax.
 
@@ -275,6 +303,8 @@ def draw_mermaid_png(
             Defaults to 1.
         retry_delay (float, optional): Delay between retries (MermaidDrawMethod.API).
             Defaults to 1.0.
+        base_url (str, optional): Base URL for the Mermaid.ink API.
+            Defaults to None.
 
     Returns:
         bytes: PNG image bytes.
@@ -283,8 +313,6 @@ def draw_mermaid_png(
         ValueError: If an invalid draw method is provided.
     """
     if draw_method == MermaidDrawMethod.PYPPETEER:
-        import asyncio
-
         img_bytes = asyncio.run(
             _render_mermaid_using_pyppeteer(
                 mermaid_syntax, output_file_path, background_color, padding
@@ -297,6 +325,7 @@ def draw_mermaid_png(
             background_color=background_color,
             max_retries=max_retries,
             retry_delay=retry_delay,
+            base_url=base_url,
         )
     else:
         supported_methods = ", ".join([m.value for m in MermaidDrawMethod])
@@ -317,11 +346,9 @@ async def _render_mermaid_using_pyppeteer(
     device_scale_factor: int = 3,
 ) -> bytes:
     """Renders Mermaid graph using Pyppeteer."""
-    try:
-        from pyppeteer import launch  # type: ignore[import-not-found]
-    except ImportError as e:
+    if not _HAS_PYPPETEER:
         msg = "Install Pyppeteer to use the Pyppeteer method: `pip install pyppeteer`."
-        raise ImportError(msg) from e
+        raise ImportError(msg)
 
     browser = await launch()
     page = await browser.newPage()
@@ -390,16 +417,18 @@ def _render_mermaid_using_api(
     file_type: Optional[Literal["jpeg", "png", "webp"]] = "png",
     max_retries: int = 1,
     retry_delay: float = 1.0,
+    base_url: Optional[str] = None,
 ) -> bytes:
     """Renders Mermaid graph using the Mermaid.INK API."""
-    try:
-        import requests
-    except ImportError as e:
+    # Defaults to using the public mermaid.ink server.
+    base_url = base_url if base_url is not None else "https://mermaid.ink"
+
+    if not _HAS_REQUESTS:
         msg = (
             "Install the `requests` module to use the Mermaid.INK API: "
             "`pip install requests`."
         )
-        raise ImportError(msg) from e
+        raise ImportError(msg)
 
     # Use Mermaid API to render the image
     mermaid_syntax_encoded = base64.b64encode(mermaid_syntax.encode("utf8")).decode(
@@ -413,7 +442,7 @@ def _render_mermaid_using_api(
             background_color = f"!{background_color}"
 
     image_url = (
-        f"https://mermaid.ink/img/{mermaid_syntax_encoded}"
+        f"{base_url}/img/{mermaid_syntax_encoded}"
         f"?type={file_type}&bgColor={background_color}"
     )
 
@@ -445,7 +474,7 @@ def _render_mermaid_using_api(
 
             # For other status codes, fail immediately
             msg = (
-                "Failed to reach https://mermaid.ink/ API while trying to render "
+                f"Failed to reach {base_url} API while trying to render "
                 f"your graph. Status code: {response.status_code}.\n\n"
             ) + error_msg_suffix
             raise ValueError(msg)
@@ -457,14 +486,14 @@ def _render_mermaid_using_api(
                 time.sleep(sleep_time)
             else:
                 msg = (
-                    "Failed to reach https://mermaid.ink/ API while trying to render "
+                    f"Failed to reach {base_url} API while trying to render "
                     f"your graph after {max_retries} retries. "
                 ) + error_msg_suffix
                 raise ValueError(msg) from e
 
     # This should not be reached, but just in case
     msg = (
-        "Failed to reach https://mermaid.ink/ API while trying to render "
+        f"Failed to reach {base_url} API while trying to render "
         f"your graph after {max_retries} retries. "
     ) + error_msg_suffix
     raise ValueError(msg)

langchain_core/runnables/graph_png.py

@@ -4,29 +4,25 @@ from typing import Any, Optional
 
 from langchain_core.runnables.graph import Graph, LabelsDict
 
+try:
+    import pygraphviz as pgv  # type: ignore[import-not-found]
+
+    _HAS_PYGRAPHVIZ = True
+except ImportError:
+    _HAS_PYGRAPHVIZ = False
+
 
 class PngDrawer:
     """Helper class to draw a state graph into a PNG file.
 
-    It requires `graphviz` and `pygraphviz` to be installed.
-    :param fontname: The font to use for the labels
-    :param labels: A dictionary of label overrides. The dictionary
-        should have the following format:
-        {
-            "nodes": {
-                "node1": "CustomLabel1",
-                "node2": "CustomLabel2",
-                "__end__": "End Node"
-            },
-            "edges": {
-                "continue": "ContinueLabel",
-                "end": "EndLabel"
-            }
-        }
-        The keys are the original labels, and the values are the new labels.
-    Usage:
-        drawer = PngDrawer()
-        drawer.draw(state_graph, 'graph.png')
+    It requires ``graphviz`` and ``pygraphviz`` to be installed.
+
+    Example:
+
+        .. code-block:: python
+
+            drawer = PngDrawer()
+            drawer.draw(state_graph, "graph.png")
     """
 
     def __init__(
@@ -85,9 +81,6 @@ class PngDrawer:
         Args:
             viz: The graphviz object.
             node: The node to add.
-
-        Returns:
-            None
         """
         viz.add_node(
             node,
@@ -114,9 +107,6 @@ class PngDrawer:
             target: The target node.
             label: The label for the edge. Defaults to None.
             conditional: Whether the edge is conditional. Defaults to False.
-
-        Returns:
-            None
         """
         viz.add_edge(
             source,
@@ -131,14 +121,20 @@ class PngDrawer:
         """Draw the given state graph into a PNG file.
 
         Requires `graphviz` and `pygraphviz` to be installed.
-        :param graph: The graph to draw
-        :param output_path: The path to save the PNG. If None, PNG bytes are returned.
+
+        Args:
+            graph: The graph to draw
+            output_path: The path to save the PNG. If None, PNG bytes are returned.
+
+        Raises:
+            ImportError: If ``pygraphviz`` is not installed.
+
+        Returns:
+            The PNG bytes if ``output_path`` is None, else None.
         """
-        try:
-            import pygraphviz as pgv  # type: ignore[import-not-found]
-        except ImportError as exc:
+        if not _HAS_PYGRAPHVIZ:
             msg = "Install pygraphviz to draw graphs: `pip install pygraphviz`."
-            raise ImportError(msg) from exc
+            raise ImportError(msg)
 
         # Create a directed graph
         viz = pgv.AGraph(directed=True, nodesep=0.9, ranksep=1.0)

langchain_core/runnables/history.py

@@ -18,6 +18,7 @@ from typing_extensions import override
 
 from langchain_core.chat_history import BaseChatMessageHistory
 from langchain_core.load.load import load
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
 from langchain_core.runnables.base import Runnable, RunnableBindingBase, RunnableLambda
 from langchain_core.runnables.passthrough import RunnablePassthrough
 from langchain_core.runnables.utils import (
@@ -29,7 +30,6 @@ from langchain_core.utils.pydantic import create_model_v2
 
 if TYPE_CHECKING:
     from langchain_core.language_models.base import LanguageModelLike
-    from langchain_core.messages.base import BaseMessage
     from langchain_core.runnables.config import RunnableConfig
     from langchain_core.tracers.schemas import Run
 
@@ -72,20 +72,6 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
     For production use cases, you will want to use a persistent implementation
     of chat message history, such as ``RedisChatMessageHistory``.
 
-    Parameters:
-        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.
-        input_messages_key: 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: 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: 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.
-
     Example: Chat message history with an in-memory implementation for testing.
 
     .. code-block:: python
@@ -145,11 +131,13 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
             from langchain_core.runnables.history import RunnableWithMessageHistory
 
 
-            prompt = ChatPromptTemplate.from_messages([
-                ("system", "You're an assistant who's good at {ability}"),
-                MessagesPlaceholder(variable_name="history"),
-                ("human", "{question}"),
-            ])
+            prompt = ChatPromptTemplate.from_messages(
+                [
+                    ("system", "You're an assistant who's good at {ability}"),
+                    MessagesPlaceholder(variable_name="history"),
+                    ("human", "{question}"),
+                ]
+            )
 
             chain = prompt | ChatAnthropic(model="claude-2")
 
@@ -162,18 +150,22 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
                 history_messages_key="history",
             )
 
-            print(chain_with_history.invoke(  # noqa: T201
-                {"ability": "math", "question": "What does cosine mean?"},
-                config={"configurable": {"session_id": "foo"}}
-            ))
+            print(
+                chain_with_history.invoke(  # noqa: T201
+                    {"ability": "math", "question": "What does cosine mean?"},
+                    config={"configurable": {"session_id": "foo"}},
+                )
+            )
 
             # Uses the store defined in the example above.
             print(store)  # noqa: T201
 
-            print(chain_with_history.invoke(  # noqa: T201
-                {"ability": "math", "question": "What's its inverse"},
-                config={"configurable": {"session_id": "foo"}}
-            ))
+            print(
+                chain_with_history.invoke(  # noqa: T201
+                    {"ability": "math", "question": "What's its inverse"},
+                    config={"configurable": {"session_id": "foo"}},
+                )
+            )
 
             print(store)  # noqa: T201
 
@@ -184,6 +176,7 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
 
             store = {}
 
+
             def get_session_history(
                 user_id: str, conversation_id: str
             ) -> BaseChatMessageHistory:
@@ -191,11 +184,14 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
                     store[(user_id, conversation_id)] = InMemoryHistory()
                 return store[(user_id, conversation_id)]
 
-            prompt = ChatPromptTemplate.from_messages([
-                ("system", "You're an assistant who's good at {ability}"),
-                MessagesPlaceholder(variable_name="history"),
-                ("human", "{question}"),
-            ])
+
+            prompt = ChatPromptTemplate.from_messages(
+                [
+                    ("system", "You're an assistant who's good at {ability}"),
+                    MessagesPlaceholder(variable_name="history"),
+                    ("human", "{question}"),
+                ]
+            )
 
             chain = prompt | ChatAnthropic(model="claude-2")
 
@@ -226,16 +222,27 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
 
             with_message_history.invoke(
                 {"ability": "math", "question": "What does cosine mean?"},
-                config={"configurable": {"user_id": "123", "conversation_id": "1"}}
+                config={"configurable": {"user_id": "123", "conversation_id": "1"}},
             )
 
     """
 
     get_session_history: GetSessionHistoryCallable
+    """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"""
     input_messages_key: Optional[str] = None
+    """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: Optional[str] = None
+    """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: Optional[str] = None
+    """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."""
 
     def __init__(
         self,
@@ -261,17 +268,21 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
         """Initialize RunnableWithMessageHistory.
 
         Args:
-            runnable: The base Runnable to be wrapped. Must take as input one of:
-                1. A list of BaseMessages
+            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
-                    a separate key for historical messages. If the input key points
-                    to a string, it will be treated as a HumanMessage in history.
+                   a separate key for historical messages. If the input key points
+                   to a string, it will be treated as a ``HumanMessage`` in history.
 
                 Must return as output one of:
-                1. A string which can be treated as an AIMessage
-                2. A BaseMessage or sequence of BaseMessages
-                3. A dict with a key for a BaseMessage or sequence of BaseMessages
+
+                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
+                    ``BaseMessage``
 
             get_session_history: Function that returns a new BaseChatMessageHistory.
                 This function should either take a single positional argument
@@ -280,11 +291,8 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
                 .. code-block:: python
 
                     def get_session_history(
-                        session_id: str,
-                        *,
-                        user_id: Optional[str]=None
-                    ) -> BaseChatMessageHistory:
-                      ...
+                        session_id: str, *, user_id: Optional[str] = None
+                    ) -> BaseChatMessageHistory: ...
 
                 Or it should take keyword arguments that match the keys of
                 `session_history_config_specs` and return a corresponding
@@ -296,8 +304,7 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
                         *,
                         user_id: str,
                         thread_id: str,
-                    ) -> BaseChatMessageHistory:
-                        ...
+                    ) -> BaseChatMessageHistory: ...
 
             input_messages_key: Must be specified if the base runnable accepts a dict
                 as input. Default is None.
@@ -377,8 +384,6 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
     def get_input_schema(
         self, config: Optional[RunnableConfig] = None
     ) -> type[BaseModel]:
-        from langchain_core.messages import BaseMessage
-
         fields: dict = {}
         if self.input_messages_key and self.history_messages_key:
             fields[self.input_messages_key] = (
@@ -440,8 +445,6 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
     def _get_input_messages(
         self, input_val: Union[str, BaseMessage, Sequence[BaseMessage], dict]
     ) -> list[BaseMessage]:
-        from langchain_core.messages import BaseMessage
-
         # If dictionary, try to pluck the single key representing messages
         if isinstance(input_val, dict):
             if self.input_messages_key:
@@ -454,8 +457,6 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
 
         # If value is a string, convert to a human message
         if isinstance(input_val, str):
-            from langchain_core.messages import HumanMessage
-
             return [HumanMessage(content=input_val)]
         # If value is a single message, convert to a list
         if isinstance(input_val, BaseMessage):
@@ -482,8 +483,6 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
     def _get_output_messages(
         self, output_val: Union[str, BaseMessage, Sequence[BaseMessage], dict]
     ) -> list[BaseMessage]:
-        from langchain_core.messages import BaseMessage
-
         # If dictionary, try to pluck the single key representing messages
         if isinstance(output_val, dict):
             if self.output_messages_key:
@@ -500,8 +499,6 @@ class RunnableWithMessageHistory(RunnableBindingBase):  # type: ignore[no-redef]
                 output_val = output_val[key]
 
         if isinstance(output_val, str):
-            from langchain_core.messages import AIMessage
-
             return [AIMessage(content=output_val)]
         # If value is a single message, convert to a list
         if isinstance(output_val, BaseMessage):