README.md

metadata

title: Spam Email Classifier with XAI (v2)
emoji: 📧
colorFrom: blue
colorTo: red
sdk: gradio
sdk_version: 5.23.0
python_version: '3.11'
app_file: app.py
pinned: false
license: mit
tags:
  - spam-detection
  - xai
  - lime
  - shap
  - eli5
  - scikit-learn
  - nlp
  - explainable-ai
models:
  - VoltageVagabond/spam-xai-model-v2
  - VoltageVagabond/spam-classifier-mlx
  - VoltageVagabond/spam-classifier-liquid
datasets:
  - VoltageVagabond/spam-email-dataset

Spam Email Classifier with XAI Explanations

ENGT 375 — Applied Machine Learning | Spring 2026 | Old Dominion University

Disclaimer: This model was created as a student project for Applied Machine Learning at ODU. It is intended for educational and research purposes only and should not be used as a sole spam/phishing filter in production. Classification accuracy may vary, and the model may produce incorrect or misleading results. Always use established email security tools for real-world spam filtering.

A Gradio web app that classifies emails as spam or ham and provides explainable AI (XAI) insights using three different methods (LIME, SHAP, and ELI5).

What's new in v2: beginner-friendly notebook refactor (explicit for-loops over comprehensions, no decorators, no premature abstractions), lecture-style charts in the student teaching notebook, a separate app_student.py / utils_student.py / retrain_student.py track for course readers, and a fresh full-dataset retrain (99,999 samples — 69,999 train / 30,000 test) producing a re-tuned classification threshold of 0.3714. v2 is deployed as its own HuggingFace Space at VoltageVagabond/spam-xai-classifier-v2.

Features

• Paste any email and get an instant spam/ham prediction
• LIME explanations — which words pushed the decision
• SHAP feature importance — game-theoretic attribution
• ELI5 — model internal feature weights and permutation importance
• Side-by-side comparison of all three XAI methods
• Plain English summary of why the model made its decision
• User feedback — thumbs up/down to log corrections for batch retraining
• Adjustable classification threshold

How to Run Locally

# Install dependencies
pip install -r requirements.txt

# Train the model (first run only — produces models/voting_model.joblib)
python3 train_ensemble.py

# Launch the Gradio web app
python3 app.py

# Or open the student teaching notebook
jupyter notebook notebooks/spam_classifier_xai_student.ipynb

You can also double-click any of these .command files in Finder:

• launch-gradio.command — opens the Gradio web UI in your browser
• launch-notebook.command — opens the student notebook in Jupyter
• launch-app.command — opens the legacy Streamlit app (kept for reference; the active UI is launch-gradio.command)
• retrain-fast.command — quick retrain (~2-5 min, single RF, no grid search)
• retrain-full.command — full retrain (~15-30 min, voting ensemble + grid search)

Retraining

python3 retrain.py --mode fast        # quick retrain, single RF
python3 retrain.py --mode full        # full retrain, voting ensemble + grid search
python3 retrain.py --mode full --no-feedback   # full retrain, ignore user feedback log

The retrain script reads accumulated user corrections from data/feedback/feedback_log.csv and merges them into the training data with 5x weighting.

Model

Voting ensemble (Random Forest + Logistic Regression + Linear SVM with calibration) trained on the full Kaggle 100K spam dataset + GitHub email-dataset (99,999 samples total: 69,999 train / 30,000 test), using 3,000 TF-IDF features + 24 hand-crafted metadata features.

Model	Accuracy	F1 Score
Random Forest	97.75%	0.976
Logistic Regression	96.57%	0.964
SVM (LinearSVC + calibration)	96.89%	0.967
VotingClassifier (deployed)	97.40%	0.973

Optimal classification threshold: 0.3714 (targeting 99% ham precision; value read from models/optimal_threshold.joblib written by train_ensemble.py).

Notebooks

Notebook	Purpose
notebooks/spam_classifier_xai_student.ipynb	Main teaching notebook (turn-in artifact for the course). Full XAI walkthrough with LIME, SHAP, ELI5, and a feature reduction experiment based on Kuzlu et al. 2020
notebooks/spam_classifier_gradio.ipynb	Shorter pipeline focused on the ensemble model and Gradio deployment

Documentation

• docs/references/how-to.html — full reference index with clickable links to all local PDFs (LIME, SHAP, TreeSHAP, Kuzlu et al., 5 spam-detection papers) and HTML guides (sklearn user guide, Gradio quickstart, HF Spaces docs, Molnar Interpretable ML book)
• docs/07-code-sources-reference.md — markdown version of the references with citation entries
• CHANGELOG.md — full project history from v0.1 (Streamlit) through v1.1 (merged Gradio)

Tech Stack

• scikit-learn — Random Forest, Logistic Regression, LinearSVC, VotingClassifier, CalibratedClassifierCV, TfidfVectorizer, MinMaxScaler, GridSearchCV, metrics
• LIME + SHAP + ELI5 — explainability
• Gradio — web interface (live deployment on HuggingFace Spaces)
• NLTK — text preprocessing (Porter stemmer, English stopwords)
• scipy.sparse — efficient handling of TF-IDF + metadata feature combination

Sibling Projects

This is the sklearn / classical ML variant. Two LLM-based variants are in sibling folders:

• ../spam-classifier-mlx/ — Apple MLX LoRA fine-tune of Qwen3.5-0.8B
• ../spam-classifier-liquid/ — HuggingFace TRL+PEFT LoRA fine-tune of Liquid AI LFM2.5-1.2B

Citation

If you reference this work academically:

Balfour, D. (2026). Spam Email Classifier with Explainable AI.
ENGT 375 Applied Machine Learning project, Old Dominion University, Spring 2026.
https://huggingface.co/spaces/VoltageVagabond/spam-xai-classifier-v2