TrailCoach — Coach IA trail running

01

Ce qu'il fait, concrètement.

Pas un wrapper ChatGPT autour de Garmin. Un vrai pipeline d'entraînement avec mémoire long terme et garde-fous physiologiques.

01

Onboarding qui creuse

Conversation guidée par Claude Opus 4.7 en extended thinking. Extrait ton profil, ton objectif principal, tes contraintes de vie et ton niveau réel. Pas de form rigide à remplir.

02

Plan périodisé sur ton objectif

Découpage automatique en phases BASE, BUILD, SPECIFIC, TAPER, RACE selon ta cible, du 10 km route à l'ultra trail 100+. Polarisation 80/20, volume et D+ calibrés sur ton historique.

03

Séances structurées dans ta Garmin

Push direct des workouts dans Garmin Connect : warmup, intervalles, cibles FC ou zone, récup, cooldown. Tu lances la séance, ta montre te guide, le coach récupère l'activité ensuite.

04

Debrief auto post-séance

Dès qu'une nouvelle activité est détectée via le poll horaire Garmin, TrailCoach compare prévu et réalisé, calcule un score plan-vs-actual et te demande ton RPE pour formuler un debrief court.

05

Proactif sur les signaux santé

HRV qui chute 3 jours, Body Battery bas, sommeil dégradé, ACWR au-dessus de 1.5, séance ratée, pattern PPG zappée 3 semaines. Le coach intervient le matin avec une recommandation chiffrée.

06

Adapte le plan aux imprévus

Tu lui dis "je pars 5 jours sans courir" ou "j'ai un startup weekend vendredi", il décale, supprime ou allège les séances de la fenêtre concernée. Re-push Garmin automatique.

02

Sur quoi il se base.

Les recommandations ne sortent pas du chapeau. Le coach raisonne sur des données fraîches plus une base de connaissance scientifique.

Données

Activités Garmin 12 moisdistance, durée, FC, zones, D+, allure, dérive cardiaque. Vue saisonnière complète : pics, périodes off, blessures.
Métriques quotidiennes 30 jourssommeil, HRV nuit, Body Battery, stress, training status (Garmin n'expose que ~30j en API).
Profil athlèteFC max, FC repos, zones perso, PB sur toutes les distances, historique blessures, contexte de vie.
Charge calculée 180jCTL 42j, ATL 7j, TSB, ACWR. Recompute tous les matins.
Plan en coursphase actuelle, cibles volume et D+, séances pushées vs réalisées.

Connaissance

Daniels Running Formulazones VDOT, allures cibles par filière.
Stephen Seilerpolarisation 80/20, hiérarchie endurance / qualité.
Jason KoopTraining Essentials for Ultrarunning. Spécificité trail long, D+, terrain.
Steve MagnessScience of Running. Adaptation neuromusculaire, taper.
RAG embeddings~200 chunks scientifiques indexés (text-embedding-3-small), requêtés à la volée.

Règles dures

HRV chute > 10% / 3jséance allégée ou repos imposé.
ACWR > 1.5semaine de décharge déclenchée.
Missed session ×2check-in proactif obligatoire.
Anti-hallucinationle coach DOIT consulter le plan réel avant de dire "demain tu fais X".
Repos = entraînementpas une option à zapper.

03

Stack technique.

Tout en Python 3.13 async, déployé sur un VPS Hostinger sous Debian 13.

LLM

Claude Opus 4.7 (intake)
Claude Sonnet 4.6 (conversation)

Boucle tool_use multi-itérations, prompt caching agressif, une vingtaine de tools exposés (get_plan, push_garmin, replace_workout, query_kb, cancel_workouts_in_range).

Intégrations

Garmin Connect
Discord

Login MFA, sync 365j d'activités plus 30j de daily metrics, push de workouts structurés, schedule sur date donnée. DM Discord côté athlète, pas de UI à installer.

Persistance

Postgres + pgvector
SQLAlchemy 2.0 async

Migrations Alembic, partial unique indexes, JSONB pour les structures de workout. Embeddings de la KB stockés en pgvector pour la recherche sémantique.

Scheduler

APScheduler
3 jobs cron

Brief matin 6h30, check-in soir 21h, sync horaire à xx:15. Anti-spam par dedup_key et cap 4 messages proactifs / jour hors debriefs factuels.

Web

FastAPI + nginx
Vanilla JS dashboard

API read-only avec auth Bearer magic-link expirant 24h. Dashboard minimal pour visualiser plan, charge, activités. SSL Let's Encrypt.

Observabilité

Logs journalctl + DB audit

Chaque trigger proactif loggé avec son dedup_key, son context et le message envoyé. Replay possible. 53 tests pytest sur la logique métier.

04

Une journée type.

Quatre rendez-vous fixes par jour, plus la conversation libre.

06:30

Brief matin
Sync Garmin du sommeil et de la HRV de la nuit. Recalcul CTL, ATL, ACWR. Si signal critique (HRV chute, ACWR > 1.5, J-3 d'une course objectif), DM proactif avec recommandation.
XX:15

Poll Garmin horaire
À chaque heure pile + 15 min, sync des activités du jour. Si une nouvelle sortie est détectée sans WorkoutExecution lié, debrief auto en DM : FC moy, zones, comparaison à la séance prévue.
Anytime

Conversation libre
Tu DM le bot avec une question, un ressenti, une contrainte. Le coach lit l'historique récent plus ton plan plus ta charge, raisonne avec ses tools, et peut modifier le plan en direct si besoin.
21:00

Check-in soir
Vérif que la séance du jour a été faite. Si non, ping. Pattern detection : PPG zappée 3 semaines de suite, inactivité 5j et plus, séance longue sautée régulièrement.

05

Statut du projet.

Projet perso assumé. MVP en prod, deux athlètes en test.

MVP en prod

Bot Discord Trailcoach#3287 connecté, scheduler actif, sync Garmin OK, push workouts OK. Deux athlètes en test, Julia et moi.

Pas de signup public

Pas de SaaS, pas de marketing. L'onboarding se fait via DM Discord après ajout manuel du discord_user_id en DB. Si tu veux tester, écris-moi.

Roadmap court terme

Voice memo Discord vers Whisper, dashboard mobile, intégration Strava en fallback, race day pacing live, post-mortem détaillé de course.