Trainner AI 🚀

Pipeline cuantitativo y de automatización para la extracción e ingesta de métricas biométricas mediante IA y análisis de bases de datos.

Trainner AI es un ecosistema avanzado, inspirado en arquitecturas de datos institucionales, diseñado para la ingesta, limpieza, modelización cuantitativa y explotación algorítmica de métricas de salud y rendimiento deportivo.

El proyecto integra desde la extracción robusta de datos crudos vía APIs de terceros (Google Health Connect) hasta la exposición de microservicios (MCP) que actúan como oráculos para Modelos de Lenguaje Grandes (LLMs).

🧠 Arquitectura y Lógica de Negocio

La filosofía detrás de Trainner AI emula los pipelines de gestión de riesgos y pricing del sector financiero, aplicando modelización cuantitativa a la fisiología humana:

• Data Engineering (ETL): Un pipeline contenerizado en Docker extrae telemetría desde Google Drive (API), normaliza estructuras complejas (frecuencia cardíaca intradiaria, GPS, potencia, variabilidad cardíaca) y mapea los datos en una base de datos relacional (SQLite) optimizada para lecturas de series temporales.

• Modelización Cuantitativa (Quants):

  • Implementación del modelo Banister / Coggan (ATL/CTL/TSB) mediante medias móviles ponderadas exponencialmente (EWMA) para calcular la Carga Aguda (fatiga), Carga Crónica (estado de forma) y Frescura.

  • Evaluación algorítmica multidimensional del Readiness (semáforo de riesgo de sobreentrenamiento). Se evalúan variables como la deuda de sueño, desviación del HRV y frecuencia cardíaca en reposo.

• Inferencia LLM y FastMCP (Microservicios): Exposición de la capa de datos mediante el protocolo de contexto de modelos (MCP). Esto permite que sistemas de Inteligencia Artificial (Gemini, Claude) realicen consultas al vuelo, crucen dominios (e ej. impacto de la calidad del sueño en la eficiencia aeróbica) y generen adaptaciones dinámicas en los planes de entrenamiento.

Related MCP server: Intervals.icu MCP Server

🛠️ Stack Tecnológico Transferible

• Lenguajes y Frameworks: Python 3.12, FastMCP, SQLite3.

• Integraciones / APIs: Google Cloud (Drive API, OAuth 2.0), Google Health Connect.

• Infraestructura y Despliegue: Docker, Docker Compose, Automatización vía Cron.

• Algoritmia: Modelos predictivos EWMA (Exponentially Weighted Moving Average), análisis de series temporales.

🚀 Despliegue Rápido (Quickstart)

⚠️ Privacidad First: Este repositorio no contiene datos personales ni bases de datos de salud de los usuarios. Todo el procesamiento se realiza localmente.

1. Clonar e inicializar variables de entorno

git clone https://github.com/tu-usuario/trainner-ai.git
cd trainner-ai
cp .env.example .env
cp docker/.env.example docker/.env

(Edita los ficheros .env añadiendo tus API Keys de Google AI y tu File ID de Drive).

2. Levantar el motor de extracción (ETL)

El contenedor Docker se autenticará con Google Cloud, descargará la telemetría y poblará la base de datos docker/data/health_data.db.

cd docker
docker compose run --rm health-extractor

3. Generar informes diarios y ejecutar el servidor MCP

Una vez la base de datos esté nutrida, genera la analítica:

python3 reports/generate_reports.py --backfill --days 30

Arranca la capa de microservicios para permitir la ingesta a tu LLM de confianza:

python3 trainner_mcp/server.py

📊 Dominios de Análisis

El sistema particiona el riesgo y el rendimiento en 5 dominios críticos de datos:

1. Sleep (Descanso): Eficiencia, arquitectura del sueño, despertares.

2. Metrics (Biometría diaria): HRV, VO2 Max, ritmo cardíaco basal.

3. Exercise (Rendimiento): Curvas de potencia, zonas de FC, GPS.

4. Nutrition (Ingesta): Balance calórico y macronutrientes.

5. Training Load (Riesgo): Modelización de cargas crónicas y agudas.

Desarrollado con un enfoque estricto en la escalabilidad, la integración y la eficiencia operativa.