🗺️ 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 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

---

🏆 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

Bonus Quests

---

✨ 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):

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. The fine-tuned model can be enabled with a one-line change in app/services/generator.py.

---

🚀 Run locally

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. Voice-journal ASR setup: see 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

---

🙏 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