@bowenqt/qiniu-ai-sdk 0.10.0 → 0.13.0

package/dist/ai/generate-text.mjs

@@ -304,4 +304,135 @@ function parseToolArguments(payload) {
         return payload;
     }
 }
+// ============================================================================
+// G2/G4: Graph-based generateText implementation
+// ============================================================================
+import { AgentGraph } from './agent-graph.mjs';
+/**
+ * Generate text using the AgentGraph runtime.
+ *
+ * Benefits over generateText:
+ * - Skills injection with automatic compaction
+ * - Node-level event hooks (onNodeEnter/onNodeExit)
+ * - Consistent event ordering (text→tool_call→tool_result)
+ * - JSON mode non-streaming fallback
+ *
+ * @example
+ * ```typescript
+ * const result = await generateTextWithGraph({
+ *   client,
+ *   model: 'deepseek-v3',
+ *   messages: [{ role: 'user', content: 'Hello' }],
+ *   skills: [await skillLoader.load('my-skill')],
+ *   onStepFinish: (step) => console.log(step),
+ * });
+ * ```
+ */
+export async function generateTextWithGraph(options) {
+    const { client, model, tools, skills, maxSteps = 10, maxContextTokens, onStepFinish, onNodeEnter, onNodeExit, abortSignal, temperature, topP, maxTokens, responseFormat, toolChoice, } = options;
+    // Normalize messages
+    const messages = normalizeMessages(options);
+    // Track current messages for tool context (will be updated during execution)
+    let currentMessages = [...messages];
+    // Convert tools to RegisteredTool format
+    // High fix: use convertToolParameters for Zod support and preserve required fields
+    const registeredTools = {};
+    if (tools) {
+        for (const [name, tool] of Object.entries(tools)) {
+            // Convert parameters using same logic as generateText
+            const convertedParams = convertToolParameters(tool.parameters);
+            registeredTools[name] = {
+                name,
+                description: tool.description || '',
+                parameters: {
+                    type: 'object',
+                    properties: convertedParams.properties || convertedParams,
+                    required: convertedParams.required,
+                },
+                source: { type: 'user', namespace: 'generateText' },
+                execute: tool.execute
+                    ? async (args, execContext) => {
+                        // Use context from execute-node (has real toolCallId), fallback to currentMessages
+                        const context = execContext
+                            ? {
+                                toolCallId: execContext.toolCallId,
+                                messages: execContext.messages,
+                                abortSignal: execContext.abortSignal,
+                            }
+                            : {
+                                toolCallId: '',
+                                messages: currentMessages,
+                                abortSignal,
+                            };
+                        return tool.execute(args, context);
+                    }
+                    : undefined,
+            };
+        }
+    }
+    // Track nodes visited
+    const nodesVisited = [];
+    // Create AgentGraph
+    const graph = new AgentGraph({
+        client,
+        model,
+        tools: registeredTools,
+        skills,
+        maxSteps,
+        maxContextTokens, // Pass through for compaction
+        temperature,
+        topP,
+        maxTokens,
+        responseFormat,
+        toolChoice,
+        abortSignal,
+        events: {
+            onStepFinish: (step) => {
+                if (onStepFinish) {
+                    // Convert internal StepResult to public StepResult
+                    const publicStep = {
+                        type: step.type,
+                        content: step.content,
+                        reasoning: step.reasoning,
+                        toolCalls: step.toolCalls,
+                        toolResults: step.toolResults?.map(r => ({
+                            toolCallId: r.toolCallId,
+                            result: r.result,
+                        })),
+                    };
+                    onStepFinish(publicStep);
+                }
+            },
+            onNodeEnter: (nodeName) => {
+                nodesVisited.push(nodeName);
+                onNodeEnter?.(nodeName);
+            },
+            onNodeExit: onNodeExit,
+        },
+    });
+    // Execute graph
+    const graphResult = await graph.invoke(messages);
+    // Build result
+    return {
+        text: graphResult.text,
+        reasoning: graphResult.reasoning,
+        steps: graphResult.steps.map(s => ({
+            type: s.type,
+            content: s.content,
+            reasoning: s.reasoning,
+            toolCalls: s.toolCalls,
+            toolResults: s.toolResults?.map(r => ({
+                toolCallId: r.toolCallId,
+                result: r.result,
+            })),
+        })),
+        usage: graphResult.usage,
+        finishReason: graphResult.finishReason,
+        graphInfo: {
+            nodesVisited,
+            skillsInjected: skills?.map(s => s.name) || [],
+            compaction: graphResult.compaction,
+        },
+    };
+}
 //# sourceMappingURL=generate-text.js.map

package/dist/ai/graph/checkpointer.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Checkpointer - State persistence for Graph execution.
+ *
+ * Provides save/load capabilities for resumable agent sessions.
+ */
+import type { AgentState } from '../internal-types';
+/**
+ * Checkpoint metadata.
+ */
+export interface CheckpointMetadata {
+    /** Unique checkpoint ID */
+    id: string;
+    /** Thread ID for grouping checkpoints */
+    threadId: string;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Step count at checkpoint */
+    stepCount: number;
+    /** Optional user-provided metadata */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Stored checkpoint data.
+ */
+export interface Checkpoint {
+    metadata: CheckpointMetadata;
+    /** Serialized state (JSON) */
+    state: SerializedAgentState;
+}
+/**
+ * Serialized agent state (JSON-safe).
+ * Note: Tools Map is converted to Record, non-serializable fields stripped.
+ */
+export interface SerializedAgentState {
+    messages: Array<{
+        role: string;
+        content: unknown;
+        tool_calls?: unknown[];
+        tool_call_id?: string;
+        _meta?: {
+            skillId?: string;
+            droppable?: boolean;
+        };
+    }>;
+    stepCount: number;
+    maxSteps: number;
+    done: boolean;
+    output: string;
+    reasoning: string;
+    finishReason: string | null;
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+/**
+ * Checkpointer interface.
+ */
+export interface Checkpointer {
+    /**
+     * Save a checkpoint.
+     */
+    save(threadId: string, state: AgentState, custom?: Record<string, unknown>): Promise<CheckpointMetadata>;
+    /**
+     * Load the latest checkpoint for a thread.
+     */
+    load(threadId: string): Promise<Checkpoint | null>;
+    /**
+     * List all checkpoints for a thread.
+     */
+    list(threadId: string): Promise<CheckpointMetadata[]>;
+    /**
+     * Delete a checkpoint.
+     */
+    delete(checkpointId: string): Promise<boolean>;
+    /**
+     * Clear all checkpoints for a thread.
+     */
+    clear(threadId: string): Promise<number>;
+}
+/**
+ * In-memory checkpointer implementation.
+ * Suitable for testing and short-lived sessions.
+ */
+export declare class MemoryCheckpointer implements Checkpointer {
+    private readonly checkpoints;
+    private readonly maxItems;
+    constructor(options?: {
+        maxItems?: number;
+    });
+    save(threadId: string, state: AgentState, custom?: Record<string, unknown>): Promise<CheckpointMetadata>;
+    load(threadId: string): Promise<Checkpoint | null>;
+    list(threadId: string): Promise<CheckpointMetadata[]>;
+    delete(checkpointId: string): Promise<boolean>;
+    clear(threadId: string): Promise<number>;
+    /**
+     * Serialize agent state to JSON-safe format.
+     * Strips non-serializable fields (abortSignal, tools Map).
+     */
+    private serializeState;
+    /**
+     * Cleanup old checkpoints to stay under maxItems.
+     */
+    private cleanup;
+}
+/**
+ * Deserialize checkpoint state back to AgentState.
+ * Note: Tools must be re-provided, abortSignal reset to undefined.
+ */
+export declare function deserializeCheckpoint(checkpoint: Checkpoint, tools?: Map<string, any>): AgentState;
+//# sourceMappingURL=checkpointer.d.ts.map

package/dist/ai/graph/checkpointer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpointer.d.ts","sourceRoot":"","sources":["../../../src/ai/graph/checkpointer.ts"],"names":[],"mappings":"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"}

package/dist/ai/graph/checkpointer.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * Checkpointer - State persistence for Graph execution.
+ *
+ * Provides save/load capabilities for resumable agent sessions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCheckpointer = void 0;
+exports.deserializeCheckpoint = deserializeCheckpoint;
+/**
+ * In-memory checkpointer implementation.
+ * Suitable for testing and short-lived sessions.
+ */
+class MemoryCheckpointer {
+    constructor(options) {
+        this.checkpoints = new Map();
+        this.maxItems = options?.maxItems ?? 100;
+    }
+    async save(threadId, state, custom) {
+        const id = `ckpt_${threadId}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const metadata = {
+            id,
+            threadId,
+            createdAt: Date.now(),
+            stepCount: state.stepCount,
+            custom,
+        };
+        const serialized = this.serializeState(state);
+        this.checkpoints.set(id, {
+            metadata,
+            state: serialized,
+        });
+        // Cleanup old checkpoints if over limit
+        await this.cleanup();
+        return metadata;
+    }
+    async load(threadId) {
+        // Find latest checkpoint for thread
+        let latest = null;
+        for (const checkpoint of this.checkpoints.values()) {
+            if (checkpoint.metadata.threadId === threadId) {
+                if (!latest || checkpoint.metadata.createdAt > latest.metadata.createdAt) {
+                    latest = checkpoint;
+                }
+            }
+        }
+        return latest;
+    }
+    async list(threadId) {
+        const result = [];
+        for (const checkpoint of this.checkpoints.values()) {
+            if (checkpoint.metadata.threadId === threadId) {
+                result.push(checkpoint.metadata);
+            }
+        }
+        return result.sort((a, b) => b.createdAt - a.createdAt);
+    }
+    async delete(checkpointId) {
+        return this.checkpoints.delete(checkpointId);
+    }
+    async clear(threadId) {
+        let count = 0;
+        for (const [id, checkpoint] of this.checkpoints) {
+            if (checkpoint.metadata.threadId === threadId) {
+                this.checkpoints.delete(id);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Serialize agent state to JSON-safe format.
+     * Strips non-serializable fields (abortSignal, tools Map).
+     */
+    serializeState(state) {
+        return {
+            messages: state.messages.map(msg => ({
+                role: msg.role,
+                content: msg.content,
+                tool_calls: msg.tool_calls,
+                tool_call_id: msg.tool_call_id,
+                _meta: msg._meta,
+            })),
+            stepCount: state.stepCount,
+            maxSteps: state.maxSteps,
+            done: state.done,
+            output: state.output,
+            reasoning: state.reasoning,
+            finishReason: state.finishReason,
+            usage: state.usage,
+        };
+    }
+    /**
+     * Cleanup old checkpoints to stay under maxItems.
+     */
+    async cleanup() {
+        if (this.checkpoints.size <= this.maxItems) {
+            return;
+        }
+        // Sort by creation time (oldest first)
+        const sorted = Array.from(this.checkpoints.entries())
+            .sort((a, b) => a[1].metadata.createdAt - b[1].metadata.createdAt);
+        // Delete oldest until under limit
+        const toDelete = sorted.slice(0, this.checkpoints.size - this.maxItems);
+        for (const [id] of toDelete) {
+            this.checkpoints.delete(id);
+        }
+    }
+}
+exports.MemoryCheckpointer = MemoryCheckpointer;
+/**
+ * Deserialize checkpoint state back to AgentState.
+ * Note: Tools must be re-provided, abortSignal reset to undefined.
+ */
+function deserializeCheckpoint(checkpoint, tools) {
+    const s = checkpoint.state;
+    return {
+        messages: s.messages,
+        skills: [], // Skills reconstructed from messages with _meta
+        tools: tools ?? new Map(),
+        stepCount: s.stepCount,
+        maxSteps: s.maxSteps,
+        done: s.done,
+        output: s.output,
+        reasoning: s.reasoning,
+        finishReason: s.finishReason,
+        usage: s.usage,
+        abortSignal: undefined,
+    };
+}
+//# sourceMappingURL=checkpointer.js.map

package/dist/ai/graph/checkpointer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpointer.js","sourceRoot":"","sources":["../../../src/ai/graph/checkpointer.ts"],"names":[],"mappings":"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"}

package/dist/ai/graph/checkpointer.mjs

@@ -0,0 +1,126 @@
+/**
+ * Checkpointer - State persistence for Graph execution.
+ *
+ * Provides save/load capabilities for resumable agent sessions.
+ */
+/**
+ * In-memory checkpointer implementation.
+ * Suitable for testing and short-lived sessions.
+ */
+export class MemoryCheckpointer {
+    constructor(options) {
+        this.checkpoints = new Map();
+        this.maxItems = options?.maxItems ?? 100;
+    }
+    async save(threadId, state, custom) {
+        const id = `ckpt_${threadId}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const metadata = {
+            id,
+            threadId,
+            createdAt: Date.now(),
+            stepCount: state.stepCount,
+            custom,
+        };
+        const serialized = this.serializeState(state);
+        this.checkpoints.set(id, {
+            metadata,
+            state: serialized,
+        });
+        // Cleanup old checkpoints if over limit
+        await this.cleanup();
+        return metadata;
+    }
+    async load(threadId) {
+        // Find latest checkpoint for thread
+        let latest = null;
+        for (const checkpoint of this.checkpoints.values()) {
+            if (checkpoint.metadata.threadId === threadId) {
+                if (!latest || checkpoint.metadata.createdAt > latest.metadata.createdAt) {
+                    latest = checkpoint;
+                }
+            }
+        }
+        return latest;
+    }
+    async list(threadId) {
+        const result = [];
+        for (const checkpoint of this.checkpoints.values()) {
+            if (checkpoint.metadata.threadId === threadId) {
+                result.push(checkpoint.metadata);
+            }
+        }
+        return result.sort((a, b) => b.createdAt - a.createdAt);
+    }
+    async delete(checkpointId) {
+        return this.checkpoints.delete(checkpointId);
+    }
+    async clear(threadId) {
+        let count = 0;
+        for (const [id, checkpoint] of this.checkpoints) {
+            if (checkpoint.metadata.threadId === threadId) {
+                this.checkpoints.delete(id);
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Serialize agent state to JSON-safe format.
+     * Strips non-serializable fields (abortSignal, tools Map).
+     */
+    serializeState(state) {
+        return {
+            messages: state.messages.map(msg => ({
+                role: msg.role,
+                content: msg.content,
+                tool_calls: msg.tool_calls,
+                tool_call_id: msg.tool_call_id,
+                _meta: msg._meta,
+            })),
+            stepCount: state.stepCount,
+            maxSteps: state.maxSteps,
+            done: state.done,
+            output: state.output,
+            reasoning: state.reasoning,
+            finishReason: state.finishReason,
+            usage: state.usage,
+        };
+    }
+    /**
+     * Cleanup old checkpoints to stay under maxItems.
+     */
+    async cleanup() {
+        if (this.checkpoints.size <= this.maxItems) {
+            return;
+        }
+        // Sort by creation time (oldest first)
+        const sorted = Array.from(this.checkpoints.entries())
+            .sort((a, b) => a[1].metadata.createdAt - b[1].metadata.createdAt);
+        // Delete oldest until under limit
+        const toDelete = sorted.slice(0, this.checkpoints.size - this.maxItems);
+        for (const [id] of toDelete) {
+            this.checkpoints.delete(id);
+        }
+    }
+}
+/**
+ * Deserialize checkpoint state back to AgentState.
+ * Note: Tools must be re-provided, abortSignal reset to undefined.
+ */
+export function deserializeCheckpoint(checkpoint, tools) {
+    const s = checkpoint.state;
+    return {
+        messages: s.messages,
+        skills: [], // Skills reconstructed from messages with _meta
+        tools: tools ?? new Map(),
+        stepCount: s.stepCount,
+        maxSteps: s.maxSteps,
+        done: s.done,
+        output: s.output,
+        reasoning: s.reasoning,
+        finishReason: s.finishReason,
+        usage: s.usage,
+        abortSignal: undefined,
+    };
+}
+//# sourceMappingURL=checkpointer.js.map

package/dist/ai/graph/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Graph Runtime public exports.
+ */
+export { StateGraph, MaxGraphStepsError } from './state-graph';
+export { END } from './types';
+export type { NodeFunction, EdgeResolver, GraphNode, GraphEdge, CompiledGraph, InvokeOptions, StateGraphConfig, } from './types';
+export { MemoryCheckpointer, deserializeCheckpoint, } from './checkpointer';
+export type { Checkpointer, Checkpoint, CheckpointMetadata, SerializedAgentState, } from './checkpointer';
+export { RedisCheckpointer } from './redis-checkpointer';
+export type { RedisClient, RedisCheckpointerConfig } from './redis-checkpointer';
+export { PostgresCheckpointer } from './postgres-checkpointer';
+export type { PostgresClient, PostgresCheckpointerConfig } from './postgres-checkpointer';
+//# sourceMappingURL=index.d.ts.map

package/dist/ai/graph/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai/graph/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAC9B,YAAY,EACR,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,SAAS,EACT,aAAa,EACb,aAAa,EACb,gBAAgB,GACnB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACH,kBAAkB,EAClB,qBAAqB,GACxB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACR,YAAY,EACZ,UAAU,EACV,kBAAkB,EAClB,oBAAoB,GACvB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAGjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,YAAY,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/ai/graph/index.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Graph Runtime public exports.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresCheckpointer = exports.RedisCheckpointer = exports.deserializeCheckpoint = exports.MemoryCheckpointer = exports.END = exports.MaxGraphStepsError = exports.StateGraph = void 0;
+var state_graph_1 = require("./state-graph");
+Object.defineProperty(exports, "StateGraph", { enumerable: true, get: function () { return state_graph_1.StateGraph; } });
+Object.defineProperty(exports, "MaxGraphStepsError", { enumerable: true, get: function () { return state_graph_1.MaxGraphStepsError; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "END", { enumerable: true, get: function () { return types_1.END; } });
+// Checkpointers
+var checkpointer_1 = require("./checkpointer");
+Object.defineProperty(exports, "MemoryCheckpointer", { enumerable: true, get: function () { return checkpointer_1.MemoryCheckpointer; } });
+Object.defineProperty(exports, "deserializeCheckpoint", { enumerable: true, get: function () { return checkpointer_1.deserializeCheckpoint; } });
+// Redis Checkpointer (optional - requires ioredis)
+var redis_checkpointer_1 = require("./redis-checkpointer");
+Object.defineProperty(exports, "RedisCheckpointer", { enumerable: true, get: function () { return redis_checkpointer_1.RedisCheckpointer; } });
+// Postgres Checkpointer (optional - requires pg)
+var postgres_checkpointer_1 = require("./postgres-checkpointer");
+Object.defineProperty(exports, "PostgresCheckpointer", { enumerable: true, get: function () { return postgres_checkpointer_1.PostgresCheckpointer; } });
+//# sourceMappingURL=index.js.map

package/dist/ai/graph/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ai/graph/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,6CAA+D;AAAtD,yGAAA,UAAU,OAAA;AAAE,iHAAA,kBAAkB,OAAA;AACvC,iCAA8B;AAArB,4FAAA,GAAG,OAAA;AAWZ,gBAAgB;AAChB,+CAGwB;AAFpB,kHAAA,kBAAkB,OAAA;AAClB,qHAAA,qBAAqB,OAAA;AASzB,mDAAmD;AACnD,2DAAyD;AAAhD,uHAAA,iBAAiB,OAAA;AAG1B,iDAAiD;AACjD,iEAA+D;AAAtD,6HAAA,oBAAoB,OAAA"}

package/dist/ai/graph/index.mjs

@@ -0,0 +1,12 @@
+/**
+ * Graph Runtime public exports.
+ */
+export { StateGraph, MaxGraphStepsError } from './state-graph.mjs';
+export { END } from './types.mjs';
+// Checkpointers
+export { MemoryCheckpointer, deserializeCheckpoint, } from './checkpointer.mjs';
+// Redis Checkpointer (optional - requires ioredis)
+export { RedisCheckpointer } from './redis-checkpointer.mjs';
+// Postgres Checkpointer (optional - requires pg)
+export { PostgresCheckpointer } from './postgres-checkpointer.mjs';
+//# sourceMappingURL=index.js.map

package/dist/ai/graph/postgres-checkpointer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * PostgreSQL Checkpointer implementation.
+ * Requires pg as a peer dependency.
+ *
+ * @example
+ * ```typescript
+ * import { Pool } from 'pg';
+ * import { PostgresCheckpointer } from '@bowenqt/qiniu-ai-sdk';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const checkpointer = new PostgresCheckpointer(pool, { tableName: 'checkpoints' });
+ *
+ * // Create table (run once)
+ * await checkpointer.createTable();
+ * ```
+ */
+import type { AgentState } from '../internal-types';
+import type { Checkpoint, CheckpointMetadata, Checkpointer } from './checkpointer';
+/** Postgres client interface (compatible with pg Pool) */
+export interface PostgresClient {
+    query<T = unknown>(text: string, values?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+/** Postgres checkpointer configuration */
+export interface PostgresCheckpointerConfig {
+    /** Table name (default: 'qiniu_checkpoints') */
+    tableName?: string;
+    /** Schema name (default: 'public') */
+    schema?: string;
+}
+/**
+ * PostgreSQL-based checkpointer.
+ * Uses pg-compatible client interface.
+ */
+export declare class PostgresCheckpointer implements Checkpointer {
+    private readonly client;
+    private readonly tableName;
+    private readonly schema;
+    constructor(client: PostgresClient, config?: PostgresCheckpointerConfig);
+    private get table();
+    /**
+     * Create the checkpoints table if it doesn't exist.
+     * Run this during application setup.
+     */
+    createTable(): Promise<void>;
+    save(threadId: string, state: AgentState, custom?: Record<string, unknown>): Promise<CheckpointMetadata>;
+    load(threadId: string): Promise<Checkpoint | null>;
+    list(threadId: string): Promise<CheckpointMetadata[]>;
+    delete(checkpointId: string): Promise<boolean>;
+    clear(threadId: string): Promise<number>;
+    private serializeState;
+}
+//# sourceMappingURL=postgres-checkpointer.d.ts.map

package/dist/ai/graph/postgres-checkpointer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-checkpointer.d.ts","sourceRoot":"","sources":["../../../src/ai/graph/postgres-checkpointer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAwB,MAAM,gBAAgB,CAAC;AAEzG,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC3B,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC,CAAC;CAChF;AAED,0CAA0C;AAC1C,MAAM,WAAW,0BAA0B;IACvC,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,cAAc,EAAE,MAAM,GAAE,0BAA+B;IAM3E,OAAO,KAAK,KAAK,GAEhB;IAED;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB5B,IAAI,CACN,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,UAAU,EACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,kBAAkB,CAAC;IAuBxB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAkClD,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA0BrD,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ9C,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ9C,OAAO,CAAC,cAAc;CAkBzB"}