@langgraph-js/pure-graph 1.3.0 → 1.4.0

package/README.md

@@ -1,6 +1,13 @@
 # Pure Graph
 
-Pure Graph is a library that provides a standard LangGraph endpoint for integrating into various frameworks like NextJS and Hono.js. This document will guide you on how to use Pure Graph in your projects.
+Pure Graph is a library that provides a standard LangGraph endpoint for integrating into various frameworks like NextJS and Hono.js. It supports multiple storage backends (SQLite, PostgreSQL, Redis) and message queues. This document will guide you on how to use Pure Graph in your projects.
+
+## Features
+
+-   **Multiple Storage Backends**: Support for SQLite, PostgreSQL, Redis, and in-memory storage
+-   **Message Queue**: Redis-based stream queue with TTL support
+-   **Thread Management**: Comprehensive thread lifecycle management with status tracking
+-   **Framework Integration**: Native support for Next.js and Hono.js frameworks
 
 ## Installation
 
@@ -84,27 +91,28 @@ To integrate Pure Graph into a Hono.js project, follow these steps:
 
 Here are the environment variables you need to configure:
 
-- `SQLITE_DATABASE_URI`: Path to your SQLite database.
-- `CHECKPOINT_TYPE`: Type of checkpoint storage (e.g., `postgres`, `redis`, `shallow/redis`).
-- `REDIS_URL`: URL for Redis (required if using Redis).
+-   `SQLITE_DATABASE_URI`: Path to your SQLite database (e.g., `./.langgraph_api/chat.db`).
+-   `DATABASE_URL`: PostgreSQL connection string (required for PostgreSQL checkpoint storage).
+-   `CHECKPOINT_TYPE`: Type of checkpoint storage (optional, defaults to memory; options: `postgres`, `redis`, `shallow/redis`).
+-   `REDIS_URL`: URL for Redis (required if using Redis checkpoint or message queue).
 
 ## API Endpoints
 
 ### Assistants
 
-- **GET /assistants**: Search for assistants.
-- **GET /assistants/{assistantId}**: Retrieve a specific assistant graph.
+-   **GET /assistants**: Search for assistants.
+-   **GET /assistants/{assistantId}**: Retrieve a specific assistant graph.
 
 ### Threads
 
-- **POST /threads**: Create a new thread.
-- **GET /threads**: Search for threads.
-- **GET /threads/{threadId}**: Retrieve a specific thread.
-- **DELETE /threads/{threadId}**: Delete a specific thread.
+-   **POST /threads**: Create a new thread.
+-   **GET /threads**: Search for threads.
+-   **GET /threads/{threadId}**: Retrieve a specific thread.
+-   **DELETE /threads/{threadId}**: Delete a specific thread.
 
 ### Runs
 
-- **GET /threads/{threadId}/runs**: List runs in a thread.
-- **POST /threads/{threadId}/runs**: Create a new run.
-- **DELETE /threads/{threadId}/runs/{runId}**: Cancel a specific run.
-- **GET /threads/{threadId}/runs/{runId}/stream**: Stream run data.
+-   **GET /threads/{threadId}/runs**: List runs in a thread.
+-   **POST /threads/{threadId}/runs**: Create a new run.
+-   **DELETE /threads/{threadId}/runs/{runId}**: Cancel a specific run.
+-   **GET /threads/{threadId}/runs/{runId}/stream**: Stream run data.

package/dist/adapter/nextjs/router.js

@@ -39,7 +39,7 @@ export async function GET(req) {
         const match = pathname.match(/\/assistants\/([^/]+)\/graph$/);
         if (match) {
             const assistant_id = match[1];
-            const xrayParam = url.searchParams.get('xray');
+            const xrayParam = url.searchParams.get('xray') ?? undefined;
             const queryParams = { xray: xrayParam };
             const { xray } = AssistantGraphQuerySchema.parse(queryParams);
             const data = await client.assistants.getGraph(assistant_id, {
@@ -62,9 +62,9 @@ export async function GET(req) {
         const match = pathname.match(/\/threads\/([0-9a-fA-F-]{36})\/runs$/);
         if (match) {
             const thread_id = match[1];
-            const limit = url.searchParams.get('limit');
-            const offset = url.searchParams.get('offset');
-            const status = url.searchParams.get('status');
+            const limit = url.searchParams.get('limit') ?? undefined;
+            const offset = url.searchParams.get('offset') ?? undefined;
+            const status = url.searchParams.get('status') ?? undefined;
             const queryParams = { limit, offset, status };
             const { limit: parsedLimit, offset: parsedOffset, status: parsedStatus, } = RunListQuerySchema.parse(queryParams);
             const runs = await client.runs.list(thread_id, {
@@ -148,8 +148,8 @@ export async function POST(req) {
         if (match) {
             const thread_id = match[1];
             const run_id = match[2];
-            const waitParam = url.searchParams.get('wait');
-            const actionParam = url.searchParams.get('action');
+            const waitParam = url.searchParams.get('wait') ?? undefined;
+            const actionParam = url.searchParams.get('action') ?? undefined;
             const queryParams = {
                 wait: waitParam ? waitParam === 'true' : false,
                 action: actionParam ?? 'interrupt',

package/dist/global.d.ts

@@ -1,6 +1,7 @@
 import type { SqliteSaver } from './storage/sqlite/checkpoint.js';
+import type { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
 export declare class LangGraphGlobal {
     static globalMessageQueue: import("./queue/stream_queue.js").StreamQueueManager<import("./queue/stream_queue.js").BaseStreamQueueInterface>;
-    static globalCheckPointer: import("@langchain/langgraph-checkpoint-redis").RedisSaver | import("@langchain/langgraph-checkpoint-redis/shallow").ShallowRedisSaver | SqliteSaver | import("@langchain/langgraph-checkpoint").MemorySaver;
-    static globalThreadsManager: import("./storage/sqlite/threads.js").SQLiteThreadsManager<unknown> | import("./storage/memory/threads.js").MemoryThreadsManager<unknown>;
+    static globalCheckPointer: import("@langchain/langgraph-checkpoint-redis").RedisSaver | import("@langchain/langgraph-checkpoint-redis/shallow").ShallowRedisSaver | PostgresSaver | SqliteSaver | import("@langchain/langgraph-checkpoint").MemorySaver;
+    static globalThreadsManager: import("./storage/pg/threads.js").PostgresThreadsManager<unknown> | import("./storage/sqlite/threads.js").SQLiteThreadsManager<unknown> | import("./storage/memory/threads.js").MemoryThreadsManager<unknown>;
 }

package/dist/storage/index.d.ts

@@ -2,9 +2,10 @@ import { BaseStreamQueueInterface, StreamQueueManager } from '../queue/stream_qu
 import { MemorySaver } from './memory/checkpoint';
 import { MemoryThreadsManager } from './memory/threads';
 import type { SqliteSaver as SqliteSaverType } from './sqlite/checkpoint';
+import type { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
 import { SQLiteThreadsManager } from './sqlite/threads';
-export declare const createCheckPointer: () => Promise<import("@langchain/langgraph-checkpoint-redis").RedisSaver | import("@langchain/langgraph-checkpoint-redis/shallow").ShallowRedisSaver | SqliteSaverType | MemorySaver>;
+export declare const createCheckPointer: () => Promise<import("@langchain/langgraph-checkpoint-redis").RedisSaver | import("@langchain/langgraph-checkpoint-redis/shallow").ShallowRedisSaver | PostgresSaver | SqliteSaverType | MemorySaver>;
 export declare const createMessageQueue: () => Promise<StreamQueueManager<BaseStreamQueueInterface>>;
 export declare const createThreadManager: (config: {
-    checkpointer?: SqliteSaverType;
-}) => SQLiteThreadsManager<unknown> | MemoryThreadsManager<unknown>;
+    checkpointer?: SqliteSaverType | PostgresSaver;
+}) => Promise<import("./pg/threads").PostgresThreadsManager<unknown> | SQLiteThreadsManager<unknown> | MemoryThreadsManager<unknown>>;

package/dist/storage/index.js

@@ -8,6 +8,7 @@ export const createCheckPointer = async () => {
     if ((process.env.REDIS_URL && process.env.CHECKPOINT_TYPE === 'redis') ||
         process.env.CHECKPOINT_TYPE === 'shallow/redis') {
         if (process.env.CHECKPOINT_TYPE === 'redis') {
+            console.log('Using redis as checkpoint');
             const { RedisSaver } = await import('@langchain/langgraph-checkpoint-redis');
             return await RedisSaver.fromUrl(process.env.REDIS_URL, {
                 defaultTTL: 60, // TTL in minutes
@@ -15,11 +16,18 @@ export const createCheckPointer = async () => {
             });
         }
         if (process.env.CHECKPOINT_TYPE === 'shallow/redis') {
+            console.log('Using shallow redis as checkpoint');
             const { ShallowRedisSaver } = await import('@langchain/langgraph-checkpoint-redis/shallow');
             return await ShallowRedisSaver.fromUrl(process.env.REDIS_URL);
         }
     }
+    if (process.env.DATABASE_URL) {
+        console.log('Using postgres as checkpoint');
+        const { createPGCheckpoint } = await import('./pg/checkpoint');
+        return createPGCheckpoint();
+    }
     if (process.env.SQLITE_DATABASE_URI) {
+        console.log('Using sqlite as checkpoint');
         const { SqliteSaver } = await import('./sqlite/checkpoint');
         const db = SqliteSaver.fromConnString(process.env.SQLITE_DATABASE_URI);
         return db;
@@ -38,7 +46,11 @@ export const createMessageQueue = async () => {
     }
     return new StreamQueueManager(q);
 };
-export const createThreadManager = (config) => {
+export const createThreadManager = async (config) => {
+    if (process.env.DATABASE_URL && config.checkpointer) {
+        const { PostgresThreadsManager } = await import('./pg/threads');
+        return new PostgresThreadsManager(config.checkpointer);
+    }
     if (process.env.SQLITE_DATABASE_URI && config.checkpointer) {
         return new SQLiteThreadsManager(config.checkpointer);
     }

package/dist/storage/pg/checkpoint.d.ts

@@ -0,0 +1,2 @@
+import { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
+export declare const createPGCheckpoint: () => Promise<PostgresSaver>;

package/dist/storage/pg/checkpoint.js

@@ -0,0 +1,9 @@
+import { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
+export const createPGCheckpoint = async () => {
+    const checkpointer = PostgresSaver.fromConnString(process.env.DATABASE_URL);
+    if (process.env.DATABASE_INIT === 'true') {
+        console.log('Initializing postgres checkpoint');
+        await checkpointer.setup();
+    }
+    return checkpointer;
+};

package/dist/storage/pg/threads.d.ts

@@ -0,0 +1,43 @@
+import { BaseThreadsManager } from '../../threads/index.js';
+import { Command, Config, Metadata, OnConflictBehavior, Run, RunStatus, SortOrder, Thread, ThreadSortBy, ThreadStatus } from '@langgraph-js/sdk';
+import type { PostgresSaver } from '@langchain/langgraph-checkpoint-postgres';
+export declare class PostgresThreadsManager<ValuesType = unknown> implements BaseThreadsManager<ValuesType> {
+    private pool;
+    private isSetup;
+    constructor(checkpointer: PostgresSaver);
+    private setup;
+    create(payload?: {
+        metadata?: Metadata;
+        threadId?: string;
+        ifExists?: OnConflictBehavior;
+        graphId?: string;
+        supersteps?: Array<{
+            updates: Array<{
+                values: unknown;
+                command?: Command;
+                asNode: string;
+            }>;
+        }>;
+    }): Promise<Thread<ValuesType>>;
+    search(query?: {
+        metadata?: Metadata;
+        limit?: number;
+        offset?: number;
+        status?: ThreadStatus;
+        sortBy?: ThreadSortBy;
+        sortOrder?: SortOrder;
+    }): Promise<Thread<ValuesType>[]>;
+    get(threadId: string): Promise<Thread<ValuesType>>;
+    set(threadId: string, thread: Partial<Thread<ValuesType>>): Promise<void>;
+    updateState(threadId: string, thread: Partial<Thread<ValuesType>>): Promise<Pick<Config, 'configurable'>>;
+    delete(threadId: string): Promise<void>;
+    createRun(threadId: string, assistantId: string, payload?: {
+        metadata?: Metadata;
+    }): Promise<Run>;
+    listRuns(threadId: string, options?: {
+        limit?: number;
+        offset?: number;
+        status?: RunStatus;
+    }): Promise<Run[]>;
+    updateRun(runId: string, run: Partial<Run>): Promise<void>;
+}

package/dist/storage/pg/threads.js

@@ -0,0 +1,304 @@
+import { getGraph } from '../../utils/getGraph.js';
+import { serialiseAsDict } from '../../graph/stream.js';
+export class PostgresThreadsManager {
+    pool;
+    isSetup = false;
+    constructor(checkpointer) {
+        // 访问 PostgresSaver 的 pool 属性（虽然是 private，但在运行时可以访问）
+        this.pool = checkpointer.pool;
+        this.setup();
+    }
+    async setup() {
+        if (this.isSetup) {
+            return;
+        }
+        // 创建 threads 表
+        await this.pool.query(`
+            CREATE TABLE IF NOT EXISTS threads (
+                thread_id TEXT PRIMARY KEY,
+                created_at TIMESTAMP NOT NULL,
+                updated_at TIMESTAMP NOT NULL,
+                metadata JSONB NOT NULL DEFAULT '{}',
+                status TEXT NOT NULL DEFAULT 'idle',
+                "values" JSONB,
+                interrupts JSONB NOT NULL DEFAULT '{}'
+            )
+        `);
+        // 创建 runs 表
+        await this.pool.query(`
+            CREATE TABLE IF NOT EXISTS runs (
+                run_id TEXT PRIMARY KEY,
+                thread_id TEXT NOT NULL,
+                assistant_id TEXT NOT NULL,
+                created_at TIMESTAMP NOT NULL,
+                updated_at TIMESTAMP NOT NULL,
+                status TEXT NOT NULL DEFAULT 'pending',
+                metadata JSONB NOT NULL DEFAULT '{}',
+                multitask_strategy TEXT NOT NULL DEFAULT 'reject',
+                FOREIGN KEY (thread_id) REFERENCES threads(thread_id) ON DELETE CASCADE
+            )
+        `);
+        // 创建索引以提高查询性能
+        await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_threads_status ON threads(status)`);
+        await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_threads_created_at ON threads(created_at)`);
+        await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_threads_updated_at ON threads(updated_at)`);
+        await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_runs_thread_id ON runs(thread_id)`);
+        await this.pool.query(`CREATE INDEX IF NOT EXISTS idx_runs_status ON runs(status)`);
+        this.isSetup = true;
+    }
+    async create(payload) {
+        const threadId = payload?.threadId || crypto.randomUUID();
+        // 检查线程是否已存在
+        if (payload?.ifExists === 'raise') {
+            const result = await this.pool.query('SELECT thread_id FROM threads WHERE thread_id = $1', [threadId]);
+            if (result.rows.length > 0) {
+                throw new Error(`Thread with ID ${threadId} already exists.`);
+            }
+        }
+        const now = new Date();
+        const metadata = payload?.metadata || {};
+        const interrupts = {};
+        const thread = {
+            thread_id: threadId,
+            created_at: now.toISOString(),
+            updated_at: now.toISOString(),
+            metadata,
+            status: 'idle',
+            values: null,
+            interrupts,
+        };
+        // 插入到数据库
+        await this.pool.query(`
+            INSERT INTO threads (thread_id, created_at, updated_at, metadata, status, "values", interrupts)
+            VALUES ($1, $2, $3, $4, $5, $6, $7)
+        `, [threadId, now, now, JSON.stringify(metadata), 'idle', null, JSON.stringify(interrupts)]);
+        return thread;
+    }
+    async search(query) {
+        let sql = 'SELECT * FROM threads';
+        const whereConditions = [];
+        const params = [];
+        let paramIndex = 1;
+        // 构建 WHERE 条件
+        if (query?.status) {
+            whereConditions.push(`status = $${paramIndex++}`);
+            params.push(query.status);
+        }
+        if (query?.metadata) {
+            for (const [key, value] of Object.entries(query.metadata)) {
+                whereConditions.push(`metadata->$${paramIndex} = $${paramIndex + 1}`);
+                params.push(key, JSON.stringify(value));
+                paramIndex += 2;
+            }
+        }
+        if (whereConditions.length > 0) {
+            sql += ' WHERE ' + whereConditions.join(' AND ');
+        }
+        // 添加排序
+        if (query?.sortBy) {
+            sql += ` ORDER BY ${query.sortBy}`;
+            if (query.sortOrder === 'desc') {
+                sql += ' DESC';
+            }
+            else {
+                sql += ' ASC';
+            }
+        }
+        // 添加分页
+        if (query?.limit) {
+            sql += ` LIMIT $${paramIndex++}`;
+            params.push(query.limit);
+            if (query?.offset) {
+                sql += ` OFFSET $${paramIndex++}`;
+                params.push(query.offset);
+            }
+        }
+        const result = await this.pool.query(sql, params);
+        return result.rows.map((row) => ({
+            thread_id: row.thread_id,
+            created_at: new Date(row.created_at).toISOString(),
+            updated_at: new Date(row.updated_at).toISOString(),
+            metadata: row.metadata,
+            status: row.status,
+            values: row.values || null,
+            interrupts: row.interrupts,
+        }));
+    }
+    async get(threadId) {
+        const result = await this.pool.query('SELECT * FROM threads WHERE thread_id = $1', [threadId]);
+        if (result.rows.length === 0) {
+            throw new Error(`Thread with ID ${threadId} not found.`);
+        }
+        const row = result.rows[0];
+        return {
+            thread_id: row.thread_id,
+            created_at: new Date(row.created_at).toISOString(),
+            updated_at: new Date(row.updated_at).toISOString(),
+            metadata: row.metadata,
+            status: row.status,
+            values: row.values || null,
+            interrupts: row.interrupts,
+        };
+    }
+    async set(threadId, thread) {
+        // 检查线程是否存在
+        const existingThread = await this.pool.query('SELECT thread_id FROM threads WHERE thread_id = $1', [threadId]);
+        if (existingThread.rows.length === 0) {
+            throw new Error(`Thread with ID ${threadId} not found.`);
+        }
+        const updateFields = [];
+        const values = [];
+        let paramIndex = 1;
+        if (thread.metadata !== undefined) {
+            updateFields.push(`metadata = $${paramIndex++}`);
+            values.push(JSON.stringify(thread.metadata));
+        }
+        if (thread.status !== undefined) {
+            updateFields.push(`status = $${paramIndex++}`);
+            values.push(thread.status);
+        }
+        if (thread.values !== undefined) {
+            updateFields.push(`"values" = $${paramIndex++}`);
+            values.push(thread.values ? JSON.stringify(thread.values) : null);
+        }
+        if (thread.interrupts !== undefined) {
+            updateFields.push(`interrupts = $${paramIndex++}`);
+            values.push(JSON.stringify(thread.interrupts));
+        }
+        // 总是更新 updated_at
+        updateFields.push(`updated_at = $${paramIndex++}`);
+        values.push(new Date());
+        if (updateFields.length > 0) {
+            values.push(threadId);
+            await this.pool.query(`
+                UPDATE threads 
+                SET ${updateFields.join(', ')} 
+                WHERE thread_id = $${paramIndex}
+            `, values);
+        }
+    }
+    async updateState(threadId, thread) {
+        // 从数据库查询线程信息
+        const result = await this.pool.query('SELECT * FROM threads WHERE thread_id = $1', [threadId]);
+        if (result.rows.length === 0) {
+            throw new Error(`Thread with ID ${threadId} not found.`);
+        }
+        const row = result.rows[0];
+        const targetThread = {
+            thread_id: row.thread_id,
+            created_at: new Date(row.created_at).toISOString(),
+            updated_at: new Date(row.updated_at).toISOString(),
+            metadata: row.metadata,
+            status: row.status,
+            values: row.values || null,
+            interrupts: row.interrupts,
+        };
+        if (targetThread.status === 'busy') {
+            throw new Error(`Thread with ID ${threadId} is busy, can't update state.`);
+        }
+        if (!targetThread.metadata?.graph_id) {
+            throw new Error(`Thread with ID ${threadId} has no graph_id.`);
+        }
+        const graphId = targetThread.metadata?.graph_id;
+        const config = {
+            configurable: {
+                thread_id: threadId,
+                graph_id: graphId,
+            },
+        };
+        const graph = await getGraph(graphId, config);
+        const nextConfig = await graph.updateState(config, thread.values);
+        const graphState = await graph.getState(config);
+        await this.set(threadId, { values: JSON.parse(serialiseAsDict(graphState.values)) });
+        return nextConfig;
+    }
+    async delete(threadId) {
+        const result = await this.pool.query('DELETE FROM threads WHERE thread_id = $1', [threadId]);
+        if (result.rowCount === 0) {
+            throw new Error(`Thread with ID ${threadId} not found.`);
+        }
+    }
+    async createRun(threadId, assistantId, payload) {
+        const runId = crypto.randomUUID();
+        const now = new Date();
+        const metadata = payload?.metadata ?? {};
+        const run = {
+            run_id: runId,
+            thread_id: threadId,
+            assistant_id: assistantId,
+            created_at: now.toISOString(),
+            updated_at: now.toISOString(),
+            status: 'pending',
+            metadata,
+            multitask_strategy: 'reject',
+        };
+        // 插入到数据库
+        await this.pool.query(`
+            INSERT INTO runs (run_id, thread_id, assistant_id, created_at, updated_at, status, metadata, multitask_strategy)
+            VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+        `, [runId, threadId, assistantId, now, now, 'pending', JSON.stringify(metadata), 'reject']);
+        return run;
+    }
+    async listRuns(threadId, options) {
+        let sql = 'SELECT * FROM runs WHERE thread_id = $1';
+        const params = [threadId];
+        let paramIndex = 2;
+        if (options?.status) {
+            sql += ` AND status = $${paramIndex++}`;
+            params.push(options.status);
+        }
+        sql += ' ORDER BY created_at DESC';
+        if (options?.limit) {
+            sql += ` LIMIT $${paramIndex++}`;
+            params.push(options.limit);
+            if (options?.offset) {
+                sql += ` OFFSET $${paramIndex++}`;
+                params.push(options.offset);
+            }
+        }
+        const result = await this.pool.query(sql, params);
+        return result.rows.map((row) => ({
+            run_id: row.run_id,
+            thread_id: row.thread_id,
+            assistant_id: row.assistant_id,
+            created_at: new Date(row.created_at).toISOString(),
+            updated_at: new Date(row.updated_at).toISOString(),
+            status: row.status,
+            metadata: row.metadata,
+            multitask_strategy: row.multitask_strategy,
+        }));
+    }
+    async updateRun(runId, run) {
+        // 检查运行是否存在
+        const existingRun = await this.pool.query('SELECT run_id FROM runs WHERE run_id = $1', [runId]);
+        if (existingRun.rows.length === 0) {
+            throw new Error(`Run with ID ${runId} not found.`);
+        }
+        const updateFields = [];
+        const values = [];
+        let paramIndex = 1;
+        if (run.status !== undefined) {
+            updateFields.push(`status = $${paramIndex++}`);
+            values.push(run.status);
+        }
+        if (run.metadata !== undefined) {
+            updateFields.push(`metadata = $${paramIndex++}`);
+            values.push(JSON.stringify(run.metadata));
+        }
+        if (run.multitask_strategy !== undefined) {
+            updateFields.push(`multitask_strategy = $${paramIndex++}`);
+            values.push(run.multitask_strategy);
+        }
+        // 总是更新 updated_at
+        updateFields.push(`updated_at = $${paramIndex++}`);
+        values.push(new Date());
+        if (updateFields.length > 0) {
+            values.push(runId);
+            await this.pool.query(`
+                UPDATE runs 
+                SET ${updateFields.join(', ')} 
+                WHERE run_id = $${paramIndex}
+            `, values);
+        }
+    }
+}