Skip to content

Completion Report — Repo DONE (D1–D12)

Date: 2026-07-23
Plan: docs/21_E2E_ROADMAP_COMPLETE_REPO.md
Verdict: COMPLETE for required path (P0–P6). P7 stretch left optional.

D1–D12 status

Gate Status Evidence
D1 Packaging PASS pyproject.toml; pip install -e ".[dev]"; import bnn exports API; console script bnn
D2 Native kernel PASS bnn validate-native → err_nat=0.0, native_available: True
D3 Kernel speed floors PASS results/benchmark.json + tests/test_bench_regression.py (≥2× @4096; soft floor vs 3.61×)
D4 Compression 32× PASS bnn export-check → 32.00×; pytest test_export_check
D5 MNIST gates PASS results/train_results.json: FP 97.67% / binary 96.36% (gap 1.31 pp)
D6 CIFAR proxy PASS results/cifar10_proxy.* + bnn train-cifar + tutorial 03
D7 Wrapper CLI PASS bnn wrap; wrap_model policies; results/wrap_demo.json
D8 pytest + CI PASS 26 tests green; .github/workflows/ci.yml (Windows + Linux)
D9 Docs linked PASS README E2E link, tutorials, API stub, one-pager, bridges 22–25
D10 Eval harness PASS bnn eval-suite → regenerates results/SUMMARY.md
D11 Non-goals PASS ADR/guides: GPU → INT4/FP8; no CUDA-BNN 32×; NPU INT8-first
D12 Repro PASS seeds/--threads; MSVC notes; requirements.txt + pyproject pins

Tasks completed

  • Required tracker items in docs/21 §10 marked [x] for P0–P6.
  • Left open (non-blocking): OpenMP/AVX (P1.T5–T6), remaining P7 stretch (FINN/mobile/RAPL/ARM).
  • Closed in image/audio pass (docs/28_IMAGE_AUDIO_COMPLETION.md): longer CIFAR via train-image, ApproxSign (P2.T5), BinaryConv wrap (P3.T7), ImageNet stub (P7.T2).

What remains (optional only)

Item Why optional
OpenMP / AVX2 kernels ADR ACCEPTED-NON-GOAL (G11)
Full ImageNet train ADR ACCEPTED-NON-GOAL (G23)
RAPL board Joules CLOSED-BY-PROXY already
FINN / mobile export / ARM CI P7 stretch
Longer CIFAR / ReAct STE Nice-to-have quality polish

Key files added

  • pyproject.toml, .gitignore, .github/workflows/ci.yml
  • bnn/cli.py, bnn/export.py, bnn/eval_report.py
  • bnn/kernels/ternary_gemm.py
  • tests/*, tests/golden_floors.json
  • scripts/run_eval_suite.py, recommend_stack.py, distill_sketch.py, hf_tiny_wrap_demo.py
  • configs/wrap_default.json
  • docs/tutorials/*, docs/api/README.md, docs/22_HF_TO_GGUF_GUIDE.md … 25_ONEPAGER.md
  • CONTRIBUTING.md, CHANGELOG.md, this report

Verify in 5 commands

cd path\to\Binary-Neural-Networks
pip install -e ".[dev]"
python -m bnn.kernels.compile_native
pytest -q
bnn export-check
bnn eval-suite --skip-pytest

Honest notes

  • Image Bi-Real gap (~10 pp @ 30k/8ep) is expected vs fuller ReActNet schedules; not ImageNet SOTA.
  • Audio synthetic tones are an easy classification toy — not ASR quality evidence.
  • Conv pack compression can be <32× on small kernels (uint64 padding); Linear pack remains ~32×.
  • GitHub Actions MSVC compile uses continue-on-error if vcvars path differs; local Windows Build Tools verified.
  • Thesis unchanged: CPU/edge packed inference; GPU path is INT4/FP8 — not classic BNN.