@langgraph-js/pure-graph 1.3.0 → 1.4.1

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
 
@@ -20,6 +27,25 @@ yarn add @langgraph-js/pure-graph
 
 ### Next.js Example
 
+```text
+my-nextjs-app/
+├── app/
+│   ├── api/
+│   │   └── langgraph/
+│   │       └── [...path]/
+│   │           └── route.ts      # LangGraph API endpoint
+│   ├── layout.tsx                # Root layout
+│   └── page.tsx                  # Your page
+├── agent/
+│   └── graph-name/
+│       ├── graph.ts              # Main graph implementation
+│       ├── state.ts              # Graph state definitions
+│       └── prompt.ts             # Prompt templates
+├── .env.local                    # Environment variables
+├── package.json                  # Dependencies and scripts
+└── tsconfig.json                 # TypeScript configuration
+```
+
 To integrate Pure Graph into a Next.js project, follow these steps:
 
 1. **Create a Route Handler**
@@ -30,7 +56,7 @@ To integrate Pure Graph into a Next.js project, follow these steps:
     // app/api/langgraph/[...path]/route.ts
     import { GET, POST, DELETE } from '@langgraph-js/pure-graph/dist/adapter/nextjs/router.js';
     import { registerGraph } from '@langgraph-js/pure-graph';
-    import { graph } from './path/to/your/graph'; // Replace with your graph implementation
+    import { graph } from '../../../agent/graph-name/graph';
 
     registerGraph('test', graph);
 
@@ -58,7 +84,7 @@ To integrate Pure Graph into a Hono.js project, follow these steps:
     ```js
     // app.js
     import { registerGraph } from '@langgraph-js/pure-graph';
-    import { graph } from './path/to/your/graph'; // Replace with your graph implementation
+    import { graph } from './agent/graph-name/graph';
     import { Hono } from 'hono';
     import LangGraphApp from '@langgraph-js/pure-graph/dist/adapter/hono/index';
 
@@ -84,27 +110,165 @@ 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).
+-   `DATABASE_INIT`: Set to `true` for initial PostgreSQL database setup (required only on first run with PostgreSQL).
+-   `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).
+
+## Persistence Configuration
+
+Pure Graph supports multiple storage backends for persisting graph state, checkpoints, and thread data. Choose the appropriate storage type based on your requirements for scalability, persistence, and performance.
+
+### Memory Storage (Default)
+
+**Best for**: Development, testing, or stateless applications.
+
+**Configuration**:
+
+```bash
+# No additional configuration required - this is the default
+```
+
+**Characteristics**:
+
+-   Fastest performance
+-   No persistence across restarts
+-   Data is lost when the application stops
+-   Suitable for development and testing
+
+### SQLite Storage
+
+**Best for**: Single-server applications, development, or small-scale production.
+
+**Configuration**:
+
+```bash
+SQLITE_DATABASE_URI=./.langgraph_api/chat.db
+```
+
+**Setup**:
+
+```bash
+# Create the database directory
+mkdir -p .langgraph_api
+
+# The database file will be created automatically on first run
+```
+
+**Characteristics**:
+
+-   File-based database
+-   Good performance for moderate workloads
+-   ACID compliant
+-   Single-writer limitation
+
+### PostgreSQL Storage
+
+**Best for**: Production applications requiring high reliability and scalability.
+
+**Configuration**:
+
+```bash
+DATABASE_URL=postgresql://username:password@localhost:5432/langgraph_db
+DATABASE_INIT=true  # Only needed for initial setup
+CHECKPOINT_TYPE=postgres
+```
+
+**Setup**:
+
+```bash
+# First run with DATABASE_INIT=true to create tables
+export DATABASE_INIT=true
+# Run your application once to initialize the database
+
+# Remove DATABASE_INIT for subsequent runs
+unset DATABASE_INIT
+```
+
+**Characteristics**:
+
+-   Full ACID compliance
+-   Concurrent access support
+-   Scalable for high-throughput applications
+-   Requires PostgreSQL server setup
+
+### Redis Storage
+
+Pure Graph supports two Redis checkpoint modes:
+
+#### Full Redis Checkpoint
+
+**Best for**: High-performance caching with full persistence.
+
+**Configuration**:
+
+```bash
+REDIS_URL=redis://localhost:6379
+CHECKPOINT_TYPE=redis
+```
+
+#### Shallow Redis Checkpoint
+
+**Best for**: Memory-efficient Redis usage with lighter persistence.
+
+**Configuration**:
+
+```bash
+REDIS_URL=redis://localhost:6379
+CHECKPOINT_TYPE=shallow/redis
+```
+
+**Characteristics**:
+
+-   High performance
+-   TTL-based automatic cleanup
+-   Distributed caching capabilities
+-   Requires Redis server setup
+
+### Redis Message Queue
+
+When using Redis, message queues are automatically enabled for better performance:
+
+**Configuration**:
+
+```bash
+REDIS_URL=redis://localhost:6379
+# Message queues will use Redis automatically when REDIS_URL is set
+```
+
+**Characteristics**:
+
+-   Automatic TTL management (300 seconds)
+-   Improved streaming performance
+-   Better resource utilization
+
+### Configuration Priority
+
+Storage backends are selected in this priority order:
+
+1. **Redis** (if `REDIS_URL` set and `CHECKPOINT_TYPE` matches)
+2. **PostgreSQL** (if `DATABASE_URL` set)
+3. **SQLite** (if `SQLITE_DATABASE_URI` set)
+4. **Memory** (fallback default)
 
 ## 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: SqliteSaver | PostgresSaver | import("@langchain/langgraph-checkpoint-redis").RedisSaver | import("@langchain/langgraph-checkpoint-redis/shallow").ShallowRedisSaver | 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/global.js

@@ -1,8 +1,11 @@
 import { createCheckPointer, createMessageQueue, createThreadManager } from './storage/index.js';
 const [globalMessageQueue, globalCheckPointer] = await Promise.all([createMessageQueue(), createCheckPointer()]);
+console.debug('LG | checkpointer created');
 const globalThreadsManager = await createThreadManager({
     checkpointer: globalCheckPointer,
 });
+console.debug('LG | threads manager created');
+console.debug('LG | global init done');
 export class LangGraphGlobal {
     static globalMessageQueue = globalMessageQueue;
     static globalCheckPointer = globalCheckPointer;

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<SqliteSaverType | PostgresSaver | import("@langchain/langgraph-checkpoint-redis").RedisSaver | import("@langchain/langgraph-checkpoint-redis/shallow").ShallowRedisSaver | 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.debug('LG | 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.debug('LG | 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.debug('LG | Using postgres as checkpoint');
+        const { createPGCheckpoint } = await import('./pg/checkpoint');
+        return createPGCheckpoint();
+    }
     if (process.env.SQLITE_DATABASE_URI) {
+        console.debug('LG | Using sqlite as checkpoint');
         const { SqliteSaver } = await import('./sqlite/checkpoint');
         const db = SqliteSaver.fromConnString(process.env.SQLITE_DATABASE_URI);
         return db;
@@ -29,7 +37,7 @@ export const createCheckPointer = async () => {
 export const createMessageQueue = async () => {
     let q;
     if (process.env.REDIS_URL) {
-        console.log('Using redis as stream queue');
+        console.debug('LG | Using redis as stream queue');
         const { RedisStreamQueue } = await import('./redis/queue');
         q = RedisStreamQueue;
     }
@@ -38,9 +46,19 @@ 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');
+        const threadsManager = new PostgresThreadsManager(config.checkpointer);
+        if (process.env.DATABASE_INIT === 'true') {
+            await threadsManager.setup();
+        }
+        return threadsManager;
+    }
     if (process.env.SQLITE_DATABASE_URI && config.checkpointer) {
-        return new SQLiteThreadsManager(config.checkpointer);
+        const threadsManager = new SQLiteThreadsManager(config.checkpointer);
+        await threadsManager.setup();
+        return threadsManager;
     }
     return new MemoryThreadsManager();
 };

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

@@ -2,6 +2,7 @@ import { BaseThreadsManager } from '../../threads/index.js';
 import { Command, Config, Metadata, OnConflictBehavior, Run, RunStatus, SortOrder, Thread, ThreadSortBy, ThreadStatus } from '@langgraph-js/sdk';
 export declare class MemoryThreadsManager<ValuesType = unknown> implements BaseThreadsManager<ValuesType> {
     private threads;
+    setup(): Promise<void>;
     create(payload?: {
         metadata?: Metadata;
         threadId?: string;

package/dist/storage/memory/threads.js

@@ -2,6 +2,9 @@ import { getGraph } from '../../utils/getGraph.js';
 import { serialiseAsDict } from '../../graph/stream.js';
 export class MemoryThreadsManager {
     threads = [];
+    async setup() {
+        return;
+    }
     async create(payload) {
         const threadId = payload?.threadId || crypto.randomUUID();
         if (payload?.ifExists === 'raise' && this.threads.some((t) => t.thread_id === threadId)) {

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.debug('LG | 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);
+    setup(): Promise<void>;
+    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>;
+}