GuardDen/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

• src/guardden/ is the main package: bot.py (bot lifecycle), cogs/ (Discord commands/events), services/ (business logic), models/ (SQLAlchemy models), config.py (settings), and utils/ (shared helpers).
• tests/ holds pytest suites (test_*.py) for services and utilities.
• migrations/ and alembic.ini define database migrations.
• docker-compose.yml and Dockerfile support containerized development/deployments.
• .env.example provides the configuration template.

Build, Test, and Development Commands

• pip install -e ".[dev,ai]" installs dev tooling plus optional AI providers.
• python -m guardden runs the bot locally.
• pytest runs the full test suite; pytest tests/test_verification.py::TestVerificationService::test_verify_correct runs a single test.
• ruff check src tests lints; ruff format src tests formats.
• mypy src runs strict type checks.
• docker compose up -d starts the full stack; docker compose up db -d starts only Postgres.

Coding Style & Naming Conventions

• Python 3.11 with 4-space indentation; keep lines within 100 chars (Ruff config).
• Prefer type hints and clean async patterns; mypy runs in strict mode.
• Naming: snake_case for modules/functions, CamelCase for classes, UPPER_SNAKE for constants.
• New cogs live in src/guardden/cogs/ and should be wired in _load_cogs() in src/guardden/bot.py.

Testing Guidelines

• Tests use pytest + pytest-asyncio (asyncio_mode=auto).
• Follow test_*.py file names and test_* function names; group related cases in Test* classes.
• Add or update tests for new services, automod rules, or AI provider behavior.

Commit & Pull Request Guidelines

• Commit messages are short, imperative, and capitalized (e.g., Fix: initialize guild config..., Add Discord bot setup...).
• PRs should include a concise summary, tests run, and any config or migration notes; link related issues when available.

Security & Configuration Tips

• Store secrets in .env (never commit); configuration keys are prefixed with GUARDDEN_.
• PostgreSQL is required; default URL is postgresql://guardden:guardden@localhost:5432/guardden.
• AI features require GUARDDEN_AI_PROVIDER plus the matching API key.