Documentation
¶
Index ¶
- Constants
- func RegisterRoutes(api huma.API, store *Store, opts Options)
- type ActivationSummary
- type AgentDailyCount
- type AnalyticsConsumersBody
- type Breakdown
- type BreakdownRow
- type DailyCount
- type Event
- type EventFilter
- type Options
- type OverviewData
- type QualitySummary
- type SecuritySummary
- type SkillAnalytics
- type SkillsQuery
- type Store
- func (s *Store) CleanupOldEvents(ctx context.Context, retentionDays int) (int64, error)
- func (s *Store) DismissSkill(ctx context.Context, name string) error
- func (s *Store) GetActivations(ctx context.Context, skillName string, days int, filter EventFilter) (*ActivationSummary, error)
- func (s *Store) GetAllTags(ctx context.Context) ([]string, error)
- func (s *Store) GetBreakdown(ctx context.Context, days int, skill, userID string, admin bool, ...) (*Breakdown, error)
- func (s *Store) GetConsumers(ctx context.Context) (*AnalyticsConsumersBody, error)
- func (s *Store) GetOverview(ctx context.Context, days int, filter EventFilter) (*OverviewData, error)
- func (s *Store) GetSkillTimeSeries(ctx context.Context, skillName string, days int, filter EventFilter) ([]AgentDailyCount, error)
- func (s *Store) GetSkillsAnalytics(ctx context.Context, days int, opts SkillsQuery) ([]SkillAnalytics, int, error)
- func (s *Store) GetTimeSeries(ctx context.Context, days int, filter EventFilter) ([]DailyCount, error)
- func (s *Store) GetUnregisteredSkills(ctx context.Context, days int) ([]UnregisteredSkill, error)
- func (s *Store) Insert(ctx context.Context, e Event) error
- type UnregisteredSkill
Constants ¶
const ( VisibilityAggregate = "aggregate" VisibilityPerson = "person" )
Member visibility of per-person activation data.
const MinGroup = 5
MinGroup is the smallest group a member sees in an aggregate. A smaller one could point at one person.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ActivationSummary ¶
type ActivationSummary struct {
TotalCount int `json:"total_count"`
UniqueDevs int `json:"unique_devs"`
LastTriggered *time.Time `json:"last_triggered"`
ByAgent map[string]int `json:"by_agent"`
BySource map[string]int `json:"by_source"`
// HookActivations and AutomatedActivations split TotalCount by who observed
// the activation: a hook on a developer machine or a consumer's report.
HookActivations int `json:"hook_activations"`
AutomatedActivations int `json:"automated_activations"`
ByConsumer map[string]int `json:"by_consumer"`
}
ActivationSummary summarises activations for a specific skill over a time window.
type AgentDailyCount ¶
AgentDailyCount holds per-agent activation counts for a single day.
func (AgentDailyCount) MarshalJSON ¶
func (a AgentDailyCount) MarshalJSON() ([]byte, error)
MarshalJSON produces a flat object: {"date":"2026-05-20","claude-code":5,"cursor":2}
type AnalyticsConsumersBody ¶ added in v0.16.0
type AnalyticsConsumersBody struct {
Consumers []string `json:"consumers"`
Roles []string `json:"roles"`
}
AnalyticsConsumersBody lists the values the consumer and role filters accept.
type Breakdown ¶ added in v0.19.0
type Breakdown struct {
Days int `json:"days"`
Visibility string `json:"visibility"`
IdentityRecorded bool `json:"identity_recorded"`
ByModel []BreakdownRow `json:"by_model"`
ByHarness []BreakdownRow `json:"by_harness"`
// ByPerson is set for an admin, and for a member when visibility is person.
ByPerson []BreakdownRow `json:"by_person"`
// Mine is the caller's own activations.
Mine int `json:"mine"`
// Hidden counts the groups below MinGroup left out for a member.
Hidden int `json:"hidden"`
}
Breakdown is who used skills, on which model and harness, over a window.
type BreakdownRow ¶ added in v0.19.0
type BreakdownRow struct {
Key string `json:"key"`
Label string `json:"label"`
Activations int `json:"activations"`
People int `json:"people"`
}
BreakdownRow is one model, harness or person.
type DailyCount ¶
DailyCount holds the activation count for a single day.
type Event ¶
type Event struct {
SkillName string `json:"skill_name"`
Agent string `json:"agent"`
TriggerType string `json:"trigger_type"`
ProjectHash string `json:"project_hash"`
DeveloperHash string `json:"developer_hash"`
// EventSource records how the activation was observed. "tool_invocation" is
// an agent reporting an explicit skill call; "transcript_scan" is a hook
// deriving activations by reading a session transcript afterwards. The two
// are not the same measurement and must never be summed unlabelled.
EventSource string `json:"event_source"`
// UserID is the person whose key sent the event, empty when the org
// records no identity. Model, Version and HarnessVersion are empty or 0
// when the hook could not tell.
UserID string `json:"-"`
Model string `json:"model,omitempty"`
Version int `json:"version,omitempty"`
HarnessVersion string `json:"harness_version,omitempty"`
}
Event represents a single skill activation telemetry record.
type EventFilter ¶ added in v0.16.0
type EventFilter struct {
Consumer string `query:"consumer" doc:"Count only activations this consumer reported"`
Role string `query:"role" doc:"Count only activations reported for this role"`
}
EventFilter narrows activation counts to one consumer and one role. An empty field applies no filter. Hook events have neither, so any filter excludes them.
type Options ¶ added in v0.19.0
type Options struct {
// RecordIdentity false stores no user on an event. Nil records it.
RecordIdentity func() bool
// MemberVisibility is "aggregate" or "person". Nil is aggregate.
MemberVisibility func() string
}
Options are the org's activation settings, read on each request.
type OverviewData ¶
type OverviewData struct {
TotalSkills int `json:"total_skills"`
ActiveSkills int `json:"active_skills"`
TotalActivations int `json:"total_activations"`
UnreviewedSkills int `json:"unreviewed_skills"`
Security SecuritySummary `json:"security"`
// UnregisteredActivations counts events whose skill name was not in the
// registry when they arrived. They are deliberately excluded from
// TotalActivations — unvalidated names are not proof of use.
UnregisteredActivations int `json:"unregistered_activations"`
}
OverviewData holds top-level KPI metrics for the analytics overview strip.
type QualitySummary ¶ added in v0.10.0
type QualitySummary struct {
Version int `json:"version"`
Headline float64 `json:"headline_score"`
Verified bool `json:"verified"`
PanelComplete bool `json:"panel_complete"`
ScoredAt time.Time `json:"scored_at"`
Lift *float64 `json:"lift,omitempty"`
}
QualitySummary is the compact quality state a list row needs to render a badge: enough to draw the meter and to say whether it may be trusted, and nothing more. The full report is a separate endpoint.
type SecuritySummary ¶
type SecuritySummary struct {
Clean int `json:"clean"`
Warning int `json:"warning"`
Critical int `json:"critical"`
}
SecuritySummary aggregates skill security statuses. The scanner produces "warn" and "high" status strings; both are counted under the Warning field. "critical" maps to Critical. Everything else (including "clean", "info", and skills with no scan results) maps to Clean.
type SkillAnalytics ¶
type SkillAnalytics struct {
Name string `json:"name"`
Description string `json:"description"`
Tags []string `json:"tags"`
Author string `json:"author"`
SpecCompliance string `json:"spec_compliance"`
Activations int `json:"activations"`
UniqueDevs int `json:"unique_devs"`
LastTriggered *time.Time `json:"last_triggered"`
SecurityStatus string `json:"security_status"`
ReviewedAt *time.Time `json:"reviewed_at"`
LatestVersion int `json:"latest_version"`
UpdatedAt time.Time `json:"updated_at"`
// Quality is nil when the skill has never been scored. Nil, not a zero
// value: an unscored skill and a skill that scored zero are different
// facts, and every surface renders them differently.
Quality *QualitySummary `json:"quality,omitempty"`
}
SkillAnalytics holds per-skill analytics data for the table view.
type SkillsQuery ¶ added in v0.4.0
type SkillsQuery struct {
Limit int
Offset int
Sort string // "activations" (default) | "name" | "updated" | "quality" | "lift"
Query string // case-insensitive substring on name/description
Tag string // frontmatter tag membership
// Order is "asc" or "desc"; anything else uses the sort clause's own
// default direction.
Order string
// Scored filters to skills that have ("yes") or have not ("no") been
// scored. Empty means no filter.
Scored string
// Filter counts only matching activations. An active filter also drops the
// skills with no matching activation, so the table shows what was used.
Filter EventFilter
}
GetSkillsAnalytics returns per-skill analytics for all skills over the last `days` days, ordered by activation count descending. SkillsQuery holds optional list filters/pagination for GetSkillsAnalytics.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store handles Postgres persistence for skill_events.
func (*Store) CleanupOldEvents ¶ added in v0.7.0
CleanupOldEvents deletes events older than retentionDays and returns the number of rows removed. Pass 0 to disable (caller should check before calling).
func (*Store) DismissSkill ¶
DismissSkill inserts a name into dismissed_skills. Idempotent.
func (*Store) GetActivations ¶
func (s *Store) GetActivations(ctx context.Context, skillName string, days int, filter EventFilter) (*ActivationSummary, error)
GetActivations returns an ActivationSummary for the given skill over the last `days` days. Returns a zero-value summary (no error) when no events exist.
func (*Store) GetAllTags ¶ added in v0.4.0
GetAllTags returns the distinct, sorted set of tags across all skills.
func (*Store) GetBreakdown ¶ added in v0.19.0
func (s *Store) GetBreakdown(ctx context.Context, days int, skill, userID string, admin bool, visibility string) (*Breakdown, error)
GetBreakdown returns the breakdown the caller may see.
func (*Store) GetConsumers ¶ added in v0.16.0
func (s *Store) GetConsumers(ctx context.Context) (*AnalyticsConsumersBody, error)
GetConsumers returns the distinct consumers and roles in stored events.
func (*Store) GetOverview ¶
func (s *Store) GetOverview(ctx context.Context, days int, filter EventFilter) (*OverviewData, error)
GetOverview returns aggregate KPI data covering the last `days` days.
func (*Store) GetSkillTimeSeries ¶
func (s *Store) GetSkillTimeSeries(ctx context.Context, skillName string, days int, filter EventFilter) ([]AgentDailyCount, error)
GetSkillTimeSeries returns daily per-agent activation counts for a specific skill over the last `days` days. Days with zero activations are included.
func (*Store) GetSkillsAnalytics ¶
func (s *Store) GetSkillsAnalytics(ctx context.Context, days int, opts SkillsQuery) ([]SkillAnalytics, int, error)
func (*Store) GetTimeSeries ¶
func (s *Store) GetTimeSeries(ctx context.Context, days int, filter EventFilter) ([]DailyCount, error)
GetTimeSeries returns daily activation counts for the last `days` days. Days with zero activations are included (filled with 0).
func (*Store) GetUnregisteredSkills ¶
GetUnregisteredSkills returns skill names from events that don't exist in the skills table or dismissed_skills table, with activation stats.
type UnregisteredSkill ¶
type UnregisteredSkill struct {
Name string `json:"name"`
Activations int `json:"activations"`
UniqueDevs int `json:"unique_devs"`
LastTriggered *time.Time `json:"last_triggered"`
FirstSeen *time.Time `json:"first_seen"`
}
UnregisteredSkill represents a skill name found in events but not in the registry.