@langgraph-js/pure-graph 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+import { Thread, Assistant, Run, StreamMode, Command, Metadata, AssistantGraph, OnConflictBehavior, ThreadStatus, Checkpoint } from '@langchain/langgraph-sdk';
+import { StreamEvent } from '@langchain/core/tracers/log_stream';
+import { EventMessage } from './queue/event_message';
+import { RunnableConfig } from '@langchain/core/runnables';
+export type AssistantSortBy = 'assistant_id' | 'graph_id' | 'name' | 'created_at' | 'updated_at';
+export type ThreadSortBy = 'thread_id' | 'status' | 'created_at' | 'updated_at';
+export type SortOrder = 'asc' | 'desc';
+export type RunStatus = 'pending' | 'running' | 'error' | 'success' | 'timeout' | 'interrupted';
+export type MultitaskStrategy = 'reject' | 'interrupt' | 'rollback' | 'enqueue';
+export type DisconnectMode = 'cancel' | 'continue';
+export type OnCompletionBehavior = 'complete' | 'continue';
+export type CancelAction = 'interrupt' | 'rollback';
+export type StreamInputData = {
+    input?: Record<string, unknown> | null;
+    metadata?: Metadata;
+    config?: RunnableConfig;
+    checkpointId?: string;
+    checkpoint?: Omit<Checkpoint, 'thread_id'>;
+    checkpoint_during?: boolean;
+    interrupt_before?: '*' | string[];
+    interrupt_after?: '*' | string[];
+    multitask_strategy?: MultitaskStrategy;
+    on_completion?: OnCompletionBehavior;
+    signal?: AbortController['signal'];
+    webhook?: string;
+    on_disconnect?: DisconnectMode;
+    after_seconds?: number;
+    if_not_exists?: 'create' | 'reject';
+    command?: Command;
+    onRunCreated?: (params: {
+        run_id: string;
+        thread_id?: string;
+    }) => void;
+    stream_mode?: StreamMode[];
+    stream_subgraphs?: boolean;
+    stream_resumable?: boolean;
+    feedback_keys?: string[];
+    temporary?: boolean;
+};
+/**
+ * 兼容 LangGraph SDK 的接口定义，方便进行无侵入式的扩展
+ */
+export interface ILangGraphClient<TStateType = unknown> {
+    assistants: {
+        search(query?: {
+            graphId?: string;
+            metadata?: Metadata;
+            limit?: number;
+            offset?: number;
+            sortBy?: AssistantSortBy;
+            sortOrder?: SortOrder;
+        }): Promise<Assistant[]>;
+        getGraph(assistantId: string, options?: {
+            xray?: boolean | number;
+        }): Promise<AssistantGraph>;
+    };
+    threads: {
+        create(payload?: {
+            metadata?: Metadata;
+            thread_id?: string;
+            if_exists?: OnConflictBehavior;
+            graph_id?: string;
+        }): Promise<Thread<TStateType>>;
+        search(query?: {
+            metadata?: Metadata;
+            limit?: number;
+            offset?: number;
+            status?: ThreadStatus;
+            sortBy?: ThreadSortBy;
+            sortOrder?: SortOrder;
+        }): Promise<Thread<TStateType>[]>;
+        get(threadId: string): Promise<Thread<TStateType>>;
+        delete(threadId: string): Promise<void>;
+    };
+    runs: {
+        list(threadId: string, options?: {
+            limit?: number;
+            offset?: number;
+            status?: RunStatus;
+        }): Promise<Run[]>;
+        stream(threadId: string, assistantId: string, payload?: StreamInputData): AsyncGenerator<EventMessage>;
+        joinStream(threadId: string, runId: string, options?: {
+            signal?: AbortSignal;
+            cancelOnDisconnect?: boolean;
+            lastEventId?: string;
+            streamMode?: StreamMode | StreamMode[];
+        } | AbortSignal): AsyncGenerator<{
+            id?: string;
+            event: StreamEvent;
+            data: any;
+        }>;
+        cancel(threadId: string, runId: string, wait?: boolean, action?: CancelAction): Promise<void>;
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/getGraph.d.ts

@@ -0,0 +1,10 @@
+import { BaseCheckpointSaver, BaseStore, CompiledGraph, CompiledStateGraph, LangGraphRunnableConfig } from '@langchain/langgraph';
+export type CompiledGraphFactory<T extends string> = (config: {
+    configurable?: Record<string, unknown>;
+}) => Promise<CompiledGraph<T>>;
+export declare const GRAPHS: Record<string, CompiledGraph<string> | CompiledGraphFactory<string>>;
+export declare function registerGraph(graphId: string, graph: CompiledGraph<any> | CompiledStateGraph<any, any, any, any, any, any, any> | CompiledGraphFactory<any>): Promise<void>;
+export declare function getGraph(graphId: string, config: LangGraphRunnableConfig | undefined, options?: {
+    checkpointer?: BaseCheckpointSaver | null;
+    store?: BaseStore;
+}): Promise<CompiledGraph<string, any, any, Record<string, any>, any, any, unknown>>;

package/dist/utils/getGraph.js

@@ -0,0 +1,18 @@
+import { globalCheckPointer } from '../global';
+export const GRAPHS = {};
+export async function registerGraph(graphId, graph) {
+    GRAPHS[graphId] = graph;
+}
+export async function getGraph(graphId, config, options) {
+    if (!GRAPHS[graphId])
+        throw new Error(`Graph "${graphId}" not found`);
+    const compiled = typeof GRAPHS[graphId] === 'function' ? await GRAPHS[graphId](config ?? { configurable: {} }) : GRAPHS[graphId];
+    if (typeof options?.checkpointer !== 'undefined') {
+        compiled.checkpointer = options?.checkpointer ?? globalCheckPointer;
+    }
+    else {
+        compiled.checkpointer = globalCheckPointer;
+    }
+    compiled.store = options?.store ?? undefined;
+    return compiled;
+}

package/dist/utils/getLangGraphCommand.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@langchain/langgraph';
+import { Command as ClientCommand } from '@langgraph-js/sdk';
+export interface RunSend {
+    node: string;
+    input?: unknown;
+}
+export interface RunCommand extends ClientCommand {
+}
+export declare const getLangGraphCommand: (command: RunCommand) => Command<unknown, Record<string, unknown>, string>;

package/dist/utils/getLangGraphCommand.js

@@ -0,0 +1,13 @@
+import { Command, Send } from '@langchain/langgraph';
+export const getLangGraphCommand = (command) => {
+    let goto = command.goto != null && !Array.isArray(command.goto) ? [command.goto] : command.goto;
+    return new Command({
+        goto: goto?.map((item) => {
+            if (typeof item !== 'string')
+                return new Send(item.node, item.input);
+            return item;
+        }),
+        update: command.update ?? undefined,
+        resume: command.resume,
+    });
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@langgraph-js/pure-graph",
+  "version": "1.0.0",
+  "description": "",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js"
+    },
+    "/hono": {
+      "import": "./dist/adapter/hono/index.js"
+    }
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@langchain/core": "^0.3.77",
+    "@langchain/langgraph": "^0.4.9",
+    "@langchain/langgraph-checkpoint": "^0.1.1",
+    "@langgraph-js/pro": "^1.8.1",
+    "eventemitter3": "^5.0.1",
+    "zod": "^3"
+  },
+  "optionalDependencies": {
+    "@hono/zod-validator": "^0.7.3",
+    "hono": "^4.9.9"
+  },
+  "devDependencies": {
+    "@langchain/langgraph-sdk": "^0.1.7",
+    "@langgraph-js/sdk": "^2.0.1",
+    "@types/node": "^22.13.5",
+    "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "dev": "bun run test/hono.ts",
+    "build": "tsc"
+  }
+}

package/src/adapter/hono/assistants.ts

@@ -0,0 +1,41 @@
+import { zValidator } from '@hono/zod-validator';
+import { Hono } from 'hono';
+import { z } from 'zod';
+import { client } from './endpoint';
+import { MetadataSchema } from './zod';
+const api = new Hono();
+
+api.post(
+    '/assistants/search',
+    zValidator(
+        'json',
+        z.object({
+            graph_id: z.string().optional(),
+            metadata: MetadataSchema.optional(),
+            limit: z.number().int().optional(),
+            offset: z.number().int().optional(),
+        }),
+    ),
+    async (c) => {
+        // Search Assistants
+        const payload = c.req.valid('json');
+        let total = 0;
+        const data = await client.assistants.search(payload);
+        c.res.headers.set('X-Pagination-Total', total.toString());
+        return c.json(data);
+    },
+);
+
+api.get(
+    '/assistants/:assistant_id/graph',
+    zValidator('query', z.object({ xray: z.string().optional() })),
+    async (c) => {
+        const xray = c.req.valid('query').xray;
+        const data = await client.assistants.getGraph(c.req.param('assistant_id'), {
+            xray: xray !== undefined ? xray === 'true' : undefined,
+        });
+        return c.json(data);
+    },
+);
+
+export default api;

package/src/adapter/hono/endpoint.ts

@@ -0,0 +1,4 @@
+import { createEndpoint } from '../../createEndpoint.js';
+import { MemoryThreadsManager } from '../../storage/memory/threads.js';
+
+export const client = createEndpoint(new MemoryThreadsManager());

package/src/adapter/hono/index.ts

@@ -0,0 +1,14 @@
+import { Hono } from 'hono';
+import Assistants from './assistants';
+import Runs from './runs';
+import Threads from './threads';
+import { cors } from 'hono/cors';
+const app = new Hono();
+
+app.use(cors());
+
+app.route('/', Assistants);
+app.route('/', Runs);
+app.route('/', Threads);
+
+export default app;

package/src/adapter/hono/runs.ts

@@ -0,0 +1,102 @@
+import { zValidator } from '@hono/zod-validator';
+import { Hono } from 'hono';
+
+import { streamSSE } from 'hono/streaming';
+import { z } from 'zod';
+import { client } from './endpoint';
+import { AssistantConfig, CommandSchema, MetadataSchema } from './zod';
+import { serialiseAsDict } from '../../graph/stream';
+
+const api = new Hono();
+
+// 最常用的对话接口
+api.post(
+    '/threads/:thread_id/runs/stream',
+    zValidator('param', z.object({ thread_id: z.string().uuid() })),
+    zValidator(
+        'json',
+        z
+            .object({
+                assistant_id: z.union([z.string().uuid(), z.string()]),
+                checkpoint_id: z.string().optional(),
+                // checkpoint: CheckpointSchema.optional(),
+                input: z.any().optional(),
+                command: CommandSchema.optional(),
+                metadata: MetadataSchema.optional(),
+                config: AssistantConfig.optional(),
+                webhook: z.string().optional(),
+                interrupt_before: z.union([z.literal('*'), z.array(z.string())]).optional(),
+                interrupt_after: z.union([z.literal('*'), z.array(z.string())]).optional(),
+                on_disconnect: z.enum(['cancel', 'continue']).optional().default('continue'),
+                multitask_strategy: z.enum(['reject', 'rollback', 'interrupt', 'enqueue']).optional(),
+                stream_mode: z
+                    .array(z.enum(['values', 'messages', 'messages-tuple', 'updates', 'events', 'debug', 'custom']))
+                    .optional(),
+                stream_subgraphs: z.boolean().optional(),
+                stream_resumable: z.boolean().optional(),
+                after_seconds: z.number().optional(),
+                if_not_exists: z.enum(['create', 'reject']).optional(),
+                on_completion: z.enum(['complete', 'continue']).optional(),
+                feedback_keys: z.array(z.string()).optional(),
+                langsmith_tracer: z.unknown().optional(),
+            })
+            .describe('Payload for creating a stateful run.'),
+    ),
+    async (c) => {
+        // Stream Run
+        const { thread_id } = c.req.valid('param');
+        const payload = c.req.valid('json');
+
+        // c.header('Content-Location', `/threads/${thread_id}/runs/${run.run_id}`);
+        return streamSSE(c, async (stream) => {
+            /** @ts-ignore zod v3 的问题，与 ts 类型不一致 */
+            for await (const { event, data } of client.runs.stream(thread_id, payload.assistant_id, payload)) {
+                await stream.writeSSE({ data: serialiseAsDict(data), event });
+            }
+            // await stream.sleep(500); // 不知为何要等
+        });
+    },
+);
+
+api.get(
+    '/threads/:thread_id/runs',
+    zValidator('param', z.object({ thread_id: z.string().uuid() })),
+    zValidator(
+        'query',
+        z.object({
+            limit: z.string().optional(),
+            offset: z.string().optional(),
+            status: z.enum(['pending', 'running', 'error', 'success', 'timeout', 'interrupted']).optional(),
+        }),
+    ),
+    async (c) => {
+        const { thread_id } = c.req.valid('param');
+        const { limit, offset, status } = c.req.valid('query');
+        const runs = await client.runs.list(thread_id, { limit: Number(limit), offset: Number(offset), status });
+        return c.json(runs);
+    },
+);
+
+api.post(
+    '/threads/:thread_id/runs/:run_id/cancel',
+    zValidator('param', z.object({ thread_id: z.string().uuid(), run_id: z.string().uuid() })),
+    zValidator(
+        'query',
+        z.object({
+            wait: z.coerce.boolean().optional().default(false),
+            action: z.enum(['interrupt', 'rollback']).optional().default('interrupt'),
+        }),
+    ),
+    async (c) => {
+        // Cancel Run Http
+        const { thread_id, run_id } = c.req.valid('param');
+        const { wait, action } = c.req.valid('query');
+        const cancel = client.runs.cancel(thread_id, run_id, wait, action);
+        if (wait) {
+            await cancel;
+        }
+        return c.body(null, wait ? 204 : 202);
+    },
+);
+
+export default api;

package/src/adapter/hono/threads.ts

@@ -0,0 +1,92 @@
+import { zValidator } from '@hono/zod-validator';
+import { Hono } from 'hono';
+import { z } from 'zod';
+import { client } from './endpoint';
+import { CommandSchema, MetadataSchema } from './zod';
+
+const api = new Hono();
+
+// Threads Routes
+api.post(
+    '/threads',
+    zValidator(
+        'json',
+        z
+            .object({
+                // supersteps: z
+                //     .array(
+                //         z.object({
+                //             updates: z.array(
+                //                 z.object({
+                //                     values: z.unknown(),
+                //                     command: CommandSchema.optional(),
+                //                     as_node: z.string(),
+                //                 }),
+                //             ),
+                //         }),
+                //     )
+                //     .describe('The supersteps to apply to the thread.')
+                //     .optional(),
+                thread_id: z
+                    .string()
+                    .uuid()
+                    .describe('The ID of the thread. If not provided, an ID is generated.')
+                    .optional(),
+                metadata: MetadataSchema.optional(),
+                if_exists: z.union([z.literal('raise'), z.literal('do_nothing')]).optional(),
+            })
+            .describe('Payload for creating a thread.'),
+    ),
+    async (c) => {
+        const payload = c.req.valid('json');
+        const thread = await client.threads.create(payload);
+
+        return c.json(thread);
+    },
+);
+
+api.post(
+    '/threads/search',
+    zValidator(
+        'json',
+        z
+            .object({
+                metadata: z.record(z.unknown()).describe('Metadata to search for.').optional(),
+                status: z
+                    .enum(['idle', 'busy', 'interrupted', 'error'])
+                    .describe('Filter by thread status.')
+                    .optional(),
+                values: z.record(z.unknown()).describe('Filter by thread values.').optional(),
+                limit: z.number().int().gte(1).lte(1000).describe('Maximum number to return.').optional(),
+                offset: z.number().int().gte(0).describe('Offset to start from.').optional(),
+                sort_by: z
+                    .enum(['thread_id', 'status', 'created_at', 'updated_at'])
+                    .describe('Sort by field.')
+                    .optional(),
+                sort_order: z.enum(['asc', 'desc']).describe('Sort order.').optional(),
+            })
+            .describe('Payload for listing threads.'),
+    ),
+    async (c) => {
+        // Search Threads
+        const payload = c.req.valid('json');
+        const result = await client.threads.search(payload as any);
+        c.res.headers.set('X-Pagination-Total', result.length.toString());
+        return c.json(result);
+    },
+);
+
+api.get('/threads/:thread_id', zValidator('param', z.object({ thread_id: z.string().uuid() })), async (c) => {
+    // Get Thread
+    const { thread_id } = c.req.valid('param');
+    return c.json(await client.threads.get(thread_id));
+});
+
+api.delete('/threads/:thread_id', zValidator('param', z.object({ thread_id: z.string().uuid() })), async (c) => {
+    // Delete Thread
+    const { thread_id } = c.req.valid('param');
+    await client.threads.delete(thread_id);
+    return new Response(null, { status: 204 });
+});
+
+export default api;

package/src/adapter/hono/zod.ts

@@ -0,0 +1,49 @@
+import z from 'zod';
+
+export const AssistantConfigurable = z
+    .object({
+        thread_id: z.string().optional(),
+        thread_ts: z.string().optional(),
+    })
+    .catchall(z.unknown());
+
+export const AssistantConfig = z
+    .object({
+        tags: z.array(z.string()).optional(),
+        recursion_limit: z.number().int().optional(),
+        configurable: AssistantConfigurable.optional(),
+    })
+    .catchall(z.unknown())
+    .describe('The configuration of an assistant.');
+
+export const Assistant = z.object({
+    assistant_id: z.string().uuid(),
+    graph_id: z.string(),
+    config: AssistantConfig,
+    created_at: z.string(),
+    updated_at: z.string(),
+    metadata: z.object({}).catchall(z.any()),
+});
+
+export const MetadataSchema = z
+    .object({
+        source: z.union([z.literal('input'), z.literal('loop'), z.literal('update'), z.string()]).optional(),
+        step: z.number().optional(),
+        writes: z.record(z.unknown()).nullable().optional(),
+        parents: z.record(z.string()).optional(),
+    })
+    .catchall(z.unknown());
+
+export const SendSchema = z.object({
+    node: z.string(),
+    input: z.unknown().nullable(),
+});
+
+export const CommandSchema = z.object({
+    update: z
+        .union([z.record(z.unknown()), z.array(z.tuple([z.string(), z.unknown()]))])
+        .nullable()
+        .optional(),
+    resume: z.unknown().optional(),
+    goto: z.union([SendSchema, z.array(SendSchema), z.string(), z.array(z.string())]).optional(),
+});

package/src/createEndpoint.ts

@@ -0,0 +1,106 @@
+import { StreamEvent } from '@langchain/core/tracers/log_stream';
+import { streamState } from './graph/stream.js';
+import { Assistant, Run, StreamMode, Metadata, AssistantGraph } from '@langchain/langgraph-sdk';
+import { getGraph, GRAPHS } from './utils/getGraph.js';
+import { BaseThreadsManager } from './threads/index.js';
+import { globalMessageQueue } from './global.js';
+import { AssistantSortBy, CancelAction, ILangGraphClient, RunStatus, SortOrder, StreamInputData } from './types.js';
+export { registerGraph } from './utils/getGraph.js';
+
+export const AssistantEndpoint: ILangGraphClient['assistants'] = {
+    async search(query?: {
+        graphId?: string;
+        metadata?: Metadata;
+        limit?: number;
+        offset?: number;
+        sortBy?: AssistantSortBy;
+        sortOrder?: SortOrder;
+    }): Promise<Assistant[]> {
+        if (query?.graphId) {
+            return [
+                {
+                    assistant_id: query.graphId,
+                    graph_id: query.graphId,
+                    config: {},
+                    created_at: new Date().toISOString(),
+                    updated_at: new Date().toISOString(),
+                    metadata: {},
+                    version: 1,
+                    name: query.graphId,
+                    description: '',
+                } as Assistant,
+            ];
+        }
+        return Object.entries(GRAPHS).map(
+            ([graphId, _]) =>
+                ({
+                    assistant_id: graphId,
+                    graph_id: graphId,
+                    config: {},
+                    metadata: {},
+                    version: 1,
+                    name: graphId,
+                    description: '',
+                    created_at: new Date().toISOString(),
+                    updated_at: new Date().toISOString(),
+                } as Assistant),
+        );
+    },
+    async getGraph(assistantId: string, options?: { xray?: boolean | number }): Promise<AssistantGraph> {
+        const config = {};
+        const graph = await getGraph(assistantId, config);
+        const drawable = await graph.getGraphAsync({
+            ...config,
+            xray: options?.xray ?? undefined,
+        });
+        return drawable.toJSON() as AssistantGraph;
+    },
+};
+
+export const createEndpoint = (threads: BaseThreadsManager): ILangGraphClient => {
+    return {
+        assistants: AssistantEndpoint,
+        threads,
+        runs: {
+            list(threadId: string, options?: { limit?: number; offset?: number; status?: RunStatus }): Promise<Run[]> {
+                return threads.listRuns(threadId, options);
+            },
+            async cancel(threadId: string, runId: string, wait?: boolean, action?: CancelAction): Promise<void> {
+                return globalMessageQueue.cancelQueue(runId);
+            },
+            async *stream(threadId: string, assistantId: string, payload: StreamInputData) {
+                if (!payload.config) {
+                    payload.config = {
+                        configurable: {
+                            graph_id: assistantId,
+                            thread_id: threadId,
+                        },
+                    };
+                }
+
+                const run = threads.createRun(threadId, assistantId, payload);
+
+                for await (const data of streamState(threads, run, payload, {
+                    attempt: 0,
+                    getGraph,
+                })) {
+                    yield data;
+                }
+            },
+            joinStream(
+                threadId: string,
+                runId: string,
+                options?:
+                    | {
+                          signal?: AbortSignal;
+                          cancelOnDisconnect?: boolean;
+                          lastEventId?: string;
+                          streamMode?: StreamMode | StreamMode[];
+                      }
+                    | AbortSignal,
+            ): AsyncGenerator<{ id?: string; event: StreamEvent; data: any }> {
+                throw new Error('Function not implemented.');
+            },
+        },
+    };
+};

package/src/global.ts

@@ -0,0 +1,6 @@
+import { createCheckPointer, createMessageQueue } from './storage/index.js';
+
+/** 全局队列管理器 */
+export const globalMessageQueue = createMessageQueue();
+/** 全局 Checkpointer */
+export const globalCheckPointer = createCheckPointer();