Skip to content

README.md

Latest commit

 

History

History
263 lines (201 loc) · 8.47 KB

README.md

File metadata and controls

263 lines (201 loc) · 8.47 KB

🫁 PneumoScan AI

Deep-learning powered pneumonia detection from chest X-rays

Python TensorFlow FastAPI Docker CI License

Overview

PneumoScan AI is a full-stack medical image analysis application that classifies chest X-ray images as Normal, Pneumonia, or Uncertain using a fine-tuned MobileNetV2 deep learning model. It includes Grad-CAM explainability to visualise which lung regions influenced the model's decision — critical for trust in medical AI.

Key Features

Feature Description
Transfer Learning MobileNetV2 pretrained on ImageNet, fine-tuned on chest X-rays
Two-Phase Training Frozen base → unfreeze last 20 layers for domain adaptation
Grad-CAM Heatmaps Visual explainability showing model attention regions
REST API FastAPI backend with Pydantic validation, health checks, OpenAPI docs
Modern Frontend Glassmorphism UI with drag-and-drop, real-time results
Containerised Multi-stage Dockerfile with health checks
CI/CD GitHub Actions pipeline with testing + Docker build
Tested Unit + integration tests with pytest

Architecture

┌──────────────────────────────────────────────────────────┐
│                      Frontend (HTML/JS)                  │
│  Upload X-ray → Predict / Explain (Grad-CAM)            │
└────────────────────────┬─────────────────────────────────┘
                         │ HTTP POST
┌────────────────────────▼─────────────────────────────────┐
│                   FastAPI Backend                         │
│  /predict  → preprocess → MobileNetV2 → result          │
│  /gradcam  → preprocess → MobileNetV2 → heatmap         │
│  /health   → model status + uptime                      │
└────────────────────────┬─────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────┐
│              MobileNetV2 (Fine-tuned)                    │
│  Input: 224×224×3  →  Sigmoid  →  P(Pneumonia)          │
└──────────────────────────────────────────────────────────┘

Project Structure

pneumonia-ai/
├── app/
│   ├── main.py            # FastAPI app — routes, validation, CORS
│   ├── model_loader.py    # Singleton model loading with caching
│   ├── predict.py         # Image preprocessing & prediction logic
│   └── gradcam.py         # Grad-CAM heatmap generation
├── frontend/
│   ├── index.html         # Single-page application
│   ├── script.js          # (legacy) JS — now inlined in index.html
│   └── style.css          # (legacy) CSS — now inlined in index.html
├── training/
│   └── train.py           # Full training pipeline with metrics & plots
├── model/
│   └── pneumonia_model.keras  # Trained model (not in git — see Setup)
├── data/                  # Dataset (not in git — see Setup)
├── tests/
│   └── test_app.py        # Unit + integration tests
├── .github/workflows/
│   └── ci.yml             # GitHub Actions CI pipeline
├── Dockerfile             # Multi-stage container build
├── requirements.txt       # Python dependencies
├── pyproject.toml         # Pytest configuration
├── .gitignore
└── README.md

Quick Start

Prerequisites

  • Python 3.10+
  • pip

1. Clone & install

git clone https://github.com/Sujith-RMD/pneumonia-ai.git
cd pneumonia-ai
python -m venv venv
source venv/bin/activate     # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Download the dataset

Download the Chest X-Ray Images (Pneumonia) dataset from Kaggle and extract it:

data/
├── train/
│   ├── NORMAL/
│   └── PNEUMONIA/
├── val/
│   ├── NORMAL/
│   └── PNEUMONIA/
└── test/
    ├── NORMAL/
    └── PNEUMONIA/

3. Train the model (optional — or use a pre-trained checkpoint)

python training/train.py

This will:

  • Train MobileNetV2 in two phases (frozen → fine-tuned)
  • Evaluate on the test set and print classification report + ROC-AUC
  • Save the model to model/pneumonia_model.keras
  • Generate plots in training/plots/ (accuracy, loss, confusion matrix, ROC curve)

4. Run the app

uvicorn app.main:app --reload

Open http://localhost:8000 in your browser.

5. Run tests

pip install httpx anyio pytest-anyio
pytest tests/ -v

Docker

docker build -t pneumoscan-ai .
docker run -p 8000:8000 pneumoscan-ai

API Documentation

FastAPI auto-generates interactive docs:

URL Description
/docs Swagger UI
/redoc ReDoc

Endpoints

Method Path Description
GET / Serve frontend
GET /health Health check (model status, uptime)
POST /predict Upload X-ray → get prediction
POST /gradcam Upload X-ray → get prediction + Grad-CAM heatmap

Example response — /predict

{
  "prediction": "PNEUMONIA",
  "confidence": 94.32,
  "raw_probability": 0.9432
}

Example response — /gradcam

{
  "prediction": "PNEUMONIA",
  "confidence": 94.32,
  "raw_probability": 0.9432,
  "gradcam_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
}

Model Performance

Update these numbers after training on your machine.

Metric Value
Test Accuracy ~93%
ROC-AUC ~0.97
Architecture MobileNetV2 (fine-tuned last 20 layers)
Input Size 224 × 224 × 3
Training Data 5,216 images
Augmentation Rotation, zoom, shift, flip, brightness

Training Plots

After training, plots are saved to training/plots/:

  • Accuracy & Loss curves (with fine-tuning boundary marked)
  • Confusion Matrix
  • ROC Curve

Tech Stack

Layer Technology
Deep Learning TensorFlow / Keras · MobileNetV2
Explainability Grad-CAM (Class Activation Maps)
Backend FastAPI · Pydantic · Uvicorn
Frontend Vanilla HTML/CSS/JS · Glassmorphism
Computer Vision OpenCV · Pillow
Metrics scikit-learn (classification report, ROC-AUC)
Testing pytest · httpx
Containerisation Docker (multi-stage)
CI/CD GitHub Actions

What I Learned

  • Transfer learning and fine-tuning strategies for medical imaging
  • Importance of model explainability (Grad-CAM) in healthcare AI
  • Building production-ready ML APIs with FastAPI and Pydantic validation
  • Two-phase training: frozen backbone → gradual unfreezing
  • Handling class imbalance and choosing appropriate evaluation metrics
  • Docker containerisation for ML applications
  • Writing testable ML code with proper separation of concerns

Disclaimer

This is an educational prototype and is not intended for clinical diagnosis. Always consult a qualified medical professional for health-related decisions.

License

MIT License — see LICENSE for details.