AI Coach - Personalized Smart Marathon AI Coach | Garmin, Sports Science & Google Gemini

TELEGRAM SMART NOTIFIER

Delivered at 04:00 AM: Two-Part Reports & HD Telemetry Charts

Featuring a dual-track split: Part 1 presents telemetry metrics and lap splits; Part 2 is dedicated to Gemini AI coaching diagnosis and daily adaptive workout menus; accompanied by 3 independent high-definition sports science charts.

🤖

AI Coach Bot

bot • online

04:00 AM

📊 [Runner Training Telemetry Report - gemini-2.5-flash] Message 1/2

👤 Runner Profile: PB 3:45 | Born 1985 (Age 40)

🎯 [VDOT 42.8 Target Paces] E 5:32~6:08 | M 5:12 | T 4:50 | I 4:26 | R 4:06

🏆 [Upcoming Races (Next 90 Days Countdown)]

🚩 2026-10-25 (32 Days to go (~4 Weeks)) EVA Air Marathon | Half Marathon (21.1 km)

🩺 [Autonomic Recovery & Readiness]: HRV 58ms (Balanced) | RHR 48 bpm | Body Battery 86

📈 [ACWR Workload Ratio]: 1.14 (Sweet Spot - Optimal Adaptation Zone)

[Lap Splits (Pace | HR | Elev | Cadence | Time)]
  - L01: 6:02 | 126bpm | 0m | 174spm | 6:02
  - L02: 5:54 | 131bpm | 1m | 176spm | 5:54
  - L03: 5:50 | 133bpm | 0m | 178spm | 5:50
  ... (10 laps structured breakdown)

📲 Pushes 3 Full-Resolution Telemetry Charts:

⚡ Pace/HR Dual-Axis

📈 ACWR Workload Gauge

💓 HR 5 Zones

Click on any chart to view high-resolution image

🤖 [Gemini AI Coach Insights] Message 2/2

1. Workout Execution Evaluation: Identified as "Zone 2 Aerobic Base Run". Time in Z2 reached 86%, cadence steady at 178 spm, even pacing throughout. Outstanding execution quality.

2. Aerobic Decoupling Diagnosis: Today's decoupling rate is 3.2% (Well-Trained zone). No significant cardiac drift observed, demonstrating a solid aerobic base with effective thermoregulation at 24°C.

3. Periodization Analysis: 32 days out from EVA Air Half Marathon (Specialized Prep Phase 2). Current ACWR 1.14 is in the optimal adaptation window with no signs of overtraining.

🎯 [Today's Specific Workout Menu (Weekday Flexible Execution)]
• Core Workout: E-Pace Active Recovery Run 6.0 km (Target Pace 5:32 ~ 6:08 /km | HR Cap ≤ 140 bpm)
(💡 Execute only one session today based on your daily schedule. Avoid two-a-days!)
• 🌅 Morning Runners: 10 min dynamic warmup, deliberately slow down for the first km, refuel with protein breakfast post-run.
• 🌙 Evening Runners: Light carb snack at 16:30, adjust pace using RPE/HR to manage workday stress, full cooldown stretch post-run.

🌿 [Runner Rest Day & Supercompensation Report - gemini-2.5-flash] Message 1/2

👤 Runner Profile: PB 3:45 | Born 1985 (Age 40)

🎯 [VDOT 42.8 Target Paces] E 5:32~6:08 | M 5:12 | T 4:50 | I 4:26 | R 4:06

🏆 [Upcoming Races]: 🚩 2026-10-25 EVA Air Half Marathon (32 Days to go)

🩺 [Autonomic Recovery]: HRV 62ms (Balanced) | RHR 46 bpm | Body Battery 92

📈 [ACWR Workload Ratio]: 0.98 (Optimal Absorption Sweet Spot)

📊 [Past 7 Activities Micro-Cycle]:
• Total Mileage: 42.5 km | Total Workload: 482
• Runs: 4 | Cross-training: Strength 1, Swim 1
• 💡 Status: No new running activity in past 26 hours. Scheduled supercompensation rest day today!

🤖 [Gemini Recovery & Supercompensation Advice] Message 2/2

1. Load & Fatigue Diagnosis: Accumulated 42.5 km in 7 days, HRV rebounded to 62ms, cardiovascular fatigue fully dissipated. Perfect timing for supercompensation.

2. Active Recovery Prescription: 15 min foam rolling (calves and quads) + 20 min core isometric holds. No strenuous cardio needed.

3. Nutrition Focus: 35ml water per kg body weight, high-quality protein (soy milk, chicken, eggs) to repair muscle fibers.

🎯 [Today's Rest Guidance & Next Workout Preview (Rest Day)]
• Next Workout: 8km Progressive Run (E-Pace warming up to M-Pace in final 2km).

CORE HIGHLIGHTS

Deep Sports Science & AI Diagnostics

Far beyond basic GPS distance tracking: Built on exercise physiology models including Jack Daniels' VDOT, ACWR, and Aerobic Decoupling %.

Jack Daniels' VDOT Paces

Real-time derivation from your personal Marathon PB into E, M, T, I, and R training paces based on scientific oxygen cost equations.

ACWR Workload Ratio

7-day acute fatigue vs 28-day chronic fitness workload ratio, categorized into 4 tiers to keep your training in the optimal Sweet Spot.

Aerobic Decoupling (Decoupling %)

Joe Friel's Efficiency Factor (EF) model split into first & second halves, diagnosing cardiac drift and aerobic base solidity.

Race Countdown & Daily Menu

Auto-syncs Garmin calendar races (next 90 days, de-duplicated), periodizes training phases, and dynamically adapts between weekday and weekend time slots.

Gemini Multi-Model Failover

Dynamically scans Gemini 2.5 / 2.0 Flash models with automated millisecond failover upon peak 503 UNAVAILABLE errors. 100% push reliability.

Open-Meteo Micro-Weather

Fetches historical temperature, relative humidity, and heat index at the exact GPS coordinates and start time to factor in thermal stress.

Advanced Running Dynamics

Running Power (W), Cadence (spm), Stride Length, Vertical Oscillation, Stride Ratio, and Ground Contact Time (GCT) running economy analysis.

HRV & Recovery Degradation

Integrates overnight HRV, Resting Heart Rate, and Body Battery; gracefully skips missing data without interrupting the workflow.

3 Independent HD Charts

No crammed multi-panel images! Matplotlib outputs standalone high-res images for pace/HR trend, ACWR gauge, and HR zones donut.

INTERACTIVE SCIENCE LAB

Interactive Running Fitness Calculators

Ported directly from our project's Python sports science algorithms. Input your race time to test Jack Daniels' VDOT formula live!

Jack Daniels' VDOT Calculator

Daniels' Running Formula

Live Calc

Marathon Personal Best (PB) — e.g. 3:45 or 3:30:00

42.195 km

Goals:

Calculated VDOT Score 42.8

E Pace (Easy / LSD)

Aerobic Base & Recovery (~65-74%)

5:32~6:08

M Pace (Marathon)

Race Cruise Pace (~80%)

5:12

T Pace (Threshold)

Lactate Clearance (~88%)

4:50

I Pace (Interval)

VO2 Max Stimulation (~98%)

4:26

R Pace (Repetition)

Neuromuscular Speed (~108%)

4:06

Telegram Single-Line Preview:

🎯 【VDOT 42.8 Target Paces】E 5:32~6:08 | M 5:12 | T 4:50 | I 4:26 | R 4:06

Aerobic Decoupling %

Joe Friel Efficiency Factor (EF) Model

Drift Lab

$$\text{Decoupling (\%)} = \frac{\text{EF}_1 - \text{EF}_2}{\text{EF}_1} \times 100\%$$

EF (Efficiency Factor) = Speed (m/min) or Power (W) ÷ Avg Heart Rate (bpm)

First Half (First 50%)

Speed (m/min) 171.4 m/min ≈ 5:50/km

Avg Heart Rate (bpm)

Second Half (Last 50%)

Speed (m/min) 171.4 m/min ≈ 5:50/km

Avg Heart Rate (bpm)

Decoupling Rate 2.94%

Elite Aerobic Base

Cardiac drift is below 3.0%, indicating an exceptionally solid aerobic foundation with minimal compensatory cardiovascular strain over time.

ARCHITECTURE & TELEMETRY

End-to-End Automated System Architecture

An event- and schedule-driven modern Python architecture, decoupling data ingestion, exercise physiology algorithms, AI prompt engineering, and instant messaging push.

Click to zoom into full 16:9 HD panoramic view

Lap Pace & HR Dual-Axis Trend

Left Y-axis features inverted time-based pace, right Y-axis displays HR, with a purple vertical halfway decoupling split.

ACWR Workload Ratio Gauge

Left side compares 7-day acute vs 28-day chronic load; right side features large status badge and 4-tier injury-prevention gauge.

Heart Rate 5 Zones Distribution

Sporty donut chart displays total workout duration with a clean vertical breakdown of time-in-zone and percentages.

ZERO-COST DEPLOYMENT

Only 3 Steps, Ready in 5 Minutes

No cloud server (VPS) required, no software installation! Simply fork on GitHub and run free forever.

1

Fork the Repository

Navigate to our GitHub repo and click the Fork button in the top right to copy the codebase into your personal account.

Fork This Project

2

Configure 5 Secrets

In your repo, go to Settings → Secrets and variables → Actions and input these 5 keys:

GARMIN_EMAILGarmin Account

GARMIN_PWDGarmin Password

TG_TOKENBotFather Token

TG_CHAT_IDTelegram Chat ID

GEMINI_API_KEYGoogle AI Studio

Protected by GitHub Bank-Grade Encryption

3

Enable GitHub Actions

Click the Actions tab in your repo and enable workflows. It will run automatically every morning, or you can trigger Run workflow manually anytime!

Includes Cleanup workflow to clear run history with one click!

Optional: Personalized Runner Settings (GitHub Secrets)

Customize RUNNER_NAME, RUNNER_PB (e.g. 3:45), RUNNER_BIRTH_YEAR, and ZONE2_MAX_HR for custom VDOT target zones.

View Documentation →

FREQUENTLY ASKED QUESTIONS

Frequently Asked Questions

Everything you need to know about security, costs, APIs, and schedule timing.

Is it really 100% free with no hidden fees?

Yes, 100% free! GitHub Actions provides 2,000 free CI/CD minutes per month (this script takes only 30-50 seconds daily, and is unlimited for public repos); Google Gemini API offers a generous free tier (hundreds of daily requests); Open-Meteo weather API is completely open-source without requiring an API key.

Is my Garmin account login secure?

Extremely secure. All credentials are stored inside your private GitHub Repository Secrets, encrypted via asymmetric public-key cryptography on GitHub's secure infrastructure. The code is 100% open-source Python, connecting directly from the GitHub runner to Garmin Connect with zero third-party proxies.

Will I still receive a report if I rest today?

Yes! The system features an intelligent 26-hour recency detection window. If no new workout has been logged, it automatically switches to the Rest Day & Supercompensation Report, analyzing your rolling 7-workout cumulative volume and acute workload to prescribe foam rolling, hydration recovery, and a preview of your next session.

Can I customize the daily delivery time?

Absolutely. Simply edit .github/workflows/daily_task.yml in your repository and adjust the cron expression (default is UTC 19:55, which delivers around 03:55~04:00 AM local time for early risers to review their plan for the day; note GitHub Actions cron operates in UTC).