budget

Documentation

Overview

Package budget implements token budget calculation and allocation for nightshift. Supports daily and weekly modes with reserve and aggressive end-of-week options.

Index

• type AllowanceResult
• type BudgetEstimate
• type BudgetSource
• type ClaudeUsageProvider
• type CodexUsageProvider
• type Manager
  • func NewManager(cfg *config.Config, claude ClaudeUsageProvider, codex CodexUsageProvider, ...) *Manager
  • func NewManagerFromProviders(cfg *config.Config, claude *providers.Claude, codex *providers.Codex, ...) *Manager
  • func (m *Manager) CalculateAllowance(provider string) (*AllowanceResult, error)
  • func (m *Manager) CanRun(provider string, estimatedTokens int64) (bool, error)
  • func (m *Manager) DaysUntilWeeklyReset(provider string) (int, error)
  • func (m *Manager) GetUsedPercent(provider string) (float64, error)
  • func (m *Manager) Summary(provider string) (string, error)
• type Option
  • func WithBudgetSource(source BudgetSource) Option
  • func WithTrendAnalyzer(analyzer TrendAnalyzer) Option
• type Tracker
  • func NewTracker(limitCents int64) *Tracker
  • func (t *Tracker) Record(provider string, tokens int, costCents int64)
  • func (t *Tracker) Remaining() int64
• type TrendAnalyzer
• type UsageProvider
• type UsedPercentSourceProvider

Types

type AllowanceResult

type AllowanceResult struct {
	Allowance          int64   // Final token allowance for this run
	AllowanceNoDaytime int64   // Allowance before predicted daytime usage is reserved
	WeeklyBudget       int64   // Weekly token budget used for calculation
	BudgetBase         int64   // Base budget (daily or remaining weekly)
	UsedPercent        float64 // Current used percentage
	UsedPercentSource  string  // Source of used percentage (e.g., stats-cache, jsonl-fallback)
	ReserveAmount      int64   // Tokens reserved
	PredictedUsage     int64   // Predicted remaining usage today
	Mode               string  // "daily" or "weekly"
	RemainingDays      int     // Days until reset (weekly mode only)
	Multiplier         float64 // End-of-week multiplier (weekly mode only)
	BudgetSource       string  // calibrated, api, config
	BudgetConfidence   string  // none, low, medium, high
	BudgetSampleCount  int     // number of samples used
}

AllowanceResult contains the calculated budget allowance and metadata.

type BudgetEstimate

type BudgetEstimate struct {
	WeeklyTokens int64
	Source       string
	Confidence   string
	SampleCount  int
	Variance     float64
}

BudgetEstimate provides a resolved weekly budget with metadata.

type BudgetSource

type BudgetSource interface {
	GetBudget(provider string) (BudgetEstimate, error)
}

BudgetSource provides calibrated or external budget estimates.

type ClaudeUsageProvider

type ClaudeUsageProvider interface {
	UsageProvider
	GetUsedPercent(mode string, weeklyBudget int64) (float64, error)
}

ClaudeUsageProvider extends UsageProvider for Claude-specific usage methods.

type CodexUsageProvider

type CodexUsageProvider interface {
	UsageProvider
	GetUsedPercent(mode string, weeklyBudget int64) (float64, error)
	GetResetTime(mode string) (time.Time, error)
}

CodexUsageProvider extends UsageProvider for Codex-specific usage methods.

type Manager

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

Manager calculates and manages token budget allocation across providers.

func NewManager

func NewManager(cfg *config.Config, claude ClaudeUsageProvider, codex CodexUsageProvider, opts ...Option) *Manager

NewManager creates a budget manager with the given configuration and providers.

func NewManagerFromProviders

func NewManagerFromProviders(cfg *config.Config, claude *providers.Claude, codex *providers.Codex, opts ...Option) *Manager

NewManagerFromProviders is a convenience constructor that accepts the concrete provider types.

func (*Manager) CalculateAllowance

func (m *Manager) CalculateAllowance(provider string) (*AllowanceResult, error)

CalculateAllowance determines how many tokens nightshift can use for this run.

func (*Manager) CanRun

func (m *Manager) CanRun(provider string, estimatedTokens int64) (bool, error)

CanRun checks if there's enough budget to run a task with the given estimated cost.

func (*Manager) DaysUntilWeeklyReset

func (m *Manager) DaysUntilWeeklyReset(provider string) (int, error)

DaysUntilWeeklyReset calculates days remaining until the weekly budget resets. For Claude: assumes weekly reset on Sunday (7 - current weekday, or 7 if Sunday). For Codex: uses the secondary rate limit's resets_at timestamp.

func (*Manager) GetUsedPercent

func (m *Manager) GetUsedPercent(provider string) (float64, error)

GetUsedPercent retrieves the used percentage from the appropriate provider. Uses the resolved (calibrated) budget so percentages match the displayed budget.

func (*Manager) Summary

func (m *Manager) Summary(provider string) (string, error)

Summary returns a human-readable summary of the budget state for a provider.

type Option

type Option func(*Manager)

Option configures a Manager.

func WithBudgetSource

func WithBudgetSource(source BudgetSource) Option

WithBudgetSource injects a BudgetSource for calibrated budgets.

func WithTrendAnalyzer

func WithTrendAnalyzer(analyzer TrendAnalyzer) Option

WithTrendAnalyzer injects a trend analyzer for predicted daytime usage.

type Tracker

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

Tracker provides backward compatibility for tracking actual spend. Deprecated: Use Manager for budget calculations.

func NewTracker

func NewTracker(limitCents int64) *Tracker

NewTracker creates a budget tracker with the given limit. Deprecated: Use NewManager instead.

func (*Tracker) Record

func (t *Tracker) Record(provider string, tokens int, costCents int64)

Record logs spending for a provider.

func (*Tracker) Remaining

func (t *Tracker) Remaining() int64

Remaining returns cents left in budget.

type TrendAnalyzer

type TrendAnalyzer interface {
	PredictDaytimeUsage(provider string, now time.Time, weeklyBudget int64) (int64, error)
}

TrendAnalyzer predicts near-term usage to protect daytime budget.

type UsageProvider

type UsageProvider interface {
	Name() string
}

UsageProvider is the interface for getting usage data from a provider.

type UsedPercentSourceProvider

type UsedPercentSourceProvider interface {
	LastUsedPercentSource() string
}

UsedPercentSourceProvider reports where the last used-percent value came from. Implemented optionally by providers to improve CLI diagnostics.