Organize documentation: Move all .md files to readmes/ directory
This commit is contained in:
290
readmes/AUTONOMOUS_V2_MIGRATION.md
Normal file
290
readmes/AUTONOMOUS_V2_MIGRATION.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# 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! 🧠✨
|
||||
Reference in New Issue
Block a user