agentdb 3.0.0-alpha.2 → 3.0.0-alpha.4

package/src/backends/detector.ts

@@ -0,0 +1,283 @@
+/**
+ * Backend Detection - Auto-detect available vector backends
+ *
+ * Detection priority:
+ * 1. RuVector (@ruvector/core) - preferred for performance
+ * 2. HNSWLib (hnswlib-node) - stable fallback
+ *
+ * Additional features detected:
+ * - @ruvector/gnn - GNN learning capabilities
+ * - @ruvector/graph-node - Graph database capabilities
+ */
+
+/**
+ * Backend type identifier
+ */
+export type BackendType = 'ruvector' | 'hnswlib' | 'auto';
+
+/**
+ * Platform information
+ */
+export interface PlatformInfo {
+  /** Operating system */
+  platform: NodeJS.Platform;
+
+  /** CPU architecture */
+  arch: string;
+
+  /** Combined platform identifier (e.g., 'linux-x64', 'darwin-arm64') */
+  combined: string;
+}
+
+/**
+ * Backend detection result
+ */
+export interface DetectionResult {
+  /** Detected backend type */
+  backend: 'ruvector' | 'hnswlib';
+
+  /** Available feature flags */
+  features: {
+    /** GNN learning available */
+    gnn: boolean;
+
+    /** Graph database available */
+    graph: boolean;
+
+    /** Compression available */
+    compression: boolean;
+  };
+
+  /** Platform information */
+  platform: PlatformInfo;
+
+  /** Whether native bindings are available (vs WASM fallback) */
+  native: boolean;
+
+  /** Version information */
+  versions?: {
+    core?: string;
+    gnn?: string;
+    graph?: string;
+  };
+}
+
+/**
+ * RuVector availability check result
+ */
+interface RuVectorAvailability {
+  available: boolean;
+  native: boolean;
+  gnn: boolean;
+  graph: boolean;
+  version?: string;
+}
+
+/**
+ * Detect available vector backend and features
+ *
+ * @returns Detection result with backend type and available features
+ */
+export async function detectBackend(): Promise<DetectionResult> {
+  // Get platform information
+  const platform = getPlatformInfo();
+
+  // Check for RuVector (preferred)
+  const ruvectorAvailable = await checkRuVector();
+
+  if (ruvectorAvailable.available) {
+    return {
+      backend: 'ruvector',
+      features: {
+        gnn: ruvectorAvailable.gnn,
+        graph: ruvectorAvailable.graph,
+        compression: true, // RuVector always supports compression
+      },
+      platform,
+      native: ruvectorAvailable.native,
+      versions: {
+        core: ruvectorAvailable.version,
+      },
+    };
+  }
+
+  // Fallback to HNSWLib
+  const hnswlibNative = await checkHnswlib();
+
+  return {
+    backend: 'hnswlib',
+    features: {
+      gnn: false,
+      graph: false,
+      compression: false,
+    },
+    platform,
+    native: hnswlibNative,
+  };
+}
+
+/**
+ * Check RuVector availability and features
+ */
+async function checkRuVector(): Promise<RuVectorAvailability> {
+  try {
+    // Try to import @ruvector/core
+    const core = await import('@ruvector/core');
+
+    // Check if native bindings are available
+    const native = (core as any).isNative?.() ?? false;
+
+    // Get version (if available)
+    const version = (core as any).version ?? 'unknown';
+
+    // Check for GNN support
+    let gnn = false;
+    try {
+      await import('@ruvector/gnn');
+      gnn = true;
+    } catch {
+      // GNN not available
+    }
+
+    // Check for Graph support
+    let graph = false;
+    try {
+      await import('@ruvector/graph-node');
+      graph = true;
+    } catch {
+      // Graph not available
+    }
+
+    return {
+      available: true,
+      native,
+      gnn,
+      graph,
+      version,
+    };
+  } catch (error) {
+    // RuVector not available
+    return {
+      available: false,
+      native: false,
+      gnn: false,
+      graph: false,
+    };
+  }
+}
+
+/**
+ * Check HNSWLib availability
+ */
+async function checkHnswlib(): Promise<boolean> {
+  try {
+    // Try to import hnswlib-node
+    await import('hnswlib-node');
+    return true;
+  } catch (error) {
+    console.warn('[AgentDB] HNSWLib not available:', error);
+    return false;
+  }
+}
+
+/**
+ * Get platform information
+ */
+function getPlatformInfo(): PlatformInfo {
+  return {
+    platform: process.platform,
+    arch: process.arch,
+    combined: `${process.platform}-${process.arch}`,
+  };
+}
+
+/**
+ * Validate requested backend is available
+ *
+ * @param requested - Requested backend type
+ * @param detected - Detected backend from auto-detection
+ * @throws Error if requested backend is not available
+ */
+export function validateBackend(
+  requested: BackendType,
+  detected: DetectionResult
+): void {
+  if (requested === 'auto') {
+    // Auto-detection always succeeds
+    return;
+  }
+
+  if (requested === 'ruvector' && detected.backend !== 'ruvector') {
+    throw new Error(
+      'RuVector backend requested but not available.\n' +
+        'Install with: npm install @ruvector/core\n' +
+        'See: https://github.com/ruvnet/ruvector'
+    );
+  }
+
+  if (requested === 'hnswlib' && detected.backend !== 'hnswlib') {
+    throw new Error(
+      'HNSWLib backend requested but not available.\n' +
+        'Install with: npm install hnswlib-node'
+    );
+  }
+}
+
+/**
+ * Get recommended backend for a given use case
+ *
+ * @param useCase - Use case identifier
+ * @returns Recommended backend type
+ */
+export function getRecommendedBackend(useCase: string): BackendType {
+  const useCaseLower = useCase.toLowerCase();
+
+  // RuVector recommended for advanced features
+  if (
+    useCaseLower.includes('learning') ||
+    useCaseLower.includes('gnn') ||
+    useCaseLower.includes('graph') ||
+    useCaseLower.includes('compression')
+  ) {
+    return 'ruvector';
+  }
+
+  // Auto-detection for general use
+  return 'auto';
+}
+
+/**
+ * Format detection result for display
+ *
+ * @param result - Detection result
+ * @returns Formatted string for console output
+ */
+export function formatDetectionResult(result: DetectionResult): string {
+  const lines: string[] = [];
+
+  lines.push('📊 Backend Detection Results:');
+  lines.push('');
+  lines.push(`  Backend:     ${result.backend}`);
+  lines.push(`  Platform:    ${result.platform.combined}`);
+  lines.push(`  Native:      ${result.native ? '✅' : '❌ (using WASM)'}`);
+  lines.push(`  GNN:         ${result.features.gnn ? '✅' : '❌'}`);
+  lines.push(`  Graph:       ${result.features.graph ? '✅' : '❌'}`);
+  lines.push(`  Compression: ${result.features.compression ? '✅' : '❌'}`);
+
+  if (result.versions?.core) {
+    lines.push(`  Version:     ${result.versions.core}`);
+  }
+
+  lines.push('');
+
+  // Add recommendations
+  if (result.backend === 'hnswlib') {
+    lines.push('💡 Tip: Install @ruvector/core for 150x faster performance');
+    lines.push('   npm install @ruvector/core');
+  } else if (!result.features.gnn) {
+    lines.push('💡 Tip: Install @ruvector/gnn for adaptive learning');
+    lines.push('   npm install @ruvector/gnn');
+  }
+
+  return lines.join('\n');
+}

package/src/backends/factory.ts

@@ -0,0 +1,279 @@
+/**
+ * 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 type { VectorBackend, VectorConfig } from './VectorBackend.js';
+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';
+
+export type BackendType = 'auto' | 'ruvector' | 'hnswlib';
+
+export interface BackendDetection {
+  available: 'ruvector' | 'hnswlib' | 'none';
+  ruvector: {
+    core: boolean;
+    gnn: boolean;
+    graph: boolean;
+    native: boolean;
+    graphTransformer: boolean;
+  };
+  hnswlib: boolean;
+}
+
+/**
+ * Detect available vector backends
+ */
+export async function detectBackends(): Promise<BackendDetection> {
+  const result: BackendDetection = {
+    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
+    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
+    result.ruvector.native = (ruvector as any).isNative?.() ?? false;
+    result.available = 'ruvector';
+  } catch {
+    // Try scoped packages as fallback
+    try {
+      const core = await import('@ruvector/core');
+      result.ruvector.core = true;
+      result.ruvector.native = (core as any).isNative?.() ?? false;
+      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' as string);
+        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' as string);
+      result.ruvector.graphTransformer = true;
+    } catch {
+      // graph-transformer not installed
+    }
+  }
+
+  // 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: BackendType,
+  config: VectorConfig
+): Promise<VectorBackend> {
+  const detection = await detectBackends();
+
+  let backend: VectorBackend;
+
+  // 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);
+      console.log(
+        `[AgentDB] Using RuVector backend (${detection.ruvector.native ? 'native' : 'WASM'})`
+      );
+
+      // Try to initialize RuVector, fallback to HNSWLib if it fails
+      try {
+        await (backend as any).initialize();
+        return backend;
+      } catch (error) {
+        const errorMessage = (error as 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/core (recommended)\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 as any).initialize();
+  } catch (error) {
+    // Ignore if already initialized
+    if (!(error as Error).message.includes('already initialized')) {
+      throw error;
+    }
+  }
+
+  return backend;
+}
+
+/**
+ * Get recommended backend type based on environment
+ */
+export async function getRecommendedBackend(): Promise<BackendType> {
+  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: 'ruvector' | 'hnswlib'): Promise<boolean> {
+  const detection = await detectBackends();
+
+  if (backend === 'ruvector') {
+    return detection.ruvector.core;
+  }
+
+  return detection.hnswlib;
+}
+
+/**
+ * Get installation instructions for a backend
+ */
+export function getInstallCommand(backend: 'ruvector' | 'hnswlib'): string {
+  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: BackendType,
+  config: VectorConfig & { database?: any }
+): Promise<{ backend: GuardedVectorBackend; guard: MutationGuard; log: AttestationLog | null }> {
+  const inner = await createBackend(type, config);
+  const guard = new MutationGuard({
+    dimension: config.dimension ?? config.dimensions ?? 384,
+    maxElements: config.maxElements ?? 10000,
+    enableWasmProofs: true,
+    enableAttestationLog: true,
+    defaultNamespace: 'default',
+  });
+  await guard.initialize();
+
+  let log: AttestationLog | null = null;
+  if (config.database) {
+    log = new AttestationLog(config.database);
+  }
+
+  return { backend: new GuardedVectorBackend(inner, guard, log ?? undefined), guard, log };
+}