README.md

metadata

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
🎬 Watch the demo Read the Blog

Social media Post Linkedin

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