README.md

metadata

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:

{
  "status": "ok",
  "message": "Spam Detector API is running."
}

---

POST /predict

Classify a piece of text as spam or not spam.

Request Body:

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

Response:

{
  "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:

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

# 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

---

📦 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.