FitCoach Bot

Coach sportif et nutritionnel IA sur Telegram. Tracking complet, analyse de photos de repas, gamification, rappels proactifs — tout piloté par un LLM qui décide seul quels outils appeler.

Fonctionnalités

• Onboarding interactif — collecte du profil (poids, taille, objectif, etc.) en conversation naturelle
• Logging d'activités — séances (exercices/sets/reps/poids), repas (macros), hydratation, poids, humeur
• Analyse de photos de repas — estimation calories/macros par vision model, infographie visuelle auto-générée
• Étiquettes nutritionnelles — extraction par photo, ajout à la base alimentaire personnelle
• Messages vocaux — transcription automatique via Whisper
• Base alimentaire personnelle — aliments ajoutés via labels ou manuellement, réutilisés pour le logging
• Exercices en GIF — recherche ExerciseDB, démonstration animée + conseils coaching
• Gamification — points hebdomadaires, streaks (sport/nutrition/hydratation), badges, cheat meal débloqué à 80% des points
• Rappels — ponctuels ou récurrents (daily/weekly/monthly), heures silencieuses
• Mémoire coach — observations et préférences accumulées, compaction automatique
• Édition de messages — retraitement automatique si l'utilisateur édite un message

Stack technique

• Python 3.11+, python-telegram-bot
• LangChain (agent ReAct) + LiteLLM proxy (cloud LLM, STT, embeddings)
• PostgreSQL 16 (pgvector) avec JSONB pour les slots utilisateur
• asyncpg (pas d'ORM)
• APScheduler pour les jobs cron
• CairoSVG pour la génération d'infographies repas

Installation

pip install -e ".[dev]"

Configuration

Copier .env.example en .env et remplir les variables :

Variable	Description
TELEGRAM_BOT_TOKEN	Token du bot Telegram
DATABASE_URL	Connection string PostgreSQL
LITELLM_BASE_URL	URL du proxy LiteLLM (ex: http://localhost:4000)
LITELLM_API_KEY	Clé API pour le proxy LiteLLM
LLM_MODEL	Alias du modèle chat (défaut: coach-chat)
LLM_VISION_MODEL	Alias du modèle vision (défaut: coach-vision)
LLM_STT_MODEL	Alias du modèle STT (défaut: coach-stt)
EMBEDDING_MODEL	Alias du modèle embeddings (défaut: coach-embed)
MAX_COACH_MEMORY_TOKENS	Seuil de compaction de la mémoire coach (défaut: 500)
TZ	Timezone (ex: Europe/Paris)
DEV_MODE	Active les logs détaillés et l'affichage des tool calls

Tous les appels LLM (chat, vision, STT, embeddings) passent par le proxy LiteLLM. Les noms de modèles sont des alias définis dans la config LiteLLM (YAML). Changer de provider = changer la config du proxy, pas le code du bot.

Lancement

Local

python main.py

Docker

docker-compose up -d

Démarre le bot, PostgreSQL et Adminer (interface DB sur le port 8080).

Tests

pytest                # Tous les tests
pytest tests/db/      # Module spécifique
pytest --cov          # Avec couverture

Tests asynchrones via pytest-asyncio (asyncio_mode = "auto").

Architecture

Message utilisateur
  → lock par utilisateur
  → chargement slots (JSONB) + historique conversation (50 derniers messages)
  → prompt système (onboarding ou coaching)
  → agent ReAct LangChain avec 25+ outils
  → streaming de la réponse
  → compaction automatique de la mémoire si nécessaire

Mémoire à 3 niveaux :

• Slots (~400 tokens) — profil, semaine en cours, gamification, préférences, mémoire coach
• Fenêtre de conversation — 50 derniers messages
• Logs d'activité — historique complet et illimité (requêtable par les outils)

Jobs planifiés :

• Reset hebdomadaire (lundi minuit)
• Cheat meal auto (vendredi 18h)
• Vérification des rappels (toutes les 60s)
• Triggers proactifs (toutes les 30 min)

Migrations : fichiers SQL numérotés dans db/migrations/, appliqués automatiquement au démarrage.

Commandes Telegram

Commande	Description
/start	Présentation du bot
/clear	Effacer l'historique de conversation
/reset	Réinitialiser profil et données