aodhan/storyteller
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Aodhan Collins
2025-10-11 21:21:36 +01:00
commit eccd456c59
29 changed files with 5375 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
docs/reference/LLM_GUIDE.md Normal file
View File

@@ -0,0 +1,166 @@
# 🤖 LLM Model Guide
## Overview
Each character in the storyteller RPG can use a different AI model, giving them unique personality traits and response styles. This creates incredible variety and emergent gameplay!
## Available Models
### OpenAI Models (requires OPENAI_API_KEY)
#### GPT-4o (Latest)
- **Best for**: All-around excellence, latest capabilities
- **Personality**: Intelligent, balanced, reliable
- **Cost**: $$$$
- **Speed**: Fast
#### GPT-4 Turbo
- **Best for**: Complex reasoning, detailed responses
- **Personality**: Thoughtful, articulate, analytical
- **Cost**: $$$
- **Speed**: Medium
#### GPT-3.5 Turbo
- **Best for**: Quick interactions, budget-friendly
- **Personality**: Energetic, conversational, casual
- **Cost**: $
- **Speed**: Very Fast
### OpenRouter Models (requires OPENROUTER_API_KEY)
#### Claude 3.5 Sonnet (Anthropic)
- **Best for**: Creative roleplay, nuanced responses
- **Personality**: Thoughtful, creative, emotionally aware
- **Cost**: $$$
- **Speed**: Fast
- **Great for**: Characters with depth and complexity
#### Claude 3 Opus (Anthropic)
- **Best for**: Most sophisticated responses
- **Personality**: Highly intelligent, philosophical
- **Cost**: $$$$
- **Speed**: Medium
- **Great for**: Wise characters, strategists
#### Claude 3 Haiku (Anthropic)
- **Best for**: Quick, concise responses
- **Personality**: Efficient, direct, clever
- **Cost**: $
- **Speed**: Very Fast
- **Great for**: Action-oriented characters
#### Gemini Pro 1.5 (Google)
- **Best for**: Factual knowledge, analytical thinking
- **Personality**: Logical, informative, precise
- **Cost**: $$
- **Speed**: Fast
- **Great for**: Scholarly characters, investigators
#### Llama 3.1 70B (Meta)
- **Best for**: Free-spirited, creative responses
- **Personality**: Bold, spontaneous, unpredictable
- **Cost**: $$
- **Speed**: Medium
- **Great for**: Wild characters, rogues
#### Llama 3.1 8B (Meta)
- **Best for**: Fast, lightweight interactions
- **Personality**: Quick-witted, energetic
- **Cost**: $
- **Speed**: Very Fast
- **Great for**: Nimble characters, scouts
#### Mistral Large (Mistral AI)
- **Best for**: European flair, multilingual
- **Personality**: Cultured, articulate, sophisticated
- **Cost**: $$
- **Speed**: Fast
- **Great for**: Noble characters, diplomats
#### Command R+ (Cohere)
- **Best for**: Following instructions precisely
- **Personality**: Obedient, structured, methodical
- **Cost**: $$
- **Speed**: Fast
- **Great for**: Soldiers, servants, loyal companions
## Mixing Models for Rich Gameplay
### Example Party Compositions
#### The Diverse Adventurers
- **Wise Wizard**: Claude 3 Opus (philosophical, strategic)
- **Brave Warrior**: GPT-4 Turbo (tactical, heroic)
- **Sneaky Rogue**: Llama 3.1 70B (unpredictable, bold)
- **Scholar**: Gemini Pro (analytical, knowledgeable)
#### The Quick Squad
- **Scout**: Llama 3.1 8B (fast, energetic)
- **Fighter**: Claude 3 Haiku (direct, efficient)
- **Mage**: GPT-3.5 Turbo (quick casting)
#### The Elite Team
- **Leader**: GPT-4o (balanced, excellent)
- **Advisor**: Claude 3.5 Sonnet (creative strategy)
- **Specialist**: Gemini Pro (expert knowledge)
## Cost Considerations
Models are charged per token (roughly per word). Approximate costs:
- **$**: ~$0.50-1 per 1000 messages
- **$$**: ~$1-3 per 1000 messages
- **$$$**: ~$3-10 per 1000 messages
- **$$$$**: ~$10-30 per 1000 messages
**Tips to save money:**
- Use cheaper models (GPT-3.5, Claude Haiku, Llama 8B) for most characters
- Reserve expensive models (GPT-4o, Claude Opus) for key NPCs or special moments
- Mix and match based on character importance
## Setting Up API Keys
### OpenAI
1. Create account at <https://platform.openai.com>
2. Add payment method
3. Generate API key at <https://platform.openai.com/api-keys>
4. Add to `.env`: `OPENAI_API_KEY=sk-...`
### OpenRouter
1. Create account at <https://openrouter.ai>
2. Add credits (starts at $5)
3. Generate API key at <https://openrouter.ai/keys>
4. Add to `.env`: `OPENROUTER_API_KEY=sk-...`
**Why OpenRouter?**
- Single API key for 100+ models
- Pay-as-you-go pricing
- No monthly subscriptions
- Access to Claude, Llama, Gemini, Mistral, and more
## Testing Models
Try creating characters with different models and see how they respond differently to the same situation!
Example test:
1. Create 3 characters with different models
2. Have all three search a mysterious room
3. Compare their unique approaches:
- GPT-4: Methodical, detailed search
- Claude: Creative interpretations
- Llama: Bold, risky actions
- Gemini: Logical deductions
## Advanced: Custom Model Configuration
You can add more models by editing `main.py`:
```python
# In the get_available_models() function
models["openrouter"] = [
{"id": "your/model-id", "name": "Display Name", "provider": "Provider"},
# Add more models here
]
```
Find model IDs at <https://openrouter.ai/models>

300
docs/reference/PROJECT_FILES_REFERENCE.md Normal file
View File

@@ -0,0 +1,300 @@
# 📂 Project Files Reference
Quick reference guide to all files in the Storyteller RPG project.
---
## 🔧 Core Application Files
### Backend (Python/FastAPI)
| File | Lines | Purpose |
|------|-------|---------|
| **main.py** | 398 | Complete FastAPI backend with WebSocket support, LLM integration, and all API endpoints |
| **requirements.txt** | 9 | Python dependencies (FastAPI, OpenAI, httpx, etc.) |
### Frontend (React)
| File | Lines | Purpose |
|------|-------|---------|
| **frontend/src/App.js** | 40 | Main router component, manages session/character state |
| **frontend/src/App.css** | 704 | Complete styling for entire application |
| **frontend/src/index.js** | 12 | React entry point |
| **frontend/src/components/SessionSetup.js** | 180 | Session creation and joining interface with model selection |
| **frontend/src/components/CharacterView.js** | 141 | Character's private conversation interface |
| **frontend/src/components/StorytellerView.js** | 243 | Storyteller dashboard with character management |
| **frontend/public/index.html** | 18 | HTML template |
| **frontend/package.json** | 40 | Node.js dependencies and scripts |
---
## 📚 Documentation Files
| File | Purpose | When to Read |
|------|---------|--------------|
| **README.md** | Comprehensive project overview, features, setup instructions | First time setup or sharing with others |
| **QUICKSTART.md** | 5-minute quick start guide | When you want to run the app quickly |
| **SESSION_SUMMARY.md** | Complete development session summary, architecture, decisions | When continuing development or understanding the codebase |
| **NEXT_STEPS.md** | Detailed roadmap of future features and improvements | When planning next development phase |
| **PROJECT_FILES_REFERENCE.md** | This file - quick reference to all files | When navigating the project |
| **LLM_GUIDE.md** | Guide to available LLM models (if exists) | When choosing AI models for characters |
---
## 🔐 Configuration Files
| File | Purpose | Notes |
|------|---------|-------|
| **.env.example** | Template for environment variables | Copy to `.env` and add your API keys |
| **.env** | Your actual API keys | **GITIGNORED** - never commit this |
| **.python-version** | Python version specification | For pyenv users |
---
## 🚀 Scripts
| File | Purpose | Usage |
|------|---------|-------|
| **start.sh** | Auto-start both backend and frontend | `./start.sh` (Unix/Mac/Linux) |
| **start.bat** | Windows version of start script | `start.bat` (Windows) |
| **dev.sh** | Development mode with tmux split terminals | `./dev.sh` (requires tmux) |
---
## 📁 Directory Structure
```
storyteller/
├── 📄 Backend Files
│ ├── main.py # ⭐ Main backend application
│ └── requirements.txt # Python dependencies
│
├── 🌐 Frontend Files
│ └── frontend/
│ ├── src/
│ │ ├── App.js # ⭐ Main React component
│ │ ├── App.css # ⭐ All styles
│ │ ├── index.js # React entry point
│ │ └── components/
│ │ ├── SessionSetup.js # ⭐ Session creation/joining
│ │ ├── CharacterView.js # ⭐ Character interface
│ │ └── StorytellerView.js # ⭐ Storyteller dashboard
│ ├── public/
│ │ ├── index.html # HTML template
│ │ ├── manifest.json # PWA manifest
│ │ └── robots.txt # SEO robots
│ ├── package.json # Node dependencies
│ └── node_modules/ # Installed packages (auto-generated)
│
├── 📚 Documentation
│ ├── README.md # ⭐ Main documentation
│ ├── QUICKSTART.md # Quick setup guide
│ ├── SESSION_SUMMARY.md # ⭐ Development session summary
│ ├── NEXT_STEPS.md # ⭐ Future roadmap
│ └── PROJECT_FILES_REFERENCE.md # This file
│
├── 🔐 Configuration
│ ├── .env.example # Environment template
│ ├── .env # Your API keys (gitignored)
│ └── .python-version # Python version
│
└── 🚀 Scripts
├── start.sh # Unix/Mac/Linux launcher
├── start.bat # Windows launcher
└── dev.sh # Dev mode with tmux
```
---
## 🎯 Files by Priority
### Must Understand (Core Application)
1. **main.py** - Backend logic, WebSocket handling, LLM integration
2. **SessionSetup.js** - How users create/join sessions
3. **CharacterView.js** - Character's private conversation interface
4. **StorytellerView.js** - Storyteller's dashboard and response interface
5. **App.js** - React routing logic
### Important (Configuration & Styling)
6. **App.css** - All visual styling
7. **.env** - API keys configuration
8. **requirements.txt** - Backend dependencies
9. **package.json** - Frontend dependencies
### Reference (Documentation)
10. **SESSION_SUMMARY.md** - Understanding the architecture
11. **NEXT_STEPS.md** - Planning future work
12. **README.md** - Setup and feature overview
13. **QUICKSTART.md** - Fast setup instructions
---
## 🔍 Where to Find Things
### Adding New Features
**New WebSocket message type:**
- Backend: `main.py` → `character_websocket()` or `storyteller_websocket()`
- Frontend: Relevant component's `useEffect` → `ws.onmessage`
**New REST endpoint:**
- Backend: `main.py` → Add `@app.post()` or `@app.get()` decorator
- Frontend: Component → Add `fetch()` call
**New UI component:**
- Create in: `frontend/src/components/NewComponent.js`
- Import in: `frontend/src/App.js`
- Style in: `frontend/src/App.css`
**New LLM provider:**
- Backend: `main.py` → Update `call_llm()` function
- Frontend: `SessionSetup.js` → Model selector will auto-update from `/models` endpoint
### Understanding How It Works
**Message flow (Character → Storyteller):**
1. `CharacterView.js` → `sendMessage()` → WebSocket
2. `main.py` → `character_websocket()` → Receives message
3. Stored in `character.conversation_history`
4. Forwarded to storyteller via `manager.send_to_client()`
5. `StorytellerView.js` → `ws.onmessage` → Displays in UI
**Message flow (Storyteller → Character):**
1. `StorytellerView.js` → `sendResponse()` → WebSocket
2. `main.py` → `storyteller_websocket()` → Receives response
3. Stored in `character.conversation_history`
4. Sent to specific character via `manager.send_to_client()`
5. `CharacterView.js` → `ws.onmessage` → Displays in UI
**How LLM integration works:**
1. Character chooses model in `SessionSetup.js`
2. Stored in `Character.llm_model` field
3. When generating response: `call_llm(character.llm_model, messages)`
4. Function routes to OpenAI or OpenRouter based on model prefix
5. Returns generated text to be sent to character
### Styling
**Global styles:**
- `App.css` → Lines 1-100 (body, session-setup)
**SessionSetup styles:**
- `App.css` → Lines 18-180 (setup-container, input-group, divider, model-selector)
**CharacterView styles:**
- `App.css` → Lines 181-350 (character-view, character-header, messages)
**StorytellerView styles:**
- `App.css` → Lines 351-704 (storyteller-view, character-list, conversation-panel)
---
## 🛠️ Quick Modifications
### Change default LLM model
**File:** `main.py` line 47
```python
llm_model: str = "gpt-3.5-turbo" # Change default here
```
### Change ports
**Backend:** `main.py` line 397
```python
uvicorn.run(app, host="0.0.0.0", port=8000) # Change port here
```
**Frontend:** `package.json` or set `PORT=3001` environment variable
### Change API URLs
**File:** `SessionSetup.js`, `CharacterView.js`, `StorytellerView.js`
```javascript
const API_URL = 'http://localhost:8000'; // Change this
const WS_URL = 'ws://localhost:8000'; // And this
```
### Add new available model
**File:** `main.py` → `get_available_models()` function (lines 323-351)
```python
models["openai"].append({
"id": "gpt-4o-mini",
"name": "GPT-4o Mini",
"provider": "OpenAI"
})
```
### Modify color scheme
**File:** `App.css`
- Line 13: `background: linear-gradient(...)` - Main gradient
- Lines 100-150: Button colors (`.btn-primary`)
- Lines 400-450: Message colors (`.message.sent`, `.message.received`)
---
## 📊 File Statistics
| Category | Files | Total Lines |
|----------|-------|-------------|
| Backend | 2 | ~407 |
| Frontend JS | 5 | ~616 |
| Frontend CSS | 1 | 704 |
| Frontend HTML | 1 | 18 |
| Documentation | 5 | ~1,500 |
| Scripts | 3 | ~250 |
| **Total** | **17** | **~3,495** |
---
## 🔄 Git/Version Control
### Files that should be gitignored:
- `.env` (contains API keys)
- `node_modules/` (npm packages)
- `.venv/` or `venv/` (Python virtual environment)
- `__pycache__/` (Python cache)
- `frontend/build/` (React build output)
- `.DS_Store` (Mac system files)
### Files that should be committed:
- All `.js`, `.py`, `.css`, `.html` files
- All `.md` documentation files
- `.env.example` (template without real keys)
- `requirements.txt` and `package.json`
- All script files (`.sh`, `.bat`)
---
## 💡 Tips for Navigating
1. **Start with README.md** for overall understanding
2. **Check SESSION_SUMMARY.md** for architecture details
3. **Read main.py** to understand backend flow
4. **Look at App.js** to see component structure
5. **Each component is self-contained** - easy to modify independently
6. **Styles are organized by component** in App.css
7. **WebSocket messages use JSON** with a `type` field for routing
---
## 🆘 Troubleshooting Guide
### "Can't find file X"
- Check you're in project root: `/home/aodhan/projects/apps/storyteller`
- Frontend files are in `frontend/` subdirectory
- Components are in `frontend/src/components/`
### "Code isn't working"
- Check if both servers are running (backend on 8000, frontend on 3000)
- Check browser console for JavaScript errors
- Check terminal for Python errors
- Verify `.env` file exists with valid API keys
### "Want to understand feature X"
- Search in `SESSION_SUMMARY.md` for architecture
- Search in `main.py` for backend implementation
- Search in relevant component file for frontend
- Check `App.css` for styling
---
*Last Updated: October 11, 2025*
*Total Project Size: ~3,500 lines of code + documentation*