ruvector 0.1.25 → 0.1.27

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

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

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

@@ -1,10 +1,10 @@
 [
   {
-    "id": "cmd-hooks-1764542370895",
+    "id": "cmd-hooks-1764779126675",
     "type": "hooks",
     "success": true,
-    "duration": 15.263496999999973,
-    "timestamp": 1764542370910,
+    "duration": 6.509910999999988,
+    "timestamp": 1764779126682,
     "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/dist/core/agentdb-fast.d.ts

@@ -0,0 +1,149 @@
+/**
+ * AgentDB Fast - High-performance in-process alternative to AgentDB CLI
+ *
+ * The AgentDB CLI has ~2.3s startup overhead due to npx initialization.
+ * This module provides 50-200x faster operations by using in-process calls.
+ *
+ * Features:
+ * - In-memory episode storage with LRU eviction
+ * - Vector similarity search using @ruvector/core
+ * - Compatible API with AgentDB's episode/trajectory interfaces
+ */
+/**
+ * Episode entry for trajectory storage
+ */
+export interface Episode {
+    id: string;
+    state: number[];
+    action: string | number;
+    reward: number;
+    nextState: number[];
+    done: boolean;
+    metadata?: Record<string, any>;
+    timestamp?: number;
+}
+/**
+ * Trajectory (sequence of episodes)
+ */
+export interface Trajectory {
+    id: string;
+    episodes: Episode[];
+    totalReward: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Search result for episode queries
+ */
+export interface EpisodeSearchResult {
+    episode: Episode;
+    similarity: number;
+    trajectoryId?: string;
+}
+/**
+ * Fast in-memory AgentDB implementation
+ */
+export declare class FastAgentDB {
+    private episodes;
+    private trajectories;
+    private vectorDb;
+    private dimensions;
+    private maxEpisodes;
+    private episodeOrder;
+    /**
+     * Create a new FastAgentDB instance
+     *
+     * @param dimensions - Vector dimensions for state embeddings
+     * @param maxEpisodes - Maximum episodes to store (LRU eviction)
+     */
+    constructor(dimensions?: number, maxEpisodes?: number);
+    /**
+     * Initialize the vector database
+     */
+    private initVectorDb;
+    /**
+     * Store an episode
+     *
+     * @param episode - Episode to store
+     * @returns Episode ID
+     */
+    storeEpisode(episode: Omit<Episode, 'id'> & {
+        id?: string;
+    }): Promise<string>;
+    /**
+     * Store multiple episodes in batch
+     */
+    storeEpisodes(episodes: (Omit<Episode, 'id'> & {
+        id?: string;
+    })[]): Promise<string[]>;
+    /**
+     * Retrieve an episode by ID
+     */
+    getEpisode(id: string): Promise<Episode | null>;
+    /**
+     * Search for similar episodes by state
+     *
+     * @param queryState - State vector to search for
+     * @param k - Number of results to return
+     * @returns Similar episodes sorted by similarity
+     */
+    searchByState(queryState: number[] | Float32Array, k?: number): Promise<EpisodeSearchResult[]>;
+    /**
+     * Fallback similarity search using brute-force cosine similarity
+     */
+    private fallbackSearch;
+    /**
+     * Compute cosine similarity between two vectors
+     */
+    private cosineSimilarity;
+    /**
+     * Store a trajectory (sequence of episodes)
+     */
+    storeTrajectory(episodes: (Omit<Episode, 'id'> & {
+        id?: string;
+    })[], metadata?: Record<string, any>): Promise<string>;
+    /**
+     * Get a trajectory by ID
+     */
+    getTrajectory(id: string): Promise<Trajectory | null>;
+    /**
+     * Get top trajectories by total reward
+     */
+    getTopTrajectories(k?: number): Promise<Trajectory[]>;
+    /**
+     * Sample random episodes (for experience replay)
+     */
+    sampleEpisodes(n: number): Promise<Episode[]>;
+    /**
+     * Get database statistics
+     */
+    getStats(): {
+        episodeCount: number;
+        trajectoryCount: number;
+        dimensions: number;
+        maxEpisodes: number;
+        vectorDbAvailable: boolean;
+    };
+    /**
+     * Clear all data
+     */
+    clear(): void;
+    /**
+     * Generate a unique ID
+     */
+    private generateId;
+}
+/**
+ * Create a fast AgentDB instance
+ */
+export declare function createFastAgentDB(dimensions?: number, maxEpisodes?: number): FastAgentDB;
+/**
+ * Get the default FastAgentDB instance
+ */
+export declare function getDefaultAgentDB(): FastAgentDB;
+declare const _default: {
+    FastAgentDB: typeof FastAgentDB;
+    createFastAgentDB: typeof createFastAgentDB;
+    getDefaultAgentDB: typeof getDefaultAgentDB;
+};
+export default _default;
+//# sourceMappingURL=agentdb-fast.d.ts.map

package/dist/core/agentdb-fast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentdb-fast.d.ts","sourceRoot":"","sources":["../../src/core/agentdb-fast.ts"],"names":[],"mappings":"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"}

package/dist/core/agentdb-fast.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * AgentDB Fast - High-performance in-process alternative to AgentDB CLI
+ *
+ * The AgentDB CLI has ~2.3s startup overhead due to npx initialization.
+ * This module provides 50-200x faster operations by using in-process calls.
+ *
+ * Features:
+ * - In-memory episode storage with LRU eviction
+ * - Vector similarity search using @ruvector/core
+ * - Compatible API with AgentDB's episode/trajectory interfaces
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FastAgentDB = void 0;
+exports.createFastAgentDB = createFastAgentDB;
+exports.getDefaultAgentDB = getDefaultAgentDB;
+// Lazy load ruvector core
+let coreModule = null;
+function getCoreModule() {
+    if (coreModule)
+        return coreModule;
+    try {
+        coreModule = require('@ruvector/core');
+        return coreModule;
+    }
+    catch {
+        // Fallback to ruvector if core not available
+        try {
+            coreModule = require('ruvector');
+            return coreModule;
+        }
+        catch (e) {
+            throw new Error(`Neither @ruvector/core nor ruvector is available: ${e.message}`);
+        }
+    }
+}
+/**
+ * Fast in-memory AgentDB implementation
+ */
+class FastAgentDB {
+    /**
+     * Create a new FastAgentDB instance
+     *
+     * @param dimensions - Vector dimensions for state embeddings
+     * @param maxEpisodes - Maximum episodes to store (LRU eviction)
+     */
+    constructor(dimensions = 128, maxEpisodes = 100000) {
+        this.episodes = new Map();
+        this.trajectories = new Map();
+        this.vectorDb = null;
+        this.episodeOrder = []; // For LRU eviction
+        this.dimensions = dimensions;
+        this.maxEpisodes = maxEpisodes;
+    }
+    /**
+     * Initialize the vector database
+     */
+    async initVectorDb() {
+        if (this.vectorDb)
+            return;
+        try {
+            const core = getCoreModule();
+            this.vectorDb = new core.VectorDB({
+                dimensions: this.dimensions,
+                distanceMetric: 'Cosine',
+            });
+        }
+        catch (e) {
+            // Vector DB not available, use fallback similarity
+            console.warn(`VectorDB not available, using fallback similarity: ${e.message}`);
+        }
+    }
+    /**
+     * Store an episode
+     *
+     * @param episode - Episode to store
+     * @returns Episode ID
+     */
+    async storeEpisode(episode) {
+        await this.initVectorDb();
+        const id = episode.id ?? this.generateId();
+        const fullEpisode = {
+            ...episode,
+            id,
+            timestamp: episode.timestamp ?? Date.now(),
+        };
+        // LRU eviction if needed
+        if (this.episodes.size >= this.maxEpisodes) {
+            const oldestId = this.episodeOrder.shift();
+            if (oldestId) {
+                this.episodes.delete(oldestId);
+            }
+        }
+        this.episodes.set(id, fullEpisode);
+        this.episodeOrder.push(id);
+        // Index in vector DB if available
+        if (this.vectorDb && fullEpisode.state.length === this.dimensions) {
+            try {
+                await this.vectorDb.insert({
+                    id,
+                    vector: new Float32Array(fullEpisode.state),
+                });
+            }
+            catch {
+                // Ignore indexing errors
+            }
+        }
+        return id;
+    }
+    /**
+     * Store multiple episodes in batch
+     */
+    async storeEpisodes(episodes) {
+        const ids = [];
+        for (const episode of episodes) {
+            const id = await this.storeEpisode(episode);
+            ids.push(id);
+        }
+        return ids;
+    }
+    /**
+     * Retrieve an episode by ID
+     */
+    async getEpisode(id) {
+        const episode = this.episodes.get(id);
+        if (episode) {
+            // Update LRU order
+            const idx = this.episodeOrder.indexOf(id);
+            if (idx > -1) {
+                this.episodeOrder.splice(idx, 1);
+                this.episodeOrder.push(id);
+            }
+        }
+        return episode ?? null;
+    }
+    /**
+     * Search for similar episodes by state
+     *
+     * @param queryState - State vector to search for
+     * @param k - Number of results to return
+     * @returns Similar episodes sorted by similarity
+     */
+    async searchByState(queryState, k = 10) {
+        await this.initVectorDb();
+        const query = Array.isArray(queryState) ? queryState : Array.from(queryState);
+        // Use vector DB if available
+        if (this.vectorDb && query.length === this.dimensions) {
+            try {
+                const results = await this.vectorDb.search({
+                    vector: new Float32Array(query),
+                    k,
+                });
+                return results
+                    .map((r) => {
+                    const episode = this.episodes.get(r.id);
+                    if (!episode)
+                        return null;
+                    return {
+                        episode,
+                        similarity: 1 - r.score, // Convert distance to similarity
+                    };
+                })
+                    .filter((r) => r !== null);
+            }
+            catch {
+                // Fall through to fallback
+            }
+        }
+        // Fallback: brute-force cosine similarity
+        return this.fallbackSearch(query, k);
+    }
+    /**
+     * Fallback similarity search using brute-force cosine similarity
+     */
+    fallbackSearch(query, k) {
+        const results = [];
+        for (const episode of this.episodes.values()) {
+            if (episode.state.length !== query.length)
+                continue;
+            const similarity = this.cosineSimilarity(query, episode.state);
+            results.push({ episode, similarity });
+        }
+        return results
+            .sort((a, b) => b.similarity - a.similarity)
+            .slice(0, k);
+    }
+    /**
+     * Compute cosine similarity between two vectors
+     */
+    cosineSimilarity(a, b) {
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        const denom = Math.sqrt(normA) * Math.sqrt(normB);
+        return denom === 0 ? 0 : dotProduct / denom;
+    }
+    /**
+     * Store a trajectory (sequence of episodes)
+     */
+    async storeTrajectory(episodes, metadata) {
+        const trajectoryId = this.generateId();
+        const storedEpisodes = [];
+        let totalReward = 0;
+        for (const episode of episodes) {
+            const id = await this.storeEpisode(episode);
+            const stored = await this.getEpisode(id);
+            if (stored) {
+                storedEpisodes.push(stored);
+                totalReward += stored.reward;
+            }
+        }
+        const trajectory = {
+            id: trajectoryId,
+            episodes: storedEpisodes,
+            totalReward,
+            metadata,
+        };
+        this.trajectories.set(trajectoryId, trajectory);
+        return trajectoryId;
+    }
+    /**
+     * Get a trajectory by ID
+     */
+    async getTrajectory(id) {
+        return this.trajectories.get(id) ?? null;
+    }
+    /**
+     * Get top trajectories by total reward
+     */
+    async getTopTrajectories(k = 10) {
+        return Array.from(this.trajectories.values())
+            .sort((a, b) => b.totalReward - a.totalReward)
+            .slice(0, k);
+    }
+    /**
+     * Sample random episodes (for experience replay)
+     */
+    async sampleEpisodes(n) {
+        const allEpisodes = Array.from(this.episodes.values());
+        const sampled = [];
+        for (let i = 0; i < Math.min(n, allEpisodes.length); i++) {
+            const idx = Math.floor(Math.random() * allEpisodes.length);
+            sampled.push(allEpisodes[idx]);
+        }
+        return sampled;
+    }
+    /**
+     * Get database statistics
+     */
+    getStats() {
+        return {
+            episodeCount: this.episodes.size,
+            trajectoryCount: this.trajectories.size,
+            dimensions: this.dimensions,
+            maxEpisodes: this.maxEpisodes,
+            vectorDbAvailable: this.vectorDb !== null,
+        };
+    }
+    /**
+     * Clear all data
+     */
+    clear() {
+        this.episodes.clear();
+        this.trajectories.clear();
+        this.episodeOrder = [];
+    }
+    /**
+     * Generate a unique ID
+     */
+    generateId() {
+        return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+}
+exports.FastAgentDB = FastAgentDB;
+/**
+ * Create a fast AgentDB instance
+ */
+function createFastAgentDB(dimensions = 128, maxEpisodes = 100000) {
+    return new FastAgentDB(dimensions, maxEpisodes);
+}
+// Singleton instance for convenience
+let defaultInstance = null;
+/**
+ * Get the default FastAgentDB instance
+ */
+function getDefaultAgentDB() {
+    if (!defaultInstance) {
+        defaultInstance = new FastAgentDB();
+    }
+    return defaultInstance;
+}
+exports.default = {
+    FastAgentDB,
+    createFastAgentDB,
+    getDefaultAgentDB,
+};