analytics

package
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterRoutes

func RegisterRoutes(api huma.API, store *Store)

RegisterRoutes wires up all analytics-related HTTP endpoints onto the provided Huma API.

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

type AgentDailyCount struct {
	Date   string         `json:"date"`
	Agents map[string]int `json:"-"`
}

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 DailyCount

type DailyCount struct {
	Date  string `json:"date"`
	Count int    `json:"count"`
}

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"`
}

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 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 NewStore

func NewStore(pool *pgxpool.Pool) *Store

NewStore constructs a Store backed by the given connection pool.

func (*Store) CleanupOldEvents added in v0.7.0

func (s *Store) CleanupOldEvents(ctx context.Context, retentionDays int) (int64, error)

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

func (s *Store) DismissSkill(ctx context.Context, name string) error

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

func (s *Store) GetAllTags(ctx context.Context) ([]string, error)

GetAllTags returns the distinct, sorted set of tags across all skills.

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

func (s *Store) GetUnregisteredSkills(ctx context.Context, days int) ([]UnregisteredSkill, error)

GetUnregisteredSkills returns skill names from events that don't exist in the skills table or dismissed_skills table, with activation stats.

func (*Store) Insert

func (s *Store) Insert(ctx context.Context, e Event) error

Insert writes a single activation event into skill_events.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL