Souk Compass

Inspiration

Small sellers and creators in Morocco often pick products and content from gut feeling or from generic global trends. Taste is local and cross-domain: someone who likes a certain artist may also like a certain food, brand or place. Qloo's taste graph is built for exactly that kind of cross-domain link. We wanted an agent that uses it as evidence, and that is honest about what the evidence can and cannot say.

What it does

You enter up to three taste anchors (artists, brands, films or books - the anchor types the demo offers), an optional cultural keyword, a location and an optional age signal. The agent then:

1. Resolves each anchor through Qloo search and shows the matched names, so you can see if it picked the wrong entity.
2. Looks up Qloo tags for the keyword and requests cross-domain insights with location context.
3. Checks if the coverage is weak. If so it revises, at most twice: first by dropping the tag signal, then by letting Gemini suggest a broader keyword, which is resolved against Qloo's tag API. Gemini cannot invent tag IDs.
4. Keeps only evidence that has an entity ID and a numeric affinity.
5. Produces two sets of experiments side by side: an LLM-only baseline, and a Qloo-grounded plan. Same brief, model, temperature and output limit. The only difference is the evidence. This is a qualitative comparison, not an uplift claim.
6. Drops any generated idea that does not cite a valid returned entity ID, and shows a decision trace that labels what came from the API, what came from a rule, and what came from the LLM.

What makes it Qloo-powered

Every grounded suggestion must point at an entity ID that Qloo actually returned. Search, tags and insights are all called live (/search, /v2/tags, /v2/insights on the hackathon API). The agent changes its own next call based on how much evidence came back, which is the agentic loop.

How we built it

• Cloudflare Workers (free plan) serving a small static UI and a single /api/run endpoint.
• A SQLite-backed Durable Object that enforces the per-IP daily limit, the project-wide daily admission limit and the Gemini token/call budgets atomically (covered by the offline tests).
• Qloo API for search, tags and insights (max 8 calls per run), reached through a tiny authenticated relay so the Qloo key never sits in the Worker.
• Gemini free tier for planning and for the experiment text (max 3 calls per run, each reserved against budget before dispatch).
• 22 offline tests covering bounded revisions, citation rejection, schema rejection, budget windows, concurrency, restart persistence and the relay client. An independent audit reviewed the code.
• Zero spend by design: no paid plan, no billing upgrade, no fallback to a paid model.

Challenges

• Keeping an agent loop bounded: hard caps on calls, revisions and tokens.
• Gemini's daily quota resets at Pacific midnight, so the budget uses a rolling window that survives the DST fall-back day.
• Making citations checkable: ideas without a returned ID are removed instead of being trusted.
• A debugging lesson: the deployed Worker's Qloo calls failed instantly with a bare TypeError and no HTTP status, while the same key worked everywhere else. Days of diagnostics pointed at network egress. The real cause was in our own code: we stored the global fetch on the client object and called it as a method, which the Workers runtime rejects ("Illegal invocation"). One-line fix, verified live the same day. We also route through a small authenticated relay now, so the Qloo key lives only on the relay host.

Accomplishments we are proud of

• Every grounded idea cites an entity ID that Qloo actually returned; uncited ideas are dropped. The citation proves the ID came back - it does not prove the model interpreted it correctly.
• A trace that separates API facts, rules and LLM choices.
• Hard free-tier budgets with tests, so a public demo cannot create a bill.

What we learned

• Qloo affinity is a cultural association, not demand, market size or predicted sales.
• Citation validation only proves that an ID was returned. It does not prove that the LLM interpreted it correctly.
• Generated experiments need a human to review and test them.

Limits (stated plainly)

• Public or fictional briefs only. Taste queries go to Qloo, and Gemini free-tier prompts may be used by Google to improve its products.
• Per-IP limits and the Origin check are abuse friction, not bot-proof. If the free budget is used up, the demo shows a capacity message.
• No Qloo response data is stored in the repo.

Built With

• cloudflare-workers
• durable-objects
• gemini-api
• javascript
• qloo-api
• sqlite