circuit-tracer 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. circuit_tracer-0.5.0/.gitignore +177 -0
  2. circuit_tracer-0.5.0/CHANGELOG.md +63 -0
  3. circuit_tracer-0.5.0/LICENSE +19 -0
  4. circuit_tracer-0.5.0/PKG-INFO +331 -0
  5. circuit_tracer-0.5.0/README.md +278 -0
  6. circuit_tracer-0.5.0/circuit_tracer/__init__.py +35 -0
  7. circuit_tracer-0.5.0/circuit_tracer/__main__.py +296 -0
  8. circuit_tracer-0.5.0/circuit_tracer/_version.py +3 -0
  9. circuit_tracer-0.5.0/circuit_tracer/attribution/__init__.py +34 -0
  10. circuit_tracer-0.5.0/circuit_tracer/attribution/attribute.py +287 -0
  11. circuit_tracer-0.5.0/circuit_tracer/attribution/context_nnsight.py +213 -0
  12. circuit_tracer-0.5.0/circuit_tracer/attribution/context_transformerlens.py +233 -0
  13. circuit_tracer-0.5.0/circuit_tracer/attribution/targets.py +440 -0
  14. circuit_tracer-0.5.0/circuit_tracer/frontend/__init__.py +6 -0
  15. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/LICENSE +21 -0
  16. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/README.md +11 -0
  17. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/addition/index.html +38 -0
  18. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/addition/init-add-big-feature.js +36 -0
  19. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/addition/init-add-connections.js +76 -0
  20. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/addition/init.js +26 -0
  21. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/addition/style.css +124 -0
  22. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/addition/util-add.js +189 -0
  23. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/cg.css +860 -0
  24. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/gridsnap/gridsnap.css +80 -0
  25. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/gridsnap/init-gridsnap.js +190 -0
  26. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-button-container.js +68 -0
  27. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-clerp-list.js +95 -0
  28. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-feature-detail.js +182 -0
  29. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-feature-scatter.js +85 -0
  30. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-link-graph.js +309 -0
  31. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-node-connections.js +130 -0
  32. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-subgraph.js +621 -0
  33. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg.js +233 -0
  34. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/render-act-histogram.js +187 -0
  35. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/util-cg.js +681 -0
  36. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/feature-view.html +187 -0
  37. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/feature_examples/feature-examples.css +129 -0
  38. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/feature_examples/init-feature-examples-list.js +166 -0
  39. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/feature_examples/init-feature-examples-logits.js +21 -0
  40. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/feature_examples/init-feature-examples.js +109 -0
  41. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/index.html +281 -0
  42. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/prettier.config.js +5 -0
  43. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/style.css +174 -0
  44. circuit_tracer-0.5.0/circuit_tracer/frontend/assets/util.js +350 -0
  45. circuit_tracer-0.5.0/circuit_tracer/frontend/feature_models.py +26 -0
  46. circuit_tracer-0.5.0/circuit_tracer/frontend/graph_models.py +124 -0
  47. circuit_tracer-0.5.0/circuit_tracer/frontend/local_server.py +226 -0
  48. circuit_tracer-0.5.0/circuit_tracer/frontend/utils.py +24 -0
  49. circuit_tracer-0.5.0/circuit_tracer/graph.py +409 -0
  50. circuit_tracer-0.5.0/circuit_tracer/py.typed +0 -0
  51. circuit_tracer-0.5.0/circuit_tracer/replacement_model/__init__.py +9 -0
  52. circuit_tracer-0.5.0/circuit_tracer/replacement_model/common.py +113 -0
  53. circuit_tracer-0.5.0/circuit_tracer/replacement_model/replacement_model.py +165 -0
  54. circuit_tracer-0.5.0/circuit_tracer/replacement_model/replacement_model_nnsight.py +1016 -0
  55. circuit_tracer-0.5.0/circuit_tracer/replacement_model/replacement_model_transformerlens.py +884 -0
  56. circuit_tracer-0.5.0/circuit_tracer/transcoder/__init__.py +7 -0
  57. circuit_tracer-0.5.0/circuit_tracer/transcoder/activation_functions.py +62 -0
  58. circuit_tracer-0.5.0/circuit_tracer/transcoder/cross_layer_transcoder.py +603 -0
  59. circuit_tracer-0.5.0/circuit_tracer/transcoder/single_layer_transcoder.py +616 -0
  60. circuit_tracer-0.5.0/circuit_tracer/utils/MAPPING_INFO.md +24 -0
  61. circuit_tracer-0.5.0/circuit_tracer/utils/__init__.py +11 -0
  62. circuit_tracer-0.5.0/circuit_tracer/utils/caching.py +443 -0
  63. circuit_tracer-0.5.0/circuit_tracer/utils/create_graph_files.py +210 -0
  64. circuit_tracer-0.5.0/circuit_tracer/utils/decode_url_features.py +70 -0
  65. circuit_tracer-0.5.0/circuit_tracer/utils/demo_utils.py +761 -0
  66. circuit_tracer-0.5.0/circuit_tracer/utils/disk_offload.py +80 -0
  67. circuit_tracer-0.5.0/circuit_tracer/utils/hf_utils.py +354 -0
  68. circuit_tracer-0.5.0/circuit_tracer/utils/tl_nnsight_mapping.py +292 -0
  69. circuit_tracer-0.5.0/pyproject.toml +147 -0
@@ -0,0 +1,177 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py,cover
50
+ .hypothesis/
51
+ .pytest_cache/
52
+ cover/
53
+
54
+ # Translations
55
+ *.mo
56
+ *.pot
57
+
58
+ # Django stuff:
59
+ *.log
60
+ local_settings.py
61
+ db.sqlite3
62
+ db.sqlite3-journal
63
+
64
+ # Flask stuff:
65
+ instance/
66
+ .webassets-cache
67
+
68
+ # Scrapy stuff:
69
+ .scrapy
70
+
71
+ # Sphinx documentation
72
+ docs/_build/
73
+
74
+ # PyBuilder
75
+ .pybuilder/
76
+ target/
77
+
78
+ # Jupyter Notebook
79
+ .ipynb_checkpoints
80
+ demos/**/graphs
81
+ demos/**/graph_files
82
+
83
+ # IPython
84
+ profile_default/
85
+ ipython_config.py
86
+
87
+ # pyenv
88
+ # For a library or package, you might want to ignore these files since the code is
89
+ # intended to run in multiple environments; otherwise, check them in:
90
+ # .python-version
91
+
92
+ # pipenv
93
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
94
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
95
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
96
+ # install all needed dependencies.
97
+ #Pipfile.lock
98
+
99
+ # UV
100
+ # We commit uv.lock for reproducible CI builds.
101
+ # uv.lock
102
+
103
+ # poetry
104
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
106
+ # commonly ignored for libraries.
107
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108
+ #poetry.lock
109
+
110
+ # pdm
111
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
112
+ #pdm.lock
113
+ # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
114
+ # in version control.
115
+ # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
116
+ .pdm.toml
117
+ .pdm-python
118
+ .pdm-build/
119
+
120
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
121
+ __pypackages__/
122
+
123
+ # Celery stuff
124
+ celerybeat-schedule
125
+ celerybeat.pid
126
+
127
+ # SageMath parsed files
128
+ *.sage.py
129
+
130
+ # Environments
131
+ .env
132
+ .venv
133
+ env/
134
+ venv/
135
+ ENV/
136
+ env.bak/
137
+ venv.bak/
138
+
139
+ # Spyder project settings
140
+ .spyderproject
141
+ .spyproject
142
+
143
+ # Rope project settings
144
+ .ropeproject
145
+
146
+ # mkdocs documentation
147
+ /site
148
+
149
+ # mypy
150
+ .mypy_cache/
151
+ .dmypy.json
152
+ dmypy.json
153
+
154
+ # Pyre type checker
155
+ .pyre/
156
+
157
+ # pytype static type analyzer
158
+ .pytype/
159
+
160
+ # Cython debug symbols
161
+ cython_debug/
162
+
163
+ # PyCharm
164
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
165
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
166
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
167
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
168
+ #.idea/
169
+
170
+ # Ruff stuff:
171
+ .ruff_cache/
172
+
173
+ # PyPI configuration file
174
+ .pypirc
175
+
176
+ *.parquet
177
+ .vscode/
@@ -0,0 +1,63 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.5.0] — 2026-03-28
9
+
10
+ ### Added
11
+
12
+ - **PyPI packaging**: hatchling build system, Trusted Publisher workflow, `MANIFEST.in`, `py.typed` PEP 561 marker.
13
+ - **Single-source versioning** via `circuit_tracer/_version.py`, read by both hatchling and `__init__.py`.
14
+ - **Registry pattern** for model architecture mappings (`ModelMapping` frozen dataclass, `get_mapping()`, `get_supported_architectures()`).
15
+ - **Unified attribution interface**: both NNSight and TransformerLens backends now expose `unembed_proj`, `model_config`, `run_forward_pass()`, and `get_offload_targets_phase{0,1,2}()`, allowing a single `_run_attribution()` implementation.
16
+ - **Shared utilities** in `replacement_model/common.py`: `ensure_tokenized()` and `convert_open_ended_interventions()` extracted from duplicated code.
17
+ - **Lazy imports** in `__init__.py` and `attribution/__init__.py` to prevent circular import issues.
18
+ - **CI modernisation**: uv-based workflows, Python 3.10/3.11/3.12 matrix, `requires_gpu` pytest marker.
19
+ - **CHANGELOG.md** (this file).
20
+ - `circuit-tracer` CLI entry point via `project.scripts`.
21
+
22
+ ### Changed
23
+
24
+ - **Attribution deduplication**: merged `attribute_nnsight.py` and `attribute_transformerlens.py` (~560 lines combined) into a single `attribute.py` (~170 lines) using the unified model interface.
25
+ - **`CONTRIBUTING.md`** rewritten with uv-based developer workflow.
26
+ - **`__main__.py`**: fixed `if`/`elif` dispatch bug, extracted magic numbers into named constants.
27
+ - **`frontend/local_server.py`**: extracted constants, renamed `format` → `fmt` to avoid shadowing builtin.
28
+ - **`frontend/graph_models.py`**: lifted `cantor_pairing` to module-level `_cantor_pairing()`.
29
+ - **`utils/demo_utils.py`**: removed duplicate `decode_url_features()` (~65 lines), imports from canonical location.
30
+ - **`graph.py`**: `print()` → `logging.warning()`, added type hints to `Graph.__init__` and `.to()`.
31
+ - Loosened `nnsight` dependency from `==0.6.1` to `>=0.6.0`.
32
+ - Moved `ipykernel`, `ipywidgets`, `seaborn` from core deps to `[viz]` optional extra.
33
+ - Ruff config expanded: `I` (isort), `UP` (pyupgrade), `TID` rules; banned `typing.Union`/`Optional`/`Dict`/`Tuple`/`List`.
34
+
35
+ ### Removed
36
+
37
+ - `attribute_nnsight.py` — merged into unified `attribute.py`.
38
+ - `attribute_transformerlens.py` — merged into unified `attribute.py`.
39
+ - `utils/salient_logits.py` — exact duplicate of logic in `targets.py`.
40
+ - Duplicate `decode_url_features()` and `extract_supernode_features()` from `demo_utils.py`.
41
+
42
+ ### Fixed
43
+
44
+ - Circular import between `attribution/__init__.py` and `graph.py` via lazy `__getattr__` pattern.
45
+ - `__main__.py` second command check was `if` instead of `elif`, causing potential `AttributeError`.
46
+ - pyright: resolved all 11 type errors (device nullability, `CrossLayerTranscoder` iterability, overload mismatches).
47
+
48
+ ## [0.4.1] — 2026-03-13
49
+
50
+ ### Added
51
+
52
+ - Attribution targets encapsulation (`LogitTarget`, `CustomTarget`, `AttributionTargets`).
53
+ - Active maintainer section in README.
54
+
55
+ ## [0.4.0] — 2026-02-28
56
+
57
+ ### Changed
58
+
59
+ - Version bump from 0.1.0 to 0.4.0.
60
+
61
+ ## [0.1.0] — 2026-01-14
62
+
63
+ - Initial release.
@@ -0,0 +1,19 @@
1
+ Copyright (c) 2024 Michael Hanna and Mateusz Piotrowski
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a copy
4
+ of this software and associated documentation files (the "Software"), to deal
5
+ in the Software without restriction, including without limitation the rights
6
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7
+ copies of the Software, and to permit persons to whom the Software is
8
+ furnished to do so, subject to the following conditions:
9
+
10
+ The above copyright notice and this permission notice shall be included in all
11
+ copies or substantial portions of the Software.
12
+
13
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
14
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
15
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
16
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
17
+ DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
18
+ OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
19
+ OR OTHER DEALINGS IN THE SOFTWARE.
@@ -0,0 +1,331 @@
1
+ Metadata-Version: 2.4
2
+ Name: circuit-tracer
3
+ Version: 0.5.0
4
+ Summary: Attribution graphs and circuit tracing for language model interpretability
5
+ Project-URL: Homepage, https://github.com/Caerii/circuit-tracer
6
+ Project-URL: Documentation, https://github.com/Caerii/circuit-tracer#readme
7
+ Project-URL: Repository, https://github.com/Caerii/circuit-tracer
8
+ Project-URL: Changelog, https://github.com/Caerii/circuit-tracer/blob/main/CHANGELOG.md
9
+ Project-URL: Original Repository, https://github.com/decoderesearch/circuit-tracer
10
+ Author: Michael Hanna, Mateusz Piotrowski, Decode Research
11
+ Maintainer-email: Alif Jakir <alif@superintelligent.group>
12
+ License: MIT
13
+ License-File: LICENSE
14
+ Keywords: attribution-graphs,circuit-tracing,mechanistic-interpretability,sparse-autoencoders,transcoders,transformer-lens
15
+ Classifier: Development Status :: 4 - Beta
16
+ Classifier: Intended Audience :: Science/Research
17
+ Classifier: License :: OSI Approved :: MIT License
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
23
+ Requires-Python: >=3.10
24
+ Requires-Dist: einops>=0.8.0
25
+ Requires-Dist: huggingface-hub<1.0.0
26
+ Requires-Dist: nnsight>=0.6.0
27
+ Requires-Dist: numpy>=1.24.0
28
+ Requires-Dist: pydantic>=2.0.0
29
+ Requires-Dist: safetensors>=0.5.0
30
+ Requires-Dist: tokenizers>=0.21.0
31
+ Requires-Dist: torch>=2.0.0
32
+ Requires-Dist: tqdm>=4.60.0
33
+ Requires-Dist: transformer-lens>=2.16.0
34
+ Requires-Dist: transformers<=4.57.3,>=4.56.0
35
+ Provides-Extra: all
36
+ Requires-Dist: ipykernel<7.0.0,>=6.29.5; extra == 'all'
37
+ Requires-Dist: ipython>=8.37.0; extra == 'all'
38
+ Requires-Dist: ipywidgets>=8.1.7; extra == 'all'
39
+ Requires-Dist: pyright>=1.1.403; extra == 'all'
40
+ Requires-Dist: pytest>=8.0.0; extra == 'all'
41
+ Requires-Dist: ruff>=0.12.7; extra == 'all'
42
+ Requires-Dist: seaborn>=0.13.2; extra == 'all'
43
+ Provides-Extra: dev
44
+ Requires-Dist: ipython>=8.37.0; extra == 'dev'
45
+ Requires-Dist: pyright>=1.1.403; extra == 'dev'
46
+ Requires-Dist: pytest>=8.0.0; extra == 'dev'
47
+ Requires-Dist: ruff>=0.12.7; extra == 'dev'
48
+ Provides-Extra: viz
49
+ Requires-Dist: ipykernel<7.0.0,>=6.29.5; extra == 'viz'
50
+ Requires-Dist: ipywidgets>=8.1.7; extra == 'viz'
51
+ Requires-Dist: seaborn>=0.13.2; extra == 'viz'
52
+ Description-Content-Type: text/markdown
53
+
54
+ # circuit-tracer
55
+
56
+ [![PyPI version](https://img.shields.io/pypi/v/circuit-tracer.svg)](https://pypi.org/project/circuit-tracer/)
57
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
58
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
59
+ [![CI](https://github.com/Caerii/circuit-tracer/actions/workflows/ci.yaml/badge.svg)](https://github.com/Caerii/circuit-tracer/actions/workflows/ci.yaml)
60
+
61
+ Find, visualize, and intervene on circuits inside language models using features from (cross-layer) MLP transcoders, as introduced by [Ameisen et al. (2025)](https://transformer-circuits.pub/2025/attribution-graphs/methods.html) and [Lindsey et al. (2025)](https://transformer-circuits.pub/2025/attribution-graphs/biology.html).
62
+
63
+ ## What does it do?
64
+
65
+ 1. **Attribution**: Given a model with pre-trained transcoders, compute the direct effect that each non-zero transcoder feature, error node, and input token has on each other feature and output logit — producing a full circuit / attribution graph.
66
+ 2. **Visualization**: View and annotate the resulting graph in an interactive browser UI (the same frontend used in [the original papers](https://transformer-circuits.pub/2025/attribution-graphs/methods.html)).
67
+ 3. **Intervention**: Set transcoder features to arbitrary values and observe how model output changes, validating the circuits you discover.
68
+
69
+ ---
70
+
71
+ ## Installation
72
+
73
+ ### From PyPI (recommended)
74
+
75
+ ```bash
76
+ pip install circuit-tracer
77
+ ```
78
+
79
+ Or with [uv](https://docs.astral.sh/uv/):
80
+
81
+ ```bash
82
+ uv add circuit-tracer
83
+ ```
84
+
85
+ ### Optional extras
86
+
87
+ ```bash
88
+ # Visualization dependencies (seaborn, ipykernel, ipywidgets)
89
+ pip install circuit-tracer[viz]
90
+
91
+ # Everything (viz + dev tools)
92
+ pip install circuit-tracer[all]
93
+ ```
94
+
95
+ ### From source
96
+
97
+ ```bash
98
+ git clone https://github.com/Caerii/circuit-tracer.git
99
+ cd circuit-tracer
100
+ uv sync --group dev
101
+ ```
102
+
103
+ ---
104
+
105
+ ## Quick Start
106
+
107
+ ```python
108
+ from circuit_tracer import ReplacementModel, Graph, attribute
109
+
110
+ # Load a model with transcoders
111
+ model = ReplacementModel.from_pretrained("google/gemma-2-2b", "gemma")
112
+
113
+ # Find the circuit for a prompt
114
+ graph = attribute(model, "The capital of France is")
115
+
116
+ # Save for later analysis
117
+ graph.to_pt("france_capital.pt")
118
+
119
+ # Or load an existing graph
120
+ graph = Graph.from_pt("france_capital.pt")
121
+ ```
122
+
123
+ For a complete walkthrough, try the [tutorial notebook](https://github.com/Caerii/circuit-tracer/blob/main/demos/circuit_tracing_tutorial.ipynb)!
124
+
125
+ ---
126
+
127
+ ## Getting Started
128
+
129
+ There are three ways to use circuit-tracer:
130
+
131
+ 1. **On Neuronpedia** (no install needed): Use `circuit-tracer` directly on [Neuronpedia](https://www.neuronpedia.org/gemma-2-2b/graph?slug=gemma-fact-dallas-austin&pinnedIds=27_22605_10%2C20_15589_10%2CE_26865_9%2C21_5943_10%2C23_12237_10%2C20_15589_9%2C16_25_9%2C14_2268_9%2C18_8959_10%2C4_13154_9%2C7_6861_9%2C19_1445_10%2CE_2329_7%2CE_6037_4%2C0_13727_7%2C6_4012_7%2C17_7178_10%2C15_4494_4%2C6_4662_4%2C4_7671_4%2C3_13984_4%2C1_1000_4%2C19_7477_9%2C18_6101_10%2C16_4298_10%2C7_691_10&supernodes=%5B%5B%22state%22%2C%226_4012_7%22%2C%220_13727_7%22%5D%2C%5B%22preposition+followed+by+place+name%22%2C%2219_1445_10%22%2C%2218_6101_10%22%5D%2C%5B%22Texas%22%2C%2220_15589_10%22%2C%2220_15589_9%22%2C%2219_7477_9%22%2C%2216_25_9%22%2C%224_13154_9%22%2C%2214_2268_9%22%2C%227_6861_9%22%5D%2C%5B%22capital+%2F+capital+cities%22%2C%2215_4494_4%22%2C%226_4662_4%22%2C%224_7671_4%22%2C%223_13984_4%22%2C%221_1000_4%22%2C%2221_5943_10%22%2C%2217_7178_10%22%2C%227_691_10%22%2C%2216_4298_10%22%5D%5D&pruningThreshold=0.6&clickedId=21_5943_10&densityThreshold=0.99). Click `+ New Graph` to create your own, or browse existing graphs from the drop-down.
132
+
133
+ 2. **Python script / Jupyter notebook**: Start with the [tutorial notebook](https://github.com/Caerii/circuit-tracer/blob/main/demos/circuit_tracing_tutorial.ipynb) (runs on free Colab GPUs). See the **Demos** section below.
134
+
135
+ 3. **Command-line interface**: Run the full attribution-to-visualization pipeline from your terminal. See **CLI Usage** below.
136
+
137
+ Working with Gemma-2 (2B) is possible with relatively limited GPU resources; Colab GPUs have 15GB of RAM. More GPU RAM allows less offloading and larger batch sizes.
138
+
139
+ ---
140
+
141
+ ## Supported Models & Transcoders
142
+
143
+ The following transcoders are available. Use the HuggingFace repo name as the `transcoders` argument of `ReplacementModel.from_pretrained`, or as `--transcoder_set` in the CLI.
144
+
145
+ | Model | Transcoder Type | HuggingFace Repo | Notes |
146
+ |-------|----------------|-------------------|-------|
147
+ | **Gemma-2 (2B)** | PLT | [`mntss/gemma-scope-transcoders`](https://huggingface.co/mntss/gemma-scope-transcoders) | Originally from GemmaScope |
148
+ | **Gemma-2 (2B)** | CLT (426K) | [`mntss/clt-gemma-2-2b-426k`](https://huggingface.co/mntss/clt-gemma-2-2b-426k) | |
149
+ | **Gemma-2 (2B)** | CLT (2.5M) | [`mntss/clt-gemma-2-2b-2.5M`](https://huggingface.co/mntss/clt-gemma-2-2b-2.5M) | |
150
+ | **Llama-3.2 (1B)** | PLT | [`mntss/transcoder-Llama-3.2-1B`](https://huggingface.co/mntss/transcoder-Llama-3.2-1B) | |
151
+ | **Llama-3.2 (1B)** | CLT | [`mntss/clt-llama-3.2-1b-524k`](https://huggingface.co/mntss/clt-llama-3.2-1b-524k) | |
152
+ | **Qwen-3** | PLT | [0.6B](https://huggingface.co/mwhanna/qwen3-0.6b-transcoders-lowl0), [1.7B](https://huggingface.co/mwhanna/qwen3-1.7b-transcoders-lowl0), [4B](https://huggingface.co/mwhanna/qwen3-4b-transcoders), [8B](https://huggingface.co/mwhanna/qwen3-8b-transcoders), [14B](https://huggingface.co/mwhanna/qwen3-14b-transcoders-lowl0) | |
153
+ | **GPT-OSS (20B)** | CLT | [`mntss/clt-131k`](https://huggingface.co/mntss/clt-131k) | |
154
+ | **Gemma-3** | PLT | [Collection](https://huggingface.co/collections/mwhanna/gemma-scope-2-transcoders-circuit-tracer) | 270M to 27B, PT & IT. Requires `nnsight` backend. |
155
+
156
+ ### Choosing a Backend
157
+
158
+ By default, `circuit-tracer` uses the **TransformerLens** backend (inherits from `HookedTransformer`). For models not supported by TransformerLens, use the **NNSight** backend:
159
+
160
+ ```python
161
+ # TransformerLens (default) — fast, memory-efficient
162
+ model = ReplacementModel.from_pretrained("google/gemma-2-2b", "gemma")
163
+
164
+ # NNSight — supports most HuggingFace models
165
+ model = ReplacementModel.from_pretrained("google/gemma-3-4b-pt", "gemma-3", backend="nnsight")
166
+ ```
167
+
168
+ > **Note**: The NNSight backend is still experimental: it is slower and less memory-efficient, and may not provide all of the functionality of the TransformerLens version.
169
+
170
+ ---
171
+
172
+ ## Demos
173
+
174
+ All demos live in the [`demos/`](https://github.com/Caerii/circuit-tracer/tree/main/demos) folder. The main tutorial can run on free Colab GPUs.
175
+
176
+ | Notebook | Description |
177
+ |----------|-------------|
178
+ | [**circuit_tracing_tutorial.ipynb**](https://github.com/Caerii/circuit-tracer/blob/main/demos/circuit_tracing_tutorial.ipynb) | End-to-end tutorial replicating findings from [Lindsey et al.](https://transformer-circuits.pub/2025/attribution-graphs/biology.html) |
179
+ | [attribute_demo.ipynb](https://github.com/Caerii/circuit-tracer/blob/main/demos/attribute_demo.ipynb) | How to find circuits and visualize them |
180
+ | [attribution_targets_demo.ipynb](https://github.com/Caerii/circuit-tracer/blob/main/demos/attribution_targets_demo.ipynb) | Specifying custom attribution targets (specific logits or directions) |
181
+ | [intervention_demo.ipynb](https://github.com/Caerii/circuit-tracer/blob/main/demos/intervention_demo.ipynb) | Performing feature interventions on models |
182
+ | [gemma_demo.ipynb](https://github.com/Caerii/circuit-tracer/blob/main/demos/gemma_demo.ipynb) | Pre-annotated Gemma-2 (2B) graphs with interventions |
183
+ | [gemma_it_demo.ipynb](https://github.com/Caerii/circuit-tracer/blob/main/demos/gemma_it_demo.ipynb) | Instruction-tuned Gemma-2 (2B) with base-model transcoders |
184
+ | [llama_demo.ipynb](https://github.com/Caerii/circuit-tracer/blob/main/demos/llama_demo.ipynb) | Llama 3.2 (1B) graphs (requires local GPU, not Colab) |
185
+
186
+ ---
187
+
188
+ ## Caching
189
+
190
+ To use `lazy_decoder` and `lazy_encoder` options on transcoders, they must be in `circuit-tracer`-compatible format. Rather than downloading pre-converted weights, you can build a local cache:
191
+
192
+ ```python
193
+ from circuit_tracer.utils.caching import save_transcoders_to_cache
194
+
195
+ save_transcoders_to_cache(
196
+ "mwhanna/gemma-scope-2-27b-pt/transcoder_all/width_262k_l0_small",
197
+ cache_dir="~/.cache/",
198
+ )
199
+ ```
200
+
201
+ Clear the cache with `circuit_tracer.utils.caching.empty_cache`.
202
+
203
+ ---
204
+
205
+ ## CLI Usage
206
+
207
+ The CLI runs the complete 3-step pipeline: **attribution** -> **graph file creation** -> **visualization server**.
208
+
209
+ ### Basic Usage
210
+
211
+ ```bash
212
+ circuit-tracer attribute \
213
+ --prompt "The International Advanced Security Group (IAS" \
214
+ --transcoder_set gemma \
215
+ --slug gemma-demo \
216
+ --graph_file_dir ./graph_files \
217
+ --server
218
+ ```
219
+
220
+ The server URL (e.g. `localhost:8041`) will be printed. If running on a remote machine, enable port forwarding to view the graphs locally.
221
+
222
+ ### Attribution only (save raw graph)
223
+
224
+ ```bash
225
+ circuit-tracer attribute \
226
+ --prompt "The capital of France is" \
227
+ --transcoder_set llama \
228
+ --graph_output_path france_capital.pt
229
+ ```
230
+
231
+ ### CLI Arguments
232
+
233
+ #### Required
234
+
235
+ | Argument | Description |
236
+ |----------|-------------|
237
+ | `--prompt` (`-p`) | Input prompt to analyze |
238
+ | `--transcoder_set` (`-t`) | Transcoders to use (HuggingFace repo ID, or shortcut: `gemma`, `llama`) |
239
+
240
+ Plus at least one output destination:
241
+ - `--slug` + `--graph_file_dir` (for visualization), and/or
242
+ - `--graph_output_path` (`-o`) (for raw `.pt` graph)
243
+
244
+ #### Optional
245
+
246
+ | Argument | Default | Description |
247
+ |----------|---------|-------------|
248
+ | `--model` (`-m`) | auto | Model name (auto-inferred for `gemma`/`llama` presets) |
249
+ | `--max_n_logits` | 10 | Maximum logit nodes to attribute from |
250
+ | `--desired_logit_prob` | 0.95 | Cumulative probability threshold for top logits |
251
+ | `--batch_size` | 256 | Batch size for backward passes |
252
+ | `--max_feature_nodes` | 7500 | Maximum feature nodes |
253
+ | `--dtype` | model default | Load dtype (`float32`/`fp32`, `float16`/`fp16`, `bfloat16`/`bf16`) |
254
+ | `--offload` | None | Memory optimization (`cpu`, `disk`, or `None`) |
255
+ | `--node_threshold` | 0.8 | Node pruning: keep nodes with cumulative influence >= threshold |
256
+ | `--edge_threshold` | 0.98 | Edge pruning: keep edges with cumulative influence >= threshold |
257
+ | `--port` | 8041 | Local server port |
258
+ | `--server` | false | Start visualization server after attribution |
259
+ | `--verbose` | false | Show detailed progress |
260
+
261
+ ### Graph Annotation
262
+
263
+ When using `--server`, the browser opens an interactive visualization:
264
+
265
+ - **Select a node**: Click on it
266
+ - **Pin/unpin to subgraph pane**: Ctrl+click (or Cmd+click)
267
+ - **Annotate a node**: Click "Edit" on the right side while a node is selected
268
+ - **Group nodes into a supernode**: Hold G and click on nodes
269
+ - **Ungroup a supernode**: Hold G and click the x next to it
270
+ - **Annotate a supernode**: Click on the label below it
271
+
272
+ Interventions are also available on Neuronpedia for Gemma-2 (2B): pin at least one node, then click "Steer" in the subgraph.
273
+
274
+ ---
275
+
276
+ ## Project Structure
277
+
278
+ ```
279
+ circuit_tracer/
280
+ ├── __init__.py # Public API: attribute, Graph, ReplacementModel
281
+ ├── _version.py # Single source of truth for version
282
+ ├── graph.py # Graph data structures, pruning, influence computation
283
+ ├── attribution/
284
+ │ ├── attribute.py # Unified attribution engine (both backends)
285
+ │ └── targets.py # LogitTarget, CustomTarget, AttributionTargets
286
+ ├── replacement_model/
287
+ │ ├── common.py # Shared utilities (tokenization, interventions)
288
+ │ ├── replacement_model_nnsight.py
289
+ │ └── replacement_model_transformerlens.py
290
+ ├── transcoder/
291
+ │ ├── cross_layer_transcoder.py
292
+ │ └── single_layer_transcoder.py
293
+ ├── frontend/ # Visualization server and graph models
294
+ └── utils/ # Config mapping, caching, feature decoding, etc.
295
+ ```
296
+
297
+ ---
298
+
299
+ ## Contributing
300
+
301
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and development workflow. We use [uv](https://docs.astral.sh/uv/) for dependency management.
302
+
303
+ ```bash
304
+ # Quick dev setup
305
+ git clone https://github.com/Caerii/circuit-tracer.git
306
+ cd circuit-tracer
307
+ uv sync --group dev
308
+
309
+ # Quality checks
310
+ uv run ruff format && uv run ruff check && uv run pyright && uv run pytest tests -q
311
+ ```
312
+
313
+ ---
314
+
315
+ ## Active Maintainers
316
+
317
+ - [Alif Jakir](https://github.com/Caerii)
318
+
319
+ ## Cite
320
+
321
+ ```bibtex
322
+ @misc{circuit-tracer,
323
+ author = {Hanna, Michael and Piotrowski, Mateusz and Lindsey, Jack and Ameisen, Emmanuel},
324
+ title = {circuit-tracer},
325
+ howpublished = {\url{https://github.com/decoderesearch/circuit-tracer}},
326
+ note = {The first two authors contributed equally and are listed alphabetically.},
327
+ year = {2025}
328
+ }
329
+ ```
330
+
331
+ Or cite the paper [here](https://aclanthology.org/2025.blackboxnlp-1.14/).