# Skill: Configure OpenRouter

Use when you want to access 200+ models (Claude, GPT, Gemini, Llama, Mistral, etc.)
through a single API key, or when you want to run free or cheap models for tasks that
don't need a frontier model.

OpenRouter provides an OpenAI-compatible API. arccrew handles the routing automatically
when you set `AGENT_MODEL=openrouter/...`.

## API Key Setup

```bash
# .env
OPENROUTER_API_KEY=sk-or-v1-...
```

`OPENROUTER_API_KEY` is already declared in `Settings` (`arccrew/config.py`) and exported
to `os.environ`. No config changes needed.

Get a key at: https://openrouter.ai/keys
Free tier is available — many models have a `:free` variant.

## Model Strings

```bash
# Free models (no credits required)
AGENT_MODEL=openrouter/meta-llama/llama-3.1-8b-instruct:free
AGENT_MODEL=openrouter/google/gemma-3-12b-it:free
AGENT_MODEL=openrouter/microsoft/phi-4-reasoning:free

# Paid — cheap and fast (fraction of frontier model cost)
AGENT_MODEL=openrouter/google/gemini-flash-1.5        # Very cheap, fast, good at tool calls
AGENT_MODEL=openrouter/meta-llama/llama-3.1-70b-instruct
AGENT_MODEL=openrouter/mistralai/mistral-small-3.2

# Frontier models via OpenRouter (same model, potentially cheaper with credits)
AGENT_MODEL=openrouter/anthropic/claude-sonnet-4-5
AGENT_MODEL=openrouter/openai/gpt-4o
AGENT_MODEL=openrouter/google/gemini-2.5-pro
```

Full model catalog: https://openrouter.ai/models

## Install

No additional package needed beyond what arccrew already requires:

```bash
pip install langchain-openai   # required for OpenRouter routing
```

`langchain-openai` is typically already installed as a transitive dependency.

## How It Works

arccrew's `llm.py` detects the `openrouter/` prefix and instantiates `ChatOpenAI`
with `base_url="https://openrouter.ai/api/v1"` and your `OPENROUTER_API_KEY`.
The model name (everything after `openrouter/`) is passed directly to OpenRouter.

This means **the model string format is `openrouter/<openrouter-model-id>`**, where
the model ID uses the same format as OpenRouter's catalog (`provider/model-name`).

## Per-Agent Overrides

The main use case for OpenRouter is **mixing cheap and expensive models per agent**:

```bash
# .env
AGENT_MODEL=anthropic/claude-haiku-4-5-20251001       # default (Anthropic direct)

# Use free Llama for the researcher, frontier Claude for the writer
RESEARCHER_MODEL=openrouter/meta-llama/llama-3.1-8b-instruct:free
WRITER_MODEL=anthropic/claude-sonnet-4-20250514
```

Add per-agent fields to `arccrew/config.py` → `Settings`:
```python
researcher_model: str = ""
writer_model: str = ""
```

## Model Recommendations by Task

| Task | Recommended OpenRouter model | Why |
|------|------------------------------|-----|
| Simple tool calls, routing | `meta-llama/llama-3.1-8b-instruct:free` | Free, fast enough |
| Research / summarization | `google/gemini-flash-1.5` | Cheap, large context |
| Complex reasoning | `meta-llama/llama-3.1-70b-instruct` | Strong reasoning, cheaper than Claude |
| Code generation | `anthropic/claude-sonnet-4-5` | Best code model on OpenRouter |
| Budget-conscious prod | `mistralai/mistral-small-3.2` | Good balance of quality and cost |

## `:free` Tier Notes

Free models on OpenRouter:
- Rate limited (typically 10-20 req/min)
- May have longer queue times at peak hours
- Good for development and low-volume pipelines
- Not suitable for high-throughput production workloads

## Verify Configuration

```bash
arccrew check
```

Common errors:
- `OPENROUTER_API_KEY is not set` → add key to `.env`
- `langchain-openai not found` → `pip install langchain-openai`
- HTTP 401 → invalid or expired API key
- HTTP 429 → rate limit hit, reduce concurrency or upgrade plan
