Skip to main content

Recommendation scoring

Scorer.Recommend (src/Kaleido.Gre.Recommender/Scorer.cs) is a pure function: affinities, neighbour tables, popularity, game info and today's date in; a ranked, explained list out. It never touches I/O, which makes it easy to test (ScorerTests) and fast to call.

Pipeline​

The formula​

seedWeight = sum of affinities of the seeds

similar_raw(n) = sum over seeds s that list n as a tag neighbour of affinity(s) x closeness(s, n)
------------------------------------------------------------------------------
seedWeight

crowd_raw(n) = the same over co-play neighbours

similar(n) = similar_raw(n) / max over candidates similar_raw (if ScaleToBest, else as is)
crowd(n) = crowd_raw(n) / max over candidates crowd_raw
popular(n) = popularity(n) (already 0..1)
new(n) = 1 - age_days / 180 if released within 180 days, else 0

total = SimilarWeight + CrowdWeight + PopularWeight + NewReleaseWeight
part_k = weight_k x signal_k / total
score = sum of parts (0 to 1)

Dividing by the total weight keeps the score between 0 and 1 whatever the weights are, and makes parts add up to score, which the UI shows as a stacked bar.

Why affinity-weighted means? A game close to several of the customer's favourites should beat one very close to only one. Weighting each closeness by how much the customer likes the seed makes a strong favourite pull harder than a game they tried once.

Why stretch to the best? The holdout test showed raw scores did not help: tag closeness and co-play cosines live on different scales, and stretching each to its best candidate lets the weights mean what they say. ScaleToBest = false is kept as an option and is scored as a variant in every holdout run.

Worked example​

Sam likes Dragon Gold (0.95) and Pirate Cove (0.44); seed weight 1.39. Default weights 1, 0.6, 0.1, 0.1 (total 1.8).

CandidateSimilarCrowdPopularNewScore
Dragon Fire0.971.000.800(0.97 + 0.60 + 0.08 + 0) / 1.8 = 0.92
Gold Rush1.0000.300(1.00 + 0 + 0.03 + 0) / 1.8 = 0.57
Treasure Tide0.340.260.200.83(0.34 + 0.156 + 0.02 + 0.083) / 1.8 = 0.33

Gold Rush is 50% like Dragon Gold and 70% like Pirate Cove: (0.95 x 0.5 + 0.44 x 0.7) / 1.39 = 0.56 raw, which happens to be the best tag score, so it stretches to 1.00.

Explanations​

Each item carries up to three becauseSimilar and three becauseCrowd reasons: the seed game, its affinity, the closeness, and their product. The web app renders them as:

Dragon Fire: tagged alike to Dragon Gold (80%); played together with Dragon Gold (90%).

Rules applied around the maths​

RuleWhereDefault
Player protection: suppressed customers get an empty listEndpoints.ForCustomer, before scoringalways on, fails closed
Hide games the customer already playsExcludePlayedon
At most N games per studioMaxPerStudio3
Cold start: no seeds means popular and new games onlyCandidates always include top 300 popular and recent releasescoldStart: true in the result
A candidate with no signal at all is droppedscore <= 0
Deterministic tiesOrder by score, then GameRef ordinal

Candidate generation​

Scoring every game in an 8,000-game catalogue for every request would be wasteful. RecommendService.Score first narrows to a candidate set: tag and co-play neighbours of the seeds, the 300 most popular games, games released in the last 180 days, and the customer's own games (needed for ExcludePlayed). Typically a few hundred games are scored.

Tuning and comparing​

  • PUT /settings saves; the settings cache refreshes within 5 seconds and the result cache key includes the revision, so old lists are not served after a save.
  • POST /customers/{id}/recommendations with a draft compares without saving (Tune panel).
  • POST /recommend scores any affinity vector, which is how what-if and the holdout test work.