PLAN.md

PLAN.md — MVP implementation tracker

This is the working tracker for the hackathon build. PROJECT.md explains the product and architecture; DECISIONS.md records decisions. This file answers: where are we, what is done, what is next, and what decisions are blocking implementation.

---

Current status

Current phase: Phase 7 — Persistence / Phase 8 — Submission readiness

Current task: prove the local daily loop end to end, then configure/deploy the optional Hugging Face Dataset persistence.

Next decision gate: decide the actual private Dataset repo id and Space secret setup.

Training-rule source: hypertrophy_app_training_rules.md.

Local app: running at http://127.0.0.1:7860 when started with:

scripts/reset_server.sh

Test command:

.venv/bin/python -m unittest discover -s tests

---

Phase 0 — Project alignment

Goal: lock the MVP direction and hackathon strategy.

Status: Done

• Read AGENTS.md, PROJECT.md, and DECISIONS.md.
• Decide that the MVP includes text-first check-in extraction.
• Decide that the parser may use a small model, but the engine remains deterministic.
• Decide that the engine receives only structured data.
• Decide storage path: interface first, local JSON first, Hugging Face Dataset later.
• Add hackathon optimization goals to PROJECT.md.

---

Phase 1 — Real MVP UI shell

Goal: make the first screen match the real daily loop before real parser/engine logic exists.

Status: Done for first scaffold

• Create runnable Gradio app.
• Convert app to gr.Blocks.
• Add Today tab.
• Add natural-language check-in box as the main input.
• Add editable structured fields for time, energy, sleep, soreness/constraints, pain/injury, and mood/stress.
• Show hardcoded session preview.

Not done yet:

• Replace manual structured fields with parser-filled fields.
• Replace hardcoded preview with engine output.

---

Phase 2 — Core schema

Goal: define the shared data contract before parser, engine, logging, and persistence.

Status: Done for MVP schema

Done:

• Decide schema implementation: Pydantic.
• Create training_coach/ package.
• Add CheckIn.
• Add PainIssue.
• Add ParsedCheckIn.
• Add ContextSignal.
• Add Exercise.
• Add anatomical Muscle enum.
• Add PrescribedSet.
• Add PlannedExercise.
• Add SessionPlan.
• Add LoggedSet.
• Add LoggedExercise.
• Add SessionLog.
• Add model tests.

Current models:

• CheckIn
• PainIssue
• ParsedCheckIn
• ContextSignal
• Exercise
• Muscle
• PrescribedSet
• PlannedExercise
• SessionPlan
• LoggedSet
• LoggedExercise
• SessionLog

Next tasks:

• Decide and add LoggedSet.
• Decide and add SessionLog.

Known future schema additions:

• Exercise equipment, deferred until equipment availability/substitution matters.
• Supersets, drop sets, rest-pause, and other advanced set types, deferred until the classic-set MVP works.

---

Phase 3 — Small model parser

Goal: convert natural-language check-ins into validated CheckIn objects.

Status: Done for MVP parser

Decision status:

• Choose local parser model: Ollama qwen3:1.7B.
• Replace the Hugging Face Spaces Transformers parser with a GGUF llama.cpp path.

Acceptance rule:

• Local development/evaluation now prefers Ollama because quantized llama.cpp/Metal inference is much faster on the Mac than local Transformers CPU/disk-offload.
• Current local parser default: qwen3:1.7B, chosen for MVP parser speed.

Tasks:

• Add parser output schema with missing fields, structured follow-up items, display follow-up questions, and context signals.
• Create parser module.
• Define strict JSON prompt/output format.
• Fix parser keys and enum values through schema validation.
• Validate model JSON into ParsedCheckIn.
• Add optional local Transformers runtime wrapper.
• Add parser backend selector for local Ollama vs Space llama.cpp runtime.
• Add Ollama local runtime wrapper with JSON-schema structured outputs.
• Add GGUF llama.cpp runtime wrapper for Hugging Face Spaces CPU deployment.
• Run the model on one fixture and parse raw text into ParsedCheckIn.
• Run the model against all acceptance fixtures.
• Remove overfit fixture-shaped prompt examples.
• Replace canned keyword follow-up triggers with LLM-proposed structured follow_up_items.
• Add deterministic cleanup for duplicate, already-answered, or unsupported follow-up questions.
• Add deterministic parser cleanup for obvious missing muscle mappings.
• Remove stale/repetitive sleep follow-up questions when sleep hours and quality are already known.
• Add parser tests/fixtures under tests/fixtures/:
  • short time + poor sleep + low energy
  • soreness/pain constraint
  • ambiguous check-in requiring unsure or notes
  • adjacent context signal such as "yesterday I ran a 10k"
• high energy + long session
• Wire parser output into editable UI fields.

Current parser evaluation result:

• Qwen/Qwen2.5-1.5B-Instruct passed 1/5 acceptance fixtures on the first full local run.
• Main failures: missed explicit "no pain", over-asked for sleep hours, produced markdown code fences for some JSON, missed the 10k context signal, and added unrelated pain notes.
• Local Transformers Qwen/Qwen3-4B was too slow on Mac because it offloaded to disk.
• Ollama qwen3:8b completed the same fixture run much faster and passed 2/5 under the current strict exact-match evaluator.
• Ollama qwen3:8b produced valid schema-shaped JSON, but needs tighter fixed context labels and a less brittle evaluator for free-text notes/follow-up wording.
• Context signal labels are now fixed enum values, and the evaluator now treats free-text notes/follow-up wording semantically while keeping labels/enums/numbers strict.
• Ollama qwen3:4b is installed and passed 2/5 acceptance fixtures. Main failures: missed mapping "tricep" to triceps_brachii, omitted follow-up questions for the 10k context signal, and failed one semantically acceptable ambiguous-pain follow-up due to evaluator wording.
• We no longer treat 5/5 one-shot fixture passing as the main goal. The product behavior is now multi-round: parse what is clear, ask structured follow-up questions, then build a session once the structured check-in is good enough.
• The Today UI now uses a chat-style check-in conversation and updates editable fields after each message.
• Parser output is now wired into the editable Today UI fields.

---

Phase 4 — Engine slice

Goal: build deterministic session plans from structured check-ins and history.

Status: Done for MVP spine

Blocked by: your training rules.

Important rule: no training logic gets invented by the agent. When engine work needs a rule, it must come from you and be recorded in DECISIONS.md.

Tasks:

• Decide MVP split and exercise list.
• Decide exercise order.
• Encode fixed 4-day template in training_coach.engine.
• Preserve per-exercise rest targets in PlannedExercise.
• Add unit tests for the fixed 4-day template.
• Decide how to select today's training day.
• Decide minimum completed-session fields for MVP logging.
• Implement next-day state from completed session logs.
• Add local JSON history storage.
• Decide first readiness/time adaptation rules.
• Implement readiness set/RIR modifiers.
• Implement pain/injury exercise filtering using muscle tags.
• Implement time compression from time_available_minutes.
• Decide double-progression MVP load increment.
• Decide double-progression rep range rule.
• Implement double progression: add reps before load, then +1 kg and reset reps.
• Implement pure Python build_session_for_day(...) entry point.
• Add unit tests for every encoded MVP rule.

Current fixed template:

• Day 1: Pullover, row, incline bench, incline fly, goblet squat.
• Day 2: Skullcrusher, lateral raise, triceps extension, cable lateral raise, barbell curl, hip thrust, standing calf raise.
• Day 3: Incline bench, incline fly, row, pullover, Romanian deadlift.
• Day 4: EZ-bar curl, lateral raise, hammer curl, cable lateral raise, triceps extension, goblet squat, standing calf raise.

MVP simplification:

• All exercise rests are normalized to 1 minute for now.
• Double progression uses fixed +1 kg load jumps for now.
• Single-rep template prescriptions become 5-rep ranges with the original rep target as the middle value.
• Pain filtering removes affected exercises instead of substituting replacements.
• Time compression cuts later/lower-priority sets first.
• Readiness modifies set count and target RIR.

---

Phase 5 — End-to-end daily loop

Goal: check-in text produces a real deterministic session plan.

Status: Done for local MVP

Tasks:

• Parser extracts CheckIn.
• Parsed fields are visible/editable.
• Engine builds SessionPlan.
• UI renders session clearly enough to train from.
• Keep explanation factual and based on engine output.

---

Phase 6 — Logging

Goal: record what actually happened in training so the next session and double progression have real history.

Status: Done for local MVP

Tasks:

• Decide MVP completed-session shape for day tracking and progression.
• Add performed-set logging UI.
• Save actual reps/loads.
• Save the completed training day number.
• Attach logs to the planned session/check-in. Deferred by the minimal-history MVP compromise.
• Derive next suggested day from the last completed day.
• Add tests for log serialization.

---

Phase 7 — Persistence

Goal: make training history survive restarts and deployments.

Status: Local persistence done; durable deployment persistence next

Tasks:

• Create storage interface.
• Add local JSON storage.
• Add Hugging Face Dataset storage.
• Load history on startup.
• Append completed session logs.
• Prove restart survival.

---

Phase 8 — Submission readiness

Goal: make the app demoable and optimized for the hackathon.

Status: Not started

Tasks:

• Deploy to Hugging Face Space.
• Add proof-of-use view from real logs.
• Write field notes.
• Record short demo video.
• Prepare submission copy.

---

Phase 9 — Stretch

Goal: only after the MVP spine works.

Status: Not started

• Coach-style narration.
• Progress charts.
• Better parser model.
• Tiny Titan route.
• Research-reader.
• Fine-tuning.
• llama.cpp route.
• Custom UI polish.

---

Immediate next step

Prove the local spine with one manual end-to-end training loop, then implement durable Hugging Face Dataset persistence so the deployed Space does not lose history.

Proposed starting point:

messy check-in + local history -> adjusted session -> completed log

Use the app with a few intentionally messy check-ins and inspect whether the plan notes explain every modification.