Documentation
¶
Overview ¶
Package billingexpr implements a small, dependency-free pricing expression language. An expression evaluates to USD per million tokens summed over token variables, so "p * 3 + c * 15" bills $3/M input and $15/M output. usd(x) adds a fixed USD amount. Token buckets that an expression does not reference are folded into their parent bucket before evaluation, so a missing term never undercharges.
Index ¶
Constants ¶
const ( VarInput = "p" // uncached text input VarOutput = "c" // non-reasoning text output VarReasoning = "r" // reasoning output VarCacheRead = "cr" // cache reads VarCacheWrite = "cc" // 5-minute cache writes VarCacheWrite30m = "cc30m" // 30-minute cache writes VarCacheWrite1h = "cc1h" // 1-hour cache writes VarCacheWrite12h = "cc12h" // 12-hour cache writes VarImageInput = "img" // image input VarImageOutput = "imgo" // image output VarAudioInput = "ai" // audio input VarAudioOutput = "ao" // audio output VarVideoInput = "vi" // video input VarVideoOutput = "vo" // video output VarFileInput = "fi" // file/document input VarImageCacheRead = "img_cr" // cached image input tokens VarAudioCacheRead = "acr" // cached audio input tokens VarCachedText = "ct" // cached text input tokens VarAcceptedPrediction = "apred" // accepted prediction tokens VarRejectedPrediction = "rpred" // rejected prediction tokens VarTotalTokens = "total" // total input + output tokens VarContextLength = "len" // full prompt context, for conditions only VarRequest = "req" // 1 on success, 0 on failure; "req * usd(0.01)" bills per request VarWebSearchCalls = "ws" // web search calls; bill with "ws * usd(0.01)" VarWebSearchQueries = "wsq" // web search queries VarWebFetchCalls = "wf" // web fetch calls VarXSearchCalls = "xs" // X search calls VarCodeExecutionCalls = "ce" // code execution / interpreter calls VarFileSearchCalls = "fs" // file / collections search calls VarDocumentSearchCalls = "ds" // document / attachment search calls VarMCPCalls = "mcp" // remote MCP tool calls VarGoogleMapsChunks = "maps" // Gemini Google Maps grounding chunks VarNumSourcesUsed = "src" // sources used (e.g. xAI Live Search) VarNumServerSideToolsUsed = "st" // total server-side tool invocations VarPromptMedia = "pmedia" // prompt media count VarCompletionMedia = "cmedia" // completion media count VarPromptAudio = "paudio" // prompt audio count VarImages = "imgn" // generated images; bill with "imgn * usd(0.04)" VarImageCountAlias = "image_count" // new-api alias for imgn VarImageOutputAlias = "img_o" // new-api alias for imgo VarAudioSeconds = "asec" // audio/video duration in seconds; bill with "asec * usd(0.001)" VarUpstreamCost = "upcost" // upstream reported cost in USD; bill with "usd(upcost)" VarTier = "tier" VarUpstreamTier = "upstream_tier" VarSpeed = "speed" VarGeo = "geo" VarCacheTTL = "cache_ttl" VarImageSize = "img_size" VarImageResolution = "img_res" VarImageQuality = "img_quality" VarImageAspectRatio = "img_ratio" VarImageTier = "img_tier" VarBYOK = "byok" VarResponseModel = "response_model" VarEffort = "effort" VarModel = "model" VarProvider = "provider" VarEndpoint = "endpoint" )
Token variables, in tokens. Their coefficients are USD per million tokens.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Env ¶
type Env struct {
Numbers map[string]float64
Strings map[string]string
LookupNumber func(path string) float64
LookupString func(path string) string
Now time.Time
MatchedTier string
}
Env supplies variable values, dynamic lookup hooks, and the evaluation clock.
type Program ¶
type Program struct {
// contains filtered or unexported fields
}
Program is a compiled expression.
func (*Program) EvalUSDWithTrace ¶
EvalUSDWithTrace evaluates the expression and returns the USD amount and any tier name recorded by tier(name, expr).
func (*Program) FoldTokens ¶
FoldTokens moves token buckets the program does not reference into their parent bucket so every reported token is billed at least at the parent coefficient.