miku-discord/readmes/AUTONOMOUS_V2_MIGRATION.md

# Autonomous V2 Migration Guide

## 🎯 Overview

The V2 autonomous system replaces **scheduled randomness** with **context-aware decision making**.

### Current System (V1)
- ❌ Timer fires every 15 minutes
- ❌ 10% random chance to act
- ❌ No awareness of what's happening in the channel
- ❌ Can speak when no one is around or interrupt active conversations awkwardly

### New System (V2)
- ✅ Observes channel activity in real-time
- ✅ Makes intelligent decisions based on context signals
- ✅ Mood influences behavior (bubbly = more active, shy = less active)
- ✅ Responds to social cues (FOMO, conversation momentum, user presence)
- ✅ **Zero LLM calls for decision-making** (only for content generation)

---

## 🏗️ Architecture

### Core Components

1. **`autonomous_engine.py`** - Decision engine
   - Tracks lightweight context signals (no message content stored)
   - Calculates conversation momentum, activity levels
   - Makes decisions based on thresholds and mood profiles
   
2. **`autonomous_v2.py`** - Integration layer
   - Connects engine to existing autonomous functions
   - Provides hooks for bot events
   - Manages periodic tasks

### Decision Factors

The engine considers:
- **Activity patterns**: Message frequency in last 5 min / 1 hour
- **Conversation momentum**: How active the chat is right now
- **User events**: Status changes, new activities/games started
- **Miku's state**: Time since last action, messages since appearance
- **Mood personality**: Energy, sociability, impulsiveness levels
- **Time context**: Hour of day, weekend vs weekday

### Mood Profiles

Each mood has a personality profile:

```python
"bubbly": {
    "energy": 0.9,        # High energy = breaks silence faster
    "sociability": 0.95,  # High sociability = joins conversations more
    "impulsiveness": 0.8  # High impulsiveness = acts on signals quickly
}

"shy": {
    "energy": 0.4,        # Low energy = waits longer
    "sociability": 0.2,   # Low sociability = less likely to join
    "impulsiveness": 0.2  # Low impulsiveness = more hesitant
}
```

### Action Types & Triggers

| Action | Trigger Conditions |
|--------|-------------------|
| **Join Conversation** | High message momentum + hasn't spoken in 5+ messages + 5 min since last action + mood is impulsive |
| **Engage User** | Someone started new activity + 30 min since last action + mood is sociable |
| **FOMO Response** | 25+ messages without Miku + active conversation + 15 min since last action |
| **Break Silence** | <5 messages in last hour + long quiet period (mood-dependent) + mood is energetic |
| **Share Tweet** | <10 messages/hour + 1 hour since last action + mood is curious/excited |

---

## 🔧 Integration Steps

### Step 1: Add Event Hooks to `bot.py`

```python
# At the top with other imports
from utils.autonomous_v2 import (
    on_message_event,
    on_presence_update,
    on_member_join,
    initialize_v2_system
)

# In on_ready event
@client.event
async def on_ready():
    # ... existing code ...
    
    # Initialize V2 system
    initialize_v2_system(client)

# In on_message event
@client.event
async def on_message(message):
    # ... existing code ...
    
    # Track message for autonomous engine (non-blocking)
    on_message_event(message)
    
    # ... rest of message handling ...

# Add new event handlers
@client.event
async def on_presence_update(member, before, after):
    """Track user presence changes for autonomous decisions"""
    on_presence_update(member, before, after)

@client.event
async def on_member_join(member):
    """Track member joins for autonomous decisions"""
    on_member_join(member)
```

### Step 2: Update Server Manager Scheduler

Replace random autonomous tick with V2 tick:

```python
# In server_manager.py - _run_autonomous_for_server method

def _run_autonomous_for_server(self, guild_id: int, client: discord.Client):
    """Run autonomous behavior for a specific server - called by APScheduler"""
    try:
        # NEW: Use V2 system
        from utils.autonomous_v2 import autonomous_tick_v2
        
        if client.loop and client.loop.is_running():
            client.loop.create_task(autonomous_tick_v2(guild_id))
            print(f"✅ [V2] Autonomous tick queued for server {guild_id}")
        else:
            print(f"⚠️ Client loop not available for autonomous tick in server {guild_id}")
    except Exception as e:
        print(f"⚠️ Error in autonomous tick for server {guild_id}: {e}")
```

### Step 3: Hook Mood Changes

Update mood change functions to notify the engine:

```python
# In utils/moods.py - rotate_server_mood function

async def rotate_server_mood(guild_id: int):
    # ... existing code ...
    
    server_manager.set_server_mood(guild_id, new_mood_name, load_mood_description(new_mood_name))
    
    # NEW: Notify autonomous engine
    from utils.autonomous_v2 import on_mood_change
    on_mood_change(guild_id, new_mood_name)
    
    # ... rest of function ...
```

### Step 4: Optional - Adjust Scheduler Interval

Since V2 makes smarter decisions, you can check more frequently:

```python
# In server_manager.py - setup_server_scheduler

# Change from 15 minutes to 10 minutes (or keep at 15)
scheduler.add_job(
    self._run_autonomous_for_server,
    IntervalTrigger(minutes=10),  # More frequent checks, but smarter decisions
    args=[guild_id, client],
    id=f"autonomous_{guild_id}"
)
```

---

## 📊 Benefits

### Resource Efficiency
- **No polling**: Only acts when events occur or thresholds are met
- **Lightweight tracking**: No message content stored, just timestamps and counters
- **LLM only for content**: Decision-making uses simple math, not AI

### Better User Experience
- **Context-aware**: Won't interrupt active conversations or speak to empty rooms
- **Mood-consistent**: Bubbly Miku is chatty, shy Miku is reserved
- **Natural timing**: Responds to social cues like a real person would

### Example Scenarios

**Scenario 1: Active Conversation**
```
[User A]: Did you see the new Miku concert?
[User B]: Yeah! The hologram tech was insane!
[User C]: I wish I was there...
[Engine detects: High momentum (3 messages/min), 15 messages since Miku appeared]
→ Miku joins: "Ehh?! You went to my concert? Tell me everything! 🎤✨"
```

**Scenario 2: Someone Starts Gaming**
```
[Discord shows: User D started playing "Project DIVA Mega Mix"]
[Engine detects: New activity related to Miku, 45 min since last action]
→ Miku engages: "Ooh, someone's playing Project DIVA! 🎮 What's your high score? 😊"
```

**Scenario 3: Dead Chat**
```
[No messages for 2 hours, Miku is in "bubbly" mood]
[Engine detects: Low activity, high energy mood, 2 hours since last action]
→ Miku breaks silence: "Is anyone here? I'm bored~ 🫧"
```

**Scenario 4: Shy Mood, Active Chat**
```
[Very active conversation, Miku is in "shy" mood]
[Engine detects: High momentum but low sociability score]
→ Miku waits longer, only joins after 40+ messages
→ "Um... can I join too? 👉👈"
```

---

## 🧪 Testing

### Test the Engine Directly

```python
# In Python console or test file
from utils.autonomous_engine import autonomous_engine

# Simulate activity
guild_id = 123456789
autonomous_engine.track_message(guild_id, author_is_bot=False)
autonomous_engine.track_message(guild_id, author_is_bot=False)
autonomous_engine.update_mood(guild_id, "bubbly")

# Check decision
action = autonomous_engine.should_take_action(guild_id)
print(f"Decision: {action}")
```

### Monitor Decisions

Add debug logging to see why decisions are made:

```python
# In autonomous_engine.py - should_take_action method

if action_type := self._should_join_conversation(ctx, profile):
    print(f"🎯 [DEBUG] Join conversation triggered:")
    print(f"  - Momentum: {ctx.conversation_momentum:.2f}")
    print(f"  - Messages since appearance: {ctx.messages_since_last_appearance}")
    return "join_conversation"
```

---

## 🔄 Rollback Plan

If V2 has issues, easily revert:

1. Comment out V2 hooks in `bot.py`
2. Restore original scheduler code in `server_manager.py`
3. No data loss - V1 system remains intact

---

## 🚀 Future Enhancements

Possible additions to make it even smarter:

1. **Topic detection**: Track what people are talking about (without storing content)
2. **User affinity**: Remember who Miku has interacted with recently
3. **Time-of-day patterns**: Learn peak activity times per server
4. **Sentiment signals**: Track if chat is happy/sad/angry without reading messages
5. **Cross-server learning**: Share patterns between servers (opt-in)

---

## 📝 Summary

The V2 system transforms Miku from a **random timer** into a **context-aware participant** that:
- Observes channel dynamics
- Responds to social cues
- Respects her current mood
- Uses resources efficiently

**No constant LLM polling** - just smart, lightweight context tracking! 🧠✨