Local Taste Scout

An agent that tells a local business who to partner with, what its next event should be about, and where to put flyers, from Qloo's taste graph.

Comment

Try it live: https://web-production-95a5c.up.railway.app (type your own business, or open one of three recorded cases). Code: https://github.com/DesignMaster-Solutions/local-taste-scout

Inspiration

We build websites and apps for small local businesses. The request we hear most, and answer worst, is "find me a partner nearby who shares my customers". Owners answer it by gut feeling: they have no data team, and census data says who lives nearby, not what those people like. Qloo's taste graph links places, artists and areas through shared audiences, which is exactly the signal behind a good cross-promotion.

What it does

Local Taste Scout takes a business name, what it sells in a word or two (tacos, record store, yoga), a city and optionally an audience (millennials). It returns a brief a taqueria owner can act on the same afternoon:

  1. Partners to call: taste-adjacent venues in the same city, for bundles and co-hosted nights. The business itself is dropped, since a partner is adjacent, not identical.
  2. Culture hooks: artists the local taste audience over-indexes on, for themed nights, playlists and posts.
  3. Where to put flyers: the cells of the city where the top partner's audience concentrates, each linked to a map.
  4. A plan the owner can send today: who to call first with a ready 3-sentence message, the next event (partner + culture theme), the flyer headline and where it goes. Drafted by an LLM, but every venue, artist and area in it is a Qloo result, checked by code.
  5. What this does not establish, plus the full agent trace with the Qloo correlation id behind every section.

How it is Qloo-powered

Four calls through the official @qloo/qloo-harness (qloo exec), each decided by the previous result:

  • find_tags resolves the concept. Qloo has several tags named "Tacos" (cuisine, food item, place dish). The agent prefers the place-scoped tag, lists the alternatives, and flags ties instead of guessing. No tag means it stops with needs_input; it never recommends from an uncertain tag.
  • recommend with target place, filtered to the city: partner candidates.
  • recommend with target artist and the city as a signal: culture hooks. With an audience, the city is also sent as signal_location, which Qloo requires for demographic signals.
  • where_popular on the top partner, by its Qloo id (names like "Thai Food Near Me" exist on three continents), within the city.

The same four workflows are exposed through qloo mcp (qloo.mcp.json) for any MCP client.

How the LLM is used

Qloo decides who and where; the LLM only turns those results into words. It receives the Qloo results as numbered facts (P1 partner, C1 artist, A1 area) and must cite them by id, in a fixed JSON shape. Code then checks every id it cited against the facts. A reference Qloo did not return goes back to the model once, with the error; if the second answer is still wrong, the plan is shown as UNGROUNDED instead of as checked. The message is signed "[your name]" so the model never invents a person. If the LLM call fails, the Qloo brief still prints and says why.

Model: Qwen3-235B-A22B-Instruct on Nebius Token Factory (any OpenAI-compatible endpoint via LLM_BASE_URL/LLM_MODEL). The three recorded cases include the recorded LLM reply, so they replay with no key.

How we built it

Node 22 with no framework: the agent (src/scout.mjs), a thin transport over the harness with record/replay (src/qloo.mjs), a CLI, and a small web server and page for the hosted demo. 20 unit tests run without a key (including one where the model cites an artist Qloo never returned and has to correct it), and the three demo cases replay from recorded Qloo responses so anyone can reproduce them.

Challenges we ran into

The first live runs against the hackathon API changed the code: same-name tags tied between a cuisine and a place tag, where_popular returns coordinates rather than neighborhood names, ambiguous partner names failed resolution, demographic signals require a location, and Qloo refuses the heatmap for some places (QLOO_CONTRACT), so the agent moves to the next partner and says so in the trace. Each fix has a unit test built from the real response.

Responsible data handling

Inputs that look like an email or phone number are rejected before any call, so no personal data reaches Qloo. The key lives only on the server. Harness errors surface as errors; there is no silent fallback. The live demo is rate limited per visitor.

Known limitations

Qloo describes what groups tend to like, not what any one customer will do. A partner is taste-adjacent, not confirmed as open to a deal. A borough as the city ("Brooklyn, NY") resolved to the wider metro in our tests. The competitor filter is a name heuristic.

What's next

The plan already drafts the first message; next is a one-page co-promo proposal per partner and a printable flyer with the map, for the local businesses we already build websites for.

Built With

Share this project:

Updates

Submission history