ML Hueta (Machine Learning Playground)

Idea is to have more projects here for self-education but so far it's only MNIST 👹

MNIST Digit Classifier

This project is a small handwritten-digit classifier built around the MNIST dataset. It uses plain Python and NumPy (just to speed up the training A LOT) for the neural network logic, reads the raw IDX dataset files directly, and includes a simple Tkinter app for drawing a digit and running inference with saved weights.

What the project does

• Loads raw MNIST image and label files from mnist/data/
• Trains a feed-forward neural network without PyTorch or TensorFlow
• Applies light data augmentation during training
• Saves trained weights to weights.json
• Evaluates the model on the MNIST test split
• Lets you draw a digit in a desktop window and predict it

Model overview

The current model is a 3-layer fully connected network:

• Input: 784 values (28x28 grayscale image flattened)
• Hidden layer 1: 128 neurons with ReLU
• Hidden layer 2: 64 neurons with ReLU
• Output: 10 logits with softmax for digit classes 0-9

Training uses:

• Cross-entropy loss
• Mini-batch gradient descent
• Random shuffling each epoch
• Simple augmentation:
  • small shifts
  • small rotations
  • Gaussian noise

Requirements

This project is intentionally lightweight. You only need:

• Python 3
• numpy
• tkinter for the drawing UI

Example setup:

python3 -m venv .venv
source .venv/bin/activate
pip install numpy

tkinter is part of many Python installations by default. If the UI does not launch on your machine, you may need to install your OS-specific Tk package separately.

How to run

From the repository root:

1. Train the model

python3 mnist/train.py

This will:

• load the training split from mnist/data/
• train for a few epochs
• print loss and training accuracy
• overwrite weights.json with the newly trained parameters

2. Evaluate on the test set

python3 mnist/test.py

This reads weights.json and prints a final test accuracy score.

3. Launch the digit drawer

python3 mnist/main.py

In the UI:

• draw a digit on the 28x28-style canvas
• click Predict
• see the predicted number in the window

Notes and context

• The code is written in a straightforward, educational style rather than as a reusable package.
• Some earlier implementation ideas are still visible as commented-out code, which makes the training evolution easier to follow.
• weights.json is currently ignored by Git according to .gitignore, even though a copy exists in the working tree.
• The model has about 109k trainable parameters, which is enough to do a respectable MNIST baseline while staying easy to understand.