Skip to content

Latest commit

 

History

History
94 lines (70 loc) · 4.15 KB

CONTRIBUTING.md

File metadata and controls

94 lines (70 loc) · 4.15 KB

Contributing to drowse

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.

Dev setup

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.

Running tests

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 tests

Tests marked gpu need CUDA or Apple Silicon MPS and may download model weights. CI runs the non-GPU suite on Python 3.13.

Static checks

ruff check .
pyright
python -m build

ruff check . --fix applies safe automatic lint fixes. pyright covers the package, tests, examples, and maintained scripts according to pyproject.toml.

Working on the web UI

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.

Web app (drowse.ai)

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.

Adding a new model architecture

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.

PRs

  • 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.md and the owning subtree AGENTS.md in the same change. Check CLI examples against live drowse <verb> --help output 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.

Questions

Please reach out to me or open an issue. For anything security-sensitive, also see SECURITY.md.