popularity

type Cache ¶

type Cache interface {
	Get(ctx context.Context, key string) ([]byte, bool)
	Set(ctx context.Context, key string, value []byte, ttl time.Duration)
}

Cache memoizes global rankings. Optional: without one every read hits the signal plane. Keys carry the tenant, policy name, content kind, window and bounds, so two policies sharing one cache never read each other's entries.

type Catalog ¶

type Catalog interface {
	Assignments(ctx context.Context, tenant, contentKind, taxonomyKind string, contentIDs []string) (map[string][]contentref.TaxonomyID, error)
}

Catalog is the host join port taxonomy popularity derives from: which taxonomy records (artist, series, tag, creator, character, season, ...) a work is assigned to. ContentKit never records a signal against a taxonomy id; a taxonomy record ranks by its member works. Assignments returns, per work id, the taxonomy ids of taxonomyKind effective on the work (work ∪ its versions); ids without assignments are absent.

type CatalogFunc ¶

type CatalogFunc func(ctx context.Context, tenant, contentKind, taxonomyKind string, contentIDs []string) (map[string][]contentref.TaxonomyID, error)

CatalogFunc adapts a function to Catalog.

func (f CatalogFunc) Assignments(ctx context.Context, tenant, contentKind, taxonomyKind string, contentIDs []string) (map[string][]contentref.TaxonomyID, error)

type Config ¶

type Config struct {
	Source Source
	Policy Policy
	// Catalog enables Taxonomy. Optional.
	Catalog Catalog
	// Cache memoizes Popular and Taxonomy under policy-named keys. Optional.
	Cache    Cache
	CacheTTL time.Duration // default DefaultCacheTTL
	// TaxonomyCandidateLimit is the ranked-work bound of Taxonomy (default
	// DefaultTaxonomyCandidateLimit). Part of the cache key.
	TaxonomyCandidateLimit int
}

Config builds a Ranker. Hosts pass a policy name resolved through ByName or a Policy of their own; either is validated.

type Hit ¶

type Hit struct {
	ContentID string
	Score     float64
	signal.ContentMetrics
}

Hit is one ranked work: the policy score next to its raw window metrics. Public counts come from the metrics, never from the score.

func (h Hit) MeanEngagement() float64

type MemoryCache ¶

type MemoryCache struct {
	// contains filtered or unexported fields
}

MemoryCache is a process-local Cache with per-entry expiry.

func NewMemoryCache() *MemoryCache

func (c *MemoryCache) Get(_ context.Context, key string) ([]byte, bool)

func (c *MemoryCache) Set(_ context.Context, key string, value []byte, ttl time.Duration)

type Policy ¶

type Policy struct {
	Name    string
	Weights Weights
	Priors  Priors
}

Policy is one named, immutable ranking. Changing a weight or prior is a new name, never an edit of an existing one: configuration and cache keys carry the name.

func ByName(name string) (Policy, error)

func (p Policy) MaxQuality() float64

func (p Policy) RankExpr() string

func (p Policy) Score(m signal.ContentMetrics) float64

func (p Policy) Validate() error

type Priors ¶

type Priors struct {
	Engagement       float64
	EngagementWeight float64
	Completion       float64
	CompletionWeight float64
	Approval         float64
	ApprovalWeight   float64
	RevisitWeight    float64
}

Priors smooth each term with pseudo-observations: a prior mean in [0, 1] and its weight (>= 1) in pseudo-viewers or pseudo-votes.

type Ranker ¶

type Ranker struct {
	// contains filtered or unexported fields
}

Ranker applies one policy to one tenant's signal plane.

func New(cfg Config) (*Ranker, error)

func (r *Ranker) Candidates(ctx context.Context, contentKind string, ids []string, window signal.Window) ([]Hit, error)

func (r *Ranker) Policy() Policy

func (r *Ranker) Popular(ctx context.Context, contentKind string, window signal.Window, limit int) ([]Hit, error)

func (r *Ranker) Scores(ctx context.Context, contentKind string, ids []string, window signal.Window) (map[string]float64, error)

func (r *Ranker) Taxonomy(ctx context.Context, contentKind, taxonomyKind string, window signal.Window) ([]TaxonomyHit, error)

type SessionScorer ¶

type SessionScorer struct {
	// SecondsPerUnit is the active time per covered unit at which a session
	// counts as consumed rather than flipped through (8 for gallery pages).
	// Zero means the units are seconds themselves: dwell is 1.
	SecondsPerUnit float64
	// CoveredKey names the Payload entry holding the covered units when the
	// host keeps Progress as its resume anchor; empty reads Progress.
	CoveredKey string
}

SessionScorer is the v1 session engagement score, a signal.Scorer for one content kind: coverage of the selected version times dwell.

coverage = min(1, covered / total)
dwell    = min(1, active_s / (covered × SecondsPerUnit))
score    = round(100 × coverage × (0.6 + 0.4 × dwell))      ∈ [0, 100]

covered is the distinct units exposed (pages, seconds) and total the selected version's units (ProgressMax), so size never enters: a 6-page gallery read fully scores the same as a 200-page one read fully. Completed at CompletionRatio of the units. Non-view signals pass through unchanged.

func (s SessionScorer) Score(_ context.Context, sig signal.Signal) (signal.Scored, error)

type Source ¶

type Source interface {
	Tenant() string
	Popular(ctx context.Context, contentKind string, opts signal.PopularOptions) ([]signal.PopularHit, error)
	Metrics(ctx context.Context, refs []signal.ContentRef, window signal.Window) (map[signal.ContentKey]signal.ContentMetrics, error)
}

Source reads one tenant's canonical window projections; contentkit.Hub satisfies it. Every reference the Ranker builds carries Source.Tenant().

type TaxonomyHit ¶

type TaxonomyHit struct {
	TaxonomyID   contentref.TaxonomyID
	TaxonomyKind string
	Score        float64 // summed member scores
	ContentCount uint64  // ranked members inside the candidate bound
	Viewers      uint64  // summed member viewers (a subject viewing two members counts twice)
	MeanScore    float64 // Score / ContentCount
}

TaxonomyHit is one ranked taxonomy record, derived from its member works.

type Weights ¶

type Weights struct {
	Engagement float64
	Completion float64
	Approval   float64
	Revisit    float64
}

Weights are the quality term weights, each in [0, 1].