# 🤖 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>