mnist-api / README.md
funterpie's picture
Upload 6 files
ef500f9 verified
|
Raw History Blame Contribute Delete
4.58 kB

πŸ”’ MNIST Digit Classifier

Handwritten digit recognition powered by a Keras Dense Neural Network β€” deployed via FastAPI on HuggingFace Spaces + Streamlit Cloud frontend.

FastAPI Streamlit TensorFlow Python


πŸš€ 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

GET /
{
  "message": "MNIST Digit Classifier API is running.",
  "docs": "/docs"
}

Predict Digit

POST /predict/
Content-Type: multipart/form-data

Request: Upload any PNG/JPG image of a handwritten digit.

Response:

{
  "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

curl -X POST "https://YOUR_HF_USERNAME-mnist-api.hf.space/predict/" \
  -F "file=@digit_0.png"

πŸ› οΈ Local Setup

# 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
  2. Select Docker as SDK
  3. Push these files:
    • main.py
    • mnist_model.keras
    • requirements.txt
    • Dockerfile
    • README.md
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
  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 SMIT Batch 10 β€” AI & Data Science

Email LinkedIn GitHub


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