@ruvector/ruvllm 4.0.1 → 4.2.0

package/README.md

@@ -1,187 +1,473 @@
-# MetaHarness weight experiments
+# @ruvector/ruvllm
+
+<p align="center"><img src="https://raw.githubusercontent.com/ruvnet/RuVector/main/assets/ruvector/packages/ruvllm.svg" alt="@ruvector/ruvllm: self-learning LLM runtime for Node.js with GGUF inference, SONA, TurboQuant KV cache and an optional GPU job loop." width="100%"></p>
+
+[![npm version](https://img.shields.io/npm/v/@ruvector/ruvllm.svg)](https://www.npmjs.com/package/@ruvector/ruvllm)
+[![Downloads](https://img.shields.io/npm/dm/@ruvector/ruvllm)](https://www.npmjs.com/package/@ruvector/ruvllm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Stars](https://img.shields.io/github/stars/ruvnet/ruvector?style=social)](https://github.com/ruvnet/ruvector)
+
+**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.
+
+> Inference at **88-135 tok/s** on M4 Pro | **<1ms** SONA adaptation | **6-8x** KV-cache compression via TurboQuant
+
+## One package: the LLM runtime and the GPU job loop (4.1.0)
+
+`@ruvector/ruvllm` is the RuVLLM **self-learning LLM runtime for Node.js**:
+GGUF inference, SONA adaptive learning, MicroLoRA, TurboQuant KV-cache
+compression, FlashAttention, speculative decoding, HNSW memory, the `ruvllm`
+CLI and a local `ruvllm serve` HTTP server. Since 4.1.0 it also pulls in
+**[`@ruvector/ruvllm-gpu-loop`](https://www.npmjs.com/package/@ruvector/ruvllm-gpu-loop)**
+(the RuVLLM GPU job loop, Vast.ai host adapter, adapter archives and bounded
+weight experiments) as an optional dependency, so a single
+`npm install @ruvector/ruvllm` gives you both.
+
+**Why 4.1.0 exists.** Versions 4.0.0 and 4.0.1 were published from a different
+repository (`ruvnet/ruvllm`) and replaced this runtime with only the GPU job
+loop harness: no runtime API, no native bindings, no `ruvllm` CLI. 4.1.0
+restores the runtime (the same API as 3.0.0) and keeps every 4.0.x entry point
+working through `@ruvector/ruvllm-gpu-loop`. Do not use 4.0.0 or 4.0.1.
+
+| You used | In 4.1.0 |
+| :--- | :--- |
+| 3.x / 2.x runtime: `require('@ruvector/ruvllm')`, `import … from '@ruvector/ruvllm'` | Unchanged (CommonJS and ESM) |
+| 4.0.x root: `import { runExperiment } from '@ruvector/ruvllm'` | `import { runExperiment } from '@ruvector/ruvllm/engine'` |
+| 4.0.x subpaths: `@ruvector/ruvllm/gpu-loop`, `/adapters`, `/gpu-host`, `/gpu-spool-adapter`, `/vast-host-adapter`, `/fixture` | Unchanged (re-exported from `@ruvector/ruvllm-gpu-loop`) |
+| 4.0.x CLI: `ruvllm run …`, `ruvllm fixture …` | `ruvllm gpu run …`, `ruvllm gpu fixture …` (or `ruvllm-gpu` from `@ruvector/ruvllm-gpu-loop`) |
+| `ruvllm-gpu-loop`, `ruvllm-adapters` | Unchanged; also `ruvllm gpu loop …`, `ruvllm gpu adapters …` |
+
+The GPU-loop subpaths are loaded lazily: importing the root never loads them.
+They need Node 22+ (the GPU-loop package's requirement). If the optional
+package was skipped (`--omit=optional`), they throw `RUVLLM_GPU_LOOP_MISSING`
+naming the install command. They are ESM; `require()` of them works where
+Node supports `require(esm)` (20.19+ / 22.12+). If you only need the GPU job
+loop, install `@ruvector/ruvllm-gpu-loop` on its own.
+
+## Installation
+
+```bash
+npm install @ruvector/ruvllm
+```
 
-<p align="center"><img src="https://raw.githubusercontent.com/ruvnet/ruvllm/ruvllm-npm-v4.0.1/docs/assets/gpu-job-loop.svg" alt="The GPU job loop checks a spending ceiling, rents the offer and arms a destroy timer, runs the pinned job, pulls raw outputs, checks them locally, then destroys the rental and confirms it is gone." width="100%"></p>
+## Quick Start
 
-<p align="center"><img src="https://raw.githubusercontent.com/ruvnet/ruvllm/ruvllm-npm-v4.0.1/docs/assets/heldout-results.svg" alt="Held-out results on 256 untouched tasks: tool passes 149, 176 and 192 of 192 for base, coding-4b and coding-4b-r2; arithmetic 62, 64 and 46 of 64. coding-4b is kept; coding-4b-r2 is rejected." width="100%"></p>
+```typescript
+import { RuvLLM, RuvLLMConfig } from '@ruvector/ruvllm';
 
-Published on npm as `@ruvector/ruvllm`. Version 4.0.0 replaces the 3.x
-inference runtime from `ruvnet/ruvector` with this package, because ruvllm now
-lives in `ruvnet/ruvllm`. The 3.x API and its CLI subcommands are not part of
-4.x; pin `@ruvector/ruvllm@3` to keep using them. The npm package ships the
-JavaScript controller, GPU loop and Vast.ai host adapter. It does not ship the
-native `weight_evolution` binary, model weights or adapters. Build the binary
-from this repository and pass its path with `--binary`.
+// Initialize with default configuration
+const llm = new RuvLLM();
 
-```sh
-npm install @ruvector/ruvllm
-npx ruvllm --help            # bounded weight-edit experiments
-npx ruvllm-gpu-loop status --config /abs/private/gpu-loop.json
+// Or with custom configuration
+const llm = new RuvLLM({ embeddingDim: 384, learningEnabled: true });
+
+// Routing, memory and embeddings (no model needed)
+const decision = llm.route('Explain quantum computing');
+llm.addMemory('RuvLLM routes queries with FastGRNN', { source: 'docs' });
+const hits = llm.searchMemory('how are queries routed?', 3);
+const vec = llm.embed('Explain quantum computing');
+```
+
+## Text Generation (GGUF)
+
+Text comes only from a model you load. `loadModel()` runs a local GGUF file
+on the native candle backend (CPU; Metal on macOS builds with the `metal`
+feature):
+
+```typescript
+const llm = new RuvLLM();
+llm.loadModel('./qwen2.5-0.5b-instruct-q4_k_m.gguf', { maxContext: 4096 });
+
+const out = llm.chat([{ role: 'user', content: 'What is the capital of France?' }], {
+  maxTokens: 64,
+  temperature: 0,
+});
+// { text: 'The capital of France is Paris.', promptTokens: 15,
+//   completionTokens: 8, finishReason: 'stop' }
+```
+
+- **Architectures**: GGUF `llama`, `mistral`, `qwen2` (Qwen2.5) and `qwen3`.
+  Any other architecture (phi, gemma, qwen3.5, ...) fails to load with an error
+  naming it.
+- **Tokenizer**: a `tokenizer.json` next to the GGUF, else the tokenizer
+  embedded in the GGUF. The embedded one works for byte-level BPE (`gpt2`)
+  vocabularies such as Qwen and Llama 3; GGUFs with a SentencePiece vocabulary
+  (Llama 2, Mistral, TinyLlama) need the `tokenizer.json`, otherwise loading
+  fails with `RUVLLM_TOKENIZER_MISSING`.
+- **`chat()`** applies the model's chat template, read from the GGUF's
+  embedded `tokenizer.chat_template` (ChatML for Qwen). A `qwen2`/`qwen3` GGUF
+  whose template is not ChatML (e.g. DeepSeek-R1-Distill-Qwen) fails to load
+  with `RUVLLM_MODEL_LOAD_FAILED` rather than run under the wrong format.
+- **`generate()`** continues the prompt verbatim; **`query()`** routes, then
+  answers as a single chat message.
+- **Usage**: `promptTokens`/`completionTokens` are counted with the model's
+  tokenizer; `finishReason` is `stop` (end-of-sequence token or a stop
+  sequence) or `length` (`maxTokens` reached or the context is full).
+- **Blocking**: loading and generation are synchronous and block the event
+  loop; run them in a worker thread if that matters.
+
+Without a loaded model, `generate()`, `query()`, `chat()` and
+`generateDetailed()` throw `RUVLLM_NO_LANGUAGE_MODEL`; they never return text
+that is not model output. For demos and tests, `new RuvLLM({ allowPlaceholder:
+true })` (or `RUVLLM_ALLOW_MOCK=1`) makes `generate()`/`query()` return the
+labelled `PLACEHOLDER_TEXT` instead, with a one-time warning.
+
+### Native binary requirements
+
+Model loading needs a native binary built with the `candle` feature;
+`supportsModelLoading()` reports whether the installed one was.
+
+| Native binary | `loadModel()` |
+|---------------|---------------|
+| Built from this source (`npm run build:native`) | Works |
+| `@ruvector/ruvllm-<platform>` 2.1.x (installed with `@ruvector/ruvllm` 4.2.0+, built by the release workflow with `candle`) | Works |
+| `@ruvector/ruvllm-<platform>` 2.0.x | Throws `RUVLLM_NATIVE_TOO_OLD`: they predate model loading |
+| Built with `--features napi` only (no `candle`) | Throws `RUVLLM_NO_INFERENCE_BACKEND` |
+| None for your platform | Throws `RUVLLM_NATIVE_UNAVAILABLE` |
+
+To use a binary you built, point `RUVLLM_NATIVE_PATH` at it (it takes
+precedence over the installed platform package):
+
+```bash
+npm run build:native   # writes ruvllm.<platform>.node (needs a Rust toolchain)
+RUVLLM_NATIVE_PATH=$PWD/ruvllm.linux-x64-gnu.node node app.js
+```
+
+From 4.2.0 the platform packages (`@ruvector/ruvllm-<platform>@2.1.0`) are
+built with `candle`, so `loadModel()`, `query`/`generate` with `--model` and
+`ruvllm serve` work on a plain `npm install` for linux-x64, linux-arm64,
+darwin-x64, darwin-arm64 and win32-x64. 4.1.0 and earlier shipped the 2.0.1
+binaries, which predate model loading.
+
+| Error code | Meaning |
+|------------|---------|
+| `RUVLLM_NO_LANGUAGE_MODEL` | Generation was requested with no model loaded |
+| `RUVLLM_NATIVE_UNAVAILABLE` | No native binary could be loaded |
+| `RUVLLM_NATIVE_TOO_OLD` | The native binary predates model loading (2.0.x platform packages) |
+| `RUVLLM_NO_INFERENCE_BACKEND` | The native binary was built without the `candle` backend |
+| `RUVLLM_MODEL_NOT_FOUND` | The model path does not exist |
+| `RUVLLM_MODEL_LOAD_FAILED` | The file could not be loaded (unsupported architecture, not GGUF, ...) |
+| `RUVLLM_TOKENIZER_MISSING` | Weights loaded but no usable tokenizer was found |
+
+## What's New in v2.5
+
+| Feature | Description |
+|---------|-------------|
+| **TurboQuant KV-Cache** | 2-4 bit asymmetric quantization with per-channel scale/zero-point — 6-8x memory reduction, <0.5% perplexity loss |
+| **TurboQuant Embedding Store** | Quantized vector storage with compressed search — 10-30x memory savings |
+| **H2O / PyramidKV Eviction** | Intelligent cache eviction policies for long-context inference |
+| **Optimized Inner Product** | Asymmetric distance on quantized data — skip decompression for 2-4x faster search |
+| **RuvLTRA Models** | Purpose-built 0.5B & 3B models for Claude Flow |
+| **Task-Specific LoRA** | 5 pre-trained adapters (coder, researcher, security, architect, reviewer) |
+| **HuggingFace Hub** | Download/upload models directly |
+| **Adapter Merging** | TIES, DARE, SLERP strategies |
+| **HNSW Routing** | 150x faster semantic matching |
+| **Evaluation Harness** | SWE-Bench testing with 5 ablation modes |
+| **mistral-rs Backend** | Production serving with PagedAttention, X-LoRA, ISQ |
+
+## TurboQuant — KV-Cache Compression
+
+Reduce inference memory by 6-8x with <0.5% quality loss:
+
+```typescript
+import { simd } from '@ruvector/ruvllm/simd';
+
+// TurboQuant compresses KV-cache entries at 2-4 bit precision
+// with per-channel asymmetric quantization (scale + zero-point).
+// Eviction policies (H2O, Sliding Window, PyramidKV) keep the
+// most important tokens in cache during long-context generation.
+
+// Supported bit widths: 2-bit (32x), 3-bit (10.7x), 4-bit (8x), 8-bit (4x)
+```
+
+| Bits | Compression | Perplexity Loss | Use Case |
+|------|-------------|-----------------|----------|
+| 2-bit | 32x | ~2% | Maximum compression, edge devices |
+| 3-bit | 10.7x | <1% | Balanced — recommended for most uses |
+| 4-bit | 8x | <0.5% | High quality, long-context inference |
+| 8-bit | 4x | ~0% | Baseline quantization |
+
+## CLI Usage
+
+```bash
+# Query a model (this package's `ruvllm` bin; needs --model, see above)
+ruvllm query "What is machine learning?" --model ./qwen2.5-0.5b-instruct-q4_k_m.gguf
+
+# The commands below are the Rust ruvllm CLI (crate ruvllm-cli)
+# Stream output
+ruvllm query --stream "Write a poem"
+
+# Download a model
+ruvllm download ruvector/ruvltra-small-q4km
+
+# Benchmark
+ruvllm bench ./models/model.gguf
+
+# Run evaluation (SWE-Bench)
+ruvllm eval --model ./models/model.gguf --subset lite --max-tasks 50
+```
+
+## HTTP server: `ruvllm serve`
+
+`ruvllm serve` runs a local LLM server over a GGUF model, on
+`127.0.0.1:3000` by default (`--host`, `--port`, `--max-context`,
+`--max-tokens`, `--temperature`). It is the endpoint the
+[ruflo / claude-flow](https://github.com/ruvnet/claude-flow) RuVector provider
+calls:
+
+```bash
+npx @ruvector/ruvllm serve ./qwen2.5-0.5b-instruct-q4_k_m.gguf
+curl -s localhost:3000/health
+curl -s localhost:3000/query -H 'content-type: application/json' -d '{"query":"What is HNSW?"}'
+curl -s localhost:3000/v1/chat/completions -H 'content-type: application/json' \
+  -d '{"messages":[{"role":"user","content":"Hello"}],"max_tokens":32}'
 ```
 
-Run multiple bounded RuVLLM edits against one unchanged checkpoint, validate
-supplied evaluations, package RVF evidence, restore every patched checkpoint,
-and rank research-qualified candidates through MetaHarness. This controller
-uses the actual Flywheel, Darwin and Weight-EFT packages pinned in
-[package-lock.json](package-lock.json).
-
-The runner does not perform inference, discover an effective weight edit, train
-an adapter or activate a model. CPU fixtures exercise real file editing and
-restoration with explicitly synthetic evaluation receipts. External evaluation
-files remain caller-supplied evidence; hashes do not authenticate their origin.
-
-## Install and run the CPU fixture
-
-Requirements: Linux or macOS, Node 22+, Python 3.12+, a C linker, and Rust 1.97.1
-as pinned by `native/rust-toolchain.toml`. Activate any locally installed Rust
-toolchain before using Cargo. From the repository root:
-
-```sh
-(cd integrations/metaharness && npm ci --ignore-scripts)
-(cd native && cargo build --locked --release --bin weight_evolution)
-python3 native/verify_source.py
-node integrations/metaharness/src/cli.mjs fixture \
-  --dir "$PWD/runtime/metaharness-fixture" \
-  --binary "$PWD/native/target/release/weight_evolution"
+| Endpoint | Body / response |
+| :--- | :--- |
+| `GET /health` | `{ status, model, modelLoaded, native, sona, hnsw, version }` |
+| `GET /v1/models` | OpenAI-style model list |
+| `POST /query` | `{ query, session_id? }` → `{ id, model, content, done, usage, router_metrics }` |
+| `POST /v1/chat/completions` | OpenAI chat format; `stream: true` returns the finished completion as one SSE chunk, then `[DONE]` |
+
+The server is strict: it starts only after the model loads, and exits 1
+otherwise (no placeholder answers, so clients such as ruflo fall back to
+another provider instead of receiving non-model text). Generation is
+synchronous, so requests are answered one at a time.
+
+## GPU job loop: `ruvllm gpu`
+
+The RuVLLM GPU job loop schedules bounded GPU jobs (spending ceiling, destroy
+timer, confirmed cleanup) on a Vast.ai host, packages LoRA adapter archives
+and runs bounded weight-edit experiments. It lives in
+[`@ruvector/ruvllm-gpu-loop`](https://www.npmjs.com/package/@ruvector/ruvllm-gpu-loop)
+([source](https://github.com/ruvnet/ruvllm/tree/main/integrations/metaharness));
+this package exposes it as:
+
+```bash
+npx ruvllm gpu loop status --config /abs/private/gpu-loop.json   # = ruvllm-gpu-loop
+npx ruvllm gpu adapters training-plan < plan.json                # = ruvllm-adapters
+npx ruvllm gpu fixture --dir /abs/new-dir --binary /abs/weight_evolution
 ```
 
-Create the fixture's parent directory first (`mkdir -p runtime`). Its own directory
-must not exist: exclusive creation prevents accidental replacement. For another
-fixture use a new directory. The report should select `fixture-improvement`, leave
-`unevaluated-control` unqualified, verify RVF and exact rollback for both, and
-report `inferencePerformed: false`, `independentConfirmation: false` and
-`productionActivation: false`. A selected synthetic candidate says nothing about
-actual model accuracy.
-
-## Configure real experiment inputs
-
-Prepare reviewed source checkpoint, patch, policy and optional evaluation JSON
-under explicit input roots. Native request/data contracts are described in the
-[native guide](../../native/README.md). Patch generation remains model specific;
-the controller does not guess useful tensor edits.
-
-Run the project-local installer with paths you control:
-
-```sh
-bash scripts/install-metaharness.sh \
-  --config-dir /absolute/private/operator-profile \
-  --read-root /absolute/checkpoints \
-  --read-root /absolute/experiment-inputs \
-  --policy /absolute/experiment-inputs/policy.json \
-  --output-root /absolute/private/experiment-outputs
+```js
+import { tickLoop, readLoopStatus } from '@ruvector/ruvllm/gpu-loop';
+import { createVastAdapter } from '@ruvector/ruvllm/vast-host-adapter';
 ```
 
-It installs frozen npm dependencies without lifecycle scripts, builds the native
-binary, verifies native provenance and runs its smoke fixture. It creates a
-private runtime profile and Claude launcher without changing global settings.
-Repeat `--read-root`/`--policy` for additional approved inputs. Existing profile
-files are never replaced; use another directory for a new profile. Existing config
-and output directories must be owner-only. `--configure-only` skips installation
-and building but still checks native readiness.
-
-Example plan inside an approved read root:
-
-```json
-{
-  "schema": "ruvllm-experiment-plan/v1",
-  "evidenceMode": "external",
-  "source": "/absolute/checkpoints/source.safetensors",
-  "policy": "/absolute/experiment-inputs/policy.json",
-  "candidates": [
-    {
-      "id": "candidate-01",
-      "patch": "/absolute/experiment-inputs/patch.json",
-      "evaluation": "/absolute/experiment-inputs/evaluation.json"
-    }
-  ]
+## API Reference
+
+### RuvLLM Class
+
+```typescript
+class RuvLLM {
+  constructor(config?: RuvLLMConfig);
+
+  // Language model (see "Text Generation" above)
+  loadModel(path: string, options?: LoadModelOptions): LoadedModelInfo;
+  unloadModel(): void;
+  isModelLoaded(): boolean;
+  modelInfo(): LoadedModelInfo | null;
+  supportsModelLoading(): boolean; // native binary can load models
+
+  // Generation; all throw RUVLLM_NO_LANGUAGE_MODEL without a loaded model
+  chat(messages: ChatMessage[], config?: GenerationConfig): GenerationResult;
+  generateDetailed(prompt: string, config?: GenerationConfig): GenerationResult;
+  generate(prompt: string, config?: GenerationConfig): string;
+  query(text: string, config?: GenerationConfig): QueryResponse; // routed, + token usage
+
+  // Routing, memory and embeddings
+  route(text: string): RoutingDecision;
+  addMemory(content: string, metadata?: Record<string, unknown>): MemoryId;
+  searchMemory(text: string, k?: number): MemoryResult[];
+  embed(text: string): Embedding;
+
+  // Not in this package: token streaming (StreamingGenerator chunks a
+  // finished generate() result), mistral-rs backends.
+
+  // Get SONA learning stats
+  sonaStats(): SonaStats | null;
+
+  // Adapt on feedback
+  adapt(input: Float32Array, quality: number): void;
 }
 ```
 
-```sh
-node integrations/metaharness/src/cli.mjs run \
-  --config /absolute/private/operator-profile/runtime.json \
-  --plan /absolute/experiment-inputs/plan.json
+### Configuration
+
+```typescript
+interface RuvLLMConfig {
+  modelPath?: string;              // GGUF to load in the constructor (throws if it cannot be loaded)
+  modelOptions?: LoadModelOptions; // { maxContext?: number } for modelPath
+  allowPlaceholder?: boolean;      // generate()/query() return PLACEHOLDER_TEXT instead of
+                                   // throwing when no model is loaded (default: false)
+  strict?: boolean;                // Throw instead of warning for unsupported options (`backend`)
+  // ...plus routing/memory options (embeddingDim, hnswM, ...), see types.ts
+}
 ```
 
-Omit `evaluation` to run mechanical checks without qualification. After an external
-inference runner has evaluated a candidate, submit its hash-bound evaluation in a
-new plan/run. Candidate checkpoint hashes are deterministic for the same patch;
-new artifact paths do not relax identity checks. Paired baseline, protocol, suite,
-runtime, precision and output-budget consistency remain the evaluator's responsibility.
+### Generation Config and Result
+
+```typescript
+interface GenerationConfig {
+  maxTokens?: number;          // default 256
+  temperature?: number;        // default 0.7; 0 = greedy
+  topP?: number;               // default 0.9, in (0, 1]
+  topK?: number;               // default 50; 0 disables
+  repetitionPenalty?: number;  // default 1.1
+  stopSequences?: string[];    // stop text is not included in the output
+  seed?: number;               // reproducible sampling at temperature > 0
+}
 
-Runs use new private `run-*` directories and preserve rejected candidates. Reports
-bind config/plan/source/policy/binary/gate/patch/evaluation identities and record
-rollback and RVF verification. Native rejection records a reason. Structural or
-restoration failures abort; interrupted runs can leave artifacts. Reconcile those
-directories before retrying; never erase failed evidence to manufacture success.
+interface GenerationResult {
+  text: string;
+  promptTokens: number;        // after the chat template, for chat()
+  completionTokens: number;    // includes an end-of-sequence token that ended generation
+  finishReason: 'stop' | 'length' | 'cancelled';
+}
+```
 
-## Claude Code and Ruflo
+## SIMD Module
 
-Load [ruflo-metaharness](../../plugins/ruflo-metaharness/README.md) using the
-generated `launch-claude.sh`, or set `RUVLLM_EXPERIMENT_CONFIG` and use Claude's
-`--plugin-dir`. The `/ruflo-metaharness:weight-experiment` command and reviewer
-agent guide the bounded workflow. Its single MCP tool accepts a plan path; the
-model cannot override the operator configuration. The same stdio server can be
-registered in a Ruflo project's MCP configuration. Portable wire tests exercise
-the real engine; installed Claude/Ruflo client acceptance is separate.
+For direct access to optimized SIMD kernels:
 
-## Scheduled GPU work
+```typescript
+import { simd } from '@ruvector/ruvllm/simd';
 
-For scheduled GPU work, use the [durable GPU loop](GPU-LOOP.md). It supports
-host-owned ruOS secret references, Vast job descriptors, persisted reservations,
-deadline-aware polling and confirmed cleanup. Local contract tests require no
-live provider. The bundled file handoff keeps requests pending for a trusted host.
+// Dot product
+const result = simd.dotProduct(vecA, vecB);
 
-## Weight-EFT data and plans
+// Matrix multiplication
+const output = simd.matmul(matrix, vector);
 
-The data-only adapter CLI reads JSON stdin, with a 16 MiB bound:
+// Flash Attention
+const attended = simd.flashAttention(query, key, value, scale);
 
-```sh
-node integrations/metaharness/src/adapters-cli.mjs export < reviewed-archive-input.json > export.json
-node integrations/metaharness/src/adapters-cli.mjs training-plan < training-input.json > plan.json
-node integrations/metaharness/src/adapters-cli.mjs select < measured-candidates.json > selection.json
+// RMS Normalization
+simd.rmsNorm(hidden, weights, epsilon);
 ```
 
-`export` takes `{archive, evalHoldout, maxTokens?}`. Archive entries follow the
-pinned Weight-EFT `DarwinTrajectory` contract (`instance_id`, `model`, `tier`,
-boolean `resolved`, `messages`, `model_patch`). All actual evaluation instance IDs
-must be in `evalHoldout`. Output contains standard `sft`/`dpo` arrays, drop reports
-and input hashes. Reward-hacking filtering stays enabled, overlength traces are
-dropped, and tool calls are preserved. These filters cannot authenticate outcomes
-or detect all semantic contamination.
-
-`training-plan` takes `{base:{id,paramsB},sftPath,dpoPath,adapterPrefix}`. It emits
-upstream plans plus `executionStatus: not_executed` and
-`runnerCompatibility: adapter-required`. This repository has no upstream
-`ruvllm microlora` executable. Its existing fixed CUDA/PEFT experiment runner is
-not a configurable SFT/DPO trainer. No GPU, model download or paid job is started.
-
-`select` takes `{baseline,candidates,envelope}` with entries
-`{id,score,evidenceSha256}`. It replays finite, supplied scores through Darwin's
-contrastive engine. It is development ranking with an immutable envelope and no
-independent confirmation; it cannot authenticate caller-supplied evidence. The
-native runner applies its stricter qualification first.
-
-## Tests and benchmark
-
-```sh
-(cd integrations/metaharness && npm test)
-node --test plugins/ruflo-metaharness/test/*.test.mjs
-node integrations/metaharness/bench/run.mjs --iterations 7 --warmup 2 --candidates 2
+## Performance (M4 Pro)
+
+| Operation | Performance |
+|-----------|-------------|
+| Inference | 88-135 tok/s |
+| Flash Attention | 320µs (seq=2048) |
+| HNSW Search | 17-62µs |
+| SONA Adapt | <1ms |
+| Evaluation | 5 ablation modes |
+
+## Evaluation Harness
+
+> **Not in this npm package**: `EvaluationHarness` and `AblationMode` are
+> not exported by `@ruvector/ruvllm`. The sketch below shows the intended API.
+
+Run model evaluations with SWE-Bench integration:
+
+```typescript
+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`);
+}
 ```
 
-Tests require the built native binary. In restricted agent environments the Node
-test runner, native child processes and package fetching may require the host's
-supported execution permission. Verify actual subtest counts; a file-only runner
-summary is insufficient evidence. Do not disable TLS/checksums or native checks.
-
-The benchmark compares fresh versus reused Node processes on identical CPU
-fixtures, retaining raw latency samples and implementation/binary/lock hashes.
-The reused process matches the MCP server architecture. All native hashing,
-patch validation and byte restoration remain enabled. See the
-[benchmark report](../../docs/benchmarks/metaharness-cpu.md) for measured scope
-and limits; no model-performance claim follows from orchestration speed.
-
-Architecture and threat boundaries are recorded in
-[ADR 012](../../docs/adr/ADR-012-metaharness-bounded-experiment-runner.md),
-[ADR 013](../../docs/adr/ADR-013-training-and-development-selection.md) and
-[ADR 014](../../docs/adr/ADR-014-claude-ruflo-integration.md).
+## mistral-rs Backend (Production Serving)
+
+For production deployments with 10-100+ concurrent users, use the mistral-rs backend:
+
+```typescript
+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');
+```
+
+> **Not in this npm package**: `MistralBackend` is not exported, the
+> `backend` option is ignored (with a `RUVLLM_UNSUPPORTED_OPTION` warning), and
+> `loadModel()` takes a local GGUF path, not a Hub id. mistral-rs serving is a
+> feature of the Rust crate (`mistral-rs` feature).
+
+## Supported Models
+
+GGUF files loadable with `loadModel()` (architectures llama, mistral, qwen2, qwen3):
+
+- **RuvLTRA-Small** (494M) - Q4K, Q5K, Q8
+- **RuvLTRA-Medium** (3B) - Q4K, Q5K, Q8
+- **Qwen 2.5 / Qwen 3** (0.5B-72B)
+- **Llama 3.x** (8B-70B)
+- **Mistral** (7B-22B)
+
+Phi-3, Gemma-2 and Qwen3.5 GGUFs are not supported: loading fails with an
+error naming the architecture.
+
+## Platform Support
+
+The table covers routing, memory and embeddings. Model loading additionally
+needs a native binary built with the `candle` feature (see "Native binary
+requirements").
+
+| 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/ruvllm-gpu-loop](https://www.npmjs.com/package/@ruvector/ruvllm-gpu-loop) - RuVLLM GPU job loop, Vast.ai adapter and adapter archives
+- [@ruvector/ruvector](https://www.npmjs.com/package/@ruvector/ruvector) - Full Ruvector SDK
+
+## Links
+
+- [GitHub Repository](https://github.com/ruvnet/ruvector)
+- [API Documentation](https://docs.rs/ruvllm)
+- [Crate (Rust)](https://crates.io/crates/ruvllm)
+
+## License
+
+MIT OR Apache-2.0