latte
b4f29a9d5e
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.
88 lines
3.0 KiB
Markdown
88 lines
3.0 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 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
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pip install -e ".[dev,ai]"
|
|
|
|
# Run the bot
|
|
python -m guardden
|
|
|
|
# Run tests
|
|
pytest
|
|
|
|
# Run single test
|
|
pytest tests/test_automod.py::TestAutomodService::test_spam_detection
|
|
|
|
# Lint and format
|
|
ruff check src tests
|
|
ruff format src tests
|
|
|
|
# Type checking
|
|
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/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 loaded from single `config.yml` file (not per-guild)
|
|
- Discord snowflake IDs stored as `BigInteger` in PostgreSQL
|
|
- No moderation logging or strike system
|
|
- Environment variables: `GUARDDEN_DISCORD_TOKEN`, `GUARDDEN_DATABASE_URL`, AI keys
|
|
|
|
## Automod System
|
|
|
|
- `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
|
|
- Results return `AutomodResult` dataclass with actions to take
|
|
- Everyone gets moderated (no whitelist, no bypass for permissions)
|
|
|
|
## AI Moderation System
|
|
|
|
- `services/ai/` contains provider abstraction and implementations
|
|
- `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)`
|
|
- `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
|
|
|
|
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`
|