Documentation
¶
Overview ¶
Package pricing computes session cost from a model rate table compiled into the binary. There is no runtime catalog or refresh: updating rates means a new build. Rates are a snapshot in USD per one million tokens and are intentionally approximate; an unknown model yields known=false so callers can mark a cost as partial rather than reporting a misleading zero.
A model's price carries a time dimension: each model maps to a list of date-effective rates, and a lookup selects the entry in effect at the usage event's time. That lets one model ID price pre-change and post-change usage differently (an introductory promo that reverts on a date, or a mid-life reprice) without inventing a second ID. A single-entry list is the common case and reproduces a flat rate: the one window is in effect for all time.
Index ¶
Constants ¶
const Version = 3
Version stamps the rate table below. Bump it whenever a rate in `table` changes: a new or removed model, a different Input/Output/CacheWrite/CacheRead number for an existing one, or a new or moved date-effective window.
It exists because a reprice makes two stored figures go stale in different ways, and only one of them is fixed by the reparse that a reprice already triggers. Per-row cost is stored on each usage_events row at parse time, so a reprice reparses the corpus (via parse.Epoch) to rewrite every row's cost; a session that fails to reparse keeps old cost, which is the honest state for a transcript the parser can no longer rebuild. The per-session cache-savings rollup is different: it is priced from usage_events, not stored per row, and a failed-reparse session keeps its old-priced rollup with cache_savings_backfilled=true, so nothing re-prices it and its tile drifts from a live SessionCacheStats recompute forever. The cache-savings reconcile (store.reconcileCacheSavingsPricingIfNeeded) closes that gap by re-pricing every cache-bearing session on a Version change, independent of whether its reparse succeeds.
Version is deliberately separate from parse.Epoch. Epoch bumps for any parser or reducer change (a new projection column, a changed field), most of which do not touch rates; keying the cache-savings reconcile off Epoch would re-price the whole corpus on every unrelated Epoch bump. A dedicated pricing Version fires that reconcile only on an actual rate change. Pair a Version bump with a parse.Epoch bump, as any reprice already must, so per-row cost and the cache-savings rollup are both rebuilt on the same deploy.
Version 1 -> 2: add claude-sonnet-5 (Sonnet 5 at the standard $3/$15 Sonnet rate). Sonnet 5 priced as unknown before, so a cache-bearing Sonnet 5 session carried an unpriced cache-savings rollup; this bump fires reconcileCacheSavingsPricingIfNeeded to re-price the cache-bearing corpus, paired with the parse.Epoch 9 -> 10 reparse that rewrites each Sonnet 5 usage row's per-row cost.
Version 2 -> 3: give claude-sonnet-5 its two-window introductory rate ($2/$10 per MTok through 2026-08-31, reverting to the $3/$15 sticker on 2026-09-01), replacing the single flat $3/$15 entry Version 2 encoded. A Sonnet 5 event logged inside the intro window now prices cheaper, so this is a reprice: it fires reconcileCacheSavingsPricingIfNeeded to re-price the cache-bearing corpus at the windowed rates, paired with the parse.Epoch 10 -> 11 reparse that rewrites each Sonnet 5 usage row's per-row cost from the window in effect at its OccurredAt.
Variables ¶
This section is empty.
Functions ¶
func CacheSavings ¶
CacheSavings returns the USD that prompt caching saved versus paying the full uncached input rate for the same prompt tokens, and whether the model was priced. The time selects the date-effective rate window, so cached volume prices at the rate in effect when it was spent.
Caching changes only the prompt side. A token served from cache (cacheRead) would otherwise be billed at the input rate; a token written to cache (cacheWrite) would otherwise be a plain input token too. So the saving is the rate gap on each, summed: cacheRead*(Input-CacheRead) + cacheWrite*(Input-CacheWrite).
For Claude the cacheWrite term is negative: cache creation is priced above input (the premium paid up front to make later reads cheap), so netting it in keeps the figure honest rather than advertising only the read discount. For OpenAI the Codex parser reports cache creation as ordinary input (CacheWrite is unset and cacheWrite tokens are nil), so the write term vanishes and the saving is the read discount alone. The result can be negative in principle (cache written but never re-read) and is returned unfloored, so a caller can surface that caching cost more than it saved.
Counts are int64, not the int that Cost takes: this is the one pricing entry point fed rolled, fleet-wide aggregates, whose cache-read sum over a long window can run past a 32-bit range, where Cost only ever sees a single session's tokens. A caller that rolls many events into one figure must bucket them so every event in a bucket falls in one rate window (see store/analytics_cache.go), since a single time picks a single window for the whole sum.
func Cost ¶
Cost returns the USD cost for a token count under a model at the time the usage occurred, and whether the model was priced. Token counts are in tokens (not millions). The time selects the date-effective rate window.
func Known ¶ added in v0.2.7
Known reports whether a model is priced at all, independent of any date. A model's windows all share one ID, so its presence in the table does not depend on when it ran; a by-model view that only needs to fold unpriced models into an "Other" bucket asks this rather than picking an arbitrary window's rate.
Types ¶
type DatedRate ¶ added in v0.2.7
type DatedRate struct {
From time.Time // inclusive lower bound; zero value = in effect from the beginning
Rate Rate
}
DatedRate is a rate that took effect on a date and stays in effect until the next window's From. From is inclusive; the zero value means "since the beginning", the open-ended first window every model has. A model's windows are sorted by From ascending, so a lookup walks them and keeps the last one whose From is at or before the event time.
type Rate ¶
type Rate struct {
Input float64
Output float64
CacheWrite float64 // cache creation
CacheRead float64
}
Rate holds per-million-token prices for one model family.
func RateAt ¶ added in v0.2.7
RateAt returns the rate for a model at a point in time, and whether it was found. The model string is normalized (lowercased, trimmed, and stripped of a trailing release-date snapshot) and then matched exactly against the table. There is no prefix matching: a key prices only its exact model, so a model we have not listed reports known=false rather than inheriting a neighbor's price. The time selects the date-effective window (see rateAt).
Source Files