ipjrb120803/circuitscope

CircuitScope

An interactive transformer visualizer and safety eval dashboard. The Explore tab walks through a model's forward pass in 3D and overlays where a phenomenon (temporal preference, harm framing) is linearly readable inside the network. The Dashboard tab runs the same probes as evaluations: knowing-saying gap analysis on held-out prompts, capability micro-benchmarks, and side-by-side model comparison across GPT-2, DistilGPT-2, GPT-2 medium, and Pythia-160m.

Built as an AI safety portfolio piece. The probing method, its honest limitations, and the extension path to new phenomena are documented below.

Two ways to run it

A) Public live version on Hugging Face Spaces (free, real URL, all models, live probing). The full backend runs on a free Space; anyone with the link probes any prompt on any bundled model. The free CPU tier sleeps when idle and wakes in ~30 seconds on the first visit after a pause.

One-time deploy:

# 1. fit probes + evals locally for the models you want live on the Space
pip install -r backend/requirements.txt
python backend/scripts/prepare_space.py --models gpt2 distilgpt2

# 2. create a Space at https://huggingface.co/new-space
#    - SDK: Docker  - Hardware: CPU basic (free)
# 3. rename SPACE_README.md to README.md IN THE SPACE (it carries the required
#    YAML header), then push this whole repo to the Space's git remote:
git remote add space https://huggingface.co/spaces/<your-username>/circuitscope
git add -A && git commit -m "CircuitScope Space"
git push space main

The Space builds the frontend and backend from the included Dockerfile and serves both on one URL: https://<your-username>-circuitscope.hf.space. Commit the fitted artifacts (backend/phenomena/*/probes, backend/cache) so probes are ready at boot; models themselves download on first request and cache on the Space disk.

B) Local full version (all models, causal interventions, ASR). Everything below.

Quick start

Requires Python 3.10+ and Node 18+.

pip install -r backend/requirements.txt

# fit probes + cache demos per model (downloads weights on first run, CPU)
python backend/scripts/precompute.py --models gpt2 distilgpt2

# run the safety eval suite per model (a few CPU minutes each)
python backend/scripts/run_evals.py --models gpt2 distilgpt2

cd frontend && npm install && npm run build && cd ..

make run          # or: python -m uvicorn backend.app.main:app --port 8000

Supported models: gpt2, distilgpt2, gpt2-medium, pythia-160m, and base/instruct pairs Qwen/Qwen2.5-0.5B(-Instruct), Qwen/Qwen2.5-1.5B(-Instruct), meta-llama/Llama-3.2-1B(-Instruct). Add any to both --models lists; weights download once per model. The header dropdown switches model family; where a base and instruct variant exist, a base/instruct toggle appears beside it. One model is held in memory at a time. Llama is gated on Hugging Face, so set HF_TOKEN in your environment before requesting it.

The base/instruct toggle is where the safety story lives: the attack-success-rate eval only applies to instruct models (base models have no refusal behaviour to attack), so comparing a base model against its instruct sibling shows what alignment training changed, both in behaviour (ASR, refusal rate) and in internals (the harm-framing probe and its causal faithfulness).

Open http://localhost:8000. Click any component in the schematic for a plain-language explanation, toggle Advanced mode for the numbers, and run a prompt to light up the circuit.

For frontend development with hot reload, run the backend as above and npm run dev in frontend/ (Vite proxies /api to port 8000).

What you're looking at

The main view is an interactive 3D rendering of GPT-2 small's actual forward pass in the spirit of bbycroft's llm-viz, but textured with live data. Token tiles at the base feed an embedding slab, and each of the 12 blocks above is drawn as a strip of 12 attention-pattern grids (each head's real seq-by-seq attention weights) plus a residual-stream slab showing that layer's actual activations, 768 dimensions downsampled to 64 cells per token. The residual stream also runs as a glowing beam beside the tower, and next-token predictions appear as probability bars at the top. Drag to orbit, scroll to zoom, click any part for a plain-language explanation, toggle Advanced mode for the numbers. A flat schematic view is available from the header for a more diagrammatic read of the same structure.

When you run a prompt, a pulse travels up the residual beam, the slabs fill with the prompt's actual activations, and every layer and head border is tinted by how strongly the internals lean toward the "immediate" (amber) or "delayed" (teal) framing direction. Selecting a head draws its attention pattern as arcs between the token tiles. The left panel also shows a knowing-vs-saying readout: the probe's internal reading against a crude behavioural score from the model's next-token distribution, a seed of the Phase 2 safety dashboard. Precomputed demos load instantly without inference; live prompts run a real forward pass on CPU (a second or two).

The dashboard

The dashboard reports proper interpretability and safety metrics, not loose accuracies:

Attack success rate (ASR), for instruct models: over a set of harmful requests, the fraction where the model's first-token compliance mass exceeds its refusal mass, read against the benign compliance rate as a baseline. This is a next-token proxy, not full generation grading, and is stated as such.

Knowing-saying gap, per phenomenon: probe AUROC and behavioural AUROC on held-out prompts, class separation (Cohen's d), sign-disagreement rate, and the internal-vs-stated scatter. AUROC and separation are threshold-free, which is what you want when comparing probes across models and layers.

Causal faithfulness: the fraction of the behavioural signal that collapses when the probe direction is ablated from the residual stream, plus ablation flip rate and steering shift. A high-AUROC direction with low faithfulness is exactly the knowing-saying gap made quantitative, a direction that reads well but the model barely uses.

Capability micro-benchmarks (arithmetic, factual recall, subject-verb agreement, induction copying) via teacher-forced log-prob comparison. Selecting two models (or a base/instruct pair) shows a delta table including ASR and disagreement.

All numbers are comparable within this suite, not against published benchmarks, and the UI labels each metric's evidence level.

Method

The probe is difference-in-means. 50 paired sentences, identical except for temporal framing ("the payment arrives right now" vs "the payment arrives in ten years"), are run through the model. For each layer, the direction is the mean difference between the two groups' residual stream activations at the final token, and a prompt's score is its projection onto that direction, standardized against training statistics. Pairs never straddle the train/test split, and held-out accuracy per layer is shown in the UI. Head-level highlights project each head's output contribution onto the layer direction.

Rigor and controls

The probe pipeline now carries its own evidence hierarchy, marked in the UI with correlational and intervention badges. Best-layer selection uses 4-fold cross-validation over training pairs only, never the held-out set. Held-out accuracy is reported with a 95% binomial CI next to a label-shuffle control fit through the identical pipeline, which should sit near chance. A logit-lens readout shows which vocabulary tokens each layer's direction writes toward, making lexical shortcuts visible instead of hidden, and a position-by-layer score map shows where in the sentence the signal appears. The causal layer on top: directional ablation (the best-layer direction projected out of the residual stream at every layer, in the style of Arditi et al.'s refusal-direction work) and ±3σ activation steering, with the resulting shift in behavioural output reported per prompt and aggregated in the dashboard as ablation effect, flip rate, and steering shift.

The browser demo vs the local app

The browser demo shows GPT-2's genuine precomputed internals (real per-layer and per-token probe scores, logit lens, attention, knowing-saying readout) for a curated prompt library, and matches typed prompts to the nearest library entry. It does not run the model live, because the standard GPT-2 ONNX export exposes only logits, not the residual stream, so browser-side activation extraction is not possible without a custom multi-hundred-MB model export (over GitHub's file limit). The local app runs any prompt live with the full residual stream via TransformerLens, plus per-head attribution, causal ablation/steering, the multi-model base/instruct comparison, and ASR. Both are honest about which is which.

Limitations, stated plainly

The overlay itself remains a correlational reading on small synthetic datasets; the intervention numbers are the causal evidence, and they are single-direction, single-behaviour tests, not circuit-level claims. Template datasets share surface vocabulary, so part of the signal is lexical, which the logit lens and position map are there to expose rather than hide. Micro-benchmark numbers are comparable within this suite only. Treat everything as "where to look first and how much to trust it", not "what the model is thinking".

Adding a phenomenon

Drop a folder under backend/phenomena/<id>/ with metadata.json (name, description, labels, colors, behaviour token sets) and dataset.json (contrast examples {text, label, pair_id}), then rerun precompute.py. The API, registry, overlay, and phenomenon selector pick it up without code changes. Two phenomena ship: temporal preference and harm framing (mild descriptive contrasts, deliberately non-operational).

Sharing a static copy

To produce a single HTML file you can attach to an email (recipients just double-click it; demos and the full dashboard work, live probing is disabled with a note):

cd frontend && npm run build:single && cd ..
python backend/scripts/export_static.py --models gpt2 distilgpt2

This writes circuitscope.html (~3-6 MB) at the repo root.

Tests

make test         # runs on a tiny random model, no downloads

Layout

backend/app/        FastAPI app, model layer, probing, phenomenon registry
backend/scripts/    dataset generator, one-time precompute
backend/phenomena/  contrast datasets + fitted probes
backend/cache/      precomputed demo payloads
frontend/           React + Vite + TypeScript, SVG schematic, CircuitsVis attention

Credits

Model access via TransformerLens (MIT). Attention heatmaps via CircuitsVis (MIT). Visual walkthrough concept inspired by bbycroft/llm-viz (design reference only; no code reused, as it ships no license).