Kenny Workout Plans - Simplified Program Generator

A streamlined AI-powered workout program generation system that creates personalized training plans and exports them as easy-to-use workout files.

🚀 Features

Core Functionality

• AI-Powered Program Generation: Create personalized multi-week training programs using advanced periodization strategies
• Workout File Export: Generate detailed workout files in markdown format for easy use
• Profile Management: Create and manage user profiles with goals, experience, and equipment
• AI Coaching: Get personalized advice and recommendations from GPT-4 powered AI coach
• Smart Exercise Selection: Intelligent exercise selection from 228+ exercises based on equipment and preferences

Technical Features

• Modern Web Architecture: FastAPI backend with responsive HTML/CSS/JavaScript frontend
• RESTful API: Clean API design for easy integration and extensibility
• Persistent Data Storage: JSON-based user data storage with automatic backup
• Real-Time Updates: Async functionality for smooth user experience
• Mobile Responsive: Works seamlessly across desktop, tablet, and mobile devices

🏗️ Architecture

Backend (FastAPI)

• FastAPI: High-performance Python web framework
• Pydantic: Data validation and serialization
• Async Support: Non-blocking operations for better performance
• CORS Enabled: Cross-origin resource sharing support

Frontend (Modern Web)

• Vanilla JavaScript: No framework dependencies, fast loading
• Responsive CSS: Mobile-first design with modern CSS Grid and Flexbox
• Progressive Enhancement: Core functionality works without JavaScript
• Accessible Design: WCAG compliant interface elements

Core AI/ML Components

• Kenny Workout Engine: Advanced workout programming algorithms
• OpenAI Integration: GPT-4 powered coaching and explanations
• ML Exercise Selection: Machine learning enhanced exercise recommendation
• Outcome Prediction: AI-powered training outcome forecasting

📦 Installation

Prerequisites

• Python 3.8+
• pip package manager

Quick Start

1. Clone and setup:

   cd "Kenny Workout Plans"
   pip install -r requirements.txt

2. Configure environment (optional):

   # Create .env file for OpenAI API key
   echo "OPENAI_API_KEY=your_api_key_here" > .env

3. Run the application:

   python app.py

4. Open in browser: Navigate to http://localhost:8000

🎯 Usage Guide

Getting Started

1. Create Profile: Set up your personal training profile with goals, experience, and equipment
2. Generate Program: Use AI to create a personalized multi-week training program
3. Export Workout Files: Download detailed workout files for each training session
4. Follow Your Program: Use the exported files to guide your training
5. Get AI Coaching: Ask questions and get personalized advice

API Endpoints

User Management

• GET /api/users - List all users
• POST /api/users - Create new user profile
• GET /api/users/{user_id} - Get user profile and status

Program Management

• POST /api/users/{user_id}/programs - Generate new training program
• GET /api/users/{user_id}/programs/current - Get current program

Program Export

• GET /api/users/{user_id}/programs/{program_id}/export - Export program as workout files
• GET /api/users/{user_id}/programs/{program_id}/download/{week}/{filename} - Download specific workout file

AI Coaching

• POST /api/users/{user_id}/ai-advice - Get AI coaching advice

⚙️ Configuration

Program Generation Options

• Duration: 1-16 weeks
• Periodization: Linear, Undulating, Block, Conjugate
• Progression: Linear, Double Progression, Wave Loading, Percentage-based, Auto-regulation
• Deload Weeks: Automatic recovery periods

AI Features

• Exercise Explanations: Detailed reasoning for exercise selection
• Program Recommendations: AI-suggested optimal program parameters
• Outcome Predictions: Forecasted training results and adaptations
• Real-time Coaching: Personalized advice during workouts

🔧 Development

Project Structure

Kenny Workout Plans/
├── app.py                     # Main FastAPI application
├── run.py                     # Application runner script
├── requirements.txt           # Python dependencies
├── README.md                  # This file
├── templates/
│   └── index.html            # Main web interface
├── src/kenny_workout/        # Core workout engine
│   ├── models.py            # Data models (Profile, Program, Session, etc.)
│   ├── allocation.py        # Training volume allocation
│   ├── scheduler.py         # Session scheduling algorithms
│   ├── outcomes_log.py      # Training outcome logging
│   ├── programming/         # Program generation algorithms
│   │   ├── program_builder.py    # Multi-week program generation
│   │   ├── periodization.py      # Periodization strategies
│   │   ├── progression.py        # Load progression algorithms
│   │   └── deload.py             # Deload week planning
│   ├── ai/                  # AI components
│   │   ├── explanations.py       # Exercise explanations
│   │   ├── recommendations.py    # Program recommendations
│   │   ├── predictions.py        # Outcome predictions
│   │   └── openai_explainer.py   # OpenAI integration
│   ├── exercises/           # Exercise database and selection
│   │   ├── database.py           # Exercise database
│   │   ├── selector.py           # Exercise selection logic
│   │   ├── progressions.py       # Exercise progressions
│   │   └── mega_dataset_importer.py # MegaGym dataset integration
│   ├── ml/                  # Machine learning components
│   │   ├── exercise_selection.py # ML exercise selection
│   │   ├── features.py           # Feature engineering
│   │   └── load_progression.py   # Load progression models
│   └── rules/               # Training rules and configuration
│       └── config.yaml           # Training rules configuration
├── data/                    # External datasets
│   ├── external/           # Raw datasets (MegaGym, MET values, etc.)
│   └── README.md          # Data documentation
├── models/                 # Trained ML models
│   └── slot_regressor.joblib    # Pre-trained slot regression model
├── user_data/             # User profiles and generated programs
└── rules/                 # Additional rules documentation
    └── rules.md          # Training rules reference

Adding New Features

1. Backend: Add new endpoints to app.py
2. Frontend: Extend JavaScript functions in templates/index.html
3. Core Logic: Modify components in src/kenny_workout/
4. Styling: Update CSS in templates/index.html

API Documentation

When running, visit http://localhost:8000/docs for interactive API documentation.

🧪 Testing

Run the application and test core functionality:

1. Create a user profile
2. Generate a multi-week program
3. Complete a workout session
4. View progress analytics
5. Ask the AI coach questions

🔒 Data Security

• Local Storage: All user data stored locally in JSON files
• No External Dependencies: Core functionality works offline
• Privacy First: No data sent to external services except OpenAI (optional)
• User Control: Users own their data completely

🤝 Contributing

This is a personal project, but suggestions and improvements are welcome:

1. Issues: Report bugs or suggest features
2. Code Review: Review implementation and suggest optimizations
3. Testing: Help test edge cases and user scenarios
4. Documentation: Improve documentation and examples

📈 Performance

• Fast Startup: Typically loads in <2 seconds
• Responsive UI: Sub-100ms response times for most operations
• Efficient Memory: Minimal memory footprint
• Scalable: Handles multiple users concurrently

🔮 Future Enhancements

• Advanced Analytics: More detailed progress tracking and predictions
• Social Features: Share programs and compete with friends
• Mobile App: Native mobile applications
• Advanced AI: More sophisticated coaching and program adaptation
• Integration: Connect with fitness trackers and apps

📄 License

This project is for personal use and educational purposes. The core Kenny Workout engine contains proprietary algorithms for workout programming and AI integration.

---

Built with ❤️ for serious fitness enthusiasts who want AI-powered, science-based training programs.