Food and Recipe Scoring Algorithm Reference

Part 1: The Average Score (1-8)

The Average Score provides a general nutritional rating for a food, independent of any user. It starts with a baseline score of 5 and is adjusted based on the following rules, applied to the food’s per-100g nutritional values. The final result is capped between 1 and 8.

Part 0: What Gets Scored At All

Wholefoods and recipes are scored (base + personal). Cheat foods and supplements are never scored — neither layer runs for them. Cheats are packaged/processed items where nobody really knows what’s in them, so a nutrient score would be misleading — a short notice badge shows instead. Supplements carry no nutrient/calorie data at all and have their own separate detail-card path that never touches this file.

Part 1a: Recipe Scoring (Ingredient-by-Ingredient)

Recipes are scored differently from a single wholefood, because a recipe is really several wholefoods combined in different amounts. As of this update, a recipe is no longer blended into one “per 100g of the whole pot” number. Instead:

1. Every ingredient is scored completely on its own — exact same Base Score and Personal Adjustment rules as a plain wholefood (Parts 1 and 2 below), using that ingredient’s own real per-100g nutrients and its own real wellness tags.
2. Each ingredient’s score is then weighted by how much of the recipe’s total weight it actually makes up (its grams ÷ the recipe’s total grams).
3. The weighted scores are added together for the recipe’s final Base Score and final Adjustment Value.

Result: a recipe that’s mostly chicken breast with a pinch of salt scores like chicken, not like an even blend of the two. A large ingredient drives the result; a trace ingredient barely moves it.

This only works because every ingredient in a recipe built via “Build It” or “Picture It” (recipes/recipeStudio.php) is guaranteed to be a real, matched wholefood carrying a barcode — any ingredient that doesn’t match a real catalog item is silently dropped at save time, never saved. Recipes saved before this matching existed may have no traceable ingredients at all; those cannot be scored this way and are flagged for the admin to rebuild or delete (see release_plans/SCHEDULER_MASTER_PLAN.md).

All of this lives in one shared file, pantry/food_score_calculator.php, used by both plain wholefoods and every recipe ingredient — one set of rules, not two.

Part 1b: The Colour Bands

The score circle’s colour comes from which of 5 bands the Base Score falls into. The middle “Okay” band is deliberately just the single value 5 — the exact untouched baseline, with no bonuses or penalties either way — rather than a wide range, so a small change like the fruit/veg bonus above is actually visible as a colour change instead of getting lost inside a big “amber” zone.

This band rule is shared (bsm_food_score_band() in pantry/food_score_calculator.php) by every place a score gets a colour — the food/recipe widget above and the meal-plan page — so the same score never shows as a different colour in two places. Each page is still free to use its own exact shades for a given band (the meal-plan page deliberately uses stronger, higher-contrast colours than the widget here).

Part 2: The Personalization Layer

This layer takes the Base Score and applies a series of adjustments based on the specific user’s health profile (“God JSON”). This generates the Adjustment Value (e.g., +2, -3) shown in the black badge. There are two paths depending on whether a food has been processed by the DB Tagger yet, described below. For a recipe, this runs once per ingredient (see Part 1a), not once for the whole dish.

A1. Tier-Based Point Weighting (Path A)

Every wellness-factor code encodes its own priority tier as a number prefix — T5_VERIFIED_LACTOSE is tier 5, T30_SYS_LACTOSE is tier 30, and so on. Lower tier numbers mean higher evidentiary confidence (5 = lab/monitor verified, 10 = blood biomarker derived, 30 = onboarding-survey risk score), so avoid penalties get bigger as the tier number gets smaller — mirroring the original -4/-3/-2/-1 deal-breaker scale below. Tiers 40 and up (mind states, neurotype traits, coaching preference, goals) aren’t clinical risk tiers, so they get a flat, gentle weight instead.

Every matched tag adds its own penalty or bonus independently, so a food can rack up several adjustments at once if it trips multiple wellness factors the user actually has — unlike Path B’s fixed, single-shot condition checks below.

A2. Fallback: Legacy Hand-Coded Scoring (Path B)

Path B is the fallback for any individual wholefood (or, for a recipe, any individual ingredient) the DB Tagger hasn’t processed yet. Cheats and supplements never reach either path — they aren’t scored at all (see Part 0 above).

B1. Major Penalties (Deal-Breakers)

Note: the lactose check used to only match "High", silently skipping the worse "Severe" band entirely. It now matches both, matching the correction made to the diabetes check below.

B2. Weighted Health Risk Penalties

B3. Goal-Oriented Bonuses

B4. Targeted Nutrient Bonuses