Reorganize and consolidate documentation
Documentation Structure: - Created docs/features/ for all feature documentation - Moved CONTEXTUAL_RESPONSE_FEATURE.md, DEMO_SESSION.md, FIXES_SUMMARY.md, PROMPT_IMPROVEMENTS.md to docs/features/ - Moved TESTING_GUIDE.md and TEST_RESULTS.md to docs/development/ - Created comprehensive docs/features/README.md with feature catalog Cleanup: - Removed outdated CURRENT_STATUS.md and SESSION_SUMMARY.md - Removed duplicate files in docs/development/ - Consolidated scattered documentation Main README Updates: - Reorganized key features into categories (Core, AI, Technical) - Added Demo Session section with quick-access info - Updated Quick Start section with bash start.sh instructions - Added direct links to feature documentation Documentation Hub Updates: - Updated docs/README.md with new structure - Added features section at top - Added current status (v0.2.0) - Added documentation map visualization - Better quick links for different user types New Files: - CHANGELOG.md - Version history following Keep a Changelog format - docs/features/README.md - Complete feature catalog and index Result: Clean, organized documentation structure with clear navigation
This commit is contained in:
Aodhan Collins
167
CHANGELOG.md
Normal file
167
CHANGELOG.md
Normal file
@@ -0,0 +1,167 @@
|
|||||||
|
# Changelog
|
||||||
|
|
||||||
|
All notable changes to the Storyteller RPG project will be documented in this file.
|
||||||
|
|
||||||
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||||
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## [0.2.0] - 2025-10-12
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- **Context-Aware Response Generator** 🧠
|
||||||
|
- Select multiple characters to include in AI-generated responses
|
||||||
|
- Two modes: Scene descriptions (broadcast) or Individual responses (private)
|
||||||
|
- Smart context building with character profiles, personalities, and conversation history
|
||||||
|
- Automatic parsing and distribution of individual responses
|
||||||
|
- Improved prompts with explicit `[CharacterName]` format for reliable parsing
|
||||||
|
|
||||||
|
- **Demo Session** 🎮
|
||||||
|
- Pre-configured "The Cursed Tavern" adventure
|
||||||
|
- Two characters: Bargin Ironforge (Dwarf Warrior) & Willow Moonwhisper (Elf Ranger)
|
||||||
|
- Auto-created on server startup
|
||||||
|
- Quick-access buttons on home page for instant testing
|
||||||
|
- Eliminates need to recreate test data during development
|
||||||
|
|
||||||
|
- **Session ID Copy Button** 📋
|
||||||
|
- One-click clipboard copy in storyteller dashboard
|
||||||
|
- Improved UX for session sharing
|
||||||
|
|
||||||
|
- **Comprehensive Documentation** 📚
|
||||||
|
- Feature guides for all major features
|
||||||
|
- Prompt engineering documentation
|
||||||
|
- Demo session usage guide
|
||||||
|
- Bug fixes summary
|
||||||
|
|
||||||
|
### Fixed
|
||||||
|
- **Character Chat History** - Characters can now see full conversation with storyteller (not just most recent message)
|
||||||
|
- Fixed WebSocket message type handling (`storyteller_response` and `new_message`)
|
||||||
|
|
||||||
|
- **Pydantic Deprecation Warnings** - Replaced all `.dict()` calls with `.model_dump()` (9 instances)
|
||||||
|
- Code is now Pydantic V2 compliant
|
||||||
|
- No more deprecation warnings in console
|
||||||
|
|
||||||
|
- **WebSocket Manager Reference** - Fixed `character_connections` error in contextual response endpoint
|
||||||
|
- Now properly uses `manager.send_to_client()` with correct key format
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
- Improved LLM prompts for individual responses with explicit format instructions
|
||||||
|
- Simplified response parsing from 4 regex patterns to single reliable pattern
|
||||||
|
- Enhanced system prompts for better LLM compliance
|
||||||
|
- Reorganized documentation structure with dedicated features folder
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## [0.1.0] - 2025-10-11
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- **Core Session Management**
|
||||||
|
- Create and join game sessions
|
||||||
|
- Session ID-based access control
|
||||||
|
- In-memory session storage
|
||||||
|
|
||||||
|
- **Character System**
|
||||||
|
- Character creation with name, description, and personality
|
||||||
|
- Character profiles visible to storyteller
|
||||||
|
- Per-character conversation history
|
||||||
|
|
||||||
|
- **Flexible Messaging System** 📨
|
||||||
|
- **Private Messages** - Character ↔ Storyteller only
|
||||||
|
- **Public Messages** - Visible to all players
|
||||||
|
- **Mixed Messages** - Public action + private thoughts
|
||||||
|
- Real-time message delivery via WebSockets
|
||||||
|
|
||||||
|
- **Scene Narration** 📜
|
||||||
|
- Storyteller can broadcast scene descriptions
|
||||||
|
- Scenes visible to all connected characters
|
||||||
|
- Scene history tracking
|
||||||
|
|
||||||
|
- **AI-Assisted Responses** ✨
|
||||||
|
- "AI Suggest" button for storytellers
|
||||||
|
- Generate response suggestions using character's LLM
|
||||||
|
- Editable before sending
|
||||||
|
|
||||||
|
- **Multi-LLM Support** 🤖
|
||||||
|
- Support for 100+ models via OpenRouter and OpenAI
|
||||||
|
- Per-character model selection
|
||||||
|
- Models: GPT-4o, GPT-4, GPT-3.5, Claude, Llama, Gemini, Mistral, etc.
|
||||||
|
- Each character can use a different model
|
||||||
|
|
||||||
|
- **Real-time Communication** ⚡
|
||||||
|
- WebSocket endpoints for characters and storyteller
|
||||||
|
- Instant message delivery
|
||||||
|
- Connection status indicators
|
||||||
|
- Pending response tracking
|
||||||
|
|
||||||
|
- **Modern UI** 🎨
|
||||||
|
- Clean, intuitive interface
|
||||||
|
- Gradient-themed design
|
||||||
|
- Responsive layout
|
||||||
|
- Character-specific color schemes
|
||||||
|
- Loading states and animations
|
||||||
|
|
||||||
|
### Technical
|
||||||
|
- FastAPI backend with WebSocket support
|
||||||
|
- React frontend with modern hooks
|
||||||
|
- ConnectionManager for WebSocket state
|
||||||
|
- Pydantic models for data validation
|
||||||
|
- CORS configuration for local development
|
||||||
|
- Environment-based API key management
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## [Unreleased]
|
||||||
|
|
||||||
|
### Planned Features
|
||||||
|
- Database persistence (PostgreSQL/MongoDB)
|
||||||
|
- User authentication system
|
||||||
|
- Character sheets with stats
|
||||||
|
- Dice rolling mechanics
|
||||||
|
- Combat system
|
||||||
|
- Image generation for scenes/characters
|
||||||
|
- Voice message support
|
||||||
|
- Session export functionality
|
||||||
|
- Mobile app versions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Version History
|
||||||
|
|
||||||
|
- **0.2.0** (2025-10-12) - Context-Aware AI, Demo Session, Bug Fixes
|
||||||
|
- **0.1.0** (2025-10-11) - Initial MVP Release
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Migration Notes
|
||||||
|
|
||||||
|
### 0.1.0 → 0.2.0
|
||||||
|
|
||||||
|
**No breaking changes.** All existing functionality preserved.
|
||||||
|
|
||||||
|
**New Features Available:**
|
||||||
|
- Click "▶ Show Generator" in storyteller dashboard for context-aware responses
|
||||||
|
- Demo session auto-created on startup (session ID: `demo-session-001`)
|
||||||
|
- Copy button next to session ID for easy sharing
|
||||||
|
|
||||||
|
**Bug Fixes Applied Automatically:**
|
||||||
|
- Full conversation history now visible
|
||||||
|
- No more Pydantic warnings
|
||||||
|
- WebSocket messages work correctly
|
||||||
|
|
||||||
|
**No Action Required:**
|
||||||
|
- In-memory sessions continue to work as before
|
||||||
|
- No database migrations needed
|
||||||
|
- Frontend automatically detects new features
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
See [docs/README.md](./docs/README.md) for documentation guidelines.
|
||||||
|
|
||||||
|
Report bugs or suggest features via GitHub issues.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Format inspired by [Keep a Changelog](https://keepachangelog.com/)*
|
||||||
@@ -1,308 +0,0 @@
|
|||||||
# 🎭 Storyteller RPG - Current Status
|
|
||||||
|
|
||||||
**Date:** October 11, 2025
|
|
||||||
**Session Duration:** ~1 hour
|
|
||||||
**Status:** ✅ Major MVP Features Implemented
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎉 What We Accomplished Today
|
|
||||||
|
|
||||||
### 1. ✨ AI-Assisted Storyteller Responses (Quick Win)
|
|
||||||
**New Feature:** Storytellers can now click "✨ AI Suggest" to generate response suggestions using the character's chosen LLM model.
|
|
||||||
|
|
||||||
**Implementation:**
|
|
||||||
- Added button in StorytellerView response section
|
|
||||||
- Shows loading state while generating
|
|
||||||
- Populates textarea with suggestion (editable before sending)
|
|
||||||
- Uses existing backend endpoint
|
|
||||||
|
|
||||||
**Files Modified:**
|
|
||||||
- `frontend/src/components/StorytellerView.js`
|
|
||||||
- `frontend/src/App.css` (added `.btn-secondary`, `.response-buttons`)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2. 📢 Enhanced Message System (MVP Phase 1 - COMPLETE!)
|
|
||||||
|
|
||||||
This is the **core feature** that makes the app unique for RPG gameplay.
|
|
||||||
|
|
||||||
#### Message Types
|
|
||||||
1. **🔒 Private** - Only storyteller sees (default)
|
|
||||||
- Example: "I attempt to pickpocket the merchant"
|
|
||||||
|
|
||||||
2. **📢 Public** - All players see
|
|
||||||
- Example: "I shake hands with the merchant"
|
|
||||||
|
|
||||||
3. **🔀 Mixed** - Public action + secret motive
|
|
||||||
- Public: "I shake hands with the merchant"
|
|
||||||
- Private: "While shaking hands, I try to slip my hand into his pocket"
|
|
||||||
|
|
||||||
#### Backend Changes (`main.py`)
|
|
||||||
- **Message Model Updated:**
|
|
||||||
```python
|
|
||||||
class Message:
|
|
||||||
visibility: str = "private" # "public", "private", "mixed"
|
|
||||||
public_content: Optional[str] = None
|
|
||||||
private_content: Optional[str] = None
|
|
||||||
```
|
|
||||||
|
|
||||||
- **GameSession Model Updated:**
|
|
||||||
```python
|
|
||||||
class GameSession:
|
|
||||||
public_messages: List[Message] = [] # Shared feed
|
|
||||||
```
|
|
||||||
|
|
||||||
- **WebSocket Routing:**
|
|
||||||
- Private messages → Only to storyteller
|
|
||||||
- Public messages → Broadcast to all characters
|
|
||||||
- Mixed messages → Both feeds appropriately
|
|
||||||
|
|
||||||
#### Frontend Changes
|
|
||||||
|
|
||||||
**CharacterView.js:**
|
|
||||||
- Message type selector dropdown
|
|
||||||
- Public messages section (shows all player actions)
|
|
||||||
- Private conversation section (storyteller only)
|
|
||||||
- Mixed message composer with dual textareas
|
|
||||||
- Real-time updates for both feeds
|
|
||||||
|
|
||||||
**StorytellerView.js:**
|
|
||||||
- Public actions feed (last 5 actions)
|
|
||||||
- View all message types
|
|
||||||
- See both public and private content
|
|
||||||
|
|
||||||
**App.css:**
|
|
||||||
- New sections for public/private message display
|
|
||||||
- Mixed message composer styling
|
|
||||||
- Visual distinction between message types
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🏗️ Architecture Improvements
|
|
||||||
|
|
||||||
### Message Flow
|
|
||||||
|
|
||||||
```
|
|
||||||
CHARACTER A STORYTELLER CHARACTER B
|
|
||||||
| | |
|
|
||||||
| "I pickpocket" (private) | |
|
|
||||||
|----------------------------->| |
|
|
||||||
| | |
|
|
||||||
| "I wave hello" (public) | |
|
|
||||||
|----------------------------->|----------------------------->|
|
|
||||||
| | |
|
|
||||||
| Sees both | Sees only public |
|
|
||||||
```
|
|
||||||
|
|
||||||
### Privacy Model
|
|
||||||
- ✅ Characters only see their own private messages
|
|
||||||
- ✅ Characters see ALL public messages
|
|
||||||
- ✅ Storyteller sees EVERYTHING
|
|
||||||
- ✅ Mixed messages split correctly
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎮 How to Use
|
|
||||||
|
|
||||||
### As a Character:
|
|
||||||
|
|
||||||
1. **Join a session** at http://localhost:3000
|
|
||||||
2. **Select message type** from dropdown:
|
|
||||||
- 🔒 Private (default) - Secret actions
|
|
||||||
- 📢 Public - Actions everyone sees
|
|
||||||
- 🔀 Mixed - Do something publicly while attempting something secret
|
|
||||||
3. **Send messages** - They route appropriately
|
|
||||||
4. **View public feed** - See what other players are doing
|
|
||||||
5. **Private conversation** - Your secret messages with storyteller
|
|
||||||
|
|
||||||
### As a Storyteller:
|
|
||||||
|
|
||||||
1. **Create session** and share ID
|
|
||||||
2. **View public feed** - See all public actions
|
|
||||||
3. **Select character** - View their private messages
|
|
||||||
4. **Click "✨ AI Suggest"** - Generate response ideas
|
|
||||||
5. **Respond privately** - Each character gets personalized replies
|
|
||||||
6. **Narrate scenes** - Broadcast to everyone
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📁 Files Modified
|
|
||||||
|
|
||||||
### Backend
|
|
||||||
- ✅ `main.py` - Message model, routing, public messages
|
|
||||||
|
|
||||||
### Frontend Components
|
|
||||||
- ✅ `frontend/src/components/CharacterView.js` - Message composer, public feed
|
|
||||||
- ✅ `frontend/src/components/StorytellerView.js` - AI suggest, public feed
|
|
||||||
|
|
||||||
### Styles
|
|
||||||
- ✅ `frontend/src/App.css` - New sections and components
|
|
||||||
|
|
||||||
### Documentation
|
|
||||||
- ✅ `docs/development/MVP_PROGRESS.md` - Detailed progress report
|
|
||||||
- ✅ `CURRENT_STATUS.md` - This file
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🧪 Testing Status
|
|
||||||
|
|
||||||
### ✅ Verified
|
|
||||||
- Backend starts with new message model
|
|
||||||
- Frontend compiles successfully
|
|
||||||
- Both servers running (ports 3000 & 8000)
|
|
||||||
- API endpoints include `public_messages`
|
|
||||||
|
|
||||||
### ⏳ Manual Testing Needed
|
|
||||||
You should test these scenarios:
|
|
||||||
|
|
||||||
1. **Two Character Test:**
|
|
||||||
- Open two browser windows
|
|
||||||
- Create session as storyteller in window 1
|
|
||||||
- Join as Character A in window 2
|
|
||||||
- Join as Character B in window 3
|
|
||||||
- Send public message from Character A
|
|
||||||
- Verify Character B sees it
|
|
||||||
- Send private message from Character A
|
|
||||||
- Verify Character B does NOT see it
|
|
||||||
- Verify storyteller sees both
|
|
||||||
|
|
||||||
2. **Mixed Message Test:**
|
|
||||||
- Select "Mixed" message type
|
|
||||||
- Enter public action: "I examine the door"
|
|
||||||
- Enter private action: "I check for traps"
|
|
||||||
- Send and verify both parts appear correctly
|
|
||||||
|
|
||||||
3. **AI Suggest Test:**
|
|
||||||
- As storyteller, click "✨ AI Suggest"
|
|
||||||
- Verify suggestion generates
|
|
||||||
- Edit and send
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 What's Next
|
|
||||||
|
|
||||||
### Immediate Priorities
|
|
||||||
|
|
||||||
#### 1. Database Persistence (High Priority - 3-4 hours)
|
|
||||||
**Why:** Currently sessions only exist in memory. Server restart = data loss.
|
|
||||||
|
|
||||||
**What to add:**
|
|
||||||
```bash
|
|
||||||
# requirements.txt
|
|
||||||
sqlalchemy==2.0.23
|
|
||||||
aiosqlite==3.0.10
|
|
||||||
alembic==1.13.0
|
|
||||||
```
|
|
||||||
|
|
||||||
**Implementation:**
|
|
||||||
- Create `database.py` with SQLAlchemy models
|
|
||||||
- Replace in-memory `sessions` dict
|
|
||||||
- Add save/load endpoints
|
|
||||||
- Enable session persistence
|
|
||||||
|
|
||||||
#### 2. Character Profile System (MVP Phase 2 - 1-2 days)
|
|
||||||
Implement the race/class/personality system from MVP roadmap:
|
|
||||||
|
|
||||||
**Features:**
|
|
||||||
- Character creation wizard
|
|
||||||
- Race selection (Human/Elf/Dwarf/Orc/Halfling)
|
|
||||||
- Class selection (Warrior/Wizard/Cleric/Archer/Rogue)
|
|
||||||
- Personality (Friendly/Serious/Doubtful/Measured)
|
|
||||||
- Profile-based LLM prompts
|
|
||||||
- Import/export (JSON & PNG)
|
|
||||||
|
|
||||||
#### 3. Show Character Names in Public Feed (Quick Fix - 30 mins)
|
|
||||||
Currently public messages don't clearly show WHO did the action.
|
|
||||||
|
|
||||||
**Update needed:**
|
|
||||||
- Include character name in public message broadcasts
|
|
||||||
- Display in public feed: "Gandalf the Wizard: I cast light"
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 MVP Progress
|
|
||||||
|
|
||||||
**Phase 1:** ✅ 100% Complete (Enhanced Message System)
|
|
||||||
**Phase 2:** ⏳ 0% Complete (Character Profiles) - **NEXT**
|
|
||||||
**Phase 3:** ⏳ 0% Complete (User Mode Interfaces)
|
|
||||||
**Phase 4:** ⏳ 0% Complete (AI Automation)
|
|
||||||
**Phase 5:** ⏳ 0% Complete (Game Management & Database)
|
|
||||||
**Phase 6:** ⏳ 0% Complete (Polish & Testing)
|
|
||||||
|
|
||||||
**Overall MVP Progress:** ~8% (1/12 weeks)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎯 Success Metrics
|
|
||||||
|
|
||||||
### ✅ Completed
|
|
||||||
- [x] Private character-storyteller communication
|
|
||||||
- [x] Public message broadcasting
|
|
||||||
- [x] Mixed message support
|
|
||||||
- [x] AI-assisted responses UI
|
|
||||||
- [x] Real-time WebSocket updates
|
|
||||||
- [x] Message type selection
|
|
||||||
- [x] Visual distinction between message types
|
|
||||||
|
|
||||||
### 🎲 Ready for Testing
|
|
||||||
- [ ] Multi-character public feed
|
|
||||||
- [ ] Mixed message splitting
|
|
||||||
- [ ] AI suggestion quality
|
|
||||||
- [ ] Message persistence across refresh (needs DB)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 💡 Key Insights
|
|
||||||
|
|
||||||
1. **Message System is Core:** The public/private/mixed system is what makes this app special for RPG. Players can now create dramatic situations where they act one way publicly while secretly doing something else.
|
|
||||||
|
|
||||||
2. **Quick Wins Matter:** The AI Suggest button took 30 minutes but adds huge value for storytellers.
|
|
||||||
|
|
||||||
3. **Database is Critical:** Next session should start with SQLite implementation to prevent data loss and enable real features.
|
|
||||||
|
|
||||||
4. **Profile System is Next:** Character profiles with race/class/personality will make the LLM responses much more interesting and distinct.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔧 Running the Application
|
|
||||||
|
|
||||||
The application is currently running:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Backend: http://localhost:8000
|
|
||||||
# Frontend: http://localhost:3000
|
|
||||||
|
|
||||||
# To restart both:
|
|
||||||
bash start.sh
|
|
||||||
|
|
||||||
# To stop:
|
|
||||||
# Ctrl+C in the terminal running start.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📚 Documentation
|
|
||||||
|
|
||||||
- **Setup:** `docs/setup/QUICKSTART.md`
|
|
||||||
- **MVP Roadmap:** `docs/planning/MVP_ROADMAP.md`
|
|
||||||
- **Progress Report:** `docs/development/MVP_PROGRESS.md`
|
|
||||||
- **Implementation Details:** `docs/development/IMPLEMENTATION_SUMMARY.md`
|
|
||||||
- **API Reference:** `docs/reference/LLM_GUIDE.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎉 Summary
|
|
||||||
|
|
||||||
**Excellent progress!** We've completed Phase 1 of the MVP roadmap (Enhanced Message System) and added a valuable quick win (AI Suggest). The application now supports:
|
|
||||||
|
|
||||||
- ✨ **AI-assisted storyteller responses**
|
|
||||||
- 🔒 **Private messages** (character ↔ storyteller only)
|
|
||||||
- 📢 **Public messages** (visible to all players)
|
|
||||||
- 🔀 **Mixed messages** (public action + secret motive)
|
|
||||||
- 🎭 **Real-time broadcasting** to appropriate audiences
|
|
||||||
- 🤖 **Multi-LLM support** (OpenAI + OpenRouter)
|
|
||||||
|
|
||||||
**The foundation is solid.** The message system works as designed, and the architecture supports the remaining MVP phases. Next session should focus on database persistence and character profiles to make the app truly shine.
|
|
||||||
|
|
||||||
**Great work finishing the MVP!** 🚀
|
|
||||||
71
README.md
71
README.md
@@ -4,13 +4,23 @@ A storyteller-centric roleplaying application where characters communicate **pri
|
|||||||
|
|
||||||
## ✨ Key Features
|
## ✨ Key Features
|
||||||
|
|
||||||
|
### Core Features
|
||||||
- **🔒 Private Character-Storyteller Communication**: Each character has a completely isolated conversation with the storyteller - no character can see what others are saying or receiving
|
- **🔒 Private Character-Storyteller Communication**: Each character has a completely isolated conversation with the storyteller - no character can see what others are saying or receiving
|
||||||
|
- **📢 Flexible Messaging System**: Private, public, or mixed messages for different roleplay scenarios
|
||||||
- **🎲 Storyteller-Centric Workflow**: The storyteller sees all character messages and responds to each individually
|
- **🎲 Storyteller-Centric Workflow**: The storyteller sees all character messages and responds to each individually
|
||||||
- **🤖 Multiple LLM Support**: Each character can use a different AI model (GPT-4, Claude, Llama, Gemini, Mistral, etc.) via OpenRouter or OpenAI
|
- **🧠 Context-Aware AI**: Generate responses considering multiple characters' actions simultaneously
|
||||||
- **📜 Scene Narration**: Storyteller can broadcast scene descriptions visible to all characters
|
- **🎮 Demo Session**: Pre-loaded "Cursed Tavern" adventure with two characters for instant testing
|
||||||
- **🧠 Isolated Memory Sessions**: Each character maintains their own separate conversation history with the storyteller
|
|
||||||
|
### AI & LLM Support
|
||||||
|
- **🤖 Multiple LLM Support**: GPT-4o, GPT-4, GPT-3.5, Claude, Llama, Gemini, Mistral (100+ models via OpenRouter)
|
||||||
|
- **✨ AI-Assisted Responses**: Get AI suggestions for storyteller responses
|
||||||
|
- **🎯 Smart Context Building**: AI considers character profiles, personalities, and conversation history
|
||||||
|
|
||||||
|
### Technical Features
|
||||||
- **⚡ Real-time WebSocket Communication**: Instant message delivery
|
- **⚡ Real-time WebSocket Communication**: Instant message delivery
|
||||||
|
- **🧠 Isolated Memory Sessions**: Each character maintains their own separate conversation history
|
||||||
- **🎨 Modern, Beautiful UI**: Clean, intuitive interface with gradient themes
|
- **🎨 Modern, Beautiful UI**: Clean, intuitive interface with gradient themes
|
||||||
|
- **📱 Responsive Design**: Works on desktop, tablet, and mobile
|
||||||
|
|
||||||
## 🎯 How It Works
|
## 🎯 How It Works
|
||||||
|
|
||||||
@@ -69,27 +79,51 @@ A storyteller-centric roleplaying application where characters communicate **pri
|
|||||||
npm install
|
npm install
|
||||||
```
|
```
|
||||||
|
|
||||||
## Running the Application
|
## 🚀 Quick Start
|
||||||
|
|
||||||
### Start the Backend
|
### Easy Start (Recommended)
|
||||||
|
|
||||||
From the project root directory:
|
Use the startup script to launch both backend and frontend:
|
||||||
|
|
||||||
|
**Linux/Mac:**
|
||||||
|
```bash
|
||||||
|
bash start.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
**Windows:**
|
||||||
|
```bash
|
||||||
|
start.bat
|
||||||
|
```
|
||||||
|
|
||||||
|
This will:
|
||||||
|
1. Start the FastAPI backend on `http://localhost:8000`
|
||||||
|
2. Start the React frontend on `http://localhost:3000`
|
||||||
|
3. Create a demo session automatically
|
||||||
|
4. Open your browser
|
||||||
|
|
||||||
|
### Demo Session 🎲
|
||||||
|
|
||||||
|
A pre-configured "Cursed Tavern" adventure is automatically created with:
|
||||||
|
- **Session ID:** `demo-session-001`
|
||||||
|
- **Characters:** Bargin (Dwarf Warrior) & Willow (Elf Ranger)
|
||||||
|
- **Quick-access buttons** on the home page
|
||||||
|
|
||||||
|
Just click a button and start playing!
|
||||||
|
|
||||||
|
### Manual Start
|
||||||
|
|
||||||
|
If you prefer to run services separately:
|
||||||
|
|
||||||
|
**Backend:**
|
||||||
```bash
|
```bash
|
||||||
uvicorn main:app --reload
|
uvicorn main:app --reload
|
||||||
```
|
```
|
||||||
|
|
||||||
The backend will be available at `http://localhost:8000`
|
**Frontend:**
|
||||||
|
|
||||||
### Start the Frontend
|
|
||||||
|
|
||||||
In a new terminal, navigate to the frontend directory and run:
|
|
||||||
```bash
|
```bash
|
||||||
cd frontend
|
cd frontend && npm start
|
||||||
npm start
|
|
||||||
```
|
```
|
||||||
|
|
||||||
The frontend will open in your default browser at `http://localhost:3000`
|
|
||||||
|
|
||||||
## 🎮 How to Use
|
## 🎮 How to Use
|
||||||
|
|
||||||
### As the Storyteller
|
### As the Storyteller
|
||||||
@@ -184,10 +218,15 @@ Each character has a **completely isolated** conversation with the storyteller:
|
|||||||
|
|
||||||
All project documentation is organized in the [`docs/`](./docs/) folder:
|
All project documentation is organized in the [`docs/`](./docs/) folder:
|
||||||
|
|
||||||
|
### Quick Links
|
||||||
|
- **[Features Guide](./docs/features/)** - All features with examples and guides
|
||||||
|
- [Demo Session](./docs/features/DEMO_SESSION.md)
|
||||||
|
- [Context-Aware Responses](./docs/features/CONTEXTUAL_RESPONSE_FEATURE.md)
|
||||||
|
- [Bug Fixes Summary](./docs/features/FIXES_SUMMARY.md)
|
||||||
- **[Setup Guides](./docs/setup/)** - Quick start and installation
|
- **[Setup Guides](./docs/setup/)** - Quick start and installation
|
||||||
- **[Planning](./docs/planning/)** - Roadmaps and feature plans
|
- **[Planning](./docs/planning/)** - Roadmaps and feature plans
|
||||||
- **[Reference](./docs/reference/)** - Technical guides and file references
|
- **[Reference](./docs/reference/)** - Technical guides and file references
|
||||||
- **[Development](./docs/development/)** - Session notes and implementation details
|
- **[Development](./docs/development/)** - Testing and implementation details
|
||||||
|
|
||||||
See [docs/README.md](./docs/README.md) for the complete documentation index.
|
See [docs/README.md](./docs/README.md) for the complete documentation index.
|
||||||
|
|
||||||
|
|||||||
@@ -1,437 +0,0 @@
|
|||||||
# 🎉 Development Session Summary
|
|
||||||
|
|
||||||
**Date:** October 11, 2025
|
|
||||||
**Duration:** ~2 hours
|
|
||||||
**Branch:** mvp-phase-02
|
|
||||||
**Status:** ✅ Highly Productive - Phase 1 Complete + Tests Added
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 Major Accomplishments
|
|
||||||
|
|
||||||
### 1. ✅ Phase 1 MVP Implementation (Complete!)
|
|
||||||
|
|
||||||
#### Enhanced Message System
|
|
||||||
Implemented the **core differentiating feature** of the application:
|
|
||||||
|
|
||||||
**Three Message Types:**
|
|
||||||
- **🔒 Private Messages** - Character ↔ Storyteller only
|
|
||||||
- **📢 Public Messages** - Visible to all players (action feed)
|
|
||||||
- **🔀 Mixed Messages** - Public action + secret motive
|
|
||||||
|
|
||||||
**Example Use Case:**
|
|
||||||
```
|
|
||||||
Player sends mixed message:
|
|
||||||
Public: "I shake hands with the merchant warmly"
|
|
||||||
Private: "While shaking, I try to pickpocket his coin purse"
|
|
||||||
|
|
||||||
Result:
|
|
||||||
- All players see: "I shake hands with the merchant"
|
|
||||||
- Only storyteller sees: "I try to pickpocket his coin purse"
|
|
||||||
```
|
|
||||||
|
|
||||||
**Implementation:**
|
|
||||||
- Updated backend `Message` model with visibility fields
|
|
||||||
- Added `public_messages` array to `GameSession`
|
|
||||||
- WebSocket routing for all message types
|
|
||||||
- Frontend message composer with type selector
|
|
||||||
- Separate public/private message displays
|
|
||||||
|
|
||||||
#### AI-Assisted Responses (Quick Win)
|
|
||||||
- Added "✨ AI Suggest" button in storyteller interface
|
|
||||||
- Generates contextual responses using character's LLM
|
|
||||||
- Editable before sending
|
|
||||||
- Visual loading state
|
|
||||||
|
|
||||||
### 2. ✅ Comprehensive Test Suite (88.9% Pass Rate)
|
|
||||||
|
|
||||||
Created 54 tests across 3 test files:
|
|
||||||
|
|
||||||
#### test_models.py (25 tests - ✅ 100% pass)
|
|
||||||
- Message creation and validation
|
|
||||||
- Character model testing
|
|
||||||
- GameSession functionality
|
|
||||||
- Message visibility logic
|
|
||||||
- Character isolation verification
|
|
||||||
|
|
||||||
#### test_api.py (23 tests - ✅ 100% pass)
|
|
||||||
- Session CRUD endpoints
|
|
||||||
- Character management
|
|
||||||
- Available models endpoint
|
|
||||||
- Error handling (404s)
|
|
||||||
- State persistence
|
|
||||||
|
|
||||||
#### test_websockets.py (23 tests - ⚠️ 74% pass)
|
|
||||||
- WebSocket connections ✅
|
|
||||||
- Message routing ⚠️ (6 async tests fail - TestClient limitation)
|
|
||||||
- Storyteller responses ⚠️
|
|
||||||
- Scene narration ⚠️
|
|
||||||
- Connection management ✅
|
|
||||||
|
|
||||||
**Coverage:** 78% (171/219 statements)
|
|
||||||
|
|
||||||
**Test Quality:**
|
|
||||||
- All critical paths tested
|
|
||||||
- Error handling validated
|
|
||||||
- Character isolation confirmed
|
|
||||||
- Message visibility verified
|
|
||||||
|
|
||||||
### 3. 📚 Documentation Created
|
|
||||||
|
|
||||||
Created comprehensive documentation:
|
|
||||||
|
|
||||||
1. **CURRENT_STATUS.md** - Complete feature overview
|
|
||||||
2. **MVP_PROGRESS.md** - Detailed progress tracking
|
|
||||||
3. **TESTING_GUIDE.md** - Manual test scenarios
|
|
||||||
4. **TEST_RESULTS.md** - Test suite analysis
|
|
||||||
5. **SESSION_SUMMARY.md** - This document
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 Statistics
|
|
||||||
|
|
||||||
### Code Changes
|
|
||||||
- **Files Modified:** 7
|
|
||||||
- **Lines Added:** 1,398+
|
|
||||||
- **Backend Changes:** `main.py` (message system)
|
|
||||||
- **Frontend Changes:** `CharacterView.js`, `StorytellerView.js`
|
|
||||||
- **CSS Added:** Public/private message styling
|
|
||||||
- **Tests Added:** 54 comprehensive tests
|
|
||||||
|
|
||||||
### Test Results
|
|
||||||
- **Total Tests:** 54
|
|
||||||
- **Passed:** 48 (88.9%)
|
|
||||||
- **Failed:** 6 (WebSocket async - known limitation)
|
|
||||||
- **Coverage:** 78%
|
|
||||||
- **Status:** ✅ Production ready
|
|
||||||
|
|
||||||
### Features Completed
|
|
||||||
- ✅ Private messages
|
|
||||||
- ✅ Public messages
|
|
||||||
- ✅ Mixed messages
|
|
||||||
- ✅ AI-assisted responses
|
|
||||||
- ✅ Public action feed
|
|
||||||
- ✅ Message type selector
|
|
||||||
- ✅ Visual distinction between types
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🛠️ Technical Highlights
|
|
||||||
|
|
||||||
### Backend Architecture
|
|
||||||
```python
|
|
||||||
class Message(BaseModel):
|
|
||||||
visibility: str = "private" # "public", "private", "mixed"
|
|
||||||
public_content: Optional[str] = None
|
|
||||||
private_content: Optional[str] = None
|
|
||||||
|
|
||||||
class GameSession(BaseModel):
|
|
||||||
public_messages: List[Message] = [] # Shared feed
|
|
||||||
```
|
|
||||||
|
|
||||||
### Message Routing Logic
|
|
||||||
```
|
|
||||||
Private → Character's private history only
|
|
||||||
Public → public_messages feed (broadcast to all)
|
|
||||||
Mixed → Both public_messages AND private history
|
|
||||||
```
|
|
||||||
|
|
||||||
### Frontend Components
|
|
||||||
- Message type selector (dropdown)
|
|
||||||
- Public messages section (highlighted feed)
|
|
||||||
- Private conversation section
|
|
||||||
- Mixed message composer (dual textareas)
|
|
||||||
- AI suggestion button (storyteller only)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎯 MVP Progress
|
|
||||||
|
|
||||||
### Phase 1: Enhanced Message System ✅ COMPLETE
|
|
||||||
- [x] Public/Private/Mixed message types
|
|
||||||
- [x] Message type selector UI
|
|
||||||
- [x] Message filtering logic
|
|
||||||
- [x] WebSocket handling
|
|
||||||
- [x] Public message broadcasting
|
|
||||||
|
|
||||||
### Phase 2: Character Profile System ⏳ NEXT
|
|
||||||
**Target:** 1-2 days
|
|
||||||
|
|
||||||
**Features to Implement:**
|
|
||||||
- Race selection (Human/Elf/Dwarf/Orc/Halfling)
|
|
||||||
- Class selection (Warrior/Wizard/Cleric/Archer/Rogue)
|
|
||||||
- Personality (Friendly/Serious/Doubtful/Measured)
|
|
||||||
- Profile-based LLM prompts
|
|
||||||
- Character import/export (JSON & PNG)
|
|
||||||
- Avatar upload
|
|
||||||
|
|
||||||
**Estimated Time:** 8-12 hours
|
|
||||||
|
|
||||||
### Overall MVP Status
|
|
||||||
- **Phase 1:** ✅ 100%
|
|
||||||
- **Phase 2:** ⏳ 0%
|
|
||||||
- **Phase 3:** ⏳ 0%
|
|
||||||
- **Phase 4:** ⏳ 0%
|
|
||||||
- **Phase 5:** ⏳ 0%
|
|
||||||
- **Phase 6:** ⏳ 0%
|
|
||||||
- **Overall:** ~8% (1/12 weeks)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🐛 Known Issues
|
|
||||||
|
|
||||||
### Minor Issues
|
|
||||||
1. **Pydantic Deprecation Warnings** (10 occurrences)
|
|
||||||
- Fix: Replace `.dict()` with `.model_dump()`
|
|
||||||
- Time: 5 minutes
|
|
||||||
- Priority: Medium
|
|
||||||
|
|
||||||
2. **Character Names in Public Feed**
|
|
||||||
- Public messages don't show which character sent them
|
|
||||||
- Time: 30 minutes
|
|
||||||
- Priority: Medium
|
|
||||||
|
|
||||||
3. **WebSocket Test Failures** (6 tests)
|
|
||||||
- TestClient limitation, not code issue
|
|
||||||
- Production functionality verified
|
|
||||||
- Priority: Low (accept as-is)
|
|
||||||
|
|
||||||
### Future Needs
|
|
||||||
- Database persistence (SQLite → PostgreSQL)
|
|
||||||
- Session authentication
|
|
||||||
- Character profiles (Phase 2)
|
|
||||||
- Game save/load
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📝 Files Changed
|
|
||||||
|
|
||||||
### Backend
|
|
||||||
- `main.py` - Message system, public_messages, routing
|
|
||||||
|
|
||||||
### Frontend
|
|
||||||
- `src/components/CharacterView.js` - Message composer, public feed
|
|
||||||
- `src/components/StorytellerView.js` - AI suggest, public feed
|
|
||||||
- `src/App.css` - Public/private message styling
|
|
||||||
|
|
||||||
### Tests
|
|
||||||
- `tests/test_models.py` - Model validation (25 tests)
|
|
||||||
- `tests/test_api.py` - API endpoints (23 tests)
|
|
||||||
- `tests/test_websockets.py` - WebSocket functionality (23 tests)
|
|
||||||
- `pytest.ini` - Test configuration
|
|
||||||
- `requirements.txt` - Added pytest dependencies
|
|
||||||
|
|
||||||
### Documentation
|
|
||||||
- `CURRENT_STATUS.md` - Feature overview
|
|
||||||
- `MVP_PROGRESS.md` - Progress tracking
|
|
||||||
- `TESTING_GUIDE.md` - Test scenarios
|
|
||||||
- `TEST_RESULTS.md` - Test analysis
|
|
||||||
- `SESSION_SUMMARY.md` - This file
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎓 What We Learned
|
|
||||||
|
|
||||||
### Technical Insights
|
|
||||||
1. **Message Visibility is Key** - The public/private/mixed system is what makes this RPG app unique
|
|
||||||
2. **WebSocket Testing is Hard** - TestClient has async limitations; integration tests needed
|
|
||||||
3. **Pydantic V2 Changes** - Need to update `.dict()` to `.model_dump()`
|
|
||||||
4. **Test-First Approach** - Having tests before Phase 2 will speed development
|
|
||||||
|
|
||||||
### Design Decisions
|
|
||||||
1. **Three Message Types** - Simple but powerful system
|
|
||||||
2. **Separate Feeds** - Public messages in their own feed vs private conversation
|
|
||||||
3. **Mixed Messages** - Most interesting feature for dramatic gameplay
|
|
||||||
4. **AI Suggestions** - Quick win that adds huge value
|
|
||||||
|
|
||||||
### Best Practices Applied
|
|
||||||
- Comprehensive unit tests
|
|
||||||
- Clear documentation
|
|
||||||
- Git commit messages
|
|
||||||
- Code coverage tracking
|
|
||||||
- Error handling validation
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ✅ Definition of Done
|
|
||||||
|
|
||||||
### Phase 1 Checklist
|
|
||||||
- [x] Message visibility fields added to models
|
|
||||||
- [x] Public messages feed implemented
|
|
||||||
- [x] WebSocket routing for all message types
|
|
||||||
- [x] Frontend message type selector
|
|
||||||
- [x] Public/private message displays
|
|
||||||
- [x] AI suggestion button
|
|
||||||
- [x] Visual distinction between types
|
|
||||||
- [x] Tests written (88.9% pass rate)
|
|
||||||
- [x] Documentation complete
|
|
||||||
- [x] Code committed to git
|
|
||||||
|
|
||||||
**Phase 1 Status:** ✅ **COMPLETE**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 Next Session Priorities
|
|
||||||
|
|
||||||
### Immediate (Start of Next Session)
|
|
||||||
|
|
||||||
1. **Fix Pydantic Warnings** (5 minutes)
|
|
||||||
```python
|
|
||||||
# Replace in main.py
|
|
||||||
msg.dict() → msg.model_dump()
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Add Character Names to Public Feed** (30 minutes)
|
|
||||||
- Include character name in public message broadcasts
|
|
||||||
- Display: "Gandalf: I wave to the group"
|
|
||||||
|
|
||||||
### Phase 2 Implementation (Main Work)
|
|
||||||
|
|
||||||
3. **Character Profile Models** (2 hours)
|
|
||||||
- Add gender, race, class, personality fields
|
|
||||||
- Create profile prompt templates
|
|
||||||
- Update Character model
|
|
||||||
|
|
||||||
4. **Character Creation Wizard** (4 hours)
|
|
||||||
- Multi-step form UI
|
|
||||||
- Dropdown selectors
|
|
||||||
- Profile preview
|
|
||||||
- Custom prompts section
|
|
||||||
|
|
||||||
5. **Profile-Based LLM Prompts** (2 hours)
|
|
||||||
- Combine race + class + personality
|
|
||||||
- Inject into character LLM requests
|
|
||||||
- Test with different combinations
|
|
||||||
|
|
||||||
6. **Character Import/Export** (3 hours)
|
|
||||||
- JSON export/import
|
|
||||||
- PNG with metadata (stretch goal)
|
|
||||||
- Profile validation
|
|
||||||
|
|
||||||
7. **Phase 2 Tests** (2 hours)
|
|
||||||
- Test profile creation
|
|
||||||
- Test LLM prompt building
|
|
||||||
- Test import/export
|
|
||||||
- Aim for 80%+ coverage
|
|
||||||
|
|
||||||
**Total Estimated Time for Phase 2:** 12-15 hours (1.5-2 days)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 💡 Recommendations
|
|
||||||
|
|
||||||
### Technical
|
|
||||||
1. ✅ **Tests First Approach** - We have good test coverage now
|
|
||||||
2. 🔄 **Incremental Commits** - Keep committing as features complete
|
|
||||||
3. 📝 **Update Documentation** - Keep docs in sync with code
|
|
||||||
4. 🎯 **One Feature at a Time** - Finish Phase 2 before Phase 3
|
|
||||||
|
|
||||||
### Process
|
|
||||||
1. **Manual Testing** - Test the enhanced message system manually
|
|
||||||
2. **Git Branches** - Stay on `mvp-phase-02` for Phase 2 work
|
|
||||||
3. **Coverage Goals** - Maintain 75%+ test coverage
|
|
||||||
4. **Documentation** - Update MVP_PROGRESS.md as you go
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📈 Success Metrics
|
|
||||||
|
|
||||||
### Achieved Today
|
|
||||||
- ✅ **Phase 1 Complete** - Core feature fully implemented
|
|
||||||
- ✅ **54 Tests Written** - Comprehensive test coverage
|
|
||||||
- ✅ **88.9% Pass Rate** - High quality tests
|
|
||||||
- ✅ **78% Code Coverage** - Excellent for MVP
|
|
||||||
- ✅ **5 Documentation Files** - Well-documented
|
|
||||||
- ✅ **All Committed to Git** - Clean version control
|
|
||||||
|
|
||||||
### Quality Indicators
|
|
||||||
- Zero critical bugs
|
|
||||||
- All core features working
|
|
||||||
- Tests passing for critical paths
|
|
||||||
- Documentation comprehensive
|
|
||||||
- Code reviewed and committed
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎉 Celebration Points!
|
|
||||||
|
|
||||||
**Huge Wins Today:**
|
|
||||||
1. 🎯 **Phase 1 MVP Feature Complete** - The message visibility system works beautifully
|
|
||||||
2. 🧪 **Test Suite Established** - 54 tests give us confidence
|
|
||||||
3. 📚 **Documentation Complete** - Easy to pick up next session
|
|
||||||
4. 🚀 **Production Ready** - Both servers running with new features
|
|
||||||
5. 💪 **Solid Foundation** - Ready for Phase 2 character profiles
|
|
||||||
|
|
||||||
**This is excellent progress!** The enhanced message system is the heart of what makes this RPG app unique. Players can now perform public actions while keeping secrets - exactly what you need for dramatic gameplay.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔮 Looking Ahead
|
|
||||||
|
|
||||||
### Next Session Goals
|
|
||||||
1. Implement Phase 2 (Character Profiles)
|
|
||||||
2. Add race/class/personality system
|
|
||||||
3. Build character creation wizard
|
|
||||||
4. Create profile-based LLM prompts
|
|
||||||
5. Add import/export functionality
|
|
||||||
|
|
||||||
### Future Phases
|
|
||||||
- **Phase 3:** User mode interfaces (Player/Storyteller/Gamemaster)
|
|
||||||
- **Phase 4:** AI automation (AI players & storytellers)
|
|
||||||
- **Phase 5:** Database & game management
|
|
||||||
- **Phase 6:** Polish & testing
|
|
||||||
|
|
||||||
**The MVP roadmap is solid, and we're executing well!**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 Final Stats
|
|
||||||
|
|
||||||
| Metric | Value |
|
|
||||||
|--------|-------|
|
|
||||||
| **Session Duration** | ~2 hours |
|
|
||||||
| **Features Completed** | Phase 1 + AI Suggest + Tests |
|
|
||||||
| **Tests Written** | 54 |
|
|
||||||
| **Test Pass Rate** | 88.9% |
|
|
||||||
| **Code Coverage** | 78% |
|
|
||||||
| **Lines of Code Added** | 1,398+ |
|
|
||||||
| **Files Modified** | 7 |
|
|
||||||
| **Documentation Pages** | 5 |
|
|
||||||
| **Git Commits** | 1 major commit |
|
|
||||||
| **MVP Progress** | 8% → 16% (Phase 1 done!) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ✅ Session Complete!
|
|
||||||
|
|
||||||
**Status:** ✅ **Highly Successful**
|
|
||||||
|
|
||||||
We've completed Phase 1 of the MVP roadmap, added a comprehensive test suite with 88.9% pass rate, and created detailed documentation. The enhanced message system (private/public/mixed) is working perfectly - this is the core feature that makes your RPG app unique.
|
|
||||||
|
|
||||||
**Ready for Phase 2!** 🚀
|
|
||||||
|
|
||||||
The test suite gives us confidence to build character profiles knowing we won't break existing functionality. Great work!
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Commands to Remember:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Run tests
|
|
||||||
.venv/bin/pytest -v
|
|
||||||
|
|
||||||
# Run specific test file
|
|
||||||
.venv/bin/pytest tests/test_models.py -v
|
|
||||||
|
|
||||||
# Run with coverage
|
|
||||||
.venv/bin/pytest --cov=main --cov-report=html
|
|
||||||
|
|
||||||
# Start application
|
|
||||||
bash start.sh
|
|
||||||
|
|
||||||
# Check servers
|
|
||||||
curl http://localhost:8000/docs # Backend API
|
|
||||||
curl http://localhost:3000 # Frontend
|
|
||||||
```
|
|
||||||
|
|
||||||
**Next Session:** Start with character profile system implementation! 🎭
|
|
||||||
168
docs/README.md
168
docs/README.md
@@ -1,66 +1,152 @@
|
|||||||
# 📚 Storyteller RPG - Documentation
|
# 📚 Storyteller RPG Documentation
|
||||||
|
|
||||||
Welcome to the Storyteller RPG documentation. All project documentation is organized here by category.
|
Welcome to the Storyteller RPG documentation hub. All project documentation is organized here for easy navigation.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📁 Documentation Structure
|
## 📂 Documentation Structure
|
||||||
|
|
||||||
### 🚀 [setup/](./setup/)
|
### ✨ [Features](./features/)
|
||||||
**Getting started guides and quick references**
|
|
||||||
|
|
||||||
- **[QUICKSTART.md](./setup/QUICKSTART.md)** - 5-minute quick start guide
|
Comprehensive feature documentation with examples and guides.
|
||||||
- **[QUICK_REFERENCE.md](./setup/QUICK_REFERENCE.md)** - Quick reference for common tasks
|
|
||||||
|
|
||||||
### 📋 [planning/](./planning/)
|
- **[Features Overview](./features/README.md)** - Complete feature catalog
|
||||||
**Product roadmaps and feature planning**
|
- **[Demo Session Guide](./features/DEMO_SESSION.md)** - Using the pre-configured test session
|
||||||
|
- **[Context-Aware Responses](./features/CONTEXTUAL_RESPONSE_FEATURE.md)** - Multi-character AI generation
|
||||||
|
- **[Prompt Engineering](./features/PROMPT_IMPROVEMENTS.md)** - LLM prompt techniques
|
||||||
|
- **[Bug Fixes](./features/FIXES_SUMMARY.md)** - Recent fixes and improvements
|
||||||
|
|
||||||
- **[MVP_ROADMAP.md](./planning/MVP_ROADMAP.md)** - MVP feature requirements and roadmap
|
### 🚀 [Setup Guides](./setup/)
|
||||||
- **[NEXT_STEPS.md](./planning/NEXT_STEPS.md)** - Detailed future development roadmap
|
|
||||||
- **[PROJECT_PLAN.md](./planning/PROJECT_PLAN.md)** - Overall project planning and goals
|
|
||||||
|
|
||||||
### 📖 [reference/](./reference/)
|
Get started quickly with installation and configuration guides.
|
||||||
**Technical references and guides**
|
|
||||||
|
|
||||||
- **[LLM_GUIDE.md](./reference/LLM_GUIDE.md)** - Guide to available LLM models
|
- **[Quickstart Guide](./setup/QUICKSTART.md)** - Step-by-step setup instructions
|
||||||
- **[PROJECT_FILES_REFERENCE.md](./reference/PROJECT_FILES_REFERENCE.md)** - Complete file structure reference
|
- **[Quick Reference](./setup/QUICK_REFERENCE.md)** - Common commands and workflows
|
||||||
|
|
||||||
### 🔧 [development/](./development/)
|
### 📋 [Planning & Roadmap](./planning/)
|
||||||
**Development session notes and implementation details**
|
|
||||||
|
|
||||||
- **[SESSION_SUMMARY.md](./development/SESSION_SUMMARY.md)** - Complete development session summary
|
Project vision, milestones, and future plans.
|
||||||
- **[IMPLEMENTATION_SUMMARY.md](./development/IMPLEMENTATION_SUMMARY.md)** - Technical implementation details
|
|
||||||
|
- **[Project Plan](./planning/PROJECT_PLAN.md)** - Overall project structure and goals
|
||||||
|
- **[MVP Roadmap](./planning/MVP_ROADMAP.md)** - Minimum viable product phases
|
||||||
|
- **[Next Steps](./planning/NEXT_STEPS.md)** - Immediate priorities and tasks
|
||||||
|
|
||||||
|
### 🔧 [Development](./development/)
|
||||||
|
|
||||||
|
Technical implementation details and testing.
|
||||||
|
|
||||||
|
- **[MVP Progress](./development/MVP_PROGRESS.md)** - Current status and achievements
|
||||||
|
- **[Testing Guide](./development/TESTING_GUIDE.md)** - How to test the application
|
||||||
|
- **[Test Results](./development/TEST_RESULTS.md)** - Latest test results
|
||||||
|
|
||||||
|
### 📖 [Reference](./reference/)
|
||||||
|
|
||||||
|
Technical guides and comprehensive references.
|
||||||
|
|
||||||
|
- **[LLM Guide](./reference/LLM_GUIDE.md)** - Working with different AI models
|
||||||
|
- **[Project Files Reference](./reference/PROJECT_FILES_REFERENCE.md)** - Complete file structure
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🎯 Quick Navigation
|
## 🔗 Quick Links
|
||||||
|
|
||||||
**New to the project?**
|
### For New Users
|
||||||
1. Start with the main [README.md](../README.md) in the root directory
|
1. ⚡ Start with [Quickstart Guide](./setup/QUICKSTART.md)
|
||||||
2. Follow [setup/QUICKSTART.md](./setup/QUICKSTART.md) to get running
|
2. 🎮 Try the [Demo Session](./features/DEMO_SESSION.md) (pre-configured!)
|
||||||
3. Review [planning/MVP_ROADMAP.md](./planning/MVP_ROADMAP.md) to understand the vision
|
3. 📖 Review [Features Overview](./features/README.md) to see what's possible
|
||||||
|
4. 🤖 Check [LLM Guide](./reference/LLM_GUIDE.md) for model selection
|
||||||
|
|
||||||
**Want to contribute?**
|
### For Developers
|
||||||
1. Read [development/SESSION_SUMMARY.md](./development/SESSION_SUMMARY.md) for architecture
|
1. 🔧 Read [MVP Progress](./development/MVP_PROGRESS.md) for current state
|
||||||
2. Check [planning/NEXT_STEPS.md](./planning/NEXT_STEPS.md) for feature priorities
|
2. 🧪 Check [Testing Guide](./development/TESTING_GUIDE.md)
|
||||||
3. Refer to [reference/PROJECT_FILES_REFERENCE.md](./reference/PROJECT_FILES_REFERENCE.md) for code navigation
|
3. 📁 Review [Project Files Reference](./reference/PROJECT_FILES_REFERENCE.md)
|
||||||
|
4. 🚀 Follow [Next Steps](./planning/NEXT_STEPS.md) for contribution areas
|
||||||
|
|
||||||
**Looking for specific info?**
|
### For Storytellers
|
||||||
- **Setup/Installation** → [setup/](./setup/)
|
1. 🎭 See [Features Guide](./features/README.md) for all tools
|
||||||
- **Features & Roadmap** → [planning/](./planning/)
|
2. 🧠 Learn about [Context-Aware Responses](./features/CONTEXTUAL_RESPONSE_FEATURE.md)
|
||||||
- **API/Models/Files** → [reference/](./reference/)
|
3. 💡 Use [Quick Reference](./setup/QUICK_REFERENCE.md) for common tasks
|
||||||
- **Architecture** → [development/](./development/)
|
4. 🎲 Start with [Demo Session](./features/DEMO_SESSION.md) for practice
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 📊 Documentation Overview
|
## 📊 Current Status (v0.2.0)
|
||||||
|
|
||||||
| Category | Files | Purpose |
|
### ✅ Completed Features
|
||||||
|----------|-------|---------|
|
- Private/public/mixed messaging system
|
||||||
| **Setup** | 2 | Getting started and quick references |
|
- Context-aware AI response generator
|
||||||
| **Planning** | 3 | Roadmaps, feature plans, project goals |
|
- Demo session with pre-configured characters
|
||||||
| **Reference** | 2 | Technical guides and file references |
|
- Real-time WebSocket communication
|
||||||
| **Development** | 2 | Session notes and implementation details |
|
- Multi-LLM support (GPT-4o, Claude, Llama, etc.)
|
||||||
|
- AI-assisted storyteller suggestions
|
||||||
|
- Session ID quick copy
|
||||||
|
- Full conversation history
|
||||||
|
|
||||||
|
### 🚧 Coming Soon
|
||||||
|
- Database persistence
|
||||||
|
- Character sheets & stats
|
||||||
|
- Dice rolling mechanics
|
||||||
|
- Combat system
|
||||||
|
- Image generation
|
||||||
|
- Voice messages
|
||||||
|
|
||||||
|
See [MVP Roadmap](./planning/MVP_ROADMAP.md) for the complete timeline.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📝 Documentation Principles
|
||||||
|
|
||||||
|
This documentation follows these principles:
|
||||||
|
|
||||||
|
- **Progressive Disclosure**: Start simple, dive deeper as needed
|
||||||
|
- **Always Current**: Updated with each feature implementation
|
||||||
|
- **Example-Driven**: Real code examples and use cases
|
||||||
|
- **Clear Structure**: Logical organization for easy navigation
|
||||||
|
- **Feature-Focused**: Detailed guides for every feature
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Documentation Map
|
||||||
|
|
||||||
|
```
|
||||||
|
docs/
|
||||||
|
├── features/ ← Feature guides & examples
|
||||||
|
│ ├── README.md
|
||||||
|
│ ├── DEMO_SESSION.md
|
||||||
|
│ ├── CONTEXTUAL_RESPONSE_FEATURE.md
|
||||||
|
│ ├── PROMPT_IMPROVEMENTS.md
|
||||||
|
│ └── FIXES_SUMMARY.md
|
||||||
|
├── setup/ ← Installation & quick start
|
||||||
|
│ ├── QUICKSTART.md
|
||||||
|
│ └── QUICK_REFERENCE.md
|
||||||
|
├── planning/ ← Roadmap & future plans
|
||||||
|
│ ├── PROJECT_PLAN.md
|
||||||
|
│ ├── MVP_ROADMAP.md
|
||||||
|
│ └── NEXT_STEPS.md
|
||||||
|
├── development/ ← Technical & testing docs
|
||||||
|
│ ├── MVP_PROGRESS.md
|
||||||
|
│ ├── TESTING_GUIDE.md
|
||||||
|
│ └── TEST_RESULTS.md
|
||||||
|
└── reference/ ← Technical references
|
||||||
|
├── LLM_GUIDE.md
|
||||||
|
└── PROJECT_FILES_REFERENCE.md
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🤝 Contributing to Documentation
|
||||||
|
|
||||||
|
Found a typo or want to improve the docs? Contributions are welcome!
|
||||||
|
|
||||||
|
1. Documentation lives in the `docs/` folder
|
||||||
|
2. Use clear, concise language
|
||||||
|
3. Include examples where helpful
|
||||||
|
4. Keep formatting consistent
|
||||||
|
5. Update relevant indexes when adding new docs
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Need help?** Start with the [Quickstart Guide](./setup/QUICKSTART.md) or check the main [README](../README.md).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -1,126 +0,0 @@
|
|||||||
# Implementation Summary
|
|
||||||
|
|
||||||
## ✅ Completed Features
|
|
||||||
|
|
||||||
### Backend (`main.py`)
|
|
||||||
- **Isolated Character Sessions**: Each character has a separate conversation history that only they and the storyteller can see
|
|
||||||
- **Private WebSocket Channels**:
|
|
||||||
- `/ws/character/{session_id}/{character_id}` - Character's private connection
|
|
||||||
- `/ws/storyteller/{session_id}` - Storyteller's master connection
|
|
||||||
- **Message Routing**: Messages flow privately between storyteller and individual characters
|
|
||||||
- **Scene Broadcasting**: Storyteller can narrate scenes visible to all characters
|
|
||||||
- **Real-time Updates**: WebSocket events for character joins, messages, and responses
|
|
||||||
- **Pending Response Tracking**: System tracks which characters are waiting for storyteller responses
|
|
||||||
- **AI Suggestions** (Optional): Endpoint for AI-assisted storyteller response generation
|
|
||||||
|
|
||||||
### Frontend Components
|
|
||||||
|
|
||||||
#### 1. **SessionSetup.js**
|
|
||||||
- Create new session (storyteller)
|
|
||||||
- Join existing session (character)
|
|
||||||
- Character creation with name, description, and personality
|
|
||||||
- Beautiful gradient UI with modern styling
|
|
||||||
|
|
||||||
#### 2. **CharacterView.js**
|
|
||||||
- Private chat interface with storyteller
|
|
||||||
- Real-time message delivery via WebSocket
|
|
||||||
- Scene narration display
|
|
||||||
- Conversation history preservation
|
|
||||||
- Connection status indicator
|
|
||||||
|
|
||||||
#### 3. **StorytellerView.js**
|
|
||||||
- Dashboard showing all characters
|
|
||||||
- Character list with pending response indicators
|
|
||||||
- Click character to view their private conversation
|
|
||||||
- Individual response system for each character
|
|
||||||
- Scene narration broadcast to all characters
|
|
||||||
- Visual indicators for pending messages
|
|
||||||
|
|
||||||
### Styling (`App.css`)
|
|
||||||
- Modern gradient theme (purple/blue)
|
|
||||||
- Responsive design
|
|
||||||
- Smooth animations and transitions
|
|
||||||
- Clear visual hierarchy
|
|
||||||
- Mobile-friendly layout
|
|
||||||
|
|
||||||
### Documentation
|
|
||||||
- **README.md**: Comprehensive guide with architecture, features, and API docs
|
|
||||||
- **QUICKSTART.md**: Fast setup and testing guide
|
|
||||||
- **.env.example**: Environment variable template
|
|
||||||
|
|
||||||
## 🔐 Privacy Implementation
|
|
||||||
|
|
||||||
The core requirement - **isolated character sessions** - is implemented through:
|
|
||||||
|
|
||||||
1. **Separate Data Structures**: Each character has `conversation_history: List[Message]`
|
|
||||||
2. **WebSocket Isolation**: Separate WebSocket connections per character
|
|
||||||
3. **Message Routing**: Messages only sent to intended recipient
|
|
||||||
4. **Storyteller View**: Only storyteller can see all conversations
|
|
||||||
5. **Scene Broadcast**: Shared narrations go to all, but conversations stay private
|
|
||||||
|
|
||||||
## 🎯 Workflow
|
|
||||||
|
|
||||||
```
|
|
||||||
Character A → Storyteller: "I search the room"
|
|
||||||
Character B → Storyteller: "I attack the guard"
|
|
||||||
↓
|
|
||||||
Storyteller sees both messages separately
|
|
||||||
↓
|
|
||||||
Storyteller → Character A: "You find a hidden key"
|
|
||||||
Storyteller → Character B: "You miss your swing"
|
|
||||||
↓
|
|
||||||
Character A only sees their conversation
|
|
||||||
Character B only sees their conversation
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📁 File Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
windsurf-project/
|
|
||||||
├── main.py # FastAPI backend with WebSocket support
|
|
||||||
├── requirements.txt # Python dependencies
|
|
||||||
├── .env.example # Environment template
|
|
||||||
├── README.md # Full documentation
|
|
||||||
├── QUICKSTART.md # Quick start guide
|
|
||||||
├── IMPLEMENTATION_SUMMARY.md # This file
|
|
||||||
└── frontend/
|
|
||||||
├── package.json
|
|
||||||
└── src/
|
|
||||||
├── App.js # Main app router
|
|
||||||
├── App.css # All styling
|
|
||||||
└── components/
|
|
||||||
├── SessionSetup.js # Session creation/join
|
|
||||||
├── CharacterView.js # Character interface
|
|
||||||
└── StorytellerView.js # Storyteller dashboard
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🚀 To Run
|
|
||||||
|
|
||||||
**Backend:**
|
|
||||||
```bash
|
|
||||||
python main.py
|
|
||||||
```
|
|
||||||
|
|
||||||
**Frontend:**
|
|
||||||
```bash
|
|
||||||
cd frontend && npm start
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎨 Design Decisions
|
|
||||||
|
|
||||||
1. **WebSocket over REST**: Real-time bidirectional communication required for instant message delivery
|
|
||||||
2. **In-Memory Storage**: Simple session management; can be replaced with database for production
|
|
||||||
3. **Component-Based Frontend**: Separate views for different roles (setup, character, storyteller)
|
|
||||||
4. **Message Model**: Includes sender, content, timestamp for rich conversation history
|
|
||||||
5. **Pending Response Flag**: Helps storyteller track which characters need attention
|
|
||||||
|
|
||||||
## 🔮 Future Enhancements
|
|
||||||
|
|
||||||
- Database persistence (PostgreSQL/MongoDB)
|
|
||||||
- User authentication
|
|
||||||
- Character sheets with stats
|
|
||||||
- Dice rolling system
|
|
||||||
- Voice/audio support
|
|
||||||
- Mobile apps
|
|
||||||
- Multi-storyteller support
|
|
||||||
- Group chat rooms (for party discussions)
|
|
||||||
@@ -1,502 +0,0 @@
|
|||||||
# 📝 Development Session Summary
|
|
||||||
|
|
||||||
**Date:** October 11, 2025
|
|
||||||
**Project:** Storyteller RPG Application
|
|
||||||
**Status:** ✅ Fully Functional MVP Complete
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎯 Project Overview
|
|
||||||
|
|
||||||
Built a **storyteller-centric roleplaying application** where multiple AI character bots or human players interact with a storyteller through **completely isolated, private conversations**.
|
|
||||||
|
|
||||||
### Core Concept
|
|
||||||
- **Characters communicate ONLY with the storyteller** (never with each other by default)
|
|
||||||
- **Each character has separate memory/LLM sessions** - their responses are isolated
|
|
||||||
- **Storyteller sees all conversations** but responds to each character individually
|
|
||||||
- **Characters cannot see other characters' messages or responses**
|
|
||||||
- Characters can use **different AI models** (GPT-4, Claude, Llama, etc.) giving each unique personalities
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🏗️ Architecture Built
|
|
||||||
|
|
||||||
### Backend: FastAPI + WebSockets
|
|
||||||
**File:** `/home/aodhan/projects/apps/storyteller/main.py` (398 lines)
|
|
||||||
|
|
||||||
**Key Components:**
|
|
||||||
1. **Data Models:**
|
|
||||||
- `GameSession` - Manages the game session and all characters
|
|
||||||
- `Character` - Stores character info, LLM model, and private conversation history
|
|
||||||
- `Message` - Individual message with sender, content, timestamp
|
|
||||||
- `ConnectionManager` - Handles WebSocket connections
|
|
||||||
|
|
||||||
2. **WebSocket Endpoints:**
|
|
||||||
- `/ws/character/{session_id}/{character_id}` - Private character connection
|
|
||||||
- `/ws/storyteller/{session_id}` - Storyteller dashboard connection
|
|
||||||
|
|
||||||
3. **REST Endpoints:**
|
|
||||||
- `POST /sessions/` - Create new game session
|
|
||||||
- `GET /sessions/{session_id}` - Get session details
|
|
||||||
- `POST /sessions/{session_id}/characters/` - Add character to session
|
|
||||||
- `GET /sessions/{session_id}/characters/{character_id}/conversation` - Get conversation history
|
|
||||||
- `POST /sessions/{session_id}/generate_suggestion` - AI-assisted storyteller responses
|
|
||||||
- `GET /models` - List available LLM models
|
|
||||||
|
|
||||||
4. **LLM Integration:**
|
|
||||||
- **OpenAI**: GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo
|
|
||||||
- **OpenRouter**: Claude 3.5, Llama 3.1, Gemini Pro, Mistral, Cohere, 100+ models
|
|
||||||
- `call_llm()` function routes to appropriate provider based on model ID
|
|
||||||
- Each character can use a different model
|
|
||||||
|
|
||||||
5. **Message Flow:**
|
|
||||||
```
|
|
||||||
Character sends message → WebSocket → Stored in Character.conversation_history
|
|
||||||
↓
|
|
||||||
Forwarded to Storyteller
|
|
||||||
↓
|
|
||||||
Storyteller responds → WebSocket → Stored in Character.conversation_history
|
|
||||||
↓
|
|
||||||
Sent ONLY to that Character
|
|
||||||
```
|
|
||||||
|
|
||||||
### Frontend: React
|
|
||||||
**Files:**
|
|
||||||
- `frontend/src/App.js` - Main router component
|
|
||||||
- `frontend/src/components/SessionSetup.js` (180 lines) - Session creation/joining
|
|
||||||
- `frontend/src/components/CharacterView.js` (141 lines) - Character interface
|
|
||||||
- `frontend/src/components/StorytellerView.js` (243 lines) - Storyteller dashboard
|
|
||||||
- `frontend/src/App.css` (704 lines) - Complete styling
|
|
||||||
|
|
||||||
**Key Features:**
|
|
||||||
1. **SessionSetup Component:**
|
|
||||||
- Create new session (becomes storyteller)
|
|
||||||
- Join existing session (becomes character)
|
|
||||||
- Select LLM model for character
|
|
||||||
- Model selector fetches available models from backend
|
|
||||||
|
|
||||||
2. **CharacterView Component:**
|
|
||||||
- Private conversation with storyteller
|
|
||||||
- WebSocket connection for real-time updates
|
|
||||||
- See scene narrations from storyteller
|
|
||||||
- Character info display (name, description, personality)
|
|
||||||
- Connection status indicator
|
|
||||||
|
|
||||||
3. **StorytellerView Component:**
|
|
||||||
- Dashboard showing all characters
|
|
||||||
- Click character to view their private conversation
|
|
||||||
- Respond to characters individually
|
|
||||||
- Narrate scenes visible to all characters
|
|
||||||
- Pending response indicators (red badges)
|
|
||||||
- Character cards showing:
|
|
||||||
- Name, description, personality
|
|
||||||
- LLM model being used
|
|
||||||
- Message count
|
|
||||||
- Pending status
|
|
||||||
|
|
||||||
4. **UI/UX Design:**
|
|
||||||
- Beautiful gradient purple theme
|
|
||||||
- Responsive design
|
|
||||||
- Real-time message updates
|
|
||||||
- Auto-scroll to latest messages
|
|
||||||
- Clear visual distinction between sent/received messages
|
|
||||||
- Session ID prominently displayed for sharing
|
|
||||||
- Empty states with helpful instructions
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔑 Key Technical Decisions
|
|
||||||
|
|
||||||
### 1. **Isolated Conversations (Privacy-First)**
|
|
||||||
- Each `Character` object has its own `conversation_history: List[Message]`
|
|
||||||
- Messages are never broadcast to all clients
|
|
||||||
- WebSocket routing ensures messages only go to intended recipient
|
|
||||||
- Storyteller has separate WebSocket endpoint to see all
|
|
||||||
|
|
||||||
### 2. **Multi-LLM Support**
|
|
||||||
- Characters choose model at creation time
|
|
||||||
- Stored in `Character.llm_model` field
|
|
||||||
- Backend dynamically routes API calls based on model prefix:
|
|
||||||
- `gpt-*` → OpenAI API
|
|
||||||
- Everything else → OpenRouter API
|
|
||||||
- Enables creative gameplay with different AI personalities
|
|
||||||
|
|
||||||
### 3. **In-Memory Storage (Current)**
|
|
||||||
- `sessions: Dict[str, GameSession]` stores all active sessions
|
|
||||||
- Fast and simple for MVP
|
|
||||||
- **Limitation:** Data lost on server restart
|
|
||||||
- **Next step:** Add database persistence (see NEXT_STEPS.md)
|
|
||||||
|
|
||||||
### 4. **WebSocket-First Architecture**
|
|
||||||
- Real-time bidirectional communication
|
|
||||||
- Native WebSocket API (not socket.io)
|
|
||||||
- JSON message format with `type` field for routing
|
|
||||||
- Separate connections for characters and storyteller
|
|
||||||
|
|
||||||
### 5. **Scene Narration System**
|
|
||||||
- Storyteller can broadcast "scene" messages
|
|
||||||
- Sent to all connected characters simultaneously
|
|
||||||
- Stored in `GameSession.current_scene` and `scene_history`
|
|
||||||
- Different from private character-storyteller messages
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📁 Project Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
storyteller/
|
|
||||||
├── main.py # FastAPI backend (398 lines)
|
|
||||||
├── requirements.txt # Python dependencies
|
|
||||||
├── .env.example # API key template
|
|
||||||
├── .env # Your API keys (gitignored)
|
|
||||||
├── README.md # Comprehensive documentation
|
|
||||||
├── QUICKSTART.md # 5-minute setup guide
|
|
||||||
├── NEXT_STEPS.md # Future development roadmap
|
|
||||||
├── SESSION_SUMMARY.md # This file
|
|
||||||
├── start.sh # Auto-start script
|
|
||||||
├── dev.sh # Development mode script
|
|
||||||
└── frontend/
|
|
||||||
├── package.json # Node dependencies
|
|
||||||
├── public/
|
|
||||||
│ └── index.html # HTML template
|
|
||||||
└── src/
|
|
||||||
├── App.js # Main router
|
|
||||||
├── App.css # All styles (704 lines)
|
|
||||||
├── index.js # React entry point
|
|
||||||
└── components/
|
|
||||||
├── SessionSetup.js # Session creation/joining
|
|
||||||
├── CharacterView.js # Character interface
|
|
||||||
└── StorytellerView.js # Storyteller dashboard
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 How to Run
|
|
||||||
|
|
||||||
### Quick Start (Automated)
|
|
||||||
```bash
|
|
||||||
cd /home/aodhan/projects/apps/storyteller
|
|
||||||
chmod +x start.sh
|
|
||||||
./start.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
### Manual Start
|
|
||||||
```bash
|
|
||||||
# Terminal 1 - Backend
|
|
||||||
cd /home/aodhan/projects/apps/storyteller
|
|
||||||
source .venv/bin/activate # or: source venv/bin/activate
|
|
||||||
python main.py
|
|
||||||
|
|
||||||
# Terminal 2 - Frontend
|
|
||||||
cd /home/aodhan/projects/apps/storyteller/frontend
|
|
||||||
npm start
|
|
||||||
```
|
|
||||||
|
|
||||||
### Environment Setup
|
|
||||||
```bash
|
|
||||||
# Copy example and add your API keys
|
|
||||||
cp .env.example .env
|
|
||||||
|
|
||||||
# Edit .env and add at least one:
|
|
||||||
# OPENAI_API_KEY=sk-... # For GPT models
|
|
||||||
# OPENROUTER_API_KEY=sk-... # For Claude, Llama, etc.
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔍 Important Implementation Details
|
|
||||||
|
|
||||||
### WebSocket Message Types
|
|
||||||
|
|
||||||
**Character → Storyteller:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"type": "message",
|
|
||||||
"content": "I search the room for clues"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Storyteller → Character:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"type": "storyteller_response",
|
|
||||||
"message": {
|
|
||||||
"id": "...",
|
|
||||||
"sender": "storyteller",
|
|
||||||
"content": "You find a hidden letter",
|
|
||||||
"timestamp": "2025-10-11T20:30:00"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Storyteller → All Characters:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"type": "narrate_scene",
|
|
||||||
"content": "The room grows dark as thunder rumbles"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Storyteller receives character message:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"type": "character_message",
|
|
||||||
"character_id": "uuid",
|
|
||||||
"character_name": "Aragorn",
|
|
||||||
"message": { ... }
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Character joined notification:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"type": "character_joined",
|
|
||||||
"character": {
|
|
||||||
"id": "uuid",
|
|
||||||
"name": "Legolas",
|
|
||||||
"description": "...",
|
|
||||||
"llm_model": "gpt-4"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### LLM Integration
|
|
||||||
|
|
||||||
**Function:** `call_llm(model, messages, temperature, max_tokens)`
|
|
||||||
|
|
||||||
**Routing Logic:**
|
|
||||||
```python
|
|
||||||
if model.startswith("gpt-") or model.startswith("o1-"):
|
|
||||||
# Use OpenAI client
|
|
||||||
response = await client.chat.completions.create(...)
|
|
||||||
else:
|
|
||||||
# Use OpenRouter via httpx
|
|
||||||
response = await http_client.post("https://openrouter.ai/api/v1/chat/completions", ...)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Available Models (as of this session):**
|
|
||||||
- OpenAI: gpt-4o, gpt-4-turbo, gpt-4, gpt-3.5-turbo
|
|
||||||
- Anthropic (via OpenRouter): claude-3.5-sonnet, claude-3-opus, claude-3-haiku
|
|
||||||
- Meta: llama-3.1-70b, llama-3.1-8b
|
|
||||||
- Google: gemini-pro-1.5
|
|
||||||
- Mistral: mistral-large
|
|
||||||
- Cohere: command-r-plus
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎨 UI/UX Highlights
|
|
||||||
|
|
||||||
### Color Scheme
|
|
||||||
- Primary gradient: Purple (`#667eea` → `#764ba2`)
|
|
||||||
- Background: White cards on gradient
|
|
||||||
- Messages: Blue (sent) / Gray (received)
|
|
||||||
- Pending indicators: Red badges
|
|
||||||
- Status: Green (connected) / Gray (disconnected)
|
|
||||||
|
|
||||||
### Key UX Features
|
|
||||||
1. **Session ID prominently displayed** for easy sharing
|
|
||||||
2. **Pending response badges** show storyteller which characters are waiting
|
|
||||||
3. **Character cards** with all relevant info at a glance
|
|
||||||
4. **Empty states** guide users on what to do next
|
|
||||||
5. **Connection status** always visible
|
|
||||||
6. **Auto-scroll** to latest message
|
|
||||||
7. **Keyboard shortcuts** (Enter to send)
|
|
||||||
8. **Model selector** with descriptions helping users choose
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🐛 Known Limitations & TODO
|
|
||||||
|
|
||||||
### Current Limitations
|
|
||||||
1. **No persistence** - Sessions lost on server restart
|
|
||||||
2. **No authentication** - Anyone with session ID can join
|
|
||||||
3. **No message editing/deletion** - Messages are permanent
|
|
||||||
4. **No character limit** on messages (could be abused)
|
|
||||||
5. **No rate limiting** - API calls not throttled
|
|
||||||
6. **No offline support** - Requires active connection
|
|
||||||
7. **No mobile optimization** - Works but could be better
|
|
||||||
8. **No sound notifications** - Easy to miss new messages
|
|
||||||
|
|
||||||
### Security Considerations
|
|
||||||
- **CORS is wide open** (`allow_origins=["*"]`) - Restrict in production
|
|
||||||
- **No input validation** on message content - Add sanitization
|
|
||||||
- **API keys in environment** - Good, but consider secrets manager
|
|
||||||
- **No session expiration** - Sessions live forever in memory
|
|
||||||
- **WebSocket not authenticated** - Anyone with session ID can connect
|
|
||||||
|
|
||||||
### Performance Considerations
|
|
||||||
- **In-memory storage** - Won't scale to many sessions
|
|
||||||
- **No message pagination** - All history loaded at once
|
|
||||||
- **No connection pooling** - Each character = new WebSocket
|
|
||||||
- **No caching** - LLM calls always go to API
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 💡 What Makes This Special
|
|
||||||
|
|
||||||
### Unique Features
|
|
||||||
1. **Each character uses a different AI model** - Creates emergent gameplay
|
|
||||||
2. **Completely private conversations** - True secret communication
|
|
||||||
3. **Storyteller-centric design** - Built for tabletop RPG flow
|
|
||||||
4. **Real-time updates** - Feels like a chat app
|
|
||||||
5. **Model flexibility** - 100+ LLMs via OpenRouter
|
|
||||||
6. **Zero configuration** - Works out of the box
|
|
||||||
|
|
||||||
### Design Philosophy
|
|
||||||
- **Storyteller is the hub** - All communication flows through them
|
|
||||||
- **Privacy first** - Characters truly can't see each other's messages
|
|
||||||
- **Flexibility** - Support for any LLM model
|
|
||||||
- **Simplicity** - Clean, intuitive interface
|
|
||||||
- **Real-time** - No page refreshes needed
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔄 Context for Continuing Development
|
|
||||||
|
|
||||||
### If Starting a New Chat Session
|
|
||||||
|
|
||||||
**What works:**
|
|
||||||
- ✅ Backend fully functional with all endpoints
|
|
||||||
- ✅ Frontend complete with all views
|
|
||||||
- ✅ WebSocket communication working
|
|
||||||
- ✅ Multi-LLM support implemented
|
|
||||||
- ✅ Scene narration working
|
|
||||||
- ✅ Private conversations isolated correctly
|
|
||||||
|
|
||||||
**Quick test to verify everything:**
|
|
||||||
```bash
|
|
||||||
# 1. Start servers
|
|
||||||
./start.sh
|
|
||||||
|
|
||||||
# 2. Create session as storyteller
|
|
||||||
# 3. Join session as character (new browser/incognito)
|
|
||||||
# 4. Send message from character
|
|
||||||
# 5. Verify storyteller sees it
|
|
||||||
# 6. Respond from storyteller
|
|
||||||
# 7. Verify character receives it
|
|
||||||
# 8. Test scene narration
|
|
||||||
```
|
|
||||||
|
|
||||||
**Common issues:**
|
|
||||||
- **Port 8000/3000 already in use** - `start.sh` kills existing processes
|
|
||||||
- **WebSocket won't connect** - Check backend is running, check browser console
|
|
||||||
- **LLM not responding** - Verify API keys in `.env`
|
|
||||||
- **npm/pip dependencies missing** - Run install commands
|
|
||||||
|
|
||||||
### Files to Modify for Common Tasks
|
|
||||||
|
|
||||||
**Add new WebSocket message type:**
|
|
||||||
1. Update message handler in `main.py` (character or storyteller endpoint)
|
|
||||||
2. Update frontend component to send/receive new type
|
|
||||||
|
|
||||||
**Add new REST endpoint:**
|
|
||||||
1. Add `@app.post()` or `@app.get()` in `main.py`
|
|
||||||
2. Add fetch call in appropriate frontend component
|
|
||||||
|
|
||||||
**Modify UI:**
|
|
||||||
1. Edit component in `frontend/src/components/`
|
|
||||||
2. Edit styles in `frontend/src/App.css`
|
|
||||||
|
|
||||||
**Add new LLM provider:**
|
|
||||||
1. Update `call_llm()` function in `main.py`
|
|
||||||
2. Update `get_available_models()` endpoint
|
|
||||||
3. Add model options in `SessionSetup.js`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 Project Statistics
|
|
||||||
|
|
||||||
- **Total Lines of Code:** ~1,700
|
|
||||||
- **Backend:** ~400 lines (Python/FastAPI)
|
|
||||||
- **Frontend:** ~1,300 lines (React/JavaScript/CSS)
|
|
||||||
- **Time to MVP:** 1 session
|
|
||||||
- **Dependencies:** 8 Python packages, 5 npm packages (core)
|
|
||||||
- **API Endpoints:** 6 REST + 2 WebSocket
|
|
||||||
- **React Components:** 3 main + 1 router
|
|
||||||
- **Supported LLMs:** 15+ models across 6 providers
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎓 Learning Resources Used
|
|
||||||
|
|
||||||
### Technologies
|
|
||||||
- **FastAPI:** https://fastapi.tiangolo.com/
|
|
||||||
- **WebSockets:** https://developer.mozilla.org/en-US/docs/Web/API/WebSocket
|
|
||||||
- **React:** https://react.dev/
|
|
||||||
- **OpenAI API:** https://platform.openai.com/docs
|
|
||||||
- **OpenRouter:** https://openrouter.ai/docs
|
|
||||||
|
|
||||||
### Key Concepts Implemented
|
|
||||||
- WebSocket bidirectional communication
|
|
||||||
- Async Python with FastAPI
|
|
||||||
- React state management with hooks
|
|
||||||
- Multi-provider LLM routing
|
|
||||||
- Real-time message delivery
|
|
||||||
- Isolated conversation contexts
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📝 Notes for Future You
|
|
||||||
|
|
||||||
### Why certain decisions were made:
|
|
||||||
- **WebSocket instead of polling:** Real-time updates without constant HTTP requests
|
|
||||||
- **Separate endpoints for character/storyteller:** Clean separation of concerns, different message types
|
|
||||||
- **In-memory storage first:** Fastest MVP, can migrate to DB later
|
|
||||||
- **Multi-LLM from start:** Makes the app unique and interesting
|
|
||||||
- **No socket.io:** Native WebSocket simpler for this use case
|
|
||||||
- **Private conversations:** Core feature that differentiates from group chat apps
|
|
||||||
|
|
||||||
### What went smoothly:
|
|
||||||
- FastAPI made WebSocket implementation easy
|
|
||||||
- React components stayed clean and modular
|
|
||||||
- OpenRouter integration was straightforward
|
|
||||||
- UI came together nicely with gradients
|
|
||||||
|
|
||||||
### What could be improved:
|
|
||||||
- Database persistence is the obvious next step
|
|
||||||
- Error handling could be more robust
|
|
||||||
- Mobile experience needs work
|
|
||||||
- Need proper authentication system
|
|
||||||
- Testing suite would be valuable
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 Recommended Next Actions
|
|
||||||
|
|
||||||
**Immediate (Next Session):**
|
|
||||||
1. Test the app end-to-end to ensure everything works after IDE crash
|
|
||||||
2. Add AI suggestion button to storyteller UI (backend ready, just needs frontend)
|
|
||||||
3. Implement session persistence with SQLite
|
|
||||||
|
|
||||||
**Short Term (This Week):**
|
|
||||||
4. Add dice rolling system
|
|
||||||
5. Add typing indicators
|
|
||||||
6. Improve error messages
|
|
||||||
|
|
||||||
**Medium Term (This Month):**
|
|
||||||
7. Add authentication
|
|
||||||
8. Implement character sheets
|
|
||||||
9. Add image generation for scenes
|
|
||||||
|
|
||||||
See **NEXT_STEPS.md** for detailed roadmap with priorities and implementation notes.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📞 Session Handoff Checklist
|
|
||||||
|
|
||||||
- ✅ All files verified and up-to-date
|
|
||||||
- ✅ Architecture documented
|
|
||||||
- ✅ Key decisions explained
|
|
||||||
- ✅ Next steps outlined
|
|
||||||
- ✅ Common issues documented
|
|
||||||
- ✅ Code structure mapped
|
|
||||||
- ✅ API contracts specified
|
|
||||||
- ✅ Testing instructions provided
|
|
||||||
|
|
||||||
**You're ready to continue development!** 🎉
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
*Generated: October 11, 2025*
|
|
||||||
*Project Location: `/home/aodhan/projects/apps/storyteller`*
|
|
||||||
*Status: Production-ready MVP*
|
|
||||||
179
docs/features/README.md
Normal file
179
docs/features/README.md
Normal file
@@ -0,0 +1,179 @@
|
|||||||
|
# 🎭 Features Documentation
|
||||||
|
|
||||||
|
Detailed documentation for all Storyteller RPG features.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Feature Guides
|
||||||
|
|
||||||
|
### Core Features
|
||||||
|
|
||||||
|
#### [Demo Session](./DEMO_SESSION.md)
|
||||||
|
Pre-configured test session that auto-loads on startup. Includes two characters (Bargin & Willow) and "The Cursed Tavern" adventure. Perfect for development and testing.
|
||||||
|
|
||||||
|
**Quick Access:**
|
||||||
|
- Session ID: `demo-session-001`
|
||||||
|
- One-click buttons on home page
|
||||||
|
- No setup required
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### [Context-Aware Response Generator](./CONTEXTUAL_RESPONSE_FEATURE.md)
|
||||||
|
AI-powered tool for storytellers to generate responses considering multiple characters' actions simultaneously.
|
||||||
|
|
||||||
|
**Key Features:**
|
||||||
|
- Multi-character selection
|
||||||
|
- Scene descriptions (broadcast to all)
|
||||||
|
- Individual responses (private to each)
|
||||||
|
- Automatic parsing and distribution
|
||||||
|
- Smart context building
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Technical Documentation
|
||||||
|
|
||||||
|
#### [Prompt Engineering Improvements](./PROMPT_IMPROVEMENTS.md)
|
||||||
|
Details on how we improved the LLM prompts for reliable individual response parsing using the `[CharacterName]` format.
|
||||||
|
|
||||||
|
**Topics Covered:**
|
||||||
|
- Square bracket format rationale
|
||||||
|
- Regex parsing patterns
|
||||||
|
- System prompt enhancements
|
||||||
|
- Edge case handling
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### [Bug Fixes Summary](./FIXES_SUMMARY.md)
|
||||||
|
Comprehensive list of bugs fixed in the latest release.
|
||||||
|
|
||||||
|
**Fixed Issues:**
|
||||||
|
- Character chat history showing only recent messages
|
||||||
|
- Pydantic deprecation warnings (.dict → .model_dump)
|
||||||
|
- WebSocket manager reference errors
|
||||||
|
- Session ID copy functionality
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Feature Overview by Category
|
||||||
|
|
||||||
|
### For Storytellers 🎲
|
||||||
|
|
||||||
|
| Feature | Description | Status |
|
||||||
|
|---------|-------------|--------|
|
||||||
|
| **Session Management** | Create/join sessions, manage characters | ✅ Complete |
|
||||||
|
| **Scene Narration** | Broadcast scene descriptions to all players | ✅ Complete |
|
||||||
|
| **Private Responses** | Send individual messages to characters | ✅ Complete |
|
||||||
|
| **AI Suggestions** | Get AI-generated response suggestions | ✅ Complete |
|
||||||
|
| **Context-Aware Generator** | Generate responses considering multiple characters | ✅ Complete |
|
||||||
|
| **Pending Message Tracking** | See which characters need responses | ✅ Complete |
|
||||||
|
| **Demo Session** | Pre-loaded test scenario for quick start | ✅ Complete |
|
||||||
|
|
||||||
|
### For Players 🎭
|
||||||
|
|
||||||
|
| Feature | Description | Status |
|
||||||
|
|---------|-------------|--------|
|
||||||
|
| **Character Creation** | Define name, description, personality | ✅ Complete |
|
||||||
|
| **Private Messages** | Send private messages to storyteller | ✅ Complete |
|
||||||
|
| **Public Actions** | Broadcast actions visible to all players | ✅ Complete |
|
||||||
|
| **Mixed Messages** | Public action + private thoughts | ✅ Complete |
|
||||||
|
| **Scene Viewing** | See current scene description | ✅ Complete |
|
||||||
|
| **Public Feed** | View all players' public actions | ✅ Complete |
|
||||||
|
| **Conversation History** | Full chat log with storyteller | ✅ Complete |
|
||||||
|
|
||||||
|
### Message System 📨
|
||||||
|
|
||||||
|
| Feature | Description | Status |
|
||||||
|
|---------|-------------|--------|
|
||||||
|
| **Private Messages** | One-on-one conversation | ✅ Complete |
|
||||||
|
| **Public Messages** | Visible to all players | ✅ Complete |
|
||||||
|
| **Mixed Messages** | Public + private components | ✅ Complete |
|
||||||
|
| **Real-time Updates** | WebSocket-based live updates | ✅ Complete |
|
||||||
|
| **Message Persistence** | In-memory storage (session lifetime) | ✅ Complete |
|
||||||
|
|
||||||
|
### AI Integration 🤖
|
||||||
|
|
||||||
|
| Feature | Description | Status |
|
||||||
|
|---------|-------------|--------|
|
||||||
|
| **Multiple LLM Support** | GPT-4o, GPT-4, GPT-3.5, Claude, Llama | ✅ Complete |
|
||||||
|
| **AI Response Suggestions** | Quick response generation | ✅ Complete |
|
||||||
|
| **Context-Aware Generation** | Multi-character context building | ✅ Complete |
|
||||||
|
| **Structured Output Parsing** | [CharacterName] format parsing | ✅ Complete |
|
||||||
|
| **Temperature Control** | Creative vs. focused responses | ✅ Complete |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Coming Soon 🚀
|
||||||
|
|
||||||
|
### Planned Features
|
||||||
|
|
||||||
|
- **Database Persistence** - Save sessions and characters permanently
|
||||||
|
- **Character Sheets** - Stats, inventory, abilities
|
||||||
|
- **Dice Rolling** - Built-in dice mechanics
|
||||||
|
- **Combat System** - Turn-based combat management
|
||||||
|
- **Image Generation** - AI-generated scene/character images
|
||||||
|
- **Voice Messages** - Audio message support
|
||||||
|
- **Session Export** - Export conversation logs
|
||||||
|
- **User Authentication** - Account system with saved preferences
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Feature Request Process
|
||||||
|
|
||||||
|
Want to suggest a new feature?
|
||||||
|
|
||||||
|
1. **Check existing documentation** - Feature might already exist
|
||||||
|
2. **Review roadmap** - Check if it's already planned (see [MVP_ROADMAP.md](../planning/MVP_ROADMAP.md))
|
||||||
|
3. **Create an issue** - Describe the feature and use case
|
||||||
|
4. **Discuss implementation** - We'll evaluate feasibility and priority
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Version History
|
||||||
|
|
||||||
|
### v0.2.0 - Context-Aware Features (October 2025)
|
||||||
|
- ✅ Context-aware response generator
|
||||||
|
- ✅ Demo session with pre-configured characters
|
||||||
|
- ✅ Improved prompt engineering for parsing
|
||||||
|
- ✅ Bug fixes (chat history, Pydantic warnings)
|
||||||
|
- ✅ Session ID copy button
|
||||||
|
|
||||||
|
### v0.1.0 - MVP Phase 1 (October 2025)
|
||||||
|
- ✅ Basic session management
|
||||||
|
- ✅ Character creation and joining
|
||||||
|
- ✅ Private/public/mixed messaging
|
||||||
|
- ✅ Real-time WebSocket communication
|
||||||
|
- ✅ Scene narration
|
||||||
|
- ✅ AI-assisted responses
|
||||||
|
- ✅ Multiple LLM support
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Documentation Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
docs/
|
||||||
|
├── features/ ← You are here
|
||||||
|
│ ├── README.md
|
||||||
|
│ ├── DEMO_SESSION.md
|
||||||
|
│ ├── CONTEXTUAL_RESPONSE_FEATURE.md
|
||||||
|
│ ├── PROMPT_IMPROVEMENTS.md
|
||||||
|
│ └── FIXES_SUMMARY.md
|
||||||
|
├── development/
|
||||||
|
│ ├── MVP_PROGRESS.md
|
||||||
|
│ ├── TESTING_GUIDE.md
|
||||||
|
│ └── TEST_RESULTS.md
|
||||||
|
├── planning/
|
||||||
|
│ ├── MVP_ROADMAP.md
|
||||||
|
│ ├── PROJECT_PLAN.md
|
||||||
|
│ └── NEXT_STEPS.md
|
||||||
|
├── setup/
|
||||||
|
│ ├── QUICKSTART.md
|
||||||
|
│ └── QUICK_REFERENCE.md
|
||||||
|
└── reference/
|
||||||
|
├── PROJECT_FILES_REFERENCE.md
|
||||||
|
└── LLM_GUIDE.md
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Need help?** Check the [main README](../../README.md) or the [Quick Start Guide](../setup/QUICKSTART.md).
|
||||||
Reference in New Issue
Block a user