|
| 1 | +# Contributing to Atome LM |
| 2 | + |
| 3 | +Thanks for considering a contribution. This is a small, focused project — a tiny ternary language model + a C99 inference engine that talks to it bit-exactly. Read `PROJECT_CONTENT.md` first; it covers what you must not break. |
| 4 | + |
| 5 | +## Quick start |
| 6 | + |
| 7 | +```bash |
| 8 | +git clone https://github.com/atome-lm/atome-llm-kit |
| 9 | +cd atome-llm-kit |
| 10 | +./install.sh |
| 11 | +. .venv/bin/activate |
| 12 | +pytest -q # expect: 146 passed (or 145 + 1 skipped without qemu-system-arm) |
| 13 | +``` |
| 14 | + |
| 15 | +## Reporting bugs |
| 16 | + |
| 17 | +Open an issue on GitHub with: |
| 18 | + |
| 19 | +- what you ran (exact command) |
| 20 | +- what you expected |
| 21 | +- what happened (full error, not paraphrased) |
| 22 | +- your platform: OS, Python version, and `python -c "import torch; print(torch.__version__)"` |
| 23 | + |
| 24 | +If you hit a parity failure (Python forward ≠ C forward), please attach the failing seed and any checkpoint you trained — these are the highest-priority bugs. |
| 25 | + |
| 26 | +## Submitting a pull request |
| 27 | + |
| 28 | +1. Fork the repo and create a branch off `main`. |
| 29 | +2. Make your change. |
| 30 | +3. Run the full test suite — every PR must keep `pytest -q` green. |
| 31 | +4. If your change touches `atome_llm/core/`, `c_engine/upstream/`, or the export format, **specifically confirm** these tests still pass: |
| 32 | + - `tests/test_parity_with_c.py` — single-forward Python ↔ C parity |
| 33 | + - `tests/test_parity_multitoken.py` — multi-token Python ↔ C parity |
| 34 | + - `tests/test_export_format.py` — binary format + header generation |
| 35 | +5. Open the PR. CI will rerun the suite on Python 3.10 / 3.11 / 3.12. |
| 36 | + |
| 37 | +## Scope of acceptable changes |
| 38 | + |
| 39 | +Welcome: |
| 40 | + |
| 41 | +- Bug fixes |
| 42 | +- New test coverage (especially fuzz cases on the C parser and edge inputs to `atome_predict_next` / `atome_generate`) |
| 43 | +- Performance improvements that preserve bit-exact parity |
| 44 | +- Documentation fixes and clarifications |
| 45 | +- New MCU target boards under `c_engine/targets/`, *as long as they don't change the upstream engine* |
| 46 | +- New baselines under `atome_llm/baselines/` for honest A/B comparison |
| 47 | + |
| 48 | +Out of scope, please don't open PRs for these: |
| 49 | + |
| 50 | +- Adding heap allocation, dynamic memory, or libc dependencies to `c_engine/upstream/` |
| 51 | +- Adding "shouldn't happen" fallbacks to deterministic code paths |
| 52 | +- Bundling new tokenizers (BPE / sentencepiece) — the byte tokenizer is a load-bearing design choice for MCU flash budget |
| 53 | +- Changes that break Python ↔ C parity, even if they improve a benchmark |
| 54 | +- New features that promote code from `c_engine/experiments/` into `c_engine/upstream/` without full parity + bounds-check coverage |
| 55 | + |
| 56 | +## Coding standards |
| 57 | + |
| 58 | +- Python: keep it simple, no helper layers, no decorators-for-style. Match the existing voice — small functions, no premature abstraction, comments only when the *why* is non-obvious. |
| 59 | +- C: C99 only, no GNU extensions, no libc beyond `<string.h>` / `<math.h>` / `<stdint.h>`. Static buffers sized by compile-time `ATOME_*` macros. Bounds-check all public API inputs. |
| 60 | + |
| 61 | +## Security |
| 62 | + |
| 63 | +If you find a security issue (anything that lets a malicious checkpoint or `.atome` blob compromise a host running the engine), please email **hello@atomelm.com** instead of filing a public issue. We'll coordinate disclosure. |
| 64 | + |
| 65 | +## License |
| 66 | + |
| 67 | +By submitting a contribution you agree it will be released under the Apache License 2.0 (the project license — see `LICENSE`). |
0 commit comments