Project Overview

Challenges

What challenges or difficulties have I faced with this project?

Workout apps miss context from notes, scaling, and lifestyle data.

Solution

What steps did I take to deal with a complication?

LLM-powered agents parse notes and personalize recommendations.

Outcome

How did my challenges eventually come to a resolution?

Smarter tracking, adaptive plans, and coach-like feedback.

Problem

Most fitness apps record only top-line metrics. For many athletes, especially in CrossFit, the nuance lives in free-text notes: scaling choices (e.g., push-ups on the knee vs. strict), band colors for pull-ups (red/green/blue), substitutions due to injury, combinations of exercises that change the difficulty, and daily readiness signals (sleep, nutrition).

✓Numbers alone miss progression (e.g., blue → green → red band pull-ups).
✓Readiness varies with sleep, HRV, soreness, and macros.
✓Manual parsing is tedious; insights rarely make it back into programming.

Solution Overview

Designed an agentic ML pipeline that:

Parses unstructured workout notes using an LLM-first approach.
Generates structured exercise-level stats (e.g., deadlift load/reps, pull-up variants, substitutions).
Links related movements (e.g., squats → posterior-chain assistance).
Delivers personalized recommendations for target weights, pacing, scaling, and recovery.
Learns continuously by reconciling recommendations with actual workout performance.

‍

Architecture

High-Level Flow

Ingest raw notes + metrics + device signals (Apple/Google, Garmin, Oura).
Planner analyzes history schema; spins up parsing executors.
Executors produce structured events per exercise and linked movements.
Store raw + structured + vectors; compute features & trends.
Recommendation agent outputs today’s targets & scales.
Post-workout, reconcile recommendations vs. actual; learn.

‍

Key Components

1. Workout History Parsing Agent

The agent avoids brittle custom parsers. The planner examines the historical structure and composes specialized LLM executors that extract loads/reps, variants (knee push-ups, band colors), substitutions, and readiness. It also maps linked exercises (e.g., heavy squats linked to posterior-chain assistance).

You are a sports data extractor. Given raw notes, output JSON with:
- exercises[]: { name, variant?, sets[], reps[], load[], linked_exercises[], insights[] }
- readiness: { sleep_h, hrv_state, nutrition_summary }
- flags[]: substitutions, injuries, scaling

Follow the schema strictly.

‍

2. Personal Recommendation Agent

Inputs

User details (age, gender, demography, injuries, experience).
History-derived exercise stats & trends.
Today’s workout intent (lift/engine mix).
Readiness signals (sleep, HRV, soreness) and macros.

Outputs

Target loads (%, RPE/RIR), pacing ranges, scale choices.
Technique cues and linked accessory work.
Recovery suggestions (mobility, breath work).
Confidence + what-if alternatives (e.g., lack of equipment).

Policy sketch (hybrid rules + LLM)

If sleep < 6.5h OR HRV low: cap intensity at ~80% 1RM, prefer volume @ RIR 2.
If prior session high fatigue + same muscle group today: reduce load by 5–10%.
If band pull-ups @ green ≥ 5x5 for 2+ weeks: test red band singles.
Use user's goal horizon to set weekly progression (micro 2.5–5 lb).

‍

Future Enhancements

Wearable Integrations: Apple Health (sleep, HRV, steps), Garmin (VO₂ max, load), Oura/Whoop (readiness, strain), MyFitnessPal (macros).
Advanced Personalization: Goal-based progression planning (e.g., first unassisted pull-up, marathon prep).
Coach Dashboard: Aggregated athlete insights, readiness alerts, and auto-programming suggestions.

‍

Workout Copilot