Spaces:
Running on Zero
Running on Zero
| title: FrogQuest | |
| emoji: 🐸 | |
| colorFrom: green | |
| colorTo: yellow | |
| sdk: gradio | |
| sdk_version: 6.17.3 | |
| python_version: '3.12' | |
| app_file: app.py | |
| hf_oauth: true | |
| pinned: true | |
| license: apache-2.0 | |
| short_description: A text-image based RPG built to help fight procrastination | |
| tags: | |
| - track:backyard | |
| - track:wood | |
| - sponsor:openai | |
| - sponsor:nvidia | |
| - sponsor:modal | |
| - sponsor:black-forest-labs | |
| - achievement:offgrid | |
| - achievement:offbrand | |
| - achievement:llama | |
| - achievement:fieldnotes | |
| Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference | |
| ## FrogQuest | |
| **[▶️ Try the Space](https://huggingface.co/spaces/build-small-hackathon/FrogQuest)** | |
| **[🎬 Watch the demo](https://youtu.be/n-2a7a56wWU)** | |
| **[Read the Blog ](https://huggingface.co/blog/build-small-hackathon/frogquest)** | |
| [Social media Post Linkedin](https://www.linkedin.com/posts/soumya532_try-frogquest-today-ugcPost-7471943345662021632-rmnx/?utm_source=share&utm_medium=member_desktop&rcm=ACoAAETNtiwB6QJ_lnhIW_3QCLWUz5B_HzSts-E) | |
| Turn your real life goals into an 8-bit pixel-art text-adventure quest log where **you** are the | |
| hero. Named for the "Eat That Frog" method: your hardest/most important task is the **frog** — the | |
| boss quest you face first. | |
| - **Nemotron Nano 4B** (text only, via llama.cpp on ZeroGPU) writes the quest JSON — Eat That Frog | |
| prioritization, linked sub-task chains, and optional self-care bonus quests. | |
| - A fixed pixel-art frontend (`gr.Server` custom UI) renders that JSON as the quest log. | |
| - **FLUX.2 [klein] 4B** (diffusers) generates each quest's image using your uploaded photo as a | |
| reference, then edits that same image into success / "retreat to fight another day" states. | |
| Your photo and quest state live in your browser (localStorage) **and** in a private per-user JSON | |
| record on the Space's storage. **Sign in with your Hugging Face account** (top right) and the | |
| record is keyed to your account — same state on any device, nothing to remember. Logged out, it's | |
| keyed by a random **Hero Code** shown in the left panel instead — paste it on a new device (or | |
| after a cleared browser) to get everything back. The photo is sent to the GPU only transiently | |
| during generation. | |
| NOTE: after enabling/changing `hf_oauth`, fully restart (factory rebuild) the Space so the OAuth | |
| login route gets registered — clicking Sign in before that yields a "Could not parse server | |
| response" error. | |
| ### Durable storage (Storage Bucket) | |
| For the server-side record to survive Space restarts, mount a HF **Storage Bucket**: | |
| 1. Create a bucket at https://huggingface.co/new-bucket (private is fine). | |
| 2. Space **Settings → Storage Buckets → Mount a bucket** → pick it, mount path **`/data`**, | |
| read-write. | |
| The app writes `users/<hero-code>.json` files there (`store.py`; `FROGQUEST_DATA_DIR` overrides the | |
| location, and without any mount it falls back to the container's ephemeral disk — fine for testing, | |
| wiped on rebuild). | |
| ### GPU backend (ZeroGPU or Modal) | |
| The GPU work (quest JSON + images) runs through a pluggable backend chosen by the | |
| `FROGQUEST_BACKEND` env var. The frontend, signatures, and behavior are identical either way. | |
| **`zerogpu` (default).** Everything runs in-Space on ZeroGPU. | |
| - Set the Space hardware to **ZeroGPU**. | |
| - First quest generation cold-downloads the models, then runs fast. | |
| - Subject to ZeroGPU daily quotas (anon 2 min, free 5 min, PRO 40 min per day). | |
| **`modal` (opt-in).** The Space runs on CPU-basic and offloads GPU work to [Modal](https://modal.com) | |
| (dedicated GPU, pay-per-second, no quota). Switching is **two steps** — the env var alone does NOT | |
| change hardware: | |
| 1. Set the Space hardware to **CPU basic**. | |
| 2. Add a Space **variable** `FROGQUEST_BACKEND=modal`. | |
| One-time Modal setup: | |
| 1. `pip install modal` and `modal token new` (authenticate). | |
| 2. `modal deploy modal_app.py` (deploys the `frogquest` app: an `LLM` class + a `Flux` class). | |
| 3. Add `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` as Space **secrets** so the Space can call Modal. | |
| 4. Optional: set `FROGQUEST_MODAL_FLUX_GPU` before `modal deploy` to pick the image GPU | |
| (default `A10G`; `L4` cheaper; `L40S`/`A100-40GB` if it OOMs). | |
| Optional: rename `requirements-modal.txt` → `requirements.txt` on the Space to skip installing the | |
| heavy GPU libs (torch/diffusers/llama-cpp) and speed up CPU-basic builds. | |
|  | |