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 ¶
This section is empty.
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