miku-discord/readmes/CONFIG_SOURCES_ANALYSIS.md

📊 Configuration Sources Analysis

🎯 Configuration Sources Identified

Bot Web UI (bot/static/index.html)

Settings that can be changed via the web UI:

Setting	API Endpoint	Storage	Runtime Variable
DM Mood	GET/POST /mood	globals.DM_MOOD	Runtime only
Language Mode	GET/POST /language/toggle	globals.LANGUAGE_MODE	Runtime only
Evil Mode	GET/POST /evil-mode	globals.EVIL_MODE	Runtime only
GPU Selection	GET/POST /gpu-select	memory/gpu_state.json	JSON file
Server Mood	GET/POST /servers/{guild_id}/mood	server_manager.servers	servers_config.json
Autonomous Channel	POST /servers/{guild_id}/autonomous-channel	server_manager.servers	servers_config.json
Bedtime Range	POST /servers/{guild_id}/bedtime-range	server_manager.servers	servers_config.json
Bipolar Mode	POST /bipolar-mode/toggle	globals.BIPOLAR_MODE	Runtime only
Log Configuration	GET/POST /api/log/config	memory/log_config.json	JSON file

config.yaml (Static Configuration)

Settings that SHOULD be in config.yaml:

Setting	Current Location	Should Be
Service URLs	config.yaml ✓	config.yaml ✓
Model Names	config.yaml ✓	config.yaml ✓
Language Mode	config.yaml	Both! (config default, UI override)
GPU Preference	config.yaml	Both! (config default, UI override)
Debug Modes	config.yaml	config.yaml ✓
Timeouts	config.yaml	config.yaml ✓
Port Numbers	config.yaml	config.yaml ✓

Cheshire Cat UI (Port 1865)

Settings managed via Cheshire Cat web interface:

• Personality prompts
• Plugin configurations
• Memory settings
• Tool settings

---

🔄 Priority Hierarchy

1. Web UI Changes (highest priority)
   ↓
2. Runtime State (globals.py)
   ↓
3. JSON Files (memory/*)
   ↓
4. config.yaml (default values)
   ↓
5. Hardcoded defaults (fallback)

---

⚠️ Problem Identified

Current Issues:

1. Runtime-only changes - Web UI changes don't persist across restarts (except GPU state)
2. No sync between sources - config.yaml and web UI are disconnected
3. Inconsistent storage - Some in JSON, some in memory, some hardcoded
4. No configuration versioning - Can't tell if config is out of sync

What We Need:

1. Unified config manager - Single source of truth
2. Persistence layer - Web UI changes saved to config
3. Priority system - Web UI > config > defaults
4. Sync mechanism - Reload config when changed
5. API for config management - Read/write config from anywhere

---

🎯 Solution Design

Hybrid Configuration System

┌─────────────────────────────────────────────┐
│          config.yaml (Defaults)            │
│    - Static configuration values            │
│    - Default settings                     │
│    - Safe to commit to git               │
└──────────────┬──────────────────────────┘
               │
               │ Loaded at startup
               ↓
┌─────────────────────────────────────────────┐
│       Runtime Configuration (Active)       │
│    - Can be modified via Web UI          │
│    - Can be modified via API             │
│    - Can be modified via CLI             │
└──────┬────────────────────┬─────────────┘
       │                    │
       │                    │
       ↓                    ↓
┌─────────────┐      ┌─────────────┐
│  Web UI     │      │   CLI/API   │
│  Changes    │      │   Changes   │
└──────┬──────┘      └──────┬──────┘
       │                    │
       │                    │
       ↓                    ↓
┌─────────────────────────────────────────────┐
│      config_runtime.yaml (Optional)        │
│    - Overrides config.yaml                │
│    - Only contains changed values         │
│    - Auto-generated                     │
│    - DO NOT commit to git               │
└──────────────┬──────────────────────────┘
               │
               │ Optional persistence
               ↓
┌─────────────────────────────────────────────┐
│          Reverted to config.yaml          │
│    (on next restart if no overrides)     │
└─────────────────────────────────────────────┘

---

📝 Implementation Plan

Phase 1: Create Config Manager

• Create bot/config_manager.py
• Implement unified loading (config.yaml + overrides)
• Implement persistence (save runtime changes)
• Implement priority system

Phase 2: Update API Endpoints

• Add GET/POST /config endpoint
• Update existing endpoints to use config_manager
• Save runtime changes to config_runtime.yaml

Phase 3: Update Web UI

• Add "System Settings" tab
• Display current config values
• Allow editing of config.yaml values
• Add "Reset to Defaults" button

Phase 4: Testing

• Test config loading
• Test Web UI changes
• Test persistence
• Test config reload

---

🔧 Configuration Categories

Static (config.yaml only)

• Service URLs
• Port numbers
• Timeout values
• File paths
• GPU device IDs

Hybrid (config default + UI override)

• Language mode
• GPU preference
• Debug modes
• Model names (some)

Dynamic (Web UI only)

• Mood (DM and per-server)
• Evil mode
• Bipolar mode
• Server-specific settings (autonomous channel, bedtime)
• Autonomous features

External (Cheshire Cat UI)

• Personality settings
• Plugin configurations
• Memory settings

---

📊 Configuration File Structure

config.yaml (Defaults, committed)

discord:
  language_mode: english  # Default, can be overridden by UI
  api_port: 3939

gpu:
  prefer_amd: false  # Default, can be overridden by UI
  amd_models_enabled: true

models:
  text: llama3.1
  vision: vision
  evil: darkidol
  japanese: swallow

# ... etc

config_runtime.yaml (Overrides, not committed)

# Auto-generated file - do not edit manually
# Contains values changed via Web UI that should persist across restarts

discord:
  language_mode: japanese  # Overridden by Web UI

gpu:
  prefer_amd: true  # Overridden by Web UI

# ... only changed values

memory/gpu_state.json (Current GPU)

{
  "current_gpu": "amd",
  "last_updated": "2026-02-15T10:30:00"
}

memory/servers_config.json (Per-server settings)

{
  "123456789": {
    "mood": "bubbly",
    "autonomous_channel_id": 987654321,
    "bedtime_hour": 22,
    "bedtime_minute": 0
  }
  // ... per-server settings
}

---

🎯 Next Steps

1. Create bot/config_manager.py - Unified configuration manager
2. Update bot/config.py - Integrate config_manager
3. Add /config API endpoints - Read/write config
4. Update Web UI - Add config management tab
5. Test - Verify all configuration paths work correctly