ANN From Scratch

Table of Contents

• About
• Features
• Tech Stack
• Installation & Setup
• Usage
• Configuration
• Project Structure
• Contributing
• License
• Contact

About

ANN From Scratch is a minimal, from-scratch implementation of a feedforward neural network written in Python for the MNIST Digit Recognizer task. It’s ideal for learning and experimentation: inspect weights, run training and inference, and produce a Kaggle-compatible submission. A pre-trained model (mnist_model.pkl) is included for convenience but may not deliver competitive accuracy — use it as a starting point.

Features

• 🧠 Simple feedforward Neural Network implementation from scratch
• 🔍 Visualization tools (first-layer weight maps, confusion matrix)
• 📊 Notebook-driven analysis and qualitative error inspection
• 🛠️ Training and inference scripts that produce a Kaggle submission.csv

Tech Stack

• Python 3 (tested with 3.12.12)
• NumPy, Pandas, Matplotlib, Seaborn, scikit-learn (for visualization only)
• Minimal custom code under src/ (no PyTorch / TensorFlow required)

Installation & Setup

Prerequisites

• Python 3.12.12 installed
• Git (optional)

Create a virtual environment and install dependencies:

python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows (PowerShell)
.venv\Scripts\activate

pip install -r requirements.txt

Notes

• Place the dataset CSV files under data/ (train.csv, test.csv) as expected by src/data_loader.py.
• If you don't have the data, it will download automatically from Kaggle for you, to do so add a kaggle.json in a .kaggle dir.
• A saved model mnist_model.pkl may already exist in the repository root; it is provided as an example checkpoint but is not optimized for best accuracy.

Quick Start

Train the model:

python train.py

Note: You can change the model architecture and training arguments in this code easily.

Run experiments (Jupyter Notebook):

# or open and run the notebook
jupyter notebook notebooks/experiments.ipynb

Live Web Demo: To launch the real-time interactive drawing prediction web interface:

python app.py

Then navigate to the given URL, draw any digit on the canvas and see the result of the model you have just trained.

Project Structure

• train.py — training entrypoint
• app.py — real-time web application
• src/ — library code
  • network.py — NeuralNet implementation
  • data_loader.py — functions to load / preprocess MNIST CSVs
  • components.py — layers, activations, loss implementations
• data/ — expected datasets: train.csv, test.csv, sample_submission.csv
• notebooks/experiments.ipynb — visualization and analysis (examples included)
• requirements.txt — Python dependencies

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a topic branch (git checkout -b feat/awesome-feature)
3. Commit your changes (git commit -m "Add feature")
4. Push to your branch (git push origin feat/awesome-feature)
5. Open a Pull Request

Please open issues for bugs, questions, or design discussions.

License

This project uses the MIT License.

Contact

If you have questions or want to collaborate, open an issue or a pull request.