# AI Cycling Coach - Terminal Edition šŸš“ā€ā™‚ļø An intelligent cycling training coach with a sleek Terminal User Interface (TUI) that creates personalized training plans and analyzes your workouts using AI, with seamless Garmin Connect integration. ## āœØ Features - **šŸ§  AI-Powered Plan Generation**: Create personalized 4-week training plans based on your goals and constraints - **šŸ“Š Automatic Workout Analysis**: Get detailed AI feedback on your completed rides with terminal-based visualizations - **āŒš Garmin Connect Integration**: Sync activities automatically from your Garmin device - **šŸ”„ Plan Evolution**: Training plans adapt based on your actual performance - **šŸ—ŗļø GPX Route Management**: Upload and visualize your favorite cycling routes with ASCII maps - **šŸ“ˆ Progress Tracking**: Monitor your training progress with terminal charts and metrics - **šŸ’» Pure Terminal Interface**: Beautiful, responsive TUI that works entirely in your terminal - **šŸ—ƒļø SQLite Database**: Lightweight, portable database that travels with your data - **šŸš€ No Docker Required**: Simple installation and native performance ## šŸ Quick Start ### Option 1: Automated Installation (Recommended) ```bash git clone https://github.com/ai-cycling-coach/ai-cycling-coach.git cd ai-cycling-coach ./install.sh ``` ### Option 2: Manual Installation ```bash # Clone and setup git clone https://github.com/ai-cycling-coach/ai-cycling-coach.git cd ai-cycling-coach # Create virtual environment python3 -m venv venv source venv/bin/activate # Install pip install -e . # Initialize database make init-db # Run the application cycling-coach ``` ## āš™ļø Configuration Edit the `.env` file with your settings: ```bash # Database Configuration (SQLite) DATABASE_URL=sqlite+aiosqlite:///data/cycling_coach.db # File Storage GPX_STORAGE_PATH=data/gpx # AI Service Configuration OPENROUTER_API_KEY=your_openrouter_api_key_here AI_MODEL=deepseek/deepseek-r1 # Garmin Connect Credentials GARMIN_USERNAME=your_garmin_email@example.com GARMIN_PASSWORD=your_secure_password # Optional: Logging Configuration LOG_LEVEL=INFO ``` ## šŸŽ® Usage ### Terminal Interface Start the application with: ```bash cycling-coach # or ai-cycling-coach # or python main.py ``` Navigate through the interface using: 1. **šŸ  Dashboard**: View recent workouts, weekly stats, and sync status 2. **šŸ“‹ Plans**: Generate new training plans or manage existing ones 3. **šŸ’Ŗ Workouts**: Sync from Garmin, view detailed analysis, and approve AI suggestions 4. **šŸ“ Rules**: Define custom training constraints and preferences 5. **šŸ—ŗļø Routes**: Upload GPX files and view ASCII route visualizations ### Key Features #### šŸ§  AI-Powered Analysis - Detailed workout feedback with actionable insights - Performance trend analysis - Training load recommendations - Recovery suggestions #### šŸ—ŗļø ASCII Route Visualization ``` Route Map: Sā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—E ā— ā— ā— Morning Loop - 15.2km ā— ā— ā— ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā—ā— Elevation Profile (50m - 180m): ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆ ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆ ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆ ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆ ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆ ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆ ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆ ``` #### šŸ“Š Terminal-Based Charts - Heart rate zones - Power distribution - Training load trends - Weekly volume tracking ## šŸ—ļø Architecture ### šŸ”§ Technology Stack - **Backend**: Python with SQLAlchemy + SQLite - **TUI Framework**: Textual (Rich terminal interface) - **AI Integration**: OpenRouter API (Deepseek R1, Claude, GPT) - **Garmin Integration**: garth library - **Database**: SQLite with async support ### šŸ“ Project Structure ``` ai-cycling-coach/ ā”œā”€ā”€ main.py # Application entrypoint ā”œā”€ā”€ backend/ # Core business logic ā”‚ ā”œā”€ā”€ app/ ā”‚ ā”‚ ā”œā”€ā”€ models/ # Database models ā”‚ ā”‚ ā”œā”€ā”€ services/ # Business services ā”‚ ā”‚ ā””ā”€ā”€ config.py # Configuration ā”‚ ā””ā”€ā”€ alembic/ # Database migrations ā”œā”€ā”€ tui/ # Terminal interface ā”‚ ā”œā”€ā”€ views/ # TUI screens ā”‚ ā”œā”€ā”€ services/ # TUI service layer ā”‚ ā””ā”€ā”€ widgets/ # Custom UI components ā””ā”€ā”€ data/ # SQLite database and files ā”œā”€ā”€ cycling_coach.db ā””ā”€ā”€ gpx/ # GPX route files ``` ## šŸ› ļø Development ### Setup Development Environment ```bash # Clone repository git clone https://github.com/ai-cycling-coach/ai-cycling-coach.git cd ai-cycling-coach # Install in development mode make dev-install # Initialize database make init-db # Run tests make test # Format code make format # Run application make run ``` ### Available Make Commands ```bash make help # Show all available commands make install # Install the application make dev-install # Install in development mode make run # Run the application make init-db # Initialize the database make test # Run tests make clean # Clean build artifacts make build # Build distribution packages make package # Create standalone executable make setup # Complete setup for new users ``` ### Creating a Standalone Executable ```bash make package # Creates: dist/cycling-coach ``` ## šŸš€ Deployment Options ### 1. Portable Installation ```bash # Create portable package make build pip install dist/ai-cycling-coach-*.whl ``` ### 2. Standalone Executable ```bash # Create single-file executable make package # Copy dist/cycling-coach to target system ``` ### 3. Development Installation ```bash # For development and testing make dev-install ``` ## šŸ“‹ Requirements - **Python**: 3.8 or higher - **Operating System**: Linux, macOS, Windows - **Terminal**: Any terminal with Unicode support - **Memory**: ~100MB RAM - **Storage**: ~50MB + data files ## šŸ¤ Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Make your changes 4. Run tests (`make test`) 5. Format code (`make format`) 6. Commit changes (`git commit -m 'Add amazing feature'`) 7. Push to branch (`git push origin feature/amazing-feature`) 8. Open a Pull Request ## šŸ› Troubleshooting ### Common Issues **Database errors:** ```bash make init-db # Reinitialize database ``` **Import errors:** ```bash pip install -e . # Reinstall in development mode ``` **Garmin sync fails:** - Check credentials in `.env` - Verify Garmin Connect account access - Check internet connection **TUI rendering issues:** - Ensure terminal supports Unicode - Try different terminal emulators - Check terminal size (minimum 80x24) ### Getting Help - šŸ“– Check the documentation - šŸ› Open an issue on GitHub - šŸ’¬ Join our community discussions ## šŸ“„ License MIT License - see [LICENSE](LICENSE) file for details. ## šŸ™ Acknowledgments - [Textual](https://github.com/Textualize/textual) - Amazing TUI framework - [garth](https://github.com/matin/garth) - Garmin Connect integration - [OpenRouter](https://openrouter.ai/) - AI model access - [SQLAlchemy](https://www.sqlalchemy.org/) - Database toolkit