# OpenRouter billing for the omp-spt Librarian (S5, plan item #3)

Routing the Librarian's model spend through OpenRouter is **omp configuration, not adapter
code** — omp's provider system (`docs/providers.md` in oh-my-pi) takes custom openai-completions
providers natively, with role routing (default/smol/slow/plan) and fallback chains built in. The
adapter's whole job here is to document the fragment and note the key conventions.

## The models.yml fragment

`~/.omp/agent/models.yml` (or per-profile: `~/.omp/profiles/<name>/agent/models.yml`):

```yaml
providers:
  openrouter:
    baseUrl: https://openrouter.ai/api/v1
    api: openai-completions
    apiKey: OPENROUTER_API_KEY   # an env-var NAME (resolved at runtime) or a literal key
    models:
      - id: anthropic/claude-sonnet-5
        name: Claude Sonnet 5 (OpenRouter)
        contextWindow: 200000
        maxTokens: 8192
      # add more OpenRouter model ids as needed; omp fuzzy-matches --model against them
```

## Key resolution + .env layering

omp resolves an API key in this precedence (first wins):

1. CLI `--api-key`
2. `models.yml` `apiKey`
3. stored credential (`/login`)
4. OAuth
5. provider env / `.env` files
6. fallback resolver

`.env` layering (nearest wins): `cwd/.env` → `~/.omp/agent/.env` → `~/.omp/.env` → `~/.env`.
So the operational convention is: put `OPENROUTER_API_KEY=…` in `~/.omp/agent/.env` (machine-wide)
or the Librarian project's `.env` (project-scoped), and reference it by NAME in `models.yml`.

## Role routing

Selecting the Librarian's models at bringup is a role assignment, not adapter logic:

- default model: `--model <fuzzy>` or `/model` in-session
- `--smol` / `PI_SMOL_MODEL` — lightweight tasks (title-gen, quick classification)
- `--slow` / `PI_SLOW_MODEL` — thorough reasoning
- `--plan` / `PI_PLAN_MODEL` — architectural planning

The adapter's shims deliberately do NOT pin models (`psyche-omp`, `echo-commune-omp` run the
profile default): a hardcoded model name may not resolve against a user's provider set. Keep the
cheap-companion economics by assigning an inexpensive default (or smol) model in the profile the
Librarian endpoint runs under.

## Status on this host

The default `~/.omp` profile already routes through OpenRouter (verified live 2026-07-09:
`get_state` reports `api: openrouter`, `provider: openrouter`) — so for the Librarian bringup the
remaining choice is which models/roles to assign, not whether billing routing works.

## Isolated profile for the Librarian (optional)

`omp --profile librarian` gives the endpoint its own auth/sessions/settings/caches under
`~/.omp/profiles/librarian/`. Put the profile flag directly on the native OMP session command while
retaining the packaged SPT extension, e.g.:

```toml
[session.self]
command = "omp --profile librarian --extension {adapter_dir}/strings/omp-spt.mjs"
```