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:

"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

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

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

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

# 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

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

# 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! 🧠✨