🛡️ CommentGuard

Open-source, self-hostable toxic comment moderation API + Chrome extension.
Multi-label toxicity detection with anti-evasion. Drop-in Perspective API replacement.
No paid SaaS, no data leaving your servers.

---

Google is sunsetting the Perspective API, leaving developers without a reliable, privacy-focused way to moderate text. CommentGuard is a fast, 1:1 drop-in replacement built from the ground up. It uses a custom anti-evasion engine and a Deep Learning Transformer model to locally detect 6 categories of toxicity. 100% open-source, and your data never leaves your servers.

---

📑 Table of Contents

• Features
• Performance & Benchmarks
• Quick Start
• Developer SDK & Integrations
• Live Dashboard
• Chrome Extension
• Perspective API Migration
• API Reference

---

✨ Features

• 🏷️ Multi-label classification — 6 toxicity categories: toxic, severe_toxic, obscene, threat, insult, identity_hate
• ⚡ FastAPI backend — POST /moderate classifies text in < 50ms (classical) or ~150ms (transformer)
• 🛡️ Anti-evasion — defeats leetspeak (h4t3), Unicode tricks, zero-width chars, separator evasion (k.i.l.l)
• 🔄 Perspective API compatible — drop-in replacement endpoint (POST /v1/comments:analyze)
• 📦 Batch API — moderate up to 100 texts in a single request
• 🧠 Swappable models — TF-IDF + Logistic Regression or unitary/toxic-bert via MODEL_TYPE env var
• 📈 Live Dashboard — beautiful React/Vite analytics dashboard to visualize the moderation stream
• 🧩 Chrome extension — live-filters 9 sites: YouTube, Reddit, HN, Twitter/X, Discord, Twitch, Facebook, Instagram
• 📊 Live analytics — /stats endpoint with per-category toxicity breakdown
• 🔁 Feedback loop — users can report false positives; data is logged for retraining
• 🔌 Drop-in integration — Node.js, Django, Laravel, Next.js examples included
• 🐳 Docker-ready — docker compose up and you're live
• 🔒 Privacy-first — runs 100% on your own infrastructure

---

---

📊 Performance & Benchmarks

1. Unbiased Benchmark (Kaggle Jigsaw Dataset)

To ensure zero bias, we tested a random sample of 500 comments from the Kaggle Toxic Comment Classification dataset (comments the model has never seen).

Metric	CommentGuard v3.0	Google Perspective (Published)
Accuracy	94.6%	~92.1%
Recall (Catch Rate)	93.3%	~87.2%
F1 Score	75.7%	~88.3%
Avg Latency	50ms	~200-400ms (Cloud Roundtrip)
Privacy	✅ 100% Local	❌ Sends data to Google

2. Edge-Case Stress Test (Anti-Evasion)

In addition to the random benchmark, we performed a hand-picked "Stress Test" on 40 tricky comments (leetspeak, Unicode obfuscation, and subtle slang) to verify our Anti-Evasion engine.

• SAMPLES.md: View the results of our hand-picked 40-item Stress Test.
• KAGGLE_SAMPLES.md: View the first 50 comments from the Unbiased 500-comment Benchmark.
• benchmark.py: The script used to calculate these metrics.

Choosing the Right Threshold

CommentGuard is tuned to be highly protective by default. You can adjust the sensitivity in your .env file to match your community's needs:

Use Case	Threshold	Philosophy	Result
The Shield	0.50 (Default)	Catch everything. Safety first.	Max Recall (93%). Highest security.
The Balanced	0.65	Best overall balance.	Optimal F1 Score (80%). Fewer false flags.
The Minimalist	0.85	Stay out of the way.	Highest Precision. Only blocks extreme toxicity.

---

🏗️ Architecture

graph TD
    A[Browser Extension] -->|POST /moderate| B(FastAPI Backend)
    C[Node.js SDK Apps] -->|POST /moderate| B
    D[Legacy Perspective Apps] -->|POST /v1/comments:analyze| B
    
    B --> E{Anti-Evasion Preprocessor}
    E --> F[Transformer Neural Net]
    
    F -->|6-Category Scores| B
    B -->|Logs & Stats| G[(In-Memory Analytics)]
    
    H[React Dashboard] -->|GET /stats| G

Loading

---

🚀 Quick Start

Prerequisites

Before running the project, make sure you have the following installed on your machine:

• Python 3.10+ (For the AI Backend)
• Node.js & npm (For the React Dashboard and SDK)

Option A — 1-Click Local Start (Easiest)

We wrote a startup script that automatically boots up both the AI Backend and the React Dashboard for you.

# Clone the repository
git clone https://github.com/init-krish/commentguard
cd commentguard

# On Mac/Linux:
./start.sh

# On Windows:
start.bat

Both the API (localhost:8000) and the Dashboard (localhost:3000) will instantly go live. -d '{"text": "I hate you so much"}'

### Option B — Docker

```bash
cd commentguard/backend
cp .env.example .env
docker compose up -d

```bash
curl http://localhost:8000/health

---

📈 Live Dashboard

CommentGuard comes with a beautiful, real-time React dashboard to monitor toxicity rates and view live moderation logs.

cd dashboard
npm install
npm run dev

Navigate to http://localhost:3000 to see your AI in action.

---

🔌 Developer SDK & Integrations

Integrating CommentGuard into your application is incredibly simple. We offer an official Node.js SDK:

npm install commentguard-sdk

For full copy-paste examples in Node.js, Vanilla JS, Python, and PHP, see our Integration Guide.

---

🔄 Perspective API Migration

Google's Perspective API is shutting down on Dec 31, 2026. CommentGuard acts as a 1:1 drop-in replacement. See our Perspective Migration Guide for instructions on how to switch by changing just one line of code.

---

🧠 Model Training (Classical)

CommentGuard runs with the Deep Learning Transformer by default. If you want to use the ultra-fast classical model (TF-IDF + Logistic Regression), you need to train it first.

Step-by-Step Training Guide

1. Download Dataset: Get the Jigsaw Toxic Comment Dataset from Kaggle.
2. Train: Run python model/train.py on your local machine or in a Kaggle Notebook.
3. Move Files: The script will output three files. You must move them into the backend directory:
   • Move vectorizer.joblib ➡️ backend/app/ml/vectorizer.joblib
   • Move models.joblib ➡️ backend/app/ml/models.joblib
   • Move model_meta.json ➡️ backend/app/ml/model_meta.json
4. Configure: Open your backend/.env file and set MODEL_TYPE=classical.
5. Restart: Restart the backend or Docker container.

Evaluation Metrics (Classical)

Metric	Score
ROC-AUC	~0.97
Precision (toxic)	~0.82
Recall (toxic)	~0.76
F1 (toxic)	~0.79

For full model documentation, see model/MODEL_CARD.md

---

🔌 API Reference

Method	Endpoint	Description
POST	/moderate	Multi-label moderation — returns scores for 6 toxicity categories
POST	/moderate/batch	Batch moderation — up to 100 texts in one request
POST	/v1/comments:analyze	Perspective API compatible — drop-in replacement
POST	/predict	Alias for /moderate (Chrome extension backwards compat)
GET	/health	Health check — model type, version, features, categories
GET	/stats	Live analytics — per-category breakdown, recent log
POST	/feedback	Submit false positive/negative reports for retraining
GET	/docs	Interactive Swagger UI (auto-generated by FastAPI)

Example Request & Response

curl -X POST http://localhost:8000/moderate \
  -H "Content-Type: application/json" \
  -d '{"text": "You are terrible", "threshold": 0.5}'

{
  "label": "toxic",
  "toxic_prob": 0.87,
  "decision": "block",
  "categories": ["toxic", "insult"],
  "scores": {
    "toxic": 0.87,
    "severe_toxic": 0.12,
    "obscene": 0.34,
    "threat": 0.08,
    "insult": 0.82,
    "identity_hate": 0.05
  },
  "flagged": true
}

Decision logic:

• block — toxic_prob >= threshold
• review — toxic_prob >= threshold × 0.6 (borderline)
• allow — below review threshold

---

🧩 Chrome Extension

Installation Open chrome://extensions/ (or brave://extensions/) Enable Developer Mode Click Load unpacked → select extension/ folder Navigate to any supported site Toxic comments are blurred with category badges Supported Sites (9) Site Status YouTube ✅ Reddit ✅ Hacker News ✅ Twitter / X ✅ Discord (web) ✅ Twitch ✅ Facebook ✅ Instagram ✅ Hacker News Comment text blocks Add more sites by extending SITE_SELECTORS in content.js

Extension Features 🔴 Toxic comments → blurred with red badge + probability % 🟡 Borderline comments → softly blurred with amber badge 👆 Click to reveal — any blurred comment can be unblurred 📊 Live session stats — scanned, blurred, blocked counts in popup ⚙️ Configurable — threshold slider, custom API endpoint 🔁 Auto-feedback — revealing a comment sends a false-positive report

---

⚙️ Configuration

Set via .env file or environment variables:

Variable	Default	Options	Description
MODEL_TYPE	classical	classical, transformer	Model backend to use
THRESHOLD	0.5	0.0 – 1.0	Default block threshold
ENV	development	development, production	Environment label

---

🔗 Integrate Into Your Website

See docs/INTEGRATIONS.md for copy-paste examples in:

• Node.js / Express
• Python / Django
• PHP / Laravel
• Next.js (API routes)

Pattern: Call POST /moderate before saving any user comment to your database. Use the decision field to allow, review, or block.

---

🧪 Testing

cd backend
pip install -r requirements.txt   # includes pytest
pytest tests/ -v

The test suite covers:

• Health check endpoint
• Toxic & clean comment classification
• Empty/missing text validation (422)
• Custom threshold overrides
• Feedback recording
• Edge cases (Unicode, long text, special characters)

---

📋 Roadmap

• Multi-label classification (insult / threat / hate / obscene)
• Hindi + Hinglish support
• Dashboard web UI for analytics
• Persistent feedback logging (SQLite)
• Firefox extension
• npm package: commentguard-client
• Rate limiting middleware
• Batch moderation endpoint (POST /moderate/batch)

---

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

---

📄 License

Licensed under the Apache License 2.0 — see LICENSE for details.

Free to use, modify, and deploy commercially with attribution.