// Package usage records model calls for attribution and chargeback. package usage import ( "context" "strings" "time" ) // Source is what made a model call. type Source string const ( SourceTask Source = "task" SourceChat Source = "chat" SourceCurator Source = "curator" ) // Record is one model call. A task's record belongs to the task's org, // whatever Org says. type Record struct { Org string Source Source TaskID int64 Attempt int Workflow string Step string Alias string Provider string Model string // Identity is who the work was requested as: the identity that created // the task, or the calling principal for chat and curator calls. Empty // when the caller knew none. Identity string InputTokens int64 OutputTokens int64 CachedTokens int64 At time.Time } // Recorder appends usage records. type Recorder interface { RecordUsage(ctx context.Context, r Record) error } // MaxReportDays bounds a usage report's range. const MaxReportDays = 365 // NormalizeDays clamps a requested report range to a usable number of days. func NormalizeDays(days int) int { if days < 1 { return 1 } if days > MaxReportDays { return MaxReportDays } return days } // ReportWindow is the UTC window a report of days days covers, ending at now: // whole days, today included. Rows are bucketed by UTC day, so the window // starts at a UTC midnight. func ReportWindow(days int, now time.Time) (from, to time.Time) { now = now.UTC() start := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, time.UTC) return start.AddDate(0, 0, -(NormalizeDays(days) - 1)), now } // TotalRow is one cell of a usage report: the day, source and model an org's // calls used and the tokens they spent. Cost is not carried; the reader // prices the tokens against the model catalog. type TotalRow struct { Day string Source Source Provider string Model string Identity string Calls int64 InputTokens int64 OutputTokens int64 CachedTokens int64 } // WithRef fills Provider and Model from a "provider/model" ref. func (r Record) WithRef(ref string) Record { r.Provider, r.Model, _ = strings.Cut(ref, "/") return r }