@langchain/langgraph 0.2.40 → 0.2.42

package/dist/pregel/runner.js

@@ -0,0 +1,271 @@
+import { Call } from "./types.js";
+import { CONFIG_KEY_SEND, CONFIG_KEY_SCRATCHPAD, PUSH, ERROR, INTERRUPT, RESUME, NO_WRITES, TAG_HIDDEN, RETURN, CONFIG_KEY_CALL, } from "../constants.js";
+import { isGraphBubbleUp, isGraphInterrupt, } from "../errors.js";
+import { _runWithRetry } from "./retry.js";
+/**
+ * Responsible for handling task execution on each tick of the {@link PregelLoop}.
+ */
+export class PregelRunner {
+    /**
+     * Construct a new PregelRunner, which executes tasks from the provided PregelLoop.
+     * @param loop - The PregelLoop that produces tasks for this runner to execute.
+     */
+    constructor({ loop, nodeFinished, }) {
+        Object.defineProperty(this, "nodeFinished", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "loop", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.loop = loop;
+        this.nodeFinished = nodeFinished;
+    }
+    /**
+     * Execute tasks from the current step of the PregelLoop.
+     *
+     * Note: this method does NOT call {@link PregelLoop}#tick. That must be handled externally.
+     * @param options - Options for the execution.
+     */
+    async tick(options = {}) {
+        const { timeout, signal, retryPolicy, onStepWrite } = options;
+        let graphInterrupt;
+        // Start task execution
+        const pendingTasks = Object.values(this.loop.tasks).filter((t) => t.writes.length === 0);
+        const taskStream = this._executeTasksWithRetry(pendingTasks, {
+            stepTimeout: timeout,
+            signal,
+            retryPolicy,
+        });
+        for await (const { task, error } of taskStream) {
+            graphInterrupt = this._commit(task, error) ?? graphInterrupt;
+        }
+        onStepWrite?.(this.loop.step, Object.values(this.loop.tasks)
+            .map((task) => task.writes)
+            .flat());
+        if (graphInterrupt) {
+            throw graphInterrupt;
+        }
+    }
+    /**
+     * Concurrently executes tasks with the requested retry policy, yielding a {@link SettledPregelTask} for each task as it completes.
+     * @param tasks - The tasks to execute.
+     * @param options - Options for the execution.
+     */
+    async *_executeTasksWithRetry(tasks, options) {
+        const { stepTimeout, retryPolicy } = options ?? {};
+        let signal = options?.signal;
+        const promiseAddedSymbol = Symbol.for("promiseAdded");
+        let addedPromiseSignal;
+        let addedPromiseWait;
+        function waitHandler(resolve) {
+            addedPromiseSignal = () => {
+                addedPromiseWait = new Promise(waitHandler);
+                resolve(promiseAddedSymbol);
+            };
+        }
+        addedPromiseWait = new Promise(waitHandler);
+        const executingTasksMap = {};
+        const writer = (task, writes, { calls } = {}) => {
+            if (writes.every(([channel]) => channel !== PUSH)) {
+                return task.config?.configurable?.[CONFIG_KEY_SEND]?.(writes) ?? [];
+            }
+            // Schedule PUSH tasks, collect promises
+            const scratchpad = task.config?.configurable?.[CONFIG_KEY_SCRATCHPAD];
+            const rtn = {};
+            for (const [idx, write] of writes.entries()) {
+                const [channel] = write;
+                if (channel !== PUSH) {
+                    continue;
+                }
+                const wcall = calls?.[idx];
+                const cnt = scratchpad.callCounter;
+                scratchpad.callCounter += 1;
+                if (wcall == null) {
+                    throw new Error("BUG: No call found");
+                }
+                const nextTask = this.loop.acceptPush(task, cnt, wcall);
+                if (!nextTask) {
+                    continue;
+                }
+                // Check if this task is already running
+                const existingPromise = executingTasksMap[nextTask.id];
+                if (existingPromise !== undefined) {
+                    // If the parent task was retried, the next task might already be running
+                    rtn[idx] = existingPromise;
+                }
+                else if (nextTask.writes.length > 0) {
+                    // If it already ran, return the result
+                    const returns = nextTask.writes.filter(([c]) => c === RETURN);
+                    const errors = nextTask.writes.filter(([c]) => c === ERROR);
+                    if (returns.length > 0) {
+                        // Task completed successfully
+                        if (returns.length === 1) {
+                            rtn[idx] = Promise.resolve(returns[0][1]);
+                        }
+                        else {
+                            // should be unreachable
+                            throw new Error(`BUG: multiple returns found for task ${nextTask.name}__${nextTask.id}`);
+                        }
+                    }
+                    else if (errors.length > 0) {
+                        if (errors.length === 1) {
+                            const errorValue = errors[0][1];
+                            // Task failed
+                            const error = 
+                            // eslint-disable-next-line no-instanceof/no-instanceof
+                            errorValue instanceof Error
+                                ? errorValue
+                                : new Error(String(errorValue));
+                            rtn[idx] = Promise.reject(error);
+                        }
+                        else {
+                            // the only way this should happen is if the task executes multiple times and writes aren't cleared
+                            throw new Error(`BUG: multiple errors found for task ${nextTask.name}__${nextTask.id}`);
+                        }
+                    }
+                }
+                else {
+                    // Schedule the next task with retry
+                    const prom = _runWithRetry(nextTask, retryPolicy, {
+                        [CONFIG_KEY_SEND]: writer.bind(this, nextTask),
+                        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+                        [CONFIG_KEY_CALL]: call.bind(this, nextTask),
+                    });
+                    executingTasksMap[nextTask.id] = prom;
+                    addedPromiseSignal();
+                    rtn[idx] = prom.then(({ result, error }) => {
+                        if (error) {
+                            return Promise.reject(error);
+                        }
+                        return result;
+                    });
+                }
+            }
+            return Object.values(rtn);
+        };
+        const call = (task, func, name, input, options = {}) => {
+            const result = writer(task, [[PUSH, null]], {
+                calls: [
+                    new Call({
+                        func,
+                        name,
+                        input,
+                        retry: options.retry,
+                        callbacks: options.callbacks,
+                    }),
+                ],
+            });
+            // eslint-disable-next-line no-instanceof/no-instanceof
+            if (result !== undefined) {
+                if (result.length === 1) {
+                    return result[0];
+                }
+                return Promise.all(result);
+            }
+            return Promise.resolve();
+        };
+        if (stepTimeout && signal) {
+            if ("any" in AbortSignal) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                signal = AbortSignal.any([
+                    signal,
+                    AbortSignal.timeout(stepTimeout),
+                ]);
+            }
+        }
+        else if (stepTimeout) {
+            signal = AbortSignal.timeout(stepTimeout);
+        }
+        if (signal?.aborted) {
+            // note: don't use throwIfAborted here because it throws a DOMException,
+            // which isn't consistent with how we throw on abort below.
+            throw new Error("Abort");
+        }
+        // Start tasks
+        Object.assign(executingTasksMap, Object.fromEntries(tasks.map((pregelTask) => {
+            return [
+                pregelTask.id,
+                _runWithRetry(pregelTask, retryPolicy, {
+                    [CONFIG_KEY_SEND]: writer?.bind(this, pregelTask),
+                    [CONFIG_KEY_CALL]: call?.bind(this, pregelTask),
+                }).catch((error) => {
+                    return { task: pregelTask, error };
+                }),
+            ];
+        })));
+        let listener;
+        const signalPromise = new Promise((_resolve, reject) => {
+            listener = () => reject(new Error("Abort"));
+            signal?.addEventListener("abort", listener);
+        }).finally(() => signal?.removeEventListener("abort", listener));
+        while (Object.keys(executingTasksMap).length > 0) {
+            const settledTask = await Promise.race([
+                ...Object.values(executingTasksMap),
+                signalPromise,
+                addedPromiseWait,
+            ]);
+            if (settledTask === promiseAddedSymbol) {
+                continue;
+            }
+            yield settledTask;
+            delete executingTasksMap[settledTask.task.id];
+        }
+    }
+    /**
+     * Determines what writes to apply based on whether the task completed successfully, and what type of error occurred.
+     *
+     * Throws an error if the error is a {@link GraphBubbleUp} error and {@link PregelLoop}#isNested is true.
+     *
+     * Note that in the case of a {@link GraphBubbleUp} error that is not a {@link GraphInterrupt}, like a {@link Command}, this method does not apply any writes.
+     *
+     * @param task - The task to commit.
+     * @param error - The error that occurred, if any.
+     * @returns The {@link GraphInterrupt} that occurred, if the user's code threw one.
+     */
+    _commit(task, error) {
+        let graphInterrupt;
+        if (error !== undefined) {
+            if (isGraphBubbleUp(error)) {
+                if (this.loop.isNested) {
+                    throw error;
+                }
+                if (isGraphInterrupt(error)) {
+                    graphInterrupt = error;
+                    if (error.interrupts.length) {
+                        const interrupts = error.interrupts.map((interrupt) => [INTERRUPT, interrupt]);
+                        const resumes = task.writes.filter((w) => w[0] === RESUME);
+                        if (resumes.length) {
+                            interrupts.push(...resumes);
+                        }
+                        this.loop.putWrites(task.id, interrupts);
+                    }
+                }
+            }
+            else {
+                this.loop.putWrites(task.id, [
+                    [ERROR, { message: error.message, name: error.name }],
+                ]);
+                throw error;
+            }
+        }
+        else {
+            if (this.nodeFinished &&
+                (task.config?.tags == null || !task.config.tags.includes(TAG_HIDDEN))) {
+                this.nodeFinished(String(task.name));
+            }
+            if (task.writes.length === 0) {
+                // Add no writes marker
+                task.writes.push([NO_WRITES, null]);
+            }
+            // Save task writes to checkpointer
+            this.loop.putWrites(task.id, task.writes);
+        }
+        return graphInterrupt;
+    }
+}

package/dist/pregel/stream.cjs

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IterableReadableWritableStream = void 0;
+const stream_1 = require("@langchain/core/utils/stream");
+class IterableReadableWritableStream extends stream_1.IterableReadableStream {
+    get closed() {
+        return this._closed;
+    }
+    constructor(params) {
+        let streamControllerPromiseResolver;
+        const streamControllerPromise = new Promise((resolve) => {
+            streamControllerPromiseResolver = resolve;
+        });
+        super({
+            start: (controller) => {
+                streamControllerPromiseResolver(controller);
+            },
+        });
+        Object.defineProperty(this, "modes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "controller", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "passthroughFn", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_closed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        // .start() will always be called before the stream can be interacted
+        // with anyway
+        void streamControllerPromise.then((controller) => {
+            this.controller = controller;
+        });
+        this.passthroughFn = params.passthroughFn;
+        this.modes = params.modes;
+    }
+    push(chunk) {
+        this.passthroughFn?.(chunk);
+        this.controller.enqueue(chunk);
+    }
+    close() {
+        try {
+            this.controller.close();
+        }
+        catch (e) {
+            // pass
+        }
+        finally {
+            this._closed = true;
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    error(e) {
+        this.controller.error(e);
+    }
+}
+exports.IterableReadableWritableStream = IterableReadableWritableStream;

package/dist/pregel/stream.d.ts

@@ -0,0 +1,17 @@
+import { IterableReadableStream } from "@langchain/core/utils/stream";
+import { StreamMode } from "./types.js";
+export type StreamChunk = [string[], StreamMode, unknown];
+export declare class IterableReadableWritableStream extends IterableReadableStream<StreamChunk> {
+    modes: Set<StreamMode>;
+    private controller;
+    private passthroughFn?;
+    private _closed;
+    get closed(): boolean;
+    constructor(params: {
+        passthroughFn?: (chunk: StreamChunk) => void;
+        modes: Set<StreamMode>;
+    });
+    push(chunk: StreamChunk): void;
+    close(): void;
+    error(e: any): void;
+}

package/dist/pregel/stream.js

@@ -0,0 +1,67 @@
+import { IterableReadableStream } from "@langchain/core/utils/stream";
+export class IterableReadableWritableStream extends IterableReadableStream {
+    get closed() {
+        return this._closed;
+    }
+    constructor(params) {
+        let streamControllerPromiseResolver;
+        const streamControllerPromise = new Promise((resolve) => {
+            streamControllerPromiseResolver = resolve;
+        });
+        super({
+            start: (controller) => {
+                streamControllerPromiseResolver(controller);
+            },
+        });
+        Object.defineProperty(this, "modes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "controller", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "passthroughFn", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_closed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        // .start() will always be called before the stream can be interacted
+        // with anyway
+        void streamControllerPromise.then((controller) => {
+            this.controller = controller;
+        });
+        this.passthroughFn = params.passthroughFn;
+        this.modes = params.modes;
+    }
+    push(chunk) {
+        this.passthroughFn?.(chunk);
+        this.controller.enqueue(chunk);
+    }
+    close() {
+        try {
+            this.controller.close();
+        }
+        catch (e) {
+            // pass
+        }
+        finally {
+            this._closed = true;
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    error(e) {
+        this.controller.error(e);
+    }
+}

package/dist/pregel/types.cjs

@@ -1,2 +1,56 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCall = exports.Call = void 0;
+class Call {
+    constructor({ func, name, input, retry, callbacks }) {
+        Object.defineProperty(this, "func", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "input", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "retry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "callbacks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "__lg_type", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "call"
+        });
+        this.func = func;
+        this.name = name;
+        this.input = input;
+        this.retry = retry;
+        this.callbacks = callbacks;
+    }
+}
+exports.Call = Call;
+function isCall(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "__lg_type" in value &&
+        value.__lg_type === "call");
+}
+exports.isCall = isCall;

package/dist/pregel/types.d.ts

@@ -8,6 +8,9 @@ import { RetryPolicy } from "./utils/index.js";
 import { Interrupt } from "../constants.js";
 import { type ManagedValueSpec } from "../managed/base.js";
 import { LangGraphRunnableConfig } from "./runnable_types.js";
+/**
+ * Selects the type of output you'll receive when streaming from the graph. See [Streaming](/langgraphjs/how-tos/#streaming) for more details.
+ */
 export type StreamMode = "values" | "updates" | "debug" | "messages" | "custom";
 export type PregelInputType = any;
 export type PregelOutputType = any;
@@ -15,8 +18,12 @@ export type PregelOutputType = any;
  * Config for executing the graph.
  */
 export interface PregelOptions<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel | ManagedValueSpec>, ConfigurableFieldType extends Record<string, any> = Record<string, any>> extends RunnableConfig<ConfigurableFieldType> {
-    /** The stream mode for the graph run. Default is ["values"]. */
+    /**
+     * The stream mode for the graph run. See [Streaming](/langgraphjs/how-tos/#streaming) for more details.
+     * @default ["values"]
+     */
     streamMode?: StreamMode | StreamMode[];
+    /** The input keys to retrieve from the checkpoint on resume. You generally don't need to set this. */
     inputKeys?: keyof Cc | Array<keyof Cc>;
     /** The output keys to retrieve from the graph run. */
     outputKeys?: keyof Cc | Array<keyof Cc>;
@@ -54,27 +61,57 @@ export interface PregelInterface<Nn extends StrRecord<string, PregelNode>, Cc ex
     stream(input: PregelInputType, options?: Partial<PregelOptions<Nn, Cc, ConfigurableFieldType>>): Promise<IterableReadableStream<PregelOutputType>>;
     invoke(input: PregelInputType, options?: Partial<PregelOptions<Nn, Cc, ConfigurableFieldType>>): Promise<PregelOutputType>;
 }
+/**
+ * Parameters for creating a Pregel graph.
+ * @internal
+ */
 export type PregelParams<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel | ManagedValueSpec>> = {
+    /**
+     * The name of the graph. @see {@link Runnable.name}
+     */
+    name?: string;
+    /**
+     * The nodes in the graph.
+     */
     nodes: Nn;
+    /**
+     * The channels in the graph.
+     */
     channels: Cc;
     /**
+     * Whether to validate the graph.
+     *
      * @default true
      */
     autoValidate?: boolean;
     /**
-     * @default "values"
+     * The stream mode for the graph run. See [Streaming](/langgraphjs/how-tos/#streaming) for more details.
+     *
+     * @default ["values"]
      */
     streamMode?: StreamMode | StreamMode[];
+    /**
+     * The input channels for the graph run.
+     */
     inputChannels: keyof Cc | Array<keyof Cc>;
+    /**
+     * The output channels for the graph run.
+     */
     outputChannels: keyof Cc | Array<keyof Cc>;
     /**
+     * After processing one of the nodes named in this list, the graph will be interrupted and a resume {@link Command} must be provided to proceed with the execution of this thread.
      * @default []
      */
     interruptAfter?: Array<keyof Nn> | All;
     /**
+     * Before processing one of the nodes named in this list, the graph will be interrupted and a resume {@link Command} must be provided to proceed with the execution of this thread.
      * @default []
      */
     interruptBefore?: Array<keyof Nn> | All;
+    /**
+     * The channels to stream from the graph run.
+     * @default []
+     */
     streamChannels?: keyof Cc | Array<keyof Cc>;
     /**
      * @default undefined
@@ -84,8 +121,17 @@ export type PregelParams<Nn extends StrRecord<string, PregelNode>, Cc extends St
      * @default false
      */
     debug?: boolean;
+    /**
+     * The {@link BaseCheckpointSaver | checkpointer} to use for the graph run.
+     */
     checkpointer?: BaseCheckpointSaver | false;
+    /**
+     * The default retry policy for this graph. For defaults, see {@link RetryPolicy}.
+     */
     retryPolicy?: RetryPolicy;
+    /**
+     * The configuration for the graph run.
+     */
     config?: LangGraphRunnableConfig;
     /**
      * Memory store to use for SharedValues.
@@ -98,7 +144,7 @@ export interface PregelTaskDescription {
     readonly error?: unknown;
     readonly interrupts: Interrupt[];
     readonly state?: LangGraphRunnableConfig | StateSnapshot;
-    readonly path?: [string, ...(string | number)[]];
+    readonly path?: TaskPath;
 }
 export interface PregelExecutableTask<N extends PropertyKey, C extends PropertyKey> {
     readonly name: N;
@@ -109,7 +155,7 @@ export interface PregelExecutableTask<N extends PropertyKey, C extends PropertyK
     readonly triggers: Array<string>;
     readonly retry_policy?: RetryPolicy;
     readonly id: string;
-    readonly path?: [string, ...(string | number)[]];
+    readonly path?: TaskPath;
     readonly subgraphs?: Runnable[];
     readonly writers: Runnable[];
 }
@@ -144,9 +190,35 @@ export interface StateSnapshot {
      */
     readonly tasks: PregelTaskDescription[];
 }
-export type PregelScratchpad<Resume> = {
+export type PregelScratchpad<Resume = unknown> = {
+    /** Counter for tracking call invocations */
+    callCounter: number;
+    /** Counter for tracking interrupts */
     interruptCounter: number;
-    usedNullResume: boolean;
+    /** List of resume values */
     resume: Resume[];
+    /** Single resume value for null task ID */
+    nullResume: Resume;
+};
+export type CallOptions = {
+    func: (...args: unknown[]) => unknown | Promise<unknown>;
+    name: string;
+    input: unknown;
+    retry?: RetryPolicy;
+    callbacks?: unknown;
 };
+export declare class Call {
+    func: (...args: unknown[]) => unknown | Promise<unknown>;
+    name: string;
+    input: unknown;
+    retry?: RetryPolicy;
+    callbacks?: unknown;
+    readonly __lg_type = "call";
+    constructor({ func, name, input, retry, callbacks }: CallOptions);
+}
+export declare function isCall(value: unknown): value is Call;
+export type SimpleTaskPath = [string, string | number];
+export type VariadicTaskPath = [string, ...(string | number)[]];
+export type CallTaskPath = [string, ...(string | number)[], Call] | [string, TaskPath, ...(string | number)[], Call];
+export type TaskPath = SimpleTaskPath | CallTaskPath | VariadicTaskPath;
 export {};

package/dist/pregel/types.js

@@ -1 +1,51 @@
-export {};
+export class Call {
+    constructor({ func, name, input, retry, callbacks }) {
+        Object.defineProperty(this, "func", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "input", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "retry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "callbacks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "__lg_type", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "call"
+        });
+        this.func = func;
+        this.name = name;
+        this.input = input;
+        this.retry = retry;
+        this.callbacks = callbacks;
+    }
+}
+export function isCall(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "__lg_type" in value &&
+        value.__lg_type === "call");
+}