Affected by 
Documentation
¶
Index ¶
- Constants
- func CompileFromCache(exprStr string) (*vm.Program, error)
- func CompileFromCacheByHash(exprStr, hash string) (*vm.Program, error)
- func ExprHashString(expr string) string
- func ExprVersion(exprStr string) int
- func InvalidateCache()
- func ParseExprVersion(exprStr string) (version int, body string)
- func QuotaRound(f float64) int
- func UsedVars(exprStr string) map[string]bool
- type BillingSnapshot
- type RequestInput
- type TieredResult
- type TokenParams
- type TraceResult
- func RunExpr(exprStr string, params TokenParams) (float64, TraceResult, error)
- func RunExprByHash(exprStr, hash string, params TokenParams) (float64, TraceResult, error)
- func RunExprByHashWithRequest(exprStr, hash string, params TokenParams, request RequestInput) (float64, TraceResult, error)
- func RunExprWithRequest(exprStr string, params TokenParams, request RequestInput) (float64, TraceResult, error)
Constants ¶
const DefaultExprVersion = 1
DefaultExprVersion is used when an expression string has no version prefix.
Variables ¶
This section is empty.
Functions ¶
func CompileFromCache ¶
CompileFromCache compiles an expression string, using a cached program when available. The cache is keyed by the SHA-256 hex digest of the expression.
func CompileFromCacheByHash ¶
CompileFromCacheByHash is like CompileFromCache but accepts a pre-computed hash, useful when the caller already has the BillingSnapshot.ExprHash.
func ExprHashString ¶
ExprHashString returns the SHA-256 hex digest of an expression string.
func ExprVersion ¶
ExprVersion returns the version of a cached expression. Returns DefaultExprVersion if the expression hasn't been compiled yet or is empty.
func InvalidateCache ¶
func InvalidateCache()
InvalidateCache clears the compiled-expression cache. Called when billing rules are updated.
func ParseExprVersion ¶
ParseExprVersion extracts the version tag and body from an expression string. Format: "v1:tier(...)" → version=1, body="tier(...)". No prefix defaults to DefaultExprVersion.
func QuotaRound ¶
QuotaRound converts a float64 quota value to int using half-away-from-zero rounding. Every tiered billing path (pre-consume, settlement, breakdown validation, log fields) MUST use this function to avoid +-1 discrepancies.
Types ¶
type BillingSnapshot ¶
type BillingSnapshot struct {
BillingMode string `json:"billing_mode"`
ModelName string `json:"model_name"`
ExprString string `json:"expr_string"`
ExprHash string `json:"expr_hash"`
GroupRatio float64 `json:"group_ratio"`
EstimatedPromptTokens int `json:"estimated_prompt_tokens"`
EstimatedCompletionTokens int `json:"estimated_completion_tokens"`
EstimatedQuotaBeforeGroup float64 `json:"estimated_quota_before_group"`
EstimatedQuotaAfterGroup int `json:"estimated_quota_after_group"`
EstimatedTier string `json:"estimated_tier"`
QuotaPerUnit float64 `json:"quota_per_unit"`
ExprVersion int `json:"expr_version"`
}
BillingSnapshot captures the billing rule state frozen at pre-consume time. It is fully serializable and contains no compiled program pointers.
type RequestInput ¶
type TieredResult ¶
type TieredResult struct {
ActualQuotaBeforeGroup float64 `json:"actual_quota_before_group"`
ActualQuotaAfterGroup int `json:"actual_quota_after_group"`
MatchedTier string `json:"matched_tier"`
CrossedTier bool `json:"crossed_tier"`
}
TieredResult holds everything needed after running tiered settlement.
func ComputeTieredQuota ¶
func ComputeTieredQuota(snap *BillingSnapshot, params TokenParams) (TieredResult, error)
ComputeTieredQuota runs the Expr from a frozen BillingSnapshot against actual token counts and returns the settlement result.
func ComputeTieredQuotaWithRequest ¶
func ComputeTieredQuotaWithRequest(snap *BillingSnapshot, params TokenParams, request RequestInput) (TieredResult, error)
type TokenParams ¶
type TokenParams struct {
P float64 // prompt tokens (text)
C float64 // completion tokens (text)
CR float64 // cache read (hit) tokens
CC float64 // cache creation tokens (5-min TTL for Claude, generic for others)
CC1h float64 // cache creation tokens — 1-hour TTL (Claude only)
Img float64 // image input tokens
ImgO float64 // image output tokens
AI float64 // audio input tokens
AO float64 // audio output tokens
}
TokenParams holds all token dimensions passed into an Expr evaluation. Fields beyond P and C are optional — when absent they default to 0, which means cache-unaware expressions keep working unchanged.
type TraceResult ¶
TraceResult holds side-channel info captured by the tier() function during Expr execution. This replaces the old Breakdown mechanism — the Expr itself is the single source of truth for billing logic.
func RunExpr ¶
func RunExpr(exprStr string, params TokenParams) (float64, TraceResult, error)
RunExpr compiles (with cache) and executes an expression string. The environment exposes:
- p, c — prompt / completion tokens
- cr, cc, cc1h — cache read / creation / creation-1h tokens
- tier(name, value) — trace callback that records which tier matched
- max, min, abs, ceil, floor — standard math helpers
Returns the resulting float64 quota (before group ratio) and a TraceResult with side-channel info captured by tier() during execution.
func RunExprByHash ¶
func RunExprByHash(exprStr, hash string, params TokenParams) (float64, TraceResult, error)
RunExprByHash is like RunExpr but accepts a pre-computed hash for the cache lookup, avoiding a redundant SHA-256 computation when the caller already holds BillingSnapshot.ExprHash.
func RunExprByHashWithRequest ¶
func RunExprByHashWithRequest(exprStr, hash string, params TokenParams, request RequestInput) (float64, TraceResult, error)
func RunExprWithRequest ¶
func RunExprWithRequest(exprStr string, params TokenParams, request RequestInput) (float64, TraceResult, error)
Source Files