agentdb 1.6.0 → 2.0.0-alpha.1

package/src/backends/VectorBackend.ts

@@ -0,0 +1,145 @@
+/**
+ * VectorBackend - Unified interface for vector database backends
+ *
+ * Provides abstraction over different vector search implementations
+ * (RuVector, hnswlib-node) for AgentDB v2.
+ *
+ * Design:
+ * - String-based IDs for all operations (backends handle label mapping internally)
+ * - Consistent SearchResult format across backends
+ * - Save/load with metadata persistence
+ * - Backend-specific optimizations hidden behind interface
+ */
+
+export interface VectorConfig {
+  /** Vector dimension (e.g., 384, 768, 1536) */
+  dimension: number;
+
+  /** Distance metric: 'cosine', 'l2' (Euclidean), 'ip' (inner product) */
+  metric: 'cosine' | 'l2' | 'ip';
+
+  /** Maximum number of elements (default: 100000) */
+  maxElements?: number;
+
+  /** HNSW M parameter - connections per layer (default: 16) */
+  M?: number;
+
+  /** HNSW efConstruction - build quality (default: 200) */
+  efConstruction?: number;
+
+  /** HNSW efSearch - search quality (default: 100) */
+  efSearch?: number;
+}
+
+export interface SearchResult {
+  /** String ID of the vector */
+  id: string;
+
+  /** Raw distance value from backend */
+  distance: number;
+
+  /** Normalized similarity (0-1, higher is more similar) */
+  similarity: number;
+
+  /** Optional metadata attached to vector */
+  metadata?: Record<string, any>;
+}
+
+export interface SearchOptions {
+  /** Minimum similarity threshold (0-1) */
+  threshold?: number;
+
+  /** Override efSearch for this query */
+  efSearch?: number;
+
+  /** Metadata filters (post-filtering) */
+  filter?: Record<string, any>;
+}
+
+export interface VectorStats {
+  /** Number of vectors in index */
+  count: number;
+
+  /** Vector dimension */
+  dimension: number;
+
+  /** Distance metric */
+  metric: string;
+
+  /** Backend name */
+  backend: 'ruvector' | 'hnswlib';
+
+  /** Memory usage in bytes (0 if not available) */
+  memoryUsage: number;
+}
+
+/**
+ * VectorBackend - Interface for vector search implementations
+ *
+ * All backends must:
+ * 1. Accept string IDs and handle label mapping internally
+ * 2. Normalize distances to similarities (0-1 range)
+ * 3. Support save/load with metadata persistence
+ * 4. Provide stats for monitoring
+ */
+export interface VectorBackend {
+  /** Backend name for detection and logging */
+  readonly name: 'ruvector' | 'hnswlib';
+
+  /**
+   * Insert a single vector with optional metadata
+   * @param id - Unique string identifier
+   * @param embedding - Vector as Float32Array
+   * @param metadata - Optional metadata to store with vector
+   */
+  insert(id: string, embedding: Float32Array, metadata?: Record<string, any>): void;
+
+  /**
+   * Insert multiple vectors in batch (more efficient)
+   * @param items - Array of {id, embedding, metadata?}
+   */
+  insertBatch(items: Array<{
+    id: string;
+    embedding: Float32Array;
+    metadata?: Record<string, any>;
+  }>): void;
+
+  /**
+   * Search for k-nearest neighbors
+   * @param query - Query vector
+   * @param k - Number of results
+   * @param options - Search options (threshold, efSearch, filters)
+   * @returns Sorted results (most similar first)
+   */
+  search(query: Float32Array, k: number, options?: SearchOptions): SearchResult[];
+
+  /**
+   * Remove a vector by ID
+   * @param id - Vector ID to remove
+   * @returns true if removed, false if not found
+   */
+  remove(id: string): boolean;
+
+  /**
+   * Get backend statistics
+   * @returns Stats object with count, dimension, backend name, etc.
+   */
+  getStats(): VectorStats;
+
+  /**
+   * Save index to disk
+   * @param path - File path (backend adds extensions as needed)
+   */
+  save(path: string): Promise<void>;
+
+  /**
+   * Load index from disk
+   * @param path - File path (backend looks for associated files)
+   */
+  load(path: string): Promise<void>;
+
+  /**
+   * Close and cleanup resources
+   */
+  close(): void;
+}

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.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,193 @@
+/**
+ * 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';
+
+export type BackendType = 'auto' | 'ruvector' | 'hnswlib';
+
+export interface BackendDetection {
+  available: 'ruvector' | 'hnswlib' | 'none';
+  ruvector: {
+    core: boolean;
+    gnn: boolean;
+    graph: boolean;
+    native: 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
+    },
+    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.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.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
+      }
+    } catch {
+      // RuVector not installed - will try fallback
+    }
+  }
+
+  // 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'})`
+      );
+    } 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
+  await (backend as any).initialize();
+
+  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';
+}