Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 6 additions & 9 deletions .github/workflows/ruvector-npm-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -140,22 +140,19 @@ jobs:
run: node --test tests/*.test.mjs

- name: weight-space absent — CLI/MCP install hint, require('ruvector') still loads
# @ruvector/weight-space is an optional peer and is not installed above;
# the test also hides it with a resolve shim, so it holds either way.
# @ruvector/weight-space is a hard dependency, so it is installed above; the
# test hides it with a resolve shim to prove a pruned install still degrades
# to the install hint instead of crashing.
run: node test/weight-space-optional.js

- name: weight-space present — ruvector weights CLI + weights_* MCP (real import)
# @ruvector/weight-space is not on npm yet: build and pack the sibling
# package, then install the tarball without saving it to package.json.
# --save-dev only picks the edge type: the package is a declared peer, and
# --legacy-peer-deps skips peer edges, so a plain --no-save install is a
# silent no-op ("up to date"). --no-save still leaves package.json alone.
# A plain install resolves the published dependency; fail loudly if it does
# not, rather than letting the CLI test skip.
run: |
set -e
(cd ../weight-space && npm install --no-workspaces --no-audit --no-fund && npm run build && npm pack --pack-destination "$RUNNER_TEMP")
npm install --no-save --save-dev --no-workspaces --no-audit --no-fund --legacy-peer-deps "$RUNNER_TEMP"/ruvector-weight-space-0.1.0.tgz
node -e "require('@ruvector/weight-space')"
node test/weight-space-cli.js
node test/weight-space-edit.js

# ──────────────────────────────────────────────────────────────────────────
# 3. FUNCTIONAL SMOKE — npx-style CLI works end-to-end
Expand Down
34 changes: 34 additions & 0 deletions docs/adr/ADR-358-weight-space-ruv-fann-registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,40 @@ from the mirrored constants.
loaded, path-confined to the working directory (the MCP rule from #1306/#1307),
and print `npm i @ruvector/weight-space@0.1.0` when the package is absent.

### Amendment 2026-11-13: hard dependency (supersedes the optional peer above)

The owner asked for `@ruvector/weight-space` to be a primary dependency of
`ruvector`, as `@ruvector/e-means` already is (#1489). The optional peer, and the
rule that a default install does not fetch it, are superseded.

- It is an exact-pinned `dependencies` entry (`0.1.0`) and is removed from
`peerDependencies` and `peerDependenciesMeta`.
- Cost, measured on the registry: 175 KB unpacked for the package, plus `ruv-fann`
(19 KB) and its `ruv-fann-wasm` runtime. Nothing is loaded at start-up: the
`weights` commands and `weights_*` tools still `require` it inside the operation,
so `ruvector --help` and MCP start-up are unchanged (`test/startup-budget.js`).
- The "package absent" path stays, as a degradation path rather than the normal
case. A pruned install or a package manager that does not expose it still gets
`ERR_WEIGHT_SPACE_MISSING` and the install hint, not a crash.
- **Side effect on `neural-q`.** `ruv-fann` stays an optional peer of `ruvector`, but
it is now also a transitive dependency through `@ruvector/weight-space`. On a
default npm install it therefore resolves, and `neural-q` uses its MLP backend
instead of falling back to tabular `q-learning`. That is what the algorithm name
promises, and it only affects users who select `neural-q`. A strict layout such as
pnpm may not expose the transitive package to `ruvector`; those users install
`ruv-fann@0.1.0` directly, as before.
- `test/weight-space-cli.js` now fails, rather than skips, when the package does not
resolve, because a skip would hide a broken install.
- **Edit and fine-tune surface.** `ruvector weights set-layer|perturb|learn` and the MCP
tools `weights_set_layer|weights_perturb|weights_learn` expose the registry's
versioned edit and `learnFromOutcomes` operations (`bin/weights-edit.js`). Each writes a
child snapshot and never changes its parent. Inputs are bounded (epochs, rows, vector
and patch sizes, seeds), file inputs use the same working-directory confinement as
`save`, and a fine-tune that does not clear its held-out check writes nothing and
returns `accepted: false` rather than an error. These tools write to the registry, so
operators who expose the MCP server read-only should deny them with
`RUVECTOR_MCP_DENY` (ADR-256).

## Evaluation

The numbers below were measured on ruvultra (Linux x64, Node 22, ruv-fann
Expand Down
14 changes: 10 additions & 4 deletions npm/packages/ruvector/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,23 +138,29 @@ The engine adds 458 KB unpacked to an install. `npx ruvector --help` cold start

## Weight registry (`@ruvector/weight-space`)

`ruvector weights` stores [`ruv-fann`](https://www.npmjs.com/package/ruv-fann) model snapshots (`ruv-fann.dense-layers/1` JSON) in a versioned registry keyed by a task embedding, so you can find the snapshot saved for the most similar past task. It runs on the optional peer `@ruvector/weight-space`, which `ruvector` does not install. Without it, the command prints `npm i @ruvector/weight-space@0.1.0` and exits non-zero.
`ruvector weights` stores [`ruv-fann`](https://www.npmjs.com/package/ruv-fann) model snapshots (`ruv-fann.dense-layers/1` JSON) in a versioned registry keyed by a task embedding, so you can find the snapshot saved for the most similar past task. It runs on `@ruvector/weight-space`, a dependency of `ruvector` that installs with it and is loaded only when a `weights` command runs, so it adds nothing to `ruvector --help` start-up. If an install is incomplete (for example a pruned `node_modules`), the command prints `npm i @ruvector/weight-space@0.1.0` and exits non-zero.

```bash
npm i @ruvector/weight-space@0.1.0
npx ruvector weights save --model model.json --embedding 1,0,0 --task classify --tags v1
npx ruvector weights save --model model.json --text "classify support tickets" # ONNX embedding
npx ruvector weights nearest --embedding 0.9,0.1,0 -k 5
npx ruvector weights lineage <id>
npx ruvector weights diff <idA> <idB> --json
npx ruvector weights get <id>

# Edit and fine-tune: each writes a CHILD snapshot of <id>; the parent never changes
npx ruvector weights set-layer <id> 0 --patch patch.json # {"bias":[...]} / weights / activation / steepness; shape cannot change
npx ruvector weights perturb <id> --scale 0.05 --seed 7 # seeded Gaussian noise (same seed, same model); --layers 0,1 --no-bias --relative
npx ruvector weights learn <id> --trajectories rows.json --epochs 300 --learning-rate 0.2
```

The registry is an append-only JSON-lines log, `.ruvector/weights.jsonl` by default (`--registry <path>`), with a `.index.db` vector index beside it. All snapshots in one registry share one embedding dimension, so do not mix `--text` (384-d) and hand-written `--embedding` vectors in the same registry. Registry and model paths must be inside the working directory. MCP clients get `weights_save`, `weights_nearest`, `weights_diff` and `weights_lineage`, which take an explicit `embedding` array and apply the same path rule (plus `RUVECTOR_MCP_ROOTS`).
`learn` trains on rows of `{input, output, score, correction?}`: a row at or above `--success-threshold` (default 0.5) trains toward its `output`, and a failure trains toward its `correction` (failures without one are skipped). A child snapshot is written **only if** a held-out check improves by at least `--min-improvement` (default 1%); otherwise nothing is written and the result says why, with exit code 0. Epochs are capped at 10,000 and trajectories at 10,000 rows.

The registry is an append-only JSON-lines log, `.ruvector/weights.jsonl` by default (`--registry <path>`), with a `.index.db` vector index beside it. All snapshots in one registry share one embedding dimension, so do not mix `--text` (384-d) and hand-written `--embedding` vectors in the same registry. Registry and model paths must be inside the working directory. MCP clients get `weights_save`, `weights_nearest`, `weights_diff` and `weights_lineage`, which take an explicit `embedding` array, plus the writing tools `weights_set_layer`, `weights_perturb` and `weights_learn` (inline `patch` / `trajectories`, or a `patch_path` / `trajectories_path` file). All apply the same path rule (plus `RUVECTOR_MCP_ROOTS`). To expose only the read tools, use `RUVECTOR_MCP_DENY=weights_save,weights_set_layer,weights_perturb,weights_learn`.

## Recipe: route unseen states with `neural-q` (`ruv-fann`)

The tabular learning algorithms score a state they have never seen as all zeros. `neural-q` fits a small MLP Q-function over hashed state features, so `refactor:.rs` is routed from what was learned on `fix:.rs` and `edit:.rs`. It runs on the optional peer [`ruv-fann`](https://www.npmjs.com/package/ruv-fann). Without it, `neural-q` behaves exactly like `q-learning`, and `ruvector` does not install it by default.
The tabular learning algorithms score a state they have never seen as all zeros. `neural-q` fits a small MLP Q-function over hashed state features, so `refactor:.rs` is routed from what was learned on `fix:.rs` and `edit:.rs`. It runs on [`ruv-fann`](https://www.npmjs.com/package/ruv-fann), an optional peer of `ruvector`. `ruv-fann` is also a dependency of `@ruvector/weight-space`, which `ruvector` now installs, so a default npm install resolves it and `neural-q` uses the MLP. A package manager that does not expose transitive dependencies to `ruvector` (pnpm's strict layout, for example) may not; install `ruv-fann@0.1.0` yourself there. Where `ruv-fann` does not resolve, `neural-q` behaves exactly like `q-learning`.

```bash
npm i ruvector ruv-fann@0.1.0
Expand Down
5 changes: 4 additions & 1 deletion npm/packages/ruvector/bin/mcp-server.js
Original file line number Diff line number Diff line change
Expand Up @@ -1902,7 +1902,7 @@ const TOOLS = [
}
},
// ── Weight registry Tools (optional @ruvector/weight-space) ──────────────
// weights_save, weights_nearest, weights_diff, weights_lineage
// weights_save, weights_nearest, weights_diff, weights_lineage, weights_set_layer, weights_perturb, weights_learn
...weightsTools.MCP_TOOLS,
// ── RVF Vector Store Tools ────────────────────────────────────────────────
{
Expand Down Expand Up @@ -4223,6 +4223,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
case 'weights_nearest':
case 'weights_diff':
case 'weights_lineage':
case 'weights_set_layer':
case 'weights_perturb':
case 'weights_learn':
return await weightsTools.runMcpTool(name, args, validateRvfPath);

// ── RVF Tool Handlers ─────────────────────────────────────────────────
Expand Down
Loading
Loading