@langchain/core 0.3.5 → 0.3.6

package/dist/runnables/graph.cjs

@@ -5,30 +5,28 @@ const zod_to_json_schema_1 = require("zod-to-json-schema");
 const uuid_1 = require("uuid");
 const utils_js_1 = require("./utils.cjs");
 const graph_mermaid_js_1 = require("./graph_mermaid.cjs");
-const MAX_DATA_DISPLAY_NAME_LENGTH = 42;
-function nodeDataStr(node) {
-    if (!(0, uuid_1.validate)(node.id)) {
-        return node.id;
+function nodeDataStr(id, data) {
+    if (id !== undefined && !(0, uuid_1.validate)(id)) {
+        return id;
     }
-    else if ((0, utils_js_1.isRunnableInterface)(node.data)) {
+    else if ((0, utils_js_1.isRunnableInterface)(data)) {
         try {
-            let data = node.data.getName();
-            data = data.startsWith("Runnable") ? data.slice("Runnable".length) : data;
-            if (data.length > MAX_DATA_DISPLAY_NAME_LENGTH) {
-                data = `${data.substring(0, MAX_DATA_DISPLAY_NAME_LENGTH)}...`;
-            }
-            return data;
+            let dataStr = data.getName();
+            dataStr = dataStr.startsWith("Runnable")
+                ? dataStr.slice("Runnable".length)
+                : dataStr;
+            return dataStr;
         }
         catch (error) {
-            return node.data.getName();
+            return data.getName();
         }
     }
     else {
-        return node.data.name ?? "UnknownSchema";
+        return data.name ?? "UnknownSchema";
     }
 }
 function nodeDataJson(node) {
-    // if node.data is implements Runnable
+    // if node.data implements Runnable
     if ((0, utils_js_1.isRunnableInterface)(node.data)) {
         return {
             type: "runnable",
@@ -46,7 +44,7 @@ function nodeDataJson(node) {
     }
 }
 class Graph {
-    constructor() {
+    constructor(params) {
         Object.defineProperty(this, "nodes", {
             enumerable: true,
             configurable: true,
@@ -59,6 +57,8 @@ class Graph {
             writable: true,
             value: []
         });
+        this.nodes = params?.nodes ?? this.nodes;
+        this.edges = params?.edges ?? this.edges;
     }
     // Convert the graph to a JSON-serializable format.
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -87,12 +87,19 @@ class Graph {
             }),
         };
     }
-    addNode(data, id) {
+    addNode(data, id, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    metadata) {
         if (id !== undefined && this.nodes[id] !== undefined) {
             throw new Error(`Node with id ${id} already exists`);
         }
-        const nodeId = id || (0, uuid_1.v4)();
-        const node = { id: nodeId, data };
+        const nodeId = id ?? (0, uuid_1.v4)();
+        const node = {
+            id: nodeId,
+            data,
+            name: nodeDataStr(id, data),
+            metadata,
+        };
         this.nodes[nodeId] = node;
         return node;
     }
@@ -119,24 +126,10 @@ class Graph {
         return edge;
     }
     firstNode() {
-        const targets = new Set(this.edges.map((edge) => edge.target));
-        const found = [];
-        Object.values(this.nodes).forEach((node) => {
-            if (!targets.has(node.id)) {
-                found.push(node);
-            }
-        });
-        return found[0];
+        return _firstNode(this);
     }
     lastNode() {
-        const sources = new Set(this.edges.map((edge) => edge.source));
-        const found = [];
-        Object.values(this.nodes).forEach((node) => {
-            if (!sources.has(node.id)) {
-                found.push(node);
-            }
-        });
-        return found[0];
+        return _lastNode(this);
     }
     /**
      * Add all nodes and edges from another graph.
@@ -172,35 +165,59 @@ class Graph {
     }
     trimFirstNode() {
         const firstNode = this.firstNode();
-        if (firstNode) {
-            const outgoingEdges = this.edges.filter((edge) => edge.source === firstNode.id);
-            if (Object.keys(this.nodes).length === 1 || outgoingEdges.length === 1) {
-                this.removeNode(firstNode);
-            }
+        if (firstNode && _firstNode(this, [firstNode.id])) {
+            this.removeNode(firstNode);
         }
     }
     trimLastNode() {
         const lastNode = this.lastNode();
-        if (lastNode) {
-            const incomingEdges = this.edges.filter((edge) => edge.target === lastNode.id);
-            if (Object.keys(this.nodes).length === 1 || incomingEdges.length === 1) {
-                this.removeNode(lastNode);
-            }
+        if (lastNode && _lastNode(this, [lastNode.id])) {
+            this.removeNode(lastNode);
         }
     }
+    /**
+     * Return a new graph with all nodes re-identified,
+     * using their unique, readable names where possible.
+     */
+    reid() {
+        const nodeLabels = Object.fromEntries(Object.values(this.nodes).map((node) => [node.id, node.name]));
+        const nodeLabelCounts = new Map();
+        Object.values(nodeLabels).forEach((label) => {
+            nodeLabelCounts.set(label, (nodeLabelCounts.get(label) || 0) + 1);
+        });
+        const getNodeId = (nodeId) => {
+            const label = nodeLabels[nodeId];
+            if ((0, uuid_1.validate)(nodeId) && nodeLabelCounts.get(label) === 1) {
+                return label;
+            }
+            else {
+                return nodeId;
+            }
+        };
+        return new Graph({
+            nodes: Object.fromEntries(Object.entries(this.nodes).map(([id, node]) => [
+                getNodeId(id),
+                { ...node, id: getNodeId(id) },
+            ])),
+            edges: this.edges.map((edge) => ({
+                ...edge,
+                source: getNodeId(edge.source),
+                target: getNodeId(edge.target),
+            })),
+        });
+    }
     drawMermaid(params) {
-        const { withStyles, curveStyle, nodeColors = { start: "#ffdfba", end: "#baffc9", other: "#fad7de" }, wrapLabelNWords, } = params ?? {};
-        const nodes = {};
-        for (const node of Object.values(this.nodes)) {
-            nodes[node.id] = nodeDataStr(node);
-        }
-        const firstNode = this.firstNode();
-        const firstNodeLabel = firstNode ? nodeDataStr(firstNode) : undefined;
-        const lastNode = this.lastNode();
-        const lastNodeLabel = lastNode ? nodeDataStr(lastNode) : undefined;
-        return (0, graph_mermaid_js_1.drawMermaid)(nodes, this.edges, {
-            firstNodeLabel,
-            lastNodeLabel,
+        const { withStyles, curveStyle, nodeColors = {
+            default: "fill:#f2f0ff,line-height:1.2",
+            first: "fill-opacity:0",
+            last: "fill:#bfb6fc",
+        }, wrapLabelNWords, } = params ?? {};
+        const graph = this.reid();
+        const firstNode = graph.firstNode();
+        const lastNode = graph.lastNode();
+        return (0, graph_mermaid_js_1.drawMermaid)(graph.nodes, graph.edges, {
+            firstNode: firstNode?.id,
+            lastNode: lastNode?.id,
             withStyles,
             curveStyle,
             nodeColors,
@@ -215,3 +232,39 @@ class Graph {
     }
 }
 exports.Graph = Graph;
+/**
+ * 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 undefined.
+ * When drawing the graph, this node would be the origin.
+ */
+function _firstNode(graph, exclude = []) {
+    const targets = new Set(graph.edges
+        .filter((edge) => !exclude.includes(edge.source))
+        .map((edge) => edge.target));
+    const found = [];
+    for (const node of Object.values(graph.nodes)) {
+        if (!exclude.includes(node.id) && !targets.has(node.id)) {
+            found.push(node);
+        }
+    }
+    return found.length === 1 ? found[0] : undefined;
+}
+/**
+ * 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 undefined.
+ * When drawing the graph, this node would be the destination.
+ */
+function _lastNode(graph, exclude = []) {
+    const sources = new Set(graph.edges
+        .filter((edge) => !exclude.includes(edge.target))
+        .map((edge) => edge.source));
+    const found = [];
+    for (const node of Object.values(graph.nodes)) {
+        if (!exclude.includes(node.id) && !sources.has(node.id)) {
+            found.push(node);
+        }
+    }
+    return found.length === 1 ? found[0] : undefined;
+}

package/dist/runnables/graph.d.ts

@@ -3,8 +3,12 @@ export { Node, Edge };
 export declare class Graph {
     nodes: Record<string, Node>;
     edges: Edge[];
+    constructor(params?: {
+        nodes: Record<string, Node>;
+        edges: Edge[];
+    });
     toJSON(): Record<string, any>;
-    addNode(data: RunnableInterface | RunnableIOSchema, id?: string): Node;
+    addNode(data: RunnableInterface | RunnableIOSchema, id?: string, metadata?: Record<string, any>): Node;
     removeNode(node: Node): void;
     addEdge(source: Node, target: Node, data?: string, conditional?: boolean): Edge;
     firstNode(): Node | undefined;
@@ -19,6 +23,11 @@ export declare class Graph {
     } | undefined)[];
     trimFirstNode(): void;
     trimLastNode(): void;
+    /**
+     * Return a new graph with all nodes re-identified,
+     * using their unique, readable names where possible.
+     */
+    reid(): Graph;
     drawMermaid(params?: {
         withStyles?: boolean;
         curveStyle?: string;

package/dist/runnables/graph.js

@@ -2,30 +2,28 @@ import { zodToJsonSchema } from "zod-to-json-schema";
 import { v4 as uuidv4, validate as isUuid } from "uuid";
 import { isRunnableInterface } from "./utils.js";
 import { drawMermaid, drawMermaidPng } from "./graph_mermaid.js";
-const MAX_DATA_DISPLAY_NAME_LENGTH = 42;
-function nodeDataStr(node) {
-    if (!isUuid(node.id)) {
-        return node.id;
+function nodeDataStr(id, data) {
+    if (id !== undefined && !isUuid(id)) {
+        return id;
     }
-    else if (isRunnableInterface(node.data)) {
+    else if (isRunnableInterface(data)) {
         try {
-            let data = node.data.getName();
-            data = data.startsWith("Runnable") ? data.slice("Runnable".length) : data;
-            if (data.length > MAX_DATA_DISPLAY_NAME_LENGTH) {
-                data = `${data.substring(0, MAX_DATA_DISPLAY_NAME_LENGTH)}...`;
-            }
-            return data;
+            let dataStr = data.getName();
+            dataStr = dataStr.startsWith("Runnable")
+                ? dataStr.slice("Runnable".length)
+                : dataStr;
+            return dataStr;
         }
         catch (error) {
-            return node.data.getName();
+            return data.getName();
         }
     }
     else {
-        return node.data.name ?? "UnknownSchema";
+        return data.name ?? "UnknownSchema";
     }
 }
 function nodeDataJson(node) {
-    // if node.data is implements Runnable
+    // if node.data implements Runnable
     if (isRunnableInterface(node.data)) {
         return {
             type: "runnable",
@@ -43,7 +41,7 @@ function nodeDataJson(node) {
     }
 }
 export class Graph {
-    constructor() {
+    constructor(params) {
         Object.defineProperty(this, "nodes", {
             enumerable: true,
             configurable: true,
@@ -56,6 +54,8 @@ export class Graph {
             writable: true,
             value: []
         });
+        this.nodes = params?.nodes ?? this.nodes;
+        this.edges = params?.edges ?? this.edges;
     }
     // Convert the graph to a JSON-serializable format.
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -84,12 +84,19 @@ export class Graph {
             }),
         };
     }
-    addNode(data, id) {
+    addNode(data, id, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    metadata) {
         if (id !== undefined && this.nodes[id] !== undefined) {
             throw new Error(`Node with id ${id} already exists`);
         }
-        const nodeId = id || uuidv4();
-        const node = { id: nodeId, data };
+        const nodeId = id ?? uuidv4();
+        const node = {
+            id: nodeId,
+            data,
+            name: nodeDataStr(id, data),
+            metadata,
+        };
         this.nodes[nodeId] = node;
         return node;
     }
@@ -116,24 +123,10 @@ export class Graph {
         return edge;
     }
     firstNode() {
-        const targets = new Set(this.edges.map((edge) => edge.target));
-        const found = [];
-        Object.values(this.nodes).forEach((node) => {
-            if (!targets.has(node.id)) {
-                found.push(node);
-            }
-        });
-        return found[0];
+        return _firstNode(this);
     }
     lastNode() {
-        const sources = new Set(this.edges.map((edge) => edge.source));
-        const found = [];
-        Object.values(this.nodes).forEach((node) => {
-            if (!sources.has(node.id)) {
-                found.push(node);
-            }
-        });
-        return found[0];
+        return _lastNode(this);
     }
     /**
      * Add all nodes and edges from another graph.
@@ -169,35 +162,59 @@ export class Graph {
     }
     trimFirstNode() {
         const firstNode = this.firstNode();
-        if (firstNode) {
-            const outgoingEdges = this.edges.filter((edge) => edge.source === firstNode.id);
-            if (Object.keys(this.nodes).length === 1 || outgoingEdges.length === 1) {
-                this.removeNode(firstNode);
-            }
+        if (firstNode && _firstNode(this, [firstNode.id])) {
+            this.removeNode(firstNode);
         }
     }
     trimLastNode() {
         const lastNode = this.lastNode();
-        if (lastNode) {
-            const incomingEdges = this.edges.filter((edge) => edge.target === lastNode.id);
-            if (Object.keys(this.nodes).length === 1 || incomingEdges.length === 1) {
-                this.removeNode(lastNode);
-            }
+        if (lastNode && _lastNode(this, [lastNode.id])) {
+            this.removeNode(lastNode);
         }
     }
+    /**
+     * Return a new graph with all nodes re-identified,
+     * using their unique, readable names where possible.
+     */
+    reid() {
+        const nodeLabels = Object.fromEntries(Object.values(this.nodes).map((node) => [node.id, node.name]));
+        const nodeLabelCounts = new Map();
+        Object.values(nodeLabels).forEach((label) => {
+            nodeLabelCounts.set(label, (nodeLabelCounts.get(label) || 0) + 1);
+        });
+        const getNodeId = (nodeId) => {
+            const label = nodeLabels[nodeId];
+            if (isUuid(nodeId) && nodeLabelCounts.get(label) === 1) {
+                return label;
+            }
+            else {
+                return nodeId;
+            }
+        };
+        return new Graph({
+            nodes: Object.fromEntries(Object.entries(this.nodes).map(([id, node]) => [
+                getNodeId(id),
+                { ...node, id: getNodeId(id) },
+            ])),
+            edges: this.edges.map((edge) => ({
+                ...edge,
+                source: getNodeId(edge.source),
+                target: getNodeId(edge.target),
+            })),
+        });
+    }
     drawMermaid(params) {
-        const { withStyles, curveStyle, nodeColors = { start: "#ffdfba", end: "#baffc9", other: "#fad7de" }, wrapLabelNWords, } = params ?? {};
-        const nodes = {};
-        for (const node of Object.values(this.nodes)) {
-            nodes[node.id] = nodeDataStr(node);
-        }
-        const firstNode = this.firstNode();
-        const firstNodeLabel = firstNode ? nodeDataStr(firstNode) : undefined;
-        const lastNode = this.lastNode();
-        const lastNodeLabel = lastNode ? nodeDataStr(lastNode) : undefined;
-        return drawMermaid(nodes, this.edges, {
-            firstNodeLabel,
-            lastNodeLabel,
+        const { withStyles, curveStyle, nodeColors = {
+            default: "fill:#f2f0ff,line-height:1.2",
+            first: "fill-opacity:0",
+            last: "fill:#bfb6fc",
+        }, wrapLabelNWords, } = params ?? {};
+        const graph = this.reid();
+        const firstNode = graph.firstNode();
+        const lastNode = graph.lastNode();
+        return drawMermaid(graph.nodes, graph.edges, {
+            firstNode: firstNode?.id,
+            lastNode: lastNode?.id,
             withStyles,
             curveStyle,
             nodeColors,
@@ -211,3 +228,39 @@ export class Graph {
         });
     }
 }
+/**
+ * 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 undefined.
+ * When drawing the graph, this node would be the origin.
+ */
+function _firstNode(graph, exclude = []) {
+    const targets = new Set(graph.edges
+        .filter((edge) => !exclude.includes(edge.source))
+        .map((edge) => edge.target));
+    const found = [];
+    for (const node of Object.values(graph.nodes)) {
+        if (!exclude.includes(node.id) && !targets.has(node.id)) {
+            found.push(node);
+        }
+    }
+    return found.length === 1 ? found[0] : undefined;
+}
+/**
+ * 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 undefined.
+ * When drawing the graph, this node would be the destination.
+ */
+function _lastNode(graph, exclude = []) {
+    const sources = new Set(graph.edges
+        .filter((edge) => !exclude.includes(edge.target))
+        .map((edge) => edge.source));
+    const found = [];
+    for (const node of Object.values(graph.nodes)) {
+        if (!exclude.includes(node.id) && !sources.has(node.id)) {
+            found.push(node);
+        }
+    }
+    return found.length === 1 ? found[0] : undefined;
+}

package/dist/runnables/graph_mermaid.cjs

@@ -5,16 +5,11 @@ function _escapeNodeLabel(nodeLabel) {
     // Escapes the node label for Mermaid syntax.
     return nodeLabel.replace(/[^a-zA-Z-_0-9]/g, "_");
 }
-// Adjusts Mermaid edge to map conditional nodes to pure nodes.
-function _adjustMermaidEdge(edge, nodes) {
-    const sourceNodeLabel = nodes[edge.source] ?? edge.source;
-    const targetNodeLabel = nodes[edge.target] ?? edge.target;
-    return [sourceNodeLabel, targetNodeLabel];
-}
+const MARKDOWN_SPECIAL_CHARS = ["*", "_", "`"];
 function _generateMermaidGraphStyles(nodeColors) {
     let styles = "";
     for (const [className, color] of Object.entries(nodeColors)) {
-        styles += `\tclassDef ${className}class fill:${color};\n`;
+        styles += `\tclassDef ${className} ${color};\n`;
     }
     return styles;
 }
@@ -22,7 +17,7 @@ function _generateMermaidGraphStyles(nodeColors) {
  * Draws a Mermaid graph using the provided graph data
  */
 function drawMermaid(nodes, edges, config) {
-    const { firstNodeLabel, lastNodeLabel, nodeColors, withStyles = true, curveStyle = "linear", wrapLabelNWords = 9, } = config ?? {};
+    const { firstNode, lastNode, nodeColors, withStyles = true, curveStyle = "linear", wrapLabelNWords = 9, } = config ?? {};
     // Initialize Mermaid graph configuration
     let mermaidGraph = withStyles
         ? `%%{init: {'flowchart': {'curve': '${curveStyle}'}}}%%\ngraph TD;\n`
@@ -31,87 +26,99 @@ function drawMermaid(nodes, edges, config) {
         // Node formatting templates
         const defaultClassLabel = "default";
         const formatDict = {
-            [defaultClassLabel]: "{0}([{1}]):::otherclass",
+            [defaultClassLabel]: "{0}({1})",
         };
-        if (firstNodeLabel !== undefined) {
-            formatDict[firstNodeLabel] = "{0}[{0}]:::startclass";
+        if (firstNode !== undefined) {
+            formatDict[firstNode] = "{0}([{1}]):::first";
         }
-        if (lastNodeLabel !== undefined) {
-            formatDict[lastNodeLabel] = "{0}[{0}]:::endclass";
+        if (lastNode !== undefined) {
+            formatDict[lastNode] = "{0}([{1}]):::last";
         }
         // Add nodes to the graph
-        for (const node of Object.values(nodes)) {
-            const nodeLabel = formatDict[node] ?? formatDict[defaultClassLabel];
-            const escapedNodeLabel = _escapeNodeLabel(node);
-            const nodeParts = node.split(":");
-            const nodeSplit = nodeParts[nodeParts.length - 1];
-            mermaidGraph += `\t${nodeLabel
-                .replace(/\{0\}/g, escapedNodeLabel)
-                .replace(/\{1\}/g, nodeSplit)};\n`;
+        for (const [key, node] of Object.entries(nodes)) {
+            const nodeName = node.name.split(":").pop() ?? "";
+            const label = MARKDOWN_SPECIAL_CHARS.some((char) => nodeName.startsWith(char) && nodeName.endsWith(char))
+                ? `<p>${nodeName}</p>`
+                : nodeName;
+            let finalLabel = label;
+            if (Object.keys(node.metadata ?? {}).length) {
+                finalLabel += `<hr/><small><em>${Object.entries(node.metadata ?? {})
+                    .map(([k, v]) => `${k} = ${v}`)
+                    .join("\n")}</em></small>`;
+            }
+            const nodeLabel = (formatDict[key] ?? formatDict[defaultClassLabel])
+                .replace("{0}", _escapeNodeLabel(key))
+                .replace("{1}", finalLabel);
+            mermaidGraph += `\t${nodeLabel}\n`;
         }
     }
-    let subgraph = "";
-    // Add edges to the graph
+    // Group edges by their common prefixes
+    const edgeGroups = {};
     for (const edge of edges) {
-        const sourcePrefix = edge.source.includes(":")
-            ? edge.source.split(":")[0]
-            : undefined;
-        const targetPrefix = edge.target.includes(":")
-            ? edge.target.split(":")[0]
-            : undefined;
-        // Exit subgraph if source or target is not in the same subgraph
-        if (subgraph !== "" &&
-            (subgraph !== sourcePrefix || subgraph !== targetPrefix)) {
-            mermaidGraph += "\tend\n";
-            subgraph = "";
+        const srcParts = edge.source.split(":");
+        const tgtParts = edge.target.split(":");
+        const commonPrefix = srcParts
+            .filter((src, i) => src === tgtParts[i])
+            .join(":");
+        if (!edgeGroups[commonPrefix]) {
+            edgeGroups[commonPrefix] = [];
         }
-        // Enter subgraph if source and target are in the same subgraph
-        if (subgraph === "" &&
-            sourcePrefix !== undefined &&
-            sourcePrefix === targetPrefix) {
-            mermaidGraph = `\tsubgraph ${sourcePrefix}\n`;
-            subgraph = sourcePrefix;
-        }
-        const [source, target] = _adjustMermaidEdge(edge, nodes);
-        let edgeLabel = "";
-        // Add BR every wrapLabelNWords words
-        if (edge.data !== undefined) {
-            let edgeData = edge.data;
-            const words = edgeData.split(" ");
-            // Group words into chunks of wrapLabelNWords size
-            if (words.length > wrapLabelNWords) {
-                edgeData = words
-                    .reduce((acc, word, i) => {
-                    if (i % wrapLabelNWords === 0)
-                        acc.push("");
-                    acc[acc.length - 1] += ` ${word}`;
-                    return acc;
-                }, [])
-                    .join("<br>");
+        edgeGroups[commonPrefix].push(edge);
+    }
+    const seenSubgraphs = new Set();
+    function addSubgraph(edges, prefix) {
+        const selfLoop = edges.length === 1 && edges[0].source === edges[0].target;
+        if (prefix && !selfLoop) {
+            const subgraph = prefix.split(":").pop();
+            if (seenSubgraphs.has(subgraph)) {
+                throw new Error(`Found duplicate subgraph '${subgraph}' -- this likely means that ` +
+                    "you're reusing a subgraph node with the same name. " +
+                    "Please adjust your graph to have subgraph nodes with unique names.");
             }
-            if (edge.conditional) {
-                edgeLabel = ` -. ${edgeData} .-> `;
+            seenSubgraphs.add(subgraph);
+            mermaidGraph += `\tsubgraph ${subgraph}\n`;
+        }
+        for (const edge of edges) {
+            const { source, target, data, conditional } = edge;
+            let edgeLabel = "";
+            if (data !== undefined) {
+                let edgeData = data;
+                const words = edgeData.split(" ");
+                if (words.length > wrapLabelNWords) {
+                    edgeData = Array.from({ length: Math.ceil(words.length / wrapLabelNWords) }, (_, i) => words
+                        .slice(i * wrapLabelNWords, (i + 1) * wrapLabelNWords)
+                        .join(" ")).join("&nbsp;<br>&nbsp;");
+                }
+                edgeLabel = conditional
+                    ? ` -. &nbsp;${edgeData}&nbsp; .-> `
+                    : ` -- &nbsp;${edgeData}&nbsp; --> `;
             }
             else {
-                edgeLabel = ` -- ${edgeData} --> `;
+                edgeLabel = conditional ? " -.-> " : " --> ";
             }
+            mermaidGraph += `\t${_escapeNodeLabel(source)}${edgeLabel}${_escapeNodeLabel(target)};\n`;
         }
-        else {
-            if (edge.conditional) {
-                edgeLabel = ` -.-> `;
-            }
-            else {
-                edgeLabel = ` --> `;
+        // Recursively add nested subgraphs
+        for (const nestedPrefix in edgeGroups) {
+            if (nestedPrefix.startsWith(`${prefix}:`) && nestedPrefix !== prefix) {
+                addSubgraph(edgeGroups[nestedPrefix], nestedPrefix);
             }
         }
-        mermaidGraph += `\t${_escapeNodeLabel(source)}${edgeLabel}${_escapeNodeLabel(target)};\n`;
+        if (prefix && !selfLoop) {
+            mermaidGraph += "\tend\n";
+        }
     }
-    if (subgraph !== "") {
-        mermaidGraph += "end\n";
+    // Start with the top-level edges (no common prefix)
+    addSubgraph(edgeGroups[""] ?? [], "");
+    // Add remaining subgraphs
+    for (const prefix in edgeGroups) {
+        if (!prefix.includes(":") && prefix !== "") {
+            addSubgraph(edgeGroups[prefix], prefix);
+        }
     }
     // Add custom styles for nodes
-    if (withStyles && nodeColors !== undefined) {
-        mermaidGraph += _generateMermaidGraphStyles(nodeColors);
+    if (withStyles) {
+        mermaidGraph += _generateMermaidGraphStyles(nodeColors ?? {});
     }
     return mermaidGraph;
 }

package/dist/runnables/graph_mermaid.d.ts

@@ -1,10 +1,10 @@
-import { Edge } from "./types.js";
+import { Edge, Node } from "./types.js";
 /**
  * Draws a Mermaid graph using the provided graph data
  */
-export declare function drawMermaid(nodes: Record<string, string>, edges: Edge[], config?: {
-    firstNodeLabel?: string;
-    lastNodeLabel?: string;
+export declare function drawMermaid(nodes: Record<string, Node>, edges: Edge[], config?: {
+    firstNode?: string;
+    lastNode?: string;
     curveStyle?: string;
     withStyles?: boolean;
     nodeColors?: Record<string, string>;

package/dist/runnables/graph_mermaid.js

@@ -2,16 +2,11 @@ function _escapeNodeLabel(nodeLabel) {
     // Escapes the node label for Mermaid syntax.
     return nodeLabel.replace(/[^a-zA-Z-_0-9]/g, "_");
 }
-// Adjusts Mermaid edge to map conditional nodes to pure nodes.
-function _adjustMermaidEdge(edge, nodes) {
-    const sourceNodeLabel = nodes[edge.source] ?? edge.source;
-    const targetNodeLabel = nodes[edge.target] ?? edge.target;
-    return [sourceNodeLabel, targetNodeLabel];
-}
+const MARKDOWN_SPECIAL_CHARS = ["*", "_", "`"];
 function _generateMermaidGraphStyles(nodeColors) {
     let styles = "";
     for (const [className, color] of Object.entries(nodeColors)) {
-        styles += `\tclassDef ${className}class fill:${color};\n`;
+        styles += `\tclassDef ${className} ${color};\n`;
     }
     return styles;
 }
@@ -19,7 +14,7 @@ function _generateMermaidGraphStyles(nodeColors) {
  * Draws a Mermaid graph using the provided graph data
  */
 export function drawMermaid(nodes, edges, config) {
-    const { firstNodeLabel, lastNodeLabel, nodeColors, withStyles = true, curveStyle = "linear", wrapLabelNWords = 9, } = config ?? {};
+    const { firstNode, lastNode, nodeColors, withStyles = true, curveStyle = "linear", wrapLabelNWords = 9, } = config ?? {};
     // Initialize Mermaid graph configuration
     let mermaidGraph = withStyles
         ? `%%{init: {'flowchart': {'curve': '${curveStyle}'}}}%%\ngraph TD;\n`
@@ -28,87 +23,99 @@ export function drawMermaid(nodes, edges, config) {
         // Node formatting templates
         const defaultClassLabel = "default";
         const formatDict = {
-            [defaultClassLabel]: "{0}([{1}]):::otherclass",
+            [defaultClassLabel]: "{0}({1})",
         };
-        if (firstNodeLabel !== undefined) {
-            formatDict[firstNodeLabel] = "{0}[{0}]:::startclass";
+        if (firstNode !== undefined) {
+            formatDict[firstNode] = "{0}([{1}]):::first";
         }
-        if (lastNodeLabel !== undefined) {
-            formatDict[lastNodeLabel] = "{0}[{0}]:::endclass";
+        if (lastNode !== undefined) {
+            formatDict[lastNode] = "{0}([{1}]):::last";
         }
         // Add nodes to the graph
-        for (const node of Object.values(nodes)) {
-            const nodeLabel = formatDict[node] ?? formatDict[defaultClassLabel];
-            const escapedNodeLabel = _escapeNodeLabel(node);
-            const nodeParts = node.split(":");
-            const nodeSplit = nodeParts[nodeParts.length - 1];
-            mermaidGraph += `\t${nodeLabel
-                .replace(/\{0\}/g, escapedNodeLabel)
-                .replace(/\{1\}/g, nodeSplit)};\n`;
+        for (const [key, node] of Object.entries(nodes)) {
+            const nodeName = node.name.split(":").pop() ?? "";
+            const label = MARKDOWN_SPECIAL_CHARS.some((char) => nodeName.startsWith(char) && nodeName.endsWith(char))
+                ? `<p>${nodeName}</p>`
+                : nodeName;
+            let finalLabel = label;
+            if (Object.keys(node.metadata ?? {}).length) {
+                finalLabel += `<hr/><small><em>${Object.entries(node.metadata ?? {})
+                    .map(([k, v]) => `${k} = ${v}`)
+                    .join("\n")}</em></small>`;
+            }
+            const nodeLabel = (formatDict[key] ?? formatDict[defaultClassLabel])
+                .replace("{0}", _escapeNodeLabel(key))
+                .replace("{1}", finalLabel);
+            mermaidGraph += `\t${nodeLabel}\n`;
         }
     }
-    let subgraph = "";
-    // Add edges to the graph
+    // Group edges by their common prefixes
+    const edgeGroups = {};
     for (const edge of edges) {
-        const sourcePrefix = edge.source.includes(":")
-            ? edge.source.split(":")[0]
-            : undefined;
-        const targetPrefix = edge.target.includes(":")
-            ? edge.target.split(":")[0]
-            : undefined;
-        // Exit subgraph if source or target is not in the same subgraph
-        if (subgraph !== "" &&
-            (subgraph !== sourcePrefix || subgraph !== targetPrefix)) {
-            mermaidGraph += "\tend\n";
-            subgraph = "";
+        const srcParts = edge.source.split(":");
+        const tgtParts = edge.target.split(":");
+        const commonPrefix = srcParts
+            .filter((src, i) => src === tgtParts[i])
+            .join(":");
+        if (!edgeGroups[commonPrefix]) {
+            edgeGroups[commonPrefix] = [];
         }
-        // Enter subgraph if source and target are in the same subgraph
-        if (subgraph === "" &&
-            sourcePrefix !== undefined &&
-            sourcePrefix === targetPrefix) {
-            mermaidGraph = `\tsubgraph ${sourcePrefix}\n`;
-            subgraph = sourcePrefix;
-        }
-        const [source, target] = _adjustMermaidEdge(edge, nodes);
-        let edgeLabel = "";
-        // Add BR every wrapLabelNWords words
-        if (edge.data !== undefined) {
-            let edgeData = edge.data;
-            const words = edgeData.split(" ");
-            // Group words into chunks of wrapLabelNWords size
-            if (words.length > wrapLabelNWords) {
-                edgeData = words
-                    .reduce((acc, word, i) => {
-                    if (i % wrapLabelNWords === 0)
-                        acc.push("");
-                    acc[acc.length - 1] += ` ${word}`;
-                    return acc;
-                }, [])
-                    .join("<br>");
+        edgeGroups[commonPrefix].push(edge);
+    }
+    const seenSubgraphs = new Set();
+    function addSubgraph(edges, prefix) {
+        const selfLoop = edges.length === 1 && edges[0].source === edges[0].target;
+        if (prefix && !selfLoop) {
+            const subgraph = prefix.split(":").pop();
+            if (seenSubgraphs.has(subgraph)) {
+                throw new Error(`Found duplicate subgraph '${subgraph}' -- this likely means that ` +
+                    "you're reusing a subgraph node with the same name. " +
+                    "Please adjust your graph to have subgraph nodes with unique names.");
             }
-            if (edge.conditional) {
-                edgeLabel = ` -. ${edgeData} .-> `;
+            seenSubgraphs.add(subgraph);
+            mermaidGraph += `\tsubgraph ${subgraph}\n`;
+        }
+        for (const edge of edges) {
+            const { source, target, data, conditional } = edge;
+            let edgeLabel = "";
+            if (data !== undefined) {
+                let edgeData = data;
+                const words = edgeData.split(" ");
+                if (words.length > wrapLabelNWords) {
+                    edgeData = Array.from({ length: Math.ceil(words.length / wrapLabelNWords) }, (_, i) => words
+                        .slice(i * wrapLabelNWords, (i + 1) * wrapLabelNWords)
+                        .join(" ")).join("&nbsp;<br>&nbsp;");
+                }
+                edgeLabel = conditional
+                    ? ` -. &nbsp;${edgeData}&nbsp; .-> `
+                    : ` -- &nbsp;${edgeData}&nbsp; --> `;
             }
             else {
-                edgeLabel = ` -- ${edgeData} --> `;
+                edgeLabel = conditional ? " -.-> " : " --> ";
             }
+            mermaidGraph += `\t${_escapeNodeLabel(source)}${edgeLabel}${_escapeNodeLabel(target)};\n`;
         }
-        else {
-            if (edge.conditional) {
-                edgeLabel = ` -.-> `;
-            }
-            else {
-                edgeLabel = ` --> `;
+        // Recursively add nested subgraphs
+        for (const nestedPrefix in edgeGroups) {
+            if (nestedPrefix.startsWith(`${prefix}:`) && nestedPrefix !== prefix) {
+                addSubgraph(edgeGroups[nestedPrefix], nestedPrefix);
             }
         }
-        mermaidGraph += `\t${_escapeNodeLabel(source)}${edgeLabel}${_escapeNodeLabel(target)};\n`;
+        if (prefix && !selfLoop) {
+            mermaidGraph += "\tend\n";
+        }
     }
-    if (subgraph !== "") {
-        mermaidGraph += "end\n";
+    // Start with the top-level edges (no common prefix)
+    addSubgraph(edgeGroups[""] ?? [], "");
+    // Add remaining subgraphs
+    for (const prefix in edgeGroups) {
+        if (!prefix.includes(":") && prefix !== "") {
+            addSubgraph(edgeGroups[prefix], prefix);
+        }
     }
     // Add custom styles for nodes
-    if (withStyles && nodeColors !== undefined) {
-        mermaidGraph += _generateMermaidGraphStyles(nodeColors);
+    if (withStyles) {
+        mermaidGraph += _generateMermaidGraphStyles(nodeColors ?? {});
     }
     return mermaidGraph;
 }

package/dist/runnables/types.d.ts

@@ -39,7 +39,9 @@ export interface Edge {
 }
 export interface Node {
     id: string;
+    name: string;
     data: RunnableIOSchema | RunnableInterface;
+    metadata?: Record<string, any>;
 }
 export interface RunnableConfig extends BaseCallbackConfig {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/core",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Core LangChain.js abstractions and schemas",
   "type": "module",
   "engines": {