Affinity Director

Inspiration

General-purpose AI agents are good at logistics, but cultural recommendations often fall back to broad stereotypes or model priors. We wanted to build an agent that can plan across music, venues, brands and film while keeping the cultural evidence visible. The core idea behind Affinity Director is that Qloo should be the grounding layer for cultural affinity, while the agent handles orchestration, ranking, coherence and product UX.

What it does

Affinity Director takes a small set of taste signals plus an optional location and turns them into one coherent cross-domain direction. The agent plans domain-specific discovery tasks, queries the Qloo integration layer, preserves raw affinity separately from its own Cultural Fit Score, ranks candidates, removes duplicate or over-concentrated results, and presents recommendations across multiple cultural domains.

The interface also builds an evidence graph from explicit contribution metadata so users can inspect why a recommendation is connected to the original taste signals. A baseline comparison makes it clear what the grounded pipeline adds over a generic recommendation path.

How we built it

The backend is written in Python with FastAPI. The agent orchestrator fans out discovery across artists, places, brands and movies, normalizes results, applies transparent scoring and confidence labels, then runs a deterministic coherence and deduplication pass. The project includes a Qloo API v2 client, bounded request validation, an explainability graph, a deterministic evaluation harness, a live-validation gate, and a container-ready deployment definition.

Development can run in a clearly labeled synthetic-fixture mode when credentials are unavailable. Synthetic data is never presented as Qloo data, and the live-validation gate refuses to make real-quality claims until a QLOO_API_KEY is configured and the validation checks pass.

Challenges

The hardest part was keeping source evidence separate from product-level reasoning. We did not want a polished score to obscure what came from Qloo versus what was computed by the application. We therefore preserve raw affinity, expose the Cultural Fit Score independently, and only create explainability edges when explicit numeric evidence exists.

A second challenge was cross-domain coherence. Simply combining the highest-ranked items can create repetitive results, so the agent includes a deterministic coherence pass that limits duplication while maintaining diversity across domains.

What we learned

Agentic recommendation systems are more useful when orchestration and grounding are treated as separate responsibilities. The model or agent can decide what to explore and how to assemble the experience, while a cultural-intelligence layer such as Qloo provides evidence that can be inspected rather than guessed.

What's next

Before final judging, the project is designed to run its live Qloo validation suite, freeze response parsing against observed live payloads, publish the containerized demo, and expose the public source repository with an open-source license.

Built With

• css
• docker
• fastapi
• html
• javascript
• pydantic
• python
• qloo-api
• uvicorn