File size: 4,579 Bytes
ef500f9 e8e2477 ef500f9 e8e2477 ef500f9 e8e2477 ef500f9 e8e2477 ef500f9 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 | # π’ MNIST Digit Classifier
> Handwritten digit recognition powered by a Keras Dense Neural Network β deployed via FastAPI on HuggingFace Spaces + Streamlit Cloud frontend.
[](https://huggingface.co/spaces/YOUR_HF_USERNAME/mnist-api)
[](https://YOUR_APP.streamlit.app)
[](https://tensorflow.org)
[](https://python.org)
---
## π Live Demo
| Service | URL |
|---------|-----|
| π Streamlit Frontend | `https://YOUR_APP.streamlit.app` |
| β‘ FastAPI Backend | `https://YOUR_HF_USERNAME-mnist-api.hf.space` |
| π API Swagger Docs | `https://YOUR_HF_USERNAME-mnist-api.hf.space/docs` |
---
## π Project Structure
```
mnist-digit-classifier/
β
βββ main.py # FastAPI backend
βββ app.py # Streamlit frontend
βββ Notebook.ipynb # Model training notebook
βββ mnist_model.keras # Trained Keras model
βββ Dockerfile # HuggingFace Docker config
βββ requirements.txt # Backend dependencies
βββ sample_digits/ # Sample test images (0β9)
β βββ digit_0.png
β βββ digit_1.png
β βββ ...
βββ README.md
```
---
## π§ Model Architecture
```
Input Layer β 784 neurons (28Γ28 flattened)
Dense Layer 1 β 256 neurons, ReLU activation
Dense Layer 2 β 128 neurons, ReLU activation
Output Layer β 10 neurons, Softmax activation
```
| Parameter | Value |
|-----------|-------|
| Dataset | MNIST (70,000 images) |
| Optimizer | Adam |
| Loss | Sparse Categorical Crossentropy |
| Epochs | 10 |
| Batch Size | 128 |
| **Test Accuracy** | **97.65%** |
---
## β‘ API Reference
### Health Check
```http
GET /
```
```json
{
"message": "MNIST Digit Classifier API is running.",
"docs": "/docs"
}
```
### Predict Digit
```http
POST /predict/
Content-Type: multipart/form-data
```
**Request:** Upload any PNG/JPG image of a handwritten digit.
**Response:**
```json
{
"filename": "digit_3.png",
"predicted_digit": 3,
"confidence": 0.9921,
"all_probabilities": {
"0": 0.0001, "1": 0.0000, "2": 0.0012,
"3": 0.9921, "4": 0.0003, "5": 0.0020,
"6": 0.0001, "7": 0.0002, "8": 0.0035, "9": 0.0005
}
}
```
### cURL Example
```bash
curl -X POST "https://YOUR_HF_USERNAME-mnist-api.hf.space/predict/" \
-F "file=@digit_0.png"
```
---
## π οΈ Local Setup
```bash
# 1. Clone the repo
git clone https://github.com/funterpie/mnist-digit-classifier.git
cd mnist-digit-classifier
# 2. Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Run FastAPI backend
uvicorn main:app --reload
# β http://127.0.0.1:8000/docs
# 5. Run Streamlit frontend (new terminal)
pip install streamlit
streamlit run app.py
# β http://localhost:8501
```
---
## βοΈ Deployment Guide
### FastAPI β HuggingFace Spaces (Docker)
1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
2. Select **Docker** as SDK
3. Push these files:
- `main.py`
- `mnist_model.keras`
- `requirements.txt`
- `Dockerfile`
- `README.md`
```bash
git clone https://huggingface.co/spaces/YOUR_HF_USERNAME/mnist-api
cd mnist-api
# copy your files here
git add . && git commit -m "deploy: FastAPI MNIST backend"
git push
```
### Streamlit Frontend β Streamlit Cloud
1. Push `app.py` + `requirements.txt` + `sample_digits/` to GitHub
2. Go to [share.streamlit.io](https://share.streamlit.io)
3. Connect your GitHub repo
4. Set main file: `app.py`
5. Update `API_URL` in `app.py` to your HF Space URL
---
## π¨βπ» Author
**Muhammad Taha Sattar Arain**
Founder & CEO β [Alpha Orbit](https://alphaorbit.site)
SMIT Batch 10 β AI & Data Science
[](mailto:taha@alphaorbit.site)
[](https://linkedin.com/in/taha-arain)
[](https://github.com/funterpie)
---
*Assignment 8 β Deep Learning | SMIT AI & Data Science Batch 10*
|