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 workflow was supported by Nora, an AI assistant powered by OpenAI, across development, testing, browser automation, and submission workflow; Ermir Kazazi remains the sole human creator and official entrant.

Challenges we ran into

Transitioning from synthetic fixtures to the Qloo hackathon live API required careful mode management to avoid mixing test and production data. We discovered that Qloo's per-candidate explainability referenced underlying entity IDs rather than user-entered signal names, necessitating additional parsing and mapping logic. To handle ambiguous free-form phrases, we implemented conservative exact-only signal resolution to prevent unrelated ranked search hits from being force-mapped. We also maintained a strict separation between raw Qloo affinity scores and the product-level Cultural Fit Score, ensuring raw API values were never conflated with derived metrics. Finally, we validated deployment and live API behavior without exposing API keys or raw sensitive response artifacts in logs or UI. These challenges were resolved through careful architectural design and thorough testing.

Live validation results

We verified the final deployed pipeline against the Qloo hackathon API with real requests. Two canaries covered music, venue, brand and film with zero provider failures and complete verification. In the Milan scenario, A24 and Arctic Monkeys resolved to exact provider IDs while "technical streetwear" stayed on Qloo's native named-query path; selected candidates reached 1.0 evidence coverage with 16 explicit signal-to-result edges. A second cross-domain canary kept "Japanese contemporary design" on the native named-query path while A24 resolved exactly, again with 1.0 evidence coverage. These checks validate live integration, orchestration and explainability wiring, not generalized recommendation superiority or human-preference quality.

What's next

Live validation complete, parser stabilized against observed live payloads, containerized demo published, and source repository publicly available.

Built With

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