docs/nutrition_tools.md

Nutrition calculation tools (MuscleGrowthAI)

Deterministic fitness/nutrition math for advisor responses. LLM personas receive pre-computed values instead of doing arithmetic themselves.

Tools in use

Source	Cost	Status	Purpose
Local Python formulas	Free	Active	lbs↔kg, protein g/kg (1.6–2.2), meal splits
USDA FoodData Central	Free (API key)	Planned	Food nutrient lookup by name/barcode
Open Food Facts	Free (no key)	Planned	Product/barcode nutrient data

Core formulas (local)

• Weight: kg = lbs × 0.45359237
• Protein (hypertrophy): protein_g_min = round(weight_kg × 1.6), protein_g_mid = round(weight_kg × 1.9), protein_g_max = round(weight_kg × 2.2)
• Meal split: even distribution with remainder assigned to first meals

Example: 230 lb → 104.33 kg → 167–230 g protein/day; midpoint at 1.9 g/kg ≈ ~198 g/day (4 meals ≈ 50/50/49/49 g at the midpoint).

How calculations reach advisors

1. Context injection (primary): When chat history mentions protein and a body weight is present, compute_protein_advisory_context() runs in _build_enhanced_context_for_persona() and adds a PRE-COMPUTED NUTRITION VALUES JSON block to each persona system prompt.
2. LLM tool calling (optional): calculate_protein_target is registered in app/tools/nutrition_calculator.py and enabled via muscle_growth_config.yaml → tools.nutrition_calculator.enabled: true. The orchestrator may call it for direct tool responses when appropriate.

Files

• multi_llm_chatbot_backend/app/tools/nutrition_calculator.py — formulas + tool definition
• multi_llm_chatbot_backend/app/core/improved_orchestrator.py — injects computed context into persona prompts
• muscle_growth_config.yaml — enables nutrition_calculator tool

USDA / Open Food Facts (later)

• USDA: register at https://fdc.nal.usda.gov/api-key-signup, set USDA_API_KEY env var.
• Open Food Facts: https://world.openfoodfacts.org/api/v2/product/{barcode} — no key required.