Thanks for your interest in M*! Contributions of all kinds are welcome, and you don't need to read a rulebook first.
- Bug? Open a bug report.
- Idea or feature? Open a feature request.
- Want a model supported? Open a new model request.
General questions are welcome too — a plain issue or an email to atindra@cs.stanford.edu is fine.
- Fork and create a branch.
- Make a focused change.
- Run
ruff check .(CI enforces it). - Open a PR against
main. It runs CI and gets a review before merging. To merge, add it to the merge queue ("Merge when ready"): the queue runs CI on your PR merged withmainand with every PR queued ahead of it, and lands it only if that passes, so two PRs that are each green alone can't breakmaintogether.
The Python HTTP frontend is being retired in favor of the Rust one (rust/server/). A new route, request field, response format or model OpenAI adapter goes into both in the same PR, with a test in test/rust/ comparing the two; see invariant 15 in AGENTS.md.
During the Mintlify migration, docs/*.rst remains the canonical source. If a guide
has a counterpart in docs/mintlify/, update its .rst and .mdx files in the
same PR, including model, resource, installation, and environment-variable changes.
See the Mintlify contributor guide for preview and
validation commands. The generated Python API reference remains on Sphinx.
A bot posts a review when someone asks for one with a /review command on a PR, from a fork or not; it never runs on its own when a PR is opened or pushed to. A contributor (the team, or anyone who has had a PR merged here) can comment /review light on their own PR for a light review, and someone with write access can do so on any PR, or, on a PR whose author has write access, comment /review nogpu for the nogpu mode, which also reports P3 improvements and design questions, or /review, which adds a live GPU test and can approve a PR that meets a fixed rule. It checks the invariants in AGENTS.md (the model/engine boundary, resource declarations, rank lockstep, one graph runtime, documented environment variables) and cites them by number. Light and nogpu reviews are advisory, and a maintainer still reviews your PR. Comment the same command again for a re-review after pushes. Reply to disagree. Details in .github/review/.
These are welcome, with two conditions: read AGENTS.md first (point your agent at it, or symlink it to whatever filename your tooling expects), and say in the PR description that AI assistance was used, which tests you ran, and what the results were. You need to understand and be able to defend every line you submit.
On Apple Silicon macOS, you can check your current worktree before committing or pushing:
./scripts/ci/mac.sh allThis is opt-in: no Git hooks are installed and running it is not a contribution
requirement. It uses native linux/arm64 Docker containers. Passing these Mac
checks does not establish that the full x86 CPU suite or GPU tests pass. GitHub
continues to run the full CPU Core suite on its Ubuntu runners.
You need Git, Python 3, and an ARM Docker engine, such as Docker Desktop or Docker with Colima on your Mac. Remote x86 Docker engines are unsupported. Colima is not an mstar dependency. Allocate at least 8 GiB of VM memory for the Rust build; validation used 4 CPUs and 8 GiB. Rust release linking can exhaust a 2 GiB VM even with one compilation job.
The runner uses your current Docker context. You can select another configured
context with DOCKER_CONTEXT=your-context ./scripts/ci/mac.sh all. It does not
create, resize, or reconfigure your VM. The initial run downloads images,
Python packages and Rust dependencies; no GPU or model weights are needed.
This first version supports Apple Silicon macOS with rootful Docker, without
user-namespace remapping. Intel Macs, other host operating systems and x86
emulation are outside its supported scope. In particular, setting
CI_PLATFORM=linux/amd64 is rejected.
| Command | Checks |
|---|---|
./scripts/ci/mac.sh lint |
Ruff and runner regression tests |
./scripts/ci/mac.sh cpu-smoke |
ARM-compatible subset of the CPU Core suite |
./scripts/ci/mac.sh dynamo |
Dynamo bridges and registration |
./scripts/ci/mac.sh rust |
Native Rust tests, server/extension builds and Python integration tests |
all runs these four checks sequentially and stops at the first failure.
cpu-smoke runs the CPU Core job's test paths without
the modules listed in test/cpu-mac-exclude.txt:
test_waypoint_components.pytest_waypoint_dit.pytest_flex_attention_resource.pytest_waypoint_benchmark_videos.py
The first three invoke compiled FlexAttention, which requires AVX2 with the
pinned PyTorch CPU implementation (seen with 2.9.1). The video test hits an illegal
instruction in PyAV 19.0.1 encoding in the tested Apple VM; this also reproduces
without mstar. The entire modules are excluded,
including their portable structural cases. The runner prints the exclusions
and saves the exact pytest arguments in cpu-smoke-tests.txt with the
reports. New core modules are included automatically unless explicitly
excluded; invalid or stale exclusions fail the check. Existing GPU/optional-feature skips are reported by pytest.
No test assertions are changed for the Mac runner.
CPU smoke also disables PyTorch's oneDNN backend in its test process: the pinned ARM wheel crashes on a standalone BF16 Linear operation in the tested Apple VM. BF16 tests still execute through PyTorch's CPU fallback with their original assertions. These checks do not cover optimized oneDNN kernels. The setting does not affect GitHub or other jobs.
The local installation and check scripts follow the existing GitHub jobs, with
Python 3.12 and a separate environment for each check. The local image uses
Debian ARM while GitHub uses Ubuntu x86. Some dependencies and Rust stable are
unpinned; resolved packages and tool versions are recorded per run. When
updating CI dependencies, update scripts/ci/install.sh and
scripts/ci/cpu-torch.txt alongside .github/workflows/ci.yml.
The snapshot includes current tracked files and eligible untracked source, including uncommitted edits. Untracked ignored files, local environments and build outputs are excluded; tracked files are retained. Tests run on copies inside disposable containers and do not modify your checkout. This checks the working tree, rather than only staged changes or GitHub's PR merge commit.
Logs, timings and pytest reports go to .ci-results/. Download and Rust build
caches use Docker volumes named mstar-ci-*. Images and caches remain for later
runs; containers and temporary snapshots are removed. Ctrl-C also removes the
active container and retains its logs. There is no automatic local job timeout.
Rust defaults to two parallel compilation jobs; use CI_BUILD_JOBS=1 to reduce
parallelism when needed.
The native Rust server links against the build interpreter's libpython.
When launching the binary separately, make that matching library available to
the dynamic loader. The local Rust check configures LD_LIBRARY_PATH for it.
The CPU Core job runs every test module under the directories in
CPU_TEST_PATHS (scripts/ci/select_cpu_tests.py):
test/modular/, test/distributed/, the model-local mstar/model/*/tests/
and a few more, on a GitHub-hosted Ubuntu runner whenever a PR targeting main
is opened, updated or reopened. It runs as two shards on two runners, "CPU Core 1/2"
and "CPU Core 2/2", each split over the runner's 4 cores with pytest-xdist; a test
file goes whole to one shard, by a stable hash of its path
(scripts/ci/shard_plugin.py, MSTAR_CI_SHARD=i/n). test_tp_async_lockstep_sim.py
runs in a third job beside them, "CPU Core (TP lockstep sim)", and a "CPU Core" job
passes only when all three did. It needs no GPU or model weights. New updates cancel
an older CPU Core run for the same PR. The installation and invocation commands are in
the CI workflow.
There is no list of test files to add to: a new module under one of those
directories runs in CI as soon as it exists, so it must pass or skip on a
CPU-only machine without model weights or optional packages. A test module
anywhere else must be listed in NOT_CPU_CORE in the same script, with the
place it runs instead; test/ci/test_cpu_selection.py fails on a module in
neither, and on any module the old test/cpu-core.txt ran that is no longer
selected. Within the selected directories:
- a module that needs CUDA throughout sets
pytestmark = pytest.mark.skipif(not torch.cuda.is_available(), reason=...); - a module that imports an optional package at module level calls
pytest.importorskip("<module>")with the import name (flashinfer,misaki,qwen_tts, ...) before that import; - a single test that needs one makes the same call at its top, and a real-weights test skips when the checkpoint isn't cached;
- a test that is broken on
maingets@pytest.mark.skip(reason=...)in its own file, with a reason that says why and names the PR or issue fixing it when one exists, so the fix removes the skip; - a test that reads or writes a fixed path or port uses
tmp_pathor a free port instead, since the workers run tests concurrently; - a test module outside a Python package has a basename no other selected module has (pytest imports it by that name; the guard checks);
- a guard on a reference package named like an mstar model (
kokoro,chatterbox,omnivoice, ...) imports a submodule only the reference has, e.g.pytest.importorskip("kokoro.model").mstar/modelis a namespace package, so pytest puts it onsys.pathfor the model-local tests, and from then on the bare name finds mstar's own model package for the rest of the session.
Run the new file with CI's installation before opening the PR. Check ARM
compatibility before extending the Mac exclusion list. CI prints the slowest
tests and retains JUnit reports for seven days. Which checks
must pass before a PR merges, in the queue or not, is set in main's branch protection rule;
every required check has to run on the merge_group event too.
The randomized tests in test/modular/test_kv_page_ownership.py add their seed
and recent operations to a failure; rerun one with the node id pytest prints.
Start with the Adding a New Model guide — it walks through the component graph, Walks, and the submodule pattern.
By contributing, you agree that your contributions are licensed under the repository's Apache-2.0 license.