README.md

---
title: GitHub Spam Detector API
emoji: 🛡️
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
license: mit
app_port: 7860
---

# 🛡️ GitHub Spam Detector API

A production-ready REST API to classify GitHub comments as **Spam** or **Not Spam** in real time.

Built with **FastAPI** and deployed via **Docker** on Hugging Face Spaces.

---

## 📌 Model Details

| Property | Value |
|---|---|
| **Training Data** | 100,000+ real GitHub issue & PR comments |
| **Feature Extraction** | TF-IDF (unigrams + bigrams, stop-words removed) |
| **Classifier** | LinearSVC (tuned via GridSearchCV) |
| **Test Accuracy** | 99% |
| **Test F1-Score** | 0.99 (both classes) |
| **AUC-ROC** | 1.00 |

---

## 🚀 API Endpoints

### `GET /`
Health check — confirms the server is running.

**Response:**
```json
{
  "status": "ok",
  "message": "Spam Detector API is running."
}
```

---

### `POST /predict`
Classify a piece of text as spam or not spam.

**Request Body:**
```json
{
  "text": "Please fix the bug at line 56, it causes a null pointer exception."
}
```

**Response:**
```json
{
  "text": "Please fix the bug at line 56, it causes a null pointer exception.",
  "prediction": 0,
  "label": "not_spam"
}
```

| Field | Type | Description |
|---|---|---|
| `prediction` | `int` | `0` = Not Spam, `1` = Spam |
| `label` | `string` | `"spam"` or `"not_spam"` |

---

## 🧪 Try it Out

Once the Space is running, visit the interactive Swagger docs at:

```
https://<your-username>-github-spam-detector-api.hf.space/docs
```

Or use `curl`:
```bash
curl -X POST "https://<your-username>-github-spam-detector-api.hf.space/predict" \
     -H "Content-Type: application/json" \
     -d '{"text": "subscribe me if u love eminem"}'
```

---

## 🛠️ Run Locally

```bash
# Install dependencies
pip install -r requirements.txt

# Start the server
uvicorn main:app --host 0.0.0.0 --port 7860 --reload
```

Then visit: [http://localhost:7860/docs](http://localhost:7860/docs)

---

## 📦 Tech Stack
- **Python 3.12**
- **FastAPI** — REST API framework
- **scikit-learn** — TF-IDF + LinearSVC model
- **Uvicorn** — ASGI server
- **Docker** — containerized deployment

---

## ⚠️ Known Limitations

- Trained exclusively on GitHub comment data. May underperform on spam from other domains (e.g., YouTube, email).
- Context-blind to "Markdown camouflage" — wrapping spam text inside ` ```diff ` code blocks may fool the model as the TF-IDF vectorizer weighs the code-block tokens heavily toward non-spam.
- For multilingual or highly obfuscated spam, consider upgrading to a transformer-based model (e.g., DistilBERT).

---

*Part of the H2-GitGriffin Hackathon Project.*