ruvector 0.1.23 → 0.1.25

package/.claude-flow/metrics/performance.json

@@ -1,7 +1,7 @@
 {
-  "startTime": 1764217582157,
-  "sessionId": "session-1764217582157",
-  "lastActivity": 1764217582157,
+  "startTime": 1764542370768,
+  "sessionId": "session-1764542370768",
+  "lastActivity": 1764542370768,
   "sessionDuration": 0,
   "totalTasks": 1,
   "successfulTasks": 1,

package/.claude-flow/metrics/task-metrics.json

@@ -1,10 +1,10 @@
 [
   {
-    "id": "cmd-hooks-1764217582465",
+    "id": "cmd-hooks-1764542370895",
     "type": "hooks",
     "success": true,
-    "duration": 37.93139400000007,
-    "timestamp": 1764217582503,
+    "duration": 15.263496999999973,
+    "timestamp": 1764542370910,
     "metadata": {}
   }
 ]

package/bin/cli.js

@@ -47,6 +47,46 @@ try {
   // GNN not available - commands will show helpful message
 }
 
+// Import Attention (optional - graceful fallback if not available)
+let DotProductAttention, MultiHeadAttention, HyperbolicAttention, FlashAttention, LinearAttention, MoEAttention;
+let GraphRoPeAttention, EdgeFeaturedAttention, DualSpaceAttention, LocalGlobalAttention;
+let benchmarkAttention, computeAttentionAsync, batchAttentionCompute, parallelAttentionCompute;
+let expMap, logMap, mobiusAddition, poincareDistance, projectToPoincareBall;
+let attentionInfo, attentionVersion;
+let attentionAvailable = false;
+try {
+  const attention = require('@ruvector/attention');
+  // Core mechanisms
+  DotProductAttention = attention.DotProductAttention;
+  MultiHeadAttention = attention.MultiHeadAttention;
+  HyperbolicAttention = attention.HyperbolicAttention;
+  FlashAttention = attention.FlashAttention;
+  LinearAttention = attention.LinearAttention;
+  MoEAttention = attention.MoEAttention;
+  // Graph attention
+  GraphRoPeAttention = attention.GraphRoPeAttention;
+  EdgeFeaturedAttention = attention.EdgeFeaturedAttention;
+  DualSpaceAttention = attention.DualSpaceAttention;
+  LocalGlobalAttention = attention.LocalGlobalAttention;
+  // Utilities
+  benchmarkAttention = attention.benchmarkAttention;
+  computeAttentionAsync = attention.computeAttentionAsync;
+  batchAttentionCompute = attention.batchAttentionCompute;
+  parallelAttentionCompute = attention.parallelAttentionCompute;
+  // Hyperbolic math
+  expMap = attention.expMap;
+  logMap = attention.logMap;
+  mobiusAddition = attention.mobiusAddition;
+  poincareDistance = attention.poincareDistance;
+  projectToPoincareBall = attention.projectToPoincareBall;
+  // Meta
+  attentionInfo = attention.info;
+  attentionVersion = attention.version;
+  attentionAvailable = true;
+} catch (e) {
+  // Attention not available - commands will show helpful message
+}
+
 const program = new Command();
 
 // Get package version from package.json
@@ -855,4 +895,1190 @@ gnnCmd
     console.log(chalk.gray(`  binary (freq <= 0.01) - ~32x compression, archive`));
   });
 
+// =============================================================================
+// Attention Commands
+// =============================================================================
+
+// Helper to require attention module
+function requireAttention() {
+  if (!attentionAvailable) {
+    console.error(chalk.red('Error: @ruvector/attention is not installed'));
+    console.error(chalk.yellow('Install it with: npm install @ruvector/attention'));
+    process.exit(1);
+  }
+}
+
+// Attention parent command
+const attentionCmd = program
+  .command('attention')
+  .description('High-performance attention mechanism operations');
+
+// Attention compute command - run attention on input vectors
+attentionCmd
+  .command('compute')
+  .description('Compute attention over input vectors')
+  .requiredOption('-q, --query <json>', 'Query vector as JSON array')
+  .requiredOption('-k, --keys <file>', 'Keys file (JSON array of vectors)')
+  .option('-v, --values <file>', 'Values file (JSON array of vectors, defaults to keys)')
+  .option('-t, --type <type>', 'Attention type (dot|multi-head|flash|hyperbolic|linear)', 'dot')
+  .option('-h, --heads <number>', 'Number of attention heads (for multi-head)', '4')
+  .option('-d, --head-dim <number>', 'Head dimension (for multi-head)', '64')
+  .option('--curvature <number>', 'Curvature for hyperbolic attention', '1.0')
+  .option('-o, --output <file>', 'Output file for results')
+  .action((options) => {
+    requireAttention();
+    const spinner = ora('Loading keys...').start();
+
+    try {
+      const query = JSON.parse(options.query);
+      const keysData = JSON.parse(fs.readFileSync(options.keys, 'utf8'));
+      const keys = keysData.map(k => k.vector || k);
+
+      let values = keys;
+      if (options.values) {
+        const valuesData = JSON.parse(fs.readFileSync(options.values, 'utf8'));
+        values = valuesData.map(v => v.vector || v);
+      }
+
+      spinner.text = `Computing ${options.type} attention...`;
+
+      let result;
+      let attentionWeights;
+
+      switch (options.type) {
+        case 'dot': {
+          const attn = new DotProductAttention();
+          const queryMat = [query];
+          const output = attn.forward(queryMat, keys, values);
+          result = output[0];
+          attentionWeights = attn.getLastWeights ? attn.getLastWeights()[0] : null;
+          break;
+        }
+        case 'multi-head': {
+          const numHeads = parseInt(options.heads);
+          const headDim = parseInt(options.headDim);
+          const attn = new MultiHeadAttention(query.length, numHeads, headDim);
+          const queryMat = [query];
+          const output = attn.forward(queryMat, keys, values);
+          result = output[0];
+          break;
+        }
+        case 'flash': {
+          const attn = new FlashAttention(query.length);
+          const queryMat = [query];
+          const output = attn.forward(queryMat, keys, values);
+          result = output[0];
+          break;
+        }
+        case 'hyperbolic': {
+          const curvature = parseFloat(options.curvature);
+          const attn = new HyperbolicAttention(query.length, curvature);
+          const queryMat = [query];
+          const output = attn.forward(queryMat, keys, values);
+          result = output[0];
+          break;
+        }
+        case 'linear': {
+          const attn = new LinearAttention(query.length);
+          const queryMat = [query];
+          const output = attn.forward(queryMat, keys, values);
+          result = output[0];
+          break;
+        }
+        default:
+          throw new Error(`Unknown attention type: ${options.type}`);
+      }
+
+      spinner.succeed(chalk.green(`Attention computed (${options.type})`));
+
+      console.log(chalk.cyan('\nAttention Results:'));
+      console.log(chalk.white(`  Type:        ${chalk.yellow(options.type)}`));
+      console.log(chalk.white(`  Query dim:   ${chalk.yellow(query.length)}`));
+      console.log(chalk.white(`  Num keys:    ${chalk.yellow(keys.length)}`));
+      console.log(chalk.white(`  Output dim:  ${chalk.yellow(result.length)}`));
+      console.log(chalk.white(`  Output:      ${chalk.gray(`[${result.slice(0, 4).map(v => v.toFixed(4)).join(', ')}...]`)}`));
+
+      if (attentionWeights) {
+        console.log(chalk.cyan('\nAttention Weights:'));
+        attentionWeights.slice(0, 5).forEach((w, i) => {
+          console.log(chalk.gray(`  Key ${i}: ${w.toFixed(4)}`));
+        });
+        if (attentionWeights.length > 5) {
+          console.log(chalk.gray(`  ... and ${attentionWeights.length - 5} more`));
+        }
+      }
+
+      if (options.output) {
+        const outputData = { result, attentionWeights };
+        fs.writeFileSync(options.output, JSON.stringify(outputData, null, 2));
+        console.log(chalk.green(`\nResults saved to: ${options.output}`));
+      }
+    } catch (error) {
+      spinner.fail(chalk.red('Failed to compute attention'));
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+// Attention benchmark command
+attentionCmd
+  .command('benchmark')
+  .description('Benchmark attention mechanisms')
+  .option('-d, --dimension <number>', 'Vector dimension', '256')
+  .option('-n, --num-vectors <number>', 'Number of vectors', '100')
+  .option('-i, --iterations <number>', 'Benchmark iterations', '100')
+  .option('-t, --types <list>', 'Attention types to benchmark (comma-separated)', 'dot,flash,linear')
+  .action((options) => {
+    requireAttention();
+    const spinner = ora('Setting up benchmark...').start();
+
+    try {
+      const dim = parseInt(options.dimension);
+      const numVectors = parseInt(options.numVectors);
+      const iterations = parseInt(options.iterations);
+      const types = options.types.split(',').map(t => t.trim());
+
+      // Generate random test data
+      spinner.text = 'Generating test data...';
+      const query = Array.from({ length: dim }, () => Math.random());
+      const keys = Array.from({ length: numVectors }, () =>
+        Array.from({ length: dim }, () => Math.random())
+      );
+
+      console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
+      console.log(chalk.cyan('                Attention Mechanism Benchmark'));
+      console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
+
+      console.log(chalk.white(`  Dimension:    ${chalk.yellow(dim)}`));
+      console.log(chalk.white(`  Vectors:      ${chalk.yellow(numVectors)}`));
+      console.log(chalk.white(`  Iterations:   ${chalk.yellow(iterations)}`));
+      console.log('');
+
+      const results = [];
+
+      for (const type of types) {
+        spinner.text = `Benchmarking ${type} attention...`;
+        spinner.start();
+
+        let attn;
+        try {
+          switch (type) {
+            case 'dot':
+              attn = new DotProductAttention();
+              break;
+            case 'flash':
+              attn = new FlashAttention(dim);
+              break;
+            case 'linear':
+              attn = new LinearAttention(dim);
+              break;
+            case 'hyperbolic':
+              attn = new HyperbolicAttention(dim, 1.0);
+              break;
+            case 'multi-head':
+              attn = new MultiHeadAttention(dim, 4, 64);
+              break;
+            default:
+              console.log(chalk.yellow(`  Skipping unknown type: ${type}`));
+              continue;
+          }
+        } catch (e) {
+          console.log(chalk.yellow(`  ${type}: not available`));
+          continue;
+        }
+
+        // Warm up
+        const queryMat = [query];
+        for (let i = 0; i < 5; i++) {
+          attn.forward(queryMat, keys, keys);
+        }
+
+        // Benchmark
+        const start = process.hrtime.bigint();
+        for (let i = 0; i < iterations; i++) {
+          attn.forward(queryMat, keys, keys);
+        }
+        const end = process.hrtime.bigint();
+        const totalMs = Number(end - start) / 1_000_000;
+        const avgMs = totalMs / iterations;
+        const opsPerSec = 1000 / avgMs;
+
+        results.push({ type, avgMs, opsPerSec });
+        spinner.succeed(chalk.green(`${type}: ${avgMs.toFixed(3)} ms/op (${opsPerSec.toFixed(1)} ops/sec)`));
+      }
+
+      // Summary
+      if (results.length > 0) {
+        console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
+        console.log(chalk.cyan('                         Summary'));
+        console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
+
+        const fastest = results.reduce((a, b) => a.avgMs < b.avgMs ? a : b);
+        console.log(chalk.green(`  Fastest: ${fastest.type} (${fastest.avgMs.toFixed(3)} ms/op)\n`));
+
+        console.log(chalk.white('  Relative Performance:'));
+        for (const r of results) {
+          const relPerf = (fastest.avgMs / r.avgMs * 100).toFixed(1);
+          const bar = '█'.repeat(Math.round(relPerf / 5));
+          console.log(chalk.white(`    ${r.type.padEnd(12)} ${chalk.cyan(bar)} ${relPerf}%`));
+        }
+      }
+    } catch (error) {
+      spinner.fail(chalk.red('Benchmark failed'));
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+// Hyperbolic math command
+attentionCmd
+  .command('hyperbolic')
+  .description('Hyperbolic geometry operations')
+  .requiredOption('-a, --action <type>', 'Action: exp-map|log-map|distance|project|mobius-add')
+  .requiredOption('-v, --vector <json>', 'Input vector(s) as JSON')
+  .option('-b, --vector-b <json>', 'Second vector for binary operations')
+  .option('-c, --curvature <number>', 'Poincaré ball curvature', '1.0')
+  .option('-o, --origin <json>', 'Origin point for exp/log maps')
+  .action((options) => {
+    requireAttention();
+
+    try {
+      const vecArray = JSON.parse(options.vector);
+      const vec = new Float32Array(vecArray);
+      const curvature = parseFloat(options.curvature);
+
+      let result;
+      let description;
+
+      switch (options.action) {
+        case 'exp-map': {
+          const originArray = options.origin ? JSON.parse(options.origin) : Array(vec.length).fill(0);
+          const origin = new Float32Array(originArray);
+          result = expMap(origin, vec, curvature);
+          description = 'Exponential map (tangent → Poincaré ball)';
+          break;
+        }
+        case 'log-map': {
+          const originArray = options.origin ? JSON.parse(options.origin) : Array(vec.length).fill(0);
+          const origin = new Float32Array(originArray);
+          result = logMap(origin, vec, curvature);
+          description = 'Logarithmic map (Poincaré ball → tangent)';
+          break;
+        }
+        case 'distance': {
+          if (!options.vectorB) {
+            throw new Error('--vector-b required for distance calculation');
+          }
+          const vecBArray = JSON.parse(options.vectorB);
+          const vecB = new Float32Array(vecBArray);
+          result = poincareDistance(vec, vecB, curvature);
+          description = 'Poincaré distance';
+          break;
+        }
+        case 'project': {
+          result = projectToPoincareBall(vec, curvature);
+          description = 'Project to Poincaré ball';
+          break;
+        }
+        case 'mobius-add': {
+          if (!options.vectorB) {
+            throw new Error('--vector-b required for Möbius addition');
+          }
+          const vecBArray = JSON.parse(options.vectorB);
+          const vecB = new Float32Array(vecBArray);
+          result = mobiusAddition(vec, vecB, curvature);
+          description = 'Möbius addition';
+          break;
+        }
+        default:
+          throw new Error(`Unknown action: ${options.action}`);
+      }
+
+      console.log(chalk.cyan('\nHyperbolic Operation:'));
+      console.log(chalk.white(`  Action:     ${chalk.yellow(description)}`));
+      console.log(chalk.white(`  Curvature:  ${chalk.yellow(curvature)}`));
+
+      if (typeof result === 'number') {
+        console.log(chalk.white(`  Result:     ${chalk.green(result.toFixed(6))}`));
+      } else {
+        const resultArray = Array.from(result);
+        console.log(chalk.white(`  Input dim:  ${chalk.yellow(vec.length)}`));
+        console.log(chalk.white(`  Output dim: ${chalk.yellow(resultArray.length)}`));
+        console.log(chalk.white(`  Result:     ${chalk.gray(`[${resultArray.slice(0, 5).map(v => v.toFixed(4)).join(', ')}...]`)}`));
+
+        // Compute norm to verify it's in the ball
+        const norm = Math.sqrt(resultArray.reduce((sum, x) => sum + x * x, 0));
+        console.log(chalk.white(`  Norm:       ${chalk.yellow(norm.toFixed(6))} ${norm < 1 ? chalk.green('(inside ball)') : chalk.red('(outside ball)')}`));
+      }
+    } catch (error) {
+      console.error(chalk.red('Hyperbolic operation failed:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Attention info command
+attentionCmd
+  .command('info')
+  .description('Show attention module information')
+  .action(() => {
+    if (!attentionAvailable) {
+      console.log(chalk.yellow('\nAttention Module: Not installed'));
+      console.log(chalk.white('Install with: npm install @ruvector/attention'));
+      return;
+    }
+
+    console.log(chalk.cyan('\nAttention Module Information'));
+    console.log(chalk.white(`  Status:         ${chalk.green('Available')}`));
+    console.log(chalk.white(`  Version:        ${chalk.yellow(attentionVersion ? attentionVersion() : 'unknown')}`));
+    console.log(chalk.white(`  Platform:       ${chalk.yellow(process.platform)}`));
+    console.log(chalk.white(`  Architecture:   ${chalk.yellow(process.arch)}`));
+
+    console.log(chalk.cyan('\nCore Attention Mechanisms:'));
+    console.log(chalk.white(`  • DotProductAttention  - Scaled dot-product attention`));
+    console.log(chalk.white(`  • MultiHeadAttention   - Multi-head self-attention`));
+    console.log(chalk.white(`  • FlashAttention       - Memory-efficient IO-aware attention`));
+    console.log(chalk.white(`  • HyperbolicAttention  - Poincaré ball attention`));
+    console.log(chalk.white(`  • LinearAttention      - O(n) linear complexity attention`));
+    console.log(chalk.white(`  • MoEAttention         - Mixture of Experts attention`));
+
+    console.log(chalk.cyan('\nGraph Attention:'));
+    console.log(chalk.white(`  • GraphRoPeAttention   - Rotary position embeddings for graphs`));
+    console.log(chalk.white(`  • EdgeFeaturedAttention - Edge feature-enhanced attention`));
+    console.log(chalk.white(`  • DualSpaceAttention   - Euclidean + hyperbolic dual space`));
+    console.log(chalk.white(`  • LocalGlobalAttention - Local-global graph attention`));
+
+    console.log(chalk.cyan('\nHyperbolic Math:'));
+    console.log(chalk.white(`  • expMap, logMap       - Exponential/logarithmic maps`));
+    console.log(chalk.white(`  • mobiusAddition       - Möbius addition in Poincaré ball`));
+    console.log(chalk.white(`  • poincareDistance     - Hyperbolic distance metric`));
+    console.log(chalk.white(`  • projectToPoincareBall - Project vectors to ball`));
+
+    console.log(chalk.cyan('\nTraining Utilities:'));
+    console.log(chalk.white(`  • AdamOptimizer, AdamWOptimizer, SgdOptimizer`));
+    console.log(chalk.white(`  • InfoNceLoss, LocalContrastiveLoss`));
+    console.log(chalk.white(`  • CurriculumScheduler, TemperatureAnnealing`));
+    console.log(chalk.white(`  • HardNegativeMiner, InBatchMiner`));
+  });
+
+// Attention list command - list available mechanisms
+attentionCmd
+  .command('list')
+  .description('List all available attention mechanisms')
+  .option('-v, --verbose', 'Show detailed information')
+  .action((options) => {
+    console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
+    console.log(chalk.cyan('              Available Attention Mechanisms'));
+    console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
+
+    const mechanisms = [
+      { name: 'DotProductAttention', type: 'core', complexity: 'O(n²)', available: !!DotProductAttention },
+      { name: 'MultiHeadAttention', type: 'core', complexity: 'O(n²)', available: !!MultiHeadAttention },
+      { name: 'FlashAttention', type: 'core', complexity: 'O(n²) IO-optimized', available: !!FlashAttention },
+      { name: 'HyperbolicAttention', type: 'core', complexity: 'O(n²)', available: !!HyperbolicAttention },
+      { name: 'LinearAttention', type: 'core', complexity: 'O(n)', available: !!LinearAttention },
+      { name: 'MoEAttention', type: 'core', complexity: 'O(n*k)', available: !!MoEAttention },
+      { name: 'GraphRoPeAttention', type: 'graph', complexity: 'O(n²)', available: !!GraphRoPeAttention },
+      { name: 'EdgeFeaturedAttention', type: 'graph', complexity: 'O(n²)', available: !!EdgeFeaturedAttention },
+      { name: 'DualSpaceAttention', type: 'graph', complexity: 'O(n²)', available: !!DualSpaceAttention },
+      { name: 'LocalGlobalAttention', type: 'graph', complexity: 'O(n*k)', available: !!LocalGlobalAttention },
+    ];
+
+    console.log(chalk.white('  Core Attention:'));
+    mechanisms.filter(m => m.type === 'core').forEach(m => {
+      const status = m.available ? chalk.green('✓') : chalk.red('✗');
+      console.log(chalk.white(`    ${status} ${m.name.padEnd(22)} ${chalk.gray(m.complexity)}`));
+    });
+
+    console.log(chalk.white('\n  Graph Attention:'));
+    mechanisms.filter(m => m.type === 'graph').forEach(m => {
+      const status = m.available ? chalk.green('✓') : chalk.red('✗');
+      console.log(chalk.white(`    ${status} ${m.name.padEnd(22)} ${chalk.gray(m.complexity)}`));
+    });
+
+    if (!attentionAvailable) {
+      console.log(chalk.yellow('\n  Note: @ruvector/attention not installed'));
+      console.log(chalk.white('  Install with: npm install @ruvector/attention'));
+    }
+
+    if (options.verbose) {
+      console.log(chalk.cyan('\n  Usage Examples:'));
+      console.log(chalk.gray('    # Compute dot-product attention'));
+      console.log(chalk.white('    npx ruvector attention compute -q "[1,2,3]" -k keys.json -t dot'));
+      console.log(chalk.gray('\n    # Benchmark attention mechanisms'));
+      console.log(chalk.white('    npx ruvector attention benchmark -d 256 -n 100'));
+      console.log(chalk.gray('\n    # Hyperbolic distance'));
+      console.log(chalk.white('    npx ruvector attention hyperbolic -a distance -v "[0.1,0.2]" -b "[0.3,0.4]"'));
+    }
+  });
+
+// =============================================================================
+// Doctor Command - Check system health and dependencies
+// =============================================================================
+
+program
+  .command('doctor')
+  .description('Check system health and dependencies')
+  .option('-v, --verbose', 'Show detailed information')
+  .action(async (options) => {
+    const { execSync } = require('child_process');
+
+    console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
+    console.log(chalk.cyan('                    RuVector Doctor'));
+    console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
+
+    let issues = 0;
+    let warnings = 0;
+
+    // Helper functions
+    const check = (name, condition, fix) => {
+      if (condition) {
+        console.log(chalk.green(`  ✓ ${name}`));
+        return true;
+      } else {
+        console.log(chalk.red(`  ✗ ${name}`));
+        if (fix) console.log(chalk.gray(`    Fix: ${fix}`));
+        issues++;
+        return false;
+      }
+    };
+
+    const warn = (name, condition, suggestion) => {
+      if (condition) {
+        console.log(chalk.green(`  ✓ ${name}`));
+        return true;
+      } else {
+        console.log(chalk.yellow(`  ! ${name}`));
+        if (suggestion) console.log(chalk.gray(`    Suggestion: ${suggestion}`));
+        warnings++;
+        return false;
+      }
+    };
+
+    const getVersion = (cmd) => {
+      try {
+        return execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+      } catch (e) {
+        return null;
+      }
+    };
+
+    // System Information
+    console.log(chalk.cyan('System Information:'));
+    console.log(chalk.white(`  Platform:      ${chalk.yellow(process.platform)}`));
+    console.log(chalk.white(`  Architecture:  ${chalk.yellow(process.arch)}`));
+    console.log(chalk.white(`  Node.js:       ${chalk.yellow(process.version)}`));
+    console.log('');
+
+    // Node.js Checks
+    console.log(chalk.cyan('Node.js Environment:'));
+    const nodeVersion = parseInt(process.version.slice(1).split('.')[0]);
+    check('Node.js >= 14', nodeVersion >= 14, 'Upgrade Node.js: https://nodejs.org');
+
+    const npmVersion = getVersion('npm --version');
+    if (npmVersion) {
+      console.log(chalk.green(`  ✓ npm ${npmVersion}`));
+    } else {
+      check('npm installed', false, 'Install npm or reinstall Node.js');
+    }
+    console.log('');
+
+    // RuVector Packages
+    console.log(chalk.cyan('RuVector Packages:'));
+
+    // Check @ruvector/core
+    let coreAvailable = false;
+    try {
+      require.resolve('@ruvector/core');
+      coreAvailable = true;
+      console.log(chalk.green(`  ✓ @ruvector/core installed`));
+    } catch (e) {
+      console.log(chalk.yellow(`  ! @ruvector/core not found (using WASM fallback)`));
+      warnings++;
+    }
+
+    // Check if native binding works
+    if (coreAvailable && loadRuvector()) {
+      const info = getVersion();
+      console.log(chalk.green(`  ✓ Native binding working (${info.implementation})`));
+    } else if (coreAvailable) {
+      console.log(chalk.yellow(`  ! Native binding failed to load`));
+      warnings++;
+    }
+
+    // Check @ruvector/gnn
+    if (gnnAvailable) {
+      console.log(chalk.green(`  ✓ @ruvector/gnn installed`));
+    } else {
+      console.log(chalk.gray(`  ○ @ruvector/gnn not installed (optional)`));
+    }
+
+    // Check @ruvector/attention
+    if (attentionAvailable) {
+      console.log(chalk.green(`  ✓ @ruvector/attention installed`));
+    } else {
+      console.log(chalk.gray(`  ○ @ruvector/attention not installed (optional)`));
+    }
+
+    // Check @ruvector/graph-node
+    try {
+      require.resolve('@ruvector/graph-node');
+      console.log(chalk.green(`  ✓ @ruvector/graph-node installed`));
+    } catch (e) {
+      console.log(chalk.gray(`  ○ @ruvector/graph-node not installed (optional)`));
+    }
+    console.log('');
+
+    // Rust Toolchain (optional for development)
+    console.log(chalk.cyan('Rust Toolchain (optional):'));
+
+    const rustVersion = getVersion('rustc --version');
+    if (rustVersion) {
+      console.log(chalk.green(`  ✓ ${rustVersion}`));
+    } else {
+      console.log(chalk.gray(`  ○ Rust not installed (only needed for development)`));
+    }
+
+    const cargoVersion = getVersion('cargo --version');
+    if (cargoVersion) {
+      console.log(chalk.green(`  ✓ ${cargoVersion}`));
+    } else if (rustVersion) {
+      console.log(chalk.yellow(`  ! cargo not found`));
+      warnings++;
+    }
+    console.log('');
+
+    // Build Tools (optional)
+    if (options.verbose) {
+      console.log(chalk.cyan('Build Tools (for native compilation):'));
+
+      const hasGcc = getVersion('gcc --version');
+      const hasClang = getVersion('clang --version');
+      const hasCc = getVersion('cc --version');
+
+      if (hasGcc || hasClang || hasCc) {
+        console.log(chalk.green(`  ✓ C compiler available`));
+      } else {
+        console.log(chalk.gray(`  ○ No C compiler found (only needed for building from source)`));
+      }
+
+      const hasMake = getVersion('make --version');
+      if (hasMake) {
+        console.log(chalk.green(`  ✓ make available`));
+      } else {
+        console.log(chalk.gray(`  ○ make not found`));
+      }
+
+      const hasCmake = getVersion('cmake --version');
+      if (hasCmake) {
+        console.log(chalk.green(`  ✓ cmake available`));
+      } else {
+        console.log(chalk.gray(`  ○ cmake not found`));
+      }
+      console.log('');
+    }
+
+    // Summary
+    console.log(chalk.cyan('═══════════════════════════════════════════════════════════════'));
+    if (issues === 0 && warnings === 0) {
+      console.log(chalk.green('\n  ✓ All checks passed! RuVector is ready to use.\n'));
+    } else if (issues === 0) {
+      console.log(chalk.yellow(`\n  ! ${warnings} warning(s) found. RuVector should work but may have limited features.\n`));
+    } else {
+      console.log(chalk.red(`\n  ✗ ${issues} issue(s) and ${warnings} warning(s) found.\n`));
+      console.log(chalk.white('  Run "npx ruvector setup" for installation instructions.\n'));
+    }
+  });
+
+// =============================================================================
+// Setup Command - Installation instructions
+// =============================================================================
+
+program
+  .command('setup')
+  .description('Show installation and setup instructions')
+  .option('--rust', 'Show Rust installation instructions')
+  .option('--npm', 'Show npm package installation instructions')
+  .option('--all', 'Show all installation instructions')
+  .action((options) => {
+    const showAll = options.all || (!options.rust && !options.npm);
+
+    console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
+    console.log(chalk.cyan('                    RuVector Setup Guide'));
+    console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
+
+    // Quick install
+    console.log(chalk.cyan('Quick Install (one-liner):'));
+    console.log(chalk.white('  curl -fsSL https://raw.githubusercontent.com/ruvnet/ruvector/main/install.sh | bash'));
+    console.log('');
+
+    if (showAll || options.npm) {
+      console.log(chalk.cyan('───────────────────────────────────────────────────────────────'));
+      console.log(chalk.cyan('npm Packages'));
+      console.log(chalk.cyan('───────────────────────────────────────────────────────────────\n'));
+
+      console.log(chalk.yellow('All-in-one CLI:'));
+      console.log(chalk.white('  npm install -g ruvector'));
+      console.log(chalk.white('  npx ruvector'));
+      console.log('');
+
+      console.log(chalk.yellow('Core packages:'));
+      console.log(chalk.white('  npm install @ruvector/core       # Vector database'));
+      console.log(chalk.white('  npm install @ruvector/gnn        # Graph Neural Networks'));
+      console.log(chalk.white('  npm install @ruvector/graph-node # Hypergraph database'));
+      console.log('');
+
+      console.log(chalk.yellow('Install all optional packages:'));
+      console.log(chalk.white('  npx ruvector install --all'));
+      console.log('');
+
+      console.log(chalk.yellow('List available packages:'));
+      console.log(chalk.white('  npx ruvector install'));
+      console.log('');
+    }
+
+    if (showAll || options.rust) {
+      console.log(chalk.cyan('───────────────────────────────────────────────────────────────'));
+      console.log(chalk.cyan('Rust Installation'));
+      console.log(chalk.cyan('───────────────────────────────────────────────────────────────\n'));
+
+      console.log(chalk.yellow('1. Install Rust:'));
+      console.log(chalk.white('  curl --proto \'=https\' --tlsv1.2 -sSf https://sh.rustup.rs | sh'));
+      console.log(chalk.gray('  # Follow the prompts, then restart your terminal or run:'));
+      console.log(chalk.white('  source $HOME/.cargo/env'));
+      console.log('');
+
+      console.log(chalk.yellow('2. Verify installation:'));
+      console.log(chalk.white('  rustc --version'));
+      console.log(chalk.white('  cargo --version'));
+      console.log('');
+
+      console.log(chalk.yellow('3. Add RuVector crates to your project:'));
+      console.log(chalk.white('  cargo add ruvector-core          # Vector database'));
+      console.log(chalk.white('  cargo add ruvector-graph         # Hypergraph with Cypher'));
+      console.log(chalk.white('  cargo add ruvector-gnn           # Graph Neural Networks'));
+      console.log('');
+
+      console.log(chalk.yellow('4. Other available crates:'));
+      console.log(chalk.white('  cargo add ruvector-cluster       # Distributed clustering'));
+      console.log(chalk.white('  cargo add ruvector-raft          # Raft consensus'));
+      console.log(chalk.white('  cargo add ruvector-replication   # Data replication'));
+      console.log(chalk.white('  cargo add ruvector-tiny-dancer-core  # AI routing'));
+      console.log(chalk.white('  cargo add ruvector-router-core   # Semantic routing'));
+      console.log('');
+
+      console.log(chalk.yellow('Platform-specific notes:'));
+      console.log('');
+
+      if (process.platform === 'darwin') {
+        console.log(chalk.cyan('  macOS:'));
+        console.log(chalk.white('    xcode-select --install  # Install command line tools'));
+        console.log('');
+      } else if (process.platform === 'linux') {
+        console.log(chalk.cyan('  Linux (Debian/Ubuntu):'));
+        console.log(chalk.white('    sudo apt-get update'));
+        console.log(chalk.white('    sudo apt-get install build-essential pkg-config libssl-dev'));
+        console.log('');
+        console.log(chalk.cyan('  Linux (RHEL/CentOS):'));
+        console.log(chalk.white('    sudo yum groupinstall "Development Tools"'));
+        console.log(chalk.white('    sudo yum install openssl-devel'));
+        console.log('');
+      } else if (process.platform === 'win32') {
+        console.log(chalk.cyan('  Windows:'));
+        console.log(chalk.white('    # Install Visual Studio Build Tools'));
+        console.log(chalk.white('    # https://visualstudio.microsoft.com/visual-cpp-build-tools/'));
+        console.log(chalk.white('    # Or use WSL2 for best experience'));
+        console.log('');
+      }
+    }
+
+    console.log(chalk.cyan('───────────────────────────────────────────────────────────────'));
+    console.log(chalk.cyan('Documentation & Resources'));
+    console.log(chalk.cyan('───────────────────────────────────────────────────────────────\n'));
+
+    console.log(chalk.white('  GitHub:     https://github.com/ruvnet/ruvector'));
+    console.log(chalk.white('  npm:        https://www.npmjs.com/package/ruvector'));
+    console.log(chalk.white('  crates.io:  https://crates.io/crates/ruvector-core'));
+    console.log(chalk.white('  Issues:     https://github.com/ruvnet/ruvector/issues'));
+    console.log('');
+
+    console.log(chalk.cyan('Quick Commands:'));
+    console.log(chalk.white('  npx ruvector doctor     # Check system health'));
+    console.log(chalk.white('  npx ruvector info       # Show version info'));
+    console.log(chalk.white('  npx ruvector benchmark  # Run performance test'));
+    console.log(chalk.white('  npx ruvector install    # List available packages'));
+    console.log('');
+  });
+
+// =============================================================================
+// Graph Commands - Cypher queries and graph operations
+// =============================================================================
+
+program
+  .command('graph')
+  .description('Graph database operations (requires @ruvector/graph-node)')
+  .option('-q, --query <cypher>', 'Execute Cypher query')
+  .option('-c, --create <label>', 'Create a node with label')
+  .option('-p, --properties <json>', 'Node properties as JSON')
+  .option('-r, --relate <spec>', 'Create relationship (from:rel:to)')
+  .option('--info', 'Show graph info and stats')
+  .action(async (options) => {
+    let graphNode;
+    try {
+      graphNode = require('@ruvector/graph-node');
+    } catch (e) {
+      console.log(chalk.yellow('\n  @ruvector/graph-node is not installed.\n'));
+      console.log(chalk.cyan('  Install with:'));
+      console.log(chalk.white('    npm install @ruvector/graph-node\n'));
+      console.log(chalk.cyan('  Features:'));
+      console.log(chalk.gray('    - Cypher query language support'));
+      console.log(chalk.gray('    - Hypergraph data structure'));
+      console.log(chalk.gray('    - Knowledge graph operations'));
+      console.log(chalk.gray('    - Neo4j-compatible syntax\n'));
+      console.log(chalk.cyan('  Example usage:'));
+      console.log(chalk.white('    npx ruvector graph --query "CREATE (n:Person {name: \'Alice\'})"'));
+      console.log(chalk.white('    npx ruvector graph --query "MATCH (n) RETURN n"'));
+      console.log('');
+      return;
+    }
+
+    console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
+    console.log(chalk.cyan('                    RuVector Graph'));
+    console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
+
+    if (options.info) {
+      console.log(chalk.green('  @ruvector/graph-node is available!'));
+      console.log(chalk.gray(`  Platform: ${process.platform}-${process.arch}`));
+      console.log('');
+      console.log(chalk.yellow('  Available operations:'));
+      console.log(chalk.white('    --query <cypher>    Execute Cypher query'));
+      console.log(chalk.white('    --create <label>    Create node with label'));
+      console.log(chalk.white('    --relate <spec>     Create relationship'));
+      console.log('');
+      return;
+    }
+
+    if (options.query) {
+      console.log(chalk.yellow('  Cypher Query:'), chalk.white(options.query));
+      console.log('');
+      // Actual implementation would execute the query
+      console.log(chalk.gray('  Note: Full Cypher execution requires running ruvector-server'));
+      console.log(chalk.gray('  See: npx ruvector server --help'));
+    }
+
+    if (options.create) {
+      const label = options.create;
+      const props = options.properties ? JSON.parse(options.properties) : {};
+      console.log(chalk.yellow('  Creating node:'), chalk.white(label));
+      console.log(chalk.gray('  Properties:'), JSON.stringify(props, null, 2));
+    }
+
+    console.log('');
+  });
+
+// =============================================================================
+// Router Commands - AI agent routing
+// =============================================================================
+
+program
+  .command('router')
+  .description('AI semantic router operations (requires ruvector-router-core)')
+  .option('--route <text>', 'Route text to best matching intent')
+  .option('--intents <file>', 'Load intents from JSON file')
+  .option('--add-intent <name>', 'Add new intent')
+  .option('--examples <json>', 'Example utterances for intent')
+  .option('--info', 'Show router info')
+  .action(async (options) => {
+    console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
+    console.log(chalk.cyan('                    RuVector Router'));
+    console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
+
+    console.log(chalk.yellow('  Semantic Router for AI Agent Routing\n'));
+
+    if (options.info || (!options.route && !options.intents && !options.addIntent)) {
+      console.log(chalk.cyan('  Features:'));
+      console.log(chalk.gray('    - Semantic intent matching'));
+      console.log(chalk.gray('    - Multi-agent routing'));
+      console.log(chalk.gray('    - Dynamic intent registration'));
+      console.log(chalk.gray('    - Vector-based similarity matching'));
+      console.log('');
+      console.log(chalk.cyan('  Status:'), chalk.yellow('Coming Soon'));
+      console.log(chalk.gray('  The npm package for router is in development.'));
+      console.log(chalk.gray('  Rust crate available: cargo add ruvector-router-core'));
+      console.log('');
+      console.log(chalk.cyan('  Usage (when available):'));
+      console.log(chalk.white('    npx ruvector router --route "What is the weather?"'));
+      console.log(chalk.white('    npx ruvector router --intents intents.json --route "query"'));
+      console.log('');
+      return;
+    }
+
+    if (options.route) {
+      console.log(chalk.yellow('  Input:'), chalk.white(options.route));
+      console.log(chalk.gray('  Router package not yet available in npm.'));
+      console.log(chalk.gray('  Check issue #20 for roadmap.'));
+    }
+
+    console.log('');
+  });
+
+// =============================================================================
+// Server Commands - HTTP/gRPC server
+// =============================================================================
+
+program
+  .command('server')
+  .description('Start RuVector HTTP/gRPC server')
+  .option('-p, --port <number>', 'HTTP port', '8080')
+  .option('-g, --grpc-port <number>', 'gRPC port', '50051')
+  .option('-d, --data-dir <path>', 'Data directory', './ruvector-data')
+  .option('--http-only', 'Start only HTTP server')
+  .option('--grpc-only', 'Start only gRPC server')
+  .option('--cors', 'Enable CORS for all origins')
+  .option('--info', 'Show server info')
+  .action(async (options) => {
+    console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
+    console.log(chalk.cyan('                    RuVector Server'));
+    console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
+
+    if (options.info || Object.keys(options).filter(k => k !== 'port' && k !== 'grpcPort' && k !== 'dataDir').length === 0) {
+      console.log(chalk.cyan('  Status:'), chalk.yellow('Coming Soon'));
+      console.log('');
+      console.log(chalk.cyan('  Planned Features:'));
+      console.log(chalk.gray('    - REST API for vector operations'));
+      console.log(chalk.gray('    - gRPC high-performance interface'));
+      console.log(chalk.gray('    - WebSocket real-time updates'));
+      console.log(chalk.gray('    - OpenAPI/Swagger documentation'));
+      console.log(chalk.gray('    - Prometheus metrics endpoint'));
+      console.log(chalk.gray('    - Health check endpoints'));
+      console.log('');
+      console.log(chalk.cyan('  Rust binary available:'));
+      console.log(chalk.white('    cargo install ruvector-server  # When published'));
+      console.log('');
+      console.log(chalk.cyan('  Configuration (when available):'));
+      console.log(chalk.white(`    --port ${options.port}            # HTTP port`));
+      console.log(chalk.white(`    --grpc-port ${options.grpcPort}       # gRPC port`));
+      console.log(chalk.white(`    --data-dir ${options.dataDir}  # Data directory`));
+      console.log('');
+      console.log(chalk.gray('  Track progress: https://github.com/ruvnet/ruvector/issues/20'));
+      console.log('');
+      return;
+    }
+
+    console.log(chalk.yellow('  Server package not yet available.'));
+    console.log(chalk.gray('  Check issue #20 for roadmap.'));
+    console.log('');
+  });
+
+// =============================================================================
+// Cluster Commands - Distributed operations
+// =============================================================================
+
+program
+  .command('cluster')
+  .description('Distributed cluster operations')
+  .option('--status', 'Show cluster status')
+  .option('--join <address>', 'Join existing cluster')
+  .option('--leave', 'Leave cluster')
+  .option('--nodes', 'List cluster nodes')
+  .option('--leader', 'Show current leader')
+  .option('--info', 'Show cluster info')
+  .action(async (options) => {
+    console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
+    console.log(chalk.cyan('                    RuVector Cluster'));
+    console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
+
+    console.log(chalk.cyan('  Status:'), chalk.yellow('Coming Soon'));
+    console.log('');
+    console.log(chalk.cyan('  Features:'));
+    console.log(chalk.gray('    - Raft consensus for leader election'));
+    console.log(chalk.gray('    - Automatic failover'));
+    console.log(chalk.gray('    - Data replication'));
+    console.log(chalk.gray('    - Sharding support'));
+    console.log(chalk.gray('    - Distributed queries'));
+    console.log('');
+    console.log(chalk.cyan('  Rust crates available:'));
+    console.log(chalk.white('    cargo add ruvector-cluster      # Clustering'));
+    console.log(chalk.white('    cargo add ruvector-raft         # Raft consensus'));
+    console.log(chalk.white('    cargo add ruvector-replication  # Replication'));
+    console.log('');
+    console.log(chalk.cyan('  Commands (when available):'));
+    console.log(chalk.white('    npx ruvector cluster --status'));
+    console.log(chalk.white('    npx ruvector cluster --join 192.168.1.10:7000'));
+    console.log(chalk.white('    npx ruvector cluster --nodes'));
+    console.log('');
+    console.log(chalk.gray('  Track progress: https://github.com/ruvnet/ruvector/issues/20'));
+    console.log('');
+  });
+
+// =============================================================================
+// Export/Import Commands - Database backup/restore
+// =============================================================================
+
+program
+  .command('export <database>')
+  .description('Export database to file')
+  .option('-o, --output <file>', 'Output file path')
+  .option('-f, --format <type>', 'Export format (json|binary|parquet)', 'json')
+  .option('--compress', 'Compress output')
+  .option('--vectors-only', 'Export only vectors (no metadata)')
+  .action(async (dbPath, options) => {
+    requireRuvector();
+    const spinner = ora('Exporting database...').start();
+
+    try {
+      const outputFile = options.output || `${dbPath.replace(/\/$/, '')}_export.${options.format}`;
+
+      // Load database
+      const db = new VectorDB({ dimension: 384 }); // Will be overwritten by load
+      if (fs.existsSync(dbPath)) {
+        db.load(dbPath);
+      } else {
+        spinner.fail(chalk.red(`Database not found: ${dbPath}`));
+        process.exit(1);
+      }
+
+      const stats = db.getStats();
+      const data = {
+        version: packageJson.version,
+        exportedAt: new Date().toISOString(),
+        stats: stats,
+        vectors: [] // Would contain actual vector data
+      };
+
+      if (options.format === 'json') {
+        fs.writeFileSync(outputFile, JSON.stringify(data, null, 2));
+      } else {
+        spinner.fail(chalk.yellow(`Format '${options.format}' not yet supported. Using JSON.`));
+        fs.writeFileSync(outputFile.replace(/\.[^.]+$/, '.json'), JSON.stringify(data, null, 2));
+      }
+
+      spinner.succeed(chalk.green(`Exported to: ${outputFile}`));
+      console.log(chalk.gray(`  Vectors: ${stats.count || 0}`));
+      console.log(chalk.gray(`  Format: ${options.format}`));
+    } catch (error) {
+      spinner.fail(chalk.red('Export failed'));
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('import <file>')
+  .description('Import database from file')
+  .option('-d, --database <path>', 'Target database path')
+  .option('--merge', 'Merge with existing data')
+  .option('--replace', 'Replace existing data')
+  .action(async (file, options) => {
+    requireRuvector();
+    const spinner = ora('Importing database...').start();
+
+    try {
+      if (!fs.existsSync(file)) {
+        spinner.fail(chalk.red(`File not found: ${file}`));
+        process.exit(1);
+      }
+
+      const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const dbPath = options.database || file.replace(/_export\.json$/, '');
+
+      spinner.text = 'Creating database...';
+
+      const db = new VectorDB({
+        dimension: data.stats?.dimension || 384,
+        path: dbPath,
+        autoPersist: true
+      });
+
+      // Would import actual vectors here
+      db.save(dbPath);
+
+      spinner.succeed(chalk.green(`Imported to: ${dbPath}`));
+      console.log(chalk.gray(`  Source version: ${data.version}`));
+      console.log(chalk.gray(`  Exported at: ${data.exportedAt}`));
+    } catch (error) {
+      spinner.fail(chalk.red('Import failed'));
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+// =============================================================================
+// Embed Command - Generate embeddings
+// =============================================================================
+
+program
+  .command('embed')
+  .description('Generate embeddings from text')
+  .option('-t, --text <string>', 'Text to embed')
+  .option('-f, --file <path>', 'File containing text (one per line)')
+  .option('-m, --model <name>', 'Embedding model', 'all-minilm-l6-v2')
+  .option('-o, --output <file>', 'Output file for embeddings')
+  .option('--info', 'Show embedding info')
+  .action(async (options) => {
+    console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
+    console.log(chalk.cyan('                    RuVector Embed'));
+    console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
+
+    if (options.info || (!options.text && !options.file)) {
+      console.log(chalk.cyan('  Generate vector embeddings from text\n'));
+      console.log(chalk.cyan('  Supported Models:'));
+      console.log(chalk.gray('    - all-minilm-l6-v2 (384 dims, fast)'));
+      console.log(chalk.gray('    - nomic-embed-text-v1.5 (768 dims, balanced)'));
+      console.log(chalk.gray('    - openai/text-embedding-3-small (1536 dims, requires API key)'));
+      console.log('');
+      console.log(chalk.cyan('  Status:'), chalk.yellow('Coming Soon'));
+      console.log(chalk.gray('  Built-in embedding generation is planned for future release.'));
+      console.log('');
+      console.log(chalk.cyan('  Current options:'));
+      console.log(chalk.gray('    1. Use external embedding API (OpenAI, Cohere, etc.)'));
+      console.log(chalk.gray('    2. Use transformers.js in your application'));
+      console.log(chalk.gray('    3. Pre-generate embeddings with Python'));
+      console.log('');
+      console.log(chalk.cyan('  Usage (when available):'));
+      console.log(chalk.white('    npx ruvector embed --text "Hello world"'));
+      console.log(chalk.white('    npx ruvector embed --file texts.txt --output embeddings.json'));
+      console.log('');
+      return;
+    }
+
+    if (options.text) {
+      console.log(chalk.yellow('  Input text:'), chalk.white(options.text.substring(0, 50) + '...'));
+      console.log(chalk.yellow('  Model:'), chalk.white(options.model));
+      console.log('');
+      console.log(chalk.gray('  Embedding generation not yet available in CLI.'));
+      console.log(chalk.gray('  Use the SDK or external embedding services.'));
+    }
+
+    console.log('');
+  });
+
+// =============================================================================
+// Demo Command - Interactive tutorial
+// =============================================================================
+
+program
+  .command('demo')
+  .description('Run interactive demo and tutorials')
+  .option('--basic', 'Basic vector operations demo')
+  .option('--gnn', 'GNN differentiable search demo')
+  .option('--graph', 'Graph database demo')
+  .option('--benchmark', 'Performance benchmark demo')
+  .option('-i, --interactive', 'Interactive mode')
+  .action(async (options) => {
+    console.log(chalk.cyan('\n═══════════════════════════════════════════════════════════════'));
+    console.log(chalk.cyan('                    RuVector Demo'));
+    console.log(chalk.cyan('═══════════════════════════════════════════════════════════════\n'));
+
+    const showMenu = !options.basic && !options.gnn && !options.graph && !options.benchmark;
+
+    if (showMenu) {
+      console.log(chalk.yellow('  Available Demos:\n'));
+      console.log(chalk.white('    --basic      '), chalk.gray('Basic vector operations (insert, search, delete)'));
+      console.log(chalk.white('    --gnn        '), chalk.gray('GNN differentiable search with gradients'));
+      console.log(chalk.white('    --graph      '), chalk.gray('Graph database and Cypher queries'));
+      console.log(chalk.white('    --benchmark  '), chalk.gray('Performance benchmark suite'));
+      console.log('');
+      console.log(chalk.cyan('  Run a demo:'));
+      console.log(chalk.white('    npx ruvector demo --basic'));
+      console.log(chalk.white('    npx ruvector demo --gnn'));
+      console.log('');
+      return;
+    }
+
+    if (options.basic) {
+      requireRuvector();
+      console.log(chalk.yellow('  Basic Vector Operations Demo\n'));
+
+      const spinner = ora('Creating demo database...').start();
+
+      try {
+        const db = new VectorDB({ dimension: 4, metric: 'cosine' });
+
+        spinner.text = 'Inserting vectors...';
+        db.insert('vec1', [1.0, 0.0, 0.0, 0.0], { label: 'x-axis' });
+        db.insert('vec2', [0.0, 1.0, 0.0, 0.0], { label: 'y-axis' });
+        db.insert('vec3', [0.0, 0.0, 1.0, 0.0], { label: 'z-axis' });
+        db.insert('vec4', [0.7, 0.7, 0.0, 0.0], { label: 'xy-diagonal' });
+
+        spinner.succeed('Demo database created with 4 vectors');
+
+        console.log(chalk.cyan('\n  Vectors inserted:'));
+        console.log(chalk.gray('    vec1: [1,0,0,0] - x-axis'));
+        console.log(chalk.gray('    vec2: [0,1,0,0] - y-axis'));
+        console.log(chalk.gray('    vec3: [0,0,1,0] - z-axis'));
+        console.log(chalk.gray('    vec4: [0.7,0.7,0,0] - xy-diagonal'));
+
+        console.log(chalk.cyan('\n  Searching for nearest to [0.8, 0.6, 0, 0]:'));
+        const results = db.search([0.8, 0.6, 0.0, 0.0], 3);
+        results.forEach((r, i) => {
+          console.log(chalk.gray(`    ${i + 1}. ${r.id} (score: ${r.score.toFixed(4)})`));
+        });
+
+        console.log(chalk.green('\n  Demo complete!'));
+      } catch (error) {
+        spinner.fail(chalk.red('Demo failed'));
+        console.error(chalk.red(error.message));
+      }
+    }
+
+    if (options.gnn) {
+      if (!gnnAvailable) {
+        console.log(chalk.yellow('  @ruvector/gnn not installed.'));
+        console.log(chalk.white('  Install with: npm install @ruvector/gnn'));
+        console.log('');
+        return;
+      }
+
+      console.log(chalk.yellow('  GNN Differentiable Search Demo\n'));
+
+      try {
+        console.log(chalk.cyan('  Running differentiable search with gradients...\n'));
+
+        const queryVec = [1.0, 0.5, 0.3, 0.1];
+        const dbVectors = [
+          [1.0, 0.0, 0.0, 0.0],
+          [0.0, 1.0, 0.0, 0.0],
+          [0.5, 0.5, 0.5, 0.5],
+          [0.9, 0.4, 0.2, 0.1]
+        ];
+
+        const result = differentiableSearch(queryVec, dbVectors, 3, 10.0);
+
+        console.log(chalk.cyan('  Query:'), JSON.stringify(queryVec));
+        console.log(chalk.cyan('  Top 3 results:'));
+        result.indices.forEach((idx, i) => {
+          console.log(chalk.gray(`    ${i + 1}. Index ${idx} (attention: ${result.attention_weights[i].toFixed(4)})`));
+        });
+
+        console.log(chalk.cyan('\n  Gradient flow enabled:'), chalk.green('Yes'));
+        console.log(chalk.gray('  Use for: Neural network training, learned retrieval'));
+
+        console.log(chalk.green('\n  GNN demo complete!'));
+      } catch (error) {
+        console.error(chalk.red('GNN demo failed:', error.message));
+      }
+    }
+
+    if (options.graph) {
+      console.log(chalk.yellow('  Graph Database Demo\n'));
+
+      let graphNode;
+      try {
+        graphNode = require('@ruvector/graph-node');
+        console.log(chalk.green('  @ruvector/graph-node is available!'));
+        console.log(chalk.gray('  Full graph demo coming soon.'));
+      } catch (e) {
+        console.log(chalk.yellow('  @ruvector/graph-node not installed.'));
+        console.log(chalk.white('  Install with: npm install @ruvector/graph-node'));
+      }
+      console.log('');
+    }
+
+    if (options.benchmark) {
+      console.log(chalk.yellow('  Redirecting to benchmark command...\n'));
+      console.log(chalk.white('  Run: npx ruvector benchmark'));
+      console.log('');
+    }
+  });
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvector",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "High-performance vector database for Node.js with automatic native/WASM fallback",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,7 +29,11 @@
     "wasm",
     "native",
     "ruv",
-    "ruvector"
+    "ruvector",
+    "attention",
+    "transformer",
+    "flash-attention",
+    "hyperbolic"
   ],
   "author": "ruv.io Team <info@ruv.io> (https://ruv.io)",
   "homepage": "https://ruv.io",
@@ -43,12 +47,15 @@
     "directory": "npm/packages/ruvector"
   },
   "dependencies": {
-    "@ruvector/core": "^0.1.15",
+    "@ruvector/core": "^0.1.16",
     "@ruvector/gnn": "^0.1.15",
     "commander": "^11.1.0",
     "chalk": "^4.1.2",
     "ora": "^5.4.1"
   },
+  "optionalDependencies": {
+    "@ruvector/attention": "^0.1.1"
+  },
   "devDependencies": {
     "@types/node": "^20.10.5",
     "typescript": "^5.3.3"