Spaces:
Running on Zero
A newer version of the Gradio SDK is available: 6.20.0
title: Unstuck
emoji: 🧩
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 6.17.3
python_version: 3.12.12
app_file: app.py
pinned: false
short_description: Tiny timed steps that learn your time-blindness
tags:
- build-small-hackathon
- backyard-ai
- track:backyard
- track:wood
- achievement:offbrand
- achievement:fieldnotes
- achievement:sharing
- achievement:offgrid
- achievement:llama
- achievement:welltuned
- sponsor:openai
- sponsor:openbmb
- sponsor:nvidia
- sponsor:modal
- tiny-titan
- tiny-model
- llama-cpp
- off-brand
- field-notes
- sharing-is-caring
- codex
- agent-trace
- zerogpu
- qwen
- adhd
- time-blindness
- task-breakdown
- calibration
- privacy
- small-models
Unstuck
Unstuck turns one overwhelming task into tiny timed steps, then learns your personal time-blindness and recalibrates the estimates to you. Built for the HF Build Small Hackathon (Backyard AI track). Runs a ≤4B model (Qwen/Qwen3-4B-Instruct-2507).
Your data stays yours. Plans and calibration history live in your browser (localStorage), not on the server — nothing is shared between users, and only the task text you submit ever reaches the model. Export/Import gives you the full round-trip.
What it does beyond a breakdown bot: a built-in step timer (Start → Done measures for you), per-category calibration learned from your actual times with a visible "Your patterns" history, progressive reveal (only the next step is live — no wall of steps), recursive "Still stuck?" re-breakdown, skip-without-polluting-the-data, plan persistence across reloads, and a markdown checklist export. One generate() seam serves eight interchangeable backends: ZeroGPU, HF serverless inference, Nebius Token Factory, a fully-offline local GGUF (offgrid), OpenBMB MiniCPM (minicpm) and NVIDIA Nemotron (nemotron), a fine-tuned Qwen2.5-0.5B we trained on Modal and published to the Hub (finetuned), and that fine-tune served on a Modal web endpoint (modal) — each picked by one env var with no app changes. ZeroGPU also falls back ZeroGPU → HF serverless → local fine-tune, so a plan always returns even if GPU quota is exhausted.
Demo & submission
- 📺 Demo video: watch the ~90-second demo
- 📣 Social post: https://x.com/arty_able/status/2066306266843021603
- 🧾 Agent trace (open trace): https://huggingface.co/datasets/build-small-hackathon/unstuck-agent-trace
- 📝 Field notes (build write-up): HF blog post · source
- 💻 Source: https://github.com/art87able/unstuck
Model: Qwen/Qwen3-4B-Instruct-2507 (4B — within the Tiny Titan ≤4B bar). Built small, in the open with OpenAI Codex (Codex-attributed commits) and an honest deterministic calibration layer — no AI in the differentiator.
Badges & bonus quests — the evidence
| Badge / track | Claim | Evidence |
|---|---|---|
| 🏡 Backyard AI (track) | A real anti-overwhelm tool for ADHD time-blindness | the whole app: tiny timed steps + honest per-category calibration |
| 🪶 Tiny Titan (≤4B) | Runs on a genuinely tiny model | default model Qwen/Qwen3-4B-Instruct-2507 (4 B) |
| 🔌 Off the Grid (local-first) | No cloud APIs — runs on the model in front of you | UNSTUCK_BACKEND=offgrid → local GGUF, zero network. Verified: docs/offgrid-proof.png is a plan generated fully offline by the local model. See Run fully offline below. |
| 🦙 Llama Champion (llama.cpp) | Model runs through the llama.cpp runtime | the offgrid backend drives Qwen3-4B-…-Q4_K_M.gguf via llama-cpp-python (same proof screenshot) |
| 🧾 Sharing is Caring (open trace) | Agent trace shared on the Hub | unstuck-agent-trace dataset |
| 🎨 Off-Brand (custom UI) | A frontend that pushes past the default Gradio look | custom gr.themes theme + a Fraunces gradient wordmark, gradient buttons, layered/hover step cards, indigo focus rings, fully de-branded chrome (see THEME/CSS in app.py) |
| 📝 Field Notes | A published write-up of what we built and learned | HF blog: Building Unstuck small (also in docs/field-notes.md) |
| 🤖 sponsor:openai (Codex) | Codex-attributed commits in the repo | built with the OpenAI Codex CLI — commit trail + the agent-trace dataset |
| 🟢 sponsor:nvidia (Nemotron) | The app runs on an NVIDIA Nemotron model | nvidia/Nemotron-Mini-4B-Instruct (4B, under the 32B cap) through the app's exact prompt + validator — verified 5/5 schema-valid breakdowns (scripts/finetune/modal_nemotron_test.py). The larger reasoning Nemotron-3-Nano-30B is also callable via Nebius/NIM, but its think-tokens are less schema-reliable — see the bake-off below |
| 🔵 sponsor:openbmb (MiniCPM) | The app runs on an OpenBMB MiniCPM model | UNSTUCK_BACKEND=minicpm serves openbmb/MiniCPM-V-4_5 over Nebius serverless via the same seam — live-verified valid breakdowns |
| ⚡ sponsor:modal (Modal) | Modal used to build and serve the app | the fine-tune was LoRA-trained on a Modal A10G GPU (modal_finetune.py) and is served on a Modal web endpoint (modal_serve.py) reachable via UNSTUCK_BACKEND=modal — development and runtime |
| 🎯 achievement:welltuned (fine-tuned) | The app uses a fine-tuned model published on HF | art87able/unstuck-qwen2.5-0.5b-steps — Qwen2.5-0.5B LoRA-tuned on 130 distilled Unstuck breakdowns (dataset); UNSTUCK_BACKEND=finetuned runs the app on it, and it's the always-on local fallback if ZeroGPU quota runs dry |
| 🏅 Bonus Quest Champion | Most bonus criteria met | the twelve rows above, each genuinely earned |
Backend bake-off — the seam, measured
Every small model is driven through Unstuck's exact breakdown contract (strict JSON schema + one repair retry) via the same ModelAdapter the app uses. Honest results (scripts/bakeoff.py):
| Model (serverless on Nebius) | Valid / 5 | Avg steps | Avg latency |
|---|---|---|---|
| Qwen3-30B-A3B (teacher) | 5/5 | 5.0 | 2.9s |
| OpenBMB MiniCPM-V-4.5 | 5/5 | 4.2 | 0.8s |
| NVIDIA Nemotron-3-Nano-30B (reasoning) | 0/5 | — | 41.8s |
| NVIDIA Nemotron-Mini-4B-Instruct (on Modal) | 5/5 | 5.4 | — |
| Unstuck fine-tune (Qwen2.5-0.5B) (on Modal) | ✓ valid | — | — |
The reasoning 30B Nemotron is the outlier — its think-tokens overrun the token budget and break the schema, which is exactly why we use the 4B non-reasoning Nemotron-Mini for the NVIDIA path.
Run locally
pip install -r requirements.txt gradio
UNSTUCK_BACKEND=hf_inference HF_TOKEN=... python app.py
The default backend is zerogpu, which the Space uses. The hf_inference path is the lightweight local option.
Run fully offline (offgrid)
No network, no cloud — a local quantised GGUF drives the same generate() seam (the honest basis for the offgrid badge):
pip install -r requirements.txt gradio llama-cpp-python
# drop a Qwen3-4B GGUF (e.g. Qwen3-4B-Instruct-2507-Q4_K_M.gguf) into ./models/
UNSTUCK_BACKEND=offgrid OFFGRID_GGUF_PATH=models/Qwen3-4B-Instruct-2507-Q4_K_M.gguf python app.py
llama-cpp-python is deliberately left out of requirements.txt (it would bloat the Space build) — install it only for offline use.
Verified locally — here it is generating a plan with no network, entirely on Qwen3-4B-Instruct-2507-Q4_K_M.gguf through llama.cpp:
Reproducible transcript (env → local .gguf load → model output, no network): docs/offgrid-proof.log.
Run on MiniCPM or Nemotron (Nebius serverless)
The same generate() seam runs the app on OpenBMB MiniCPM or NVIDIA Nemotron — both small (<32B) models served by Nebius Token Factory, selected by one env var:
# OpenBMB MiniCPM (sponsor:openbmb)
UNSTUCK_BACKEND=minicpm NEBIUS_API_KEY=... python app.py
# NVIDIA Nemotron (sponsor:nvidia) — 30B-A3B reasoning model, callable but less schema-reliable
UNSTUCK_BACKEND=nemotron NEBIUS_API_KEY=... python app.py
MiniCPM-V is live-verified valid (5/5 in the bake-off). The Nebius Nemotron above is the 30B reasoning model — callable, but the verified-valid Nemotron is the 4B nvidia/Nemotron-Mini-4B-Instruct (run on Modal, 5/5). Override MINICPM_MODEL / NEMOTRON_MODEL (or *_BASE_URL + *_API_KEY) to point at any other host — e.g. NVIDIA's own NIM endpoint at build.nvidia.com:
# Nemotron on NVIDIA's own NIM (build.nvidia.com)
UNSTUCK_BACKEND=nemotron \
NEMOTRON_BASE_URL=https://integrate.api.nvidia.com/v1 \
NEMOTRON_API_KEY=nvapi-... \
NEMOTRON_MODEL=nvidia/nemotron-3-nano-30b-a3b \
python app.py
Run on our fine-tuned model (finetuned)
UNSTUCK_BACKEND=finetuned runs the app on art87able/unstuck-qwen2.5-0.5b-steps — a Qwen2.5-0.5B-Instruct LoRA we trained on a Modal A10G GPU by distilling 130 schema-valid breakdowns out of the strong serverless model, then merged and published to the Hub:
pip install -r requirements.txt gradio torch transformers
UNSTUCK_BACKEND=finetuned python app.py # loads the published model, runs locally
The whole pipeline is in scripts/finetune/: gen_dataset.py (distillation) → modal_finetune.py (LoRA on Modal) → modal_verify.py (reloads the published model and asserts a schema-valid breakdown).
Your history lives in your browser. Use the in-app Export/Import buttons to move it between devices.
Source: https://github.com/art87able/unstuck (Codex Track)