README.md

metadata

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 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 with a full reproducible Modal pipeline (see training/); 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

---

✨ 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. 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

Member	Hugging Face	Email
Nithin Sai Kumar Kopparapu	@NANI-Nithin	naniknsk2002@gmail.com
Bhargav Malasani Nagaraj	@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