Py.rsonal-Trainer 🏃‍♂️🐍

Py.rsonal-Trainer (Python Personal Trainer) is a modular Python application to track, analyze and optimize endurance training — running, trail, cycling, or ultra-distance — with integrated load analysis, nutrition guidance, and performance testing tools.

⚠️ This project is currently under active development.
Release planning and delivery dates are tracked via GitHub Milestones.

---

📌 Overview

Py.rsonal-Trainer is designed for athletes and coaches who want to go beyond basic GPS stats, implementing scientifically grounded metrics like:

• Acute & Chronic Training Loads (ATL / CTL)
• Weekly ramp rate and ACWR (Acute:Chronic Workload Ratio)
• Training Stress Balance (TSB)
• Nutrition guidance and gap analysis
• Integration of sports test results (VMA, FTP, LTHR) for training zones

It uses a JSON database as the central data store, with:

• Modular architecture (models, data, analytics, nutrition, cli, ui)
• Flexible import/export
• CLI-based and future GUI-based interaction

---

🛠 Current Status

Stage: 🚧 In Construction
I am currently at First Release (Alpha) — building the core data handling and basic load metrics.
Full roadmap is defined with versioned milestones: from Alpha → v1.0 (UI release) (GitHub Milestones).

---

📂 Repository Structure

Todo

---

🚀 Installation

git clone https://github.com/SKOHscripts/Py.rsonal-Trainer.git
cd Py.rsonal-Trainer
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

---

✨ Features

✅ Available

🚧 In development

• YAML schema for athlete & activities
• Data loading/saving with validation
• Daily load calculation (sRPE)
• Weekly summaries
• ATL/CTL (Rolling Average 7/28 days)
• ACWR (RA + EWMA)
• Training Stress Balance (TSB)
• CLI "summary" and "forecast"
• Nutrition events schema + CRUD
• Import test results (VMA, FTP, LTHR)
• Training zones derivation

📅 Planned (See GitHub Milestones)

• Banister impulse–response model
• Multi-metric load plugins (TRIMP, distance, elevation)
• Data anomaly detection & alerts
• Intelligent CLI Q&A
• Complete GUI/TUI (v1.0)

---

📋 TODO & Roadmap

All feature delivery and timing are tracked in GitHub Milestones:

• 0.1.0 First Release (Alpha) → Data foundations, minimal CLI, basic loads.
• 0.2.0 → ATL/CTL (RA), ACWR v1.
• 0.3.0 → EWMA models, TSB.
• 0.4.0 → CLI essentials, reporting & what-if.
• 0.5.0 → Nutrition schema, basic guidance, gap reports.
• 0.6.0 → Test ingestion, zones, intensity-weighted load.
• 0.7.0 → Data QA, anomaly detection, performance benchmarks.
• 0.8.0 → Intelligent CLI queries & alerts.
• 0.9.0 → Banister model & alternative load metrics.
• v1.0.0 → Full release with UI.

---

🔍 Example Usage

Todo

---

📜 Scientific References

This project’s metrics are based on:

• sRPE Load: Foster et al., "Monitoring Training in Athletes"

• ATL/CTL/TSB: Performance Manager Model

• ACWR: Hulin et al., "The Acute:Chronic Workload Ratio"

• Banister Model: Impulse–Response performance modeling

• Nutrition Guidance: Consensus recommendations for endurance sports fueling & hydration

• More references will be listed here while developing. References will also be provided in the relevant modules.

---

🤝 Contributing

We welcome contributions:

1. Check open issues & milestones.
2. Fork and create feature branches.
3. Add unit tests for new code.
4. Submit a Pull Request with a clear description.

---

🗺 License

This project is released under the .