Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/backends.md
Original file line number Diff line number Diff line change
Expand Up @@ -629,6 +629,14 @@ rankings and cache-penalty analysis substitute the input rate for a missing cach
rate so absent metadata cannot make a model look free; API-equivalent totals and token
economics keep the catalog's zero rate and flag it.

Snapshot rows keep card facts beside the rates (`CARD_INFO_KEYS`): a `reasoning` rate
only where it differs from output (tiers carry their own), release date, knowledge
cutoff, maximum output, open weights, and `type` only for non-chat models.
`reasoning_price()` follows the same card selection as `model_price()`, so per-request
costs, token economics and `w` (both frontends) bill reasoning at it; a tier without its
own reasoning rate uses the tier's output. `model_card_info()` and `catalog_card()`
expose the facts for `P` and the programmatic model listings.

Explicit context-tier tables win over legacy `context_over_200k`, which alone implies a
200,000-token boundary. Numeric request-context buckets, not dollars, survive rollups,
warm caches and machine exports, so a rate refresh reprices without rereading
Expand Down
33 changes: 28 additions & 5 deletions docs/pricing.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,8 @@ session's recorded tokens cost if one model had produced them all?
| `Enter` | Select the target |

Your used models are ranked by token usage. Catalog models are ranked by effective
price at your overall token mix. If none of your models has a price, the catalog opens
price at your overall token mix; embedding, image, speech and other non-chat models
are left out. If none of your models has a price, the catalog opens
directly. `w` works in demo mode and is never remembered between runs.

Where it shows:
Expand Down Expand Up @@ -109,7 +110,7 @@ tokens while output accounts for most of the price.
|------|-----------|
| Uncached input | Input rate |
| Output | Output rate |
| Reasoning | Output rate; counted separately only when the harness records it apart from output |
| Reasoning | Output rate, or the card's own reasoning rate where models.dev publishes one (some Qwen and DeepSeek routes); counted separately only when the harness records it apart from output |
| Cache read | Cache-read rate |
| Cache write | Cache-write rate ([lifetimes](#cache-write-lifetimes)) |

Expand Down Expand Up @@ -141,7 +142,9 @@ and marked `~` with an explanation in Token economics. That happens for summary-
records, older exports, Codex deltas that span several requests, and VS Code chat.
CSV/JSONL producers can supply `context_tokens` to avoid it.

The `P` table shows **base rates**; tiers apply per request, not to monthly totals.
The `P` table shows **base rates** with a `↑272k` tag on rows whose rates rise; tiers
apply per request, not to monthly totals. `Enter` on a row lists each tier's rates and
how much of your list cost ran at them ([model card](#the-model-card)).

### Cache-write lifetimes

Expand Down Expand Up @@ -206,22 +209,42 @@ Press `p` (or `h` / `l`, or click a tab) to switch:

In the models.dev view the same model repeats across gateways on purpose: resale
markups are the point. Your models keep their use bar on every route that sells them.
Free and local models are left out, and a tag marks alpha, beta and deprecated models.
Free and local models are left out, and a tag marks alpha, beta and deprecated models
and non-chat ones such as `embedding`. In every view, `↑272k` marks rates that rise
above that request context.

### The model card

`Enter` opens a row's sessions under a card with what models.dev knows about it:

| Line | Shows |
|------|-------|
| **List rates** | The row's rates, plus a reasoning rate where the card publishes one that differs from output |
| **Above 272k** | Each context tier's rates; a request over the threshold bills whole at them |
| **Your use** | The share of your list cost that ran at long-context rates, and the share whose request size is unknown, which is priced at base |
| **Model** | Release date, knowledge cutoff, context window, maximum output, open weights, model type |
| **Cheapest route** | For open-weight models, a provider selling the same model at least 5% cheaper at your mix, with your reasoning tokens billed at each provider's own reasoning rate. Free cards, local servers and subscription routes such as Copilot don't count, and hosts can differ in quantization and limits. Closed models get no such line: a far cheaper route for one is grey-market resale |

Lines without data are left out. Your use follows the table's scope: all time, the
current identity filters, ignored sessions per `I`.

### Keys

| Key | Action |
|-----|--------|
| `j` / `k` | Select a row |
| `Space` | Pin the row to a ★ shortlist shown first in every view; pinning a catalog row pins only that route. Remembered between runs |
| `Enter` | Show the sessions that used the model, across routes and spellings |
| `Enter` | Show the model card and the sessions that used the model, across routes and spellings |
| `s` (or click a header) | Sort by model, eff, use or a rate |
| `~` (or click the header again) | Reverse the sort |
| `f` | Filter by model, vendor or route; matches word starts, so `opus48` and `snt45` work |
| `r` | Refresh rates from models.dev |
| `p` / `h` / `l` | Switch views |

The web browser has the same table on `P`, with clickable ☆/★ pins saved in the browser.
Click a row to expand its model card. In the models.dev view the browser's card has
rates, tiers and type only, because the facts for thousands of catalog rows would bloat
every report.

## Refreshing rates

Expand Down
6 changes: 6 additions & 0 deletions docs/programmatic.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,12 @@ For `models list`, `--search` matches model names. With `--catalog` it browses t
price list without opening sessions, and only `--search`, `--limit`, `--offset`,
`--no-state` and `--pretty` apply.

Each model row carries its `*_usd_per_mtok` rates, including `reasoning_usd_per_mtok`
(the output rate unless the card publishes its own), and models.dev's card facts:
`context_tiers` (rates above `above_context_tokens`, per request), `release_date`,
`knowledge_cutoff`, `max_output_tokens`, `open_weights` and `model_type`. Facts the
catalog lacks are `null`; `model_type` is `null` only for a model with no catalog card.

### Dates select whole sessions

A range selects sessions by the day their **root session started**, and each one
Expand Down
3 changes: 3 additions & 0 deletions docs/tui.md
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,9 @@ together. `get_wch` reads characters rather than UTF-8 bytes; `_read_key` return
ASCII and special keys as integers, other characters as strings. Both forms go
through action lookup, so non-ASCII keys can be bound as well as typed. Text
prompts budget input length separately from visible width and scroll long input.
A held key queues repeats faster than a frame paints; `_drain_repeats` handles
queued copies of the same key before the next paint (at least every 100 ms), so
motion stops on release. A different key or a click waits for that paint.

Search uses `[search.edit]`, `[search]` and shared `[menu]` bindings. Its tabs,
pickers, footer, help and mouse regions reuse existing renderers. Results splits
Expand Down
3 changes: 3 additions & 0 deletions src/opentab/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@
"cache_ttl_seconds",
"cache_write_1h_price",
"canonical_model",
"catalog_card",
"catalog_models",
"display_model",
"effective_price",
Expand All @@ -75,12 +76,14 @@
"is_local_provider",
"model_context_window",
"model_family",
"model_card_info",
"model_matches",
"model_price",
"price_cache_meta",
"price_cache_path",
"price_source_meta",
"prune_models_dev",
"reasoning_price",
"refresh_model_prices",
),
),
Expand Down
Loading
Loading