Documentation
¶
Overview ¶
Package leaderboard is the ranking of who uses AI most, in your org and globally.
It ranks who leads inside an org, which orgs lead globally, and draws a GitHub-style per-day contribution graph for one subject — all opt-in for public listing.
It is a DERIVED, read-only lens over the ONE usage ledger (hanzo.cloud_usage) through the datastore OLAP rollup — it adds no metering path and double-counts nothing.
Surface (all /v1, NO /api/ prefix; org-scoped, fail-closed):
GET /v1/usage/leaderboard ranked top users (personal|org) or orgs (global) GET /v1/usage/activity per-day series for a heatmap + timeline (authorized subject) GET /v1/usage/leaderboard/optin the caller's opt-in + their org's opt-in PUT /v1/usage/leaderboard/optin set the caller's OWN public-listing opt-in PUT /v1/usage/leaderboard/optin/org set the ORG's public-board opt-in (org admin) POST /v1/usage/rollup/backfill seed the rollup from ledger history (SuperAdmin, once)
It co-owns the /v1/usage/* prefix with apps/usage (the cost footprint at /v1/usage/summary) — a DISTINCT concern (who leads + your activity graph) at its own paths, registered as a separate subsystem so it stays isolated. Its auto health route is /v1/leaderboard/health (the spec name). apps/usage's own doc claims it "owns ALL usage"; two packages under one prefix is one prefix with no owner, and the name here (leaderboard) does not match the prefix it serves.
TENANT ISOLATION (the bar). The org is the VALIDATED IAM owner claim (principal.Org — the trusted X-Org-Id the identity middleware minted from the verified bearer, HIP-0026; NEVER a client header) AND a validated principal is required. Every datastore read binds the org POSITIONALLY (never interpolated). A user board only ever contains the caller's own org's rows; an org board carries org-level aggregates only; cross-org detail is structurally impossible. Fail closed: no principal → 401; datastore not connected → honest-empty (available:false), never fabricated ranks.
PRIVACY (opt-in). Public listing is OPT-IN and PRIVATE by default: a user sees their OWN rank always, but is shown to others only after opting in with a chosen handle; an org appears on the cross-org global board only after an org admin opts it in. See view.go for the naming/anonymization policy.
Index ¶
- func BackfillUsageRollup(ctx context.Context, before time.Time) error
- func EnsureUsageRollup(ctx context.Context) error
- func Mount(app cloud.Router, deps cloud.Deps) error
- func Shutdown(_ context.Context) error
- type ActivityPoint
- type ActivityTotals
- type ActivityView
- type LeaderboardRow
- type LeaderboardView
- type SelfRank
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BackfillUsageRollup ¶
BackfillUsageRollup seeds the rollup from ledger history before the cutoff. It is the DEPLOY-GATED, run-ONCE step: because SummingMergeTree accumulates, re-seeding a day it already holds would double that day, so the handler guards on the seed's own range (rollupRowsSeeded) or an explicit force. `before` is snapped to UTC midnight so the seed's day-range and the guard's are identical.
func EnsureUsageRollup ¶
EnsureUsageRollup creates the derived rollup table + the incremental MV if they do not exist (the base ledger first, since the MV reads it). Idempotent and latched: a transient datastore blip does not permanently poison later attempts. Every leaderboard/activity read calls it first — the same discipline as EnsureCloudUsageTable — so the feature self-provisions its rollup the first time it runs against a connected datastore.
Types ¶
type ActivityPoint ¶
type ActivityPoint struct {
Day string `json:"day"` // "2006-01-02"
Requests int64 `json:"requests"`
Tokens int64 `json:"tokens"`
CostCents int64 `json:"costCents"`
}
ActivityPoint is one day of a subject's usage — the atom of the contribution heatmap + timeline. CostCents populated only when the viewer may see spend.
type ActivityTotals ¶
type ActivityTotals struct {
Requests int64 `json:"requests"`
Tokens int64 `json:"tokens"`
CostCents int64 `json:"costCents"`
ActiveDays int `json:"activeDays"` // days with any usage
MaxTokens int64 `json:"maxTokens"` // busiest day's tokens (heatmap intensity ceiling)
MaxRequests int64 `json:"maxRequests"`
}
ActivityTotals are the window sums + heatmap-scaling hints.
type ActivityView ¶
type ActivityView struct {
Subject string `json:"subject"` // user|org|project
ID string `json:"id"` // resolved subject id (echoed)
From string `json:"from"`
To string `json:"to"`
Days []ActivityPoint `json:"days"`
Totals ActivityTotals `json:"totals"`
Available bool `json:"available"`
Source string `json:"source"`
Note string `json:"note,omitempty"` // honest note (e.g. project attribution not in the ledger)
}
ActivityView is the per-day series for one authorized subject.
type LeaderboardRow ¶
type LeaderboardRow struct {
Rank int `json:"rank"`
Handle string `json:"handle"`
Anonymous bool `json:"anonymous"`
Self bool `json:"self"`
Requests int64 `json:"requests"`
Tokens int64 `json:"tokens"`
CostCents int64 `json:"costCents"`
Metric int64 `json:"metric"`
}
LeaderboardRow is one ranked subject (a user or an org). Handle is the display identity per the privacy model; Anonymous marks a withheld identity; Self marks the caller's own row. Requests/Tokens are non-sensitive volume aggregates; CostCents is populated ONLY when the viewer is authorized to see this subject's spend (self, admin, or an explicit cost board — see costVisible). Metric is the value the board is ranked by (for bar sizing on the client).
type LeaderboardView ¶
type LeaderboardView struct {
Scope string `json:"scope"` // personal|org|global
Subject string `json:"subject"` // user|org
Metric string `json:"metric"` // tokens|requests|cost
Period string `json:"period"` // day|week|month|all|custom
Start string `json:"start"` // "" for all
End string `json:"end"`
Rows []LeaderboardRow `json:"rows"`
Self *SelfRank `json:"self,omitempty"`
Total int64 `json:"total"` // ranked subjects in the window
Available bool `json:"available"`
Source string `json:"source"`
}
LeaderboardView is the whole leaderboard response.
type SelfRank ¶
type SelfRank struct {
Ranked bool `json:"ranked"`
Rank int `json:"rank"`
OfTotal int64 `json:"ofTotal"`
Requests int64 `json:"requests"`
Tokens int64 `json:"tokens"`
CostCents int64 `json:"costCents"`
Metric int64 `json:"metric"`
Handle string `json:"handle"`
Listed bool `json:"listed"` // is the caller publicly listed (opted in)
}
SelfRank is the caller's own standing on a user board, INCLUDED even when the caller falls outside the top-N page. Ranked=false means the caller has no usage in the window (unranked) — the client shows "—", never a fabricated rank.
Source Files