@ruvector/ruvllm 0.2.3 → 0.2.4

package/README.md

@@ -1,886 +1,406 @@
-# RuvLLM
+# @ruvector/ruvllm
 
-[![Rust](https://img.shields.io/badge/rust-1.77%2B-orange.svg)](https://www.rust-lang.org/)
-[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-62%20passing-brightgreen.svg)](#testing)
-[![CPU](https://img.shields.io/badge/platform-CPU%20SIMD-green.svg)](#architecture)
-[![HuggingFace](https://img.shields.io/badge/export-HuggingFace-yellow.svg)](#huggingface-export)
-[![npm](https://img.shields.io/npm/v/@ruvector/ruvllm.svg)](https://www.npmjs.com/package/@ruvector/ruvllm)
-[![TRM](https://img.shields.io/badge/TRM-7M%20params-purple.svg)](#trm-tiny-recursive-models)
+**Build AI that learns and improves from every interaction.**
 
-**Self-Optimizing Neural Architecture (SONA) with TRM Recursive Reasoning, LFM2 Cortex, Ruvector Memory, and Intelligent Routing**
+RuvLLM is a self-learning language model toolkit that gets smarter over time. Unlike traditional LLMs that remain static after training, RuvLLM continuously adapts to your use case while remembering what it learned before.
 
-> *"The intelligence is not in one model anymore. It is in the loop."*
+## What Makes RuvLLM Different?
 
----
+Traditional LLMs forget old knowledge when learning new things (called "catastrophic forgetting"). RuvLLM solves this with three key innovations:
 
-## What is RuvLLM?
+1. **It Learns Without Forgetting** - Uses tiny parameter updates (LoRA) and memory protection (EWC++) to learn new patterns while preserving existing knowledge
 
-RuvLLM is a **self-learning language model orchestration system** that combines frozen foundation models with adaptive memory and intelligent routing. Unlike traditional LLMs that rely solely on static parameters, RuvLLM continuously improves from every interaction through three temporal learning loops.
+2. **It Remembers Context** - Built-in vector memory stores and retrieves relevant information instantly using similarity search
 
-**Key Innovation**: RuvLLM doesn't replace your LLM—it makes any LLM smarter over time by learning from experience, routing intelligently, and preventing catastrophic forgetting.
+3. **It Routes Intelligently** - Automatically selects the right model size and parameters based on query complexity, saving resources on simple tasks
 
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                         RuvLLM Architecture                              │
-├─────────────────────────────────────────────────────────────────────────┤
-│                                                                          │
-│    Query ──► Embedding ──► Memory Search ──► Router Decision            │
-│                               │                    │                     │
-│                               ▼                    ▼                     │
-│                         Graph Attention      Model Selection             │
-│                               │                    │                     │
-│                               └────────┬───────────┘                     │
-│                                        ▼                                 │
-│                              ┌─────────────────────┐                     │
-│                              │   LLM Inference    │                     │
-│                              │  (Any LLM Backend)  │                     │
-│                              └─────────────────────┘                     │
-│                                        │                                 │
-│                                        ▼                                 │
-│                    ┌───────────────────────────────────┐                │
-│                    │  SONA Learning (3 Temporal Loops) │                │
-│                    │  • Instant: Per-request MicroLoRA │                │
-│                    │  • Background: Hourly patterns    │                │
-│                    │  • Deep: Weekly EWC++ updates     │                │
-│                    └───────────────────────────────────┘                │
-│                                                                          │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Features
-
-### Core Components
-
-| Component | Description | Implementation |
-|-----------|-------------|----------------|
-| **LFM2 Cortex** | Frozen reasoning engine (135M-2.6B params) | Mock, Candle, or external (llama.cpp/vLLM) |
-| **Ruvector Memory** | Adaptive synaptic mesh with HNSW indexing | Full CPU implementation with graph expansion |
-| **FastGRNN Router** | Intelligent model selection circuit | Sparse + low-rank matrices with EWC learning |
-| **Graph Attention** | Multi-head attention with edge features | 8-head attention, layer normalization |
-| **SONA Engine** | Self-optimizing neural architecture | LoRA + EWC++ + ReasoningBank |
-| **TRM Engine** | Tiny Recursive Models (7M params) | Recursive latent refinement with SONA bridge |
-
-### TRM (Tiny Recursive Models)
-
-RuvLLM v0.2.3 introduces **TRM** - Samsung SAIL Montreal's parameter-efficient recursive reasoning approach. TRM achieves strong reasoning performance with only **7M parameters** through iterative latent refinement.
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                         TRM Architecture                                 │
-├─────────────────────────────────────────────────────────────────────────┤
-│                                                                          │
-│    Question ──┬► Latent Update (n times) ──► Answer Refine ──┐          │
-│               │                                               │          │
-│               └───────────────────────────────────────────────┘          │
-│                            (repeat K times)                              │
-│                                                                          │
-│    Components:                                                           │
-│    • MLP Latent Updater - Fast feed-forward updates                     │
-│    • Attention Latent Updater - Multi-head attention refinement         │
-│    • Confidence Scorer - Early stopping based on convergence            │
-│    • Answer Refiner - Residual-based answer improvement                 │
-│    • SONA Bridge - Integration with learning loops                      │
-│                                                                          │
-└─────────────────────────────────────────────────────────────────────────┘
-```
-
-**Key Features:**
-- **7M parameters** - Achieves 83% on GSM8K with minimal compute
-- **Recursive refinement** - Iteratively improves answers through K iterations
-- **Adaptive K** - SONA routing determines optimal iteration count
-- **Early stopping** - Confidence-based termination for efficiency
-- **NaN-safe** - Robust numerical guards prevent gradient explosions
-- **Buffer reuse** - Optimized memory allocation for production use
-
-### SONA: Self-Optimizing Neural Architecture
-
-RuvLLM introduces **SONA**, a three-tier temporal learning system:
-
-```
-┌──────────────────────────────────────────────────────────────────────────┐
-│  Loop A: Instant (Per-Request)                           Latency: <100μs │
-│  ──────────────────────────────────────                                  │
-│  • Records query trajectories with activation patterns                   │
-│  • MicroLoRA adaptation (rank 1-2) for immediate improvement             │
-│  • SIMD-optimized: 2,236 ops/sec throughput                              │
-├──────────────────────────────────────────────────────────────────────────┤
-│  Loop B: Background (Hourly)                                             │
-│  ─────────────────────────────                                           │
-│  • K-means++ clustering extracts patterns (100 clusters = 1.3ms search)  │
-│  • Base LoRA updates (rank 4-16) from successful patterns                │
-│  • ReasoningBank stores learned strategies                               │
-├──────────────────────────────────────────────────────────────────────────┤
-│  Loop C: Deep (Weekly)                                                   │
-│  ─────────────────────                                                   │
-│  • Dream consolidation across all memory                                 │
-│  • EWC++ prevents catastrophic forgetting (λ=2000 optimal)               │
-│  • Concept hierarchies created, old nodes archived                       │
-└──────────────────────────────────────────────────────────────────────────┘
-```
-
-### Advanced Features
-
-| Feature | Description |
-|---------|-------------|
-| **SIMD Inference** | Native AVX2/AVX512/SSE4.1 operations for CPU optimization |
-| **Q4 Quantization** | 4-bit weight quantization for memory efficiency |
-| **MicroLoRA** | Per-request adaptation with rank 1-2 (benchmark: rank-2 is 5% faster) |
-| **EWC++** | Enhanced elastic weight consolidation with online Fisher estimation |
-| **ReasoningBank** | Pattern storage with K-means++ clustering |
-| **HuggingFace Export** | Export LoRA weights, patterns, and preference pairs |
-| **Real Inference** | Candle-based inference with HuggingFace model support |
-| **Multi-Model Routing** | Automatic selection between SmolLM, Qwen2, TinyLlama |
-| **Federated Learning** | Distributed learning across ephemeral agents with central coordinator |
-| **WASM Support** | Run SONA in browsers and edge devices |
-| **Training Pipelines** | Templated training for code, chat, reasoning, and custom agents |
-| **Agent Factory** | Create and manage multiple specialized learning agents |
-| **TRM Reasoning** | Recursive reasoning with only 7M parameters (83% GSM8K) |
-| **Adaptive K Routing** | SONA-driven iteration count for optimal compute |
-| **NaN Guards** | Robust numerical stability for production deployment |
-
-### Federated Learning Architecture
-
-RuvLLM supports **federated learning** where ephemeral agents collect trajectories and export to a central coordinator:
-
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  Agent A    │     │  Agent B    │     │  Agent C    │
-│ (ephemeral) │     │ (ephemeral) │     │ (ephemeral) │
-└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
-       │                   │                   │
-       │    export()       │    export()       │    export()
-       ▼                   ▼                   ▼
-  ┌────────────────────────────────────────────────┐
-  │            Federated Coordinator               │
-  │         (persistent, large capacity)           │
-  │  • Aggregates trajectories from all agents     │
-  │  • Quality-filtered acceptance (threshold)     │
-  │  • Auto-consolidation every N agents           │
-  │  • Shares patterns with new agents             │
-  └────────────────────────────────────────────────┘
-```
-
-**Key Components**:
-- **EphemeralAgent**: Short-lived agents that process tasks and export learned state
-- **FederatedCoordinator**: Central aggregator with 50K trajectory capacity
-- **AgentExport**: Serializable state containing trajectories, stats, and patterns
-- **Quality Filtering**: Only high-quality trajectories (>0.4 score) are aggregated
-
----
-
-## Performance Benchmarks
-
-### Orchestration Latency (CPU-Only)
-
-| Metric | Value | Notes |
-|--------|-------|-------|
-| **Initialization** | 3.71ms | Full system startup |
-| **Average Query** | 0.09ms | Single query latency |
-| **Session Query** | 0.04ms | With context reuse |
-| **Throughput** | ~38,000 q/s | 8 concurrent queries |
-| **Memory Footprint** | ~50MB | Base system |
-
-### Latency Breakdown
-
-```
-Embedding:    ~0.02ms  ████░░░░░░  (20%)
-Retrieval:    ~0.01ms  ██░░░░░░░░  (10%)
-Routing:      ~0.01ms  ██░░░░░░░░  (10%)
-Attention:    ~0.02ms  ████░░░░░░  (20%)
-Generation:   ~0.04ms  ████████░░  (40%)
-```
-
-### SONA Learning Performance
+## Key Features
 
-| Component | Metric | Value |
-|-----------|--------|-------|
-| MicroLoRA | Throughput | 2,236 ops/sec |
-| MicroLoRA | Batch-32 Latency | 0.447ms |
-| ReasoningBank | Pattern Search | 1.3ms (100 clusters) |
-| EWC++ | Fisher Update | <1ms |
+| Feature | What It Does | Why It Matters |
+|---------|-------------|----------------|
+| **Adaptive Learning** | Learns from user feedback in real-time | Improves accuracy over time without retraining |
+| **Memory System** | Stores context with instant similarity search | Finds relevant information in microseconds |
+| **Smart Routing** | Picks optimal model/settings per query | Reduces costs, improves response quality |
+| **SIMD Acceleration** | Uses CPU vector instructions (AVX2/NEON) | 10-50x faster vector operations |
+| **Federated Learning** | Train across devices without sharing data | Privacy-preserving distributed learning |
+| **LoRA Adapters** | Parameter-efficient fine-tuning with low-rank matrices | Fast adaptation with minimal memory |
+| **EWC++ Protection** | Elastic Weight Consolidation prevents forgetting | Learn new tasks without losing old knowledge |
+| **SafeTensors Export** | HuggingFace-compatible model serialization | Share models with the ML ecosystem |
+| **Training Pipeline** | Full training infrastructure with schedulers | Production-ready model training |
+| **Session Management** | Stateful conversations with streaming | Build chat applications easily |
 
-### Comparison with Traditional Systems
-
-| System | P50 (ms) | P95 (ms) | vs GPT-4o |
-|--------|----------|----------|-----------|
-| GPT-4o (API) | 450.00 | 585.00 | 1.0x (baseline) |
-| Claude 3.5 Sonnet | 380.00 | 456.00 | 1.2x |
-| Gemini 2.0 Flash | 180.00 | 234.00 | 2.5x |
-| Llama 3.3 70B (vLLM) | 120.00 | 168.00 | 3.8x |
-| **RuvLLM Orchestration** | **0.06** | **0.08** | **~7,500x** |
-
-> **Note**: RuvLLM orchestration latency measures memory retrieval, routing, and context preparation—NOT LLM generation. Actual response quality depends on your LLM backend.
-
----
-
-## Feature Comparison
-
-| Feature | GPT-4o | Claude | RAG | vLLM | RuvLLM |
-|---------|--------|--------|-----|------|--------|
-| On-device Inference | ✗ | ✗ | ✗ | ✓ | ✓ |
-| Continuous Learning | ✗ | ✗ | ✗ | ✗ | ✓ |
-| Graph-based Memory | ✗ | ✗ | △ | ✗ | ✓ |
-| Adaptive Model Routing | ✗ | ✗ | ✗ | ✗ | ✓ |
-| EWC Anti-Forgetting | ✗ | ✗ | ✗ | ✗ | ✓ |
-| LoRA Adaptation | ✗ | ✗ | ✗ | ✗ | ✓ |
-| Pattern Extraction | ✗ | ✗ | ✗ | ✗ | ✓ |
-| HuggingFace Export | ✗ | ✗ | ✗ | ✗ | ✓ |
-| SIMD Optimization | ✗ | ✗ | ✗ | △ | ✓ |
-| Sub-ms Orchestration | ✗ | ✗ | ✗ | ✗ | ✓ |
-| Federated Learning | ✗ | ✗ | ✗ | ✗ | ✓ |
-| WASM/Browser Support | ✗ | ✗ | ✗ | ✗ | ✓ |
-| Training Pipelines | ✗ | ✗ | ✗ | ✗ | ✓ |
-| Works with ANY LLM | ✗ | ✗ | ✓ | ✗ | ✓ |
-| **TRM Recursive Reasoning** | ✗ | ✗ | ✗ | ✗ | ✓ |
-| **7M Param Efficiency** | ✗ | ✗ | ✗ | ✗ | ✓ |
-
-*Legend: ✓ = Full Support, △ = Partial, ✗ = Not Supported*
-
----
-
-## Quick Start
-
-### Prerequisites
-
-- Rust 1.77+
-- Cargo
-
-### Installation
+## Installation
 
 ```bash
-# Clone the repository
-git clone https://github.com/ruvnet/ruvector.git
-cd ruvector/examples/ruvLLM
-
-# Build in release mode
-cargo build --release
+npm install @ruvector/ruvllm
 ```
 
-### Run the Demo
+Or run directly:
 
 ```bash
-# Interactive demo with mock inference
-cargo run --bin ruvllm-demo --release
-
-# SIMD capabilities demo
-cargo run --bin ruvllm-simd-demo --release
-
-# Quick benchmark
-cargo run --bin ruvllm-bench --release
-
-# Full benchmark suite
-cargo run --bin ruvllm-benchmark-suite --release
-
-# HTTP server (requires 'server' feature)
-cargo run --bin ruvllm-server --release --features server
-
-# Pretraining pipeline
-cargo run --bin ruvllm-pretrain --release
-
-# HuggingFace export (requires 'hf-export' feature)
-cargo run --bin ruvllm-export --release --features hf-export -- help
+npx @ruvector/ruvllm info
 ```
 
-### Library Usage
-
-```rust
-use ruvllm::{Config, RuvLLM, Result};
+## Quick Start Tutorial
 
-#[tokio::main]
-async fn main() -> Result<()> {
-    // Configure the system
-    let config = Config::builder()
-        .embedding_dim(768)
-        .router_hidden_dim(128)
-        .hnsw_params(32, 200, 64)  // M, ef_construction, ef_search
-        .learning_enabled(true)
-        .build()?;
+### 1. Basic Query
 
-    // Initialize
-    let llm = RuvLLM::new(config).await?;
+```typescript
+import { RuvLLM } from '@ruvector/ruvllm';
 
-    // Create a session for multi-turn conversation
-    let session = llm.new_session();
+const llm = new RuvLLM();
 
-    // Query with session context
-    let response = llm.query_session(&session, "What is machine learning?").await?;
+// Ask a question - routing happens automatically
+const response = llm.query('Explain neural networks simply');
+console.log(response.text);
+// Output: "Neural networks are computing systems inspired by..."
 
-    println!("Response: {}", response.text);
-    println!("Model: {:?}", response.routing_info.model);
-    println!("Confidence: {:.2}%", response.confidence * 100.0);
-
-    // Provide feedback for learning
-    llm.feedback(Feedback {
-        request_id: response.request_id,
-        rating: Some(5),
-        correction: None,
-        task_success: Some(true),
-    }).await?;
-
-    Ok(())
-}
+console.log(`Used model: ${response.model}`);
+console.log(`Confidence: ${(response.confidence * 100).toFixed(1)}%`);
 ```
 
-### SIMD Inference Engine
-
-```rust
-use ruvllm::{SimdInferenceEngine, SimdGenerationConfig, SimdOps};
+### 2. Teaching the System
 
-// Create SIMD-optimized engine
-let engine = SimdInferenceEngine::new(256, 128, 4, 4)?;
+```typescript
+// Query and get a response
+const response = llm.query('What is the capital of France?');
 
-// Configure generation
-let config = SimdGenerationConfig {
-    max_tokens: 50,
-    temperature: 0.7,
-    top_p: 0.9,
-    ..Default::default()
-};
+// Provide feedback - the system learns from this
+llm.feedback({
+  requestId: response.requestId,
+  rating: 5,  // 1-5 scale
+  correction: 'Paris is the capital and largest city of France'
+});
 
-// Generate with SIMD acceleration
-let result = engine.generate("Once upon a time", &config)?;
+// Future similar queries will be more accurate
 ```
 
-### SONA Learning Loops
+### 3. Using Memory
 
-```rust
-use ruvllm::sona::{LoopCoordinator, SonaConfig, InstantLoop, BackgroundLoop};
+```typescript
+// Store important context
+llm.addMemory('Company policy: All returns accepted within 30 days', {
+  category: 'policy',
+  department: 'customer-service'
+});
 
-// Initialize SONA coordinator
-let config = SonaConfig {
-    hidden_dim: 256,
-    embedding_dim: 256,
-    pattern_clusters: 100,
-    ..Default::default()
-};
+llm.addMemory('Product X launched in March 2024 with features A, B, C', {
+  category: 'product',
+  name: 'Product X'
+});
 
-let coordinator = LoopCoordinator::new(config);
-
-// Instant learning (per-request)
-coordinator.instant_loop().record_trajectory(query, response, quality);
-
-// Background learning (hourly)
-coordinator.background_loop().extract_patterns().await;
-
-// Deep learning (weekly) - automatically handles EWC++
-coordinator.deep_consolidation().await;
+// Search memory for relevant context
+const results = llm.searchMemory('return policy', 5);
+console.log(results[0].content);
+// Output: "Company policy: All returns accepted within 30 days"
+console.log(`Relevance: ${(results[0].score * 100).toFixed(1)}%`);
 ```
 
-### TRM Recursive Reasoning
-
-```rust
-use ruvllm::trm::{TrmEngine, TrmEngineBuilder, TrmConfig, RecursiveReasoner};
-
-// Build TRM engine with custom configuration
-let mut engine = TrmEngineBuilder::new()
-    .hidden_dim(256)
-    .embedding_dim(256)
-    .default_k(10)           // Default K iterations
-    .n_inner(4)              // Inner latent updates per K
-    .confidence_threshold(0.95)  // Early stopping threshold
-    .build()
-    .unwrap();
-
-// Prepare question and answer embeddings
-let question = vec![0.5; 256];  // Question embedding
-let mut answer = vec![0.1; 256]; // Initial answer (refined in-place)
-
-// Perform recursive reasoning
-let result = engine.reason(&question, &mut answer);
+### 4. Computing Similarity
 
-println!("Confidence: {:.2}%", result.confidence * 100.0);
-println!("Iterations used: {}/{}", result.iterations_used, result.max_iterations);
-println!("Early stopped: {}", result.early_stopped);
+```typescript
+import { SimdOps } from '@ruvector/ruvllm';
 
-// With SONA routing for adaptive K
-use ruvllm::trm::SonaBridge;
+const simd = new SimdOps();
 
-let bridge = SonaBridge::new(256, 256);
-let routing = bridge.compute_routing(&question, 0.8);  // quality hint
-
-let result = engine.reason_with_routing(&question, &mut answer, &routing);
-println!("Adaptive K used: {}", routing.k);
-```
-
-### Federated Learning
-
-```rust
-use ruvector_sona::training::{EphemeralAgent, FederatedCoordinator, SonaConfig};
-
-// Create central coordinator (persistent, large capacity)
-let mut coordinator = FederatedCoordinator::default_coordinator("main", 3072);
-coordinator.set_quality_threshold(0.4);  // Only accept high-quality trajectories
-coordinator.set_consolidation_interval(50);  // Auto-consolidate every 50 agents
-
-// Create ephemeral agents for distributed learning
-let mut agent = EphemeralAgent::default_federated("agent-1", 3072);
-
-// Agent processes tasks and learns locally
-agent.process_trajectory(
-    embedding,      // Query embedding
-    activations,    // Hidden state activations
-    quality,        // Quality score [0.0, 1.0]
-    Some("gpt-4".to_string()),  // Model route
-    vec!["code".to_string()],   // Context tags
+// Compare two texts
+const score = llm.similarity(
+  'How do I reset my password?',
+  'I forgot my login credentials'
 );
+console.log(`Similarity: ${(score * 100).toFixed(1)}%`);
+// Output: "Similarity: 78.3%"
 
-// Export state before agent termination
-let export = agent.export_state();
-println!("Agent exported {} trajectories", export.trajectories.len());
-
-// Coordinator aggregates learning from all agents
-let result = coordinator.aggregate(export);
-println!("Accepted: {}, Rejected: {}",
-    result.trajectories_accepted,
-    result.trajectories_rejected
-);
-
-// Get patterns for warm-starting new agents
-let patterns = coordinator.get_initial_patterns(10);
+// Fast vector operations
+const embedding1 = llm.embed('machine learning');
+const embedding2 = llm.embed('deep learning');
+const similarity = simd.cosineSimilarity(embedding1, embedding2);
 ```
 
-### WASM Usage (Browser/Edge)
+### 5. Batch Processing
 
-Build SONA for WebAssembly:
+```typescript
+// Process multiple queries efficiently
+const batch = llm.batchQuery({
+  queries: [
+    'What is AI?',
+    'Explain machine learning',
+    'How do neural networks work?'
+  ],
+  config: { temperature: 0.7 }
+});
 
-```bash
-# Build WASM package
-cd crates/sona
-wasm-pack build --target web --features wasm
+batch.responses.forEach((r, i) => {
+  console.log(`Query ${i + 1}: ${r.text.slice(0, 50)}...`);
+});
+console.log(`Total time: ${batch.totalLatencyMs}ms`);
 ```
 
-Use in JavaScript:
+## CLI Commands
 
-```javascript
-import init, { WasmSonaEngine } from './pkg/sona.js';
-
-async function main() {
-  await init();
-
-  // Create SONA engine
-  const engine = new WasmSonaEngine(256);  // hidden_dim = 256
+```bash
+# Get system information
+ruvllm info
 
-  // Or with custom configuration
-  const engineCustom = WasmSonaEngine.withConfig({
-    hidden_dim: 256,
-    embedding_dim: 256,
-    micro_lora_rank: 2,
-    base_lora_rank: 16,
-    ewc_lambda: 1000.0,
-    pattern_clusters: 128,
-  });
+# Query the model
+ruvllm query "What is quantum computing?"
 
-  // Start trajectory
-  const embedding = new Float32Array(256).fill(0.1);
-  const trajectoryId = engine.startTrajectory(embedding);
+# Generate text with custom settings
+ruvllm generate "Write a product description for:" --temperature 0.8 --max-tokens 200
 
-  // Record steps
-  engine.recordStep(trajectoryId, 42, 0.8, 1000);
+# Memory operations
+ruvllm memory add "Important fact to remember"
+ruvllm memory search "fact" --k 10
 
-  // End trajectory with quality score
-  engine.endTrajectory(trajectoryId, 0.85);
+# Compare texts
+ruvllm similarity "hello world" "hi there"
 
-  // Apply LoRA transformation
-  const input = new Float32Array(256).fill(1.0);
-  const output = engine.applyLora(input);
+# Get embeddings
+ruvllm embed "your text here"
 
-  // Run learning cycles
-  engine.runInstantCycle();  // Flush micro-LoRA updates
-  if (engine.tick()) {       // Background learning
-    console.log('Background learning completed');
-  }
+# Run performance benchmark
+ruvllm benchmark --dims 768 --iterations 5000
 
-  // Get statistics
-  const stats = engine.stats();
-  console.log('Patterns:', stats.patterns_stored);
-}
+# View statistics
+ruvllm stats --json
 ```
 
----
+## Benchmarks
 
-## HuggingFace Export
+*Benchmarked in Docker (node:20-alpine, x64) - December 2024*
 
-Export learned patterns, LoRA weights, and preference pairs to HuggingFace:
+### Core Operations
 
-```bash
-# Export LoRA weights in PEFT-compatible SafeTensors format
-ruvllm-export safetensors ./exports/lora
+| Operation | Time | Throughput |
+|-----------|------|------------|
+| Query (short) | 1.49μs | **670K ops/s** |
+| Query (long) | 874ns | **1.14M ops/s** |
+| Generate | 88ns | **11.4M ops/s** |
+| Route | 92ns | **10.9M ops/s** |
+| Embed (256d) | 10.6μs | **94K ops/s** |
+| Embed (768d) | 7.1μs | **140K ops/s** |
 
-# Export learned patterns as JSONL dataset
-ruvllm-export patterns ./exports/patterns
+### SIMD Vector Operations
 
-# Export DPO/RLHF preference pairs
-ruvllm-export preferences ./exports/preferences
+| Operation | 128d | 256d | 512d | 768d |
+|-----------|------|------|------|------|
+| Dot Product | 214ns / **4.67M ops/s** | 318ns / **3.15M ops/s** | 609ns / **1.64M ops/s** | 908ns / **1.10M ops/s** |
+| Cosine Similarity | 233ns / **4.30M ops/s** | 335ns / **2.99M ops/s** | 652ns / **1.53M ops/s** | 972ns / **1.03M ops/s** |
+| L2 Distance | 195ns / **5.14M ops/s** | 315ns / **3.18M ops/s** | 612ns / **1.63M ops/s** | 929ns / **1.08M ops/s** |
 
-# Export all artifacts
-ruvllm-export all ./exports
+### LoRA Adapter Performance
 
-# Push to HuggingFace Hub
-HF_TOKEN=your_token ruvllm-export push username/my-sona-model
+| Operation | 64d | 128d | 256d |
+|-----------|-----|------|------|
+| Forward (r=4) | 6.09μs / **164K ops/s** | 2.74μs / **365K ops/s** | 4.83μs / **207K ops/s** |
+| Forward (r=8) | 2.17μs / **462K ops/s** | 4.30μs / **233K ops/s** | 8.99μs / **111K ops/s** |
+| Forward (r=16) | 4.85μs / **206K ops/s** | 9.05μs / **111K ops/s** | 18.3μs / **55K ops/s** |
+| Backward (r=8) | - | 110μs / **9.1K ops/s** | - |
+| Batch (100) | - | 467μs / **2.1K ops/s** | - |
 
-# Generate pretraining pipeline configuration
-ruvllm-export pretrain ./exports
-```
+### Memory Operations
 
----
+| Operation | Time | Throughput |
+|-----------|------|------------|
+| Add Memory | 5.3μs | **189K ops/s** |
+| Search (k=5) | 45.6μs | **21.9K ops/s** |
+| Search (k=10) | 28.3μs | **35.3K ops/s** |
+| Search (k=20) | 33.1μs | **30.2K ops/s** |
 
-## Architecture Deep Dive
+### SONA Learning System
 
-### HNSW Memory Index
+| Operation | Time | Throughput |
+|-----------|------|------------|
+| Pattern Store | 14.4μs | **69.5K ops/s** |
+| Pattern Find Similar | 224μs | **4.5K ops/s** |
+| EWC Register Task | 6.5μs | **154K ops/s** |
+| EWC Compute Penalty | 501μs | **2.0K ops/s** |
+| Trajectory Build | 1.24μs | **807K ops/s** |
 
-The memory system uses Hierarchical Navigable Small World graphs:
+### Federated Learning
 
-```
-Layer 2:  [3] ─────────────────── [7]
-           │                       │
-Layer 1:  [3] ─── [5] ─────────── [7] ─── [9]
-           │      │                │       │
-Layer 0:  [1]─[2]─[3]─[4]─[5]─[6]─[7]─[8]─[9]─[10]
-
-• M = 32 connections per node
-• ef_construction = 200 for build quality
-• ef_search = 64 for query speed
-• O(log N) search complexity
-```
+| Operation | Time | Throughput |
+|-----------|------|------------|
+| Agent Create | 7.8μs | **128K ops/s** |
+| Process Task | 7.9μs | **126K ops/s** |
+| Apply LoRA | 12.6μs | **79.6K ops/s** |
+| Export State | 48.9μs | **20.4K ops/s** |
+| Aggregate | 5.26ms | **190 ops/s** |
 
-### FastGRNN Router
+### Session & Streaming
 
-Sparse + Low-rank matrices for efficient routing:
+| Operation | Time | Throughput |
+|-----------|------|------------|
+| Session Create | 1.45μs | **690K ops/s** |
+| Session Chat | 3.28μs | **305K ops/s** |
+| Session Export | 3.91ms | **255 ops/s** |
+| Session Import | 1.60ms | **625 ops/s** |
 
-```
-           Input (128-dim)
-                │
-        ┌───────┴───────┐
-        │  LayerNorm    │
-        └───────┬───────┘
-                │
-    ┌───────────┴───────────┐
-    │   FastGRNN Cell       │
-    │                       │
-    │  W_sparse (90% zero)  │
-    │  U = A @ B (rank-8)   │
-    │                       │
-    │  z = σ(Wx + Uh + b)   │
-    │  h' = z⊙h + (1-z)⊙ν   │
-    └───────────┬───────────┘
-                │
-        ┌───────┴───────┐
-        │ Output Heads  │
-        ├───────────────┤
-        │ Model Select  │ → 4 classes
-        │ Context Size  │ → 5 buckets
-        │ Temperature   │ → continuous
-        │ Top-p         │ → continuous
-        │ Confidence    │ → continuous
-        └───────────────┘
-```
+### Training Pipeline
 
-### MicroLoRA Architecture
+| Operation | Time |
+|-----------|------|
+| Pipeline Create | 70.6μs |
+| Add Data (100 samples) | 70.6μs |
+| Train (32 samples, 3 epochs) | 1.33s |
 
-Two-tier LoRA system for adaptive learning:
+### Export/Import
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      MicroLoRA (Rank 1-2)                   │
-│                   Per-Request Adaptation                    │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│   Input ──► Down Proj ──► Up Proj ──► Scale ──► Add        │
-│   (dim)     (dim→rank)   (rank→dim)   (α/r)    to output   │
-│                                                             │
-│   Performance: <100μs latency, 2,236 ops/sec               │
-│   Rank-2 is ~5% faster than Rank-1 (better SIMD)           │
-└─────────────────────────────────────────────────────────────┘
-
-┌─────────────────────────────────────────────────────────────┐
-│                      BaseLoRA (Rank 4-16)                   │
-│                   Background Adaptation                     │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│   Aggregated from successful MicroLoRA patterns             │
-│   Merged hourly into base weights                           │
-│   EWC++ regularization prevents forgetting                  │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
+| Operation | Time | Throughput |
+|-----------|------|------------|
+| SafeTensors Write | 67.3μs | **14.9K ops/s** |
+| SafeTensors Read | 102μs | **9.8K ops/s** |
+| LoRA to JSON | 87.9μs | **11.4K ops/s** |
+| LoRA from JSON | 86.0μs | **11.6K ops/s** |
 
-### EWC++ (Enhanced Elastic Weight Consolidation)
+### Performance Highlights
 
-Prevents catastrophic forgetting:
+- **Fastest**: Generate at **11.4M ops/s**, Route at **10.9M ops/s**
+- **Vector Ops**: Up to **5.14M ops/s** for L2 distance (128d)
+- **LoRA Forward**: Up to **462K ops/s** (64d, rank-8)
+- **Memory Search**: **35K ops/s** (k=10)
+- **Session Create**: **690K ops/s**
 
-```
-Loss = Task_Loss + λ * Σᵢ Fᵢ(θᵢ - θ*ᵢ)²
-
-Where:
-• Fᵢ = Online Fisher information (EMA decay 0.999)
-• θ*ᵢ = Optimal weights for previous tasks
-• λ = Adaptive (2000 default, range 100-15000)
-• Multi-task memory with circular buffer (10 tasks)
-• Automatic task boundary detection
-```
-
-### SIMD Operations
+## Configuration
 
-Native CPU acceleration:
+```typescript
+const llm = new RuvLLM({
+  // Embedding settings
+  embeddingDim: 768,        // Vector dimensions (384, 768, 1024)
 
-```rust
-// AVX2 dot product (8 floats at a time)
-#[target_feature(enable = "avx2")]
-unsafe fn dot_product_avx2(a: &[f32], b: &[f32]) -> f32
+  // Memory settings
+  hnswM: 16,                // Graph connectivity (higher = better recall, more memory)
+  hnswEfConstruction: 100,  // Build quality (higher = better index, slower build)
+  hnswEfSearch: 64,         // Search quality (higher = better recall, slower search)
 
-// SSE4.1 fallback (4 floats at a time)
-#[target_feature(enable = "sse4.1")]
-unsafe fn dot_product_sse(a: &[f32], b: &[f32]) -> f32
+  // Learning settings
+  learningEnabled: true,    // Enable adaptive learning
+  qualityThreshold: 0.7,    // Min confidence to skip learning
+  ewcLambda: 2000,          // Memory protection strength
 
-// Automatic detection and dispatch
-let result = SimdOps::dot_product(&a, &b);
+  // Router settings
+  routerHiddenDim: 128,     // Router network size
+});
 ```
 
----
-
-## Supported Models
+## Platform Support
 
-### Real Inference (CPU SIMD)
+Native acceleration available on:
 
-| Model | Parameters | Context | Repo |
-|-------|------------|---------|------|
-| SmolLM 135M | 135M | 2048 | HuggingFaceTB/SmolLM-135M |
-| SmolLM 360M | 360M | 2048 | HuggingFaceTB/SmolLM-360M |
-| Qwen2 0.5B | 500M | 4096 | Qwen/Qwen2-0.5B |
-| TinyLlama 1.1B | 1.1B | 2048 | TinyLlama/TinyLlama-1.1B-Chat |
+| Platform | Architecture | SIMD Support |
+|----------|-------------|--------------|
+| macOS | Apple Silicon (M1/M2/M3) | NEON |
+| macOS | Intel x64 | AVX2, SSE4.1 |
+| Linux | x64 | AVX2, AVX-512, SSE4.1 |
+| Linux | ARM64 | NEON |
+| Windows | x64 | AVX2, SSE4.1 |
 
-All models support Q4_K_M quantization for efficient CPU inference.
+Falls back to optimized JavaScript on unsupported platforms.
 
----
+## Real-World Use Cases
 
-## HTTP Server API
+### Customer Support Bot
+```typescript
+// Store FAQ and policies
+faqs.forEach(faq => llm.addMemory(faq.answer, { question: faq.question }));
 
-When running with the `server` feature:
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/health` | GET | Health check |
-| `/query` | POST | Submit query |
-| `/stats` | GET | Get statistics |
-| `/feedback` | POST | Submit feedback |
-| `/session` | POST | Create new session |
-
-```bash
-# Example query
-curl -X POST http://localhost:3000/query \
-  -H "Content-Type: application/json" \
-  -d '{"query": "What is Rust?", "session_id": null}'
+// Answer questions with context
+function answerQuestion(question: string) {
+  const context = llm.searchMemory(question, 3);
+  const prompt = `Context:\n${context.map(c => c.content).join('\n')}\n\nQuestion: ${question}`;
+  return llm.query(prompt);
+}
 ```
 
----
-
-## Testing
-
-```bash
-# Run all tests
-cargo test -p ruvllm
-
-# Unit tests only (47 tests)
-cargo test -p ruvllm --lib
-
-# Integration tests (15 tests)
-cargo test -p ruvllm --test integration
+### Document Search
+```typescript
+// Index documents
+documents.forEach(doc => {
+  llm.addMemory(doc.content, {
+    title: doc.title,
+    path: doc.path
+  });
+});
 
-# With output
-cargo test -p ruvllm -- --nocapture
+// Semantic search
+const results = llm.searchMemory('quarterly revenue growth', 10);
 ```
 
-### Test Coverage
-
-| Module | Tests | Coverage |
-|--------|-------|----------|
-| Memory (HNSW) | 12 | Search, insertion, graph expansion |
-| Router (FastGRNN) | 8 | Forward pass, training, EWC |
-| Attention | 6 | Multi-head, edge features, cross-attention |
-| Embedding | 9 | Tokenization, caching, pooling |
-| SONA | 10 | LoRA, EWC++, ReasoningBank, loops |
-| Orchestrator | 2 | End-to-end pipeline |
-| Integration | 15 | Full system tests |
-
----
-
-## Project Structure
+### Personalized Recommendations
+```typescript
+// Learn from user interactions
+function recordInteraction(userId: string, itemId: string, rating: number) {
+  const response = llm.query(`User ${userId} rated ${itemId}`);
+  llm.feedback({ requestId: response.requestId, rating });
+}
 
+// Get recommendations
+function recommend(userId: string) {
+  return llm.searchMemory(`preferences for user ${userId}`, 10);
+}
 ```
-examples/ruvLLM/
-├── Cargo.toml              # Dependencies and features
-├── README.md               # This file
-├── src/
-│   ├── lib.rs              # Library entry point
-│   ├── config.rs           # Configuration system
-│   ├── error.rs            # Error types
-│   ├── types.rs            # Core domain types
-│   ├── orchestrator.rs     # Main RuvLLM coordinator
-│   ├── memory.rs           # HNSW memory service
-│   ├── router.rs           # FastGRNN router
-│   ├── attention.rs        # Graph attention engine
-│   ├── embedding.rs        # Embedding service
-│   ├── inference.rs        # Mock inference pool
-│   ├── inference_real.rs   # Candle-based real inference
-│   ├── simd_inference.rs   # SIMD-optimized transformer
-│   ├── learning.rs         # Self-learning service
-│   ├── compression.rs      # Memory compression
-│   ├── training.rs         # Pretraining pipeline
-│   ├── trm/                # TRM (Tiny Recursive Models) module
-│   │   ├── mod.rs          # Module exports and traits
-│   │   ├── engine.rs       # Main TRM reasoning engine
-│   │   ├── config.rs       # Configuration and builder
-│   │   ├── mlp.rs          # MLP latent updater
-│   │   ├── attention.rs    # Attention latent updater
-│   │   ├── refiner.rs      # Answer refinement
-│   │   ├── confidence.rs   # Confidence scoring
-│   │   ├── sona_bridge.rs  # SONA integration
-│   │   ├── types.rs        # TRM types and results
-│   │   └── error.rs        # Error handling
-│   ├── sona/               # SONA module
-│   │   ├── mod.rs          # Module exports
-│   │   ├── types.rs        # SONA types
-│   │   ├── lora.rs         # MicroLoRA & BaseLoRA
-│   │   ├── ewc.rs          # EWC++ implementation
-│   │   ├── reasoning_bank.rs  # Pattern storage
-│   │   ├── trajectory.rs   # Trajectory recording
-│   │   ├── engine.rs       # SONA engine
-│   │   └── loops/          # Temporal learning loops
-│   │       ├── instant.rs  # Per-request loop
-│   │       ├── background.rs  # Hourly loop
-│   │       └── coordinator.rs # Loop coordinator
-│   └── bin/
-│       ├── demo.rs         # Interactive demo
-│       ├── bench.rs        # Quick benchmarks
-│       ├── benchmark_suite.rs  # Full benchmark suite
-│       ├── simd_demo.rs    # SIMD capabilities demo
-│       ├── pretrain.rs     # Pretraining pipeline
-│       ├── export.rs       # HuggingFace export
-│       └── server.rs       # HTTP server
-├── tests/
-│   └── integration.rs      # Integration tests
-├── benches/
-│   ├── pipeline.rs         # Full pipeline benchmarks
-│   ├── router.rs           # Router benchmarks
-│   ├── memory.rs           # Memory benchmarks
-│   ├── attention.rs        # Attention benchmarks
-│   ├── sona_bench.rs       # SONA benchmarks
-│   └── trm_bench.rs        # TRM benchmarks
-├── config/                 # Configuration files
-└── docs/
-    └── sparc/              # SPARC methodology docs
-```
-
----
-
-## Feature Flags
-
-### RuvLLM Features
-
-| Feature | Default | Description |
-|---------|---------|-------------|
-| `storage` | ✓ | Persistent storage and HNSW indexing |
-| `metrics` | ✓ | Prometheus metrics export |
-| `server` | ✗ | HTTP server with Axum |
-| `real-inference` | ✗ | Candle-based real LLM inference |
-| `hf-export` | ✗ | HuggingFace export via ruvector-sona |
-| `full` | ✗ | All features enabled |
 
+## API Reference
+
+### RuvLLM Class
+
+| Method | Description |
+|--------|-------------|
+| `query(text, config?)` | Query with automatic model routing |
+| `generate(prompt, config?)` | Generate text with given prompt |
+| `route(text)` | Get routing decision without executing |
+| `addMemory(content, metadata?)` | Store content in vector memory |
+| `searchMemory(text, k?)` | Find similar content (default k=10) |
+| `feedback(fb)` | Submit feedback for learning |
+| `embed(text)` | Get embedding vector for text |
+| `similarity(t1, t2)` | Compute similarity between texts |
+| `stats()` | Get engine statistics |
+| `forceLearn()` | Trigger immediate learning cycle |
+
+### SimdOps Class
+
+| Method | Description |
+|--------|-------------|
+| `dotProduct(a, b)` | Vector dot product |
+| `cosineSimilarity(a, b)` | Cosine similarity (0-1) |
+| `l2Distance(a, b)` | Euclidean distance |
+| `normalize(v)` | Normalize to unit length |
+| `softmax(v)` | Softmax activation |
+| `relu(v)` | ReLU activation |
+| `gelu(v)` | GELU activation |
+| `layerNorm(v, eps?)` | Layer normalization |
+| `matvec(m, v)` | Matrix-vector multiply |
+
+## Troubleshooting
+
+**Q: Native module not loading?**
 ```bash
-# Build with all features
-cargo build --release --features full
+ruvllm info  # Check if native is loaded
 ```
-
-### ruvector-sona Features (Dependency)
-
-| Feature | Default | Description |
-|---------|---------|-------------|
-| `serde-support` | ✓ | Serialization for export, training, and federated learning |
-| `wasm` | ✗ | WebAssembly bindings for browser/edge deployment |
-| `napi` | ✗ | N-API bindings for Node.js integration |
-
+If "Native: Fallback", install platform-specific package manually:
 ```bash
-# Build SONA with WASM support
-cd crates/sona
-wasm-pack build --target web --features wasm
+npm install @ruvector/ruvllm-darwin-arm64  # For Apple Silicon
 ```
 
----
-
-## Configuration Options
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `embedding.dimension` | 768 | Embedding vector size |
-| `embedding.max_tokens` | 512 | Max tokens per input |
-| `memory.hnsw_m` | 16 | HNSW connections per node |
-| `memory.hnsw_ef_construction` | 100 | Build quality parameter |
-| `memory.hnsw_ef_search` | 64 | Search quality parameter |
-| `router.input_dim` | 128 | Router input features |
-| `router.hidden_dim` | 64 | FastGRNN hidden size |
-| `router.sparsity` | 0.9 | Weight matrix sparsity |
-| `router.rank` | 8 | Low-rank decomposition |
-| `learning.enabled` | true | Enable self-learning |
-| `learning.quality_threshold` | 0.7 | Min quality for writeback |
-| `learning.ewc_lambda` | 2000 | EWC regularization strength |
-| `sona.pattern_clusters` | 100 | K-means++ clusters |
-| `sona.micro_lora_rank` | 2 | MicroLoRA rank |
-
-### Federated Learning Configuration
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `federated.quality_threshold` | 0.4 | Min quality for trajectory acceptance |
-| `federated.consolidation_interval` | 50 | Auto-consolidate every N agents |
-| `federated.coordinator_capacity` | 50000 | Trajectory buffer size for coordinator |
-| `federated.agent_capacity` | 500 | Trajectory buffer size per agent |
-| `federated.base_lora_rank` | 16 | Coordinator LoRA rank (deeper for aggregation) |
-
----
-
-## Self-Learning Improvement Over Time
-
-| Epoch | Queries | Quality | Routing | Cache Hit | Memory | Improvement |
-|-------|---------|---------|---------|-----------|--------|-------------|
-| 0 | 0 | 65.0% | 50.0% | 0.0% | 0 | 0.0% (baseline) |
-| 1 | 50 | 67.2% | 58.0% | 10.0% | 25 | +3.4% |
-| 2 | 100 | 69.8% | 66.0% | 20.0% | 50 | +7.4% |
-| 3 | 150 | 71.5% | 74.0% | 30.0% | 75 | +10.0% |
-| 4 | 200 | 73.2% | 82.0% | 40.0% | 100 | +12.6% |
-| 5 | 250 | 74.8% | 90.0% | 50.0% | 125 | +15.1% |
-
----
-
-## References
-
-- [TinyRecursiveModels](https://github.com/SamsungSAILMontreal/TinyRecursiveModels) - Samsung SAIL Montreal's recursive reasoning approach
-- [LFM2: Liquid Foundation Models](https://arxiv.org/abs/2511.23404v1) - Gated convolutions + grouped query attention
-- [FastGRNN](https://arxiv.org/abs/1901.02358) - Fast, Accurate, Stable and Tiny GRU
-- [HNSW](https://arxiv.org/abs/1603.09320) - Hierarchical Navigable Small World Graphs
-- [EWC](https://arxiv.org/abs/1612.00796) - Elastic Weight Consolidation
-- [LoRA](https://arxiv.org/abs/2106.09685) - Low-Rank Adaptation of Large Language Models
-
----
-
-## License
-
-Licensed under either of:
-
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+**Q: Memory usage too high?**
+Reduce HNSW parameters:
+```typescript
+const llm = new RuvLLM({ hnswM: 8, hnswEfConstruction: 50 });
+```
 
-at your option.
+**Q: Learning not improving results?**
+Check that feedback is being processed:
+```typescript
+const stats = llm.stats();
+console.log(`Patterns learned: ${stats.patternsLearned}`);
+```
 
-## Contributing
+## License
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+MIT OR Apache-2.0
 
----
+## Links
 
-<p align="center">
-  <b>Built with Rust + Ruvector</b><br>
-  <i>Self-Learning AI that gets smarter with every interaction</i>
-</p>
+- [GitHub Repository](https://github.com/ruvnet/ruvector)
+- [Documentation](https://github.com/ruvnet/ruvector/tree/main/examples/ruvLLM)
+- [Issue Tracker](https://github.com/ruvnet/ruvector/issues)