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

### 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:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: .\venv\Scripts\activate
   ```

2. Install the required Python packages:
   ```bash
   pip install -r requirements.txt
   ```

3. Set up your environment variables. Copy the example file and add your API keys:
   ```bash
   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:
   ```bash
   cd frontend
   ```

2. Install the required Node.js packages:
   ```bash
   npm install
   ```

## 🚀 Quick Start

### Easy Start (Recommended)

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
uvicorn main:app --reload
```

**Frontend:**
```bash
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/`](./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
- **[Planning](./docs/planning/)** - Roadmaps and feature plans  
- **[Reference](./docs/reference/)** - Technical guides and file references
- **[Development](./docs/development/)** - Testing and implementation details

See [docs/README.md](./docs/README.md) for the complete documentation index.

## 🤖 Using Different LLMs

See [docs/reference/LLM_GUIDE.md](./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