docs/PLAN.md

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