# aqn96/llm-conquestfour architecture

> Architecture diagram of the GitHub repository aqn96/llm-conquestfour, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aqn96/llm-conquestfour
- Repository: https://github.com/aqn96/llm-conquestfour

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer (UI)
    subgraph "Presentation Layer" 
        direction TB
        UI_Window["connect4_game_window.py"]:::frontend
        UI_Board["connect4board.py"]:::frontend
        UI_Setup["game_setup.py"]:::frontend
        Demo_Window["window_setup.py"]:::frontend
        Demo_Layout["layout_builder.py"]:::frontend
        Demo_Narr["narrative.py"]:::frontend
        Demo_Styles["styles.py"]:::frontend
    end

    %% Application Logic
    subgraph "Application Logic" 
        direction TB
        CF["connect_four.py"]:::core
        Minimax["minimax.py"]:::core
        Validator["state_validator.py"]:::core
        Difficulty["difficulty_levels.py"]:::core
        ThermalAware["thermal_aware_ai.py"]:::core
        Demo_CF["connect_four.py (demo)"]:::core
        Demo_Minimax["minimax.py (demo)"]:::core
        Demo_Validator["state_validator.py (demo)"]:::core
    end

    %% AI & Narrative Layer
    subgraph "AI & Narrative Layer" 
        direction TB
        LlamaBot["llama_bot.py"]:::ai
        Personality["personality.py"]:::ai
        ContextPrompter["context_prompter.py"]:::ai
        ModelLoader["model_loader.py"]:::ai
        UnifiedInterface["unified_model_interface.py"]:::ai
        BaseLoader["base_model_loader.py"]:::ai
        MistralLoader["mistral_loader.py"]:::ai
        BaseNarrator["base_narrator.py"]:::ai
        FallbackNarrator["fallback_narrator.py"]:::ai
    end

    %% System Services
    subgraph "System Services" 
        direction TB
        Thermal_Core["thermal_monitor.py"]:::svc
        Demo_Therm1["thermal_monitor.py (demo ai)"]:::svc
        Demo_Therm2["temperature_monitor.py"]:::svc
        Fantasy["fantasy.jinja2"]:::svc
        SciFi["scifi.jinja2"]:::svc
        Demo_Temp_F["fantasy.jinja2 (demo)"]:::svc
        Demo_Temp_S["scifi.jinja2 (demo)"]:::svc
    end

    %% Optional Voice I/O
    subgraph "Optional Voice I/O" 
        direction TB
        STT_Recorder["audio_recorder.py"]:::svc
        STT_Pipeline["record_and_transcribe.py"]:::svc
        STT_Module["speech_to_text.py"]:::svc
        TTS["text_to_speech.py"]:::svc
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        Ollama((Ollama Server)):::external
        Mistral((Mistral-7B)):::external
        FFmpeg((FFmpeg)):::external
    end

    %% Data Flows
    UI_Window -->|user action| CF
    UI_Board --> CF
    UI_Setup --> CF
    CF -->|updates state| Validator
    CF --> Minimax
    CF --> Difficulty
    CF --> ThermalAware
    Validator --> ContextPrompter
    ContextPrompter --> UnifiedInterface
    UnifiedInterface --> LlamaBot
    UnifiedInterface --> Personality
    LlamaBot --> Ollama
    Ollama --> Mistral
    UnifiedInterface -->|narrative text| Demo_Narr
    UnifiedInterface -->|audio data| TTS
    Thermal_Core --> UnifiedInterface
    Demo_Therm1 --> UnifiedInterface
    Demo_Therm2 --> UnifiedInterface
    STT_Recorder --> STT_Pipeline
    STT_Pipeline --> STT_Module
    STT_Module --> Demo_Narr
    TTS -->|play audio| Demo_Narr

    %% Click Events
    click UI_Window "https://github.com/aqn96/llm-conquestfour/blob/master/ui/connect4_game_window.py"
    click UI_Board "https://github.com/aqn96/llm-conquestfour/blob/master/ui/connect4board.py"
    click UI_Setup "https://github.com/aqn96/llm-conquestfour/blob/master/ui/game_setup.py"
    click Demo_Window "https://github.com/aqn96/llm-conquestfour/blob/master/demo/app/ui/window_setup.py"
    click Demo_Layout "https://github.com/aqn96/llm-conquestfour/blob/master/demo/app/ui/layout_builder.py"
    click Demo_Narr "https://github.com/aqn96/llm-conquestfour/blob/master/demo/app/ui/narrative.py"
    click Demo_Styles "https://github.com/aqn96/llm-conquestfour/blob/master/demo/app/ui/styles.py"
    click CF "https://github.com/aqn96/llm-conquestfour/blob/master/game/connect_four.py"
    click Minimax "https://github.com/aqn96/llm-conquestfour/blob/master/game/minimax.py"
    click Validator "https://github.com/aqn96/llm-conquestfour/blob/master/game/state_validator.py"
    click Difficulty "https://github.com/aqn96/llm-conquestfour/blob/master/game/difficulty_levels.py"
    click ThermalAware "https://github.com/aqn96/llm-conquestfour/blob/master/game/thermal_aware_ai.py"
    click Demo_CF "https://github.com/aqn96/llm-conquestfour/blob/master/demo/game/connect_four.py"
    click Demo_Minimax "https://github.com/aqn96/llm-conquestfour/blob/master/demo/game/minimax.py"
    click Demo_Validator "https://github.com/aqn96/llm-conquestfour/blob/master/demo/game/state_validator.py"
    click LlamaBot "https://github.com/aqn96/llm-conquestfour/blob/master/ai/ollama/llama_bot.py"
    click Personality "https://github.com/aqn96/llm-conquestfour/blob/master/ai/ollama/personality.py"
    click ContextPrompter "https://github.com/aqn96/llm-conquestfour/blob/master/demo/ai/context_prompter.py"
    click ModelLoader "https://github.com/aqn96/llm-conquestfour/blob/master/demo/ai/model_loader.py"
    click UnifiedInterface "https://github.com/aqn96/llm-conquestfour/blob/master/demo/ai/unified_model_interface.py"
    click BaseLoader "https://github.com/aqn96/llm-conquestfour/blob/master/demo/ai/loaders/base_model_loader.py"
    click MistralLoader "https://github.com/aqn96/llm-conquestfour/blob/master/demo/ai/loaders/mistral_loader.py"
    click BaseNarrator "https://github.com/aqn96/llm-conquestfour/blob/master/demo/ai/narrators/base_narrator.py"
    click FallbackNarrator "https://github.com/aqn96/llm-conquestfour/blob/master/demo/ai/narrators/fallback_narrator.py"
    click Thermal_Core "https://github.com/aqn96/llm-conquestfour/blob/master/ai/utils/thermal_monitor.py"
    click Demo_Therm1 "https://github.com/aqn96/llm-conquestfour/blob/master/demo/ai/thermal_monitor.py"
    click Demo_Therm2 "https://github.com/aqn96/llm-conquestfour/blob/master/demo/app/utils/temperature_monitor.py"
    click Fantasy "https://github.com/aqn96/llm-conquestfour/blob/master/conquest_four/templates/fantasy.jinja2"
    click SciFi "https://github.com/aqn96/llm-conquestfour/blob/master/conquest_four/templates/scifi.jinja2"
    click Demo_Temp_F "https://github.com/aqn96/llm-conquestfour/blob/master/demo/templates/fantasy.jinja2"
    click Demo_Temp_S "https://github.com/aqn96/llm-conquestfour/blob/master/demo/templates/scifi.jinja2"
    click STT_Recorder "https://github.com/aqn96/llm-conquestfour/blob/master/speech_to_text/audio_recorder.py"
    click STT_Pipeline "https://github.com/aqn96/llm-conquestfour/blob/master/speech_to_text/record_and_transcribe.py"
    click STT_Module "https://github.com/aqn96/llm-conquestfour/blob/master/speech_to_text/speech_to_text.py"
    click TTS "https://github.com/aqn96/llm-conquestfour/blob/master/text_to_speech/text_to_speech.py"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000
    classDef core fill:#90EE90,stroke:#000
    classDef ai fill:#FFA500,stroke:#000
    classDef svc fill:#D3D3D3,stroke:#000
    classDef external fill:#DDA0DD,stroke:#000
```
