Flare

Flare is an AI assistant that actually understands taste. Instead of guessing, it asks Qloo’s taste graph — then shows you exactly why each recommendation fits.

Comment

Inspiration

AI agents today can reason, plan, and execute almost anything — except understand what people actually want. Ask most AI assistants for a movie, a restaurant, or a playlist, and you get a plausible-sounding guess pulled from general training data, not from any real signal about taste. That's the exact gap the Qloo Agentic Hackathon calls out: agents are "culturally blind." Qloo's taste graph — 250M+ entities spanning music, film, dining, fashion, books, and more — exists specifically to close that gap. We wanted to find out what happens when an everyday, general-purpose AI assistant actually consults that graph before it answers, instead of guessing and hoping.

What it does

Flare is a complete conversational AI assistant — you can ask it anything, the same way you'd use ChatGPT, Gemini, or Claude. It explains concepts, writes code, does math, holds a normal conversation, and can look up current information through live web search. That's the baseline.

What makes it different is what happens the moment a question touches on taste — a mood, a meal, a movie, a place, an artist, a brand. At that point, Flare doesn't answer from memory. It routes the request through Qloo's taste graph, resolves the thing you mentioned into a real entity, pulls back genuine affinity-scored recommendations, and only then writes its answer — grounded in what that data actually returned.

The most important part isn't the lookup itself, it's what Flare does with it: cross-domain discovery. Mention a specific restaurant you love, and Flare can trace that exact taste signal into a completely different category — music that shares real cultural affinity with the people who love that same restaurant, not music that merely shares a keyword. You can keep chaining: from food, to music, to film, to books, each hop backed by a genuine Qloo signal, not an assumption we hardcoded.

Every single recommendation Flare gives carries visible, honest attribution. If Qloo's data was genuinely used to produce the answer, you see a clear "Qloo-powered" marker and can expand it to see the actual contributing signals and affinity scores. If it wasn't — because the query wasn't cultural, or because the model ultimately didn't rely on what Qloo returned — that attribution is withheld automatically. We treat this as a strict backend rule, not a UI decoration: attribution is computed server-side based on whether the returned items were actually incorporated into the final answer, and it's covered by its own dedicated regression test suite so it can never silently lie.

Beyond the chat experience, Flare exposes this same intelligence as a real, callable API: POST /v1/discover. It's documented, rate-limited, protected by its own API key, and has a live in-browser playground where you can run real queries against it and see the raw JSON. We also built a small, honestly-labeled developer page showing what it could look like if a third-party app — a streaming service, a music app, a food delivery app — embedded Flare's taste intelligence directly into their own product, with mockups clearly marked as illustrative rather than real partnerships.

How we built it

Frontend: React + TypeScript, with a custom dark, editorial visual design (deep charcoal and crimson, Unbounded/Manrope typography) built specifically to avoid looking like a templated AI-wrapper product. The chat interface streams responses in real time over Server-Sent Events, renders markdown safely, and shows live progressive status updates ("Accessing Qloo taste graph," "Calculating cultural affinities," "Synthesizing recommendations") so the agent's reasoning process is visible, not a black box.

Backend: Node.js + TypeScript (Hono), structured around a central agent loop rather than a rigid, hardcoded router. The model itself decides, per message, which tools it needs — Qloo's workflows, live web search, or nothing at all for a normal question — using real tool-calling, not keyword matching. This was deliberate: a scripted if/else router would have been easy to build but would have undercut the entire "agentic" premise of the hackathon.

Qloo integration: We built a dedicated provider layer wrapping several of Qloo's workflows — entity resolution/search, recommend for affinity-scored suggestions, find_tags for resolving ambiguous concepts into the right taxonomy type, where_popular for geographic signal, and explainability data showing exactly which input signal drove which output. Nothing in the rest of the app talks to Qloo directly; everything goes through this one layer, which also handles self-recommendation filtering (so a seed entity never recommends itself back to you) and seed resolution in parallel rather than sequentially, to cut latency.

LLM layer: A swappable provider interface so the underlying model isn't hardcoded to one vendor. In production we route through Token Harbor's gateway with an automatic failover chain — if the primary model hits a rate limit or outage mid-request, the system cascades through several fallback models, including a paid-tier model as a last resort, so a single provider hiccup can't take the whole demo down.

Enrichment and honesty layer: Qloo's recommendations get enriched with real-world data — live search results with visible source attribution, and movie/entity artwork — but every enriched item is explicitly tagged as either "Qloo Supported" or "Editorial Grounding," so a user (or a judge) can never mistake a general web result for a genuine taste-graph recommendation. We treat this distinction as seriously as the core Qloo integration itself.

Infrastructure we didn't skip: per-IP and global rate limiting tied to our actual provider quotas (not arbitrary numbers — we specifically checked Qloo's, Token Harbor's, and our search provider's real limits and set caps that protect all three simultaneously), a persistent-process deployment (chosen deliberately over serverless, because our rate limiter and cache are in-memory and would silently stop working on a platform that spins up fresh instances per request), and health-check endpoints for monitoring.

Challenges we ran into

Avoiding a thin wrapper. The hackathon brief is blunt: "if your submission would work the same without Qloo, you're building the wrong thing." Our first working version technically used Qloo, but it was just calling recommend and listing results — functionally interchangeable with a generic recommendation API. The real unlock was forcing ourselves to build cross-domain chaining as a first-class feature, so Qloo's actual strength — correlating taste across completely different categories — became the headline experience, not a backend implementation detail.

A catastrophic performance problem. Our first fully working Qloo-powered flow had a baseline response time that spiked as high as 70+ seconds on a bad run — completely unusable for a live demo judges would actually click through. We profiled it rather than guessing, and found two real causes: the backend was making a non-streaming LLM call to process Qloo's tool output and then a second, separate streaming call to actually respond — an entire redundant generation cycle — and image enrichment was blocking the whole response instead of resolving asynchronously. Fixing both cut response times by roughly 3.5x, down to a consistent 9–13 seconds for a completely fresh, uncached query, with live status updates covering the wait so it never feels broken.

One specific response had taken over 22 seconds even after the fix, which we initially worried was a regression. Instead of assuming it was fixed or broken, we tested it directly: it turned out to be a single-word movie title (a common English word) that genuinely needed heavier disambiguation against Qloo's full entity catalog. Testing several other fresh seeds confirmed that was a genuine outlier, not a systemic problem — but we wouldn't have known that without actually measuring rather than assuming.

Keeping attribution honest under pressure. It would have been far easier to just display "Qloo-powered" on every taste-adjacent response and call it done. We built a stricter system instead — attribution is only granted when the model's final answer demonstrably used Qloo's returned items, and it's revoked if the model discarded them or the underlying query turned out not to be cultural at all. We wrote and ran a dedicated attribution-lifecycle test suite specifically to make sure this rule can never be silently violated, because a judge checking this closely was exactly the scenario we wanted to survive.

A real security incident, caught in time. During development, an API key was accidentally committed to a test file and briefly pushed to a public GitHub repository. We caught it through a deliberate audit (not luck), made the repository private immediately, rotated every potentially affected credential, and verified — through direct GitHub traffic data — that the exposure window had no measurable external access before resubmitting. We treat this as part of the project's story rather than something to hide, because shipping fast under a deadline is real, and catching mistakes before they matter is part of doing it responsibly.

Honesty about what's real vs. planned. We built a developer-facing page showcasing the /v1/discover API and, early on, drafted example SDK install instructions for packages that didn't actually exist yet. We caught this ourselves before submission, verified directly against the npm and PyPI registries that neither package was published, and rewrote that section to clearly separate what works today (the live API, the in-browser playground) from what's genuinely just a roadmap (SDKs, partner dashboards, embeddable components) — using future tense throughout rather than letting it read as an existing feature.

Accomplishments that we're proud of

  • A genuinely agentic routing system, not a keyword-matched router — verified against a 36-prompt regression suite achieving 100% precision and 100% recall separating cultural/taste queries from general, factual, coding, and sensitive-topic queries that should never touch Qloo.
  • A real cross-domain discovery experience that demonstrates what makes Qloo structurally different from a generic recommendation engine, rather than just calling its API and listing the output.
  • A strict, server-enforced, independently-tested attribution system — Qloo gets credit exactly when and only when it earned it.
  • A working, documented, rate-limited, publicly callable API (/v1/discover) with a live playground, proving the "Flare as embeddable infrastructure" vision isn't just a pitch — it's something you can curl right now.
  • A 3.5x performance improvement found and fixed through actual profiling, not guesswork, taking the core experience from unusable to genuinely demo-ready.
  • Honest, verified documentation — we specifically checked claims against reality (package registries, actual test results, actual measured response times) rather than writing what sounded impressive.
  • A caught-and-corrected security incident, handled transparently rather than swept under the rug.

What we learned

That the hardest part of building "an AI with taste" was never the API call — Qloo's workflows are well-documented and straightforward to integrate. The hard part was making the taste data visibly and verifiably load-bearing in every single answer, so that the difference between Flare and a generic chatbot is something a skeptical judge can actually see and test, not something we just claim in a pitch. We also relearned a basic but easy-to-forget engineering lesson: measure before you optimize, and verify before you trust a report — several of our biggest fixes (the redundant LLM round-trip, the exposed API key, the unpublished SDK claim) only got caught because we checked directly against reality instead of assuming something worked.

What's next for Flare

The /v1/discover API and developer page represent a genuine proof of concept, not a finished platform, and we've been deliberate about labeling it that way throughout. The honest next steps: per-partner API keys with their own usage dashboards and billing, published TypeScript and Python SDKs (neither exists yet — we removed install instructions for both once we confirmed they weren't real packages), and embeddable UI components so a partner wouldn't need to build their own interface around our raw JSON. None of this exists today. It's the roadmap for what Flare could become if "Qloo, embedded inside the apps people already use" moved from a hackathon demo to something real.

Built With

Share this project:

Updates

Submission history