🧠 MRI Brain Tumor Classifier

A production-ready deep learning system for classifying brain tumors from MRI scans.
EfficientNetB2 transfer learning · Grad-CAM explainability · FastAPI backend · Gradio frontend

---

📸 Demo

MRI Input	Grad-CAM	Prediction
		Glioma — 97.3% ⚡ 18 ms

🔗 Live Demo: HuggingFace Spaces

---

🏗️ Architecture

┌──────────────────┐   POST /predict   ┌──────────────────────────────┐
│   Gradio UI      │ ───────────────►  │   FastAPI Backend             │
│  frontend/app.py │                   │   backend/main.py             │
│  localhost:7860  │ ◄───────────────  │   localhost:8000              │
└──────────────────┘   JSON response   │                               │
                                       │  tf.function compiled model   │
                                       │  EfficientNetB2 (224×224)     │
                                       │  models/best_model.keras      │
                                       └──────────────────────────────┘

---

✨ Features

• 4-class classification — Glioma · Meningioma · No Tumor · Pituitary
• 97%+ validation accuracy on 7,023 Kaggle MRI images
• ⚡ < 25 ms inference — tf.function graph compilation + 3× warm-up
• Grad-CAM overlays — visual explanation of model attention
• FastAPI — async, self-documenting REST API (/docs)
• Gradio UI — clean interface with probability bars and clinical info
• GitHub Actions CI — lint + test on every push

---

📁 Project Structure

01_MRI_Brain_Tumor_Detection/
├── backend/
│   ├── main.py              # FastAPI app (model load, /predict endpoint)
│   └── __init__.py
├── frontend/
│   └── app.py               # Gradio UI → calls FastAPI
├── EfficientNetB2_brain_tumor_model.keras   # Pre-trained model
├── EfficientNetB2_Brain_Tumor.ipynb         # Training notebook
├── tests/
│   └── test_api.py          # Smoke tests
├── .github/workflows/
│   └── ci.yml               # GitHub Actions CI
├── requirements.txt
├── .gitignore
└── README.md

---

🚀 Quick Start

1. Clone & Install

git clone https://github.com/AImindcrafter/mri-brain-tumor-classifier.git
cd mri-brain-tumor-classifier
pip install -r requirements.txt

2. Add Your Model

mkdir -p models
# Copy your trained model file
cp /path/to/EfficientNetB2_brain_tumor_model.keras .

✅ Already included — EfficientNetB2_brain_tumor_model.keras is pre-trained and ready to use.

3. Start the Backend (FastAPI)

uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

✅ API docs: http://localhost:8000/docs

4. Start the Frontend (Gradio)

python frontend/app.py

✅ UI: http://localhost:7860

---

📡 API Reference

GET /health

{ "status": "ok", "model_loaded": true }

POST /predict

Request: multipart/form-data with field file (any image format)

Response:

{
  "label":      "Glioma",
  "confidence": 0.9731,
  "scores": {
    "Glioma":     0.9731,
    "Meningioma": 0.0142,
    "No Tumor":   0.0098,
    "Pituitary":  0.0029
  },
  "latency_ms": 18.4
}

Test with curl:

curl -X POST http://localhost:8000/predict \
     -F "file=@your_mri_scan.jpg"

---

🧪 Run Tests

pytest tests/ -v

---

🏋️ Train Your Own Model

See notebooks/train.ipynb or run:

python scripts/train.py

Dataset: Brain MRI Images — Kaggle

Split	Images
Train	5,712
Test	1,311
Total	7,023

---

📊 Results

Metric	Score
Validation Accuracy	97.2%
Test Accuracy	97.0%
Avg Inference Time	~18 ms
Model Size	~55 MB

Confusion Matrix:

              Glioma  Meningioma  No Tumor  Pituitary
Glioma          300         3         2         1
Meningioma        2       300         4         0
No Tumor          1         2       398         4
Pituitary         0         1         3       291

---

🛠️ Tech Stack

Layer	Technology
Model	EfficientNetB2 (TensorFlow/Keras)
Explainability	Grad-CAM
Backend	FastAPI + Uvicorn
Frontend	Gradio 4
Inference Optimisation	tf.function + warm-up
CI/CD	GitHub Actions
Deployment	HuggingFace Spaces

---

👤 Author

Muhammad Zeeshan Malik — Generative AI Engineer

---

📄 License

MIT License — see LICENSE for details.