How matt-the-thew/andy-ai works
Project type and purpose
• This is a full-stack (single-process) Discord bot written in Python.
• Purpose: listen for user mentions/commands in Discord, forward them to OpenAI’s GPT-4 model, apply caching, rate limiting, and logging, and send back a concise response.
File structure
• Entry point: main.py (initializes the bot, loads config, cogs, and runs the event loop).
• cogs/ (Discord “cogs”—modular event handlers):
• message_handler.py: receives and parses Discord messages, extracts user input.
• services/:
• llm_service.py: encapsulates all interaction with OpenAI’s API (ask, retry, cache lookup).
• utils/:
• cache.py: in-memory TTL cache
• rate_limit.py: per-user and per-guild limiter
• logger.py: structured logger with file rotation
• config/:
• settings.py: loads environment variables into a Config object
• tests/: unit tests for LLMService and utils.
• start.sh, requirements.txt: deployment scripts and dependencies.
README for additional insights
• Architectural patterns:
• Modular “cogs” (plug-in handlers)
• Service layer for external API
• Cross-cutting concerns (logging, caching, rate limiting) factored into utils
• Runtime dependencies: Discord API, OpenAI API
a. Main components:
1. Discord Gateway (external)
2. Bot Process (Python):
• Config Loader (settings.py)
• Main Controller (main.py)
• MessageHandler Cog
• LLMService
• Utilities (Cache, RateLimiter, Logger)
3. OpenAI API (external)
b. Relationships and interactions:
• Discord Gateway → (websocket events) → Main Controller → MessageHandler
• MessageHandler → (calls) → RateLimiter → allows or blocks request
• If allowed: MessageHandler → LLMService.ask
• LLMService.ask → (checks) → Cache
• Hit → returns cached response
• Miss → calls OpenAI API (with retry/backoff) → stores result in Cache
• LLMService → returns text → MessageHandler → sends message back via Discord API
• All steps use Logger to emit structured logs
• Config is globally accessible to all modules
c. Architectural patterns & design principles:
• Separation of concerns:
• Cogs for Discord events
• Service layer for external API
• Utils for cross-cutting
• Dependency inversion: modules depend on abstractions (e.g., Config, Logger)
• Single process, asynchronous event-driven architecture (Discord.py)
d. Key technologies/frameworks:
• discord.py (or similar) for Discord Gateway
• OpenAI Python SDK (requests under the hood)
• Python’s asyncio event loop
• In-memory cache (dict + TTL)
• Pytest for tests
• dotenv/envvars for configuration
Elements
• Clear labels for each component (e.g., “MessageHandler Cog,” “LLMService,” “Cache”)
• Discord → MessageHandler → LLMService → OpenAI → LLMService → MessageHandler → Discord
• Clouds for external services (Discord, OpenAI)
• Rectangles for internal modules