README.md

metadata

title: Tiny Quest Forge
emoji: 🎲
colorFrom: indigo
colorTo: yellow
sdk: gradio
python_version: 3.10.13
sdk_version: 5.0.2
app_file: app.py
fullWidth: true
header: mini
startup_duration_timeout: 1h
models:
  - openbmb/MiniCPM5-1B
preload_from_hub:
  - openbmb/MiniCPM5-1B
tags:
  - build-small-hackathon
  - gradio
  - zerogpu
  - thousand-token-wood
  - tiny-titan
  - openbmb
  - off-brand
  - off-the-grid
  - field-notes

Tiny Quest Forge

Tiny Quest Forge is a joyful 5-round AI-native mini-game. Each round invents one impossible errand, four strange item cards, and one hidden scoring rule. The player answers with a single sentence. The local judge awards points, a badge, and a twist. After five rounds, the app forges a shareable final result card.

The core model is openbmb/MiniCPM5-1B, a 1B parameter model. The Space uses local model inference only: no cloud APIs, no external inference APIs, no custom server, and no WebSockets.

Important: suggested_hardware does not assign ZeroGPU automatically. The Space owner must select ZeroGPU hardware in Space settings.

Prize Targets

• Thousand Token Wood: whimsical AI-native game loop with generated errands, item cards, hidden rules, and judging.
• OpenBMB Best MiniCPM Build: MiniCPM5-1B is the load-bearing game engine.
• Tiny Titan: the model is 1B parameters, under 4B.
• Off-Brand: custom Gradio Blocks UI with CSS and gr.HTML.
• Off the Grid: local inference only, with deterministic fallbacks when inference fails.
• Field Notes: build notes are included below.
• Best Demo: demo script is included below and in demo_script.md.
• OpenAI/Codex: built with Codex; commit history should use Codex attribution when published.

Demo video link: TBD

Social post link: TBD

Field Notes

What worked: small-model generation is strongest when each model call has a tight job. Tiny Quest Forge splits play into two short JSON tasks: make a round, then judge one move. That keeps prompts short, outputs parseable, and the game loop fast enough for a Space.

ZeroGPU choices: the model and tokenizer load at module level, and the shared generation function is decorated with @spaces.GPU(duration=25). The app does not lazy-load the model inside the GPU function and does not move the model to CUDA there. Generation is capped below the hackathon limit with max_new_tokens <= 220.

Why the model is load-bearing: the model is not decorative flavor text. It creates the errand, item constraints, hidden scoring rule, verdict, score, badge, twist, and next hook. If inference fails, deterministic fallbacks preserve the demo, but the intended play experience is model-authored.

Resilience: all model calls are wrapped. JSON is extracted with a robust parser, scores are clamped in Python from 0 to 20, and failures render a graceful fallback round instead of crashing the UI.

Demo Script

1. Start game.
2. Show the AI-generated challenge, including the errand, goal, item chips, and judge hint.
3. Enter a funny one-sentence solution using at least one strange item.
4. Show the AI judging result, score delta, twist, and badge.
5. Repeat through round five and show the final share card.

Local Development

Install dependencies, then run:

python app.py

For production on Hugging Face Spaces, use Gradio SDK with ZeroGPU hardware selected in the Space settings.