Function reference

All functions are registered on the jinja environment by the nutrition extension. Amounts/units/prep are read off cooklang ingredient objects where noted.

Function	Returns	Notes
`nutrition_for(ingredient)`	macros only (`kcal`, `protein_g`, `fat_g`, `carb_g`, `fiber_g`)	reads qty/unit/prep off the ingredient object
`nutrition_for_amount(name, amount, unit, prep)`	full item (macros + micros + vitamins)	lower-level; no ingredient object needed
`aggregate_nutrition(ingredients)`	`{ items, totals, confidence_breakdown, allergen_summary, … }`	one call for a whole list
`total_calories(ingredients)`	number	shortcut
`macros(ingredients)`	`{kcal, protein_g, …}`	shortcut
`vitamins(ingredients)`	object	`totals.vitamins` shortcut
`nutrient_total(ingredients, key)`	number	looks in micros then vitamins (`"iron_mg"`, `"vit_d_iu"`)
`is_in_category(ingredient, slug)`	bool	tree-aware (`oily_fish` ⇒ `fish_and_shellfish`)
`category_servings(plan, slug)`	int	meals containing ≥1 ingredient in the category
`convert(amount, from, to, ingredient?)`	number	unit conversion; ingredient needed for volume/count
`compare(actual, target, op)`	bool	`gte` / `lte` / `eq`
`within_tol(actual, target, tol_pct)`	bool	true when `actual` is within `tol_pct` % of `target`
`nutrition_report(...)`	report object	builds the full per-recipe report structure used by templates
`record_check(label, ok)`	—	records a pass/fail check for the run summary
`all_checks()`	list	every recorded check (`{label, ok}`)
`failed_checks()`	list	only the failed checks; drives the non-zero exit code
`matched_exclusions(ingredients, exclusions)`	list	exclusions found in the list
`unresolved_exclusions(ingredients, exclusions)`	list	requested exclusions that couldn't be resolved

Reading nutrition

`nutrition_for(ingredient)`

Resolves a cooklang ingredient (using its quantity, unit, and prep) to its macros — kcal, protein_g, fat_g, carb_g, fiber_g. For micronutrients and vitamins, use nutrition_for_amount or aggregate_nutrition.

{% set n = nutrition_for(ingredient) %}
{{ n.kcal }} kcal, {{ n.protein_g }} g protein

`nutrition_for_amount(name, amount, unit, prep)`

Lower-level form when you don't have an ingredient object. Returns the full resolved item, including micronutrients and vitamins.

{{ nutrition_for_amount("salmon", 150, "g", "cooked").protein_g }}

`aggregate_nutrition(ingredients)`

Sums a list in one call; returns items, totals, and a confidence_breakdown (see Confidence & provenance).

`total_calories`, `macros`, `vitamins`, `nutrient_total`

Shortcuts over aggregate_nutrition. nutrient_total(ingredients, key) looks the key up in micros then vitamins.

Allergens

Every resolved item carries an allergens block, and aggregate_nutrition adds a top-level allergen_summary:

allergens.status — verified (audited against the 14 EU allergen classes; contains is complete) or unverified (never audited; contains is empty and means nothing known — never "allergen-free").
allergen_summary.contains — union of allergens across verified items, each {class, subtype?, label}. A floor, not a ceiling whenever unverified_ingredients is non-empty.
allergen_summary.unverified_ingredients — canonical names of resolved items we have no allergen data for.
The view follows the reference standard: fda shows the 9 US major allergens (wheat, not gluten-at-large), eu/uk all 14.

{% set alg = aggregate_nutrition(il).allergen_summary %}
{% if alg.status == "unverified" %}
Allergen info unverified
{% elif alg.contains %}
Contains{% if alg.unverified_ingredients %} at least{% endif %}: {{ alg.contains | map(attribute="label") | join(", ") }}
{% endif %}

Check status first, before looking at contains: a never-audited ingredient's block is {status: "unverified", contains: [], view: ...}, and an empty contains on its own is indistinguishable from the genuine "audited, contains none" case — skipping the status check turns an unverified ingredient into a false allergen-free claim.

Reports don't have to hand-write that snippet — the extension registers a shared "allergens" template that renders the standard unverified/Contains/incomplete lines (status-guarded, per above) for both shapes: the batch allergen_summary rollup and the per-item nutrition_for_amount(...).allergens block. Set alg and include it:

{% set alg = aggregate_nutrition(il).allergen_summary %}
{% include "allergens" %}

Categories & conversion

`is_in_category(ingredient, slug)` / `category_servings(plan, slug)`

Tree-aware membership and per-plan serving counts (see Plan-aware reports).

`convert(amount, from, to, ingredient?)`

Unit conversion; ingredient is required for volume/count units that need density or portion data.

Assertions & check tracking

`compare(actual, target, op)` / `within_tol(actual, target, tol_pct)`

compare takes gte / lte / eq. within_tol is true when actual is within tol_pct percent of target.

`record_check`, `all_checks`, `failed_checks`

Track pass/fail checks. failed_checks() being non-empty makes the demo exit non-zero. The ck macros call record_check for you.

`nutrition_report(...)`

Builds the full report data structure templates render from.

Exclusions

`matched_exclusions(ingredients, exclusions)` / `unresolved_exclusions(ingredients, exclusions)`

Which excluded ingredients were found, and which requested exclusions couldn't be resolved against the catalog.

Function reference

Reading nutrition

nutrition_for(ingredient)

nutrition_for_amount(name, amount, unit, prep)

aggregate_nutrition(ingredients)

total_calories, macros, vitamins, nutrient_total