285 lines
6.2 KiB
Markdown
285 lines
6.2 KiB
Markdown
# Autonomous V2 Debug Guide
|
||
|
||
Quick reference for debugging the Autonomous V2 decision system.
|
||
|
||
---
|
||
|
||
## 🔧 Enable Debug Mode
|
||
|
||
### Option 1: Environment Variable (Persistent)
|
||
|
||
Add to your `.env` file or `docker-compose.yml`:
|
||
|
||
```bash
|
||
AUTONOMOUS_DEBUG=true
|
||
```
|
||
|
||
### Option 2: Terminal (Temporary)
|
||
|
||
```bash
|
||
export AUTONOMOUS_DEBUG=true
|
||
python bot.py
|
||
```
|
||
|
||
### Option 3: Code (Development)
|
||
|
||
In `bot/globals.py`:
|
||
```python
|
||
AUTONOMOUS_DEBUG = True # Force enable
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 What You'll See
|
||
|
||
### Normal Mode (Debug Off)
|
||
```
|
||
🤖 [V2] Autonomous engine decided to: join_conversation for server 123456
|
||
✅ [V2] Autonomous tick queued for server 123456
|
||
```
|
||
|
||
### Debug Mode (Debug On)
|
||
```
|
||
🔍 [V2 Debug] Decision Check for Guild 123456
|
||
Mood: bubbly (energy=0.90, sociability=0.95, impulsiveness=0.80)
|
||
Momentum: 0.75
|
||
Messages (5min/1hr): 15/42
|
||
Messages since appearance: 8
|
||
Time since last action: 450s
|
||
Active activities: 2
|
||
|
||
[Join Conv] momentum=0.75 > 0.63? True
|
||
[Join Conv] messages=8 >= 5? True
|
||
[Join Conv] cooldown=450s > 300s? True
|
||
[Join Conv] impulsive roll? True | Result: True
|
||
|
||
✅ [V2 Debug] DECISION: join_conversation
|
||
|
||
🤖 [V2] Autonomous engine decided to: join_conversation for server 123456
|
||
✅ [V2] Autonomous tick queued for server 123456
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 Understanding the Output
|
||
|
||
### Decision Types Checked (in order)
|
||
|
||
1. **[Join Conv]** - High momentum conversation
|
||
- Shows: momentum threshold, message count, cooldown, impulsiveness roll
|
||
|
||
2. **[Engage]** - User started new activity
|
||
- Shows: active activities list, cooldown, sociability × impulsiveness threshold
|
||
|
||
3. **[FOMO]** - Lots of messages without Miku
|
||
- Shows: message count vs threshold, momentum, cooldown
|
||
|
||
4. **[Silence]** - Break long silence
|
||
- Shows: messages last hour, time threshold, energy roll
|
||
|
||
5. **[Share]** - Share tweet/content
|
||
- Shows: quiet check, cooldown, energy threshold, mood appropriateness
|
||
|
||
### Context Signals
|
||
|
||
```
|
||
Mood: bubbly (energy=0.90, sociability=0.95, impulsiveness=0.80)
|
||
```
|
||
- Current mood and personality profile values
|
||
|
||
```
|
||
Momentum: 0.75
|
||
```
|
||
- Conversation momentum (0-1 scale)
|
||
- Higher = more active chat
|
||
|
||
```
|
||
Messages (5min/1hr): 15/42
|
||
```
|
||
- Recent activity levels
|
||
- First number: last 5 minutes
|
||
- Second number: last hour
|
||
|
||
```
|
||
Messages since appearance: 8
|
||
```
|
||
- How many messages since Miku last spoke
|
||
- Capped at 100 to prevent FOMO spam
|
||
|
||
```
|
||
Time since last action: 450s
|
||
```
|
||
- Seconds since Miku's last autonomous action
|
||
- Used for cooldown checks
|
||
|
||
```
|
||
Active activities: 2
|
||
```
|
||
- Number of user activities being tracked
|
||
- Max 5, auto-expire after 1 hour
|
||
|
||
---
|
||
|
||
## 🐛 Common Debugging Scenarios
|
||
|
||
### "Why isn't Miku joining the conversation?"
|
||
|
||
Enable debug mode and look for:
|
||
```
|
||
[Join Conv] momentum=0.45 > 0.63? False
|
||
```
|
||
- Momentum too low for current mood
|
||
- Try waiting for more messages or changing to more social mood
|
||
|
||
### "Why is Miku so chatty?"
|
||
|
||
Check the mood:
|
||
```
|
||
Mood: excited (energy=0.95, sociability=0.90, impulsiveness=0.90)
|
||
```
|
||
- High sociability = lower thresholds = more likely to act
|
||
- Change to "shy" or "serious" for less activity
|
||
|
||
### "Why isn't Miku reacting to user activities?"
|
||
|
||
Look for:
|
||
```
|
||
Active activities: 0
|
||
```
|
||
- No activities being tracked
|
||
- Check that presence intents are enabled
|
||
- Verify users are actually starting games/activities
|
||
|
||
### "Miku isn't breaking silence"
|
||
|
||
Check:
|
||
```
|
||
[Silence] msgs_last_hour=42 < 5? False
|
||
```
|
||
- Channel isn't quiet enough
|
||
- Energy roll might have failed (random)
|
||
|
||
### "No actions happening at all"
|
||
|
||
Check:
|
||
```
|
||
💤 [V2 Debug] Mood is 'asleep' - no action taken
|
||
```
|
||
- Miku is asleep! Change mood to wake her up
|
||
|
||
---
|
||
|
||
## 📈 Monitoring Tips
|
||
|
||
### Watch for Decay Task
|
||
Every 15 minutes you should see:
|
||
```
|
||
🧹 [V2] Decay task completed (iteration #4, uptime: 1.0h)
|
||
└─ Processed 3 servers
|
||
```
|
||
|
||
If you don't see this, the decay task might not be running.
|
||
|
||
### Track Activity Events
|
||
When users do things:
|
||
```
|
||
👤 [V2] Username status changed: online → idle
|
||
🎮 [V2] Username started activity: Genshin Impact
|
||
```
|
||
|
||
If you never see these, presence tracking isn't working.
|
||
|
||
### Decision Frequency
|
||
In an active server, you should see decision checks:
|
||
- Every time a message is sent (but most will be "None")
|
||
- Every 10-15 minutes (scheduler tick)
|
||
|
||
---
|
||
|
||
## 🔍 Performance Impact
|
||
|
||
**Debug Mode OFF** (Production):
|
||
- Minimal overhead
|
||
- Only logs when actions are taken
|
||
- ~99% of checks are silent
|
||
|
||
**Debug Mode ON** (Development):
|
||
- Verbose logging on every decision check
|
||
- Can generate lots of output in active servers
|
||
- Useful for tuning but not for production
|
||
|
||
**Recommendation**: Only enable debug mode when actively troubleshooting.
|
||
|
||
---
|
||
|
||
## 🎛️ Tuning Thresholds
|
||
|
||
If you want to adjust behavior, edit `bot/utils/autonomous_engine.py`:
|
||
|
||
### Make Miku More Active
|
||
```python
|
||
# In _should_join_conversation
|
||
base_threshold = 0.5 # Lower from 0.6
|
||
```
|
||
|
||
### Make Miku Less Active
|
||
```python
|
||
# In _should_join_conversation
|
||
base_threshold = 0.7 # Raise from 0.6
|
||
```
|
||
|
||
### Change FOMO Sensitivity
|
||
```python
|
||
# In _should_respond_to_fomo
|
||
fomo_threshold = 30 * (2.0 - profile["sociability"]) # Raise from 25
|
||
```
|
||
|
||
### Adjust Silence Breaking
|
||
```python
|
||
# In _should_break_silence
|
||
min_silence = 2400 * (2.0 - profile["energy"]) # Raise from 1800 (30 min to 40 min)
|
||
```
|
||
|
||
**Note**: After tuning, monitor with debug mode to verify the changes work as expected.
|
||
|
||
---
|
||
|
||
## 📞 Quick Reference Commands
|
||
|
||
```bash
|
||
# Enable debug for current session
|
||
export AUTONOMOUS_DEBUG=true
|
||
|
||
# Disable debug
|
||
export AUTONOMOUS_DEBUG=false
|
||
unset AUTONOMOUS_DEBUG
|
||
|
||
# Check if debug is enabled
|
||
echo $AUTONOMOUS_DEBUG
|
||
|
||
# Watch logs in real-time
|
||
tail -f bot.log | grep "V2 Debug"
|
||
|
||
# Count decision checks in last hour
|
||
grep "Decision Check" bot.log | wc -l
|
||
|
||
# See all actions taken
|
||
grep "DECISION:" bot.log
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ Troubleshooting Checklist
|
||
|
||
- [ ] Is `AUTONOMOUS_DEBUG=true` set?
|
||
- [ ] Did you restart the bot after setting the env var?
|
||
- [ ] Are presence intents enabled in `globals.py`?
|
||
- [ ] Is the bot actually receiving messages?
|
||
- [ ] Is the mood set to something other than "asleep"?
|
||
- [ ] Is the decay task running (check logs every 15 min)?
|
||
- [ ] Are there actually users in the server to track?
|
||
|
||
---
|
||
|
||
**Happy debugging! With debug mode enabled, you'll have full visibility into every decision the autonomous system makes.** 🔍✨
|