actlens 0.1.0__tar.gz

actlens-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.env/
+node_modules/
+frontend/dist/
+__pycache__/
+.pytest_cache/
+*.pyc
+.claude/
+docs/
+.DS_Store
+.vscode
+dist/

actlens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan704
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

actlens-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: actlens
+Version: 0.1.0
+Summary: Interactive viewer for the activations of a Hugging Face model during a forward pass
+Project-URL: Homepage, https://github.com/Evan704/ActLens
+Project-URL: Repository, https://github.com/Evan704/ActLens
+Project-URL: Issues, https://github.com/Evan704/ActLens/issues
+Author: Evan704
+License-Expression: MIT
+License-File: LICENSE
+Keywords: activations,huggingface,interpretability,transformers,visualization
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: nnsight>=0.7
+Requires-Dist: numpy>=1.26
+Requires-Dist: torch>=2
+Requires-Dist: transformers>=5
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ActLens
+
+**See inside a language model while it reads your prompt.**
+
+ActLens is an interactive viewer for the activations of any supported Hugging Face model. Type a prompt, pick an
+activation and a layer, and browse the result as a token × channel heatmap: residual stream, attention patterns, Q/K/V,
+MLP internals and more. It runs locally, in one command.
+
+[![PyPI](https://img.shields.io/pypi/v/actlens)](https://pypi.org/project/actlens/)
+[![Python](https://img.shields.io/pypi/pyversions/actlens)](https://pypi.org/project/actlens/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Evan704/ActLens/blob/main/LICENSE)
+
+## Features
+
+- **Every activation, every layer.** Residual stream, attention (Q, K, V, RoPE, patterns, context, output) and MLP
+  (gate, up, SwiGLU, down), captured lazily and cached.
+- **Two views.** *Layer* shows a token × channel heatmap for one layer; *Across layers* shows a per-token statistic
+  (L2 norm, |max|, mean, std, kurtosis, or a single channel) for every layer at once.
+- **Attention explorer.** A grid of all heads, a full query × key map per head, and a layer × head map of entropy,
+  sink mass and attention distance.
+- **Find outlier channels.** Rank channels by |max|, std or |mean|; jump straight to a head.
+- **Distributions.** Histograms and summary statistics over a region, a channel, a token, or the whole layer.
+- **Fast to navigate.** Pan, zoom, brush and inspect; large activations are pooled server-side so zooming out stays cheap.
+- **Publication-ready export.** PNG and PDF with title, prompt, axes and colorbar at up to 4×.
+- **Extensible.** Add support for a new architecture with a small adapter.
+
+## Quick start
+
+```bash
+pip install actlens      # Python >= 3.10; use a fresh virtual environment
+actlens                  # loads Qwen/Qwen3-0.6B and serves the UI at http://127.0.0.1:8000
+```
+
+The first run downloads the model weights from the Hugging Face Hub. ActLens is developed and tested against
+torch 2, transformers 5 and nnsight 0.7.
+
+```bash
+actlens -m Qwen/Qwen2.5-0.5B             # another Hugging Face model id or a local path
+actlens --device cuda --dtype bfloat16   # device: auto | cpu | cuda | mps; dtype: float32 | float16 | bfloat16
+actlens --port 9000 --open               # custom port, open the browser when ready
+actlens --cache-mb 4096                  # activation cache budget (or $ACTLENS_CACHE_MB)
+```
+
+You can load more models from the UI at any time.
+
+> **Security note.** The server binds to `127.0.0.1` by default. The API can load any model and has no
+> authentication, so only use `--host 0.0.0.0` on a network you trust.
+
+### Google Colab
+
+No local GPU? Run the model on a free Colab GPU and view the visualization in your own browser.
+
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Evan704/ActLens/blob/main/colab/ActLens.ipynb)
+
+1. Open the notebook and pick a GPU runtime (Runtime → Change runtime type → T4 GPU).
+2. Run the first cell. It installs ActLens, starts the server and opens a Cloudflare tunnel.
+3. Click the **Open ActLens** link it prints. The UI opens in your browser; keep the Colab tab open while you use it.
+
+Or in any notebook:
+
+```python
+!pip install -q actlens
+from actlens.colab import launch
+launch(model="Qwen/Qwen3-0.6B", dtype="float16")
+```
+
+The link contains a random access token, and the server rejects requests without it. Anyone who has the full link can use
+your session, so do not share it. Use `actlens.colab.stop()` to shut everything down. If the page does not load, check
+`actlens.log`.
+
+You can also protect a server of your own with `actlens --token` (generates a token and prints the URL) or `--token VALUE`.
+
+## Using the viewer
+
+Pick an **activation** and a **layer** in the selection bar (`[` and `]` step through layers), then choose a view.
+
+| Interaction | Action |
+|---|---|
+| Drag | Pan |
+| Pinch, or ⌘/Ctrl + scroll | Zoom |
+| Shift + drag | Select a region |
+| Click | Place the cursor |
+| Double-click | Reset the view |
+| `[` / `]` | Previous / next layer |
+| Esc | Clear the selection |
+
+For head-structured activations (`q k v q_norm k_norm q_rope k_rope attn_ctx`) the channel axis is `head × head_dim`,
+with ticks like `h3·17` and faint separators between heads; the **Head** control jumps the window to one head.
+
+### Available activations
+
+The picker lists only what the loaded model provides.
+
+| Group | Activations |
+|---|---|
+| Residual | `resid_pre`, `resid_mid`, `resid_post` |
+| Attention | `attn_norm`, `q`, `k`, `v`, `q_norm`, `k_norm`, `q_rope`, `k_rope`, `attn_pattern`, `attn_ctx`, `o` |
+| MLP | `mlp_norm`, `gate`, `up`, `silu`, `swiglu`, `mlp_act`, `down` |
+
+### Distribution panel
+
+- **Values**: histogram and summary (mean, std, percentiles, kurtosis, skew) of the raw values for the visible window,
+  a brushed selection, the cursor's channel or token, or the whole layer.
+- **Per channel / Per token**: one statistic per channel or token, shown as a histogram with a clickable list of the
+  top outliers.
+
+### Export
+
+The PNG and PDF buttons render the current view at 1–4×. The histogram and the attention head grid have their own PNG
+export. PDFs embed the figure as a high-resolution image so CJK tokens render correctly.
+
+## Supported models
+
+| Adapter | `model_type` | Models |
+|---|---|---|
+| `llama` | `llama`, `qwen2`, `qwen3`, `mistral`, and models with the same module layout | Llama, Qwen2/2.5/3, Mistral, SmolLM |
+| `gpt2` | `gpt2` | GPT-2, DistilGPT-2 |
+
+Qwen3-0.6B and GPT-2 are tested on real checkpoints; every adapter is also tested on a tiny random model. An
+unsupported model is rejected at load time with a message naming the missing modules.
+
+Want another architecture? See [Adding an architecture](https://github.com/Evan704/ActLens/blob/main/CONTRIBUTING.md#adding-an-architecture).
+
+## Troubleshooting
+
+- **Attention patterns need eager attention.** ActLens loads models with `attn_implementation="eager"` because SDPA does
+  not return attention probabilities.
+- **Slow first open of an activation.** The first time you open an activation, one forward pass captures it for every
+  layer (about 0.1–0.4 s for Qwen3-0.6B); after that it comes from the cache.
+- **Running out of memory.** Use a smaller model, `--dtype float16` or `bfloat16`, or lower `--cache-mb`.
+
+## Contributing
+
+Development setup, tests, architecture notes and the release process are in
+[CONTRIBUTING.md](https://github.com/Evan704/ActLens/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/Evan704/ActLens/blob/main/LICENSE)

actlens-0.1.0/README.md

@@ -0,0 +1,139 @@
+# ActLens
+
+**See inside a language model while it reads your prompt.**
+
+ActLens is an interactive viewer for the activations of any supported Hugging Face model. Type a prompt, pick an
+activation and a layer, and browse the result as a token × channel heatmap: residual stream, attention patterns, Q/K/V,
+MLP internals and more. It runs locally, in one command.
+
+[![PyPI](https://img.shields.io/pypi/v/actlens)](https://pypi.org/project/actlens/)
+[![Python](https://img.shields.io/pypi/pyversions/actlens)](https://pypi.org/project/actlens/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Evan704/ActLens/blob/main/LICENSE)
+
+## Features
+
+- **Every activation, every layer.** Residual stream, attention (Q, K, V, RoPE, patterns, context, output) and MLP
+  (gate, up, SwiGLU, down), captured lazily and cached.
+- **Two views.** *Layer* shows a token × channel heatmap for one layer; *Across layers* shows a per-token statistic
+  (L2 norm, |max|, mean, std, kurtosis, or a single channel) for every layer at once.
+- **Attention explorer.** A grid of all heads, a full query × key map per head, and a layer × head map of entropy,
+  sink mass and attention distance.
+- **Find outlier channels.** Rank channels by |max|, std or |mean|; jump straight to a head.
+- **Distributions.** Histograms and summary statistics over a region, a channel, a token, or the whole layer.
+- **Fast to navigate.** Pan, zoom, brush and inspect; large activations are pooled server-side so zooming out stays cheap.
+- **Publication-ready export.** PNG and PDF with title, prompt, axes and colorbar at up to 4×.
+- **Extensible.** Add support for a new architecture with a small adapter.
+
+## Quick start
+
+```bash
+pip install actlens      # Python >= 3.10; use a fresh virtual environment
+actlens                  # loads Qwen/Qwen3-0.6B and serves the UI at http://127.0.0.1:8000
+```
+
+The first run downloads the model weights from the Hugging Face Hub. ActLens is developed and tested against
+torch 2, transformers 5 and nnsight 0.7.
+
+```bash
+actlens -m Qwen/Qwen2.5-0.5B             # another Hugging Face model id or a local path
+actlens --device cuda --dtype bfloat16   # device: auto | cpu | cuda | mps; dtype: float32 | float16 | bfloat16
+actlens --port 9000 --open               # custom port, open the browser when ready
+actlens --cache-mb 4096                  # activation cache budget (or $ACTLENS_CACHE_MB)
+```
+
+You can load more models from the UI at any time.
+
+> **Security note.** The server binds to `127.0.0.1` by default. The API can load any model and has no
+> authentication, so only use `--host 0.0.0.0` on a network you trust.
+
+### Google Colab
+
+No local GPU? Run the model on a free Colab GPU and view the visualization in your own browser.
+
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Evan704/ActLens/blob/main/colab/ActLens.ipynb)
+
+1. Open the notebook and pick a GPU runtime (Runtime → Change runtime type → T4 GPU).
+2. Run the first cell. It installs ActLens, starts the server and opens a Cloudflare tunnel.
+3. Click the **Open ActLens** link it prints. The UI opens in your browser; keep the Colab tab open while you use it.
+
+Or in any notebook:
+
+```python
+!pip install -q actlens
+from actlens.colab import launch
+launch(model="Qwen/Qwen3-0.6B", dtype="float16")
+```
+
+The link contains a random access token, and the server rejects requests without it. Anyone who has the full link can use
+your session, so do not share it. Use `actlens.colab.stop()` to shut everything down. If the page does not load, check
+`actlens.log`.
+
+You can also protect a server of your own with `actlens --token` (generates a token and prints the URL) or `--token VALUE`.
+
+## Using the viewer
+
+Pick an **activation** and a **layer** in the selection bar (`[` and `]` step through layers), then choose a view.
+
+| Interaction | Action |
+|---|---|
+| Drag | Pan |
+| Pinch, or ⌘/Ctrl + scroll | Zoom |
+| Shift + drag | Select a region |
+| Click | Place the cursor |
+| Double-click | Reset the view |
+| `[` / `]` | Previous / next layer |
+| Esc | Clear the selection |
+
+For head-structured activations (`q k v q_norm k_norm q_rope k_rope attn_ctx`) the channel axis is `head × head_dim`,
+with ticks like `h3·17` and faint separators between heads; the **Head** control jumps the window to one head.
+
+### Available activations
+
+The picker lists only what the loaded model provides.
+
+| Group | Activations |
+|---|---|
+| Residual | `resid_pre`, `resid_mid`, `resid_post` |
+| Attention | `attn_norm`, `q`, `k`, `v`, `q_norm`, `k_norm`, `q_rope`, `k_rope`, `attn_pattern`, `attn_ctx`, `o` |
+| MLP | `mlp_norm`, `gate`, `up`, `silu`, `swiglu`, `mlp_act`, `down` |
+
+### Distribution panel
+
+- **Values**: histogram and summary (mean, std, percentiles, kurtosis, skew) of the raw values for the visible window,
+  a brushed selection, the cursor's channel or token, or the whole layer.
+- **Per channel / Per token**: one statistic per channel or token, shown as a histogram with a clickable list of the
+  top outliers.
+
+### Export
+
+The PNG and PDF buttons render the current view at 1–4×. The histogram and the attention head grid have their own PNG
+export. PDFs embed the figure as a high-resolution image so CJK tokens render correctly.
+
+## Supported models
+
+| Adapter | `model_type` | Models |
+|---|---|---|
+| `llama` | `llama`, `qwen2`, `qwen3`, `mistral`, and models with the same module layout | Llama, Qwen2/2.5/3, Mistral, SmolLM |
+| `gpt2` | `gpt2` | GPT-2, DistilGPT-2 |
+
+Qwen3-0.6B and GPT-2 are tested on real checkpoints; every adapter is also tested on a tiny random model. An
+unsupported model is rejected at load time with a message naming the missing modules.
+
+Want another architecture? See [Adding an architecture](https://github.com/Evan704/ActLens/blob/main/CONTRIBUTING.md#adding-an-architecture).
+
+## Troubleshooting
+
+- **Attention patterns need eager attention.** ActLens loads models with `attn_implementation="eager"` because SDPA does
+  not return attention probabilities.
+- **Slow first open of an activation.** The first time you open an activation, one forward pass captures it for every
+  layer (about 0.1–0.4 s for Qwen3-0.6B); after that it comes from the cache.
+- **Running out of memory.** Use a smaller model, `--dtype float16` or `bfloat16`, or lower `--cache-mb`.
+
+## Contributing
+
+Development setup, tests, architecture notes and the release process are in
+[CONTRIBUTING.md](https://github.com/Evan704/ActLens/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/Evan704/ActLens/blob/main/LICENSE)

actlens-0.1.0/backend/actlens/__init__.py

@@ -0,0 +1,3 @@
+"""ActLens: interactive activation viewer backend."""
+
+__version__ = "0.1.0"

actlens-0.1.0/backend/actlens/app.py

@@ -0,0 +1,318 @@
+"""FastAPI app: model management, runs, and windowed activation slices."""
+from __future__ import annotations
+
+import asyncio
+import gc
+import hmac
+import json
+import os
+import threading
+import time
+import uuid
+from contextlib import asynccontextmanager
+from collections import OrderedDict
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Callable
+
+from fastapi import FastAPI, HTTPException, Query, Request
+from fastapi.responses import FileResponse, PlainTextResponse, RedirectResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+from . import slicing
+from .cache import ActivationCache
+from .capture import ATTN_ACT, Capture, Run
+from .providers import ActivationProvider, NNsightProvider
+from .wire import frame_response
+
+DEFAULT_MODEL = "Qwen/Qwen3-0.6B"
+PRESET_MODELS = [
+    {"id": "Qwen/Qwen3-0.6B", "label": "Qwen3-0.6B"},
+    {"id": "Qwen/Qwen2.5-0.5B", "label": "Qwen2.5-0.5B"},
+    {"id": "HuggingFaceTB/SmolLM2-360M", "label": "SmolLM2-360M"},
+    {"id": "openai-community/gpt2", "label": "GPT-2"},
+]
+MAX_RUNS = 3
+TOKEN_COOKIE = "actlens_token"
+DEFAULT_CACHE_MB = 2048
+CORPUS = json.loads((Path(__file__).parent / "corpus.json").read_text())
+_PACKAGED_DIST = Path(__file__).parent / "static"  # bundled into the wheel
+_DEV_DIST = Path(__file__).resolve().parents[2] / "frontend" / "dist"  # source checkout
+FRONTEND_DIST = _PACKAGED_DIST if (_PACKAGED_DIST / "index.html").is_file() else _DEV_DIST
+
+
+def cache_budget_bytes() -> int:
+    try:
+        mb = float(os.environ.get("ACTLENS_CACHE_MB", DEFAULT_CACHE_MB))
+    except ValueError:
+        mb = DEFAULT_CACHE_MB
+    return int(mb * 2**20)
+
+
+class ModelManager:
+    """Owns the single loaded model. All model work runs on one dedicated thread."""
+
+    def __init__(self, factory: Callable[[str, str, str], ActivationProvider] = NNsightProvider,
+                 cache_bytes: int | None = None):
+        self.factory = factory
+        self.executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="model")
+        self.provider: ActivationProvider | None = None
+        self.state = "idle"  # idle | loading | ready | error
+        self.target: str | None = None
+        self.error: str | None = None
+        self.runs: OrderedDict[str, Run] = OrderedDict()
+        self.cache = ActivationCache(cache_budget_bytes() if cache_bytes is None else cache_bytes)
+        self._lock = threading.Lock()
+
+    def status(self) -> dict:
+        return {
+            "state": self.state,
+            "model_id": self.provider.model_id if self.provider else self.target,
+            "target": self.target,
+            "error": self.error,
+            "info": self.provider.info if self.state == "ready" and self.provider else None,
+        }
+
+    def load(self, model_id: str, device: str = "auto", dtype: str = "float32") -> None:
+        with self._lock:
+            if self.state == "loading":
+                raise HTTPException(409, "A model is already loading")
+            self.state, self.target, self.error = "loading", model_id, None
+        self.executor.submit(self._load, model_id, device, dtype)
+
+    def _load(self, model_id: str, device: str, dtype: str) -> None:
+        try:
+            if self.provider is not None:
+                self.provider.close()
+                self.provider = None
+            self.runs.clear()
+            self.cache.clear()
+            gc.collect()
+            self.provider = self.factory(model_id, device, dtype)
+            self.state = "ready"
+        except Exception as e:  # surfaced to the UI via /api/status
+            self.error = f"{type(e).__name__}: {e}"
+            self.state = "error"
+
+    def _register(self, provider: ActivationProvider, text: str, max_tokens: int) -> Run:
+        t0 = time.perf_counter()
+        ids, tokens, truncated = provider.tokenize(text, max_tokens)
+        specs = {s.id: s for s in provider.activations()}
+        keys = ("n_layers", "hidden_size", "intermediate_size", "n_heads", "n_kv_heads", "head_dim")
+        return Run(run_id=uuid.uuid4().hex[:12], model_id=provider.model_id, text=text, token_ids=list(ids),
+                   tokens=list(tokens), truncated=truncated, specs=specs,
+                   model={k: provider.info.get(k) for k in keys}, elapsed_ms=(time.perf_counter() - t0) * 1000)
+
+    async def run(self, text: str, max_tokens: int) -> Run:
+        """Tokenize and register a run. No activations are captured yet."""
+        if self.state != "ready" or self.provider is None:
+            raise HTTPException(409, f"Model not ready (state: {self.state})")
+        loop = asyncio.get_running_loop()
+        try:
+            run = await loop.run_in_executor(self.executor, self._register, self.provider, text, max_tokens)
+        except ValueError as e:
+            raise HTTPException(400, str(e))
+        self.runs[run.run_id] = run
+        while len(self.runs) > MAX_RUNS:
+            old, _ = self.runs.popitem(last=False)
+            self.cache.drop_run(old)
+        return run
+
+    def get(self, run_id: str) -> Run:
+        run = self.runs.get(run_id)
+        if run is None:
+            raise HTTPException(404, "Unknown run (it may have been evicted); run the prompt again")
+        self.runs.move_to_end(run_id)
+        return run
+
+    def capture(self, run: Run, act: str) -> Capture:
+        """Blocking (call from a worker thread): return the cached capture, building it on the model thread if needed.
+        Concurrent callers for the same (run, act) share one forward pass."""
+        provider = self.provider
+        if provider is None or run.run_id not in self.runs or provider.model_id != run.model_id:
+            raise HTTPException(404, "Unknown run (it may have been evicted); run the prompt again")
+
+        def build() -> Capture:
+            arr = self.executor.submit(provider.capture, run.token_ids, act).result()
+            return Capture(act=act, arr=arr)
+
+        try:
+            cap = self.cache.get((run.run_id, act), build)
+        except HTTPException:
+            raise
+        except ValueError as e:
+            raise HTTPException(400, str(e))
+        except Exception as e:
+            raise HTTPException(500, f"Capture of {act!r} failed: {type(e).__name__}: {e}")
+        if run.run_id not in self.runs:  # run was evicted while we were capturing
+            self.cache.drop_run(run.run_id)
+        return cap
+
+
+class LoadRequest(BaseModel):
+    model_id: str
+    device: str = "auto"
+    dtype: str = "float32"
+
+
+class RunRequest(BaseModel):
+    text: str
+    max_tokens: int = 512
+
+
+def create_app(manager: ModelManager | None = None, autoload: bool = True, model_id: str = DEFAULT_MODEL,
+               device: str = "auto", dtype: str = "float32", token: str | None = None) -> FastAPI:
+    mgr = manager or ModelManager()
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI):
+        if autoload and mgr.state == "idle":
+            mgr.load(model_id, device, dtype)
+        yield
+
+    app = FastAPI(title="ActLens", lifespan=lifespan)
+    app.state.manager = mgr
+
+    if token:
+        # Access token for a server that is reachable from outside (e.g. a tunnel from Colab). Open
+        # `/?token=...` once: the token is stored in an HttpOnly cookie and the URL is cleaned up.
+        # Scripts can send `Authorization: Bearer <token>` instead.
+        def valid(candidate: str | None) -> bool:
+            return bool(candidate) and hmac.compare_digest(candidate.encode(), token.encode())
+
+        @app.middleware("http")
+        async def require_token(request: Request, call_next):
+            bearer = request.headers.get("authorization", "")
+            if valid(request.cookies.get(TOKEN_COOKIE)) or valid(bearer.removeprefix("Bearer ").strip()):
+                return await call_next(request)
+            if request.method == "GET" and valid(request.query_params.get("token")):
+                url = request.url.remove_query_params("token")
+                resp = RedirectResponse(url.path + (f"?{url.query}" if url.query else ""), status_code=303)
+                # Lax, not Strict: the link is usually opened from another site (Colab), and a Strict cookie is
+                # not sent on the redirect that follows a cross-site navigation.
+                https = "https" in (request.url.scheme, request.headers.get("x-forwarded-proto", ""))
+                resp.set_cookie(TOKEN_COOKIE, token, httponly=True, samesite="lax", secure=https)
+                return resp
+            return PlainTextResponse("ActLens: missing or invalid access token. Open the full link printed "
+                                     "by the server (it ends in ?token=...).", status_code=401)
+
+    def guarded(fn, *a, **kw):
+        try:
+            return fn(*a, **kw)
+        except ValueError as e:
+            raise HTTPException(400, str(e))
+
+    def token_capture(run_id: str, act: str, layer: int | None = None) -> Capture:
+        """Validate `act` (a token-kind activation of this run's model) and capture it lazily."""
+        run = mgr.get(run_id)
+        spec = run.specs.get(act)
+        if spec is None:
+            raise HTTPException(400, f"unknown act {act!r}; expected one of {list(run.specs)}")
+        if spec.kind != "token":
+            raise HTTPException(400, f"act {act!r} is an attention pattern; use the /attn endpoints")
+        if layer is not None and not 0 <= layer < spec.n_layers:
+            raise HTTPException(400, f"layer {layer} out of range for {act} (0..{spec.n_layers - 1})")
+        return mgr.capture(run, act)
+
+    def attn_capture(run_id: str) -> Capture:
+        run = mgr.get(run_id)
+        if ATTN_ACT not in run.specs:
+            raise HTTPException(400, "this model does not expose attention patterns")
+        return mgr.capture(run, ATTN_ACT)
+
+    # ----- models / corpus -----
+    @app.get("/api/status")
+    def status():
+        return {**mgr.status(), "presets": PRESET_MODELS}
+
+    @app.post("/api/models/load", status_code=202)
+    def load_model(req: LoadRequest):
+        mgr.load(req.model_id, req.device, req.dtype)
+        return mgr.status()
+
+    @app.get("/api/corpus")
+    def corpus():
+        return CORPUS
+
+    # ----- runs -----
+    @app.post("/api/run")
+    async def run(req: RunRequest):
+        r = await mgr.run(req.text, max(1, min(req.max_tokens, 1024)))
+        return {
+            "run_id": r.run_id, "model_id": r.model_id, "tokens": r.tokens, "token_ids": r.token_ids,
+            "truncated": r.truncated, "elapsed_ms": round(r.elapsed_ms, 1), "model": r.model,
+            "activations": [sp.info() for sp in r.specs.values()],
+        }
+
+    @app.get("/api/run/{run_id}/overview")
+    def overview(run_id: str, act: str = "resid_post", stat: str = "norm", dim: int = 0):
+        cap = token_capture(run_id, act)
+        arr, meta = guarded(slicing.overview, cap, stat, dim)
+        return frame_response(meta, arr)
+
+    @app.get("/api/run/{run_id}/slice")
+    def slice_(run_id: str, act: str, layer: int, t0: int = 0, t1: int = 64, d0: int = 0, d1: int = 128,
+               max_h: int = Query(512, ge=1, le=2048), max_w: int = Query(1024, ge=1, le=4096),
+               agg: str = "absmax", order: str = "natural"):
+        cap = token_capture(run_id, act, layer)
+        arr, meta = guarded(slicing.token_dim_slice, cap, layer, t0, t1, d0, d1, max_h, max_w, agg, order)
+        return frame_response(meta, arr)
+
+    @app.get("/api/run/{run_id}/profile")
+    def profile(run_id: str, act: str, layer: int, order: str = "natural", bins: int = Query(512, ge=8, le=4096)):
+        cap = token_capture(run_id, act, layer)
+        arr, meta = guarded(slicing.dim_profile, cap, layer, order, bins)
+        return frame_response(meta, arr)
+
+    @app.get("/api/run/{run_id}/stats")
+    def stats(run_id: str, act: str, layer: int, t0: int = 0, t1: int = 64, d0: int = 0, d1: int = 128,
+              order: str = "natural", clip: bool = False):
+        cap = token_capture(run_id, act, layer)
+        return guarded(slicing.token_region_stats, cap, layer, t0, t1, d0, d1, order, clip)
+
+    @app.get("/api/run/{run_id}/axis_stats")
+    def axis_stats(run_id: str, act: str, layer: int, axis: str = "channel", stat: str = "norm",
+                   t0: int = 0, t1: int = 64, d0: int = 0, d1: int = 128, order: str = "natural",
+                   clip: bool = False, top: int = 10, bins: int = 64):
+        cap = token_capture(run_id, act, layer)
+        return guarded(slicing.axis_stats, cap, layer, axis, stat, t0, t1, d0, d1, order, clip, top, bins)
+
+    @app.get("/api/run/{run_id}/attn")
+    def attn(run_id: str, layer: int, head: int = -1, q0: int = 0, q1: int = 100000, k0: int = 0, k1: int = 100000,
+             max_q: int = Query(512, ge=1, le=1024), max_k: int = Query(512, ge=1, le=1024), agg: str = "max"):
+        cap = attn_capture(run_id)
+        if not 0 <= layer < cap.n_layers:
+            raise HTTPException(400, f"layer {layer} out of range (0..{cap.n_layers - 1})")
+        arr, meta = guarded(slicing.attn_slice, cap, layer, head, q0, q1, k0, k1, max_q, max_k, agg)
+        return frame_response(meta, arr)
+
+    @app.get("/api/run/{run_id}/attn_overview")
+    def attn_overview(run_id: str, stat: str = "entropy"):
+        cap = attn_capture(run_id)
+        arr, meta = guarded(slicing.attn_overview, cap, stat)
+        return frame_response(meta, arr)
+
+    @app.get("/api/run/{run_id}/attn_stats")
+    def attn_stats(run_id: str, layer: int, head: int, q0: int = 0, q1: int = 100000, k0: int = 0, k1: int = 100000,
+                   clip: bool = False):
+        cap = attn_capture(run_id)
+        if not (0 <= layer < cap.n_layers and 0 <= head < cap.n_heads):
+            raise HTTPException(400, "layer/head out of range")
+        return guarded(slicing.attn_region_stats, cap, layer, head, q0, q1, k0, k1, clip)
+
+    # ----- static frontend (production build) -----
+    if (FRONTEND_DIST / "index.html").is_file():
+        app.mount("/assets", StaticFiles(directory=FRONTEND_DIST / "assets"), name="assets")
+
+        @app.get("/{path:path}")
+        def spa(path: str):
+            if path.startswith("api/"):
+                raise HTTPException(404)
+            f = FRONTEND_DIST / path
+            return FileResponse(f if path and f.is_file() else FRONTEND_DIST / "index.html")
+
+    return app
+
+
+app = create_app()

actlens-0.1.0/backend/actlens/archs/__init__.py

@@ -0,0 +1,7 @@
+"""Architecture adapters: how each model family exposes its activations. See `base.ArchAdapter`."""
+from . import gpt2, llama  # noqa: F401  (importing registers the built-in adapters)
+from .base import ActDef, ArchAdapter, Dims, PreNormBlockAdapter, TraceCtx, get, has
+from .registry import ADAPTERS, load_plugins, register, resolve_adapter, supported_model_types
+
+__all__ = ["ActDef", "ArchAdapter", "Dims", "PreNormBlockAdapter", "TraceCtx", "ADAPTERS", "get", "has",
+           "load_plugins", "register", "resolve_adapter", "supported_model_types"]