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)

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

4. 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:

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

Replace the placeholder values with your actual keys and tokens.

Quick Start Guide

1. Populate .env

nano .env
# Add your DISCORD_BOT_TOKEN

2. (Optional) Customize config.yaml

nano config.yaml
# Adjust service URLs, model names, timeouts as needed

3. Build and Start the Bot

docker compose build miku-bot
docker compose up -d

4. Check Bot Status

docker compose logs -f miku-bot

5. Access Web UI

Open http://localhost:3939 in your browser

6. Test Configuration

# 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

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

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

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

Modified ✅

• docker-compose.yml - Removed hardcoded token, added .env/config mounts
• bot/requirements.txt - Added pydantic dependencies
• bot/Dockerfile - Added config.py to build
• .gitignore - Enhanced for security
• bot/bot.py - Imported config system
• 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
• Web UI Analysis: CONFIG_SOURCES_ANALYSIS.md
• System Summary: CONFIG_SYSTEM_COMPLETE.md
• Migration Tracker: 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