⚙️ Meal Planner Algorithms and AI/PHP Hybrid Grounding
Documentation of the deterministic logic and hybrid AI math driving the Meal Planner ecosystem. This architecture ensures 100% hallucination-free, clinically accurate meal planning.
1. The Hybrid AI Architecture (How it Works)
Large Language Models (AI) are excellent at creative pattern recognition but notoriously terrible at exact mathematics and factual recall. If asked to “build a 2,000 calorie plan,” an AI will confidently invent fake foods and hallucinate incorrect macro data.
To solve this, our system puts the AI in a strict mathematical straitjacket. We separate the Creative (AI) from the Calculations (PHP/Database).
Step 1: Grounding & Guardrails (PHP)
Before the AI is even contacted, the PHP server reads the user’s “God JSON” (Clinical Assessment). It identifies target calories and absolute red flags (e.g., Severe Celiac, Lactose Intolerance). PHP then queries the user’s personal database of saved Wholefoods and Custom Recipes. Any food that violates the user’s clinical red flags is silently stripped out.
Step 2: The “Chef” (AI Drafting)
The PHP server sends this heavily filtered, safe list of Food IDs to the AI. The AI’s only job is to act as a chef: it looks at the available ingredients and groups them logically (e.g., it pairs Oats with Berries, not Oats with Salmon). The AI returns a strict JSON array containing the selected Item_IDs and a rough estimated portion in grams.
Step 3: The Handoff & The “Calculator” (PHP)
The AI hands the JSON back to the PHP server. PHP completely ignores any nutritional claims the AI makes. Instead, PHP takes the AI’s chosen Item_IDs, queries our deterministic database for the true nutritional values per 100g, and calculates the exact caloric total of the AI’s drafted plate.
Step 4: Deterministic Scaling (The Magic Fix)
Because the AI’s drafted portions will rarely hit the exact God JSON target, PHP executes a scaling algorithm. If the user’s target is 3,029 kcal, but the AI’s draft equals 2,600 kcal, PHP calculates the difference (a multiplier of 1.165). PHP instantly multiplies the portion size of every item on the plate by 1.165.
The Result: The user receives a meal plan with highly logical, appetizing food combinations (chosen by AI), but with absolute portions locked mathematically by the database to hit their exact clinical targets.
2. Caloric Scaling Formula
The exact mathematical sequence used in Step 4 to dynamically scale the AI’s draft.
2. Multiplier = God_JSON_Target_Kcal / Draft_Kcal
3. Final_Item_Qty = Math.round(AI_Drafted_Qty * Multiplier)
3. Cooking Method Physics
Raw wholefood macros are dynamically adjusted in the UI based on the chosen cooking preparation method. The engine calculates added calories and assumes they are derived entirely from absorbed cooking fats (oils/butter).
| Method | Caloric Multiplier | Fat Addition Formula |
|---|---|---|
| Raw / Boiled / Steamed | x 1.0 (0% added) | +0.0g Fat |
| Baked / Grilled | x 1.1 (+10% Kcal) | (Final Kcal – Base Kcal) / 9 |
| Pan-Fried / Butter | x 1.2 (+20% Kcal) | (Final Kcal – Base Kcal) / 9 |
| Deep-Fried | x 1.4 (+40% Kcal) | (Final Kcal – Base Kcal) / 9 |
4. 7-Day Protocol Weekly Insights
When a 7-day protocol is rendered, the system parses all 7 days of meal data simultaneously, combines the exact macros, and evaluates them against weekly clinical thresholds.
Caloric Accuracy
Calculates variance against a 7-day extended God JSON target (Daily Target * 7).
- 🔥 Calories On Target If Variance < 10%
- ⚠️ Calories Over Target If Variance ≥ 10% AND Actual > Target
- ⚠️ Calories Under Target If Variance ≥ 10% AND Actual < Target
Protein Density
Determines if the week successfully hits a high-protein baseline relative to total caloric intake (4 calories per gram of protein).
- 💪 High Protein Week If Protein_Ratio > 20% (0.20)
Clinical Watch-Outs (Sugar & Salt)
Monitors standard NHS/WHO upper limits scaled across 7 days. These triggers also append tiny badges to individual daily cards to expose the exact day causing the breach.
- Salt: Limit is 6g per day (42g/week).
⚠️ Watch Salt Intake If Weekly Salt > (6 * Days Rendered) - Sugar: Limit is roughly 30g free sugars per day (210g/week).
⚠️ Watch Sugar Intake If Weekly Sugar > (30 * Days Rendered)
5. Daily Traffic Light Indicators (Per 100g)
Used on the individual recipe/food views to highlight base macro density. Follows standard UK Food Standards Agency guidelines per 100g.
| Nutrient | Green (Low) | Amber (Medium) | Red (High) |
|---|---|---|---|
| Fat | ≤ 3.0g | 3.1g – 17.5g | > 17.5g |
| Sat Fat | ≤ 1.5g | 1.6g – 5.0g | > 5.0g |
| Sugars | ≤ 5.0g | 5.1g – 22.5g | > 22.5g |
| Salt | ≤ 0.3g | 0.31g – 1.5g | > 1.5g |