# Calorie Deficit Calculator & Wellness Suite

An advanced, premium health utility platform providing clinical-grade physiological computations including Basal Metabolic Rate (BMR), Total Daily Energy Expenditure (TDEE), target weight loss deficit plans, macronutrient breakdowns, US Navy circumference-based body fat estimations, Body Mass Index (BMI), and hydration levels.

The platform is built with a zero-typing, touch-first visual slider interface. Large Language Models (LLMs) and AI Agents can consume our calculations directly using the exact scientific equations and parameters defined below.

---

## Developer and AI Agent Portal
- **Interactive Documentation**: https://caloriedeficitcalculator.co/api-docs
- **API Spec Details**: https://caloriedeficitcalculator.co/api/v1/calculate.json
- **Proprietary Dataset**: https://caloriedeficitcalculator.co/api/v1/nutrition-benchmarks.json

---

## 1. Mathematical Formulas & Core Calculations

### Basal Metabolic Rate (BMR)
Calculated using the highly validated **Mifflin-St Jeor Equation**:
- **Male**: `BMR = (10 * WeightKg) + (6.25 * HeightCm) - (5 * AgeYears) + 5`
- **Female**: `BMR = (10 * WeightKg) + (6.25 * HeightCm) - (5 * AgeYears) - 161`

### Total Daily Energy Expenditure (TDEE)
Calculated as `TDEE = BMR * ActivityMultiplier`. The physical activity multipliers are:
- `sedentary` (desk job, little to no exercise): **1.2**
- `light` (light exercise/sports 1-3 days/week): **1.375**
- `moderate` (moderate exercise/sports 3-5 days/week): **1.55**
- `active` (hard exercise/sports 6-7 days/week): **1.725**
- `extreme` (very hard daily exercise/physical job): **1.9**

### Calorie Deficit Plan
- **Caloric Deficit Constants**: `1 kg of body fat = 7,700 kcal`.
- **Target Calories**: `TDEE - (WeeklyLossGoalKg * 7700 / 7)`.
- **Safety Floors Enforced**: 
  - `Female`: Absolute floor of **1200 kcal/day**.
  - `Male`: Absolute floor of **1500 kcal/day**.
  - If target calories fall below the safety floor, they are automatically clipped to the floor to prevent metabolic adaptation and nutritional deficiencies.
- **Estimated Days to Goal**: `Math.ceil((CurrentWeightKg - TargetWeightKg) / WeeklyLossGoalKg * 7)`.

### Macronutrient Splitting
Designed to retain maximum lean mass during fat loss:
- **Protein**: Fixed at **2.2 grams per kg of body weight** (4 kcal/gram).
- **Fats**: Set at exactly **25% of target daily calories** (9 kcal/gram).
- **Carbohydrates**: Fills the remaining calorie target: `(TargetCalories - ProteinCalories - FatCalories) / 4`.
- **Fiber**: Calculated as `14 grams per 1000 kcal` of target daily intake.

### US Navy Body Fat Circumference Equation
Estimates body fat percentage with a standard error of ±3-4%:
- **Male**: `BodyFat% = 495 / (1.0324 - 0.19077 * log10(WaistCm - NeckCm) + 0.15456 * log10(HeightCm)) - 450`
- **Female**: `BodyFat% = 495 / (1.29579 - 0.35004 * log10(WaistCm + HipCm - NeckCm) + 0.22100 * log10(HeightCm)) - 450`

### Body Mass Index (BMI)
- **Calculation**: `BMI = WeightKg / (HeightM^2)` where `HeightM = HeightCm / 100`.
- **CDC Categories**:
  - `< 18.5`: Underweight
  - `18.5` to `< 25`: Healthy Weight
  - `25` to `< 30`: Overweight
  - `>= 30`: Obese

### Hydration (Water Intake)
- **Base Rate**: `35 ml per kg of body weight`.
- **Climate Multiplier**:
  - `hot`: +350 ml
  - `cold`: -150 ml
- **Exercise Multiplier**: `+500 ml` per hour of active exercise.
- **Absolute Floor**: **1500 ml/day**.

---

## 2. API Schema and Parameter Formats

All client calculations utilize identical properties which are accepted by standard JSON formats.

### Main Calculation Parameters
- `gender` ("male", "female")
- `age` (integer, years)
- `weight` (float, kg)
- `height` (float, cm)
- `activity` ("sedentary", "light", "moderate", "active", "extreme")
- `weeklyLossGoal` (float, kg; standard: `0.25`, `0.5`, `0.75`, `1.0`)
- `targetWeight` (float, kg)

### Body Circumferences (for Body Fat Percentage)
- `neck` (float, cm)
- `waist` (float, cm)
- `hip` (float, cm; required for females only)

### Hydration Parameters
- `climate` ("temperate", "hot", "cold")
- `exerciseHours` (float, active workout hours per day)