Nguyen Tran Trung Thanh
Back to Overview
Containerized Open Source ServiceFastAPI · Containerized Service

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.

PythonFastAPIXGBoostRandom ForestCollaborative Filteringscikit-learnDockerPydantic
GitHub Repository
VERIFIED REPOSITORY IMPLEMENTATION
  • • 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
EXPLICIT BOUNDARIES (NON-CLAIMS)
  • • 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
Pipeline Architecture

Separation of Physiological Estimation and Recommendation Logic

TWO-STAGE ESTIMATION & HYBRID RECOMMENDATION PIPELINEFastAPI · XGBoost · Random Forest · Collaborative Filtering · Docker
Input Schema & Validation
Pydantic Request Schemas
agegenderheight/weightsteps & heart_ratesleep_hoursgoal & fitness_level
STAGE 1: Physiological Estimation & BaselinesML Regressors + Deterministic Anchor
XGBoost Regressor
Predicts caloric expenditure based on biometric and activity features.
Random Forest Regressor
Estimates empirical BMI, with deterministic formula fallback for outliers.
Harris-Benedict Calculator
Mathematical BMR & TDEE baselines anchoring metabolic calculations.
STAGE 2: Recommendation & Composition LogicHybrid Scoring (0.6 Content + 0.4 Collaborative)
Workout Recommendation (/recommend/workout)

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.

Meal Recommendation (/recommend/meal)

Calculates daily calorie targets and distributes macronutrients across meals matching user goals (loss/gain/maintenance) and activity levels.

Runtime: FastAPI asynchronous service containerized with multi-stage Docker & Docker ComposeNon-clinical tool

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 XGBRegressor trained 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 RandomForestRegressor trained 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:

// Modular FastAPI route structure
app = FastAPI(title="AI Fitness & Nutrition System")
app.include_router(health.router, prefix="/api/v1/predict")
app.include_router(workout.router, prefix="/api/v1/recommend")
app.include_router(meal.router, prefix="/api/v1/recommend")
// Multi-stage Dockerfile packaging Python 3.10-slim with uvicorn
Back to PortfolioView TRANSO Case Study →