ruvector 0.1.29 → 0.1.31

package/test/benchmark-gnn.js

@@ -0,0 +1,373 @@
+/**
+ * GNN Performance Benchmark Suite
+ *
+ * Tests performance of GNN operations and identifies bottlenecks
+ */
+
+const { performance } = require('perf_hooks');
+
+// Try to load native GNN module directly
+let gnnNative;
+let gnnWrapper;
+
+try {
+  gnnNative = require('@ruvector/gnn');
+  console.log('✅ @ruvector/gnn loaded');
+} catch (e) {
+  console.log('❌ @ruvector/gnn not available:', e.message);
+}
+
+// Benchmark utilities
+function generateRandomVector(dim) {
+  const arr = new Array(dim);
+  for (let i = 0; i < dim; i++) {
+    arr[i] = Math.random();
+  }
+  return arr;
+}
+
+function generateRandomFloat32(dim) {
+  const arr = new Float32Array(dim);
+  for (let i = 0; i < dim; i++) {
+    arr[i] = Math.random();
+  }
+  return arr;
+}
+
+function benchmark(name, fn, iterations = 1000) {
+  // Warmup
+  for (let i = 0; i < 10; i++) fn();
+
+  const times = [];
+  for (let i = 0; i < iterations; i++) {
+    const start = performance.now();
+    fn();
+    times.push(performance.now() - start);
+  }
+
+  times.sort((a, b) => a - b);
+  const avg = times.reduce((a, b) => a + b, 0) / times.length;
+  const p50 = times[Math.floor(times.length * 0.5)];
+  const p95 = times[Math.floor(times.length * 0.95)];
+  const p99 = times[Math.floor(times.length * 0.99)];
+
+  return { name, avg, p50, p95, p99, iterations };
+}
+
+function formatMs(ms) {
+  if (ms < 0.001) return `${(ms * 1000000).toFixed(2)}ns`;
+  if (ms < 1) return `${(ms * 1000).toFixed(2)}µs`;
+  return `${ms.toFixed(2)}ms`;
+}
+
+function printResult(result) {
+  console.log(`  ${result.name}:`);
+  console.log(`    avg: ${formatMs(result.avg)} | p50: ${formatMs(result.p50)} | p95: ${formatMs(result.p95)} | p99: ${formatMs(result.p99)}`);
+}
+
+// Array conversion benchmarks
+function benchmarkArrayConversion() {
+  console.log('\n📊 Array Conversion Overhead Benchmarks');
+  console.log('=========================================');
+
+  const dims = [128, 256, 512, 768, 1024];
+
+  for (const dim of dims) {
+    console.log(`\n  Dimension: ${dim}`);
+
+    const regularArray = generateRandomVector(dim);
+    const float32Array = generateRandomFloat32(dim);
+
+    // Test Array.from on Float32Array
+    printResult(benchmark(`Array.from(Float32Array)`, () => {
+      return Array.from(float32Array);
+    }));
+
+    // Test spread operator
+    printResult(benchmark(`[...Float32Array]`, () => {
+      return [...float32Array];
+    }));
+
+    // Test slice (for regular arrays - noop baseline)
+    printResult(benchmark(`Array.slice() (baseline)`, () => {
+      return regularArray.slice();
+    }));
+
+    // Test Float32Array.from
+    printResult(benchmark(`Float32Array.from(Array)`, () => {
+      return Float32Array.from(regularArray);
+    }));
+
+    // Test new Float32Array
+    printResult(benchmark(`new Float32Array(Array)`, () => {
+      return new Float32Array(regularArray);
+    }));
+  }
+}
+
+// GNN operation benchmarks
+function benchmarkGnnOperations() {
+  if (!gnnNative) {
+    console.log('\n⚠️  Skipping GNN benchmarks - module not available');
+    return;
+  }
+
+  console.log('\n📊 GNN Operation Benchmarks');
+  console.log('===========================');
+
+  const dims = [128, 256, 512];
+  const candidateCounts = [100, 1000, 10000];
+
+  for (const dim of dims) {
+    for (const count of candidateCounts) {
+      console.log(`\n  Dimension: ${dim}, Candidates: ${count}`);
+
+      // Prepare data as regular arrays (user input)
+      const queryArray = generateRandomVector(dim);
+      const candidatesArray = Array.from({ length: count }, () => generateRandomVector(dim));
+
+      // Prepare data as Float32Array (pre-converted for max performance)
+      const queryFloat32 = new Float32Array(queryArray);
+      const candidatesFloat32 = candidatesArray.map(arr => new Float32Array(arr));
+
+      const iters = Math.min(100, Math.floor(10000 / count));
+
+      // Measure Float32Array conversion overhead (Array -> Float32Array)
+      const conversionOverheadResult = benchmark(`Array→Float32 conversion`, () => {
+        const q = new Float32Array(queryArray);
+        const c = candidatesArray.map(arr => new Float32Array(arr));
+        return { q, c };
+      }, iters);
+      printResult(conversionOverheadResult);
+
+      // Wrapped interface with regular arrays (tests full conversion + native)
+      try {
+        const wrappedArrayResult = benchmark(`Wrapped (from Array)`, () => {
+          return gnnNative.differentiableSearch(queryArray, candidatesArray, 10, 1.0);
+        }, iters);
+        printResult(wrappedArrayResult);
+      } catch (e) {
+        console.log(`    Wrapped (from Array): Error - ${e.message}`);
+      }
+
+      // Wrapped interface with Float32Array (tests zero-copy path)
+      try {
+        const wrappedFloat32Result = benchmark(`Wrapped (from Float32)`, () => {
+          return gnnNative.differentiableSearch(queryFloat32, candidatesFloat32, 10, 1.0);
+        }, iters);
+        printResult(wrappedFloat32Result);
+      } catch (e) {
+        console.log(`    Wrapped (from Float32): Error - ${e.message}`);
+      }
+
+      // Native direct with Float32Array (bypasses wrapper, max performance)
+      try {
+        const nativeResult = benchmark(`Native direct (Float32)`, () => {
+          return gnnNative.nativeDifferentiableSearch(queryFloat32, candidatesFloat32, 10, 1.0);
+        }, iters);
+        printResult(nativeResult);
+      } catch (e) {
+        console.log(`    Native direct (Float32): Error - ${e.message}`);
+      }
+
+      console.log('');
+    }
+  }
+}
+
+// Batch operation benchmarks
+function benchmarkBatchOperations() {
+  if (!gnnNative) return;
+
+  console.log('\n📊 Batch vs Sequential Benchmarks');
+  console.log('==================================');
+
+  const dim = 256;
+  const batchSizes = [10, 50, 100];
+  const candidateCount = 1000;
+
+  const candidates = Array.from({ length: candidateCount }, () => generateRandomVector(dim));
+
+  for (const batchSize of batchSizes) {
+    console.log(`\n  Batch size: ${batchSize}, Candidates: ${candidateCount}`);
+
+    const queries = Array.from({ length: batchSize }, () => generateRandomVector(dim));
+
+    // Sequential search
+    const sequentialResult = benchmark(`Sequential search`, () => {
+      const results = [];
+      for (const query of queries) {
+        results.push(gnnNative.differentiableSearch(query, candidates, 10, 1.0));
+      }
+      return results;
+    }, 10);
+    printResult(sequentialResult);
+
+    // Note: batch search would need to be implemented in native
+    console.log(`    Batch search: Not implemented (potential ${batchSize}x improvement)`);
+  }
+}
+
+// RuvectorLayer benchmarks
+function benchmarkRuvectorLayer() {
+  if (!gnnNative) return;
+
+  console.log('\n📊 RuvectorLayer Benchmarks');
+  console.log('===========================');
+
+  const dims = [128, 256, 512];
+  const neighborCounts = [5, 10, 20, 50];
+
+  for (const dim of dims) {
+    for (const neighborCount of neighborCounts) {
+      console.log(`\n  Dimension: ${dim}, Neighbors: ${neighborCount}`);
+
+      const layer = new gnnNative.RuvectorLayer(dim, dim, 4, 0.1);
+
+      // Test with regular arrays (triggers conversion)
+      const nodeArray = generateRandomVector(dim);
+      const neighborsArray = Array.from({ length: neighborCount }, () => generateRandomVector(dim));
+      const weightsArray = generateRandomVector(neighborCount);
+
+      // Test with Float32Arrays (zero-copy)
+      const nodeFloat32 = new Float32Array(nodeArray);
+      const neighborsFloat32 = neighborsArray.map(arr => new Float32Array(arr));
+      const weightsFloat32 = new Float32Array(weightsArray);
+
+      try {
+        const arrayResult = benchmark(`Layer forward (Array)`, () => {
+          return layer.forward(nodeArray, neighborsArray, weightsArray);
+        }, 1000);
+        printResult(arrayResult);
+      } catch (e) {
+        console.log(`    Layer forward (Array): Error - ${e.message}`);
+      }
+
+      try {
+        const float32Result = benchmark(`Layer forward (Float32)`, () => {
+          return layer.forward(nodeFloat32, neighborsFloat32, weightsFloat32);
+        }, 1000);
+        printResult(float32Result);
+      } catch (e) {
+        console.log(`    Layer forward (Float32): Error - ${e.message}`);
+      }
+    }
+  }
+}
+
+// TensorCompress benchmarks
+function benchmarkTensorCompress() {
+  if (!gnnNative) return;
+
+  console.log('\n📊 TensorCompress Benchmarks');
+  console.log('============================');
+
+  const dims = [128, 256, 512, 768, 1024];
+
+  const compressor = new gnnNative.TensorCompress();
+
+  for (const dim of dims) {
+    console.log(`\n  Dimension: ${dim}`);
+
+    const embeddingArray = generateRandomVector(dim);
+    const embeddingFloat32 = new Float32Array(embeddingArray);
+
+    // Test with Array (triggers conversion)
+    try {
+      const arrayResult = benchmark(`Compress Array (freq=0.5)`, () => {
+        return compressor.compress(embeddingArray, 0.5);
+      }, 1000);
+      printResult(arrayResult);
+    } catch (e) {
+      console.log(`    Compress Array: Error - ${e.message}`);
+    }
+
+    // Test with Float32Array (zero-copy)
+    try {
+      const float32Result = benchmark(`Compress Float32 (freq=0.5)`, () => {
+        return compressor.compress(embeddingFloat32, 0.5);
+      }, 1000);
+      printResult(float32Result);
+    } catch (e) {
+      console.log(`    Compress Float32: Error - ${e.message}`);
+    }
+
+    // Decompress benchmark
+    try {
+      const compressed = compressor.compress(embeddingFloat32, 0.5);
+      const decompressResult = benchmark(`Decompress`, () => {
+        return compressor.decompress(compressed);
+      }, 1000);
+      printResult(decompressResult);
+    } catch (e) {
+      console.log(`    Decompress: Error - ${e.message}`);
+    }
+  }
+}
+
+// Memory allocation benchmarks
+function benchmarkMemoryAllocation() {
+  console.log('\n📊 Memory Allocation Patterns');
+  console.log('=============================');
+
+  const dim = 256;
+  const count = 1000;
+
+  // Regular array creation
+  printResult(benchmark(`Create ${count} regular arrays (${dim}d)`, () => {
+    const arrays = [];
+    for (let i = 0; i < count; i++) {
+      arrays.push(new Array(dim).fill(0).map(() => Math.random()));
+    }
+    return arrays;
+  }, 100));
+
+  // Float32Array creation
+  printResult(benchmark(`Create ${count} Float32Arrays (${dim}d)`, () => {
+    const arrays = [];
+    for (let i = 0; i < count; i++) {
+      const arr = new Float32Array(dim);
+      for (let j = 0; j < dim; j++) arr[j] = Math.random();
+      arrays.push(arr);
+    }
+    return arrays;
+  }, 100));
+
+  // Pre-allocated buffer
+  printResult(benchmark(`Pre-allocated buffer (${count * dim} floats)`, () => {
+    const buffer = new Float32Array(count * dim);
+    for (let i = 0; i < buffer.length; i++) {
+      buffer[i] = Math.random();
+    }
+    return buffer;
+  }, 100));
+}
+
+// Main
+async function main() {
+  console.log('🚀 RuVector GNN Performance Benchmark Suite');
+  console.log('============================================\n');
+
+  console.log('System Info:');
+  console.log(`  Platform: ${process.platform}`);
+  console.log(`  Node.js: ${process.version}`);
+  console.log(`  CPU: ${require('os').cpus()[0].model}`);
+  console.log(`  Memory: ${Math.round(require('os').totalmem() / 1024 / 1024 / 1024)}GB`);
+
+  benchmarkArrayConversion();
+  benchmarkMemoryAllocation();
+  benchmarkGnnOperations();
+  benchmarkRuvectorLayer();
+  benchmarkTensorCompress();
+  benchmarkBatchOperations();
+
+  console.log('\n\n📋 Performance Optimization Recommendations');
+  console.log('============================================');
+  console.log('1. Avoid Array.from() conversion - use typed arrays directly');
+  console.log('2. Cache converted arrays when possible');
+  console.log('3. Use pre-allocated buffers for batch operations');
+  console.log('4. Implement native batch search for multiple queries');
+  console.log('5. Consider zero-copy operations with SharedArrayBuffer');
+}
+
+main().catch(console.error);

package/test/integration.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+
+/**
+ * Integration test for ruvector package
+ * Tests the smart loader and basic functionality
+ */
+
+const assert = require('assert');
+const path = require('path');
+
+console.log('ruvector Integration Test\n');
+console.log('='.repeat(50));
+
+// Test 1: Load ruvector module
+console.log('\n1. Testing module loading...');
+try {
+  const ruvector = require('../dist/index.js');
+  console.log('   ✓ Module loaded successfully');
+
+  // Check exports
+  assert(typeof ruvector.VectorDB === 'function', 'VectorDB should be a function');
+  assert(typeof ruvector.getImplementationType === 'function', 'getImplementationType should be a function');
+  assert(typeof ruvector.isNative === 'function', 'isNative should be a function');
+  assert(typeof ruvector.isWasm === 'function', 'isWasm should be a function');
+  assert(typeof ruvector.getVersion === 'function', 'getVersion should be a function');
+  console.log('   ✓ All exports present');
+} catch (error) {
+  console.error('   ✗ Failed to load module:', error.message);
+  process.exit(1);
+}
+
+// Test 2: Check implementation detection
+console.log('\n2. Testing implementation detection...');
+try {
+  const { getImplementationType, isNative, isWasm, getVersion } = require('../dist/index.js');
+
+  const implType = getImplementationType();
+  console.log(`   Implementation type: ${implType}`);
+
+  assert(['native', 'wasm'].includes(implType), 'Implementation type should be native or wasm');
+  console.log('   ✓ Valid implementation type');
+
+  const version = getVersion();
+  console.log(`   Version: ${version.version}`);
+  console.log(`   Using: ${version.implementation}`);
+  assert(version.version === '0.1.1', 'Version should be 0.1.1');
+  console.log('   ✓ Version info correct');
+
+  assert(isNative() !== isWasm(), 'Should be either native OR wasm, not both');
+  console.log('   ✓ Implementation flags consistent');
+} catch (error) {
+  console.error('   ✗ Implementation detection failed:', error.message);
+  // This is expected to fail until we have the actual implementations
+  console.log('   ⚠ This is expected until @ruvector/core and @ruvector/wasm are built');
+}
+
+// Test 3: Type definitions
+console.log('\n3. Testing TypeScript type definitions...');
+try {
+  const fs = require('fs');
+
+  const typeDefsExist = fs.existsSync(path.join(__dirname, '../dist/types.d.ts'));
+  assert(typeDefsExist, 'Type definitions should exist');
+  console.log('   ✓ Type definitions file exists');
+
+  const indexDefsExist = fs.existsSync(path.join(__dirname, '../dist/index.d.ts'));
+  assert(indexDefsExist, 'Index type definitions should exist');
+  console.log('   ✓ Index type definitions exist');
+
+  // Check type definitions content
+  const typeDefs = fs.readFileSync(path.join(__dirname, '../dist/types.d.ts'), 'utf8');
+  assert(typeDefs.includes('VectorEntry'), 'Should include VectorEntry interface');
+  assert(typeDefs.includes('SearchQuery'), 'Should include SearchQuery interface');
+  assert(typeDefs.includes('SearchResult'), 'Should include SearchResult interface');
+  assert(typeDefs.includes('DbOptions'), 'Should include DbOptions interface');
+  assert(typeDefs.includes('VectorDB'), 'Should include VectorDB interface');
+  console.log('   ✓ All type definitions present');
+} catch (error) {
+  console.error('   ✗ Type definitions test failed:', error.message);
+  process.exit(1);
+}
+
+// Test 4: Package structure
+console.log('\n4. Testing package structure...');
+try {
+  const fs = require('fs');
+
+  const packageJson = require('../package.json');
+  assert(packageJson.name === 'ruvector', 'Package name should be ruvector');
+  assert(packageJson.version === '0.1.1', 'Version should be 0.1.1');
+  assert(packageJson.main === 'dist/index.js', 'Main entry should be dist/index.js');
+  assert(packageJson.types === 'dist/index.d.ts', 'Types entry should be dist/index.d.ts');
+  assert(packageJson.bin.ruvector === './bin/cli.js', 'CLI bin should be ./bin/cli.js');
+  console.log('   ✓ package.json structure correct');
+
+  const cliExists = fs.existsSync(path.join(__dirname, '../bin/cli.js'));
+  assert(cliExists, 'CLI script should exist');
+  console.log('   ✓ CLI script exists');
+
+  const cliContent = fs.readFileSync(path.join(__dirname, '../bin/cli.js'), 'utf8');
+  assert(cliContent.startsWith('#!/usr/bin/env node'), 'CLI should have shebang');
+  console.log('   ✓ CLI has proper shebang');
+} catch (error) {
+  console.error('   ✗ Package structure test failed:', error.message);
+  process.exit(1);
+}
+
+// Test 5: CLI functionality (basic)
+console.log('\n5. Testing CLI basic functionality...');
+try {
+  const { execSync } = require('child_process');
+
+  // Test CLI help
+  try {
+    const output = execSync('node bin/cli.js --help', {
+      cwd: path.join(__dirname, '..'),
+      encoding: 'utf8'
+    });
+    assert(output.includes('ruvector'), 'Help should mention ruvector');
+    assert(output.includes('create'), 'Help should include create command');
+    assert(output.includes('search'), 'Help should include search command');
+    console.log('   ✓ CLI help works');
+  } catch (error) {
+    // CLI might fail if dependencies aren't available
+    console.log('   ⚠ CLI help test skipped (dependencies not available)');
+  }
+
+  // Test info command
+  try {
+    const output = execSync('node bin/cli.js info', {
+      cwd: path.join(__dirname, '..'),
+      encoding: 'utf8'
+    });
+    assert(output.includes('0.1.1'), 'Info should show version');
+    console.log('   ✓ CLI info command works');
+  } catch (error) {
+    console.log('   ⚠ CLI info test skipped (dependencies not available)');
+  }
+} catch (error) {
+  console.error('   ✗ CLI test failed:', error.message);
+}
+
+// Summary
+console.log('\n' + '='.repeat(50));
+console.log('\n✓ Core package structure tests passed!');
+console.log('\nPackage ready for:');
+console.log('  - Platform detection and smart loading');
+console.log('  - TypeScript type definitions');
+console.log('  - CLI tools (create, insert, search, stats, benchmark)');
+console.log('  - Integration with @ruvector/core and @ruvector/wasm');
+console.log('\nNext steps:');
+console.log('  1. Build @ruvector/core (native Rust bindings)');
+console.log('  2. Build @ruvector/wasm (WebAssembly module)');
+console.log('  3. Test full integration with real implementations');
+console.log('\nPackage location: /workspaces/ruvector/npm/packages/ruvector');

package/test/mock-implementation.js

@@ -0,0 +1,151 @@
+/**
+ * Mock VectorDB implementation for testing
+ * This simulates the interface that @ruvector/core and @ruvector/wasm will provide
+ */
+
+class VectorDB {
+  constructor(options) {
+    this.options = options;
+    this.dimension = options.dimension;
+    this.metric = options.metric || 'cosine';
+    this.vectors = new Map();
+  }
+
+  insert(entry) {
+    if (!entry.id || !entry.vector) {
+      throw new Error('Entry must have id and vector');
+    }
+    if (entry.vector.length !== this.dimension) {
+      throw new Error(`Vector dimension must be ${this.dimension}`);
+    }
+    this.vectors.set(entry.id, {
+      id: entry.id,
+      vector: entry.vector,
+      metadata: entry.metadata || {}
+    });
+  }
+
+  insertBatch(entries) {
+    for (const entry of entries) {
+      this.insert(entry);
+    }
+  }
+
+  search(query) {
+    const results = [];
+    const k = query.k || 10;
+    const threshold = query.threshold || 0.0;
+
+    for (const [id, entry] of this.vectors.entries()) {
+      const score = this._computeSimilarity(query.vector, entry.vector);
+      if (score >= threshold) {
+        results.push({
+          id: entry.id,
+          score,
+          vector: entry.vector,
+          metadata: entry.metadata
+        });
+      }
+    }
+
+    // Sort by score descending
+    results.sort((a, b) => b.score - a.score);
+
+    return results.slice(0, k);
+  }
+
+  get(id) {
+    return this.vectors.get(id) || null;
+  }
+
+  delete(id) {
+    return this.vectors.delete(id);
+  }
+
+  updateMetadata(id, metadata) {
+    const entry = this.vectors.get(id);
+    if (entry) {
+      entry.metadata = { ...entry.metadata, ...metadata };
+    }
+  }
+
+  stats() {
+    return {
+      count: this.vectors.size,
+      dimension: this.dimension,
+      metric: this.metric,
+      memoryUsage: this.vectors.size * this.dimension * 8, // rough estimate
+      indexType: 'flat'
+    };
+  }
+
+  save(path) {
+    // Mock save
+    const data = {
+      dimension: this.dimension,
+      metric: this.metric,
+      vectors: Array.from(this.vectors.values())
+    };
+    return JSON.stringify(data);
+  }
+
+  load(path) {
+    // Mock load - would read from file
+    this.vectors.clear();
+  }
+
+  clear() {
+    this.vectors.clear();
+  }
+
+  buildIndex() {
+    // Mock index building
+  }
+
+  optimize() {
+    // Mock optimization
+  }
+
+  _computeSimilarity(a, b) {
+    if (this.metric === 'cosine') {
+      return this._cosineSimilarity(a, b);
+    } else if (this.metric === 'euclidean') {
+      return 1 / (1 + this._euclideanDistance(a, b));
+    } else {
+      return this._dotProduct(a, b);
+    }
+  }
+
+  _cosineSimilarity(a, b) {
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+
+    for (let i = 0; i < a.length; i++) {
+      dot += a[i] * b[i];
+      magA += a[i] * a[i];
+      magB += b[i] * b[i];
+    }
+
+    return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+  }
+
+  _euclideanDistance(a, b) {
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+      const diff = a[i] - b[i];
+      sum += diff * diff;
+    }
+    return Math.sqrt(sum);
+  }
+
+  _dotProduct(a, b) {
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+      sum += a[i] * b[i];
+    }
+    return sum;
+  }
+}
+
+module.exports = { VectorDB };