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).
| Candidate | Similar | Crowd | Popular | New | Score |
|---|---|---|---|---|---|
| Dragon Fire | 0.97 | 1.00 | 0.80 | 0 | (0.97 + 0.60 + 0.08 + 0) / 1.8 = 0.92 |
| Gold Rush | 1.00 | 0 | 0.30 | 0 | (1.00 + 0 + 0.03 + 0) / 1.8 = 0.57 |
| Treasure Tide | 0.34 | 0.26 | 0.20 | 0.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
| Rule | Where | Default |
|---|---|---|
| Player protection: suppressed customers get an empty list | Endpoints.ForCustomer, before scoring | always on, fails closed |
| Hide games the customer already plays | ExcludePlayed | on |
| At most N games per studio | MaxPerStudio | 3 |
| Cold start: no seeds means popular and new games only | Candidates always include top 300 popular and recent releases | coldStart: true in the result |
| A candidate with no signal at all is dropped | score <= 0 | |
| Deterministic ties | Order 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 /settingssaves; 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}/recommendationswith a draft compares without saving (Tune panel).POST /recommendscores any affinity vector, which is how what-if and the holdout test work.