Qloo in Moûsa
Request by request
Moûsa calls the Qloo Insights API at hackathon.api.qloo.com with GET requests and the key in X-Api-Key, never through the model. A session measures its audience once, at most 24 requests, after the agent's guess is sealed, and answers later taste questions from that measurement.
What each request decides
The measurement is the engine's, so every agent and every host sends the same requests for the same audience.
/search
Resolves each name the audience is described by. A match counts only when the meaningful words of both names agree; a work or creator wins over a same-named place.
Decides: Which works the measurement starts from, and which names are reported as unresolved.
/v2/tags
Resolves genre and interest words to tags, typed first for music genres.
Decides: Seeds an audience named by a genre rather than a work.
/v2/audiences
Resolves audience descriptions such as "parents with young children" to Qloo audience segments.
Decides: Weights every Insights request toward that segment.
/v2/insights, entities
One request per taste domain the medium needs: brands, films, artists, books, TV, podcasts, games or places. The resolved seeds go in signal.interests.entities, the seeds themselves are excluded, explainability is asked for, and brands and films are asked again below a popularity cap for lesser-known neighbours. An optional place and age bands weight every request.
Decides: The works the audience loves: the names the agent's guess is compared with, and the anchors of the Design DNA.
/v2/insights, tags
Two audience-level rankings, style and aesthetic properties, sent apart: in one combined request, no aesthetic tag reached the first twelve.
Decides: The pacing, surfaces and tone that direct motion and illustration.
Typed tags of the returned works
No request: the tags each measured work carries are grouped by their Qloo type into look, mood and meaning. A tag two or more works share becomes a quality.
Decides: Palette, type and voice anchor to qualities, so one loud keyword cannot become the design.
/v2/insights with filter.results.entities
Ranks a shortlist the agent gives, on one scale.
Decides: Answers a design question between named options, such as which of three references fits.
Budget and cache
- At most 24 requests a session; a live try's measurement used 12.
- Answers are cached in the project for a week, so a second design for the same audience costs nothing.
- Requests go two at a time, with a short retry on a rate limit, a timeout or a server error, each counted toward the budget.
Qloo's data stays private
- The cache lives only on the machine or server that asked.
- This site and the public repository show the names Qloo measured, never its ids, affinity scores, popularity or descriptions.
- A test fails the repository's build if a Qloo id or a scored entity is committed.
What the live API taught us
Each of these came from a recorded request and changed the engine.
- The search for "Paterson" returned the city before the film, so a work or creator now wins over a same-named place, and places belong in the location signal.
- "Studio Ghibli films" matched the music artist Studio Ghibli, and "ambient music" an artist named Ambient Music. A reference's last word now decides which kind of entity may seed it.
- The canonical game type urn:entity:videogame returned 200; the hackathon guide's video_game spelling returned 400 in this environment.
- A style ranking seeded with an entity and a genre tag together returned HTTP 500; with the entity alone it returned eight tags. Tag rankings now take entity seeds when any resolved.
- Four requests in parallel hit the rate limit on three of seven; two at a time, with a short retry, does not. Timeouts on a busy afternoon answered a minute later.
- A work's first keyword can take over a design: the hockey team LA Kings brought a black-and-silver palette tag to a food shop. Grouping typed tags into shared qualities stopped it.
- Books in the recorded passes carried no typed look, mood or meaning tag, and brands' look tags describe their logos more than the audience's taste.
- Unsupported parameters can be ignored silently with a 200, so Moûsa records what it asked and reads the returned context before saying a filter applied.
The full account, with the requests and their dates: docs/qloo-integration.md.