How aqn96/llm-conquestfour works
Project type and purpose
• ConquestFour is a desktop application that combines a classic Connect Four game with an on-device AI–powered narrative.
• It isn’t a web app or microservices system—it’s a modular Python application with a GUI (PyQt6), local LLM integration (Ollama + Mistral-7B), core game logic, narrative templating, and optional voice I/O.
File structure
Top-level directories and their roles:
• ai/ → AI engine integration, model loaders, prompt builders, personalities, unified interface
• game/ → Core Connect Four logic, minimax algorithm, state validation, difficulty levels
• ui/ → PyQt6 GUI widgets, windows, board rendering, theme management
• speech_to_text/ → Optional STT module for recording and transcribing audio
• text_to_speech/ → Optional TTS module for synthesizing audio
• templates/ → Jinja2 narrative templates (fantasy, scifi)
• assets/ → Static images and other assets
• main.py & demo/ → Entrypoints and a structured demo showcasing app components
README for additional insights
• Modular architecture is called out: Game Logic Core, UI Layer, AI Engine, Narrative System, System Monitoring.
• Technologies: Python 3.9–3.12, PyQt6, Ollama, Mistral-7B, Jinja2, FFmpeg (optional).
• Features: local processing, thermal management, three difficulty levels, chat interface, themes.
Main components to reflect
a. UI Layer (PyQt6)
• Located in ui/ and demo/app/ui/
b. Game Logic Core
• Four rules, minimax with alpha-beta pruning, state validator, difficulty levels
• Located in game/ and demo/game/
c. AI Engine & Narrative System
• Model loading (Ollama wrappers), context prompter, unified model interface, personalities, fallback strategies
• Narrative templating (Jinja2) under templates/ and ai/ollama/
d. System Monitoring
• Thermal monitor to scale LLM usage based on device temperature
• Located in ai/utils/thermal_monitor.py and demo/ai/thermal_monitor.py
e. Optional Voice I/O
• Speech-to-text pipeline, audio recorder, TTS using FFmpeg
• In speech_to_text/ and text_to_speech/
Relationships and data flows
• User clicks on UI → UI controller invokes Game Logic → Game Logic updates board state.
• On each move, UI or controller calls the Narrative System → Context Prompter builds prompt → unified_model_interface sends prompt to Ollama server → Mistral-7B generates narrative.
• Narrative returned → UI updates narrative panel + optional audio (TTS).
• Thermal Monitor observes CPU temperature in parallel and may throttle AI calls or reduce model precision.
• Optional STT: user voice → audio_recorder → speech_to_text module → transcribed text → chat interface in UI.
Architectural patterns and design principles
• MVC-like separation:
• Model = game state & AI model interface
• View = PyQt6 UI components
• Controller = ui controllers / demo/app/controllers
• Modular layering: UI ↔ Game Core ↔ AI/Narrative ↔ External LLM service
• Single-responsibility: each folder handles one aspect (logic, UI, AI, I/O, assets).
• Abstraction over LLM: unified_model_interface hides Ollama specifics and allows fallback narrators.
Final advice
• Be exhaustive: capture every high-level folder and its role.
• How modules interact at runtime, not just static containment.
• Keep labels brief but precise; include key technologies (PyQt6, Ollama, Mistral, Jinja2).
• Iterate with the engineering team to validate accuracy of data flows and throttling logic.