@langchain/langgraph 0.2.3 → 0.2.5-rc.0

package/dist/pregel/loop.js

@@ -8,6 +8,7 @@ import { mapInput, mapOutputUpdates, mapOutputValues } from "./io.js";
 import { EmptyInputError, GraphInterrupt } from "../errors.js";
 import { getNewChannelVersions } from "./utils.js";
 import { mapDebugTasks, mapDebugCheckpoint, mapDebugTaskResults, } from "./debug.js";
+import { AsyncBatchedStore } from "../store/batch.js";
 const INPUT_DONE = Symbol.for("INPUT_DONE");
 const INPUT_RESUMING = Symbol.for("INPUT_RESUMING");
 const DEFAULT_LOOP_LIMIT = 25;
@@ -44,6 +45,12 @@ export class PregelLoop {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "managed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "checkpoint", {
             enumerable: true,
             configurable: true,
@@ -148,6 +155,12 @@ export class PregelLoop {
             writable: true,
             value: Promise.resolve()
         });
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.input = params.input;
         this.config = params.config;
         this.checkpointer = params.checkpointer;
@@ -164,6 +177,7 @@ export class PregelLoop {
         this.checkpointMetadata = params.checkpointMetadata;
         this.checkpointPreviousVersions = params.checkpointPreviousVersions;
         this.channels = params.channels;
+        this.managed = params.managed;
         this.checkpointPendingWrites = params.checkpointPendingWrites;
         this.step = params.step;
         this.stop = params.stop;
@@ -172,6 +186,7 @@ export class PregelLoop {
         this.streamKeys = params.streamKeys;
         this.nodes = params.nodes;
         this.skipDoneTasks = this.config.configurable?.checkpoint_id === undefined;
+        this.store = params.store;
     }
     static async initialize(params) {
         const saved = (await params.checkpointer?.getTuple(params.config)) ?? {
@@ -199,6 +214,13 @@ export class PregelLoop {
         const step = (checkpointMetadata.step ?? 0) + 1;
         const stop = step + (params.config.recursionLimit ?? DEFAULT_LOOP_LIMIT) + 1;
         const checkpointPreviousVersions = { ...checkpoint.channel_versions };
+        const store = params.store
+            ? new AsyncBatchedStore(params.store)
+            : undefined;
+        if (store) {
+            // Start the store. This is a batch store, so it will run continuously
+            store.start();
+        }
         return new PregelLoop({
             input: params.input,
             config: params.config,
@@ -207,6 +229,7 @@ export class PregelLoop {
             checkpointMetadata,
             checkpointConfig,
             channels,
+            managed: params.managed,
             step,
             stop,
             checkpointPreviousVersions,
@@ -214,6 +237,7 @@ export class PregelLoop {
             outputKeys: params.outputKeys ?? [],
             streamKeys: params.streamKeys ?? [],
             nodes: params.nodes,
+            store,
         });
     }
     _checkpointerPutAfterPrevious(input) {
@@ -222,6 +246,13 @@ export class PregelLoop {
         });
         this.checkpointerPromises.push(this._checkpointerChainedPromise);
     }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async updateManagedValues(key, values) {
+        const mv = this.managed.get(key);
+        if (mv && "update" in mv && typeof mv.update === "function") {
+            await mv.update(values);
+        }
+    }
     /**
      * Put writes for a task, to be read by the next tick.
      * @param taskId
@@ -255,6 +286,9 @@ export class PregelLoop {
      * @param params
      */
     async tick(params) {
+        if (this.store && !this.store.isRunning) {
+            this.store?.start();
+        }
         const { inputKeys = [], interruptAfter = [], interruptBefore = [], manager, } = params;
         if (this.status !== "pending") {
             throw new Error(`Cannot tick when status is no longer "pending". Current status: "${this.status}"`);
@@ -265,7 +299,10 @@ export class PregelLoop {
         else if (this.tasks.every((task) => task.writes.length > 0)) {
             const writes = this.tasks.flatMap((t) => t.writes);
             // All tasks have finished
-            _applyWrites(this.checkpoint, this.channels, this.tasks, this.checkpointerGetNextVersion);
+            const myWrites = _applyWrites(this.checkpoint, this.channels, this.tasks, this.checkpointerGetNextVersion);
+            for (const [key, values] of Object.entries(myWrites)) {
+                await this.updateManagedValues(key, values);
+            }
             // produce values output
             const valuesOutput = await gatherIterator(prefixGenerator(mapOutputValues(this.outputKeys, writes, this.channels), "values"));
             this.stream.push(...valuesOutput);
@@ -293,7 +330,7 @@ export class PregelLoop {
             this.status = "out_of_steps";
             return false;
         }
-        const nextTasks = _prepareNextTasks(this.checkpoint, this.nodes, this.channels, this.config, true, {
+        const nextTasks = _prepareNextTasks(this.checkpoint, this.nodes, this.channels, this.managed, this.config, true, {
             step: this.step,
             checkpointer: this.checkpointer,
             isResuming: this.input === INPUT_RESUMING,
@@ -371,7 +408,7 @@ export class PregelLoop {
             if (inputWrites.length === 0) {
                 throw new EmptyInputError(`Received no input writes for ${JSON.stringify(inputKeys, null, 2)}`);
             }
-            const discardTasks = _prepareNextTasks(this.checkpoint, this.nodes, this.channels, this.config, true, { step: this.step });
+            const discardTasks = _prepareNextTasks(this.checkpoint, this.nodes, this.channels, this.managed, this.config, true, { step: this.step });
             _applyWrites(this.checkpoint, this.channels, discardTasks.concat([
                 {
                     name: INPUT,

package/dist/pregel/types.d.ts

@@ -4,6 +4,8 @@ import type { BaseChannel } from "../channels/base.js";
 import type { PregelNode } from "./read.js";
 import { RetryPolicy } from "./utils.js";
 import { Interrupt } from "../constants.js";
+import { BaseStore } from "../store/base.js";
+import { type ManagedValueSpec } from "../managed/base.js";
 export type StreamMode = "values" | "updates" | "debug";
 /**
  * Construct a type with a set of properties K of type T
@@ -11,7 +13,7 @@ export type StreamMode = "values" | "updates" | "debug";
 type StrRecord<K extends string, T> = {
     [P in K]: T;
 };
-export interface PregelInterface<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel>> {
+export interface PregelInterface<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel | ManagedValueSpec>> {
     nodes: Nn;
     channels: Cc;
     /**
@@ -24,6 +26,7 @@ export interface PregelInterface<Nn extends StrRecord<string, PregelNode>, Cc ex
     streamMode?: StreamMode | StreamMode[];
     inputChannels: keyof Cc | Array<keyof Cc>;
     outputChannels: keyof Cc | Array<keyof Cc>;
+    configKeys?: string[];
     /**
      * @default []
      */
@@ -44,8 +47,12 @@ export interface PregelInterface<Nn extends StrRecord<string, PregelNode>, Cc ex
     debug?: boolean;
     checkpointer?: BaseCheckpointSaver;
     retryPolicy?: RetryPolicy;
+    /**
+     * Memory store to use for SharedValues.
+     */
+    store?: BaseStore;
 }
-export type PregelParams<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel>> = Omit<PregelInterface<Nn, Cc>, "streamChannelsAsIs">;
+export type PregelParams<Nn extends StrRecord<string, PregelNode>, Cc extends StrRecord<string, BaseChannel | ManagedValueSpec>> = Omit<PregelInterface<Nn, Cc>, "streamChannelsAsIs">;
 export interface PregelTaskDescription {
     readonly id: string;
     readonly name: string;

package/dist/pregel/validate.d.ts

@@ -1,10 +1,11 @@
 import { All } from "@langchain/langgraph-checkpoint";
 import { BaseChannel } from "../channels/index.js";
 import { PregelNode } from "./read.js";
+import { type ManagedValueSpec } from "../managed/base.js";
 export declare class GraphValidationError extends Error {
     constructor(message?: string);
 }
-export declare function validateGraph<Nn extends Record<string, PregelNode>, Cc extends Record<string, BaseChannel>>({ nodes, channels, inputChannels, outputChannels, streamChannels, interruptAfterNodes, interruptBeforeNodes, }: {
+export declare function validateGraph<Nn extends Record<string, PregelNode>, Cc extends Record<string, BaseChannel | ManagedValueSpec>>({ nodes, channels, inputChannels, outputChannels, streamChannels, interruptAfterNodes, interruptBeforeNodes, }: {
     nodes: Nn;
     channels: Cc;
     inputChannels: keyof Cc | Array<keyof Cc>;
@@ -13,4 +14,4 @@ export declare function validateGraph<Nn extends Record<string, PregelNode>, Cc
     interruptAfterNodes?: Array<keyof Nn> | All;
     interruptBeforeNodes?: Array<keyof Nn> | All;
 }): void;
-export declare function validateKeys<Cc extends Record<string, BaseChannel>>(keys: keyof Cc | Array<keyof Cc>, channels: Cc): void;
+export declare function validateKeys<Cc extends Record<string, BaseChannel | ManagedValueSpec>>(keys: keyof Cc | Array<keyof Cc>, channels: Cc): void;

package/dist/store/base.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseStore = void 0;
+class BaseStore {
+    stop() {
+        // no-op if not implemented.
+    }
+    start() {
+        // no-op if not implemented.
+    }
+}
+exports.BaseStore = BaseStore;

package/dist/store/base.d.ts

@@ -0,0 +1,7 @@
+export type Values = Record<string, any>;
+export declare abstract class BaseStore {
+    abstract list(prefixes: string[]): Promise<Record<string, Record<string, Values>>>;
+    abstract put(writes: Array<[string, string, Values | null]>): Promise<void>;
+    stop(): void;
+    start(): void;
+}

package/dist/store/base.js

@@ -0,0 +1,8 @@
+export class BaseStore {
+    stop() {
+        // no-op if not implemented.
+    }
+    start() {
+        // no-op if not implemented.
+    }
+}

package/dist/store/batch.cjs

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncBatchedStore = void 0;
+const base_js_1 = require("./base.cjs");
+/**
+ * AsyncBatchedStore extends BaseStore to provide batched operations for list and put methods.
+ * It queues operations and processes them in batches for improved efficiency. This store is
+ * designed to run for the full duration of the process, or until `stop()` is called.
+ */
+class AsyncBatchedStore extends base_js_1.BaseStore {
+    get isRunning() {
+        return this.running;
+    }
+    constructor(store) {
+        super();
+        /**
+         * The store to batch operations for.
+         * @type {BaseStore}
+         */
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * A queue of operations to be processed in batch.
+         * @type {QueueItem[]}
+         */
+        Object.defineProperty(this, "queue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        /**
+         * Whether or not the batched processing is currently running.
+         * @type {boolean}
+         * @default {false}
+         */
+        Object.defineProperty(this, "running", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        this.store = store;
+    }
+    /**
+     * Queues a list operation to be processed in batch.
+     * @param {string[]} prefixes An array of prefixes to list.
+     * @returns {Promise<Record<string, Record<string, Values>>>} A promise that resolves with the list results.
+     */
+    async list(prefixes) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({ resolve, reject, op: { prefixes } });
+        });
+    }
+    /**
+     * Queues a put operation to be processed in batch.
+     * @param {Array<[string, string, Values | null]>} writes An array of write operations to be performed.
+     * @returns {Promise<void>} A promise that resolves when the put operation is complete.
+     */
+    async put(writes) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({ resolve, reject, op: { writes } });
+        });
+    }
+    /**
+     * Start running the batched processing of operations.
+     * This process will run continuously until the store is stopped,
+     * which can be done by calling the `stop()` method.
+     */
+    start() {
+        this.running = true;
+        void this.processBatchQueue();
+    }
+    /**
+     * Stops the batched processing of operations.
+     */
+    stop() {
+        this.running = false;
+    }
+    /**
+     * Runs the task that processes queued operations in batches.
+     * This method runs continuously until the store is stopped,
+     * or the process is terminated.
+     * @returns {Promise<void>} A promise that resolves when the task is complete.
+     */
+    async processBatchQueue() {
+        while (this.running) {
+            await new Promise((resolve) => {
+                setTimeout(resolve, 0);
+            });
+            if (this.queue.length === 0)
+                continue;
+            const taken = this.queue.splice(0);
+            const lists = taken.filter((item) => "prefixes" in item.op);
+            if (lists.length > 0) {
+                try {
+                    const allPrefixes = lists.flatMap((item) => item.op.prefixes);
+                    const results = await this.store.list(allPrefixes);
+                    lists.forEach((item) => {
+                        const { prefixes } = item.op;
+                        item.resolve(Object.fromEntries(prefixes.map((p) => [p, results[p] || {}])));
+                    });
+                }
+                catch (e) {
+                    lists.forEach((item) => item.reject(e));
+                }
+            }
+            const puts = taken.filter((item) => "writes" in item.op);
+            if (puts.length > 0) {
+                try {
+                    const allWrites = puts.flatMap((item) => item.op.writes);
+                    await this.store.put(allWrites);
+                    puts.forEach((item) => item.resolve());
+                }
+                catch (e) {
+                    puts.forEach((item) => item.reject(e));
+                }
+            }
+        }
+    }
+}
+exports.AsyncBatchedStore = AsyncBatchedStore;

package/dist/store/batch.d.ts

@@ -0,0 +1,55 @@
+import { BaseStore, type Values } from "./base.js";
+/**
+ * AsyncBatchedStore extends BaseStore to provide batched operations for list and put methods.
+ * It queues operations and processes them in batches for improved efficiency. This store is
+ * designed to run for the full duration of the process, or until `stop()` is called.
+ */
+export declare class AsyncBatchedStore extends BaseStore {
+    /**
+     * The store to batch operations for.
+     * @type {BaseStore}
+     */
+    private store;
+    /**
+     * A queue of operations to be processed in batch.
+     * @type {QueueItem[]}
+     */
+    private queue;
+    /**
+     * Whether or not the batched processing is currently running.
+     * @type {boolean}
+     * @default {false}
+     */
+    private running;
+    get isRunning(): boolean;
+    constructor(store: BaseStore);
+    /**
+     * Queues a list operation to be processed in batch.
+     * @param {string[]} prefixes An array of prefixes to list.
+     * @returns {Promise<Record<string, Record<string, Values>>>} A promise that resolves with the list results.
+     */
+    list(prefixes: string[]): Promise<Record<string, Record<string, Values>>>;
+    /**
+     * Queues a put operation to be processed in batch.
+     * @param {Array<[string, string, Values | null]>} writes An array of write operations to be performed.
+     * @returns {Promise<void>} A promise that resolves when the put operation is complete.
+     */
+    put(writes: Array<[string, string, Values | null]>): Promise<void>;
+    /**
+     * Start running the batched processing of operations.
+     * This process will run continuously until the store is stopped,
+     * which can be done by calling the `stop()` method.
+     */
+    start(): void;
+    /**
+     * Stops the batched processing of operations.
+     */
+    stop(): void;
+    /**
+     * Runs the task that processes queued operations in batches.
+     * This method runs continuously until the store is stopped,
+     * or the process is terminated.
+     * @returns {Promise<void>} A promise that resolves when the task is complete.
+     */
+    private processBatchQueue;
+}

package/dist/store/batch.js

@@ -0,0 +1,122 @@
+import { BaseStore } from "./base.js";
+/**
+ * AsyncBatchedStore extends BaseStore to provide batched operations for list and put methods.
+ * It queues operations and processes them in batches for improved efficiency. This store is
+ * designed to run for the full duration of the process, or until `stop()` is called.
+ */
+export class AsyncBatchedStore extends BaseStore {
+    get isRunning() {
+        return this.running;
+    }
+    constructor(store) {
+        super();
+        /**
+         * The store to batch operations for.
+         * @type {BaseStore}
+         */
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * A queue of operations to be processed in batch.
+         * @type {QueueItem[]}
+         */
+        Object.defineProperty(this, "queue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        /**
+         * Whether or not the batched processing is currently running.
+         * @type {boolean}
+         * @default {false}
+         */
+        Object.defineProperty(this, "running", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        this.store = store;
+    }
+    /**
+     * Queues a list operation to be processed in batch.
+     * @param {string[]} prefixes An array of prefixes to list.
+     * @returns {Promise<Record<string, Record<string, Values>>>} A promise that resolves with the list results.
+     */
+    async list(prefixes) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({ resolve, reject, op: { prefixes } });
+        });
+    }
+    /**
+     * Queues a put operation to be processed in batch.
+     * @param {Array<[string, string, Values | null]>} writes An array of write operations to be performed.
+     * @returns {Promise<void>} A promise that resolves when the put operation is complete.
+     */
+    async put(writes) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({ resolve, reject, op: { writes } });
+        });
+    }
+    /**
+     * Start running the batched processing of operations.
+     * This process will run continuously until the store is stopped,
+     * which can be done by calling the `stop()` method.
+     */
+    start() {
+        this.running = true;
+        void this.processBatchQueue();
+    }
+    /**
+     * Stops the batched processing of operations.
+     */
+    stop() {
+        this.running = false;
+    }
+    /**
+     * Runs the task that processes queued operations in batches.
+     * This method runs continuously until the store is stopped,
+     * or the process is terminated.
+     * @returns {Promise<void>} A promise that resolves when the task is complete.
+     */
+    async processBatchQueue() {
+        while (this.running) {
+            await new Promise((resolve) => {
+                setTimeout(resolve, 0);
+            });
+            if (this.queue.length === 0)
+                continue;
+            const taken = this.queue.splice(0);
+            const lists = taken.filter((item) => "prefixes" in item.op);
+            if (lists.length > 0) {
+                try {
+                    const allPrefixes = lists.flatMap((item) => item.op.prefixes);
+                    const results = await this.store.list(allPrefixes);
+                    lists.forEach((item) => {
+                        const { prefixes } = item.op;
+                        item.resolve(Object.fromEntries(prefixes.map((p) => [p, results[p] || {}])));
+                    });
+                }
+                catch (e) {
+                    lists.forEach((item) => item.reject(e));
+                }
+            }
+            const puts = taken.filter((item) => "writes" in item.op);
+            if (puts.length > 0) {
+                try {
+                    const allWrites = puts.flatMap((item) => item.op.writes);
+                    await this.store.put(allWrites);
+                    puts.forEach((item) => item.resolve());
+                }
+                catch (e) {
+                    puts.forEach((item) => item.reject(e));
+                }
+            }
+        }
+    }
+}

package/dist/store/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./base.cjs"), exports);
+__exportStar(require("./batch.cjs"), exports);
+__exportStar(require("./memory.cjs"), exports);

package/dist/store/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./base.js";
+export * from "./batch.js";
+export * from "./memory.js";

package/dist/store/index.js

@@ -0,0 +1,3 @@
+export * from "./base.js";
+export * from "./batch.js";
+export * from "./memory.js";

package/dist/store/memory.cjs

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryStore = void 0;
+const base_js_1 = require("./base.cjs");
+class MemoryStore extends base_js_1.BaseStore {
+    constructor() {
+        super(...arguments);
+        Object.defineProperty(this, "data", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    async list(prefixes) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result = {};
+        for (const prefix of prefixes) {
+            if (this.data.has(prefix)) {
+                result[prefix] = Object.fromEntries(this.data.get(prefix));
+            }
+            else {
+                result[prefix] = {};
+            }
+        }
+        return Promise.resolve(result);
+    }
+    async put(writes) {
+        for (const [namespace, key, value] of writes) {
+            if (!this.data.has(namespace)) {
+                this.data.set(namespace, new Map());
+            }
+            const namespaceMap = this.data.get(namespace);
+            if (value === null) {
+                namespaceMap.delete(key);
+            }
+            else {
+                namespaceMap.set(key, value);
+            }
+        }
+    }
+}
+exports.MemoryStore = MemoryStore;

package/dist/store/memory.d.ts

@@ -0,0 +1,6 @@
+import { BaseStore, type Values } from "./base.js";
+export declare class MemoryStore extends BaseStore {
+    private data;
+    list(prefixes: string[]): Promise<Record<string, Record<string, Values>>>;
+    put(writes: Array<[string, string, Values | null]>): Promise<void>;
+}

package/dist/store/memory.js

@@ -0,0 +1,39 @@
+import { BaseStore } from "./base.js";
+export class MemoryStore extends BaseStore {
+    constructor() {
+        super(...arguments);
+        Object.defineProperty(this, "data", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    async list(prefixes) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result = {};
+        for (const prefix of prefixes) {
+            if (this.data.has(prefix)) {
+                result[prefix] = Object.fromEntries(this.data.get(prefix));
+            }
+            else {
+                result[prefix] = {};
+            }
+        }
+        return Promise.resolve(result);
+    }
+    async put(writes) {
+        for (const [namespace, key, value] of writes) {
+            if (!this.data.has(namespace)) {
+                this.data.set(namespace, new Map());
+            }
+            const namespaceMap = this.data.get(namespace);
+            if (value === null) {
+                namespaceMap.delete(key);
+            }
+            else {
+                namespaceMap.set(key, value);
+            }
+        }
+    }
+}