ruvector 0.1.35 → 0.1.37

package/README.md

@@ -1,1739 +1,627 @@
-# ruvector
+# RuVector
 
-[![npm version](https://badge.fury.io/js/ruvector.svg)](https://www.npmjs.com/package/ruvector)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Node Version](https://img.shields.io/node/v/ruvector)](https://nodejs.org)
-[![Downloads](https://img.shields.io/npm/dm/ruvector)](https://www.npmjs.com/package/ruvector)
-[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/ruvnet/ruvector)
-[![Performance](https://img.shields.io/badge/latency-<0.5ms-green.svg)](https://github.com/ruvnet/ruvector)
-[![GitHub Stars](https://img.shields.io/github/stars/ruvnet/ruvector?style=social)](https://github.com/ruvnet/ruvector)
-
-**The fastest vector database for Node.js—built in Rust, runs everywhere**
-
-Ruvector is a next-generation vector database that brings **enterprise-grade semantic search** to Node.js applications. Unlike cloud-only solutions or Python-first databases, Ruvector is designed specifically for JavaScript/TypeScript developers who need **blazing-fast vector similarity search** without the complexity of external services.
-
-> 🚀 **Sub-millisecond queries** • 🎯 **52,000+ inserts/sec** • 💾 **~50 bytes per vector** • 🌍 **Runs anywhere**
-
-Built by [rUv](https://ruv.io) with production-grade Rust performance and intelligent platform detection—**automatically uses native bindings when available, falls back to WebAssembly when needed**.
-
-🌐 **[Visit ruv.io](https://ruv.io)** | 📦 **[GitHub](https://github.com/ruvnet/ruvector)** | 📚 **[Documentation](https://github.com/ruvnet/ruvector/tree/main/docs)**
-
----
-
-## 🌟 Why Ruvector?
-
-### The Problem with Existing Vector Databases
-
-Most vector databases force you to choose between three painful trade-offs:
-
-1. **Cloud-Only Services** (Pinecone, Weaviate Cloud) - Expensive, vendor lock-in, latency issues, API rate limits
-2. **Python-First Solutions** (ChromaDB, Faiss) - Poor Node.js support, require separate Python processes
-3. **Self-Hosted Complexity** (Milvus, Qdrant) - Heavy infrastructure, Docker orchestration, operational overhead
-
-**Ruvector eliminates these trade-offs.**
-
-### The Ruvector Advantage
-
-Ruvector is purpose-built for **modern JavaScript/TypeScript applications** that need vector search:
-
-🎯 **Native Node.js Integration**
-- Drop-in npm package—no Docker, no Python, no external services
-- Full TypeScript support with complete type definitions
-- Automatic platform detection with native Rust bindings
-- Seamless WebAssembly fallback for universal compatibility
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![npm](https://img.shields.io/npm/v/ruvector.svg)](https://www.npmjs.com/package/ruvector)
+[![npm downloads](https://img.shields.io/npm/dm/ruvector.svg)](https://www.npmjs.com/package/ruvector)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-16+-green.svg)](https://nodejs.org/)
 
-⚡ **Production-Grade Performance**
-- **52,000+ inserts/second** with native Rust (10x faster than Python alternatives)
-- **<0.5ms query latency** with HNSW indexing and SIMD optimizations
-- **~50 bytes per vector** with advanced memory optimization
-- Scales from edge devices to millions of vectors
+**A distributed vector database that learns.** Store embeddings, query with Cypher, scale horizontally, and let the index improve itself through Graph Neural Networks.
 
-🧠 **Built for AI Applications**
-- Optimized for LLM embeddings (OpenAI, Cohere, Hugging Face)
-- Perfect for RAG (Retrieval-Augmented Generation) systems
-- Agent memory and semantic caching
-- Real-time recommendation engines
+```bash
+npx ruvector
+```
 
-🌍 **Universal Deployment**
-- **Linux, macOS, Windows** with native performance
-- **Browser support** via WebAssembly (experimental)
-- **Edge computing** and serverless environments
-- **Alpine Linux** and non-glibc systems supported
+> **All-in-One Package**: The `ruvector` package includes everything — vector search, graph queries, GNN layers, AI agent routing, and WASM support. No additional packages needed.
 
-💰 **Zero Operational Costs**
-- No cloud API fees or usage limits
-- No infrastructure to manage
-- No separate database servers
-- Open source MIT license
+## Why RuVector?
 
-### Key Advantages
+Traditional vector databases just store and search. When you ask "find similar items," they return results but never get smarter. They can't handle complex relationships. They don't optimize your AI costs.
 
-- ⚡ **Blazing Fast**: <0.5ms p50 latency with native Rust, 10-50ms with WASM fallback
-- 🎯 **Automatic Platform Detection**: Uses native when available, falls back to WASM seamlessly
-- 🧠 **AI-Native**: Built specifically for embeddings, RAG, semantic search, and agent memory
-- 🔧 **CLI Tools Included**: Full command-line interface for database management
-- 🌍 **Universal Deployment**: Works on all platforms—Linux, macOS, Windows, even browsers
-- 💾 **Memory Efficient**: ~50 bytes per vector with advanced quantization
-- 🚀 **Production Ready**: Battle-tested algorithms with comprehensive benchmarks
-- 🔓 **Open Source**: MIT licensed, community-driven
+**RuVector is built for the agentic AI era:**
 
-## 🚀 Quick Start Tutorial
+| Challenge | RuVector Solution |
+|-----------|-------------------|
+| RAG retrieval quality plateaus | **Self-learning GNN** improves results over time |
+| Knowledge graphs need separate DB | **Cypher queries** built-in (Neo4j syntax) |
+| LLM costs spiral out of control | **AI Router** sends simple queries to cheaper models |
+| Memory usage explodes at scale | **Adaptive compression** (2-32x reduction) |
+| Can't run AI in the browser | **Full WASM support** for client-side inference |
 
-### Step 1: Installation
+## Quick Start
 
-Install Ruvector with a single npm command:
+### Installation
 
 ```bash
+# Install the package
 npm install ruvector
-```
 
-**What happens during installation:**
-- npm automatically detects your platform (Linux, macOS, Windows)
-- Downloads the correct native binary for maximum performance
-- Falls back to WebAssembly if native binaries aren't available
-- No additional setup, Docker, or external services required
-
-**Verify installation:**
-```bash
-npx ruvector info
-```
+# Or try instantly without installing
+npx ruvector
 
-You should see your platform and implementation type (native Rust or WASM fallback).
+# With yarn
+yarn add ruvector
 
-### Step 2: Your First Vector Database
+# With pnpm
+pnpm add ruvector
+```
 
-Let's create a simple vector database and perform basic operations. This example demonstrates the complete CRUD (Create, Read, Update, Delete) workflow:
+### Basic Vector Search
 
 ```javascript
-const { VectorDb } = require('ruvector');
-
-async function tutorial() {
-  // Step 2.1: Create a new vector database
-  // The 'dimensions' parameter must match your embedding model
-  // Common sizes: 128, 384 (sentence-transformers), 768 (BERT), 1536 (OpenAI)
-  const db = new VectorDb({
-    dimensions: 128,           // Vector size - MUST match your embeddings
-    maxElements: 10000,        // Maximum vectors (can grow automatically)
-    storagePath: './my-vectors.db'  // Persist to disk (omit for in-memory)
-  });
-
-  console.log('✅ Database created successfully');
-
-  // Step 2.2: Insert vectors
-  // In real applications, these would come from an embedding model
-  const documents = [
-    { id: 'doc1', text: 'Artificial intelligence and machine learning' },
-    { id: 'doc2', text: 'Deep learning neural networks' },
-    { id: 'doc3', text: 'Natural language processing' },
-  ];
-
-  for (const doc of documents) {
-    // Generate random vector for demonstration
-    // In production: use OpenAI, Cohere, or sentence-transformers
-    const vector = new Float32Array(128).map(() => Math.random());
-
-    await db.insert({
-      id: doc.id,
-      vector: vector,
-      metadata: {
-        text: doc.text,
-        timestamp: Date.now(),
-        category: 'AI'
-      }
-    });
-
-    console.log(`✅ Inserted: ${doc.id}`);
-  }
+const { VectorDB } = require('ruvector');
 
-  // Step 2.3: Search for similar vectors
-  // Create a query vector (in production, this would be from your search query)
-  const queryVector = new Float32Array(128).map(() => Math.random());
+// Create a vector database (384 = OpenAI ada-002 dimensions)
+const db = new VectorDB(384);
 
-  const results = await db.search({
-    vector: queryVector,
-    k: 5,              // Return top 5 most similar vectors
-    threshold: 0.7     // Only return results with similarity > 0.7
-  });
-
-  console.log('\n🔍 Search Results:');
-  results.forEach((result, index) => {
-    console.log(`${index + 1}. ${result.id} - Score: ${result.score.toFixed(3)}`);
-    console.log(`   Text: ${result.metadata.text}`);
-  });
-
-  // Step 2.4: Retrieve a specific vector
-  const retrieved = await db.get('doc1');
-  if (retrieved) {
-    console.log('\n📄 Retrieved document:', retrieved.metadata.text);
-  }
-
-  // Step 2.5: Get database statistics
-  const count = await db.len();
-  console.log(`\n📊 Total vectors in database: ${count}`);
-
-  // Step 2.6: Delete a vector
-  const deleted = await db.delete('doc1');
-  console.log(`\n🗑️  Deleted doc1: ${deleted ? 'Success' : 'Not found'}`);
-
-  // Final count
-  const finalCount = await db.len();
-  console.log(`📊 Final count: ${finalCount}`);
-}
+// Insert vectors with metadata
+await db.insert('doc1', embedding1, {
+  title: 'Introduction to AI',
+  category: 'tech',
+  date: '2024-01-15'
+});
 
-// Run the tutorial
-tutorial().catch(console.error);
-```
+// Semantic search
+const results = await db.search(queryEmbedding, 10);
 
-**Expected Output:**
+// Filter by metadata
+const filtered = await db.search(queryEmbedding, 10, {
+  category: 'tech',
+  date: { $gte: '2024-01-01' }
+});
 ```
-✅ Database created successfully
-✅ Inserted: doc1
-✅ Inserted: doc2
-✅ Inserted: doc3
-
-🔍 Search Results:
-1. doc2 - Score: 0.892
-   Text: Deep learning neural networks
-2. doc1 - Score: 0.856
-   Text: Artificial intelligence and machine learning
-3. doc3 - Score: 0.801
-   Text: Natural language processing
-
-📄 Retrieved document: Artificial intelligence and machine learning
-
-📊 Total vectors in database: 3
 
-🗑️  Deleted doc1: Success
-📊 Final count: 2
-```
+### RAG (Retrieval-Augmented Generation)
 
-### Step 3: TypeScript Tutorial
+```javascript
+const { VectorDB } = require('ruvector');
+const OpenAI = require('openai');
 
-Ruvector provides full TypeScript support with complete type safety. Here's how to use it:
+const db = new VectorDB(1536); // text-embedding-3-small dimensions
+const openai = new OpenAI();
 
-```typescript
-import { VectorDb, VectorEntry, SearchQuery, SearchResult } from 'ruvector';
-
-// Step 3.1: Define your custom metadata type
-interface DocumentMetadata {
-  title: string;
-  content: string;
-  author: string;
-  date: Date;
-  tags: string[];
+// Index your documents
+async function indexDocument(doc) {
+  const embedding = await openai.embeddings.create({
+    model: 'text-embedding-3-small',
+    input: doc.content
+  });
+  await db.insert(doc.id, embedding.data[0].embedding, {
+    title: doc.title,
+    content: doc.content
+  });
 }
 
-async function typescriptTutorial() {
-  // Step 3.2: Create typed database
-  const db = new VectorDb({
-    dimensions: 384,  // sentence-transformers/all-MiniLM-L6-v2
-    maxElements: 10000,
-    storagePath: './typed-vectors.db'
+// RAG query
+async function ragQuery(question) {
+  // 1. Embed the question
+  const questionEmb = await openai.embeddings.create({
+    model: 'text-embedding-3-small',
+    input: question
   });
 
-  // Step 3.3: Type-safe vector entry
-  const entry: VectorEntry<DocumentMetadata> = {
-    id: 'article-001',
-    vector: new Float32Array(384),  // Your embedding here
-    metadata: {
-      title: 'Introduction to Vector Databases',
-      content: 'Vector databases enable semantic search...',
-      author: 'Jane Doe',
-      date: new Date('2024-01-15'),
-      tags: ['database', 'AI', 'search']
-    }
-  };
-
-  // Step 3.4: Insert with type checking
-  await db.insert(entry);
-  console.log('✅ Inserted typed document');
+  // 2. Retrieve relevant context
+  const context = await db.search(questionEmb.data[0].embedding, 5);
 
-  // Step 3.5: Type-safe search
-  const query: SearchQuery = {
-    vector: new Float32Array(384),
-    k: 10,
-    threshold: 0.8
-  };
+  // 3. Generate answer with context
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4-turbo',
+    messages: [{
+      role: 'user',
+      content: `Context:\n${context.map(c => c.metadata.content).join('\n\n')}
 
-  // Step 3.6: Fully typed results
-  const results: SearchResult<DocumentMetadata>[] = await db.search(query);
-
-  // TypeScript knows the exact shape of metadata
-  results.forEach(result => {
-    console.log(`Title: ${result.metadata.title}`);
-    console.log(`Author: ${result.metadata.author}`);
-    console.log(`Tags: ${result.metadata.tags.join(', ')}`);
-    console.log(`Similarity: ${result.score.toFixed(3)}\n`);
+Question: ${question}
+Answer based only on the context above:`
+    }]
   });
 
-  // Step 3.7: Type-safe retrieval
-  const doc = await db.get('article-001');
-  if (doc) {
-    // TypeScript autocomplete works perfectly here
-    const publishYear = doc.metadata.date.getFullYear();
-    console.log(`Published in ${publishYear}`);
-  }
+  return response.choices[0].message.content;
 }
-
-typescriptTutorial().catch(console.error);
 ```
 
-**TypeScript Benefits:**
-- ✅ Full autocomplete for all methods and properties
-- ✅ Compile-time type checking prevents errors
-- ✅ IDE IntelliSense shows documentation
-- ✅ Custom metadata types for your use case
-- ✅ No `any` types - fully typed throughout
-
-## 🎯 Platform Detection
-
-Ruvector automatically detects the best implementation for your platform:
+### Knowledge Graphs (Cypher)
 
 ```javascript
-const { getImplementationType, isNative, isWasm } = require('ruvector');
-
-console.log(getImplementationType()); // 'native' or 'wasm'
-console.log(isNative()); // true if using native Rust
-console.log(isWasm()); // true if using WebAssembly fallback
-
-// Performance varies by implementation:
-// Native (Rust):  <0.5ms latency, 50K+ ops/sec
-// WASM fallback:  10-50ms latency, ~1K ops/sec
-```
-
-## 🔧 CLI Tools
-
-Ruvector includes a full command-line interface for database management:
-
-### Create Database
+const { GraphDB } = require('ruvector');
+
+const graph = new GraphDB();
+
+// Create entities and relationships
+graph.execute(`
+  CREATE (alice:Person {name: 'Alice', role: 'Engineer'})
+  CREATE (bob:Person {name: 'Bob', role: 'Manager'})
+  CREATE (techcorp:Company {name: 'TechCorp', industry: 'AI'})
+  CREATE (alice)-[:WORKS_AT {since: 2022}]->(techcorp)
+  CREATE (bob)-[:WORKS_AT {since: 2020}]->(techcorp)
+  CREATE (alice)-[:REPORTS_TO]->(bob)
+`);
+
+// Query relationships
+const team = graph.execute(`
+  MATCH (p:Person)-[:WORKS_AT]->(c:Company {name: 'TechCorp'})
+  RETURN p.name, p.role
+`);
+
+// Find paths
+const chain = graph.execute(`
+  MATCH path = (a:Person {name: 'Alice'})-[:REPORTS_TO*1..3]->(manager)
+  RETURN path
+`);
+
+// Combine with vector search
+const similarPeople = graph.execute(`
+  MATCH (p:Person)
+  WHERE vector.similarity(p.embedding, $queryEmbedding) > 0.8
+  RETURN p ORDER BY vector.similarity(p.embedding, $queryEmbedding) DESC
+  LIMIT 10
+`);
+```
+
+### GNN-Enhanced Search (Self-Learning)
 
-```bash
-# Create a new vector database
-npx ruvector create mydb.vec --dimensions 384 --metric cosine
-
-# Options:
-#   --dimensions, -d  Vector dimensionality (required)
-#   --metric, -m      Distance metric (cosine, euclidean, dot)
-#   --max-elements    Maximum number of vectors (default: 10000)
-```
-
-### Insert Vectors
-
-```bash
-# Insert vectors from JSON file
-npx ruvector insert mydb.vec vectors.json
-
-# JSON format:
-# [
-#   { "id": "doc1", "vector": [0.1, 0.2, ...], "metadata": {...} },
-#   { "id": "doc2", "vector": [0.3, 0.4, ...], "metadata": {...} }
-# ]
-```
-
-### Search Vectors
-
-```bash
-# Search for similar vectors
-npx ruvector search mydb.vec --vector "[0.1,0.2,0.3,...]" --top-k 10
-
-# Options:
-#   --vector, -v   Query vector (JSON array)
-#   --top-k, -k    Number of results (default: 10)
-#   --threshold    Minimum similarity score
-```
-
-### Database Statistics
-
-```bash
-# Show database statistics
-npx ruvector stats mydb.vec
-
-# Output:
-#   Total vectors: 10,000
-#   Dimensions: 384
-#   Metric: cosine
-#   Memory usage: ~500 KB
-#   Index type: HNSW
-```
-
-### Benchmarking
-
-```bash
-# Run performance benchmark
-npx ruvector benchmark --num-vectors 10000 --num-queries 1000
-
-# Options:
-#   --num-vectors   Number of vectors to insert
-#   --num-queries   Number of search queries
-#   --dimensions    Vector dimensionality (default: 128)
-```
+```javascript
+const { GNNLayer, VectorDB } = require('ruvector');
 
-### System Information
+// Create GNN layer for query enhancement
+const gnn = new GNNLayer(384, 512, 4); // input_dim, output_dim, num_heads
 
-```bash
-# Show platform and implementation info
-npx ruvector info
+// The GNN learns from your search patterns
+async function enhancedSearch(query) {
+  // Get initial results
+  const neighbors = await db.search(query, 20);
 
-# Output:
-#   Platform: linux-x64-gnu
-#   Implementation: native (Rust)
-#   GNN Module: Available
-#   Node.js: v18.17.0
-#   Performance: <0.5ms p50 latency
-```
+  // Compute attention weights based on user clicks/relevance
+  const weights = computeRelevanceWeights(neighbors);
 
-### Install Optional Packages
+  // GNN enhances the query using graph structure
+  const enhancedQuery = gnn.forward(query,
+    neighbors.map(n => n.embedding),
+    weights
+  );
 
-Ruvector supports optional packages that extend functionality. Use the `install` command to add them:
+  // Re-rank with enhanced understanding
+  return db.search(enhancedQuery, 10);
+}
 
-```bash
-# List available packages
-npx ruvector install
-
-# Output:
-#   Available Ruvector Packages:
-#
-#     gnn      not installed
-#              Graph Neural Network layers, tensor compression, differentiable search
-#              npm: @ruvector/gnn
-#
-#     core     ✓ installed
-#              Core vector database with native Rust bindings
-#              npm: @ruvector/core
-
-# Install specific package
-npx ruvector install gnn
-
-# Install all optional packages
-npx ruvector install --all
-
-# Interactive selection
-npx ruvector install -i
+// Train on user feedback
+gnn.train({
+  queries: historicalQueries,
+  clicks: userClickData,
+  relevance: expertLabels
+}, { epochs: 100 });
 ```
 
-The install command auto-detects your package manager (npm, yarn, pnpm, bun).
+### AI Agent Routing (Tiny Dancer)
 
-### GNN Commands
+Route queries to the optimal LLM based on complexity — save 60-80% on API costs:
 
-Ruvector includes Graph Neural Network (GNN) capabilities for advanced tensor compression and differentiable search.
+```javascript
+const { Router } = require('ruvector');
 
-#### GNN Info
+const router = new Router({
+  confidenceThreshold: 0.85,
+  maxUncertainty: 0.15,
+  enableCircuitBreaker: true
+});
 
-```bash
-# Show GNN module information
-npx ruvector gnn info
-
-# Output:
-#   GNN Module Information
-#     Status:         Available
-#     Platform:       linux
-#     Architecture:   x64
-#
-#   Available Features:
-#     • RuvectorLayer   - GNN layer with multi-head attention
-#     • TensorCompress  - Adaptive tensor compression (5 levels)
-#     • differentiableSearch - Soft attention-based search
-#     • hierarchicalForward  - Multi-layer GNN processing
-```
+// Define your model candidates
+const models = [
+  { id: 'gpt-4-turbo', embedding: gpt4Emb, cost: 0.03, quality: 0.95 },
+  { id: 'gpt-3.5-turbo', embedding: gpt35Emb, cost: 0.002, quality: 0.80 },
+  { id: 'claude-3-haiku', embedding: haikuEmb, cost: 0.001, quality: 0.75 },
+  { id: 'llama-3-8b', embedding: llamaEmb, cost: 0.0005, quality: 0.70 }
+];
 
-#### GNN Layer
+async function smartComplete(prompt) {
+  const promptEmb = await embed(prompt);
 
-```bash
-# Create and test a GNN layer
-npx ruvector gnn layer -i 128 -h 256 --test
-
-# Options:
-#   -i, --input-dim   Input dimension (required)
-#   -h, --hidden-dim  Hidden dimension (required)
-#   -a, --heads       Number of attention heads (default: 4)
-#   -d, --dropout     Dropout rate (default: 0.1)
-#   --test            Run a test forward pass
-#   -o, --output      Save layer config to JSON file
-```
+  // Router decides optimal model
+  const decision = router.route(promptEmb, models);
 
-#### GNN Compress
+  console.log(`Routing to ${decision.candidateId} (confidence: ${decision.confidence})`);
+  // Output: "Routing to gpt-3.5-turbo (confidence: 0.92)"
 
-```bash
-# Compress embeddings using adaptive tensor compression
-npx ruvector gnn compress -f embeddings.json -l pq8 -o compressed.json
-
-# Options:
-#   -f, --file         Input JSON file with embeddings (required)
-#   -l, --level        Compression level: none|half|pq8|pq4|binary (default: auto)
-#   -a, --access-freq  Access frequency for auto compression (default: 0.5)
-#   -o, --output       Output file for compressed data
-
-# Compression levels:
-#   none   (freq > 0.8)  - Full precision, hot data
-#   half   (freq > 0.4)  - ~50% savings, warm data
-#   pq8    (freq > 0.1)  - ~8x compression, cool data
-#   pq4    (freq > 0.01) - ~16x compression, cold data
-#   binary (freq <= 0.01) - ~32x compression, archive
+  // Call the selected model
+  return callModel(decision.candidateId, prompt);
+}
 ```
 
-#### GNN Search
+### Compression (2-32x Memory Savings)
 
-```bash
-# Differentiable search with soft attention
-npx ruvector gnn search -q "[1.0,0.0,0.0]" -c candidates.json -k 5
-
-# Options:
-#   -q, --query        Query vector as JSON array (required)
-#   -c, --candidates   Candidates file - JSON array of vectors (required)
-#   -k, --top-k        Number of results (default: 5)
-#   -t, --temperature  Softmax temperature (default: 1.0)
+```javascript
+const { compress, decompress, CompressionTier } = require('ruvector');
+
+// Automatic tier selection
+const auto = compress(embedding, 0.3); // 30% quality threshold
+
+// Explicit tiers
+const f16 = compress(embedding, CompressionTier.F16);     // 2x compression
+const pq8 = compress(embedding, CompressionTier.PQ8);     // 8x compression
+const pq4 = compress(embedding, CompressionTier.PQ4);     // 16x compression
+const binary = compress(embedding, CompressionTier.Binary); // 32x compression
+
+// Adaptive tiering based on access frequency
+db.enableAdaptiveCompression({
+  hotThreshold: 0.8,    // Keep hot data in f32
+  warmThreshold: 0.4,   // Compress to f16
+  coldThreshold: 0.1,   // Compress to PQ8
+  archiveThreshold: 0.01 // Compress to binary
+});
 ```
 
-### Attention Commands
-
-Ruvector includes high-performance attention mechanisms for transformer-based operations, hyperbolic embeddings, and graph attention.
+## CLI Usage
 
 ```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
+# Show system info and backend status
+npx ruvector 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
-```
+# Initialize a new index
+npx ruvector init my-index --dimension 384 --type hnsw
 
-#### Attention List
+# Insert vectors from JSON/JSONL
+npx ruvector insert my-index vectors.json
+npx ruvector insert my-index vectors.jsonl --format jsonl
 
-```bash
-# List all available attention mechanisms
-npx ruvector attention list
+# Search with a query
+npx ruvector search my-index --query "[0.1, 0.2, ...]" -k 10
+npx ruvector search my-index --text "machine learning" -k 10  # Auto-embed
 
-# With verbose details
-npx ruvector attention list -v
-```
+# Show index statistics
+npx ruvector stats my-index
 
-#### Attention Benchmark
+# Run performance benchmarks
+npx ruvector benchmark --dimension 384 --num-vectors 10000
 
-```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)
+# Export/import
+npx ruvector export my-index backup.bin
+npx ruvector import backup.bin restored-index
 ```
 
-#### 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]"
+## Integrations
 
-# Project vector to Poincaré ball
-npx ruvector attention hyperbolic -a project -v "[1.5,2.0,0.8]"
+### LangChain
 
-# Möbius addition in hyperbolic space
-npx ruvector attention hyperbolic -a mobius-add -v "[0.1,0.2]" -b "[0.3,0.4]"
+```javascript
+const { RuVectorStore } = require('ruvector/langchain');
+const { OpenAIEmbeddings } = require('@langchain/openai');
 
-# Exponential map (tangent space → Poincaré ball)
-npx ruvector attention hyperbolic -a exp-map -v "[0.1,0.2,0.3]"
+const vectorStore = new RuVectorStore(
+  new OpenAIEmbeddings(),
+  { dimension: 1536 }
+);
 
-# 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)
+await vectorStore.addDocuments(documents);
+const results = await vectorStore.similaritySearch("query", 5);
 ```
 
-#### 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:
-
-### Native Performance (Rust)
-
-| Operation | Throughput | Latency (p50) | Latency (p99) |
-|-----------|------------|---------------|---------------|
-| Insert    | 52,341 ops/sec | 0.019 ms | 0.045 ms |
-| Search (k=10) | 11,234 ops/sec | 0.089 ms | 0.156 ms |
-| Search (k=100) | 8,932 ops/sec | 0.112 ms | 0.203 ms |
-| Delete    | 45,678 ops/sec | 0.022 ms | 0.051 ms |
-
-**Memory Usage**: ~50 bytes per 128-dim vector (including index)
-
-### Comparison with Alternatives
-
-| Database | Insert (ops/sec) | Search (ops/sec) | Memory per Vector | Node.js | Browser |
-|----------|------------------|------------------|-------------------|---------|---------|
-| **Ruvector (Native)** | **52,341** | **11,234** | **50 bytes** | ✅ | ❌ |
-| **Ruvector (WASM)** | **~1,000** | **~100** | **50 bytes** | ✅ | ✅ |
-| Faiss (HNSW) | 38,200 | 9,800 | 68 bytes | ❌ | ❌ |
-| Hnswlib | 41,500 | 10,200 | 62 bytes | ✅ | ❌ |
-| ChromaDB | ~1,000 | ~20 | 150 bytes | ✅ | ❌ |
-
-*Benchmarks measured with 100K vectors, 128 dimensions, k=10*
-
-## 🔍 Comparison with Other Vector Databases
-
-Comprehensive comparison of Ruvector against popular vector database solutions:
-
-| Feature | Ruvector | Pinecone | Qdrant | Weaviate | Milvus | ChromaDB | Faiss |
-|---------|----------|----------|--------|----------|--------|----------|-------|
-| **Deployment** |
-| Installation | `npm install` ✅ | Cloud API ☁️ | Docker 🐳 | Docker 🐳 | Docker/K8s 🐳 | `pip install` 🐍 | `pip install` 🐍 |
-| Node.js Native | ✅ First-class | ❌ API only | ⚠️ HTTP API | ⚠️ HTTP API | ⚠️ HTTP API | ❌ Python | ❌ Python |
-| Setup Time | < 1 minute | 5-10 minutes | 10-30 minutes | 15-30 minutes | 30-60 minutes | 5 minutes | 5 minutes |
-| Infrastructure | None required | Managed cloud | Self-hosted | Self-hosted | Self-hosted | Embedded | Embedded |
-| **Performance** |
-| Query Latency (p50) | **<0.5ms** | ~2-5ms | ~1-2ms | ~2-3ms | ~3-5ms | ~50ms | ~1ms |
-| Insert Throughput | **52,341 ops/sec** | ~10,000 ops/sec | ~20,000 ops/sec | ~15,000 ops/sec | ~25,000 ops/sec | ~1,000 ops/sec | ~40,000 ops/sec |
-| Memory per Vector (128d) | **50 bytes** | ~80 bytes | 62 bytes | ~100 bytes | ~70 bytes | 150 bytes | 68 bytes |
-| Recall @ k=10 | 95%+ | 93% | 94% | 92% | 96% | 85% | 97% |
-| **Platform Support** |
-| Linux | ✅ Native | ☁️ API | ✅ Docker | ✅ Docker | ✅ Docker | ✅ Python | ✅ Python |
-| macOS | ✅ Native | ☁️ API | ✅ Docker | ✅ Docker | ✅ Docker | ✅ Python | ✅ Python |
-| Windows | ✅ Native | ☁️ API | ✅ Docker | ✅ Docker | ⚠️ WSL2 | ✅ Python | ✅ Python |
-| Browser/WASM | ✅ Yes | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |
-| ARM64 | ✅ Native | ☁️ API | ✅ Yes | ✅ Yes | ⚠️ Limited | ✅ Yes | ✅ Yes |
-| Alpine Linux | ✅ WASM | ☁️ API | ⚠️ Build from source | ⚠️ Build from source | ❌ No | ✅ Yes | ✅ Yes |
-| **Features** |
-| Distance Metrics | Cosine, L2, Dot | Cosine, L2, Dot | 11 metrics | 10 metrics | 8 metrics | L2, Cosine, IP | L2, IP, Cosine |
-| Filtering | ✅ Metadata | ✅ Advanced | ✅ Advanced | ✅ Advanced | ✅ Advanced | ✅ Basic | ❌ Limited |
-| Persistence | ✅ File-based | ☁️ Managed | ✅ Disk | ✅ Disk | ✅ Disk | ✅ DuckDB | ❌ Memory |
-| Indexing | HNSW | Proprietary | HNSW | HNSW | IVF/HNSW | HNSW | IVF/HNSW |
-| Quantization | ✅ PQ | ✅ Yes | ✅ Scalar | ✅ PQ | ✅ PQ/SQ | ❌ No | ✅ PQ |
-| Batch Operations | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
-| **Developer Experience** |
-| TypeScript Types | ✅ Full | ✅ Generated | ⚠️ Community | ⚠️ Community | ⚠️ Community | ⚠️ Partial | ❌ No |
-| Documentation | ✅ Excellent | ✅ Excellent | ✅ Good | ✅ Good | ✅ Good | ✅ Good | ⚠️ Technical |
-| Examples | ✅ Many | ✅ Many | ✅ Good | ✅ Good | ✅ Many | ✅ Good | ⚠️ Limited |
-| CLI Tools | ✅ Included | ⚠️ Limited | ✅ Yes | ✅ Yes | ✅ Yes | ⚠️ Basic | ❌ No |
-| **Operations** |
-| Monitoring | ✅ Metrics | ✅ Dashboard | ✅ Prometheus | ✅ Prometheus | ✅ Prometheus | ⚠️ Basic | ❌ No |
-| Backups | ✅ File copy | ☁️ Automatic | ✅ Snapshots | ✅ Snapshots | ✅ Snapshots | ✅ File copy | ❌ Manual |
-| High Availability | ⚠️ App-level | ✅ Built-in | ✅ Clustering | ✅ Clustering | ✅ Clustering | ❌ No | ❌ No |
-| Auto-Scaling | ⚠️ App-level | ✅ Automatic | ⚠️ Manual | ⚠️ Manual | ⚠️ K8s HPA | ❌ No | ❌ No |
-| **Cost** |
-| Pricing Model | Free (MIT) | Pay-per-use | Free (Apache) | Free (BSD) | Free (Apache) | Free (Apache) | Free (MIT) |
-| Monthly Cost (1M vectors) | **$0** | ~$70-200 | ~$20-50 (infra) | ~$30-60 (infra) | ~$50-100 (infra) | $0 | $0 |
-| Monthly Cost (10M vectors) | **$0** | ~$500-1000 | ~$100-200 (infra) | ~$150-300 (infra) | ~$200-400 (infra) | $0 | $0 |
-| API Rate Limits | None | Yes | None | None | None | None | None |
-| **Use Cases** |
-| RAG Systems | ✅ Excellent | ✅ Excellent | ✅ Excellent | ✅ Excellent | ✅ Excellent | ✅ Good | ⚠️ Limited |
-| Serverless | ✅ Perfect | ✅ Good | ❌ No | ❌ No | ❌ No | ⚠️ Possible | ⚠️ Possible |
-| Edge Computing | ✅ Excellent | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No | ⚠️ Possible |
-| Production Scale (100M+) | ⚠️ Single node | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Excellent | ⚠️ Limited | ⚠️ Manual |
-| Embedded Apps | ✅ Excellent | ❌ No | ❌ No | ❌ No | ❌ No | ⚠️ Possible | ✅ Good |
-
-### When to Choose Ruvector
-
-✅ **Perfect for:**
-- **Node.js/TypeScript applications** needing embedded vector search
-- **Serverless and edge computing** where external services aren't practical
-- **Rapid prototyping and development** with minimal setup time
-- **RAG systems** with LangChain, LlamaIndex, or custom implementations
-- **Cost-sensitive projects** that can't afford cloud API pricing
-- **Offline-first applications** requiring local vector search
-- **Browser-based AI** with WebAssembly fallback
-- **Small to medium scale** (up to 10M vectors per instance)
-
-⚠️ **Consider alternatives for:**
-- **Massive scale (100M+ vectors)** - Consider Pinecone, Milvus, or Qdrant clusters
-- **Multi-tenancy requirements** - Weaviate or Qdrant offer better isolation
-- **Distributed systems** - Milvus provides better horizontal scaling
-- **Zero-ops cloud solution** - Pinecone handles all infrastructure
-
-### Why Choose Ruvector Over...
-
-**vs Pinecone:**
-- ✅ No API costs (save $1000s/month)
-- ✅ No network latency (10x faster queries)
-- ✅ No vendor lock-in
-- ✅ Works offline and in restricted environments
-- ❌ No managed multi-region clusters
-
-**vs ChromaDB:**
-- ✅ 50x faster queries (native Rust vs Python)
-- ✅ True Node.js support (not HTTP API)
-- ✅ Better TypeScript integration
-- ✅ Lower memory usage
-- ❌ Smaller ecosystem and community
-
-**vs Qdrant:**
-- ✅ Zero infrastructure setup
-- ✅ Embedded in your app (no Docker)
-- ✅ Better for serverless environments
-- ✅ Native Node.js bindings
-- ❌ No built-in clustering or HA
-
-**vs Faiss:**
-- ✅ Full Node.js support (Faiss is Python-only)
-- ✅ Easier API and better developer experience
-- ✅ Built-in persistence and metadata
-- ⚠️ Slightly lower recall at same performance
-
-## 🎯 Real-World Tutorials
-
-### Tutorial 1: Building a RAG System with OpenAI
-
-**What you'll learn:** Create a production-ready Retrieval-Augmented Generation system that enhances LLM responses with relevant context from your documents.
-
-**Prerequisites:**
-```bash
-npm install ruvector openai
-export OPENAI_API_KEY="your-api-key-here"
-```
-
-**Complete Implementation:**
+### LlamaIndex
 
 ```javascript
-const { VectorDb } = require('ruvector');
-const OpenAI = require('openai');
-
-class RAGSystem {
-  constructor() {
-    // Initialize OpenAI client
-    this.openai = new OpenAI({
-      apiKey: process.env.OPENAI_API_KEY
-    });
-
-    // Create vector database for OpenAI embeddings
-    // text-embedding-ada-002 produces 1536-dimensional vectors
-    this.db = new VectorDb({
-      dimensions: 1536,
-      maxElements: 100000,
-      storagePath: './rag-knowledge-base.db'
-    });
-
-    console.log('✅ RAG System initialized');
-  }
-
-  // Step 1: Index your knowledge base
-  async indexDocuments(documents) {
-    console.log(`📚 Indexing ${documents.length} documents...`);
-
-    for (let i = 0; i < documents.length; i++) {
-      const doc = documents[i];
-
-      // Generate embedding for the document
-      const response = await this.openai.embeddings.create({
-        model: 'text-embedding-ada-002',
-        input: doc.content
-      });
-
-      // Store in vector database
-      await this.db.insert({
-        id: doc.id || `doc_${i}`,
-        vector: new Float32Array(response.data[0].embedding),
-        metadata: {
-          title: doc.title,
-          content: doc.content,
-          source: doc.source,
-          date: doc.date || new Date().toISOString()
-        }
-      });
-
-      console.log(`  ✅ Indexed: ${doc.title}`);
-    }
-
-    const count = await this.db.len();
-    console.log(`\n✅ Indexed ${count} documents total`);
-  }
-
-  // Step 2: Retrieve relevant context for a query
-  async retrieveContext(query, k = 3) {
-    console.log(`🔍 Searching for: "${query}"`);
-
-    // Generate embedding for the query
-    const response = await this.openai.embeddings.create({
-      model: 'text-embedding-ada-002',
-      input: query
-    });
-
-    // Search for similar documents
-    const results = await this.db.search({
-      vector: new Float32Array(response.data[0].embedding),
-      k: k,
-      threshold: 0.7  // Only use highly relevant results
-    });
+const { RuVectorIndex } = require('ruvector/llamaindex');
 
-    console.log(`📄 Found ${results.length} relevant documents\n`);
-
-    return results.map(r => ({
-      content: r.metadata.content,
-      title: r.metadata.title,
-      score: r.score
-    }));
-  }
-
-  // Step 3: Generate answer with retrieved context
-  async answer(question) {
-    // Retrieve relevant context
-    const context = await this.retrieveContext(question, 3);
-
-    if (context.length === 0) {
-      return "I don't have enough information to answer that question.";
-    }
-
-    // Build prompt with context
-    const contextText = context
-      .map((doc, i) => `[${i + 1}] ${doc.title}\n${doc.content}`)
-      .join('\n\n');
-
-    const prompt = `Answer the question based on the following context. If the context doesn't contain the answer, say so.
-
-Context:
-${contextText}
-
-Question: ${question}
-
-Answer:`;
-
-    console.log('🤖 Generating answer...\n');
-
-    // Generate completion
-    const completion = await this.openai.chat.completions.create({
-      model: 'gpt-4',
-      messages: [
-        { role: 'system', content: 'You are a helpful assistant that answers questions based on provided context.' },
-        { role: 'user', content: prompt }
-      ],
-      temperature: 0.3  // Lower temperature for more factual responses
-    });
-
-    return {
-      answer: completion.choices[0].message.content,
-      sources: context.map(c => c.title)
-    };
-  }
-}
-
-// Example Usage
-async function main() {
-  const rag = new RAGSystem();
-
-  // Step 1: Index your knowledge base
-  const documents = [
-    {
-      id: 'doc1',
-      title: 'Ruvector Introduction',
-      content: 'Ruvector is a high-performance vector database for Node.js built in Rust. It provides sub-millisecond query latency and supports over 52,000 inserts per second.',
-      source: 'documentation'
-    },
-    {
-      id: 'doc2',
-      title: 'Vector Databases Explained',
-      content: 'Vector databases store data as high-dimensional vectors, enabling semantic similarity search. They are essential for AI applications like RAG systems and recommendation engines.',
-      source: 'blog'
-    },
-    {
-      id: 'doc3',
-      title: 'HNSW Algorithm',
-      content: 'Hierarchical Navigable Small World (HNSW) is a graph-based algorithm for approximate nearest neighbor search. It provides excellent recall with low latency.',
-      source: 'research'
-    }
-  ];
-
-  await rag.indexDocuments(documents);
-
-  // Step 2: Ask questions
-  console.log('\n' + '='.repeat(60) + '\n');
-
-  const result = await rag.answer('What is Ruvector and what are its performance characteristics?');
-
-  console.log('📝 Answer:', result.answer);
-  console.log('\n📚 Sources:', result.sources.join(', '));
-}
-
-main().catch(console.error);
-```
+const index = new RuVectorIndex({
+  dimension: 384,
+  enableGNN: true
+});
 
-**Expected Output:**
+await index.insert(documents);
+const queryEngine = index.asQueryEngine();
+const response = await queryEngine.query("What is machine learning?");
 ```
-✅ RAG System initialized
-📚 Indexing 3 documents...
-  ✅ Indexed: Ruvector Introduction
-  ✅ Indexed: Vector Databases Explained
-  ✅ Indexed: HNSW Algorithm
 
-✅ Indexed 3 documents total
+### OpenAI / Anthropic
 
-============================================================
-
-🔍 Searching for: "What is Ruvector and what are its performance characteristics?"
-📄 Found 2 relevant documents
+```javascript
+const { createEmbedder } = require('ruvector');
 
-🤖 Generating answer...
+// OpenAI
+const openaiEmbed = createEmbedder('openai', {
+  model: 'text-embedding-3-small'
+});
 
-📝 Answer: Ruvector is a high-performance vector database built in Rust for Node.js applications. Its key performance characteristics include:
-- Sub-millisecond query latency
-- Over 52,000 inserts per second
-- Optimized for semantic similarity search
+// Anthropic (via Voyage)
+const anthropicEmbed = createEmbedder('voyage', {
+  model: 'voyage-2'
+});
 
-📚 Sources: Ruvector Introduction, Vector Databases Explained
+// Cohere
+const cohereEmbed = createEmbedder('cohere', {
+  model: 'embed-english-v3.0'
+});
 ```
 
-**Production Tips:**
-- ✅ Use batch embedding for better throughput (OpenAI supports up to 2048 texts)
-- ✅ Implement caching for frequently asked questions
-- ✅ Add error handling for API rate limits
-- ✅ Monitor token usage and costs
-- ✅ Regularly update your knowledge base
+## Benchmarks
 
----
-
-### Tutorial 2: Semantic Search Engine
-
-**What you'll learn:** Build a semantic search engine that understands meaning, not just keywords.
+| Operation | Dimensions | Time | Throughput |
+|-----------|------------|------|------------|
+| **HNSW Search (k=10)** | 384 | 61µs | 16,400 QPS |
+| **HNSW Search (k=100)** | 384 | 164µs | 6,100 QPS |
+| **Cosine Similarity** | 1536 | 143ns | 7M ops/sec |
+| **Dot Product** | 384 | 33ns | 30M ops/sec |
+| **Insert** | 384 | 20µs | 50,000/sec |
+| **GNN Forward** | 384→512 | 89µs | 11,200/sec |
+| **Compression (PQ8)** | 384 | 12µs | 83,000/sec |
 
-**Prerequisites:**
+Run your own benchmarks:
 ```bash
-npm install ruvector @xenova/transformers
-```
-
-**Complete Implementation:**
-
-```javascript
-const { VectorDb } = require('ruvector');
-const { pipeline } = require('@xenova/transformers');
-
-class SemanticSearchEngine {
-  constructor() {
-    this.db = null;
-    this.embedder = null;
-  }
-
-  // Step 1: Initialize the embedding model
-  async initialize() {
-    console.log('🚀 Initializing semantic search engine...');
-
-    // Load sentence-transformers model (runs locally, no API needed!)
-    console.log('📥 Loading embedding model...');
-    this.embedder = await pipeline(
-      'feature-extraction',
-      'Xenova/all-MiniLM-L6-v2'
-    );
-
-    // Create vector database (384 dimensions for all-MiniLM-L6-v2)
-    this.db = new VectorDb({
-      dimensions: 384,
-      maxElements: 50000,
-      storagePath: './semantic-search.db'
-    });
-
-    console.log('✅ Search engine ready!\n');
-  }
-
-  // Step 2: Generate embeddings
-  async embed(text) {
-    const output = await this.embedder(text, {
-      pooling: 'mean',
-      normalize: true
-    });
-
-    // Convert to Float32Array
-    return new Float32Array(output.data);
-  }
-
-  // Step 3: Index documents
-  async indexDocuments(documents) {
-    console.log(`📚 Indexing ${documents.length} documents...`);
-
-    for (const doc of documents) {
-      const vector = await this.embed(doc.content);
-
-      await this.db.insert({
-        id: doc.id,
-        vector: vector,
-        metadata: {
-          title: doc.title,
-          content: doc.content,
-          category: doc.category,
-          url: doc.url
-        }
-      });
-
-      console.log(`  ✅ ${doc.title}`);
-    }
-
-    const count = await this.db.len();
-    console.log(`\n✅ Indexed ${count} documents\n`);
-  }
-
-  // Step 4: Semantic search
-  async search(query, options = {}) {
-    const {
-      k = 5,
-      category = null,
-      threshold = 0.3
-    } = options;
-
-    console.log(`🔍 Searching for: "${query}"`);
-
-    // Generate query embedding
-    const queryVector = await this.embed(query);
-
-    // Search vector database
-    const results = await this.db.search({
-      vector: queryVector,
-      k: k * 2,  // Get more results for filtering
-      threshold: threshold
-    });
-
-    // Filter by category if specified
-    let filtered = results;
-    if (category) {
-      filtered = results.filter(r => r.metadata.category === category);
-    }
-
-    // Return top k after filtering
-    const final = filtered.slice(0, k);
-
-    console.log(`📄 Found ${final.length} results\n`);
-
-    return final.map(r => ({
-      id: r.id,
-      title: r.metadata.title,
-      content: r.metadata.content,
-      category: r.metadata.category,
-      score: r.score,
-      url: r.metadata.url
-    }));
-  }
-
-  // Step 5: Find similar documents
-  async findSimilar(documentId, k = 5) {
-    const doc = await this.db.get(documentId);
-
-    if (!doc) {
-      throw new Error(`Document ${documentId} not found`);
-    }
-
-    const results = await this.db.search({
-      vector: doc.vector,
-      k: k + 1  // +1 because the document itself will be included
-    });
-
-    // Remove the document itself from results
-    return results
-      .filter(r => r.id !== documentId)
-      .slice(0, k);
-  }
-}
-
-// Example Usage
-async function main() {
-  const engine = new SemanticSearchEngine();
-  await engine.initialize();
-
-  // Sample documents (in production, load from your database)
-  const documents = [
-    {
-      id: '1',
-      title: 'Understanding Neural Networks',
-      content: 'Neural networks are computing systems inspired by biological neural networks. They learn to perform tasks by considering examples.',
-      category: 'AI',
-      url: '/docs/neural-networks'
-    },
-    {
-      id: '2',
-      title: 'Introduction to Machine Learning',
-      content: 'Machine learning is a subset of artificial intelligence that provides systems the ability to learn and improve from experience.',
-      category: 'AI',
-      url: '/docs/machine-learning'
-    },
-    {
-      id: '3',
-      title: 'Web Development Best Practices',
-      content: 'Modern web development involves responsive design, performance optimization, and accessibility considerations.',
-      category: 'Web',
-      url: '/docs/web-dev'
-    },
-    {
-      id: '4',
-      title: 'Deep Learning Applications',
-      content: 'Deep learning has revolutionized computer vision, natural language processing, and speech recognition.',
-      category: 'AI',
-      url: '/docs/deep-learning'
-    }
-  ];
-
-  // Index documents
-  await engine.indexDocuments(documents);
-
-  // Example 1: Basic semantic search
-  console.log('Example 1: Basic Search\n' + '='.repeat(60));
-  const results1 = await engine.search('AI and neural nets');
-  results1.forEach((result, i) => {
-    console.log(`${i + 1}. ${result.title} (Score: ${result.score.toFixed(3)})`);
-    console.log(`   ${result.content.slice(0, 80)}...`);
-    console.log(`   Category: ${result.category}\n`);
-  });
-
-  // Example 2: Category-filtered search
-  console.log('\nExample 2: Category-Filtered Search\n' + '='.repeat(60));
-  const results2 = await engine.search('learning algorithms', {
-    category: 'AI',
-    k: 3
-  });
-  results2.forEach((result, i) => {
-    console.log(`${i + 1}. ${result.title} (Score: ${result.score.toFixed(3)})`);
-  });
+npx ruvector benchmark --dimension 384 --num-vectors 100000
+```
+
+## Comparison
+
+| Feature | RuVector | Pinecone | Qdrant | ChromaDB | Milvus | Weaviate |
+|---------|----------|----------|--------|----------|--------|----------|
+| **Latency (p50)** | **61µs** | ~2ms | ~1ms | ~50ms | ~5ms | ~3ms |
+| **Graph Queries** | ✅ Cypher | ❌ | ❌ | ❌ | ❌ | ✅ GraphQL |
+| **Self-Learning** | ✅ GNN | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **AI Routing** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Browser/WASM** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Compression** | 2-32x | ❌ | ✅ | ❌ | ✅ | ✅ |
+| **Hybrid Search** | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
+| **Multi-tenancy** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **Open Source** | ✅ MIT | ❌ | ✅ Apache | ✅ Apache | ✅ Apache | ✅ BSD |
+| **Pricing** | Free | $70+/mo | Free | Free | Free | Free |
+
+## npm Packages
+
+| Package | Description |
+|---------|-------------|
+| [`ruvector`](https://www.npmjs.com/package/ruvector) | **All-in-one package (recommended)** |
+| [`@ruvector/wasm`](https://www.npmjs.com/package/@ruvector/wasm) | Browser/WASM bindings |
+| [`@ruvector/graph`](https://www.npmjs.com/package/@ruvector/graph) | Graph database with Cypher |
+| [`@ruvector/gnn`](https://www.npmjs.com/package/@ruvector/gnn) | Graph Neural Network layers |
+| [`@ruvector/tiny-dancer`](https://www.npmjs.com/package/@ruvector/tiny-dancer) | AI agent routing (FastGRNN) |
+| [`@ruvector/router`](https://www.npmjs.com/package/@ruvector/router) | Semantic routing engine |
 
-  // Example 3: Find similar documents
-  console.log('\n\nExample 3: Find Similar Documents\n' + '='.repeat(60));
-  const similar = await engine.findSimilar('1', 2);
-  console.log('Documents similar to "Understanding Neural Networks":');
-  similar.forEach((doc, i) => {
-    console.log(`${i + 1}. ${doc.metadata.title} (Score: ${doc.score.toFixed(3)})`);
-  });
-}
+```bash
+# Install all-in-one (recommended)
+npm install ruvector
 
-main().catch(console.error);
+# Or install specific packages
+npm install @ruvector/graph @ruvector/gnn
 ```
 
-**Key Features:**
-- ✅ Runs completely locally (no API keys needed)
-- ✅ Understands semantic meaning, not just keywords
-- ✅ Category filtering for better results
-- ✅ "Find similar" functionality
-- ✅ Fast: ~10ms query latency
-
----
-
-### Tutorial 3: AI Agent Memory System
-
-**What you'll learn:** Implement a memory system for AI agents that remembers past experiences and learns from them.
-
-**Complete Implementation:**
-
-```javascript
-const { VectorDb } = require('ruvector');
-
-class AgentMemory {
-  constructor(agentId) {
-    this.agentId = agentId;
-
-    // Create separate databases for different memory types
-    this.episodicMemory = new VectorDb({
-      dimensions: 768,
-      storagePath: `./memory/${agentId}-episodic.db`
-    });
-
-    this.semanticMemory = new VectorDb({
-      dimensions: 768,
-      storagePath: `./memory/${agentId}-semantic.db`
-    });
-
-    console.log(`🧠 Memory system initialized for agent: ${agentId}`);
-  }
-
-  // Step 1: Store an experience (episodic memory)
-  async storeExperience(experience) {
-    const {
-      state,
-      action,
-      result,
-      reward,
-      embedding
-    } = experience;
-
-    const experienceId = `exp_${Date.now()}_${Math.random()}`;
-
-    await this.episodicMemory.insert({
-      id: experienceId,
-      vector: new Float32Array(embedding),
-      metadata: {
-        state: state,
-        action: action,
-        result: result,
-        reward: reward,
-        timestamp: Date.now(),
-        type: 'episodic'
-      }
-    });
-
-    console.log(`💾 Stored experience: ${action} -> ${result} (reward: ${reward})`);
-    return experienceId;
-  }
-
-  // Step 2: Store learned knowledge (semantic memory)
-  async storeKnowledge(knowledge) {
-    const {
-      concept,
-      description,
-      embedding,
-      confidence = 1.0
-    } = knowledge;
-
-    const knowledgeId = `know_${Date.now()}`;
-
-    await this.semanticMemory.insert({
-      id: knowledgeId,
-      vector: new Float32Array(embedding),
-      metadata: {
-        concept: concept,
-        description: description,
-        confidence: confidence,
-        learned: Date.now(),
-        uses: 0,
-        type: 'semantic'
-      }
-    });
-
-    console.log(`📚 Learned: ${concept}`);
-    return knowledgeId;
-  }
-
-  // Step 3: Recall similar experiences
-  async recallExperiences(currentState, k = 5) {
-    console.log(`🔍 Recalling similar experiences...`);
-
-    const results = await this.episodicMemory.search({
-      vector: new Float32Array(currentState.embedding),
-      k: k,
-      threshold: 0.6  // Only recall reasonably similar experiences
-    });
-
-    // Sort by reward to prioritize successful experiences
-    const sorted = results.sort((a, b) => b.metadata.reward - a.metadata.reward);
-
-    console.log(`📝 Recalled ${sorted.length} relevant experiences`);
-
-    return sorted.map(r => ({
-      state: r.metadata.state,
-      action: r.metadata.action,
-      result: r.metadata.result,
-      reward: r.metadata.reward,
-      similarity: r.score
-    }));
-  }
-
-  // Step 4: Query knowledge base
-  async queryKnowledge(query, k = 3) {
-    const results = await this.semanticMemory.search({
-      vector: new Float32Array(query.embedding),
-      k: k
-    });
-
-    // Update usage statistics
-    for (const result of results) {
-      const knowledge = await this.semanticMemory.get(result.id);
-      if (knowledge) {
-        knowledge.metadata.uses += 1;
-        // In production, update the entry
-      }
-    }
-
-    return results.map(r => ({
-      concept: r.metadata.concept,
-      description: r.metadata.description,
-      confidence: r.metadata.confidence,
-      relevance: r.score
-    }));
-  }
-
-  // Step 5: Reflect and learn from experiences
-  async reflect() {
-    console.log('\n🤔 Reflecting on experiences...');
+## API Reference
 
-    // Get all experiences
-    const totalExperiences = await this.episodicMemory.len();
-    console.log(`📊 Total experiences: ${totalExperiences}`);
+### VectorDB
 
-    // Analyze success rate
-    // In production, you'd aggregate experiences and extract patterns
-    console.log('💡 Analysis complete');
-
-    return {
-      totalExperiences: totalExperiences,
-      knowledgeItems: await this.semanticMemory.len()
-    };
-  }
-
-  // Step 6: Get memory statistics
-  async getStats() {
-    return {
-      episodicMemorySize: await this.episodicMemory.len(),
-      semanticMemorySize: await this.semanticMemory.len(),
-      agentId: this.agentId
-    };
-  }
+```typescript
+class VectorDB {
+  constructor(dimension: number, options?: VectorDBOptions);
+
+  // CRUD operations
+  insert(id: string, values: number[], metadata?: object): Promise<void>;
+  insertBatch(vectors: Vector[], options?: BatchOptions): Promise<void>;
+  get(id: string): Promise<Vector | null>;
+  update(id: string, values?: number[], metadata?: object): Promise<void>;
+  delete(id: string): Promise<boolean>;
+
+  // Search
+  search(query: number[], k?: number, filter?: Filter): Promise<SearchResult[]>;
+  hybridSearch(query: number[], text: string, k?: number): Promise<SearchResult[]>;
+
+  // Persistence
+  save(path: string): Promise<void>;
+  static load(path: string): Promise<VectorDB>;
+
+  // Management
+  stats(): Promise<IndexStats>;
+  optimize(): Promise<void>;
+  clear(): Promise<void>;
 }
+```
 
-// Example Usage: Simulated agent learning to navigate
-async function main() {
-  const agent = new AgentMemory('agent-001');
-
-  // Simulate embedding function (in production, use a real model)
-  function embed(text) {
-    return Array(768).fill(0).map(() => Math.random());
-  }
-
-  console.log('\n' + '='.repeat(60));
-  console.log('PHASE 1: Learning from experiences');
-  console.log('='.repeat(60) + '\n');
-
-  // Store some experiences
-  await agent.storeExperience({
-    state: { location: 'room1', goal: 'room3' },
-    action: 'move_north',
-    result: 'reached room2',
-    reward: 0.5,
-    embedding: embed('navigating from room1 to room2')
-  });
-
-  await agent.storeExperience({
-    state: { location: 'room2', goal: 'room3' },
-    action: 'move_east',
-    result: 'reached room3',
-    reward: 1.0,
-    embedding: embed('navigating from room2 to room3')
-  });
-
-  await agent.storeExperience({
-    state: { location: 'room1', goal: 'room3' },
-    action: 'move_south',
-    result: 'hit wall',
-    reward: -0.5,
-    embedding: embed('failed navigation attempt')
-  });
-
-  // Store learned knowledge
-  await agent.storeKnowledge({
-    concept: 'navigation_strategy',
-    description: 'Moving north then east is efficient for reaching room3 from room1',
-    embedding: embed('navigation strategy knowledge'),
-    confidence: 0.9
-  });
-
-  console.log('\n' + '='.repeat(60));
-  console.log('PHASE 2: Applying memory');
-  console.log('='.repeat(60) + '\n');
-
-  // Agent encounters a similar situation
-  const currentState = {
-    location: 'room1',
-    goal: 'room3',
-    embedding: embed('navigating from room1 to room3')
-  };
-
-  // Recall relevant experiences
-  const experiences = await agent.recallExperiences(currentState, 3);
-
-  console.log('\n📖 Recalled experiences:');
-  experiences.forEach((exp, i) => {
-    console.log(`${i + 1}. Action: ${exp.action} | Result: ${exp.result} | Reward: ${exp.reward} | Similarity: ${exp.similarity.toFixed(3)}`);
-  });
-
-  // Query relevant knowledge
-  const knowledge = await agent.queryKnowledge({
-    embedding: embed('how to navigate efficiently')
-  }, 2);
+### GraphDB
 
-  console.log('\n📚 Relevant knowledge:');
-  knowledge.forEach((k, i) => {
-    console.log(`${i + 1}. ${k.concept}: ${k.description} (confidence: ${k.confidence})`);
-  });
+```typescript
+class GraphDB {
+  constructor(options?: GraphDBOptions);
 
-  console.log('\n' + '='.repeat(60));
-  console.log('PHASE 3: Reflection');
-  console.log('='.repeat(60) + '\n');
+  // Cypher execution
+  execute(cypher: string, params?: object): QueryResult;
 
-  // Reflect on learning
-  const stats = await agent.reflect();
-  const memoryStats = await agent.getStats();
+  // Direct API
+  createNode(label: string, properties: object): string;
+  createRelationship(from: string, to: string, type: string, props?: object): void;
+  createHyperedge(nodeIds: string[], type: string, props?: object): string;
 
-  console.log('\n📊 Memory Statistics:');
-  console.log(`   Episodic memories: ${memoryStats.episodicMemorySize}`);
-  console.log(`   Semantic knowledge: ${memoryStats.semanticMemorySize}`);
-  console.log(`   Agent ID: ${memoryStats.agentId}`);
+  // Traversal
+  shortestPath(from: string, to: string): Path | null;
+  neighbors(nodeId: string, depth?: number): Node[];
 }
-
-main().catch(console.error);
 ```
 
-**Expected Output:**
-```
-🧠 Memory system initialized for agent: agent-001
-
-============================================================
-PHASE 1: Learning from experiences
-============================================================
-
-💾 Stored experience: move_north -> reached room2 (reward: 0.5)
-💾 Stored experience: move_east -> reached room3 (reward: 1.0)
-💾 Stored experience: move_south -> hit wall (reward: -0.5)
-📚 Learned: navigation_strategy
-
-============================================================
-PHASE 2: Applying memory
-============================================================
-
-🔍 Recalling similar experiences...
-📝 Recalled 3 relevant experiences
+### GNNLayer
 
-📖 Recalled experiences:
-1. Action: move_east | Result: reached room3 | Reward: 1.0 | Similarity: 0.892
-2. Action: move_north | Result: reached room2 | Reward: 0.5 | Similarity: 0.876
-3. Action: move_south | Result: hit wall | Reward: -0.5 | Similarity: 0.654
-
-📚 Relevant knowledge:
-1. navigation_strategy: Moving north then east is efficient for reaching room3 from room1 (confidence: 0.9)
-
-============================================================
-PHASE 3: Reflection
-============================================================
+```typescript
+class GNNLayer {
+  constructor(inputDim: number, outputDim: number, numHeads: number);
 
-🤔 Reflecting on experiences...
-📊 Total experiences: 3
-💡 Analysis complete
+  // Inference
+  forward(query: number[], neighbors: number[][], weights: number[]): number[];
 
-📊 Memory Statistics:
-   Episodic memories: 3
-   Semantic knowledge: 1
-   Agent ID: agent-001
+  // Training
+  train(data: TrainingData, config?: TrainingConfig): TrainingMetrics;
+  save(path: string): void;
+  static load(path: string): GNNLayer;
+}
 ```
 
-**Use Cases:**
-- ✅ Reinforcement learning agents
-- ✅ Chatbot conversation history
-- ✅ Game AI that learns from gameplay
-- ✅ Personal assistant memory
-- ✅ Robotic navigation systems
-
-## 🏗️ API Reference
-
-### Constructor
+### Router
 
 ```typescript
-new VectorDb(options: {
-  dimensions: number;        // Vector dimensionality (required)
-  maxElements?: number;      // Max vectors (default: 10000)
-  storagePath?: string;      // Persistent storage path
-  ef_construction?: number;  // HNSW construction parameter (default: 200)
-  m?: number;               // HNSW M parameter (default: 16)
-  distanceMetric?: string;  // 'cosine', 'euclidean', or 'dot' (default: 'cosine')
-})
-```
-
-### Methods
+class Router {
+  constructor(config?: RouterConfig);
 
-#### insert(entry: VectorEntry): Promise<string>
-Insert a vector into the database.
+  // Routing
+  route(query: number[], candidates: Candidate[]): RoutingDecision;
+  routeBatch(queries: number[][], candidates: Candidate[]): RoutingDecision[];
 
-```javascript
-const id = await db.insert({
-  id: 'doc_1',
-  vector: new Float32Array([0.1, 0.2, 0.3, ...]),
-  metadata: { title: 'Document 1' }
-});
+  // Management
+  reloadModel(): void;
+  circuitBreakerStatus(): 'closed' | 'open' | 'half-open';
+  resetCircuitBreaker(): void;
+}
 ```
 
-#### search(query: SearchQuery): Promise<SearchResult[]>
-Search for similar vectors.
+## Use Cases
 
-```javascript
-const results = await db.search({
-  vector: new Float32Array([0.1, 0.2, 0.3, ...]),
-  k: 10,
-  threshold: 0.7
-});
-```
-
-#### get(id: string): Promise<VectorEntry | null>
-Retrieve a vector by ID.
+### Agentic AI / Multi-Agent Systems
 
 ```javascript
-const entry = await db.get('doc_1');
-if (entry) {
-  console.log(entry.vector, entry.metadata);
-}
-```
-
-#### delete(id: string): Promise<boolean>
-Remove a vector from the database.
+// Route tasks to specialized agents
+const agents = [
+  { id: 'researcher', embedding: researchEmb, capabilities: ['search', 'summarize'] },
+  { id: 'coder', embedding: codeEmb, capabilities: ['code', 'debug'] },
+  { id: 'analyst', embedding: analysisEmb, capabilities: ['data', 'visualize'] }
+];
 
-```javascript
-const deleted = await db.delete('doc_1');
-console.log(deleted ? 'Deleted' : 'Not found');
+const taskEmb = await embed("Write a Python script to analyze sales data");
+const decision = router.route(taskEmb, agents);
+// Routes to 'coder' agent with high confidence
 ```
 
-#### len(): Promise<number>
-Get the total number of vectors.
+### Recommendation Systems
 
 ```javascript
-const count = await db.len();
-console.log(`Total vectors: ${count}`);
+const recommendations = graph.execute(`
+  MATCH (user:User {id: $userId})-[:VIEWED]->(item:Product)
+  MATCH (item)-[:SIMILAR_TO]->(rec:Product)
+  WHERE NOT (user)-[:VIEWED]->(rec)
+    AND vector.similarity(rec.embedding, $userPreference) > 0.7
+  RETURN rec
+  ORDER BY vector.similarity(rec.embedding, $userPreference) DESC
+  LIMIT 10
+`);
 ```
 
-## 🎨 Advanced Configuration
-
-### HNSW Parameters
+### Semantic Caching
 
 ```javascript
-const db = new VectorDb({
-  dimensions: 384,
-  maxElements: 1000000,
-  ef_construction: 200,  // Higher = better recall, slower build
-  m: 16,                 // Higher = better recall, more memory
-  storagePath: './large-db.db'
-});
-```
-
-**Parameter Guidelines:**
-- `ef_construction`: 100-400 (higher = better recall, slower indexing)
-- `m`: 8-64 (higher = better recall, more memory)
-- Default values work well for most use cases
+const cache = new VectorDB(1536);
 
-### Distance Metrics
+async function cachedLLMCall(prompt) {
+  const promptEmb = await embed(prompt);
 
-```javascript
-// Cosine similarity (default, best for normalized vectors)
-const db1 = new VectorDb({
-  dimensions: 128,
-  distanceMetric: 'cosine'
-});
+  // Check semantic cache
+  const cached = await cache.search(promptEmb, 1);
+  if (cached[0]?.score > 0.95) {
+    return cached[0].metadata.response; // Cache hit
+  }
 
-// Euclidean distance (L2, best for spatial data)
-const db2 = new VectorDb({
-  dimensions: 128,
-  distanceMetric: 'euclidean'
-});
+  // Cache miss - call LLM
+  const response = await llm.complete(prompt);
+  await cache.insert(generateId(), promptEmb, { prompt, response });
 
-// Dot product (best for pre-normalized vectors)
-const db3 = new VectorDb({
-  dimensions: 128,
-  distanceMetric: 'dot'
-});
+  return response;
+}
 ```
 
-### Persistence
+### Document Q&A with Sources
 
 ```javascript
-// Auto-save to disk
-const persistent = new VectorDb({
-  dimensions: 128,
-  storagePath: './persistent.db'
-});
+async function qaWithSources(question) {
+  const results = await db.search(await embed(question), 5);
 
-// In-memory only (faster, but data lost on exit)
-const temporary = new VectorDb({
-  dimensions: 128
-  // No storagePath = in-memory
-});
-```
-
-## 📦 Platform Support
-
-Automatically installs the correct implementation for:
-
-### Native (Rust) - Best Performance
-- **Linux**: x64, ARM64 (GNU libc)
-- **macOS**: x64 (Intel), ARM64 (Apple Silicon)
-- **Windows**: x64 (MSVC)
-
-Performance: **<0.5ms latency**, **50K+ ops/sec**
-
-### WASM Fallback - Universal Compatibility
-- Any platform where native module isn't available
-- Browser environments (experimental)
-- Alpine Linux (musl) and other non-glibc systems
-
-Performance: **10-50ms latency**, **~1K ops/sec**
-
-**Node.js 18+ required** for all platforms.
+  const answer = await llm.complete({
+    prompt: `Answer based on these sources:\n${results.map(r =>
+      `[${r.id}] ${r.metadata.content}`
+    ).join('\n')}\n\nQuestion: ${question}`,
+  });
 
-## 🔧 Building from Source
+  return {
+    answer,
+    sources: results.map(r => ({
+      id: r.id,
+      title: r.metadata.title,
+      relevance: r.score
+    }))
+  };
+}
+```
 
-If you need to rebuild the native module:
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                         ruvector                              │
+│                  (All-in-One npm Package)                     │
+├──────────────┬──────────────┬──────────────┬─────────────────┤
+│   VectorDB   │   GraphDB    │   GNNLayer   │     Router      │
+│   (Search)   │   (Cypher)   │    (ML)      │  (AI Routing)   │
+├──────────────┴──────────────┴──────────────┴─────────────────┤
+│                      Rust Core Engine                         │
+│  • HNSW Index  • Cypher Parser  • Attention  • FastGRNN      │
+│  • SIMD Ops    • Hyperedges     • Training   • Uncertainty   │
+└──────────────────────────────────────────────────────────────┘
+                              │
+           ┌──────────────────┼──────────────────┐
+           │                  │                  │
+      ┌────▼────┐       ┌────▼────┐       ┌────▼────┐
+      │  Native │       │  WASM   │       │   FFI   │
+      │(napi-rs)│       │(wasm32) │       │   (C)   │
+      └─────────┘       └─────────┘       └─────────┘
+           │                  │                  │
+      ┌────▼────┐       ┌────▼────┐       ┌────▼────┐
+      │ Node.js │       │ Browser │       │ Python  │
+      │   Bun   │       │  Deno   │       │   Go    │
+      └─────────┘       └─────────┘       └─────────┘
+```
+
+## Platform Support
+
+| Platform | Backend | Installation |
+|----------|---------|--------------|
+| **Node.js 16+** | Native (napi-rs) | `npm install ruvector` |
+| **Node.js (fallback)** | WASM | Automatic if native fails |
+| **Bun** | Native | `bun add ruvector` |
+| **Deno** | WASM | `import from "npm:ruvector"` |
+| **Browser** | WASM | `npm install @ruvector/wasm` |
+| **Cloudflare Workers** | WASM | `npm install @ruvector/wasm` |
+| **Vercel Edge** | WASM | `npm install @ruvector/wasm` |
+
+## Documentation
+
+- [Getting Started Guide](https://github.com/ruvnet/ruvector/blob/main/docs/guide/GETTING_STARTED.md)
+- [Cypher Reference](https://github.com/ruvnet/ruvector/blob/main/docs/api/CYPHER_REFERENCE.md)
+- [GNN Architecture](https://github.com/ruvnet/ruvector/blob/main/docs/gnn-layer-implementation.md)
+- [Performance Tuning](https://github.com/ruvnet/ruvector/blob/main/docs/optimization/PERFORMANCE_TUNING_GUIDE.md)
+- [API Reference](https://github.com/ruvnet/ruvector/tree/main/docs/api)
+
+## Contributing
 
 ```bash
-# Install Rust toolchain
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-
 # Clone repository
 git clone https://github.com/ruvnet/ruvector.git
 cd ruvector
 
-# Build native module
-cd npm/packages/core
-npm run build:napi
-
-# Build wrapper package
-cd ../ruvector
+# Install dependencies
 npm install
-npm run build
 
 # Run tests
 npm test
-```
-
-**Requirements:**
-- Rust 1.77+
-- Node.js 18+
-- Cargo
-
-## 🌍 Ecosystem
-
-### Related Packages
 
-- **[ruvector-core](https://www.npmjs.com/package/ruvector-core)** - Core native bindings (lower-level API)
-- **[ruvector-wasm](https://www.npmjs.com/package/ruvector-wasm)** - WebAssembly implementation for browsers
-- **[ruvector-cli](https://www.npmjs.com/package/ruvector-cli)** - Standalone CLI tools
-
-### Platform-Specific Packages (auto-installed)
-
-- **[ruvector-core-linux-x64-gnu](https://www.npmjs.com/package/ruvector-core-linux-x64-gnu)**
-- **[ruvector-core-linux-arm64-gnu](https://www.npmjs.com/package/ruvector-core-linux-arm64-gnu)**
-- **[ruvector-core-darwin-x64](https://www.npmjs.com/package/ruvector-core-darwin-x64)**
-- **[ruvector-core-darwin-arm64](https://www.npmjs.com/package/ruvector-core-darwin-arm64)**
-- **[ruvector-core-win32-x64-msvc](https://www.npmjs.com/package/ruvector-core-win32-x64-msvc)**
-
-## 🐛 Troubleshooting
-
-### Native Module Not Loading
-
-If you see "Cannot find module 'ruvector-core-*'":
-
-```bash
-# Reinstall with optional dependencies
-npm install --include=optional ruvector
-
-# Verify platform
-npx ruvector info
+# Build
+npm run build
 
-# Check Node.js version (18+ required)
-node --version
+# Benchmarks
+npm run bench
 ```
 
-### WASM Fallback Performance
+See [CONTRIBUTING.md](https://github.com/ruvnet/ruvector/blob/main/docs/development/CONTRIBUTING.md) for guidelines.
 
-If you're using WASM fallback and need better performance:
+## License
 
-1. **Install native toolchain** for your platform
-2. **Rebuild native module**: `npm rebuild ruvector`
-3. **Verify native**: `npx ruvector info` should show "native (Rust)"
-
-### Platform Compatibility
-
-- **Alpine Linux**: Uses WASM fallback (musl not supported)
-- **Windows ARM**: Not yet supported, uses WASM fallback
-- **Node.js < 18**: Not supported, upgrade to Node.js 18+
-
-## 📚 Documentation
-
-- 🏠 [Homepage](https://ruv.io)
-- 📦 [GitHub Repository](https://github.com/ruvnet/ruvector)
-- 📚 [Full Documentation](https://github.com/ruvnet/ruvector/tree/main/docs)
-- 🚀 [Getting Started Guide](https://github.com/ruvnet/ruvector/blob/main/docs/guide/GETTING_STARTED.md)
-- 📖 [API Reference](https://github.com/ruvnet/ruvector/blob/main/docs/api/NODEJS_API.md)
-- 🎯 [Performance Tuning](https://github.com/ruvnet/ruvector/blob/main/docs/optimization/PERFORMANCE_TUNING_GUIDE.md)
-- 🐛 [Issue Tracker](https://github.com/ruvnet/ruvector/issues)
-- 💬 [Discussions](https://github.com/ruvnet/ruvector/discussions)
-
-## 🤝 Contributing
-
-We welcome contributions! See [CONTRIBUTING.md](https://github.com/ruvnet/ruvector/blob/main/docs/development/CONTRIBUTING.md) for guidelines.
-
-### Quick Start
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/amazing-feature`
-3. Commit changes: `git commit -m 'Add amazing feature'`
-4. Push to branch: `git push origin feature/amazing-feature`
-5. Open a Pull Request
-
-## 🌐 Community & Support
-
-- **GitHub**: [github.com/ruvnet/ruvector](https://github.com/ruvnet/ruvector) - ⭐ Star and follow
-- **Discord**: [Join our community](https://discord.gg/ruvnet) - Chat with developers
-- **Twitter**: [@ruvnet](https://twitter.com/ruvnet) - Follow for updates
-- **Issues**: [Report bugs](https://github.com/ruvnet/ruvector/issues)
-
-### Enterprise Support
-
-Need custom development or consulting?
-
-📧 [enterprise@ruv.io](mailto:enterprise@ruv.io)
-
-## 📜 License
-
-**MIT License** - see [LICENSE](https://github.com/ruvnet/ruvector/blob/main/LICENSE) for details.
-
-Free for commercial and personal use.
-
-## 🙏 Acknowledgments
-
-Built with battle-tested technologies:
-
-- **HNSW**: Hierarchical Navigable Small World graphs
-- **SIMD**: Hardware-accelerated vector operations via simsimd
-- **Rust**: Memory-safe, zero-cost abstractions
-- **NAPI-RS**: High-performance Node.js bindings
-- **WebAssembly**: Universal browser compatibility
+MIT License — free for commercial and personal use.
 
 ---
 
 <div align="center">
 
-**Built with ❤️ by [rUv](https://ruv.io)**
+**Built by [rUv](https://ruv.io)** • [GitHub](https://github.com/ruvnet/ruvector) • [npm](https://npmjs.com/package/ruvector)
 
-[![npm](https://img.shields.io/npm/v/ruvector.svg)](https://www.npmjs.com/package/ruvector)
-[![GitHub Stars](https://img.shields.io/github/stars/ruvnet/ruvector?style=social)](https://github.com/ruvnet/ruvector)
-[![Twitter](https://img.shields.io/twitter/follow/ruvnet?style=social)](https://twitter.com/ruvnet)
+*Vector search that gets smarter over time.*
 
-**[Get Started](https://github.com/ruvnet/ruvector/blob/main/docs/guide/GETTING_STARTED.md)** • **[Documentation](https://github.com/ruvnet/ruvector/tree/main/docs)** • **[API Reference](https://github.com/ruvnet/ruvector/blob/main/docs/api/NODEJS_API.md)** • **[Contributing](https://github.com/ruvnet/ruvector/blob/main/docs/development/CONTRIBUTING.md)**
+**[⭐ Star on GitHub](https://github.com/ruvnet/ruvector)** if RuVector helps your project!
 
 </div>