Skip to main content

Recommender service (Kaleido.Gre.Recommender, :8084)

The recommender is the decider. Given a customer, it reads their affinities, finds candidate games through tag neighbours and co-play neighbours, adds popularity and newness, and returns a ranked list where every item explains which of the customer's games pulled it in. Player protection is checked before anything else.

It is designed so that a request never touches the database: the catalogue, both neighbour tables, popularity, the settings and the suppression list are all held in memory and refreshed in the background.

API​

MethodPathPurpose
GET/customers/{id}/recommendations?limit&sourceRanked list for a stored customer. source=profile (batch) or redis (live); default Recommender:AffinitySource
POST/customers/{id}/recommendations?sourceSame, with draft settings and limit in the body; never cached
GET/customers/{id}/played?limit&sourceThe customer's seed games, strongest first
GET/customers/{id}/live-activityThe customer's decayed totals per game straight from Redis
POST/recommendAny affinity vector (up to 500), for what-if and the holdout test
GET, PUT, DELETE/suppressed, /suppressed/{id}Player-protection list
GET, PUT/settingsBlend settings
POST/builds?kind=catalogue|crowd|allQueue builds; 409 if one is queued or running
GET/builds, /builds/scheduleRecent builds; scheduler cadence and crowd source
DELETE/dataDrop co-play and popularity (keeps catalogue and tag neighbours)
GET/statsGames, tagged games, link counts, popular games
GET/games/{ref}/neighbours, /games/lookup, /games, /mapDebug and UI views over the catalogue and links

Response shape​

{
"items": [{
"rank": 1,
"game": { "gameRef": "dragonfire", "name": "Dragon Fire", "studio": "...", "releaseDate": "2026-07-01" },
"score": 0.92,
"signals": { "similar": 0.97, "crowd": 1.0, "popular": 0.8, "new": 0.0 },
"parts": { "similar": 0.539, "crowd": 0.333, "popular": 0.044, "new": 0.0 },
"becauseSimilar": [{ "gameRef": "dragongold", "name": "Dragon Gold", "affinity": 0.95, "closeness": 0.8, "weight": 0.76 }],
"becauseCrowd": [{ "gameRef": "dragongold", "affinity": 0.95, "closeness": 0.9, "weight": 0.855 }]
}],
"seeds": 2, "coldStart": false, "catalogueReady": true, "suppressed": null
}

signals are each clue on a 0 to 1 scale; parts are what each one added to score after weighting. At most 3 reasons per kind are returned.

Request sequence​

Errors from the source are mapped: profile service unreachable gives 502, Redis unreachable gives 503.

Result cache key. customerId | source | settings revision | limit | catalogue version | data version. The profile source cannot report a data version, so its results are never cached. The Redis source's version is the v field of the customer's hash, which increments on every applied event, so a new bet invalidates the cached list at once.

Builds​

KindReadsWritesThen
catalogueGET /similarity/export?size=200&k=30 from the Taxonomy API (logs in with a service account; re-logs on 401)recommender.game and neighbour rows with Kind=0Deletes games and Kind 0 links from older builds
crowdGET /affinities from Profile, or Redis SCAN when Crowd:Source=redisneighbour rows with Kind=1, popularityDeletes Kind 1 links and popularity from older builds

Both end with CatalogueCache.Invalidate(), so the next request reloads. Other recommender instances notice within 15 seconds because the cache loop compares a fingerprint of the four most recent finished build ids.

The algorithms are in Crowd signals and Recommendation scoring.

Settings​

SettingDefaultRangeMeaning
SeedGames151 to 100Strongest games of the customer used as starting points
SimilarWeight10 to 10"Tagged like games you play"
CrowdWeight0.60 to 10"Played by customers who play what you play"
PopularWeight0.10 to 10Global popularity
NewReleaseWeight0.10 to 10Released in the last 180 days
ExcludePlayedtrueHide games the customer already plays
MaxPerStudio30 to 50Studio diversity cap; 0 = no limit
DefaultLimit101 to 100List size when none is given
ScaleToBesttrueStretch similar and crowd so each one's best candidate is 1

Configuration​

KeyDefaultPurpose
Recommender:AffinitySourceprofileDefault affinity source
Redis:ConnectionunsetEnables the Redis affinity source and /live-activity
Crowd:Sourceunsetredis builds co-play and popularity from live state
Crowd:SampleCustomers250,000Sample size for the Redis crowd build
Crowd:GamesPerCustomer20Top games per customer fed to the crowd build from Redis
Builds:CrowdEveryMinutes, Builds:CatalogueEveryMinutes0 (off)Scheduled build cadence (compose sets crowd to 0.17, about 10 s)
Builds:CheckSeconds30Scheduler tick (compose sets 5)
Cache:ResultSeconds, Cache:MaxEntries60, 50,000Result cache
Stream:HalfLifeDays, Stream:KeyTtlDays14, 30Must match the ingest service
Stream:CountWeight, AmountWeight, TimeWeight, MinScore1, 1, 1, 0.05Live affinity weights
Taxonomy:Url, Taxonomy:User, Taxonomy:PasswordCatalogue source and service account
Profile:Urlhttp://localhost:8083Batch affinity source