Real-Time Purchase Predictor

Production-style machine learning system for predicting e-commerce purchase intent in real time.
The project includes data validation and transformation, model training with MLflow tracking, a FastAPI prediction service, prediction logging, drift detection, and a Streamlit monitoring dashboard.

Features

• Real-time prediction API with FastAPI (/predict, /predict/batch, /health, /stats)
• End-to-end training pipeline using XGBoost
• MLflow experiment tracking for params, metrics, and artifacts
• SQLite prediction logging for monitoring and drift analysis
• Drift detection on recent production predictions
• Streamlit dashboard for live model and system monitoring
• Docker + Docker Compose deployment

Project Structure

real-time-purchase-predictor/
├── data/
│   ├── raw/
│   ├── processed/
│   └── predictions.db
├── artifacts/
│   ├── train_data.csv
│   ├── test_data.csv
│   └── drift_report.json
├── models/
│   └── model.pkl
├── mlruns/
├── src/
│   ├── app.py
│   ├── components/
│   │   ├── data_ingestion.py
│   │   ├── data_transformation.py
│   │   ├── data_validation.py
│   │   ├── model_trainer.py
│   │   ├── model_evaluation.py
│   │   └── drift_detection.py
│   ├── pipeline/
│   │   ├── training_pipeline.py
│   │   └── prediction_pipeline.py
│   └── utils/
│       ├── logger.py
│       └── database.py
├── dashboard.py
├── demo_train.py
├── demo_training.py
├── demo_api.py
├── demo_database.py
├── demo_drift.py
├── demo_mlflow.py
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

Tech Stack

• Python 3.12
• FastAPI + Uvicorn
• Streamlit + Plotly
• XGBoost + scikit-learn
• MLflow
• SQLite
• Docker / Docker Compose

Local Setup

1) Clone and install

git clone https://github.com/M-Wajeeh/real-time-purchase-predictor.git
cd real-time-purchase-predictor

python -m venv .venv
# Windows PowerShell
.\.venv\Scripts\Activate.ps1

pip install -r requirements.txt

2) Train model

Either command works:

python demo_train.py
# or
python demo_training.py

This creates:

• models/model.pkl
• artifacts/train_data.csv
• artifacts/test_data.csv
• MLflow run in mlruns/

3) Start API

python -m uvicorn src.app:app --host 0.0.0.0 --port 8000 --reload

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

4) Start dashboard

python -m streamlit run dashboard.py

Dashboard: http://localhost:8501

API Endpoints

GET /health

Returns API and model health.

POST /predict

Single prediction for one transformed feature row.

Example request:

{
	"features": {
		"0": 0.12,
		"1": 1.0,
		"2": 0.0
	},
	"session_id": "optional-session-id"
}

POST /predict/batch

Batch predictions.

GET /stats?hours=24

Returns prediction statistics from logged production data.

Dashboard

The Streamlit dashboard includes:

• API/model/database health status
• Key prediction metrics (volume, purchase rate, confidence)
• Model performance cards (from artifacts/metrics.json or latest MLflow run)
• Trend charts over time
• Drift report display
• Recent predictions table with CSV download

MLflow

Training automatically logs to MLflow experiment purchase_prediction.

Run UI:

mlflow ui

Open: http://localhost:5000

Drift Detection

Generate and save drift report:

python demo_drift.py

Output file:

• artifacts/drift_report.json

Docker Deployment

Build and run all services:

docker compose up --build -d

Services:

• API: http://localhost:8000
• Dashboard: http://localhost:8501
• MLflow UI: http://localhost:5000

Stop:

docker compose down

Troubleshooting

Dashboard shows no model metrics

Run training first:

python demo_train.py

Dashboard will read from latest MLflow run even if artifacts/metrics.json is missing.

API health is offline in dashboard

Start API before opening dashboard:

python -m uvicorn src.app:app --host 0.0.0.0 --port 8000

Missing script error (demo_training.py not found)

Use python demo_train.py or updated compatibility script demo_training.py.

Current Model Snapshot

• Algorithm: XGBoost Classifier
• Features: 66 transformed features
• Last observed metrics:
  • Accuracy: ~90.23%
  • Precision: ~72.10%
  • Recall: ~60.21%
  • F1: ~65.62%

License

This project is licensed under the MIT License. See LICENSE for details.