{"_id":"@aigentic/ruvllm","_rev":"3-647c0724579e1237a6e1b62340835adb","name":"@aigentic/ruvllm","dist-tags":{"latest":"2.5.6"},"versions":{"2.5.5":{"name":"@aigentic/ruvllm","version":"2.5.5","keywords":["ruvllm","llm","self-learning","adaptive-learning","sona","lora","ewc","hnsw","vector-database","fastgrnn","router","simd","inference","federated-learning","continual-learning","machine-learning","ai","deep-learning","napi","rust","ruvector","turboquant","kv-cache","quantization","flash-attention","speculative-decoding","gguf","mamba","transformer","edge-ai","local-llm","model-compression"],"author":{"name":"rUv Team","email":"team@ruv.io"},"license":"MIT OR Apache-2.0","_id":"@aigentic/ruvllm@2.5.5","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"homepage":"https://github.com/ruvnet/ruvector/tree/main/examples/ruvLLM","bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"bin":{"ruvllm":"bin/cli.js"},"dist":{"shasum":"6c12f8f489607e473611abc0764451aa09e058f9","tarball":"https://registry.npmjs.org/@aigentic/ruvllm/-/ruvllm-2.5.5.tgz","fileCount":135,"integrity":"sha512-w41shoO0sc1odog4d/IY6FlzQ/h15rZRR5eZ0jav/tkaMHSWqeiOZbVEnbz0l/VBZJGg/NhCsPSMjK4dfaguxg==","signatures":[{"sig":"MEUCIDRxFtv24BX6JqOg6a2SgSdd/LVp+uRDc/w0KAnYdi8XAiEAy6G7qRI5DHV9oe7sGSku9Ti/fWA5PXEe2w3AnRp/ufM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2406681},"main":"dist/cjs/index.js","napi":{"targets":["x86_64-unknown-linux-gnu","aarch64-unknown-linux-gnu","x86_64-apple-darwin","aarch64-apple-darwin","x86_64-pc-windows-msvc"],"binaryName":"ruvllm"},"types":"dist/cjs/index.d.ts","module":"dist/esm/index.js","engines":{"node":">= 18"},"exports":{".":{"import":{"types":"./dist/esm/index.d.ts","default":"./dist/esm/index.js"},"require":{"types":"./dist/cjs/index.d.ts","default":"./dist/cjs/index.js"}},"./simd":{"import":{"types":"./dist/esm/simd.d.ts","default":"./dist/esm/simd.js"},"require":{"types":"./dist/cjs/simd.d.ts","default":"./dist/cjs/simd.js"}}},"gitHead":"06426cbc6e70f09762e996a98517b0b1fd1c7c4e","scripts":{"test":"node --test test/*.test.js","build":"npm run build:cjs && npm run build:esm","clean":"rm -rf dist","version":"napi version","artifacts":"napi artifacts","build:cjs":"tsc","build:esm":"tsc -p tsconfig.esm.json","typecheck":"tsc --noEmit","universal":"napi universal","build:debug":"napi build --platform -p ruvllm --manifest-path ../../../examples/ruvLLM/Cargo.toml -F napi","build:native":"napi build --platform --release -p ruvllm --manifest-path ../../../examples/ruvLLM/Cargo.toml -F napi","prepublishOnly":"npm run build"},"_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git","directory":"npm/packages/ruvllm"},"_npmVersion":"11.12.0","description":"Self-learning LLM runtime — TurboQuant KV-cache (6-8x compression), SONA adaptive learning, FlashAttention, speculative decoding, GGUF inference","directories":{},"_nodeVersion":"22.22.1","dependencies":{"ora":"^5.4.1","chalk":"^4.1.2","commander":"^12.0.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.3","@types/node":"^20.10.5","@napi-rs/cli":"^2.18.0"},"optionalDependencies":{"@aigentic/ruvllm-darwin-x64":"2.0.1","@aigentic/ruvllm-darwin-arm64":"2.0.1","@aigentic/ruvllm-linux-x64-gnu":"2.0.1","@aigentic/ruvllm-win32-x64-msvc":"2.0.1","@aigentic/ruvllm-linux-arm64-gnu":"2.0.1"},"_npmOperationalInternal":{"tmp":"tmp/ruvllm_2.5.5_1779091171104_0.7201450057190077","host":"s3://npm-registry-packages-npm-production"}},"2.5.6":{"name":"@aigentic/ruvllm","version":"2.5.6","keywords":["ruvllm","llm","self-learning","adaptive-learning","sona","lora","ewc","hnsw","vector-database","fastgrnn","router","simd","inference","federated-learning","continual-learning","machine-learning","ai","deep-learning","napi","rust","ruvector","turboquant","kv-cache","quantization","flash-attention","speculative-decoding","gguf","mamba","transformer","edge-ai","local-llm","model-compression"],"author":{"name":"rUv Team","email":"team@ruv.io"},"license":"MIT OR Apache-2.0","_id":"@aigentic/ruvllm@2.5.6","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"homepage":"https://github.com/ruvnet/ruvector/tree/main/examples/ruvLLM","bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"bin":{"ruvllm":"bin/cli.js"},"dist":{"shasum":"a2653ed66de57de5a536987404903ace0b34502e","tarball":"https://registry.npmjs.org/@aigentic/ruvllm/-/ruvllm-2.5.6.tgz","fileCount":135,"integrity":"sha512-0VXT1pT3Gc+9jNngzml2rAJPgreGNi3flB0jU4dGitigtEAWMblOf+pdEENl8JNQjt6Ar1BzZGYa64eUtKzUmw==","signatures":[{"sig":"MEUCIQD+4oUwKZRCNatoVTxj2UTOjEY5b+8TBiL6waPtkzU66QIgCLfRPw7PZ3zTHs2g5EDwKzHpJP8QBZHIKu5tJF7Ob4Q=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2406681},"main":"dist/cjs/index.js","napi":{"targets":["x86_64-unknown-linux-gnu","aarch64-unknown-linux-gnu","x86_64-apple-darwin","aarch64-apple-darwin","x86_64-pc-windows-msvc"],"binaryName":"ruvllm"},"types":"dist/cjs/index.d.ts","module":"dist/esm/index.js","engines":{"node":">= 18"},"exports":{".":{"import":{"types":"./dist/esm/index.d.ts","default":"./dist/esm/index.js"},"require":{"types":"./dist/cjs/index.d.ts","default":"./dist/cjs/index.js"}},"./simd":{"import":{"types":"./dist/esm/simd.d.ts","default":"./dist/esm/simd.js"},"require":{"types":"./dist/cjs/simd.d.ts","default":"./dist/cjs/simd.js"}}},"gitHead":"06426cbc6e70f09762e996a98517b0b1fd1c7c4e","scripts":{"test":"node --test test/*.test.js","build":"npm run build:cjs && npm run build:esm","clean":"rm -rf dist","version":"napi version","artifacts":"napi artifacts","build:cjs":"tsc","build:esm":"tsc -p tsconfig.esm.json","typecheck":"tsc --noEmit","universal":"napi universal","build:debug":"napi build --platform -p ruvllm --manifest-path ../../../examples/ruvLLM/Cargo.toml -F napi","build:native":"napi build --platform --release -p ruvllm --manifest-path ../../../examples/ruvLLM/Cargo.toml -F napi","prepublishOnly":"npm run build"},"_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git","directory":"npm/packages/ruvllm"},"_npmVersion":"11.12.0","description":"Self-learning LLM runtime — TurboQuant KV-cache (6-8x compression), SONA adaptive learning, FlashAttention, speculative decoding, GGUF inference","directories":{},"_nodeVersion":"22.22.1","dependencies":{"ora":"^5.4.1","chalk":"^4.1.2","commander":"^12.0.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.3.3","@types/node":"^20.10.5","@napi-rs/cli":"^2.18.0"},"optionalDependencies":{"@aigentic/ruvllm-darwin-x64":"2.0.1","@aigentic/ruvllm-darwin-arm64":"2.0.1","@aigentic/ruvllm-linux-x64-gnu":"2.0.1","@aigentic/ruvllm-win32-x64-msvc":"2.0.1","@aigentic/ruvllm-linux-arm64-gnu":"2.0.1"},"_npmOperationalInternal":{"tmp":"tmp/ruvllm_2.5.6_1779092989842_0.24691967764864797","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-18T07:59:31.028Z","modified":"2026-09-13T15:30:36.005Z","2.5.5":"2026-05-18T07:59:31.299Z","2.5.6":"2026-05-18T08:29:50.013Z"},"bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"author":{"name":"rUv Team","email":"team@ruv.io"},"license":"MIT OR Apache-2.0","homepage":"https://github.com/ruvnet/ruvector/tree/main/examples/ruvLLM","keywords":["ruvllm","llm","self-learning","adaptive-learning","sona","lora","ewc","hnsw","vector-database","fastgrnn","router","simd","inference","federated-learning","continual-learning","machine-learning","ai","deep-learning","napi","rust","ruvector","turboquant","kv-cache","quantization","flash-attention","speculative-decoding","gguf","mamba","transformer","edge-ai","local-llm","model-compression"],"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git","directory":"npm/packages/ruvllm"},"description":"Self-learning LLM runtime — TurboQuant KV-cache (6-8x compression), SONA adaptive learning, FlashAttention, speculative decoding, GGUF inference","maintainers":[{"email":"engineering@aigentic.net","name":"aiggy"}],"readme":"# @ruvector/ruvllm\n\n[![npm version](https://img.shields.io/npm/v/@ruvector/ruvllm.svg)](https://www.npmjs.com/package/@ruvector/ruvllm)\n[![Downloads](https://img.shields.io/npm/dm/@ruvector/ruvllm)](https://www.npmjs.com/package/@ruvector/ruvllm)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![GitHub Stars](https://img.shields.io/github/stars/ruvnet/ruvector?style=social)](https://github.com/ruvnet/ruvector)\n\n**Self-learning LLM runtime for Node.js** — GGUF inference, TurboQuant KV-cache compression (6-8x memory savings), SONA adaptive learning, FlashAttention, speculative decoding, and SIMD-optimized kernels. Built in Rust, runs everywhere.\n\n> Inference at **88-135 tok/s** on M4 Pro | **<1ms** SONA adaptation | **6-8x** KV-cache compression via TurboQuant\n\n## Installation\n\n```bash\nnpm install @ruvector/ruvllm\n```\n\n## Quick Start\n\n```typescript\nimport { RuvLLM, RuvLLMConfig } from '@ruvector/ruvllm';\n\n// Initialize with default configuration\nconst llm = new RuvLLM();\n\n// Or with custom configuration\nconst llm = new RuvLLM({\n  modelPath: './models/ruvltra-small-q4km.gguf',\n  sonaEnabled: true,\n  flashAttention: true,\n  maxTokens: 256,\n});\n\n// Generate text\nconst response = await llm.query('Explain quantum computing');\nconsole.log(response.text);\n\n// Stream generation\nfor await (const token of llm.stream('Write a haiku about Rust')) {\n  process.stdout.write(token);\n}\n```\n\n## What's New in v2.5\n\n| Feature | Description |\n|---------|-------------|\n| **TurboQuant KV-Cache** | 2-4 bit asymmetric quantization with per-channel scale/zero-point — 6-8x memory reduction, <0.5% perplexity loss |\n| **TurboQuant Embedding Store** | Quantized vector storage with compressed search — 10-30x memory savings |\n| **H2O / PyramidKV Eviction** | Intelligent cache eviction policies for long-context inference |\n| **Optimized Inner Product** | Asymmetric distance on quantized data — skip decompression for 2-4x faster search |\n| **RuvLTRA Models** | Purpose-built 0.5B & 3B models for Claude Flow |\n| **Task-Specific LoRA** | 5 pre-trained adapters (coder, researcher, security, architect, reviewer) |\n| **HuggingFace Hub** | Download/upload models directly |\n| **Adapter Merging** | TIES, DARE, SLERP strategies |\n| **HNSW Routing** | 150x faster semantic matching |\n| **Evaluation Harness** | SWE-Bench testing with 5 ablation modes |\n| **mistral-rs Backend** | Production serving with PagedAttention, X-LoRA, ISQ |\n\n## TurboQuant — KV-Cache Compression\n\nReduce inference memory by 6-8x with <0.5% quality loss:\n\n```typescript\nimport { simd } from '@ruvector/ruvllm/simd';\n\n// TurboQuant compresses KV-cache entries at 2-4 bit precision\n// with per-channel asymmetric quantization (scale + zero-point).\n// Eviction policies (H2O, Sliding Window, PyramidKV) keep the\n// most important tokens in cache during long-context generation.\n\n// Supported bit widths: 2-bit (32x), 3-bit (10.7x), 4-bit (8x), 8-bit (4x)\n```\n\n| Bits | Compression | Perplexity Loss | Use Case |\n|------|-------------|-----------------|----------|\n| 2-bit | 32x | ~2% | Maximum compression, edge devices |\n| 3-bit | 10.7x | <1% | Balanced — recommended for most uses |\n| 4-bit | 8x | <0.5% | High quality, long-context inference |\n| 8-bit | 4x | ~0% | Baseline quantization |\n\n## CLI Usage\n\n```bash\n# Query a model\nruvllm query \"What is machine learning?\"\n\n# Stream output\nruvllm query --stream \"Write a poem\"\n\n# Download a model\nruvllm download ruvector/ruvltra-small-q4km\n\n# Benchmark\nruvllm bench ./models/model.gguf\n\n# Run evaluation (SWE-Bench)\nruvllm eval --model ./models/model.gguf --subset lite --max-tasks 50\n```\n\n## API Reference\n\n### RuvLLM Class\n\n```typescript\nclass RuvLLM {\n  constructor(config?: RuvLLMConfig);\n\n  // Generate text\n  query(prompt: string, params?: GenerateParams): Promise<Response>;\n\n  // Stream generation\n  stream(prompt: string, params?: GenerateParams): AsyncIterable<string>;\n\n  // Load a model\n  loadModel(path: string): Promise<void>;\n\n  // Get SONA learning stats\n  sonaStats(): SonaStats | null;\n\n  // Adapt on feedback\n  adapt(input: Float32Array, quality: number): void;\n}\n```\n\n### Configuration\n\n```typescript\ninterface RuvLLMConfig {\n  modelPath?: string;       // Path to GGUF model\n  sonaEnabled?: boolean;    // Enable SONA learning (default: true)\n  flashAttention?: boolean; // Use Flash Attention 2 (default: true)\n  maxTokens?: number;       // Max generation tokens (default: 256)\n  temperature?: number;     // Sampling temperature (default: 0.7)\n  topP?: number;            // Top-p sampling (default: 0.9)\n}\n```\n\n### Generate Parameters\n\n```typescript\ninterface GenerateParams {\n  maxTokens?: number;\n  temperature?: number;\n  topP?: number;\n  topK?: number;\n  repetitionPenalty?: number;\n  stopSequences?: string[];\n}\n```\n\n## SIMD Module\n\nFor direct access to optimized SIMD kernels:\n\n```typescript\nimport { simd } from '@ruvector/ruvllm/simd';\n\n// Dot product\nconst result = simd.dotProduct(vecA, vecB);\n\n// Matrix multiplication\nconst output = simd.matmul(matrix, vector);\n\n// Flash Attention\nconst attended = simd.flashAttention(query, key, value, scale);\n\n// RMS Normalization\nsimd.rmsNorm(hidden, weights, epsilon);\n```\n\n## Performance (M4 Pro)\n\n| Operation | Performance |\n|-----------|-------------|\n| Inference | 88-135 tok/s |\n| Flash Attention | 320µs (seq=2048) |\n| HNSW Search | 17-62µs |\n| SONA Adapt | <1ms |\n| Evaluation | 5 ablation modes |\n\n## Evaluation Harness\n\nRun model evaluations with SWE-Bench integration:\n\n```typescript\nimport { RuvLLM, EvaluationHarness, AblationMode } from '@ruvector/ruvllm';\n\nconst harness = new EvaluationHarness({\n  modelPath: './models/model.gguf',\n  enableHnsw: true,\n  enableSona: true,\n});\n\n// Run single evaluation\nconst result = await harness.evaluate(\n  'Fix the null pointer exception',\n  'def process(data): return data.split()',\n  AblationMode.Full\n);\n\nconsole.log(`Success: ${result.success}, Quality: ${result.qualityScore}`);\n\n// Run ablation study (Baseline, RetrievalOnly, AdaptersOnly, R+A, Full)\nconst report = await harness.runAblationStudy(tasks);\nfor (const [mode, metrics] of Object.entries(report.modeMetrics)) {\n  console.log(`${mode}: ${metrics.successRate * 100}% success`);\n}\n```\n\n## mistral-rs Backend (Production Serving)\n\nFor production deployments with 10-100+ concurrent users, use the mistral-rs backend:\n\n```typescript\nimport { RuvLLM, MistralBackend, PagedAttentionConfig } from '@ruvector/ruvllm';\n\n// Configure for production serving\nconst backend = new MistralBackend({\n  // PagedAttention: 5-10x more concurrent users\n  pagedAttention: {\n    blockSize: 16,\n    maxBlocks: 4096,\n    gpuMemoryFraction: 0.9,\n    prefixCaching: true,\n  },\n  // X-LoRA: Per-token adapter routing\n  xlora: {\n    adapters: ['./adapters/coder', './adapters/researcher'],\n    topK: 2,\n  },\n  // ISQ: Runtime quantization\n  isq: {\n    bits: 4,\n    method: 'awq',\n  },\n});\n\nconst llm = new RuvLLM({ backend });\nawait llm.loadModel('mistralai/Mistral-7B-Instruct-v0.2');\n\n// Serve multiple concurrent requests\nconst response = await llm.query('Write production code');\n```\n\n> **Note**: mistral-rs features require the Rust backend with `mistral-rs` feature enabled. Native bindings will use mistral-rs when available.\n\n## Supported Models\n\n- **RuvLTRA-Small** (494M) - Q4K, Q5K, Q8\n- **RuvLTRA-Medium** (3B) - Q4K, Q5K, Q8\n- **Qwen 2.5** (0.5B-72B)\n- **Llama 3.x** (8B-70B)\n- **Mistral** (7B-22B)\n- **Phi-3** (3.8B-14B)\n- **Gemma-2** (2B-27B)\n\n## Platform Support\n\n| Platform | Architecture | Status |\n|----------|--------------|--------|\n| macOS | arm64 (M1-M4) | ✅ Full support |\n| macOS | x64 | ✅ Supported |\n| Linux | x64 | ✅ Supported |\n| Linux | arm64 | ✅ Supported |\n| Windows | x64 | ✅ Supported |\n\n## Related Packages\n\n- [@ruvector/core](https://www.npmjs.com/package/@ruvector/core) - Vector operations\n- [@ruvector/sona](https://www.npmjs.com/package/@ruvector/sona) - SONA learning engine\n- [@ruvector/ruvector](https://www.npmjs.com/package/@ruvector/ruvector) - Full Ruvector SDK\n\n## Links\n\n- [GitHub Repository](https://github.com/ruvnet/ruvector)\n- [API Documentation](https://docs.rs/ruvllm)\n- [Crate (Rust)](https://crates.io/crates/ruvllm)\n\n## License\n\nMIT OR Apache-2.0\n","readmeFilename":"README.md"}