Method
Every rule and every call
The agent chooses which tools to call and in what order. It does not choose what goes on the card. Rules in code do, after Qloo answers, even when the same limit was sent as a filter.
- Rules in code
- 12
- Qloo calls
- 8
- Gap between calls
- 250 ms
- Answers cached
- 1 day
The rules
Era and truth
What can appear on a card at all.
- 01
The window
A resident's window is the years they were 10 to 30 years old. The carer can move it between 5 and 35. It is a hard filter: anything outside is rejected in code, with the reason shown.
backend/src/core/window.ts
- 02
Real entities only
Every item must be an entity Qloo returned in this build. A name the model makes up cannot become an item.
backend/src/core/rules.ts
- 03
Tied to a favourite
Every item must be scored by Qloo against a favourite the carer confirmed, or against something the carer saw work.
backend/src/core/rules.ts
- 04
No score, no item
Affinity is read only from query.affinity. If Qloo returns none for an item, the item is skipped. Popularity is never used in its place.
backend/src/qloo/entity.ts, backend/src/core/rules.ts
- 05
Not enough is an answer
When fewer than six items survive, the card says so and offers a five year widening. It never pads.
backend/src/core/card.ts
Ranking
How items are ordered and labelled.
- 06
Compare ranks, not raw scores
A score is only comparable between two calls that share a signal. So his favourites and the 55 and older audience are ranked over the same pinned pool, and the labels come from those ranks: Personal is top third for him and bottom half for the 55 and older audience.
backend/src/qloo/find.ts, backend/src/core/classify.ts
- 07
Signals go where they work
Music and film favourites drive music, film and television. Food favourites drive only food and places. Location is used only on open place queries, never on a pinned pool and never to localise films.
backend/src/core/route.ts, backend/src/qloo/guard.ts
Memory and care
What the carer's taps change.
- 08
Nothing that upset
An item marked upset is removed for that resident for good, and items that share two or more tags with it count for less.
backend/src/core/memory.ts
- 09
Why upset never expires
Every other reaction fades after 90 days unless it is logged again. An upset reaction does not fade, because a painful association should not lapse with the calendar. Only the family or the carer can delete it.
backend/src/core/memory.ts
- 10
Memory is the carer's taps
Six reactions, stored with who, when, card and item. Positives become new signals. Entries expire after 90 days unless logged again. The family can view and delete them.
backend/src/core/memory.ts
Words and privacy
What the model may write and what Qloo may see.
- 11
Openers name nothing else
The model writes one line per item. A line that names a person or title Qloo returned elsewhere, a multi word name not on the card, a listed health claim, or breaks house style is replaced by a template line, and the card says so.
backend/src/core/openers.ts
- 12
Qloo sees only IDs
Requests to Qloo may carry entity IDs, tag IDs, an age bracket, years, and a place as an ID or a point. A typed favourite or place name goes to search only so a match can be confirmed. A resident name, notes and health details cannot leave.
backend/src/qloo/guard.ts
The Qloo calls
In the order a card is built.
| Step | Endpoint | What is sent | What comes back |
|---|---|---|---|
| 01 Resolve favourites | /search | The typed name, optionally an entity type | Entity IDs the carer confirms |
| 02 Tags | /v2/tags | A short phrase, semantic search on | Tag IDs for cuisines and genres |
| 03 Hometown and home city | /search with a locality type | The place name | A locality ID, sent onward as an ID |
| 04 Music, film, television | /v2/insights | filter.type, signal.interests.entities, filter.release_year (film, TV), feature.explainability | Ranked entities with affinity, popularity and tags |
| 05 The 55 and older audience | /v2/insights | The same filters with signal.demographics.age=55_and_older and no favourites | The cohort's ranking of the same kind of item |
| 06 Same pool, both scores | /v2/insights with filter.results.entities | The items missing from one list | A score for every item under both signals |
| 07 Food near him, places from home | /v2/insights | filter.tags (cuisine), signal.location (a locality ID) | Places and destinations tied to home |
| 08 Not repeating | /v2/insights with filter.exclude.entities | IDs the carer marked upset | Results without them |
Calls are spaced at least 250 milliseconds apart, a rate limit response is never retried automatically, repeated requests share one call, and answers are cached on the server for a day. The exact parameters and which ones Qloo ignored are in the platform probe.
Two labelled layers on every item
From Qloo
The item, its year, its tags and its affinity. Shown as returned.
Added by Aftersong
The Personal, Shared era or Widely known tag, and the opener. Personal means the item ranks clearly higher for this person than for Qloo's 55 and older audience. Widely known means it ranks high for popularity in the pool Qloo returned.