README.md

metadata

title: FeatureLens
emoji: 🔬
colorFrom: gray
colorTo: green
sdk: gradio
python_version: 3.12.12
sdk_version: 6.24.0
app_file: app.py
pinned: false
license: mit

FeatureLens

FeatureLens is a causal interpretability workbench for Qwen/Qwen3-1.7B-Base and Qwen-Scope residual-stream sparse autoencoders. It asks one question:

Do sparse features that predict a concept also causally influence model behaviour?

The project separates representational evidence from causal evidence. A feature can classify a concept well without controlling the downstream continuation one might infer from that association.

Measured study result

The committed offline study uses 224 discovery prompts (112 paraphrase pairs across seven controlled concepts) and 28 causal tasks.

• Selected SAE features averaged 0.962 held-out AUROC (median 0.987, bootstrap 95% CI [0.927, 0.994]).
• Dense final-token residual probes reached 1.000 macro AUROC at layers 14 and 26.
• Paraphrases preserved weighted sparse representations much more strongly than exact sparse support: mean cosine 0.985 versus TopK Jaccard 0.326.
• Selected features were active at the conventional final prompt token on only 28.6% of causal tasks, but somewhere in the prompt on 82.1%.
• At the final token, targeted SAE interventions were 1.52× the norm-matched random-control effect on average, but task-level uncertainty included zero (paired advantage +0.0026, 95% CI [-0.0005, +0.0063], sign-flip p=0.1719).
• When intervention positions were chosen only from the selected feature's maximum SAE activation within the prompt, coverage rose to 82.1% and targeted effects averaged 2.33× matched-random controls (paired advantage +0.0237, 95% CI [+0.0067, +0.0469], sign-flip p≈1×10⁻⁴).
• Final-token top-5 joint ablation produced only a 1.09× SAE/random ratio, so adding more associated features did not automatically yield stronger causal specificity.
• Across the seven concepts, held-out AUROC and max-active target specificity had only weak descriptive association (Spearman ρ=-0.185).

The main conclusion is therefore not that predictive SAE features are automatically causal. Causal evidence depended strongly on where the representation was tested, and predictive strength by itself was a poor proxy for random-normalized causal specificity across concepts.

See artifacts/report.md and the Study tab for the full measured result.

Live workbench

FeatureLens loads Qwen-Scope SAEs for residual layers 4, 14, and 26 and supports:

• token-level residual capture and TopK feature inspection;
• SAE reconstruction diagnostics and layer trajectories;
• single-feature ablation, scaling, and decoder-direction injection;
• exact full-continuation teacher-forced scoring;
• next-token distribution shifts and deterministic generation comparison;
• eight norm-matched random controls for live specificity checks;
• scale dose-response and contrastive continuation preference;
• joint feature-set interventions, set-size sweeps, non-additivity, and decoder geometry;
• concept-guided candidate discovery with current-token causal readiness;
• batched candidate triage and controlled multi-candidate comparison;
• completion-cue, cue × context, token-trace, and controlled-concept diagnostics;
• local and prompt-wide paraphrase robustness;
• cross-target causal profiles and pairwise preference shifts.

Feature ids remain unlabeled unless there is empirical evidence for a concept association.

Intervention semantics

For residual vector h, SAE coefficient z_i, decoder direction d_i, and multiplier α:

ablate: h' = h - z_i d_i
scale:   h' = h + (α - 1) z_i d_i
inject:  h' = h + δ d_i

FeatureLens applies the decoded delta to the original residual instead of replacing the residual with the full SAE reconstruction. Batched causal experiments include a zero-edit condition in the same execution context, and random controls match the L2 norm of the targeted SAE perturbation.

Offline study design

Concept evidence uses prompt-wide maximum SAE activation across non-padding tokens. Final-token sparse activations are saved separately for local analyses.

Causal evidence is reported under two position policies:

• final token — conventional final-prompt-token baseline;
• max feature activation — intervene where the selected feature is most strongly represented in that prompt.

Max-active positions are selected from SAE activation only, never from behavioral outcomes. Coverage is reported separately from effect strength.

The primary causal statistical unit is the causal task: ablation and 2× amplification are averaged within task before paired bootstrap and sign-flip inference.

The study additionally includes:

• train-only feature selection with held-out AUROC/F1;
• dense final-token residual linear-probe baselines;
• paraphrase robustness;
• 128-resample candidate-selection sensitivity;
• top-1/3/5 feature-set causal diagnostics;
• norm-matched random residual controls;
• cross-concept association-versus-causality synthesis.

Reproducing the study

The canonical command is:

python -m experiments.run_all --resume

On a 16 GB GPU, a smaller activation batch is usually more comfortable:

python -m experiments.run_all --resume --activation-batch-size 8

After the expensive model stages exist, regenerate only CPU analysis with:

python -m experiments.run_analysis_only

Validate the final artifact bundle with:

python -m scripts.validate_artifacts

Google Colab

Use notebooks/FeatureLens_Offline_Study_Colab.ipynb for a fresh full reproduction.

notebooks/FeatureLens_Causal_Addendum_Colab.ipynb is retained as the exact migration path used to extend an already-completed final-token baseline with the max-active causal study without recollecting discovery activations.

See notebooks/README.md and docs/COLAB.md.

Public artifacts

The repository commits only small measured outputs. Large activation caches and model/SAE weights are excluded.

artifacts/
├── feature_catalog.csv
├── layer_metrics.csv
├── stability.csv
├── selection_stability.csv
├── causal_results_final_token.csv
├── causal_results_max_active.csv
├── causal_position_summary.csv
├── feature_set_results.csv
├── study_feature_summary.csv
├── study_summary.json
├── summary.json
├── report.md
├── split.json
└── figures/

The Study tab reads these artifacts directly and does not rerun the model.

Repository layout

FeatureLens/
├── app.py
├── featurelens/          # SAE/runtime/intervention/study code
├── experiments/          # offline collection, causal study, analysis, reports
├── data/                 # controlled discovery prompts and causal tasks
├── artifacts/            # committed measured study outputs
├── notebooks/            # Colab study runners
├── scripts/              # validation and UI smoke checks
├── tests/
├── docs/
├── DESIGN.md
└── research_config.json

Validation

python3 -m pytest -q
python3 -m compileall -q app.py featurelens experiments scripts
python3 -m ruff check app.py featurelens experiments tests scripts
python3 scripts/ui_smoke.py
python3 scripts/release_check.py
python3 -m scripts.validate_artifacts

The UI smoke test performs a real local Gradio launch().

Interpretation guardrails

• Held-out AUROC/F1 measure concept association, not causal influence.
• Max-active intervention positions are selected from SAE activation only, never from behavioral effect size.
• Cross-concept correlations use only seven concepts and are descriptive.
• Per-concept causal task counts are small; the primary inference pools task-level paired effects across all 28 causal tasks.
• Five causal tasks contained no activation of the selected feature anywhere in the prompt; max-active coverage was therefore 82.1%, not 100%.
• Dense linear probes and prompt-wide SAE features use different pooling schemes and are separate baselines.
• Prompt-wide max pooling discards token order.
• Live eight-control empirical tails are coarse diagnostics; the offline study is the primary aggregate evidence.

Design

The public UI follows DESIGN.md: restrained typography and color, flat information hierarchy, compact actions, explicit result headings, and minimal decorative chrome.

License

MIT. See LICENSE.