---
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: A Multiplayer game to explore cities in the vintage way
---

# 🎮 AI-Powered Real-World Game Platform

An AI-powered platform that generates complete, playable real-world games — rules, tasks, hints, scoring, and a narrative summary — based on game type, location, and player preferences.


## Games Supported

- Scavenger Hunt
- Hide & Seek
- Tag

## How It Works

1. Select a game type, city, and preferences
2. AI generates rules, tasks, and hints
3. Play in the real world, track progress in the app
4. Record voice journals during play (auto-transcribed with [Cohere Transcribe](https://huggingface.co/CohereLabs/cohere-transcribe-03-2026))
5. Receive an AI-generated story summary of the outcome

## UI Improvements (v2.0)

The Gradio interface (`app.py`) adds a more interactive, server-driven feel
while keeping the existing in-process room state and `gr.Timer` polling model
(no backend/game logic changed):

- **Real-time form validation** — the Join screen shows a live room-code
  counter/format check and only enables **Join** once a valid 6-character code
  and a name are present; the Create screen shows a live one-line summary of
  the chosen configuration.
- **Loading states** — buttons that trigger model/IO work (create, start,
  transcribe, save journal, ask the guide, recaps, posters) disable while the
  call runs to prevent double-submits, alongside the existing inline loaders.
- **Streaming recap** — the winning and funny recaps reveal
  paragraph-by-paragraph for a narrative pace (content unchanged; presentation
  only).
- **Toast notifications** — `gr.Info`/`gr.Warning` toasts confirm joins, task
  completions, photo uploads, and journal saves, and surface validation errors.
- **Animated reveals** — the task-detail panel and hint/safety notes ease in;
  status pills and the countdown timer transition smoothly on poll updates.
- **Adaptive polling** — the shared poll timer stays at 1.5 s while anything is
  changing and eases to ~3 s when a screen is idle, snapping back to fast on any
  activity or screen transition.

## AI Models

| Stage | Model | Notes |
| --- | --- | --- |
| Game generation | `nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF` via llama.cpp | Retrieval-grounded, validation + repair enforced |
| Voice journal ASR | `CohereLabs/cohere-transcribe-03-2026` via 🤗 Transformers | 14 languages, lazy-loaded; typed-input fallback |
| Recap (optional) | `openbmb/MiniCPM5-1B-GGUF` | Currently using deterministic template recap for reliability |
| Poster (optional) | `black-forest-labs/FLUX.1-schnell` | Skipped under `CITYQUEST_SKIP_MODEL` |

Set `CITYQUEST_FAST_TEST=1` to run the entire pipeline without
downloading any model weights.

## Team



Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference