Getting Started

Start here

If you want the project-level context first, read Introduction.

Repository map

  • ARCHITECTURE.md – deep technical walkthrough from model math to FSM behavior.

  • hdl/gemv.py – sequential INT8 GEMV hardware block.

  • hdl/relu.py – combinational ReLU block.

  • tests/test_gemv.py – simulation tests and cycle-count checks.

  • inspect_kernels.py – tinygrad kernel inspection workflow.

  • train_mnist.py – training script that exports MNIST weights.

  • docs/guide/api-reference.md – auto-generated API docs from Python docstrings.

Quickstart

# install dependencies
uv sync

# run tests
uv run pytest tests/test_gemv.py -k "not slow"

# run docs locally
uv run sphinx-build -b dirhtml docs docs/_build/dirhtml
python -m http.server 4173 -d docs/_build/dirhtml

Then open http://localhost:4173.

Current scope

The current implementation is a correctness-first prototype:

  • hand-authored Amaranth GEMV module,

  • simulation-based verification,

  • and documented path toward automatic generation from tinygrad kernel IR.