@langgraph-js/pure-graph 1.0.0

package/src/graph/stream.ts

@@ -0,0 +1,253 @@
+import { BaseMessageChunk, isBaseMessage } from '@langchain/core/messages';
+import type { BaseCheckpointSaver, LangGraphRunnableConfig } from '@langchain/langgraph';
+import type { Pregel } from '@langchain/langgraph/pregel';
+import { getLangGraphCommand } from '../utils/getLangGraphCommand.js';
+import type { BaseStreamQueueInterface } from '../queue/stream_queue.js';
+
+import { globalMessageQueue } from '../global.js';
+import { Run } from '@langgraph-js/sdk';
+import { EventMessage, StreamErrorEventMessage, StreamEndEventMessage } from '../queue/event_message.js';
+
+import { BaseThreadsManager } from '../threads/index.js';
+import { StreamInputData } from '../types.js';
+
+export type LangGraphStreamMode = Pregel<any, any>['streamMode'][number];
+
+export async function streamStateWithQueue(
+    threads: BaseThreadsManager,
+    run: Run,
+    queue: BaseStreamQueueInterface,
+    payload: StreamInputData,
+    options: {
+        attempt: number;
+        getGraph: (
+            graphId: string,
+            config: LangGraphRunnableConfig | undefined,
+            options?: { checkpointer?: BaseCheckpointSaver | null },
+        ) => Promise<Pregel<any, any, any, any, any>>;
+        compressMessages?: boolean;
+    },
+): Promise<void> {
+    const kwargs = payload;
+    const graphId = kwargs.config?.configurable?.graph_id;
+
+    if (!graphId || typeof graphId !== 'string') {
+        throw new Error('Invalid or missing graph_id');
+    }
+
+    const graph = await options.getGraph(graphId, payload.config, {
+        checkpointer: payload.temporary ? null : undefined,
+    });
+
+    const userStreamMode = payload.stream_mode ?? [];
+
+    const libStreamMode: Set<LangGraphStreamMode> = new Set([
+        'values',
+        ...userStreamMode.filter((mode) => mode !== 'events' && mode !== 'messages-tuple'),
+    ]);
+
+    if (userStreamMode.includes('messages-tuple')) {
+        libStreamMode.add('messages');
+    }
+
+    if (userStreamMode.includes('messages')) {
+        libStreamMode.add('values');
+    }
+
+    await queue.push(new EventMessage('metadata', { run_id: run.run_id, attempt: options.attempt, graph_id: graphId }));
+
+    const metadata = {
+        ...payload.config?.metadata,
+        run_attempt: options.attempt,
+    };
+    const events = graph.streamEvents(
+        payload.command != null ? getLangGraphCommand(payload.command) : payload.input ?? null,
+        {
+            version: 'v2' as const,
+
+            interruptAfter: payload.interrupt_after,
+            interruptBefore: payload.interrupt_before,
+
+            tags: payload.config?.tags,
+            configurable: payload.config?.configurable,
+            recursionLimit: payload.config?.recursionLimit,
+            subgraphs: payload.stream_subgraphs,
+            metadata,
+
+            runId: run.run_id,
+            streamMode: [...libStreamMode],
+            signal: queue.cancelSignal.signal,
+        },
+    );
+
+    const messages: Record<string, BaseMessageChunk> = {};
+    const completedIds = new Set<string>();
+
+    try {
+        for await (const event of events) {
+            // console.log(event);
+            if (event.tags?.includes('langsmith:hidden')) continue;
+            if (event.event === 'on_chain_stream' && event.run_id === run.run_id) {
+                const [ns, mode, chunk] = (
+                    payload.stream_subgraphs ? event.data.chunk : [null, ...event.data.chunk]
+                ) as [string[] | null, LangGraphStreamMode, unknown];
+
+                // Listen for debug events and capture checkpoint
+                let data: unknown = chunk;
+
+                if (mode === 'messages') {
+                    if (userStreamMode.includes('messages-tuple')) {
+                        await queue.push(new EventMessage('messages', data));
+                    }
+                } else if (userStreamMode.includes(mode)) {
+                    if (payload.stream_subgraphs && ns?.length) {
+                        await queue.push(new EventMessage(`${mode}|${ns.join('|')}`, data));
+                    } else {
+                        await queue.push(new EventMessage(mode, data));
+                    }
+                }
+                if (mode === 'values') {
+                    await threads.set(run.thread_id, { values: JSON.parse(serialiseAsDict(data)) });
+                }
+            } else if (userStreamMode.includes('events')) {
+                await queue.push(new EventMessage('events', event));
+            }
+
+            // TODO: we still rely on old messages mode based of streamMode=values
+            // In order to fully switch to library messages mode, we need to do ensure that
+            // `StreamMessagesHandler` sends the final message, which requires the following:
+            // - handleLLMEnd does not send the final message b/c handleLLMNewToken sets the this.emittedChatModelRunIds[runId] flag. Python does not do that
+            // - handleLLMEnd receives the final message as BaseMessageChunk rather than BaseMessage, which from the outside will become indistinguishable.
+            // - handleLLMEnd should not dedupe the message
+            // - Don't think there's an utility that would convert a BaseMessageChunk to a BaseMessage?
+            if (userStreamMode.includes('messages')) {
+                if (event.event === 'on_chain_stream' && event.run_id === run.run_id) {
+                    const newMessages: Array<BaseMessageChunk> = [];
+                    const [_, chunk]: [string, any] = event.data.chunk;
+
+                    let chunkMessages: Array<BaseMessageChunk> = [];
+                    if (typeof chunk === 'object' && chunk != null && 'messages' in chunk && !isBaseMessage(chunk)) {
+                        chunkMessages = chunk?.messages;
+                    }
+
+                    if (!Array.isArray(chunkMessages)) {
+                        chunkMessages = [chunkMessages];
+                    }
+
+                    for (const message of chunkMessages) {
+                        if (!message.id || completedIds.has(message.id)) continue;
+                        completedIds.add(message.id);
+                        newMessages.push(message);
+                    }
+
+                    if (newMessages.length > 0) {
+                        await queue.push(new EventMessage('messages/complete', newMessages));
+                    }
+                } else if (event.event === 'on_chat_model_stream' && !event.tags?.includes('nostream')) {
+                    const message: BaseMessageChunk = event.data.chunk;
+
+                    if (!message.id) continue;
+
+                    if (messages[message.id] == null) {
+                        messages[message.id] = message;
+                        await queue.push(
+                            new EventMessage('messages/metadata', { [message.id]: { metadata: event.metadata } }),
+                        );
+                    } else {
+                        messages[message.id] = messages[message.id].concat(message);
+                    }
+
+                    await queue.push(new EventMessage('messages/partial', [messages[message.id]]));
+                }
+            }
+        }
+    } finally {
+        // 发送流结束信号
+        await queue.push(new StreamEndEventMessage());
+    }
+}
+
+/**
+ * 从队列创建数据流生成器
+ * @param queueId 队列 ID
+ * @param signal 中止信号
+ * @returns 数据流生成器
+ */
+export async function* createStreamFromQueue(queueId: string): AsyncGenerator<{ event: string; data: unknown }> {
+    const queue = globalMessageQueue.getQueue(queueId);
+    return queue.onDataReceive();
+}
+
+export const serialiseAsDict = (obj: unknown) => {
+    return JSON.stringify(
+        obj,
+        function (key: string | number, value: unknown) {
+            const rawValue = this[key];
+            if (
+                rawValue != null &&
+                typeof rawValue === 'object' &&
+                'toDict' in rawValue &&
+                typeof rawValue.toDict === 'function'
+            ) {
+                // TODO: we need to upstream this to LangChainJS
+                const { type, data } = rawValue.toDict();
+                return { ...data, type };
+            }
+
+            return value;
+        },
+        2,
+    );
+};
+/**
+ * 兼容性函数：保持原有 API，同时使用队列模式
+ * @param run 运行配置
+ * @param options 选项
+ * @returns 数据流生成器
+ */
+export async function* streamState(
+    threads: BaseThreadsManager,
+    run: Run | Promise<Run>,
+    payload: StreamInputData,
+    options: {
+        attempt: number;
+        getGraph: (
+            graphId: string,
+            config: LangGraphRunnableConfig | undefined,
+            options?: { checkpointer?: BaseCheckpointSaver | null },
+        ) => Promise<Pregel<any, any, any, any, any>>;
+        compressMessages?: boolean;
+    },
+) {
+    run = await run;
+    // 生成唯一的队列 ID
+    const queueId = run.run_id;
+    const threadId = run.thread_id;
+    try {
+        // 启动队列推送任务（在后台异步执行）
+        await threads.set(threadId, { status: 'busy' });
+        await threads.updateRun(run.run_id, { status: 'running' });
+        const queue = globalMessageQueue.createQueue(queueId);
+        const state = queue.onDataReceive();
+        streamStateWithQueue(threads, run, queue, payload, options).catch((error) => {
+            console.error('Queue task error:', error);
+            // 如果生产者出错，向队列推送错误信号
+            globalMessageQueue.pushToQueue(queueId, new StreamErrorEventMessage(error));
+            // TODO 不知道这里需不需要错误处理
+        });
+        for await (const data of state) {
+            yield data;
+        }
+        await threads.updateRun(run.run_id, { status: 'success' });
+    } catch (error) {
+        // 如果发生错误，确保清理资源
+        console.error('Stream error:', error);
+        await threads.updateRun(run.run_id, { status: 'error' });
+        await threads.set(threadId, { status: 'error' });
+        // throw error;
+    } finally {
+        // 在完成后立即清理队列，因为消费者已经完成
+        await threads.set(threadId, { status: 'idle' });
+        globalMessageQueue.removeQueue(queueId);
+    }
+}

package/src/graph/stringify.ts

@@ -0,0 +1,219 @@
+/* eslint-disable */
+// @ts-nocheck
+
+// Stringify that can handle circular references.
+// Inlined due to ESM import issues
+// Source: https://www.npmjs.com/package/fast-safe-stringify
+
+var LIMIT_REPLACE_NODE = '[...]';
+var CIRCULAR_REPLACE_NODE = '[Circular]';
+
+var arr = [];
+var replacerStack = [];
+
+function defaultOptions() {
+    return {
+        depthLimit: Number.MAX_SAFE_INTEGER,
+        edgesLimit: Number.MAX_SAFE_INTEGER,
+    };
+}
+
+// Regular stringify
+export function stringify(obj, replacer?, spacer?, options?) {
+    if (typeof options === 'undefined') {
+        options = defaultOptions();
+    }
+
+    decirc(obj, '', 0, [], undefined, 0, options);
+    var res;
+    try {
+        if (replacerStack.length === 0) {
+            res = JSON.stringify(obj, replacer, spacer);
+        } else {
+            res = JSON.stringify(obj, replaceGetterValues(replacer), spacer);
+        }
+    } catch (_) {
+        return JSON.stringify('[unable to serialize, circular reference is too complex to analyze]');
+    } finally {
+        while (arr.length !== 0) {
+            var part = arr.pop();
+            if (part.length === 4) {
+                Object.defineProperty(part[0], part[1], part[3]);
+            } else {
+                part[0][part[1]] = part[2];
+            }
+        }
+    }
+    return res;
+}
+
+function setReplace(replace, val, k, parent) {
+    var propertyDescriptor = Object.getOwnPropertyDescriptor(parent, k);
+    if (propertyDescriptor.get !== undefined) {
+        if (propertyDescriptor.configurable) {
+            Object.defineProperty(parent, k, { value: replace });
+            arr.push([parent, k, val, propertyDescriptor]);
+        } else {
+            replacerStack.push([val, k, replace]);
+        }
+    } else {
+        parent[k] = replace;
+        arr.push([parent, k, val]);
+    }
+}
+
+function decirc(val, k, edgeIndex, stack, parent, depth, options) {
+    depth += 1;
+    var i;
+    if (typeof val === 'object' && val !== null) {
+        for (i = 0; i < stack.length; i++) {
+            if (stack[i] === val) {
+                setReplace(CIRCULAR_REPLACE_NODE, val, k, parent);
+                return;
+            }
+        }
+
+        if (typeof options.depthLimit !== 'undefined' && depth > options.depthLimit) {
+            setReplace(LIMIT_REPLACE_NODE, val, k, parent);
+            return;
+        }
+
+        if (typeof options.edgesLimit !== 'undefined' && edgeIndex + 1 > options.edgesLimit) {
+            setReplace(LIMIT_REPLACE_NODE, val, k, parent);
+            return;
+        }
+
+        stack.push(val);
+        // Optimize for Arrays. Big arrays could kill the performance otherwise!
+        if (Array.isArray(val)) {
+            for (i = 0; i < val.length; i++) {
+                decirc(val[i], i, i, stack, val, depth, options);
+            }
+        } else {
+            var keys = Object.keys(val);
+            for (i = 0; i < keys.length; i++) {
+                var key = keys[i];
+                decirc(val[key], key, i, stack, val, depth, options);
+            }
+        }
+        stack.pop();
+    }
+}
+
+// Stable-stringify
+function compareFunction(a, b) {
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
+
+function deterministicStringify(obj, replacer, spacer, options) {
+    if (typeof options === 'undefined') {
+        options = defaultOptions();
+    }
+
+    var tmp = deterministicDecirc(obj, '', 0, [], undefined, 0, options) || obj;
+    var res;
+    try {
+        if (replacerStack.length === 0) {
+            res = JSON.stringify(tmp, replacer, spacer);
+        } else {
+            res = JSON.stringify(tmp, replaceGetterValues(replacer), spacer);
+        }
+    } catch (_) {
+        return JSON.stringify('[unable to serialize, circular reference is too complex to analyze]');
+    } finally {
+        // Ensure that we restore the object as it was.
+        while (arr.length !== 0) {
+            var part = arr.pop();
+            if (part.length === 4) {
+                Object.defineProperty(part[0], part[1], part[3]);
+            } else {
+                part[0][part[1]] = part[2];
+            }
+        }
+    }
+    return res;
+}
+
+function deterministicDecirc(val, k, edgeIndex, stack, parent, depth, options) {
+    depth += 1;
+    var i;
+    if (typeof val === 'object' && val !== null) {
+        for (i = 0; i < stack.length; i++) {
+            if (stack[i] === val) {
+                setReplace(CIRCULAR_REPLACE_NODE, val, k, parent);
+                return;
+            }
+        }
+        try {
+            if (typeof val.toJSON === 'function') {
+                return;
+            }
+        } catch (_) {
+            return;
+        }
+
+        if (typeof options.depthLimit !== 'undefined' && depth > options.depthLimit) {
+            setReplace(LIMIT_REPLACE_NODE, val, k, parent);
+            return;
+        }
+
+        if (typeof options.edgesLimit !== 'undefined' && edgeIndex + 1 > options.edgesLimit) {
+            setReplace(LIMIT_REPLACE_NODE, val, k, parent);
+            return;
+        }
+
+        stack.push(val);
+        // Optimize for Arrays. Big arrays could kill the performance otherwise!
+        if (Array.isArray(val)) {
+            for (i = 0; i < val.length; i++) {
+                deterministicDecirc(val[i], i, i, stack, val, depth, options);
+            }
+        } else {
+            // Create a temporary object in the required way
+            var tmp = {};
+            var keys = Object.keys(val).sort(compareFunction);
+            for (i = 0; i < keys.length; i++) {
+                var key = keys[i];
+                deterministicDecirc(val[key], key, i, stack, val, depth, options);
+                tmp[key] = val[key];
+            }
+            if (typeof parent !== 'undefined') {
+                arr.push([parent, k, val]);
+                parent[k] = tmp;
+            } else {
+                return tmp;
+            }
+        }
+        stack.pop();
+    }
+}
+
+// wraps replacer function to handle values we couldn't replace
+// and mark them as replaced value
+function replaceGetterValues(replacer) {
+    replacer =
+        typeof replacer !== 'undefined'
+            ? replacer
+            : function (k, v) {
+                  return v;
+              };
+    return function (key, val) {
+        if (replacerStack.length > 0) {
+            for (var i = 0; i < replacerStack.length; i++) {
+                var part = replacerStack[i];
+                if (part[1] === key && part[0] === val) {
+                    val = part[2];
+                    replacerStack.splice(i, 1);
+                    break;
+                }
+            }
+        }
+        return replacer.call(this, key, val);
+    };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './createEndpoint';
+export * from './types';
+export * from './global';
+
+export * from './threads/index';

package/src/queue/JsonPlusSerializer.ts

@@ -0,0 +1,143 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable no-instanceof/no-instanceof */
+import { load } from '@langchain/core/load';
+import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
+import { stringify } from '../graph/stringify.js';
+
+function isLangChainSerializedObject(value: Record<string, unknown>) {
+    return value !== null && value.lc === 1 && value.type === 'constructor' && Array.isArray(value.id);
+}
+
+/**
+ * The replacer in stringify does not allow delegation to built-in LangChain
+ * serialization methods, and instead immediately calls `.toJSON()` and
+ * continues to stringify subfields.
+ *
+ * We therefore must start from the most nested elements in the input and
+ * deserialize upwards rather than top-down.
+ */
+async function _reviver(value: any): Promise<any> {
+    if (value && typeof value === 'object') {
+        if (Array.isArray(value)) {
+            const revivedArray = await Promise.all(value.map((item) => _reviver(item)));
+            return revivedArray;
+        } else {
+            const revivedObj: any = {};
+            for (const [k, v] of Object.entries(value)) {
+                revivedObj[k] = await _reviver(v);
+            }
+
+            if (revivedObj.lc === 2 && revivedObj.type === 'undefined') {
+                return undefined;
+            } else if (revivedObj.lc === 2 && revivedObj.type === 'constructor' && Array.isArray(revivedObj.id)) {
+                try {
+                    const constructorName = revivedObj.id[revivedObj.id.length - 1];
+                    let constructor: any;
+
+                    switch (constructorName) {
+                        case 'Set':
+                            constructor = Set;
+                            break;
+                        case 'Map':
+                            constructor = Map;
+                            break;
+                        case 'RegExp':
+                            constructor = RegExp;
+                            break;
+                        case 'Error':
+                            constructor = Error;
+                            break;
+                        default:
+                            return revivedObj;
+                    }
+                    if (revivedObj.method) {
+                        return (constructor as any)[revivedObj.method](...(revivedObj.args || []));
+                    } else {
+                        return new (constructor as any)(...(revivedObj.args || []));
+                    }
+                } catch (error) {
+                    return revivedObj;
+                }
+            } else if (isLangChainSerializedObject(revivedObj)) {
+                return load(JSON.stringify(revivedObj));
+            }
+
+            return revivedObj;
+        }
+    }
+    return value;
+}
+
+function _encodeConstructorArgs(
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    constructor: Function,
+    method?: string,
+    args?: any[],
+    kwargs?: Record<string, any>,
+): object {
+    return {
+        lc: 2,
+        type: 'constructor',
+        id: [constructor.name],
+        method: method ?? null,
+        args: args ?? [],
+        kwargs: kwargs ?? {},
+    };
+}
+
+function _default(obj: any): any {
+    if (obj === undefined) {
+        return {
+            lc: 2,
+            type: 'undefined',
+        };
+    } else if (obj instanceof Set || obj instanceof Map) {
+        return _encodeConstructorArgs(obj.constructor, undefined, [Array.from(obj)]);
+    } else if (obj instanceof RegExp) {
+        return _encodeConstructorArgs(RegExp, undefined, [obj.source, obj.flags]);
+    } else if (obj instanceof Error) {
+        return _encodeConstructorArgs(obj.constructor, undefined, [obj.message]);
+        // TODO: Remove special case
+    } else if (obj?.lg_name === 'Send') {
+        return {
+            node: obj.node,
+            args: obj.args,
+        };
+    } else {
+        return obj;
+    }
+}
+
+export class JsonPlusSerializer implements SerializerProtocol {
+    protected _dumps(obj: any): Uint8Array {
+        const encoder = new TextEncoder();
+        return encoder.encode(
+            stringify(obj, (_: string, value: any) => {
+                return _default(value);
+            }),
+        );
+    }
+
+    async dumpsTyped(obj: any): Promise<[string, Uint8Array]> {
+        if (obj instanceof Uint8Array) {
+            return ['bytes', obj];
+        } else {
+            return ['json', this._dumps(obj)];
+        }
+    }
+
+    protected async _loads(data: string): Promise<any> {
+        const parsed = JSON.parse(data);
+        return _reviver(parsed);
+    }
+
+    async loadsTyped(type: string, data: Uint8Array | string): Promise<any> {
+        if (type === 'bytes') {
+            return typeof data === 'string' ? new TextEncoder().encode(data) : data;
+        } else if (type === 'json') {
+            return this._loads(typeof data === 'string' ? data : new TextDecoder().decode(data));
+        } else {
+            throw new Error(`Unknown serialization type: ${type}`);
+        }
+    }
+}

package/src/queue/event_message.ts

@@ -0,0 +1,30 @@
+export class EventMessage {
+    event: string;
+    data: unknown;
+    id?: string;
+    constructor(event: string, data?: unknown) {
+        this.event = event;
+        this.data = data;
+    }
+}
+
+export class CancelEventMessage extends EventMessage {
+    constructor() {
+        super('__system_cancel__', 'user cancel this run');
+    }
+}
+
+export class StreamEndEventMessage extends EventMessage {
+    constructor() {
+        super('__stream_end__');
+    }
+}
+
+export class StreamErrorEventMessage extends EventMessage {
+    public constructor(error: Error) {
+        super('__stream_error__', {
+            error: error.name,
+            message: error.message,
+        });
+    }
+}