Initial commit
This commit is contained in:
Aodhan Collins
214
README.md
Normal file
214
README.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# 🎭 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:
|
||||
```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
|
||||
```
|
||||
|
||||
## Running the Application
|
||||
|
||||
### Start the Backend
|
||||
|
||||
From the project root directory:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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/`](./docs/) folder:
|
||||
|
||||
- **[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/)** - Session notes 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
|
||||
Reference in New Issue
Block a user