Documentation
¶
Overview ¶
Package pricing maps Claude model IDs to per-million-token USD rates and computes cost for a given token mix.
Rates are sourced from a VENDORED, pinned release of the public ai-price-index dataset (github.com/RoninForge/ai-price-index). The raw artifacts live under internal/pricing/index/** (committed for audit), and internal/pricing/gen/main.go codegens table_gen.go from them at build time via `go generate`. There is NO runtime network access: the price table is embedded in the binary as generated Go.
The dataset records POINT-IN-TIME pricing: each model carries an input and an output series of half-open [from, to) intervals, so a cost can be computed as of the instant an event occurred (RatesForAt / CostForModelAt) rather than only at "now". The "now" wrappers (RatesFor / CostForModel) preserve the original behavior and signatures so existing callers compile unchanged.
To update prices: re-pin internal/pricing/PINNED_TAG to a newer dataset tag, run `go run ./internal/pricing/gen -fetch` to refresh the vendored artifacts + PROVENANCE.json, then `go generate ./internal/pricing/` to regenerate table_gen.go. The arithmetic and parity tests guard against silent drift.
Cache semantics follow Anthropic's published multipliers applied to the model's input rate:
cache read = 0.1 × input rate cache write 5m = 1.25 × input rate cache write 1h = 2.0 × input rate
The multipliers are centralized in one place (below) so a future Anthropic change only needs a single edit.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoRateAtTime = errors.New("no rate effective at time")
ErrNoRateAtTime is returned when the model is known but no price interval covers the requested instant (for example, a date before the model's earliest recorded price).
var ErrUnknownModel = errors.New("unknown model")
ErrUnknownModel is returned when a lookup sees a model identifier not in the pricing table (and not resolvable via an alias). Callers should log and skip the event rather than halting the watcher.
Functions ¶
func Cost ¶
Cost computes the total USD cost for a given (Rates, Usage) pair. Zero-cost calls are valid and return 0 without error.
func CostForModel ¶
CostForModel is the convenience one-shot at current rates: look up the model, then price the usage. Returns ErrUnknownModel if the model is unknown. Thin "now" wrapper over CostForModelAt; signature preserved.
func CostForModelAt ¶ added in v1.0.0
CostForModelAt is the point-in-time one-shot: resolve the model's rates as of at, then price the usage. Returns ErrUnknownModel for an unknown model or ErrNoRateAtTime if no interval covers at.
func KnownModels ¶
func KnownModels() []string
KnownModels returns a sorted list of model IDs that price successfully: the union of canonical series ids and alias ids. Useful for `budgetclaw pricing list` and for fuzzing tests.
func Provenance ¶ added in v1.0.0
func Provenance() (tag, commit string)
Provenance returns the pinned dataset tag and the ai-price-index repo commit the embedded pricing table was generated from. Surfaced by `budgetclaw pricing provenance` so an auditor can trace every rate to an exact upstream commit.
Types ¶
type Interval ¶ added in v1.0.0
type Interval struct {
From time.Time // inclusive lower bound, UTC midnight
To *time.Time // exclusive upper bound, UTC midnight; nil = open
Rates Rates // input/output/cache rates effective in [From, To)
}
Interval is one exported half-open [From, To) price window for a single model, derived input+output rates included. To is nil when the interval is still current (open). Returned by History for rendering the full point-in-time table to humans.
func History ¶ added in v1.0.0
History returns the full point-in-time interval series for a model, each interval carrying the rates effective in its window. The model is resolved through the alias map (and tolerates a trailing "[1m]" suffix). Returns ErrUnknownModel if the model is not known.
The series is built from the union of the input and output series boundary dates so a price change on either variation produces a new interval. The rates for each interval are resolved at its From instant, which is exactly how cost would be computed for an event at that time.
type Rates ¶
type Rates struct {
InputPerMTok float64
OutputPerMTok float64
CacheReadPerMTok float64
CacheWrite5mPerMTok float64
CacheWrite1hPerMTok float64
}
Rates is the per-million-token cost in USD for one model.
func RatesFor ¶
RatesFor returns the current pricing rates for a model (rates as of now). Unknown models produce ErrUnknownModel. This is a thin "now" wrapper over RatesForAt that preserves the original signature.
func RatesForAt ¶ added in v1.0.0
RatesForAt returns the pricing rates for a model as of instant at, including derived cache rates. The model is resolved through the alias map (and tolerates a trailing "[1m]" suffix). It returns ErrUnknownModel if the model is not known at all, or ErrNoRateAtTime if the model is known but no interval covers at.
Source Files