Files
archie/internal/webui/usage.go
T
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

247 lines
8.3 KiB
Go

package webui
import (
"context"
"math"
"net/http"
"sort"
"strconv"
"github.com/samcharles93/archie-core/internal/domain/usage"
)
// usageBucketView is a token and cost total for one slice of a usage report.
// CostUSD is nil when nothing in the slice could be priced: the report shows
// tokens rather than a guessed cost.
type usageBucketView struct {
Calls int64 `json:"calls"`
InputTokens int64 `json:"input_tokens"`
OutputTokens int64 `json:"output_tokens"`
CachedTokens int64 `json:"cached_tokens"`
CostUSD *float64 `json:"cost_usd"`
UnpricedCalls int64 `json:"unpriced_calls"`
}
// usageDayView is one UTC day's totals.
type usageDayView struct {
Day string `json:"day"`
usageBucketView
}
// usageModelView is one provider/model's totals.
type usageModelView struct {
Provider string `json:"provider"`
Model string `json:"model"`
usageBucketView
}
// usageSourceView is one call source's totals.
type usageSourceView struct {
Source string `json:"source"`
usageBucketView
}
// usageIdentityView is one identity's totals. IdentityName is "Unknown" when
// the record carried no identity.
type usageIdentityView struct {
IdentityID string `json:"identity_id"`
IdentityName string `json:"identity_name"`
usageBucketView
}
// usageReportView is GET /api/usage's payload: the range, its totals, and the
// same totals sliced every way the page shows them.
type usageReportView struct {
Days int `json:"days"`
Totals usageBucketView `json:"totals"`
ByDay []usageDayView `json:"by_day"`
ByModel []usageModelView `json:"by_model"`
BySource []usageSourceView `json:"by_source"`
ByIdentity []usageIdentityView `json:"by_identity"`
}
// handleUsage reports the caller org's model usage. The org is never a
// parameter: the State Store scopes the read to the calling principal's org,
// so cross-org reporting does not exist rather than being refused.
func (s *Server) handleUsage(w http.ResponseWriter, r *http.Request) {
if s.Usage == nil {
http.Error(w, "usage unavailable", http.StatusServiceUnavailable)
return
}
days := 30
if raw := r.URL.Query().Get("days"); raw != "" {
if n, err := strconv.Atoi(raw); err == nil {
days = n
}
}
days = usage.NormalizeDays(days)
rows, err := s.Usage.UsageTotals(r.Context(), days)
if err != nil {
s.logf("usage totals unavailable", "err", err)
http.Error(w, "usage unavailable", http.StatusServiceUnavailable)
return
}
writeJSON(w, usageReport(days, rows, s.modelPrices(r.Context()), s.identityNames(r.Context())))
}
// modelPrices prices each model from the catalog view the configuration owner
// publishes. A model it does not price is absent, so its calls are counted as
// unpriced instead of costed at zero.
func (s *Server) modelPrices(ctx context.Context) map[string]ModelCostView {
prices := map[string]ModelCostView{}
view, found, err := s.configSource()(ctx)
if err != nil || !found {
return prices
}
for _, provider := range view.Catalog {
for model, cost := range provider.Costs {
prices[usagePriceKey(provider.ID, model)] = cost
}
}
return prices
}
// identityNames resolves the caller's identities for display. A read that
// fails leaves the report with ids: naming is presentation, not the data.
func (s *Server) identityNames(ctx context.Context) map[string]string {
names := map[string]string{}
if s.Identities == nil {
return names
}
identities, err := s.Identities.List(ctx)
if err != nil {
s.logf("usage identity names unavailable", "err", err)
return names
}
for _, identity := range identities {
names[string(identity.ID)] = identity.DisplayName
}
return names
}
// usagePriceKey identifies one priced model. Provider and model are joined by
// a byte no model id contains, so ("a/b", "c") and ("a", "b/c") stay distinct.
func usagePriceKey(provider, model string) string {
return provider + "\x00" + model
}
// add accumulates one usage row, pricing it when the catalog published a
// price for its model.
func (b *usageBucketView) add(row usage.TotalRow, prices map[string]ModelCostView) {
b.Calls += row.Calls
b.InputTokens += row.InputTokens
b.OutputTokens += row.OutputTokens
b.CachedTokens += row.CachedTokens
cost, priced := prices[usagePriceKey(row.Provider, row.Model)]
if !priced {
b.UnpricedCalls += row.Calls
return
}
total := 0.0
if b.CostUSD != nil {
total = *b.CostUSD
}
costUSD := roundUSD(total + modelCallCost(row, cost))
b.CostUSD = &costUSD
}
// modelCallCost prices one row's tokens at the model's list price, netting
// cache hits: cached tokens are part of the input count and are charged the
// cache-read rate. A catalog that publishes no cache-read price is charged at
// the input rate, because reporting less than the provider bills is worse
// than reporting more.
func modelCallCost(row usage.TotalRow, cost ModelCostView) float64 {
cachedRate := cost.CacheRead
if cachedRate == 0 {
cachedRate = cost.Input
}
uncached := max(row.InputTokens-row.CachedTokens, 0)
return (float64(uncached)*cost.Input +
float64(row.CachedTokens)*cachedRate +
float64(row.OutputTokens)*cost.Output) / 1e6
}
// roundUSD keeps a cent-level figure readable instead of exposing float noise
// to the page.
func roundUSD(amount float64) float64 {
return math.Round(amount*1e6) / 1e6
}
// usageReport slices rows by day, model, source and identity. Every slice is
// also summed into the report's totals.
func usageReport(days int, rows []usage.TotalRow, prices map[string]ModelCostView, names map[string]string) usageReportView {
report := usageReportView{
Days: days,
ByDay: []usageDayView{},
ByModel: []usageModelView{},
BySource: []usageSourceView{},
ByIdentity: []usageIdentityView{},
}
byDay := map[string]*usageBucketView{}
byModel := map[[2]string]*usageBucketView{}
bySource := map[string]*usageBucketView{}
byIdentity := map[string]*usageBucketView{}
for _, row := range rows {
report.Totals.add(row, prices)
usageBucketFor(byDay, row.Day).add(row, prices)
usageBucketFor(byModel, [2]string{row.Provider, row.Model}).add(row, prices)
usageBucketFor(bySource, string(row.Source)).add(row, prices)
usageBucketFor(byIdentity, row.Identity).add(row, prices)
}
for day, bucket := range byDay {
report.ByDay = append(report.ByDay, usageDayView{Day: day, usageBucketView: *bucket})
}
for key, bucket := range byModel {
report.ByModel = append(report.ByModel, usageModelView{Provider: key[0], Model: key[1], usageBucketView: *bucket})
}
for source, bucket := range bySource {
report.BySource = append(report.BySource, usageSourceView{Source: source, usageBucketView: *bucket})
}
for id, bucket := range byIdentity {
name := names[id]
switch {
case id == "":
name = "Unknown"
case name == "":
name = id
}
report.ByIdentity = append(report.ByIdentity, usageIdentityView{IdentityID: id, IdentityName: name, usageBucketView: *bucket})
}
sort.Slice(report.ByDay, func(i, j int) bool { return report.ByDay[i].Day < report.ByDay[j].Day })
sort.Slice(report.ByModel, func(i, j int) bool {
return usageViewLess(report.ByModel[i].tokens(), report.ByModel[j].tokens(), report.ByModel[i].Provider+"/"+report.ByModel[i].Model, report.ByModel[j].Provider+"/"+report.ByModel[j].Model)
})
sort.Slice(report.BySource, func(i, j int) bool {
return usageViewLess(report.BySource[i].tokens(), report.BySource[j].tokens(), report.BySource[i].Source, report.BySource[j].Source)
})
sort.Slice(report.ByIdentity, func(i, j int) bool {
return usageViewLess(report.ByIdentity[i].tokens(), report.ByIdentity[j].tokens(), report.ByIdentity[i].IdentityID, report.ByIdentity[j].IdentityID)
})
return report
}
// usageViewLess orders the largest spenders first, then by a stable key so a
// report is stable between reads of the same data.
func usageViewLess(tokensI, tokensJ int64, keyI, keyJ string) bool {
if tokensI != tokensJ {
return tokensI > tokensJ
}
return keyI < keyJ
}
// tokens is the figure the page and the ordering use: a cached token is part
// of the input count, so adding it again would double-count.
func (b *usageBucketView) tokens() int64 {
return b.InputTokens + b.OutputTokens
}
// usageBucketFor returns the bucket for key, creating it on first use.
func usageBucketFor[K comparable](buckets map[K]*usageBucketView, key K) *usageBucketView {
bucket, ok := buckets[key]
if !ok {
bucket = &usageBucketView{}
buckets[key] = bucket
}
return bucket
}