Open-source content moderation for group chats. Protects communities — especially those with minors — from violence, NSFW content, sexual violence, cyberbullying, and deepfakes.

Works with Telegram and WhatsApp. More platforms planned.

• What It Does
• Quick Start
• Deepfake Detection Setup
• How It Works (Under the Hood)
• Configuration Reference
• API Reference
• GDPR & Privacy
• Running Tests
• Roadmap
• Contributing
• License

A bot sits in your group chat. When someone sends a message, image, or video, the bot checks it using ML models and returns one of three verdicts:

What are ML models? ML (machine learning) models are pre-trained programs that can understand content — like recognising violent images or toxic language. Deepfake Guardian downloads these models automatically the first time they're needed. They run locally on your server, so no message content is sent to external services (unless you choose a cloud-based deepfake provider).

Categories detected: violence, sexual violence, NSFW, cyberbullying, deepfakes

Who is this for?

• Schools and class chats
• Youth organisations and sports clubs
• Companies and teams
• Any community group that needs moderation

Use MODERATION_PROFILE=minors_strict for groups with children — it lowers all thresholds automatically.

• Docker (recommended) — or Python 3.11+ and Node.js 18+
• A Telegram bot token from @BotFather
• ~4 GB disk and ~4 GB RAM (models are downloaded on demand, see below)

# 1. Clone and copy config files
git clone https://github.com/richardkfm/deepfake-guardian.git
cd deepfake-guardian
cp engine/.env.example engine/.env
cp telegram-bot/.env.example telegram-bot/.env

# 2. Set your Telegram bot token
#    Open telegram-bot/.env and paste your token:
#    TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

# 3. Start everything
docker compose up --build

That's it. Add the bot to a Telegram group, give it admin rights, and it starts moderating.

Without admin rights the bot will @-mention admins instead of deleting messages.

The engine starts immediately — no upfront download required. ML models are downloaded on demand when the first message of each type arrives:

After the first download, models are cached. Docker volumes persist the cache across container restarts, so subsequent starts are instant.

Tip: To pre-download all models before going live, send one test request per type after starting the engine:

# Pre-download text models
curl -X POST http://localhost:8000/moderate_text \
  -H "Content-Type: application/json" -d '{"text": "test"}'

# Pre-download image models
curl -X POST http://localhost:8000/moderate_image \
  -H "Content-Type: application/json" -d '{"image_url": "https://placehold.co/10x10.png"}'

Set ENABLED_LANGUAGES=en (or =de) in engine/.env to skip loading the other language model entirely — saves ~500 MB–1.6 GB of RAM and disk.

# Terminal 1 — Engine
cd engine && pip install -r requirements.txt && python main.py

# Terminal 2 — Telegram bot
cd telegram-bot && pip install -r requirements.txt && python main.py

# Terminal 3 — WhatsApp bot (optional)
cd whatsapp-bot && npm install && npm run build && npm start

Bare-metal also needs ffmpeg installed (apt install ffmpeg or brew install ffmpeg).

Deepfake detection is off by default (stub mode — no models downloaded, no API calls). To enable it, pick a provider and set the config in engine/.env.

DEEPFAKE_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here

Get a key at platform.openai.com/api-keys. Uses GPT-4o vision. No local model download needed. Face images are sent to OpenAI — consider GDPR implications for groups with minors.

DEEPFAKE_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llava

Install Ollama, then ollama pull llava. All data stays on your machine. No additional downloads by the engine itself.

DEEPFAKE_PROVIDER=local

Runs an EfficientNet-B0 model on CPU. Downloads a ~50 MB ONNX model on first use. Needs ~500 MB extra RAM and the onnxruntime, mediapipe, opencv-python-headless packages (already included in requirements.txt). Nothing leaves the server.

# SightEngine
DEEPFAKE_PROVIDER=sightengine
SIGHTENGINE_API_USER=your-user
SIGHTENGINE_API_SECRET=your-secret

# Or any HTTP endpoint
DEEPFAKE_PROVIDER=api
DEEPFAKE_API_URL=https://your-api.com/detect
DEEPFAKE_API_KEY=your-key

┌─────────────┐                    ┌────────────────────┐
│ Telegram Bot │──── HTTP/JSON ───▶│                    │
└─────────────┘                    │  Moderation Engine │
┌──────────────┐                   │     (FastAPI)      │
│ WhatsApp Bot │──── HTTP/JSON ───▶│                    │
└──────────────┘                    └────────────────────┘

The engine is the brain. Bots are thin clients — they forward content, get a verdict, and act on it.

1. Bot receives a message (text / image / video) in a group chat
2. Forwards content to the engine API
3. Engine auto-detects language, runs ML classifiers + pattern matchers
4. Engine returns verdict + confidence scores
5. Bot deletes, flags, or allows the message

Auto-detects language per message. Each language has its own ML model, patterns, and educational messages.

Add a new language by creating one file in engine/i18n/packs/. Enable with ENABLED_LANGUAGES=en,de,fr.

All config lives in .env files. Copy from .env.example and edit.

Set all thresholds at once with MODERATION_PROFILE:

How thresholds work: each threshold is the minimum confidence score that triggers an automatic deletion. A lower value means stricter — the engine deletes at lower model confidence, catching the category earlier and more aggressively. A higher value means the model must be very confident before acting, reducing false positives.

Individual THRESHOLD_* vars override specific values within the profile.

POST /moderate_text    {"text": "...", "language": "en"}
POST /moderate_image   {"image_base64": "..." | "image_url": "..."}
POST /moderate_video   {"video_base64": "..." | "video_url": "..."}
GET  /health

{
  "verdict": "allow",
  "reasons": [],
  "scores": {
    "violence": 0.02,
    "sexual_violence": 0.01,
    "nsfw": 0.01,
    "deepfake_suspect": 0.0,
    "cyberbullying": 0.01
  },
  "language": "en"
}

curl -s -X POST http://localhost:8000/moderate_text \
  -H "Content-Type: application/json" \
  -d '{"text": "hello world"}' | python3 -m json.tool

POST /gdpr/export              — export all data for a user (Article 15)
POST /gdpr/delete_request      — submit erasure request (Article 17)
GET  /gdpr/delete_request/{id} — check erasure status

POST /warnings/record          — record a violation, returns escalation action
GET  /warnings/{user_id_hash}  — fetch warning history

Escalation: 1st = educational notice, 2nd = admin notification, 3rd+ = supervisor escalation.

Telegram bot commands:

• /privacy — shows privacy notice in the group
• /delete_my_data — submits an Article 17 erasure request

Privacy notes:

• Content is never stored — only an 80-char preview in debug logs (never in DB)
• User IDs are hashed before storage
• DEEPFAKE_PROVIDER=ollama or local keeps all data on your server
• DEEPFAKE_PROVIDER=openai, sightengine, or api sends face crops externally

cd engine && pip install -r requirements.txt && pytest
cd telegram-bot && pip install -r requirements.txt && pytest

See ROADMAP.md for full details.

Contributions welcome. Open an issue before starting large changes.

Help needed with:

• Language packs (French, Spanish, Turkish, Arabic)
• Tests and documentation
• WhatsApp bot features

See CLAUDE.md for a detailed technical guide to the codebase.

MIT — see LICENSE.