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.
- circuit_tracer-0.5.0/.gitignore +177 -0
- circuit_tracer-0.5.0/CHANGELOG.md +63 -0
- circuit_tracer-0.5.0/LICENSE +19 -0
- circuit_tracer-0.5.0/PKG-INFO +331 -0
- circuit_tracer-0.5.0/README.md +278 -0
- circuit_tracer-0.5.0/circuit_tracer/__init__.py +35 -0
- circuit_tracer-0.5.0/circuit_tracer/__main__.py +296 -0
- circuit_tracer-0.5.0/circuit_tracer/_version.py +3 -0
- circuit_tracer-0.5.0/circuit_tracer/attribution/__init__.py +34 -0
- circuit_tracer-0.5.0/circuit_tracer/attribution/attribute.py +287 -0
- circuit_tracer-0.5.0/circuit_tracer/attribution/context_nnsight.py +213 -0
- circuit_tracer-0.5.0/circuit_tracer/attribution/context_transformerlens.py +233 -0
- circuit_tracer-0.5.0/circuit_tracer/attribution/targets.py +440 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/__init__.py +6 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/LICENSE +21 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/README.md +11 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/addition/index.html +38 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/addition/init-add-big-feature.js +36 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/addition/init-add-connections.js +76 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/addition/init.js +26 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/addition/style.css +124 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/addition/util-add.js +189 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/cg.css +860 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/gridsnap/gridsnap.css +80 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/gridsnap/init-gridsnap.js +190 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-button-container.js +68 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-clerp-list.js +95 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-feature-detail.js +182 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-feature-scatter.js +85 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-link-graph.js +309 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-node-connections.js +130 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg-subgraph.js +621 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/init-cg.js +233 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/render-act-histogram.js +187 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/attribution_graph/util-cg.js +681 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/feature-view.html +187 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/feature_examples/feature-examples.css +129 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/feature_examples/init-feature-examples-list.js +166 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/feature_examples/init-feature-examples-logits.js +21 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/feature_examples/init-feature-examples.js +109 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/index.html +281 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/prettier.config.js +5 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/style.css +174 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/assets/util.js +350 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/feature_models.py +26 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/graph_models.py +124 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/local_server.py +226 -0
- circuit_tracer-0.5.0/circuit_tracer/frontend/utils.py +24 -0
- circuit_tracer-0.5.0/circuit_tracer/graph.py +409 -0
- circuit_tracer-0.5.0/circuit_tracer/py.typed +0 -0
- circuit_tracer-0.5.0/circuit_tracer/replacement_model/__init__.py +9 -0
- circuit_tracer-0.5.0/circuit_tracer/replacement_model/common.py +113 -0
- circuit_tracer-0.5.0/circuit_tracer/replacement_model/replacement_model.py +165 -0
- circuit_tracer-0.5.0/circuit_tracer/replacement_model/replacement_model_nnsight.py +1016 -0
- circuit_tracer-0.5.0/circuit_tracer/replacement_model/replacement_model_transformerlens.py +884 -0
- circuit_tracer-0.5.0/circuit_tracer/transcoder/__init__.py +7 -0
- circuit_tracer-0.5.0/circuit_tracer/transcoder/activation_functions.py +62 -0
- circuit_tracer-0.5.0/circuit_tracer/transcoder/cross_layer_transcoder.py +603 -0
- circuit_tracer-0.5.0/circuit_tracer/transcoder/single_layer_transcoder.py +616 -0
- circuit_tracer-0.5.0/circuit_tracer/utils/MAPPING_INFO.md +24 -0
- circuit_tracer-0.5.0/circuit_tracer/utils/__init__.py +11 -0
- circuit_tracer-0.5.0/circuit_tracer/utils/caching.py +443 -0
- circuit_tracer-0.5.0/circuit_tracer/utils/create_graph_files.py +210 -0
- circuit_tracer-0.5.0/circuit_tracer/utils/decode_url_features.py +70 -0
- circuit_tracer-0.5.0/circuit_tracer/utils/demo_utils.py +761 -0
- circuit_tracer-0.5.0/circuit_tracer/utils/disk_offload.py +80 -0
- circuit_tracer-0.5.0/circuit_tracer/utils/hf_utils.py +354 -0
- circuit_tracer-0.5.0/circuit_tracer/utils/tl_nnsight_mapping.py +292 -0
- 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
|
+
[](https://pypi.org/project/circuit-tracer/)
|
|
57
|
+
[](https://python.org)
|
|
58
|
+
[](LICENSE)
|
|
59
|
+
[](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/).
|