feat: Complete minimal bot refactor - AI providers, models, docs, and migration
Changes: - Strip AI providers to image-only analysis (remove text/phishing methods) - Simplify guild models (remove BannedWord, reduce GuildSettings columns) - Create migration to drop unused tables and columns - Rewrite README for minimal bot focus - Update CLAUDE.md architecture documentation Result: -992 lines, +158 lines (net -834 lines) Cost-conscious bot ready for deployment.
This commit is contained in:
74
CLAUDE.md
74
CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
## Project Overview
|
||||
|
||||
GuardDen is a Discord moderation bot built with discord.py, PostgreSQL, and optional AI integration (Claude/OpenAI). Self-hosted with Docker support.
|
||||
GuardDen is a minimal, cost-conscious Discord moderation bot focused on spam detection and NSFW image filtering. Built with discord.py, PostgreSQL, and optional AI integration (Claude/OpenAI) for image analysis only. Self-hosted with Docker support.
|
||||
|
||||
## Commands
|
||||
|
||||
@@ -19,7 +19,7 @@ python -m guardden
|
||||
pytest
|
||||
|
||||
# Run single test
|
||||
pytest tests/test_verification.py::TestVerificationService::test_verify_correct
|
||||
pytest tests/test_automod.py::TestAutomodService::test_spam_detection
|
||||
|
||||
# Lint and format
|
||||
ruff check src tests
|
||||
@@ -30,73 +30,48 @@ mypy src
|
||||
|
||||
# Docker deployment
|
||||
docker compose up -d
|
||||
|
||||
# Database migrations
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
- `src/guardden/bot.py` - Main bot class (`GuardDen`) extending `commands.Bot`, manages lifecycle and services
|
||||
- `src/guardden/config.py` - Pydantic settings loaded from environment variables (prefix: `GUARDDEN_`)
|
||||
- `src/guardden/models/` - SQLAlchemy 2.0 async models for PostgreSQL
|
||||
- `src/guardden/services/` - Business logic (database, guild config, automod, AI, verification, rate limiting)
|
||||
- `src/guardden/cogs/` - Discord command groups (events, moderation, admin, automod, ai_moderation, verification)
|
||||
- `src/guardden/models/guild.py` - SQLAlchemy 2.0 async models for guilds and settings
|
||||
- `src/guardden/services/` - Business logic (database, guild config, automod, AI, rate limiting)
|
||||
- `src/guardden/cogs/` - Discord command groups (automod, ai_moderation, owner)
|
||||
- `config.yml` - Single YAML file for bot configuration
|
||||
|
||||
## Key Patterns
|
||||
|
||||
- All database operations use async SQLAlchemy with `asyncpg`
|
||||
- Guild configurations are cached in `GuildConfigService._cache`
|
||||
- Guild configurations loaded from single `config.yml` file (not per-guild)
|
||||
- Discord snowflake IDs stored as `BigInteger` in PostgreSQL
|
||||
- Moderation actions logged to `ModerationLog` table with automatic strike escalation
|
||||
- Environment variables: `GUARDDEN_DISCORD_TOKEN`, `GUARDDEN_DATABASE_URL`
|
||||
- No moderation logging or strike system
|
||||
- Environment variables: `GUARDDEN_DISCORD_TOKEN`, `GUARDDEN_DATABASE_URL`, AI keys
|
||||
|
||||
## Automod System
|
||||
|
||||
- `AutomodService` in `services/automod.py` handles rule-based content filtering
|
||||
- Checks run in order: banned words → scam links → spam → invite links
|
||||
- `AutomodService` in `services/automod.py` handles spam detection
|
||||
- Checks: message rate limit → duplicate messages → mass mentions
|
||||
- Spam tracking uses per-guild, per-user trackers with automatic cleanup
|
||||
- Scam detection uses compiled regex patterns in `SCAM_PATTERNS` list
|
||||
- Results return `AutomodResult` dataclass with actions to take
|
||||
- **Whitelist**: Users in `GuildSettings.whitelisted_user_ids` bypass ALL automod checks
|
||||
- Users with "Manage Messages" permission also bypass automod
|
||||
- Everyone gets moderated (no whitelist, no bypass for permissions)
|
||||
|
||||
## AI Moderation System
|
||||
|
||||
- `services/ai/` contains provider abstraction and implementations
|
||||
- `AIProvider` base class defines interface: `moderate_text()`, `analyze_image()`, `analyze_phishing()`
|
||||
- `AIProvider` base class defines interface: `analyze_image()` only
|
||||
- `AnthropicProvider` and `OpenAIProvider` implement the interface
|
||||
- `NullProvider` used when AI is disabled (returns empty results)
|
||||
- Factory pattern via `create_ai_provider(provider, api_key)`
|
||||
- `ModerationResult` includes severity scoring based on confidence + category weights
|
||||
- Sensitivity setting (0-100) adjusts thresholds per guild
|
||||
- **NSFW-Only Filtering** (default: `True`): When enabled, only sexual content is filtered; violence, harassment, etc. are allowed
|
||||
- Filtering controlled by `nsfw_only_filtering` field in `GuildSettings`
|
||||
- **Whitelist**: Users in `GuildSettings.whitelisted_user_ids` bypass ALL AI moderation checks
|
||||
|
||||
## Verification System
|
||||
|
||||
- `VerificationService` in `services/verification.py` manages challenges
|
||||
- Challenge types: button, captcha, math, emoji (via `ChallengeGenerator` classes)
|
||||
- `PendingVerification` tracks user challenges with expiry and attempt limits
|
||||
- Discord UI components in `cogs/verification.py`: `VerifyButton`, `EmojiButton`, `CaptchaModal`
|
||||
- Background task cleans up expired verifications every 5 minutes
|
||||
|
||||
## Rate Limiting System
|
||||
|
||||
- `RateLimiter` in `services/ratelimit.py` provides general-purpose rate limiting
|
||||
- Scopes: USER (global), MEMBER (per-guild), CHANNEL, GUILD
|
||||
- `@ratelimit()` decorator for easy command rate limiting
|
||||
- `get_rate_limiter()` returns singleton instance
|
||||
- Default limits configured for commands, moderation, verification, messages
|
||||
|
||||
## Notification System
|
||||
|
||||
- `utils/notifications.py` contains `send_moderation_notification()` utility
|
||||
- Handles sending moderation warnings to users with DM → in-channel fallback
|
||||
- **In-Channel Warnings** (default: `False`): Optional PUBLIC channel messages when DMs fail
|
||||
- **IMPORTANT**: In-channel messages are PUBLIC, visible to all users (Discord API limitation)
|
||||
- Temporary messages auto-delete after 10 seconds to minimize clutter
|
||||
- Used by automod, AI moderation, and manual moderation commands
|
||||
- Controlled by `send_in_channel_warnings` field in `GuildSettings`
|
||||
- Disabled by default for privacy reasons
|
||||
- `ImageAnalysisResult` includes NSFW categories, severity, confidence
|
||||
- Sensitivity setting (0-100) adjusts thresholds
|
||||
- **NSFW-Only Filtering** (default: `True`): Only sexual content is filtered
|
||||
- **Cost Controls**: Rate limiting, deduplication, file size limits, max images per message
|
||||
- `AIRateLimiter` in `services/ai_rate_limiter.py` tracks usage
|
||||
|
||||
## Adding New Cogs
|
||||
|
||||
@@ -110,10 +85,3 @@ docker compose up -d
|
||||
2. Implement `AIProvider` abstract class
|
||||
3. Add to factory in `services/ai/factory.py`
|
||||
4. Add config option in `config.py`
|
||||
|
||||
## Adding New Challenge Type
|
||||
|
||||
1. Create new `ChallengeGenerator` subclass in `services/verification.py`
|
||||
2. Add to `ChallengeType` enum
|
||||
3. Register in `VerificationService._generators`
|
||||
4. Create corresponding UI components in `cogs/verification.py` if needed
|
||||
|
||||
Reference in New Issue
Block a user