Documentation
¶
Overview ¶
Package budget defines resource tracking types for loop execution. SP1 stub extended by SP3 (governance): adds Budget caps, Ledger enforcement, subtree Grant arithmetic, and BudgetExceededError. All types remain backward-compatible with the SP1 Spend/Dimension base.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Budget ¶
type Budget struct {
// Tokens is the maximum total tokens (input+output). 0 = unlimited.
Tokens int64
// USD is the maximum monetary cost. 0 = unlimited.
USD float64
// WallClock is the maximum elapsed time. 0 = unlimited.
WallClock time.Duration
// Iterations is the maximum number of loop iterations. 0 = unlimited.
Iterations int
}
Budget declares the maximum allowed spend across each dimension. Zero values mean unlimited for that dimension.
func (Budget) Grant ¶
Grant carves a child budget out of a parent. It validates that the child does not exceed the remaining parent capacity (parent budget − parent spent). A zero child dimension inherits unlimited for that dimension. Returns (child, nil) on success, or (Budget{}, error) if child > remaining.
type BudgetExceededError ¶
type BudgetExceededError struct {
// Dimension is the axis that was exhausted.
Dimension Dimension
// Spent is the current accumulated spend at time of refusal.
Spent Spend
// Budget is the configured limit that was breached.
Budget Budget
}
BudgetExceededError is returned by Ledger.Authorize when a budget limit would be breached.
func (*BudgetExceededError) Error ¶
func (e *BudgetExceededError) Error() string
type Dimension ¶
type Dimension string
Dimension identifies which budget axis is being tracked or has been exceeded.
const ( // DimensionTokens tracks LLM token consumption. DimensionTokens Dimension = "tokens" // DimensionUSD tracks monetary cost. DimensionUSD Dimension = "usd" // DimensionWallClock tracks elapsed real time. DimensionWallClock Dimension = "wallclock" // DimensionIterations tracks the number of loop iterations. DimensionIterations Dimension = "iterations" )
type Estimate ¶
Estimate is a pre-authorization request before an action executes. Fields are additive: the estimate projects future spend.
type Ledger ¶
type Ledger struct {
// contains filtered or unexported fields
}
Ledger is a pure fold over BudgetCharged events. It tracks cumulative spend and enforces budget caps. Create with NewLedger; use Authorize before an action and Charge after.
func NewLedger ¶
NewLedger creates a Ledger enforcing the given budget caps. Zero values in budget mean unlimited for that dimension.
func (*Ledger) Authorize ¶
Authorize checks whether the projected spend (current + estimate) would exceed any budget cap. Returns *BudgetExceededError if so, nil otherwise. Authorize does NOT modify the ledger state.
func (*Ledger) BudgetCaps ¶
Budget returns the configured budget caps.
func (*Ledger) Charge ¶
Charge adds the actual spend to the ledger. It is idempotent for replay: callers must not double-charge.
type Spend ¶
type Spend struct {
// Tokens is the total number of LLM tokens consumed (input + output).
Tokens int64
// USD is the monetary cost in US dollars.
USD float64
// WallClock is the total elapsed wall-clock time.
WallClock time.Duration
// Iterations is the number of loop iterations completed.
Iterations int
}
Spend tracks accumulated resource consumption across all budget dimensions. All fields are additive. Zero value means no spend.
Source Files