Files
sam 4728c8c253 feat(usage): report model usage per org with identity and cost (#1855)
Model usage was recorded per call and never read, so an org could not see
what it spent. Add the read side:

- model_usage carries identity_id. Task calls take it from the task row,
  chat and curator calls from the calling principal carried in the usage
  record, so an outbox replay keeps its attribution. Existing task rows are
  backfilled from tasks.
- StatsService.UsageTotals sums the caller org's rows by UTC day, source,
  provider, model and identity. The org comes from the principal, with no
  org parameter, so cross-org reads do not exist.
- GET /api/usage prices tokens at the catalog's list rate, netting cache
  hits, and reports calls to unpriced models as tokens only. The published
  catalog view now carries each model's cost.
- A new org Usage page behind a read_usage grant: admin and owner only,
  with a 7, 30 or 90 day range, totals, the daily series, and model, source
  and identity breakdowns. The org shell keeps it on the caller's own org.
2026-11-11 02:15:29 +11:00

89 lines
2.2 KiB
Go

// 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
}