Eve library

nous-circuits

Other

Revision 1

On this page

Circuit discovery and feature graphs for mechanistic interpretability (Phase 177.3), in PyTorch, CPU-runnable.

Model-agnostic core#

graph.py — a CircuitGraph DAG of component nodes and candidate edges (topological order, reverse-topological edge order, subgraphs). model.py — an AdditiveDAG runner: a real differentiable computational graph where value[c] = act(bias + Σ W[p,c]·src[p]) and an ablated edge feeds the child its parent's corrupt-run value. With act=identity the network is linear, giving a known ground-truth circuit the discovery algorithms are verified against.

Discovery#

  • ACDC (acdc.py, 177.3.1.1) — Conmy et al. Greedy reverse-topological edge ablation; prune an edge when removing it raises divergence-from-clean by ≤ τ. Recovers the minimal circuit.
  • EAP-IG (eap_ig.py, 177.3.1.2) — Syed/Rager/Conmy. Integrated-gradient edge attribution along the corrupt→clean input path, scoring every edge from one backward-per-step. score(p→c) = ⟨Δvalue[p], W[p,c]ᵀ·∂metric/∂pre[c]⟩ (IG). Dead / zero-signal edges score ~0; top-scored edges match ACDC's kept set.
  • Transcoders (transcoder.py, 177.3.1.3) — a wide sparse ReLU replacement for one MLP predicting its output from its input residual, so every residual→feature→output path is a clean, additive feature-graph edge (f_i · W_dec[i]).

Visualisation (177.3.1.4)#

viz.py — a CircuitVisualisation that exports the discovered circuit (nodes by layer, edges weighted by importance, per-prompt activation traces, downstream token effects) to a JSON contract and renders it into a self-contained, offline interactive HTML page (inline SVG + vanilla JS; hover a node for its activation trace and top token effects). No external assets.

Tests#

python3 -m pytest tests/ -q — 17 tests: topological order + cycle detection, dead-edge signal check, ACDC recovering the exact ground-truth circuit and reproducing the clean metric, EAP-IG scoring dead edges ~0 / matching ACDC / the output-edge completeness identity, transcoder MLP approximation (FVU < 0.15)

  • additive feature contributions, and the visualisation JSON/HTML contract.

Not locally actionable#

177.3.2.1–177.3.2.4 (refusal / factual-recall / code-generation / deception circuit investigations on real trained @nous/llm, @iris/code checkpoints) require those trained weights and are left unchecked; the discovery tooling they would use is complete here.