CircuitKIT : Circuit Discovery, Evaluation, and Application Toolkit for Mechanistic Interpretability

Abstract: Circuit analysis can support not only model explanation but also downstream interventions such as pruning, editing, steering, and selective fine-tuning. However, conducting such analyses currently requires stitching together separate implementations for discovery, evaluation, and intervention, as well as hand-authoring the contrastive prompts required by many discovery methods. This fragmentation makes methods difficult to compare and limits their application beyond canonical tasks. We introduce CircuitKIT, a source-available library that connects the circuit-analysis workflow through a typed, serializable representation. CircuitKIT provides a suite of discovery algorithms, declarative interfaces for mapping structured data into discovery tasks, complementary circuit diagnostics, and downstream application modules. Together, these components provide common infrastructure for conducting and comparing circuit analyses. The library, examples, notebooks, and documentation are released at https://github.com/Lexsi-Labs/CircuitKIT .

• The paper introduces CircuitKIT, a typed and serializable toolkit that unifies 13 circuit-discovery algorithms, six faithfulness-evaluation pillars, and seven intervention modules across a common discover–evaluate–intervene workflow.
• The paper demonstrates that circuit quality depends on the evaluation and intervention used: patch faithfulness reached 1.00 in several studies, yet pruning utility showed a strong negative correlation with patch faithfulness (Spearman ρ = −0.78).
• The paper provides custom-data ingestion, clean-only and contrastive discovery routes, node- and neuron-level analysis, and declarative YAML workflows while documenting important limitations in cross-seed reliability, model coverage, and statistical power.

Circuit analysis in mechanistic interpretability has accumulated a rich set of methods for discovering, evaluating, and acting on circuits—the subgraphs of attention heads, MLP sublayers, and neurons causally responsible for a target behavior—but these methods ship in per-paper repositories with incompatible artifact formats. CircuitKIT addresses this fragmentation by providing a source-available Python library that composes the full discover–evaluate–intervene pipeline behind a single typed, serializable artifact, and by offering a declarative path from structured user data to circuit discovery (2607.19317).

Motivation and positioning

The paper identifies two gaps in the existing tooling ecosystem. The first is pipeline fragmentation: discovery algorithms (EAP, EAP-IG, EAP-GP, ACDC, IBCircuit, CD-T, RelP), evaluation criteria (MIB, InterpBench, Auto-Circuit's patching metrics), and downstream interventions (ROME, MEMIT, LLM-Pruner, activation steering) each live in separate codebases, so every method–criterion–intervention combination requires custom glue code. The second gap is subtler and empirically consequential: faithfulness scores depend on the ablation method used to compute them, and switching that single choice can reverse the ranking of discovery methods (Miller et al., 2024). Because each repository hard-codes its ablation choice, numbers do not compare across papers. Existing substrates such as TransformerLens and NNsight provide hook-based introspection but ship no standardized task interface, multi-criterion evaluation framework, or intervention contract; MIB and InterpBench are fixed-dataset benchmarks that neither accept user data nor connect to interventions.

A finer gap lies on the data side. Contrastive attribution methods require every example to arrive as a (clean, corrupt) pair, which is freely available for canonical tasks like IOI but is the practical bottleneck for arbitrary structured datasets. CircuitKIT's template-driven custom-data path, plus clean-only routing to IBCircuit and CD-T, closes this gap.

Architecture and the shared artifact

CircuitKIT is built on TransformerLens and organizes the workflow around CircuitScores, a typed, serializable record carrying the task descriptor, model identifier, discovery algorithm, granularity level, per-component attribution scores, and configuration. Discovery backends produce this artifact; evaluation produces a FaithfulnessReport; application modules consume the artifact and produce modified models or checkpoints. Three interchangeable interfaces—a stateful Pipeline, a flat functional API, and a YAML-driven CLI—operate over the same artifact contract, so a circuit discovered in one interface can be evaluated or applied through another without conversion.

Discovery algorithms and granularity

The library ships thirteen discovery algorithms across four backend families, split into explicit stability tiers. Six stable-tier algorithms have been tested across GPT-2, Llama, Gemma, and Qwen families: the gradient-attribution EAP family (EAP, EAP-IG, EAP-GP), the search-based ACDC, the information-bottleneck IBCircuit, and contextual decomposition (CD-T). Seven research-tier variants extend the EAP family and are validated only on GPT-2/IOI. The tier split is a governance mechanism: stable methods carry backward-compatibility guarantees, and research methods are promoted as cross-model validation evidence accrues.

A distinguishing design choice is that discovery runs at two first-class granularities. At node level, an entire attention head or MLP sublayer receives one score; at neuron level, per-head channels and MLP neurons are scored individually. For the MLP, an mlp_hook option selects between scoring at the residual-stream interface (mlp_out) and at the post-activation hidden layer (post_act, the conventional "MLP neuron"). Neuron-level circuits map directly onto the units that the intervention modules prune, quantize, or fine-tune, which is what makes the granularity choice consequential rather than cosmetic. ACDC is node-only by construction.

Task specification and the custom-data path

Tasks are specified in three modes. Sixteen built-in tasks are registered by short key (IOI, greater-than, MMLU, BoolQ, WMDP, and others), each with prompts, metrics, and dataloaders. The template-driven path maps a CSV, JSONL, or HuggingFace dataset into a discovery task by declaring prompt and answer templates over its columns; the pipeline handles token-length alignment between clean and corrupt halves (filtering, padding, or passing through misaligned pairs), which is a correctness requirement for element-wise EAP attribution rather than a convenience. When only clean data exists, the task routes automatically to IBCircuit or CD-T. An automatic HuggingFace ingestion path infers dataset schemas via a DatasetShape taxonomy and runs a pre-flight "worthiness" gate—eight checks covering token alignment, answer determinism, logit-difference signal, class balance, and pair uniqueness—returning a green/yellow/red verdict before discovery compute is spent. A corruption package synthesizes the corrupt half when no counterfactual exists, with answer-changing strategies (entity-swap, token-swap, role-swap) for discovery and answer-preserving strategies (paraphrase, distractor) reserved for robustness testing; a degenerate-pair check prevents silently discovering on clean-equals-corrupt pairs.

Multi-pillar faithfulness evaluation

Because single faithfulness metrics are not robust across ablation methods (Miller et al., 2024), CircuitKIT reports a panel of six configurable pillars from one entry point: causal patching (soft counterfactual, complement noised toward corrupted activations), ablation faithfulness (hard removal with zero/mean/mean-positional replacement), stability (Jaccard overlap and Spearman correlation across data resamples), robustness (score retention across a corruption-strategy family), baseline comparison (against size-matched random and magnitude subgraphs), and generalization (cross-task transfer, with a transfer-matrix tool). Ratios are reported signed rather than clamped to $[0,1]$: a value below zero indicates a behavioral inversion beneath the corrupt-run baseline, and the paper demonstrates on real data (studies E3 and E4) that clamping would hide this signal. An optional seventh pillar, intervention reliability, aggregates seed consistency, effect magnitude, and effect variance across re-discoveries into a harmonic-mean reliability index; it is optional because it requires re-running discovery rather than scoring a single circuit.

Intervention modules

Seven application modules consume the shared artifact. Three form the primary layer: structural pruning (zero-masking low-scoring components, with LLM-Pruner integration for circuit-guided importance as a drop-in criterion against magnitude and Taylor baselines), mixed-precision quantization (circuit-ranked tier assignment under a fixed precision budget via quanto or llmcompressor), and selective fine-tuning (resolving top-$k\%$ components to weight-matrix index ranges for static gradient masks or LoRA target modules). Four further modules ship in the library: ROME/MEMIT knowledge editing restricted to circuit-resident MLP layers (with a cached get_covariance for the model-specific second-moment statistic), activation steering via per-node steering vectors, CircuitLoRA healing of pruned models, and hallucination probing. All exported checkpoints are scored through lm-evaluation-harness, which is what lets intervention studies report standardized accuracy rather than proxy metrics. A selector registry with fourteen built-in importance functions makes circuit-versus-baseline comparisons a matter of swapping one configuration field.

Validation studies

Seven studies validate the pipeline stage by stage, with the intervention studies (E5–E7) reusing runs from a companion actionability audit.

Algorithm validation (E1). On GPT-2 Small IOI at node level, the EAP family recovers the behavior with perfect patching (P1 = 1.00) and the highest canonical-head overlap (Jaccard 0.43–0.50, recall 0.60–0.67) at minute-scale cost. The most instructive result is a disagreement: CD-T is faithful by both pillars (0.89 patching, 1.00 ablation) yet shares zero heads with the canonical IOI taxonomy, routing twelve of its fifteen top slots through MLPs. Only the overlap columns beside the faithfulness columns distinguish a canonical circuit from an equally faithful non-canonical one. ACDC scores poorly under the fixed-sparsity protocol (0.21/0.04) at 24–133× the cost, which the paper attributes to projecting its variable-size edge set onto a fixed node budget rather than to the underlying search.

Cross-family discovery (E2). With EAP-IG fixed, all twelve (model, task) cells across six families (GPT-2 Small through Phi-2) complete with only a model-name change. Patching recovery is high everywhere (P1 ≥ 0.91, six cells at exactly 1.00) and stability is strong ($J$ = 0.80–0.92); every circuit beats a size-matched random subgraph. But ablation sufficiency ranges from 0.24 (Gemma-2-2B/IOI) to 1.00 (Phi-2/IOI) across cells with nearly indistinguishable patching scores. A reader taking P1 alone would call the circuits interchangeable; one taking P2 alone would call discovery a failure on Gemma.

Neuron-level discovery (E3). On Llama-3.2-1B IOI, EAP-IG holds perfect patching at neuron granularity (P1 = 1.00) at essentially node-level cost, while single-point-gradient EAP inverts under hard ablation (signed P2 = −0.35, raw logit difference −0.57 against a clean-run 1.69). Integrated-gradient interpolation matters most where single-point gradients are noisiest, i.e., at fine granularity.

Custom-data path (E4). A 334-row jailbreak-detection CSV reaches a multi-pillar-evaluated refusal circuit on Qwen2.5-1.5B-Instruct with zero pairing code, down both the paired route (EAP-IG, 85% of the refusal gap recovered, 1.71× over random baselines) and the clean-only route (IBCircuit at neuron level matching full-model accuracy). The striking finding is the soft/hard disagreement: the same circuit that recovers 85% under patching inverts toward compliance under hard zero-ablation (signed ratio −2.61). Localizing a safety behavior and preserving it under intervention are different achievements, which bears directly on refusal-direction and circuit-restricted editing work (Arditi et al., 2024, Kasliwal et al., 4 Feb 2026). Cross-route agreement and multi-seed stability for this cell were not run and are not claimed.

Pruning (E5). Circuit-guided pruning is competitive at the top—IBCircuit retains 98.6% of base accuracy on Llama-3.2-3B-Instruct/BoolQ at 30% sparsity, within 4.1 pp of Taylor—while magnitude, Wanda, and random collapse (50.1–51.9%). The bold claim is the anti-correlation: across the audit's ten-selector grid, patch faithfulness anti-correlates with pruning retention (Spearman $\rho = -0.78$, $p = 0.010$). EAP-IG and CD-T rank among the worst compressors despite strong patch faithfulness. The implication is direct: a faithfulness score is evidence about what a circuit explains, not a forecast of what happens when one acts on it, so extrinsic validation before committing to a cut is not optional. The paper concedes this is one cell of a broader audit, not a population estimate.

Quantization (E6). Under a fixed 3-bit/8-bit recipe, patch faithfulness does not predict retention ($\rho = +0.23$, $p = 0.55$, non-significant), while ablation faithfulness does ($\rho = +0.73$, $p = 0.031$), consistent with zero-ablation being a closer counterfactual to quantization error than activation patching. Quantization distributes precision rather than forcing a hard partition, so the ranking errors that punish pruning have no channel through which to bite.

Selective fine-tuning (E7). A null result on both axes, reported as such: circuit selection does not separate from random selection at matched budget (pooled mean $\Delta$(circuit − random) = −0.001), while masked fine-tuning of either kind preserves WikiText-2 perplexity near the unmodified model's 11.05 (12.0–14.1), versus 14.2–22.0 for full-parameter training. What protects coherence is the budget constraint itself—freezing 70% of the model—not which 30% is chosen.

Read together, E5–E7 establish the paper's central empirical pattern: the value of a circuit signal depends on the intervention that consumes it. Pruning forces a hard partition where selector quality is decisive; quantization forces none; fine-tuning constrains a budget where mask identity is irrelevant. This is the toolkit-level argument for a faithfulness panel over a single score.

Extensibility, visualization, and interfaces

All extension points follow one pattern: a typed registry with a decorator entry point. Fourteen selectors, thirteen discovery algorithms, ten corruption strategies (each declaring a LengthContract so gradient-based methods can verify token alignment), and architecture-registry entries for intervention-capable model families (Llama, Qwen, Gemma primary; Mistral, Phi, GPT-2, Falcon structurally complete) all register without touching the core. Visualization offers graph, comparison, and dashboard modes over the same artifact, and reporting serializes to JSON for cross-run diffing. The CLI exposes fifteen commands, and a version-controlled YAML file executes an entire discover–evaluate–intervene–benchmark run with no Python.

Limitations and open questions

The paper is explicit about its constraints. Intervention coverage trails discovery because interventions require architecture-registry entries and inherit TransformerLens's version pins (3.x support is planned). IBCircuit trains its mask in a single batch, limiting its footprint at scale; ACDC is node-only by construction. The corruption strategies assume identifiable syntactic structure and may find nothing to perturb on instruction-tuned prompts, where user-supplied corrupt columns are recommended. Statistical power is bounded throughout: the stability pillar uses three resamples, the other studies are single-seed, and the cross-seed intervention reliability (Pillar 7's $k\%$0) is unmeasured, leaving the stability-to-reliability association an open empirical question. The headline $k\%$1 pruning anti-correlation is one (model, task) cell of a broader audit that the paper says replicates only qualitatively on Gemma-3-4B-IT, where full-parameter training is itself unstable. On ethics, the library is released under the Lexsi Labs Source Available License (LSAL v1.1), which permits research and audit use while prohibiting commercial exploitation and safety-degrading applications—a deliberate response to the dual-use risk that E4 makes concrete, since a discovered refusal circuit can, isolated under hard ablation, invert from refusal toward compliance.

Conclusion

CircuitKIT contributes common infrastructure for the full circuit-analysis workflow: thirteen discovery algorithms behind one typed artifact, six-plus complementary faithfulness diagnostics motivated by the known non-robustness of single metrics, seven intervention modules, and a declarative path from raw structured data to discovery that removes the contrastive-pairing bottleneck. Its validation studies are notable less for confirming the pipeline than for documenting where the pipeline's own diagnostics disagree—faithful-but-non-canonical circuits, patch/ablation inversions on safety behaviors, and the negative correlation between patch faithfulness and pruning utility. The paper's stance is that CircuitKIT standardizes how circuit hypotheses are produced, evaluated, and applied without assuming that any discovery method or intrinsic score is universally reliable, and its open questions—cross-seed intervention reliability, corruption-strategy coverage on adversarial datasets, and the generality of the faithfulness–actionability decoupling—are precisely the ones its infrastructure is positioned to measure.