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)
```yaml
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)
```yaml
# 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)
```json
{
  "current_gpu": "amd",
  "last_updated": "2026-02-15T10:30:00"
}
```

### **memory/servers_config.json** (Per-server settings)
```json
{
  "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