residual-stream-state

Analyze layer-by-layer transformer predictions using tuned lenses and logit lens techniques.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires torch, transformers, numpy, matplotlib, datasets, tuned-lens, and includes scripts (resource) and references (resource) components.

What problem does it solve? Understanding how a transformer model builds its predictions across layers is difficult because intermediate hidden states are not directly interpretable. This Skill trains and applies tuned lenses to project intermediate residual stream states into vocabulary space, revealing how predictions evolve layer by layer. ## Core Features & Use Cases - Tuned Lens Training: Train affine translators per layer that map hidden states to vocabulary logits by minimizing KL divergence against the model's final output distribution. - Layer-wise Prediction Analysis: Extract hidden states from any HuggingFace causal LM, apply a lens at each layer, and inspect top-k token predictions, entropy evolution, and prediction trajectories. - Visualization & Comparison: Plot prediction trajectories for target tokens across layers and compare predictions at early, middle, and final layers. - Use Case: Given a prompt like "The capital of France is", trace how the model's belief about the next token shifts from generic words in early layers to "Paris" in later layers, quantifying confidence and entropy at each stage. ## Quick Start Run the tuned lens analysis on GPT-2 for the prompt "The capital of France is" and show me the top predictions at each layer.

Frequently Asked Questions about residual-stream-state

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

FAQPage Schema
How do I train a tuned lens for a transformer model?

Train one affine translator per layer that maps hidden states to vocabulary logits, minimizing KL divergence against the model's final output distribution. The train_tuned_lens.py script implements this using PyTorch, HuggingFace Transformers, and a text dataset like wikitext.

How to analyze layer-by-layer predictions in GPT-2?

Extract hidden states from every layer using output_hidden_states=True, then apply the unembedding matrix or a trained tuned lens to each state to get per-layer token probabilities. The analyze_predictions.py script computes top-k predictions and entropy per layer.

What is the difference between logit lens and tuned lens?

The logit lens directly applies the model's unembedding matrix to intermediate hidden states, while the tuned lens trains affine translators per layer to better align intermediate representations with the final output distribution. Tuned lenses typically give more accurate intermediate predictions.

Does tuned lens analysis work with models other than GPT-2?

Yes, the scripts work with any HuggingFace causal language model loaded via AutoModelForCausalLM. The code handles configuration differences such as n_layer versus num_hidden_layers and various unembedding attribute names.

What are the limitations of tuned lens interpretability?

Tuned lenses approximate final predictions from intermediate states but do not reveal the causal mechanisms producing them. Training quality depends on dataset coverage, and the simple logit lens fallback can be misleading for models whose residual stream is not aligned with the unembedding basis.