Bug reports, focused fixes, new model support, and documentation improvements are
all welcome. The repository supports Python 3.11–3.13 and uses pip plus
setuptools; there is no lockfile-based development workflow.
git clone https://github.com/stdlogits/drowse
cd drowse
pip install -e ".[dev]"Use [hf] for streamed dataset-backed lens/SAE fitting, [gguf] for GGUF
export, [research] for the analysis examples, and [notebook] for the Plotly
notebook helpers. SAELens, the HTTP server, and the prebuilt dashboard are part
of the base install. [cuda] adds bitsandbytes and Hugging Face
kernels; [flash] adds the stable, tested FlashAttention path. Install
.[cuda,flash] for both. The CUDA and FlashAttention extras are Linux/CUDA-only.
pytest -q -m "not gpu" # CI-equivalent CPU suite
pytest -q tests/ # everything available on this machine
pytest -q tests/gpu/test_smoke.py # real-model smoke testsTests marked gpu need CUDA or Apple Silicon MPS and may download model weights.
CI runs the non-GPU suite on Python 3.13.
ruff check .
pyright
python -m buildruff check . --fix applies safe automatic lint fixes. pyright covers the
package, tests, examples, and maintained scripts according to pyproject.toml.
The dashboard source is a Svelte 5 and Vite app at the repo's top-level webui/ directory. The committed drowse/web/dist/ bundle is the source of truth that ships in the wheel.
cd webui
npm ci
npm run dev # vite dev server on http://localhost:5173 with hot reload
npm run check # svelte-check + theme-token validation
npm run build # writes ../drowse/web/dist/npm run dev proxies /drowse, /v1, and /api (including WebSockets) to
http://localhost:8000. Keep drowse serve <model> running in another shell.
The production bundle under drowse/web/dist/ is committed package data, so UI
changes must include the rebuilt bundle. CI rebuilds it and fails on any diff.
The hosted browser app lives in
stdlogits/drowse.ai. It builds this
repository's dashboard source (webui/src) from a pinned submodule, so a change
to shared dashboard code lands here first and reaches the site when its
submodule is bumped. Its own checks run in that repository's CI.
The parity fixtures under tests/fixtures/browser/ are the Python reference
outputs the browser runtime replays. Changing engine semantics they cover means
regenerating them here and updating the browser runtime in drowse.ai.
If you want to add another model's architecture, add an entry to drowse/model/loading.py:_ARCH_PROFILES, keyed by the HuggingFace model_type: _prof(accessor), or _prof(accessor, tested=True) once it has a real-model smoke result. The accessor takes a loaded model and returns the list of transformer blocks; _LAYER_ACCESSORS and _TESTED_ARCHS are derived views over that one registry. The rest of the code (capture.py, hooks.py, monitor.py) doesn't depend on the architecture.
If the model is quirky (multimodal text extraction, FP8 dequantization,
nonstandard tokenizer behavior), inspect the existing text-only multimodal path
and architecture-specific workarounds in drowse/model/loading.py. Include a focused
accessor test and a real-model smoke result when possible.
- If you're adding an architecture, include the exact model ID, device, dtype or quantization mode, and the commands you ran. A fit or generation using a bundled manifold is the most useful end-to-end proof.
- If you change a cross-cutting runtime contract, update
ARCHITECTURE.mdand the owning subtreeAGENTS.mdin the same change. Check CLI examples against livedrowse <verb> --helpoutput rather than copying an older command list. - Please don't bump the version in your PR unless you want a new release; the PyPI publish workflow is triggered by a version update.
Please reach out to me or open an issue. For anything security-sensitive, also see SECURITY.md.