From 024b0ead1b0839d3591bad3bdd3a6ab6bd20c381 Mon Sep 17 00:00:00 2001
From: Martin Kagamino Lehoux <martin@lehoux.net>
Date: Thu, 27 Aug 2026 12:10:55 +0200
Subject: Migrate to uv and Python 3.14 and add MNIST downloader to make the
 project runnable

Context / Problem: setup.py + requirements.txt (Python 3.5) no longer install on modern Python, matplotlib missing from deps, main.py save/load broke on numpy 2.x (inhomogeneous array / allow_pickle), and demo required manual mnist.npy/data files.

What: replace setup.py/requirements.txt with pyproject.toml (hatchling, PEP 621, requires-python >=3.10, classifiers 3.10-3.14), add .python-version 3.14 and uv.lock, add MultiLayerPerceptron/download.py (mlp-download) to fetch MNIST from storage.googleapis and generate data/train.npy, data/test.npy, mnist.npy, fix MultiLayerPerceptron/main.py layers class var and pickle handling with minimal changes, ignore .venv and track uv.lock, update README with uv workflow.

QA: verified uv sync --all-groups, uv run mlp-download, uv run python -m MultiLayerPerceptron.main loads and trains, ruff check passes.
---
 README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 52 insertions(+), 9 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 8118d9e..6807e1e 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,56 @@
+# multilayer-perceptron
+
+A simple multilayer perceptron implementation in NumPy.
+
+## Requirements
+
+- Python >=3.10 (pinned to 3.14 via `.python-version`)
+- [uv](https://docs.astral.sh/uv/)
+
+## Getting started
+
+```bash
+# install dependencies (creates .venv, respects uv.lock)
+uv sync --all-groups
+
+# quick sanity check (no data files needed)
+uv run python -c "from MultiLayerPerceptron.main import MultiLayerPerceptron; import numpy as np; mlp = MultiLayerPerceptron([2,4,1]); print(mlp.frontprop(np.array([0,1])) )"
+
+# download MNIST and prepare files (one-time, ~60k train / 10k test)
+uv run mlp-download
+#  creates data/train.npy, data/test.npy, mnist.npy (initial weights for [784,32,16,10])
+
+# run the MNIST demo (requires data/train.npy, data/test.npy, mnist.npy)
+uv run python -m MultiLayerPerceptron.main
+```
+
+Manual data tooling (MNIST `idx` → `npy` via `idx2numpy`):
+
+```bash
+uv run python -m MultiLayerPerceptron.download --help
+uv run python -m MultiLayerPerceptron.data  # legacy, expects idx files in cwd
+```
+
+Development:
+
+```bash
+uv run ruff check .
+uv run ruff format .
+uv run ty check
+uv run pytest
+```
+
 ## How to use
 
-1. Download data and save them in `.npy` format. See `data.py` for details.
-2. Write a run file for processing data. See script in `main.py` for details.
+1. Download data and save them in `.npy` format. See `MultiLayerPerceptron/data.py` for details.
+2. Write a run file for processing data. See script in `MultiLayerPerceptron/main.py` for details.
 
 ## TODO
-* [ ] Print stages
-* [ ] Learning samples method
-* [ ] Save mlp
-* [ ] Choose error
-* [ ] Choose function
-* [ ] CLI
-* [ ] Multithread / Multiprocess
\ No newline at end of file
+
+- [ ] Print stages
+- [ ] Learning samples method
+- [ ] Save mlp
+- [ ] Choose error
+- [ ] Choose function
+- [ ] CLI
+- [ ] Multithread / Multiprocess
-- 
cgit v1.3