README.md

---
language: en
tags:
- image-classification
- pytorch
- tensorflow
- scikit-learn
- mnist
- computer-vision
datasets:
- mnist
metrics:
- accuracy
---

# MNIST Framework Bake-off Models

## Model Details
This repository contains pre-trained model weights for handwritten digit classification (0-9) trained on the MNIST dataset. 
It was developed as part of an end-to-end MLOps and framework benchmarking portfolio project. 

Three distinct architectures are hosted here to demonstrate the trade-offs between deep learning and classical machine learning on spatial data:

1. **CNN (PyTorch & TensorFlow) (`pytorch_cnn_weights.pth`, `tf_cnn_model.keras`):** A Convolutional Neural Network designed for high accuracy and $O(1)$ inference latency.
2. **Random Forest Classifier (Scikit-Learn) (`sklearn_rf.joblib`):** A baseline classical Machine Learning architecture to establish performance bounds before applying deep learning.
3. **Soft-Voting Ensemble (Scikit-Learn) (`sklearn_ensemble.joblib`):** An ensemble combining a Multi-Layer Perceptron (MLP) and a K-Nearest Neighbors (K-NN) classifier.

* **Developed by:** AKinoshi
* **Model Date:** July 2026
* **Model Type:** Image Classification 
* **License:** MIT

## Intended Use
* **Primary Use Case:** Educational benchmarking and portfolio demonstration of framework agility and model deployment.
* **Out-of-Scope:** This model is trained exclusively on cleanly centered, 28x28 grayscale digits. It is not intended for general-purpose Optical Character Recognition (OCR) on real-world, noisy documents or alphabetic text.

## Training Data
The models were trained on the **MNIST dataset**, which consists of 70,000 images of handwritten digits normalized to fit into a 28x28 pixel bounding box and anti-aliased.
* **Preprocessing (PyTorch / TensorFlow):** Pixel values normalized to a range of [-1, 1] or [0, 1] with an explicit channel dimension added.
* **Preprocessing (Scikit-Learn):** MinMax scaling applied to flatten 1D arrays, scaling intensities from [0, 255] down to [0, 1].

## Evaluation Metrics
Models were evaluated using **Accuracy** and a detailed classification report (Precision, Recall, F1-Score) on a 20% holdout test set.

* **CNN:** ~99.08% Test Accuracy. Demonstrates excellent spatial feature extraction through convolutional filters.
* **Random Forest Classifier:** ~96.75% Test Accuracy. Fast CPU training, but loses spatial hierarchy due to image flattening.
* **Scikit-Learn Ensemble:** ~98.33% Test Accuracy. While highly accurate, the K-NN component introduces significant inference latency $O(N \times D)$, making it less suitable for real-time production endpoints compared to the compiled CNN.

## How to Get Started with the Model

You can dynamically download these weights directly into your Python scripts using the `huggingface_hub` library.

```python
# pip install huggingface_hub torch

import torch
from huggingface_hub import hf_hub_download

# 1. Download the PyTorch weights (caches automatically)
model_path = hf_hub_download(
    repo_id="AKinoshi/mnist-framework-bakeoff", 
    filename="pytorch_cnn_weights.pth"
)

# 2. Load into your PyTorch architecture
# model = DigitClassifierCNN()
# model.load_state_dict(torch.load(model_path, map_location=torch.device('cpu')))
# model.eval()