Spaces:
Running on Zero
Running on Zero
| # Plan: Gamified Productivity Buddy | |
| ## Context | |
| Building a hackathon entry for HF "Build Small" (Thousand Token Wood track, deadline June 15 2026 — 2 days). | |
| The app is a whimsical RPG-flavored productivity companion: a 3D character lives on the left, a local LLM buddy lives on the right, and your focus sessions earn XP, coins, and cosmetic gear. | |
| --- | |
| ## Tech Stack | |
| | Layer | Choice | Reason | | |
| |---|---|---| | |
| | App framework | Gradio `gr.Blocks` | Required by hackathon | | |
| | Hosting | HF Spaces (GPU T4) | Required; enables Off-the-Grid badge | | |
| | LLM | `Qwen/Qwen2.5-3B-Instruct` via 🤗 `transformers` | 3B = fast on T4, excellent tool-call support | | |
| | 3D avatar | Three.js + GLB/GLTF model | User confirmed; served from Gradio static | | |
| | Frontend glue | Embedded `<script>` in `gr.HTML` + hidden textbox bridge | JS→Python event passing | | |
| | Python env | `venv` | User requirement | | |
| **Bonus badges targeted**: Off the Grid (no cloud APIs), Off-Brand (custom frontend), Tiny Titan (≤4B model). | |
| --- | |
| ## Project Structure | |
| ``` | |
| 08/ | |
| ├── app.py # Gradio entry point | |
| ├── src/ | |
| │ ├── llm.py # Model load, chat, tool-call parsing | |
| │ ├── game_state.py # XP / coins / levels / inventory dataclass | |
| │ ├── tools.py # Tool definitions + executor | |
| │ └── reminder.py # Idle detection thread | |
| ├── static/ | |
| │ ├── js/ | |
| │ │ ├── avatar.js # Three.js scene, GLB loader, animations | |
| │ │ ├── timer.js # Pomodoro / free-flow countdown + JS events | |
| │ │ └── bridge.js # Dispatches JS events → hidden Gradio textbox | |
| │ ├── css/ | |
| │ │ └── style.css # 2-column RPG dark theme | |
| │ └── models/ | |
| │ └── character.glb # Free CC0 character (see note below) | |
| ├── requirements.txt | |
| ├── .env.example | |
| └── README.md | |
| ``` | |
| **GLB model source**: Use the free CC0 "Adventurer" from Kenney (kenney.nl/assets/adventurer) or any Mixamo Y-Bot export. Place the file at `static/models/character.glb`. Animations needed: `idle`, `walk`, `celebrate`. | |
| --- | |
| ## Layout (Gradio custom HTML) | |
| ``` | |
| ┌──────────────────────┬──────────────────────┐ | |
| │ 3D Avatar (Three.js)│ Chat window │ | |
| │ [idle / celebrate] │ (gr.Chatbot) │ | |
| │ │ │ | |
| │ XP: 120 | ⚙ Lv.2 │ ── Inventory ── │ | |
| │ 💰 Coins: 35 │ (slides over chat │ | |
| │ │ when [Bag] clicked)│ | |
| │ ── Timer ── │ │ | |
| │ [🍅 Pomodoro] │ │ | |
| │ [∞ Free Flow] │ │ | |
| │ [Start] [Stop] │ │ | |
| │ │ │ | |
| │ ── To-Do ── │ │ | |
| │ [ ] Task 1 │ │ | |
| │ [✓] Task 2 │ │ | |
| │ [+ Add task] │ │ | |
| └──────────────────────┴──────────────────────┘ | |
| ``` | |
| The two columns are rendered inside a single `gr.HTML` component that bootstraps Three.js and the timer. Gradio components (`gr.Chatbot`, `gr.Textbox` input, hidden state bridges) sit in `gr.Row`/`gr.Column` alongside. | |
| --- | |
| ## Implementation Steps | |
| > Tracer-bullet order: each slice is a working vertical cut of the full stack. | |
| ### ✅ 1. Bootstrap | |
| - `python -m venv .venv`, install deps, `requirements.txt` — **done** | |
| ### 2. Chat with local LLM | |
| Goal: bare-bones two-column Gradio app where you can talk to Qwen2.5-3B-Instruct. | |
| - `src/llm.py`: load model with `AutoModelForCausalLM` + `bfloat16` + `device_map="auto"`; `chat(messages) -> str` | |
| - `app.py`: minimal `gr.Blocks` with left placeholder column + right `gr.Chatbot` + `gr.Textbox` input | |
| - System prompt: whimsical RPG companion persona | |
| - Deliverable: type a message, get a reply | |
| ### 3. Timer | |
| Goal: functional Pomodoro/free-flow timer in the left column with configurable durations. | |
| - `static/js/timer.js`: countdown logic, work/break modes, start/stop/reset | |
| - `static/css/style.css`: dark RPG theme skeleton, two-column layout | |
| - Left column rendered via `gr.HTML`: timer display + mode selector (Pomodoro / Free Flow) + duration inputs + Start/Stop buttons | |
| - `static/js/bridge.js`: JS → Python bridge via hidden `gr.Textbox` | |
| - Python handler: receives `timer_complete` event, lays groundwork for XP (stub for now) | |
| - Deliverable: timer counts down, rings on completion | |
| ### 4. LLM → Timer tool calls | |
| Goal: LLM can start/stop the timer via natural language. | |
| - `src/game_state.py`: add `timer_state` dict to a minimal `GameState` dataclass | |
| - `src/tools.py`: define `start_timer` and `stop_timer` JSON schemas + executor | |
| - `src/llm.py`: extend `chat()` to pass tools, parse Qwen `<tool_call>` tags, execute, re-call model | |
| - Inject current timer state into system prompt each turn | |
| - Python → JS: after tool execution, return a JS command string to update timer UI | |
| - Deliverable: "start a 25 minute focus session" → timer starts in UI | |
| ### 5. Todo list | |
| Goal: functional todo list in the left column (below timer). | |
| - Extend `GameState`: add `todos: list[dict]` with `id`, `task`, `done` | |
| - `gr.HTML` todo section: renders current todos from state, checkbox to complete, delete button | |
| - Python handlers: `add_todo`, `complete_todo`, `remove_todo` update state + re-render HTML | |
| - Inject todo list into system prompt each turn | |
| - Deliverable: todos appear, can be checked off manually | |
| ### 6. LLM → Todo tool calls | |
| Goal: LLM can manage todos via natural language. | |
| - `src/tools.py`: add `add_todo`, `complete_todo`, `remove_todo` schemas + executors | |
| - Wire into `chat()` tool loop (same pattern as timer) | |
| - On `complete_todo`: award +10 XP (introduce XP to `GameState` here) | |
| - Deliverable: "add a todo: review PR" → todo appears; "mark it done" → checked off, XP ticks up | |
| ### ✅ 7. 3D Avatar | |
| Goal: Three.js GLB character in the left column that reacts to app events. | |
| - `static/js/avatar.js`: Three.js scene, `GLTFLoader`, animation mixer | |
| - Animations mapped to events: `idle` (default), `working` (timer running), `celebrate` (timer complete / level up), `cheer` (todo complete) | |
| - `bridge.js`: extend Python → JS channel to accept `{cmd: "avatar", animation: "celebrate"}` | |
| - Hook avatar triggers into existing events: timer complete, todo complete, LLM tool responses | |
| - Deliverable: character idles, animates when timer runs, celebrates on completion | |
| --- | |
| ## Gamification Values | |
| | Event | XP | Coins | | |
| |---|---|---| | |
| | Complete a to-do | +10 | — | | |
| | Finish a Pomodoro | +25 | +5 | | |
| | Finish a free-flow session | +15 | +3 | | |
| | Level up | — | +20 bonus | | |
| Level thresholds: 0 / 100 / 250 / 500 / 900 / 1400 XP | |
| ### Sample Inventory Items | |
| | Item | Cost | Level Req | | |
| |---|---|---| | |
| | Red Hat | 10 coins | Lv.1 | | |
| | Blue Cape | 25 coins | Lv.2 | | |
| | Gold Crown | 50 coins | Lv.3 | | |
| | Dark Aura | 80 coins | Lv.4 | | |
| --- | |
| ## Verification | |
| 1. **Start app**: `python app.py` → opens at `localhost:7860` | |
| 2. **Timer**: Click Start Pomodoro → countdown runs in UI → on complete, XP/coins update, avatar plays celebrate animation | |
| 3. **LLM tool use**: Type "add a todo: finish the slides" → LLM calls `add_todo`, todo appears in left column | |
| 4. **Idle reminder**: Set idle threshold to 2 min for testing, wait → nudge appears in chat | |
| 5. **Inventory**: Click 🎒 → panel slides over chat → buy Red Hat → avatar updates | |
| 6. **Deploy**: Push to HF Spaces, confirm GPU Space, verify model loads and chat works | |