ruvector 0.1.25 → 0.1.26

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

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

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

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

package/README.md

@@ -484,6 +484,119 @@ npx ruvector gnn search -q "[1.0,0.0,0.0]" -c candidates.json -k 5
 #   -t, --temperature  Softmax temperature (default: 1.0)
 ```
 
+### Attention Commands
+
+Ruvector includes high-performance attention mechanisms for transformer-based operations, hyperbolic embeddings, and graph attention.
+
+```bash
+# Install the attention module (optional)
+npm install @ruvector/attention
+```
+
+#### Attention Mechanisms Reference
+
+| Mechanism | Type | Complexity | When to Use |
+|-----------|------|------------|-------------|
+| **DotProductAttention** | Core | O(n²) | Standard scaled dot-product attention for transformers |
+| **MultiHeadAttention** | Core | O(n²) | Parallel attention heads for capturing different relationships |
+| **FlashAttention** | Core | O(n²) IO-optimized | Memory-efficient attention for long sequences |
+| **HyperbolicAttention** | Core | O(n²) | Hierarchical data, tree-like structures, taxonomies |
+| **LinearAttention** | Core | O(n) | Very long sequences where O(n²) is prohibitive |
+| **MoEAttention** | Core | O(n*k) | Mixture of Experts routing, specialized attention |
+| **GraphRoPeAttention** | Graph | O(n²) | Graph data with rotary position embeddings |
+| **EdgeFeaturedAttention** | Graph | O(n²) | Graphs with rich edge features/attributes |
+| **DualSpaceAttention** | Graph | O(n²) | Combined Euclidean + hyperbolic representation |
+| **LocalGlobalAttention** | Graph | O(n*k) | Large graphs with local + global context |
+
+#### Attention Info
+
+```bash
+# Show attention module information
+npx ruvector attention info
+
+# Output:
+#   Attention Module Information
+#     Status:         Available
+#     Version:        0.1.0
+#     Platform:       linux
+#     Architecture:   x64
+#
+#   Core Attention Mechanisms:
+#     • DotProductAttention  - Scaled dot-product attention
+#     • MultiHeadAttention   - Multi-head self-attention
+#     • FlashAttention       - Memory-efficient IO-aware attention
+#     • HyperbolicAttention  - Poincaré ball attention
+#     • LinearAttention      - O(n) linear complexity attention
+#     • MoEAttention         - Mixture of Experts attention
+```
+
+#### Attention List
+
+```bash
+# List all available attention mechanisms
+npx ruvector attention list
+
+# With verbose details
+npx ruvector attention list -v
+```
+
+#### Attention Benchmark
+
+```bash
+# Benchmark attention mechanisms
+npx ruvector attention benchmark -d 256 -n 100 -i 100
+
+# Options:
+#   -d, --dimension     Vector dimension (default: 256)
+#   -n, --num-vectors   Number of vectors (default: 100)
+#   -i, --iterations    Benchmark iterations (default: 100)
+#   -t, --types         Attention types to benchmark (default: dot,flash,linear)
+
+# Example output:
+#   Dimension:    256
+#   Vectors:      100
+#   Iterations:   100
+#
+#   dot:   0.012ms/op (84,386 ops/sec)
+#   flash: 0.012ms/op (82,844 ops/sec)
+#   linear: 0.066ms/op (15,259 ops/sec)
+```
+
+#### Hyperbolic Operations
+
+```bash
+# Calculate Poincaré distance between two points
+npx ruvector attention hyperbolic -a distance -v "[0.1,0.2,0.3]" -b "[0.4,0.5,0.6]"
+
+# Project vector to Poincaré ball
+npx ruvector attention hyperbolic -a project -v "[1.5,2.0,0.8]"
+
+# Möbius addition in hyperbolic space
+npx ruvector attention hyperbolic -a mobius-add -v "[0.1,0.2]" -b "[0.3,0.4]"
+
+# Exponential map (tangent space → Poincaré ball)
+npx ruvector attention hyperbolic -a exp-map -v "[0.1,0.2,0.3]"
+
+# Options:
+#   -a, --action      Action: distance|project|mobius-add|exp-map|log-map
+#   -v, --vector      Input vector as JSON array (required)
+#   -b, --vector-b    Second vector for binary operations
+#   -c, --curvature   Poincaré ball curvature (default: 1.0)
+```
+
+#### When to Use Each Attention Type
+
+| Use Case | Recommended Attention | Reason |
+|----------|----------------------|--------|
+| **Standard NLP/Transformers** | MultiHeadAttention | Industry standard, well-tested |
+| **Long Documents (>4K tokens)** | FlashAttention or LinearAttention | Memory efficient |
+| **Hierarchical Classification** | HyperbolicAttention | Captures tree-like structures |
+| **Knowledge Graphs** | GraphRoPeAttention | Position-aware graph attention |
+| **Multi-Relational Graphs** | EdgeFeaturedAttention | Leverages edge attributes |
+| **Taxonomy/Ontology Search** | DualSpaceAttention | Best of both Euclidean + hyperbolic |
+| **Large-Scale Graphs** | LocalGlobalAttention | Efficient local + global context |
+| **Model Routing/MoE** | MoEAttention | Expert selection and routing |
+
 ## 📊 Performance Benchmarks
 
 Tested on AMD Ryzen 9 5950X, 128-dimensional vectors:

package/bin/cli.js

@@ -356,9 +356,10 @@ program
 
     // Try to load ruvector for implementation info
     if (loadRuvector()) {
-      const info = getVersion();
-      console.log(chalk.white(`  Core Version: ${chalk.yellow(info.version)}`));
-      console.log(chalk.white(`  Implementation: ${chalk.yellow(info.implementation)}`));
+      const version = typeof getVersion === 'function' ? getVersion() : 'unknown';
+      const impl = typeof getImplementationType === 'function' ? getImplementationType() : 'native';
+      console.log(chalk.white(`  Core Version: ${chalk.yellow(version)}`));
+      console.log(chalk.white(`  Implementation: ${chalk.yellow(impl)}`));
     } else {
       console.log(chalk.white(`  Core: ${chalk.gray('Not loaded (install @ruvector/core)')}`));
     }
@@ -1056,6 +1057,10 @@ attentionCmd
 
       const results = [];
 
+      // Convert to Float32Arrays for compute()
+      const queryF32 = new Float32Array(query);
+      const keysF32 = keys.map(k => new Float32Array(k));
+
       for (const type of types) {
         spinner.text = `Benchmarking ${type} attention...`;
         spinner.start();
@@ -1064,39 +1069,42 @@ attentionCmd
         try {
           switch (type) {
             case 'dot':
-              attn = new DotProductAttention();
+              attn = new DotProductAttention(dim);
               break;
             case 'flash':
-              attn = new FlashAttention(dim);
+              attn = new FlashAttention(dim, 64);  // dim, block_size
               break;
             case 'linear':
-              attn = new LinearAttention(dim);
+              attn = new LinearAttention(dim, 64);  // dim, num_features
               break;
             case 'hyperbolic':
               attn = new HyperbolicAttention(dim, 1.0);
               break;
             case 'multi-head':
-              attn = new MultiHeadAttention(dim, 4, 64);
+              attn = new MultiHeadAttention(dim, 4);  // dim, num_heads
               break;
             default:
               console.log(chalk.yellow(`  Skipping unknown type: ${type}`));
               continue;
           }
         } catch (e) {
-          console.log(chalk.yellow(`  ${type}: not available`));
+          console.log(chalk.yellow(`  ${type}: not available (${e.message})`));
           continue;
         }
 
         // Warm up
-        const queryMat = [query];
         for (let i = 0; i < 5; i++) {
-          attn.forward(queryMat, keys, keys);
+          try {
+            attn.compute(queryF32, keysF32, keysF32);
+          } catch (e) {
+            // Some mechanisms may fail warmup
+          }
         }
 
         // Benchmark
         const start = process.hrtime.bigint();
         for (let i = 0; i < iterations; i++) {
-          attn.forward(queryMat, keys, keys);
+          attn.compute(queryF32, keysF32, keysF32);
         }
         const end = process.hrtime.bigint();
         const totalMs = Number(end - start) / 1_000_000;
@@ -1398,8 +1406,10 @@ program
 
     // Check if native binding works
     if (coreAvailable && loadRuvector()) {
-      const info = getVersion();
-      console.log(chalk.green(`  ✓ Native binding working (${info.implementation})`));
+      const version = typeof getVersion === 'function' ? getVersion() : null;
+      const impl = typeof getImplementationType === 'function' ? getImplementationType() : 'native';
+      const versionStr = version ? `, v${version}` : '';
+      console.log(chalk.green(`  ✓ Native binding working (${impl}${versionStr})`));
     } else if (coreAvailable) {
       console.log(chalk.yellow(`  ! Native binding failed to load`));
       warnings++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvector",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "High-performance vector database for Node.js with automatic native/WASM fallback",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -49,8 +49,8 @@
   "dependencies": {
     "@ruvector/core": "^0.1.16",
     "@ruvector/gnn": "^0.1.15",
-    "commander": "^11.1.0",
     "chalk": "^4.1.2",
+    "commander": "^11.1.0",
     "ora": "^5.4.1"
   },
   "optionalDependencies": {