https://github.com/obirikan/spam_classifer_api
📩 Spam Detection API A simple NLP project using TF-IDF and Naive Bayes to classify messages as spam or not, served via FastAPI.
https://github.com/obirikan/spam_classifer_api
naive-bayes-classifier nlp-machine-learning sckiit-learn
Last synced: 10 days ago
JSON representation
📩 Spam Detection API A simple NLP project using TF-IDF and Naive Bayes to classify messages as spam or not, served via FastAPI.
- Host: GitHub
- URL: https://github.com/obirikan/spam_classifer_api
- Owner: obirikan
- Created: 2025-05-21T15:31:55.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-29T19:40:00.000Z (about 1 year ago)
- Last Synced: 2025-10-18T00:06:02.792Z (9 months ago)
- Topics: naive-bayes-classifier, nlp-machine-learning, sckiit-learn
- Language: Python
- Homepage: https://spam-classifer-api.onrender.com/redoc
- Size: 594 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 📧 Spam Detection API (Python + FastAPI)
A beginner-friendly machine learning API that detects whether a given text message is **SPAM** or **NOT SPAM**, using:
* Python 🐍
* Scikit-learn 🤖
* FastAPI 🚀
* TF-IDF Vectorization
* Naive Bayes Classifier
---
## 🗂️ Project Structure
```
spam_api/
│
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI app entry point
│ ├── routes/
│ │ └── spam.py # API endpoint(s)
│ ├── models/
│ │ └── request.py # Input validation models
│ ├── services/
│ │ └── spam_detector.py # Core ML logic
│ └── utils/
│ └── model_loader.py # Load vectorizer & model
│
├── data/
│ └── spam_data.tsv # Your dataset
├── model/
│ ├── vectorizer.pkl # Saved TF-IDF vectorizer
│ └── spam_model.pkl # Trained model
├── trainModel.py
├── spam_data.py
├── requirements.txt # Packages
└── README.md # Optional docs
```
---
## 📦 Setup Instructions
### ✅ Prerequisites
* Python 3.8 or newer
* pip (Python package installer)
### 🔧 Step-by-step
```bash
# 1. Clone the repository (or download manually)
git clone https://github.com/obirikan/spam_classifer_api.git
cd spam_api
# 2. (Optional) Create a virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Ensure the dataset is available
# Make sure 'spam_data.tsv' is in the project root folder
# 5. Train the model
python trainModel.py
# 6. Run the FastAPI app
uvicorn api.main:app --reload
```
---
## 🔍 API Usage
### 📬 Endpoint: `POST /predict`
**Request Body (JSON):**
````json
{
"message": "Congratulations! You've won a free ticket!"
}
**Response:**
```json
{
"prediction": "spam"
}
````
---
## 🧠 How It Works
* **TF-IDF** is used to convert text messages into numerical vectors.
* A **Multinomial Naive Bayes** classifier is trained on the vectorized data.
* FastAPI handles HTTP requests and returns predictions in real-time.
---
## 📁 Dataset Info
This project uses the [SMS Spam Collection Dataset](https://archive.ics.uci.edu/ml/datasets/sms+spam+collection).
* Format: TSV (Tab-separated)
* Labels: `ham` (not spam), `spam`
Make sure to rename the downloaded file to `spam_data.tsv` and place it in the root directory.
---
## ✍️ Author
* Name: obirikan
* GitHub: [obirikan](https://github.com/obirikan)
---
## ✅ To-Do
* [ ] Add frontend (optional)
* [ ] Add logging and error handling
* [ ] Add retraining dataset with new data
---
## 📜 License
MIT License