drowse

Drowse is a local workbench for mechanistic interpretability on large language models. It ships a local dashboard, a Python API, and an HTTP server compatible with both OpenAI and Ollama clients. Quick start installs from a source checkout in a virtual environment (`uv pip install -e .`) and launches with `drowse serve google/gemma-3-4b-it`, opening a dashboard at localhost:8000. The first launch downloads the model and fits 17 bundled concept probes, stored under `~/.drowse/`. CUDA and Apple Silicon MPS are supported, with optional FlashAttention and bitsandbytes quantization extras. A hosted browser edition is included as an isolated Svelte PWA for on-device WebGPU inference. The README is candid about its limits: runtime and distribution locks are marked verified, but release checks do not guarantee GPU stability under model load; Gemma PT has a matched-weight numerical discrepancy and Qwen 3.5 still needs matched-quantization validation. Device checks report GPU vendor and architecture, block profiles with recorded device losses, and conservatively block Windows Chromium on identified Intel gen-9 adapters. WebGPU is mandatory for inference, with no cloud or CPU-only fallback, and prompts, conversations, activations, and fitted artifacts stay on the device. The WebUI organizes conversations as branching thread trees with rerolling, save/load, and standard sampling controls. Chat mode renders model templates as turns with collapsible thinking and dynamic role handling; raw mode exposes a single buffer for base models. Tokens can be highlighted by probe scores or logprob surprise, and clicking a token opens a detail drawer with geometry, logits (including token forking), SAE, and J-lens views. Instruments are grouped into Subspace, Manifold, SAE, and Lens tabs, with additional analysis tools for fitting, merging, installing, and inspecting manifolds, scoring restricted-choice templates, managing steering, and checking server health. Concepts are extracted as manifolds or subspaces: a 1D flat subspace is a steering vector, higher-rank flat subspaces are orthogonal groups, and curved manifolds fit nonlinear surfaces. Bundled probes cover epistemic, alignment, register, and cultural concept pairs, plus larger optional sets for personas, emotions, and months. A unified steering expression syntax works across Python, YAML, OpenAI, Ollama, and the native API, supporting addition/subtraction, shared-component keep/remove operators, mean ablation, manifold node selection, token-phase restrictions, decode-window restrictions, and live probe gates. Extraction has the model answer baseline prompts as each concept, then fits hidden states to a manifold or subspace, using a Mahalanobis metric for layer allocation and discriminative layer selection. Monitoring readings include fitted coordinates, subspace fraction, nearest nodes with soft assignment, and off-surface residuals for curved manifolds. The Jacobian lens follows published verbalizable-workspace work, and SAE support can use published SAELens releases or train local SAEs. The CLI has eight verbs: serve, manifold, pack, experiment, config, template, lens, and sae, covering reproducible preparation, distribution, and batch work. Manifold packs can be installed from local paths or distributed as Hugging Face model repositories, and a `.drowse` ZIP transports one manifold closure plus its referenced template. A fitted two-node PCA manifold can be exported as a llama.cpp control-vector GGUF. Hosted-browser discovery accepts only Hugging Face repositories tagged `drowse-manifold` with a single root `.drowse` and a root `manifold.json`, resolving to an immutable commit and verifying declared repository and revision. One `drowse serve` process exposes four surfaces on one port: the WebUI, OpenAI-compatible `/v1/*`, Ollama-compatible `/api/*`, and a native `/drowse/v1/*` API for sessions, loom trees, probes, manifolds, templates, SAE/J-LENS lifecycle and replay, SSE, and token-plus-measurement WebSockets. The Python API centers on `DrowseSession`, with `extract`, `add_probe`, `generate`, `generate_stream`, `generate_batch`, `generate_sweep`, and `score_choices`, plus notebook plotting helpers. Model support includes end-to-end tested paths for Qwen 2/3/3.5, Gemma 2/3/4, Mistral 3 and Ministral 3, Llama, GLM, gpt-oss, and Talkie, with additional architectures wired through a generic residual-layer interface and warnings when untested. The README explicitly frames Drowse as targeting a trusted local machine or lab network rather than a hardened multi-tenant service, and advises API keys, TLS, rate limits, and isolation if bound beyond a trusted host. Repository Python execution is disabled by default and requires explicit opt-in. State lives under `~/.drowse/` (movable via `$DROWSE_HOME`), while conversation saves are explicit browser-downloaded JSON files rather than autosaved. The project is licensed AGPL-3.0-or-later and credits Representation Engineering, repeng, difference-of-means extraction, Goodfire's manifold work, Anthropic's Assistant Axis framing, and the Gurnee et al. J-lens method.