miku-discord/WEB_UI_INTEGRATION_COMPLETE.md

# Web UI Configuration Integration - Complete

## Summary

Successfully integrated the bot Web UI (port 3939) with the unified configuration system. All Web UI changes now persist to `config_runtime.yaml` and are restored on bot restart.

## What Was Changed

### 1. API Endpoints Updated for Persistence

All Web UI endpoints now persist changes via `config_manager`:

#### Mood Management
- **POST** `/mood` - Set DM mood → persists to `runtime.mood.dm_mood`
- **POST** `/mood/reset` - Reset to neutral → persists to `runtime.mood.dm_mood`
- **POST** `/mood/calm` - Calm down → persists to `runtime.mood.dm_mood`

#### GPU Selection
- **POST** `/gpu-select` - Switch GPU → persists to `runtime.gpu.current_gpu`

#### Bipolar Mode
- **POST** `/bipolar-mode/enable` - Enable bipolar → persists to `runtime.bipolar_mode.enabled`
- **POST** `/bipolar-mode/disable` - Disable bipolar → persists to `runtime.bipolar_mode.enabled`

#### Language Mode
- **POST** `/language/toggle` - Toggle English/Japanese → persists to `discord.language_mode`

### 2. Configuration Priority System

The unified system handles three configuration sources:

1. **Runtime Overrides** (`config_runtime.yaml`) - Web UI changes, highest priority
2. **Static Configuration** (`config.yaml`) - Default values, second priority
3. **Hardcoded Defaults** - Fallback values, lowest priority

When Web UI changes a setting:
- Value is saved to `config_runtime.yaml`
- Priority system ensures Web UI value is always used (overrides static config)
- Setting persists across bot restarts
- Can be reset to defaults via `/config/reset` endpoint

### 3. Configuration Management API

New endpoints for configuration management:

- **GET** `/config` - Full configuration (static + runtime + state)
- **GET** `/config/static` - Static configuration only
- **GET** `/config/runtime` - Runtime overrides only
- **POST** `/config/set` - Set any configuration value with persistence
- **POST** `/config/reset` - Reset to defaults
- **POST** `/config/validate` - Validate current configuration
- **GET** `/config/state` - Runtime state (mood, evil mode, etc.)

## Configuration Files Created

### `.env` (Required - Contains Secrets)
```bash
DISCORD_BOT_TOKEN=your_discord_bot_token_here
CHESHIRE_CAT_API_KEY=your_cheshire_cat_api_key_here
ERROR_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN
OWNER_USER_ID=209381657369772032
```

### `config.yaml` (Static Configuration)
Contains all default settings that are safe to commit to git:
- Service URLs (llama-swap, cheshire-cat, etc.)
- Model names (text, vision, evil, japanese)
- Discord settings (language_mode, api_port, timeout)
- Timeouts and feature flags

### `config_runtime.yaml` (Runtime Overrides)
Created automatically when Web UI changes settings:
- Mood selections
- Language mode changes
- GPU selection
- Bipolar mode state
- Server-specific configurations

**IMPORTANT**: `config_runtime.yaml` is in `.gitignore` and should NOT be committed

## What Settings Are Configured by Web UI

From `CONFIG_SOURCES_ANALYSIS.md`:

### Bot Web UI (port 3939)
- **Mood Selection**: Normal, happy, sad, angry, excited, shy, playful, sleepy
- **Language Mode**: English / Japanese
- **GPU Selection**: NVIDIA / AMD
- **Evil Mode**: Enable/Disable evil personality
- **Evil Mood**: Darkidol, possessed, obsessed, manic, depressed
- **Bipolar Mode**: Enable/Disable bipolar personality
- **Server Configurations**: Autonomous channel, bedtime channels, moods per server
- **Bedtime Range**: Start/end times per server
- **Log Configuration**: View/download logs

### Static config.yaml Settings
- Service endpoints and URLs
- Model names and versions
- Timeouts (request, response, voice)
- Feature flags (pfp_context, evil_mode, autonomous_mode)
- Debug modes
- Port numbers
- Log levels

## .env Population Status

✅ **Setup Complete**: `.env` file created from `.env.example`

⚠️ **ACTION REQUIRED**: You need to populate `.env` with your actual values:

### Required Values
1. **DISCORD_BOT_TOKEN** - Your Discord bot token
   - Get from: https://discord.com/developers/applications
   - Create a bot application → Bot → Create Bot → Copy Token

### Optional Values
2. **CHESHIRE_CAT_API_KEY** - Cheshire Cat API key (if using auth)
   - Leave empty if no authentication
   - Usually not needed for local deployments

3. **ERROR_WEBHOOK_URL** - Discord webhook for error reporting
   - Create webhook in your Discord server
   - Used to send error notifications
   - Leave empty to disable

5. **OWNER_USER_ID** - Your Discord user ID for admin features
   - Default: `209381657369772032` (already set)
   - Your Discord ID (not bot ID)
   - Required for admin commands

## How to Populate .env

Edit `.env` file in your project root:

```bash
nano /home/koko210Serve/docker/miku-discord/.env
```

Replace the placeholder values with your actual keys and tokens.

## Quick Start Guide

### 1. Populate .env
```bash
nano .env
# Add your DISCORD_BOT_TOKEN
```

### 2. (Optional) Customize config.yaml
```bash
nano config.yaml
# Adjust service URLs, model names, timeouts as needed
```

### 3. Build and Start the Bot
```bash
docker compose build miku-bot
docker compose up -d
```

### 4. Check Bot Status
```bash
docker compose logs -f miku-bot
```

### 5. Access Web UI
Open http://localhost:3939 in your browser

### 6. Test Configuration
```bash
# Test GET /config
curl http://localhost:3939/config

# Test setting a value
curl -X POST http://localhost:3939/config/set \
  -H "Content-Type: application/json" \
  -d '{"key_path": "discord.language_mode", "value": "japanese"}'
```

## Configuration System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    Web UI (port 3939)                       │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │  Mood Set   │  │ GPU Select   │  │  Language Toggle │   │
│  │  /mood      │  │ /gpu-select  │  │ /language/toggle │   │
│  └──────┬──────┘  └──────┬───────┘  └────────┬─────────┘   │
│         │                │                    │              │
│         ▼                ▼                    ▼              │
│         └────────────────┴────────────────────┘              │
│                            │                                 │
│                            ▼                                 │
└───────────────────────────┼─────────────────────────────────┘
                            │
                    ┌───────▼────────┐
                    │  bot/api.py    │
                    │  FastAPI Endpoints  │
                    └───────┬────────┘
                            │
                    ┌───────▼──────────────────────────┐
                    │  bot/config_manager.py            │
                    │  - Priority system                │
                    │  - Runtime config storage         │
                    │  - Persistence layer              │
                    └───────┬──────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
┌───────────────┐  ┌────────────────┐  ┌──────────────────┐
│ .env          │  │ config.yaml    │  │ config_runtime.  │
│ (secrets)     │  │ (static)       │  │ yaml (runtime)   │
├───────────────┤  ├────────────────┤  ├──────────────────┤
│ Discord Token │  │ Service URLs   │  │ Mood settings    │
│ Fish API Key  │  │ Model names    │  │ GPU selection    │
│ Owner ID      │  │ Timeouts       │  │ Language mode    │
└───────────────┘  └────────────────┘  │ Bipolar mode     │
                                       └──────────────────┘
```

## Priority System Example

```python
# Static config.yaml:
discord:
  language_mode: "english"

# User changes via Web UI to Japanese
# → Saves to config_runtime.yaml:
runtime:
  discord:
    language_mode: "japanese"

# Bot reads config:
# Priority 1: config_runtime.yaml → "japanese" ✅ (USED)
# Priority 2: config.yaml → "english" (override, not used)
# Priority 3: Hardcoded → "english" (fallback, not used)

# If user resets to defaults:
# → config_runtime.yaml cleared
# → Falls back to config.yaml: "english"
```

## Backward Compatibility

All existing code continues to work:

```python
# Old way (still works)
from bot.globals import LANGUAGE_MODE
print(LANGUAGE_MODE)  # Reads from config with runtime override

# New way (recommended)
from bot.config_manager import config_manager
mode = config_manager.get("discord.language_mode", "english")
print(mode)
```

## File Status

### Created ✅
- [x] `.env.example` - Secrets template
- [x] `.env` - Your environment file (just created)
- [x] `config.yaml` - Static configuration
- [x] `bot/config.py` - Configuration loader
- [x] `bot/config_manager.py` - Unified config manager
- [x] `setup.sh` - Setup script (executed)
- [x] `CONFIG_README.md` - Configuration guide
- [x] `CONFIG_SOURCES_ANALYSIS.md` - Web UI analysis
- [x] `CONFIG_SYSTEM_COMPLETE.md` - Implementation summary
- [x] `WEB_UI_INTEGRATION_COMPLETE.md` - This document

### Modified ✅
- [x] `docker-compose.yml` - Removed hardcoded token, added .env/config mounts
- [x] `bot/requirements.txt` - Added pydantic dependencies
- [x] `bot/Dockerfile` - Added config.py to build
- [x] `.gitignore` - Enhanced for security
- [x] `bot/bot.py` - Imported config system
- [x] `bot/api.py` - Added config endpoints, updated Web UI persistence

### Pending ⏳
- [ ] Populate `.env` with your actual API keys and tokens
- [ ] Test configuration validation
- [ ] Test unified config system with Docker

## Troubleshooting

### Bot won't start - Missing secrets
```
Error: DISCORD_BOT_TOKEN not set
```
**Solution**: Populate `.env` with required values

### Web UI changes not persisting
```
Changes reset after restart
```
**Solution**: Check that `config_runtime.yaml` is being created in bot directory

### Can't access configuration endpoints
```
404 Not Found /config
```
**Solution**: Restart bot after updating api.py

### Priority system not working
```
Web UI changes ignored
```
**Solution**: Ensure `config_manager.set()` is called with `persist=True`

## Next Steps

### Immediate (Required)
1. ✅ Run `./setup.sh` - **DONE**
2. ⚠️ Populate `.env` with your actual values
3. ⚠️ Validate configuration via `/config/validate` endpoint
4. ⚠️ Test bot startup

### Recommended (Optional)
5. Customize `config.yaml` for your environment
6. Test Web UI persistence by changing settings and restarting bot
7. Review `CONFIG_README.md` for advanced configuration options

### Future Enhancements (Optional)
8. Update Web UI (bot/static/index.html) to display config.yaml values
9. Add configuration export/import feature
10. Implement configuration validation UI

## Documentation

- **Configuration Guide**: [CONFIG_README.md](CONFIG_README.md)
- **Web UI Analysis**: [CONFIG_SOURCES_ANALYSIS.md](CONFIG_SOURCES_ANALYSIS.md)
- **System Summary**: [CONFIG_SYSTEM_COMPLETE.md](CONFIG_SYSTEM_COMPLETE.md)
- **Migration Tracker**: [MIGRATION_CHECKLIST.md](MIGRATION_CHECKLIST.md)

## Support

If you encounter issues:
1. Check bot logs: `docker compose logs -f miku-bot`
2. Validate configuration: `curl http://localhost:3939/config/validate`
3. Review documentation in `CONFIG_README.md`
4. Check `.env` file for required values

---

**Status**: ✅ Web UI Integration Complete  
**Setup**: ✅ .env Created  
**Next Step**: ⚠️ Populate .env with actual API keys and tokens