agentic-flow 2.0.7 → 3.0.0-alpha.2

package/dist/packages/agentdb/src/backends/ruvector/RuVectorBackend.js

@@ -0,0 +1,441 @@
+/**
+ * RuVectorBackend - High-Performance Vector Storage (v0.1.99+)
+ *
+ * Implements VectorBackend using ruvector with native SIMD and multi-threading.
+ * Updated for ruvector 0.1.99+ async API with object-style insert/search.
+ *
+ * Features:
+ * - Native SIMD acceleration (2-4x faster vector ops)
+ * - Automatic fallback when ruvector packages not installed
+ * - Separate metadata storage for rich queries
+ * - Score-to-similarity conversion for all metrics
+ * - Batch operations for optimal throughput
+ * - Parallel batch search via searchBatch()
+ * - Persistent storage with separate metadata files
+ */
+export class RuVectorBackend {
+    name = 'ruvector';
+    db; // VectorDB from ruvector 0.1.99+
+    config;
+    metadata = new Map();
+    initialized = false;
+    learning = null;
+    nativeVersion = 'unknown';
+    isNativeImpl = false;
+    constructor(config) {
+        // Handle both dimension and dimensions for backward compatibility
+        const dimension = config.dimension ?? config.dimensions;
+        if (!dimension) {
+            throw new Error('Vector dimension is required (use dimension or dimensions)');
+        }
+        // Store both forms for compatibility with different backends
+        this.config = { ...config, dimension, dimensions: dimension };
+    }
+    /**
+     * Initialize RuVector database with SIMD and multi-threading (0.1.99+)
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        try {
+            // Try main ruvector package first (0.1.99+ with native SIMD)
+            let VectorDB;
+            let ruvectorModule;
+            try {
+                ruvectorModule = await import('ruvector');
+                VectorDB = ruvectorModule.VectorDB || ruvectorModule.default?.VectorDB;
+            }
+            catch {
+                // Fallback to @ruvector/core for backward compatibility
+                ruvectorModule = await import('@ruvector/core');
+                VectorDB = ruvectorModule.VectorDB || ruvectorModule.default?.VectorDB;
+            }
+            if (!VectorDB) {
+                throw new Error('Could not find VectorDB export in ruvector');
+            }
+            // Handle both 'dimension' and 'dimensions' for backward compatibility
+            const dimensions = this.config.dimension ?? this.config.dimensions;
+            if (!dimensions) {
+                throw new Error('Vector dimension is required (use dimension or dimensions)');
+            }
+            // RuVector 0.1.99+ constructor - uses 'dimensions' (plural)
+            this.db = new VectorDB({
+                dimensions: dimensions,
+                metric: this.config.metric,
+                maxElements: this.config.maxElements || 100000,
+                efConstruction: this.config.efConstruction || 200,
+                m: this.config.M || 16
+            });
+            // Detect native SIMD availability
+            if (ruvectorModule.isNative) {
+                this.isNativeImpl = ruvectorModule.isNative();
+            }
+            if (ruvectorModule.getVersion) {
+                const vInfo = ruvectorModule.getVersion();
+                this.nativeVersion = typeof vInfo === 'string' ? vInfo : vInfo?.version || 'unknown';
+            }
+            this.initialized = true;
+        }
+        catch (error) {
+            const errorMessage = error.message;
+            if (errorMessage.includes('Path traversal') || errorMessage.includes('Invalid path')) {
+                throw new Error(`RuVector does not support :memory: database paths.\n` +
+                    `Use a file path instead, or RuVector will be skipped and fallback backend will be used.\n` +
+                    `Original error: ${errorMessage}`);
+            }
+            throw new Error(`RuVector initialization failed. Please install: npm install ruvector@latest\n` +
+                `Or legacy packages: npm install @ruvector/core\n` +
+                `Error: ${errorMessage}`);
+        }
+    }
+    /**
+     * Insert single vector with optional metadata.
+     * Uses ruvector 0.1.99+ object-style API: insert({ id, vector, metadata? })
+     */
+    insert(id, embedding, metadata) {
+        this.ensureInitialized();
+        // ruvector 0.1.99+ uses object-style insert with async support
+        // The VectorBackend interface is sync, so we call without awaiting.
+        // The underlying native impl handles this via napi-rs sync path.
+        const entry = {
+            id,
+            vector: Array.from(embedding)
+        };
+        if (metadata) {
+            entry.metadata = metadata;
+            this.metadata.set(id, metadata);
+        }
+        // ruvector 0.1.99+ insert returns a promise, but the native layer
+        // executes synchronously. We fire-and-forget for interface compat.
+        const result = this.db.insert(entry);
+        if (result && typeof result.catch === 'function') {
+            result.catch((err) => {
+                console.error(`[RuVectorBackend] Insert failed for ${id}: ${err.message}`);
+            });
+        }
+    }
+    /**
+     * Batch insert for optimal performance.
+     * Uses ruvector 0.1.99+ insertBatch([{ id, vector, metadata? }])
+     */
+    insertBatch(items) {
+        this.ensureInitialized();
+        const entries = items.map(item => {
+            const entry = {
+                id: item.id,
+                vector: Array.from(item.embedding)
+            };
+            if (item.metadata) {
+                entry.metadata = item.metadata;
+                this.metadata.set(item.id, item.metadata);
+            }
+            return entry;
+        });
+        const result = this.db.insertBatch(entries);
+        if (result && typeof result.catch === 'function') {
+            result.catch((err) => {
+                console.error(`[RuVectorBackend] Batch insert failed: ${err.message}`);
+            });
+        }
+    }
+    /**
+     * Set a RuVectorLearning instance for GNN-enhanced search
+     */
+    setLearning(learning) {
+        this.learning = learning;
+    }
+    /**
+     * Get the current RuVectorLearning instance, if any
+     */
+    getLearning() {
+        return this.learning;
+    }
+    /**
+     * Search for k-nearest neighbors with optional filtering and GNN enhancement.
+     * Uses ruvector 0.1.99+ search({ vector, k, efSearch?, filter? })
+     * Results contain { id, score, vector?, metadata? }
+     */
+    search(query, k, options) {
+        this.ensureInitialized();
+        // Build search query for ruvector 0.1.99+ API
+        const searchQuery = {
+            vector: Array.from(query),
+            k
+        };
+        if (options?.efSearch) {
+            searchQuery.efSearch = options.efSearch;
+        }
+        if (options?.filter) {
+            searchQuery.filter = options.filter;
+        }
+        // ruvector 0.1.99+ search is async but native layer is sync
+        let rawResults = [];
+        const searchPromise = this.db.search(searchQuery);
+        if (searchPromise && typeof searchPromise.then === 'function') {
+            // Synchronous extraction for interface compat - the native binding
+            // resolves immediately when using N-API sync path
+            // For truly async scenarios, use searchBatch() instead
+            let resolved = false;
+            searchPromise.then((r) => {
+                rawResults = r || [];
+                resolved = true;
+            });
+            // If promise resolved synchronously (common with native bindings)
+            if (!resolved) {
+                // Fallback: return empty and log warning
+                console.warn('[RuVectorBackend] Search returned async promise; use searchBatch() for async searches');
+                return [];
+            }
+        }
+        else {
+            rawResults = searchPromise || [];
+        }
+        // Convert ruvector 0.1.99+ results (score-based) to SearchResult format
+        let results = rawResults
+            .map((r) => ({
+            id: r.id,
+            distance: this.scoreToDistance(r.score),
+            similarity: r.score,
+            metadata: r.metadata || this.metadata.get(r.id)
+        }))
+            .filter((r) => {
+            if (options?.threshold && r.similarity < options.threshold) {
+                return false;
+            }
+            if (options?.filter && r.metadata) {
+                return Object.entries(options.filter).every(([key, value]) => r.metadata[key] === value);
+            }
+            return true;
+        });
+        // Enhance with GNN if available
+        if (this.learning && this.learning.getState().initialized && results.length > 0) {
+            try {
+                const neighbors = [];
+                const weights = [];
+                for (const r of results) {
+                    weights.push(r.similarity);
+                    neighbors.push(query);
+                }
+                for (let i = 0; i < rawResults.length && i < results.length; i++) {
+                    const raw = rawResults[i];
+                    if (raw.vector) {
+                        const vec = raw.vector instanceof Float32Array
+                            ? raw.vector
+                            : new Float32Array(Object.values(raw.vector));
+                        neighbors[i] = vec;
+                    }
+                }
+                const enhanced = this.learning.enhance(query, neighbors, weights);
+                if (enhanced && enhanced.length > 0) {
+                    const enhancedQuery = {
+                        vector: Array.from(enhanced),
+                        k
+                    };
+                    if (options?.efSearch)
+                        enhancedQuery.efSearch = options.efSearch;
+                    const enhancedPromise = this.db.search(enhancedQuery);
+                    let enhancedRaw = [];
+                    if (enhancedPromise && typeof enhancedPromise.then === 'function') {
+                        let resolved = false;
+                        enhancedPromise.then((r) => { enhancedRaw = r || []; resolved = true; });
+                        if (!resolved)
+                            return results;
+                    }
+                    else {
+                        enhancedRaw = enhancedPromise || [];
+                    }
+                    const enhancedResults = enhancedRaw
+                        .map((r) => ({
+                        id: r.id,
+                        distance: this.scoreToDistance(r.score),
+                        similarity: r.score,
+                        metadata: r.metadata || this.metadata.get(r.id)
+                    }))
+                        .filter((r) => {
+                        if (options?.threshold && r.similarity < options.threshold)
+                            return false;
+                        if (options?.filter && r.metadata) {
+                            return Object.entries(options.filter).every(([key, value]) => r.metadata[key] === value);
+                        }
+                        return true;
+                    });
+                    if (enhancedResults.length > 0) {
+                        results = enhancedResults;
+                    }
+                }
+            }
+            catch {
+                // Fall through to raw results if GNN enhancement fails
+            }
+        }
+        return results;
+    }
+    /**
+     * Batch search for parallel query processing (0.1.99+).
+     * Executes multiple searches concurrently for throughput.
+     */
+    async searchBatch(queries, k, options) {
+        this.ensureInitialized();
+        const results = await Promise.all(queries.map(async (query) => {
+            const searchQuery = {
+                vector: Array.from(query),
+                k
+            };
+            if (options?.efSearch)
+                searchQuery.efSearch = options.efSearch;
+            if (options?.filter)
+                searchQuery.filter = options.filter;
+            const rawResults = await this.db.search(searchQuery);
+            return (rawResults || []).map((r) => ({
+                id: r.id,
+                distance: this.scoreToDistance(r.score),
+                similarity: r.score,
+                metadata: r.metadata || this.metadata.get(r.id)
+            })).filter((r) => {
+                if (options?.threshold && r.similarity < options.threshold)
+                    return false;
+                if (options?.filter && r.metadata) {
+                    return Object.entries(options.filter).every(([key, value]) => r.metadata[key] === value);
+                }
+                return true;
+            });
+        }));
+        return results;
+    }
+    /**
+     * Remove vector by ID.
+     * Uses ruvector 0.1.99+ delete(id) instead of remove(id)
+     */
+    remove(id) {
+        this.ensureInitialized();
+        this.metadata.delete(id);
+        try {
+            const result = this.db.delete(id);
+            // Handle async result
+            if (result && typeof result.then === 'function') {
+                let resolved = false;
+                let success = false;
+                result.then((r) => { success = r; resolved = true; });
+                if (resolved)
+                    return success;
+                // Fire-and-forget for async case
+                result.catch(() => { });
+                return true;
+            }
+            return result !== false;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get database statistics including native SIMD status
+     */
+    getStats() {
+        this.ensureInitialized();
+        let count = 0;
+        const lenResult = this.db.len();
+        if (lenResult && typeof lenResult.then === 'function') {
+            let resolved = false;
+            lenResult.then((c) => { count = c; resolved = true; });
+            if (!resolved)
+                count = this.metadata.size; // fallback
+        }
+        else {
+            count = lenResult || 0;
+        }
+        return {
+            count,
+            dimension: this.config.dimension || 384,
+            metric: this.config.metric,
+            backend: 'ruvector',
+            memoryUsage: 0,
+            // Extended stats for 0.1.99+
+            ...(this.isNativeImpl && {
+                nativeVersion: this.nativeVersion,
+                simdEnabled: true,
+                implementation: 'native'
+            })
+        };
+    }
+    /**
+     * Get extended stats including SIMD and version info
+     */
+    getExtendedStats() {
+        const base = this.getStats();
+        return {
+            count: base.count,
+            dimension: base.dimension,
+            metric: base.metric,
+            backend: base.backend,
+            nativeVersion: this.nativeVersion,
+            isNative: this.isNativeImpl,
+            simdEnabled: this.isNativeImpl
+        };
+    }
+    /**
+     * Save index and metadata to disk
+     */
+    async save(path) {
+        this.ensureInitialized();
+        // Save vector index (if ruvector supports it)
+        if (typeof this.db.save === 'function') {
+            await this.db.save(path);
+        }
+        // Save metadata separately as JSON
+        const metadataPath = path + '.meta.json';
+        const fs = await import('fs/promises');
+        await fs.writeFile(metadataPath, JSON.stringify(Object.fromEntries(this.metadata), null, 2));
+    }
+    /**
+     * Load index and metadata from disk
+     */
+    async load(path) {
+        this.ensureInitialized();
+        // Load vector index (if ruvector supports it)
+        if (typeof this.db.load === 'function') {
+            await this.db.load(path);
+        }
+        // Load metadata
+        const metadataPath = path + '.meta.json';
+        try {
+            const fs = await import('fs/promises');
+            const data = await fs.readFile(metadataPath, 'utf-8');
+            this.metadata = new Map(Object.entries(JSON.parse(data)));
+        }
+        catch {
+            console.debug(`[RuVectorBackend] No metadata file found at ${metadataPath}`);
+        }
+    }
+    /**
+     * Close and cleanup resources
+     */
+    close() {
+        this.metadata.clear();
+    }
+    /**
+     * Convert score to distance for backward compatibility.
+     * ruvector 0.1.99+ returns scores (higher = more similar).
+     */
+    scoreToDistance(score) {
+        switch (this.config.metric) {
+            case 'cosine':
+                return 1 - score;
+            case 'l2':
+                return score === 0 ? Infinity : -Math.log(score);
+            case 'ip':
+                return -score;
+            default:
+                return 1 - score;
+        }
+    }
+    /**
+     * Ensure database is initialized before operations
+     */
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('RuVectorBackend not initialized. Call initialize() first.');
+        }
+    }
+}
+//# sourceMappingURL=RuVectorBackend.js.map

package/dist/packages/agentdb/src/backends/ruvector/RuVectorBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuVectorBackend.js","sourceRoot":"","sources":["../../../../../../../packages/agentdb/src/backends/ruvector/RuVectorBackend.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * RuVectorBackend - High-Performance Vector Storage (v0.1.99+)\n *\n * Implements VectorBackend using ruvector with native SIMD and multi-threading.\n * Updated for ruvector 0.1.99+ async API with object-style insert/search.\n *\n * Features:\n * - Native SIMD acceleration (2-4x faster vector ops)\n * - Automatic fallback when ruvector packages not installed\n * - Separate metadata storage for rich queries\n * - Score-to-similarity conversion for all metrics\n * - Batch operations for optimal throughput\n * - Parallel batch search via searchBatch()\n * - Persistent storage with separate metadata files\n */\n\nimport type { VectorBackend, VectorConfig, SearchResult, SearchOptions, VectorStats } from '../VectorBackend.js';\nimport type { RuVectorLearning } from './RuVectorLearning.js';\n\nexport class RuVectorBackend implements VectorBackend {\n  readonly name = 'ruvector' as const;\n  private db: any; // VectorDB from ruvector 0.1.99+\n  private config: VectorConfig;\n  private metadata: Map<string, Record<string, any>> = new Map();\n  private initialized = false;\n  private learning: RuVectorLearning | null = null;\n  private nativeVersion: string = 'unknown';\n  private isNativeImpl: boolean = false;\n\n  constructor(config: VectorConfig) {\n    // Handle both dimension and dimensions for backward compatibility\n    const dimension = config.dimension ?? config.dimensions;\n    if (!dimension) {\n      throw new Error('Vector dimension is required (use dimension or dimensions)');\n    }\n    // Store both forms for compatibility with different backends\n    this.config = { ...config, dimension, dimensions: dimension };\n  }\n\n  /**\n   * Initialize RuVector database with SIMD and multi-threading (0.1.99+)\n   */\n  async initialize(): Promise<void> {\n    if (this.initialized) return;\n\n    try {\n      // Try main ruvector package first (0.1.99+ with native SIMD)\n      let VectorDB;\n      let ruvectorModule: any;\n      try {\n        ruvectorModule = await import('ruvector');\n        VectorDB = ruvectorModule.VectorDB || ruvectorModule.default?.VectorDB;\n      } catch {\n        // Fallback to @ruvector/core for backward compatibility\n        ruvectorModule = await import('@ruvector/core');\n        VectorDB = ruvectorModule.VectorDB || ruvectorModule.default?.VectorDB;\n      }\n\n      if (!VectorDB) {\n        throw new Error('Could not find VectorDB export in ruvector');\n      }\n\n      // Handle both 'dimension' and 'dimensions' for backward compatibility\n      const dimensions = this.config.dimension ?? this.config.dimensions;\n      if (!dimensions) {\n        throw new Error('Vector dimension is required (use dimension or dimensions)');\n      }\n\n      // RuVector 0.1.99+ constructor - uses 'dimensions' (plural)\n      this.db = new VectorDB({\n        dimensions: dimensions,\n        metric: this.config.metric,\n        maxElements: this.config.maxElements || 100000,\n        efConstruction: this.config.efConstruction || 200,\n        m: this.config.M || 16\n      });\n\n      // Detect native SIMD availability\n      if (ruvectorModule.isNative) {\n        this.isNativeImpl = ruvectorModule.isNative();\n      }\n      if (ruvectorModule.getVersion) {\n        const vInfo = ruvectorModule.getVersion();\n        this.nativeVersion = typeof vInfo === 'string' ? vInfo : vInfo?.version || 'unknown';\n      }\n\n      this.initialized = true;\n    } catch (error) {\n      const errorMessage = (error as Error).message;\n\n      if (errorMessage.includes('Path traversal') || errorMessage.includes('Invalid path')) {\n        throw new Error(\n          `RuVector does not support :memory: database paths.\\n` +\n          `Use a file path instead, or RuVector will be skipped and fallback backend will be used.\\n` +\n          `Original error: ${errorMessage}`\n        );\n      }\n\n      throw new Error(\n        `RuVector initialization failed. Please install: npm install ruvector@latest\\n` +\n        `Or legacy packages: npm install @ruvector/core\\n` +\n        `Error: ${errorMessage}`\n      );\n    }\n  }\n\n  /**\n   * Insert single vector with optional metadata.\n   * Uses ruvector 0.1.99+ object-style API: insert({ id, vector, metadata? })\n   */\n  insert(id: string, embedding: Float32Array, metadata?: Record<string, any>): void {\n    this.ensureInitialized();\n\n    // ruvector 0.1.99+ uses object-style insert with async support\n    // The VectorBackend interface is sync, so we call without awaiting.\n    // The underlying native impl handles this via napi-rs sync path.\n    const entry: any = {\n      id,\n      vector: Array.from(embedding)\n    };\n\n    if (metadata) {\n      entry.metadata = metadata;\n      this.metadata.set(id, metadata);\n    }\n\n    // ruvector 0.1.99+ insert returns a promise, but the native layer\n    // executes synchronously. We fire-and-forget for interface compat.\n    const result = this.db.insert(entry);\n    if (result && typeof result.catch === 'function') {\n      result.catch((err: Error) => {\n        console.error(`[RuVectorBackend] Insert failed for ${id}: ${err.message}`);\n      });\n    }\n  }\n\n  /**\n   * Batch insert for optimal performance.\n   * Uses ruvector 0.1.99+ insertBatch([{ id, vector, metadata? }])\n   */\n  insertBatch(items: Array<{ id: string; embedding: Float32Array; metadata?: Record<string, any> }>): void {\n    this.ensureInitialized();\n\n    const entries = items.map(item => {\n      const entry: any = {\n        id: item.id,\n        vector: Array.from(item.embedding)\n      };\n      if (item.metadata) {\n        entry.metadata = item.metadata;\n        this.metadata.set(item.id, item.metadata);\n      }\n      return entry;\n    });\n\n    const result = this.db.insertBatch(entries);\n    if (result && typeof result.catch === 'function') {\n      result.catch((err: Error) => {\n        console.error(`[RuVectorBackend] Batch insert failed: ${err.message}`);\n      });\n    }\n  }\n\n  /**\n   * Set a RuVectorLearning instance for GNN-enhanced search\n   */\n  setLearning(learning: RuVectorLearning | null): void {\n    this.learning = learning;\n  }\n\n  /**\n   * Get the current RuVectorLearning instance, if any\n   */\n  getLearning(): RuVectorLearning | null {\n    return this.learning;\n  }\n\n  /**\n   * Search for k-nearest neighbors with optional filtering and GNN enhancement.\n   * Uses ruvector 0.1.99+ search({ vector, k, efSearch?, filter? })\n   * Results contain { id, score, vector?, metadata? }\n   */\n  search(query: Float32Array, k: number, options?: SearchOptions): SearchResult[] {\n    this.ensureInitialized();\n\n    // Build search query for ruvector 0.1.99+ API\n    const searchQuery: any = {\n      vector: Array.from(query),\n      k\n    };\n\n    if (options?.efSearch) {\n      searchQuery.efSearch = options.efSearch;\n    }\n\n    if (options?.filter) {\n      searchQuery.filter = options.filter;\n    }\n\n    // ruvector 0.1.99+ search is async but native layer is sync\n    let rawResults: any[] = [];\n    const searchPromise = this.db.search(searchQuery);\n\n    if (searchPromise && typeof searchPromise.then === 'function') {\n      // Synchronous extraction for interface compat - the native binding\n      // resolves immediately when using N-API sync path\n      // For truly async scenarios, use searchBatch() instead\n      let resolved = false;\n      searchPromise.then((r: any[]) => {\n        rawResults = r || [];\n        resolved = true;\n      });\n\n      // If promise resolved synchronously (common with native bindings)\n      if (!resolved) {\n        // Fallback: return empty and log warning\n        console.warn('[RuVectorBackend] Search returned async promise; use searchBatch() for async searches');\n        return [];\n      }\n    } else {\n      rawResults = searchPromise || [];\n    }\n\n    // Convert ruvector 0.1.99+ results (score-based) to SearchResult format\n    let results: SearchResult[] = rawResults\n      .map((r: { id: string; score: number; metadata?: any }) => ({\n        id: r.id,\n        distance: this.scoreToDistance(r.score),\n        similarity: r.score,\n        metadata: r.metadata || this.metadata.get(r.id)\n      }))\n      .filter((r: SearchResult) => {\n        if (options?.threshold && r.similarity < options.threshold) {\n          return false;\n        }\n        if (options?.filter && r.metadata) {\n          return Object.entries(options.filter).every(\n            ([key, value]) => r.metadata![key] === value\n          );\n        }\n        return true;\n      });\n\n    // Enhance with GNN if available\n    if (this.learning && this.learning.getState().initialized && results.length > 0) {\n      try {\n        const neighbors: Float32Array[] = [];\n        const weights: number[] = [];\n        for (const r of results) {\n          weights.push(r.similarity);\n          neighbors.push(query);\n        }\n\n        for (let i = 0; i < rawResults.length && i < results.length; i++) {\n          const raw = rawResults[i];\n          if (raw.vector) {\n            const vec = raw.vector instanceof Float32Array\n              ? raw.vector\n              : new Float32Array(Object.values(raw.vector) as number[]);\n            neighbors[i] = vec;\n          }\n        }\n\n        const enhanced = this.learning.enhance(query, neighbors, weights);\n        if (enhanced && enhanced.length > 0) {\n          const enhancedQuery: any = {\n            vector: Array.from(enhanced),\n            k\n          };\n          if (options?.efSearch) enhancedQuery.efSearch = options.efSearch;\n\n          const enhancedPromise = this.db.search(enhancedQuery);\n          let enhancedRaw: any[] = [];\n          if (enhancedPromise && typeof enhancedPromise.then === 'function') {\n            let resolved = false;\n            enhancedPromise.then((r: any[]) => { enhancedRaw = r || []; resolved = true; });\n            if (!resolved) return results;\n          } else {\n            enhancedRaw = enhancedPromise || [];\n          }\n\n          const enhancedResults: SearchResult[] = enhancedRaw\n            .map((r: { id: string; score: number; metadata?: any }) => ({\n              id: r.id,\n              distance: this.scoreToDistance(r.score),\n              similarity: r.score,\n              metadata: r.metadata || this.metadata.get(r.id)\n            }))\n            .filter((r: SearchResult) => {\n              if (options?.threshold && r.similarity < options.threshold) return false;\n              if (options?.filter && r.metadata) {\n                return Object.entries(options.filter).every(\n                  ([key, value]) => r.metadata![key] === value\n                );\n              }\n              return true;\n            });\n\n          if (enhancedResults.length > 0) {\n            results = enhancedResults;\n          }\n        }\n      } catch {\n        // Fall through to raw results if GNN enhancement fails\n      }\n    }\n\n    return results;\n  }\n\n  /**\n   * Batch search for parallel query processing (0.1.99+).\n   * Executes multiple searches concurrently for throughput.\n   */\n  async searchBatch(\n    queries: Float32Array[],\n    k: number,\n    options?: SearchOptions\n  ): Promise<SearchResult[][]> {\n    this.ensureInitialized();\n\n    const results = await Promise.all(\n      queries.map(async (query) => {\n        const searchQuery: any = {\n          vector: Array.from(query),\n          k\n        };\n        if (options?.efSearch) searchQuery.efSearch = options.efSearch;\n        if (options?.filter) searchQuery.filter = options.filter;\n\n        const rawResults = await this.db.search(searchQuery);\n        return (rawResults || []).map((r: { id: string; score: number; metadata?: any }) => ({\n          id: r.id,\n          distance: this.scoreToDistance(r.score),\n          similarity: r.score,\n          metadata: r.metadata || this.metadata.get(r.id)\n        })).filter((r: SearchResult) => {\n          if (options?.threshold && r.similarity < options.threshold) return false;\n          if (options?.filter && r.metadata) {\n            return Object.entries(options.filter).every(\n              ([key, value]) => r.metadata![key] === value\n            );\n          }\n          return true;\n        });\n      })\n    );\n\n    return results;\n  }\n\n  /**\n   * Remove vector by ID.\n   * Uses ruvector 0.1.99+ delete(id) instead of remove(id)\n   */\n  remove(id: string): boolean {\n    this.ensureInitialized();\n    this.metadata.delete(id);\n\n    try {\n      const result = this.db.delete(id);\n      // Handle async result\n      if (result && typeof result.then === 'function') {\n        let resolved = false;\n        let success = false;\n        result.then((r: boolean) => { success = r; resolved = true; });\n        if (resolved) return success;\n        // Fire-and-forget for async case\n        result.catch(() => {});\n        return true;\n      }\n      return result !== false;\n    } catch {\n      return false;\n    }\n  }\n\n  /**\n   * Get database statistics including native SIMD status\n   */\n  getStats(): VectorStats {\n    this.ensureInitialized();\n\n    let count = 0;\n    const lenResult = this.db.len();\n    if (lenResult && typeof lenResult.then === 'function') {\n      let resolved = false;\n      lenResult.then((c: number) => { count = c; resolved = true; });\n      if (!resolved) count = this.metadata.size; // fallback\n    } else {\n      count = lenResult || 0;\n    }\n\n    return {\n      count,\n      dimension: this.config.dimension || 384,\n      metric: this.config.metric,\n      backend: 'ruvector',\n      memoryUsage: 0,\n      // Extended stats for 0.1.99+\n      ...(this.isNativeImpl && {\n        nativeVersion: this.nativeVersion,\n        simdEnabled: true,\n        implementation: 'native'\n      })\n    } as VectorStats;\n  }\n\n  /**\n   * Get extended stats including SIMD and version info\n   */\n  getExtendedStats(): {\n    count: number;\n    dimension: number;\n    metric: string;\n    backend: string;\n    nativeVersion: string;\n    isNative: boolean;\n    simdEnabled: boolean;\n  } {\n    const base = this.getStats();\n    return {\n      count: base.count,\n      dimension: base.dimension,\n      metric: base.metric,\n      backend: base.backend,\n      nativeVersion: this.nativeVersion,\n      isNative: this.isNativeImpl,\n      simdEnabled: this.isNativeImpl\n    };\n  }\n\n  /**\n   * Save index and metadata to disk\n   */\n  async save(path: string): Promise<void> {\n    this.ensureInitialized();\n\n    // Save vector index (if ruvector supports it)\n    if (typeof this.db.save === 'function') {\n      await this.db.save(path);\n    }\n\n    // Save metadata separately as JSON\n    const metadataPath = path + '.meta.json';\n    const fs = await import('fs/promises');\n    await fs.writeFile(\n      metadataPath,\n      JSON.stringify(Object.fromEntries(this.metadata), null, 2)\n    );\n  }\n\n  /**\n   * Load index and metadata from disk\n   */\n  async load(path: string): Promise<void> {\n    this.ensureInitialized();\n\n    // Load vector index (if ruvector supports it)\n    if (typeof this.db.load === 'function') {\n      await this.db.load(path);\n    }\n\n    // Load metadata\n    const metadataPath = path + '.meta.json';\n    try {\n      const fs = await import('fs/promises');\n      const data = await fs.readFile(metadataPath, 'utf-8');\n      this.metadata = new Map(Object.entries(JSON.parse(data)));\n    } catch {\n      console.debug(`[RuVectorBackend] No metadata file found at ${metadataPath}`);\n    }\n  }\n\n  /**\n   * Close and cleanup resources\n   */\n  close(): void {\n    this.metadata.clear();\n  }\n\n  /**\n   * Convert score to distance for backward compatibility.\n   * ruvector 0.1.99+ returns scores (higher = more similar).\n   */\n  private scoreToDistance(score: number): number {\n    switch (this.config.metric) {\n      case 'cosine':\n        return 1 - score;\n      case 'l2':\n        return score === 0 ? Infinity : -Math.log(score);\n      case 'ip':\n        return -score;\n      default:\n        return 1 - score;\n    }\n  }\n\n  /**\n   * Ensure database is initialized before operations\n   */\n  private ensureInitialized(): void {\n    if (!this.initialized) {\n      throw new Error('RuVectorBackend not initialized. Call initialize() first.');\n    }\n  }\n}\n"]}

package/dist/packages/agentdb/src/backends/ruvector/RuVectorLearning.d.ts

@@ -0,0 +1,108 @@
+/**
+ * RuVectorLearning - GNN-Enhanced Vector Search
+ *
+ * Integrates Graph Neural Networks for query enhancement using @ruvector/gnn.
+ * Requires optional @ruvector/gnn package.
+ *
+ * Features:
+ * - Query enhancement using neighbor context with multi-head attention
+ * - Differentiable search with soft weights
+ * - Hierarchical forward pass through GNN layers
+ * - Graceful degradation when GNN not available
+ *
+ * Note: @ruvector/gnn provides stateless GNN layers (inference only).
+ * Training is handled separately by the consuming application.
+ */
+export interface LearningConfig {
+    inputDim: number;
+    hiddenDim: number;
+    heads: number;
+    dropout?: number;
+}
+export interface EnhancementOptions {
+    temperature?: number;
+    k?: number;
+}
+export declare class RuVectorLearning {
+    private gnnLayer;
+    private config;
+    private initialized;
+    private differentiableSearch;
+    private hierarchicalForward;
+    constructor(config: LearningConfig);
+    /**
+     * Initialize GNN layer with optional dependency handling
+     */
+    initialize(): Promise<void>;
+    /**
+     * Enhance query embedding using neighbor context
+     *
+     * Uses Graph Attention Network to aggregate information from
+     * nearest neighbors, weighted by their relevance scores.
+     *
+     * @param query - Query embedding to enhance
+     * @param neighbors - Neighbor embeddings
+     * @param weights - Edge weights (relevance scores)
+     * @returns Enhanced query embedding
+     */
+    enhance(query: Float32Array, neighbors: Float32Array[], weights: number[]): Float32Array;
+    /**
+     * Differentiable search with soft attention
+     *
+     * Uses soft attention mechanism instead of hard top-k selection.
+     * Returns indices and weights that can be used for gradient-based optimization.
+     *
+     * @param query - Query embedding
+     * @param candidates - Candidate embeddings
+     * @param options - Search options
+     * @returns Search result with indices and soft weights
+     */
+    search(query: Float32Array, candidates: Float32Array[], options?: EnhancementOptions): {
+        indices: number[];
+        weights: number[];
+    };
+    /**
+     * Hierarchical forward pass through multiple GNN layers
+     *
+     * Used for HNSW-style hierarchical search where embeddings
+     * are organized by graph layers.
+     *
+     * @param query - Query embedding
+     * @param layerEmbeddings - Embeddings organized by layer
+     * @returns Final enhanced embedding
+     */
+    enhanceHierarchical(query: Float32Array, layerEmbeddings: Float32Array[][]): Float32Array;
+    /**
+     * Serialize GNN layer to JSON
+     *
+     * Allows saving/loading the GNN layer configuration.
+     *
+     * @returns JSON string representation
+     */
+    toJson(): string;
+    /**
+     * Create GNN layer from JSON
+     *
+     * @param json - JSON string from toJson()
+     * @returns New RuVectorLearning instance
+     */
+    static fromJson(json: string, config: LearningConfig): Promise<RuVectorLearning>;
+    /**
+     * Check if GNN layer is initialized and ready for use
+     */
+    isInitialized(): boolean;
+    /**
+     * Get current state
+     */
+    getState(): {
+        initialized: boolean;
+        config: LearningConfig;
+        hiddenDim: number;
+        heads: number;
+    };
+    /**
+     * Ensure GNN is initialized before operations
+     */
+    private ensureInitialized;
+}
+//# sourceMappingURL=RuVectorLearning.d.ts.map

package/dist/packages/agentdb/src/backends/ruvector/RuVectorLearning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuVectorLearning.d.ts","sourceRoot":"","sources":["../../../../../../../packages/agentdb/src/backends/ruvector/RuVectorLearning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,oBAAoB,CAAM;IAClC,OAAO,CAAC,mBAAmB,CAAM;gBAErB,MAAM,EAAE,cAAc;IAOlC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BjC;;;;;;;;;;OAUG;IACH,OAAO,CACL,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,YAAY,EAAE,EACzB,OAAO,EAAE,MAAM,EAAE,GAChB,YAAY;IAwBf;;;;;;;;;;OAUG;IACH,MAAM,CACJ,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,YAAY,EAAE,EAC1B,OAAO,GAAE,kBAAuB,GAC/B;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE;IA0B3C;;;;;;;;;OASG;IACH,mBAAmB,CACjB,KAAK,EAAE,YAAY,EACnB,eAAe,EAAE,YAAY,EAAE,EAAE,GAChC,YAAY;IA0Bf;;;;;;OAMG;IACH,MAAM,IAAI,MAAM;IAKhB;;;;;OAKG;WACU,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAatF;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,QAAQ,IAAI;QACV,WAAW,EAAE,OAAO,CAAC;QACrB,MAAM,EAAE,cAAc,CAAC;QACvB,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;KACf;IASD;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAK1B"}