How uppermoon0/lilythethird works
Project Type and Purpose
• Project Type: A full‑stack “unified platform” combining a desktop GUI (PyQt5), an LLM‑powered chatbot, a Discord bot, and VTube Studio integration.
• Purpose: Provide a single interface for chat (with translation & TTS), Discord interactions, virtual avatar control, and long‑term semantic memory via MongoDB.
File Structure
• Top‑level:
– main.py: entry point launching the GUI and orchestrating subsystems.
– settings_manager.py + config/models.py: handles environment and configuration.
– requirements.txt, .env.template, llm_api_keys.json.template.
• Directories:
– views/: PyQt5 UI components (chat_tab, discord_tab, vtube_tab, plus reusable components).
– llm/: LLM abstraction layers (base_llm, chatbox_llm, discord_llm, tool_executor, action_extractor).
– memory/: mongo_handler for long‑term memory (vector embeddings, semantic search).
– discord_integration/: Discord.py bot code, command modules, separate process wrapper (processes/discord_process.py).
– tools/: auxiliary tool implementations (file, web search, time).
– translator.py & tts.py: translation via Deep Translator & TTS‑Provider client.
– lib/: frontend static assets (JS/CSS for rich components within the GUI).
Extract Additional Insights from README
• Long‑term memory uses MongoDB + sentence‑transformers for semantic search.
• LLM API keys are managed via round‑robin in llm_api_keys.json.
• External services: OpenAI/Gemini APIs, external TTS‑Provider server, MongoDB, VTube Studio WebSocket API.
Main Components
a. GUI Layer (PyQt5)
– Chat Tab
– Discord Tab
– VTube Tab
– Shared UI Components (attachment_chip, color_circle, etc.)
b. Core Orchestrator
– main.py
– settings_manager & config/models
c. LLM Layer
– LLM Client (llm/llm_client.py)
– ChatboxLLM & DiscordLLM modules
– Tool Executor & Action Extractor
d. Memory Layer
– MongoDB instance
– Memory Manager (memory/mongo_handler)
e. Tooling Layer
– Translator (translator.py)
– TTS Client (tts.py ↔ external TTS‑Provider over WebSocket)
– Misc Tools (tools/file_tool, time_tool, web_search_tool)
f. Integration Layer
– Discord Bot Process (discord_integration + processes/discord_process)
– VTube Studio WebSocket connector
g. External Services
– OpenAI/Gemini LLM APIs
– Deep Translator service
– TTS‑Provider WebSocket server
– MongoDB server
– VTube Studio application
Relationships & Data Flows
• User → GUI → Core Orchestrator → LLM Layer → External LLM API → LLM Layer processes response.
• LLM Layer ↔ Memory Layer for fetch_memory/save_memory.
• LLM Layer ↔ Tools Layer (translator, web search, time).
• Translator → Deep Translator service.
• TTS Client → TTS‑Provider WebSocket → audio streamed back → GUI plays sound.
• GUI Discord Tab → Core Orchestrator → spawns Discord Bot Process → Discord.py communicates with LLM Layer similarly, then posts back to Discord channel.
• GUI VTube Tab → WebSocket → VTube Studio → avatar control commands.
Architectural Patterns & Design Principles
• Layered Architecture: clearly separate presentation (views), business logic (llm, memory, tools), and integration (discord_integration, VTube WS).
• Plug‑in Style Tools: each tool implements a common interface, orchestrated by a Tool Executor.
• Process Isolation: run Discord bot in its own process to prevent GUI blocking.
• Round‑Robin Key Management: LLM API keys cycled for reliability/throughput.
• MVC‑like Separation: views/ components (views/) vs. models (models/) vs. controllers (llm, processes)