# Model Selection Guide

This guide helps you choose the right AI models for different tasks in the platform.

## Quick Reference

### Text Generation (LLMs)

| Use Case | Recommended Model | Context | Cost | Notes |
|----------|-------------------|---------|------|-------|
| Complex reasoning | `anthropic/claude-sonnet-4.5` | 200K | $$$ | Best quality |
| Fast responses | `openai/gpt-4o-mini` | 128K | $ | Good for simple tasks |
| Long documents | `google/gemini-2.5-pro-preview-05-06` | 2M | $$ | Massive context |
| Cost-sensitive | `meta-llama/llama-3.3-70b-instruct` | 131K | $ | Open source |
| Coding | `anthropic/claude-sonnet-4.5` | 200K | $$$ | Best for code |

### Embeddings

| Use Case | Model | Dimensions | Cost |
|----------|-------|------------|------|
| General purpose | `openai/text-embedding-3-small` | 1536 | $ |
| High accuracy | `openai/text-embedding-3-large` | 3072 | $$ |
| Reduced dimensions | Any with `dimensions: 512` | 512 | $ |

### Text-to-Speech

| Use Case | Model | Latency | Quality |
|----------|-------|---------|---------|
| Real-time | `eleven_flash_v2_5` | ~75ms | Good |
| High quality | `eleven_v3` | Standard | Excellent |
| Multi-language | `eleven_multilingual_v2` | Standard | Good |

### Image Generation

| Use Case | Model | Speed | Quality |
|----------|-------|-------|---------|
| Fast previews | `google/gemini-2.5-flash-image-preview` | Fast | Good |
| High quality | `openai/dall-e-3` | Slow | Excellent |

## Detailed Model Profiles

### Claude Sonnet 4.5

**Best for**: Complex reasoning, meditation scripts, content generation

```typescript
const response = await provider.complete({
  model: 'anthropic/claude-sonnet-4.5',
  max_tokens: 4096,
  temperature: 0.7
});
```

**Strengths**:
- Excellent at following complex instructions
- Strong tradition-specific knowledge
- Great at maintaining consistent tone
- Best for multi-agent pipelines

**Pricing**: $3.00/M input, $15.00/M output tokens

**Use when**:
- Generating meditation scripts
- Creating nuanced content
- Complex reasoning tasks
- Quality is more important than cost

### GPT-4o Mini

**Best for**: Simple tasks, quick responses, cost-sensitive operations

```typescript
const response = await provider.complete({
  model: 'openai/gpt-4o-mini',
  max_tokens: 1000,
  temperature: 0.7
});
```

**Strengths**:
- Very fast responses
- Good for straightforward tasks
- Low cost per token
- 128K context window

**Pricing**: $0.15/M input, $0.60/M output tokens

**Use when**:
- Generating daily quotes
- Simple text transformations
- Bulk content generation
- Budget constraints

### Gemini 2.5 Pro

**Best for**: Processing long documents, analyzing transcripts

```typescript
const response = await provider.complete({
  model: 'google/gemini-2.5-pro-preview-05-06',
  max_tokens: 8192
});
```

**Strengths**:
- 2 million token context window
- Good at summarization
- Handles multiple documents

**Pricing**: $1.25/M input, $5.00/M output tokens

**Use when**:
- Processing entire book chapters
- Analyzing long conversation transcripts
- Cross-referencing multiple traditions

### Llama 3.3 70B

**Best for**: Cost-effective generation, open-source compliance

```typescript
const response = await provider.complete({
  model: 'meta-llama/llama-3.3-70b-instruct',
  max_tokens: 2000
});
```

**Strengths**:
- Open source model
- Good quality/cost ratio
- 131K context

**Pricing**: ~$0.90/M tokens (varies by provider)

**Use when**:
- High volume generation
- Open-source requirements
- Cost optimization

## Task-Specific Recommendations

### Meditation Script Generation

**Primary**: `anthropic/claude-sonnet-4.5`
**Fallback**: `openai/gpt-4o`

```typescript
// Pipeline configuration
const pipelineModels = {
  architect: 'anthropic/claude-sonnet-4.5',    // Structure planning
  writer: 'anthropic/claude-sonnet-4.5',       // Prose generation
  traditionExpert: 'anthropic/claude-sonnet-4.5', // Authenticity
  reviewer: 'openai/gpt-4o-mini'               // Quality checks
};
```

**Why**: Claude excels at maintaining consistent tone and following complex instructions for meditation content.

### Daily Quotes

**Primary**: `openai/gpt-4o-mini`
**Fallback**: `meta-llama/llama-3.3-70b-instruct`

```typescript
const quote = await provider.complete({
  model: 'openai/gpt-4o-mini',
  max_tokens: 200,
  temperature: 0.9  // Higher creativity
});
```

**Why**: Simple task, high volume, cost-sensitive.

### Conversation Generation

**Primary**: `anthropic/claude-sonnet-4.5`
**Fallback**: `openai/gpt-4o`

```typescript
const conversation = await provider.complete({
  model: 'anthropic/claude-sonnet-4.5',
  max_tokens: 8000,
  temperature: 0.7
});
```

**Why**: Multi-speaker dialogues require nuanced character voices.

### Embeddings for RAG

**Primary**: `openai/text-embedding-3-small`
**High accuracy**: `openai/text-embedding-3-large`

```typescript
// Standard embeddings
const embeddings = await provider.createEmbedding({
  model: 'openai/text-embedding-3-small',
  input: texts
});

// Reduced dimensions for faster search
const fastEmbeddings = await provider.createEmbedding({
  model: 'openai/text-embedding-3-small',
  input: texts,
  dimensions: 512
});
```

### Quality Review

**Primary**: `openai/gpt-4o-mini`

```typescript
const review = await provider.complete({
  model: 'openai/gpt-4o-mini',
  system_prompt: 'You are a content quality reviewer...',
  max_tokens: 500
});
```

**Why**: Structured output, simple classification, cost-effective.

## TTS Model Selection

### Real-Time Applications

Use `eleven_flash_v2_5` for:
- Conversational AI responses
- Interactive meditation guidance
- Live feedback systems

```typescript
const audio = await provider.synthesize({
  text: 'Response text',
  model_id: 'eleven_flash_v2_5',
  voice_id: 'voice_id'
});
```

### Pre-Generated Content

Use `eleven_v3` for:
- Meditation recordings
- Course content
- Sleep stories

```typescript
const audio = await provider.synthesize({
  text: scriptContent,
  model_id: 'eleven_v3',
  voice_id: 'voice_id'
});
```

### Multi-Language Content

Use `eleven_multilingual_v2` for:
- International content
- Language learning
- Mantra pronunciation

## Cost Optimization by Task

### High Volume Tasks

| Task | Recommended | Cost/1K tokens |
|------|-------------|----------------|
| Quotes | `gpt-4o-mini` | ~$0.0004 |
| Summaries | `gpt-4o-mini` | ~$0.0004 |
| Classifications | `gpt-4o-mini` | ~$0.0004 |
| Embeddings | `text-embedding-3-small` | ~$0.00002 |

### Quality-Critical Tasks

| Task | Recommended | Cost/1K tokens |
|------|-------------|----------------|
| Meditation scripts | `claude-sonnet-4.5` | ~$0.009 |
| Tradition content | `claude-sonnet-4.5` | ~$0.009 |
| Conversations | `claude-sonnet-4.5` | ~$0.009 |

## Fallback Chains

Configure fallback chains for reliability:

```typescript
provider.configureFallbackChain({
  chat: [
    'anthropic/claude-sonnet-4.5',
    'openai/gpt-4o',
    'google/gemini-2.5-pro-preview-05-06',
    'meta-llama/llama-3.3-70b-instruct'
  ],
  embeddings: [
    'openai/text-embedding-3-small',
    'voyage-ai/voyage-3'
  ],
  images: [
    'google/gemini-2.5-flash-image-preview',
    'openai/dall-e-3'
  ]
});
```

## Temperature Guidelines

| Content Type | Temperature | Rationale |
|--------------|-------------|-----------|
| Factual content | 0.0-0.3 | Consistency |
| Meditation scripts | 0.5-0.7 | Balance |
| Creative content | 0.7-0.9 | Variation |
| Quotes | 0.8-1.0 | Creativity |

## Context Window Considerations

### Long Content

```typescript
// For long meditation scripts
const response = await provider.complete({
  model: 'google/gemini-2.5-pro-preview-05-06',  // 2M context
  messages: longConversation
});
```

### Chunking Strategy

```typescript
// For models with smaller context
const chunks = splitIntoChunks(longText, 100000);
const results = await Promise.all(
  chunks.map(chunk => provider.complete({
    model: 'openai/gpt-4o-mini',
    user_prompt: chunk
  }))
);
```

## Model Availability

Check model availability before use:

```typescript
const models = await provider.fetchModelCapabilities();
const available = models.find(m => m.id === 'anthropic/claude-sonnet-4.5');

if (!available) {
  // Use fallback
  model = fallbackChain[0];
}
```

## Best Practices

### 1. Match Model to Task Complexity

```typescript
// Simple: Use fast, cheap model
const simple = await provider.complete({
  model: 'openai/gpt-4o-mini',
  user_prompt: 'Summarize this in one sentence'
});

// Complex: Use powerful model
const complex = await provider.complete({
  model: 'anthropic/claude-sonnet-4.5',
  system_prompt: 'You are a Buddhist meditation teacher...',
  user_prompt: 'Create a 10-minute loving-kindness meditation'
});
```

### 2. Use Appropriate Max Tokens

```typescript
// Short output
max_tokens: 100  // For quotes

// Medium output
max_tokens: 500  // For summaries

// Long output
max_tokens: 4000  // For scripts
```

### 3. Cache Model Capabilities

```typescript
const provider = new OpenRouterProvider({
  modelCacheTTL: 3600000  // 1 hour cache
});
```

### 4. Monitor and Adjust

```typescript
// Track usage by model
const byModel = provider.getUsageByModel();
for (const [model, usage] of Object.entries(byModel)) {
  console.log(`${model}: ${usage.totalTokens} tokens, $${usage.estimatedCost.toFixed(4)}`);
}
```

## Related Resources

- [OpenRouter Integration Guide](./openrouter-integration.md)
- [ElevenLabs Integration Guide](./elevenlabs-integration.md)
- [Cost Optimization Guide](./cost-optimization.md)
