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
| Method | Path | Purpose |
|---|---|---|
| GET | /customers/{id}/recommendations?limit&source | Ranked list for a stored customer. source=profile (batch) or redis (live); default Recommender:AffinitySource |
| POST | /customers/{id}/recommendations?source | Same, with draft settings and limit in the body; never cached |
| GET | /customers/{id}/played?limit&source | The customer's seed games, strongest first |
| GET | /customers/{id}/live-activity | The customer's decayed totals per game straight from Redis |
| POST | /recommend | Any affinity vector (up to 500), for what-if and the holdout test |
| GET, PUT, DELETE | /suppressed, /suppressed/{id} | Player-protection list |
| GET, PUT | /settings | Blend settings |
| POST | /builds?kind=catalogue|crowd|all | Queue builds; 409 if one is queued or running |
| GET | /builds, /builds/schedule | Recent builds; scheduler cadence and crowd source |
| DELETE | /data | Drop co-play and popularity (keeps catalogue and tag neighbours) |
| GET | /stats | Games, tagged games, link counts, popular games |
| GET | /games/{ref}/neighbours, /games/lookup, /games, /map | Debug 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
| Kind | Reads | Writes | Then |
|---|---|---|---|
catalogue | GET /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=0 | Deletes games and Kind 0 links from older builds |
crowd | GET /affinities from Profile, or Redis SCAN when Crowd:Source=redis | neighbour rows with Kind=1, popularity | Deletes 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
| Setting | Default | Range | Meaning |
|---|---|---|---|
SeedGames | 15 | 1 to 100 | Strongest games of the customer used as starting points |
SimilarWeight | 1 | 0 to 10 | "Tagged like games you play" |
CrowdWeight | 0.6 | 0 to 10 | "Played by customers who play what you play" |
PopularWeight | 0.1 | 0 to 10 | Global popularity |
NewReleaseWeight | 0.1 | 0 to 10 | Released in the last 180 days |
ExcludePlayed | true | Hide games the customer already plays | |
MaxPerStudio | 3 | 0 to 50 | Studio diversity cap; 0 = no limit |
DefaultLimit | 10 | 1 to 100 | List size when none is given |
ScaleToBest | true | Stretch similar and crowd so each one's best candidate is 1 |
Configuration
| Key | Default | Purpose |
|---|---|---|
Recommender:AffinitySource | profile | Default affinity source |
Redis:Connection | unset | Enables the Redis affinity source and /live-activity |
Crowd:Source | unset | redis builds co-play and popularity from live state |
Crowd:SampleCustomers | 250,000 | Sample size for the Redis crowd build |
Crowd:GamesPerCustomer | 20 | Top games per customer fed to the crowd build from Redis |
Builds:CrowdEveryMinutes, Builds:CatalogueEveryMinutes | 0 (off) | Scheduled build cadence (compose sets crowd to 0.17, about 10 s) |
Builds:CheckSeconds | 30 | Scheduler tick (compose sets 5) |
Cache:ResultSeconds, Cache:MaxEntries | 60, 50,000 | Result cache |
Stream:HalfLifeDays, Stream:KeyTtlDays | 14, 30 | Must match the ingest service |
Stream:CountWeight, AmountWeight, TimeWeight, MinScore | 1, 1, 1, 0.05 | Live affinity weights |
Taxonomy:Url, Taxonomy:User, Taxonomy:Password | Catalogue source and service account | |
Profile:Url | http://localhost:8083 | Batch affinity source |