Deploy ICA explorer app

.dockerignore

@@ -0,0 +1,6 @@
+.git
+__pycache__
+*.pyc
+.pytest_cache
+.venv
+artifacts/fetched/.cache

Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    ICA_EXPLORER_MODEL_NAME=gpt2 \
+    ICA_EXPLORER_ENABLED_MODELS=gpt2 \
+    ICA_EXPLORER_DEVICE=cpu \
+    ICA_EXPLORER_DTYPE=float32
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["python", "-m", "server.app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -3,8 +3,8 @@ title: ICAExplorer
 emoji: 📈
 colorFrom: red
 colorTo: gray
-sdk: static
+sdk: docker
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+ICA Lens Explorer Space.

configs/comparisons/gemma2_2b.toml

@@ -0,0 +1,76 @@
+[model]
+short_name = "gemma2_2b"
+hidden_size = 2304
+num_hidden_layers = 26
+
+[ica]
+artifact_set = "v3_frozen_ica"
+artifact_root = "artifacts/fetched/models"
+preprocess = "with_normalization"
+
+[sae]
+repo_id = "google/gemma-scope-2b-pt-res"
+checkpoint_format = "npz"
+hook_name_template = "model.layers.{layer}"
+layers = "all_transformer_layers"
+width = 16384
+direction_source = "decoder"
+decoder_key = "W_dec"
+
+# Gemma Scope stores concrete average_l0 folders rather than stable canonical files.
+# These width_16k residual SAEs match the v3 comparison configuration.
+[sae.layer_checkpoints]
+"0" = "layer_0/width_16k/average_l0_25/params.npz"
+"1" = "layer_1/width_16k/average_l0_20/params.npz"
+"2" = "layer_2/width_16k/average_l0_24/params.npz"
+"3" = "layer_3/width_16k/average_l0_28/params.npz"
+"4" = "layer_4/width_16k/average_l0_31/params.npz"
+"5" = "layer_5/width_16k/average_l0_34/params.npz"
+"6" = "layer_6/width_16k/average_l0_36/params.npz"
+"7" = "layer_7/width_16k/average_l0_36/params.npz"
+"8" = "layer_8/width_16k/average_l0_37/params.npz"
+"9" = "layer_9/width_16k/average_l0_37/params.npz"
+"10" = "layer_10/width_16k/average_l0_39/params.npz"
+"11" = "layer_11/width_16k/average_l0_41/params.npz"
+"12" = "layer_12/width_16k/average_l0_41/params.npz"
+"13" = "layer_13/width_16k/average_l0_43/params.npz"
+"14" = "layer_14/width_16k/average_l0_43/params.npz"
+"15" = "layer_15/width_16k/average_l0_41/params.npz"
+"16" = "layer_16/width_16k/average_l0_42/params.npz"
+"17" = "layer_17/width_16k/average_l0_42/params.npz"
+"18" = "layer_18/width_16k/average_l0_40/params.npz"
+"19" = "layer_19/width_16k/average_l0_40/params.npz"
+"20" = "layer_20/width_16k/average_l0_38/params.npz"
+"21" = "layer_21/width_16k/average_l0_38/params.npz"
+"22" = "layer_22/width_16k/average_l0_38/params.npz"
+"23" = "layer_23/width_16k/average_l0_38/params.npz"
+"24" = "layer_24/width_16k/average_l0_38/params.npz"
+"25" = "layer_25/width_16k/average_l0_28/params.npz"
+
+[direction_overlap]
+top_k = 1
+sae_chunk_size = 4096
+nearest_metric = "maximum_absolute_cosine"
+
+[saebench_tpp]
+enabled = true
+saebench_model_name = "gemma-2-2b"
+hook_name_template = "blocks.{layer}.hook_resid_post"
+llm_dtype = "bfloat16"
+llm_batch_size = 32
+sae_batch_size = 125
+random_seed = 42
+lower_vram_usage = false
+row_normalize = false
+signed_identity = false
+n_values = [2, 5, 10, 20, 50, 100, 500]
+dataset_names = [
+  "LabHC/bias_in_bios_class_set1",
+  "canrager/amazon_reviews_mcauley_1and5",
+]
+
+[saebench_tpp.sae_baseline]
+source = "sae_lens_registry"
+release_pattern = "gemma-scope-2b-pt-res"
+id_from_sae_layer_checkpoints = true
+allow_multiple = false

configs/comparisons/gpt2.toml

@@ -0,0 +1,46 @@
+[model]
+short_name = "gpt2"
+hidden_size = 768
+num_hidden_layers = 12
+
+[ica]
+artifact_set = "v3_frozen_ica"
+artifact_root = "artifacts/fetched/models"
+preprocess = "with_normalization"
+
+[sae]
+repo_id = "jbloom/GPT2-Small-OAI-v5-32k-resid-post-SAEs"
+checkpoint_template = "v5_32k_layer_{layer}.pt/sae_weights.safetensors"
+checkpoint_format = "safetensors"
+hook_name_template = "blocks.{layer}.hook_resid_post"
+layers = "all_transformer_layers"
+width = 32768
+direction_source = "decoder"
+
+[direction_overlap]
+top_k = 1
+sae_chunk_size = 4096
+nearest_metric = "maximum_absolute_cosine"
+
+[saebench_tpp]
+enabled = true
+saebench_model_name = "gpt2-small"
+hook_name_template = "blocks.{layer}.hook_resid_post"
+llm_dtype = "float32"
+llm_batch_size = 256
+sae_batch_size = 250
+random_seed = 42
+lower_vram_usage = false
+row_normalize = false
+signed_identity = false
+n_values = [2, 5, 10, 20, 50, 100, 500]
+dataset_names = [
+  "LabHC/bias_in_bios_class_set1",
+  "canrager/amazon_reviews_mcauley_1and5",
+]
+
+[saebench_tpp.sae_baseline]
+source = "sae_lens_registry"
+release_pattern = "gpt2-small-resid-post-v5-32k"
+id_pattern_template = "blocks\\.{layer}\\.hook_resid_post"
+allow_multiple = false

configs/comparisons/qwen3_5_2b_base.toml

@@ -0,0 +1,49 @@
+[model]
+short_name = "qwen3_5_2b_base"
+hidden_size = 2048
+num_hidden_layers = 24
+
+[ica]
+artifact_set = "v3_frozen_ica"
+artifact_root = "artifacts/fetched/models"
+preprocess = "with_normalization"
+
+[sae]
+repo_id = "Qwen/SAE-Res-Qwen3.5-2B-Base-W32K-L0_50"
+activation = "topk"
+checkpoint_template = "layer{layer}.sae.pt"
+checkpoint_format = "torch"
+hook_name_template = "model.layers.{layer}"
+layers = "all_transformer_layers"
+width = 32768
+direction_source = "decoder"
+decoder_key = "W_dec"
+top_k = 50
+
+[direction_overlap]
+top_k = 1
+sae_chunk_size = 4096
+nearest_metric = "maximum_absolute_cosine"
+
+[saebench_tpp]
+enabled = true
+saebench_model_name = "Qwen/Qwen3.5-2B-Base"
+hook_name_template = "blocks.{layer}.hook_resid_post"
+llm_dtype = "bfloat16"
+llm_batch_size = 16
+sae_batch_size = 125
+random_seed = 42
+lower_vram_usage = false
+row_normalize = false
+signed_identity = false
+n_values = [2, 5, 10, 20, 50, 100, 500]
+dataset_names = [
+  "LabHC/bias_in_bios_class_set1",
+  "canrager/amazon_reviews_mcauley_1and5",
+]
+
+[saebench_tpp.sae_baseline]
+source = "custom_checkpoint"
+release_name = "qwen_scope_res_w32k_l0_50_layer_{layer}"
+hook_name_template = "blocks.{layer}.hook_resid_post"
+allow_multiple = false

requirements.txt

@@ -0,0 +1,9 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+huggingface-hub>=0.23.0
+pydantic>=2.10.0
+numpy>=1.26.0
+torch>=2.5.0
+transformers>=4.44.0
+datasets>=2.20.0
+safetensors>=0.4.0

server/README.md

@@ -0,0 +1,40 @@
+# ICA Lens Explorer and Annotator
+
+This server is the public `v6` explorer/annotator for released ICA Lens
+artifacts. It serves component statistics, examples, annotations, random
+component samples, and live text probing when the corresponding model weights
+and ICA artifacts are available.
+
+Default local inputs:
+
+```text
+artifacts/fetched/models/
+artifacts/fetched/databases/ica_probe_mini.sqlite
+```
+
+The fetched mini database is the default server database. Use
+`ICA_EXPLORER_DB_PATH` only when you want to point the explorer at another
+SQLite file, such as `artifacts/fetched/databases/ica_probe_full.sqlite` or a
+locally reproduced demo database.
+
+Run from `v6`:
+
+```bash
+uv run python -m server.app --port 8001
+```
+
+Pages:
+
+```text
+/           GPT-2 text probe explorer
+/stats      component statistics overview
+/component  component examples page
+/annotate   manual annotation editor
+/random-components  random 05.1 component sample list
+```
+
+Set `ICA_EXPLORER_DB_PATH`, `ICA_EXPLORER_ICA_ROOT`,
+`ICA_EXPLORER_ICA_DIR`, `ICA_EXPLORER_DEVICE`, or `ICA_EXPLORER_DTYPE` to
+override defaults. If local inputs are missing, the server attempts to fetch
+released artifacts from the configured Hugging Face dataset unless
+`ICA_EXPLORER_DOWNLOAD_MISSING=0`.

server/app.py

@@ -0,0 +1,816 @@
+from __future__ import annotations
+
+import argparse
+import gc
+import html
+import json
+import threading
+from contextlib import asynccontextmanager
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, ConfigDict, Field
+
+from .artifacts import resolve_db_path, resolve_ica_dir, validate_ica_dir
+from .config import Settings, load_settings
+from .model_runtime import load_model_and_tokenizer, load_tokenizer
+from .probe import _decode_byte_level_token, fastica_artifact_path, interpret_text_probe, list_ica_layer_keys
+from .sae_probe import interpret_text_sae_probe, list_sae_layers, load_sae_config
+from .store import (
+    connect,
+    get_annotation,
+    get_component_row,
+    get_examples_by_region,
+    infer_default_annotation_sign,
+    init_db,
+    list_annotated_components,
+    list_component_example_details,
+    list_component_examples,
+    list_component_metadata,
+    list_component_neighbors,
+    list_component_stats,
+    list_components,
+    list_chosen_random_components,
+    list_layers,
+    list_models,
+    pick_default_region,
+    search_components,
+    update_annotation,
+    validate_db,
+)
+
+
+STATIC_DIR = Path(__file__).resolve().parent / "static"
+V6_ROOT = Path(__file__).resolve().parents[1]
+GPT2_LAYER11_PATCH_ROOT = V6_ROOT / "patch_gpt2_layer11"
+GPT2_LAYER11_PATCH_DB = GPT2_LAYER11_PATCH_ROOT / "data" / "server" / "db" / "ica_probe_gpt2_layer11_patch.sqlite"
+GPT2_LAYER11_PATCH_ICA_ROOT = GPT2_LAYER11_PATCH_ROOT / "data" / "ica"
+ANNOTATION_TYPES = ["Form", "Word", "Phrase", "Sentence", "Long-Range Context", "Global", "Position", "Sophisticated"]
+
+
+class ProbeRequest(BaseModel):
+    text: str = Field(..., min_length=1, max_length=100_000)
+    model_name: str = "gpt2"
+    layer: str
+    top_k: int = Field(5, ge=1, le=32)
+    highlights: list[int] = Field(default_factory=list, max_length=256)
+    max_length: int | None = Field(None, ge=16, le=8192)
+    keep_models: bool = False
+
+
+class SaeProbeRequest(BaseModel):
+    text: str = Field(..., min_length=1, max_length=100_000)
+    model_name: str = "gpt2"
+    layer: str
+    top_k: int = Field(5, ge=1, le=128)
+    max_length: int | None = Field(None, ge=16, le=8192)
+    keep_models: bool = False
+
+
+class AnnotationUpdate(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    model_name: str
+    layer: str
+    component: int
+    positive_label: str = ""
+    positive_confidence: str = "unclear"
+    positive_interpretation_types: list[str] = Field(default_factory=list)
+    negative_label: str = ""
+    negative_confidence: str = "unclear"
+    negative_interpretation_types: list[str] = Field(default_factory=list)
+    summary: str = ""
+    notes: str = ""
+    include_as_case_study: bool = False
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    settings = settings or load_settings()
+    db_path = resolve_db_path(settings)
+    ica_dirs = {}
+    for model_name, model_settings in settings.models.items():
+        try:
+            ica_dirs[model_name] = resolve_ica_dir(settings, model_name=model_name, ica_dir=model_settings.ica_dir)
+        except FileNotFoundError:
+            continue
+    if not ica_dirs:
+        raise FileNotFoundError("No ICA artifact directories are available for the configured models.")
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        conn = connect(db_path)
+        init_db(conn)
+        validate_db(conn, None)
+        app.state.conn = conn
+        app.state.settings = settings
+        app.state.ica_dirs = ica_dirs
+        app.state.ica_dir = ica_dirs.get(settings.model_name, next(iter(ica_dirs.values())))
+        app.state.use_gpt2_layer11_patch = bool(getattr(settings, "use_gpt2_layer11_patch", False)) or _db_marks_gpt2_layer11_raw_hook(conn)
+        app.state.db_lock = threading.RLock()
+        app.state.runtime_lock = threading.Lock()
+        app.state.runtimes = {}
+        app.state.runtime = None
+        app.state.runtime_key = None
+        app.state.full_context_cache = {}
+        try:
+            yield
+        finally:
+            app.state.runtimes.clear()
+            app.state.runtime = None
+            app.state.runtime_key = None
+            conn.close()
+            _collect_memory()
+
+    app = FastAPI(title="ICA Lens Explorer", lifespan=lifespan)
+    app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
+    app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+    @app.get("/api/health")
+    def health() -> dict[str, str]:
+        return {"status": "ok"}
+
+    @app.get("/api/meta")
+    def meta(model: str | None = None) -> dict[str, Any]:
+        model_name = model or app.state.settings.model_name
+        return _model_meta(app, model_name)
+
+    @app.post("/api/probe")
+    def probe(body: ProbeRequest) -> dict[str, Any]:
+        model_settings = _model_settings(app, body.model_name)
+        ica_dir = app.state.ica_dirs.get(model_settings.model_name)
+        if ica_dir is None:
+            raise HTTPException(status_code=404, detail=f"No ICA artifacts for model {model_settings.model_name!r}")
+        artifact = fastica_artifact_path(ica_dir, body.layer)
+        if not artifact.is_file():
+            raise HTTPException(status_code=404, detail=f"No ICA artifact for {model_settings.model_name!r} layer {body.layer!r}")
+        try:
+            with app.state.runtime_lock:
+                runtimes = app.state.runtimes
+                if not body.keep_models:
+                    for loaded_name in list(runtimes):
+                        if loaded_name != model_settings.model_name:
+                            del runtimes[loaded_name]
+                    _collect_memory()
+                runtime = runtimes.get(model_settings.model_name)
+                if runtime is None:
+                    runtime = load_model_and_tokenizer(
+                        model_settings.model_id,
+                        device=app.state.settings.device,
+                        dtype=model_settings.dtype,
+                    )
+                    runtimes[model_settings.model_name] = runtime
+                app.state.runtime = runtime
+                app.state.runtime_key = model_settings.model_name
+                model, tokenizer = runtime
+                result = interpret_text_probe(
+                    model=model,
+                    tokenizer=tokenizer,
+                    text=body.text,
+                    layer=body.layer,
+                    ica_artifact_path=artifact,
+                    top_k=body.top_k,
+                    highlight_components=body.highlights,
+                    max_length=body.max_length or model_settings.context_length,
+                    raw_gpt2_block_index=_raw_gpt2_block_index_for_probe(app, model_settings.model_name, body.layer),
+                )
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        except RuntimeError as exc:
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
+        components = sorted({int(pair["component"]) for token in result.get("tokens", []) for pair in token.get("top", [])})
+        with app.state.db_lock:
+            annotated = list_component_metadata(app.state.conn, model_settings.model_name, body.layer, components)
+        return {**result, "annotated_components": annotated}
+
+    @app.get("/api/sae-meta")
+    def sae_meta(model: str | None = None) -> dict[str, Any]:
+        model_name = model or app.state.settings.model_name
+        model_settings = _model_settings(app, model_name)
+        try:
+            sae_config = load_sae_config(model_settings.model_name)
+            layers = list_sae_layers(model_settings.model_name)
+        except (FileNotFoundError, KeyError, ValueError) as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        return {
+            "model_name": model_settings.model_name,
+            "display_name": model_settings.display_name,
+            "model_id": model_settings.model_id,
+            "context_length": model_settings.context_length,
+            "layers": layers,
+            "device": app.state.settings.device,
+            "dtype": model_settings.dtype,
+            "sae": {
+                "repo_id": sae_config.get("repo_id"),
+                "width": sae_config.get("width"),
+                "top_k": sae_config.get("top_k"),
+                "activation": sae_config.get("activation"),
+            },
+            "model_loaded": model_settings.model_name in getattr(app.state, "runtimes", {}),
+        }
+
+    @app.post("/api/sae-probe")
+    def sae_probe(body: SaeProbeRequest) -> dict[str, Any]:
+        model_settings = _model_settings(app, body.model_name)
+        try:
+            if body.layer not in list_sae_layers(model_settings.model_name):
+                raise ValueError(f"No SAE configured for {model_settings.model_name!r} layer {body.layer!r}")
+            with app.state.runtime_lock:
+                runtimes = app.state.runtimes
+                if not body.keep_models:
+                    for loaded_name in list(runtimes):
+                        if loaded_name != model_settings.model_name:
+                            del runtimes[loaded_name]
+                    _collect_memory()
+                runtime = runtimes.get(model_settings.model_name)
+                if runtime is None:
+                    runtime = load_model_and_tokenizer(
+                        model_settings.model_id,
+                        device=app.state.settings.device,
+                        dtype=model_settings.dtype,
+                    )
+                    runtimes[model_settings.model_name] = runtime
+                app.state.runtime = runtime
+                app.state.runtime_key = model_settings.model_name
+                model, tokenizer = runtime
+                return interpret_text_sae_probe(
+                    model=model,
+                    tokenizer=tokenizer,
+                    text=body.text,
+                    model_name=model_settings.model_name,
+                    layer=body.layer,
+                    top_k=body.top_k,
+                    max_length=body.max_length or model_settings.context_length,
+                )
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        except (FileNotFoundError, KeyError) as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        except RuntimeError as exc:
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    @app.get("/api/component-stats")
+    def component_stats(model: str | None = None) -> dict[str, Any]:
+        model_name = model or app.state.settings.model_name
+        with app.state.db_lock:
+            rows = list_component_stats(app.state.conn, model_name)
+        layers: list[dict[str, Any]] = []
+        for row in rows:
+            if not layers or layers[-1]["layer"] != row["layer"]:
+                layers.append({"layer": row["layer"], "components": []})
+            layers[-1]["components"].append({key: value for key, value in row.items() if key != "layer"})
+        return {"model_name": model_name, "layers": layers}
+
+    @app.get("/api/component-examples")
+    def component_examples(layer: str, component: int, model: str | None = None) -> dict[str, Any]:
+        model_name = model or app.state.settings.model_name
+        with app.state.db_lock:
+            rows = list_components(app.state.conn, model_name, layer=layer, component=component)
+            if not rows:
+                raise HTTPException(status_code=404, detail="Unknown layer/component")
+            examples = list_component_example_details(app.state.conn, model_name, layer=layer, component=component)
+        tokenizer = None
+        model_settings = app.state.settings.models.get(model_name)
+        if model_settings is not None:
+            tokenizer = load_tokenizer(model_settings.model_id)
+        for example in examples:
+            example["token"] = _visible_token_text(example.get("token"), token_id=example.get("token_id"), tokenizer=tokenizer)
+        bands: dict[str, list[dict[str, Any]]] = {}
+        for example in examples:
+            bands.setdefault(str(example["region"] or "examples"), []).append(example)
+        return {
+            "model_name": model_name,
+            "layer": layer,
+            "component": component,
+            "excess_kurtosis": rows[0]["excess_kurtosis"],
+            "bands": [{"region": region, "examples": items} for region, items in sorted(bands.items(), key=lambda item: _example_band_sort_key(item[0]))],
+        }
+
+    @app.get("/api/component-token-stats")
+    def component_token_stats(layer: str, component: int, model: str | None = None) -> dict[str, Any]:
+        model_name = model or app.state.settings.model_name
+        with app.state.db_lock:
+            rows = list_components(app.state.conn, model_name, layer=layer, component=component)
+            if not rows:
+                raise HTTPException(status_code=404, detail="Unknown layer/component")
+            examples = list_component_examples(app.state.conn, model_name, layer=layer, component=component).get((layer, component), [])
+        tokenizer = None
+        model_settings = app.state.settings.models.get(model_name)
+        if model_settings is not None:
+            tokenizer = load_tokenizer(model_settings.model_id)
+        counts: dict[str, int] = {}
+        first_seen: dict[str, int] = {}
+        total_count = 0
+        for example in examples:
+            if example["region"] not in {"top_abs", "top_abs_sample_500"}:
+                continue
+            token = _visible_token_text(example["token"], token_id=example.get("token_id"), tokenizer=tokenizer)
+            if not token:
+                continue
+            total_count += 1
+            first_seen.setdefault(token, total_count)
+            counts[token] = counts.get(token, 0) + 1
+        ordered_tokens = sorted(counts.items(), key=lambda item: (-item[1], first_seen[item[0]]))
+        return {"model_name": model_name, "layer": layer, "component": component, "total_count": total_count, "tokens": [{"token": token, "count": count} for token, count in ordered_tokens]}
+
+    @app.get("/api/component-neighbors")
+    def component_neighbors(layer: str, component: int, model: str | None = None) -> dict[str, Any]:
+        model_name = model or app.state.settings.model_name
+        with app.state.db_lock:
+            rows = list_components(app.state.conn, model_name, layer=layer, component=component)
+            if not rows:
+                raise HTTPException(status_code=404, detail="Unknown layer/component")
+            neighbors = list_component_neighbors(app.state.conn, model_name, layer=layer, component=component)
+        return {"model_name": model_name, "layer": layer, "component": component, "neighbors": neighbors}
+
+    @app.get("/api/models")
+    def api_models() -> dict[str, Any]:
+        models = []
+        with app.state.db_lock:
+            model_names = list_models(app.state.conn)
+        for model_name in model_names:
+            model_settings = app.state.settings.models.get(model_name)
+            ica_dir = app.state.ica_dirs.get(model_name)
+            models.append(
+                {
+                    "model_name": model_name,
+                    "display_name": model_settings.display_name if model_settings else model_name,
+                    "model_id": model_settings.model_id if model_settings else "",
+                    "context_length": model_settings.context_length if model_settings else None,
+                    "has_examples": True,
+                    "probe_supported": model_settings is not None and ica_dir is not None,
+                    "ica_layers": list_ica_layer_keys(ica_dir) if ica_dir else [],
+                }
+            )
+        return {"models": models}
+
+    @app.get("/api/layers")
+    def api_layers(model: str) -> dict[str, Any]:
+        with app.state.db_lock:
+            layers = list_layers(app.state.conn, model)
+        return {"layers": layers}
+
+    @app.get("/api/components")
+    def api_components(model: str, layer: str | None = None, search: str | None = None) -> dict[str, Any]:
+        with app.state.db_lock:
+            components = list_components(app.state.conn, model_name=model, layer=layer, search=search)
+        return {"components": components}
+
+    @app.get("/api/search/components")
+    def api_search_components(model: str | None = None, q: str | None = None, confidence: str | None = None, type: str | None = None, include_examples: bool = False, limit: int = 200) -> dict[str, Any]:
+        with app.state.db_lock:
+            results = search_components(app.state.conn, model_name=model, query=q or "", confidence=confidence or "", annotation_type=type or "", include_examples=include_examples, limit=limit)
+        return {"results": results}
+
+    @app.get("/api/random-components")
+    def api_random_components(model: str | None = None, selection: str | None = None) -> dict[str, Any]:
+        with app.state.db_lock:
+            rows = list_chosen_random_components(app.state.conn, model_name=model, selection_name=selection)
+        runs_by_key: dict[tuple[str, str], dict[str, Any]] = {}
+        for row in rows:
+            model_name = str(row["model_name"])
+            selection_name = str(row["selection_name"])
+            key = (model_name, selection_name)
+            run = runs_by_key.setdefault(
+                key,
+                {
+                    "model": model_name,
+                    "selection_name": selection_name,
+                    "source_json": row.get("source_json"),
+                    "settings": {
+                        "n": row.get("requested_n"),
+                        "seed": row.get("seed"),
+                    },
+                    "inventory_size": row.get("inventory_size"),
+                    "selected_size": row.get("selected_size"),
+                    "selected_components": [],
+                },
+            )
+            component = int(row["component"])
+            layer = str(row["layer"])
+            default_sign = infer_default_annotation_sign(app.state.conn, model_name, layer, component)
+            run["selected_components"].append(
+                {
+                    **row,
+                    "component_index": component,
+                    "top_abs_sign": default_sign,
+                    "annotation": _annotation_response(row),
+                    "annotate_url": f"/annotate?model={model_name}&layer={layer}&component={component}",
+                }
+            )
+        return {"runs": list(runs_by_key.values())}
+
+    @app.get("/api/annotations/component")
+    def api_get_annotation(model: str, layer: str, component: int) -> dict[str, Any]:
+        with app.state.db_lock:
+            row = get_annotation(app.state.conn, model, layer, component)
+            if not row:
+                sign = infer_default_annotation_sign(app.state.conn, model, layer, component)
+                return _blank_annotation(model, layer, component, default_sign=sign)
+        return _annotation_response(row)
+
+    @app.post("/api/annotations/component")
+    def api_post_annotation(body: AnnotationUpdate) -> dict[str, str]:
+        with app.state.db_lock:
+            if get_component_row(app.state.conn, body.model_name, body.layer, body.component) is None:
+                raise HTTPException(status_code=404, detail="Unknown model/layer/component")
+            update_annotation(
+                app.state.conn,
+                model_name=body.model_name,
+                layer=body.layer,
+                component=body.component,
+                positive_label=body.positive_label,
+                positive_confidence=body.positive_confidence,
+                positive_interpretation_types=body.positive_interpretation_types,
+                negative_label=body.negative_label,
+                negative_confidence=body.negative_confidence,
+                negative_interpretation_types=body.negative_interpretation_types,
+                summary=body.summary,
+                notes=body.notes,
+                include_as_case_study=body.include_as_case_study,
+            )
+        return {"status": "ok"}
+
+    @app.get("/api/examples/component")
+    def api_examples_component(model: str, layer: str, component: int) -> dict[str, Any]:
+        with app.state.db_lock:
+            if get_component_row(app.state.conn, model, layer, component) is None:
+                raise HTTPException(status_code=404, detail="Unknown model/layer/component")
+            regions, examples_by_region = get_examples_by_region(app.state.conn, model, layer, component)
+        tokenizer = None
+        model_settings = app.state.settings.models.get(model)
+        if model_settings is not None:
+            tokenizer = load_tokenizer(model_settings.model_id)
+        for examples in examples_by_region.values():
+            for example in examples:
+                example["token"] = _visible_token_text(example.get("token"), token_id=example.get("token_id"), tokenizer=tokenizer)
+        return {"model_name": model, "layer": layer, "component": component, "regions": regions, "default_region": pick_default_region(regions, examples_by_region), "examples_by_region": examples_by_region}
+
+    @app.get("/api/annotation-types")
+    def api_annotation_types() -> dict[str, Any]:
+        return {"types": ANNOTATION_TYPES}
+
+    @app.get("/context")
+    def full_context_page(model: str, doc_id: int, position: int | None = None, target: str | None = None) -> HTMLResponse:
+        model_settings = _model_settings(app, model)
+        text = _load_dataset_doc_text(app, model_settings, doc_id)
+        target_span = _target_token_char_span(model_settings, text, position)
+        if target_span is None:
+            target_span = _fallback_target_char_span(text, target)
+        return HTMLResponse(
+            _render_full_context_page(
+                model_name=model_settings.model_name,
+                doc_id=doc_id,
+                position=position,
+                text=text,
+                target_span=target_span,
+            )
+        )
+
+    @app.get("/")
+    def index() -> FileResponse:
+        return FileResponse(STATIC_DIR / "index.html")
+
+    @app.get("/stats")
+    def stats() -> FileResponse:
+        return FileResponse(STATIC_DIR / "stats.html")
+
+    @app.get("/component")
+    def component_page() -> FileResponse:
+        return FileResponse(STATIC_DIR / "component.html")
+
+    @app.get("/annotate")
+    def annotate_page() -> FileResponse:
+        return FileResponse(STATIC_DIR / "annotate.html")
+
+    @app.get("/random-components")
+    def random_components_page() -> FileResponse:
+        return FileResponse(STATIC_DIR / "random_components.html")
+
+    @app.get("/sae-explorer")
+    def sae_explorer_page() -> FileResponse:
+        return FileResponse(STATIC_DIR / "sae_explorer.html")
+
+    return app
+
+
+def _model_settings(app: FastAPI, model_name: str):
+    model_settings = app.state.settings.models.get(model_name)
+    if model_settings is None:
+        raise HTTPException(status_code=404, detail=f"Model {model_name!r} is not configured for text probing.")
+    return model_settings
+
+
+def _raw_gpt2_block_index_for_probe(app: FastAPI, model_name: str, layer: str) -> int | None:
+    if not getattr(app.state, "use_gpt2_layer11_patch", False):
+        return None
+    if model_name == "gpt2" and layer == "layer_11":
+        return 11
+    return None
+
+
+def _db_marks_gpt2_layer11_raw_hook(conn) -> bool:
+    try:
+        row = conn.execute(
+            """
+            SELECT value
+            FROM import_meta
+            WHERE model_name = ?
+              AND key = ?
+            """,
+            ("gpt2", "gpt2_layer11_probe_site"),
+        ).fetchone()
+    except Exception:
+        return False
+    if row is None:
+        return False
+    value = str(row[0]).strip().lower()
+    return value in {"raw_block_11_resid_post", "patched_raw_block_11_resid_post"}
+
+
+def _settings_with_gpt2_layer11_patch(settings: Settings) -> Settings:
+    gpt2_settings = settings.models.get("gpt2")
+    if gpt2_settings is None:
+        raise RuntimeError("GPT-2 settings are required for --use-gpt2-layer11-patch.")
+    if not GPT2_LAYER11_PATCH_DB.is_file():
+        raise FileNotFoundError(f"Patch SQLite database does not exist: {GPT2_LAYER11_PATCH_DB}")
+    if not (GPT2_LAYER11_PATCH_ICA_ROOT / "gpt2" / "layer_11_fastica.pt").is_file():
+        raise FileNotFoundError(f"Patch ICA artifact does not exist: {GPT2_LAYER11_PATCH_ICA_ROOT / 'gpt2' / 'layer_11_fastica.pt'}")
+    models = dict(settings.models)
+    models["gpt2"] = replace(gpt2_settings, ica_dir=GPT2_LAYER11_PATCH_ICA_ROOT / "gpt2")
+    patched = replace(
+        settings,
+        db_path=GPT2_LAYER11_PATCH_DB,
+        ica_root=GPT2_LAYER11_PATCH_ICA_ROOT,
+        ica_dir=GPT2_LAYER11_PATCH_ICA_ROOT / "gpt2",
+        model_name="gpt2",
+        download_missing=False,
+        models=models,
+        use_gpt2_layer11_patch=True,
+    )
+    return patched
+
+
+def _model_meta(app: FastAPI, model_name: str) -> dict[str, Any]:
+    model_settings = _model_settings(app, model_name)
+    ica_dir = app.state.ica_dirs.get(model_settings.model_name)
+    layers = list_ica_layer_keys(ica_dir) if ica_dir else []
+    with app.state.db_lock:
+        db_layers = set(list_layers(app.state.conn, model_settings.model_name))
+    return {
+        "model_name": model_settings.model_name,
+        "display_name": model_settings.display_name,
+        "model_id": model_settings.model_id,
+        "context_length": model_settings.context_length,
+        "layers": [layer for layer in layers if layer in db_layers],
+        "device": app.state.settings.device,
+        "dtype": model_settings.dtype,
+        "model_loaded": model_settings.model_name in getattr(app.state, "runtimes", {}),
+    }
+
+
+def _blank_annotation(model: str, layer: str, component: int, *, default_sign: int) -> dict[str, Any]:
+    positive_label = "" if default_sign >= 0 else "?"
+    negative_label = "?" if default_sign >= 0 else ""
+    return {
+        "model_name": model,
+        "layer": layer,
+        "component": component,
+        "positive_label": positive_label,
+        "positive_confidence": "unclear",
+        "positive_interpretation_types": [],
+        "negative_label": negative_label,
+        "negative_confidence": "unclear",
+        "negative_interpretation_types": [],
+        "summary": "",
+        "notes": "",
+        "include_as_case_study": False,
+        "updated_at": None,
+    }
+
+
+def _annotation_response(row: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "model_name": row["model_name"],
+        "layer": row["layer"],
+        "component": int(row["component"]),
+        "positive_label": row.get("positive_label") or "",
+        "positive_confidence": row.get("positive_confidence") or "unclear",
+        "positive_interpretation_types": _json_list(row.get("positive_interpretation_types_json")),
+        "negative_label": row.get("negative_label") or "",
+        "negative_confidence": row.get("negative_confidence") or "unclear",
+        "negative_interpretation_types": _json_list(row.get("negative_interpretation_types_json")),
+        "summary": row.get("summary") or "",
+        "notes": row.get("notes") or "",
+        "include_as_case_study": bool(row.get("include_as_case_study")),
+        "updated_at": row.get("updated_at"),
+    }
+
+
+def _json_list(value: Any) -> list[str]:
+    import json
+    try:
+        parsed = json.loads(value or "[]")
+    except json.JSONDecodeError:
+        return []
+    return [str(item) for item in parsed] if isinstance(parsed, list) else []
+
+
+def _load_dataset_doc_text(app: FastAPI, model_settings: Any, doc_id: int) -> str:
+    if doc_id < 0:
+        raise HTTPException(status_code=400, detail="doc_id must be non-negative")
+    key = (model_settings.model_name, doc_id)
+    cached = app.state.full_context_cache.get(key)
+    if cached is not None:
+        return cached
+    try:
+        from datasets import load_dataset
+    except ImportError as exc:
+        raise HTTPException(status_code=500, detail="datasets is required to open full document context") from exc
+    dataset_kwargs: dict[str, Any] = {
+        "path": model_settings.dataset_path,
+        "split": model_settings.dataset_split,
+        "streaming": model_settings.dataset_streaming,
+    }
+    if model_settings.dataset_name:
+        dataset_kwargs["name"] = model_settings.dataset_name
+    try:
+        dataset = load_dataset(**dataset_kwargs)
+        if model_settings.dataset_streaming:
+            for idx, row in enumerate(dataset):
+                if idx == doc_id:
+                    text = str(row[model_settings.dataset_text_column])
+                    app.state.full_context_cache[key] = text
+                    return text
+                if idx > doc_id:
+                    break
+        else:
+            row = dataset[doc_id]
+            text = str(row[model_settings.dataset_text_column])
+            app.state.full_context_cache[key] = text
+            return text
+    except IndexError as exc:
+        raise HTTPException(status_code=404, detail=f"Document {doc_id} not found in {model_settings.dataset_path}/{model_settings.dataset_split}") from exc
+    except KeyError as exc:
+        raise HTTPException(status_code=500, detail=f"Dataset row does not contain text column {model_settings.dataset_text_column!r}") from exc
+    raise HTTPException(status_code=404, detail=f"Document {doc_id} not found in {model_settings.dataset_path}/{model_settings.dataset_split}")
+
+
+def _target_token_char_span(model_settings: Any, text: str, position: int | None) -> tuple[int, int] | None:
+    if position is None or position < 0:
+        return None
+    tokenizer = load_tokenizer(model_settings.model_id)
+    try:
+        encoded = tokenizer(
+            text,
+            truncation=True,
+            max_length=model_settings.context_length,
+            return_offsets_mapping=True,
+        )
+    except (NotImplementedError, TypeError, ValueError):
+        return None
+    offsets = encoded.get("offset_mapping")
+    if offsets is None or position >= len(offsets):
+        return None
+    start, stop = offsets[position]
+    start = int(start)
+    stop = int(stop)
+    if stop <= start:
+        return None
+    return start, stop
+
+
+def _fallback_target_char_span(text: str, target: str | None) -> tuple[int, int] | None:
+    if not target:
+        return None
+    candidates = [target.replace("\ufffd", "")]
+    stripped = candidates[0].strip()
+    if stripped and stripped != candidates[0]:
+        candidates.append(stripped)
+    for candidate in candidates:
+        if not candidate:
+            continue
+        start = text.find(candidate)
+        if start >= 0:
+            return start, start + len(candidate)
+    return None
+
+
+def _highlighted_text_html(text: str, target_span: tuple[int, int] | None) -> str:
+    if target_span is None:
+        return html.escape(text)
+    start, stop = target_span
+    start = max(0, min(start, len(text)))
+    stop = max(start, min(stop, len(text)))
+    return f'{html.escape(text[:start])}<mark id="target-token">{html.escape(text[start:stop])}</mark>{html.escape(text[stop:])}'
+
+
+def _render_full_context_page(*, model_name: str, doc_id: int, position: int | None, text: str, target_span: tuple[int, int] | None) -> str:
+    pos = "" if position is None else f" - pos={html.escape(str(position))}"
+    title = f"{model_name} - doc={doc_id}{pos}"
+    content = _highlighted_text_html(text, target_span)
+    target_status = "" if target_span is not None else '<span class="target-status">target token not located</span>'
+    return f'''<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>{html.escape(title)}</title>
+  <style>
+    body {{ margin:0; background:#f8fafc; color:#0f172a; font:16px/1.55 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif; }}
+    header {{ position:sticky; top:0; background:#fff; border-bottom:1px solid #cbd5e1; padding:14px 18px; color:#475569; font-size:13px; box-shadow:0 1px 2px rgb(15 23 42 / .08); }}
+    pre {{ max-width:980px; margin:24px auto; padding:0 20px 48px; white-space:pre-wrap; overflow-wrap:anywhere; font:inherit; }}
+    mark {{ background:#bfdbfe; color:#172554; border-radius:4px; padding:1px 3px; box-shadow:0 0 0 1px #93c5fd inset; }}
+    .target-status {{ margin-left:10px; color:#b45309; }}
+  </style>
+</head>
+<body>
+  <header>{html.escape(title)}{target_status}</header>
+  <pre>{content}</pre>
+  <script>const target=document.getElementById("target-token"); if(target) target.scrollIntoView({{block:"center"}});</script>
+</body>
+</html>'''
+
+
+def _collect_memory() -> None:
+    gc.collect()
+    try:
+        import torch
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+    except Exception:
+        pass
+
+
+def _example_band_sort_key(region: str) -> tuple[int, str]:
+    name = str(region or "").lower().replace("-", "_")
+    compact = name.replace("_", "")
+    if name == "top_abs" or compact == "topabs":
+        return (0, name)
+    if "sample" in name:
+        return (1, name)
+    if "near_zero" in name or "nearzero" in compact:
+        return (2, name)
+    if "opposite" in name:
+        return (3, name)
+    return (4, name)
+
+
+def _visible_token_text(token: Any, *, token_id: Any = None, tokenizer: Any = None) -> str:
+    raw = str(token or "")
+    text = raw.strip()
+    if (not text or "\ufffd" in text) and tokenizer is not None and token_id is not None:
+        try:
+            token_id_int = int(token_id)
+            decoded = str(tokenizer.decode([token_id_int], skip_special_tokens=False, clean_up_tokenization_spaces=False))
+        except Exception:
+            decoded = ""
+        if decoded and "\ufffd" not in decoded:
+            raw = decoded
+            text = raw.strip()
+        else:
+            try:
+                raw_token = str(tokenizer.convert_ids_to_tokens(token_id_int))
+            except Exception:
+                raw_token = ""
+            byte_decoded = _decode_byte_level_token(raw_token) if raw_token else None
+            if byte_decoded:
+                raw = byte_decoded
+                text = raw.strip()
+            elif raw_token and "\ufffd" not in raw_token:
+                raw = raw_token
+                text = raw.strip()
+    if text:
+        return text
+    if raw == " ":
+        return "[space]"
+    if raw == "\n":
+        return "[newline]"
+    if raw == "\t":
+        return "[tab]"
+    return raw.replace("\ufffd", "[invalid]")
+
+
+def main() -> None:
+    import uvicorn
+    parser = argparse.ArgumentParser(description="Run the ICA Lens explorer/annotator server.")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8764)
+    parser.add_argument(
+        "--use-gpt2-layer11-patch",
+        action="store_true",
+        help="Use the isolated corrected GPT-2 layer-11 patch DB/artifacts and raw block hook for live layer-11 probes.",
+    )
+    args = parser.parse_args()
+    settings = load_settings()
+    if args.use_gpt2_layer11_patch:
+        settings = _settings_with_gpt2_layer11_patch(settings)
+    uvicorn.run(create_app(settings), host=args.host, port=args.port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

server/artifacts.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from huggingface_hub import hf_hub_download, snapshot_download
+
+from .config import Settings
+
+
+RELEASED_DATABASES = {"ica_probe_mini.sqlite", "ica_probe_full.sqlite"}
+
+
+def resolve_db_path(settings: Settings) -> Path:
+    if settings.db_path.is_file():
+        _validate_readable_file(settings.db_path)
+        return settings.db_path
+    if not settings.download_missing:
+        raise FileNotFoundError(f"SQLite database does not exist: {settings.db_path}")
+    if settings.db_path.name not in RELEASED_DATABASES:
+        raise FileNotFoundError(
+            f"SQLite database does not exist: {settings.db_path}. "
+            "Automatic download is only supported for released mini/full databases."
+        )
+    settings.db_path.parent.mkdir(parents=True, exist_ok=True)
+    local_dir = settings.db_path.parent.parent if settings.db_path.parent.name == "databases" else settings.db_path.parent
+    downloaded = Path(
+        hf_hub_download(
+            repo_id=settings.db_repo,
+            repo_type="dataset",
+            filename=f"databases/{settings.db_path.name}",
+            revision=settings.hf_revision,
+            local_dir=local_dir,
+        )
+    )
+    _validate_readable_file(downloaded)
+    return downloaded
+
+
+def resolve_ica_dir(settings: Settings, *, model_name: str | None = None, ica_dir: Path | None = None) -> Path:
+    target_model = model_name or settings.model_name
+    target_dir = ica_dir or settings.ica_dir
+    if _has_fastica_artifacts(target_dir):
+        return target_dir
+    if not settings.download_missing:
+        raise FileNotFoundError(f"ICA artifacts do not exist: {target_dir}")
+    target_dir.parent.parent.mkdir(parents=True, exist_ok=True)
+    snapshot_download(
+        repo_id=settings.artifact_repo,
+        repo_type="dataset",
+        revision=settings.hf_revision,
+        allow_patterns=[f"models/{target_model}/**"],
+        local_dir=target_dir.parent.parent,
+    )
+    if not _has_fastica_artifacts(target_dir):
+        raise FileNotFoundError(f"Downloaded artifacts but found no FastICA files in {target_dir}")
+    return target_dir
+
+
+def validate_ica_dir(ica_dir: Path) -> None:
+    if not _has_fastica_artifacts(ica_dir):
+        raise FileNotFoundError(f"No *_fastica.pt artifacts found in {ica_dir}")
+
+
+def _has_fastica_artifacts(path: Path) -> bool:
+    return path.is_dir() and any(path.glob("*_fastica.pt"))
+
+
+def _validate_readable_file(path: Path) -> None:
+    try:
+        with path.open("rb"):
+            pass
+    except OSError as exc:
+        raise RuntimeError(f"File exists but cannot be accessed: {path}") from exc

server/config.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+V6_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_ARTIFACT_REPO = "sida/ica-lens-paper"
+DEFAULT_DB_REPO = "sida/ica-lens-paper"
+DEFAULT_DB_FILENAME = "ica_probe_mini.sqlite"
+DEFAULT_MODEL_ID = "openai-community/gpt2"
+DEFAULT_MODEL_NAME = "gpt2"
+DEFAULT_MODEL_REGISTRY = {
+    "gpt2": {"model_id": "openai-community/gpt2", "display_name": "GPT-2", "context_length": 1024, "dtype": "bfloat16", "dataset_path": "NeelNanda/pile-10k", "dataset_name": "", "dataset_split": "train", "dataset_text_column": "text", "dataset_streaming": False},
+    "gemma2_2b": {"model_id": "google/gemma-2-2b", "display_name": "Gemma 2 2B", "context_length": 1024, "dtype": "bfloat16", "dataset_path": "NeelNanda/pile-10k", "dataset_name": "", "dataset_split": "train", "dataset_text_column": "text", "dataset_streaming": False},
+    "qwen3_5_2b_base": {"model_id": "Qwen/Qwen3.5-2B-Base", "display_name": "Qwen3.5 2B Base", "context_length": 1024, "dtype": "bfloat16", "dataset_path": "NeelNanda/pile-10k", "dataset_name": "", "dataset_split": "train", "dataset_text_column": "text", "dataset_streaming": False},
+}
+
+
+@dataclass(frozen=True)
+class ModelSettings:
+    model_name: str
+    model_id: str
+    display_name: str
+    ica_dir: Path
+    context_length: int
+    dtype: str
+    dataset_path: str
+    dataset_name: str | None
+    dataset_split: str
+    dataset_text_column: str
+    dataset_streaming: bool
+
+
+@dataclass(frozen=True)
+class Settings:
+    db_path: Path
+    ica_dir: Path
+    ica_root: Path
+    artifact_repo: str
+    db_repo: str
+    hf_revision: str | None
+    model_id: str
+    model_name: str
+    device: str
+    dtype: str
+    context_length: int
+    download_missing: bool
+    models: dict[str, ModelSettings]
+    use_gpt2_layer11_patch: bool = False
+
+
+def load_settings() -> Settings:
+    fetched_root = V6_ROOT / "artifacts" / "fetched"
+    db_path = Path(os.environ.get("ICA_EXPLORER_DB_PATH", str(fetched_root / "databases" / DEFAULT_DB_FILENAME))).expanduser()
+    ica_root = Path(os.environ.get("ICA_EXPLORER_ICA_ROOT", str(fetched_root / "models"))).expanduser()
+    ica_dir = Path(os.environ.get("ICA_EXPLORER_ICA_DIR", str(ica_root / DEFAULT_MODEL_NAME))).expanduser()
+    enabled_models = _enabled_model_names()
+    models = {
+        model_name: ModelSettings(
+            model_name=model_name,
+            model_id=str(meta["model_id"]),
+            display_name=str(meta["display_name"]),
+            ica_dir=ica_root / model_name,
+            context_length=int(meta["context_length"]),
+            dtype=str(meta["dtype"]),
+            dataset_path=str(meta["dataset_path"]),
+            dataset_name=str(meta["dataset_name"]) or None,
+            dataset_split=str(meta["dataset_split"]),
+            dataset_text_column=str(meta["dataset_text_column"]),
+            dataset_streaming=bool(meta["dataset_streaming"]),
+        )
+        for model_name, meta in DEFAULT_MODEL_REGISTRY.items()
+        if model_name in enabled_models
+    }
+    if os.environ.get("ICA_EXPLORER_ICA_DIR"):
+        default = models[DEFAULT_MODEL_NAME]
+        models[DEFAULT_MODEL_NAME] = ModelSettings(
+            model_name=default.model_name,
+            model_id=default.model_id,
+            display_name=default.display_name,
+            ica_dir=ica_dir,
+            context_length=default.context_length,
+            dtype=default.dtype,
+            dataset_path=default.dataset_path,
+            dataset_name=default.dataset_name,
+            dataset_split=default.dataset_split,
+            dataset_text_column=default.dataset_text_column,
+            dataset_streaming=default.dataset_streaming,
+        )
+    return Settings(
+        db_path=db_path,
+        ica_dir=ica_dir,
+        ica_root=ica_root,
+        artifact_repo=os.environ.get("ICA_EXPLORER_ARTIFACT_REPO", DEFAULT_ARTIFACT_REPO),
+        db_repo=os.environ.get("ICA_EXPLORER_DB_REPO", DEFAULT_DB_REPO),
+        hf_revision=os.environ.get("ICA_EXPLORER_HF_REVISION") or None,
+        model_id=os.environ.get("ICA_EXPLORER_MODEL_ID", DEFAULT_MODEL_ID),
+        model_name=os.environ.get("ICA_EXPLORER_MODEL_NAME", DEFAULT_MODEL_NAME),
+        device=os.environ.get("ICA_EXPLORER_DEVICE", "auto"),
+        dtype=os.environ.get("ICA_EXPLORER_DTYPE", "bfloat16"),
+        context_length=int(os.environ.get("ICA_EXPLORER_CONTEXT_LENGTH", "1024")),
+        download_missing=os.environ.get("ICA_EXPLORER_DOWNLOAD_MISSING", "1").strip().lower() not in {"0", "false", "no"},
+        models=models,
+    )
+
+
+def _enabled_model_names() -> set[str]:
+    raw = os.environ.get("ICA_EXPLORER_ENABLED_MODELS")
+    if not raw:
+        return set(DEFAULT_MODEL_REGISTRY)
+    names = {name.strip() for name in raw.split(",") if name.strip()}
+    unknown = names - set(DEFAULT_MODEL_REGISTRY)
+    if unknown:
+        raise ValueError(f"Unknown ICA_EXPLORER_ENABLED_MODELS value(s): {', '.join(sorted(unknown))}")
+    if not names:
+        raise ValueError("ICA_EXPLORER_ENABLED_MODELS did not contain any model names.")
+    return names

server/model_runtime.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Any
+
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+
+def torch_dtype(name: str) -> torch.dtype:
+    aliases = {
+        "float16": torch.float16,
+        "fp16": torch.float16,
+        "bfloat16": torch.bfloat16,
+        "bf16": torch.bfloat16,
+        "float32": torch.float32,
+        "fp32": torch.float32,
+    }
+    try:
+        return aliases[name.lower()]
+    except KeyError as exc:
+        raise ValueError(f"Unsupported torch dtype {name!r}") from exc
+
+
+def resolve_device(requested: str) -> torch.device:
+    if requested == "auto":
+        return torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    if requested.startswith("cuda") and not torch.cuda.is_available():
+        raise RuntimeError("CUDA was requested but torch.cuda.is_available() is false.")
+    return torch.device(requested)
+
+
+@lru_cache(maxsize=None)
+def load_tokenizer(model_id: str) -> Any:
+    tokenizer = AutoTokenizer.from_pretrained(model_id)
+    ensure_pad_token(tokenizer)
+    return tokenizer
+
+
+def load_model_and_tokenizer(model_id: str, *, device: str, dtype: str) -> tuple[torch.nn.Module, Any]:
+    torch_device = resolve_device(device)
+    tokenizer = load_tokenizer(model_id)
+
+    model_dtype = torch_dtype(dtype)
+    if torch_device.type == "cpu" and model_dtype in {torch.float16, torch.bfloat16}:
+        model_dtype = torch.float32
+
+    model = AutoModelForCausalLM.from_pretrained(
+        model_id,
+        torch_dtype=model_dtype,
+        low_cpu_mem_usage=True,
+    )
+    model.to(torch_device)
+    model.eval()
+    return model, tokenizer
+
+
+def ensure_pad_token(tokenizer: Any) -> None:
+    if tokenizer.pad_token_id is None:
+        if tokenizer.eos_token_id is None:
+            raise ValueError("Tokenizer has neither pad_token_id nor eos_token_id.")
+        tokenizer.pad_token = tokenizer.eos_token

server/probe.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+from collections.abc import Collection
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import torch
+
+
+def list_ica_layer_keys(ica_dir: Path) -> list[str]:
+    if not ica_dir.is_dir():
+        return []
+    layers = [path.name[: -len("_fastica.pt")] for path in ica_dir.glob("*_fastica.pt")]
+    return sorted(layers, key=_layer_sort_key)
+
+
+def fastica_artifact_path(ica_dir: Path, layer: str) -> Path:
+    return ica_dir / f"{layer}_fastica.pt"
+
+
+def interpret_text_probe(
+    *,
+    model: torch.nn.Module,
+    tokenizer: Any,
+    text: str,
+    layer: str,
+    ica_artifact_path: Path,
+    top_k: int,
+    highlight_components: Collection[int] | None,
+    max_length: int,
+    raw_gpt2_block_index: int | None = None,
+) -> dict[str, Any]:
+    num_transformer_layers = int(model.config.num_hidden_layers)
+    hidden_index = _layer_key_to_hidden_index(layer, num_transformer_layers=num_transformer_layers)
+    show_predictions = layer == f"layer_{num_transformer_layers - 1:02d}"
+    full_ids = tokenizer.encode(text, add_special_tokens=True)
+    truncated = len(full_ids) > max_length
+    encoded = tokenizer(text, return_tensors="pt", truncation=True, max_length=max_length)
+    input_ids = encoded["input_ids"].to(next(model.parameters()).device)
+    attention_mask = encoded.get("attention_mask")
+    if attention_mask is not None:
+        attention_mask = attention_mask.to(input_ids.device)
+
+    predictions: list[dict[str, Any]] | None = None
+    with torch.inference_mode():
+        if layer == "embedding":
+            hidden = model.get_input_embeddings()(input_ids)[0]
+        elif raw_gpt2_block_index is not None:
+            captured: dict[str, torch.Tensor] = {}
+            blocks = getattr(getattr(model, "transformer", None), "h", None)
+            if blocks is None:
+                raise RuntimeError("raw_gpt2_block_index requires a GPT-2 style model.transformer.h module list.")
+
+            def hook(_module: Any, _inputs: Any, output: Any) -> None:
+                captured["hidden"] = output[0].detach() if isinstance(output, tuple) else output.detach()
+
+            handle = blocks[int(raw_gpt2_block_index)].register_forward_hook(hook)
+            try:
+                outputs = model(
+                    input_ids=input_ids,
+                    attention_mask=attention_mask,
+                    use_cache=False,
+                )
+            finally:
+                handle.remove()
+            captured_hidden = captured.get("hidden")
+            if captured_hidden is None:
+                raise RuntimeError("GPT-2 raw block hook did not capture hidden states.")
+            hidden = captured_hidden[0]
+            if show_predictions:
+                pred_ids = torch.argmax(outputs.logits[0], dim=-1).detach().cpu().tolist()
+                predictions = [
+                    {
+                        "token_id": int(pred_id),
+                        "token": tokenizer.convert_ids_to_tokens(int(pred_id)),
+                        "token_text": _decode_token_text(tokenizer, int(pred_id)),
+                    }
+                    for pred_id in pred_ids
+                ]
+        else:
+            outputs = model(
+                input_ids=input_ids,
+                attention_mask=attention_mask,
+                output_hidden_states=True,
+                use_cache=False,
+            )
+            hidden_states = outputs.hidden_states
+            if hidden_states is None:
+                raise RuntimeError("Model did not return hidden states.")
+            hidden = hidden_states[hidden_index][0]
+            if show_predictions:
+                pred_ids = torch.argmax(outputs.logits[0], dim=-1).detach().cpu().tolist()
+                predictions = [
+                    {
+                        "token_id": int(pred_id),
+                        "token": tokenizer.convert_ids_to_tokens(int(pred_id)),
+                        "token_text": _decode_token_text(tokenizer, int(pred_id)),
+                    }
+                    for pred_id in pred_ids
+                ]
+
+    artifact = _load_fastica_artifact(ica_artifact_path)
+    scores = _all_source_scores(hidden, **artifact)
+    idx, vals = _topk_components_per_token(scores, top_k=top_k)
+    forced = sorted({int(component) for component in (highlight_components or [])})
+    out_of_range = [component for component in forced if component < 0 or component >= int(scores.shape[1])]
+    if out_of_range:
+        raise ValueError(f"highlight component out of range: {out_of_range[0]}")
+
+    ids = input_ids[0].detach().cpu().tolist()
+    idx_cpu = idx.detach().cpu().tolist()
+    vals_cpu = vals.detach().cpu().tolist()
+    forced_scores = scores[:, forced].detach().cpu().tolist() if forced else []
+
+    tokens = []
+    for pos, token_id in enumerate(ids):
+        top = [
+            {"component": int(idx_cpu[pos][j]), "score": float(vals_cpu[pos][j])}
+            for j in range(len(idx_cpu[pos]))
+        ]
+        seen = {item["component"] for item in top}
+        for j, component in enumerate(forced):
+            if component not in seen:
+                top.append({"component": component, "score": float(forced_scores[pos][j]), "highlighted": True})
+        token_item = {
+            "position": pos,
+            "token_id": int(token_id),
+            "token": tokenizer.convert_ids_to_tokens(int(token_id)),
+            "token_text": _decode_token_text(tokenizer, int(token_id)),
+            "top": top,
+        }
+        if predictions is not None:
+            token_item["prediction"] = predictions[pos]
+        tokens.append(token_item)
+
+    return {
+        "layer": layer,
+        "top_k": int(top_k),
+        "max_length": int(max_length),
+        "tokens": tokens,
+        "seq_len": len(tokens),
+        "truncated": truncated,
+        "n_components": int(scores.shape[1]),
+        "predictions_available": predictions is not None,
+    }
+
+
+@lru_cache(maxsize=None)
+def _load_fastica_artifact(path: Path) -> dict[str, torch.Tensor | float]:
+    blob = torch.load(path, map_location="cpu")
+    tensors = blob["tensors"]
+    meta = blob.get("metadata") or {}
+    mean = tensors["mean"].to(torch.float32)
+    if mean.dim() == 1:
+        mean = mean.unsqueeze(0)
+    return {
+        "mean": mean,
+        "components": tensors["components"].to(torch.float32),
+        "norm_eps": float(meta.get("norm_eps", 1e-12)),
+    }
+
+
+def _all_source_scores(
+    activations: torch.Tensor,
+    *,
+    mean: torch.Tensor,
+    components: torch.Tensor,
+    norm_eps: float,
+) -> torch.Tensor:
+    x = activations.to(dtype=torch.float32)
+    normalized = x / torch.linalg.vector_norm(x, dim=1, keepdim=True).clamp_min(norm_eps)
+    return (normalized - mean.to(x.device)) @ components.to(x.device).T
+
+
+def _topk_components_per_token(scores: torch.Tensor, *, top_k: int) -> tuple[torch.Tensor, torch.Tensor]:
+    k = min(int(top_k), int(scores.shape[1]))
+    if k <= 0:
+        raise ValueError("top_k must be positive.")
+    idx = torch.topk(scores.abs(), k, dim=1).indices
+    row_idx = torch.arange(scores.shape[0], device=scores.device, dtype=torch.long).unsqueeze(1).expand_as(idx)
+    return idx, scores[row_idx, idx]
+
+
+def _layer_key_to_hidden_index(layer: str, *, num_transformer_layers: int) -> int:
+    if layer == "embedding":
+        return 0
+    if not layer.startswith("layer_"):
+        raise ValueError(f"Unknown layer key: {layer!r}")
+    idx = int(layer.split("_", maxsplit=1)[1])
+    if idx < 0 or idx >= num_transformer_layers:
+        raise ValueError(f"Layer index out of range: {layer!r}")
+    return idx + 1
+
+
+def _layer_sort_key(layer: str) -> tuple[int, int | str]:
+    if layer == "embedding":
+        return (0, 0)
+    if layer.startswith("layer_"):
+        return (1, int(layer.removeprefix("layer_")))
+    return (2, layer)
+
+
+def _decode_token_text(tokenizer: Any, token_id: int) -> str:
+    try:
+        decoded = str(tokenizer.decode([token_id], skip_special_tokens=False, clean_up_tokenization_spaces=False))
+    except Exception:
+        decoded = ""
+    raw_token = str(tokenizer.convert_ids_to_tokens(token_id))
+    if "\ufffd" in decoded:
+        byte_text = _decode_byte_level_token(raw_token)
+        if byte_text is not None:
+            return byte_text
+    return decoded or raw_token
+
+
+def _decode_byte_level_token(token: str) -> str | None:
+    byte_decoder = _gpt2_byte_decoder()
+    try:
+        raw = bytes(byte_decoder[ch] for ch in token)
+    except KeyError:
+        return None
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return "".join(f"\\x{byte:02X}" for byte in raw)
+
+
+def _gpt2_byte_decoder() -> dict[str, int]:
+    bs = (
+        list(range(ord("!"), ord("~") + 1))
+        + list(range(ord("¡"), ord("¬") + 1))
+        + list(range(ord("®"), ord("ÿ") + 1))
+    )
+    cs = bs[:]
+    n = 0
+    for byte in range(256):
+        if byte not in bs:
+            bs.append(byte)
+            cs.append(256 + n)
+            n += 1
+    return {chr(char): byte for byte, char in zip(bs, cs, strict=True)}

server/sae_probe.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import tomllib
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+from huggingface_hub import hf_hub_download
+from safetensors.torch import load_file
+
+from .probe import _decode_token_text, _layer_key_to_hidden_index
+
+
+V6_ROOT = Path(__file__).resolve().parents[1]
+CONFIG_ROOT = V6_ROOT / "configs" / "comparisons"
+
+
+def list_sae_layers(model_name: str) -> list[str]:
+    config = load_sae_config(model_name)
+    model_config = load_comparison_config(model_name).get("model", {})
+    n_layers = int(model_config.get("num_hidden_layers") or 0)
+    layer_checkpoints = config.get("layer_checkpoints")
+    if isinstance(layer_checkpoints, dict) and layer_checkpoints:
+        indices = sorted(int(key) for key in layer_checkpoints)
+    else:
+        indices = list(range(n_layers))
+    return [f"layer_{idx:02d}" for idx in indices]
+
+
+def load_comparison_config(model_name: str) -> dict[str, Any]:
+    path = CONFIG_ROOT / f"{model_name}.toml"
+    if not path.is_file():
+        raise FileNotFoundError(f"No SAE comparison config for {model_name!r}: {path}")
+    return tomllib.loads(path.read_text(encoding="utf-8"))
+
+
+def load_sae_config(model_name: str) -> dict[str, Any]:
+    data = load_comparison_config(model_name)
+    if "sae" not in data:
+        raise KeyError(f"Comparison config for {model_name!r} has no [sae] section.")
+    return dict(data["sae"])
+
+
+def interpret_text_sae_probe(
+    *,
+    model: torch.nn.Module,
+    tokenizer: Any,
+    text: str,
+    model_name: str,
+    layer: str,
+    top_k: int,
+    max_length: int,
+) -> dict[str, Any]:
+    if layer == "embedding":
+        raise ValueError("SAE Explorer currently supports transformer layers, not embedding.")
+    layer_index = int(layer.removeprefix("layer_"))
+    hidden_index = _layer_key_to_hidden_index(layer, num_transformer_layers=int(model.config.num_hidden_layers))
+    full_ids = tokenizer.encode(text, add_special_tokens=True)
+    truncated = len(full_ids) > max_length
+    encoded = tokenizer(text, return_tensors="pt", truncation=True, max_length=max_length)
+    input_ids = encoded["input_ids"].to(next(model.parameters()).device)
+    attention_mask = encoded.get("attention_mask")
+    if attention_mask is not None:
+        attention_mask = attention_mask.to(input_ids.device)
+
+    with torch.inference_mode():
+        outputs = model(
+            input_ids=input_ids,
+            attention_mask=attention_mask,
+            output_hidden_states=True,
+            use_cache=False,
+        )
+        hidden_states = outputs.hidden_states
+        if hidden_states is None:
+            raise RuntimeError("Model did not return hidden states.")
+        hidden = hidden_states[hidden_index][0].to(dtype=torch.float32)
+        sae = load_sae(model_name, layer_index, hidden_size=int(hidden.shape[-1]), device=hidden.device)
+        pre, acts = sae_forward(hidden, sae=sae)
+        idx, vals = topk_features(acts, top_k=top_k)
+
+    ids = input_ids[0].detach().cpu().tolist()
+    idx_cpu = idx.detach().cpu().tolist()
+    vals_cpu = vals.detach().cpu().tolist()
+    pre_cpu = pre.detach().cpu()
+    tokens = []
+    for pos, token_id in enumerate(ids):
+        top = []
+        for j in range(len(idx_cpu[pos])):
+            feature = int(idx_cpu[pos][j])
+            top.append(
+                {
+                    "feature": feature,
+                    "activation": float(vals_cpu[pos][j]),
+                    "preactivation": float(pre_cpu[pos, feature].item()),
+                }
+            )
+        tokens.append(
+            {
+                "position": pos,
+                "token_id": int(token_id),
+                "token": tokenizer.convert_ids_to_tokens(int(token_id)),
+                "token_text": _decode_token_text(tokenizer, int(token_id)),
+                "top": top,
+            }
+        )
+    return {
+        "model_name": model_name,
+        "layer": layer,
+        "top_k": int(top_k),
+        "max_length": int(max_length),
+        "tokens": tokens,
+        "seq_len": len(tokens),
+        "truncated": truncated,
+        "sae_width": int(sae["w_enc"].shape[1]),
+        "activation_rule": sae["activation_rule"],
+    }
+
+
+@lru_cache(maxsize=64)
+def _load_sae_cpu(model_name: str, layer: int, hidden_size: int) -> dict[str, Any]:
+    config = load_sae_config(model_name)
+    path = _resolve_sae_weights_path(config, layer=layer)
+    weights = _load_sae_weights(path, config=config)
+    w_dec = _decoder_weight(weights, hidden_size=hidden_size, preferred_key=config.get("decoder_key")).to(dtype=torch.float32)
+    w_enc = _encoder_weight(weights, hidden_size=hidden_size, d_sae=int(w_dec.shape[0])).to(dtype=torch.float32).contiguous()
+    b_enc = _vector_weight(weights, names=("b_enc", "encoder.bias"), length=int(w_enc.shape[1]))
+    b_dec = _vector_weight(weights, names=("b_dec", "decoder.bias", "bias"), length=hidden_size)
+    threshold = weights.get("threshold")
+    return {
+        "w_enc": w_enc,
+        "b_enc": b_enc.to(dtype=torch.float32).contiguous(),
+        "b_dec": b_dec.to(dtype=torch.float32).contiguous(),
+        "threshold": threshold.to(dtype=torch.float32).contiguous() if threshold is not None else None,
+        "top_k": _sae_top_k(config),
+        "activation_rule": _activation_rule_label(config),
+    }
+
+
+def load_sae(model_name: str, layer: int, *, hidden_size: int, device: torch.device) -> dict[str, Any]:
+    cpu = _load_sae_cpu(model_name, layer, hidden_size)
+    return {
+        key: value.to(device=device, dtype=torch.float32, non_blocking=True) if isinstance(value, torch.Tensor) else value
+        for key, value in cpu.items()
+    }
+
+
+def sae_forward(hidden: torch.Tensor, *, sae: dict[str, Any]) -> tuple[torch.Tensor, torch.Tensor]:
+    centered = hidden.to(dtype=torch.float32) - sae["b_dec"].unsqueeze(0)
+    pre = centered @ sae["w_enc"] + sae["b_enc"].unsqueeze(0)
+    threshold = sae["threshold"]
+    if threshold is not None:
+        return pre, torch.where(pre > threshold.unsqueeze(0), pre, torch.zeros_like(pre))
+    top_k = sae["top_k"]
+    if top_k is not None:
+        k = min(int(top_k), int(pre.shape[1]))
+        values, indices = torch.topk(pre, k=k, dim=1)
+        acts = torch.zeros_like(pre)
+        acts.scatter_(1, indices, torch.clamp(values, min=0.0))
+        return pre, acts
+    return pre, torch.relu(pre)
+
+
+def topk_features(acts: torch.Tensor, *, top_k: int) -> tuple[torch.Tensor, torch.Tensor]:
+    k = min(int(top_k), int(acts.shape[1]))
+    if k <= 0:
+        raise ValueError("top_k must be positive.")
+    vals, idx = torch.topk(acts, k=k, dim=1)
+    return idx, vals
+
+
+def _resolve_sae_weights_path(config: dict[str, Any], *, layer: int) -> str:
+    layer_checkpoints = config.get("layer_checkpoints")
+    if isinstance(layer_checkpoints, dict) and str(layer) in layer_checkpoints:
+        filename = str(layer_checkpoints[str(layer)])
+    else:
+        filename = str(config["checkpoint_template"]).format(layer=layer)
+    return hf_hub_download(repo_id=str(config["repo_id"]), filename=filename, revision=config.get("revision"))
+
+
+def _load_sae_weights(path: str, *, config: dict[str, Any]) -> dict[str, torch.Tensor]:
+    checkpoint_format = str(config.get("checkpoint_format", "")).lower()
+    if checkpoint_format == "safetensors":
+        return load_file(path, device="cpu")
+    if checkpoint_format == "npz":
+        with np.load(path) as arrays:
+            return {key: torch.from_numpy(arrays[key]) for key in arrays.files}
+    if checkpoint_format in {"torch", "pt", "pth"}:
+        try:
+            loaded = torch.load(path, map_location="cpu", weights_only=True)
+        except TypeError:
+            loaded = torch.load(path, map_location="cpu")
+        if not isinstance(loaded, dict):
+            raise TypeError(f"Expected torch checkpoint {path} to contain a dict, got {type(loaded).__name__}.")
+        return _flatten_tensor_dict(loaded)
+    raise ValueError(f"Unsupported SAE checkpoint_format {checkpoint_format!r}.")
+
+
+def _flatten_tensor_dict(payload: dict[str, Any], prefix: str = "") -> dict[str, torch.Tensor]:
+    flattened: dict[str, torch.Tensor] = {}
+    for key, value in payload.items():
+        name = f"{prefix}.{key}" if prefix else str(key)
+        if isinstance(value, torch.Tensor):
+            flattened[name] = value
+            flattened[str(key)] = value
+        elif isinstance(value, dict):
+            flattened.update(_flatten_tensor_dict(value, name))
+    return flattened
+
+
+def _encoder_weight(weights: dict[str, torch.Tensor], *, hidden_size: int, d_sae: int) -> torch.Tensor:
+    for key in ("W_enc", "encoder.weight", "W_enc.weight", "encoder.W_enc"):
+        tensor = weights.get(key)
+        if tensor is not None:
+            return _orient_encoder(tensor, hidden_size=hidden_size, d_sae=d_sae)
+    return _decoder_weight(weights, hidden_size=hidden_size).T.contiguous()
+
+
+def _decoder_weight(
+    weights: dict[str, torch.Tensor],
+    *,
+    hidden_size: int,
+    preferred_key: object = None,
+) -> torch.Tensor:
+    if preferred_key is not None:
+        key = str(preferred_key)
+        if key not in weights:
+            raise KeyError(f"Configured decoder_key {key!r} not found. Available keys: {sorted(weights)}")
+        return _orient_decoder(weights[key], hidden_size=hidden_size)
+    for key in ("W_dec", "decoder.weight", "W_dec.weight", "decoder.W_dec"):
+        tensor = weights.get(key)
+        if tensor is not None:
+            return _orient_decoder(tensor, hidden_size=hidden_size)
+    candidates = [tensor for tensor in weights.values() if tensor.ndim == 2 and hidden_size in tensor.shape]
+    if len(candidates) == 1:
+        return _orient_decoder(candidates[0], hidden_size=hidden_size)
+    raise KeyError(f"Could not identify SAE decoder weight. Available keys: {sorted(weights)}")
+
+
+def _vector_weight(weights: dict[str, torch.Tensor], *, names: tuple[str, ...], length: int) -> torch.Tensor:
+    for name in names:
+        tensor = weights.get(name)
+        if tensor is not None:
+            if int(tensor.numel()) != int(length):
+                raise ValueError(f"SAE vector {name!r} has length {tensor.numel()}, expected {length}.")
+            return tensor.reshape(length).to(dtype=torch.float32)
+    return torch.zeros(length, dtype=torch.float32)
+
+
+def _orient_decoder(tensor: torch.Tensor, *, hidden_size: int) -> torch.Tensor:
+    if int(tensor.shape[1]) == hidden_size:
+        return tensor
+    if int(tensor.shape[0]) == hidden_size:
+        return tensor.T
+    raise ValueError(f"Decoder weight shape {tuple(tensor.shape)} does not contain hidden size {hidden_size}.")
+
+
+def _orient_encoder(tensor: torch.Tensor, *, hidden_size: int, d_sae: int) -> torch.Tensor:
+    if tuple(tensor.shape) == (hidden_size, d_sae):
+        return tensor
+    if tuple(tensor.shape) == (d_sae, hidden_size):
+        return tensor.T
+    if int(tensor.shape[0]) == hidden_size:
+        return tensor
+    if int(tensor.shape[1]) == hidden_size:
+        return tensor.T
+    raise ValueError(f"Encoder weight shape {tuple(tensor.shape)} does not match hidden={hidden_size}, d_sae={d_sae}.")
+
+
+def _sae_top_k(config: dict[str, Any]) -> int | None:
+    if config.get("top_k") is not None:
+        return int(config["top_k"])
+    repo = str(config.get("repo_id") or "")
+    if "GPT2-Small-OAI-v5-32k-resid-post-SAEs" in repo:
+        return 32
+    return None
+
+
+def _activation_rule_label(config: dict[str, Any]) -> str:
+    if config.get("top_k") is not None:
+        return f"topk-{int(config['top_k'])}"
+    if str(config.get("activation") or "").lower() == "topk":
+        return "topk"
+    return "relu_or_threshold"

server/static/annotate.html

@@ -0,0 +1,220 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>ICA Annotator</title>
+  <style>
+    :root { --bg:#f8fafc; --panel:#fff; --subtle:#f1f5f9; --text:#0f172a; --muted:#64748b; --border:#cbd5e1; --accent:#2563eb; --good:#059669; --bad:#dc2626; --shadow:0 1px 2px rgb(15 23 42 / .08),0 8px 24px rgb(15 23 42 / .05); }
+    * { box-sizing:border-box; }
+    body { margin:0; background:var(--bg); color:var(--text); font:14px/1.45 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif; }
+    header { position:sticky; top:0; z-index:5; background:#fff; border-bottom:1px solid var(--border); padding:12px 16px; box-shadow:var(--shadow); }
+    .top { display:flex; justify-content:space-between; align-items:center; gap:12px; flex-wrap:wrap; }
+    h1 { margin:0; font-size:20px; }
+    nav { display:flex; gap:6px; }
+    nav a { color:var(--muted); text-decoration:none; padding:7px 10px; border-radius:7px; font-weight:650; }
+    nav a:hover, nav a.active { color:var(--accent); background:#eff6ff; }
+    .toolbar { display:flex; align-items:end; flex-wrap:wrap; gap:10px; margin-top:10px; }
+    label { color:#475569; font-size:12px; font-weight:700; }
+    select,input,textarea,button { font:inherit; border:1px solid var(--border); border-radius:7px; padding:7px 9px; background:#fff; color:var(--text); }
+    textarea { width:100%; resize:vertical; }
+    button { cursor:pointer; background:var(--subtle); }
+    button:hover { color:var(--accent); border-color:var(--accent); background:#eff6ff; }
+    .primary { color:#fff; background:var(--accent); border-color:#1d4ed8; font-weight:800; }
+    .primary:hover { color:#fff; background:#1d4ed8; }
+    main { display:grid; grid-template-columns:320px minmax(0,1fr) 360px; gap:14px; padding:14px; }
+    aside,.panel { background:var(--panel); border:1px solid var(--border); border-radius:8px; box-shadow:var(--shadow); }
+    aside { max-height:calc(100vh - 108px); overflow:auto; padding:10px; position:sticky; top:94px; }
+    .panel { padding:12px; }
+    .panel-title-row { display:flex; align-items:center; justify-content:space-between; gap:10px; margin-bottom:10px; }
+    .panel-title-row h2 { margin:0; }
+    .component-metrics { display:flex; flex-wrap:wrap; gap:6px; justify-content:flex-end; }
+    .metric-badge { display:inline-flex; align-items:center; min-height:24px; border:1px solid var(--border); border-radius:999px; padding:2px 8px; background:#f8fafc; color:#475569; font-size:12px; font-weight:800; font-variant-numeric:tabular-nums; }
+    .component-list { display:flex; flex-direction:column; gap:7px; margin-top:10px; }
+    .component-button { text-align:left; background:#fff; width:100%; border-radius:7px; }
+    .component-button.active { border-color:var(--accent); box-shadow:inset 3px 0 0 var(--accent); }
+    .component-title { display:flex; justify-content:space-between; gap:8px; font-weight:800; }
+    .label-line { color:#334155; margin-top:4px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+    .muted { color:var(--muted); }
+    .pill { display:inline-flex; border:1px solid var(--border); border-radius:999px; padding:1px 7px; color:var(--muted); font-size:12px; }
+    .examples { display:grid; grid-template-columns:repeat(auto-fit,minmax(310px,1fr)); gap:10px; }
+    .example { border:1px solid #e2e8f0; border-radius:8px; padding:10px; background:#fff; }
+    .example-head { display:flex; justify-content:space-between; gap:8px; color:var(--muted); font-size:12px; margin-bottom:8px; }
+    .example-meta { display:flex; flex-wrap:wrap; align-items:center; gap:6px; min-width:0; }
+    .doc-link { color:#2563eb; text-decoration:none; font-weight:800; }
+    .doc-link:hover { text-decoration:underline; }
+    .score { font-weight:850; color:#b91c1c; font-variant-numeric:tabular-nums; }
+    .score.neg { color:#1d4ed8; }
+    .token { background:#fee2e2; color:#7f1d1d; border-radius:5px; padding:1px 5px; font-weight:800; }
+    pre { white-space:pre-wrap; font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; margin:8px 0 0; }
+    .context { margin:8px 0 0; white-space:pre-wrap; font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; font-size:14px; line-height:1.45; }
+    .context-token { border-radius:3px; padding:0 1px; }
+    .context-token.target { outline:1px solid rgb(15 23 42 / .28); outline-offset:1px; }
+    .tabs { display:flex; flex-wrap:wrap; gap:7px; margin:10px 0; }
+    .tabs button.active { color:#fff; background:var(--accent); border-color:var(--accent); }
+    .editor { position:sticky; top:94px; max-height:calc(100vh - 108px); overflow:auto; }
+    .editor h2,.panel h2 { margin:0 0 10px; font-size:16px; }
+    .neighbor-row { display:grid; grid-template-columns:1fr 1fr; gap:8px; margin-bottom:12px; }
+    .neighbor-card { display:grid; gap:4px; min-height:68px; border:1px solid var(--border); border-radius:8px; padding:8px; background:#fff; color:var(--text); text-decoration:none; }
+    .neighbor-card:hover { border-color:var(--accent); color:var(--text); text-decoration:none; background:#eff6ff; }
+    .neighbor-card.missing { visibility:hidden; }
+    .neighbor-head { display:flex; justify-content:space-between; align-items:start; gap:8px; }
+    .neighbor-target { min-width:0; overflow:hidden; white-space:nowrap; text-overflow:ellipsis; color:var(--muted); font-size:11px; font-weight:750; }
+    .neighbor-link { min-width:0; color:var(--muted); text-decoration:none; }
+    .neighbor-link:hover { color:var(--accent); text-decoration:underline; }
+    .neighbor-copy { width:auto; min-height:24px; padding:2px 7px; border-radius:6px; font-size:11px; font-weight:800; white-space:nowrap; }
+    .neighbor-label { min-width:0; overflow:hidden; white-space:nowrap; text-overflow:ellipsis; color:var(--text); font-size:14px; font-weight:850; line-height:1.2; }
+    .neighbor-metrics { color:var(--muted); font-size:11px; font-weight:500; font-variant-numeric:tabular-nums; }
+    .neighbor-cos { min-height:20px; border:1px solid #d7dee9; border-radius:5px; padding:2px 6px; background:linear-gradient(90deg,rgb(37 99 235 / .14) 0,rgb(37 99 235 / .14) var(--cos-width,0%),transparent var(--cos-width,0%),transparent 100%); color:var(--muted); font-size:12px; font-weight:800; font-variant-numeric:tabular-nums; }
+    .field { margin-bottom:10px; }
+    .direction-block { border:1px solid #e2e8f0; border-left-width:4px; border-radius:8px; padding:10px; margin-bottom:10px; }
+    .direction-block.positive { border-left-color:#e2e8f0; }
+    .direction-block.negative { border-left-color:#e2e8f0; }
+    .direction-block.positive.active-direction { border-left-color:#dc2626; background:#fef2f2; }
+    .direction-block.negative.active-direction { border-left-color:#2563eb; background:#eff6ff; }
+    .direction-block h3 { margin:0 0 9px; font-size:14px; }
+    .field-grid { display:grid; grid-template-columns:1fr 1fr; gap:8px; margin-top:8px; }
+    .field-grid select { width:100%; min-width:0; }
+    .label-confidence-high { border-color:#16a34a; box-shadow:0 0 0 2px rgb(22 163 74 / .12); }
+    .label-confidence-high:focus { border-color:#16a34a; outline:2px solid rgb(22 163 74 / .22); outline-offset:1px; box-shadow:0 0 0 2px rgb(22 163 74 / .12); }
+    .label-confidence-medium { border-color:#d9b94e; box-shadow:0 0 0 2px rgb(217 185 78 / .16); }
+    .label-confidence-medium:focus { border-color:#d9b94e; outline:2px solid rgb(217 185 78 / .25); outline-offset:1px; box-shadow:0 0 0 2px rgb(217 185 78 / .16); }
+    .label-confidence-low { border-color:#f9a8d4; box-shadow:0 0 0 2px rgb(249 168 212 / .18); }
+    .label-confidence-low:focus { border-color:#f9a8d4; outline:2px solid rgb(249 168 212 / .28); outline-offset:1px; box-shadow:0 0 0 2px rgb(249 168 212 / .18); }
+    .label-confidence-unclear { border-color:#cbd5e1; box-shadow:none; }
+    .label-confidence-unclear:focus { border-color:#94a3b8; outline:2px solid rgb(148 163 184 / .28); outline-offset:1px; box-shadow:none; }
+    .status { margin-left:auto; color:var(--muted); }
+    .empty,.error { border:1px dashed var(--border); border-radius:8px; padding:18px; color:var(--muted); background:#fff; }
+    .error { color:#991b1b; border-color:#fecaca; background:#fef2f2; }
+    @media(max-width:1050px){ main{grid-template-columns:1fr;} aside,.editor{position:static;max-height:none;} }
+  </style>
+</head>
+<body>
+<header>
+  <div class="top">
+    <h1>ICA Annotator</h1>
+    <nav>
+      <a href="/">Explorer</a>
+      <a href="/sae-explorer">SAE Explorer</a>
+      <a href="/stats">Stats</a>
+      <a href="/annotate" class="active">Annotate</a>
+      <a href="/random-components">Random</a>
+    </nav>
+  </div>
+  <div class="toolbar">
+    <label>Model<br><select id="model"></select></label>
+    <label>Layer<br><select id="layer"></select></label>
+    <label style="flex:1;min-width:220px">Search<br><input id="search" type="search" placeholder="component id or label" /></label>
+    <button id="refresh">Refresh</button>
+    <span id="status" class="status"></span>
+  </div>
+</header>
+<main>
+  <aside>
+    <div class="muted" id="count">Loading...</div>
+    <div id="components" class="component-list"></div>
+  </aside>
+  <section class="panel">
+    <div class="panel-title-row">
+      <h2 id="detailTitle">Examples</h2>
+      <div id="componentMetrics" class="component-metrics"></div>
+    </div>
+    <div id="tabs" class="tabs"></div>
+    <div id="examples" class="examples"><div class="empty">Choose a component.</div></div>
+  </section>
+  <section class="panel editor">
+    <div id="neighborCards" class="neighbor-row" hidden></div>
+    <h2>Manual Annotation</h2>
+    <div id="editorEmpty" class="empty">Choose a component to annotate.</div>
+    <form id="form" hidden>
+      <div id="positiveBlock" class="direction-block positive">
+        <h3>Positive direction</h3>
+        <div class="field"><label>Label<br><textarea id="positiveLabel" rows="2"></textarea></label></div>
+        <div class="field-grid">
+          <label>Confidence<br><select id="positiveConfidence"></select></label>
+          <label>Interpretation type<br><select id="positiveTypes"></select></label>
+        </div>
+      </div>
+      <div id="negativeBlock" class="direction-block negative">
+        <h3>Negative direction</h3>
+        <div class="field"><label>Label<br><textarea id="negativeLabel" rows="2"></textarea></label></div>
+        <div class="field-grid">
+          <label>Confidence<br><select id="negativeConfidence"></select></label>
+          <label>Interpretation type<br><select id="negativeTypes"></select></label>
+        </div>
+      </div>
+      <div class="field"><label>Summary<br><textarea id="summary" rows="3"></textarea></label></div>
+      <div class="field"><label>Notes<br><textarea id="notes" rows="4"></textarea></label></div>
+      <div class="field"><label style="display:flex;gap:6px;align-items:center;color:var(--text);font-weight:600"><input id="caseStudy" type="checkbox"> include as case study</label></div>
+      <button class="primary" type="submit">Save annotation</button>
+    </form>
+  </section>
+</main>
+<script>
+const TYPES = ["Form", "Word", "Phrase", "Sentence", "Long-Range Context", "Global", "Position", "Sophisticated"];
+const CONF = ["high", "medium", "low", "unclear"];
+const state = { model:"", layer:"", components:[], selected:null, examples:null, region:"", annotation:null, neighbors:null };
+const el = Object.fromEntries(["model","layer","search","refresh","status","count","components","detailTitle","componentMetrics","tabs","examples","neighborCards","editorEmpty","form","positiveBlock","negativeBlock","positiveLabel","positiveConfidence","negativeLabel","negativeConfidence","positiveTypes","negativeTypes","summary","notes","caseStudy"].map(id=>[id,document.getElementById(id)]));
+async function api(path, options){ const r=await fetch(path, options); if(!r.ok){let msg=await r.text(); try{msg=JSON.parse(msg).detail||msg}catch{} throw new Error(msg)} return r.json(); }
+function esc(s){return String(s??"").replace(/[&<>"']/g,c=>({"&":"&amp;","<":"&lt;",">":"&gt;","\"":"&quot;","'":"&#39;"}[c]));}
+function scoreClass(v){return Number(v)<0?'score neg':'score';}
+function setStatus(s){el.status.textContent=s||"";}
+function fillSelect(select, values, current){select.innerHTML=values.map(v=>`<option value="${esc(v)}" ${v===current?'selected':''}>${esc(v)}</option>`).join('');}
+function fillConfidence(){ for(const id of ['positiveConfidence','negativeConfidence']) fillSelect(el[id], CONF, 'unclear'); }
+function fillTypes(){ for(const id of ['positiveTypes','negativeTypes']) fillSelect(el[id], ["", ...TYPES], ""); el.positiveTypes.options[0].textContent="none"; el.negativeTypes.options[0].textContent="none"; }
+function selectedTypes(select){ return select.value ? [select.value] : []; }
+function setTypes(select, values){ const first=(values||[]).find(Boolean)||""; select.value=first; }
+async function init(){ fillConfidence(); fillTypes(); const params=new URLSearchParams(location.search); state.targetComponent=Number(params.get('component')); const requestedModel=params.get('model')||'gpt2'; const requestedLayer=params.get('layer')||''; const models=await api('/api/models'); fillSelect(el.model, models.models.map(m=>m.model_name), requestedModel); state.model=el.model.value; state.layer=requestedLayer; await loadLayers({component:Number.isFinite(state.targetComponent)?state.targetComponent:null}); bind(); }
+function bind(){ el.model.onchange=async()=>{state.model=el.model.value; state.targetComponent=null; await loadLayers();}; el.layer.onchange=async()=>{state.layer=el.layer.value; state.targetComponent=null; await loadComponents();}; el.search.oninput=()=>renderComponents(); el.refresh.onclick=loadComponents; el.form.onsubmit=saveAnnotation; el.positiveConfidence.onchange=updateLabelConfidenceStyles; el.negativeConfidence.onchange=updateLabelConfidenceStyles; el.positiveBlock.onclick=()=>setActiveDirection('positive'); el.negativeBlock.onclick=()=>setActiveDirection('negative'); el.positiveBlock.onfocusin=()=>setActiveDirection('positive'); el.negativeBlock.onfocusin=()=>setActiveDirection('negative'); }
+async function loadLayers(options={}){ const out=await api(`/api/layers?model=${encodeURIComponent(state.model)}`); fillSelect(el.layer,out.layers,out.layers.includes(state.layer)?state.layer:out.layers[0]); state.layer=el.layer.value; await loadComponents(options); }
+async function loadComponents(options={}){ setStatus('Loading components...'); const out=await api(`/api/components?model=${encodeURIComponent(state.model)}&layer=${encodeURIComponent(state.layer)}`); state.components=out.components; state.selected=null; renderComponents(); clearDetail(); setStatus(''); const component=options.component; if(Number.isFinite(component) && state.components.some(c=>c.component===component)) await selectComponent(component); }
+function renderComponents(){ const q=el.search.value.trim().toLowerCase(); const items=state.components.filter(c=>!q||String(c.component).includes(q)||[c.positive_label,c.negative_label,c.summary,c.notes].join(' ').toLowerCase().includes(q)); el.count.textContent=`${items.length} components`; el.components.innerHTML=items.map(c=>`<button class="component-button ${state.selected&&state.selected.component===c.component?'active':''}" data-c="${c.component}"><div class="component-title"><span>${esc(c.layer)} / ${c.component}</span><span class="pill">k=${c.excess_kurtosis==null?'?':Number(c.excess_kurtosis).toFixed(1)}</span></div><div class="label-line">+ ${esc(c.positive_label||'')} </div><div class="label-line">- ${esc(c.negative_label||'')}</div></button>`).join('') || '<div class="empty">No components.</div>'; el.components.querySelectorAll('button[data-c]').forEach(b=>b.onclick=()=>selectComponent(Number(b.dataset.c))); }
+async function selectComponent(component){ state.selected=state.components.find(c=>c.component===component); renderComponents(); setStatus('Loading examples...'); const q=new URLSearchParams({model:state.model,layer:state.layer,component:String(component)}); const [examples, annotation, neighbors]=await Promise.all([api(`/api/examples/component?${q}`), api(`/api/annotations/component?${q}`), api(`/api/component-neighbors?${q}`)]); state.examples=examples; state.annotation=annotation; state.neighbors=neighbors; state.region=examples.default_region||examples.regions[0]||''; renderExamples(); renderEditor(); setStatus(''); }
+function clearDetail(){ el.detailTitle.textContent='Examples'; el.componentMetrics.innerHTML=''; el.tabs.innerHTML=''; el.examples.innerHTML='<div class="empty">Choose a component.</div>'; el.neighborCards.hidden=true; el.neighborCards.innerHTML=''; el.form.hidden=true; el.editorEmpty.hidden=false; setActiveDirection(null); }
+function renderExamples(){ const c=state.selected; el.detailTitle.textContent=`${state.model} ${state.layer} / ${c.component}`; renderComponentMetrics(c); el.tabs.innerHTML=(state.examples.regions||[]).map(r=>`<button class="${r===state.region?'active':''}" data-r="${esc(r)}">${esc(r)}</button>`).join(''); el.tabs.querySelectorAll('button').forEach(b=>b.onclick=()=>{state.region=b.dataset.r; renderExamples();}); const items=(state.examples.examples_by_region||{})[state.region]||[]; el.examples.innerHTML=items.map(renderExample).join('') || '<div class="empty">No examples in this band.</div>'; }
+function renderExample(x){ return `<article class="example"><div class="example-head"><span class="example-meta"><span>#${esc(x.rank)}</span>${docPositionLink(x)}<span class="token">${esc(visibleToken(x.token))}</span></span><span class="${scoreClass(x.source_score)}">${Number(x.source_score||0).toFixed(3)}</span></div><div class="context">${renderContext(x)}</div></article>`; }
+function docPositionLink(x){ if(x.doc_id==null||Number(x.doc_id)<0) return x.position==null?'':`<span>pos ${esc(x.position)}</span>`; const q=new URLSearchParams({model:state.model,doc_id:String(x.doc_id)}); if(x.position!=null) q.set('position',String(x.position)); const target=visibleToken(x.token); if(target) q.set('target',target); const text=`doc ${x.doc_id}${x.position==null?'':` · pos ${x.position}`}`; return `<a class="doc-link" href="/context?${esc(q.toString())}" target="_blank" rel="noopener" title="Open full document context">${esc(text)}</a>`; }
+function renderContext(x){ const tokens=Array.isArray(x.context_token_scores)?x.context_token_scores:[]; if(!tokens.length) return esc(x.context_to_target||x.context||''); const maxAbs=Math.max(1e-9, Number(x.context_score_max_abs||0), ...tokens.map(t=>Math.abs(Number(t.source_score||0)))); return tokens.map(t=>{ const score=Number(t.source_score||0); const alpha=tokenAlpha(score,maxAbs); const color=alpha===0?'transparent':score>0?`rgba(220,38,38,${alpha})`:`rgba(37,99,235,${alpha})`; const title=`score=${Number.isFinite(score)?score.toFixed(4):'n/a'}`; return `<span class="context-token ${t.is_target?'target':''}" style="background:${color}" title="${esc(title)}">${esc(visibleContextToken(t.token))}</span>`; }).join(''); }
+function tokenAlpha(score,maxAbs){ const magnitude=Math.abs(Number(score||0)); if(magnitude<1e-6) return 0; return Math.min(0.55,0.47*Math.log1p(magnitude)/Math.log1p(maxAbs)); }
+function visibleToken(value){ const text=String(value||''); if(text===' ') return '[space]'; if(text==='\n') return '[newline]'; if(text==='\f') return '\\f'; return text.replace(/\r/g,'\\r').replace(/\n/g,'\\n').replace(/\t/g,'\\t').replace(/\f/g,'\\f'); }
+function visibleContextToken(value){ return String(value||'').replace(/\r/g,'\\r').replace(/\n/g,'\\n').replace(/\t/g,'\\t').replace(/\f/g,'\\f'); }
+function renderComponentMetrics(component){ const parts=[]; const erf=Number(component.effective_context_mean); const k=Number(component.excess_kurtosis); if(Number.isFinite(erf)) parts.push(`<span class="metric-badge" title="Effective Receptive Field (ERF): estimated mean number of token positions in the local context that materially affect this component.">ERF=${erf.toFixed(1)}</span>`); if(Number.isFinite(k)) parts.push(`<span class="metric-badge" title="Kurtosis (K): excess kurtosis of this component's source scores over the sampled activation rows; larger values indicate a heavier-tailed direction.">K=${k.toFixed(1)}</span>`); el.componentMetrics.innerHTML=parts.join(''); }
+function renderEditor(){ const a=state.annotation; el.form.hidden=false; el.editorEmpty.hidden=true; el.positiveLabel.value=a.positive_label||''; el.positiveConfidence.value=a.positive_confidence||'unclear'; el.negativeLabel.value=a.negative_label||''; el.negativeConfidence.value=a.negative_confidence||'unclear'; el.summary.value=a.summary||''; el.notes.value=a.notes||''; el.caseStudy.checked=!!a.include_as_case_study; setTypes(el.positiveTypes,a.positive_interpretation_types||[]); setTypes(el.negativeTypes,a.negative_interpretation_types||[]); updateLabelConfidenceStyles(); const direction=topAbsDirection(); setActiveDirection(direction); renderNeighborCards(direction); }
+function topAbsDirection(){ const top=(state.examples?.examples_by_region?.top_abs||[])[0]; const score=Number(top?.source_score); if(!Number.isFinite(score) || score===0) return null; return score>0?'positive':'negative'; }
+function setActiveDirection(direction){ el.positiveBlock.classList.toggle('active-direction', direction==='positive'); el.negativeBlock.classList.toggle('active-direction', direction==='negative'); }
+function renderNeighborCards(sourceDirection){ const rows=state.neighbors?.neighbors||[]; const byDirection=new Map(rows.map(n=>[n.direction,n])); const sourceLabel=sourceDirection==='negative'?visibleAnnotationLabel(state.annotation?.negative_label,state.annotation?.negative_confidence):visibleAnnotationLabel(state.annotation?.positive_label,state.annotation?.positive_confidence); el.neighborCards.hidden=false; el.neighborCards.innerHTML=`${neighborCard(byDirection.get('prev'),sourceDirection,sourceLabel)}${neighborCard(byDirection.get('next'),sourceDirection,sourceLabel)}`; el.neighborCards.querySelectorAll('.neighbor-copy').forEach(b=>b.onclick=()=>copyNeighborAnnotation(b.dataset.direction)); }
+function neighborCard(n, sourceDirection, sourceLabel){ if(!n) return '<div class="neighbor-card missing" aria-hidden="true"></div>'; const layer=String(n.neighbor_layer||''); const component=Number(n.neighbor_component); const label=neighborLabel(n,sourceDirection,sourceLabel); const cos=Number(n.abs_cosine); const q=new URLSearchParams({model:state.model,layer,component:String(component)}); return `<div class="neighbor-card" title="${esc(layer)} C${component}"><div class="neighbor-head"><a class="neighbor-link" href="/annotate?${esc(q.toString())}"><span class="neighbor-target">${esc(layer)} C${component}</span></a><button class="neighbor-copy" type="button" data-direction="${esc(n.direction)}" title="Copy this neighbor annotation into the active direction">Copy</button></div><span class="neighbor-label">${esc(label)}</span><span class="neighbor-metrics">${neighborMetrics(n)}</span><span class="neighbor-cos" style="--cos-width:${cosWidth(cos)}%">cos=${Number.isFinite(cos)?cos.toFixed(3):'?'}</span></div>`; }
+function neighborLabel(n, sourceDirection, sourceLabel){ return neighborAnnotationSide(n,sourceDirection,sourceLabel).label || 'unlabeled'; }
+function neighborAnnotationSide(n, sourceDirection, sourceLabel){ const positive=visibleAnnotationLabel(n.positive_label,n.positive_confidence); const negative=visibleAnnotationLabel(n.negative_label,n.negative_confidence); const pm=labelSimilarity(sourceLabel,positive); const nm=labelSimilarity(sourceLabel,negative); if(pm>nm&&pm>0) return {side:'positive', label:positive, confidence:n.positive_confidence||'unclear', types:n.positive_types||[]}; if(nm>pm&&nm>0) return {side:'negative', label:negative, confidence:n.negative_confidence||'unclear', types:n.negative_types||[]}; const sourceSign=sourceDirection==='negative'?-1:1; const neighborSign=Number(n.neighbor_sign)<0?-1:1; if(sourceSign*neighborSign<0) return {side:'negative', label:negative, confidence:n.negative_confidence||'unclear', types:n.negative_types||[]}; return {side:'positive', label:positive, confidence:n.positive_confidence||'unclear', types:n.positive_types||[]}; }
+function copyNeighborAnnotation(direction){ const n=(state.neighbors?.neighbors||[]).find(x=>x.direction===direction); if(!n) return; const active=currentAnnotationDirection(); const sourceLabel=active==='negative'?visibleAnnotationLabel(state.annotation?.negative_label,state.annotation?.negative_confidence):visibleAnnotationLabel(state.annotation?.positive_label,state.annotation?.positive_confidence); const picked=neighborAnnotationSide(n,active,sourceLabel); if(active==='negative'){ el.negativeLabel.value=picked.label||''; el.negativeConfidence.value=picked.confidence||'unclear'; setTypes(el.negativeTypes,picked.types||[]); } else { el.positiveLabel.value=picked.label||''; el.positiveConfidence.value=picked.confidence||'unclear'; setTypes(el.positiveTypes,picked.types||[]); } updateLabelConfidenceStyles(); setActiveDirection(active); setStatus(`Copied ${direction} neighbor into ${active} direction.`); }
+function currentAnnotationDirection(){ if(el.negativeBlock.classList.contains('active-direction')) return 'negative'; if(el.positiveBlock.classList.contains('active-direction')) return 'positive'; return topAbsDirection()||'positive'; }
+function visibleAnnotationLabel(value, confidence){ const text=String(value||'').trim(); if(!text) return ''; if(text==='?' && String(confidence||'unclear')==='unclear') return ''; return text.replace(/\r/g,'\\r').replace(/\n/g,'\\n').replace(/\t/g,'\\t'); }
+function labelSimilarity(a,b){ const aa=labelTokens(a); const bb=labelTokens(b); if(!aa.size||!bb.size) return 0; let overlap=0; aa.forEach(t=>{if(bb.has(t)) overlap+=1;}); return overlap/Math.max(aa.size,bb.size); }
+function labelTokens(value){ const text=String(value||'').toLowerCase().replace(/[^a-z0-9]+/g,' ').trim(); if(!text||text==='?') return new Set(); return new Set(text.split(/\s+/).filter(Boolean)); }
+function cosWidth(value){ const cos=Math.max(0,Math.min(1,Number(value)||0)); return (100*cos).toFixed(1); }
+function neighborMetrics(n){ const parts=[]; const erf=Number(n?.effective_context_mean); const k=Number(n?.excess_kurtosis); if(Number.isFinite(erf)) parts.push(`ERF=${erf.toFixed(1)}`); if(Number.isFinite(k)) parts.push(`K=${k.toFixed(1)}`); return esc(parts.join(' · ')); }
+function updateLabelConfidenceStyles(){ setLabelConfidenceStyle(el.positiveLabel, el.positiveConfidence.value); setLabelConfidenceStyle(el.negativeLabel, el.negativeConfidence.value); }
+function setLabelConfidenceStyle(node, confidence){ node.classList.remove('label-confidence-high','label-confidence-medium','label-confidence-low','label-confidence-unclear'); node.classList.add(`label-confidence-${CONF.includes(confidence)?confidence:'unclear'}`); }
+async function saveAnnotation(ev){
+  ev.preventDefault();
+  if(!state.selected) return;
+  const component=state.selected.component;
+  const body={model_name:state.model, layer:state.layer, component, positive_label:el.positiveLabel.value, positive_confidence:el.positiveConfidence.value, positive_interpretation_types:selectedTypes(el.positiveTypes), negative_label:el.negativeLabel.value, negative_confidence:el.negativeConfidence.value, negative_interpretation_types:selectedTypes(el.negativeTypes), summary:el.summary.value, notes:el.notes.value, include_as_case_study:el.caseStudy.checked};
+  setStatus('Saving...');
+  await api('/api/annotations/component',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(body)});
+  const q=new URLSearchParams({model:state.model,layer:state.layer,component:String(component)});
+  const [annotation, components]=await Promise.all([
+    api(`/api/annotations/component?${q}`),
+    api(`/api/components?model=${encodeURIComponent(state.model)}&layer=${encodeURIComponent(state.layer)}`),
+  ]);
+  state.annotation=annotation;
+  state.components=components.components;
+  state.selected=state.components.find(c=>c.component===component) || state.selected;
+  renderComponents();
+  renderEditor();
+  setStatus('Saved.');
+}
+init().catch(e=>{setStatus(e.message); el.components.innerHTML=`<div class="error">${esc(e.message)}</div>`});
+</script>
+</body>
+</html>

server/static/component.html

@@ -0,0 +1,373 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Component Examples - GPT-2 Explorer</title>
+  <style>
+    :root {
+      --bg: #f6f7f9;
+      --panel: #fff;
+      --text: #151922;
+      --muted: #647084;
+      --border: #cbd3df;
+      --accent: #1f6feb;
+      --positive: #b91c1c;
+      --negative: #1d4ed8;
+      --mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+      --shadow: 0 1px 2px rgb(20 25 34 / .08), 0 10px 30px rgb(20 25 34 / .06);
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--text);
+      font: 14px/1.45 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+    header {
+      position: sticky;
+      top: 0;
+      z-index: 5;
+      background: var(--panel);
+      border-bottom: 1px solid var(--border);
+      box-shadow: var(--shadow);
+      padding: 12px 18px;
+    }
+    .top {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 14px;
+    }
+    h1 { margin: 0; font-size: 19px; letter-spacing: 0; }
+    .nav {
+      display: flex;
+      align-items: center;
+      gap: 14px;
+    }
+    a {
+      color: var(--accent);
+      font-weight: 750;
+      text-decoration: none;
+    }
+    a:hover { text-decoration: underline; }
+    main {
+      width: 100%;
+      margin: 0;
+      padding: 12px;
+    }
+    .summary {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: 8px 14px;
+      margin-bottom: 12px;
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 750;
+    }
+    .band {
+      margin-bottom: 14px;
+      background: var(--panel);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      box-shadow: var(--shadow);
+      overflow: hidden;
+    }
+    .band-toggle {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 12px;
+      width: 100%;
+      margin: 0;
+      padding: 9px 12px;
+      border-bottom: 1px solid #e5eaf2;
+      border-left: 0;
+      border-right: 0;
+      border-top: 0;
+      font-size: 14px;
+      font-weight: 850;
+      letter-spacing: 0;
+      background: #fbfcfe;
+      color: var(--text);
+      text-align: left;
+      cursor: pointer;
+      font-family: inherit;
+    }
+    .band-toggle:hover { background: #f1f5f9; }
+    .band-toggle:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; }
+    .band-title { min-width: 0; overflow-wrap: anywhere; }
+    .band-state { color: var(--muted); font-size: 12px; white-space: nowrap; }
+    .band.collapsed .examples { display: none; }
+    .examples {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
+      gap: 0;
+    }
+    .example {
+      min-width: 0;
+      border-right: 1px solid #e5eaf2;
+      border-bottom: 1px solid #e5eaf2;
+      padding: 10px 12px;
+    }
+    .example-head {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 10px;
+      margin-bottom: 6px;
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 750;
+    }
+    .example-meta { display: flex; flex-wrap: wrap; align-items: center; gap: 6px; min-width: 0; }
+    .doc-link { color: var(--accent); text-decoration: none; font-weight: 850; }
+    .doc-link:hover { text-decoration: underline; }
+    .score {
+      font-variant-numeric: tabular-nums;
+      white-space: nowrap;
+    }
+    .score.positive { color: var(--positive); }
+    .score.negative { color: var(--negative); }
+    .token {
+      display: inline-block;
+      margin-bottom: 6px;
+      padding: 2px 6px;
+      border: 1px solid var(--border);
+      border-radius: 5px;
+      background: #f8fafc;
+      font-weight: 850;
+      font-family: var(--mono);
+      font-size: 12px;
+      overflow-wrap: anywhere;
+    }
+    .token.positive { color: var(--positive); border-color: #fecaca; background: #fff1f2; }
+    .token.negative { color: var(--negative); border-color: #bfdbfe; background: #eff6ff; }
+    .context {
+      margin: 0;
+      white-space: pre-wrap;
+      overflow-wrap: anywhere;
+      font-family: var(--mono);
+      font-size: 12px;
+      line-height: 1.55;
+    }
+    .context-token {
+      border-radius: 3px;
+      padding: 0 1px;
+    }
+    .context-token.target {
+      box-shadow: inset 0 -2px 0 currentColor;
+      font-weight: 850;
+    }
+    .context-token.positive { color: var(--positive); }
+    .context-token.negative { color: var(--negative); }
+    .empty, .error {
+      border: 1px dashed var(--border);
+      border-radius: 8px;
+      padding: 18px;
+      color: var(--muted);
+      background: #fff;
+    }
+    .error { color: #a41414; border-color: #f0b9b9; background: #fff7f7; }
+    @media (max-width: 760px) {
+      main { padding: 8px; }
+      header { padding: 10px 12px; }
+      .top { align-items: flex-start; flex-direction: column; }
+      .examples { grid-template-columns: 1fr; }
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="top">
+      <h1 id="title">Component Examples</h1>
+      <nav class="nav" aria-label="Primary">
+        <a href="/">Explorer</a>
+        <a href="/sae-explorer">SAE Explorer</a>
+        <a href="/stats">Stats</a>
+        <a href="/annotate">Annotate</a>
+        <a href="/random-components">Random</a>
+      </nav>
+    </div>
+  </header>
+
+  <main>
+    <div id="summary" class="summary">Loading component examples...</div>
+    <div id="message" class="empty">Loading...</div>
+    <div id="content" hidden></div>
+  </main>
+
+  <script>
+    const els = {
+      title: document.getElementById("title"),
+      summary: document.getElementById("summary"),
+      message: document.getElementById("message"),
+      content: document.getElementById("content"),
+    };
+
+    async function api(path) {
+      const res = await fetch(path, { headers: { "content-type": "application/json" } });
+      if (!res.ok) {
+        let detail = res.statusText;
+        try { detail = (await res.json()).detail || detail; } catch {}
+        throw new Error(detail);
+      }
+      return res.json();
+    }
+
+    async function init() {
+      const params = new URLSearchParams(location.search);
+      const model = params.get("model") || "gpt2";
+      const layer = params.get("layer") || "";
+      const component = params.get("component") || "";
+      if (!layer || !component) {
+        showError("Missing layer or component.");
+        return;
+      }
+      try {
+        const query = new URLSearchParams({ model, layer, component });
+        const data = await api(`/api/component-examples?${query.toString()}`);
+        render(data);
+      } catch (err) {
+        showError(err.message);
+      }
+    }
+
+    function render(data) {
+      const bands = data.bands || [];
+      const total = bands.reduce((count, band) => count + (band.examples || []).length, 0);
+      const kurtosis = Number.isFinite(Number(data.excess_kurtosis)) ? `kurtosis ${Number(data.excess_kurtosis).toFixed(3)}` : "kurtosis n/a";
+      els.title.textContent = `${data.layer} C${data.component}`;
+      els.summary.textContent = `${data.model_name} - ${data.layer} component ${data.component} - ${kurtosis} - ${bands.length} bands - ${total} examples`;
+      if (!bands.length) {
+        els.message.hidden = false;
+        els.message.className = "empty";
+        els.message.textContent = "No examples found for this component.";
+        els.content.hidden = true;
+        return;
+      }
+      els.message.hidden = true;
+      els.content.hidden = false;
+      els.content.innerHTML = bands.map(renderBand).join("");
+      wireBandToggles();
+    }
+
+    function renderBand(band) {
+      const examples = band.examples || [];
+      const collapsed = shouldCollapseBand(band.region);
+      return `
+        <section class="band ${collapsed ? "collapsed" : ""}">
+          <button class="band-toggle" type="button" aria-expanded="${collapsed ? "false" : "true"}">
+            <span class="band-title">${escapeHtml(band.region)}</span>
+            <span class="band-state">${collapsed ? "show" : "hide"}</span>
+          </button>
+          <div class="examples">${examples.map(renderExample).join("")}</div>
+        </section>
+      `;
+    }
+
+    function wireBandToggles() {
+      els.content.querySelectorAll(".band-toggle").forEach(button => {
+        button.addEventListener("click", () => {
+          const band = button.closest(".band");
+          const collapsed = band.classList.toggle("collapsed");
+          button.setAttribute("aria-expanded", String(!collapsed));
+          const state = button.querySelector(".band-state");
+          if (state) state.textContent = collapsed ? "show" : "hide";
+        });
+      });
+    }
+
+    function shouldCollapseBand(region) {
+      const name = String(region || "").toLowerCase().replace(/[_-]+/g, " ");
+      return name.includes("opposite") || name.includes("near zero") || name.includes("nearzero");
+    }
+
+    function renderExample(example) {
+      const score = Number(example.source_score);
+      const scoreClass = score > 0 ? "positive" : score < 0 ? "negative" : "";
+      return `
+        <article class="example">
+          <div class="example-head">
+            <span class="example-meta"><span>#${escapeHtml(example.rank)}</span>${docPositionLink(example)}</span>
+            <span class="score ${scoreClass}">${formatScore(score)}</span>
+          </div>
+          <div class="token ${scoreClass}">${escapeHtml(visibleToken(example.token))}</div>
+          <p class="context">${renderContext(example)}</p>
+        </article>
+      `;
+    }
+
+    function docPositionLink(example) {
+      if (example.doc_id == null || Number(example.doc_id) < 0) {
+        return example.position == null ? "" : `<span>pos ${escapeHtml(example.position)}</span>`;
+      }
+      const query = new URLSearchParams({ model: state.model, doc_id: String(example.doc_id) });
+      if (example.position != null) query.set("position", String(example.position));
+      const target = visibleToken(example.token);
+      if (target) query.set("target", target);
+      const text = `doc ${example.doc_id}${example.position == null ? "" : ` · pos ${example.position}`}`;
+      return `<a class="doc-link" href="/context?${escapeAttr(query.toString())}" target="_blank" rel="noopener" title="Open full document context">${escapeHtml(text)}</a>`;
+    }
+
+    function renderContext(example) {
+      const tokens = Array.isArray(example.context_token_scores) ? example.context_token_scores : [];
+      if (!tokens.length) return escapeHtml(example.context_to_target || example.context || "");
+      const maxAbs = Math.max(
+        1e-9,
+        Number(example.context_score_max_abs || 0),
+        ...tokens.map(token => Math.abs(Number(token.source_score || 0)))
+      );
+      return tokens.map(token => {
+        const score = Number(token.source_score || 0);
+        const alpha = tokenAlpha(score, maxAbs);
+        const color = alpha === 0 ? "transparent" : score > 0 ? `rgba(220,38,38,${alpha})` : `rgba(37,99,235,${alpha})`;
+        const signClass = score > 0 ? "positive" : score < 0 ? "negative" : "";
+        const title = `score=${formatScore(score)}`;
+        return `<span class="context-token ${token.is_target ? "target" : ""} ${signClass}" style="background:${color}" title="${escapeAttr(title)}">${escapeHtml(visibleContextToken(token.token))}</span>`;
+      }).join("");
+    }
+
+    function tokenAlpha(score, maxAbs) {
+      const magnitude = Math.abs(Number(score || 0));
+      if (magnitude < 1e-6) return 0;
+      return Math.min(0.55, 0.47 * Math.log1p(magnitude) / Math.log1p(maxAbs));
+    }
+
+    function visibleToken(value) {
+      const text = String(value || "");
+      if (text === " ") return "[space]";
+      if (text === "\n") return "[newline]";
+      if (text === "\f") return "\\f";
+      return text.replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\t/g, "\\t").replace(/\f/g, "\\f");
+    }
+
+    function visibleContextToken(value) {
+      return String(value || "").replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\t/g, "\\t").replace(/\f/g, "\\f");
+    }
+
+    function formatScore(value) {
+      return Number.isFinite(value) ? value.toFixed(4).replace(/0+$/, "").replace(/\.$/, "") : "n/a";
+    }
+
+    function showError(message) {
+      els.summary.textContent = "";
+      els.message.hidden = false;
+      els.message.className = "error";
+      els.message.textContent = message;
+      els.content.hidden = true;
+    }
+
+    function escapeHtml(value) {
+      return String(value).replace(/[&<>"']/g, char => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
+    }
+
+    function escapeAttr(value) {
+      return escapeHtml(value);
+    }
+
+    init();
+  </script>
+</body>
+</html>

server/static/index.html

@@ -0,0 +1,1546 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>ICA Explorer</title>
+  <style>
+    :root {
+      --bg: #f6f7f9;
+      --panel: #fff;
+      --text: #151922;
+      --muted: #647084;
+      --border: #cbd3df;
+      --accent: #1f6feb;
+      --hot: #b42318;
+      --cold: #1e5bb8;
+      --good: #087443;
+      --warn: #a15c00;
+      --shadow: 0 1px 2px rgb(20 25 34 / .08), 0 10px 30px rgb(20 25 34 / .06);
+      --token-card-width: 140px;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--text);
+      font: 14px/1.45 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+    header {
+      position: sticky;
+      top: 0;
+      z-index: 5;
+      background: var(--panel);
+      border-bottom: 1px solid var(--border);
+      box-shadow: var(--shadow);
+      padding: 12px 18px;
+    }
+    .top {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 14px;
+    }
+    .nav {
+      display: flex;
+      align-items: center;
+      gap: 14px;
+    }
+    .nav a {
+      color: var(--accent);
+      font-weight: 750;
+      text-decoration: none;
+    }
+    .nav a:hover { text-decoration: underline; }
+    h1 { margin: 0; font-size: 19px; letter-spacing: 0; }
+    main {
+      max-width: 1240px;
+      margin: 0 auto;
+      padding: 18px;
+    }
+    footer {
+      max-width: 1240px;
+      margin: 0 auto;
+      padding: 0 18px 22px;
+      color: var(--muted);
+      font-size: 12px;
+    }
+    footer a {
+      color: var(--accent);
+      font-weight: 750;
+      text-decoration: none;
+    }
+    footer a:hover { text-decoration: underline; }
+    .controls {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) 450px;
+      gap: 12px;
+      align-items: stretch;
+    }
+    .control-stack {
+      display: flex;
+      flex-wrap: wrap;
+      align-content: flex-start;
+      align-items: center;
+      gap: 10px;
+    }
+    .inline-control {
+      display: grid;
+      grid-template-columns: max-content max-content;
+      align-items: center;
+      column-gap: 8px;
+    }
+    .inline-control > span { white-space: nowrap; }
+    .model-control { flex: 0 0 auto; }
+    .layer-control { flex: 0 0 auto; }
+    .control-break { flex-basis: 100%; height: 0; }
+    .topk-control,
+    .card-width-control,
+    .opacity-control { flex: 0 0 auto; }
+    .run-button {
+      width: auto;
+      min-height: 32px;
+      padding: 6px 12px;
+      border-color: #1458c8;
+      background: var(--accent);
+      color: #fff;
+      font-weight: 850;
+    }
+    .run-button:hover { background: #1458c8; color: #fff; }
+    .memory-control {
+      position: fixed;
+      right: 12px;
+      bottom: 10px;
+      z-index: 4;
+      display: inline-flex;
+      align-items: center;
+      gap: 5px;
+      width: auto;
+      min-height: 24px;
+      padding: 3px 6px;
+      border: 1px solid #d7dee9;
+      border-radius: 6px;
+      background: rgb(255 255 255 / .78);
+      color: #94a3b8;
+      font-size: 11px;
+      font-weight: 650;
+      white-space: nowrap;
+    }
+    .memory-control input { width: auto; margin: 0; padding: 0; accent-color: #94a3b8; }
+    .memory-control:hover { color: #64748b; border-color: #cbd5e1; background: #fff; }
+    #topK { width: 48px; min-width: 0; }
+    #cardWidth { width: 78px; min-width: 0; }
+    #weakRatio { width: 58px; min-width: 0; }
+    .model-control select,
+    .layer-control select { width: 100%; }
+    label {
+      display: grid;
+      gap: 5px;
+      color: #435066;
+      font-size: 12px;
+      font-weight: 700;
+    }
+    textarea, select, input, button {
+      width: 100%;
+      border: 1px solid var(--border);
+      border-radius: 7px;
+      background: #fff;
+      color: var(--text);
+      font: inherit;
+      padding: 8px 10px;
+    }
+    textarea {
+      height: 92px;
+      min-height: 92px;
+      resize: vertical;
+      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    }
+    button {
+      cursor: pointer;
+      min-height: 39px;
+      background: #eef2f7;
+      font-weight: 750;
+    }
+    button:hover { border-color: var(--accent); color: var(--accent); background: #edf5ff; }
+    button.primary { background: var(--accent); border-color: #1458c8; color: #fff; }
+    button.primary:hover { background: #1458c8; color: #fff; }
+    .panel {
+      margin-top: 14px;
+      background: var(--panel);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      box-shadow: var(--shadow);
+      padding: 12px;
+    }
+    .results {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(var(--token-card-width), 1fr));
+      gap: 10px;
+      margin-top: 12px;
+    }
+    .token-card {
+      position: relative;
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 6px;
+      background: #fff;
+      min-width: 0;
+      text-align: center;
+    }
+    .token-text {
+      min-height: 25px;
+      font-weight: 850;
+      text-align: center;
+      overflow-wrap: anywhere;
+      margin-bottom: 6px;
+    }
+    .score-row {
+      position: relative;
+      min-height: 24px;
+      margin-top: 3px;
+    }
+    .badge {
+      position: relative;
+      display: flex;
+      align-items: center;
+      width: 100%;
+      min-height: 24px;
+      padding: 3px 5px;
+      border: 1px solid #d5dce7;
+      border-radius: 5px;
+      background:
+        linear-gradient(
+          90deg,
+          var(--score-bg, #edf2f7) 0,
+          var(--score-bg, #edf2f7) var(--score-width, 100%),
+          transparent var(--score-width, 100%),
+          transparent 100%
+        );
+      color: var(--text);
+      font-size: 10px;
+      font-weight: 400;
+      text-align: left;
+      cursor: pointer;
+    }
+    .badge:hover {
+      border-color: var(--component-color, var(--accent));
+      color: var(--text);
+    }
+    .badge.hot {
+      border-color: var(--component-color, var(--accent));
+      --score-bg: color-mix(in srgb, var(--component-color, var(--accent)) 16%, white);
+      box-shadow: inset 3px 0 0 var(--component-color, var(--accent));
+    }
+    .badge.hot:hover {
+      color: var(--text);
+    }
+    .badge.weak {
+      opacity: .1;
+    }
+    .badge.weak:hover,
+    .badge.weak.hot {
+      opacity: 1;
+    }
+    .badge-main {
+      display: inline-flex;
+      align-items: center;
+      gap: 3px;
+      min-width: 0;
+      max-width: calc(100% - 28px);
+      overflow: hidden;
+      white-space: nowrap;
+      text-overflow: ellipsis;
+    }
+    .badge-label {
+      min-width: 0;
+      overflow: hidden;
+      white-space: nowrap;
+      text-overflow: ellipsis;
+    }
+    .annotation-dot {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      min-width: 13px;
+      height: 13px;
+      border-radius: 4px;
+      flex: 0 0 auto;
+      background: #e5e7eb;
+      box-shadow: 0 0 0 1px rgb(255 255 255 / .85);
+      color: #fff;
+      font-size: 9px;
+      font-weight: 850;
+      line-height: 1;
+    }
+    .annotation-dot.high { background: #16a34a; box-shadow: 0 0 0 1px #15803d; }
+    .annotation-dot.medium { color: #166534; background: #fef3c7; box-shadow: 0 0 0 1px #d9b94e; }
+    .annotation-dot.low { color: #9f1239; background: #ffe4e6; box-shadow: 0 0 0 1px #f9a8d4; }
+    .annotation-dot.unclear { color: #475569; background: #e5e7eb; box-shadow: 0 0 0 1px #cbd5e1; }
+    .score {
+      position: absolute;
+      left: auto;
+      right: 5px;
+      top: 50%;
+      transform: translateY(-50%);
+      width: 28px;
+      text-align: right;
+      color: var(--muted);
+      font-size: 9px;
+      font-variant-numeric: tabular-nums;
+      pointer-events: none;
+    }
+    .prediction-row {
+      display: flex;
+      align-items: center;
+      gap: 5px;
+      min-height: 24px;
+      margin-top: 5px;
+      padding: 3px 5px;
+      border: 1px solid #d8e0eb;
+      border-radius: 5px;
+      background: #f6f8fb;
+      color: #314158;
+      font-size: 10px;
+      font-weight: 650;
+      text-align: left;
+    }
+    .prediction-label {
+      color: var(--muted);
+      font-weight: 850;
+    }
+    .prediction-token {
+      min-width: 0;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    .empty, .error {
+      margin-top: 12px;
+      border: 1px dashed var(--border);
+      border-radius: 8px;
+      padding: 18px;
+      color: var(--muted);
+      background: #fff;
+    }
+    .error { color: #a41414; border-color: #f0b9b9; background: #fff7f7; }
+    .request-indicator {
+      position: fixed;
+      left: 14px;
+      top: 62px;
+      z-index: 8;
+      display: none;
+      align-items: center;
+      gap: 8px;
+      min-height: 34px;
+      padding: 8px 10px;
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      background: var(--panel);
+      box-shadow: var(--shadow);
+      color: #435066;
+      font-size: 12px;
+      font-weight: 800;
+    }
+    .request-indicator.visible { display: inline-flex; }
+    .request-spinner {
+      width: 14px;
+      height: 14px;
+      border: 2px solid #cbd5e1;
+      border-top-color: var(--accent);
+      border-radius: 50%;
+      animation: request-spin .8s linear infinite;
+    }
+    @keyframes request-spin { to { transform: rotate(360deg); } }
+    .selection-panel {
+      position: fixed;
+      right: 14px;
+      top: 82px;
+      z-index: 6;
+      display: none;
+      width: 500px;
+      max-width: calc(100vw - 28px);
+      max-height: calc(100vh - 104px);
+      overflow: auto;
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      background: var(--panel);
+      box-shadow: var(--shadow);
+      padding: 12px;
+    }
+    .selection-panel.visible { display: block; }
+    .selection-title {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 8px;
+      margin-bottom: 10px;
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 850;
+    }
+    .selection-close {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: 18px;
+      height: 18px;
+      min-height: 18px;
+      padding: 0;
+      border-radius: 5px;
+      color: var(--muted);
+      font-size: 13px;
+      line-height: 1;
+    }
+    .selection-actions {
+      display: inline-flex;
+      align-items: center;
+      gap: 5px;
+    }
+    .selection-export-toggle {
+      display: none;
+      width: auto;
+      min-height: 18px;
+      padding: 2px 7px;
+      border-radius: 5px;
+      color: var(--muted);
+      font-size: 11px;
+      font-weight: 800;
+      line-height: 1.2;
+    }
+    .selection-export-toggle.visible { display: inline-flex; align-items: center; }
+    .selection-list {
+      display: flex;
+      flex-direction: column;
+      gap: 8px;
+    }
+    .selection-entry {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) 145px;
+      gap: 8px;
+      align-items: stretch;
+    }
+    .selection-link {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 8px;
+      min-height: 30px;
+      padding: 7px 10px 5px;
+      color: var(--text);
+      font-weight: 850;
+      text-decoration: none;
+    }
+    .selection-link:hover {
+      color: var(--accent);
+      text-decoration: none;
+    }
+    .selection-item {
+      border: 1px solid var(--component-color, var(--accent));
+      border-radius: 7px;
+      background: color-mix(in srgb, var(--component-color, var(--accent)) 5%, white);
+      overflow: hidden;
+      box-shadow: inset 3px 0 0 var(--component-color, var(--accent));
+    }
+    .selection-item .selection-link {
+      border: 0;
+      border-radius: 0;
+      background: transparent;
+    }
+    .selection-score {
+      color: var(--muted);
+      font-size: 11px;
+      font-weight: 800;
+      font-variant-numeric: tabular-nums;
+    }
+    .selection-token-stats {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 4px;
+      padding: 0 10px 10px;
+      color: var(--muted);
+      font-size: 11px;
+      line-height: 1.25;
+    }
+    .selection-neighbors {
+      display: grid;
+      grid-template-rows: repeat(2, minmax(58px, auto));
+      gap: 6px;
+    }
+    .neighbor-card {
+      display: grid;
+      gap: 3px;
+      min-height: 58px;
+      padding: 7px;
+      border: 1px solid #d7dee9;
+      border-radius: 6px;
+      background: #fff;
+      color: var(--text);
+      text-decoration: none;
+    }
+    .neighbor-card:hover {
+      border-color: var(--accent);
+      color: var(--text);
+      text-decoration: none;
+    }
+    .neighbor-card.missing {
+      visibility: hidden;
+    }
+    .neighbor-card.loading {
+      color: var(--muted);
+      background: #f8fafc;
+      cursor: default;
+    }
+    .neighbor-target {
+      min-width: 0;
+      overflow: hidden;
+      white-space: nowrap;
+      text-overflow: ellipsis;
+      color: var(--muted);
+      font-size: 10px;
+      font-weight: 750;
+    }
+    .neighbor-label {
+      min-width: 0;
+      overflow: hidden;
+      white-space: nowrap;
+      text-overflow: ellipsis;
+      color: var(--text);
+      font-size: 13px;
+      font-weight: 850;
+      line-height: 1.2;
+    }
+    .neighbor-cos {
+      position: relative;
+      min-height: 18px;
+      padding: 2px 5px;
+      border: 1px solid #d7dee9;
+      border-radius: 5px;
+      background:
+        linear-gradient(
+          90deg,
+          color-mix(in srgb, var(--accent) 18%, white) 0,
+          color-mix(in srgb, var(--accent) 18%, white) var(--cos-width, 0%),
+          transparent var(--cos-width, 0%),
+          transparent 100%
+        );
+      color: var(--muted);
+      font-size: 11px;
+      font-weight: 800;
+      font-variant-numeric: tabular-nums;
+    }
+    .neighbor-metrics {
+      color: var(--muted);
+      font-size: 10px;
+      font-weight: 500;
+      font-variant-numeric: tabular-nums;
+    }
+    .selection-token-chip {
+      display: inline-flex;
+      align-items: center;
+      gap: 4px;
+      min-height: 20px;
+      max-width: 100%;
+      padding: 2px 6px;
+      border: 1px solid #d7dee9;
+      border-radius: 999px;
+      background: #fff;
+      color: #435066;
+      font-size: var(--token-font-size, 11px);
+    }
+    .selection-token-text {
+      min-width: 0;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    .selection-export {
+      position: fixed;
+      left: 14px;
+      bottom: 10px;
+      z-index: 4;
+      display: none;
+      width: min(520px, calc(100vw - 180px));
+      height: 150px;
+      border: 1px solid var(--border);
+      border-radius: 7px;
+      background: rgb(255 255 255 / .94);
+      box-shadow: var(--shadow);
+      color: #334155;
+      font: 12px/1.4 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      resize: vertical;
+    }
+    .selection-export.visible { display: block; }
+    .selection-export-copy {
+      position: fixed;
+      left: 14px;
+      bottom: 164px;
+      z-index: 5;
+      display: none;
+      width: auto;
+      min-height: 24px;
+      padding: 3px 8px;
+      border-radius: 6px;
+      color: #64748b;
+      background: rgb(255 255 255 / .92);
+      font-size: 11px;
+      font-weight: 800;
+    }
+    .selection-export-copy.visible { display: inline-flex; align-items: center; }
+    @media (max-width: 760px) {
+      main { padding: 12px; }
+      footer { padding: 0 12px 18px; }
+      .controls { grid-template-columns: 1fr; }
+      .control-stack { align-content: flex-start; }
+      .memory-control { right: 8px; bottom: 8px; }
+      .top { align-items: flex-start; flex-direction: column; }
+      .selection-panel {
+        left: 8px;
+        right: 8px;
+        top: auto;
+        bottom: 8px;
+        width: auto;
+      }
+      .selection-entry {
+        grid-template-columns: minmax(0, 1fr) 128px;
+      }
+      .selection-export {
+        left: 8px;
+        bottom: 40px;
+        width: calc(100vw - 16px);
+        height: 120px;
+      }
+      .selection-export-copy {
+        left: 8px;
+        bottom: 164px;
+      }
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="top">
+      <h1>ICA Explorer</h1>
+      <nav class="nav" aria-label="Primary">
+        <a href="/">Explorer</a>
+        <a href="/sae-explorer">SAE Explorer</a>
+        <a href="/stats">Stats</a>
+        <a href="/annotate">Annotate</a>
+        <a href="/random-components">Random</a>
+      </nav>
+    </div>
+  </header>
+
+  <main>
+    <div class="panel">
+      <div class="controls">
+        <label>
+          Text
+          <textarea id="probeText" spellcheck="false">Maya stopped at the bank before the trip, waiting in line to deposit a check and withdraw enough cash for the weekend.</textarea>
+        </label>
+        <div class="control-stack">
+          <label class="inline-control model-control">
+            <span>Model</span>
+            <select id="modelSelect"></select>
+          </label>
+          <label class="inline-control layer-control">
+            <span>Layer</span>
+            <select id="layerSelect"></select>
+          </label>
+          <span class="control-break" aria-hidden="true"></span>
+          <label class="inline-control topk-control">
+            <span>Top K</span>
+            <input id="topK" type="number" min="1" max="32" value="5" />
+          </label>
+          <label class="inline-control card-width-control">
+            <span>Card Width</span>
+            <input id="cardWidth" type="number" min="100" max="360" step="20" value="140" />
+          </label>
+          <label class="inline-control opacity-control">
+            <span>Opacity Cutoff</span>
+            <input id="weakRatio" type="number" min="0" max="1" step="0.05" value="0.5" />
+          </label>
+          <button id="runProbe" class="run-button" type="button">Run</button>
+        </div>
+        <label class="memory-control" title="Keep loaded models in VRAM when switching.">
+          <input id="keepModels" type="checkbox" checked />
+          <span>Cache LLMs in VRAM</span>
+        </label>
+      </div>
+    </div>
+
+    <div id="message" class="empty">Choose a layer and run the probe.</div>
+    <div id="results" class="results"></div>
+  </main>
+  <aside id="selectionPanel" class="selection-panel" aria-live="polite">
+    <div class="selection-title">
+      <span>Selected components</span>
+      <div class="selection-actions">
+        <button id="selectionExportToggle" class="selection-export-toggle" type="button">Hide text</button>
+        <button id="selectionClose" class="selection-close" type="button" title="Hide selected components" aria-label="Hide selected components">×</button>
+      </div>
+    </div>
+    <div id="selectionList" class="selection-list"></div>
+  </aside>
+  <div id="requestIndicator" class="request-indicator" role="status" aria-live="polite">
+    <span class="request-spinner" aria-hidden="true"></span>
+    <span>Waiting for server...</span>
+  </div>
+  <button id="selectionExportCopy" class="selection-export-copy" type="button">Copy</button>
+  <textarea id="selectionExport" class="selection-export" readonly aria-label="Selected component summary"></textarea>
+
+  <script>
+    const STORAGE_KEYS = {
+      probeText: "icaExplorer.probeText",
+      model: "icaExplorer.model",
+      layer: "icaExplorer.layer",
+      topK: "icaExplorer.topK",
+      cardWidth: "icaExplorer.cardWidth",
+      weakRatio: "icaExplorer.opacityCutoff",
+      keepModels: "icaExplorer.keepModels",
+      highlights: "icaExplorer.selectedComponents",
+    };
+
+    const state = {
+      meta: null,
+      models: [],
+      highlights: new Set(),
+      currentScores: new Map(),
+      tokenStats: new Map(),
+      tokenStatsRetries: new Map(),
+      componentNeighbors: new Map(),
+      componentNeighborsRetries: new Map(),
+      layerComponentMeta: new Map(),
+      layerComponentMetaLoading: new Set(),
+      selectionPanelHidden: false,
+      selectionExportHidden: false,
+      requestId: 0,
+      textTimer: 0,
+      pendingRequests: 0,
+      lastProbeOutput: null,
+    };
+
+    const els = {
+      text: document.getElementById("probeText"),
+      model: document.getElementById("modelSelect"),
+      layer: document.getElementById("layerSelect"),
+      topK: document.getElementById("topK"),
+      cardWidth: document.getElementById("cardWidth"),
+      weakRatio: document.getElementById("weakRatio"),
+      runProbe: document.getElementById("runProbe"),
+      keepModels: document.getElementById("keepModels"),
+      message: document.getElementById("message"),
+      results: document.getElementById("results"),
+      selectionPanel: document.getElementById("selectionPanel"),
+      selectionList: document.getElementById("selectionList"),
+      selectionClose: document.getElementById("selectionClose"),
+      selectionExportCopy: document.getElementById("selectionExportCopy"),
+      selectionExportToggle: document.getElementById("selectionExportToggle"),
+      selectionExport: document.getElementById("selectionExport"),
+      requestIndicator: document.getElementById("requestIndicator"),
+    };
+
+    async function api(path, options = {}) {
+      beginRequest();
+      try {
+        const res = await fetch(path, {
+          headers: { "content-type": "application/json" },
+          ...options,
+        });
+        if (!res.ok) {
+          let detail = res.statusText;
+          try { detail = (await res.json()).detail || detail; } catch {}
+          throw new Error(detail);
+        }
+        return res.json();
+      } finally {
+        endRequest();
+      }
+    }
+
+    function beginRequest() {
+      state.pendingRequests += 1;
+      els.requestIndicator.classList.toggle("visible", state.pendingRequests > 0);
+    }
+
+    function endRequest() {
+      state.pendingRequests = Math.max(0, state.pendingRequests - 1);
+      els.requestIndicator.classList.toggle("visible", state.pendingRequests > 0);
+    }
+
+    async function init() {
+      const savedText = localStorage.getItem(STORAGE_KEYS.probeText);
+      restoreControlValues();
+      if (savedText !== null) els.text.value = savedText;
+      try {
+        const modelsOut = await api("/api/models");
+        state.models = (modelsOut.models || []).filter(model => model.probe_supported);
+        if (!state.models.length) throw new Error("No probe-supported models are available.");
+        els.model.innerHTML = state.models.map(model => `<option value="${escapeAttr(model.model_name)}">${escapeHtml(model.display_name || model.model_name)}</option>`).join("");
+        const savedModel = localStorage.getItem(STORAGE_KEYS.model);
+        if (savedModel && state.models.some(model => model.model_name === savedModel)) els.model.value = savedModel;
+        else if (state.models.some(model => model.model_name === "gpt2")) els.model.value = "gpt2";
+        await loadModelMeta({ restoreLayer: true });
+        runProbe();
+      } catch (err) {
+        showError(err.message);
+      }
+    }
+
+    async function runProbe() {
+      const requestId = ++state.requestId;
+      els.message.className = "empty";
+      if (!els.text.value.trim()) {
+        state.highlights.clear();
+        els.results.innerHTML = "";
+        els.message.hidden = false;
+        els.message.textContent = "Enter text to run the probe.";
+        return;
+      }
+      if (!els.results.children.length) {
+        els.message.hidden = false;
+        els.message.textContent = "Running probe...";
+      }
+      try {
+        const out = await api("/api/probe", {
+          method: "POST",
+          body: JSON.stringify({
+            text: els.text.value,
+            model_name: els.model.value,
+            layer: els.layer.value,
+            top_k: Number(els.topK.value || 5),
+            highlights: [],
+            keep_models: els.keepModels.checked,
+          }),
+        });
+        if (requestId !== state.requestId) return;
+        restoreHighlightsForContext(out);
+        renderResults(out);
+      } catch (err) {
+        if (requestId !== state.requestId) return;
+        showError(err.message);
+      }
+    }
+
+    function scheduleProbe() {
+      localStorage.setItem(STORAGE_KEYS.probeText, els.text.value);
+      persistControls();
+      persistHighlights();
+      renderSelectionExport();
+    }
+
+    function handleTextKeydown(event) {
+      if ((event.ctrlKey || event.metaKey) && event.key === "Enter") {
+        event.preventDefault();
+        localStorage.setItem(STORAGE_KEYS.probeText, els.text.value);
+        persistControls();
+        runProbe();
+      }
+    }
+
+    function updateCardWidth() {
+      const value = Math.max(100, Math.min(360, Number(els.cardWidth.value || 140)));
+      document.documentElement.style.setProperty("--token-card-width", `${value}px`);
+      localStorage.setItem(STORAGE_KEYS.cardWidth, String(value));
+    }
+
+    function rerenderLastProbe() {
+      if (state.lastProbeOutput) renderResults(state.lastProbeOutput);
+    }
+
+    function renderResults(out) {
+      state.lastProbeOutput = out;
+      if (out.truncated) {
+        els.message.hidden = false;
+        els.message.className = "empty";
+        els.message.textContent = `Input was truncated to ${out.max_length} tokens.`;
+      } else {
+        els.message.hidden = true;
+      }
+      const annotationMeta = annotationMetaMap(out.annotated_components || []);
+      state.annotationMeta = annotationMeta;
+      state.currentScores = new Map();
+      (out.tokens || []).forEach(token => (token.top || []).forEach(pair => {
+        const component = Number(pair.component);
+        const score = Math.abs(Number(pair.score || 0));
+        const previous = state.currentScores.get(component);
+        if (!previous || score > Math.abs(Number(previous.score || 0))) {
+          state.currentScores.set(component, { component, score: Number(pair.score || 0) });
+        }
+      }));
+
+      els.results.innerHTML = out.tokens.map(token => `
+        <div class="token-card">
+          <div class="token-text" title="${escapeAttr(token.token)}">${escapeHtml(token.token_text || token.token)}</div>
+          ${token.top.map(pair => scoreBadge(pair, annotationMeta, tokenTopAbsScore(token))).join("")}
+          ${predictionRow(token)}
+        </div>
+      `).join("");
+      els.results.querySelectorAll(".badge").forEach(node => {
+        node.addEventListener("click", event => selectComponent(event, Number(node.dataset.component), node.dataset.selectionKey));
+      });
+      paintHighlights();
+    }
+
+    function predictionRow(token) {
+      const pred = token.prediction;
+      if (!pred) return "";
+      const text = visibleToken(pred.token_text || pred.token || "");
+      return `
+        <div class="prediction-row" title="${escapeAttr(`next token: ${text}`)}">
+          <span class="prediction-label">next</span>
+          <span class="prediction-token">${escapeHtml(text)}</span>
+        </div>
+      `;
+    }
+
+    function scoreBadge(pair, annotationMeta, tokenTopAbs) {
+      const component = Number(pair.component);
+      const score = Number(pair.score || 0);
+      const selectionKey = componentSelectionKey(component, score);
+      const active = state.highlights.has(selectionKey);
+      const ratio = tokenTopAbs > 0 ? Math.abs(score) / tokenTopAbs : 0;
+      const width = 100 * Math.max(0, Math.min(1, ratio));
+      const meta = annotationForScore(annotationMeta.get(component), score);
+      const dot = meta ? `<span class="annotation-dot ${escapeAttr(meta.confidence)}" aria-hidden="true">${escapeHtml(meta.type_letter)}</span>` : "";
+      const label = meta ? meta.label : `C${component}`;
+      const title = meta ? `C${component}: ${annotationHint(meta)}` : `C${component}`;
+      const cutoff = Math.max(0, Math.min(1, Number(els.weakRatio.value || 0.5)));
+      const weak = Number.isFinite(tokenTopAbs) && tokenTopAbs > 0 && Math.abs(score) < tokenTopAbs * cutoff;
+      return `
+        <div class="score-row">
+          <button class="badge ${active ? "hot" : ""} ${weak ? "weak" : ""}" type="button" data-component="${component}" data-selection-key="${escapeAttr(selectionKey)}" data-score="${escapeAttr(score)}" aria-pressed="${active ? "true" : "false"}" title="${escapeAttr(title)}" style="--score-width:${width.toFixed(1)}%;--component-color:${componentColor(component)}">
+            <span class="badge-main">${dot}<b class="badge-label">${escapeHtml(label)}</b></span>
+          </button>
+          <span class="score">${formatScore(pair.score)}</span>
+        </div>
+      `;
+    }
+
+    function tokenTopAbsScore(token) {
+      const scores = (token.top || []).map(pair => Math.abs(Number(pair.score || 0)));
+      return scores.length ? Math.max(...scores) : 0;
+    }
+
+    function selectComponent(event, component, selectionKey) {
+      state.selectionPanelHidden = false;
+      if (event.ctrlKey || event.metaKey) {
+        if (state.highlights.has(selectionKey)) state.highlights.delete(selectionKey);
+        else state.highlights.add(selectionKey);
+      } else {
+        state.highlights.clear();
+        state.highlights.add(selectionKey);
+      }
+      persistHighlights();
+      paintHighlights();
+    }
+
+
+    function highlightStorageKey(model = els.model.value, layer = els.layer.value) {
+      return `${model}:${layer}`;
+    }
+
+    function readHighlightStore() {
+      try {
+        const parsed = JSON.parse(localStorage.getItem(STORAGE_KEYS.highlights) || "{}");
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+      } catch {
+        return {};
+      }
+    }
+
+    function persistHighlights() {
+      const store = readHighlightStore();
+      const key = highlightStorageKey();
+      const values = [...state.highlights].filter(isValidSelectionKey).sort(compareSelectionKeys);
+      if (values.length) store[key] = values;
+      else delete store[key];
+      localStorage.setItem(STORAGE_KEYS.highlights, JSON.stringify(store));
+    }
+
+    function restoreHighlightsForContext(out) {
+      const store = readHighlightStore();
+      const saved = Array.isArray(store[highlightStorageKey()]) ? store[highlightStorageKey()] : [];
+      state.highlights = new Set(saved.map(normalizeSelectionKey).filter(Boolean));
+    }
+
+    function paintHighlights() {
+      els.results.querySelectorAll(".badge").forEach(node => {
+        const active = state.highlights.has(node.dataset.selectionKey);
+        node.classList.toggle("hot", active);
+        node.setAttribute("aria-pressed", active ? "true" : "false");
+      });
+      renderSelectionPanel();
+      renderSelectionExport();
+    }
+
+    function renderSelectionPanel() {
+      const selections = [...state.highlights].filter(isValidSelectionKey).sort(compareSelectionKeys).map(parseSelectionKey);
+      els.selectionPanel.classList.toggle("visible", selections.length > 0 && !state.selectionPanelHidden);
+      els.selectionList.innerHTML = selections.map(selection => {
+        const component = selection.component;
+        const score = selection.sign * Math.abs(Number(state.currentScores?.get(component)?.score || 1));
+        ensureLayerComponentMeta();
+        ensureTokenStats(component);
+        ensureComponentNeighbors(component);
+        const stats = state.tokenStats.get(selectionStatsKey(component));
+        const neighbors = state.componentNeighbors.get(selectionStatsKey(component));
+        const sourceLabel = sourceSideLabel(componentMeta(component), score);
+        return `
+          <div class="selection-entry" style="--component-color:${componentColor(component)}">
+            <div class="selection-item">
+              <a class="selection-link" href="${escapeAttr(componentAnnotateUrl(component))}">
+                <span>${escapeHtml(els.layer.value)} C${component}${selection.sign < 0 ? " -" : " +"}</span>
+                <span class="selection-score">${selectionMetrics(component)}</span>
+              </a>
+              <div class="selection-token-stats">${renderTokenStats(stats)}</div>
+            </div>
+            ${renderComponentNeighbors(neighbors, score, sourceLabel)}
+          </div>
+        `;
+      }).join("");
+    }
+
+    function renderSelectionExport() {
+      const selections = [...state.highlights].filter(isValidSelectionKey).sort(compareSelectionKeys).map(parseSelectionKey);
+      if (!selections.length) {
+        els.selectionExport.classList.remove("visible");
+        els.selectionExportCopy.classList.remove("visible");
+        els.selectionExportToggle.classList.remove("visible");
+        els.selectionExport.value = "";
+        return;
+      }
+      const selection = selections[0];
+      els.selectionExport.value = componentExportText(selection);
+      els.selectionExportToggle.classList.add("visible");
+      els.selectionExportToggle.textContent = state.selectionExportHidden ? "Show text" : "Hide text";
+      els.selectionExport.classList.toggle("visible", !state.selectionExportHidden);
+      els.selectionExportCopy.classList.toggle("visible", !state.selectionExportHidden);
+    }
+
+    function componentExportText(selection) {
+      const component = selection.component;
+      const meta = componentMeta(component);
+      const erf = Number(meta?.effective_context_mean);
+      const erfText = Number.isFinite(erf) ? Number(erf).toFixed(1).replace(/\.0$/, "") : "?";
+      const activations = componentTokenActivations(component, selection.sign);
+      const activationLines = activations.length
+        ? activations.map(item => `${item.index}: ${item.token} -> ${item.score.toFixed(1)}`).join("\n")
+        : "(component is not present in the current top-k token activations)";
+      return [
+        `[Component C${component}, Effective Receptive Field=${erfText}]`,
+        "",
+        "INPUT TEXT:",
+        els.text.value,
+        "",
+        "TOKEN ACTIVATIONS:",
+        activationLines,
+        "",
+        "",
+      ].join("\n");
+    }
+
+    function componentTokenActivations(component, sign) {
+      const rows = [];
+      (state.lastProbeOutput?.tokens || []).forEach(token => {
+        const item = (token.top || []).find(pair => Number(pair.component) === Number(component));
+        if (!item) return;
+        const score = Number(item.score || 0);
+        if (!Number.isFinite(score) || score === 0) return;
+        if ((score < 0 ? -1 : 1) !== sign) return;
+        rows.push({ index: Number(token.position), token: exportTokenText(token.token_text || token.token), score });
+      });
+      return rows.sort((a, b) => Math.abs(b.score) - Math.abs(a.score));
+    }
+
+    async function copySelectionExport() {
+      const text = els.selectionExport.value;
+      if (!text) return;
+      try {
+        await navigator.clipboard.writeText(text);
+      } catch {
+        els.selectionExport.focus();
+        els.selectionExport.select();
+        document.execCommand("copy");
+        els.selectionExport.setSelectionRange(0, 0);
+      }
+      const previous = els.selectionExportCopy.textContent;
+      els.selectionExportCopy.textContent = "Copied";
+      window.setTimeout(() => { els.selectionExportCopy.textContent = previous; }, 900);
+    }
+
+    function selectionMetrics(component) {
+      const parts = [];
+      const meta = componentMeta(component);
+      const ecl = meta?.effective_context_mean;
+      const kurtosis = meta?.excess_kurtosis;
+      if (Number.isFinite(ecl)) parts.push(`ERF=${Number(ecl).toFixed(1)}`);
+      if (Number.isFinite(kurtosis)) parts.push(`K=${Number(kurtosis).toFixed(1)}`);
+      return escapeHtml(parts.join(" · "));
+    }
+
+    function selectionStatsKey(component) {
+      return `${els.model.value}:${els.layer.value}:${component}`;
+    }
+
+    function layerMetaKey(model = els.model.value, layer = els.layer.value) {
+      return `${model}:${layer}`;
+    }
+
+    function componentMeta(component) {
+      return state.annotationMeta?.get(component) || state.layerComponentMeta.get(layerMetaKey())?.get(Number(component)) || null;
+    }
+
+    function ensureLayerComponentMeta() {
+      const key = layerMetaKey();
+      if (state.layerComponentMeta.has(key) || state.layerComponentMetaLoading.has(key)) return;
+      state.layerComponentMetaLoading.add(key);
+      const params = new URLSearchParams({
+        model: state.meta?.model_name || els.model.value,
+        layer: els.layer.value,
+      });
+      api(`/api/components?${params.toString()}`)
+        .then(data => {
+          state.layerComponentMeta.set(key, componentMetaMap(data.components || []));
+          renderSelectionPanel();
+          renderSelectionExport();
+        })
+        .catch(() => {
+          state.layerComponentMeta.set(key, new Map());
+        })
+        .finally(() => {
+          state.layerComponentMetaLoading.delete(key);
+        });
+    }
+
+    function componentSelectionKey(component, score) {
+      return `${Number(component)}:${Number(score) < 0 ? "-" : "+"}`;
+    }
+
+    function normalizeSelectionKey(value) {
+      if (typeof value === "number" && Number.isFinite(value)) return `${value}:+`;
+      const text = String(value || "");
+      if (/^\d+:[+-]$/.test(text)) return text;
+      const legacy = Number(text);
+      return Number.isFinite(legacy) ? `${legacy}:+` : "";
+    }
+
+    function isValidSelectionKey(value) {
+      return /^\d+:[+-]$/.test(String(value || ""));
+    }
+
+    function parseSelectionKey(value) {
+      const [component, sign] = String(value).split(":");
+      return { component: Number(component), sign: sign === "-" ? -1 : 1 };
+    }
+
+    function compareSelectionKeys(a, b) {
+      const aa = parseSelectionKey(a);
+      const bb = parseSelectionKey(b);
+      return aa.component - bb.component || bb.sign - aa.sign;
+    }
+
+    function hasHighlightedComponent(component) {
+      return state.highlights.has(`${Number(component)}:+`) || state.highlights.has(`${Number(component)}:-`);
+    }
+
+    function ensureTokenStats(component) {
+      const key = selectionStatsKey(component);
+      if (state.tokenStats.has(key)) return;
+      const retries = state.tokenStatsRetries.get(key) || 0;
+      if (retries >= 2) {
+        state.tokenStats.set(key, { error: "token stats unavailable", tokens: [] });
+        return;
+      }
+      state.tokenStatsRetries.set(key, retries + 1);
+      state.tokenStats.set(key, null);
+      const params = new URLSearchParams({
+        model: state.meta?.model_name || els.model.value,
+        layer: els.layer.value,
+        component: String(component),
+      });
+      api(`/api/component-token-stats?${params.toString()}`)
+        .then(data => {
+          state.tokenStats.set(key, data);
+          if (hasHighlightedComponent(component) && key === selectionStatsKey(component)) renderSelectionPanel();
+        })
+        .catch(err => {
+          state.tokenStats.set(key, { error: err.message || "token stats unavailable", tokens: [] });
+          if (hasHighlightedComponent(component) && key === selectionStatsKey(component)) renderSelectionPanel();
+        });
+    }
+
+    function ensureComponentNeighbors(component) {
+      const key = selectionStatsKey(component);
+      if (state.componentNeighbors.has(key)) return;
+      const retries = state.componentNeighborsRetries.get(key) || 0;
+      if (retries >= 2) {
+        state.componentNeighbors.set(key, { error: "neighbors unavailable", neighbors: [] });
+        return;
+      }
+      state.componentNeighborsRetries.set(key, retries + 1);
+      state.componentNeighbors.set(key, null);
+      const params = new URLSearchParams({
+        model: state.meta?.model_name || els.model.value,
+        layer: els.layer.value,
+        component: String(component),
+      });
+      api(`/api/component-neighbors?${params.toString()}`)
+        .then(data => {
+          state.componentNeighbors.set(key, data);
+          if (hasHighlightedComponent(component) && key === selectionStatsKey(component)) renderSelectionPanel();
+        })
+        .catch(err => {
+          state.componentNeighbors.set(key, { error: err.message || "neighbors unavailable", neighbors: [] });
+          if (hasHighlightedComponent(component) && key === selectionStatsKey(component)) renderSelectionPanel();
+        });
+    }
+
+    function renderComponentNeighbors(data, sourceScore, sourceLabel) {
+      if (data === null) {
+        return `
+          <div class="selection-neighbors">
+            ${renderLoadingNeighbor("prev")}
+          ${renderLoadingNeighbor("next")}
+          </div>
+        `;
+      }
+      const byDirection = new Map((data?.neighbors || []).map(item => [item.direction, item]));
+      return `
+        <div class="selection-neighbors">
+          ${renderNeighborCard(byDirection.get("prev"), "prev", sourceScore, sourceLabel)}
+          ${renderNeighborCard(byDirection.get("next"), "next", sourceScore, sourceLabel)}
+        </div>
+      `;
+    }
+
+    function renderNeighborCard(neighbor, direction, sourceScore, sourceLabel) {
+      if (!neighbor) return renderMissingNeighbor(direction);
+      const layer = String(neighbor.neighbor_layer || "");
+      const component = Number(neighbor.neighbor_component);
+      const label = neighborLabel(neighbor, sourceScore, sourceLabel);
+      const cos = Number(neighbor.abs_cosine);
+      const href = componentAnnotateUrl(component, layer);
+      return `
+        <a class="neighbor-card" href="${escapeAttr(href)}" title="${escapeAttr(`${direction}: ${layer} C${component} ${label}`)}">
+          <span class="neighbor-target">${escapeHtml(`${layer} C${component}`)}</span>
+          <span class="neighbor-label">${escapeHtml(label)}</span>
+          <span class="neighbor-metrics">${neighborMetrics(neighbor)}</span>
+          <span class="neighbor-cos" style="--cos-width:${cosWidth(cos)}%">cos=${Number.isFinite(cos) ? cos.toFixed(3) : "?"}</span>
+        </a>
+      `;
+    }
+
+    function renderMissingNeighbor(direction) {
+      return `
+        <div class="neighbor-card missing" aria-hidden="true">
+          <span class="neighbor-target"></span>
+          <span class="neighbor-label"></span>
+          <span class="neighbor-metrics"></span>
+          <span class="neighbor-cos"></span>
+        </div>
+      `;
+    }
+
+    function renderLoadingNeighbor(direction) {
+      return `
+        <div class="neighbor-card loading">
+          <span class="neighbor-target">loading</span>
+          <span class="neighbor-label"></span>
+          <span class="neighbor-metrics"></span>
+          <span class="neighbor-cos"></span>
+        </div>
+      `;
+    }
+
+    function neighborLabel(neighbor, sourceScore, sourceLabel) {
+      const positive = visibleAnnotationLabel(neighbor?.positive_label, neighbor?.positive_confidence);
+      const negative = visibleAnnotationLabel(neighbor?.negative_label, neighbor?.negative_confidence);
+      const positiveMatch = labelSimilarity(sourceLabel, positive);
+      const negativeMatch = labelSimilarity(sourceLabel, negative);
+      if (positiveMatch > negativeMatch && positiveMatch > 0) return positive;
+      if (negativeMatch > positiveMatch && negativeMatch > 0) return negative;
+      const sourceSign = Number(sourceScore) < 0 ? -1 : 1;
+      const neighborSign = Number(neighbor?.neighbor_sign) < 0 ? -1 : 1;
+      if (sourceSign * neighborSign < 0) return negative || "unlabeled";
+      return positive || "unlabeled";
+    }
+
+    function cosWidth(value) {
+      const cos = Math.max(0, Math.min(1, Number(value) || 0));
+      return (100 * cos).toFixed(1);
+    }
+
+    function neighborMetrics(neighbor) {
+      const parts = [];
+      const ecl = Number(neighbor?.effective_context_mean);
+      const kurtosis = Number(neighbor?.excess_kurtosis);
+      if (Number.isFinite(ecl)) parts.push(`ERF=${ecl.toFixed(1)}`);
+      if (Number.isFinite(kurtosis)) parts.push(`K=${kurtosis.toFixed(1)}`);
+      return escapeHtml(parts.join(" · "));
+    }
+
+    function sourceSideLabel(meta, score) {
+      if (!meta) return "";
+      return Number(score) < 0
+        ? visibleAnnotationLabel(meta.negative_label, meta.negative_confidence)
+        : visibleAnnotationLabel(meta.positive_label, meta.positive_confidence);
+    }
+
+    function labelSimilarity(a, b) {
+      const aTokens = labelTokens(a);
+      const bTokens = labelTokens(b);
+      if (!aTokens.size || !bTokens.size) return 0;
+      let overlap = 0;
+      aTokens.forEach(token => { if (bTokens.has(token)) overlap += 1; });
+      return overlap / Math.max(aTokens.size, bTokens.size);
+    }
+
+    function labelTokens(value) {
+      const text = String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+      if (!text || text === "?") return new Set();
+      return new Set(text.split(/\s+/).filter(Boolean));
+    }
+
+    function renderTokenStats(stats) {
+      if (stats === null) return `<span>loading tokens...</span>`;
+      if (stats?.error) return `<span>${escapeHtml(stats.error)}</span>`;
+      const tokens = stats?.tokens || [];
+      if (!tokens.length) return `<span>no example tokens</span>`;
+      const maxCount = Math.max(1, ...tokens.map(item => Number(item.count || 0)));
+      const tokenChips = tokens.map(item => `
+        <span class="selection-token-chip" title="${escapeAttr(`${visibleToken(item.token)}: ${item.count}`)}" style="--token-font-size:${tokenFontSize(item.count, maxCount)}px">
+          <span class="selection-token-text">${escapeHtml(visibleToken(item.token))}</span>
+        </span>
+      `).join("");
+      return tokenChips;
+    }
+
+    function tokenFontSize(count, maxCount) {
+      const value = Math.max(0, Number(count || 0));
+      const ratio = maxCount <= 1 ? 0 : Math.log1p(value) / Math.log1p(maxCount);
+      return (9 + 5 * ratio).toFixed(1);
+    }
+
+    function visibleToken(value) {
+      const text = String(value || "");
+      if (text === " ") return "[space]";
+      if (text === "\n") return "[newline]";
+      return text.replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+    }
+
+    function exportTokenText(value) {
+      const text = String(value || "");
+      if (text === ".") return "period";
+      if (text === ",") return "comma";
+      if (text === " ") return "[space]";
+      if (text === "\n") return "[newline]";
+      return visibleToken(text).trim() || visibleToken(text);
+    }
+
+    function componentAnnotateUrl(component, layer = els.layer.value) {
+      const params = new URLSearchParams({
+        model: state.meta?.model_name || els.model.value,
+        layer,
+        component: String(component),
+      });
+      return `/annotate?${params.toString()}`;
+    }
+
+    async function loadModelMeta(options = {}) {
+      state.meta = await api(`/api/meta?model=${encodeURIComponent(els.model.value)}`);
+      els.layer.innerHTML = state.meta.layers.map(layer => `<option value="${escapeAttr(layer)}">${escapeHtml(layer)}</option>`).join("");
+      if (!state.meta.layers.length) throw new Error(`No ICA layers are available for ${state.meta.display_name || state.meta.model_name}.`);
+      const savedLayer = localStorage.getItem(STORAGE_KEYS.layer);
+      if (options.restoreLayer && savedLayer && state.meta.layers.includes(savedLayer)) els.layer.value = savedLayer;
+    }
+
+    function restoreControlValues() {
+      setNumberInputFromStorage(els.topK, STORAGE_KEYS.topK, 1, 32);
+      setNumberInputFromStorage(els.cardWidth, STORAGE_KEYS.cardWidth, 100, 360);
+      setNumberInputFromStorage(els.weakRatio, STORAGE_KEYS.weakRatio, 0, 1);
+      els.keepModels.checked = localStorage.getItem(STORAGE_KEYS.keepModels) !== "0";
+    }
+
+    function setNumberInputFromStorage(input, key, min, max) {
+      const raw = localStorage.getItem(key);
+      if (raw === null) return;
+      const value = Number(raw);
+      if (!Number.isFinite(value)) return;
+      input.value = String(Math.max(min, Math.min(max, value)));
+    }
+
+    function persistControls() {
+      localStorage.setItem(STORAGE_KEYS.model, els.model.value);
+      localStorage.setItem(STORAGE_KEYS.layer, els.layer.value);
+      localStorage.setItem(STORAGE_KEYS.topK, els.topK.value);
+      localStorage.setItem(STORAGE_KEYS.cardWidth, els.cardWidth.value);
+      localStorage.setItem(STORAGE_KEYS.weakRatio, els.weakRatio.value);
+      localStorage.setItem(STORAGE_KEYS.keepModels, els.keepModels.checked ? "1" : "0");
+    }
+
+    function showError(message) {
+      els.message.hidden = false;
+      els.message.className = "error";
+      els.message.textContent = message;
+    }
+
+    function componentColor(componentId) {
+      return `hsl(${(37 * Number(componentId)) % 360} 78% 48%)`;
+    }
+
+    function annotationMetaMap(raw) {
+      const out = new Map();
+      if (!Array.isArray(raw)) return out;
+      raw.forEach(item => {
+        const component = Number(item?.component);
+        if (!Number.isFinite(component)) return;
+        out.set(component, {
+          positive_label: String(item.positive_label || "").trim(),
+          positive_confidence: normalizedConfidence(item.positive_confidence),
+          positive_types: Array.isArray(item.positive_types) ? item.positive_types.map(String) : [],
+          negative_label: String(item.negative_label || "").trim(),
+          negative_confidence: normalizedConfidence(item.negative_confidence),
+          negative_types: Array.isArray(item.negative_types) ? item.negative_types.map(String) : [],
+          excess_kurtosis: Number.isFinite(Number(item.excess_kurtosis)) ? Number(item.excess_kurtosis) : null,
+          effective_context_mean: Number.isFinite(Number(item.effective_context_mean)) ? Number(item.effective_context_mean) : null,
+        });
+      });
+      return out;
+    }
+
+    function componentMetaMap(raw) {
+      const out = new Map();
+      if (!Array.isArray(raw)) return out;
+      raw.forEach(item => {
+        const component = Number(item?.component);
+        if (!Number.isFinite(component)) return;
+        out.set(component, {
+          positive_label: String(item.positive_label || "").trim(),
+          positive_confidence: normalizedConfidence(item.positive_confidence),
+          positive_types: Array.isArray(item.positive_types) ? item.positive_types.map(String) : [],
+          negative_label: String(item.negative_label || "").trim(),
+          negative_confidence: normalizedConfidence(item.negative_confidence),
+          negative_types: Array.isArray(item.negative_types) ? item.negative_types.map(String) : [],
+          excess_kurtosis: Number.isFinite(Number(item.excess_kurtosis)) ? Number(item.excess_kurtosis) : null,
+          effective_context_mean: Number.isFinite(Number(item.effective_context_mean)) ? Number(item.effective_context_mean) : null,
+        });
+      });
+      return out;
+    }
+
+    function annotationForScore(meta, score) {
+      if (!meta) return null;
+      const positive = Number(score || 0) >= 0;
+      const label = positive ? meta.positive_label : meta.negative_label;
+      const confidence = positive ? meta.positive_confidence : meta.negative_confidence;
+      const types = positive ? meta.positive_types : meta.negative_types;
+      if (!visibleAnnotationLabel(label, confidence)) return null;
+      return {
+        label: visibleAnnotationLabel(label, confidence),
+        confidence,
+        type_letter: typeLetter(types),
+      };
+    }
+
+    function annotationHint(meta) {
+      return `${meta.label} (${meta.confidence})`;
+    }
+
+    function visibleAnnotationLabel(value, confidence) {
+      const text = String(value || "").trim();
+      if (!text) return "";
+      if (text === "?" && normalizedConfidence(confidence) === "unclear") return "";
+      return text.replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+    }
+
+    function normalizedConfidence(value) {
+      const confidence = String(value || "unclear").toLowerCase();
+      return ["high", "medium", "low", "unclear"].includes(confidence) ? confidence : "unclear";
+    }
+
+    function typeLetter(types) {
+      const labels = Array.isArray(types) ? types : [];
+      const priority = [
+        ["Form", "F"],
+        ["Word", "W"],
+        ["Phrase", "P"],
+        ["Sentence", "S"],
+        ["Long-Range Context", "L"],
+        ["Global", "G"],
+        ["Position", "O"],
+        ["Sophisticated", "X"],
+      ];
+      for (const [name, letter] of priority) {
+        if (labels.some(label => String(label).toLowerCase() === name.toLowerCase())) return letter;
+      }
+      const first = labels.find(label => String(label).trim());
+      return first ? String(first).trim()[0].toUpperCase() : "";
+    }
+
+    function formatScore(value) {
+      const abs = Math.abs(value);
+      if (abs >= 100) return value.toFixed(0);
+      if (abs >= 10) return value.toFixed(1);
+      return value.toFixed(2);
+    }
+
+    function escapeHtml(value) {
+      return String(value).replace(/[&<>"']/g, char => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
+    }
+
+    function escapeAttr(value) {
+      return escapeHtml(value);
+    }
+
+    els.model.addEventListener("change", async () => {
+      persistHighlights();
+      state.highlights.clear();
+      state.tokenStats.clear();
+      state.tokenStatsRetries.clear();
+      state.componentNeighbors.clear();
+      state.componentNeighborsRetries.clear();
+      persistControls();
+      try {
+        await loadModelMeta();
+        persistControls();
+        runProbe();
+      } catch (err) {
+        showError(err.message);
+      }
+    });
+    els.layer.addEventListener("change", () => {
+      persistHighlights();
+      state.highlights.clear();
+      state.componentNeighbors.clear();
+      state.componentNeighborsRetries.clear();
+      persistControls();
+      runProbe();
+    });
+    els.topK.addEventListener("change", () => { persistControls(); runProbe(); });
+    els.topK.addEventListener("input", () => { persistControls(); runProbe(); });
+    els.cardWidth.addEventListener("change", updateCardWidth);
+    els.cardWidth.addEventListener("input", updateCardWidth);
+    els.weakRatio.addEventListener("change", () => { persistControls(); rerenderLastProbe(); });
+    els.keepModels.addEventListener("change", () => { persistControls(); if (!els.keepModels.checked) runProbe(); });
+    els.selectionClose.addEventListener("click", () => {
+      state.selectionPanelHidden = true;
+      renderSelectionPanel();
+    });
+    els.selectionExportToggle.addEventListener("click", () => {
+      state.selectionExportHidden = !state.selectionExportHidden;
+      renderSelectionExport();
+    });
+    els.selectionExportCopy.addEventListener("click", copySelectionExport);
+    els.weakRatio.addEventListener("input", () => { persistControls(); rerenderLastProbe(); });
+    els.text.addEventListener("input", scheduleProbe);
+    els.text.addEventListener("keydown", handleTextKeydown);
+    els.runProbe.addEventListener("click", () => {
+      localStorage.setItem(STORAGE_KEYS.probeText, els.text.value);
+      persistControls();
+      runProbe();
+    });
+    updateCardWidth();
+    init();
+  </script>
+</body>
+</html>

server/static/random_components.html

@@ -0,0 +1,163 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Random ICA Components</title>
+  <style>
+    :root { --bg:#f8fafc; --panel:#fff; --text:#0f172a; --muted:#64748b; --border:#cbd5e1; --accent:#2563eb; --subtle:#f1f5f9; --shadow:0 1px 2px rgb(15 23 42 / .08),0 8px 24px rgb(15 23 42 / .05); }
+    * { box-sizing:border-box; }
+    body { margin:0; background:var(--bg); color:var(--text); font:14px/1.45 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif; }
+    header { position:sticky; top:0; z-index:5; background:#fff; border-bottom:1px solid var(--border); padding:12px 16px; box-shadow:var(--shadow); }
+    .top { display:flex; justify-content:space-between; align-items:center; gap:12px; flex-wrap:wrap; }
+    h1 { margin:0; font-size:20px; }
+    nav { display:flex; gap:6px; }
+    nav a { color:var(--muted); text-decoration:none; padding:7px 10px; border-radius:7px; font-weight:650; }
+    nav a:hover, nav a.active { color:var(--accent); background:#eff6ff; }
+    .toolbar { display:flex; align-items:end; flex-wrap:wrap; gap:10px; margin-top:10px; }
+    label { color:#475569; font-size:12px; font-weight:700; }
+    select,input,button { font:inherit; border:1px solid var(--border); border-radius:7px; padding:7px 9px; background:#fff; color:var(--text); }
+    button { cursor:pointer; background:var(--subtle); font-weight:750; }
+    button:hover { color:var(--accent); border-color:var(--accent); background:#eff6ff; }
+    main { padding:14px; }
+    .panel { background:var(--panel); border:1px solid var(--border); border-radius:8px; box-shadow:var(--shadow); padding:12px; }
+    .summary { color:var(--muted); margin-bottom:10px; }
+    .run { margin-top:14px; }
+    .run h2 { display:flex; align-items:baseline; justify-content:space-between; gap:10px; margin:0 0 8px; font-size:16px; }
+    .run-meta { color:var(--muted); font-size:12px; font-weight:500; }
+    table { width:100%; border-collapse:collapse; background:#fff; }
+    th,td { border-bottom:1px solid #e2e8f0; padding:8px 9px; text-align:left; vertical-align:top; }
+    th { position:sticky; top:94px; background:#f8fafc; color:#475569; font-size:12px; text-transform:uppercase; letter-spacing:.02em; z-index:1; }
+    tr:hover td { background:#f8fafc; }
+    a { color:var(--accent); text-decoration:none; font-weight:800; }
+    a:hover { text-decoration:underline; }
+    .muted { color:var(--muted); }
+    .pill { display:inline-flex; border:1px solid var(--border); border-radius:999px; padding:1px 7px; color:var(--muted); background:#fff; font-size:12px; font-weight:750; white-space:nowrap; }
+    .label { max-width:360px; color:#334155; }
+    .label-badge { display:inline-flex; align-items:center; border-radius:999px; padding:2px 8px; font-size:12px; font-weight:850; line-height:1.3; }
+    .label-badge.high { color:#166534; background:#dcfce7; border:1px solid #86efac; }
+    .label-badge.medium { color:#854d0e; background:#fef3c7; border:1px solid #fde68a; }
+    .label-badge.low { color:#9f1239; background:#ffe4e6; border:1px solid #f9a8d4; }
+    .label-badge.unclear { color:#475569; background:#e5e7eb; border:1px solid #cbd5e1; }
+    .status { margin-left:auto; color:var(--muted); }
+    .empty,.error { border:1px dashed var(--border); border-radius:8px; padding:18px; color:var(--muted); background:#fff; }
+    .error { color:#991b1b; border-color:#fecaca; background:#fef2f2; }
+    @media(max-width:760px){ th:nth-child(5),td:nth-child(5),th:nth-child(6),td:nth-child(6){display:none;} }
+  </style>
+</head>
+<body>
+<header>
+  <div class="top">
+    <h1>Random ICA Components</h1>
+    <nav aria-label="Primary">
+      <a href="/">Explorer</a>
+      <a href="/sae-explorer">SAE Explorer</a>
+      <a href="/stats">Stats</a>
+      <a href="/annotate">Annotate</a>
+      <a href="/random-components" class="active">Random</a>
+    </nav>
+  </div>
+  <div class="toolbar">
+    <label>Model<br><select id="model"><option value="">all models</option></select></label>
+    <label style="flex:1;min-width:260px">Selection<br><input id="selection" placeholder="optional: random_components_n50_seed20260524" /></label>
+    <button id="load">Load</button>
+    <span id="status" class="status"></span>
+  </div>
+</header>
+<main>
+  <section class="panel">
+    <div id="summary" class="summary">Loading random component selections...</div>
+    <div id="content"></div>
+  </section>
+</main>
+<script>
+const state = { models: [] };
+const el = Object.fromEntries(["model","selection","load","status","summary","content"].map(id=>[id,document.getElementById(id)]));
+async function api(path){ const r=await fetch(path); if(!r.ok){let msg=await r.text(); try{msg=JSON.parse(msg).detail||msg}catch{} throw new Error(msg)} return r.json(); }
+function esc(s){return String(s??"").replace(/[&<>"']/g,c=>({"&":"&amp;","<":"&lt;",">":"&gt;","\"":"&quot;","'":"&#39;"}[c]));}
+function setStatus(text){ el.status.textContent = text || ""; }
+async function init(){
+  const params = new URLSearchParams(location.search);
+  el.selection.value = params.get("selection") || "random_components_n50_seed0";
+  const requestedModel = params.get("model") || "qwen3_5_2b_base";
+  try {
+    const models = await api("/api/models");
+    state.models = models.models || [];
+    el.model.innerHTML = `<option value="">all models</option>` + state.models.map(m=>`<option value="${esc(m.model_name)}">${esc(m.display_name || m.model_name)}</option>`).join("");
+    el.model.value = requestedModel;
+  } catch {}
+  el.load.onclick = () => loadRuns(true);
+  el.model.onchange = () => loadRuns(true);
+  el.selection.onkeydown = event => { if(event.key === "Enter") loadRuns(true); };
+  await loadRuns(false);
+}
+async function loadRuns(push){
+  setStatus("Loading...");
+  el.content.innerHTML = "";
+  try {
+    const params = new URLSearchParams();
+    if(el.model.value) params.set("model", el.model.value);
+    if(el.selection.value.trim()) params.set("selection", el.selection.value.trim());
+    if(push) history.replaceState(null, "", `/random-components${params.toString() ? `?${params}` : ""}`);
+    const data = await api(`/api/random-components${params.toString() ? `?${params}` : ""}`);
+    render(data);
+    setStatus("");
+  } catch (error) {
+    el.summary.textContent = "";
+    el.content.innerHTML = `<div class="error">${esc(error.message)}</div>`;
+    setStatus("");
+  }
+}
+function render(data){
+  const runs = data.runs || [];
+  const total = runs.reduce((sum, run) => sum + Number(run.selected_size || 0), 0);
+  el.summary.textContent = `${runs.length} selection file${runs.length===1?"":"s"} - ${total} selected components`;
+  el.content.innerHTML = runs.map(renderRun).join("") || '<div class="empty">No random component selections found.</div>';
+}
+function renderRun(run){
+  const settings = run.settings || {};
+  const rows = run.selected_components || [];
+  return `<section class="run">
+    <h2>
+      <span>${esc(run.model)}</span>
+      <span class="run-meta">n=${esc(settings.n)} seed=${esc(settings.seed)} inventory=${esc(run.inventory_size)} selection=${esc(run.selection_name || "")}</span>
+    </h2>
+    <table>
+      <thead><tr><th>#</th><th>Component</th><th>Annotate</th><th>K</th><th>Current label</th></tr></thead>
+      <tbody>${rows.map((item,index)=>renderRow(item,index)).join("")}</tbody>
+    </table>
+  </section>`;
+}
+function renderRow(item,index){
+  const annotation = item.annotation || {};
+  const sign = Number(item.top_abs_sign) < 0 ? -1 : 1;
+  const rawLabel = sign < 0 ? annotation.negative_label : annotation.positive_label;
+  const confidence = normalizeConfidence(sign < 0 ? annotation.negative_confidence : annotation.positive_confidence);
+  const label = visibleLabel(rawLabel);
+  const labels = label
+    ? `<span class="label-badge ${esc(confidence)}">${label}</span>`
+    : '<span class="label-badge unclear">unlabeled</span>';
+  const k = Number(item.excess_kurtosis);
+  const erf = Number(item.effective_context_mean);
+  const metrics = `${Number.isFinite(erf) ? `<span class="pill">ERF=${erf.toFixed(1)}</span>` : ""} ${Number.isFinite(k) ? `<span class="pill">K=${k.toFixed(1)}</span>` : ""}`;
+  return `<tr>
+    <td class="muted">${index + 1}</td>
+    <td><strong>${esc(item.layer)} C${esc(item.component_index)}</strong><br><span class="muted">${esc(item.component_id || "")}</span></td>
+    <td><a href="${esc(item.annotate_url)}">Annotate</a></td>
+    <td>${metrics || '<span class="muted">?</span>'}</td>
+    <td class="label">${labels}</td>
+  </tr>`;
+}
+function visibleLabel(value){
+  const text = String(value || "").trim();
+  if(!text) return "";
+  return esc(text);
+}
+function normalizeConfidence(value){
+  const text = String(value || "unclear").trim().toLowerCase();
+  return ["high","medium","low","unclear"].includes(text) ? text : "unclear";
+}
+init();
+</script>
+</body>
+</html>

server/static/sae_explorer.html

@@ -0,0 +1,673 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>SAE Explorer</title>
+  <style>
+    :root {
+      --bg: #f6f7f9;
+      --panel: #fff;
+      --text: #151922;
+      --muted: #647084;
+      --border: #cbd3df;
+      --accent: #1f6feb;
+      --shadow: 0 1px 2px rgb(20 25 34 / .08), 0 10px 30px rgb(20 25 34 / .06);
+      --token-card-width: 140px;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--text);
+      font: 14px/1.45 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+    header {
+      position: sticky;
+      top: 0;
+      z-index: 5;
+      background: var(--panel);
+      border-bottom: 1px solid var(--border);
+      box-shadow: var(--shadow);
+      padding: 12px 18px;
+    }
+    .top {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 14px;
+    }
+    h1 { margin: 0; font-size: 19px; letter-spacing: 0; }
+    .nav {
+      display: flex;
+      align-items: center;
+      gap: 14px;
+    }
+    .nav a {
+      color: var(--accent);
+      font-weight: 750;
+      text-decoration: none;
+    }
+    .nav a.active { color: #0f172a; }
+    .nav a:hover { text-decoration: underline; }
+    main {
+      max-width: 1240px;
+      margin: 0 auto;
+      padding: 18px;
+    }
+    .panel {
+      margin-top: 14px;
+      background: var(--panel);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      box-shadow: var(--shadow);
+      padding: 12px;
+    }
+    .controls {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) 450px;
+      gap: 12px;
+      align-items: stretch;
+    }
+    .control-stack {
+      display: flex;
+      flex-wrap: wrap;
+      align-content: flex-start;
+      align-items: center;
+      gap: 10px;
+    }
+    .inline-control {
+      display: grid;
+      grid-template-columns: max-content max-content;
+      align-items: center;
+      column-gap: 8px;
+    }
+    .inline-control > span { white-space: nowrap; }
+    .control-break { flex-basis: 100%; height: 0; }
+    label {
+      display: grid;
+      gap: 5px;
+      color: #435066;
+      font-size: 12px;
+      font-weight: 700;
+    }
+    textarea, select, input, button {
+      width: 100%;
+      border: 1px solid var(--border);
+      border-radius: 7px;
+      background: #fff;
+      color: var(--text);
+      font: inherit;
+      padding: 8px 10px;
+    }
+    textarea {
+      height: 92px;
+      min-height: 92px;
+      resize: vertical;
+      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    }
+    #topK { width: 58px; min-width: 0; }
+    #cardWidth { width: 78px; min-width: 0; }
+    #weakRatio { width: 58px; min-width: 0; }
+    button {
+      cursor: pointer;
+      min-height: 39px;
+      background: #eef2f7;
+      font-weight: 750;
+    }
+    .run-button {
+      width: auto;
+      min-height: 32px;
+      padding: 6px 12px;
+      border-color: #1458c8;
+      background: var(--accent);
+      color: #fff;
+      font-weight: 850;
+    }
+    .memory-control {
+      position: fixed;
+      right: 12px;
+      bottom: 10px;
+      z-index: 4;
+      display: inline-flex;
+      align-items: center;
+      gap: 5px;
+      width: auto;
+      min-height: 24px;
+      padding: 3px 6px;
+      border: 1px solid #d7dee9;
+      border-radius: 6px;
+      background: rgb(255 255 255 / .78);
+      color: #94a3b8;
+      font-size: 11px;
+      font-weight: 650;
+      white-space: nowrap;
+    }
+    .memory-control input { width: auto; margin: 0; padding: 0; accent-color: #94a3b8; }
+    .results {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(var(--token-card-width), 1fr));
+      gap: 10px;
+      margin-top: 12px;
+    }
+    .token-card {
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 6px;
+      background: #fff;
+      min-width: 0;
+      text-align: center;
+    }
+    .token-text {
+      min-height: 25px;
+      font-weight: 850;
+      text-align: center;
+      overflow-wrap: anywhere;
+      margin-bottom: 6px;
+    }
+    .score-row {
+      position: relative;
+      min-height: 24px;
+      margin-top: 3px;
+    }
+    .badge {
+      position: relative;
+      display: flex;
+      align-items: center;
+      width: 100%;
+      min-height: 24px;
+      padding: 3px 5px;
+      border: 1px solid #d5dce7;
+      border-radius: 5px;
+      background:
+        linear-gradient(
+          90deg,
+          var(--score-bg, #edf2f7) 0,
+          var(--score-bg, #edf2f7) var(--score-width, 100%),
+          transparent var(--score-width, 100%),
+          transparent 100%
+        );
+      color: var(--text);
+      font-size: 10px;
+      font-weight: 700;
+      text-align: left;
+      cursor: pointer;
+    }
+    .badge:hover {
+      border-color: var(--feature-color, var(--accent));
+    }
+    .badge.hot {
+      opacity: 1;
+      border-color: var(--feature-color, var(--accent));
+      --score-bg: color-mix(in srgb, var(--feature-color, var(--accent)) 18%, white);
+      box-shadow: inset 3px 0 0 var(--feature-color, var(--accent));
+    }
+    .badge.weak { opacity: .16; }
+    .badge.weak.hot,
+    .badge.weak:hover { opacity: 1; }
+    .badge-main {
+      min-width: 0;
+      max-width: calc(100% - 35px);
+      overflow: hidden;
+      white-space: nowrap;
+      text-overflow: ellipsis;
+    }
+    .score {
+      position: absolute;
+      right: 5px;
+      top: 50%;
+      transform: translateY(-50%);
+      width: 34px;
+      text-align: right;
+      color: var(--muted);
+      font-size: 9px;
+      font-variant-numeric: tabular-nums;
+      pointer-events: none;
+    }
+    .empty, .error {
+      margin-top: 12px;
+      border: 1px dashed var(--border);
+      border-radius: 8px;
+      padding: 18px;
+      color: var(--muted);
+      background: #fff;
+    }
+    .error { color: #a41414; border-color: #f0b9b9; background: #fff7f7; }
+    .request-indicator {
+      position: fixed;
+      left: 14px;
+      top: 62px;
+      z-index: 8;
+      display: none;
+      align-items: center;
+      gap: 8px;
+      min-height: 34px;
+      padding: 8px 10px;
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      background: var(--panel);
+      box-shadow: var(--shadow);
+      color: #435066;
+      font-size: 12px;
+      font-weight: 800;
+    }
+    .request-indicator.visible { display: inline-flex; }
+    .request-spinner {
+      width: 14px;
+      height: 14px;
+      border: 2px solid #cbd5e1;
+      border-top-color: var(--accent);
+      border-radius: 50%;
+      animation: request-spin .8s linear infinite;
+    }
+    @keyframes request-spin { to { transform: rotate(360deg); } }
+    .meta-line {
+      margin-top: 10px;
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 650;
+    }
+    @media (max-width: 760px) {
+      main { padding: 12px; }
+      .controls { grid-template-columns: 1fr; }
+      .top { align-items: flex-start; flex-direction: column; }
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="top">
+      <h1>SAE Explorer</h1>
+      <nav class="nav" aria-label="Primary">
+        <a href="/">Explorer</a>
+        <a href="/sae-explorer" class="active">SAE Explorer</a>
+        <a href="/stats">Stats</a>
+        <a href="/annotate">Annotate</a>
+        <a href="/random-components">Random</a>
+      </nav>
+    </div>
+  </header>
+
+  <main>
+    <div class="panel">
+      <div class="controls">
+        <label>
+          Text
+          <textarea id="probeText" spellcheck="false">Maya stopped at the bank before the trip, waiting in line to deposit a check and withdraw enough cash for the weekend.</textarea>
+        </label>
+        <div class="control-stack">
+          <label class="inline-control">
+            <span>Model</span>
+            <select id="modelSelect"></select>
+          </label>
+          <label class="inline-control">
+            <span>Layer</span>
+            <select id="layerSelect"></select>
+          </label>
+          <span class="control-break" aria-hidden="true"></span>
+          <label class="inline-control">
+            <span>Top K</span>
+            <input id="topK" type="number" min="1" max="128" value="5" />
+          </label>
+          <label class="inline-control">
+            <span>Card Width</span>
+            <input id="cardWidth" type="number" min="100" max="360" step="20" value="140" />
+          </label>
+          <label class="inline-control">
+            <span>Opacity Cutoff</span>
+            <input id="weakRatio" type="number" min="0" max="1" step="0.05" value="0.5" />
+          </label>
+          <button id="runProbe" class="run-button" type="button">Run</button>
+        </div>
+        <label class="memory-control" title="Keep loaded models in VRAM when switching.">
+          <input id="keepModels" type="checkbox" checked />
+          <span>Cache LLMs in VRAM</span>
+        </label>
+      </div>
+      <div id="metaLine" class="meta-line"></div>
+    </div>
+
+    <div id="message" class="empty">Choose a layer and run the SAE probe.</div>
+    <div id="results" class="results"></div>
+  </main>
+  <div id="requestIndicator" class="request-indicator" role="status" aria-live="polite">
+    <span class="request-spinner" aria-hidden="true"></span>
+    <span>Waiting for server...</span>
+  </div>
+
+  <script>
+    const STORAGE_KEYS = {
+      probeText: "saeExplorer.probeText",
+      model: "saeExplorer.model",
+      layer: "saeExplorer.layer",
+      topK: "saeExplorer.topK",
+      cardWidth: "saeExplorer.cardWidth",
+      weakRatio: "saeExplorer.opacityCutoff",
+      keepModels: "saeExplorer.keepModels",
+      highlights: "saeExplorer.selectedFeatures",
+    };
+
+    const state = {
+      models: [],
+      meta: null,
+      requestId: 0,
+      pendingRequests: 0,
+      lastProbeOutput: null,
+      selectedFeatures: new Set(),
+    };
+
+    const els = {
+      text: document.getElementById("probeText"),
+      model: document.getElementById("modelSelect"),
+      layer: document.getElementById("layerSelect"),
+      topK: document.getElementById("topK"),
+      cardWidth: document.getElementById("cardWidth"),
+      weakRatio: document.getElementById("weakRatio"),
+      runProbe: document.getElementById("runProbe"),
+      keepModels: document.getElementById("keepModels"),
+      metaLine: document.getElementById("metaLine"),
+      message: document.getElementById("message"),
+      results: document.getElementById("results"),
+      requestIndicator: document.getElementById("requestIndicator"),
+    };
+
+    async function api(path, options = {}) {
+      beginRequest();
+      try {
+        const res = await fetch(path, {
+          headers: { "content-type": "application/json" },
+          ...options,
+        });
+        if (!res.ok) {
+          let detail = res.statusText;
+          try { detail = (await res.json()).detail || detail; } catch {}
+          throw new Error(detail);
+        }
+        return res.json();
+      } finally {
+        endRequest();
+      }
+    }
+
+    function beginRequest() {
+      state.pendingRequests += 1;
+      els.requestIndicator.classList.toggle("visible", state.pendingRequests > 0);
+    }
+
+    function endRequest() {
+      state.pendingRequests = Math.max(0, state.pendingRequests - 1);
+      els.requestIndicator.classList.toggle("visible", state.pendingRequests > 0);
+    }
+
+    async function init() {
+      restoreControlValues();
+      const savedText = localStorage.getItem(STORAGE_KEYS.probeText);
+      if (savedText !== null) els.text.value = savedText;
+      try {
+        const modelsOut = await api("/api/models");
+        state.models = modelsOut.models || [];
+        els.model.innerHTML = state.models.map(model => `<option value="${escapeAttr(model.model_name)}">${escapeHtml(model.display_name || model.model_name)}</option>`).join("");
+        const savedModel = localStorage.getItem(STORAGE_KEYS.model);
+        if (savedModel && state.models.some(model => model.model_name === savedModel)) els.model.value = savedModel;
+        else if (state.models.some(model => model.model_name === "gpt2")) els.model.value = "gpt2";
+        await loadSaeMeta({ restoreLayer: true });
+        runProbe();
+      } catch (err) {
+        showError(err.message);
+      }
+    }
+
+    async function loadSaeMeta(options = {}) {
+      state.meta = await api(`/api/sae-meta?model=${encodeURIComponent(els.model.value)}`);
+      els.layer.innerHTML = state.meta.layers.map(layer => `<option value="${escapeAttr(layer)}">${escapeHtml(layer)}</option>`).join("");
+      const savedLayer = localStorage.getItem(STORAGE_KEYS.layer);
+      if (options.restoreLayer && savedLayer && state.meta.layers.includes(savedLayer)) els.layer.value = savedLayer;
+      else if (state.meta.layers.includes("layer_05")) els.layer.value = "layer_05";
+      restoreFeatureHighlightsForContext();
+      renderMetaLine();
+    }
+
+    function renderMetaLine() {
+      const sae = state.meta?.sae || {};
+      const parts = [
+        sae.repo_id ? `SAE: ${sae.repo_id}` : "",
+        sae.width ? `width=${sae.width}` : "",
+        sae.top_k ? `SAE top-k=${sae.top_k}` : "",
+        sae.activation ? `activation=${sae.activation}` : "",
+      ].filter(Boolean);
+      els.metaLine.textContent = parts.join(" · ");
+    }
+
+    async function runProbe() {
+      const requestId = ++state.requestId;
+      if (!els.text.value.trim()) {
+        els.results.innerHTML = "";
+        els.message.hidden = false;
+        els.message.className = "empty";
+        els.message.textContent = "Enter text to run the SAE probe.";
+        return;
+      }
+      if (!els.results.children.length) {
+        els.message.hidden = false;
+        els.message.className = "empty";
+        els.message.textContent = "Running SAE probe...";
+      }
+      try {
+        const out = await api("/api/sae-probe", {
+          method: "POST",
+          body: JSON.stringify({
+            text: els.text.value,
+            model_name: els.model.value,
+            layer: els.layer.value,
+            top_k: Number(els.topK.value || 5),
+            keep_models: els.keepModels.checked,
+          }),
+        });
+        if (requestId !== state.requestId) return;
+        renderResults(out);
+      } catch (err) {
+        if (requestId !== state.requestId) return;
+        showError(err.message);
+      }
+    }
+
+    function renderResults(out) {
+      state.lastProbeOutput = out;
+      if (out.truncated) {
+        els.message.hidden = false;
+        els.message.className = "empty";
+        els.message.textContent = `Input was truncated to ${out.max_length} tokens.`;
+      } else {
+        els.message.hidden = true;
+      }
+      els.results.innerHTML = (out.tokens || []).map(token => `
+        <div class="token-card">
+          <div class="token-text" title="${escapeAttr(token.token)}">${escapeHtml(token.token_text || token.token)}</div>
+          ${(token.top || []).map(feature => featureBadge(feature, tokenTopActivation(token))).join("")}
+        </div>
+      `).join("");
+      els.results.querySelectorAll(".badge[data-feature]").forEach(node => {
+        node.addEventListener("click", event => selectFeature(event, Number(node.dataset.feature)));
+      });
+      paintFeatureHighlights();
+    }
+
+    function featureBadge(feature, tokenTop) {
+      const id = Number(feature.feature);
+      const activation = Number(feature.activation || 0);
+      const ratio = tokenTop > 0 ? activation / tokenTop : 0;
+      const width = 100 * Math.max(0, Math.min(1, ratio));
+      const cutoff = Math.max(0, Math.min(1, Number(els.weakRatio.value || 0.5)));
+      const weak = Number.isFinite(tokenTop) && tokenTop > 0 && activation < tokenTop * cutoff;
+      const active = state.selectedFeatures.has(id);
+      return `
+        <div class="score-row">
+          <button class="badge ${active ? "hot" : ""} ${weak ? "weak" : ""}" type="button" data-feature="${id}" aria-pressed="${active ? "true" : "false"}" title="${escapeAttr(`F${id}: activation ${formatScore(activation)}, preactivation ${formatScore(Number(feature.preactivation || 0))}`)}" style="--score-width:${width.toFixed(1)}%;--score-bg:${featureColor(id)}22;--feature-color:${featureColor(id)}">
+            <span class="badge-main">F${id}</span>
+          </button>
+          <span class="score">${formatScore(activation)}</span>
+        </div>
+      `;
+    }
+
+    function tokenTopActivation(token) {
+      const values = (token.top || []).map(item => Number(item.activation || 0));
+      return values.length ? Math.max(...values) : 0;
+    }
+
+    function scheduleProbe() {
+      localStorage.setItem(STORAGE_KEYS.probeText, els.text.value);
+      persistControls();
+    }
+
+    function handleTextKeydown(event) {
+      if ((event.ctrlKey || event.metaKey) && event.key === "Enter") {
+        event.preventDefault();
+        localStorage.setItem(STORAGE_KEYS.probeText, els.text.value);
+        persistControls();
+        runProbe();
+      }
+    }
+
+    function updateCardWidth() {
+      const value = Math.max(100, Math.min(360, Number(els.cardWidth.value || 140)));
+      document.documentElement.style.setProperty("--token-card-width", `${value}px`);
+      localStorage.setItem(STORAGE_KEYS.cardWidth, String(value));
+    }
+
+    function rerenderLastProbe() {
+      if (state.lastProbeOutput) renderResults(state.lastProbeOutput);
+    }
+
+    function selectFeature(event, feature) {
+      const id = Number(feature);
+      if (!Number.isFinite(id)) return;
+      if (event.ctrlKey || event.metaKey) {
+        if (state.selectedFeatures.has(id)) state.selectedFeatures.delete(id);
+        else state.selectedFeatures.add(id);
+      } else if (state.selectedFeatures.size === 1 && state.selectedFeatures.has(id)) {
+        state.selectedFeatures.clear();
+      } else {
+        state.selectedFeatures.clear();
+        state.selectedFeatures.add(id);
+      }
+      persistFeatureHighlights();
+      paintFeatureHighlights();
+    }
+
+    function paintFeatureHighlights() {
+      els.results.querySelectorAll(".badge[data-feature]").forEach(node => {
+        const active = state.selectedFeatures.has(Number(node.dataset.feature));
+        node.classList.toggle("hot", active);
+        node.setAttribute("aria-pressed", active ? "true" : "false");
+      });
+    }
+
+    function featureHighlightStorageKey(model = els.model.value, layer = els.layer.value) {
+      return `${model}:${layer}`;
+    }
+
+    function readFeatureHighlightStore() {
+      try {
+        const parsed = JSON.parse(localStorage.getItem(STORAGE_KEYS.highlights) || "{}");
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+      } catch {
+        return {};
+      }
+    }
+
+    function persistFeatureHighlights() {
+      const store = readFeatureHighlightStore();
+      const key = featureHighlightStorageKey();
+      const values = [...state.selectedFeatures].filter(Number.isFinite).sort((a, b) => a - b);
+      if (values.length) store[key] = values;
+      else delete store[key];
+      localStorage.setItem(STORAGE_KEYS.highlights, JSON.stringify(store));
+    }
+
+    function restoreFeatureHighlightsForContext() {
+      const store = readFeatureHighlightStore();
+      const saved = Array.isArray(store[featureHighlightStorageKey()]) ? store[featureHighlightStorageKey()] : [];
+      state.selectedFeatures = new Set(saved.map(Number).filter(Number.isFinite));
+    }
+
+    function restoreControlValues() {
+      setNumberInputFromStorage(els.topK, STORAGE_KEYS.topK, 1, 128);
+      setNumberInputFromStorage(els.cardWidth, STORAGE_KEYS.cardWidth, 100, 360);
+      setNumberInputFromStorage(els.weakRatio, STORAGE_KEYS.weakRatio, 0, 1);
+      els.keepModels.checked = localStorage.getItem(STORAGE_KEYS.keepModels) !== "0";
+    }
+
+    function setNumberInputFromStorage(input, key, min, max) {
+      const raw = localStorage.getItem(key);
+      if (raw === null) return;
+      const value = Number(raw);
+      if (!Number.isFinite(value)) return;
+      input.value = String(Math.max(min, Math.min(max, value)));
+    }
+
+    function persistControls() {
+      localStorage.setItem(STORAGE_KEYS.model, els.model.value);
+      localStorage.setItem(STORAGE_KEYS.layer, els.layer.value);
+      localStorage.setItem(STORAGE_KEYS.topK, els.topK.value);
+      localStorage.setItem(STORAGE_KEYS.cardWidth, els.cardWidth.value);
+      localStorage.setItem(STORAGE_KEYS.weakRatio, els.weakRatio.value);
+      localStorage.setItem(STORAGE_KEYS.keepModels, els.keepModels.checked ? "1" : "0");
+    }
+
+    function showError(message) {
+      els.message.hidden = false;
+      els.message.className = "error";
+      els.message.textContent = message;
+    }
+
+    function featureColor(featureId) {
+      return `hsl(${(37 * Number(featureId)) % 360} 74% 48%)`;
+    }
+
+    function formatScore(value) {
+      const number = Number(value || 0);
+      const abs = Math.abs(number);
+      if (abs >= 100) return number.toFixed(0);
+      if (abs >= 10) return number.toFixed(1);
+      return number.toFixed(2);
+    }
+
+    function escapeHtml(value) {
+      return String(value).replace(/[&<>"']/g, char => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
+    }
+
+    function escapeAttr(value) {
+      return escapeHtml(value);
+    }
+
+    els.model.addEventListener("change", async () => {
+      persistControls();
+      try {
+        await loadSaeMeta();
+        persistControls();
+        runProbe();
+      } catch (err) {
+        showError(err.message);
+      }
+    });
+    els.layer.addEventListener("change", () => { persistControls(); restoreFeatureHighlightsForContext(); runProbe(); });
+    els.topK.addEventListener("change", () => { persistControls(); runProbe(); });
+    els.topK.addEventListener("input", () => { persistControls(); runProbe(); });
+    els.cardWidth.addEventListener("change", updateCardWidth);
+    els.cardWidth.addEventListener("input", updateCardWidth);
+    els.weakRatio.addEventListener("change", () => { persistControls(); rerenderLastProbe(); });
+    els.weakRatio.addEventListener("input", () => { persistControls(); rerenderLastProbe(); });
+    els.keepModels.addEventListener("change", () => { persistControls(); if (!els.keepModels.checked) runProbe(); });
+    els.text.addEventListener("input", scheduleProbe);
+    els.text.addEventListener("keydown", handleTextKeydown);
+    els.runProbe.addEventListener("click", () => {
+      localStorage.setItem(STORAGE_KEYS.probeText, els.text.value);
+      persistControls();
+      runProbe();
+    });
+    updateCardWidth();
+    init();
+  </script>
+</body>
+</html>

server/static/stats.html

@@ -0,0 +1,557 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>ICA Annotation Stats</title>
+  <style>
+    :root {
+      --bg: #f6f7f9;
+      --panel: #fff;
+      --text: #151922;
+      --muted: #647084;
+      --border: #cbd3df;
+      --accent: #1f6feb;
+      --shadow: 0 1px 2px rgb(20 25 34 / .08), 0 10px 30px rgb(20 25 34 / .06);
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      background: var(--bg);
+      color: var(--text);
+      font: 14px/1.45 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+    header {
+      position: sticky;
+      top: 0;
+      z-index: 5;
+      background: var(--panel);
+      border-bottom: 1px solid var(--border);
+      box-shadow: var(--shadow);
+      padding: 12px 18px;
+    }
+    .top {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 14px;
+    }
+    h1 { margin: 0; font-size: 19px; letter-spacing: 0; }
+    .nav {
+      display: flex;
+      align-items: center;
+      gap: 14px;
+    }
+    a {
+      color: var(--accent);
+      font-weight: 750;
+      text-decoration: none;
+    }
+    a:hover { text-decoration: underline; }
+    main {
+      width: 100%;
+      margin: 0;
+      padding: 12px;
+    }
+    .panel {
+      background: var(--panel);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      box-shadow: var(--shadow);
+      padding: 12px;
+    }
+    .toolbar {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 12px;
+      margin-bottom: 12px;
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 700;
+    }
+    .model-control {
+      display: inline-flex;
+      align-items: center;
+      gap: 7px;
+      color: #435066;
+      font-size: 12px;
+      font-weight: 800;
+      white-space: nowrap;
+    }
+    .model-control select {
+      width: 210px;
+      border: 1px solid var(--border);
+      border-radius: 7px;
+      background: #fff;
+      color: var(--text);
+      font: inherit;
+      padding: 7px 9px;
+    }
+    .layer-control select {
+      width: 160px;
+    }
+    .toolbar-left {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: 10px 14px;
+    }
+    .legend {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 8px 12px;
+      align-items: center;
+    }
+    .legend-item {
+      display: inline-flex;
+      align-items: center;
+      gap: 5px;
+      white-space: nowrap;
+    }
+    .legend-toggle {
+      width: auto;
+      border: 0;
+      background: transparent;
+      color: inherit;
+      font: inherit;
+      font-weight: inherit;
+      padding: 0;
+      cursor: pointer;
+    }
+    .legend-toggle:hover { color: var(--accent); }
+    .matrix {
+      overflow: visible;
+      border: 1px solid var(--border);
+      border-radius: 7px;
+      background: #fff;
+    }
+    .layer-row {
+      display: grid;
+      grid-template-columns: 104px 86px minmax(0, 1fr);
+      align-items: start;
+      gap: 8px;
+      width: 100%;
+      padding: 6px 8px;
+      border-bottom: 1px solid #e5eaf2;
+    }
+    .layer-row:last-child { border-bottom: 0; }
+    .layer-name {
+      font-weight: 850;
+      white-space: nowrap;
+    }
+    .layer-count {
+      color: var(--muted);
+      font-size: 12px;
+      font-variant-numeric: tabular-nums;
+      text-align: right;
+      white-space: nowrap;
+    }
+    .dots {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 3px;
+      align-items: flex-start;
+      min-width: 0;
+    }
+    .component-pair {
+      display: inline-flex;
+      gap: 1px;
+      margin-right: 2px;
+      flex: 0 0 auto;
+    }
+    .dot {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: 13px;
+      height: 14px;
+      border: 1px solid #cbd5e1;
+      border-radius: 4px;
+      background: #f8fafc;
+      color: #64748b;
+      font-size: 8px;
+      font-weight: 850;
+      line-height: 1;
+      font-variant-numeric: tabular-nums;
+      flex: 0 0 auto;
+      text-decoration: none;
+    }
+    .dot:hover { text-decoration: none; outline: 2px solid rgb(31 111 235 / .25); outline-offset: 1px; }
+    .dot.high { color: #fff; background: #16a34a; border-color: #15803d; }
+    .dot.medium { color: #166534; background: #fef3c7; border-color: #d9b94e; }
+    .dot.low { color: #9f1239; background: #ffe4e6; border-color: #f9a8d4; }
+    .dot.unclear { color: #475569; background: #e5e7eb; border-color: #cbd5e1; }
+    .dot.auto {
+      color: #3b2600;
+      background: #f6c343;
+      border-color: #b77900;
+      box-shadow: inset 0 0 0 1px rgb(255 255 255 / .38);
+    }
+    .dot.erf-value {
+      overflow: hidden;
+      font-size: 7px;
+    }
+    .empty, .error {
+      border: 1px dashed var(--border);
+      border-radius: 8px;
+      padding: 18px;
+      color: var(--muted);
+      background: #fff;
+    }
+    .error { color: #a41414; border-color: #f0b9b9; background: #fff7f7; }
+    @media (max-width: 760px) {
+      main { padding: 8px; }
+      header { padding: 10px 12px; }
+      .top { align-items: flex-start; flex-direction: column; }
+      .toolbar { align-items: flex-start; flex-direction: column; }
+      .layer-row { grid-template-columns: 74px 58px minmax(0, 1fr); gap: 6px; padding: 6px; }
+      .dot { width: 11px; height: 12px; border-radius: 3px; font-size: 7px; }
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="top">
+      <h1>ICA Annotation Stats</h1>
+      <nav class="nav" aria-label="Primary">
+        <a href="/">Explorer</a>
+        <a href="/sae-explorer">SAE Explorer</a>
+        <a href="/stats">Stats</a>
+        <a href="/annotate">Annotate</a>
+        <a href="/random-components">Random</a>
+      </nav>
+    </div>
+  </header>
+
+  <main>
+    <div class="panel">
+      <div class="toolbar">
+        <div class="toolbar-left">
+          <label class="model-control">
+            Model
+            <select id="modelSelect"></select>
+          </label>
+          <label class="model-control layer-control">
+            Layer
+            <select id="layerSelect" disabled></select>
+          </label>
+          <div id="summary">Please select a model.</div>
+        </div>
+        <div class="legend" aria-label="Confidence legend">
+          <span class="legend-item"><span class="dot high">W</span> high</span>
+          <span class="legend-item"><span class="dot medium">W</span> medium</span>
+          <span class="legend-item"><span class="dot low">W</span> low</span>
+          <span class="legend-item"><span class="dot unclear">?</span> unclear</span>
+          <button id="autoToggle" class="legend-item legend-toggle" type="button" aria-pressed="true" title="Toggle auto-annotation coloring"><span class="dot auto">W</span> auto</button>
+          <button id="erfToggle" class="legend-item legend-toggle" type="button" aria-pressed="false" title="Toggle Effective Receptive Field labels"><span class="dot erf-value">11</span> ERF</button>
+          <span class="legend-item"><span class="dot"></span> blank</span>
+        </div>
+      </div>
+      <div id="message" class="empty">Loading all component stats...</div>
+      <div id="matrix" class="matrix" hidden></div>
+    </div>
+  </main>
+  <script>
+    const els = {
+      model: document.getElementById("modelSelect"),
+      layer: document.getElementById("layerSelect"),
+      summary: document.getElementById("summary"),
+      message: document.getElementById("message"),
+      matrix: document.getElementById("matrix"),
+      autoToggle: document.getElementById("autoToggle"),
+      erfToggle: document.getElementById("erfToggle"),
+    };
+
+    const STORAGE_KEYS = {
+      model: "icaExplorer.model",
+      layer: "icaExplorer.layer",
+    };
+
+    const state = {
+      model: "",
+      layer: "",
+      layers: [],
+      showAuto: true,
+      showErf: false,
+    };
+
+    async function api(path) {
+      const res = await fetch(path, { headers: { "content-type": "application/json" } });
+      if (!res.ok) {
+        let detail = res.statusText;
+        try { detail = (await res.json()).detail || detail; } catch {}
+        throw new Error(detail);
+      }
+      return res.json();
+    }
+
+    async function init() {
+      try {
+        const params = new URLSearchParams(location.search);
+        const urlModel = params.get("model") || "";
+        const urlLayer = normalizeUrlLayer(params.get("layer") || "");
+        const storedModel = localStorage.getItem(STORAGE_KEYS.model) || "";
+        const storedLayer = localStorage.getItem(STORAGE_KEYS.layer) || "";
+        const requestedModel = urlModel || storedModel;
+        const requestedLayer = urlLayer || storedLayer;
+        const models = await api("/api/models");
+        const names = (models.models || []).map(model => model.model_name);
+        fillSelect(els.model, ["", ...names], names.includes(requestedModel) ? requestedModel : "");
+        els.model.options[0].textContent = "Please select";
+        fillSelect(els.layer, [""], "");
+        els.layer.options[0].textContent = "Please select";
+        state.model = els.model.value;
+        els.model.addEventListener("change", () => {
+          state.model = els.model.value;
+          state.layer = "";
+          persistSelection();
+          updateUrl();
+          loadLayers();
+        });
+        els.layer.addEventListener("change", () => {
+          state.layer = els.layer.value;
+          persistSelection();
+          updateUrl();
+          loadStats();
+        });
+        if (state.model) await loadLayers({ requestedLayer });
+        else clearStats("Please select a model.");
+      } catch (err) {
+        showError(err.message);
+      }
+    }
+
+    async function loadLayers(options = {}) {
+      state.layers = [];
+      els.matrix.innerHTML = "";
+      els.matrix.hidden = true;
+      if (!state.model) {
+        els.layer.disabled = true;
+        fillSelect(els.layer, [""], "");
+        els.layer.options[0].textContent = "Please select";
+        clearStats("Please select a model.");
+        return;
+      }
+      els.summary.textContent = "Loading layers...";
+      const out = await api(`/api/layers?model=${encodeURIComponent(state.model)}`);
+      const layerValues = ["", "__all__", ...(out.layers || [])];
+      const requestedLayer = layerValues.includes(options.requestedLayer) ? options.requestedLayer : "";
+      fillSelect(els.layer, layerValues, requestedLayer);
+      els.layer.options[0].textContent = "Please select";
+      els.layer.options[1].textContent = "All layers";
+      els.layer.disabled = false;
+      state.layer = els.layer.value;
+      persistSelection();
+      if (state.layer) await loadStats();
+      else clearStats("Please select a layer.");
+    }
+
+    async function loadStats() {
+      if (!state.model) {
+        clearStats("Please select a model.");
+        return;
+      }
+      if (!state.layer) {
+        clearStats("Please select a layer.");
+        return;
+      }
+      els.summary.textContent = state.layer === "__all__" ? "Loading all layers..." : `Loading ${state.layer}...`;
+      if (state.layer === "__all__") {
+        const out = await api(`/api/component-stats?model=${encodeURIComponent(state.model)}`);
+        state.layers = out.layers || [];
+      } else {
+        const out = await api(`/api/components?model=${encodeURIComponent(state.model)}&layer=${encodeURIComponent(state.layer)}`);
+        state.layers = [{ layer: state.layer, components: out.components || [] }];
+      }
+      renderStats(state.layers);
+    }
+
+    function renderStats(layers) {
+      const components = layers.flatMap(layer => layer.components || []);
+      const annotated = components.reduce((total, component) => total + annotatedDirectionCount(component), 0);
+      const totalDirections = components.length * 2;
+      const scope = state.layer === "__all__" ? `${layers.length} layers` : state.layer;
+      els.summary.textContent = `${state.model} - ${scope} - ${annotated} / ${totalDirections} directions annotated`;
+      if (!layers.length) {
+        els.message.hidden = false;
+        els.message.className = "empty";
+        els.message.textContent = "No components found.";
+        els.matrix.hidden = true;
+        return;
+      }
+      els.message.hidden = true;
+      els.matrix.hidden = false;
+      els.matrix.innerHTML = layers.map(layer => layerRow(layer)).join("");
+    }
+
+    function clearStats(message) {
+      state.layers = [];
+      els.summary.textContent = message;
+      els.message.hidden = false;
+      els.message.className = "empty";
+      els.message.textContent = message;
+      els.matrix.hidden = true;
+      els.matrix.innerHTML = "";
+    }
+
+    function updateUrl() {
+      const params = new URLSearchParams();
+      if (state.model) params.set("model", state.model);
+      if (state.layer) params.set("layer", state.layer === "__all__" ? "all" : state.layer);
+      const query = params.toString();
+      history.replaceState(null, "", query ? `${location.pathname}?${query}` : location.pathname);
+    }
+
+    function persistSelection() {
+      if (state.model) localStorage.setItem(STORAGE_KEYS.model, state.model);
+      else localStorage.removeItem(STORAGE_KEYS.model);
+      if (state.layer && state.layer !== "__all__") localStorage.setItem(STORAGE_KEYS.layer, state.layer);
+    }
+
+    function normalizeUrlLayer(value) {
+      return value === "all" ? "__all__" : value;
+    }
+
+    els.autoToggle.addEventListener("click", () => {
+      state.showAuto = !state.showAuto;
+      els.autoToggle.setAttribute("aria-pressed", state.showAuto ? "true" : "false");
+      if (state.layers.length) renderStats(state.layers);
+    });
+
+    els.erfToggle.addEventListener("click", () => {
+      state.showErf = !state.showErf;
+      els.erfToggle.setAttribute("aria-pressed", state.showErf ? "true" : "false");
+      if (state.layers.length) renderStats(state.layers);
+    });
+
+    function layerRow(layer) {
+      const components = layer.components || [];
+      const annotated = components.reduce((total, component) => total + annotatedDirectionCount(component), 0);
+      const totalDirections = components.length * 2;
+      return `
+        <div class="layer-row">
+          <div class="layer-name">${escapeHtml(layer.layer)}</div>
+          <div class="layer-count">${annotated}/${totalDirections}</div>
+          <div class="dots">${components.map(component => componentPair(layer.layer, component)).join("")}</div>
+        </div>
+      `;
+    }
+
+    function componentPair(layer, component) {
+      return `
+        <span class="component-pair">
+          ${componentDirectionDot(layer, component, "positive")}
+          ${componentDirectionDot(layer, component, "negative")}
+        </span>
+      `;
+    }
+
+    function componentDirectionDot(layer, component, side) {
+      const annotation = annotationSide(component, side);
+      const title = componentTitle(component, annotation, side);
+      const href = componentExamplesUrl(layer, component);
+      const text = state.showErf ? erfText(component) : (annotation?.typeLetter || "?");
+      const erfClass = state.showErf ? " erf-value" : "";
+      if (!annotation) {
+        return `<a class="dot${erfClass}" href="${escapeAttr(href)}" title="${escapeAttr(title)}" aria-label="${escapeAttr(title)}">${escapeHtml(state.showErf ? text : "")}</a>`;
+      }
+      const classes = ["dot", annotation.confidence];
+      if (state.showErf) classes.push("erf-value");
+      if (state.showAuto && component[`${side}_auto_annotated`] && annotation.annotated) classes.push("auto");
+      return `<a class="${escapeAttr(classes.join(" "))}" href="${escapeAttr(href)}" title="${escapeAttr(title)}" aria-label="${escapeAttr(title)}">${escapeHtml(text)}</a>`;
+    }
+
+    function erfText(component) {
+      const value = Number(component.effective_context_mean);
+      return Number.isFinite(value) ? String(Math.round(value)) : "";
+    }
+
+    function componentExamplesUrl(layer, component) {
+      const params = new URLSearchParams({
+        model: state.model,
+        layer: String(layer),
+        component: String(component.component),
+      });
+      return `/component?${params.toString()}`;
+    }
+
+    function annotatedDirectionCount(component) {
+      return ["positive", "negative"].reduce((total, side) => {
+        const annotation = annotationSide(component, side);
+        return total + (annotation?.annotated ? 1 : 0);
+      }, 0);
+    }
+
+    function annotationSide(component, side) {
+      const confidence = normalizedConfidence(component[`${side}_confidence`]);
+      const label = visibleAnnotationLabel(component[`${side}_label`], confidence);
+      if (!label) return null;
+      const types = Array.isArray(component[`${side}_types`]) ? component[`${side}_types`] : [];
+      const annotated = !(label === "?" && confidence === "unclear");
+      return { side, label, confidence, types, typeLetter: typeLetter(types), annotated };
+    }
+
+    function componentTitle(component, annotation, side) {
+      const id = `C${Number(component.component)}`;
+      const kurtosis = Number.isFinite(Number(component.excess_kurtosis)) ? ` - kurtosis ${Number(component.excess_kurtosis).toFixed(2)}` : "";
+      if (!annotation) return `${id}: ${side} blank${kurtosis}`;
+      const type = annotation.types.length ? ` - ${annotation.types.join(", ")}` : "";
+      const source = state.showAuto && component[`${side}_auto_annotated`] && annotation.annotated ? " - auto-annotated" : "";
+      const erf = Number.isFinite(Number(component.effective_context_mean)) ? ` - mean ERF ${Number(component.effective_context_mean).toFixed(2)}` : "";
+      return `${id}: ${annotation.side} ${annotation.label} - ${annotation.confidence}${type}${source}${erf}${kurtosis}`;
+    }
+
+    function visibleAnnotationLabel(value, confidence) {
+      const text = String(value || "").trim();
+      if (!text) return "";
+      return text.replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+    }
+
+    function normalizedConfidence(value) {
+      const confidence = String(value || "unclear").toLowerCase();
+      return ["high", "medium", "low", "unclear"].includes(confidence) ? confidence : "unclear";
+    }
+
+    function typeLetter(types) {
+      const labels = Array.isArray(types) ? types : [];
+      const priority = [
+        ["Form", "F"],
+        ["Word", "W"],
+        ["Phrase", "P"],
+        ["Sentence", "S"],
+        ["Long-Range Context", "L"],
+        ["Global", "G"],
+        ["Position", "O"],
+        ["Sophisticated", "X"],
+      ];
+      for (const [name, letter] of priority) {
+        if (labels.some(label => String(label).toLowerCase() === name.toLowerCase())) return letter;
+      }
+      const first = labels.find(label => String(label).trim());
+      return first ? String(first).trim()[0].toUpperCase() : "";
+    }
+
+    function showError(message) {
+      els.message.hidden = false;
+      els.message.className = "error";
+      els.message.textContent = message;
+      els.matrix.hidden = true;
+    }
+
+    function fillSelect(select, values, current) {
+      select.innerHTML = values.map(value => `<option value="${escapeAttr(value)}" ${value === current ? "selected" : ""}>${escapeHtml(value)}</option>`).join("");
+    }
+
+    function escapeHtml(value) {
+      return String(value).replace(/[&<>"']/g, char => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
+    }
+
+    function escapeAttr(value) {
+      return escapeHtml(value);
+    }
+
+    init();
+  </script>
+</body>
+</html>

server/store.py

@@ -0,0 +1,772 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Any, Iterable
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS annotations (
+  model_name TEXT NOT NULL,
+  layer TEXT NOT NULL,
+  component INTEGER NOT NULL,
+  label TEXT,
+  confidence TEXT,
+  positive_label TEXT,
+  positive_confidence TEXT,
+  negative_label TEXT,
+  negative_confidence TEXT,
+  positive_interpretation_types_json TEXT,
+  negative_interpretation_types_json TEXT,
+  interpretation_types_json TEXT,
+  summary TEXT,
+  notes TEXT,
+  include_as_case_study INTEGER NOT NULL DEFAULT 0,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (model_name, layer, component)
+);
+
+CREATE TABLE IF NOT EXISTS chosen_random_components (
+  selection_name TEXT NOT NULL,
+  model_name TEXT NOT NULL,
+  selection_index INTEGER NOT NULL,
+  layer TEXT NOT NULL,
+  component INTEGER NOT NULL,
+  component_id TEXT,
+  source_json TEXT,
+  seed INTEGER,
+  requested_n INTEGER,
+  inventory_size INTEGER,
+  selected_size INTEGER,
+  fit_converged INTEGER,
+  fit_iterations INTEGER,
+  fit_final_lim REAL,
+  fit_final_lim_p95 REAL,
+  fit_seed INTEGER,
+  inserted_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (selection_name, model_name, selection_index)
+);
+
+CREATE INDEX IF NOT EXISTS idx_chosen_random_components_component
+ON chosen_random_components(model_name, layer, component);
+"""
+
+
+def connect(db_path: Path) -> sqlite3.Connection:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(db_path), check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    return conn
+
+
+def init_db(conn: sqlite3.Connection) -> None:
+    conn.executescript(SCHEMA)
+    _ensure_annotation_columns(conn)
+    conn.commit()
+
+
+def validate_db(conn: sqlite3.Connection, model_name: str | None = None) -> None:
+    tables = {str(row[0]) for row in conn.execute("SELECT name FROM sqlite_master WHERE type = 'table'").fetchall()}
+    missing = {"components", "examples", "annotations"} - tables
+    if missing:
+        raise RuntimeError(f"SQLite DB is missing required table(s): {', '.join(sorted(missing))}")
+    if model_name:
+        count = conn.execute("SELECT COUNT(*) FROM components WHERE model_name = ?", (model_name,)).fetchone()[0]
+        if int(count) == 0:
+            raise RuntimeError(f"SQLite DB has no components for model_name={model_name!r}")
+
+
+def list_models(conn: sqlite3.Connection) -> list[str]:
+    rows = conn.execute(
+        """
+        SELECT model_name FROM components
+        UNION
+        SELECT model_name FROM annotations
+        ORDER BY model_name
+        """
+    ).fetchall()
+    return [str(row[0]) for row in rows]
+
+
+def list_layers(conn: sqlite3.Connection, model_name: str) -> list[str]:
+    rows = conn.execute(
+        "SELECT DISTINCT layer FROM components WHERE model_name = ?",
+        (model_name,),
+    ).fetchall()
+    return sorted([str(row[0]) for row in rows], key=layer_sort_key)
+
+
+def list_components(conn: sqlite3.Connection, model_name: str, layer: str | None = None, component: int | None = None, search: str | None = None) -> list[dict[str, Any]]:
+    erf_join, erf_select = _erf_join_sql(conn)
+    rows = conn.execute(
+        f"""
+        SELECT c.layer,
+               c.component,
+               c.excess_kurtosis,
+               {erf_select}
+               a.positive_label,
+               a.positive_confidence,
+               a.negative_label,
+               a.negative_confidence,
+               a.positive_interpretation_types_json,
+               a.negative_interpretation_types_json,
+               a.summary,
+               a.notes,
+               a.include_as_case_study
+        FROM components c
+        LEFT JOIN annotations a
+          ON a.model_name = c.model_name
+         AND a.layer = c.layer
+         AND a.component = c.component
+        {erf_join}
+        WHERE c.model_name = ?
+          AND (? IS NULL OR c.layer = ?)
+          AND (? IS NULL OR c.component = ?)
+        """,
+        (model_name, layer, layer, component, component),
+    ).fetchall()
+    query = str(search or "").strip().lower()
+    out = []
+    for row in rows:
+        item = {
+            "layer": str(row["layer"]),
+            "component": int(row["component"]),
+            "excess_kurtosis": float(row["excess_kurtosis"]) if row["excess_kurtosis"] is not None else None,
+            "effective_context_mean": float(row["effective_context_mean"]) if row["effective_context_mean"] is not None else None,
+            **_annotation_row(row),
+        }
+        text = " ".join(str(item.get(key, "")) for key in ("component", "positive_label", "negative_label", "summary", "notes")).lower()
+        if query and query not in text:
+            continue
+        out.append(item)
+    return sorted(out, key=lambda row: (layer_sort_key(row["layer"]), row["component"]))
+
+
+def list_component_stats(conn: sqlite3.Connection, model_name: str) -> list[dict[str, Any]]:
+    erf_join, erf_select = _erf_join_sql(conn)
+    rows = conn.execute(
+        f"""
+        SELECT c.layer,
+               c.component,
+               c.excess_kurtosis,
+               {erf_select}
+               a.positive_label,
+               a.positive_confidence,
+               a.negative_label,
+               a.negative_confidence,
+               a.positive_interpretation_types_json,
+               a.negative_interpretation_types_json,
+               a.notes
+        FROM components c
+        LEFT JOIN annotations a
+          ON a.model_name = c.model_name
+         AND a.layer = c.layer
+         AND a.component = c.component
+        {erf_join}
+        WHERE c.model_name = ?
+        """,
+        (model_name,),
+    ).fetchall()
+    return sorted(
+        [
+            {
+                "layer": str(row["layer"]),
+                "effective_context_mean": float(row["effective_context_mean"]) if row["effective_context_mean"] is not None else None,
+                **_annotation_row(row),
+            }
+            for row in rows
+        ],
+        key=lambda row: (layer_sort_key(row["layer"]), row["component"]),
+    )
+
+
+def list_annotated_components(conn: sqlite3.Connection, model_name: str, layer: str) -> list[dict[str, Any]]:
+    erf_join, erf_select = _erf_join_sql(conn)
+    rows = conn.execute(
+        f"""
+        SELECT a.component,
+               {erf_select}
+               a.positive_label, a.positive_confidence,
+               a.negative_label, a.negative_confidence,
+               a.positive_interpretation_types_json,
+               a.negative_interpretation_types_json,
+               a.notes,
+               c.excess_kurtosis
+        FROM annotations a
+        LEFT JOIN components c
+          ON c.model_name = a.model_name
+         AND c.layer = a.layer
+         AND c.component = a.component
+        {erf_join}
+        WHERE a.model_name = ? AND a.layer = ?
+          AND (
+            (a.positive_label IS NOT NULL AND TRIM(a.positive_label) != '')
+            OR (a.negative_label IS NOT NULL AND TRIM(a.negative_label) != '')
+          )
+        ORDER BY a.component
+        """,
+        (model_name, layer),
+    ).fetchall()
+    out = []
+    for row in rows:
+        item = _annotation_row(row)
+        item["effective_context_mean"] = float(row["effective_context_mean"]) if row["effective_context_mean"] is not None else None
+        out.append(item)
+    return out
+
+
+
+def list_component_metadata(conn: sqlite3.Connection, model_name: str, layer: str, components: list[int]) -> list[dict[str, Any]]:
+    if not components:
+        return []
+    erf_join, erf_select = _erf_join_sql(conn)
+    unique_components = sorted({int(component) for component in components})
+    placeholders = ",".join("?" for _ in unique_components)
+    rows = conn.execute(
+        f"""
+        SELECT c.component,
+               c.excess_kurtosis,
+               {erf_select}
+               a.positive_label,
+               a.positive_confidence,
+               a.negative_label,
+               a.negative_confidence,
+               a.positive_interpretation_types_json,
+               a.negative_interpretation_types_json,
+               a.summary,
+               a.notes,
+               a.include_as_case_study
+        FROM components c
+        LEFT JOIN annotations a
+          ON a.model_name = c.model_name
+         AND a.layer = c.layer
+         AND a.component = c.component
+        {erf_join}
+        WHERE c.model_name = ? AND c.layer = ? AND c.component IN ({placeholders})
+        ORDER BY c.component
+        """,
+        (model_name, layer, *unique_components),
+    ).fetchall()
+    out = []
+    for row in rows:
+        item = _annotation_row(row)
+        item["effective_context_mean"] = float(row["effective_context_mean"]) if row["effective_context_mean"] is not None else None
+        out.append(item)
+    return out
+
+
+def list_component_neighbors(conn: sqlite3.Connection, model_name: str, layer: str, component: int) -> list[dict[str, Any]]:
+    if not _table_exists(conn, "component_neighbors"):
+        return []
+    neighbor_columns = _table_columns(conn, "component_neighbors")
+    neighbor_sign_select = "n.neighbor_sign" if "neighbor_sign" in neighbor_columns else "CASE WHEN n.signed_cosine >= 0 THEN 1 ELSE -1 END"
+    erf_join, erf_select = _component_neighbor_erf_join_sql(conn)
+    rows = conn.execute(
+        f"""
+        SELECT n.direction,
+               n.neighbor_layer,
+               n.neighbor_component AS component,
+               n.abs_cosine,
+               n.signed_cosine,
+               {neighbor_sign_select} AS neighbor_sign,
+               n.source_n_components,
+               n.neighbor_n_components,
+               {erf_select}
+               a.positive_label,
+               a.positive_confidence,
+               a.negative_label,
+               a.negative_confidence,
+               a.positive_interpretation_types_json,
+               a.negative_interpretation_types_json,
+               a.summary,
+               a.notes,
+               a.include_as_case_study,
+               c.excess_kurtosis
+        FROM component_neighbors n
+        LEFT JOIN annotations a
+          ON a.model_name = n.model_name
+         AND a.layer = n.neighbor_layer
+         AND a.component = n.neighbor_component
+        LEFT JOIN components c
+          ON c.model_name = n.model_name
+         AND c.layer = n.neighbor_layer
+         AND c.component = n.neighbor_component
+        {erf_join}
+        WHERE n.model_name = ?
+          AND n.layer = ?
+          AND n.component = ?
+        ORDER BY CASE n.direction WHEN 'prev' THEN 0 WHEN 'next' THEN 1 ELSE 2 END
+        """,
+        (model_name, layer, int(component)),
+    ).fetchall()
+    out = []
+    for row in rows:
+        item = _annotation_row(row)
+        item.update(
+            {
+                "direction": str(row["direction"]),
+                "neighbor_layer": str(row["neighbor_layer"]),
+                "neighbor_component": int(row["component"]),
+                "abs_cosine": float(row["abs_cosine"]),
+                "signed_cosine": float(row["signed_cosine"]),
+                "neighbor_sign": int(row["neighbor_sign"]),
+                "source_n_components": int(row["source_n_components"]),
+                "neighbor_n_components": int(row["neighbor_n_components"]),
+                "effective_context_mean": float(row["effective_context_mean"]) if row["effective_context_mean"] is not None else None,
+            }
+        )
+        out.append(item)
+    return out
+
+
+def list_chosen_random_components(conn: sqlite3.Connection, model_name: str | None = None, selection_name: str | None = None) -> list[dict[str, Any]]:
+    if not _table_exists(conn, "chosen_random_components"):
+        return []
+    erf_join, erf_select = _erf_join_sql(conn)
+    rows = conn.execute(
+        f"""
+        SELECT r.selection_name,
+               r.model_name,
+               r.selection_index,
+               r.layer,
+               r.component,
+               r.component_id,
+               r.source_json,
+               r.seed,
+               r.requested_n,
+               r.inventory_size,
+               r.selected_size,
+               r.fit_converged,
+               r.fit_iterations,
+               r.fit_final_lim,
+               r.fit_final_lim_p95,
+               r.fit_seed,
+               c.excess_kurtosis,
+               {erf_select}
+               a.positive_label,
+               a.positive_confidence,
+               a.negative_label,
+               a.negative_confidence,
+               a.positive_interpretation_types_json,
+               a.negative_interpretation_types_json,
+               a.summary,
+               a.notes,
+               a.include_as_case_study
+        FROM chosen_random_components r
+        LEFT JOIN components c
+          ON c.model_name = r.model_name
+         AND c.layer = r.layer
+         AND c.component = r.component
+        LEFT JOIN annotations a
+          ON a.model_name = r.model_name
+         AND a.layer = r.layer
+         AND a.component = r.component
+        {erf_join}
+        WHERE (? IS NULL OR r.model_name = ?)
+          AND (? IS NULL OR r.selection_name = ?)
+        ORDER BY r.model_name, r.selection_name, r.selection_index
+        """,
+        (model_name, model_name, selection_name, selection_name),
+    ).fetchall()
+    out = []
+    for row in rows:
+        item = _annotation_row(row)
+        item.update(
+            {
+                "selection_name": str(row["selection_name"]),
+                "model_name": str(row["model_name"]),
+                "selection_index": int(row["selection_index"]),
+                "layer": str(row["layer"]),
+                "component": int(row["component"]),
+                "component_id": str(row["component_id"] or ""),
+                "source_json": str(row["source_json"] or ""),
+                "seed": int(row["seed"]) if row["seed"] is not None else None,
+                "requested_n": int(row["requested_n"]) if row["requested_n"] is not None else None,
+                "inventory_size": int(row["inventory_size"]) if row["inventory_size"] is not None else None,
+                "selected_size": int(row["selected_size"]) if row["selected_size"] is not None else None,
+                "fit_converged": bool(row["fit_converged"]) if row["fit_converged"] is not None else None,
+                "fit_iterations": int(row["fit_iterations"]) if row["fit_iterations"] is not None else None,
+                "fit_final_lim": float(row["fit_final_lim"]) if row["fit_final_lim"] is not None else None,
+                "fit_final_lim_p95": float(row["fit_final_lim_p95"]) if row["fit_final_lim_p95"] is not None else None,
+                "fit_seed": int(row["fit_seed"]) if row["fit_seed"] is not None else None,
+                "effective_context_mean": float(row["effective_context_mean"]) if row["effective_context_mean"] is not None else None,
+            }
+        )
+        out.append(item)
+    return out
+
+
+def list_component_examples(conn: sqlite3.Connection, model_name: str, layer: str | None = None, component: int | None = None, *, region: str | None = None, limit: int | None = None) -> dict[tuple[str, int], list[dict[str, Any]]]:
+    rows = conn.execute(
+        """
+        SELECT layer,
+               component,
+               region,
+               rank,
+               row_index,
+               doc_id,
+               token_id,
+               token,
+               source_score,
+               direction_cosine,
+               position,
+               context_to_target,
+               context,
+               context_score_max_abs
+        FROM examples
+        WHERE model_name = ?
+          AND (? IS NULL OR layer = ?)
+          AND (? IS NULL OR component = ?)
+          AND (? IS NULL OR region = ?)
+          AND (? IS NULL OR rank <= ?)
+        ORDER BY layer, component, region, rank
+        """,
+        (model_name, layer, layer, component, component, region, region, limit, limit),
+    ).fetchall()
+    examples: dict[tuple[str, int], list[dict[str, Any]]] = {}
+    for row in rows:
+        key = (str(row["layer"]), int(row["component"]))
+        examples.setdefault(key, []).append(_example_row(row))
+    return examples
+
+
+def list_component_example_details(conn: sqlite3.Connection, model_name: str, *, layer: str, component: int) -> list[dict[str, Any]]:
+    rows = conn.execute(
+        """
+        SELECT id,
+               region,
+               rank,
+               row_index,
+               doc_id,
+               token_id,
+               token,
+               source_score,
+               direction_cosine,
+               position,
+               context_to_target,
+               context,
+               context_score_max_abs
+        FROM examples
+        WHERE model_name = ? AND layer = ? AND component = ?
+        ORDER BY region, rank
+        """,
+        (model_name, layer, component),
+    ).fetchall()
+    examples = []
+    by_id: dict[int, dict[str, Any]] = {}
+    for row in rows:
+        example = _example_row(row)
+        example["context_token_scores"] = []
+        examples.append(example)
+        by_id[int(row["id"])] = example
+    for ids in _chunks(list(by_id), 500):
+        if not ids:
+            continue
+        placeholders = ",".join("?" for _ in ids)
+        token_rows = conn.execute(
+            f"""
+            SELECT example_id, seq, token_position, token, source_score, direction_cosine, is_target
+            FROM context_tokens
+            WHERE example_id IN ({placeholders})
+            ORDER BY example_id, seq
+            """,
+            tuple(ids),
+        ).fetchall()
+        for token_row in token_rows:
+            example = by_id.get(int(token_row["example_id"]))
+            if example is None:
+                continue
+            example["context_token_scores"].append(
+                {
+                    "position": int(token_row["token_position"]) if token_row["token_position"] is not None else None,
+                    "token": str(token_row["token"] or ""),
+                    "source_score": float(token_row["source_score"]) if token_row["source_score"] is not None else None,
+                    "direction_cosine": float(token_row["direction_cosine"]) if token_row["direction_cosine"] is not None else None,
+                    "is_target": bool(token_row["is_target"]),
+                }
+            )
+    return examples
+
+
+def get_component_row(conn: sqlite3.Connection, model_name: str, layer: str, component: int) -> dict[str, Any] | None:
+    rows = list_components(conn, model_name, layer=layer, component=component)
+    return rows[0] if rows else None
+
+
+def get_annotation(conn: sqlite3.Connection, model_name: str, layer: str, component: int) -> dict[str, Any] | None:
+    row = conn.execute(
+        """
+        SELECT * FROM annotations
+        WHERE model_name = ? AND layer = ? AND component = ?
+        """,
+        (model_name, layer, component),
+    ).fetchone()
+    return dict(row) if row else None
+
+
+def update_annotation(conn: sqlite3.Connection, *, model_name: str, layer: str, component: int, positive_label: str, positive_confidence: str, positive_interpretation_types: list[str], negative_label: str, negative_confidence: str, negative_interpretation_types: list[str], summary: str, notes: str, include_as_case_study: bool) -> None:
+    conn.execute(
+        """
+        INSERT INTO annotations(
+          model_name, layer, component,
+          positive_label, positive_confidence, positive_interpretation_types_json,
+          negative_label, negative_confidence, negative_interpretation_types_json,
+          summary, notes, include_as_case_study, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+        ON CONFLICT(model_name, layer, component) DO UPDATE SET
+          positive_label = excluded.positive_label,
+          positive_confidence = excluded.positive_confidence,
+          positive_interpretation_types_json = excluded.positive_interpretation_types_json,
+          negative_label = excluded.negative_label,
+          negative_confidence = excluded.negative_confidence,
+          negative_interpretation_types_json = excluded.negative_interpretation_types_json,
+          summary = excluded.summary,
+          notes = excluded.notes,
+          include_as_case_study = excluded.include_as_case_study,
+          updated_at = datetime('now')
+        """,
+        (
+            model_name,
+            layer,
+            int(component),
+            positive_label,
+            _normalize_confidence(positive_confidence),
+            json.dumps([str(item) for item in positive_interpretation_types if str(item)]),
+            negative_label,
+            _normalize_confidence(negative_confidence),
+            json.dumps([str(item) for item in negative_interpretation_types if str(item)]),
+            summary,
+            notes,
+            1 if include_as_case_study else 0,
+        ),
+    )
+    conn.commit()
+
+
+def infer_default_annotation_sign(conn: sqlite3.Connection, model_name: str, layer: str, component: int) -> int:
+    row = conn.execute(
+        """
+        SELECT source_score
+        FROM examples
+        WHERE model_name = ? AND layer = ? AND component = ?
+          AND region IN ('top_abs', 'top_abs_sample_500', 'top_abs_sample_5000')
+        ORDER BY ABS(source_score) DESC, rank ASC
+        LIMIT 1
+        """,
+        (model_name, layer, component),
+    ).fetchone()
+    if row is None or row["source_score"] is None:
+        return 1
+    return 1 if float(row["source_score"]) >= 0 else -1
+
+
+def get_examples_by_region(conn: sqlite3.Connection, model_name: str, layer: str, component: int) -> tuple[list[str], dict[str, list[dict[str, Any]]]]:
+    examples = list_component_example_details(conn, model_name, layer=layer, component=component)
+    by_region: dict[str, list[dict[str, Any]]] = {}
+    for example in examples:
+        by_region.setdefault(str(example["region"] or "examples"), []).append(example)
+    regions = sorted(by_region, key=_example_band_sort_key)
+    return regions, by_region
+
+
+def pick_default_region(regions: list[str], examples_by_region: dict[str, list[dict[str, Any]]]) -> str:
+    for candidate in ("top_abs", "top_abs_sample_500", "top_abs_sample_5000"):
+        if candidate in examples_by_region:
+            return candidate
+    return regions[0] if regions else ""
+
+
+def search_components(conn: sqlite3.Connection, *, model_name: str | None, query: str, confidence: str, annotation_type: str, include_examples: bool, limit: int) -> list[dict[str, Any]]:
+    models = [model_name] if model_name else list_models(conn)
+    results = []
+    query_l = query.strip().lower()
+    for model in models:
+        for item in list_components(conn, model):
+            labels = [item.get("positive_label", ""), item.get("negative_label", ""), item.get("summary", ""), item.get("notes", "")]
+            haystack = " ".join(str(x) for x in labels).lower()
+            if query_l and query_l not in haystack:
+                continue
+            if confidence and confidence not in {item.get("positive_confidence"), item.get("negative_confidence")}:
+                continue
+            if annotation_type and annotation_type not in set(item.get("positive_types", []) + item.get("negative_types", [])):
+                continue
+            row = {"model_name": model, **item}
+            if include_examples:
+                ex = list_component_examples(conn, model, layer=item["layer"], component=item["component"], limit=3).get((item["layer"], item["component"]), [])
+                row["examples"] = ex
+            results.append(row)
+            if len(results) >= limit:
+                return results
+    return results
+
+
+def layer_sort_key(layer: str) -> tuple[int, int | str]:
+    if layer == "embedding":
+        return (0, 0)
+    if layer.startswith("layer_"):
+        return (1, int(layer.removeprefix("layer_")))
+    return (2, layer)
+
+
+def _erf_join_sql(conn: sqlite3.Connection) -> tuple[str, str]:
+    table = _first_existing_table(conn, ["effective_receptive_fields", "effective_context_lengths"])
+    if table is None:
+        return "", "NULL AS effective_context_mean,"
+    columns = _table_columns(conn, table)
+    value_column = _first_existing_name(columns, ["mean_erf", "erf_mean", "mean_length", "effective_receptive_field_mean", "effective_context_mean"])
+    if value_column is None:
+        return "", "NULL AS effective_context_mean,"
+    quoted_table = _quote_identifier(table)
+    quoted_value = _quote_identifier(value_column)
+    return (
+        f"""
+        LEFT JOIN {quoted_table} erf
+          ON erf.model_name = c.model_name
+         AND erf.layer = c.layer
+         AND erf.component = c.component
+        """,
+        f"erf.{quoted_value} AS effective_context_mean,",
+    )
+
+
+def _component_neighbor_erf_join_sql(conn: sqlite3.Connection) -> tuple[str, str]:
+    table = _first_existing_table(conn, ["effective_receptive_fields", "effective_context_lengths"])
+    if table is None:
+        return "", "NULL AS effective_context_mean,"
+    columns = _table_columns(conn, table)
+    value_column = _first_existing_name(columns, ["mean_erf", "erf_mean", "mean_length", "effective_receptive_field_mean", "effective_context_mean"])
+    if value_column is None:
+        return "", "NULL AS effective_context_mean,"
+    quoted_table = _quote_identifier(table)
+    quoted_value = _quote_identifier(value_column)
+    return (
+        f"""
+        LEFT JOIN {quoted_table} erf
+          ON erf.model_name = n.model_name
+         AND erf.layer = n.neighbor_layer
+         AND erf.component = n.neighbor_component
+        """,
+        f"erf.{quoted_value} AS effective_context_mean,",
+    )
+
+
+def _first_existing_table(conn: sqlite3.Connection, names: list[str]) -> str | None:
+    for name in names:
+        if _table_exists(conn, name):
+            return name
+    return None
+
+
+def _table_columns(conn: sqlite3.Connection, table_name: str) -> set[str]:
+    return {str(row["name"]) for row in conn.execute(f"PRAGMA table_info({_quote_identifier(table_name)})").fetchall()}
+
+
+def _first_existing_name(names: set[str], candidates: list[str]) -> str | None:
+    for candidate in candidates:
+        if candidate in names:
+            return candidate
+    return None
+
+
+def _quote_identifier(name: str) -> str:
+    return '"' + str(name).replace('"', '""') + '"'
+
+
+def _table_exists(conn: sqlite3.Connection, table_name: str) -> bool:
+    return conn.execute("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", (table_name,)).fetchone() is not None
+
+
+def _ensure_annotation_columns(conn: sqlite3.Connection) -> None:
+    columns = {str(row["name"]) for row in conn.execute("PRAGMA table_info(annotations)").fetchall()}
+    required = {
+        "label": "TEXT",
+        "confidence": "TEXT",
+        "positive_label": "TEXT",
+        "positive_confidence": "TEXT",
+        "negative_label": "TEXT",
+        "negative_confidence": "TEXT",
+        "positive_interpretation_types_json": "TEXT",
+        "negative_interpretation_types_json": "TEXT",
+        "interpretation_types_json": "TEXT",
+        "summary": "TEXT",
+        "notes": "TEXT",
+        "include_as_case_study": "INTEGER NOT NULL DEFAULT 0",
+        "updated_at": "TEXT",
+    }
+    for column, ddl in required.items():
+        if column not in columns:
+            conn.execute(f"ALTER TABLE annotations ADD COLUMN {column} {ddl}")
+
+
+def _annotation_row(row: sqlite3.Row | dict[str, Any]) -> dict[str, Any]:
+    keys = row.keys() if hasattr(row, "keys") else row
+    def get(key: str, default: Any = None) -> Any:
+        return row[key] if key in keys else default
+    positive_label = str(get("positive_label") or "")
+    negative_label = str(get("negative_label") or "")
+    auto_annotated = "auto-annotation" in str(get("notes") or "").lower()
+    return {
+        "component": int(get("component")),
+        "positive_label": positive_label,
+        "positive_confidence": _normalize_confidence(get("positive_confidence")),
+        "negative_label": negative_label,
+        "negative_confidence": _normalize_confidence(get("negative_confidence")),
+        "positive_types": _json_list(get("positive_interpretation_types_json")),
+        "negative_types": _json_list(get("negative_interpretation_types_json")),
+        "summary": str(get("summary") or ""),
+        "notes": str(get("notes") or ""),
+        "include_as_case_study": bool(get("include_as_case_study") or 0),
+        "excess_kurtosis": float(get("excess_kurtosis")) if get("excess_kurtosis") is not None else None,
+        "auto_annotated": auto_annotated,
+    }
+
+
+def _example_row(row: sqlite3.Row) -> dict[str, Any]:
+    return {
+        "region": str(row["region"] or ""),
+        "rank": int(row["rank"]),
+        "row_index": int(row["row_index"]) if "row_index" in row.keys() and row["row_index"] is not None else None,
+        "doc_id": int(row["doc_id"]) if "doc_id" in row.keys() and row["doc_id"] is not None else None,
+        "token_id": int(row["token_id"]) if "token_id" in row.keys() and row["token_id"] is not None else None,
+        "token": str(row["token"] or ""),
+        "source_score": float(row["source_score"]) if row["source_score"] is not None else None,
+        "direction_cosine": float(row["direction_cosine"]) if row["direction_cosine"] is not None else None,
+        "position": int(row["position"]) if row["position"] is not None else None,
+        "context_to_target": str(row["context_to_target"] or ""),
+        "context": str(row["context"] or ""),
+        "context_score_max_abs": float(row["context_score_max_abs"]) if row["context_score_max_abs"] is not None else None,
+    }
+
+
+def _json_list(value: Any) -> list[str]:
+    try:
+        parsed = json.loads(value or "[]")
+    except json.JSONDecodeError:
+        return []
+    return [str(item) for item in parsed] if isinstance(parsed, list) else []
+
+
+def _normalize_confidence(value: Any) -> str:
+    text = str(value or "unclear").strip().lower()
+    return text if text in {"high", "medium", "low", "unclear"} else "unclear"
+
+
+def _chunks(items: list[int], size: int) -> Iterable[list[int]]:
+    for index in range(0, len(items), size):
+        yield items[index : index + size]
+
+
+def _example_band_sort_key(region: str) -> tuple[int, str]:
+    name = str(region or "").lower().replace("-", "_")
+    compact = name.replace("_", "")
+    if name == "top_abs" or compact == "topabs":
+        return (0, name)
+    if "sample" in name:
+        return (1, name)
+    if "near_zero" in name or "nearzero" in compact:
+        return (2, name)
+    if "opposite" in name:
+        return (3, name)
+    return (4, name)