Documentation
¶
Overview ¶
Package pricing computes estimated 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. Cost reports separately whether this table knew a model's rate, because zero can also be a real estimated or provider-reported cost. Grok CLI turns that carry costUsdTicks skip this table (see the grok reducer).
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. An unknown model returns zero. 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 ¶
func Cost(model string, at time.Time, input, output, cacheWrite, cacheRead, reasoning int) (float64, bool)
Cost returns the estimated USD cost for a token count under a model at the time the usage occurred, and whether the model had a rate. Token counts are in tokens (not millions). An unknown model returns zero and false. The time selects the date-effective rate window.
func ModelNamePublic ¶ added in v0.7.4
ModelNamePublic reports whether a model identifier is safe to expose on a publicly shared overview. The catalog is an exact, fail-closed allowlist: unknown and explicitly undisclosed models return false. It uses the same normalization and direct-provider fallback as pricing.
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
Reasoning 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