Initial commit

docs/reference/LLM_GUIDE.md

@@ -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>