Contributing
Contributing
Setup
git clone https://github.com/tahabsn/flaxchat.git
cd flaxchat
pixi install
pixi run test-quick
Project Structure
flaxchat/
├── flaxchat/ # Core library (import flaxchat)
│ ├── gpt.py # THE model — start here
│ ├── optim.py # Muon + AdamW
│ ├── engine.py # Inference (KV-cache)
│ ├── common.py # Mesh, sharding, distributed
│ ├── config.py # All config dataclasses
│ ├── eval.py # CORE metric, BPB
│ ├── dataloader.py # BOS best-fit packing
│ ├── tokenizer.py # BPE (rustbpe + tiktoken)
│ ├── checkpoint.py # Orbax save/load
│ ├── report.py # Training reports
├── scripts/ # Runnable scripts (python -m scripts.XXX)
├── tasks/ # Eval tasks (MMLU, GSM8K, etc.)
├── tests/ # pytest tests
├── docs/ # This documentation
└── configs/ # YAML configs
Key Design Decisions
- No engine class — parallelism is baked into train steps, not a wrapper
- Frozen GPTConfig — registered as
jax.tree_util.register_staticfor JIT compatibility _NNX_LIST/_NNX_DICT— compat shim for Flax 0.11 vs 0.12compute_init()— single function that does distributed init + mesh creation- Replicated sharding for inference —
_to_device(arr, replicated)matches model params
Running Tests
pixi run test # Complete local suite
pixi run test-quick # Skip slow and accelerator tests
pixi run test-coverage # Enforce the branch-coverage floor
pixi run test-multidevice # Exercise an eight-device CPU mesh
pixi run -- pytest tests/test_model.py -v # Specific file
Code Style
- No docstrings on obvious functions
- Type hints where they help (not everywhere)
- Prefer
jnpoperations over numpy inside JIT - Use
nnx.data()for non-trainable module fields - Use
jax.lax.dynamic_slice/dynamic_update_slicefor traced indexing print0()for distributed-safe printing (only process 0)
Test Coverage
Well tested:
- Model forward/backward, loss, gradients, softcap, causal masking
- Muon optimizer standalone + setup_optimizer integration
- Config creation/serialization (YAML, JSON, dict, roundtrip)
- KV-cache vs padded generation consistency
- Calculator and guarded-execution behavior
Risk-based per-module coverage floors are enforced by
scripts/check_coverage.py. The coverage job prints each protected module’s
signed distance from its floor, and a low protected module fails even when the
global percentage passes, so unrelated covered code cannot mask a regression.
Accelerator-only behavior is covered by the on-demand bundled Kaggle workflow.
Ruff enables Pyflakes, fatal pycodestyle checks, and Bugbear correctness rules.
The documented per-file Bugbear exceptions in pyproject.toml are the deferred
legacy baseline; new files receive every selected rule. Pyright checks the full
flaxchat and scripts trees, with its remaining JAX-heavy modules listed in
the adjacent explicit migration baseline rather than silently excluded by a
narrow include list.
Dependency and CI policy
- Commit
pixi.lockwhenever dependency metadata changes and review JAX, accelerator-plugin, Orbax, and Flax compatibility together. - GitHub Actions are pinned to reviewed commit SHAs. Dependabot proposes monthly updates; reviewers verify the upstream tag before merging.
- Routine changes use the single Linux validation job. Run the manual macOS, Kaggle GPU, or Kaggle TPU workflows only when the affected platform or a release candidate needs fresh evidence.
- Release tags alone run the supported-Python install matrix, checksum/SBOM generation, full gates, and artifact attestation.