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 ¶
This section is empty.
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.
Types ¶
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 normalizes model and returns its price via longest-key-first prefix/substring matching against the embedded table. The second result is false when no family matches — callers MUST NOT guess a price in that case.
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