mirror of https://github.com/sstent/AICyclingCoach.git synced 2025-12-05 23:52:06 +00:00

Files

2025-09-12 09:08:10 -07:00

7.9 KiB

Raw Permalink Blame History

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)

git clone https://github.com/ai-cycling-coach/ai-cycling-coach.git
cd ai-cycling-coach
./install.sh

Option 2: Manual Installation

# 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:

# 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:

cycling-coach
# or
ai-cycling-coach
# or
python main.py

Navigate through the interface using:

🏠 Dashboard: View recent workouts, weekly stats, and sync status
📋 Plans: Generate new training plans or manage existing ones
💪 Workouts: Sync from Garmin, view detailed analysis, and approve AI suggestions
📏 Rules: Define custom training constraints and preferences
🗺️ 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

# 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

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

make package
# Creates: dist/cycling-coach

🚀 Deployment Options

1. Portable Installation

# Create portable package
make build
pip install dist/ai-cycling-coach-*.whl

2. Standalone Executable

# Create single-file executable
make package
# Copy dist/cycling-coach to target system

3. Development Installation

# 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

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (make test)
Format code (make format)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

🐛 Troubleshooting

Common Issues

Database errors:

make init-db  # Reinitialize database

Import errors:

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 file for details.

🙏 Acknowledgments

Textual - Amazing TUI framework
garth - Garmin Connect integration
OpenRouter - AI model access
SQLAlchemy - Database toolkit

7.9 KiB Raw Permalink Blame History