agentic-flow 2.0.7 → 3.0.0-alpha.2

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

@@ -0,0 +1,273 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/backends/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAC5F,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAgB/D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,MAAM,GAAqB;QAC/B,SAAS,EAAE,MAAM;QACjB,QAAQ,EAAE;YACR,IAAI,EAAE,KAAK;YACX,GAAG,EAAE,KAAK;YACV,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,KAAK;YACb,gBAAgB,EAAE,KAAK;SACxB;QACD,OAAO,EAAE,KAAK;KACf,CAAC;IAEF,4DAA4D;IAC5D,IAAI,CAAC;QACH,6CAA6C;QAC7C,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QAC1C,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC;QAC5B,MAAM,CAAC,QAAQ,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,4BAA4B;QACxD,MAAM,CAAC,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,8BAA8B;QAE5D,sDAAsD;QACtD,IAAI,OAAQ,QAAgB,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;YACrD,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAI,QAAgB,CAAC,QAAQ,EAAE,CAAC;QACxD,CAAC;aAAM,IAAI,OAAQ,QAAgB,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YAC3D,mBAAmB;YACnB,MAAM,OAAO,GAAI,QAAgB,CAAC,OAAO,EAAE,CAAC;YAC5C,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,MAAM,CAAC;QACtE,CAAC;QAED,MAAM,CAAC,SAAS,GAAG,UAAU,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,kCAAkC;QAClC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;YAC5C,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC;YAE5B,6CAA6C;YAC7C,IAAI,OAAQ,IAAY,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;gBACjD,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAI,IAAY,CAAC,QAAQ,EAAE,CAAC;YACpD,CAAC;iBAAM,IAAI,OAAQ,IAAY,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;gBACvD,MAAM,OAAO,GAAI,IAAY,CAAC,OAAO,EAAE,CAAC;gBACxC,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,MAAM,CAAC;YACtE,CAAC;YAED,MAAM,CAAC,SAAS,GAAG,UAAU,CAAC;YAE9B,0BAA0B;YAC1B,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,eAAe,CAAC,CAAC;gBAC9B,MAAM,CAAC,QAAQ,CAAC,GAAG,GAAG,IAAI,CAAC;YAC7B,CAAC;YAAC,MAAM,CAAC;gBACP,uCAAuC;YACzC,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;gBACrC,MAAM,CAAC,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAC;YAC/B,CAAC;YAAC,MAAM,CAAC;gBACP,yCAAyC;YAC3C,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,6BAAuC,CAAC,CAAC;gBACtD,MAAM,CAAC,QAAQ,CAAC,gBAAgB,GAAG,IAAI,CAAC;YAC1C,CAAC;YAAC,MAAM,CAAC;gBACP,6CAA6C;YAC/C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,6CAA6C;QAC/C,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC;QACtC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,6BAAuC,CAAC,CAAC;YACtD,MAAM,CAAC,QAAQ,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,mBAAmB;YACnB,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,iCAA2C,CAAC,CAAC;gBAC1D,MAAM,CAAC,QAAQ,CAAC,gBAAgB,GAAG,IAAI,CAAC;YAC1C,CAAC;YAAC,MAAM,CAAC;gBACP,8CAA8C;YAChD,CAAC;QACH,CAAC;IACH,CAAC;IAED,gBAAgB;IAChB,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC;QAC7B,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;QAEtB,IAAI,MAAM,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;YAChC,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC;QAC/B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,wBAAwB;IAC1B,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAiB,EACjB,MAAoB;IAEpB,MAAM,SAAS,GAAG,MAAM,cAAc,EAAE,CAAC;IAEzC,IAAI,OAAsB,CAAC;IAE3B,oCAAoC;IACpC,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,2BAA2B;gBAC3B,4CAA4C;gBAC5C,mDAAmD;gBACnD,0DAA0D,CAC3D,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;SAAM,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,0BAA0B;gBAC1B,wCAAwC,CACzC,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;SAAM,CAAC;QACN,qCAAqC;QACrC,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YAC5B,OAAO,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;YACtC,MAAM,WAAW,GAAG,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC;YAC1E,MAAM,WAAW,GAAG,SAAS,CAAC,QAAQ,CAAC,gBAAgB;gBACrD,CAAC,CAAC,4BAA4B;gBAC9B,CAAC,CAAC,mBAAmB,CAAC;YACxB,OAAO,CAAC,GAAG,CAAC,qCAAqC,WAAW,KAAK,WAAW,EAAE,CAAC,CAAC;YAEhF,8DAA8D;YAC9D,IAAI,CAAC;gBACH,MAAO,OAAe,CAAC,UAAU,EAAE,CAAC;gBACpC,OAAO,OAAO,CAAC;YACjB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,YAAY,GAAI,KAAe,CAAC,OAAO,CAAC;gBAE9C,yEAAyE;gBACzE,8BAA8B;gBAC9B,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC;oBACtB,OAAO,CAAC,GAAG,CAAC,mEAAmE,CAAC,CAAC;oBACjF,OAAO,CAAC,GAAG,CAAC,qBAAqB,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;oBAChE,OAAO,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;oBACrC,OAAO,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;gBAC5D,CAAC;qBAAM,CAAC;oBACN,wCAAwC;oBACxC,MAAM,KAAK,CAAC;gBACd,CAAC;YACH,CAAC;QACH,CAAC;aAAM,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC;YAC7B,OAAO,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;YACrC,OAAO,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;QAC5D,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CACb,gCAAgC;gBAChC,mBAAmB;gBACnB,2EAA2E;gBAC3E,gDAAgD;gBAChD,yCAAyC,CAC1C,CAAC;QACJ,CAAC;IACH,CAAC;IAED,sDAAsD;IACtD,mEAAmE;IACnE,IAAI,CAAC;QACH,MAAO,OAAe,CAAC,UAAU,EAAE,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gCAAgC;QAChC,IAAI,CAAE,KAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC;YAC9D,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB;IACzC,MAAM,SAAS,GAAG,MAAM,cAAc,EAAE,CAAC;IAEzC,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC5B,OAAO,UAAU,CAAC;IACpB,CAAC;SAAM,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC;QAC7B,OAAO,SAAS,CAAC;IACnB,CAAC;SAAM,CAAC;QACN,OAAO,MAAM,CAAC,CAAC,oCAAoC;IACrD,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAA+B;IACtE,MAAM,SAAS,GAAG,MAAM,cAAc,EAAE,CAAC;IAEzC,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3B,OAAO,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC;IACjC,CAAC;IAED,OAAO,SAAS,CAAC,OAAO,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA+B;IAC/D,OAAO,OAAO,KAAK,UAAU;QAC3B,CAAC,CAAC,sBAAsB;QACxB,CAAC,CAAC,0BAA0B,CAAC;AACjC,CAAC;AAED,wCAAwC;AACxC,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,CAAC;AAElD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,IAAiB,EACjB,MAAiE;IAEjE,MAAM,SAAS,GAAG,MAAM,cAAc,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAEhD,0EAA0E;IAC1E,MAAM,gBAAgB,GAAG,MAAM,CAAC,YAAY,IAAI,SAAS,CAAC,QAAQ,CAAC,gBAAgB,IAAI,IAAI,CAAC;IAE5F,MAAM,KAAK,GAAG,IAAI,aAAa,CAAC;QAC9B,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,UAAU,IAAI,GAAG;QACvD,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,KAAK;QACxC,gBAAgB;QAChB,oBAAoB,EAAE,IAAI;QAC1B,gBAAgB,EAAE,SAAS;KAC5B,CAAC,CAAC;IACH,MAAM,KAAK,CAAC,UAAU,EAAE,CAAC;IAEzB,8BAA8B;IAC9B,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC/B,OAAO,CAAC,GAAG,CAAC,kCAAkC,KAAK,CAAC,UAAU,qBAAqB,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC;IAE1G,IAAI,GAAG,GAA0B,IAAI,CAAC;IACtC,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,GAAG,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,oBAAoB,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,IAAI,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AAC3F,CAAC","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

@@ -0,0 +1,151 @@
+/**
+ * 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

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