latte
4e16777f25
Features: - Core moderation: warn, kick, ban, timeout, strike system - Automod: banned words filter, scam detection, anti-spam, link filtering - AI moderation: Claude/OpenAI integration, NSFW detection, phishing analysis - Verification system: button, captcha, math, emoji challenges - Rate limiting system with configurable scopes - Event logging: joins, leaves, message edits/deletes, voice activity - Per-guild configuration with caching - Docker deployment support Bug fixes applied: - Fixed await on session.delete() in guild_config.py - Fixed memory leak in AI moderation message tracking (use deque) - Added error handling to bot shutdown - Added error handling to timeout command - Removed unused Literal import - Added prefix validation - Added image analysis limit (3 per message) - Fixed test mock for SQLAlchemy model
104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
GuardDen is a Discord moderation bot built with discord.py, PostgreSQL, and optional AI integration (Claude/OpenAI). Self-hosted with Docker support.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pip install -e ".[dev,ai]"
|
|
|
|
# Run the bot
|
|
python -m guardden
|
|
|
|
# Run tests
|
|
pytest
|
|
|
|
# Run single test
|
|
pytest tests/test_verification.py::TestVerificationService::test_verify_correct
|
|
|
|
# Lint and format
|
|
ruff check src tests
|
|
ruff format src tests
|
|
|
|
# Type checking
|
|
mypy src
|
|
|
|
# Docker deployment
|
|
docker compose up -d
|
|
```
|
|
|
|
## 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)
|
|
|
|
## Key Patterns
|
|
|
|
- All database operations use async SQLAlchemy with `asyncpg`
|
|
- Guild configurations are cached in `GuildConfigService._cache`
|
|
- 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`
|
|
|
|
## Automod System
|
|
|
|
- `AutomodService` in `services/automod.py` handles rule-based content filtering
|
|
- Checks run in order: banned words → scam links → spam → invite links
|
|
- 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
|
|
|
|
## AI Moderation System
|
|
|
|
- `services/ai/` contains provider abstraction and implementations
|
|
- `AIProvider` base class defines interface: `moderate_text()`, `analyze_image()`, `analyze_phishing()`
|
|
- `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
|
|
|
|
## 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
|
|
|
|
## Adding New Cogs
|
|
|
|
1. Create file in `src/guardden/cogs/`
|
|
2. Implement `setup(bot)` async function
|
|
3. Add cog path to `_load_cogs()` in `bot.py`
|
|
|
|
## Adding New AI Provider
|
|
|
|
1. Create `src/guardden/services/ai/newprovider.py`
|
|
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
|