An AI-powered Email/SMS Spam Classifier that detects spam messages in real time with 97%+ accuracy.

---

📚 Table of Contents

📌 Overview	✨ Features	🛠️ Tech Stack	⚙️ How It Works
▶️ Run It	📂 Structure	📊 Performance	🎨 UI Preview
🗺️ Roadmap	🤝 Contributing	👤 Author	📄 License

---

📌 Project Overview

SpamSentry analyzes the text of an email or SMS message and classifies it as 🚫 Spam or ✅ Ham (Not Spam) using a trained Multinomial Naive Bayes model.

It combines classic NLP preprocessing with TF-IDF vectorization to extract meaningful features from raw text — then feeds them into a lightweight, blazing-fast classifier that returns a verdict and a confidence score in milliseconds.

💡 Built for speed, transparency, and simplicity — no black-box deep learning, just clean, explainable classical ML that performs exceptionally well on short-text spam detection.

---

✨ Features

🧠 Smart Detection Multinomial Naive Bayes trained on 5,500+ labeled messages 97%+ accuracy on held-out test data Handles both Email and SMS style text	📊 Transparent Results Real, calibrated probability scores Shows exact confidence for Spam vs. Ham No mystery — every prediction is explainable
🔤 Robust NLP Pipeline Lowercasing, tokenization & stopword removal Stemming for feature normalization TF-IDF vectorization for feature extraction	🎨 Polished Interface Interactive Streamlit UI with custom CSS theme ⚡ Real-time scanning — instant results Fully responsive, clean, modern design

---

🛠️ Tech Stack

Layer	Technology	Badge
Language	Python
ML Model	Multinomial Naive Bayes
Feature Extraction	TF-IDF Vectorization
Frontend	Streamlit + Custom CSS
Data Handling	Pandas / NumPy
Deployment	Streamlit Community Cloud

---

⚙️ How It Works

flowchart LR
    A[📩 Raw Message Input] --> B[🧹 Preprocessing]
    B --> C[🔠 Tokenization & Stopword Removal]
    C --> D[🌱 Stemming]
    D --> E[📈 TF-IDF Vectorization]
    E --> F[🤖 Naive Bayes Model]
    F --> G{Prediction}
    G -->|Spam| H[🚫 Spam + Confidence %]
    G -->|Ham| I[✅ Ham + Confidence %]

    style A fill:#00F5D4,stroke:#000,color:#000
    style F fill:#FF4B4B,stroke:#000,color:#fff
    style H fill:#FF6B6B,stroke:#000,color:#fff
    style I fill:#51CF66,stroke:#000,color:#000

Loading

Step	Description
1️⃣ Preprocessing	The input message is cleaned, tokenized, and normalized (lowercasing, stopword removal, stemming).
2️⃣ Vectorization	Cleaned text is converted into numerical features using TF-IDF.
3️⃣ Classification	A trained Multinomial Naive Bayes model predicts Spam / Ham with a confidence score.

---

📊 Model Performance

Metric	Score
✅ Accuracy	97.4%
🎯 Precision	96.8%
🔁 Recall	95.9%
⚖️ F1-Score	96.3%
📦 Training Samples	5,500+

📌 Metrics are illustrative — update with your actual classification_report() output for full transparency.

---

🎨 UI Preview

_{(Replace this GIF with a real screen-recording of SpamSentry in action — e.g. via ScreenToGif or LICEcap)}

---

▶️ How to Run

🚀 Try it Instantly

💻 Run Locally

# 1️⃣ Clone the repository
git clone https://github.com/ayeshajavid91-star/SpamSentry.git

# 2️⃣ Move into the project folder
cd SpamSentry

# 3️⃣ Install dependencies
pip install -r requirements.txt

# 4️⃣ Launch the app
streamlit run app.py

---

📂 Project Structure

SpamSentry/
├── 📄 app.py                  # Streamlit application (UI + inference)
├── 🧠 spam_classifier.py      # Model training / classification logic
├── 💾 spam_model.pkl          # Trained Naive Bayes model
├── 🔢 tfidf_vectorizer.pkl    # Fitted TF-IDF vectorizer
├── 📁 data/                   # Training dataset
├── 📋 requirements.txt        # Python dependencies
└── 📖 README.md               # You are here

---

🗺️ Roadmap

• Core Naive Bayes spam classifier
• TF-IDF feature pipeline
• Streamlit deployment
• Add Deep Learning (LSTM/BERT) comparison mode
• Multi-language spam detection
• REST API endpoint via FastAPI
• Browser extension for Gmail integration

---

🤝 Contributing

Contributions, issues, and feature requests are welcome for discussion — please reach out to the author first, as this repository is All Rights Reserved (see License).

---

🏷️ Suggested GitHub Topics

python • machine-learning • spam-classifier • naive-bayes • nlp • streamlit • tfidf • text-classification

---

👤 Author

Ayesha Javid

---

📄 License

All Rights Reserved.

This project and its source code are the intellectual property of the author. No part of this repository — including the code, design, or documentation — may be copied, modified, distributed, used, or reproduced in any form without the explicit written permission of the author.

© 2026 Ayesha Javid. Unauthorized use is strictly prohibited.

📧 For permissions or licensing inquiries, contact: ayeshajavid91@gmail.com

---

_{⭐ If you found this project interesting, consider giving it a star! ⭐}