storyteller/README.md

🎭 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

• 🔒 Private Character-Storyteller Communication: Each character has a completely isolated conversation with the storyteller - no character can see what others are saying or receiving
• 🎲 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
• 📜 Scene Narration: Storyteller can broadcast scene descriptions visible to all characters
• 🧠 Isolated Memory Sessions: Each character maintains their own separate conversation history with the storyteller
• ⚡ Real-time WebSocket Communication: Instant message delivery
• 🎨 Modern, Beautiful UI: Clean, intuitive interface with gradient themes

🎯 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
   

Running the Application

Start the Backend

From the project root directory:

uvicorn main:app --reload

The backend will be available at http://localhost:8000

Start the Frontend

In a new terminal, navigate to the frontend directory and run:

cd frontend
npm start

The frontend will open in your default browser at http://localhost:3000

🎮 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:

• Setup Guides - Quick start and installation
• Planning - Roadmaps and feature plans
• Reference - Technical guides and file references
• Development - Session notes 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