---
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_