🚀 Deploy via GitHub Actions

.gitignore

@@ -0,0 +1 @@
+dataset.csv

Dockerfile

@@ -0,0 +1,27 @@
+# Use a slim official Python image
+FROM python:3.12-slim
+
+# Hugging Face Spaces runs on port 7860
+EXPOSE 7860
+
+# Create a non-root user for security
+RUN useradd -m -u 1000 appuser
+
+WORKDIR /app
+
+# Copy dependency list first (better layer caching)
+COPY requirements.txt .
+
+# Install dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application files
+COPY . .
+
+# Set correct ownership
+RUN chown -R appuser:appuser /app
+
+USER appuser
+
+# Start the FastAPI app via Uvicorn on port 7860
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,122 @@
 ---
-title: Gitspam Detect Api
-emoji: 🌍
-colorFrom: purple
-colorTo: gray
+title: GitHub Spam Detector API
+emoji: 🛡️
+colorFrom: blue
+colorTo: indigo
 sdk: docker
 pinned: false
+license: mit
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🛡️ 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.*

main.py

@@ -0,0 +1,81 @@
+import joblib
+import os
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+
+# ------------------------------------------------------------------
+# App setup
+# ------------------------------------------------------------------
+app = FastAPI(
+    title="GitHub Spam Detector API",
+    description="Predicts whether a GitHub comment is spam (1) or not spam (0). "
+                "Trained on 100k+ real GitHub comments using TF-IDF + LinearSVC.",
+    version="1.0.0",
+)
+
+# ------------------------------------------------------------------
+# Model loading (once at startup, never per-request)
+# ------------------------------------------------------------------
+MODEL_PATH = os.getenv("MODEL_PATH", "spam_detector_model_cv.pkl")
+
+@app.on_event("startup")
+def load_model():
+    global model
+    if not os.path.exists(MODEL_PATH):
+        raise RuntimeError(f"Model file not found at: {MODEL_PATH}")
+    model = joblib.load(MODEL_PATH)
+    print(f"Model loaded successfully from {MODEL_PATH}")
+
+
+# ------------------------------------------------------------------
+# Request / Response schemas
+# ------------------------------------------------------------------
+class PredictRequest(BaseModel):
+    text: str
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "text": "Please fix the bug at line 56, it causes a null pointer exception."
+            }
+        }
+
+
+class PredictResponse(BaseModel):
+    text: str
+    prediction: int          # 0 = Not Spam, 1 = Spam
+    label: str               # Human-readable label
+
+
+# ------------------------------------------------------------------
+# Endpoints
+# ------------------------------------------------------------------
+@app.get("/", tags=["Health"])
+def root():
+    """Health check endpoint."""
+    return {"status": "ok", "message": "Spam Detector API is running."}
+
+
+@app.post("/predict", response_model=PredictResponse, tags=["Prediction"])
+def predict(request: PredictRequest):
+    """
+    Predict whether a piece of text is spam or not.
+
+    - **text**: The comment / text to classify.
+
+    Returns:
+    - **prediction**: `0` (Not Spam) or `1` (Spam)
+    - **label**: Human-readable string `"spam"` or `"not_spam"`
+    """
+    if not request.text or not request.text.strip():
+        raise HTTPException(status_code=422, detail="Input text cannot be empty.")
+
+    raw_pred = model.predict([request.text])[0]
+    prediction = int(raw_pred)
+    label = "spam" if prediction == 1 else "not_spam"
+
+    return PredictResponse(
+        text=request.text,
+        prediction=prediction,
+        label=label,
+    )

requirements.txt

@@ -0,0 +1,6 @@
+fastapi==0.111.0
+uvicorn[standard]==0.29.0
+scikit-learn==1.4.2
+joblib==1.4.2
+pydantic==2.7.1
+numpy==1.26.4

spam_detector_model_cv.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6ad1b0399122c1c3c6b8514a1cc43a60b732a8176aaa9b334f25c1c54009760e
+size 83350887