AI-powered Reddit mod queue triage bot — uses GPT-4 to classify severity, categorise violations, suggest removal reasons, and optionally act on them automatically. Every decision is audited. A live Flask dashboard lets you review the queue and execute quick actions.
| Component | Details |
|---|---|
| Reddit Integration | PRAW-based client, OAuth2 password-flow auth, mod-queue fetching, auto-actions |
| AI Triage Engine | OpenAI GPT-4 — classifies severity (low/medium/high/critical), categorises violations, suggests removal reasons, confidence scoring |
| Fallback Heuristics | Keyword-based analysis when the AI is unavailable |
| Web Dashboard | Flask app with prioritised queue view, quick-action buttons, statistics page |
| Database & Audit Log | SQLite + SQLAlchemy — every AI decision and mod action logged |
| Config System | YAML-based config with safe defaults (auto_actions: false) |
| Tests | Full pytest suite with mocked Reddit / OpenAI calls |
| CI Pipeline | GitHub Actions running lint + tests on Python 3.10 / 3.11 / 3.12 |
┌─────────────────────────────────────────────────────────┐
│ main.py │
│ (CLI entry-point — triage loop │ dashboard │ both) │
└───────────────┬──────────────────────────┬──────────────┘
│ │
┌───────▼────────┐ ┌────────▼────────┐
│ bot/ │ │ dashboard/ │
│ reddit_client │ │ app.py (Flask) │
│ ai_triage │ └────────┬────────┘
│ heuristics │ │
│ actions │ ┌────────▼────────┐
└───────┬────────┘ │ database/ │
│ │ models.py │
└────────────────►│ (SQLite audit) │
└─────────────────┘
git clone https://github.com/chrismaz11/SENTRX-Q.git
cd SENTRX-Q
pip install -r requirements.txtCopy the example env file and fill in your credentials:
cp .env.example .env # then edit .envREDDIT_CLIENT_ID=your_app_client_id
REDDIT_CLIENT_SECRET=your_app_client_secret
REDDIT_USERNAME=your_bot_reddit_username
REDDIT_PASSWORD=your_bot_reddit_password
OPENAI_API_KEY=sk-...
DASHBOARD_SECRET_KEY=change_me_in_productionReddit API credentials — create an app at https://www.reddit.com/prefs/apps (choose script type).
If you're not sure where to find your Reddit API client ID and secret, run the helper script:
pip install playwright
playwright install chromium
python scripts/fetch_reddit_credentials.pyThe script will open a browser, log you in, navigate to the Reddit apps
page, and extract/display your credentials. It will also offer to write
them directly into your .env file.
# Optional flags
python scripts/fetch_reddit_credentials.py --headless # no visible window
python scripts/fetch_reddit_credentials.py --username YOUR_NAME
⚠️ If Reddit shows a CAPTCHA or 2FA prompt during login, complete it manually in the browser — the script will pause and wait for you.
The official playtest subreddit is r/sentrx_q_dev. The default config already points there so you can start triaging immediately:
# Single triage pass (safe, no auto-actions by default)
python main.py triage --once
# Start the web dashboard
python main.py dashboard
# → open http://127.0.0.1:5000
# Run both together
python main.py runEdit config/default.yml and set:
triage:
auto_actions: true # ⚠️ validate on playtest first!
confidence_threshold: 0.85 # only fire actions above this confidenceAll settings live in config/default.yml. Every value can be overridden by an
environment variable using ${VAR_NAME} / ${VAR_NAME:-default} syntax.
| Key | Default | Description |
|---|---|---|
reddit.subreddits |
[sentrx_q_dev] |
Subreddits to monitor |
reddit.fetch_limit |
100 |
Items fetched per poll |
openai.model |
gpt-4 |
OpenAI model to use |
triage.auto_actions |
false |
Keep false until validated |
triage.confidence_threshold |
0.85 |
Minimum confidence to trigger auto-action |
triage.escalation_categories |
[threat, self_harm, csam] |
Categories that always escalate |
database.path |
sentrx_q.db |
SQLite file path |
dashboard.port |
5000 |
Dashboard port |
pytest # full suite with coverage
pytest tests/test_heuristics.py -v # single moduleThe test suite uses mocked PRAW and OpenAI clients — no real API calls.
SENTRX-Q/
├── bot/
│ ├── reddit_client.py # PRAW client — auth, mod-queue, actions
│ ├── ai_triage.py # GPT-4 triage engine
│ ├── heuristics.py # Keyword-based fallback
│ └── actions.py # Auto-action runner
├── dashboard/
│ ├── app.py # Flask application factory
│ └── templates/ # Jinja2 HTML templates
├── database/
│ └── models.py # SQLAlchemy models + AuditLog
├── config/
│ └── default.yml # YAML config (safe defaults)
├── scripts/
│ └── fetch_reddit_credentials.py # Playwright helper — auto-fetch API creds
├── tests/ # pytest suite (all mocked)
├── .github/workflows/
│ └── ci.yml # GitHub Actions CI
├── config.py # Config loader (env-var expansion)
├── main.py # CLI entry point
└── requirements.txt
- Webhook / push notifications for critical escalations
- Multi-subreddit dashboard filter
- Rate-limit aware polling with exponential back-off
- Docker image +
docker-compose.yml - GPT-4o / fine-tuned model support
- Slack / Discord alert integration
If SENTRX-Q saves you hours of manual mod-queue review, consider supporting the project:
- ❤️ GitHub Sponsors — one-time or recurring support
- ☕ Ko-fi, Buy Me a Coffee, and Patreon links coming soon
Your support helps fund API costs, new features, and keeping the hosted version free for small subreddits.
| Tier | Price | Features |
|---|---|---|
| Free | Self-host, free forever | Heuristic triage + web dashboard |
| Pro (coming soon) | TBD | AI triage (GPT-4), auto-actions, JSON API access |
| Enterprise (coming soon) | TBD | Everything in Pro + multi-subreddit, custom rules, priority support |
The free tier is fully functional for most small-to-medium subreddits.
Feature flags live in config/default.yml under the tier: key.
MIT © chrismaz11