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
6 changes: 5 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,11 @@ jobs:
- run: ruff check .

frontend:
runs-on: ubuntu-latest
# Pinned: ubuntu-latest now resolves to Ubuntu 26.04 on some runners, where
# `playwright install --with-deps chromium` (Playwright 1.55.0) has no
# supported system packages and exits 1. Return to ubuntu-latest once
# @playwright/test is upgraded to a release that supports 26.04.
runs-on: ubuntu-24.04
defaults:
run:
working-directory: evalrx/reporting/web
Expand Down
71 changes: 71 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,77 @@ Versions follow [Semantic Versioning](https://semver.org/).

## [Unreleased]

### Added — validation report for the published weight edit on Qwen3.5-0.8B

`docs/validation/astra_p50c_20261115.md` records the structure read-out, the
teacher-forced audit, the generation-level repair through the L4 fix path, and
the attempt to derive the edit from a loop contrast, with their limits. The
README gains sections on probe tools and weight edits.

### Added — generation-level check of a weight edit

`tools/generate_astra_edit_qwen35.py` runs the published p50c edit through the
L4 fix path on GSM8K: baseline, edit and random-direction control are each
generated (thinking on, the original sampling settings, batched and cached per
weight state), validated with the paired test, and summarised by whether the
model left its thinking block, stopped on its own, ended in a loop, and was
correct. `--timing-only` checks that padded batching is exact on the
architecture and prints a time estimate.

### Added — deriving and comparing weight edits along a generation

`continuation_contrast_edit` derives a rank-one edit from the contrast between
positions inside a repeated stretch and positions outside one, along recorded
generations; `collect_continuation_stats` and `rank_columns` expose the group
means and per-neuron signals. `fit_rank_one` re-expresses any edit as the
rank-one rule that reproduces it (so it can be scaled), and `edit_agreement`
compares two edits by direction and neuron overlap. `contrast_edit` and the new
function share one core, `edit_from_stats`. `tools/recover_astra_edit_qwen35.py`
runs the comparison against the published p50c edit.

### Added — weight-edit audit along a generation

`weight_edit_continuation_audit` follows a weight edit along recorded
generations (`case.observed`), teacher-forced, and reports the change in
next-token NLL and the KL from the unedited model separately for positions
inside a repeated stretch and outside one, beside the random-direction,
random-neuron and steering controls. `tools/check_astra_edit_qwen35.py` and
`tools/audit_astra_edit_qwen35.py` run the structure check and this audit for
the published p50c edit on Qwen3.5-0.8B.

### Added — probe tools (`evalrx.probing`)

Every registered analyzer is described as a tool: family, the question it
answers, access level, cost hint, JSON-schema arguments, and its availability
on a given model and batch with every reason it cannot run
(`describe_probes`, modelled on VLMProbe's `Prober.describe()`).
`ProbeRouter` ranks runnable probes for failure modes, families and access;
`ProbeToolbox.call(name, params)` runs one with schema-checked arguments and
`.tools()` returns `evalrx.core.tool.Tool` objects.

The agentic loop gains `list_probes` and `run_probe` accepts `name` + `params`
(or `probes: [...]`). Named calls run exactly the named probes, add to the
evidence gathered so far, and are rejected before any model work when the
arguments or the probe do not fit. `ProbeAgent.probe` takes `analyzer_params`
and `exact`; a pinned re-run replays the arguments of the named call.
`run_probe` with no arguments is unchanged and still limited to 3 calls per
run; the tool's overall cap is 6 to leave room for named calls.

### Added — weight-space programming (`evalrx.wsp`)

Direct, training-free weight edits: `TensorEdit` / `WeightEdit` (rank-one rule
`w' = w - alpha u (u^T w)`, low-rank, dense delta, sparse overwrite), `applied()`
(writes the edit and restores the exact weights, also on error), controls
(`random_direction`, `random_columns`), `edit_structure`, `contrast_edit`
(an edit derived from failing vs passing cases), and a reader for the edit
files published with *Sparks of Weight-Space Programming*.

New analyzers `weight_edit_structure` and `weight_edit_audit` (the edit beside
random-direction, random-neuron and steering controls). New opt-in L4 repair
candidate `rank_one_weight_edit` via `FixAgent(weight_edit=...)`, validated by
the existing paired test and recorded with a matched control. See
`docs/wsp_and_probe_tools.md`, including what has not been checked yet.

### Fixed — delta-rule relevance on transformers 5.23

transformers 5.23 moved the grouped query/key head expansion of Qwen3-Next /
Expand Down
56 changes: 55 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,11 +155,29 @@ spec runs through a black-box API or a white-box local backend — only the
available capability set changes. [Analyzer Zoo →](docs/analyzers.md) ·
[Architecture guide →](docs/architecture.md)

Analyzers are also callable as tools. Each one is described by the question it
answers, what it needs and the arguments it takes, and reports whether it can
run on the model and data in hand — and if not, why:

```python
from evalrx.probing import ProbeToolbox

box = ProbeToolbox(model, cases)
box.describe()["attention_knockout"]["missing"] # why a probe cannot run here
box.route(failure_modes=["visual_neglect"]).names # what to run first
box.call("logit_lens", {"top_k": 5}) # arguments checked against a schema
```

In the agentic loop the judge gets the same view: `list_probes` shows what can
run, and `run_probe` takes a probe's name and arguments.
[Probe tools →](docs/wsp_and_probe_tools.md#probe-tools)

## Docs & Examples

[Quickstart](docs/quickstart.md) · [CLI](docs/cli.md) ·
[Exploratory Analysis](docs/m2_analysis.md) ·
[Intervention & Verification](docs/intervention.md) ·
[Weight Edits & Probe Tools](docs/wsp_and_probe_tools.md) ·
[Analyzer Zoo](docs/analyzers.md) · [Architecture](docs/architecture.md) ·
[Extending EvalRX](docs/extending.md) · [Roadmap](docs/roadmap.md) — all live,
searchable, at [evalvitals.github.io/evalrx](https://evalvitals.github.io/evalrx/overview/).
Expand Down Expand Up @@ -203,11 +221,47 @@ raising it rather than climbing on its own.
| **L2** | Scaffolds around an unchanged model — multi-call, tools, aggregation | ✅ |
| **L3a** | Read internals — attention-guided cropping, contrastive decoding | ✅ |
| **L3b** | Write internals — attention reweighting, activation steering | ✅ |
| **L4** | **Parameter space — build a dataset, fine-tune, re-test** | ✅ LoRA on the LLM ([`fix_internals.py`](evalrx/eval_agent/stages/fix/internals.py)); other recipe shapes recorded, not yet executed |
| **L4** | **Parameter space — build a dataset, fine-tune, re-test; or write a training-free weight edit** | ✅ LoRA on the LLM ([`internals.py`](evalrx/eval_agent/stages/fix/internals.py)); ✅ rank-one weight edit, opt-in ([`weight_edit.py`](evalrx/eval_agent/stages/fix/weight_edit.py)); other recipe shapes recorded, not yet executed |

**L3b and L4 only exist for open weights** — you cannot modify a forward pass
or fine-tune through somebody's API.

### Weight edits

A weight edit changes a model by writing new values into a few tensors, with no
training: for example `w' = w - alpha * u (u^T w)` on some columns of one MLP
output projection. `evalrx.wsp` builds, applies and restores such edits, reads
their structure from the weights, and audits them against controls:

```python
from evalrx.analyzers.weights import WeightEditContinuationAudit
from evalrx.wsp import WeightEdit, applied, edit_structure

edit = WeightEdit.load("path/to/edit")
edit_structure(model, edit) # where it moved, its rank, its alpha
with applied(model, edit): # written in, then restored exactly
answer = model.generate(case.inputs)
WeightEditContinuationAudit(edit=edit).run(model, cases) # vs random direction, other neurons, steering
```

As a repair it is one more L4 candidate, validated by the same paired test and
recorded beside a matched random-direction control:
`FixAgent(max_tier="L4", weight_edit=True, finetune_pool=...)`.

Checked on Qwen3.5-0.8B with the edit published in
[*Sparks of Weight-Space Programming*](https://rikiyat.github.io/blog/weight-space-programming/):

| | Unedited | Edited | Random-direction control |
|---|---|---|---|
| GSM8K correct (64 problems, 16,384-token budget) | 6 | 37 | 7 |
| Left the thinking block | 10.9% | 92.2% | 9.4% |
| Ended in a verbatim loop | 87.5% | 1.6% | 90.6% |

31 fixed, 0 broken. That edit was written by another system; deriving one from
the model's own behaviour recovered about half of its neurons and not its
direction. [Full results and limits →](docs/validation/astra_p50c_20261115.md) ·
[Weight edits guide →](docs/wsp_and_probe_tools.md#weight-edits)

## Project Status

EvalRX is an early-stage research toolkit; interfaces may evolve, and some
Expand Down
33 changes: 32 additions & 1 deletion docs/analyzers.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,10 @@ model, not by a black-box / white-box label.
| [Lens](#lens) | `lens/` | 6 | 0 |
| [Patching](#patching) | `patching/` | 6 | 0 |
| [Geometry](#geometry) | `geometry/` | 2 | 0 |
| [Weights](#weights) | `weights/` | 3 | 0 |
| [Reasoning](#reasoning) | `reasoning/` | 7 | 0 |
| [Agent](#agent) | `agent/` | 7 | 0 |
| **Total** | | **54** | **2** |
| **Total** | | **57** | **2** |
<!-- END GENERATED -->

How to read the columns:
Expand Down Expand Up @@ -215,6 +216,36 @@ encoders; on a decoder-only MLLM, read them as within-stream layer similarity.
| Linear probe | `linear_probe` | `HIDDEN_STATES` | text + image | [Alain & Bengio 2016](https://arxiv.org/abs/1610.01644) | ✓ |
<!-- END GENERATED -->

### Weights

`evalrx/analyzers/weights/`: what a direct weight edit changes, and whether the
change is specific (`LOGITS` on a local model; the edit is written into the
module for the measurement and restored exactly afterwards). Both analyzers take
the edit as a constructor argument, an `evalrx.wsp.WeightEdit`, so a selector
only offers them when the host passes a constructed instance. See
[Weight edits and probe tools](wsp_and_probe_tools.md).

`weight_edit_structure` needs no cases: it reports where the weights moved, how
far, the rank of the change, and for a rank-one change the strength `alpha` of
the rule `w' = w - alpha u (u^T w)` that reproduces it. `weight_edit_audit`
measures the edit on the next-token distribution beside a random direction of
the same size, the same rule on other neurons, and a constant activation shift
with the weights untouched.

`weight_edit_continuation_audit` takes the same measurement along recorded
generations (`case.observed` appended to the prompt, teacher-forced), split into
positions inside a repeated stretch and positions outside one. Use it for an
edit whose effect only appears during generation, such as one that breaks
repetition loops.

<!-- BEGIN GENERATED: analyzers/weights -->
| Analyzer | Key | Requires | Modality | Paper | Status |
|---|---|---|---|---|---|
| Weight-edit structure | `weight_edit_structure` | `LOGITS` | text | [Takehi et al. 2026 (WSP)](https://rikiyat.github.io/blog/weight-space-programming/) | ✓ |
| Weight-edit audit | `weight_edit_audit` | `LOGITS` | text | [Takehi et al. 2026 (WSP)](https://rikiyat.github.io/blog/weight-space-programming/); [Zhang et al. 2026 (EditLens)](https://xxlya.github.io/editlens/) | ✓ |
| Weight-edit continuation audit | `weight_edit_continuation_audit` | `LOGITS` | text | [Takehi et al. 2026 (WSP)](https://rikiyat.github.io/blog/weight-space-programming/); [Zhang et al. 2026 (EditLens)](https://xxlya.github.io/editlens/) | ✓ |
<!-- END GENERATED -->

### Reasoning

`evalrx/analyzers/reasoning/`: text-chain diagnostics, all black-box. Read the
Expand Down
2 changes: 2 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,8 @@ evalrx/
+-- specs.py # model identity registry
+-- models/ # model composition, runtime backends, compatibility shims
+-- analyzers/ # analyzers grouped by capability (attention, lens, uncertainty, …)
+-- probing/ # analyzers as tools: catalog, availability, routing, calls by name
+-- wsp/ # weight edits: build, apply/restore, controls, structure
+-- datasets/ # loaders that produce FailureCase / CaseBatch
+-- stats/ # statistical tests: McNemar, e-value, bootstrap CI, Friedman
`-- eval_agent/ # automated diagnosis loop + selective-inference orchestration
Expand Down
5 changes: 5 additions & 0 deletions docs/intervention.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,11 @@ it:
| L3b | internals (write) | Modifies the forward pass (attention reweighting, sink suppression, activation steering). |
| L4 | parameter space | Fine-tune recipe, always recorded for a human decision. v1 additionally *executes* one shape — LoRA on the language model — when you pass `FixAgent(finetune_pool=...)` (a diagnosis-only `CaseBatch`, disjoint from what's being validated); other recipe shapes stay recorded-only. |

L4 also has a training-free option: `FixAgent(weight_edit=True, finetune_pool=...)`
proposes a rank-one weight edit built from the diagnosis pool, validated by the
same paired test and recorded beside a matched random-direction control. See
[Weight Edits and Probe Tools](wsp_and_probe_tools.md#as-a-repair-fix-tier-l4).

```python
outcome = loop.run_fix(report, failure_cases, auto_escalate=True) # steps L2 → L3a → L3b
```
Expand Down
2 changes: 2 additions & 0 deletions docs/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,8 @@ surfaces and planned interfaces.
| **RunContext** | **Single owner of a run's output directory (`report/`, `figures/`, `artifacts/`, `experiments/`, `fixes/`, `manifest.json`, auto-generated `README.txt`); per-trial folders (`new_trial()`) for fix candidates and M5 experiments.** |
| **FixAgent** | **Tiered post-loop repair (L1 prompt → L2 scaffold → L3a/b internals → L4 parameter space); paired McNemar + e-value validation; `max_repair_rounds` feedback-driven retry with candidate dedup; `loop.run_fix(auto_escalate=True)` steps the tier ladder.** |
| **Result image overlays** | **`RelativeAttentionResult.overlay()`/`.image_overlays()` — CAM-style heatmap-on-source-image blending; duck-typed hook picked up by `RunLogger` into `figures/`.** |
| **Probe tools** | **`evalrx.probing`: every analyzer as a tool (family, question, access, cost, JSON-schema arguments), availability with reasons, `ProbeRouter`, `ProbeToolbox.call(name, params)`; agentic `list_probes` and named `run_probe`.** |
| **Weight edits (WSP)** | **`evalrx.wsp`: `WeightEdit` / `TensorEdit` (rank-one, low-rank, dense, sparse), reversible `applied()`, controls, structure read-out, contrast-derived edits; `weight_edit_structure` / `weight_edit_audit` analyzers; opt-in L4 `rank_one_weight_edit` repair. Tested on a planted-defect model and tiny random modules, not yet on a full-size model.** |
| Contract tests | Parametrized pyod-style suite covering all 26 registered analyzers (554 unit tests). |

## Stage 2 stubs (registered, `_run` raises `NotImplementedError`)
Expand Down
Loading
Loading