@langchain/langgraph-sdk 0.0.112 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @langchain/langgraph-sdk
 
+## 0.1.0
+
+### Minor Changes
+
+- 35a0f1c: feat(sdk): set default limit of fetch history to 10
+- 35a0f1c: feat(sdk): set default of `fetchStateHistory` to `false`
+
+### Patch Changes
+
+- 35a0f1c: chore(sdk): decouple stream manager from React
+- 35a0f1c: fix(sdk): prevent partial history from hiding all values
+
 ## 0.0.112
 
 ### Patch Changes

package/dist/react/branching.cjs

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBranchSequence = getBranchSequence;
+exports.getBranchView = getBranchView;
+exports.getBranchContext = getBranchContext;
+function getBranchSequence(history) {
+    const nodeIds = new Set();
+    const childrenMap = {};
+    // Short circuit if there's only a singular one state
+    if (history.length <= 1) {
+        return {
+            rootSequence: {
+                type: "sequence",
+                items: history.map((value) => ({ type: "node", value, path: [] })),
+            },
+            paths: [],
+        };
+    }
+    // First pass - collect nodes for each checkpoint
+    history.forEach((state) => {
+        const checkpointId = state.parent_checkpoint?.checkpoint_id ?? "$";
+        childrenMap[checkpointId] ??= [];
+        childrenMap[checkpointId].push(state);
+        if (state.checkpoint?.checkpoint_id != null) {
+            nodeIds.add(state.checkpoint.checkpoint_id);
+        }
+    });
+    // If dealing with partial history, take the branch
+    // with the latest checkpoint and mark it as the root.
+    const maxId = (...ids) => ids
+        .filter((i) => i != null)
+        .sort((a, b) => a.localeCompare(b))
+        .at(-1);
+    const lastOrphanedNode = childrenMap.$ == null
+        ? Object.keys(childrenMap)
+            .filter((parentId) => !nodeIds.has(parentId))
+            .map((parentId) => {
+            const queue = [parentId];
+            const seen = new Set();
+            let lastId = parentId;
+            while (queue.length > 0) {
+                const current = queue.shift();
+                if (seen.has(current))
+                    continue;
+                seen.add(current);
+                const children = (childrenMap[current] ?? []).flatMap((i) => i.checkpoint?.checkpoint_id ?? []);
+                lastId = maxId(lastId, ...children);
+                queue.push(...children);
+            }
+            return { parentId, lastId };
+        })
+            .sort((a, b) => a.lastId.localeCompare(b.lastId))
+            .at(-1)?.parentId
+        : undefined;
+    if (lastOrphanedNode != null)
+        childrenMap.$ = childrenMap[lastOrphanedNode];
+    const rootSequence = { type: "sequence", items: [] };
+    const queue = [{ id: "$", sequence: rootSequence, path: [] }];
+    const paths = [];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const task = queue.shift();
+        if (visited.has(task.id))
+            continue;
+        visited.add(task.id);
+        const children = childrenMap[task.id];
+        if (children == null || children.length === 0)
+            continue;
+        // If we've encountered a fork (2+ children), push the fork
+        // to the sequence and add a new sequence for each child
+        let fork;
+        if (children.length > 1) {
+            fork = { type: "fork", items: [] };
+            task.sequence.items.push(fork);
+        }
+        for (const value of children) {
+            const id = value.checkpoint?.checkpoint_id;
+            if (id == null)
+                continue;
+            let { sequence } = task;
+            let { path } = task;
+            if (fork != null) {
+                sequence = { type: "sequence", items: [] };
+                fork.items.unshift(sequence);
+                path = path.slice();
+                path.push(id);
+                paths.push(path);
+            }
+            sequence.items.push({ type: "node", value, path });
+            queue.push({ id, sequence, path });
+        }
+    }
+    return { rootSequence, paths };
+}
+const PATH_SEP = ">";
+const ROOT_ID = "$";
+// Get flat view
+function getBranchView(sequence, paths, branch) {
+    const path = branch.split(PATH_SEP);
+    const pathMap = {};
+    for (const path of paths) {
+        const parent = path.at(-2) ?? ROOT_ID;
+        pathMap[parent] ??= [];
+        pathMap[parent].unshift(path);
+    }
+    const history = [];
+    const branchByCheckpoint = {};
+    const forkStack = path.slice();
+    const queue = [...sequence.items];
+    while (queue.length > 0) {
+        const item = queue.shift();
+        if (item.type === "node") {
+            history.push(item.value);
+            const checkpointId = item.value.checkpoint?.checkpoint_id;
+            if (checkpointId == null)
+                continue;
+            branchByCheckpoint[checkpointId] = {
+                branch: item.path.join(PATH_SEP),
+                branchOptions: (item.path.length > 0
+                    ? pathMap[item.path.at(-2) ?? ROOT_ID] ?? []
+                    : []).map((p) => p.join(PATH_SEP)),
+            };
+        }
+        if (item.type === "fork") {
+            const forkId = forkStack.shift();
+            const index = forkId != null
+                ? item.items.findIndex((value) => {
+                    const firstItem = value.items.at(0);
+                    if (!firstItem || firstItem.type !== "node")
+                        return false;
+                    return firstItem.value.checkpoint?.checkpoint_id === forkId;
+                })
+                : -1;
+            const nextItems = item.items.at(index)?.items ?? [];
+            queue.push(...nextItems);
+        }
+    }
+    return { history, branchByCheckpoint };
+}
+function getBranchContext(branch, history) {
+    const { rootSequence: branchTree, paths } = getBranchSequence(history ?? []);
+    const { history: flatHistory, branchByCheckpoint } = getBranchView(branchTree, paths, branch);
+    return {
+        branchTree,
+        flatHistory,
+        branchByCheckpoint,
+        threadHead: flatHistory.at(-1),
+    };
+}

package/dist/react/branching.d.ts

@@ -0,0 +1,35 @@
+import type { ThreadState } from "../schema.js";
+interface Node<StateType = any> {
+    type: "node";
+    value: ThreadState<StateType>;
+    path: string[];
+}
+interface Fork<StateType = any> {
+    type: "fork";
+    items: Array<Sequence<StateType>>;
+}
+export interface Sequence<StateType = any> {
+    type: "sequence";
+    items: Array<Node<StateType> | Fork<StateType>>;
+}
+export declare function getBranchSequence<StateType extends Record<string, unknown>>(history: ThreadState<StateType>[]): {
+    rootSequence: Sequence<any>;
+    paths: string[][];
+};
+export declare function getBranchView<StateType extends Record<string, unknown>>(sequence: Sequence<StateType>, paths: string[][], branch: string): {
+    history: ThreadState<StateType>[];
+    branchByCheckpoint: Record<string, {
+        branch: string | undefined;
+        branchOptions: string[] | undefined;
+    }>;
+};
+export declare function getBranchContext<StateType extends Record<string, unknown>>(branch: string, history: ThreadState<StateType>[] | undefined): {
+    branchTree: Sequence<any>;
+    flatHistory: ThreadState<any>[];
+    branchByCheckpoint: Record<string, {
+        branch: string | undefined;
+        branchOptions: string[] | undefined;
+    }>;
+    threadHead: ThreadState<any> | undefined;
+};
+export {};

package/dist/react/branching.js

@@ -0,0 +1,144 @@
+export function getBranchSequence(history) {
+    const nodeIds = new Set();
+    const childrenMap = {};
+    // Short circuit if there's only a singular one state
+    if (history.length <= 1) {
+        return {
+            rootSequence: {
+                type: "sequence",
+                items: history.map((value) => ({ type: "node", value, path: [] })),
+            },
+            paths: [],
+        };
+    }
+    // First pass - collect nodes for each checkpoint
+    history.forEach((state) => {
+        const checkpointId = state.parent_checkpoint?.checkpoint_id ?? "$";
+        childrenMap[checkpointId] ??= [];
+        childrenMap[checkpointId].push(state);
+        if (state.checkpoint?.checkpoint_id != null) {
+            nodeIds.add(state.checkpoint.checkpoint_id);
+        }
+    });
+    // If dealing with partial history, take the branch
+    // with the latest checkpoint and mark it as the root.
+    const maxId = (...ids) => ids
+        .filter((i) => i != null)
+        .sort((a, b) => a.localeCompare(b))
+        .at(-1);
+    const lastOrphanedNode = childrenMap.$ == null
+        ? Object.keys(childrenMap)
+            .filter((parentId) => !nodeIds.has(parentId))
+            .map((parentId) => {
+            const queue = [parentId];
+            const seen = new Set();
+            let lastId = parentId;
+            while (queue.length > 0) {
+                const current = queue.shift();
+                if (seen.has(current))
+                    continue;
+                seen.add(current);
+                const children = (childrenMap[current] ?? []).flatMap((i) => i.checkpoint?.checkpoint_id ?? []);
+                lastId = maxId(lastId, ...children);
+                queue.push(...children);
+            }
+            return { parentId, lastId };
+        })
+            .sort((a, b) => a.lastId.localeCompare(b.lastId))
+            .at(-1)?.parentId
+        : undefined;
+    if (lastOrphanedNode != null)
+        childrenMap.$ = childrenMap[lastOrphanedNode];
+    const rootSequence = { type: "sequence", items: [] };
+    const queue = [{ id: "$", sequence: rootSequence, path: [] }];
+    const paths = [];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const task = queue.shift();
+        if (visited.has(task.id))
+            continue;
+        visited.add(task.id);
+        const children = childrenMap[task.id];
+        if (children == null || children.length === 0)
+            continue;
+        // If we've encountered a fork (2+ children), push the fork
+        // to the sequence and add a new sequence for each child
+        let fork;
+        if (children.length > 1) {
+            fork = { type: "fork", items: [] };
+            task.sequence.items.push(fork);
+        }
+        for (const value of children) {
+            const id = value.checkpoint?.checkpoint_id;
+            if (id == null)
+                continue;
+            let { sequence } = task;
+            let { path } = task;
+            if (fork != null) {
+                sequence = { type: "sequence", items: [] };
+                fork.items.unshift(sequence);
+                path = path.slice();
+                path.push(id);
+                paths.push(path);
+            }
+            sequence.items.push({ type: "node", value, path });
+            queue.push({ id, sequence, path });
+        }
+    }
+    return { rootSequence, paths };
+}
+const PATH_SEP = ">";
+const ROOT_ID = "$";
+// Get flat view
+export function getBranchView(sequence, paths, branch) {
+    const path = branch.split(PATH_SEP);
+    const pathMap = {};
+    for (const path of paths) {
+        const parent = path.at(-2) ?? ROOT_ID;
+        pathMap[parent] ??= [];
+        pathMap[parent].unshift(path);
+    }
+    const history = [];
+    const branchByCheckpoint = {};
+    const forkStack = path.slice();
+    const queue = [...sequence.items];
+    while (queue.length > 0) {
+        const item = queue.shift();
+        if (item.type === "node") {
+            history.push(item.value);
+            const checkpointId = item.value.checkpoint?.checkpoint_id;
+            if (checkpointId == null)
+                continue;
+            branchByCheckpoint[checkpointId] = {
+                branch: item.path.join(PATH_SEP),
+                branchOptions: (item.path.length > 0
+                    ? pathMap[item.path.at(-2) ?? ROOT_ID] ?? []
+                    : []).map((p) => p.join(PATH_SEP)),
+            };
+        }
+        if (item.type === "fork") {
+            const forkId = forkStack.shift();
+            const index = forkId != null
+                ? item.items.findIndex((value) => {
+                    const firstItem = value.items.at(0);
+                    if (!firstItem || firstItem.type !== "node")
+                        return false;
+                    return firstItem.value.checkpoint?.checkpoint_id === forkId;
+                })
+                : -1;
+            const nextItems = item.items.at(index)?.items ?? [];
+            queue.push(...nextItems);
+        }
+    }
+    return { history, branchByCheckpoint };
+}
+export function getBranchContext(branch, history) {
+    const { rootSequence: branchTree, paths } = getBranchSequence(history ?? []);
+    const { history: flatHistory, branchByCheckpoint } = getBranchView(branchTree, paths, branch);
+    return {
+        branchTree,
+        flatHistory,
+        branchByCheckpoint,
+        threadHead: flatHistory.at(-1),
+    };
+}

package/dist/react/errors.cjs

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamError = void 0;
+class StreamError extends Error {
+    constructor(data) {
+        super(data.message);
+        this.name = data.name ?? data.error ?? "StreamError";
+    }
+    static isStructuredError(error) {
+        return typeof error === "object" && error != null && "message" in error;
+    }
+}
+exports.StreamError = StreamError;

package/dist/react/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class StreamError extends Error {
+    constructor(data: {
+        error?: string;
+        name?: string;
+        message: string;
+    });
+    static isStructuredError(error: unknown): error is {
+        error?: string;
+        name?: string;
+        message: string;
+    };
+}

package/dist/react/errors.js

@@ -0,0 +1,9 @@
+export class StreamError extends Error {
+    constructor(data) {
+        super(data.message);
+        this.name = data.name ?? data.error ?? "StreamError";
+    }
+    static isStructuredError(error) {
+        return typeof error === "object" && error != null && "message" in error;
+    }
+}

package/dist/react/index.d.ts

@@ -1 +1,2 @@
-export { useStream, type MessageMetadata, type UseStream, type UseStreamOptions, } from "./stream.js";
+export { useStream } from "./stream.js";
+export type { MessageMetadata, UseStream, UseStreamOptions } from "./types.js";

package/dist/react/index.js

@@ -1 +1 @@
-export { useStream, } from "./stream.js";
+export { useStream } from "./stream.js";

package/dist/react/manager.cjs

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamManager = void 0;
+const messages_js_1 = require("./messages.cjs");
+const errors_js_1 = require("./errors.cjs");
+class StreamManager {
+    constructor(messages) {
+        Object.defineProperty(this, "abortRef", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new AbortController()
+        });
+        Object.defineProperty(this, "messages", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "listeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "state", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "setState", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (newState) => {
+                this.state = { ...this.state, ...newState };
+                this.notifyListeners();
+            }
+        });
+        Object.defineProperty(this, "notifyListeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => {
+                this.listeners.forEach((listener) => listener());
+            }
+        });
+        Object.defineProperty(this, "subscribe", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (listener) => {
+                this.listeners.add(listener);
+                return () => this.listeners.delete(listener);
+            }
+        });
+        Object.defineProperty(this, "getSnapshot", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => this.state
+        });
+        Object.defineProperty(this, "setStreamValues", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (values, kind = "stream") => {
+                if (typeof values === "function") {
+                    const [prevValues, prevKind] = this.state.values ?? [null, "stream"];
+                    const nextValues = values(prevValues, prevKind);
+                    this.setState({ values: nextValues != null ? [nextValues, kind] : null });
+                }
+                else {
+                    const nextValues = values != null ? [values, kind] : null;
+                    this.setState({ values: nextValues });
+                }
+            }
+        });
+        Object.defineProperty(this, "getMutateFn", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (kind, historyValues) => {
+                return (update) => {
+                    const prev = { ...historyValues, ...this.state.values };
+                    const next = typeof update === "function" ? update(prev) : update;
+                    this.setStreamValues({ ...prev, ...next }, kind);
+                };
+            }
+        });
+        Object.defineProperty(this, "matchEventType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (expected, actual, _data) => {
+                return expected === actual || actual.startsWith(`${expected}|`);
+            }
+        });
+        Object.defineProperty(this, "start", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: async (action, options) => {
+                if (this.state.isLoading)
+                    return;
+                try {
+                    this.setState({ isLoading: true, error: undefined });
+                    this.abortRef = new AbortController();
+                    const run = await action(this.abortRef.signal);
+                    let streamError;
+                    for await (const { event, data } of run) {
+                        if (event === "error") {
+                            streamError = new errors_js_1.StreamError(data);
+                            break;
+                        }
+                        const namespace = event.includes("|")
+                            ? event.split("|").slice(1)
+                            : undefined;
+                        const mutate = this.getMutateFn("stream", options.initialValues);
+                        if (event === "metadata")
+                            options.callbacks.onMetadataEvent?.(data);
+                        if (event === "events")
+                            options.callbacks.onLangChainEvent?.(data);
+                        if (this.matchEventType("updates", event, data)) {
+                            options.callbacks.onUpdateEvent?.(data, { namespace, mutate });
+                        }
+                        if (this.matchEventType("custom", event, data)) {
+                            options.callbacks.onCustomEvent?.(data, { namespace, mutate });
+                        }
+                        if (this.matchEventType("checkpoints", event, data)) {
+                            options.callbacks.onCheckpointEvent?.(data, { namespace });
+                        }
+                        if (this.matchEventType("tasks", event, data)) {
+                            options.callbacks.onTaskEvent?.(data, { namespace });
+                        }
+                        if (this.matchEventType("debug", event, data)) {
+                            options.callbacks.onDebugEvent?.(data, { namespace });
+                        }
+                        if (event === "values") {
+                            // don't update values on interrupt values event
+                            if ("__interrupt__" in data)
+                                continue;
+                            this.setStreamValues(data);
+                        }
+                        if (this.matchEventType("messages", event, data)) {
+                            const [serialized, metadata] = data;
+                            const messageId = this.messages.add(serialized, metadata);
+                            if (!messageId) {
+                                console.warn("Failed to add message to manager, no message ID found");
+                                continue;
+                            }
+                            this.setStreamValues((streamValues) => {
+                                const values = { ...options.initialValues, ...streamValues };
+                                // Assumption: we're concatenating the message
+                                const messages = options.getMessages(values).slice();
+                                const { chunk, index } = this.messages.get(messageId, messages.length) ?? {};
+                                if (!chunk || index == null)
+                                    return values;
+                                messages[index] = (0, messages_js_1.toMessageDict)(chunk);
+                                return options.setMessages(values, messages);
+                            });
+                        }
+                    }
+                    if (streamError != null)
+                        throw streamError;
+                    const values = await options.onSuccess?.();
+                    if (typeof values !== "undefined")
+                        this.setStreamValues(values);
+                }
+                catch (error) {
+                    if (!(error instanceof Error && // eslint-disable-line no-instanceof/no-instanceof
+                        (error.name === "AbortError" || error.name === "TimeoutError"))) {
+                        console.error(error);
+                        this.setState({ error });
+                        await options.onError?.(error);
+                    }
+                }
+                finally {
+                    this.setState({ isLoading: false });
+                    this.abortRef = new AbortController();
+                }
+            }
+        });
+        Object.defineProperty(this, "stop", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: async (historyValues, options) => {
+                if (this.abortRef) {
+                    this.abortRef.abort();
+                    this.abortRef = new AbortController();
+                }
+                options.onStop?.({ mutate: this.getMutateFn("stop", historyValues) });
+            }
+        });
+        Object.defineProperty(this, "clear", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => {
+                this.setState({ error: undefined, values: null });
+                this.messages.clear();
+            }
+        });
+        this.messages = messages;
+        this.state = { isLoading: false, values: null, error: undefined };
+    }
+    get isLoading() {
+        return this.state.isLoading;
+    }
+    get values() {
+        return this.state.values?.[0] ?? null;
+    }
+    get error() {
+        return this.state.error;
+    }
+}
+exports.StreamManager = StreamManager;