Metadata-Version: 2.4
Name: circuitkit
Version: 0.1.3
Summary: Unified Discover, Evaluate, Intervene toolkit for mechanistic interpretability: 13 circuit discovery algorithms, 6-pillar faithfulness evaluation, and pruning / quantization / knowledge editing / unlearning / activation steering / contrastive weight steering interventions behind one API.
Author: Hem Gosalia, Aditya Kasliwal, Vinay Kumar Sankarapu
Author-email: Pratinav Seth <pratinav.seth@lexsi.ai>
Maintainer-email: Pratinav Seth <pratinav.seth@lexsi.ai>
License: LSAL-1.2
Project-URL: Homepage, https://github.com/Lexsi-Labs/circuitkit
Project-URL: Documentation, https://lexsi-labs.github.io/circuitkit/
Project-URL: Repository, https://github.com/Lexsi-Labs/circuitkit
Project-URL: Bug Tracker, https://github.com/Lexsi-Labs/circuitkit/issues
Project-URL: Changelog, https://github.com/Lexsi-Labs/circuitkit/blob/main/CHANGELOG.md
Project-URL: Contributing, https://github.com/Lexsi-Labs/circuitkit/blob/main/CONTRIBUTING.md
Keywords: mechanistic-interpretability,circuit-discovery,transformers,neural-networks,attention-analysis,model-pruning,faithfulness-evaluation,auto-schema,corruption-robustness,knowledge-editing,model-visualization
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: torch
Requires-Dist: einops
Requires-Dist: plotly
Requires-Dist: tqdm
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: huggingface-hub<1.0,>=0.34
Requires-Dist: transformers<5,>=4.57
Requires-Dist: safetensors
Requires-Dist: ordered-set
Requires-Dist: pyyaml
Requires-Dist: networkx
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: ipywidgets
Requires-Dist: scikit-learn
Requires-Dist: evaluate
Requires-Dist: sacrebleu
Requires-Dist: rouge_score
Requires-Dist: bert-score
Requires-Dist: accelerate
Requires-Dist: sentence-transformers
Requires-Dist: click
Requires-Dist: rich
Requires-Dist: spacy>=3.8
Requires-Dist: psutil
Requires-Dist: transformer-lens<3,>=2.18
Requires-Dist: torch-pruning>=1.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Requires-Dist: mkdocs-jupyter>=0.24; extra == "docs"
Requires-Dist: pygments>=2.15; extra == "docs"
Provides-Extra: benchmarks
Requires-Dist: lm-eval; extra == "benchmarks"
Requires-Dist: datasets>=2.20.0; extra == "benchmarks"
Provides-Extra: quantization
Requires-Dist: optimum-quanto>=0.2; extra == "quantization"
Provides-Extra: cdt
Requires-Dist: captum>=0.6; extra == "cdt"
Requires-Dist: lime>=0.2; extra == "cdt"
Requires-Dist: shap>=0.42; extra == "cdt"
Provides-Extra: pruning
Provides-Extra: gpu-cu126
Requires-Dist: torch==2.6.0+cu126; extra == "gpu-cu126"
Requires-Dist: torchvision==0.21.0+cu126; extra == "gpu-cu126"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/circuitkit-logo-white.png">
    <img src="docs/assets/circuitkit-logo-black.png" width="360" alt="CircuitKit">
  </picture>
</p>

<h1 align="center">CircuitKit</h1>

<p align="center">
  <b>Discover, evaluate, and intervene on circuits in transformer models.</b><br>
  One call takes a model + task to a discovered circuit, a 6-pillar faithfulness score, and a intervened HuggingFace checkpoint.
</p>

<p align="center">
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg" alt="Python 3.10+"></a>
  <a href="https://pytorch.org/"><img src="https://img.shields.io/badge/PyTorch-2.0%2B-ee4c2c.svg" alt="PyTorch 2.0+"></a>
  <a href="LICENSE.md"><img src="https://img.shields.io/badge/license-LSAL%20v1.2-blue.svg" alt="License: LSAL v1.2 (source-available)"></a>
  <a href="https://lexsi-labs.github.io/CircuitKIT/"><img src="https://img.shields.io/badge/docs-mkdocs%20material-EC5A2C.svg" alt="Docs"></a>
</p>

---

CircuitKit is a framework for mechanistic interpretability. Given a model and a task, it discovers the circuit driving that behaviour, evaluates how faithful it is, and lets you act on it (prune, quantize, edit, steer, or fine-tune), then export a reloadable HuggingFace checkpoint.

**No GPU required for the quickstart** — GPT-2 runs on CPU in a few minutes.

## Quick start

```bash
# CPU-only, no GPU needed:
pip install -e .

# For benchmarking, add: pip install -e ".[benchmarks]"
```

```python
from circuitkit import Pipeline

pipe = Pipeline("gpt2", task="ioi")
pipe.discover(algorithm="eap-ig", sparsity=0.3)
pipe.evaluate()
pipe.prune()
pipe.export("./checkpoint")
```

Also works as a [CLI](https://lexsi-labs.github.io/circuitkit/cli/overview/) and [YAML config](https://lexsi-labs.github.io/CircuitKIT/cli/yaml-config/).

## What is a circuit?

A **circuit** is the minimal set of attention heads and MLP layers in a transformer that drives a specific behaviour. Most interp tooling stops at "here is a subgraph with attribution scores." CircuitKit goes further: it prunes (or quantizes) the model down to that subgraph, exports a reloadable HuggingFace checkpoint, and measures how faithful the pruned model stays. Because the circuit is task-specific, this produces a task-specialized checkpoint — not a general-purpose compressed model.

## What you can do

| Capability | What it means |
|---|---|
| **Discover** | 13 algorithms across maturity tiers — 2 stable (EAP, EAP-IG), 2 experimental (ACDC, IBCircuit), 9 research |
| **Evaluate** | 6-pillar faithfulness: causal patching, ablation, stability, robustness, baselines, generalization |
| **Prune** | Structural weight pruning down to the circuit |
| **Quantize** | Circuit-aware mixed-precision quantization (3/4-bit + protect tiers) |
| **Edit** | ROME / MEMIT knowledge editing at circuit-identified components |
| **Steer** | Activation steering at inference (no retraining) |
| **Fine-tune** | Circuit-restricted LoRA — only circuit components update |
| **Benchmark** | lm-evaluation-harness integration for compressed checkpoints |

## Why CircuitKit?

| Instead of stitching together… | …CircuitKit gives you |
|---|---|
| A separate repo per discovery algorithm, plus a pruning script and lm-eval-harness — wired together by hand | One `Pipeline`: discover → evaluate → prune → export → benchmark |
| One-off data formats per tool | Standard circuit artifact + HuggingFace checkpoint |
| GPT-2-only tooling | Llama-3, Gemma, Qwen — with GQA, RoPE, chat templates |
| One faithfulness score | 6-pillar evaluation suite |

## Next steps

| | |
|---|---|
| **[Getting Started](https://lexsi-labs.github.io/CircuitKIT/getting-started/)** | Install, quickstart, core concepts |
| **[User Guide](https://lexsi-labs.github.io/CircuitKIT/guides/)** | Pipeline, custom data, evaluation, selectors, tasks |
| **[Algorithms](https://lexsi-labs.github.io/CircuitKIT/algorithms/overview/)** | EAP, ACDC, IBCircuit, CD-T — with stability tiers |
| **[Applications](https://lexsi-labs.github.io/CircuitKIT/applications/)** | Pruning, quantization, editing, steering, fine-tuning |
| **[Examples](https://lexsi-labs.github.io/CircuitKIT/examples/overview/)** | Runnable scripts and notebooks (all CPU-friendly) |
| **[API Reference](https://lexsi-labs.github.io/CircuitKIT/api-reference/overview/)** | Full API and CLI reference |

## Tests

```bash
pip install -e ".[dev]"
pytest tests/ -q
```

## Citation

```bibtex
@software{circuitkit2026,
  title  = {CircuitKit: Circuit Discovery, Evaluation, and Application Toolkit
            for Mechanistic Interpretability},
  author = {Seth, Pratinav and Gosalia, Hem and Kasliwal, Aditya
            and Sankarapu, Vinay Kumar},
  year   = {2026},
  version = {1.0.0},
  url    = {https://github.com/Lexsi-Labs/CircuitKIT}
}
```

## License

Lexsi Labs Source Available License (LSAL) v1.2: free for academic research and teaching on MIT-like terms; use by any organization requires written acknowledgement or permission (Section 1A); commercial use requires a separate license; responsible-use conditions apply. See [LICENSE.md](LICENSE.md).

