CommonGround — Qloo Agentic Hackathon

Public preview: https://meowrona.github.io/CommonGround/

Latest-build cache-bypass: https://meowrona.github.io/CommonGround/?build=20261003-open-data-v1

Public source: https://github.com/MeowRona/CommonGround

Architecture: ARCHITECTURE.md

Judging demo script: DEMO_SCRIPT.md

API-key request handoff: QLOO_KEY_REQUEST.md

Submission requirements / release gate: SUBMISSION_REQUIREMENTS.md

Use the Render button only after the Qloo key passes live_smoke.py; the Blueprint will prompt for QLOO_API_KEY as a secret.

CommonGround helps two people with different tastes find one movie that each person reaches for a different reason.

The core interaction is intentionally narrow:

1. each person searches for and selects 1–3 films or artists;
2. the live UI stores the exact Qloo entity ID/type, so ambiguous names are not silently guessed;
3. Qloo independently discovers movie candidates for A and B;
4. CommonGround unions those candidates and asks Qloo to evaluate the same movie pool for both people;
5. candidates missing an evaluation on either side stay unknown instead of becoming zero;
6. CommonGround minimizes the worse rank first, then the sum of both ranks;
7. it proposes one bridge movie;
8. both people react: Want to try / Already know / Not for me;
9. a veto or already-known result is excluded and triggers one wider second round (25 candidates per side, keeping the union within Qloo's 50-result request window);
10. after two rounds, the agent stops rather than forcing a compromise.

The public fixture deliberately includes a case where A's top 3 and B's top 3 have zero overlap, yet evaluating the union for both profiles recovers Arrival at A #3 / B #4. This makes the reason for same-pool evaluation directly inspectable instead of merely claiming that it helps.

Why Qloo matters

Without Qloo, the intended product loses its core capability: cross-domain cultural relationships from inputs such as films + artists to a movie candidate pool, plus per-result explainability metadata.

The application layer does not claim to predict whether a person will like something. It uses Qloo's result ordering as query-context evidence, then applies a transparent two-person decision policy.

Public preview vs live mode

While the Qloo hackathon key is pending, the public GitHub Pages build runs an explicitly labelled OPEN-DATA TEST MODE — NOT QLOO. It searches real entities through Wikipedia/Wikidata and uses Wikipedia morelike: related-page search to generate temporary cultural candidates. Unlike the final Qloo path, the temporary bridge may be any mapped cultural object — artist, label, album, genre, film, person, etc. — which makes it useful for testing arbitrary profiles without fabricating Qloo output.

The open-data ranking is intentionally treated as a weaker temporary heuristic. It is not described as Qloo affinity or as the final fairness signal.

• Public Pages with empty docs/runtime_config.json — open-data test mode.
• ?static=1 — deterministic fixture scenarios generated by the Python decision engine.
• COMMON_GROUND_MODE=fixture — local backend fixtures.
• COMMON_GROUND_MODE=live + configured Pages api_base — real Qloo /search + /v2/insights flow.

The live client already implements:

• entity search/resolution via /search and the app's /api/search selector endpoint;
• movie discovery via /v2/insights;
• feature.explainability=true;
• candidate exclusions via filter.exclude.entities;
• same-pool evaluation via filter.results.entities;
• defensive parsing and fail-closed behavior when response structure is unexpected.
• parallel A/B discovery and same-pool evaluation to avoid unnecessary serial API latency.
• lightweight per-client rate limits and a bridge-concurrency cap so a public demo cannot trivially burn through the hackathon API allowance.

The remaining final-submission gate is the real hackathon API key, live schema verification, and deployment of the already-prepared Render API. The temporary Wikimedia mode is for development/testing only and must not be presented as the hackathon's Qloo-powered result.

Official API key request form: https://forms.gle/zz12orkLHTAneLGz6

The repository also contains a prepared render.yaml for a free live backend once that smoke test passes.

Run locally

Python 3.11+; no third-party Python packages are required.

python app.py

Open the printed http://127.0.0.1:<port>/ URL.

Run tests:

python -m unittest discover -s tests -v

Once the hackathon key is available, run the full read-only live contract smoke test:

$env:QLOO_API_KEY="..."
python live_smoke.py --write-fixture

The script never prints or records the key. It verifies entity resolution, independent discovery, same-pool evaluation, the first bridge, and a second-round exclusion. With --write-fixture, it saves request query parameters plus raw Qloo response JSON to an ignored local fixture for schema debugging.

After deployment, run the final automated readiness check:

$env:LIVE_API_URL="https://your-service.onrender.com"
python submission_preflight.py

The preflight can be launched from any working directory. It verifies that the local HEAD is the commit actually published as origin/main and that the HTML currently served by GitHub Pages matches docs/index.html, so neither a clean-but-unpushed repo nor a stale Pages build can accidentally pass the final gate.

The final Devpost demo URL remains the fast GitHub Pages frontend. After Render is live, configure_live_frontend.py writes the Render API origin into docs/runtime_config.json; Pages then wakes and uses the live backend while keeping the key server-side.

Build the static public preview:

python build_static_preview.py

Decision policy

For every movie that has measurements on both sides:

1. minimize max(rank_A, rank_B);
2. break ties with rank_A + rank_B.

Example: A=#1 / B=#9 loses to A=#6 / B=#6, even though average rank prefers the first candidate. This is a simple least-misery-style protection rule, not a novel preference model.

Current validation

The test suite covers:

• random/unrecognized text failing instead of generating fake recommendations;
• a candidate found only in A's discovery still being evaluated for B;
• same-pool evaluation request parameters;
• missing evaluation staying unknown;
• worse-rank protection (1/9 vs 6/6);
• second-round widening and veto persistence;
• hard two-round limit;
• candidate-specific evidence;
• live search/insight response parsing fixtures;
• exact explainability-ID matching without substring false positives;
• secret-safe HTTP errors;
• explicit resolved-entity payload validation, so the agent receives stable Qloo IDs instead of reinterpreting a selected label;
• search caching, request bounds and per-client rate limits;
• real HTTP handler behavior for /health, /api/search, /api/bridge, allowed/blocked CORS origins and invalid content types;
• GitHub Pages fixture parity, runtime-config presence and non-blocking Render wake-up polling;
• smoke/preflight title matching across harmless punctuation/diacritic differences.

Submission status

Public preview and public source are ready. Do not final-submit yet. The remaining blockers are:

1. receive the Qloo hackathon API key;
2. run live /search and /v2/insights smoke tests;
3. verify the exact live explainability fields;
4. deploy the Python backend on Render Free with the key stored server-side;
5. point docs/runtime_config.json at that verified live API while keeping the same GitHub Pages demo URL;
6. run the final preflight, capture live screenshots, and complete human review/submission.