Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
116 lines (80 loc) · 4.88 KB

CONTRIBUTING.md

File metadata and controls

116 lines (80 loc) · 4.88 KB
Raw

Contributing to Lucebox

Thanks for considering a contribution. Lucebox is a hub of self-contained optimization projects. Each one lives with its own README, benchmarks, and code, and the hub stays thin on purpose.

What we accept

  • Kernel improvements that preserve correctness and improve tok/s, tok/J, or memory footprint on the target hardware. Benchmark deltas required.
  • Speculative decoding algorithms that improve our current SOTA performances
  • Benchmark harness work under benchmarks/ once that directory starts shipping code.
  • Doc fixes and writeups — always welcome.

What we don't accept (yet)

  • Closed-source dependencies. Everything here has to be reproducible from public sources.

Luce DFlash Setup

dflash

Hardware: NVIDIA sm_86+ GPU (RTX 3090, A10, A40, 4090) or Jetson AGX Thor sm_110, 24 GB VRAM. Thor requires CUDA 13+.

On Ubuntu 22.04 or 24.04, one script installs all system dependencies — build-essential, cmake, git, git-lfs, and the CUDA Toolkit from NVIDIA's repo:

sudo server/scripts/setup_system.sh

The script is idempotent and configures nvcc on PATH for both bash and zsh. For other distros see the CUDA installation guide.

Tool Min version
GCC / G++ 11
CMake 3.21
Git 2.x
git-lfs any
CUDA Toolkit 12.0+
huggingface-cli any
uv 0.11+ (Python deps)

After setup, run these commands from the repository root:

git submodule update --init --recursive

# Python deps (workspace at the repo root; one .venv shared by dflash, pflash,
# and optionally megakernel). `uv` is the canonical installer; the legacy
# per-subproject `python -m venv .venv && pip install …` flow still works.
uv sync                       # dflash + pflash deps
uv sync --extra megakernel    # also compile the megakernel CUDA extension
bash scripts/check_uv_workspace.sh  # lockfile + frozen-sync import smoke

# C++/CUDA decoder
cmake -B server/build -S server -DCMAKE_BUILD_TYPE=Release
cmake --build server/build --target test_dflash -j

If cmake was previously run without CUDA, wipe the build directory first (rm -rf server/build) to avoid a stale compiler cache.

Before you open a PR

  1. Benchmark before and after on the same hardware, at the same power limit, with the same warmup. Numbers without methodology don't get merged.
  2. Run the existing correctness check (bench_pp_tg.py for megakernel) and confirm your change doesn't regress output parity.
  3. One concern per PR. Kernel/algorithms changes, docs, and build config go in separate commits or separate PRs.

Commit message format

Conventional commits:

feat(megakernel): fused QKV+RoPE path cuts per-token launch by 1 kernel
fix(dflash): clamp int8 DeltaNet state update before dequant
docs(hub): add DVFS methodology link

Allowed types: feat, fix, refactor, perf, docs, test, bench, build, chore, ci, revert. The scope is required and lowercase, and the subject stays within 300 characters with no trailing period. CI checks every commit in a pull request (commit-style.yml).

Automated code review

When a pull request is marked ready for review (or opened as ready), a bot reviews it for bugs once and posts a review: an inline comment for each issue it is confident about, and a summary. It only comments; it never approves or blocks a merge. To ask for another review later, or one on a draft, a maintainer adds the code-review label; the bot removes it when done. See code-review.yml.

Compacting commits before merge

When a pull request is ready, a maintainer can add the compact-commits label. A bot then folds a pull request with 2 or more commits into a few conventional commits (usually one per type), checks the code is unchanged, and force-pushes them to the branch. It never merges: press Merge as usual once CI passes on the new head. On a fork, keep "Allow edits by maintainers" ticked. See compact-commits.yml.

Hardware access

If you want to contribute benchmarks but don't have the hardware:

  • We can run numbered runs on our RTX 3090 (24GB) or Ryzen 395 AI Max (128GB). Open an issue with the PR.
  • Apple Silicon numbers need an M-series machine running powermetrics, not a remote box.

Getting help

  • Discord — fastest feedback
  • Issues — for bugs and proposals
  • Mention @Luce-Org/maintainers on a PR when it's ready for review

Licensing

By contributing you agree your work is licensed under the Apache License, Version 2.0, same as the rest of the repo (see LICENSE). Historical contributions before the relicense remain available under their original MIT terms in the git history.