@ruvector/ruvllm 2.7.0 → 4.0.0

package/README.md

@@ -1,289 +1,183 @@
-# @ruvector/ruvllm
+# MetaHarness weight experiments
 
-[![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)
+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`.
 
-**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
-
-## Installation
-
-```bash
+```sh
 npm install @ruvector/ruvllm
+npx ruvllm --help            # bounded weight-edit experiments
+npx ruvllm-gpu-loop status --config /abs/private/gpu-loop.json
 ```
 
-## Quick Start
-
-```typescript
-import { RuvLLM, RuvLLMConfig } from '@ruvector/ruvllm';
-
-// Initialize with default configuration
-const llm = new RuvLLM();
-
-// Or with custom configuration
-const llm = new RuvLLM({ embeddingDim: 384, learningEnabled: true });
-
-// Routing, memory and embeddings
-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.** This package does not load model files (`modelPath` is
-> ignored), and the native engine has no language-model weights, so the text
-> returned by `generate()` and `query()` is not model output. The first such
-> call emits a `RUVLLM_NO_LANGUAGE_MODEL` warning; pass `{ strict: true }` to
-> throw instead. For GGUF inference, run the CLI (`ruvllm serve <model>`, with
-> `--strict` to exit if the model fails to load) or any OpenAI-compatible
-> server, and call it over HTTP.
-
-## 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)
+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"
 ```
 
-| 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
-ruvllm query "What is machine learning?"
-
-# 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
+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
 ```
 
-## API Reference
-
-### RuvLLM Class
-
-```typescript
-class RuvLLM {
-  constructor(config?: RuvLLMConfig);
-
-  // Routed query; text is not model output (see "Text generation" above)
-  query(text: string, config?: GenerationConfig): QueryResponse;
-
-  // Text from the native engine; not model output (see above)
-  generate(prompt: string, config?: GenerationConfig): string;
-
-  // 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: loadModel(), stream() (streaming lives in
-  // StreamingGenerator), mistral-rs backends. Use the ruvllm CLI for GGUF.
-
-  // Get SONA learning stats
-  sonaStats(): SonaStats | null;
-
-  // Adapt on feedback
-  adapt(input: Float32Array, quality: number): void;
+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"
+    }
+  ]
 }
 ```
 
-### Configuration
-
-```typescript
-interface RuvLLMConfig {
-  modelPath?: string;       // Not supported: ignored with a RUVLLM_UNSUPPORTED_OPTION warning
-  strict?: boolean;         // Throw instead of warning about placeholder text (default: false)
-  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)
-}
+```sh
+node integrations/metaharness/src/cli.mjs run \
+  --config /absolute/private/operator-profile/runtime.json \
+  --plan /absolute/experiment-inputs/plan.json
 ```
 
-### Generate Parameters
+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.
 
-```typescript
-interface GenerateParams {
-  maxTokens?: number;
-  temperature?: number;
-  topP?: number;
-  topK?: number;
-  repetitionPenalty?: number;
-  stopSequences?: string[];
-}
-```
+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.
 
-## SIMD Module
+## Claude Code and Ruflo
 
-For direct access to optimized SIMD kernels:
+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.
 
-```typescript
-import { simd } from '@ruvector/ruvllm/simd';
+## Scheduled GPU work
 
-// Dot product
-const result = simd.dotProduct(vecA, vecB);
+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.
 
-// Matrix multiplication
-const output = simd.matmul(matrix, vector);
+## Weight-EFT data and plans
 
-// Flash Attention
-const attended = simd.flashAttention(query, key, value, scale);
+The data-only adapter CLI reads JSON stdin, with a 16 MiB bound:
 
-// RMS Normalization
-simd.rmsNorm(hidden, weights, epsilon);
+```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
 ```
 
-## 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
-
-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`);
-}
+`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
 ```
 
-## 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');
-```
-
-> **Note**: mistral-rs features require the Rust backend with `mistral-rs` feature enabled. Native bindings will use mistral-rs when available.
-
-## 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)
-- [API Documentation](https://docs.rs/ruvllm)
-- [Crate (Rust)](https://crates.io/crates/ruvllm)
-
-## License
-
-MIT OR Apache-2.0
+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).

package/examples/gpu-loop.example.json

@@ -0,0 +1,26 @@
+{
+  "schema": "ruvllm-gpu-loop/v1",
+  "stateRoot": "/absolute/private/gpu-loop-state",
+  "intervalSeconds": 60,
+  "maxAttempts": 2,
+  "budgetUsd": 0,
+  "jobs": [
+    {
+      "id": "qwen35-4b-paired-evaluation",
+      "provider": "vast.ai",
+      "model": {
+        "repo": "Qwen/Qwen3.5-4B",
+        "revision": "851bf6e806efd8d0a36b00ddf55e13ccb7b8cd0a"
+      },
+      "task": "evaluate",
+      "secretRef": "ruos.vast.primary",
+      "resource": { "instanceId": "REPLACE_WITH_EXISTING_INSTANCE_ID" },
+      "maxCostUsd": 1,
+      "timeoutSeconds": 1800,
+      "experiment": {
+        "configPath": "/absolute/private/operator-profile/runtime.json",
+        "planPath": "/absolute/experiment-inputs/plan.json"
+      }
+    }
+  ]
+}