spendcontrol

Documentation

Overview

Package spendcontrol enforces spending limits for LLM requests using rolling time windows and per-session budgets.

Index

• func DefaultFilePath() string
• type CheckResult
• type FileSpendControlStorage
  • func NewFileStorage() *FileSpendControlStorage
  • func (fs *FileSpendControlStorage) Load() (*persistedState, error)
  • func (fs *FileSpendControlStorage) Save(state persistedState) error
• type InMemorySpendControlStorage
  • func (m *InMemorySpendControlStorage) Load() (*persistedState, error)
  • func (m *InMemorySpendControlStorage) Save(state persistedState) error
• type SpendControl
  • func New(storage SpendControlStorage) (*SpendControl, error)
  • func (sc *SpendControl) Check(estimatedCost float64) CheckResult
  • func (sc *SpendControl) Cleanup() error
  • func (sc *SpendControl) ClearLimit(window SpendWindow) error
  • func (sc *SpendControl) GetHistory() []SpendRecord
  • func (sc *SpendControl) GetLimits() SpendLimits
  • func (sc *SpendControl) GetRemaining() map[SpendWindow]float64
  • func (sc *SpendControl) GetSpending() map[SpendWindow]float64
  • func (sc *SpendControl) GetStatus() map[SpendWindow]StatusEntry
  • func (sc *SpendControl) Record(amount float64, model, action string) error
  • func (sc *SpendControl) SetLimit(window SpendWindow, amount float64) error
• type SpendControlStorage
• type SpendLimits
• type SpendRecord
• type SpendWindow
• type StatusEntry

Functions

func DefaultFilePath

func DefaultFilePath() string

DefaultFilePath returns ~/.dosrouter/spending.json.

Types

type CheckResult

type CheckResult struct {
	Allowed   bool        `json:"allowed"`
	BlockedBy SpendWindow `json:"blockedBy,omitempty"`
	Remaining float64     `json:"remaining"`
	Reason    string      `json:"reason,omitempty"`
	ResetIn   string      `json:"resetIn,omitempty"`
}

CheckResult is the outcome of a spend check.

type FileSpendControlStorage

type FileSpendControlStorage struct {
	Path string
}

FileSpendControlStorage reads and writes JSON to disk.

func NewFileStorage

func NewFileStorage() *FileSpendControlStorage

NewFileStorage creates a FileSpendControlStorage at the default path.

func (*FileSpendControlStorage) Load

func (fs *FileSpendControlStorage) Load() (*persistedState, error)

func (*FileSpendControlStorage) Save

func (fs *FileSpendControlStorage) Save(state persistedState) error

type InMemorySpendControlStorage

type InMemorySpendControlStorage struct {
	// contains filtered or unexported fields
}

InMemorySpendControlStorage keeps state in memory only.

func (*InMemorySpendControlStorage) Load

func (m *InMemorySpendControlStorage) Load() (*persistedState, error)

func (*InMemorySpendControlStorage) Save

func (m *InMemorySpendControlStorage) Save(state persistedState) error

type SpendControl

type SpendControl struct {
	// contains filtered or unexported fields
}

SpendControl tracks spending against configured limits.

func New

func New(storage SpendControlStorage) (*SpendControl, error)

New creates a SpendControl with the given storage backend. It loads persisted state on creation.

func (*SpendControl) Check

func (sc *SpendControl) Check(estimatedCost float64) CheckResult

Check evaluates whether a request costing estimatedCost USD is allowed.

func (*SpendControl) Cleanup

func (sc *SpendControl) Cleanup() error

Cleanup prunes records older than 24 hours.

func (*SpendControl) ClearLimit

func (sc *SpendControl) ClearLimit(window SpendWindow) error

ClearLimit removes the limit for the given window.

func (*SpendControl) GetHistory

func (sc *SpendControl) GetHistory() []SpendRecord

GetHistory returns a copy of all spending records.

func (*SpendControl) GetLimits

func (sc *SpendControl) GetLimits() SpendLimits

GetLimits returns a copy of the current limits.

func (*SpendControl) GetRemaining

func (sc *SpendControl) GetRemaining() map[SpendWindow]float64

GetRemaining returns remaining budget in each active window.

func (*SpendControl) GetSpending

func (sc *SpendControl) GetSpending() map[SpendWindow]float64

GetSpending returns total spent in each active window.

func (*SpendControl) GetStatus

func (sc *SpendControl) GetStatus() map[SpendWindow]StatusEntry

GetStatus returns a combined view of limits, spending, and remaining.

func (*SpendControl) Record

func (sc *SpendControl) Record(amount float64, model, action string) error

Record logs a completed spend and updates the session totals.

func (*SpendControl) SetLimit

func (sc *SpendControl) SetLimit(window SpendWindow, amount float64) error

SetLimit sets the maximum USD for the given window.

type SpendControlStorage

type SpendControlStorage interface {
	Save(state persistedState) error
	Load() (*persistedState, error)
}

SpendControlStorage persists spending state.

type SpendLimits

type SpendLimits map[SpendWindow]float64

SpendLimits maps each window to its maximum USD amount.

type SpendRecord

type SpendRecord struct {
	Timestamp time.Time `json:"timestamp"`
	Amount    float64   `json:"amount"`
	Model     string    `json:"model,omitempty"`
	Action    string    `json:"action,omitempty"`
}

SpendRecord is a single spending event.

type SpendWindow

type SpendWindow string

SpendWindow defines the time window over which a spending limit applies.

const (
	WindowPerRequest SpendWindow = "perRequest"
	WindowHourly     SpendWindow = "hourly"
	WindowDaily      SpendWindow = "daily"
	WindowSession    SpendWindow = "session"
)

type StatusEntry

type StatusEntry struct {
	Limit     float64 `json:"limit"`
	Spent     float64 `json:"spent"`
	Remaining float64 `json:"remaining"`
}

StatusEntry holds limit, spent, and remaining for a single window.