@bowenqt/qiniu-ai-sdk 0.10.0 → 0.14.0

package/dist/ai/graph/postgres-checkpointer.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * 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();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresCheckpointer = void 0;
+/**
+ * PostgreSQL-based checkpointer.
+ * Uses pg-compatible client interface.
+ */
+class PostgresCheckpointer {
+    constructor(client, config = {}) {
+        this.client = client;
+        this.tableName = config.tableName ?? 'qiniu_checkpoints';
+        this.schema = config.schema ?? 'public';
+    }
+    get table() {
+        return `"${this.schema}"."${this.tableName}"`;
+    }
+    /**
+     * Create the checkpoints table if it doesn't exist.
+     * Run this during application setup.
+     */
+    async createTable() {
+        await this.client.query(`
+            CREATE TABLE IF NOT EXISTS ${this.table} (
+                id TEXT PRIMARY KEY,
+                thread_id TEXT NOT NULL,
+                created_at BIGINT NOT NULL,
+                step_count INTEGER NOT NULL,
+                custom JSONB,
+                state JSONB NOT NULL,
+                created_at_ts TIMESTAMP DEFAULT NOW()
+            )
+        `);
+        await this.client.query(`
+            CREATE INDEX IF NOT EXISTS idx_${this.tableName}_thread_id 
+            ON ${this.table} (thread_id)
+        `);
+        await this.client.query(`
+            CREATE INDEX IF NOT EXISTS idx_${this.tableName}_created_at 
+            ON ${this.table} (created_at DESC)
+        `);
+    }
+    async save(threadId, state, custom) {
+        const id = `ckpt_${threadId}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const createdAt = Date.now();
+        const metadata = {
+            id,
+            threadId,
+            createdAt,
+            stepCount: state.stepCount,
+            custom,
+        };
+        const serializedState = this.serializeState(state);
+        await this.client.query(`INSERT INTO ${this.table} (id, thread_id, created_at, step_count, custom, state) 
+             VALUES ($1, $2, $3, $4, $5, $6)`, [id, threadId, createdAt, state.stepCount, JSON.stringify(custom ?? {}), JSON.stringify(serializedState)]);
+        return metadata;
+    }
+    async load(threadId) {
+        const result = await this.client.query(`SELECT id, thread_id, created_at, step_count, custom, state 
+             FROM ${this.table} 
+             WHERE thread_id = $1 
+             ORDER BY created_at DESC 
+             LIMIT 1`, [threadId]);
+        if (result.rows.length === 0)
+            return null;
+        const row = result.rows[0];
+        return {
+            metadata: {
+                id: row.id,
+                threadId: row.thread_id,
+                createdAt: Number(row.created_at),
+                stepCount: row.step_count,
+                custom: row.custom,
+            },
+            state: row.state,
+        };
+    }
+    async list(threadId) {
+        const result = await this.client.query(`SELECT id, thread_id, created_at, step_count, custom 
+             FROM ${this.table} 
+             WHERE thread_id = $1 
+             ORDER BY created_at DESC`, [threadId]);
+        return result.rows.map(row => ({
+            id: row.id,
+            threadId: row.thread_id,
+            createdAt: Number(row.created_at),
+            stepCount: row.step_count,
+            custom: row.custom,
+        }));
+    }
+    async delete(checkpointId) {
+        const result = await this.client.query(`DELETE FROM ${this.table} WHERE id = $1`, [checkpointId]);
+        return result.rowCount === 1;
+    }
+    async clear(threadId) {
+        const result = await this.client.query(`DELETE FROM ${this.table} WHERE thread_id = $1`, [threadId]);
+        return result.rowCount ?? 0;
+    }
+    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,
+        };
+    }
+}
+exports.PostgresCheckpointer = PostgresCheckpointer;
+//# sourceMappingURL=postgres-checkpointer.js.map

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

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

package/dist/ai/graph/postgres-checkpointer.mjs

@@ -0,0 +1,130 @@
+/**
+ * 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();
+ * ```
+ */
+/**
+ * PostgreSQL-based checkpointer.
+ * Uses pg-compatible client interface.
+ */
+export class PostgresCheckpointer {
+    constructor(client, config = {}) {
+        this.client = client;
+        this.tableName = config.tableName ?? 'qiniu_checkpoints';
+        this.schema = config.schema ?? 'public';
+    }
+    get table() {
+        return `"${this.schema}"."${this.tableName}"`;
+    }
+    /**
+     * Create the checkpoints table if it doesn't exist.
+     * Run this during application setup.
+     */
+    async createTable() {
+        await this.client.query(`
+            CREATE TABLE IF NOT EXISTS ${this.table} (
+                id TEXT PRIMARY KEY,
+                thread_id TEXT NOT NULL,
+                created_at BIGINT NOT NULL,
+                step_count INTEGER NOT NULL,
+                custom JSONB,
+                state JSONB NOT NULL,
+                created_at_ts TIMESTAMP DEFAULT NOW()
+            )
+        `);
+        await this.client.query(`
+            CREATE INDEX IF NOT EXISTS idx_${this.tableName}_thread_id 
+            ON ${this.table} (thread_id)
+        `);
+        await this.client.query(`
+            CREATE INDEX IF NOT EXISTS idx_${this.tableName}_created_at 
+            ON ${this.table} (created_at DESC)
+        `);
+    }
+    async save(threadId, state, custom) {
+        const id = `ckpt_${threadId}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const createdAt = Date.now();
+        const metadata = {
+            id,
+            threadId,
+            createdAt,
+            stepCount: state.stepCount,
+            custom,
+        };
+        const serializedState = this.serializeState(state);
+        await this.client.query(`INSERT INTO ${this.table} (id, thread_id, created_at, step_count, custom, state) 
+             VALUES ($1, $2, $3, $4, $5, $6)`, [id, threadId, createdAt, state.stepCount, JSON.stringify(custom ?? {}), JSON.stringify(serializedState)]);
+        return metadata;
+    }
+    async load(threadId) {
+        const result = await this.client.query(`SELECT id, thread_id, created_at, step_count, custom, state 
+             FROM ${this.table} 
+             WHERE thread_id = $1 
+             ORDER BY created_at DESC 
+             LIMIT 1`, [threadId]);
+        if (result.rows.length === 0)
+            return null;
+        const row = result.rows[0];
+        return {
+            metadata: {
+                id: row.id,
+                threadId: row.thread_id,
+                createdAt: Number(row.created_at),
+                stepCount: row.step_count,
+                custom: row.custom,
+            },
+            state: row.state,
+        };
+    }
+    async list(threadId) {
+        const result = await this.client.query(`SELECT id, thread_id, created_at, step_count, custom 
+             FROM ${this.table} 
+             WHERE thread_id = $1 
+             ORDER BY created_at DESC`, [threadId]);
+        return result.rows.map(row => ({
+            id: row.id,
+            threadId: row.thread_id,
+            createdAt: Number(row.created_at),
+            stepCount: row.step_count,
+            custom: row.custom,
+        }));
+    }
+    async delete(checkpointId) {
+        const result = await this.client.query(`DELETE FROM ${this.table} WHERE id = $1`, [checkpointId]);
+        return result.rowCount === 1;
+    }
+    async clear(threadId) {
+        const result = await this.client.query(`DELETE FROM ${this.table} WHERE thread_id = $1`, [threadId]);
+        return result.rowCount ?? 0;
+    }
+    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,
+        };
+    }
+}
+//# sourceMappingURL=postgres-checkpointer.js.map

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

@@ -0,0 +1,51 @@
+/**
+ * Redis Checkpointer implementation.
+ * Requires ioredis as a peer dependency.
+ *
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis';
+ * import { RedisCheckpointer } from '@bowenqt/qiniu-ai-sdk';
+ *
+ * const redis = new Redis('redis://localhost:6379');
+ * const checkpointer = new RedisCheckpointer(redis, { prefix: 'myapp:' });
+ * ```
+ */
+import type { AgentState } from '../internal-types';
+import type { Checkpoint, CheckpointMetadata, Checkpointer } from './checkpointer';
+/** Redis client interface (compatible with ioredis) */
+export interface RedisClient {
+    set(key: string, value: string, exMode?: string, time?: number): Promise<'OK' | null>;
+    get(key: string): Promise<string | null>;
+    del(key: string | string[]): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    smembers(key: string): Promise<string[]>;
+    sadd(key: string, ...members: string[]): Promise<number>;
+    srem(key: string, ...members: string[]): Promise<number>;
+}
+/** Redis checkpointer configuration */
+export interface RedisCheckpointerConfig {
+    /** Key prefix (default: 'qiniu:checkpoint:') */
+    prefix?: string;
+    /** TTL in seconds (default: no expiry) */
+    ttlSeconds?: number;
+}
+/**
+ * Redis-based checkpointer.
+ * Uses ioredis-compatible client interface.
+ */
+export declare class RedisCheckpointer implements Checkpointer {
+    private readonly redis;
+    private readonly prefix;
+    private readonly ttlSeconds?;
+    constructor(client: RedisClient, config?: RedisCheckpointerConfig);
+    private checkpointKey;
+    private threadKey;
+    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=redis-checkpointer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redis-checkpointer.d.ts","sourceRoot":"","sources":["../../../src/ai/graph/redis-checkpointer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAwB,MAAM,gBAAgB,CAAC;AAEzG,uDAAuD;AACvD,MAAM,WAAW,WAAW;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACtF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5D;AAED,uCAAuC;AACvC,MAAM,WAAW,uBAAuB;IACpC,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;gBAEzB,MAAM,EAAE,WAAW,EAAE,MAAM,GAAE,uBAA4B;IAMrE,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,SAAS;IAIX,IAAI,CACN,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,UAAU,EACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,kBAAkB,CAAC;IA+BxB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAmBlD,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAerD,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAW9C,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAW9C,OAAO,CAAC,cAAc;CAkBzB"}

package/dist/ai/graph/redis-checkpointer.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Redis Checkpointer implementation.
+ * Requires ioredis as a peer dependency.
+ *
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis';
+ * import { RedisCheckpointer } from '@bowenqt/qiniu-ai-sdk';
+ *
+ * const redis = new Redis('redis://localhost:6379');
+ * const checkpointer = new RedisCheckpointer(redis, { prefix: 'myapp:' });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisCheckpointer = void 0;
+/**
+ * Redis-based checkpointer.
+ * Uses ioredis-compatible client interface.
+ */
+class RedisCheckpointer {
+    constructor(client, config = {}) {
+        this.redis = client;
+        this.prefix = config.prefix ?? 'qiniu:checkpoint:';
+        this.ttlSeconds = config.ttlSeconds;
+    }
+    checkpointKey(id) {
+        return `${this.prefix}data:${id}`;
+    }
+    threadKey(threadId) {
+        return `${this.prefix}thread:${threadId}`;
+    }
+    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 checkpoint = {
+            metadata,
+            state: this.serializeState(state),
+        };
+        const key = this.checkpointKey(id);
+        const data = JSON.stringify(checkpoint);
+        if (this.ttlSeconds) {
+            await this.redis.set(key, data, 'EX', this.ttlSeconds);
+        }
+        else {
+            await this.redis.set(key, data);
+        }
+        // Add to thread index
+        await this.redis.sadd(this.threadKey(threadId), id);
+        return metadata;
+    }
+    async load(threadId) {
+        const ids = await this.redis.smembers(this.threadKey(threadId));
+        if (ids.length === 0)
+            return null;
+        let latest = null;
+        for (const id of ids) {
+            const data = await this.redis.get(this.checkpointKey(id));
+            if (data) {
+                const checkpoint = JSON.parse(data);
+                if (!latest || checkpoint.metadata.createdAt > latest.metadata.createdAt) {
+                    latest = checkpoint;
+                }
+            }
+        }
+        return latest;
+    }
+    async list(threadId) {
+        const ids = await this.redis.smembers(this.threadKey(threadId));
+        const result = [];
+        for (const id of ids) {
+            const data = await this.redis.get(this.checkpointKey(id));
+            if (data) {
+                const checkpoint = JSON.parse(data);
+                result.push(checkpoint.metadata);
+            }
+        }
+        return result.sort((a, b) => b.createdAt - a.createdAt);
+    }
+    async delete(checkpointId) {
+        const data = await this.redis.get(this.checkpointKey(checkpointId));
+        if (!data)
+            return false;
+        const checkpoint = JSON.parse(data);
+        await this.redis.del(this.checkpointKey(checkpointId));
+        await this.redis.srem(this.threadKey(checkpoint.metadata.threadId), checkpointId);
+        return true;
+    }
+    async clear(threadId) {
+        const ids = await this.redis.smembers(this.threadKey(threadId));
+        if (ids.length === 0)
+            return 0;
+        const keys = ids.map(id => this.checkpointKey(id));
+        await this.redis.del(keys);
+        await this.redis.del(this.threadKey(threadId));
+        return ids.length;
+    }
+    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,
+        };
+    }
+}
+exports.RedisCheckpointer = RedisCheckpointer;
+//# sourceMappingURL=redis-checkpointer.js.map

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

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

package/dist/ai/graph/redis-checkpointer.mjs

@@ -0,0 +1,120 @@
+/**
+ * Redis Checkpointer implementation.
+ * Requires ioredis as a peer dependency.
+ *
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis';
+ * import { RedisCheckpointer } from '@bowenqt/qiniu-ai-sdk';
+ *
+ * const redis = new Redis('redis://localhost:6379');
+ * const checkpointer = new RedisCheckpointer(redis, { prefix: 'myapp:' });
+ * ```
+ */
+/**
+ * Redis-based checkpointer.
+ * Uses ioredis-compatible client interface.
+ */
+export class RedisCheckpointer {
+    constructor(client, config = {}) {
+        this.redis = client;
+        this.prefix = config.prefix ?? 'qiniu:checkpoint:';
+        this.ttlSeconds = config.ttlSeconds;
+    }
+    checkpointKey(id) {
+        return `${this.prefix}data:${id}`;
+    }
+    threadKey(threadId) {
+        return `${this.prefix}thread:${threadId}`;
+    }
+    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 checkpoint = {
+            metadata,
+            state: this.serializeState(state),
+        };
+        const key = this.checkpointKey(id);
+        const data = JSON.stringify(checkpoint);
+        if (this.ttlSeconds) {
+            await this.redis.set(key, data, 'EX', this.ttlSeconds);
+        }
+        else {
+            await this.redis.set(key, data);
+        }
+        // Add to thread index
+        await this.redis.sadd(this.threadKey(threadId), id);
+        return metadata;
+    }
+    async load(threadId) {
+        const ids = await this.redis.smembers(this.threadKey(threadId));
+        if (ids.length === 0)
+            return null;
+        let latest = null;
+        for (const id of ids) {
+            const data = await this.redis.get(this.checkpointKey(id));
+            if (data) {
+                const checkpoint = JSON.parse(data);
+                if (!latest || checkpoint.metadata.createdAt > latest.metadata.createdAt) {
+                    latest = checkpoint;
+                }
+            }
+        }
+        return latest;
+    }
+    async list(threadId) {
+        const ids = await this.redis.smembers(this.threadKey(threadId));
+        const result = [];
+        for (const id of ids) {
+            const data = await this.redis.get(this.checkpointKey(id));
+            if (data) {
+                const checkpoint = JSON.parse(data);
+                result.push(checkpoint.metadata);
+            }
+        }
+        return result.sort((a, b) => b.createdAt - a.createdAt);
+    }
+    async delete(checkpointId) {
+        const data = await this.redis.get(this.checkpointKey(checkpointId));
+        if (!data)
+            return false;
+        const checkpoint = JSON.parse(data);
+        await this.redis.del(this.checkpointKey(checkpointId));
+        await this.redis.srem(this.threadKey(checkpoint.metadata.threadId), checkpointId);
+        return true;
+    }
+    async clear(threadId) {
+        const ids = await this.redis.smembers(this.threadKey(threadId));
+        if (ids.length === 0)
+            return 0;
+        const keys = ids.map(id => this.checkpointKey(id));
+        await this.redis.del(keys);
+        await this.redis.del(this.threadKey(threadId));
+        return ids.length;
+    }
+    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,
+        };
+    }
+}
+//# sourceMappingURL=redis-checkpointer.js.map

package/dist/ai/graph/state-graph.d.ts

@@ -0,0 +1,41 @@
+/**
+ * StateGraph - LangGraph-inspired graph builder.
+ * Minimal implementation for Phase 1.
+ */
+import type { NodeFunction, EdgeResolver, CompiledGraph, StateGraphConfig } from './types';
+/** Maximum steps error */
+export declare class MaxGraphStepsError extends Error {
+    readonly maxSteps: number;
+    constructor(maxSteps: number);
+}
+/**
+ * StateGraph builder for agent workflows.
+ */
+export declare class StateGraph<S extends object> {
+    private config;
+    private nodes;
+    private edges;
+    private entryPoint;
+    constructor(config?: StateGraphConfig<S>);
+    /**
+     * Add a node to the graph.
+     */
+    addNode(name: string, fn: NodeFunction<S>): this;
+    /**
+     * Add an edge between nodes.
+     */
+    addEdge(from: string, to: string): this;
+    /**
+     * Add a conditional edge.
+     */
+    addConditionalEdge(from: string, resolver: EdgeResolver<S>): this;
+    /**
+     * Set the entry point.
+     */
+    setEntryPoint(name: string): this;
+    /**
+     * Compile the graph into an executable form.
+     */
+    compile(): CompiledGraph<S>;
+}
+//# sourceMappingURL=state-graph.d.ts.map

package/dist/ai/graph/state-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-graph.d.ts","sourceRoot":"","sources":["../../../src/ai/graph/state-graph.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACR,YAAY,EACZ,YAAY,EAGZ,aAAa,EAEb,gBAAgB,EACnB,MAAM,SAAS,CAAC;AAGjB,0BAA0B;AAC1B,qBAAa,kBAAmB,SAAQ,KAAK;aACb,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM;CAI/C;AAED;;GAEG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,MAAM;IAKxB,OAAO,CAAC,MAAM;IAJ1B,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,UAAU,CAAuB;gBAErB,MAAM,GAAE,gBAAgB,CAAC,CAAC,CAAM;IAMpD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAWhD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAKvC;;OAEG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI;IAKjE;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKjC;;OAEG;IACH,OAAO,IAAI,aAAa,CAAC,CAAC,CAAC;CA8F9B"}