snapshots

Documentation

Overview

Package snapshots collects and stores periodic usage data from AI providers.

Index

• type ClaudeUsage
• type CodexUsage
• type Collector
  • func NewCollector(database *db.DB, claude ClaudeUsage, codex CodexUsage, scraper UsageScraper, ...) *Collector
  • func (c *Collector) GetHourlyAverages(provider string, lookbackDays int) ([]HourlyAverage, error)
  • func (c *Collector) GetLatest(provider string, n int) ([]Snapshot, error)
  • func (c *Collector) GetSinceWeekStart(provider string) ([]Snapshot, error)
  • func (c *Collector) Prune(retentionDays int) (int64, error)
  • func (c *Collector) TakeSnapshot(ctx context.Context, provider string) (Snapshot, error)
• type HourlyAverage
• type Snapshot
• type UsageScraper

Types

type ClaudeUsage

type ClaudeUsage interface {
	GetWeeklyUsage() (int64, error)
	GetTodayUsage() (int64, error)
}

ClaudeUsage defines local usage access for Claude.

type CodexUsage

type CodexUsage interface {
	GetTodayTokens() (int64, error)
	GetWeeklyTokens() (int64, error)
}

CodexUsage defines local usage access for Codex.

type Collector

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

Collector gathers and stores usage snapshots.

func NewCollector

func NewCollector(database *db.DB, claude ClaudeUsage, codex CodexUsage, scraper UsageScraper, weekStartDay time.Weekday) *Collector

NewCollector creates a snapshot collector.

func (*Collector) GetHourlyAverages

func (c *Collector) GetHourlyAverages(provider string, lookbackDays int) ([]HourlyAverage, error)

GetHourlyAverages returns average daily tokens per hour.

func (*Collector) GetLatest

func (c *Collector) GetLatest(provider string, n int) ([]Snapshot, error)

GetLatest returns the latest snapshots for a provider.

func (*Collector) GetSinceWeekStart

func (c *Collector) GetSinceWeekStart(provider string) ([]Snapshot, error)

GetSinceWeekStart returns snapshots from the current week.

func (*Collector) Prune

func (c *Collector) Prune(retentionDays int) (int64, error)

Prune deletes snapshots older than retentionDays.

func (*Collector) TakeSnapshot

func (c *Collector) TakeSnapshot(ctx context.Context, provider string) (Snapshot, error)

TakeSnapshot collects and stores a snapshot for the provider.

type HourlyAverage

type HourlyAverage struct {
	Hour           int
	AvgDailyTokens float64
}

HourlyAverage represents average daily tokens by hour.

type Snapshot

type Snapshot struct {
	ID               int64
	Provider         string
	Timestamp        time.Time
	WeekStart        time.Time
	LocalTokens      int64
	LocalDaily       int64
	ScrapedPct       *float64
	InferredBudget   *int64
	DayOfWeek        int
	HourOfDay        int
	WeekNumber       int
	Year             int
	SessionResetTime string // scraped reset time for current session/5h window
	WeeklyResetTime  string // scraped reset time for weekly window
	ScrapeErr        error  `json:"-"` // not persisted; for CLI diagnostics
}

Snapshot represents a stored usage snapshot.

type UsageScraper

type UsageScraper interface {
	ScrapeClaudeUsage(ctx context.Context) (tmux.UsageResult, error)
	ScrapeCodexUsage(ctx context.Context) (tmux.UsageResult, error)
}

UsageScraper defines tmux usage scraping behavior.