# Skill: Switch LLM Provider

Use when you want to change which AI model powers your agents — globally or per-agent.
The framework uses LangChain's `init_chat_model` which supports 20+ providers with one
config change.

## How the Model String Works

`arccrew/llm.py` uses LangChain's `init_chat_model()` which accepts a model string in two formats:

- **Colon format** (preferred): `provider:model_name` → `anthropic:claude-haiku-4-5-20251001`
- **Slash format** (legacy, still works): `provider/model_name` → `anthropic/claude-haiku-4-5-20251001`
- **Bare model name** (auto-detected for major providers): `claude-haiku-4-5-20251001`

The normalizer in `arccrew/llm.py` converts slash format to colon format automatically, so
both work. Use whichever you prefer in `.env`.

## Complete Provider Cheat Sheet

### Anthropic (Claude)
```
AGENT_MODEL=anthropic/claude-haiku-4-5-20251001    # Fast and cheap — tool calling, short tasks
AGENT_MODEL=anthropic/claude-sonnet-4-20250514      # Balanced — complex reasoning, long outputs
AGENT_MODEL=anthropic/claude-opus-4-20250514        # Most capable — hardest tasks, expensive
```
Install: `pip install langchain-anthropic`
Key: `ANTHROPIC_API_KEY=sk-ant-...`

### OpenAI (GPT + o-series)
```
AGENT_MODEL=openai/gpt-4o                           # Capable multimodal model
AGENT_MODEL=openai/gpt-4o-mini                      # Fast and cheap, similar to Haiku
AGENT_MODEL=openai/o3                               # Reasoning model, thinks internally
AGENT_MODEL=openai/o4-mini                          # Lightweight reasoning model
```
Install: `pip install langchain-openai`
Key: `OPENAI_API_KEY=sk-...`

### Google (Gemini)
```
AGENT_MODEL=google_genai/gemini-2.0-flash           # Fast and cheap, 1M context
AGENT_MODEL=google_genai/gemini-2.5-pro             # Most capable Gemini, huge context
AGENT_MODEL=google_genai/gemini-2.5-flash-thinking  # Flash with extended thinking
```
Install: `pip install langchain-google-genai`
Key: `GOOGLE_API_KEY=AIza...`
Note: set `GOOGLE_API_KEY` in `.env` — see `skills/configure-gemini/SKILL.md` for details.

### Groq (Ultra-fast inference)
```
AGENT_MODEL=groq/llama-3.3-70b-versatile            # Best quality on Groq
AGENT_MODEL=groq/llama-3.1-8b-instant               # Fastest, lowest cost
```
Install: `pip install langchain-groq`
Key: `GROQ_API_KEY=gsk_...` (already in `Settings`)

### OpenRouter (200+ models, one API key)
```
AGENT_MODEL=openrouter/meta-llama/llama-3.1-8b-instruct:free  # Free tier
AGENT_MODEL=openrouter/google/gemini-flash-1.5                 # Cheap and fast
AGENT_MODEL=openrouter/anthropic/claude-sonnet-4-5             # Frontier via OpenRouter
```
Install: `pip install langchain-openai`
Key: `OPENROUTER_API_KEY=sk-or-v1-...` (already in `Settings`)
See: `skills/configure-openrouter/SKILL.md` for full model catalog and per-agent mixing.

### Ollama (Local models, no API key)
```
AGENT_MODEL=ollama/llama3.2                         # Local Llama 3.2
AGENT_MODEL=ollama/llama3.1:8b                      # Local Llama 3.1 8B
AGENT_MODEL=ollama/qwen2.5                          # Local Qwen 2.5
```
Install: `pip install langchain-ollama` + Ollama running locally
No API key needed. Ollama must be running: `ollama serve`
See: `skills/configure-ollama/SKILL.md` for model recommendations and GPU requirements.

## Steps to Switch Provider

### Step 1: Update `AGENT_MODEL` in `.env`

```bash
# Before
AGENT_MODEL=anthropic/claude-haiku-4-5-20251001

# After (switch to Gemini Flash)
AGENT_MODEL=google_genai/gemini-2.0-flash
GOOGLE_API_KEY=AIza...
```

### Step 2: Install the Provider Package

Each provider needs its own LangChain integration package:

```bash
# Anthropic (default — likely already installed)
pip install langchain-anthropic

# OpenAI
pip install langchain-openai

# Google Gemini
pip install langchain-google-genai

# Groq
pip install langchain-groq

# Ollama
pip install langchain-ollama
```

### Step 3: Add API Key to `.env`

```bash
# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
OPENAI_API_KEY=sk-...

# Groq
GROQ_API_KEY=gsk_...
```

For Google, see `skills/configure-gemini/SKILL.md` — just set `GOOGLE_API_KEY` in `.env`.

### Step 4: Verify

```bash
arccrew check
```

`check` loads settings and attempts a minimal model initialization. If the key is missing
or the package is not installed, it tells you exactly what is wrong.

## Per-Agent Model Overrides

Mix providers by setting per-agent model env vars. The pattern is `{AGENT_NAME_UPPERCASE}_MODEL`:

```bash
# .env
AGENT_MODEL=anthropic/claude-haiku-4-5-20251001      # default for all agents
RESEARCHER_MODEL=anthropic/claude-sonnet-4-20250514  # researcher uses Sonnet
REVIEWER_MODEL=openai/gpt-4o                         # reviewer uses GPT-4o
```

This matches `BaseAgent(name="researcher")` → looks up `RESEARCHER_MODEL`.
The lookup is in `arccrew/llm.py`:

```python
raw_model = getattr(settings, f"{agent_name}_model", None) or settings.agent_model
```

For `getattr` to find `researcher_model`, it must be a declared field in `Settings`. Because
`Settings` uses `extra="ignore"`, pydantic-settings will read any env var that matches a
declared field. To make per-agent overrides work, add them to `arccrew/config.py`:

```python
class Settings(BaseSettings):
    ...
    # Per-agent model overrides
    researcher_model: str = ""
    writer_model: str = ""
    my_agent_model: str = ""
```

If the field is empty string (`""`), `get_model()` falls back to `agent_model` (the default).

## Temperature and Token Limits

These apply globally across all agents:

```bash
LLM_TEMPERATURE=0.3    # default — good for structured JSON output
LLM_MAX_TOKENS=4096    # default — enough for most agent outputs
LLM_TIMEOUT=120        # seconds — adjust for slow models
```

For reasoning models (OpenAI o-series), temperature should be `1.0`:
```bash
LLM_TEMPERATURE=1.0
AGENT_MODEL=openai/o3
```

## Model Comparison for Common Use Cases

| Use Case | Recommended | Why |
|----------|-------------|-----|
| Tool-heavy research agent | Haiku / gpt-4o-mini / gemini-2.0-flash | Fast, cheap, good at tool calls |
| Complex reasoning / long output | Sonnet / gpt-4o / gemini-2.5-pro | Better at multi-step reasoning |
| Code generation | Sonnet / gpt-4o | Strong code models |
| Reviewer / verifier (no tools) | Haiku / gpt-4o-mini | Short task, just needs judgment |
| Long document processing | gemini-2.0-flash | 1M token context window |
| Low latency prototype | groq/llama-3.1-8b-instant | Fastest inference available |
| Free model for non-critical tasks | openrouter/meta-llama/llama-3.1-8b-instruct:free | Zero cost |
| Multi-model pipeline (one key) | openrouter/<any-model> | 200+ models, single API key |
| Offline / private data | ollama/llama3.2 | Local, no data leaves machine |
