-
Web app
Inspiration
What it does
How we built it
Challenges we ran into
🛡️ SpamGuard-ML: Project Story
Overview
SpamGuard-ML is an AI-powered spam email detection system that leverages machine learning to classify emails and messages as either legitimate ("ham") or spam with high accuracy. The project demonstrates a complete machine learning pipeline—from data cleaning to model training to interactive deployment.
The Problem
Email spam remains a significant challenge in digital communication. Users receive unwanted messages that:
- Waste time and reduce productivity
- Pose security risks (phishing, malware)
- Clutter inboxes
Traditional rule-based filters struggle to adapt to evolving spam tactics. SpamGuard-ML solves this by using intelligent machine learning to learn patterns from real email data.
The Solution
SpamGuard-ML implements a complete machine learning workflow:
1. Data Pipeline (clean_dataset.py)
- Loads raw spam/ham dataset
- Cleans and normalizes data (lowercase labels, removes empty rows)
- Filters to keep only valid "spam" and "ham" categories
- Outputs
dataset.csvfor training
2. Model Training (train.py)
- Extracts features using TF-IDF Vectorization (converts text to numerical values)
- Trains a Multinomial Naive Bayes classifier
- Achieves high accuracy on test data
- Exports trained model and vectorizer for deployment
3. Interactive Web Interface (app.py)
- Built with Streamlit for easy user interaction
- Users paste any email or message to check
- Real-time predictions with confidence percentages
- Visual feedback (🚨 spam or ✅ legitimate)
- Confidence level progress bar
Technical Architecture
Stack
- Language: Python 3
- ML Framework: scikit-learn
- Web Framework: Streamlit
- Data Processing: pandas
- Model Type: Multinomial Naive Bayes
- Feature Extraction: TF-IDF Vectorization
Workflow
Raw Dataset (spam.csv)
↓
[clean_dataset.py]
↓
Clean Dataset (dataset.csv)
↓
[train.py] → Train/Test Split
↓
Vectorization (TF-IDF)
↓
Model Training (Naive Bayes)
↓
Evaluation & Export
(spam_model.pkl, vectorizer.pkl)
↓
[app.py] → Streamlit Web App
↓
User Interaction (Real-time predictions)
How to Use
Prerequisites
pip install -r requirements.txt
Train the Model
python clean_dataset.py # Prepare data
python train.py # Train model
Run the App
streamlit run app.py
The app will be available at http://localhost:8501
Key Features
✅ High Accuracy: Trained on real spam/ham data
✅ Fast Detection: Instant predictions on user input
✅ User-Friendly: Clean, intuitive Streamlit interface
✅ Confidence Scores: Shows probability of spam vs. legitimate
✅ Production-Ready: Serialized model for easy deployment
Model Performance
- Algorithm: Multinomial Naive Bayes
- Vectorization: TF-IDF (3000 features, English stop words removed)
- Train/Test Split: 80/20
- Accuracy: [See output from train.py]
Project Structure
SpamGuard-ML/
├── app.py # Streamlit web interface
├── train.py # Model training pipeline
├── clean_dataset.py # Data cleaning & preprocessing
├── dataset.csv # Clean training dataset
├── spam_model.pkl # Trained model (serialized)
├── vectorizer.pkl # TF-IDF vectorizer (serialized)
├── requirements.txt # Python dependencies
└── PROJECT_STORY.md # This file
Future Enhancements
- 🔄 Real-time model retraining pipeline
- 📊 Advanced visualizations (feature importance, confusion matrix)
- 🌐 Multi-language support
- 🚀 REST API for integration with email providers
- 📈 Performance monitoring dashboard
- 🎯 Multi-model ensemble for improved accuracy
Conclusion
SpamGuard-ML demonstrates the power of machine learning in solving real-world problems. By combining data science best practices with user-friendly web technology, it provides an accessible tool for spam detection that's both accurate and easy to use.
