| --- |
| title: CityQuest AI |
| emoji: 🗺️ |
| colorFrom: pink |
| colorTo: blue |
| sdk: gradio |
| sdk_version: 6.16.0 |
| python_version: '3.12' |
| app_file: app.py |
| pinned: false |
| license: apache-2.0 |
| short_description: AI-generated multiplayer real-world city games |
|
|
| tags: |
| - track:wood |
| - sponsor:openbmb |
| - sponsor:nvidia |
| - sponsor:modal |
| - achievement:welltuned |
| - achievement:offbrand |
| - achievement:llama |
| - achievement:fieldnotes |
| --- |
| |
| # 🗺️ CityQuest AI |
|
|
| **Turn any city into a multiplayer real-world game.** CityQuest AI generates complete, |
| playable adventures — **Scavenger Hunt, Hide & Seek, and Tag** — tailored to a real |
| location, your group size, age range, difficulty, and theme. It grounds every quest in |
| the actual city (real districts, landmarks and parks), runs a live multiplayer room with |
| proof-gated tasks and scoring, lets players record **voice journals** during play, and |
| wraps the session up with an **AI narrative recap** and a generated **poster**. |
|
|
| > Built for the **[Build Small Hackathon](https://huggingface.co/build-small-hackathon)** |
| > by Gradio × Hugging Face (June 5–15, 2026). Small models, big adventures — everything |
| > runs on models **≤ 4B parameters** through **llama.cpp**, orchestrated on a single GPU. |
|
|
| --- |
|
|
| ## 🔗 Links |
|
|
| | | | |
| | --- | --- | |
| | 🎮 **Live App (HF Space)** | https://huggingface.co/spaces/build-small-hackathon/CityQuest-AI | |
| | 💻 **GitHub** | https://github.com/NANInithin/CityQuest-AI | |
| | 🤖 **Fine-tuned model** | https://huggingface.co/NANI-Nithin/CityQuest-Nemotron-3-Nano-4B-GGUF | |
| | 🏕️ **Hackathon** | https://huggingface.co/build-small-hackathon | |
| | 𝕏 **Social Media Post|https://x.com/mnbhargav8/status/2066632722664010144?s=20| |
| |🏃 **Demo game run**|https://www.youtube.com/watch?v=QtjaA9YZHOc| |
| |🏃 **Demo game recording**|https://youtu.be/wyrfTrp68yw| |
| |
| --- |
| |
| ## 🏆 Hackathon at a glance |
| |
| # Trail: An Adventure in Thousand Token Wood |
| **Constraints met** |
| - ✅ **Gradio app hosted on a Hugging Face Space** |
| - ✅ **All models ≤ 32B** — in fact **≤ 4B** (NVIDIA Nemotron 3 Nano **4B** + OpenBMB MiniCPM5 **1B**) |
| - ✅ **Load-bearing AI** — the entire game (rules, tasks, hints, safety, scoring, recap, poster) is model-generated, not scripted |
|
|
| **Track:** primarily **Thousand Token Wood** (a delightful, original AI experience that |
| gamifies real-world exploration), with strong **Backyard AI** relevance — it solves a real |
| problem for friends/family: planning a fun, safe group outing in minutes. |
|
|
| ### Sponsor tech we build on |
| | Sponsor | How we use it | |
| | --- | --- | |
| | **NVIDIA Nemotron** | `Nemotron-3-Nano-4B` (GGUF) is our core game generator | |
| | **OpenBMB** | `MiniCPM5-1B` (GGUF) powers the episode-recap path | |
| | **Modal** | Full LoRA fine-tuning + GGUF conversion pipeline runs on Modal A100s | |
| | **Cohere** | `cohere-transcribe-03-2026` transcribes in-game voice journals | |
|
|
| ### Bonus Quests |
| | Badge | Status | Evidence | |
| | --- | --- | --- | |
| | 🦙 **Llama Champion** (llama.cpp runtime) | ✅ Earned | Nemotron **and** MiniCPM run via `llama-cpp-python` | |
| | 🪙 **Tiny Titan** (≤4B models) | ✅ Eligible | Both LLMs are ≤4B; runs on modest hardware | |
| | 🎛️ **Well-Tuned** (fine-tuned model on HF) | ✅ Eligible | LoRA fine-tune **published** at [`NANI-Nithin/CityQuest-Nemotron-3-Nano-4B-GGUF`](https://huggingface.co/NANI-Nithin/CityQuest-Nemotron-3-Nano-4B-GGUF) with a full reproducible Modal pipeline (see [`training/`](training/README.md)); under active development for location grounding | |
| | 📓 **Field Notes** (dev report) | ✅ Eligible | **published** at [Teaching a 4B Model to Run a City-Wide Scavenger Hunt — Without Naming a Single Street](https://huggingface.co/blog/build-small-hackathon/cityquest-ai) | |
|
|
|
|
| --- |
|
|
| ## ✨ Features |
|
|
| - **City-grounded generation** — live **Wikipedia** city context injects real districts, |
| landmarks and parks so quests reference actual places, not generic ones. |
| - **Three game types** — Scavenger Hunt, Hide & Seek, Tag, each with type-appropriate |
| rules, tasks/zones, hints, and scoring. |
| - **Schema-guaranteed output** — every generated game is validated against a strict JSON |
| schema, auto-**repaired** on failure, with a safe fallback — so the app never breaks. |
| - **Multiplayer rooms** — create/join with a 6-character room code; synchronized state via |
| adaptive `gr.Timer` polling (1.5s when active, eases to ~3s when idle). |
| - **Proof-gated tasks** — complete tasks with **photo / observation / text** proof; live |
| leaderboard, points, hints (with penalties), and a countdown timer. |
| - **Ask-the-Guide** — per-task AI helper for clues and clarifications during play. |
| - **Voice journals** — record audio during the quest; auto-transcribed (14 languages) with |
| a typed-input fallback. |
| - **AI recap + poster** — a streamed narrative episode recap of how the game played out, |
| plus a cinematic poster image. |
| - **Safety-first** — generated games include allowed zones, forbidden behaviors, adult- |
| supervision flags and stop conditions. |
|
|
| --- |
|
|
| ## 🧠 AI architecture — small models, orchestrated |
|
|
| Everything is built around **small, efficient models** sequenced on a single GPU (each is |
| loaded for its stage and unloaded to free VRAM for the next — appropriate model sizing by design): |
|
|
| | Stage | Model | Runtime | Notes | |
| | --- | --- | --- | --- | |
| | 🎯 Game generation | `nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF` | **llama.cpp** | Retrieval-grounded + Wikipedia city context; JSON-schema validated & repaired | |
| | 🗣️ Voice journal ASR | `CohereLabs/cohere-transcribe-03-2026` | 🤗 Transformers | 14 languages, lazy-loaded; typed fallback | |
| | 📖 Episode recap | `openbmb/MiniCPM5-1B-GGUF` | **llama.cpp** | Narrative recap (deterministic template fallback for reliability) | |
| | 🖼️ Poster | `black-forest-labs/FLUX.1-schnell` | 🤗 Diffusers | Cinematic recap poster | |
| | 📍 Location context | **Wikipedia API** | — | Real landmarks/districts/parks per city | |
|
|
| `CITYQUEST_FAST_TEST=1` runs the full pipeline without downloading any model weights. |
|
|
| --- |
|
|
| ## 🎛️ Fine-tuning (Well-Tuned quest) |
|
|
| We built a complete, reproducible pipeline to **LoRA fine-tune Nemotron 3 Nano 4B on the |
| CityQuest dataset** and ship it as a GGUF — all on **Modal**: |
|
|
| ``` |
| app/data/<game>/dataset.json |
| │ prepare_dataset.py — serve-matched SFT prompts + game_schema targets (leave-one-out retrieval) |
| ▼ |
| training/data/*.jsonl |
| │ train_modal.py — transformers + PEFT LoRA on A100 (native nemotron_h + mamba kernels, |
| │ checkpoint/resume) → merge → GGUF Q4_K_M → upload to HF |
| ▼ |
| 🤗 NANI-Nithin/CityQuest-Nemotron-3-Nano-4B-GGUF |
| │ eval_gguf.py — schema-pass evaluation vs the stock base |
| ``` |
|
|
| **Honest status:** the fine-tune is **published on Hugging Face** and the pipeline is fully |
| reproducible. On evaluation it matched the base on structure but **regressed on location |
| grounding** (the synthetic training targets used generic descriptions, so it under-used the |
| real-city context) — so the live app currently serves the **stock Nemotron base** for the best |
| player experience. The next iteration regenerates the training targets grounded in real |
| landmarks. Full details in **[`training/README.md`](training/README.md)**. The fine-tuned model |
| can be enabled with a one-line change in `app/services/generator.py`. |
|
|
| --- |
|
|
| ## 🚀 Run locally |
|
|
| ```bash |
| pip install -r requirements.txt |
| python app.py # launches the Gradio app |
| |
| # Fast smoke test (no model downloads): |
| CITYQUEST_FAST_TEST=1 python app.py |
| ``` |
|
|
| llama.cpp setup: see [`NEMOTRON_GGUF_SETUP.md`](NEMOTRON_GGUF_SETUP.md). |
| Voice-journal ASR setup: see [`COHERE_ASR_SETUP.md`](COHERE_ASR_SETUP.md). |
|
|
| --- |
|
|
| ## 🛠️ Tech stack |
|
|
| - **Gradio** app on **Hugging Face Spaces** (ZeroGPU-ready) |
| - **llama.cpp** (`llama-cpp-python`) for LLM inference |
| - **🤗 Transformers / Diffusers** for ASR and image generation |
| - **Modal** for cloud-GPU fine-tuning |
| - **PEFT / TRL-free Trainer** LoRA training; **GGUF Q4_K_M** quantization |
| - Strict **JSON-Schema** validation + repair around all generations |
|
|
| --- |
|
|
| ## 👥 Team |
|
|
| | Member | Hugging Face | Email | |
| | --- | --- | --- | |
| | **Nithin Sai Kumar Kopparapu** | [@NANI-Nithin](https://huggingface.co/NANI-Nithin) | naniknsk2002@gmail.com | |
| | **Bhargav Malasani Nagaraj** | [@MNbalu](https://huggingface.co/MNbalu) | mnbhargavfr@gmail.com | |
|
|
| --- |
|
|
| ## 🙏 Acknowledgements |
|
|
| Built for the **Build Small Hackathon** (Gradio × Hugging Face). Thanks to sponsors |
| **NVIDIA** (Nemotron), **OpenBMB** (MiniCPM), **Cohere** (Transcribe), and **Modal** for the |
| models, tooling and compute that made CityQuest possible. |
|
|
| _License: Apache-2.0_ |
|
|
