🎭 Storyteller RPG Application

A storyteller-centric roleplaying application where characters communicate privately with the storyteller, who then crafts unique, personalized responses for each player.

✨ 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
• 📢 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
• 🧠 Context-Aware AI: Generate responses considering multiple characters' actions simultaneously
• 🎮 Demo Session: Pre-loaded "Cursed Tavern" adventure with two characters for instant testing

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
• 🧠 Isolated Memory Sessions: Each character maintains their own separate conversation history
• 🎨 Modern, Beautiful UI: Clean, intuitive interface with gradient themes
• 📱 Responsive Design: Works on desktop, tablet, and mobile

🎯 How It Works

1. Storyteller creates a session and shares the session ID
2. Players join by entering the session ID and creating their character
3. Characters send private messages to the storyteller (other players can't see these)
4. Storyteller views all character messages and crafts individual responses
5. Each character receives their personalized response from the storyteller
6. Storyteller can narrate scenes that all characters experience together

📋 Prerequisites

• Python 3.8+
• Node.js 16+
• npm or yarn
• API Keys (at least one):
  • OpenAI API key (for GPT models)
  • OpenRouter API key (for Claude, Llama, Gemini, Mistral, and 100+ other models)

Setup

Backend Setup

1. Create a virtual environment and activate it:

   python -m venv venv
   source venv/bin/activate  # On Windows: .\venv\Scripts\activate
   

2. Install the required Python packages:

   pip install -r requirements.txt
   

3. Set up your environment variables. Copy the example file and add your API keys:

   cp .env.example .env
   # Edit .env and add at least one API key:
   # - OPENAI_API_KEY for GPT models
   # - OPENROUTER_API_KEY for Claude, Llama, Gemini, etc.
   

   Get API Keys:

   • OpenAI: https://platform.openai.com/api-keys
   • OpenRouter: https://openrouter.ai/keys (access 100+ models with one key!)

Frontend Setup

1. Navigate to the frontend directory:

   cd frontend
   

2. Install the required Node.js packages:

   npm install
   

🚀 Quick Start

Easy Start (Recommended)

Use the startup script to launch both backend and frontend:

Linux/Mac:

bash start.sh

Windows:

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:

uvicorn main:app --reload

Frontend:

cd frontend && npm start

🎮 How to Use

As the Storyteller

1. Create a Session

   • Enter a session name and click "Create New Session"
   • Copy the session ID and share it with your players

2. Storyteller Dashboard

   • Character List: See all characters who have joined (left panel)
   • Pending Indicators: Red badges show which characters are waiting for responses
   • Narrate Scenes: Use the scene input at the top to describe events all characters experience
   • Private Conversations: Click a character to view their conversation
   • Respond Individually: Craft unique responses for each character privately

As a Player/Character

1. Join a Session

   • Get the session ID from your storyteller
   • Enter your character name, description, and optional personality traits
   • Choose an AI model for your character:
     • GPT-4o: Latest OpenAI model, excellent all-around
     • Claude 3.5 Sonnet: Creative, nuanced, great for roleplay
     • Llama 3.1: Fast and free-spirited
     • Gemini Pro: Google's powerful model
     • Each model has unique personality traits!
   • Click "Join Session"

2. Playing Your Character

   • Send private messages to the storyteller
   • Your messages are private - other players cannot see them
   • Receive personalized responses from the storyteller (powered by your chosen LLM)
   • See scene narrations that the storyteller broadcasts to everyone
   • Your conversation history with the storyteller is preserved

🏗️ Architecture

• Backend: FastAPI with WebSockets for real-time bidirectional communication
• Frontend: React with modern component-based architecture
• AI: Multi-LLM support via:
  • OpenAI API: GPT-4o, GPT-4 Turbo, GPT-3.5 Turbo
  • OpenRouter API: Claude (Anthropic), Llama (Meta), Gemini (Google), Mistral, Cohere, and 100+ more
  • Each character can use a different model for unique personalities
• Memory: In-memory storage with isolated conversation histories per character
• Communication:
  • Separate WebSocket endpoints for characters (/ws/character/{session_id}/{character_id}) and storyteller (/ws/storyteller/{session_id})
  • Messages are routed privately between storyteller and individual characters
  • Scene narrations are broadcast to all connected characters

🔐 Privacy Model

Each character has a completely isolated conversation with the storyteller:

• ✅ Character A cannot see Character B's messages
• ✅ Character A cannot see Character B's responses from the storyteller
• ✅ Each character only sees their own private conversation + scene narrations
• ✅ Only the storyteller sees all character conversations

🚀 Future Improvements

• Add user authentication and session persistence
• Database integration (PostgreSQL/MongoDB) for storing sessions
• Character sheets with stats and inventory
• Dice rolling mechanics with visual animations
• Support for multiple AI models (Claude, Llama, etc.)
• Chat history export/import
• Audio/voice integration for immersive experience
• Mobile app versions
• Group conversations (optional feature for party discussions)
• Image generation for scenes and characters

🔧 API Endpoints

REST Endpoints

• POST /sessions/ - Create a new game session
• GET /sessions/{session_id} - Get session details
• POST /sessions/{session_id}/characters/ - Add a character to a session
• GET /sessions/{session_id}/characters/{character_id}/conversation - Get character's conversation history
• POST /sessions/{session_id}/generate_suggestion - Get AI suggestion for storyteller response (requires OpenAI API key)

WebSocket Endpoints

• ws/character/{session_id}/{character_id} - Character's private connection
• ws/storyteller/{session_id} - Storyteller's connection to manage the session

Model Management

• GET /models - Get list of available LLM models (based on configured API keys)

📚 Documentation

All project documentation is organized in the docs/ folder:

Quick Links

• Features Guide - All features with examples and guides
  • Demo Session
  • Context-Aware Responses
  • Bug Fixes Summary
• Setup Guides - Quick start and installation
• Planning - Roadmaps and feature plans
• Reference - Technical guides and file references
• Development - Testing and implementation details

See docs/README.md for the complete documentation index.

🤖 Using Different LLMs

See docs/reference/LLM_GUIDE.md for detailed information about:

• Available models and their personalities
• Cost comparisons
• Best practices for mixing models
• Setting up API keys
• Example party compositions

Quick Summary:

• Each character can use a different AI model
• OpenAI: GPT-4o, GPT-4, GPT-3.5
• OpenRouter: Claude, Llama, Gemini, Mistral, and 100+ more
• Different models = different personalities and response styles
• Creates emergent gameplay with unique character interactions

License

MIT