aodhan/storyteller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Aodhan Collins
2025-10-11 21:21:36 +01:00
commit eccd456c59
29 changed files with 5375 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

583
docs/planning/MVP_ROADMAP.md Normal file
View File

@@ -0,0 +1,583 @@
# 🎯 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

390
docs/planning/NEXT_STEPS.md Normal file
View File

@@ -0,0 +1,390 @@
# 🚀 Next Steps for Storyteller RPG
## Immediate Improvements (Quick Wins)
### 1. AI-Assisted Storyteller Responses
**Priority: High | Effort: Low**
- [x] Backend endpoint exists (`/sessions/{session_id}/generate_suggestion`)
- [ ] Add "✨ AI Suggest" button to StorytellerView response textarea
- [ ] Show suggested response that storyteller can edit before sending
- [ ] Allow storyteller to regenerate if they don't like the suggestion
**Implementation:**
```javascript
// In StorytellerView.js - Add button next to "Send Private Response"
const getSuggestion = async () => {
const response = await fetch(
`${API_URL}/sessions/${sessionId}/generate_suggestion?character_id=${selectedCharacter}`,
{ method: 'POST' }
);
const data = await response.json();
setResponseText(data.suggestion);
};
```
### 2. Session Persistence
**Priority: High | Effort: Medium**
Currently, sessions exist only in memory. Add database storage:
**Option A: SQLite (Simplest)**
```bash
pip install sqlalchemy aiosqlite
```
**Option B: PostgreSQL (Production-ready)**
```bash
pip install sqlalchemy asyncpg psycopg2-binary
```
**Files to modify:**
- Create `database.py` for SQLAlchemy models
- Update `main.py` to use database instead of `sessions: Dict`
- Add session persistence on server restart
### 3. Better UI/UX Enhancements
**Priority: Medium | Effort: Low**
- [ ] Add typing indicators ("Storyteller is typing...")
- [ ] Add sound notifications for new messages
- [ ] Add markdown support in messages (bold, italic, etc.)
- [ ] Add character avatars (emoji selector or image upload)
- [ ] Add "Export conversation" button (save as JSON/text)
- [ ] Show timestamp for when character joined
- [ ] Add "Last active" indicator for characters
### 4. Dice Rolling System
**Priority: Medium | Effort: Medium**
Add RPG dice mechanics:
```javascript
// New component: DiceRoller.js
const rollDice = (notation) => {
// Parse notation like "2d6+3", "1d20", etc.
// Return result and show animation
};
```
**Features:**
- Character can request roll from storyteller
- Storyteller sees roll request and can approve
- Results visible to storyteller only (or optionally to character)
- Support for various dice (d4, d6, d8, d10, d12, d20, d100)
## Medium-Term Features
### 5. Character Sheets & Stats
**Priority: Medium | Effort: High**
Add RPG character management:
```python
# In main.py - extend Character model
class CharacterStats(BaseModel):
health: int = 100
max_health: int = 100
attributes: Dict[str, int] = {} # Strength, Dex, etc.
inventory: List[str] = []
skills: List[str] = []
```
**UI:**
- Character view shows their stats in a sidebar
- Storyteller can edit character stats
- Add stat modification history/log
### 6. Image Generation Integration
**Priority: Medium | Effort: Medium**
Integrate DALL-E or Stable Diffusion:
```python
# New endpoint in main.py
@app.post("/sessions/{session_id}/generate_image")
async def generate_scene_image(scene_description: str):
# Use OpenAI DALL-E or Replicate Stable Diffusion
# Return image URL
pass
```
**Use cases:**
- Generate scene illustrations
- Create character portraits
- Visualize items or locations
### 7. Multiple Storytellers / Co-GMs
**Priority: Low | Effort: Medium**
Allow multiple storytellers in one session:
- One primary storyteller
- Assistant storytellers can respond to characters
- Storytellers can see each other's responses
- Add permission system
### 8. Group Conversations
**Priority: Medium | Effort: Medium**
Allow characters to talk to each other (not just storyteller):
```python
class ConversationChannel(BaseModel):
id: str
name: str # "Party Chat", "Private: Alice & Bob"
participants: List[str] # character_ids
messages: List[Message] = []
```
**Features:**
- Storyteller creates channels
- Characters can be added/removed from channels
- Storyteller can see all channels (but optionally hide from other characters)
## Advanced Features
### 9. Voice Integration
**Priority: Low | Effort: High**
Add voice chat or text-to-speech:
**Option A: Text-to-Speech**
```python
# Use OpenAI TTS or ElevenLabs
@app.post("/tts")
async def text_to_speech(text: str, voice: str):
# Generate audio from text
pass
```
**Option B: Real-time Voice**
- Integrate WebRTC for voice channels
- Voice-to-text for automatic transcription
- Character AI can speak responses
### 10. Campaign Management
**Priority: Medium | Effort: High**
Add multi-session campaign support:
```python
class Campaign(BaseModel):
id: str
name: str
sessions: List[str] # session_ids
characters: Dict[str, Character] # Persistent across sessions
world_state: Dict[str, Any] # Locations, NPCs, quests
```
### 11. AI NPCs
**Priority: Medium | Effort: Medium**
Storyteller can create AI-controlled NPCs:
```python
class NPC(BaseModel):
id: str
name: str
description: str
ai_controlled: bool = True
llm_model: str = "gpt-3.5-turbo"
```
**Features:**
- NPCs have their own LLM sessions
- NPCs can respond to character messages
- Storyteller can override/edit NPC responses
- NPCs remember previous interactions
### 12. Combat System
**Priority: Low | Effort: High**
Add turn-based combat:
- Initiative tracking
- Action queue
- Status effects
- Health/damage tracking
- Combat log visible to all participants
## Infrastructure Improvements
### 13. Authentication & User Accounts
**Priority: High | Effort: High**
Add user system:
```bash
pip install python-jose[cryptography] passlib[bcrypt]
```
**Features:**
- User registration/login
- OAuth support (Google, Discord)
- User owns their characters
- User can be storyteller for multiple campaigns
- Session access control
### 14. Database Migration
**Priority: High | Effort: Medium**
Current: In-memory storage
Target: PostgreSQL or MongoDB
**Why:**
- Persist sessions across restarts
- Scale to multiple servers
- Backup and recovery
- Query optimization
### 15. API Rate Limiting
**Priority: Medium | Effort: Low**
Prevent abuse:
```python
from slowapi import Limiter
from slowapi.util import get_remote_address
limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter
@app.post("/sessions/")
@limiter.limit("10/minute")
async def create_session(...):
pass
```
### 16. WebSocket Reconnection
**Priority: Medium | Effort: Medium**
Handle disconnections gracefully:
- Auto-reconnect on connection loss
- Queue messages while disconnected
- Sync state on reconnection
- Show connection status prominently
### 17. Mobile App
**Priority: Low | Effort: Very High**
Build native mobile apps:
**Option A: React Native**
- Reuse React components
- iOS + Android from one codebase
**Option B: Progressive Web App (PWA)**
- Add service worker
- Offline support
- Add to home screen
- Push notifications
### 18. Testing Suite
**Priority: High | Effort: Medium**
Add comprehensive tests:
```bash
# Backend tests
pip install pytest pytest-asyncio httpx
# Frontend tests (already have Jest)
cd frontend
npm test
```
**Coverage:**
- Unit tests for message routing
- Integration tests for WebSocket connections
- End-to-end tests for full user flows
- Load testing for concurrent sessions
## Polish & Quality of Life
### 19. Better Error Handling
- Show user-friendly error messages
- Add retry logic for failed API calls
- Graceful degradation when LLM API is down
- Better validation on all inputs
### 20. Accessibility
- Add keyboard navigation
- Screen reader support
- High contrast mode
- Font size controls
- Color blind friendly themes
### 21. Internationalization (i18n)
- Support multiple languages
- Translate UI elements
- LLM can respond in user's language
### 22. Analytics & Monitoring
- Track session duration
- Monitor WebSocket health
- LLM API usage and costs
- User engagement metrics
## Documentation
### 23. API Documentation
- [ ] Add Swagger/OpenAPI docs (FastAPI auto-generates this)
- [ ] Document WebSocket message formats
- [ ] Add code examples for all endpoints
### 24. Tutorial System
- [ ] In-app tutorial for new users
- [ ] Video guides
- [ ] Example campaign/scenario
- [ ] Best practices guide for storytellers
## Prioritized Roadmap
### Phase 1: Core Stability (1-2 weeks)
1. ✅ AI-assisted storyteller responses (UI hookup)
2. ✅ Database persistence (SQLite or PostgreSQL)
3. ✅ Better error handling
4. ✅ WebSocket reconnection
### Phase 2: Enhanced Gameplay (2-3 weeks)
5. ✅ Dice rolling system
6. ✅ Character sheets & stats
7. ✅ Typing indicators
8. ✅ Export conversations
### Phase 3: Rich Features (3-4 weeks)
9. ✅ Image generation
10. ✅ Group conversations
11. ✅ AI NPCs
12. ✅ Authentication system
### Phase 4: Scale & Polish (2-3 weeks)
13. ✅ Production database
14. ✅ Testing suite
15. ✅ Mobile PWA
16. ✅ Campaign management
## Quick Wins to Start With
If you're continuing development, I recommend starting with:
1. **Add AI Suggest button** (30 mins) - The backend already supports it!
2. **Add typing indicators** (1 hour) - Great UX improvement
3. **Session persistence** (3-4 hours) - Prevents data loss
4. **Dice roller** (2-3 hours) - Core RPG feature
5. **Export conversations** (1 hour) - Users will love this
## Notes for Future Development
- All WebSocket messages use JSON format with a `type` field
- Character conversations are stored in `Character.conversation_history`
- Each character has their own LLM model configurable at creation
- Frontend uses native WebSocket (not socket.io despite the package.json)
- Backend runs on port 8000, frontend on port 3000
- CORS is wide open for development - restrict in production!
## Getting Help
- **FastAPI docs**: https://fastapi.tiangolo.com/
- **React docs**: https://react.dev/
- **OpenAI API**: https://platform.openai.com/docs
- **OpenRouter**: https://openrouter.ai/docs
- **WebSocket guide**: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket

525
docs/planning/PROJECT_PLAN.md Normal file
View File

@@ -0,0 +1,525 @@
# 🎭 Storyteller RPG - Project Plan
## Vision
Transform the application into a full-featured RPG platform with multiple user roles, AI automation, and comprehensive game management capabilities.
---
## 📋 Phase 1: User Roles & Authentication System
### 1.1 Backend Infrastructure
- [ ] **User Model & Authentication**
- Implement user registration/login system
- Add JWT token-based authentication
- User profile management
- Session management with user association
- [ ] **Role-Based Access Control (RBAC)**
- Define role hierarchy: Admin > Gamemaster > Storyteller > Player
- Create permission decorators for API endpoints
- Implement role checking middleware
- Role assignment system
- [ ] **Database Integration**
- Replace in-memory storage with persistent database (SQLite/PostgreSQL)
- User table schema
- Game/Session table schema
- Character/Player table schema with user association
- Message history with ownership tracking
**Estimated Time:** 1-2 weeks
**Technical Stack:**
```python
# Backend additions needed:
- SQLAlchemy (ORM)
- JWT (python-jose)
- Password hashing (passlib)
- Database (SQLite for dev, PostgreSQL for prod)
```
---
## 📋 Phase 2: Game Creation & Management System
### 2.1 Game Configuration
- [ ] **Game Creation Interface**
- Game setup wizard for Gamemaster
- Configure game settings:
- Game name & description
- Scenario/setting details
- Number of player slots
- Storyteller assignment (human/AI)
- LLM model selection per role
- Game state management (not started, in progress, paused, completed)
- [ ] **Role Assignment System**
- Player slot management
- Assign slots to:
- Human users (invite by username/email)
- AI players (configure personality & LLM)
- Storyteller assignment (human or AI)
- Role transfer/reassignment
- [ ] **Game Lobby**
- Pre-game waiting room
- Player slot status display
- Ready/not ready indicators
- Game start conditions
**Estimated Time:** 2 weeks
**UI Components:**
```
- GameCreationWizard.js
- RoleAssignmentPanel.js
- GameLobby.js
- PlayerSlotCard.js
```
---
## 📋 Phase 3: User Mode Interfaces
### 3.1 Player Mode
- [ ] **Player Interface**
- View own character sheet
- Private messaging with storyteller
- View scene descriptions
- Message history (own messages only)
- Cannot edit storyteller responses
- Can generate/edit/write own responses
- [ ] **Player Controls**
- Message composer with AI generation option
- Edit own messages (before storyteller reads)
- Character action commands
- Inventory/stats display (if applicable)
**Permissions:**
```
✅ Read: Own messages, storyteller responses to self, scene narrations
✅ Write: Own character messages
✅ Edit: Own unread messages
❌ Edit: Storyteller responses, other players' messages
```
### 3.2 Storyteller Mode
- [ ] **Storyteller Dashboard**
- View all player messages
- Player list with status indicators
- Response composer per player
- Scene narration composer
- AI player response generation/editing
- [ ] **Storyteller Controls**
- Generate responses with AI assist (per player's LLM)
- Edit AI-generated responses before sending
- Manage AI players completely
- Broadcast scene narrations
- View conversation history per player
**Permissions:**
```
✅ Read: All player messages, all game state
✅ Write: Responses to players, scene narrations
✅ Edit: Own responses, AI player messages
❌ Edit: Human player messages
✅ Generate: AI responses for any player
```
### 3.3 Gamemaster Mode
- [ ] **Gamemaster Control Panel**
- Overview of entire game state
- All player & storyteller message threads
- Game configuration management
- Player/role management
- AI behavior controls
- [ ] **Gamemaster Powers**
- Send messages to any player
- Edit AI responses (storyteller or players)
- Pause/resume game
- Modify game settings mid-game
- View all LLM usage/costs
- Generate content with any LLM
**Permissions:**
```
✅ Read: Everything
✅ Write: Messages to anyone
✅ Edit: AI responses (storyteller & players)
❌ Edit: Human responses (storyteller & players)
✅ Configure: Game settings, roles, LLMs
✅ Control: AI automation, game flow
```
### 3.4 Admin Mode (Development)
- [ ] **Admin Dashboard**
- System-wide overview
- All games management
- User management
- LLM configuration & monitoring
- Cost tracking & analytics
- [ ] **Admin Powers**
- Full edit access to everything
- View/modify all LLMs in use
- System configuration
- Debug tools
- Performance monitoring
**Permissions:**
```
✅ Full Access: Everything, no restrictions
```
**Estimated Time:** 3-4 weeks
---
## 📋 Phase 4: AI Automation System
### 4.1 AI Player System
- [ ] **AI Player Engine**
- Automated message generation based on:
- Character personality/backstory
- Recent conversation context
- Scene descriptions
- Game scenario
- Configurable response triggers:
- Time-based (respond every N seconds)
- Event-based (respond to storyteller)
- Manual trigger (Gamemaster/Storyteller control)
- [ ] **AI Player Configuration**
- Personality templates
- Response style settings
- Behavior patterns (cautious, bold, curious, etc.)
- LLM model selection per AI player
- Temperature/creativity settings
### 4.2 AI Storyteller System
- [ ] **AI Storyteller Engine**
- Automated storytelling based on:
- Game scenario/plot
- Player actions
- Story progression rules
- Scene templates
- Response generation for each player
- Scene narration generation
- [ ] **AI Storyteller Configuration**
- Storytelling style (descriptive, action-focused, dialogue-heavy)
- Plot progression speed
- Challenge difficulty
- LLM model selection
- Context window management
### 4.3 Automation Controls
- [ ] **Manual Override System**
- Human can take over from AI at any time
- AI can be paused/resumed
- Edit AI responses before sending
- Review mode (AI generates, human approves)
- [ ] **Automation Triggers**
- Configurable response timing
- Event-based triggers
- Turn-based mode support
- Real-time mode support
**Estimated Time:** 2-3 weeks
**Technical Implementation:**
```python
# Backend components:
- AIPlayerEngine class
- AIStorytellerEngine class
- AutomationScheduler
- ResponseGenerator with context management
- Trigger system for automated responses
```
---
## 📋 Phase 5: Enhanced Features
### 5.1 Message Management
- [ ] **Message Editing System**
- Edit history tracking
- Permissions enforcement
- Real-time sync of edits
- Visual indicators for edited messages
- [ ] **Message Generation**
- AI-assisted writing for all roles
- Prompt templates library
- Context-aware suggestions
- Multi-model comparison
### 5.2 Game State Management
- [ ] **Save/Load System**
- Export game state
- Import saved games
- Game snapshots/checkpoints
- Rewind to previous state
- [ ] **Turn Management** (Optional)
- Turn-based gameplay option
- Turn order configuration
- Turn timer
- Turn history
### 5.3 Analytics & Monitoring
- [ ] **Usage Tracking**
- LLM usage per game
- Cost tracking per model
- Response time metrics
- Player engagement analytics
- [ ] **Game Insights**
- Conversation flow visualization
- Player participation metrics
- Story progression tracking
- AI vs Human response statistics
**Estimated Time:** 2 weeks
---
## 📋 Phase 6: Polish & Deployment
### 6.1 UI/UX Refinement
- [ ] Responsive design for all modes
- [ ] Mobile-friendly interfaces
- [ ] Accessibility improvements
- [ ] Theme customization
### 6.2 Testing
- [ ] Unit tests for all components
- [ ] Integration tests
- [ ] Role permission tests
- [ ] Load testing
### 6.3 Documentation
- [ ] User guides per role
- [ ] API documentation
- [ ] Deployment guide
- [ ] Developer documentation
### 6.4 Deployment
- [ ] Production environment setup
- [ ] Database migration system
- [ ] CI/CD pipeline
- [ ] Monitoring & logging
**Estimated Time:** 2 weeks
---
## 🗓️ Timeline Summary
| Phase | Description | Duration | Status |
|-------|-------------|----------|--------|
| **Phase 0** | Current MVP | - | ✅ Complete |
| **Phase 1** | User Roles & Auth | 1-2 weeks | 🔄 Planning |
| **Phase 2** | Game Management | 2 weeks | ⏳ Pending |
| **Phase 3** | User Modes | 3-4 weeks | ⏳ Pending |
| **Phase 4** | AI Automation | 2-3 weeks | ⏳ Pending |
| **Phase 5** | Enhanced Features | 2 weeks | ⏳ Pending |
| **Phase 6** | Polish & Deploy | 2 weeks | ⏳ Pending |
| **Total** | | **12-15 weeks** | |
---
## 🏗️ Technical Architecture Changes
### Current Architecture
```
Frontend (React) ←→ Backend (FastAPI) ←→ In-Memory Storage
WebSockets
```
### Target Architecture
```
Frontend (React)
├── Player Interface
├── Storyteller Interface
├── Gamemaster Interface
└── Admin Interface
↕
API Gateway (FastAPI)
├── Authentication Layer (JWT)
├── Authorization Layer (RBAC)
└── WebSocket Manager
↕
Business Logic
├── Game Engine
├── AI Player Engine
├── AI Storyteller Engine
└── Automation Scheduler
↕
Data Layer
├── Database (PostgreSQL)
├── Redis (Caching/Sessions)
└── File Storage (Game States)
↕
External Services
├── OpenAI API
├── OpenRouter API
└── Analytics Service
```
---
## 📦 New Dependencies Needed
### Backend
```python
# requirements.txt additions
sqlalchemy==2.0.23 # ORM
alembic==1.13.0 # Database migrations
psycopg2-binary==2.9.9 # PostgreSQL driver
python-jose[cryptography] # JWT (already added, needs activation)
passlib[bcrypt] # Password hashing (already added, needs activation)
redis==5.0.1 # Caching & session management
celery==5.3.4 # Task queue for AI automation
pydantic-settings==2.1.0 # Settings management
```
### Frontend
```json
// package.json additions
"@tanstack/react-query": "^5.0.0", // Data fetching
"zustand": "^4.4.0", // State management
"react-router-dom": "^6.20.0", // Routing (if not added)
"react-hook-form": "^7.48.0", // Form management
"zod": "^3.22.0", // Schema validation
"recharts": "^2.10.0", // Analytics charts
"@dnd-kit/core": "^6.1.0" // Drag-and-drop for role assignment
```
---
## 🎯 Success Criteria
### Phase 1 Complete When:
- ✅ Users can register/login
- ✅ Role-based access works
- ✅ Database stores all game data persistently
### Phase 2 Complete When:
- ✅ Gamemaster can create games
- ✅ Can assign humans/AI to roles
- ✅ Game lobby works with ready states
### Phase 3 Complete When:
- ✅ All 4 user modes functional
- ✅ Permissions enforced correctly
- ✅ UI matches role capabilities
### Phase 4 Complete When:
- ✅ AI players respond automatically
- ✅ AI storyteller can run full games
- ✅ Human override works seamlessly
### Phase 5 Complete When:
- ✅ Message editing works with permissions
- ✅ Save/load system functional
- ✅ Analytics dashboard complete
### Phase 6 Complete When:
- ✅ App deployed to production
- ✅ All tests passing
- ✅ Documentation complete
---
## 🚀 Getting Started - Phase 1
### Immediate Next Steps:
1. **Database Setup**
```bash
pip install sqlalchemy alembic psycopg2-binary
alembic init migrations
```
2. **Create Database Models**
- User model with roles
- Game model
- Character model with user_id
- Message model with ownership
3. **Implement Authentication**
- JWT token generation
- Login/register endpoints
- Protected routes
4. **Update Frontend**
- Login/register pages
- Auth state management
- Protected route wrapper
### Priority Tasks for Phase 1:
1. Database schema design
2. User authentication system
3. Role assignment logic
4. Update existing session system to use database
---
## 📝 Notes & Considerations
### Key Design Decisions:
- **Database:** PostgreSQL for production, SQLite for development
- **Auth:** JWT tokens with refresh mechanism
- **Real-time:** Continue using WebSockets, add auth to connections
- **AI Queue:** Celery for handling automated AI responses
- **Caching:** Redis for session data and frequently accessed game state
### Challenges to Address:
- **Race Conditions:** Multiple users editing same game state
- **AI Cost Control:** Budget limits per game/user
- **Scalability:** Support for multiple concurrent games
- **Context Management:** LLM context windows for long games
- **Latency:** AI response generation can be slow
### Future Enhancements (Post-MVP):
- Voice chat integration
- Character sheet system with stats/inventory
- Dice rolling system
- Battle/combat system
- Campaign management (multi-session games)
- Marketplace for game scenarios
- Community features (forums, game discovery)
---
## 🤝 Development Workflow
### Branching Strategy:
```
main (production)
├── develop (integration)
├── feature/phase1-auth
├── feature/phase2-game-creation
├── feature/phase3-player-mode
└── feature/phase4-ai-automation
```
### Testing Strategy:
- Unit tests for all new backend functions
- Integration tests for API endpoints
- E2E tests for critical user flows
- Load tests for AI automation
### Code Review Process:
- All features require PR review
- Test coverage minimum: 80%
- Documentation required for new features
---
**Last Updated:** 2025-10-11
**Next Review:** Start of Phase 1