@ruvector/ruvllm 0.2.4 → 2.4.0

package/README.md

@@ -1,406 +1,526 @@
-# @ruvector/ruvllm
+# @ruvector/ruvllm v2.4
 
-**Build AI that learns and improves from every interaction.**
+Self-learning LLM orchestration with SONA adaptive learning, HNSW memory, RLM recursive retrieval, and SIMD inference for Node.js.
 
-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.
-
-## What Makes RuvLLM Different?
-
-Traditional LLMs forget old knowledge when learning new things (called "catastrophic forgetting"). RuvLLM solves this with three key innovations:
+## Installation
 
-1. **It Learns Without Forgetting** - Uses tiny parameter updates (LoRA) and memory protection (EWC++) to learn new patterns while preserving existing knowledge
+```bash
+npm install @ruvector/ruvllm
+```
 
-2. **It Remembers Context** - Built-in vector memory stores and retrieves relevant information instantly using similarity search
+## Quick Start
 
-3. **It Routes Intelligently** - Automatically selects the right model size and parameters based on query complexity, saving resources on simple tasks
+```typescript
+import { RuvLLM, RuvLLMConfig } from '@ruvector/ruvllm';
 
-## Key Features
+// Initialize with default configuration
+const llm = new RuvLLM();
 
-| 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 |
+// Or with custom configuration
+const llm = new RuvLLM({
+  modelPath: './models/ruvltra-small-q4km.gguf',
+  sonaEnabled: true,
+  flashAttention: true,
+  maxTokens: 256,
+});
 
-## Installation
+// Generate text
+const response = await llm.query('Explain quantum computing');
+console.log(response.text);
 
-```bash
-npm install @ruvector/ruvllm
+// Stream generation
+for await (const token of llm.stream('Write a haiku about Rust')) {
+  process.stdout.write(token);
+}
 ```
 
-Or run directly:
+## What's New in v2.4
 
-```bash
-npx @ruvector/ruvllm info
-```
+| Feature | Description |
+|---------|-------------|
+| **RLM (Recursive Language Model)** | Query decomposition with recursive retrieval and synthesis |
+| **100% Routing Accuracy** | Hybrid keyword-first strategy achieves 100% on Claude Code tasks |
+| **145 Tests Passing** | Comprehensive test coverage across all modules |
+| **Contrastive Fine-tuning** | LoRA-based training with 793 contrastive pairs |
+| **Training Scripts** | Generate routing datasets and fine-tune models |
+| **HuggingFace Models** | Pre-trained RuvLTRA models available |
+
+## RLM (Recursive Language Model)
 
-## Quick Start Tutorial
+RLM provides recursive retrieval-augmented generation that breaks down complex queries into sub-queries and synthesizes answers from retrieved context.
 
-### 1. Basic Query
+### Basic Usage
 
 ```typescript
-import { RuvLLM } from '@ruvector/ruvllm';
+import { RlmController } from '@ruvector/ruvllm';
 
-const llm = new RuvLLM();
+const rlm = new RlmController({
+  maxDepth: 5,
+  retrievalTopK: 10,
+  enableCache: true,
+});
 
-// 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..."
+// Add knowledge to memory
+await rlm.addMemory('TypeScript adds static typing to JavaScript.');
+await rlm.addMemory('React is a library for building user interfaces.');
 
-console.log(`Used model: ${response.model}`);
-console.log(`Confidence: ${(response.confidence * 100).toFixed(1)}%`);
+// Query with recursive retrieval
+const answer = await rlm.query('What are causes and solutions for type errors in React?');
+console.log(answer.text);
+console.log('Sources:', answer.sources);
+console.log('Quality Score:', answer.qualityScore);
+console.log('Confidence:', answer.confidence);
 ```
 
-### 2. Teaching the System
+### Streaming
 
 ```typescript
-// Query and get a response
-const response = llm.query('What is the capital of France?');
-
-// 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'
-});
+import { RlmController } from '@ruvector/ruvllm';
+
+const rlm = new RlmController();
 
-// Future similar queries will be more accurate
+for await (const event of rlm.queryStream('Explain machine learning')) {
+  if (event.type === 'token') {
+    process.stdout.write(event.text);
+  } else {
+    console.log('\n\nQuality:', event.answer.qualityScore);
+  }
+}
 ```
 
-### 3. Using Memory
+### With Reflection
 
 ```typescript
-// Store important context
-llm.addMemory('Company policy: All returns accepted within 30 days', {
-  category: 'policy',
-  department: 'customer-service'
-});
+import { RlmController } from '@ruvector/ruvllm';
 
-llm.addMemory('Product X launched in March 2024 with features A, B, C', {
-  category: 'product',
-  name: 'Product X'
+const rlm = new RlmController({
+  enableReflection: true,
+  maxReflectionIterations: 2,
+  minQualityScore: 0.8,
 });
 
-// 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)}%`);
+// Answers will be iteratively refined until quality >= 0.8
+const answer = await rlm.query('Complex multi-part technical question...');
 ```
 
-### 4. Computing Similarity
+### RLM Configuration
 
 ```typescript
-import { SimdOps } from '@ruvector/ruvllm';
-
-const simd = new SimdOps();
+interface RlmConfig {
+  maxDepth?: number;              // Max recursion depth (default: 3)
+  maxSubQueries?: number;         // Max sub-queries per level (default: 5)
+  tokenBudget?: number;           // Token budget (default: 4096)
+  enableCache?: boolean;          // Enable caching (default: true)
+  cacheTtl?: number;              // Cache TTL in ms (default: 300000)
+  retrievalTopK?: number;         // Memory spans to retrieve (default: 10)
+  minQualityScore?: number;       // Min quality threshold (default: 0.7)
+  enableReflection?: boolean;     // Enable self-reflection (default: false)
+  maxReflectionIterations?: number; // Max reflection loops (default: 2)
+}
+```
 
-// 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%"
+## Exports
 
-// Fast vector operations
-const embedding1 = llm.embed('machine learning');
-const embedding2 = llm.embed('deep learning');
-const similarity = simd.cosineSimilarity(embedding1, embedding2);
+```typescript
+import {
+  // Core
+  RuvLLM,
+  RuvLLMConfig,
+
+  // RLM - Recursive Language Model
+  RlmController,
+  RlmConfig,
+  RlmAnswer,
+  MemorySpan,
+  StreamToken,
+
+  // RLM Training
+  RlmTrainer,
+  RlmTrainingConfig,
+  RlmTrainingExample,
+  createRlmTrainer,
+  DEFAULT_RLM_CONFIG,
+  FAST_RLM_CONFIG,
+  THOROUGH_RLM_CONFIG,
+  ROUTING_FOCUSED_CONFIG,
+
+  // SONA Learning
+  SonaCoordinator,
+  TrajectoryBuilder,
+
+  // Federated Learning
+  EphemeralAgent,
+  FederatedCoordinator,
+
+  // LoRA Adapters
+  LoraAdapter,
+  LoraManager,
+
+  // Sessions
+  SessionManager,
+
+  // Contrastive Training
+  ContrastiveTrainer,
+
+  // Benchmarks
+  ModelComparisonBenchmark,
+  RoutingBenchmark,
+  EmbeddingBenchmark,
+} from '@ruvector/ruvllm';
 ```
 
-### 5. Batch Processing
+## Performance
 
-```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 }
-});
+### Test Results
 
-batch.responses.forEach((r, i) => {
-  console.log(`Query ${i + 1}: ${r.text.slice(0, 50)}...`);
-});
-console.log(`Total time: ${batch.totalLatencyMs}ms`);
+```
+145 tests passing
+  - RLM Controller: 24 tests
+  - Routing Accuracy: 18 tests
+  - Contrastive Training: 15 tests
+  - SIMD Operations: 22 tests
+  - SONA Learning: 19 tests
+  - Memory/HNSW: 21 tests
+  - Benchmarks: 26 tests
 ```
 
-## CLI Commands
+### Routing Accuracy (Claude Code Tasks)
 
-```bash
-# Get system information
-ruvllm info
+| Strategy | RuvLTRA | Qwen Base |
+|----------|---------|-----------|
+| Embedding Only | 45% | 40% |
+| Keyword-First (Hybrid) | **100%** | 95% |
 
-# Query the model
-ruvllm query "What is quantum computing?"
+### Inference Performance (M4 Pro)
 
-# Generate text with custom settings
-ruvllm generate "Write a product description for:" --temperature 0.8 --max-tokens 200
+| Operation | Performance |
+|-----------|-------------|
+| Inference | 88-135 tok/s |
+| Flash Attention | 320us (seq=2048) |
+| HNSW Search | 17-62us |
+| SONA Adapt | <1ms |
+| RLM Query | 50-200ms |
 
-# Memory operations
-ruvllm memory add "Important fact to remember"
-ruvllm memory search "fact" --k 10
+### SIMD Optimizations
 
-# Compare texts
-ruvllm similarity "hello world" "hi there"
+- AVX2/AVX-512 on x86_64
+- NEON on ARM64
+- 4-8x speedup on vector operations
 
-# Get embeddings
-ruvllm embed "your text here"
+## CLI Usage
 
-# Run performance benchmark
-ruvllm benchmark --dims 768 --iterations 5000
+```bash
+# Query a model
+ruvllm query "What is machine learning?"
 
-# View statistics
-ruvllm stats --json
-```
+# Stream output
+ruvllm query --stream "Write a poem"
 
-## Benchmarks
+# Download a model
+ruvllm download ruvector/ruvltra-small-q4km
 
-*Benchmarked in Docker (node:20-alpine, x64) - December 2024*
+# Benchmark
+ruvllm bench ./models/model.gguf
 
-### Core Operations
+# Run evaluation (SWE-Bench)
+ruvllm eval --model ./models/model.gguf --subset lite --max-tasks 50
+```
 
-| 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** |
+## Training
 
-### SIMD Vector Operations
+### Routing Dataset Generation
 
-| 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** |
+Generate training data for agent routing:
 
-### LoRA Adapter Performance
+```bash
+# Generate routing dataset
+node scripts/training/routing-dataset.js
 
-| 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** | - |
+# Output: 381 examples, 793 contrastive pairs
+```
 
-### Memory Operations
+### Contrastive Fine-tuning
 
-| 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** |
+Fine-tune models with LoRA adapters:
 
-### SONA Learning System
+```typescript
+import { ContrastiveTrainer, ContrastivePair } from '@ruvector/ruvllm';
 
-| 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** |
+const trainer = new ContrastiveTrainer({
+  modelPath: './models/base.gguf',
+  loraRank: 8,
+  loraAlpha: 16,
+  learningRate: 1e-4,
+});
 
-### Federated Learning
+// Training pairs from routing dataset
+const pairs: ContrastivePair[] = [
+  {
+    anchor: 'Fix the authentication bug in login.ts',
+    positive: 'coder',
+    negative: 'researcher',
+  },
+  // ... more pairs
+];
+
+await trainer.train(pairs, { epochs: 10, batchSize: 32 });
+await trainer.save('./adapters/routing-lora');
+```
 
-| 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** |
+### Training Scripts
 
-### Session & Streaming
+Located in `scripts/training/`:
 
-| 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** |
+| Script | Description |
+|--------|-------------|
+| `routing-dataset.js` | Generate 381 routing examples |
+| `claude-code-synth.js` | Synthetic data generation |
+| `contrastive-finetune.js` | LoRA fine-tuning pipeline |
 
-### Training Pipeline
+## Model Links
 
-| Operation | Time |
-|-----------|------|
-| Pipeline Create | 70.6μs |
-| Add Data (100 samples) | 70.6μs |
-| Train (32 samples, 3 epochs) | 1.33s |
+### HuggingFace Repository
 
-### Export/Import
+**URL**: [https://huggingface.co/ruv/ruvltra](https://huggingface.co/ruv/ruvltra)
 
-| 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** |
+### Available Models
 
-### Performance Highlights
+| Model | File | Size | Purpose |
+|-------|------|------|---------|
+| RuvLTRA Claude Code 0.5B | `ruvltra-claude-code-0.5b-q4_k_m.gguf` | ~400MB | Agent routing (100% with hybrid) |
+| RuvLTRA Small 0.5B | `ruvltra-0.5b-q4_k_m.gguf` | ~400MB | General embeddings |
+| RuvLTRA Medium 3B | `ruvltra-3b-q4_k_m.gguf` | ~2GB | Full LLM inference |
 
-- **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**
+### Download Models
 
-## Configuration
+```bash
+# Using CLI
+ruvllm download ruv/ruvltra
 
-```typescript
-const llm = new RuvLLM({
-  // Embedding settings
-  embeddingDim: 768,        // Vector dimensions (384, 768, 1024)
+# Using HuggingFace CLI
+huggingface-cli download ruv/ruvltra ruvltra-claude-code-0.5b-q4_k_m.gguf
 
-  // 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)
+# Programmatic download
+import { downloadModel } from '@ruvector/ruvllm';
+await downloadModel('ruv/ruvltra', { quantization: 'q4_k_m' });
+```
 
-  // Learning settings
-  learningEnabled: true,    // Enable adaptive learning
-  qualityThreshold: 0.7,    // Min confidence to skip learning
-  ewcLambda: 2000,          // Memory protection strength
+### Environment Variables
 
-  // Router settings
-  routerHiddenDim: 128,     // Router network size
-});
+```bash
+# HuggingFace authentication (any of these)
+HF_TOKEN=hf_xxx
+HUGGING_FACE_HUB_TOKEN=hf_xxx
+HUGGINGFACE_API_KEY=hf_xxx
 ```
 
-## Platform Support
-
-Native acceleration available on:
+### Local Model Storage
 
-| 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 |
+```bash
+~/.ruvllm/models/       # Downloaded GGUF models
+~/.ruvllm/training/     # Training data and configs
+```
 
-Falls back to optimized JavaScript on unsupported platforms.
+## API Reference
 
-## Real-World Use Cases
+### RuvLLM Class
 
-### Customer Support Bot
 ```typescript
-// Store FAQ and policies
-faqs.forEach(faq => llm.addMemory(faq.answer, { question: faq.question }));
-
-// 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);
+class RuvLLM {
+  constructor(config?: RuvLLMConfig);
+
+  // Generate text
+  query(prompt: string, params?: GenerateParams): Promise<Response>;
+
+  // Stream generation
+  stream(prompt: string, params?: GenerateParams): AsyncIterable<string>;
+
+  // Load a model
+  loadModel(path: string): Promise<void>;
+
+  // Memory operations
+  addMemory(text: string, metadata?: Record<string, unknown>): number;
+  searchMemory(query: string, topK?: number): MemoryResult[];
+
+  // Get SONA learning stats
+  sonaStats(): SonaStats | null;
+
+  // Adapt on feedback
+  adapt(input: Float32Array, quality: number): void;
 }
 ```
 
-### Document Search
+### RlmController Class
+
 ```typescript
-// Index documents
-documents.forEach(doc => {
-  llm.addMemory(doc.content, {
-    title: doc.title,
-    path: doc.path
-  });
-});
+class RlmController {
+  constructor(config?: RlmConfig, engine?: RuvLLM);
+
+  // Query with recursive retrieval
+  query(input: string): Promise<RlmAnswer>;
+
+  // Stream query
+  queryStream(input: string): AsyncGenerator<StreamToken>;
+
+  // Memory management
+  addMemory(text: string, metadata?: Record<string, unknown>): Promise<string>;
+  searchMemory(query: string, topK?: number): Promise<MemorySpan[]>;
 
-// Semantic search
-const results = llm.searchMemory('quarterly revenue growth', 10);
+  // Cache management
+  clearCache(): void;
+  getCacheStats(): { size: number; entries: number };
+
+  // Configuration
+  updateConfig(config: Partial<RlmConfig>): void;
+  getConfig(): Required<RlmConfig>;
+}
 ```
 
-### Personalized Recommendations
+### Configuration
+
 ```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 });
+interface RuvLLMConfig {
+  modelPath?: string;       // Path to GGUF model
+  sonaEnabled?: boolean;    // Enable SONA learning (default: true)
+  flashAttention?: boolean; // Use Flash Attention 2 (default: true)
+  maxTokens?: number;       // Max generation tokens (default: 256)
+  temperature?: number;     // Sampling temperature (default: 0.7)
+  topP?: number;            // Top-p sampling (default: 0.9)
 }
+```
+
+### Generate Parameters
 
-// Get recommendations
-function recommend(userId: string) {
-  return llm.searchMemory(`preferences for user ${userId}`, 10);
+```typescript
+interface GenerateParams {
+  maxTokens?: number;
+  temperature?: number;
+  topP?: number;
+  topK?: number;
+  repetitionPenalty?: number;
+  stopSequences?: string[];
 }
 ```
 
-## API Reference
+## SIMD Module
 
-### RuvLLM Class
+For direct access to optimized SIMD kernels:
 
-| 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
-ruvllm info  # Check if native is loaded
-```
-If "Native: Fallback", install platform-specific package manually:
-```bash
-npm install @ruvector/ruvllm-darwin-arm64  # For Apple Silicon
+```typescript
+import { simd } from '@ruvector/ruvllm/simd';
+
+// Dot product
+const result = simd.dotProduct(vecA, vecB);
+
+// Matrix multiplication
+const output = simd.matmul(matrix, vector);
+
+// Flash Attention
+const attended = simd.flashAttention(query, key, value, scale);
+
+// RMS Normalization
+simd.rmsNorm(hidden, weights, epsilon);
 ```
 
-**Q: Memory usage too high?**
-Reduce HNSW parameters:
+## Evaluation Harness
+
+Run model evaluations with SWE-Bench integration:
+
 ```typescript
-const llm = new RuvLLM({ hnswM: 8, hnswEfConstruction: 50 });
+import { RuvLLM, EvaluationHarness, AblationMode } from '@ruvector/ruvllm';
+
+const harness = new EvaluationHarness({
+  modelPath: './models/model.gguf',
+  enableHnsw: true,
+  enableSona: true,
+});
+
+// Run single evaluation
+const result = await harness.evaluate(
+  'Fix the null pointer exception',
+  'def process(data): return data.split()',
+  AblationMode.Full
+);
+
+console.log(`Success: ${result.success}, Quality: ${result.qualityScore}`);
+
+// Run ablation study (Baseline, RetrievalOnly, AdaptersOnly, R+A, Full)
+const report = await harness.runAblationStudy(tasks);
+for (const [mode, metrics] of Object.entries(report.modeMetrics)) {
+  console.log(`${mode}: ${metrics.successRate * 100}% success`);
+}
 ```
 
-**Q: Learning not improving results?**
-Check that feedback is being processed:
+## mistral-rs Backend (Production Serving)
+
+For production deployments with 10-100+ concurrent users, use the mistral-rs backend:
+
 ```typescript
-const stats = llm.stats();
-console.log(`Patterns learned: ${stats.patternsLearned}`);
+import { RuvLLM, MistralBackend, PagedAttentionConfig } from '@ruvector/ruvllm';
+
+// Configure for production serving
+const backend = new MistralBackend({
+  // PagedAttention: 5-10x more concurrent users
+  pagedAttention: {
+    blockSize: 16,
+    maxBlocks: 4096,
+    gpuMemoryFraction: 0.9,
+    prefixCaching: true,
+  },
+  // X-LoRA: Per-token adapter routing
+  xlora: {
+    adapters: ['./adapters/coder', './adapters/researcher'],
+    topK: 2,
+  },
+  // ISQ: Runtime quantization
+  isq: {
+    bits: 4,
+    method: 'awq',
+  },
+});
+
+const llm = new RuvLLM({ backend });
+await llm.loadModel('mistralai/Mistral-7B-Instruct-v0.2');
+
+// Serve multiple concurrent requests
+const response = await llm.query('Write production code');
 ```
 
-## License
+> **Note**: mistral-rs features require the Rust backend with `mistral-rs` feature enabled. Native bindings will use mistral-rs when available.
 
-MIT OR Apache-2.0
+## Supported Models
+
+- **RuvLTRA-Small** (494M) - Q4K, Q5K, Q8
+- **RuvLTRA-Medium** (3B) - Q4K, Q5K, Q8
+- **Qwen 2.5** (0.5B-72B)
+- **Llama 3.x** (8B-70B)
+- **Mistral** (7B-22B)
+- **Phi-3** (3.8B-14B)
+- **Gemma-2** (2B-27B)
+
+## Platform Support
+
+| Platform | Architecture | Status |
+|----------|--------------|--------|
+| macOS | arm64 (M1-M4) | Full support |
+| macOS | x64 | Supported |
+| Linux | x64 | Supported |
+| Linux | arm64 | Supported |
+| Windows | x64 | Supported |
+
+## Related Packages
+
+- [@ruvector/core](https://www.npmjs.com/package/@ruvector/core) - Vector operations
+- [@ruvector/sona](https://www.npmjs.com/package/@ruvector/sona) - SONA learning engine
+- [@ruvector/ruvector](https://www.npmjs.com/package/@ruvector/ruvector) - Full Ruvector SDK
 
 ## Links
 
 - [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)
+- [HuggingFace Models](https://huggingface.co/ruv/ruvltra)
+- [API Documentation](https://docs.rs/ruvllm)
+- [Crate (Rust)](https://crates.io/crates/ruvllm)
+
+## License
+
+MIT OR Apache-2.0