agentic-flow 3.0.0-alpha.2 → 3.1.0

package/dist/packages/agentdb/src/backends/factory.js

@@ -1,273 +0,0 @@
-/**
- * Backend Factory - Automatic Backend Detection and Selection
- *
- * Detects available vector backends and creates appropriate instances.
- * Priority: RuVector (native/WASM) > HNSWLib (Node.js)
- *
- * Features:
- * - Automatic detection of @ruvector packages
- * - Native vs WASM detection for RuVector
- * - GNN and Graph capabilities detection
- * - Graceful fallback to HNSWLib
- * - Clear error messages for missing dependencies
- */
-import { RuVectorBackend } from './ruvector/RuVectorBackend.js';
-import { HNSWLibBackend } from './hnswlib/HNSWLibBackend.js';
-import { GuardedVectorBackend, ProofDeniedError } from './ruvector/GuardedVectorBackend.js';
-import { MutationGuard } from '../security/MutationGuard.js';
-import { AttestationLog } from '../security/AttestationLog.js';
-/**
- * Detect available vector backends
- */
-export async function detectBackends() {
-    const result = {
-        available: 'none',
-        ruvector: {
-            core: false,
-            gnn: false,
-            graph: false,
-            native: false,
-            graphTransformer: false,
-        },
-        hnswlib: false
-    };
-    // Check RuVector packages (main package or scoped packages)
-    try {
-        // Try main ruvector package first (v0.1.99+)
-        const ruvector = await import('ruvector');
-        result.ruvector.core = true;
-        result.ruvector.gnn = true; // Main package includes GNN
-        result.ruvector.graph = true; // Main package includes Graph
-        // Check for native backend availability (0.1.99+ API)
-        if (typeof ruvector.isNative === 'function') {
-            result.ruvector.native = ruvector.isNative();
-        }
-        else if (typeof ruvector.backend === 'function') {
-            // Legacy API check
-            const backend = ruvector.backend();
-            result.ruvector.native = backend === 'native' || backend === 'napi';
-        }
-        result.available = 'ruvector';
-    }
-    catch {
-        // Try scoped packages as fallback
-        try {
-            const core = await import('@ruvector/core');
-            result.ruvector.core = true;
-            // Check for native backend (scoped packages)
-            if (typeof core.isNative === 'function') {
-                result.ruvector.native = core.isNative();
-            }
-            else if (typeof core.backend === 'function') {
-                const backend = core.backend();
-                result.ruvector.native = backend === 'native' || backend === 'napi';
-            }
-            result.available = 'ruvector';
-            // Check optional packages
-            try {
-                await import('@ruvector/gnn');
-                result.ruvector.gnn = true;
-            }
-            catch {
-                // GNN not installed - this is optional
-            }
-            try {
-                await import('@ruvector/graph-node');
-                result.ruvector.graph = true;
-            }
-            catch {
-                // Graph not installed - this is optional
-            }
-            try {
-                await import('@ruvector/graph-transformer');
-                result.ruvector.graphTransformer = true;
-            }
-            catch {
-                // graph-transformer not installed - optional
-            }
-        }
-        catch {
-            // RuVector not installed - will try fallback
-        }
-    }
-    // Check @ruvector/graph-transformer independently (may exist without core)
-    if (!result.ruvector.graphTransformer) {
-        try {
-            await import('@ruvector/graph-transformer');
-            result.ruvector.graphTransformer = true;
-        }
-        catch {
-            // Try WASM version
-            try {
-                await import('ruvector-graph-transformer-wasm');
-                result.ruvector.graphTransformer = true;
-            }
-            catch {
-                // graph-transformer not installed in any form
-            }
-        }
-    }
-    // Check HNSWLib
-    try {
-        await import('hnswlib-node');
-        result.hnswlib = true;
-        if (result.available === 'none') {
-            result.available = 'hnswlib';
-        }
-    }
-    catch {
-        // HNSWLib not installed
-    }
-    return result;
-}
-/**
- * Create vector backend with automatic detection
- *
- * @param type - Backend type: 'auto', 'ruvector', or 'hnswlib'
- * @param config - Vector configuration
- * @returns Initialized VectorBackend instance
- */
-export async function createBackend(type, config) {
-    const detection = await detectBackends();
-    let backend;
-    // Handle explicit backend selection
-    if (type === 'ruvector') {
-        if (!detection.ruvector.core) {
-            throw new Error('RuVector not available.\n' +
-                'Install with: npm install @ruvector/core\n' +
-                'Optional GNN support: npm install @ruvector/gnn\n' +
-                'Optional Graph support: npm install @ruvector/graph-node');
-        }
-        backend = new RuVectorBackend(config);
-    }
-    else if (type === 'hnswlib') {
-        if (!detection.hnswlib) {
-            throw new Error('HNSWLib not available.\n' +
-                'Install with: npm install hnswlib-node');
-        }
-        backend = new HNSWLibBackend(config);
-    }
-    else {
-        // Auto-detect best available backend
-        if (detection.ruvector.core) {
-            backend = new RuVectorBackend(config);
-            const backendType = detection.ruvector.native ? 'native NAPI-RS' : 'WASM';
-            const proofStatus = detection.ruvector.graphTransformer
-                ? '+ graph-transformer proofs'
-                : '(no proof engine)';
-            console.log(`[AgentDB] Using RuVector backend (${backendType}) ${proofStatus}`);
-            // Try to initialize RuVector, fallback to HNSWLib if it fails
-            try {
-                await backend.initialize();
-                return backend;
-            }
-            catch (error) {
-                const errorMessage = error.message;
-                // If RuVector fails due to :memory: path or other initialization issues,
-                // try falling back to HNSWLib
-                if (detection.hnswlib) {
-                    console.log('[AgentDB] RuVector initialization failed, falling back to HNSWLib');
-                    console.log(`[AgentDB] Reason: ${errorMessage.split('\n')[0]}`);
-                    backend = new HNSWLibBackend(config);
-                    console.log('[AgentDB] Using HNSWLib backend (fallback)');
-                }
-                else {
-                    // No fallback available, re-throw error
-                    throw error;
-                }
-            }
-        }
-        else if (detection.hnswlib) {
-            backend = new HNSWLibBackend(config);
-            console.log('[AgentDB] Using HNSWLib backend (fallback)');
-        }
-        else {
-            throw new Error('No vector backend available.\n' +
-                'Install one of:\n' +
-                '  - npm install ruvector@0.1.99+ (recommended, includes native NAPI-RS)\n' +
-                '  - npm install @ruvector/core (alternative)\n' +
-                '  - npm install hnswlib-node (fallback)');
-        }
-    }
-    // Initialize the backend (if not already initialized)
-    // Note: RuVector may already be initialized in the try block above
-    try {
-        await backend.initialize();
-    }
-    catch (error) {
-        // Ignore if already initialized
-        if (!error.message.includes('already initialized')) {
-            throw error;
-        }
-    }
-    return backend;
-}
-/**
- * Get recommended backend type based on environment
- */
-export async function getRecommendedBackend() {
-    const detection = await detectBackends();
-    if (detection.ruvector.core) {
-        return 'ruvector';
-    }
-    else if (detection.hnswlib) {
-        return 'hnswlib';
-    }
-    else {
-        return 'auto'; // Will throw error in createBackend
-    }
-}
-/**
- * Check if a specific backend is available
- */
-export async function isBackendAvailable(backend) {
-    const detection = await detectBackends();
-    if (backend === 'ruvector') {
-        return detection.ruvector.core;
-    }
-    return detection.hnswlib;
-}
-/**
- * Get installation instructions for a backend
- */
-export function getInstallCommand(backend) {
-    return backend === 'ruvector'
-        ? 'npm install ruvector'
-        : 'npm install hnswlib-node';
-}
-// Re-export proof-gated types (ADR-060)
-export { GuardedVectorBackend, ProofDeniedError };
-/**
- * Create a proof-gated vector backend (ADR-060)
- *
- * Wraps a standard VectorBackend with MutationGuard to require
- * cryptographic proofs for all mutating operations. Optionally
- * attaches an AttestationLog when a database handle is provided.
- *
- * @param type - Backend type: 'auto', 'ruvector', or 'hnswlib'
- * @param config - Vector configuration with optional database handle
- * @returns Object containing the guarded backend, guard, and optional log
- */
-export async function createGuardedBackend(type, config) {
-    const detection = await detectBackends();
-    const inner = await createBackend(type, config);
-    // Enable proofs if graph-transformer is available or explicitly requested
-    const enableWasmProofs = config.enableProofs ?? detection.ruvector.graphTransformer ?? true;
-    const guard = new MutationGuard({
-        dimension: config.dimension ?? config.dimensions ?? 384,
-        maxElements: config.maxElements ?? 10000,
-        enableWasmProofs,
-        enableAttestationLog: true,
-        defaultNamespace: 'default',
-    });
-    await guard.initialize();
-    // Log the proof engine status
-    const stats = guard.getStats();
-    console.log(`[GuardedBackend] Proof engine: ${stats.engineType}, WASM available: ${stats.wasmAvailable}`);
-    let log = null;
-    if (config.database) {
-        log = new AttestationLog(config.database);
-    }
-    return { backend: new GuardedVectorBackend(inner, guard, log ?? undefined), guard, log };
-}
-//# sourceMappingURL=factory.js.map

package/dist/packages/agentdb/src/backends/factory.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/backends/factory.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Backend Factory - Automatic Backend Detection and Selection\n *\n * Detects available vector backends and creates appropriate instances.\n * Priority: RuVector (native/WASM) > HNSWLib (Node.js)\n *\n * Features:\n * - Automatic detection of @ruvector packages\n * - Native vs WASM detection for RuVector\n * - GNN and Graph capabilities detection\n * - Graceful fallback to HNSWLib\n * - Clear error messages for missing dependencies\n */\n\nimport type { VectorBackend, VectorConfig } from './VectorBackend.js';\nimport { RuVectorBackend } from './ruvector/RuVectorBackend.js';\nimport { HNSWLibBackend } from './hnswlib/HNSWLibBackend.js';\nimport { GuardedVectorBackend, ProofDeniedError } from './ruvector/GuardedVectorBackend.js';\nimport { MutationGuard } from '../security/MutationGuard.js';\nimport { AttestationLog } from '../security/AttestationLog.js';\n\nexport type BackendType = 'auto' | 'ruvector' | 'hnswlib';\n\nexport interface BackendDetection {\n  available: 'ruvector' | 'hnswlib' | 'none';\n  ruvector: {\n    core: boolean;\n    gnn: boolean;\n    graph: boolean;\n    native: boolean;\n    graphTransformer: boolean;\n  };\n  hnswlib: boolean;\n}\n\n/**\n * Detect available vector backends\n */\nexport async function detectBackends(): Promise<BackendDetection> {\n  const result: BackendDetection = {\n    available: 'none',\n    ruvector: {\n      core: false,\n      gnn: false,\n      graph: false,\n      native: false,\n      graphTransformer: false,\n    },\n    hnswlib: false\n  };\n\n  // Check RuVector packages (main package or scoped packages)\n  try {\n    // Try main ruvector package first (v0.1.99+)\n    const ruvector = await import('ruvector');\n    result.ruvector.core = true;\n    result.ruvector.gnn = true; // Main package includes GNN\n    result.ruvector.graph = true; // Main package includes Graph\n\n    // Check for native backend availability (0.1.99+ API)\n    if (typeof (ruvector as any).isNative === 'function') {\n      result.ruvector.native = (ruvector as any).isNative();\n    } else if (typeof (ruvector as any).backend === 'function') {\n      // Legacy API check\n      const backend = (ruvector as any).backend();\n      result.ruvector.native = backend === 'native' || backend === 'napi';\n    }\n\n    result.available = 'ruvector';\n  } catch {\n    // Try scoped packages as fallback\n    try {\n      const core = await import('@ruvector/core');\n      result.ruvector.core = true;\n\n      // Check for native backend (scoped packages)\n      if (typeof (core as any).isNative === 'function') {\n        result.ruvector.native = (core as any).isNative();\n      } else if (typeof (core as any).backend === 'function') {\n        const backend = (core as any).backend();\n        result.ruvector.native = backend === 'native' || backend === 'napi';\n      }\n\n      result.available = 'ruvector';\n\n      // Check optional packages\n      try {\n        await import('@ruvector/gnn');\n        result.ruvector.gnn = true;\n      } catch {\n        // GNN not installed - this is optional\n      }\n\n      try {\n        await import('@ruvector/graph-node');\n        result.ruvector.graph = true;\n      } catch {\n        // Graph not installed - this is optional\n      }\n\n      try {\n        await import('@ruvector/graph-transformer' as string);\n        result.ruvector.graphTransformer = true;\n      } catch {\n        // graph-transformer not installed - optional\n      }\n    } catch {\n      // RuVector not installed - will try fallback\n    }\n  }\n\n  // Check @ruvector/graph-transformer independently (may exist without core)\n  if (!result.ruvector.graphTransformer) {\n    try {\n      await import('@ruvector/graph-transformer' as string);\n      result.ruvector.graphTransformer = true;\n    } catch {\n      // Try WASM version\n      try {\n        await import('ruvector-graph-transformer-wasm' as string);\n        result.ruvector.graphTransformer = true;\n      } catch {\n        // graph-transformer not installed in any form\n      }\n    }\n  }\n\n  // Check HNSWLib\n  try {\n    await import('hnswlib-node');\n    result.hnswlib = true;\n\n    if (result.available === 'none') {\n      result.available = 'hnswlib';\n    }\n  } catch {\n    // HNSWLib not installed\n  }\n\n  return result;\n}\n\n/**\n * Create vector backend with automatic detection\n *\n * @param type - Backend type: 'auto', 'ruvector', or 'hnswlib'\n * @param config - Vector configuration\n * @returns Initialized VectorBackend instance\n */\nexport async function createBackend(\n  type: BackendType,\n  config: VectorConfig\n): Promise<VectorBackend> {\n  const detection = await detectBackends();\n\n  let backend: VectorBackend;\n\n  // Handle explicit backend selection\n  if (type === 'ruvector') {\n    if (!detection.ruvector.core) {\n      throw new Error(\n        'RuVector not available.\\n' +\n        'Install with: npm install @ruvector/core\\n' +\n        'Optional GNN support: npm install @ruvector/gnn\\n' +\n        'Optional Graph support: npm install @ruvector/graph-node'\n      );\n    }\n    backend = new RuVectorBackend(config);\n  } else if (type === 'hnswlib') {\n    if (!detection.hnswlib) {\n      throw new Error(\n        'HNSWLib not available.\\n' +\n        'Install with: npm install hnswlib-node'\n      );\n    }\n    backend = new HNSWLibBackend(config);\n  } else {\n    // Auto-detect best available backend\n    if (detection.ruvector.core) {\n      backend = new RuVectorBackend(config);\n      const backendType = detection.ruvector.native ? 'native NAPI-RS' : 'WASM';\n      const proofStatus = detection.ruvector.graphTransformer\n        ? '+ graph-transformer proofs'\n        : '(no proof engine)';\n      console.log(`[AgentDB] Using RuVector backend (${backendType}) ${proofStatus}`);\n\n      // Try to initialize RuVector, fallback to HNSWLib if it fails\n      try {\n        await (backend as any).initialize();\n        return backend;\n      } catch (error) {\n        const errorMessage = (error as Error).message;\n\n        // If RuVector fails due to :memory: path or other initialization issues,\n        // try falling back to HNSWLib\n        if (detection.hnswlib) {\n          console.log('[AgentDB] RuVector initialization failed, falling back to HNSWLib');\n          console.log(`[AgentDB] Reason: ${errorMessage.split('\\n')[0]}`);\n          backend = new HNSWLibBackend(config);\n          console.log('[AgentDB] Using HNSWLib backend (fallback)');\n        } else {\n          // No fallback available, re-throw error\n          throw error;\n        }\n      }\n    } else if (detection.hnswlib) {\n      backend = new HNSWLibBackend(config);\n      console.log('[AgentDB] Using HNSWLib backend (fallback)');\n    } else {\n      throw new Error(\n        'No vector backend available.\\n' +\n        'Install one of:\\n' +\n        '  - npm install ruvector@0.1.99+ (recommended, includes native NAPI-RS)\\n' +\n        '  - npm install @ruvector/core (alternative)\\n' +\n        '  - npm install hnswlib-node (fallback)'\n      );\n    }\n  }\n\n  // Initialize the backend (if not already initialized)\n  // Note: RuVector may already be initialized in the try block above\n  try {\n    await (backend as any).initialize();\n  } catch (error) {\n    // Ignore if already initialized\n    if (!(error as Error).message.includes('already initialized')) {\n      throw error;\n    }\n  }\n\n  return backend;\n}\n\n/**\n * Get recommended backend type based on environment\n */\nexport async function getRecommendedBackend(): Promise<BackendType> {\n  const detection = await detectBackends();\n\n  if (detection.ruvector.core) {\n    return 'ruvector';\n  } else if (detection.hnswlib) {\n    return 'hnswlib';\n  } else {\n    return 'auto'; // Will throw error in createBackend\n  }\n}\n\n/**\n * Check if a specific backend is available\n */\nexport async function isBackendAvailable(backend: 'ruvector' | 'hnswlib'): Promise<boolean> {\n  const detection = await detectBackends();\n\n  if (backend === 'ruvector') {\n    return detection.ruvector.core;\n  }\n\n  return detection.hnswlib;\n}\n\n/**\n * Get installation instructions for a backend\n */\nexport function getInstallCommand(backend: 'ruvector' | 'hnswlib'): string {\n  return backend === 'ruvector'\n    ? 'npm install ruvector'\n    : 'npm install hnswlib-node';\n}\n\n// Re-export proof-gated types (ADR-060)\nexport { GuardedVectorBackend, ProofDeniedError };\n\n/**\n * Create a proof-gated vector backend (ADR-060)\n *\n * Wraps a standard VectorBackend with MutationGuard to require\n * cryptographic proofs for all mutating operations. Optionally\n * attaches an AttestationLog when a database handle is provided.\n *\n * @param type - Backend type: 'auto', 'ruvector', or 'hnswlib'\n * @param config - Vector configuration with optional database handle\n * @returns Object containing the guarded backend, guard, and optional log\n */\nexport async function createGuardedBackend(\n  type: BackendType,\n  config: VectorConfig & { database?: any; enableProofs?: boolean }\n): Promise<{ backend: GuardedVectorBackend; guard: MutationGuard; log: AttestationLog | null }> {\n  const detection = await detectBackends();\n  const inner = await createBackend(type, config);\n\n  // Enable proofs if graph-transformer is available or explicitly requested\n  const enableWasmProofs = config.enableProofs ?? detection.ruvector.graphTransformer ?? true;\n\n  const guard = new MutationGuard({\n    dimension: config.dimension ?? config.dimensions ?? 384,\n    maxElements: config.maxElements ?? 10000,\n    enableWasmProofs,\n    enableAttestationLog: true,\n    defaultNamespace: 'default',\n  });\n  await guard.initialize();\n\n  // Log the proof engine status\n  const stats = guard.getStats();\n  console.log(`[GuardedBackend] Proof engine: ${stats.engineType}, WASM available: ${stats.wasmAvailable}`);\n\n  let log: AttestationLog | null = null;\n  if (config.database) {\n    log = new AttestationLog(config.database);\n  }\n\n  return { backend: new GuardedVectorBackend(inner, guard, log ?? undefined), guard, log };\n}\n"]}

package/dist/packages/agentdb/src/backends/graph/GraphDatabaseAdapter.d.ts

@@ -1,151 +0,0 @@
-/**
- * RuVector Graph Database Adapter - Primary Database for AgentDB v2
- *
- * Replaces SQLite with RuVector's graph database for:
- * - Episodes as nodes with vector embeddings
- * - Skills as nodes with code embeddings
- * - Causal relationships as hyperedges
- * - Cypher queries instead of SQL
- *
- * Features:
- * - 10x faster than WASM SQLite
- * - ACID transactions with persistence
- * - Vector similarity search integrated
- * - Hypergraph support for complex relationships
- * - Neo4j-compatible Cypher syntax
- */
-type JsNode = {
-    id: string;
-    embedding: Float32Array;
-    labels?: Array<string>;
-    properties?: Record<string, string>;
-};
-type JsEdge = {
-    from: string;
-    to: string;
-    description: string;
-    embedding: Float32Array;
-    confidence?: number;
-    metadata?: Record<string, string>;
-};
-type JsQueryResult = {
-    nodes: Array<any>;
-    edges: Array<any>;
-    stats?: any;
-};
-export interface GraphDatabaseConfig {
-    storagePath: string;
-    dimensions?: number;
-    distanceMetric?: 'Cosine' | 'Euclidean' | 'DotProduct' | 'Manhattan';
-}
-export interface EpisodeNode {
-    id: string;
-    sessionId: string;
-    task: string;
-    reward: number;
-    success: boolean;
-    input?: string;
-    output?: string;
-    critique?: string;
-    createdAt: number;
-    tokensUsed?: number;
-    latencyMs?: number;
-}
-export interface SkillNode {
-    id: string;
-    name: string;
-    description: string;
-    code: string;
-    usageCount: number;
-    avgReward: number;
-    createdAt: number;
-    updatedAt: number;
-    tags?: string;
-}
-export interface CausalEdge {
-    from: string;
-    to: string;
-    mechanism: string;
-    uplift: number;
-    confidence: number;
-    sampleSize: number;
-}
-/**
- * Graph Database Adapter for AgentDB
- *
- * This replaces SQL.js as the primary database, using RuVector's graph DB
- * with Cypher queries, hyperedges, and integrated vector search.
- */
-export declare class GraphDatabaseAdapter {
-    private db;
-    private config;
-    private embedder;
-    constructor(config: GraphDatabaseConfig, embedder: any);
-    /**
-     * Initialize graph database (create new or open existing)
-     */
-    initialize(): Promise<void>;
-    /**
-     * Store an episode as a graph node
-     */
-    storeEpisode(episode: EpisodeNode, embedding: Float32Array): Promise<string>;
-    /**
-     * Store a skill as a graph node
-     */
-    storeSkill(skill: SkillNode, embedding: Float32Array): Promise<string>;
-    /**
-     * Create a causal relationship edge
-     */
-    createCausalEdge(edge: CausalEdge, embedding: Float32Array): Promise<string>;
-    /**
-     * Query using Cypher syntax
-     *
-     * Examples:
-     * - MATCH (e:Episode) WHERE e.success = 'true' RETURN e
-     * - MATCH (s:Skill) RETURN s ORDER BY s.avgReward DESC LIMIT 10
-     * - MATCH (e1:Episode)-[r]->(e2:Episode) RETURN e1, r, e2
-     */
-    query(cypher: string): Promise<JsQueryResult>;
-    /**
-     * Search for similar episodes by embedding
-     */
-    searchSimilarEpisodes(embedding: Float32Array, k?: number): Promise<any[]>;
-    /**
-     * Search for similar skills by embedding
-     */
-    searchSkills(embedding: Float32Array, k?: number): Promise<SkillNode[]>;
-    /**
-     * Generic createNode method for graph traversal scenarios
-     */
-    createNode(node: JsNode): Promise<string>;
-    /**
-     * Generic createEdge method for graph traversal scenarios
-     */
-    createEdge(edge: JsEdge): Promise<void>;
-    /**
-     * Get graph statistics
-     */
-    getStats(): Promise<any>;
-    /**
-     * Begin transaction
-     */
-    beginTransaction(): Promise<string>;
-    /**
-     * Commit transaction
-     */
-    commitTransaction(txId: string): Promise<void>;
-    /**
-     * Rollback transaction
-     */
-    rollbackTransaction(txId: string): Promise<void>;
-    /**
-     * Batch insert nodes and edges
-     */
-    batchInsert(nodes: JsNode[], edges: JsEdge[]): Promise<any>;
-    /**
-     * Close database
-     */
-    close(): void;
-}
-export {};
-//# sourceMappingURL=GraphDatabaseAdapter.d.ts.map

package/dist/packages/agentdb/src/backends/graph/GraphDatabaseAdapter.d.ts.map

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