@ai.ntellect/core 1.0.0 → 1.1.1

package/routing/patterns/rag-search.json

@@ -0,0 +1,68 @@
+{
+  "name": "rag_search_workflow",
+  "description": "Retrieval-Augmented Generation workflow. Searches a knowledge base, retrieves relevant documents, and generates a response using LLM.",
+  "places": [
+    { "id": "idle", "type": "initial", "tokens": [{ "id": "start", "data": {} }] },
+    { "id": "query_parsed", "type": "normal", "tokens": [] },
+    { "id": "searching", "type": "normal", "tokens": [] },
+    { "id": "documents_retrieved", "type": "normal", "tokens": [] },
+    { "id": "generating_response", "type": "normal", "tokens": [] },
+    { "id": "completed", "type": "final", "tokens": [] },
+    { "id": "no_results", "type": "final", "tokens": [] }
+  ],
+  "transitions": [
+    {
+      "id": "parse_query",
+      "from": ["idle"],
+      "to": "query_parsed",
+      "action": {
+        "type": "dynamic",
+        "prompt": "Parse the user query to extract search terms and intent. Return structured data.",
+        "maxSteps": 2
+      }
+    },
+    {
+      "id": "search_knowledge_base",
+      "from": ["query_parsed"],
+      "to": "searching",
+      "action": {
+        "type": "graphflow",
+        "name": "vector_search",
+        "contextMapper": "ctx => ({ query: ctx.parsedQuery?.query || ctx.originalMessage })"
+      }
+    },
+    {
+      "id": "retrieve_docs",
+      "from": ["searching"],
+      "to": "documents_retrieved",
+      "guard": {
+        "type": "deterministic",
+        "condition": "context.searchResults && context.searchResults.length > 0"
+      }
+    },
+    {
+      "id": "no_results_found",
+      "from": ["searching"],
+      "to": "no_results",
+      "guard": {
+        "type": "deterministic",
+        "condition": "!context.searchResults || context.searchResults.length === 0"
+      }
+    },
+    {
+      "id": "generate_answer",
+      "from": ["documents_retrieved"],
+      "to": "generating_response",
+      "action": {
+        "type": "graphflow",
+        "name": "llm_generator",
+        "contextMapper": "ctx => ({ query: ctx.originalMessage, documents: ctx.searchResults })"
+      }
+    },
+    {
+      "id": "complete",
+      "from": ["generating_response"],
+      "to": "completed"
+    }
+  ]
+}

package/routing/postgres-checkpoint-adapter.ts

@@ -0,0 +1,172 @@
+import { PetriNet } from './index';
+import { Session } from './orchestrator';
+import { IPetriCheckpointAdapter } from './checkpoint-adapter';
+
+export interface PostgresCheckpointAdapterOptions {
+  connectionString: string;
+  tableName?: string;
+}
+
+export class PostgresPetriCheckpointAdapter implements IPetriCheckpointAdapter {
+  private connectionString: string;
+  private tableName: string;
+  private pool: any = null;
+  private initialized: boolean = false;
+
+  constructor(options: PostgresCheckpointAdapterOptions) {
+    this.connectionString = options.connectionString;
+    this.tableName = options.tableName || 'petri_checkpoints';
+  }
+
+  private async initPool(): Promise<void> {
+    if (this.initialized) return;
+
+    try {
+      const pg = await (Function('moduleName', 'return import(moduleName)') as any)('pg');
+      const { Pool } = pg;
+      this.pool = new Pool({ connectionString: this.connectionString });
+
+      const client = await this.pool.connect();
+      try {
+        await client.query(`
+          CREATE TABLE IF NOT EXISTS ${this.tableName} (
+            id VARCHAR(255) PRIMARY KEY,
+            timestamp BIGINT NOT NULL,
+            session_id VARCHAR(255),
+            data JSONB NOT NULL,
+            created_at TIMESTAMP DEFAULT NOW()
+          );
+          CREATE INDEX IF NOT EXISTS idx_${this.tableName}_session ON ${this.tableName}(session_id);
+          CREATE INDEX IF NOT EXISTS idx_${this.tableName}_timestamp ON ${this.tableName}(timestamp DESC);
+        `);
+      } finally {
+        client.release();
+      }
+
+      this.initialized = true;
+    } catch (error) {
+      throw new Error(
+        'PostgreSQL adapter requires "pg" package. Install it with: pnpm add pg @types/pg'
+      );
+    }
+  }
+
+  async save(net: PetriNet, session?: Session): Promise<string> {
+    await this.initPool();
+
+    const checkpointId = `petri-cp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+
+    const marking = (net as any).state.marking as Map<string, any[]>;
+    const serializedMarking: any[] = [];
+    for (const [pid, tokens] of marking) {
+      serializedMarking.push({
+        placeId: pid,
+        tokens: tokens.map((t: any) => ({ id: t.id, data: t.data, createdAt: t.createdAt })),
+      });
+    }
+
+    const checkpoint = {
+      id: checkpointId,
+      timestamp: Date.now(),
+      sessionId: session?.id,
+      marking: serializedMarking,
+      history: (net as any).state.history || [],
+      sessionContext: (session as any)?.context,
+      sessionTraceId: session?.traceId,
+      sessionCreatedAt: session?.createdAt,
+      sessionHistory: session?.history || [],
+    };
+
+    const sql = `
+      INSERT INTO ${this.tableName} (id, timestamp, session_id, data)
+      VALUES ($1, $2, $3, $4)
+    `;
+    await this.pool.query(sql, [
+      checkpointId,
+      checkpoint.timestamp,
+      checkpoint.sessionId || null,
+      JSON.stringify(checkpoint),
+    ]);
+
+    return checkpointId;
+  }
+
+  async load(checkpointId: string): Promise<{ net: PetriNet; session?: Session } | null> {
+    await this.initPool();
+
+    const sql = `SELECT data FROM ${this.tableName} WHERE id = $1`;
+    const result = await this.pool.query(sql, [checkpointId]);
+
+    if (result.rows.length === 0) return null;
+
+    const cp = result.rows[0].data;
+    const net = new PetriNet(cp.id);
+    const marking = (net as any).state.marking as Map<string, any[]>;
+
+    for (const item of cp.marking) {
+      marking.set(item.placeId, item.tokens.map((t: any) => ({ ...t })));
+    }
+
+    (net as any).state.history = [...cp.history];
+
+    let session: Session | undefined;
+    if (cp.sessionId) {
+      session = {
+        id: cp.sessionId,
+        petriNet: net,
+        context: cp.sessionContext || {},
+        history: cp.sessionHistory || [],
+        createdAt: cp.sessionCreatedAt || cp.timestamp,
+        traceId: cp.sessionTraceId || `trace-restored-${Date.now()}`,
+      } as Session;
+    }
+
+    return { net, session };
+  }
+
+  async list(): Promise<Array<{ id: string; timestamp: number; sessionId?: string }>> {
+    await this.initPool();
+
+    const sql = `
+      SELECT id, timestamp, session_id as "sessionId"
+      FROM ${this.tableName}
+      ORDER BY timestamp DESC
+    `;
+    const result = await this.pool.query(sql);
+    return result.rows.map((row: any) => ({
+      id: row.id,
+      timestamp: parseInt(row.timestamp),
+      sessionId: row.sessionId,
+    }));
+  }
+
+  async delete(checkpointId: string): Promise<void> {
+    await this.initPool();
+    const sql = `DELETE FROM ${this.tableName} WHERE id = $1`;
+    await this.pool.query(sql, [checkpointId]);
+  }
+
+  async listBySession(sessionId: string): Promise<Array<{ id: string; timestamp: number }>> {
+    await this.initPool();
+
+    const sql = `
+      SELECT id, timestamp
+      FROM ${this.tableName}
+      WHERE session_id = $1
+      ORDER BY timestamp DESC
+    `;
+    const result = await this.pool.query(sql, [sessionId]);
+    return result.rows.map((row: any) => ({
+      id: row.id,
+      timestamp: parseInt(row.timestamp),
+    }));
+  }
+
+  async close(): Promise<void> {
+    if (this.pool) {
+      await this.pool.end();
+      this.pool = null;
+      this.initialized = false;
+    }
+  }
+}

package/routing/redis-checkpoint-adapter.ts

@@ -0,0 +1,187 @@
+import { PetriNet } from './index';
+import { Session } from './orchestrator';
+import { IPetriCheckpointAdapter } from './checkpoint-adapter';
+import { createClient, RedisClientType } from 'redis';
+
+export interface RedisCheckpointAdapterOptions {
+  url?: string;
+  host?: string;
+  port?: number;
+  password?: string;
+  keyPrefix?: string;
+}
+
+export class RedisPetriCheckpointAdapter implements IPetriCheckpointAdapter {
+  private client: RedisClientType;
+  private keyPrefix: string;
+  private connected: boolean = false;
+
+  constructor(options?: RedisCheckpointAdapterOptions) {
+    this.keyPrefix = options?.keyPrefix || 'petri:cp:';
+
+    if (options?.url) {
+      this.client = createClient({ url: options.url }) as RedisClientType;
+    } else {
+      this.client = createClient({
+        socket: {
+          host: options?.host || 'localhost',
+          port: options?.port || 6379,
+        },
+        password: options?.password,
+      }) as RedisClientType;
+    }
+
+    this.client.on('error', (err) => {
+      console.error('Redis Client Error', err);
+    });
+  }
+
+  private async ensureConnected(): Promise<void> {
+    if (!this.connected) {
+      await this.client.connect();
+      this.connected = true;
+    }
+  }
+
+  async save(net: PetriNet, session?: Session): Promise<string> {
+    await this.ensureConnected();
+
+    const checkpointId = `petri-cp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+
+    const marking = (net as any).state.marking as Map<string, any[]>;
+    const serializedMarking: any[] = [];
+    for (const [pid, tokens] of marking) {
+      serializedMarking.push({
+        placeId: pid,
+        tokens: tokens.map(t => ({ id: t.id, data: t.data, createdAt: t.createdAt })),
+      });
+    }
+
+    const checkpoint = {
+      id: checkpointId,
+      timestamp: Date.now(),
+      sessionId: session?.id,
+      marking: serializedMarking,
+      history: (net as any).state.history || [],
+      sessionContext: (session as any)?.context,
+      sessionTraceId: session?.traceId,
+      sessionCreatedAt: session?.createdAt,
+      sessionHistory: session?.history || [],
+    };
+
+    const key = `${this.keyPrefix}${checkpointId}`;
+    await this.client.set(key, JSON.stringify(checkpoint));
+
+    const indexKey = `${this.keyPrefix}index`;
+    await this.client.zAdd(indexKey, { score: checkpoint.timestamp, value: checkpointId });
+
+    if (session?.id) {
+      const sessionKey = `${this.keyPrefix}session:${session.id}`;
+      await this.client.sAdd(sessionKey, checkpointId);
+    }
+
+    return checkpointId;
+  }
+
+  async load(checkpointId: string): Promise<{ net: PetriNet; session?: Session } | null> {
+    await this.ensureConnected();
+
+    const key = `${this.keyPrefix}${checkpointId}`;
+    const data = await this.client.get(key);
+
+    if (!data) return null;
+
+    const cp = JSON.parse(data);
+    const net = new PetriNet(cp.id);
+    const marking = (net as any).state.marking as Map<string, any[]>;
+
+    for (const item of cp.marking) {
+      marking.set(item.placeId, item.tokens.map((t: any) => ({ ...t })));
+    }
+
+    (net as any).state.history = [...cp.history];
+
+    let session: Session | undefined;
+    if (cp.sessionId) {
+      session = {
+        id: cp.sessionId,
+        petriNet: net,
+        context: cp.sessionContext || {},
+        history: cp.sessionHistory || [],
+        createdAt: cp.sessionCreatedAt || cp.timestamp,
+        traceId: cp.sessionTraceId || `trace-restored-${Date.now()}`,
+      } as Session;
+    }
+
+    return { net, session };
+  }
+
+  async list(): Promise<Array<{ id: string; timestamp: number; sessionId?: string }>> {
+    await this.ensureConnected();
+
+    const indexKey = `${this.keyPrefix}index`;
+    const ids = await this.client.zRange(indexKey, 0, -1, { REV: true });
+
+    const results = [];
+    for (const id of ids) {
+      const key = `${this.keyPrefix}${id}`;
+      const data = await this.client.get(key);
+      if (data) {
+        const cp = JSON.parse(data);
+        results.push({
+          id: cp.id,
+          timestamp: cp.timestamp,
+          sessionId: cp.sessionId,
+        });
+      }
+    }
+
+    return results;
+  }
+
+  async delete(checkpointId: string): Promise<void> {
+    await this.ensureConnected();
+
+    const key = `${this.keyPrefix}${checkpointId}`;
+    const data = await this.client.get(key);
+
+    if (data) {
+      const cp = JSON.parse(data);
+      if (cp.sessionId) {
+        const sessionKey = `${this.keyPrefix}session:${cp.sessionId}`;
+        await this.client.sRem(sessionKey, checkpointId);
+      }
+    }
+
+    await this.client.del(key);
+
+    const indexKey = `${this.keyPrefix}index`;
+    await this.client.zRem(indexKey, checkpointId);
+  }
+
+  async listBySession(sessionId: string): Promise<Array<{ id: string; timestamp: number }>> {
+    await this.ensureConnected();
+
+    const sessionKey = `${this.keyPrefix}session:${sessionId}`;
+    const ids = await this.client.sMembers(sessionKey);
+
+    const results = [];
+    for (const id of ids) {
+      const key = `${this.keyPrefix}${id}`;
+      const data = await this.client.get(key);
+      if (data) {
+        const cp = JSON.parse(data);
+        results.push({ id: cp.id, timestamp: cp.timestamp });
+      }
+    }
+
+    return results.sort((a, b) => b.timestamp - a.timestamp);
+  }
+
+  async close(): Promise<void> {
+    if (this.connected) {
+      await this.client.quit();
+      this.connected = false;
+    }
+  }
+}

package/routing/types.ts

@@ -0,0 +1,59 @@
+export interface Token {
+  id: string;
+  data: Record<string, any>;
+  createdAt: number;
+}
+
+export interface Place {
+  id: string;
+  type: 'normal' | 'initial' | 'final';
+  tokens: Token[];
+}
+
+export interface Guard {
+  type: 'deterministic' | 'llm_evaluated';
+  condition?: string;
+  name?: string;
+}
+
+export interface TransitionAction {
+  type: 'graphflow' | 'dynamic';
+  name?: string;
+  prompt?: string;
+  maxSteps?: number;
+  contextMapper?: (ctx: any) => any;
+}
+
+export interface Transition {
+  id: string;
+  from: string[];
+  to: string | string[];
+  guard?: Guard;
+  action?: TransitionAction;
+  description?: string;
+  when?: {
+    events: string[];
+    timeout?: number;
+  };
+}
+
+export interface PetriNetState {
+  marking: Map<string, Token[]>;
+  history: string[];
+}
+
+export interface TransitionResult {
+  success: boolean;
+  transitionId: string;
+  newMarking: Map<string, Token[]>;
+  consumedTokens: Token[];
+  producedTokens: Token[];
+  error?: string;
+}
+
+export type GuardLLMExecutor = (prompt: string, context: any) => Promise<boolean>;
+
+export type ActionExecutor = (
+  action: TransitionAction,
+  context: any
+) => Promise<any>;