transcoder-circuits

Train transcoders and analyze sparse feature circuits in transformer MLP sublayers.

75|7|Updated May 2, 2026
One-click install
npx skills add https://github.com/zjunlp/Mechanist --skill transcoder-circuits-zjunlp
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: transcoder-circuits
Source: https://github.com/zjunlp/Mechanist/tree/main/skills/mechanism-skills/feature-dictionary-learning/transcoder
Command: npx skills add https://github.com/zjunlp/Mechanist --skill transcoder-circuits-zjunlp

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires torch, transformer_lens, einops, datasets, huggingface_hub, wandb, and includes scripts (resource) and references (resource) components.

What problem does it solve? Reverse-engineering the internal computations of large language models requires decomposing dense MLP activations into interpretable components. This Skill trains transcoders to decompose MLP sublayers into sparse, interpretable features and provides tools for circuit analysis, activation patching, and feature visualization on models like GPT-2 and Pythia. ## Core Features & Use Cases - Transcoder Training: Train sparse transcoders on any MLP sublayer using configurable hyperparameters (L1 coefficient, expansion factor, learning rate) with optional Weights & Biases logging. - Circuit Analysis: Compute feature-level attribution scores to identify which transcoder features drive specific model outputs, using replacement contexts to patch MLP layers during inference. - Feature Dashboards: Generate dashboards showing max-activating examples, top promoted/suppressed tokens, and activation distributions for individual features. - Use Case: Load pretrained GPT-2 transcoder weights from HuggingFace, run inference with a TranscoderReplacementContext, then use get_circuit_scores to trace which features contribute most to a target logit difference. ## Quick Start Load GPT-2 via TransformerLens, load a pretrained transcoder from the pchlenski/gpt2-transcoders HuggingFace weights, and run inference inside a TranscoderReplacementContext to inspect feature activations.

Frequently Asked Questions about transcoder-circuits

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I train a transcoder on a language model MLP layer?

Build a LanguageModelSAERunnerConfig specifying the model name, hook point (e.g., blocks.0.hook_mlp_out), d_in, and expansion factor, then call language_model_sae_runner with that config. Training streams activations from a dataset like NeelNanda/pile-10k and returns a trained SparseAutoencoder.

How do I run circuit analysis with transcoders in TransformerLens?

Load your model with HookedTransformer, load per-layer transcoders, and call get_circuit_scores with a metric function such as a logit difference. The function returns per-layer feature attribution scores showing which features drive the target output.

What is the difference between a transcoder and a sparse autoencoder?

Both use the same SparseAutoencoder architecture with a ReLU sparsity bottleneck, but transcoders are trained to reconstruct MLP outputs from MLP inputs, enabling circuit decomposition across sublayers. The repository includes notebooks comparing SAE and transcoder feature interpretability on Pythia-410M.

Which models are supported for transcoder circuit analysis?

GPT-2 small is the primary model with pretrained transcoder weights available at pchlenski/gpt2-transcoders on HuggingFace. GPT-2 medium, GPT-2 large, and Pythia-410M are also supported through configurable d_in values and hook points.

Where do I get pretrained transcoder weights for GPT-2?

Run bash setup.sh, which installs dependencies and downloads weights from the pchlenski/gpt2-transcoders HuggingFace repository into ./transcoder_weights/. Each file corresponds to one layer, named gpt2-small_layer{N}_transcoder.pt.

Why does transcoder inference change model outputs?

Transcoder reconstructions are lossy, so replacing an MLP sublayer introduces reconstruction error. Set use_error_term=True in TranscoderReplacementContext to add the error back and preserve fidelity during patched inference.