@langchain/langgraph 0.0.11 → 0.0.13

package/dist/graph/graph.d.ts

@@ -1,32 +1,61 @@
 import { Runnable, RunnableConfig, RunnableLike } from "@langchain/core/runnables";
-import { Pregel } from "../pregel/index.js";
+import { PregelNode } from "../pregel/read.js";
+import { Pregel, PregelInterface } from "../pregel/index.js";
 import { BaseCheckpointSaver } from "../checkpoint/base.js";
+import { BaseChannel } from "../channels/base.js";
+import { All } from "../pregel/types.js";
+import { RunnableCallable } from "../utils.js";
+export declare const START = "__start__";
 export declare const END = "__end__";
-type EndsMap = {
-    [result: string]: string;
-};
-declare class Branch {
-    condition: CallableFunction;
-    ends?: EndsMap;
-    constructor(condition: CallableFunction, ends?: EndsMap);
-    runnable(input: any, options?: {
-        config?: RunnableConfig;
-    }): Runnable;
+export interface BranchOptions<IO, N extends string> {
+    source: N;
+    path: Branch<IO, N>["condition"];
+    pathMap?: Record<string, N | typeof END> | N[];
+    then?: N | typeof END;
 }
-export declare class Graph<RunInput = any, RunOutput = any> {
-    nodes: Record<string, Runnable<RunInput, RunOutput>>;
-    edges: Set<[string, string]>;
-    branches: Record<string, Branch[]>;
+export declare class Branch<IO, N extends string> {
+    condition: (input: IO, config?: RunnableConfig) => string | string[] | Promise<string> | Promise<string[]>;
+    ends?: Record<string, N | typeof END>;
+    then?: BranchOptions<IO, N>["then"];
+    constructor(options: Omit<BranchOptions<IO, N>, "source">);
+    compile(writer: (dests: string[]) => Runnable | undefined, reader?: (config: RunnableConfig) => IO): RunnableCallable<unknown, unknown>;
+    _route(input: IO, config: RunnableConfig, writer: (dests: string[]) => Runnable | undefined, reader?: (config: RunnableConfig) => IO): Promise<Runnable | undefined>;
+}
+export declare class Graph<const N extends string = typeof END, RunInput = any, RunOutput = any> {
+    nodes: Record<N, Runnable<RunInput, RunOutput>>;
+    edges: Set<[N | typeof START, N | typeof END]>;
+    branches: Record<string, Record<string, Branch<RunInput, N>>>;
     entryPoint?: string;
     compiled: boolean;
+    supportMultipleEdges: boolean;
     constructor();
     private warnIfCompiled;
-    addNode(key: string, action: RunnableLike<RunInput, RunOutput>): void;
-    addEdge(startKey: string, endKey: string): void;
-    addConditionalEdges(startKey: string, condition: CallableFunction, conditionalEdgeMapping?: Record<string, string>): void;
-    setEntryPoint(key: string): void;
-    setFinishPoint(key: string): void;
-    compile(checkpointer?: BaseCheckpointSaver): Pregel;
-    validate(): void;
+    get allEdges(): Set<[string, string]>;
+    addNode<K extends string>(key: K, action: RunnableLike<RunInput, RunOutput>): Graph<N | K, RunInput, RunOutput>;
+    addEdge(startKey: N | typeof START, endKey: N | typeof END): this;
+    addConditionalEdges(source: BranchOptions<RunInput, N>): this;
+    addConditionalEdges(source: N, path: Branch<RunInput, N>["condition"], pathMap?: BranchOptions<RunInput, N>["pathMap"]): this;
+    /**
+     * @deprecated use `addEdge(START, key)` instead
+     */
+    setEntryPoint(key: N): this;
+    /**
+     * @deprecated use `addEdge(key, END)` instead
+     */
+    setFinishPoint(key: N): this;
+    compile({ checkpointer, interruptBefore, interruptAfter, }?: {
+        checkpointer?: BaseCheckpointSaver;
+        interruptBefore?: N[] | All;
+        interruptAfter?: N[] | All;
+    }): CompiledGraph<N>;
+    validate(interrupt?: string[]): void;
+}
+export declare class CompiledGraph<N extends string, RunInput = any, RunOutput = any> extends Pregel<Record<N | typeof START, PregelNode<RunInput, RunOutput>>, Record<N | typeof START | typeof END | string, BaseChannel>> {
+    builder: Graph<N, RunInput, RunOutput>;
+    constructor({ builder, ...rest }: {
+        builder: Graph<N, RunInput, RunOutput>;
+    } & PregelInterface<Record<N | typeof START, PregelNode<RunInput, RunOutput>>, Record<N | typeof START | typeof END | string, BaseChannel>>);
+    attachNode(key: N, node: Runnable<RunInput, RunOutput>): void;
+    attachEdge(start: N | typeof START, end: N | typeof END): void;
+    attachBranch(start: N | typeof START, name: string, branch: Branch<RunInput, N>): void;
 }
-export {};

package/dist/graph/graph.js

@@ -1,8 +1,15 @@
-import { RunnableLambda, _coerceToRunnable, } from "@langchain/core/runnables";
+/* eslint-disable @typescript-eslint/no-use-before-define */
+import { _coerceToRunnable, } from "@langchain/core/runnables";
+import { PregelNode } from "../pregel/read.js";
 import { Channel, Pregel } from "../pregel/index.js";
+import { EphemeralValue } from "../channels/ephemeral_value.js";
+import { ChannelWrite, PASSTHROUGH } from "../pregel/write.js";
+import { TAG_HIDDEN } from "../constants.js";
+import { RunnableCallable } from "../utils.js";
+export const START = "__start__";
 export const END = "__end__";
-class Branch {
-    constructor(condition, ends) {
+export class Branch {
+    constructor(options) {
         Object.defineProperty(this, "condition", {
             enumerable: true,
             configurable: true,
@@ -15,20 +22,39 @@ class Branch {
             writable: true,
             value: void 0
         });
-        this.condition = condition;
-        this.ends = ends;
+        Object.defineProperty(this, "then", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.condition = options.path;
+        this.ends = Array.isArray(options.pathMap)
+            ? options.pathMap.reduce((acc, n) => {
+                acc[n] = n;
+                return acc;
+            }, {})
+            : options.pathMap;
+        this.then = options.then;
+    }
+    compile(writer, reader) {
+        return ChannelWrite.registerWriter(new RunnableCallable({
+            func: (input, config) => this._route(input, config, writer, reader),
+        }));
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    runnable(input, options) {
-        const result = this.condition(input, options?.config);
-        let destination;
+    async _route(input, config, writer, reader) {
+        let result = await this.condition(reader ? reader(config) : input, config);
+        if (!Array.isArray(result)) {
+            result = [result];
+        }
+        let destinations;
         if (this.ends) {
-            destination = this.ends[result];
+            destinations = result.map((r) => this.ends[r]);
         }
         else {
-            destination = result;
+            destinations = result;
         }
-        return Channel.writeTo(destination !== END ? `${destination}:inbox` : END);
+        return writer(destinations);
     }
 }
 export class Graph {
@@ -63,6 +89,12 @@ export class Graph {
             writable: true,
             value: false
         });
+        Object.defineProperty(this, "supportMultipleEdges", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
         this.nodes = {};
         this.edges = new Set();
         this.branches = {};
@@ -72,132 +104,236 @@ export class Graph {
             console.warn(message);
         }
     }
+    get allEdges() {
+        return this.edges;
+    }
     addNode(key, action) {
         this.warnIfCompiled(`Adding a node to a graph that has already been compiled. This will not be reflected in the compiled graph.`);
-        if (this.nodes[key]) {
+        if (key in this.nodes) {
             throw new Error(`Node \`${key}\` already present.`);
         }
         if (key === END) {
             throw new Error(`Node \`${key}\` is reserved.`);
         }
         this.nodes[key] = _coerceToRunnable(action);
+        return this;
     }
     addEdge(startKey, endKey) {
         this.warnIfCompiled(`Adding an edge to a graph that has already been compiled. This will not be reflected in the compiled graph.`);
         if (startKey === END) {
             throw new Error("END cannot be a start node");
         }
-        if (!this.nodes[startKey]) {
-            throw new Error(`Need to addNode \`${startKey}\` first`);
-        }
-        if (!this.nodes[endKey] && endKey !== END) {
-            throw new Error(`Need to addNode \`${endKey}\` first`);
+        if (endKey === START) {
+            throw new Error("START cannot be an end node");
         }
-        // TODO: support multiple message passing
-        if (Array.from(this.edges).some(([start]) => start === startKey)) {
+        if (!this.supportMultipleEdges &&
+            Array.from(this.edges).some(([start]) => start === startKey)) {
             throw new Error(`Already found path for ${startKey}`);
         }
         this.edges.add([startKey, endKey]);
+        return this;
     }
-    addConditionalEdges(startKey, condition, conditionalEdgeMapping) {
+    addConditionalEdges(source, path, pathMap) {
+        const options = typeof source === "object" ? source : { source, path: path, pathMap };
         this.warnIfCompiled("Adding an edge to a graph that has already been compiled. This will not be reflected in the compiled graph.");
-        if (!this.nodes[startKey]) {
-            throw new Error(`Need to addNode \`${startKey}\` first`);
-        }
-        if (condition.constructor.name === "AsyncFunction") {
-            throw new Error("Condition cannot be an async function");
-        }
-        if (conditionalEdgeMapping) {
-            const mappingValues = Array.from(Object.values(conditionalEdgeMapping));
-            const nodesValues = Object.keys(this.nodes);
-            const endExcluded = mappingValues.filter((value) => value !== END);
-            const difference = endExcluded.filter((value) => !nodesValues.some((nv) => nv === value));
-            if (difference.length > 0) {
-                throw new Error(`Missing nodes which are in conditional edge mapping.\nMapping contains possible destinations: ${mappingValues.join(", ")}.\nPossible nodes are ${nodesValues.join(", ")}.`);
-            }
+        // find a name for condition
+        const name = options.path.name || "condition";
+        // validate condition
+        if (this.branches[options.source] && this.branches[options.source][name]) {
+            throw new Error(`Condition \`${name}\` already present for node \`${source}\``);
         }
-        if (!this.branches[startKey]) {
-            this.branches[startKey] = [];
+        // save it
+        if (!this.branches[options.source]) {
+            this.branches[options.source] = {};
         }
-        this.branches[startKey].push(new Branch(condition, conditionalEdgeMapping));
+        this.branches[options.source][name] = new Branch(options);
+        return this;
     }
+    /**
+     * @deprecated use `addEdge(START, key)` instead
+     */
     setEntryPoint(key) {
         this.warnIfCompiled("Setting the entry point of a graph that has already been compiled. This will not be reflected in the compiled graph.");
-        if (!this.nodes[key]) {
-            throw new Error(`Need to addNode \`${key}\` first`);
-        }
-        this.entryPoint = key;
+        return this.addEdge(START, key);
     }
+    /**
+     * @deprecated use `addEdge(key, END)` instead
+     */
     setFinishPoint(key) {
         this.warnIfCompiled("Setting a finish point of a graph that has already been compiled. This will not be reflected in the compiled graph.");
-        this.addEdge(key, END);
-    }
-    compile(checkpointer) {
-        this.validate();
-        const outgoingEdges = {};
-        this.edges.forEach(([start, end]) => {
-            if (!outgoingEdges[start]) {
-                outgoingEdges[start] = [];
-            }
-            outgoingEdges[start].push(end !== END ? `${end}:inbox` : END);
+        return this.addEdge(key, END);
+    }
+    compile({ checkpointer, interruptBefore, interruptAfter, } = {}) {
+        // validate the graph
+        this.validate([
+            ...(Array.isArray(interruptBefore) ? interruptBefore : []),
+            ...(Array.isArray(interruptAfter) ? interruptAfter : []),
+        ]);
+        // create empty compiled graph
+        const compiled = new CompiledGraph({
+            builder: this,
+            checkpointer,
+            interruptAfter,
+            interruptBefore,
+            autoValidate: false,
+            nodes: {},
+            channels: {
+                [START]: new EphemeralValue(),
+                [END]: new EphemeralValue(),
+            },
+            inputs: START,
+            outputs: END,
+            streamChannels: [],
+            streamMode: "values",
         });
-        const nodes = {};
+        // attach nodes, edges and branches
         for (const [key, node] of Object.entries(this.nodes)) {
-            nodes[key] = Channel.subscribeTo(`${key}:inbox`)
-                .pipe(node)
-                .pipe(Channel.writeTo(key));
-        }
-        for (const key of Object.keys(this.nodes)) {
-            const outgoing = outgoingEdges[key];
-            const edgesKey = `${key}:edges`;
-            if (outgoing || this.branches[key]) {
-                nodes[edgesKey] = Channel.subscribeTo(key, {
-                    tags: ["langsmith:hidden"],
-                });
+            compiled.attachNode(key, node);
+        }
+        for (const [start, end] of this.edges) {
+            compiled.attachEdge(start, end);
+        }
+        for (const [start, branches] of Object.entries(this.branches)) {
+            for (const [name, branch] of Object.entries(branches)) {
+                compiled.attachBranch(start, name, branch);
             }
-            if (outgoing) {
-                nodes[edgesKey] = nodes[edgesKey].pipe(Channel.writeTo(...outgoing));
+        }
+        return compiled.validate();
+    }
+    validate(interrupt) {
+        // assemble sources
+        const allSources = new Set([...this.allEdges].map(([src, _]) => src));
+        for (const [start, branches] of Object.entries(this.branches)) {
+            allSources.add(start);
+            for (const branch of Object.values(branches)) {
+                if (branch.then) {
+                    if (branch.ends) {
+                        for (const end of Object.values(branch.ends)) {
+                            if (end !== END) {
+                                allSources.add(end);
+                            }
+                        }
+                    }
+                    else {
+                        for (const node of Object.keys(this.nodes)) {
+                            if (node !== start) {
+                                allSources.add(node);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        // validate sources
+        for (const node of Object.keys(this.nodes)) {
+            if (!allSources.has(node)) {
+                throw new Error(`Node \`${node}\` is a dead-end`);
             }
-            if (this.branches[key]) {
-                this.branches[key].forEach((branch) => {
-                    const runnableLambda = new RunnableLambda({
-                        func: (input) => branch.runnable(input),
-                    });
-                    nodes[edgesKey] = nodes[edgesKey].pipe(runnableLambda);
-                });
+        }
+        for (const source of allSources) {
+            if (source !== START && !(source in this.nodes)) {
+                throw new Error(`Found edge starting at unknown node \`${source}\``);
             }
         }
-        const hidden = Object.keys(this.nodes).map((node) => `${node}:inbox`);
-        if (!this.entryPoint) {
-            throw new Error("Entry point not set");
+        // assemble targets
+        const allTargets = new Set([...this.allEdges].map(([_, target]) => target));
+        for (const [start, branches] of Object.entries(this.branches)) {
+            for (const branch of Object.values(branches)) {
+                if (branch.then) {
+                    allTargets.add(branch.then);
+                }
+                if (branch.ends) {
+                    for (const end of Object.values(branch.ends)) {
+                        allTargets.add(end);
+                    }
+                }
+                else {
+                    allTargets.add(END);
+                    for (const node of Object.keys(this.nodes)) {
+                        if (node !== start && node !== branch.then) {
+                            allTargets.add(node);
+                        }
+                    }
+                }
+            }
         }
-        return new Pregel({
-            nodes,
-            input: `${this.entryPoint}:inbox`,
-            output: END,
-            hidden,
-            checkpointer,
-        });
-    }
-    validate() {
-        const allStarts = new Set([...this.edges].map(([src, _]) => src).concat(Object.keys(this.branches)));
+        // validate targets
         for (const node of Object.keys(this.nodes)) {
-            if (!allStarts.has(node)) {
-                throw new Error(`Node \`${node}\` is a dead-end`);
+            if (!allTargets.has(node)) {
+                throw new Error(`Node \`${node}\` is not reachable`);
+            }
+        }
+        for (const target of allTargets) {
+            if (target !== END && !(target in this.nodes)) {
+                throw new Error(`Found edge ending at unknown node \`${target}\``);
             }
         }
-        const allEndsAreDefined = Object.values(this.branches).every((branchList) => branchList.every((branch) => branch.ends));
-        if (allEndsAreDefined) {
-            const allEnds = new Set([...this.edges]
-                .map(([_, end]) => end)
-                .concat(...Object.values(this.branches).flatMap((branchList) => branchList.flatMap((branch) => Object.values(branch.ends ?? {}))))
-                .concat(this.entryPoint ? [this.entryPoint] : []));
-            for (const node of Object.keys(this.nodes)) {
-                if (!allEnds.has(node)) {
-                    throw new Error(`Node \`${node}\` is not reachable`);
+        // validate interrupts
+        if (interrupt) {
+            for (const node of interrupt) {
+                if (!(node in this.nodes)) {
+                    throw new Error(`Interrupt node \`${node}\` is not present`);
                 }
             }
         }
         this.compiled = true;
     }
 }
+export class CompiledGraph extends Pregel {
+    constructor({ builder, ...rest }) {
+        super(rest);
+        Object.defineProperty(this, "builder", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.builder = builder;
+    }
+    attachNode(key, node) {
+        this.channels[key] = new EphemeralValue();
+        this.nodes[key] = new PregelNode({
+            channels: [],
+            triggers: [],
+        })
+            .pipe(node)
+            .pipe(new ChannelWrite([{ channel: key, value: PASSTHROUGH }], [TAG_HIDDEN]));
+        this.streamChannels.push(key);
+    }
+    attachEdge(start, end) {
+        if (end === END) {
+            if (start === START) {
+                throw new Error("Cannot have an edge from START to END");
+            }
+            this.nodes[start].writers.push(new ChannelWrite([{ channel: END, value: PASSTHROUGH }], [TAG_HIDDEN]));
+        }
+        else {
+            this.nodes[end].triggers.push(start);
+            this.nodes[end].channels.push(start);
+        }
+    }
+    attachBranch(start, name, branch) {
+        // add hidden start node
+        if (start === START && this.nodes[START]) {
+            this.nodes[START] = Channel.subscribeTo(START, { tags: [TAG_HIDDEN] });
+        }
+        // attach branch writer
+        this.nodes[start].pipe(branch.compile((dests) => {
+            const channels = dests.map((dest) => dest === END ? END : `branch:${start}:${name}:${dest}`);
+            return new ChannelWrite(channels.map((channel) => ({ channel, value: PASSTHROUGH })), [TAG_HIDDEN]);
+        }));
+        // attach branch readers
+        const ends = branch.ends
+            ? Object.values(branch.ends)
+            : Object.keys(this.nodes);
+        for (const end of ends) {
+            if (end !== END) {
+                const channelName = `branch:${start}:${name}:${end}`;
+                this.channels[channelName] =
+                    new EphemeralValue();
+                this.nodes[end].triggers.push(channelName);
+                this.nodes[end].channels.push(channelName);
+            }
+        }
+    }
+}

package/dist/graph/index.cjs

@@ -1,11 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MessageGraph = exports.StateGraph = exports.START = exports.Graph = exports.END = void 0;
+exports.MessageGraph = exports.StateGraph = exports.Graph = exports.START = exports.END = void 0;
 var graph_js_1 = require("./graph.cjs");
 Object.defineProperty(exports, "END", { enumerable: true, get: function () { return graph_js_1.END; } });
+Object.defineProperty(exports, "START", { enumerable: true, get: function () { return graph_js_1.START; } });
 Object.defineProperty(exports, "Graph", { enumerable: true, get: function () { return graph_js_1.Graph; } });
 var state_js_1 = require("./state.cjs");
-Object.defineProperty(exports, "START", { enumerable: true, get: function () { return state_js_1.START; } });
 Object.defineProperty(exports, "StateGraph", { enumerable: true, get: function () { return state_js_1.StateGraph; } });
 var message_js_1 = require("./message.cjs");
 Object.defineProperty(exports, "MessageGraph", { enumerable: true, get: function () { return message_js_1.MessageGraph; } });

package/dist/graph/index.d.ts

@@ -1,3 +1,3 @@
-export { END, Graph } from "./graph.js";
-export { type StateGraphArgs, START, StateGraph } from "./state.js";
+export { END, START, Graph } from "./graph.js";
+export { type StateGraphArgs, StateGraph } from "./state.js";
 export { MessageGraph } from "./message.js";

package/dist/graph/index.js

@@ -1,3 +1,3 @@
-export { END, Graph } from "./graph.js";
-export { START, StateGraph } from "./state.js";
+export { END, START, Graph } from "./graph.js";
+export { StateGraph } from "./state.js";
 export { MessageGraph } from "./message.js";

package/dist/graph/message.cjs

@@ -11,9 +11,10 @@ class MessageGraph extends state_js_1.StateGraph {
     constructor() {
         super({
             channels: {
-                value: (a, b) => addMessages(a, b),
-                default: () => [],
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                __root__: {
+                    reducer: addMessages,
+                    default: () => [],
+                },
             },
         });
     }

package/dist/graph/message.d.ts

@@ -1,7 +1,10 @@
 import { BaseMessage } from "@langchain/core/messages";
 import { StateGraph } from "./state.js";
 type Messages = Array<BaseMessage> | BaseMessage;
-export declare class MessageGraph<T extends Messages> extends StateGraph<T> {
+export declare class MessageGraph extends StateGraph<BaseMessage[], Messages> {
     constructor();
 }
+export interface MessagesState {
+    messages: BaseMessage[];
+}
 export {};

package/dist/graph/message.js

@@ -8,9 +8,10 @@ export class MessageGraph extends StateGraph {
     constructor() {
         super({
             channels: {
-                value: (a, b) => addMessages(a, b),
-                default: () => [],
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                __root__: {
+                    reducer: addMessages,
+                    default: () => [],
+                },
             },
         });
     }