AI Fitness & Nutrition Recommendation System
A containerized FastAPI service decoupling physiological estimation (XGBoost for calories, Random Forest for BMI, Harris-Benedict for BMR/TDEE) from a two-stage hybrid recommender combining content-based scoring with a collaborative component over user-item interactions.
- • XGBoost Regressor for active caloric expenditure
- • Random Forest Regressor for empirical BMI estimation
- • Harris-Benedict formulas for baseline BMR & TDEE calculation
- • Hybrid recommender combining content-based scoring (0.6) with collaborative interaction scoring (0.4)
- • Structured endpoints for health prediction, workouts, and meals
- • Multi-stage Dockerfile and Docker Compose setup
- • Non-clinical fitness tool: strictly no medical or diagnostic claims
- • The repository contains an exploratory TruncatedSVD implementation, although its latent factors are not used in the current recommendation score
- • In-memory and CSV feature store: no active relational database in V1
- • No user authentication, JWT session management, or multi-tenancy
- • No hosted cloud production deployment or live user base
Separation of Physiological Estimation and Recommendation Logic
Combines Cosine Similarity on exercise catalog item features (content-based) with collaborative scoring over user-item interaction statistics (synthetic interactions are used when no user-interaction dataset is provided). Returns ranked exercises with duration and intensity.
Calculates daily calorie targets and distributes macronutrients across meals matching user goals (loss/gain/maintenance) and activity levels.
1. Empirical Physiological Estimation & Non-Probabilistic Anchors
Estimating caloric burn and body metrics cannot rely solely on opaque black-box models. The service establishes a dual estimation boundary in src/prediction/:
- XGBoost Calorie Predictor: An
XGBRegressortrained on biometric inputs (age, gender, height, weight) paired with activity telemetry (steps, average heart rate, sleep duration) to predict active caloric expenditure. - Random Forest BMI Predictor: A
RandomForestRegressortrained to predict body mass index variations, paired with a deterministic mathematical fallback to ensure results never drift outside physical constraints. - Harris-Benedict Baseline Calculator: In
bmr_calculator.py, classical metabolic equations calculate Basal Metabolic Rate (BMR) and Total Daily Energy Expenditure (TDEE). This acts as a deterministic sanity anchor for all downstream planning.
2. Two-Stage Hybrid Recommender Architecture
Recommendation logic is isolated from biometric estimation. The recommendation engine in src/recommendation/ blends content attributes with collaborative signals:
- Content-Based Matching (0.6 weight): Calculates Cosine Similarity between user target profiles and exercise catalog feature vectors in
items.csv(matching target muscle groups, difficulty, and equipment requirements). - Collaborative Component (0.4 weight): In
collaborative.py, collaborative scores are calculated over user-item interaction statistics, and synthetic interactions are used when no user-interaction dataset is provided. The repository contains an exploratory TruncatedSVD implementation, although its latent factors are not used in the current recommendation score. - Hybrid Combiner: The final score combines
0.6 * content_score + 0.4 * collaborative_score, delivering ranked workout exercises alongside estimated duration and intensity.
3. Meal Planning & Macronutrient Distribution
Complementing workout routines, the /api/v1/recommend/meal endpoint coordinates nutrition guidance:
- Adjusts daily caloric targets based on user intent (caloric deficit for weight loss, surplus for muscle hypertrophy, or maintenance).
- Divides daily calorie allowances across configured meal frequencies (e.g. 3 meals + optional snacks) with target macronutrient breakdowns (protein, carbohydrates, fats).
4. FastAPI Architecture & Docker Containerization
The backend is implemented as a modular asynchronous service: