storyteller/docs/planning/MVP_ROADMAP.md

# 🎯 Storyteller RPG - MVP Roadmap

**Goal:** Create a functional multi-user RPG system with human and AI players/storytellers, character profiles, and basic game management.

---

## 📊 Current Status

**✅ Completed:**
- Basic storyteller-player communication
- WebSocket real-time messaging
- Multiple LLM support (OpenAI + OpenRouter)
- Character-specific AI models
- Private character-storyteller conversations

**🔄 In Progress:**
- Enhanced user modes and permissions

---

## 🎯 MVP Feature Set

### Core User Modes

#### 1. **Player Mode** (Human & AI)
**Capabilities:**
- ✅ Create character with profile (race, class, gender, personality)
- ✅ Send messages to storyteller (public & private actions)
- ✅ Generate AI-assisted responses with custom prompts
- ✅ Edit/write custom messages before sending
- ✅ View storyteller responses and scene narrations
- ❌ Cannot edit storyteller responses
- ✅ Import/export character profiles (JSON & PNG with metadata)

**Message Types:**
1. **Public Action** - Visible to all players and storyteller
   - Example: "I shake hands with the merchant"
2. **Private Action** - Only visible to storyteller
   - Example: "I attempt to pickpocket him while shaking hands"
3. **Mixed Message** - Contains both public and private components

#### 2. **Storyteller Mode** (Human & AI)
**Capabilities:**
- ✅ View all player messages (public + private)
- ✅ Generate/edit responses to individual players
- ✅ Broadcast scene narrations to all players
- ✅ Control AI player responses
- ❌ Cannot edit human player messages
- ✅ Choose storytelling style (Narrator/DM/Internal)
- ✅ Set storyteller personality

**AI Storyteller:**
- Automatically generates responses to player actions
- Uses scenario/plot context to drive story
- Responds to all players based on their actions
- Can be overridden by Gamemaster

#### 3. **Gamemaster Mode** (Human Only)
**Capabilities:**
- ✅ Create and configure games
- ✅ Set player slots (human or AI)
- ✅ Assign storyteller (human or AI)
- ✅ View all game messages and state
- ✅ Send messages to any player/storyteller
- ✅ Edit AI responses (players and storyteller)
- ❌ Cannot edit human responses
- ✅ Direct commands to AI storyteller (via special channel)
- ✅ Save/load game progress

#### 4. **Admin Mode** (Development Only)
**Capabilities:**
- ✅ Full access to all games
- ✅ Edit any message or setting
- ✅ Manage LLM configuration
- ✅ View cost/usage analytics
- ✅ Debug mode features

---

## 🎭 Character Profile System (MVP)

### Character Creation Fields

```json
{
  "name": "string",
  "gender": "Male|Female|Non-binary|Custom",
  "race": "Human|Elf|Dwarf|Orc|Halfling",
  "class": "Warrior|Wizard|Cleric|Archer|Rogue",
  "personality": "Friendly|Serious|Doubtful|Measured",
  "llm_model": "string",
  "custom_prompts": {
    "character_background": "string",
    "response_style": "string",
    "special_traits": "string"
  },
  "appearance": {
    "avatar": "base64_image_data",
    "description": "string"
  }
}
```

### Race Profiles (MVP)

#### **Human**
- **Traits:** Versatile, adaptable
- **LLM Prompt:** "You are a human character, balanced and adaptable to any situation."

#### **Elf**
- **Traits:** Graceful, perceptive, long-lived
- **LLM Prompt:** "You are an elf, graceful and wise with centuries of experience and keen senses."

#### **Dwarf**
- **Traits:** Sturdy, loyal, craftsman
- **LLM Prompt:** "You are a dwarf, stout and honorable with deep knowledge of stone and metal."

#### **Orc**
- **Traits:** Strong, fierce, honorable
- **LLM Prompt:** "You are an orc, powerful and direct with a strong sense of honor and combat."

#### **Halfling**
- **Traits:** Nimble, lucky, cheerful
- **LLM Prompt:** "You are a halfling, small but brave with natural luck and a cheerful disposition."

### Class Profiles (MVP)

#### **Warrior**
- **Focus:** Physical combat, leadership
- **Prompt:** "You excel in combat and tactics, preferring direct action and protecting your allies."

#### **Wizard**
- **Focus:** Arcane knowledge, spellcasting
- **Prompt:** "You are a master of arcane arts, solving problems with magic and knowledge."

#### **Cleric**
- **Focus:** Divine magic, healing, support
- **Prompt:** "You channel divine power to heal and protect, guided by faith and compassion."

#### **Archer**
- **Focus:** Ranged combat, precision, scouting
- **Prompt:** "You are a skilled marksman, preferring distance and precision in combat."

#### **Rogue**
- **Focus:** Stealth, cunning, skills
- **Prompt:** "You rely on stealth and cunning, using tricks and skills to overcome obstacles."

### Personality Profiles (MVP)

#### **Friendly**
- **Behavior:** Optimistic, trusting, cooperative
- **Prompt Modifier:** "You are friendly and approachable, always looking for the good in others."

#### **Serious**
- **Behavior:** Focused, pragmatic, disciplined
- **Prompt Modifier:** "You are serious and focused, prioritizing efficiency and practical solutions."

#### **Doubtful**
- **Behavior:** Cautious, questioning, analytical
- **Prompt Modifier:** "You are cautious and skeptical, questioning motives and analyzing situations carefully."

#### **Measured**
- **Behavior:** Balanced, thoughtful, diplomatic
- **Prompt Modifier:** "You are measured and thoughtful, weighing options carefully before acting."

### Character Import/Export

#### **JSON Export**
```json
{
  "version": "1.0",
  "character": { /* full character data */ },
  "created_at": "2025-01-11T00:00:00Z",
  "game_history": [ /* optional */ ]
}
```

#### **PNG Export with Metadata**
- Character avatar/portrait as PNG image
- Character data embedded in PNG metadata (EXIF/custom chunks)
- Allows sharing characters visually
- Import by uploading PNG file

**Libraries Needed:**
- Frontend: `exif-js`, `png-metadata`
- Backend: `Pillow` (Python) for PNG metadata

---

## 📜 Storyteller System (MVP)

### Storyteller Styles

#### **Narrator (3rd Person)**
```
Example: "The warrior steps forward, hand extended toward the merchant. 
The shopkeeper's eyes gleam with suspicion as something feels amiss..."
```
**Prompt:** "Narrate the scene in third person, describing actions and atmosphere objectively."

#### **DM/Game Master (2nd Person)**
```
Example: "You step forward and shake the merchant's hand. As you do, 
you notice his purse hanging loosely from his belt..."
```
**Prompt:** "Address players directly in second person, as a dungeon master guiding their experience."

#### **Internal Thoughts (1st Person)**
```
Example: "I watch as the warrior approaches. Something about his 
movements seems off... Is he trying to distract me?"
```
**Prompt:** "Describe scenes from the perspective of NPCs or environment, revealing inner thoughts."

### Storyteller Personalities (MVP)

#### **Neutral**
- **Behavior:** Unbiased, balanced narration
- **Prompt:** "Narrate events fairly without favoring players or NPCs. Be descriptive but neutral."

*(Future: Add Challenging, Supportive, Mysterious personalities)*

---

## 🛠️ MVP Implementation Plan

### Phase 1: Enhanced Message System (Week 1-2)

**Tasks:**
1. **Public/Private Message Types**
   - [ ] Update `Message` model to include `visibility` field (public/private/mixed)
   - [ ] Frontend UI for selecting message visibility
   - [ ] Filter messages based on user role/permissions
   - [ ] WebSocket handling for different message types

2. **Message Composer Enhancement**
   - [ ] Tabbed interface: Public Action | Private Action | Mixed
   - [ ] Visual indicators for message type
   - [ ] Preview of what each role sees
   - [ ] AI generation respects visibility settings

**Backend Changes:**
```python
class Message(BaseModel):
    id: str
    sender_id: str
    content: str
    visibility: str  # "public", "private", "mixed"
    public_content: Optional[str]  # for mixed messages
    private_content: Optional[str]  # for mixed messages
    timestamp: datetime
```

**Frontend Components:**
```jsx
<MessageComposer
  onSend={handleSend}
  visibilityOptions={['public', 'private', 'mixed']}
  aiAssist={true}
/>
```

---

### Phase 2: Character Profile System (Week 3-4)

**Tasks:**
1. **Character Profile Data Structure**
   - [ ] Extend `Character` model with profile fields
   - [ ] Profile creation wizard UI
   - [ ] Dropdown selectors for race/class/personality/gender
   - [ ] Custom prompt input fields
   - [ ] Avatar upload/selection

2. **Profile-Based LLM Prompts**
   - [ ] Build system prompt from character profile
   - [ ] Combine race + class + personality traits
   - [ ] Inject custom prompts into LLM requests
   - [ ] Store prompt templates in database

3. **Import/Export System**
   - [ ] Export character to JSON
   - [ ] Export character to PNG with embedded metadata
   - [ ] Import from JSON file
   - [ ] Import from PNG file (extract metadata)
   - [ ] Profile validation on import

**Backend Implementation:**
```python
class CharacterProfile(BaseModel):
    gender: str
    race: str  # Human, Elf, Dwarf, Orc, Halfling
    character_class: str  # Warrior, Wizard, Cleric, Archer, Rogue
    personality: str  # Friendly, Serious, Doubtful, Measured
    background: Optional[str]
    custom_prompts: Dict[str, str]
    avatar_data: Optional[str]  # base64 encoded

def build_character_prompt(profile: CharacterProfile) -> str:
    """Builds LLM system prompt from character profile"""
    race_prompt = RACE_PROMPTS[profile.race]
    class_prompt = CLASS_PROMPTS[profile.character_class]
    personality_prompt = PERSONALITY_PROMPTS[profile.personality]
    
    return f"{race_prompt} {class_prompt} {personality_prompt} {profile.custom_prompts.get('response_style', '')}"
```

**Frontend Components:**
```jsx
<CharacterCreationWizard>
  <Step1_BasicInfo />
  <Step2_RaceSelection />
  <Step3_ClassSelection />
  <Step4_Personality />
  <Step5_CustomPrompts />
  <Step6_Avatar />
  <Step7_Review />
</CharacterCreationWizard>

<CharacterImportExport 
  onExportJSON={handleJSONExport}
  onExportPNG={handlePNGExport}
  onImport={handleImport}
/>
```

---

### Phase 3: User Mode Interfaces (Week 5-7)

**Tasks:**
1. **Player Interface Refinement**
   - [ ] Character sheet display
   - [ ] Public/private message controls
   - [ ] AI generation with character context
   - [ ] Cannot edit storyteller responses (UI enforcement)

2. **Storyteller Dashboard**
   - [ ] View all messages (public + private)
   - [ ] Response composer per player
   - [ ] AI player management
   - [ ] Style selector (Narrator/DM/Internal)
   - [ ] Cannot edit human player messages

3. **Gamemaster Control Panel**
   - [ ] Game creation wizard
   - [ ] Player slot assignment (human/AI)
   - [ ] Storyteller assignment (human/AI)
   - [ ] View all game state
   - [ ] Direct AI storyteller commands
   - [ ] Edit AI responses only

4. **Permission Enforcement**
   - [ ] Backend permission decorators
   - [ ] Frontend UI disabled states
   - [ ] WebSocket message filtering
   - [ ] API endpoint protection

**Permission Matrix:**

| Action | Player | Storyteller | Gamemaster | Admin |
|--------|--------|-------------|------------|-------|
| Read own messages | ✅ | ✅ | ✅ | ✅ |
| Read other players (public) | ✅ | ✅ | ✅ | ✅ |
| Read other players (private) | ❌ | ✅ | ✅ | ✅ |
| Edit own messages | ✅ | ✅ | ✅ | ✅ |
| Edit storyteller responses | ❌ | ✅ | ❌ | ✅ |
| Edit human player messages | ❌ | ❌ | ❌ | ✅ |
| Edit AI responses | ❌ | ✅ | ✅ | ✅ |
| Create game | ❌ | ❌ | ✅ | ✅ |
| Assign roles | ❌ | ❌ | ✅ | ✅ |
| Direct AI commands | ❌ | ❌ | ✅ | ✅ |

---

### Phase 4: AI Automation (Week 8-9)

**Tasks:**
1. **AI Player System**
   - [ ] Automated response generation
   - [ ] Use character profile in prompts
   - [ ] Respond to storyteller automatically
   - [ ] Configurable response delay
   - [ ] Generate public AND private actions

2. **AI Storyteller System**
   - [ ] Respond to all player actions
   - [ ] Generate scene narrations
   - [ ] Track plot progression
   - [ ] Use storyteller style in responses
   - [ ] Gamemaster command channel

3. **Automation Controls**
   - [ ] Enable/disable AI automation per role
   - [ ] Manual trigger for AI responses
   - [ ] Review mode (generate but don't send)
   - [ ] Override AI decisions

**AI Player Prompt Structure:**
```
System: You are {name}, a {gender} {race} {class} with a {personality} personality.

{race_traits}
{class_abilities}
{personality_traits}
{custom_background}

Current scene: {scene_description}
Recent events: {recent_context}

Respond to the storyteller's latest message. Consider:
- What would your character do publicly (visible to all)?
- What secret actions might you take (only storyteller sees)?
- Stay in character based on your race, class, and personality.

Format your response as:
PUBLIC: [what everyone sees]
PRIVATE: [secret actions only storyteller knows]
```

---

### Phase 5: Game Management & Save System (Week 10-11)

**Tasks:**
1. **Game Creation**
   - [ ] Game setup wizard
   - [ ] Scenario/setting description
   - [ ] Player slot configuration
   - [ ] Storyteller assignment
   - [ ] Game lobby/waiting room

2. **Save/Load System**
   - [ ] Export game state to JSON
   - [ ] Import saved game
   - [ ] Auto-save every N minutes
   - [ ] Game checkpoints
   - [ ] Game history log

3. **Database Implementation**
   - [ ] Replace in-memory storage
   - [ ] SQLite for development
   - [ ] PostgreSQL for production
   - [ ] Migration system (Alembic)

**Game State Schema:**
```python
class Game(Base):
    __tablename__ = "games"
    
    id: str (PK)
    name: str
    scenario: str
    created_by: str (FK to User)
    created_at: datetime
    status: str  # lobby, active, paused, completed
    
    # Configuration
    max_players: int
    storyteller_id: Optional[str]
    storyteller_is_ai: bool
    
    # Relations
    players: List[Player]
    messages: List[Message]
    checkpoints: List[GameCheckpoint]
```

---

### Phase 6: Polish & Testing (Week 12)

**Tasks:**
1. **UI/UX Polish**
   - [ ] Consistent styling across all modes
   - [ ] Loading states and animations
   - [ ] Error handling and user feedback
   - [ ] Responsive design

2. **Testing**
   - [ ] Unit tests for character profiles
   - [ ] Permission enforcement tests
   - [ ] AI automation tests
   - [ ] End-to-end game flow tests

3. **Documentation**
   - [ ] User guide for each mode
   - [ ] Character creation guide
   - [ ] Game setup tutorial
   - [ ] API documentation

4. **Performance**
   - [ ] Optimize LLM calls
   - [ ] WebSocket performance
   - [ ] Database query optimization
   - [ ] Caching strategy

---

## 📦 Dependencies to Add

### Backend
```txt
# requirements.txt additions
sqlalchemy==2.0.23
alembic==1.13.0
pillow==10.1.0  # For PNG metadata handling
```

### Frontend
```json
// package.json additions
"react-hook-form": "^7.48.0",
"zod": "^3.22.0",
"file-saver": "^2.0.5",
"png-metadata": "^1.0.0"
```

---

## 🎯 MVP Success Criteria

**The MVP is complete when:**

✅ **Players can:**
- Create characters with full profiles (race/class/personality)
- Send public and private messages
- Use AI to generate in-character responses
- Export/import character profiles (JSON & PNG)

✅ **Storytellers can:**
- View all player actions (public and private)
- Respond to players with chosen style
- Control AI players
- Generate scene narrations

✅ **AI Players can:**
- Automatically generate responses with character personality
- Create both public and private actions
- Respond contextually to storyteller

✅ **AI Storytellers can:**
- Run entire games automatically
- Respond to all player actions
- Generate appropriate scene narrations
- Accept Gamemaster override

✅ **Gamemasters can:**
- Create and configure games
- Assign human/AI to roles
- View entire game state
- Command AI storyteller
- Save/load games

✅ **System can:**
- Enforce all permissions correctly
- Save and load game progress
- Handle multiple concurrent games
- Track LLM usage and costs

---

## 🚀 Next Immediate Steps

### Week 1 - Day 1-3: Message System
1. Update `Message` model with visibility fields
2. Create message type selector UI
3. Implement message filtering logic
4. Test public/private message flow

### Week 1 - Day 4-7: Character Profiles
1. Design character profile schema
2. Create race/class/personality prompt templates
3. Build character creation wizard
4. Implement profile-based LLM prompts

**Ready to begin?** Let's start with Phase 1 - Enhanced Message System!

---

**Last Updated:** 2025-01-11  
**Target MVP Completion:** 12 weeks  
**Current Phase:** Planning → Implementation