billingexpr

package
v1.1.10 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 7 Imported by: 0

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

View Source
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

func Validate

func Validate(source string) error

Validate compiles an expression and evaluates it against sample usage. The result must be a finite, non-negative number.

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 Compile

func Compile(source string) (*Program, error)

Compile parses and checks an expression. Compiled programs are cached by source.

func (*Program) EvalUSD

func (p *Program) EvalUSD(env Env) (float64, error)

EvalUSD evaluates the expression and converts the result to USD.

func (*Program) EvalUSDWithTrace

func (p *Program) EvalUSDWithTrace(env Env) (float64, string, error)

EvalUSDWithTrace evaluates the expression and returns the USD amount and any tier name recorded by tier(name, expr).

func (*Program) FoldTokens

func (p *Program) FoldTokens(numbers map[string]float64)

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.

func (*Program) Source

func (p *Program) Source() string

Source returns the original expression text.

func (*Program) Uses

func (p *Program) Uses(name string) bool

Uses reports whether the expression references a variable.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL