VoltageVagabond/spam-xai-model

Senior Project Notice

This repository was created for a senior project in ENGT 375 Applied Machine Learning at Old Dominion University. It is provided for educational and research demonstration purposes only. It is not intended for production use, security filtering, or making real-world spam/phishing decisions. Always use established security tools for operational email protection.

Spam Email Classifier with XAI Explanations

ENGT 375 — Applied Machine Learning | Spring 2026 | Old Dominion University 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).

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 — legacy Streamlit launcher (kept for reference; app.py is now a Gradio app — use launch-gradio.command instead)
• 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 Kaggle 100K spam dataset + GitHub email-dataset, using 3,000 TF-IDF features + 24 hand-crafted metadata features.

Model	Accuracy	F1 Score
Random Forest	97.78%	0.976
Logistic Regression	96.6%	0.964
SVM (LinearSVC + calibration)	96.9%	0.967
VotingClassifier (deployed)	97.4%	0.973

Optimal classification threshold: 0.3714 (targeting 99% ham precision; value read from optimal_threshold.joblib as written by the full-corpus retrain).

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