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.

[![FastAPI](https://img.shields.io/badge/FastAPI-Backend-009688?style=flat&logo=fastapi)](https://huggingface.co/spaces/YOUR_HF_USERNAME/mnist-api)
[![Streamlit](https://img.shields.io/badge/Streamlit-Frontend-FF4B4B?style=flat&logo=streamlit)](https://YOUR_APP.streamlit.app)
[![TensorFlow](https://img.shields.io/badge/TensorFlow-2.x-FF6F00?style=flat&logo=tensorflow)](https://tensorflow.org)
[![Python](https://img.shields.io/badge/Python-3.10-3776AB?style=flat&logo=python)](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

[![Email](https://img.shields.io/badge/Email-taha@alphaorbit.site-blue?style=flat&logo=gmail)](mailto:taha@alphaorbit.site)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-taha--arain-0077B5?style=flat&logo=linkedin)](https://linkedin.com/in/taha-arain)
[![GitHub](https://img.shields.io/badge/GitHub-funterpie-181717?style=flat&logo=github)](https://github.com/funterpie)

---

*Assignment 8 β€” Deep Learning | SMIT AI & Data Science Batch 10*