How xsota/meowgent works
Project Type and Purpose
• This is a Python-based Discord bot (“meowgent”) built as a modular backend service. It connects to Discord, processes events/messages via “cogs,” calls AI and other external services, and persists state (e.g., stamina) in Firebase. Its key features are interactive chat (LLM-powered), voice channel notifications, a stamina system, and tool integrations (web search, crypto prices, IGDB).
File Structure Analysis
• Top-level configs and deployment scripts:
• .env.example / .python-version / Dockerfile / docker-compose.yml / fly.toml / Procfile / pyproject.toml
• Source code under src/:
• bot.py: bot initialization & Discord client setup
• meowgent.py: core logic for LLM calls and prompt management
• cogs/: plugin modules for each feature
– chart_cog.py (ASCII charts, uses asciichart.py + graph.py)
– price_cog.py (crypto price lookup)
– events_cog.py (voice-channel join/leave notifications)
– proposal_cog.py (game proposals via IGDB?)
• Modules:
– firebase.py (state persistence for stamina, message history)
– igdb.py (game database queries)
– discord_messages_state.py (in-memory or cached state)
– tools/: utility scripts (get_current_time, task_manager, web_search)
• CI/issue templates under .github/, plus version control ignores.
README Insights
• Confirms core features and use of environment‐variable configuration for API keys (Discord, OpenAI, SERP).
• Deployment via fly.io and Docker, typical 12-factor app.
a. Main Components
• Discord Gateway (external service)
• Bot Application (container/service)
– Discord Client & Event Loop
– Cog Manager (loads chart, price, events, proposal cogs)
– Core Logic (meowgent.py for LLM prompts, stamina checks)
• State Store: Firebase (NoSQL)
• External APIs:
– OpenAI (LLM)
– SERP API (web_search)
– Crypto Price API (price_cog)
– IGDB API (proposal_cog)
• Utility Modules (asciichart, graph, task_manager, time service)
b. Relationships & Data Flows
1. User → Discord → Bot (bot.py)
2. Bot routes event to appropriate Cog
3. Cog may:
– Query Firebase for state/stamina
– Call meowgent.py → OpenAI for NLP response
– Call tool modules (web_search, get_current_time)
– Call external domain API (price or IGDB)
4. Bot sends response → Discord → User
5. Bot writes updated state → Firebase
c. Architectural Patterns & Principles
• Plugin/Cog pattern for separation of features
• Single-responsibility modules (each module/cog handles one domain)
• Event-driven design (Discord events trigger handlers)
• Externalize state and secrets for portability (Firebase + .env)
d. Key Technologies & Frameworks
• discord.py (Discord client)
• Python 3.12+, uv (task runner)
• Firebase SDK
• OpenAI API
• SERP API, IGDB API
• Docker & fly.io for containerized deployment