disbord/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Environment

Virtual Environment & Dependencies

• Always activate the virtual environment with source .venv/bin/activate
• Use uv for all package management operations: uv sync --all-extras for installation
• Dependencies are managed via pyproject.toml with dev and test dependency groups

Python Configuration

• Python 3.12+ required
• Never use Any type - find more specific types instead
• No # type: ignore comments - fix type issues properly
• Write docstrings imperatively with punctuation
• Use modern typing patterns (from typing and collections.abc)

Core Architecture

Main Components

• core/: Core system managers (AI, database, memory, consent)

  • ai_manager.py: Orchestrates multiple AI providers (OpenAI, Anthropic, Groq, Ollama, etc.)
  • database.py: PostgreSQL database management with Alembic migrations
  • memory_manager.py: Long-term context storage using vector embeddings
  • consent_manager.py: GDPR-compliant user privacy management

• services/: Processing pipeline services organized by domain

  • audio/: Audio recording, transcription, speaker diarization, laughter detection, TTS
  • quotes/: Quote analysis and scoring using AI providers
  • automation/: Response scheduling (real-time, 6-hour rotation, daily summaries)
  • monitoring/: Health checks and metrics collection
  • interaction/: User feedback systems and assisted tagging

• plugins/: Extensible plugin system

  • ai_voice_chat/: Voice interaction capabilities
  • personality_engine/: Dynamic personality system
  • research_agent/: Information research capabilities

Bot Architecture

The main bot (QuoteBot in main.py) orchestrates all components:

1. Records 120-second rolling audio clips from Discord voice channels
2. Processes audio through speaker diarization and transcription
3. Analyzes quotes using AI providers with configurable scoring thresholds
4. Schedules responses based on quote quality scores
5. Maintains long-term conversation memory and speaker profiles

Common Development Commands

Environment Setup

make venv                    # Create virtual environment
source .venv/bin/activate    # Activate virtual environment (always required)
make install                 # Install all dependencies with uv

Running the Bot

make run                     # Run bot locally
make run-dev                 # Run with auto-reload for development
make docker-build            # Build Docker image
make docker-run              # Run bot in Docker

Testing

make test                    # Run all tests via run_tests.sh
make test-unit              # Unit tests only (fast)
make test-integration       # Integration tests only
make test-performance       # Performance benchmarks
make test-coverage          # Generate coverage report
./run_tests.sh all -v       # Run all tests with verbose output

Code Quality

make lint                   # Check code formatting and linting (black, isort, ruff)
make format                 # Auto-format code
make type-check             # Run Pyright/mypy type checking
make pre-commit             # Run all pre-commit checks
make security               # Security scans (bandit, safety)

Database Operations

make migrate                # Apply migrations
make migrate-create         # Create new migration (prompts for message)
make migrate-rollback       # Rollback last migration
make db-reset              # Reset database (DESTRUCTIVE)

Monitoring & Debugging

make logs                   # Follow bot logs
make health                 # Check bot health endpoint
make metrics               # Show bot metrics

Testing Framework

• pytest with markers: unit, integration, performance, load, slow
• Coverage: Target 80% minimum coverage (enforced in CI)
• Test structure: Separate unit/integration/performance test directories
• Fixtures: Mock Discord objects available in tests/fixtures/
• No loops or conditionals in tests - use inline functions instead
• Async testing: pytest-asyncio configured for automatic async handling

Configuration Management

Environment Variables

Key variables in .env (copy from .env.example):

• DISCORD_TOKEN: Discord bot token (required)
• DATABASE_URL: PostgreSQL connection string
• REDIS_URL: Redis cache connection
• QDRANT_URL: Vector database connection
• AI Provider keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY

Quote Scoring System

Configurable thresholds in settings:

• QUOTE_THRESHOLD_REALTIME=8.5: Immediate responses
• QUOTE_THRESHOLD_ROTATION=6.0: 6-hour summaries
• QUOTE_THRESHOLD_DAILY=3.0: Daily compilations

Data Infrastructure

Databases

• PostgreSQL: Primary data storage with Alembic migrations
• Redis: Caching and queue management
• Qdrant: Vector embeddings for memory and context

Docker Services

Full development stack via docker-compose.yml:

• Main bot application
• PostgreSQL, Redis, Qdrant databases
• Prometheus metrics collection
• Grafana monitoring dashboards
• Nginx reverse proxy

Volume Mounts

• ./data/: Persistent database storage
• ./logs/: Application logs
• ./temp/: Temporary audio files
• ./config/: Service configurations

Code Standards

Pre-commit Requirements

• All linting must pass: Never use --no-verify or skip lint errors
• Type checking: Use Pyrefly for type linting, fix all type issues
• Testing: Never skip failed tests unless explicitly instructed
• No shortcuts: Complete all discovered subtasks as part of requirements

File Creation Policy

• Avoid creating new files unless specifically required
• Prefer editing existing files over creating new ones
• Never create documentation files unless explicitly requested

AI Provider Integration

Use the Context7 MCP to validate modern patterns and syntax for AI/ML libraries. The codebase supports multiple AI providers through a unified interface in core/ai_manager.py.