# nous-circuits

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.