Documentation
¶
Overview ¶
SSOT & update mechanism ────────────────────────
This package is the single source of truth for LLM model pricing across deepwork-terminal and deepwork-pro. Both consume it as peers; neither owns it.
The embedded priceTable (table.go) is a hand-curated SNAPSHOT of LiteLLM's model_prices_and_context_window.json — the same dataset ccusage uses. It carries no network code by design: pricing must be deterministic, offline, and reviewable in a diff. To update prices, edit table.go directly with the new LiteLLM values (USD per million tokens) and re-run the tests, which pin the ccusage-verified anchors.
Cost is computed PER REQUEST, with two refinements over a flat table:
- Cache-write is split by TTL: CacheWrite5m (5-minute, 1.25× input) vs CacheWrite1h (1-hour, 2× input). The transcript usage exposes these as cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens.
- A long-context PREMIUM tier (ModelPrice.Above) applies when a request's context exceeds ModelPrice.ContextThreshold (OpenAI gpt-5.4/5.5: 272000; Gemini 2.5-pro / 3-pro: 200000). Anthropic 4.x has no context tier.
Future (OPTIONAL, not implemented now): a `go:generate` directive could fetch the upstream LiteLLM JSON and regenerate table.go, and a `Refresh`-style API could hot-reload from a cached file. Both are deferred — the snapshot is sufficient and keeps the package free of network dependencies. Do not add network code here without an explicit decision to take on that complexity.
//go:generate go run ./internal/gen-table // future: regenerate from LiteLLM JSON
Package pricing is the single source of truth (SSOT) for LLM model pricing and cost calculation across Brightman AI projects. It maps a model id to a per-token price table and computes the USD cost of a SINGLE REQUEST's token usage record.
The numbers match ccusage, which sources its prices from LiteLLM's official model_prices_and_context_window.json. Prices are expressed in USD per MILLION tokens (USD/MTok). Token classes (one request):
- Input — fresh prompt tokens.
- Output — generated completion tokens.
- CacheRead — tokens served from a prompt cache (cache-read), cheapest.
- CacheWrite5m — tokens written into a 5-minute-TTL prompt cache (Anthropic: 1.25× input). OpenAI/codex and Gemini have NO cache-write tier (0).
- CacheWrite1h — tokens written into a 1-hour-TTL prompt cache (Anthropic: 2× input). A 0 rate in the table falls back to the 5m rate.
Two billing tiers exist:
- BASE tier — the embedded Tier prices.
- ABOVE tier (long-context premium) — OpenAI gpt-5.x and Gemini roughly double per-token prices once a request's context exceeds ContextThreshold tokens (gpt-5.4/5.5: 272000; gemini 2.5-pro / 3-pro: 200000). Anthropic 4.x models have NO context tier (ContextThreshold == 0, Above == nil).
Cost is computed PER REQUEST because the context-tier decision is per-request; a caller sums Cost over the requests of a session. It lives in the shared kit (github.com/brightman-ai/kit), consumed equally by deepwork-terminal and deepwork-pro. Neither owns it; the SSOT is here.
Index ¶
- Constants
- func Cost(model string, u Usage) (cost float64, currency string, ok bool)
- func CostAt(q RequestQuery, u Usage) (cost float64, currency string, ok bool)
- func FastCreditMultiplier(model, speed string) (float64, bool)
- type Catalog
- type ModelPrice
- type RequestQuery
- type RequestQuote
- type Tier
- type Usage
Constants ¶
const CatalogVersion = "2026-07-15.2"
CatalogVersion identifies the immutable pricing snapshot used by a quote. Updating a price creates new effective-dated rules and a new version; it does not rewrite historical request facts.
const FastModeSourceURL = "https://developers.openai.com/codex/agent-configuration/speed"
Variables ¶
This section is empty.
Functions ¶
func Cost ¶
Cost returns the USD (or CNY) cost of ONE request u for model.
It first picks the billing tier: context := Input + CacheRead + CacheWrite5m + CacheWrite1h; when ContextThreshold > 0 && context > ContextThreshold and an Above tier exists, the Above (long-context premium) prices apply, otherwise the base Tier. Within the tier, cache-write tokens are charged per TTL: 5m tokens at CacheWrite5mPerM, 1h tokens at CacheWrite1hPerM (falling back to the 5m rate when CacheWrite1hPerM == 0). When the model is unknown, ok is false and cost is 0 — the cost is NEVER guessed from a fallback price.
func CostAt ¶ added in v0.16.0
func CostAt(q RequestQuery, u Usage) (cost float64, currency string, ok bool)
CostAt prices one request with its timestamp and billing service tier.
func FastCreditMultiplier ¶ added in v0.16.0
FastCreditMultiplier returns a multiplier only for an explicit Fast mode and a model with an official published multiplier. service_tier=priority is not Fast evidence and must never call this function with speed="fast" implicitly.
Types ¶
type Catalog ¶ added in v0.16.0
type Catalog struct {
// contains filtered or unexported fields
}
Catalog owns effective-dated request pricing. It is immutable after build.
func DefaultCatalog ¶ added in v0.16.0
func DefaultCatalog() Catalog
func (Catalog) Quote ¶ added in v0.16.0
func (c Catalog) Quote(q RequestQuery) (RequestQuote, bool)
Quote returns the most specific effective rule. Missing/unknown billing evidence never falls through to a guessed provider-family rate.
type ModelPrice ¶
type ModelPrice struct {
Tier // base prices (embedded)
Currency string // "USD" or "CNY"
ContextThreshold int // tokens; context > this → Above tier applies (0 = no long-context tier)
Above *Tier // long-context prices (nil = none)
}
ModelPrice is the per-million-token price of a model: a base Tier plus an optional long-context premium Tier (Above) that applies once a request's context exceeds ContextThreshold tokens.
func Lookup ¶
func Lookup(model string) (ModelPrice, bool)
Lookup returns the currently effective standard-tier price. New request-level code should call LookupAt with the request timestamp and service tier so historical prices and priority processing remain auditable.
type RequestQuery ¶ added in v0.16.0
RequestQuery contains only request-time billing evidence. Effort is retained for explainability but deliberately does not participate in unit-price selection: effort changes token use and latency, not provider token rates.
type RequestQuote ¶ added in v0.16.0
type RequestQuote struct {
RuleID string
CatalogVersion string
SourceURL string
EffectiveFrom time.Time
EffectiveUntil *time.Time
Price ModelPrice
CreditsPerM *Tier
}
RequestQuote is the auditable API-equivalent price selected for one request. CreditsPerM is populated only where the provider publishes a token-to-credit schedule; it is separate from API-equivalent currency cost.
type Tier ¶ added in v0.4.0
type Tier struct {
InputPerM float64 // USD per 1M input tokens
OutputPerM float64 // USD per 1M output tokens
CacheReadPerM float64 // USD per 1M cache-read tokens (cheapest)
CacheWrite5mPerM float64 // USD per 1M cache-write tokens, 5-minute TTL (Anthropic: 1.25× input)
CacheWrite1hPerM float64 // USD per 1M cache-write tokens, 1-hour TTL (Anthropic: 2× input); 0 → fall back to 5m
}
Tier is the per-MILLION-token unit prices for one billing tier. CacheWrite5m/CacheWrite1h are 0 for providers without a cache-write tier (OpenAI, Gemini, Chinese vendors). CacheWrite1h == 0 means "fall back to the 5m rate" — never free unless CacheWrite5m is also 0.
Source Files