🔬 Comprehensive Nutrient & Supplement Rules Engine
This document details every specific rule, threshold, and logic gate used by the Nutrient Analytics algorithm. By consulting this guide, you can see exactly how and why a supplement or nutrient avoidance is recommended to a user without needing to inspect the software’s codebase.
1. The 4-Tier Priority Architecture
The system evaluates the user’s clinical profile top-down. If a conflict occurs, the lower tier recommendation is either modified or completely stripped (vetoed) by the higher tier.
- Tier 1: Clinical Biomarkers. Hard medical data (bloodwork). Overrides all other tiers.
- Tier 2: Systemic Risks. Assessed clinical conditions (Gut health, Metabolic status, Sleep disorders).
- Tier 3: Mind & Nervous System. Mental health baselines (Burnout, Anxiety, Stress).
- Tier 4: Performance & Body Objectives. User goals (Weight loss, Muscle gain). Lowest priority.
2. Tier 1: Clinical Biomarkers (Bloodwork) Ruleset
These recommendations are triggered explicitly by uploaded lab results falling outside optimal ranges.
| Biomarker Threshold | Action | Nutrient / Supplement | System Rationale |
|---|---|---|---|
| Vitamin D < 75 | Adopt | Vitamin D3 & K2 | Levels are suboptimal. K2 helps safely direct calcium to your bones. |
| Ferritin < 50 | Adopt | Heme Iron & Vitamin C | Iron stores need a boost. Vitamin C naturally increases absorption. |
| B12 < 400 OR Folate < 15 |
Adopt | Methylated B12 & Folate | Crucial support for cellular energy, brain function, and methylation. |
| HbA1c > 41 | Avoid Adopt |
Refined Sugars & HFCS Berberine or Alpha Lipoic Acid |
Limits blood sugar spikes. Berberine supports cellular insulin sensitivity. |
| Triglycerides > 1.7 | Avoid | Excess Fructose & Trans Fats | Reducing these helps balance blood lipid profiles naturally. |
| LDL > 3.5 | Adopt Avoid |
Soluble Fiber (Beta-Glucans) Excess Saturated Fats |
Fiber binds to cholesterol to excrete it; limiting saturated fat supports heart health. |
| HDL < 1.0 | Adopt | Omega-3 (EPA/DHA) & Olive Oil | Healthy fats that naturally support the increase of protective HDL. |
| ALT > 40 OR GGT > 40 |
Avoid Adopt |
Alcohol & Processed Oils Choline & Milk Thistle |
Removes liver stress; supplements provide raw materials to clear fat deposits. |
| CRP > 3.0 | Adopt Avoid |
Curcumin & Omega-3 Ultra-Processed Foods |
Powerful natural anti-inflammatories to cool systemic stress. |
| Creatinine > 100 OR eGFR < 60 |
Avoid [VETO] |
Excessive Protein (>1.5g/kg) | Reduces filtration burden on kidneys. Generates the KidneyStress internal veto flag. |
| TSH > 4.5 OR FT4 < 12 |
Adopt Avoid |
Iodine, Selenium & Zinc Raw Goitrogens (Raw Kale/Broccoli) |
Building blocks for thyroid hormones. Raw cruciferous veg blocks iodine uptake. |
| Testosterone < 12 (Males Only) |
Adopt | Zinc, Magnesium & Vitamin D | Foundational micronutrients required for natural testosterone synthesis. |
3. Tier 2: Systemic Risks Ruleset
Triggered by assessments of digestive, metabolic, and sleep health.
| Condition Threshold | Action | Nutrient / Supplement | System Rationale |
|---|---|---|---|
| Lactose (Severe/High) | Avoid Adopt [VETO] |
Lactose & Dairy Plant-based Calcium |
Reduces inflammation. Generates the Whey internal veto flag. |
| Celiac (Severe/High) | Avoid Adopt |
Gluten, Wheat, Barley, Rye L-Glutamine & Bone Broth |
Protects intestinal health. Glutamine soothes the gut lining and supports repair. |
| IBS or SIBO (Severe) | Avoid Adopt |
High FODMAPs & Sugar Alcohols Peppermint Oil & PHGG Fiber |
Limits fermentation and bloating. Peppermint soothes the digestive tract. |
| High Blood Pressure (Yes) | Adopt Avoid Adopt |
Potassium-Rich Foods High Dietary Sodium & Licorice Dietary Nitrates (Beetroot) |
Potassium/Nitrates act as vasodilators to relax blood vessels and excrete sodium. |
| Visceral Fat (High/Severe) | Avoid Adopt |
Liquid Fructose (Sodas/Juice) Green Tea Extract (EGCG) |
Fructose converts to belly fat. EGCG supports abdominal fat oxidation. |
| Diabetes (High/Severe) | Avoid Adopt |
High GI Carbohydrates Chromium & Ceylon Cinnamon |
Limits simple sugars for steady energy; supplements healthy blood sugar metabolism. |
| Insomnia (High/Severe) | Avoid Adopt |
Post-12PM Caffeine & Alcohol Magnesium Bisglycinate & Apigenin |
Alcohol destroys REM. Magnesium/Apigenin calms the central nervous system. |
| Circadian (High/Severe) | Adopt Avoid |
Melatonin-Rich Foods (Tart Cherry) Heavy Meals within 3 Hrs of Bed |
Encourages sleep window onset. Late digestion increases core body temperature. |
4. Tier 3: Mind & Nervous System Ruleset
Triggered by the user’s current psychological and emotional state.
| Psychological State | Action | Nutrient / Supplement | System Rationale |
|---|---|---|---|
| Burnout / Freeze State | Avoid Adopt |
High-Dose Stimulants Adaptogens (Ashwagandha/Rhodiola) |
Allows exhausted nervous system to recover. Adaptogens gently process stress. |
| GAD Anxiety (High/Severe) | Adopt Avoid |
L-Theanine Excessive Caffeine |
Theanine promotes calm focus. Caffeine mimics physiological panic response. |
5. Tier 4: Performance & Body Objectives Ruleset
Triggered purely by the user’s stated fitness goals, subject to vetoes from higher tiers.
| Objective | Action | Nutrient / Supplement | System Rationale |
|---|---|---|---|
| Build Muscle | Adopt | High-Quality Whey Protein (Swaps to Plant/Beef Isolate if Whey Veto is active) |
Provides essential amino acids for lean muscle synthesis. |
| Build Muscle | Adopt | Creatine Monohydrate (Deleted entirely if KidneyStress Veto is active) |
Supports strength and cellular energy. |
| Weight Loss | Avoid Adopt |
Liquid Calories & Hidden Sugars High-Volume Soluble Fiber |
Ensures fuel comes from satiating foods. Fiber promotes fullness. |
| Weight Gain | Adopt | Caloric-Dense Healthy Fats | Provides clean, easily digestible calories to reach a surplus. |
| High Daily Activity (Burn > 500 kcal/day) |
Adopt | Electrolytes (Na, K, Mg) | Replenishes vital minerals lost through high physical exertion. |
6. The Internal Veto System (Safeguards)
The system actively prevents conflicting advice using silent tracking tags known as Vetoes.
The [Whey] Veto
If the user flags as having High/Severe Lactose intolerance in Tier 2, the system engages the [Whey] veto. When the system reaches Tier 4 and attempts to recommend Whey Protein for muscle building, the veto catches it and automatically substitutes the recommendation for “Plant/Beef Isolate Protein”.
If the user flags as having High/Severe Lactose intolerance in Tier 2, the system engages the [Whey] veto. When the system reaches Tier 4 and attempts to recommend Whey Protein for muscle building, the veto catches it and automatically substitutes the recommendation for “Plant/Beef Isolate Protein”.
The[KidneyStress] Veto
If the user has High Creatinine or Low eGFR in their Tier 1 bloodwork, the system engages the [KidneyStress] veto. When the system reaches Tier 4 and attempts to recommend Creatine Monohydrate for muscle building, the veto deletes the recommendation entirely, as Creatine can falsely elevate blood creatinine and burden compromised kidneys.
If the user has High Creatinine or Low eGFR in their Tier 1 bloodwork, the system engages the [KidneyStress] veto. When the system reaches Tier 4 and attempts to recommend Creatine Monohydrate for muscle building, the veto deletes the recommendation entirely, as Creatine can falsely elevate blood creatinine and burden compromised kidneys.