Upload Model Card

README.md

@@ -1,3 +1,68 @@
 ---
-license: mit
+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()