Deploy: Pin Streamlit to 1.61.1; add deployment parity tests

.gitattributes

@@ -0,0 +1,2 @@
+#data/*.csv filter=lfs diff=lfs merge=lfs -text
+#embeddings/*.npy filter=lfs diff=lfs merge=lfs -text 

.gitignore

@@ -0,0 +1,19 @@
+# Built catalog artifacts — rebuild with pipeline/, or pull from the Hub
+data/*.duckdb
+data/*.duckdb.wal
+data/*.parquet
+
+# Secrets — never commit. Set via HF Space "Repository secrets".
+.streamlit/secrets.toml
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+env/
+.pytest_cache/
+*.egg-info/
+
+# macOS
+.DS_Store

.streamlit/config.toml

@@ -0,0 +1,13 @@
+[server]
+headless = true
+
+[browser]
+gatherUsageStats = false
+
+[theme]
+base = "light"
+primaryColor = "#0F8A5F"
+backgroundColor = "#FBFBF9"
+secondaryBackgroundColor = "#FFFFFF"
+textColor = "#1A1F1C"
+font = "sans serif"

README.md

@@ -0,0 +1,140 @@
+---
+title: NutriWeb
+emoji: 🥗
+colorFrom: green
+colorTo: blue
+sdk: streamlit
+sdk_version: 1.61.1
+app_file: app.py
+pinned: false
+license: agpl-3.0
+---
+
+# NutriWeb
+
+Find a packaged food, and get a **healthier alternative of the same kind** that
+respects your allergens, your diet and your health profile.
+
+Built on the full [Open Food Facts product
+database](https://huggingface.co/datasets/openfoodfacts/product-database)
+(4.66M products), filtered to **796,542 US products**.
+
+---
+
+## Why this was rebuilt
+
+The previous version ran on a hand-cleaned CSV subset of unknown provenance,
+downloaded from Google Drive at startup. Its recommendations weren't
+trustworthy, and the data turned out to be only one of three causes:
+
+| Problem | Old approach | Now |
+|---|---|---|
+| **Coverage** | A static CSV subset, no lineage | 796,542 US products from the live upstream dataset, rebuildable in one command |
+| **Ingredient / allergen logic** | ~90 hardcoded substrings matched with `if key in name`, so `"sugar"` fired on *"sugar-free"* | Exact matching on Open Food Facts' canonical `allergens_tags`, `additives_tags`, `ingredients_analysis_tags` |
+| **Additive risk** | A hand-written opinion list | EFSA overexposure ratings and the ANSES watch list, via the OFF additives taxonomy |
+| **Retrieval** | FAISS index rebuilt **on every query**, with a positional slice applied to a filtered frame that misaligned scores against products | Category-constrained SQL candidate generation, ranked in NumPy |
+| **Relevance** | No category constraint — a soda could return a candy bar | Candidates must share a category tag; regression-tested |
+| **Blood-pressure rule** | `sodium_100g > 5.0` — five *grams* per 100 g, a level no food reaches, so it never fired | FDA-derived per-100g ceilings for salt and saturated fat |
+| **Passwords** | Stored and compared in plaintext | bcrypt via passlib |
+| **Dependencies** | torch + transformers + faiss ≈ 2 GB | None of them; ~40 MB of pure Python and DuckDB |
+
+## What it does
+
+**Health score (0–100)** — the single quantity used for ranking:
+70% Nutri-Score 2023 + 30% NOVA processing group, minus a capped penalty for
+additives flagged by EFSA or ANSES.
+
+**Nutri-Score, computed where Open Food Facts has none.** Only 44% of US
+products carry an OFF grade, because Nutri-Score is a European scheme and OFF
+usually cannot assign one without a category. NutriWeb ports the official 2023
+algorithm from OFF's own reference implementation and computes the rest:
+
+| | products | share |
+|---|---|---|
+| Published by Open Food Facts | 352,295 | 44.2% |
+| **Computed by NutriWeb** | **290,908** | **36.5%** |
+| **Total graded** | **643,203** | **80.7%** |
+
+Validated against OFF's own grades on **317,265 products where both exist**:
+**98.37% exact agreement**, 99.73% within one letter, 95.99% exact numeric score.
+
+Grades are never silently merged — the UI labels every grade with its source,
+and grades computed for products with no category are marked *low confidence*.
+
+**Recommendations** — three stages:
+
+1. **Candidates** — products sharing a category tag, choosing the most specific
+   tag whose pool clears a minimum size. Falls back to ingredient-tag overlap
+   for the 49% of US products with no category.
+2. **Hard filters** — allergens (including traces), diet, and health-condition
+   ceilings, applied in SQL *before* the limit so the pool is filtered, not truncated.
+   These exclude; they are never traded off against a good score.
+3. **Ranking** — 45% health gain, 30% macro similarity, 20% ingredient overlap,
+   5% popularity. Every component is shown to the user.
+
+## Running it
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+
+# Build the catalog (one-off; ~7.2 GB download, then about a minute)
+python pipeline/01_download.py      # fetch food.parquet from the Hub
+python pipeline/02_curate.py        # filter, flatten, pivot -> DuckDB
+python pipeline/03_score.py         # Nutri-Score + health score + validation
+python pipeline/04_audit.py         # coverage report — read this
+
+streamlit run app.py
+```
+
+`01_download.py` needs a Hugging Face token (`hf auth login`, or `HF_TOKEN`):
+anonymous requests get rate-limited on a file that size.
+
+### Deploying to Spaces
+
+Publish the built catalog so the Space doesn't rebuild from 7.2 GB on cold start:
+
+```bash
+python pipeline/05_publish.py <your-username>/nutriweb-us-catalog
+```
+
+Then set on the Space:
+- `NUTRIWEB_CATALOG_REPO` = `<your-username>/nutriweb-us-catalog`
+- `MONGODB_URI` *(optional)* — as a **repository secret**, never in a file.
+  Without it the app runs with session-only profiles.
+
+## Layout
+
+```
+app.py                  entry point; st.navigation
+views/                  search · product · recommend · compare · profile · insights
+components/             badges, cards, nutrient tables
+nutriweb/
+  data/catalog.py       DuckDB access, FTS search
+  scoring/              nutriscore.py (2023 algorithm) · health_score.py · additives.py
+  reco/                 engine.py · filters.py · similarity.py
+  profile/              model.py · auth.py
+pipeline/               01_download → 02_curate → 03_score → 04_audit → 05_publish
+tests/                  64 tests: algorithm, filters, engine
+```
+
+## Tests
+
+```bash
+pytest
+```
+
+Covers Nutri-Score variant selection and grade boundaries, the safety filters
+(an allergen must never reach a result), and engine guarantees — every
+recommendation is strictly healthier, shares the source category, and a soda
+never returns confectionery.
+
+## Data and licence
+
+Product data © Open Food Facts contributors, licensed
+[ODbL](https://opendatacommons.org/licenses/odbl/). The Nutri-Score
+implementation is ported from
+[openfoodfacts-server](https://github.com/openfoodfacts/openfoodfacts-server)
+(`lib/ProductOpener/Nutriscore.pm`), AGPL-3.0. This project is AGPL-3.0.
+
+NutriWeb is an informational tool, not medical or dietary advice.

app.py

@@ -0,0 +1,61 @@
+"""NutriWeb — entry point.
+
+Replaces the previous single 450-line script that routed pages by mutating
+`st.session_state.page` and calling `st.stop()` at the end of each branch. This
+uses Streamlit's own navigation, so the browser URL, the back button and the
+sidebar all behave normally.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import streamlit as st
+
+REPO_ROOT = Path(__file__).resolve().parent
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+st.set_page_config(
+    page_title="NutriWeb",
+    page_icon="🥗",
+    layout="wide",
+    initial_sidebar_state="expanded",
+)
+
+
+@st.cache_resource
+def _styles() -> str:
+    return (REPO_ROOT / "styles.css").read_text()
+
+
+st.markdown(f"<style>{_styles()}</style>", unsafe_allow_html=True)
+
+from nutriweb.profile.model import UserProfile  # noqa: E402
+from views import state  # noqa: E402
+
+state.init()
+
+pages = [
+    st.Page("views/search.py", title="Search", icon=":material/search:", default=True),
+    st.Page("views/product.py", title="Product", icon=":material/nutrition:"),
+    st.Page("views/recommend.py", title="Healthier swaps", icon=":material/swap_horiz:"),
+    st.Page("views/compare.py", title="Compare", icon=":material/compare_arrows:"),
+    st.Page("views/profile_page.py", title="My profile", icon=":material/person:"),
+    st.Page("views/insights.py", title="Data insights", icon=":material/insights:"),
+]
+
+with st.sidebar:
+    st.markdown("### 🥗 NutriWeb")
+    st.caption("Personalised food choices, from the full Open Food Facts US catalog.")
+    profile: UserProfile = st.session_state.profile
+    if profile.user_id:
+        st.success(f"Signed in as **{profile.user_id}**")
+        if st.button("Sign out", use_container_width=True):
+            state.sign_out()
+            st.rerun()
+    else:
+        st.info("Browsing as a guest. Set a profile to get personalised results.")
+
+st.navigation(pages).run()

components/__init__.py

@@ -0,0 +1 @@
+"""Reusable UI components."""

components/badges.py

@@ -0,0 +1,134 @@
+"""Score badges, chips and meters — the small visual vocabulary of the app.
+
+Everything returns an HTML string rather than calling st.* directly, so the
+pieces compose inside cards and columns.
+
+A recurring rule here: whenever a Nutri-Score grade is shown, its *source* is
+shown with it. Roughly 45% of the grades in the catalog were computed by
+NutriWeb rather than published by Open Food Facts, and presenting the two
+identically would overstate what we know.
+"""
+
+from __future__ import annotations
+
+import html
+
+from nutriweb.util import num, tag_set
+
+GRADE_LABEL = {
+    "a": "A", "b": "B", "c": "C", "d": "D", "e": "E",
+}
+NOVA_LABEL = {
+    1: "Unprocessed",
+    2: "Culinary ingredient",
+    3: "Processed",
+    4: "Ultra-processed",
+}
+
+
+def esc(value) -> str:
+    return html.escape(str(value)) if value is not None else ""
+
+
+def nutriscore_badge(grade: str | None, source: str | None = None) -> str:
+    """Nutri-Score pill. `source` is 'off' or 'nutriweb'."""
+    if not grade or str(grade).lower() not in GRADE_LABEL:
+        return '<span class="nw-badge nw-badge-neutral">Nutri-Score n/a</span>'
+    g = str(grade).lower()
+    chip = ""
+    if source == "nutriweb":
+        chip = '<span class="nw-source" title="Computed by NutriWeb from the nutrition facts, because Open Food Facts has no grade for this product">est.</span>'
+    elif source == "off":
+        chip = '<span class="nw-source" title="Published by Open Food Facts">OFF</span>'
+    return (
+        f'<span class="nw-badge ns-{g}"><span class="k">Nutri-Score</span> '
+        f"{GRADE_LABEL[g]}</span>{chip}"
+    )
+
+
+def nova_badge(nova) -> str:
+    value = num(nova)
+    if value is None or int(value) not in NOVA_LABEL:
+        return ""
+    n = int(value)
+    tone = {1: "chip-good", 2: "chip-good", 3: "chip-warn", 4: "chip-danger"}[n]
+    return f'<span class="nw-chip {tone}" title="NOVA {n}">{NOVA_LABEL[n]}</span>'
+
+
+def eco_badge(grade) -> str:
+    if not grade or str(grade).lower() not in GRADE_LABEL:
+        return ""
+    g = str(grade).lower()
+    return f'<span class="nw-badge ns-{g}"><span class="k">Eco</span> {GRADE_LABEL[g]}</span>'
+
+
+def badge_row(product: dict) -> str:
+    parts = [
+        nutriscore_badge(product.get("nutriscore_grade"), product.get("nutriscore_source")),
+        eco_badge(product.get("environmental_score_grade")),
+        nova_badge(product.get("nova_group")),
+    ]
+    return '<div class="nw-badges">' + "".join(p for p in parts if p) + "</div>"
+
+
+def health_meter(score, confidence: str | None = None) -> str:
+    """The 0-100 NutriWeb health score with a coloured bar."""
+    value = num(score)
+    if value is None:
+        return '<div class="nw-health"><span class="m">Not enough data to score</span></div>'
+
+    colour = (
+        "var(--ns-a)" if value >= 75
+        else "var(--ns-b)" if value >= 55
+        else "var(--ns-c)" if value >= 40
+        else "var(--ns-d)" if value >= 25
+        else "var(--ns-e)"
+    )
+    note = f" · {esc(confidence)} confidence" if confidence else ""
+    return (
+        '<div class="nw-health">'
+        f'<span class="v">{value:.0f}</span><span class="m">/100 health score{note}</span>'
+        "</div>"
+        f'<div class="nw-meter"><span style="width:{max(2, min(100, value)):.0f}%;'
+        f'background:{colour}"></span></div>'
+    )
+
+
+def thumb(product: dict) -> str:
+    url = product.get("image_url")
+    if url and not isinstance(url, float):
+        return f'<img class="nw-thumb" src="{esc(url)}" loading="lazy" alt="">'
+    return '<div class="nw-thumb nw-thumb-empty">🥫</div>'
+
+
+def chips(tags, tone: str = "", limit: int = 12, strip_prefix: bool = True) -> str:
+    """Render OFF tags as chips: 'en:peanuts' -> 'peanuts'."""
+    items = sorted(tag_set(tags)) if not isinstance(tags, list) else list(tags)
+    if not items:
+        return ""
+    out = []
+    for tag in items[:limit]:
+        label = tag.split(":", 1)[-1].replace("-", " ") if strip_prefix else tag
+        out.append(f'<span class="nw-chip {tone}">{esc(label)}</span>')
+    if len(items) > limit:
+        out.append(f'<span class="nw-chip">+{len(items) - limit} more</span>')
+    return '<div class="nw-chips">' + "".join(out) + "</div>"
+
+
+def title_of(product: dict) -> str:
+    name = product.get("product_name")
+    return esc(name) if name and not isinstance(name, float) else "Unnamed product"
+
+
+def brand_of(product: dict) -> str:
+    brands = product.get("brands")
+    if not brands or isinstance(brands, float):
+        return ""
+    # OFF stores brands as a comma-separated string, often with duplicates.
+    seen, out = set(), []
+    for b in str(brands).split(","):
+        b = b.strip()
+        if b and b.lower() not in seen:
+            seen.add(b.lower())
+            out.append(b)
+    return esc(", ".join(out[:2]))

components/cards.py

@@ -0,0 +1,119 @@
+"""Product cards and the verdict panel."""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from components import badges
+from nutriweb.reco.engine import Recommendation
+from nutriweb.reco.filters import Verdict
+
+
+def product_card(product: dict, *, key: str, on_open, cta: str = "View details") -> None:
+    """A search-result card with an action button beneath it."""
+    st.markdown(
+        f"""<div class="nw-card">
+            {badges.thumb(product)}
+            <h4>{badges.title_of(product)}</h4>
+            <div class="nw-brand">{badges.brand_of(product) or "&nbsp;"}</div>
+            {badges.badge_row(product)}
+            {badges.health_meter(product.get("health_score"))}
+        </div>""",
+        unsafe_allow_html=True,
+    )
+    if st.button(cta, key=key, width='stretch'):
+        on_open(product["code"])
+
+
+def recommendation_card(rec: Recommendation, *, key: str, on_open) -> None:
+    """A recommendation card. Always states why this specific swap was chosen."""
+    product = rec.product
+    warning = ""
+    if rec.warnings:
+        warning = (
+            '<div class="nw-why" style="color:#8A6D00">⚠︎ '
+            + badges.esc("; ".join(rec.warnings))
+            + "</div>"
+        )
+
+    st.markdown(
+        f"""<div class="nw-card">
+            {badges.thumb(product)}
+            <h4>{badges.title_of(product)}</h4>
+            <div class="nw-brand">{badges.brand_of(product) or "&nbsp;"}</div>
+            <span class="nw-gain">+{rec.health_gain:.0f} health</span>
+            {badges.badge_row(product)}
+            <div class="nw-why">{badges.esc(rec.why)}</div>
+            {warning}
+        </div>""",
+        unsafe_allow_html=True,
+    )
+    if st.button("View details", key=key, width='stretch'):
+        on_open(product["code"])
+
+
+def verdict_panel(verdict: Verdict, profile_is_empty: bool = False) -> None:
+    """The "is this for you" panel.
+
+    Driven by the same `filters.evaluate` the engine uses, so what the user is
+    told here always matches what the recommender actually did.
+    """
+    if profile_is_empty:
+        st.markdown(
+            '<div class="nw-verdict v-warn"><h5>No profile set</h5>'
+            "<div>Add your allergens and dietary preferences to see whether this "
+            "product suits you.</div></div>",
+            unsafe_allow_html=True,
+        )
+        return
+
+    tone = "v-block" if verdict.blockers else ("v-warn" if verdict.warnings else "v-ok")
+    icon = "✕" if verdict.blockers else ("!" if verdict.warnings else "✓")
+    items = "".join(
+        f"<li>{badges.esc(m)}</li>" for m in (*verdict.blockers, *verdict.warnings)
+    )
+    body = f"<ul>{items}</ul>" if items else "<div>Nothing in your profile conflicts with this product.</div>"
+
+    st.markdown(
+        f'<div class="nw-verdict {tone}"><h5>{icon} {badges.esc(verdict.summary)}</h5>{body}</div>',
+        unsafe_allow_html=True,
+    )
+
+
+def nutrient_table(product: dict, reference: dict | None = None) -> str:
+    """Per-100g nutrient table with bars scaled to a reference intake.
+
+    Bars are relative to a rough per-100g share of an adult reference intake,
+    so they answer "is this a lot?" rather than just restating the number.
+    """
+    rows = [
+        ("Energy", "energy_kcal_100g", "kcal", 200.0),
+        ("Fat", "fat_100g", "g", 17.5),
+        ("  of which saturates", "saturated_fat_100g", "g", 5.0),
+        ("Carbohydrates", "carbohydrates_100g", "g", 45.0),
+        ("  of which sugars", "sugars_100g", "g", 22.5),
+        ("Fibre", "fiber_100g", "g", 7.5),
+        ("Protein", "proteins_100g", "g", 25.0),
+        ("Salt", "salt_derived", "g", 1.5),
+    ]
+    from nutriweb.util import num
+
+    out = ['<table class="nw-nutri">']
+    for label, col, unit, high in rows:
+        value = num(product.get(col))
+        if value is None:
+            out.append(
+                f'<tr><td class="n">{badges.esc(label)}</td>'
+                f'<td class="v nw-sub">—</td><td></td></tr>'
+            )
+            continue
+        pct = max(2.0, min(100.0, value / high * 100.0))
+        over = " over" if value > high else ""
+        out.append(
+            f'<tr><td class="n">{badges.esc(label)}</td>'
+            f'<td class="v">{value:.1f} {unit}</td>'
+            f'<td><div class="nw-bar"><span class="{over.strip()}" '
+            f'style="width:{pct:.0f}%"></span></div></td></tr>'
+        )
+    out.append("</table>")
+    return "".join(out)

data/additives.json

@@ -0,0 +1,1327 @@
+{
+ "en:e100": {
+  "concern": "watch",
+  "e_number": "100",
+  "name": "E100 - Curcumin",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e104": {
+  "concern": "watch",
+  "e_number": "104",
+  "name": "E104 - Quinoline yellow",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e110": {
+  "concern": "watch",
+  "e_number": "110",
+  "name": "E110 - Sunset yellow FCF",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e124": {
+  "concern": "watch",
+  "e_number": "124",
+  "name": "E124 - Ponceau 4r",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e129": {
+  "concern": "watch",
+  "e_number": "129",
+  "name": "E129 - Allura red",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e131": {
+  "concern": "moderate",
+  "e_number": "131",
+  "name": "E131 - Patent blue v",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e133": {
+  "concern": "moderate",
+  "e_number": "133",
+  "name": "E133 - Brilliant blue FCF",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e141": {
+  "concern": "watch",
+  "e_number": "141",
+  "name": "E141 - Copper complexes of chlorophylls and chlorophyllins",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e141i": {
+  "concern": "watch",
+  "e_number": "141",
+  "name": "E141i - Copper complexes of chlorophylls",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e141ii": {
+  "concern": "watch",
+  "e_number": "141",
+  "name": "E141ii - Copper complexes of chlorophyllins",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e142": {
+  "concern": "moderate",
+  "e_number": "142",
+  "name": "E142 - Green s",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e150a": {
+  "concern": "watch",
+  "e_number": "150a",
+  "name": "E150a - Plain caramel",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e150b": {
+  "concern": "watch",
+  "e_number": "150b",
+  "name": "E150b - Caustic sulphite caramel",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e150c": {
+  "concern": "moderate",
+  "e_number": "150c",
+  "name": "E150c - Ammonia caramel",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e150d": {
+  "concern": "watch",
+  "e_number": "150d",
+  "name": "E150d - Sulphite ammonia caramel",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e155": {
+  "concern": "high",
+  "e_number": "155",
+  "name": "E155 - Brown ht",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e160ai": {
+  "concern": "watch",
+  "e_number": "160a",
+  "name": "E160ai - Beta-carotene",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e160aii": {
+  "concern": "watch",
+  "e_number": "160a",
+  "name": "E160aii - Plant carotenes",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e160b": {
+  "concern": "watch",
+  "e_number": "160b",
+  "name": "E160b - Annatto",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e160e": {
+  "concern": "watch",
+  "e_number": "160e",
+  "name": "E160e - Beta-apo-8\u2032-carotenal (c30)",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e160f": {
+  "concern": "watch",
+  "e_number": "160f",
+  "name": "E160f - Ethyl ester of beta-apo-8'-carotenic acid (C 30)",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e161b": {
+  "concern": "watch",
+  "e_number": "161b",
+  "name": "E161b - Lutein",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e170": {
+  "concern": "watch",
+  "e_number": null,
+  "name": "E170 - Calcium carbonates",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e171": {
+  "concern": "watch",
+  "e_number": "171",
+  "name": "E171 - Titanium dioxide",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e172": {
+  "concern": "watch",
+  "e_number": "172",
+  "name": "E172 - Iron oxides and iron hydroxides",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e174": {
+  "concern": "watch",
+  "e_number": "174",
+  "name": "E174 - Silver",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e180": {
+  "concern": "watch",
+  "e_number": "180",
+  "name": "E180 - Litholrubine bk",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e200": {
+  "concern": "high",
+  "e_number": "200",
+  "name": "E200 - Sorbic acid",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e202": {
+  "concern": "high",
+  "e_number": "202",
+  "name": "E202 - Potassium sorbate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e210": {
+  "concern": "high",
+  "e_number": "210",
+  "name": "E210 - Benzoic acid",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e211": {
+  "concern": "high",
+  "e_number": "211",
+  "name": "E211 - Sodium benzoate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e212": {
+  "concern": "high",
+  "e_number": "212",
+  "name": "E212 - Potassium benzoate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e213": {
+  "concern": "high",
+  "e_number": "213",
+  "name": "E213 - Calcium benzoate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e220": {
+  "concern": "high",
+  "e_number": "220",
+  "name": "E220 - Sulphur dioxide",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e221": {
+  "concern": "high",
+  "e_number": "221",
+  "name": "E221 - Sodium sulphite",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e222": {
+  "concern": "high",
+  "e_number": "222",
+  "name": "E222 - Sodium bisulphite",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e223": {
+  "concern": "high",
+  "e_number": "223",
+  "name": "E223 - Sodium metabisulphite",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e224": {
+  "concern": "high",
+  "e_number": "224",
+  "name": "E224 - Potassium metabisulphite",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e225": {
+  "concern": "watch",
+  "e_number": "225",
+  "name": "E225 - Calcium Disulphite",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e226": {
+  "concern": "high",
+  "e_number": "226",
+  "name": "E226 - Calcium sulphite",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e227": {
+  "concern": "high",
+  "e_number": "227",
+  "name": "E227 - Calcium bisulphite",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e228": {
+  "concern": "high",
+  "e_number": "228",
+  "name": "E228 - Potassium bisulphite",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e243": {
+  "concern": "watch",
+  "e_number": "243",
+  "name": "E243 - Ethyl lauroyl arginate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e249": {
+  "concern": "watch",
+  "e_number": "249",
+  "name": "E249 - Potassium nitrite",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e250": {
+  "concern": "high",
+  "e_number": "250",
+  "name": "E250 - Sodium nitrite",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e251": {
+  "concern": "high",
+  "e_number": "251",
+  "name": "E251 - Sodium nitrate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e252": {
+  "concern": "high",
+  "e_number": "252",
+  "name": "E252 - Potassium nitrate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e321": {
+  "concern": "watch",
+  "e_number": "321",
+  "name": "E321 - Butylated hydroxytoluene",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e334": {
+  "concern": "watch",
+  "e_number": "334",
+  "name": "E334 - L(+)-tartaric acid",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e335": {
+  "concern": "watch",
+  "e_number": "335",
+  "name": "E335 - Sodium tartrates",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e335i": {
+  "concern": "watch",
+  "e_number": "335",
+  "name": "E335i - Monosodium tartrate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e335ii": {
+  "concern": "watch",
+  "e_number": "335",
+  "name": "E335ii - Disodium tartrate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e336": {
+  "concern": "watch",
+  "e_number": "336",
+  "name": "E336 - Potassium tartrates",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e336i": {
+  "concern": "watch",
+  "e_number": "336",
+  "name": "E336i - Monopotassium tartrate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e336ii": {
+  "concern": "watch",
+  "e_number": "336",
+  "name": "E336ii - Dipotassium tartrate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e337": {
+  "concern": "watch",
+  "e_number": "337",
+  "name": "E337 - Potassium sodium tartrate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e338": {
+  "concern": "high",
+  "e_number": "338",
+  "name": "E338 - Phosphoric acid",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e339": {
+  "concern": "high",
+  "e_number": "339",
+  "name": "E339 - Sodium phosphates",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e339i": {
+  "concern": "watch",
+  "e_number": "339",
+  "name": "E339i - Monosodium phosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e339ii": {
+  "concern": "watch",
+  "e_number": "339",
+  "name": "E339ii - Disodium phosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e339iii": {
+  "concern": "watch",
+  "e_number": "339",
+  "name": "E339iii - Trisodium phosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e340": {
+  "concern": "high",
+  "e_number": "340",
+  "name": "E340 - Potassium phosphates",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e340i": {
+  "concern": "watch",
+  "e_number": "340",
+  "name": "E340i - Monopotassium phosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e340ii": {
+  "concern": "watch",
+  "e_number": "340",
+  "name": "E340ii - Dipotassium phosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e340iii": {
+  "concern": "watch",
+  "e_number": "340",
+  "name": "E340iii - Tripotassium phosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e341": {
+  "concern": "high",
+  "e_number": "341",
+  "name": "E341 - Calcium phosphates",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e341i": {
+  "concern": "watch",
+  "e_number": "341",
+  "name": "E341i - Monocalcium phosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e341ii": {
+  "concern": "watch",
+  "e_number": "341",
+  "name": "E341ii - Dicalcium phosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e341iii": {
+  "concern": "watch",
+  "e_number": "341",
+  "name": "E341iii - Tricalcium phosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e343": {
+  "concern": "high",
+  "e_number": "343",
+  "name": "E343 - Magnesium phosphates",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e343i": {
+  "concern": "watch",
+  "e_number": "343",
+  "name": "E343i - Monomagnesium phosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e343ii": {
+  "concern": "watch",
+  "e_number": "343",
+  "name": "E343ii - Dimagnesium phosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e354": {
+  "concern": "watch",
+  "e_number": "354",
+  "name": "E354 - Calcium tartrate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e407": {
+  "concern": "high",
+  "e_number": "407",
+  "name": "E407 - Carrageenan",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e407a": {
+  "concern": "high",
+  "e_number": "407a",
+  "name": "E407a - Processed eucheuma seaweed",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e432": {
+  "concern": "moderate",
+  "e_number": "432",
+  "name": "E432 - Polyoxyethylene sorbitan monolaurate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e433": {
+  "concern": "moderate",
+  "e_number": "433",
+  "name": "E433 - Polyoxyethylene sorbitan monooleate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e434": {
+  "concern": "moderate",
+  "e_number": "434",
+  "name": "E434 - Polyoxyethylene sorbitan monopalmitate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e435": {
+  "concern": "moderate",
+  "e_number": "435",
+  "name": "E435 - Polyoxyethylene sorbitan monostearate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e436": {
+  "concern": "moderate",
+  "e_number": "436",
+  "name": "E436 - Polyoxyethylene sorbitan tristearate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e450": {
+  "concern": "high",
+  "e_number": "450",
+  "name": "E450 - Diphosphates",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e450i": {
+  "concern": "watch",
+  "e_number": "450",
+  "name": "E450i - Disodium diphosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e450ii": {
+  "concern": "watch",
+  "e_number": "450",
+  "name": "E450ii - Trisodium diphosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e450iii": {
+  "concern": "watch",
+  "e_number": "450",
+  "name": "E450iii - Tetrasodium diphosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e450v": {
+  "concern": "watch",
+  "e_number": "450",
+  "name": "E450v - Tetrapotassium diphosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e450vi": {
+  "concern": "watch",
+  "e_number": "450",
+  "name": "E450vi - Dicalcium diphosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e450vii": {
+  "concern": "watch",
+  "e_number": "450",
+  "name": "E450vii - Calcium dihydrogen diphosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e451": {
+  "concern": "high",
+  "e_number": "451",
+  "name": "E451 - Triphosphates",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e451i": {
+  "concern": "watch",
+  "e_number": "451",
+  "name": "E451i - Pentasodium triphosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e451ii": {
+  "concern": "watch",
+  "e_number": "451",
+  "name": "E451ii - Pentapotassium triphosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e452": {
+  "concern": "high",
+  "e_number": "452",
+  "name": "E452 - Polyphosphates",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e452i": {
+  "concern": "watch",
+  "e_number": "452",
+  "name": "E452i - Sodium polyphosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e452ii": {
+  "concern": "watch",
+  "e_number": "452",
+  "name": "E452ii - Potassium polyphosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e452iii": {
+  "concern": "watch",
+  "e_number": "452",
+  "name": "E452iii - Sodium calcium polyphosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e452iv": {
+  "concern": "watch",
+  "e_number": "452",
+  "name": "E452iv - Calcium polyphosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e459": {
+  "concern": "high",
+  "e_number": "459",
+  "name": "E459 - Beta-cyclodextrine",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e460i": {
+  "concern": "watch",
+  "e_number": "460",
+  "name": "E460i - Microcrystalline cellulose",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e472e": {
+  "concern": "watch",
+  "e_number": "472e",
+  "name": "E472e - Mono- and diacetyltartaric acid esters of mono- and diglycerides of fatty acids",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e473": {
+  "concern": "high",
+  "e_number": "473",
+  "name": "E473 - Sucrose esters of fatty acids",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e474": {
+  "concern": "watch",
+  "e_number": "474",
+  "name": "E474 - Sucroglycerides",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e475": {
+  "concern": "watch",
+  "e_number": "475",
+  "name": "E475 - Polyglycerol esters of fatty acids",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e481": {
+  "concern": "high",
+  "e_number": "481",
+  "name": "E481 - Sodium stearoyl-2-lactylate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e482": {
+  "concern": "high",
+  "e_number": "482",
+  "name": "E482 - Calcium stearoyl-2-lactylate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e483": {
+  "concern": "watch",
+  "e_number": "483",
+  "name": "E483 - Stearyl tartrate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e491": {
+  "concern": "high",
+  "e_number": "491",
+  "name": "E491 - Sorbitan monostearate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e492": {
+  "concern": "high",
+  "e_number": "492",
+  "name": "E492 - Sorbitan tristearate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e493": {
+  "concern": "high",
+  "e_number": "493",
+  "name": "E493 - Sorbitan monolaurate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e494": {
+  "concern": "high",
+  "e_number": "494",
+  "name": "E494 - Sorbitan monooleate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e495": {
+  "concern": "high",
+  "e_number": "495",
+  "name": "E495 - Sorbitan monopalmitate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e507": {
+  "concern": "moderate",
+  "e_number": "507",
+  "name": "E507 - Hydrochloric acid",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e508": {
+  "concern": "moderate",
+  "e_number": "508",
+  "name": "E508 - Potassium chloride",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e509": {
+  "concern": "moderate",
+  "e_number": "509",
+  "name": "E509 - Calcium chloride",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e511": {
+  "concern": "moderate",
+  "e_number": "511",
+  "name": "E511 - Magnesium chloride",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake"
+  ]
+ },
+ "en:e520": {
+  "concern": "watch",
+  "e_number": "520",
+  "name": "E520 - Aluminium sulphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e521": {
+  "concern": "watch",
+  "e_number": "521",
+  "name": "E521 - Aluminium sodium sulphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e522": {
+  "concern": "watch",
+  "e_number": "522",
+  "name": "E522 - Aluminium potassium sulphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e523": {
+  "concern": "watch",
+  "e_number": "523",
+  "name": "E523 - Aluminium ammonium sulphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e535": {
+  "concern": "watch",
+  "e_number": "535",
+  "name": "E535 - Sodium ferrocyanide",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e536": {
+  "concern": "watch",
+  "e_number": "536",
+  "name": "E536 - Potassium ferrocyanide",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e538": {
+  "concern": "watch",
+  "e_number": "538",
+  "name": "E538 - Calcium ferrocyanide",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e541": {
+  "concern": "watch",
+  "e_number": "541",
+  "name": "E541 - Sodium aluminium phosphate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e551": {
+  "concern": "watch",
+  "e_number": "551",
+  "name": "E551 - Silicon dioxide",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e554": {
+  "concern": "watch",
+  "e_number": "554",
+  "name": "E554 - Sodium aluminium silicate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e555": {
+  "concern": "watch",
+  "e_number": "555",
+  "name": "E555 - Potassium aluminium silicate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e556": {
+  "concern": "watch",
+  "e_number": "556",
+  "name": "E556 - Calcium aluminium silicate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e558": {
+  "concern": "watch",
+  "e_number": "558",
+  "name": "E558 - Bentonite",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e559": {
+  "concern": "watch",
+  "e_number": "559",
+  "name": "E559 - Aluminium silicate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e620": {
+  "concern": "watch",
+  "e_number": "620",
+  "name": "E620 - Glutamic acid",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e621": {
+  "concern": "high",
+  "e_number": "621",
+  "name": "E621 - Monosodium glutamate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "EFSA: high risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e622": {
+  "concern": "watch",
+  "e_number": "622",
+  "name": "E622 - Monopotassium glutamate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e623": {
+  "concern": "watch",
+  "e_number": "623",
+  "name": "E623 - Calcium diglutamate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e624": {
+  "concern": "watch",
+  "e_number": "624",
+  "name": "E624 - Monoammonium glutamate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e625": {
+  "concern": "watch",
+  "e_number": "625",
+  "name": "E625 - Magnesium diglutamate",
+  "non_nutritive_sweetener": false,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e950": {
+  "concern": "watch",
+  "e_number": "950",
+  "name": "E950 - Acesulfame k",
+  "non_nutritive_sweetener": true,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e951": {
+  "concern": "none",
+  "e_number": "951",
+  "name": "E951 - Aspartame",
+  "non_nutritive_sweetener": true,
+  "reasons": []
+ },
+ "en:e952": {
+  "concern": "none",
+  "e_number": "952",
+  "name": "E952 - Cyclamic acid and its Na and Ca salts",
+  "non_nutritive_sweetener": true,
+  "reasons": []
+ },
+ "en:e954": {
+  "concern": "none",
+  "e_number": "954",
+  "name": "E954 - saccharin and its salts",
+  "non_nutritive_sweetener": true,
+  "reasons": []
+ },
+ "en:e955": {
+  "concern": "watch",
+  "e_number": "955",
+  "name": "E955 - Sucralose",
+  "non_nutritive_sweetener": true,
+  "reasons": [
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e957": {
+  "concern": "none",
+  "e_number": "957",
+  "name": "E957 - Thaumatin",
+  "non_nutritive_sweetener": true,
+  "reasons": []
+ },
+ "en:e959": {
+  "concern": "none",
+  "e_number": "959",
+  "name": "E959 - Neohesperidine dihydrochalcone",
+  "non_nutritive_sweetener": true,
+  "reasons": []
+ },
+ "en:e960": {
+  "concern": "moderate",
+  "e_number": "960",
+  "name": "E960 - Steviol glycosides",
+  "non_nutritive_sweetener": true,
+  "reasons": [
+   "EFSA: moderate risk of exceeding the acceptable daily intake",
+   "On ANSES' list of additives of interest"
+  ]
+ },
+ "en:e960a": {
+  "concern": "none",
+  "e_number": "960a",
+  "name": "E960a - Steviol glycosides from Stevia",
+  "non_nutritive_sweetener": true,
+  "reasons": []
+ },
+ "en:e961": {
+  "concern": "none",
+  "e_number": "961",
+  "name": "E961 - Neotame",
+  "non_nutritive_sweetener": true,
+  "reasons": []
+ },
+ "en:e962": {
+  "concern": "none",
+  "e_number": "962",
+  "name": "E962 - Salt of aspartame-acesulfame",
+  "non_nutritive_sweetener": true,
+  "reasons": []
+ },
+ "en:e969": {
+  "concern": "none",
+  "e_number": "969",
+  "name": "E969 - Advantame",
+  "non_nutritive_sweetener": true,
+  "reasons": []
+ }
+}

data/nutriscore_categories.json

@@ -0,0 +1,547 @@
+{
+ "fat_oil_nuts_seeds": [
+  "en:almond-butters",
+  "en:almond-flakes",
+  "en:almond-peeled-unpeeled-or-blanched",
+  "en:almonds",
+  "en:almonds-roasted-and-unsalted",
+  "en:areca-nuts",
+  "en:black-sesame",
+  "en:black-walnuts",
+  "en:blanched-almonds",
+  "en:blanched-roasted-hazelnuts",
+  "en:blanched-shelled-hazelnuts",
+  "en:boiled-chestnuts",
+  "en:brazil-nuts",
+  "en:brown-flax-seeds",
+  "en:canned-chestnut",
+  "en:cashew-butters",
+  "en:cashew-nuts",
+  "en:cedar-nuts",
+  "en:chia",
+  "en:coated-peanuts",
+  "en:coconut-butters",
+  "en:coconut-kernel-in-syrup",
+  "en:coconuts",
+  "en:cotton-seeds",
+  "en:creamy-peanut-butters",
+  "en:creamy-pure-peanut-butters",
+  "en:crunchy-peanut-butters",
+  "en:crunchy-pure-peanut-butters",
+  "en:cucurbitacea-seeds",
+  "en:dried-coconut-kernel",
+  "en:european-pine",
+  "en:flax-seeds",
+  "en:fresh-chestnuts",
+  "en:fresh-immature-coconut-kernel",
+  "en:fresh-ripe-coconut-kernel",
+  "en:fresh-walnuts",
+  "en:gold-flax-seeds",
+  "en:grated-coconut",
+  "en:grilled-and-salted-macadamia-nut",
+  "en:grilled-chestnut",
+  "en:ground-almonds",
+  "en:ground-brown-flax-seeds",
+  "en:ground-flax-seeds",
+  "en:ground-gold-flax-seeds",
+  "en:hacked-pistachios",
+  "en:hazelnut-butters",
+  "en:hazelnut-grilled-salted",
+  "en:hazelnut-powders",
+  "en:hazelnuts",
+  "en:hazelnuts-from-cervione",
+  "en:hazelnuts-from-reus",
+  "en:hazelnuts-whole",
+  "en:husked-sesame-seed",
+  "en:kola-nuts",
+  "en:korean-pine",
+  "en:macadamia-nut-butters",
+  "en:macadamia-nuts",
+  "en:marcona-almonds",
+  "en:melon-seeds",
+  "en:mixed-nut-butters",
+  "en:mustard-seeds",
+  "en:non-blanched-almonds",
+  "en:non-roasted-cashew-nuts",
+  "en:non-roasted-pumpkin-seeds",
+  "en:non-roasted-unsalted-shelled-pumpkin-seeds",
+  "en:nonpareil-almonds",
+  "en:nut-butters",
+  "en:papaver-seeds",
+  "en:peanut-butters",
+  "en:peanut-grilled-salted",
+  "en:peanuts",
+  "en:peanuts-cooked-in-water-with-salt",
+  "en:pecan-nuts",
+  "en:pine-nuts",
+  "en:pine-nuts-plain",
+  "en:pine-nuts-roasted",
+  "en:pistachio-butters",
+  "en:pistachio-butters-100",
+  "en:pistachio-kernels",
+  "en:pistachios",
+  "en:pistachios-from-bronte",
+  "en:pistachios-from-raffadali",
+  "en:pistachios-roasted-and-salted",
+  "en:plain-pecan-nuts",
+  "en:plain-pistachios",
+  "en:pumpkin-seeds",
+  "en:pure-peanut-butters",
+  "en:raw-almonds",
+  "en:raw-cashew-nuts",
+  "en:raw-hazelnuts",
+  "en:roasted-almonds",
+  "en:roasted-and-salted-almonds",
+  "en:roasted-and-salted-pecan-nuts",
+  "en:roasted-cashew-nuts",
+  "en:roasted-hazelnuts",
+  "en:roasted-hazelnuts-with-skin",
+  "en:roasted-nuts",
+  "en:roasted-peanuts",
+  "en:roasted-pecan-nuts",
+  "en:roasted-pistachios",
+  "en:roasted-pumpkin-seeds",
+  "en:roasted-shelled-pumpkin-seeds",
+  "en:roasted-shelled-sunflower-seeds",
+  "en:roasted-sunflower-seeds",
+  "en:roasted-unshelled-pumpkin-seeds",
+  "en:roasted-unshelled-sunflower-seeds",
+  "en:safflower-seeds",
+  "en:salted-almonds",
+  "en:salted-brazil-nuts",
+  "en:salted-cashews",
+  "en:salted-peanuts",
+  "en:salted-pecan-nuts",
+  "en:salted-pistachios",
+  "en:sesame",
+  "en:shelled-almonds",
+  "en:shelled-brazil-nuts",
+  "en:shelled-chestnuts",
+  "en:shelled-hazelnuts",
+  "en:shelled-hazelnuts-with-skin",
+  "en:shelled-macadamia-nuts",
+  "en:shelled-pine-nuts",
+  "en:shelled-pumpkin-seeds",
+  "en:shelled-sunflower-seeds",
+  "en:siberian-pine",
+  "en:slivered-almonds",
+  "en:sunflower-seed-grilled-and-salted",
+  "en:sunflower-seeds",
+  "en:toasted-sesame",
+  "en:unroasted-almonds",
+  "en:unsalted-almonds",
+  "en:unsalted-brazil-nuts",
+  "en:unsalted-cashews",
+  "en:unsalted-hazelnuts",
+  "en:unsalted-pistachios",
+  "en:unshelled-almonds",
+  "en:unshelled-brazil-nuts",
+  "en:unshelled-hazelnuts",
+  "en:unshelled-peanuts",
+  "en:unshelled-pistachios",
+  "en:unshelled-pumpkin-seeds",
+  "en:unshelled-sunflower-seeds",
+  "en:walnut-butters",
+  "en:walnut-kernels",
+  "en:walnuts",
+  "en:walnuts-from-grenoble",
+  "en:walnuts-from-the-perigord",
+  "en:wasabi-coated-peanuts",
+  "en:white-almond-butters",
+  "en:whole-almond-purees",
+  "en:whole-almonds",
+  "es:almendra-de-mallorca",
+  "fr:amandes-hachees",
+  "fr:chataigne-d-ardeche",
+  "it:marrone-del-mugello",
+  "it:marrone-della-valle-di-susa",
+  "it:marrone-di-caprese-michelangelo",
+  "it:marrone-di-castel-del-rio",
+  "it:marrone-di-combai",
+  "it:marrone-di-roccadaspide",
+  "it:marrone-di-san-zeno",
+  "it:marrone-di-serino",
+  "it:pinoli-del-tirreno",
+  "nl:katjang-pedis",
+  "nl:witte-chiazaad"
+ ],
+ "red_meat": [
+  "de:bayerisches-rindfleisch",
+  "en:arrotolata-pancetta",
+  "en:back-bacon",
+  "en:bacon",
+  "en:bacon-covered-with-cornmeal",
+  "en:bacon-rashers",
+  "en:beef",
+  "en:beef-bacon",
+  "en:beef-blood",
+  "en:beef-bolar-blade",
+  "en:beef-cheek",
+  "en:beef-chuck",
+  "en:beef-flank-steak",
+  "en:beef-from-bazas",
+  "en:beef-from-chalosse",
+  "en:beef-from-charolles",
+  "en:beef-from-maine",
+  "en:beef-from-vendee",
+  "en:beef-front-quarter",
+  "en:beef-hanger-steak",
+  "en:beef-heart",
+  "en:beef-kidney",
+  "en:beef-knuckle",
+  "en:beef-livers",
+  "en:beef-marrowbone",
+  "en:beef-offals",
+  "en:beef-oxtail",
+  "en:beef-rib-steak",
+  "en:beef-ribs",
+  "en:beef-round",
+  "en:beef-rump-steak",
+  "en:beef-short-ribs",
+  "en:beef-shoulder",
+  "en:beef-sirloin-steak",
+  "en:beef-sirloin-steak-red-label",
+  "en:beef-steaks",
+  "en:beef-stew-meat",
+  "en:beef-thin-flank",
+  "en:beef-tongues",
+  "en:beef-topside",
+  "en:boiled-beef-knuckle",
+  "en:boiled-beef-oxtail",
+  "en:braised-beef",
+  "en:braised-beef-cheek",
+  "en:braised-beef-chuck",
+  "en:braised-beef-neck",
+  "en:braised-beef-short-ribs",
+  "en:braised-lamb-kidneys",
+  "en:braised-lamb-leg",
+  "en:braised-lamb-neck",
+  "en:braised-pork-brain",
+  "en:braised-pork-spare-ribs",
+  "en:braised-veal-shoulder",
+  "en:calf-brain",
+  "en:calf-foot",
+  "en:calf-kidney",
+  "en:calf-liver",
+  "en:calf-sweetbread",
+  "en:calf-tongue",
+  "en:cambrian-mountains-lamb",
+  "en:canned-sheep-meat",
+  "en:chop-grilled-lamb-rib",
+  "en:comeragh-mountain-lamb",
+  "en:connemara-hill-lamb",
+  "en:cooked-beef-heart",
+  "en:cooked-beef-kidney",
+  "en:cooked-beef-meat",
+  "en:cooked-beef-round",
+  "en:cooked-beef-tongue",
+  "en:cooked-calf-brain",
+  "en:cooked-calf-liver",
+  "en:cooked-calf-tongue",
+  "en:cooked-ground-beef-steaks",
+  "en:cooked-lamb-brains",
+  "en:cooked-lamb-chops",
+  "en:cooked-lamb-hearts",
+  "en:cooked-lamb-liver",
+  "en:cooked-lamb-meat",
+  "en:cooked-lamb-sweetbread",
+  "en:cooked-minced-beef-steak-with-10-fat",
+  "en:cooked-minced-beef-steak-with-15-fat",
+  "en:cooked-minced-beef-steak-with-20-fat",
+  "en:cooked-minced-beef-steak-with-5-fat",
+  "en:cooked-pork-filet-mignon",
+  "en:cooked-pork-ham-escalope",
+  "en:cooked-pork-kidneys",
+  "en:cooked-pork-liver",
+  "en:cooked-pork-loin",
+  "en:cooked-pork-meat",
+  "en:cooked-pork-racks",
+  "en:cooked-pork-roast",
+  "en:cooked-pork-round-steak",
+  "en:cooked-pork-shoulder",
+  "en:cooked-pork-shoulder-choice",
+  "en:cooked-pork-tenderloin-roast",
+  "en:cooked-sheep-meat",
+  "en:cooked-veal-escalopes",
+  "en:cooked-young-cow-liver",
+  "en:cooked-young-goat",
+  "en:coppata-pancetta",
+  "en:cured-pork-loin",
+  "en:cvarci-dry-bacon",
+  "en:devilled-pork-shoulder-in-mustard-sauce",
+  "en:dry-bacon",
+  "en:dry-cured-ham-with-fat-and-rind-removed",
+  "en:fleica-dry-bacon",
+  "en:french-pork",
+  "en:fresh-ground-beef-steaks",
+  "en:fried-pork-rind",
+  "en:frozen-beef-cheek",
+  "en:frozen-beef-flank-steak",
+  "en:frozen-beef-front-quarter",
+  "en:frozen-beef-knuckle",
+  "en:frozen-beef-marrowbone",
+  "en:frozen-beef-offals",
+  "en:frozen-beef-rib-steak",
+  "en:frozen-beef-ribs",
+  "en:frozen-beef-round",
+  "en:frozen-beef-rump-steak",
+  "en:frozen-beef-shoulder",
+  "en:frozen-beef-sirloin-steak",
+  "en:frozen-ground-beef-meats",
+  "en:frozen-ground-beef-steaks",
+  "en:frozen-ground-pork-meat",
+  "en:frozen-ground-sheep-meat",
+  "en:frozen-lamb-breast",
+  "en:frozen-lamb-fat",
+  "en:frozen-lamb-leg",
+  "en:frozen-lamb-loin",
+  "en:frozen-lamb-meat",
+  "en:frozen-lamb-offals",
+  "en:frozen-lamb-rack",
+  "en:frozen-lamb-shank",
+  "en:frozen-marbled-beef-ribs",
+  "en:frozen-mutton-shoulder",
+  "en:frozen-pork-belly",
+  "en:frozen-pork-jowl",
+  "en:frozen-pork-knuckle",
+  "en:frozen-pork-loin",
+  "en:frozen-pork-meat",
+  "en:frozen-pork-offals",
+  "en:frozen-pork-shoulders",
+  "en:frozen-pork-tenderloin-lean",
+  "en:frozen-pork-way-leg-without-rind-fat-and-bone",
+  "en:frozen-sheep-meat",
+  "en:frozen-veal-chop",
+  "en:frozen-veal-fillets",
+  "en:frozen-veal-knuckle",
+  "en:frozen-veal-neck",
+  "en:frozen-veal-offals",
+  "en:frozen-veal-rump-steak",
+  "en:frozen-veal-shin",
+  "en:frozen-veal-shoulder",
+  "en:goat-meat",
+  "en:gower-salt-marsh-lamb",
+  "en:grilled-beef-bolar-blade",
+  "en:grilled-beef-flank-steak",
+  "en:grilled-beef-hanger-steak",
+  "en:grilled-beef-rump-steak",
+  "en:grilled-beef-sirloin-steak",
+  "en:grilled-beef-steaks",
+  "en:grilled-beef-thin-flank",
+  "en:grilled-beef-topside",
+  "en:grilled-lamb-chop-fillet",
+  "en:grilled-lamb-chops",
+  "en:grilled-lamb-cutlet",
+  "en:grilled-lamb-leg",
+  "en:grilled-lamb-saddle",
+  "en:grilled-lean-beef-rib-steak",
+  "en:grilled-pork-chops",
+  "en:grilled-veal-chop",
+  "en:grilled-veal-shoulder",
+  "en:grilled-veal-tenderloin",
+  "en:ground-beef-meats",
+  "en:ground-beef-steaks",
+  "en:ground-pork-meat",
+  "en:ground-sheep-meat",
+  "en:horse-fresh-meat",
+  "en:horse-rib-steak",
+  "en:horse-sirloin-steak",
+  "en:horse-steak",
+  "en:horse-topside",
+  "en:isle-of-man-manx-loaghtan-lamb",
+  "en:lamb-bone",
+  "en:lamb-brain",
+  "en:lamb-breast",
+  "en:lamb-carcass",
+  "en:lamb-chop",
+  "en:lamb-chop-fillet",
+  "en:lamb-cutlet",
+  "en:lamb-fat",
+  "en:lamb-heart",
+  "en:lamb-kidneys",
+  "en:lamb-leg",
+  "en:lamb-liver",
+  "en:lamb-loin",
+  "en:lamb-meat",
+  "en:lamb-neck",
+  "en:lamb-offals",
+  "en:lamb-on-skewer",
+  "en:lamb-rack",
+  "en:lamb-rib-chop",
+  "en:lamb-saddle",
+  "en:lamb-shank",
+  "en:lamb-shoulder",
+  "en:lamb-sweetbread",
+  "en:lean-lamb-shoulder",
+  "en:lomo-embuchado",
+  "en:lomo-iberico",
+  "en:lomo-iberico-bellota",
+  "en:marbled-beef-ribs",
+  "en:minced-beef-steak-with-10-fat",
+  "en:minced-beef-steak-with-15-fat",
+  "en:minced-beef-steak-with-20-fat",
+  "en:minced-beef-steak-with-5-fat",
+  "en:mutton-leg",
+  "en:mutton-shoulder",
+  "en:njeguska-dry-bacon",
+  "en:olive-veal",
+  "en:orkney-beef",
+  "en:orkney-lamb",
+  "en:pan-fried-calf-sweetbread",
+  "en:pancetta",
+  "en:pig-head",
+  "en:pig-heart",
+  "en:pigs-in-a-blanket",
+  "en:pigs-in-blankets",
+  "en:pork",
+  "en:pork-80-20-trimming",
+  "en:pork-90-10-trimming",
+  "en:pork-belly",
+  "en:pork-belly-with-flank-removed",
+  "en:pork-brain",
+  "en:pork-eye-of-shortloin",
+  "en:pork-fat",
+  "en:pork-filet-mignon",
+  "en:pork-ham-escalope",
+  "en:pork-jowl",
+  "en:pork-kidney",
+  "en:pork-knuckle",
+  "en:pork-liver",
+  "en:pork-liver-mousse",
+  "en:pork-liver-mousse-superior-quality",
+  "en:pork-loin",
+  "en:pork-offals",
+  "en:pork-racks",
+  "en:pork-ribs",
+  "en:pork-rind",
+  "en:pork-roasts",
+  "en:pork-round-steak",
+  "en:pork-salami",
+  "en:pork-shoulder-lower-half-without-rind-fat-and-bone-raw",
+  "en:pork-shoulder-upper-half-without-rind-fat-and-bone",
+  "en:pork-shoulders",
+  "en:pork-spare-ribs",
+  "en:pork-tenderloin",
+  "en:pork-tenderloin-lean",
+  "en:pork-tongue",
+  "en:pork-way-leg-without-rind-fat-and-bone",
+  "en:prepared-veal-meat",
+  "en:preserved-pork-liver",
+  "en:refrigerated-ground-beef-meats",
+  "en:rindless-pork-back-fat",
+  "en:rindless-pork-jowl",
+  "en:rindless-short-cut-bacon",
+  "en:roast-beef",
+  "en:roasted-beef-bolar-blade",
+  "en:roasted-beef-sirloin-steak",
+  "en:roasted-beef-topside",
+  "en:roasted-lamb-leg",
+  "en:roasted-lamb-shoulders",
+  "en:roasted-lean-lamb-saddle",
+  "en:roasted-lean-lamb-shoulders",
+  "en:roasted-veal-fillet",
+  "en:roasted-veal-tenderloin",
+  "en:rolled-escalope-of-pork-with-pistachios",
+  "en:salami-ungherese",
+  "en:salt-cured-pork-belly",
+  "en:salt-cured-pork-ear",
+  "en:salt-cured-pork-trotters",
+  "en:sauteed-veal-kidney",
+  "en:sauteed-veal-loin",
+  "en:saxe-fillet",
+  "en:scotch-beef",
+  "en:scotch-lamb",
+  "en:sheep-carcass",
+  "en:sheep-foot",
+  "en:sheep-head",
+  "en:sheep-meat",
+  "en:shetland-lamb",
+  "en:slanina-dry-bacon",
+  "en:sliced-bacon",
+  "en:smoked-back-bacon",
+  "en:smoked-bacon",
+  "en:smoked-bacon-covered-with-cornmeal",
+  "en:smoked-bacon-lardons",
+  "en:smoked-cooked-beef-meat",
+  "en:smoked-cooked-pork-meat",
+  "en:smoked-pork-belly",
+  "en:smoked-rindless-back-bacon-rashers",
+  "en:spianata",
+  "en:standard-rindless-and-fatless-cooked-pork-shoulder",
+  "en:steccata-pancetta",
+  "en:stufata-pancetta",
+  "en:sunculita-dry-bacon",
+  "en:tesa-pancetta",
+  "en:traditionally-farmed-gloucestershire-old-spots-pork",
+  "en:traditionally-reared-pedigree-welsh-pork",
+  "en:unsmoked-back-bacon",
+  "en:unsmoked-bacon",
+  "en:unsmoked-rindless-back-bacon-rashers",
+  "en:veal-breast",
+  "en:veal-chop",
+  "en:veal-escalopes",
+  "en:veal-fillets",
+  "en:veal-heart",
+  "en:veal-knuckle",
+  "en:veal-loin",
+  "en:veal-meat",
+  "en:veal-medallion",
+  "en:veal-minced-steak-with-15-fat",
+  "en:veal-minced-steak-with-20-fat",
+  "en:veal-neck",
+  "en:veal-offals",
+  "en:veal-orloff",
+  "en:veal-paupiette-cooked-in-oven",
+  "en:veal-rump-steak",
+  "en:veal-shin",
+  "en:veal-shoulder",
+  "en:veal-tenderloins",
+  "en:ventricina",
+  "en:welsh-beef",
+  "en:welsh-lamb",
+  "en:west-country-beef",
+  "en:west-country-lamb",
+  "en:young-cow-liver",
+  "en:young-goat",
+  "fr:agneau-de-l-aveyron",
+  "fr:agneau-de-lait-des-pyrenees",
+  "fr:agneau-de-lozere",
+  "fr:agneau-de-pauillac",
+  "fr:agneau-de-sisteron",
+  "fr:agneau-du-bourbonnais",
+  "fr:agneau-du-limousin",
+  "fr:agneau-du-perigord",
+  "fr:agneau-du-poitou-charentes",
+  "fr:agneau-du-quercy",
+  "fr:boeuf-charolais-du-bourbonnais",
+  "fr:echine-de-porc",
+  "fr:echine-de-porc-rotie",
+  "fr:filets-mignons-de-porc",
+  "fr:genisse-fleur-d-aubrac",
+  "fr:maine-anjou",
+  "fr:palette-de-porc-fumee",
+  "fr:porc-d-auvergne",
+  "fr:porc-de-franche-comte",
+  "fr:porc-de-l-aveyron",
+  "fr:porc-de-la-sarthe",
+  "fr:porc-de-normandie",
+  "fr:porc-de-vendee",
+  "fr:porc-du-limousin",
+  "fr:porc-du-sud-ouest",
+  "fr:porc-noir-de-bigorre",
+  "fr:pres-sales-de-la-baie-de-somme",
+  "fr:pres-sales-du-mont-saint-michel",
+  "fr:ribs-de-boeuf-sauce-barbecue",
+  "fr:souris-d-agneau",
+  "fr:steak-hache-de-porc",
+  "fr:taureau-de-camargue",
+  "fr:veau-d-aveyron-et-du-segala",
+  "fr:veau-du-limousin",
+  "it:pancetta-di-calabria",
+  "it:pancetta-piacentina",
+  "sv:h\u00e5nnlamb",
+  "tr:uykuluk-\u015fi\u015f",
+  "xx:kakuni",
+  "xx:yakibuta"
+ ]
+}

nutriweb/data/__init__.py

@@ -0,0 +1 @@
+"""DuckDB catalog access."""

nutriweb/data/catalog.py

@@ -0,0 +1,235 @@
+"""Read access to the curated DuckDB catalog.
+
+The catalog is built offline by `pipeline/` and downloaded from the Hugging
+Face Hub at app startup. Everything here is read-only and query-time.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from functools import lru_cache
+from pathlib import Path
+
+import duckdb
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+DEFAULT_CATALOG = REPO_ROOT / "data" / "nutriweb-us.duckdb"
+
+# Set to a HF dataset repo id to fetch the catalog at startup instead of
+# expecting it on local disk (this is how the Space runs).
+CATALOG_REPO = os.environ.get("NUTRIWEB_CATALOG_REPO", "")
+CATALOG_FILENAME = "nutriweb-us.duckdb"
+
+# Columns the UI needs. Selecting explicitly keeps result frames small --
+# `catalog` carries the full tag arrays, which are heavy to materialise.
+PRODUCT_COLUMNS = """
+    code, product_name, generic_name, brands, quantity, serving_size,
+    image_url, ingredients_text, primary_category, categories_tags,
+    ingredients_tags, allergens_tags, traces_tags, additives_tags,
+    labels_tags, ingredients_analysis_tags, nutrient_levels_tags,
+    energy_kcal_100g, energy_kj_derived, fat_100g, saturated_fat_100g,
+    carbohydrates_100g, sugars_100g, fiber_100g, proteins_100g,
+    salt_derived, sodium_100g, fruits_veg_derived,
+    nova_group, environmental_score_grade,
+    nutriscore_grade, nutriscore_grade_off, nutriscore_grade_computed,
+    nutriscore_score_computed, nutriscore_source,
+    health_score, health_confidence, additive_penalty, n_flagged_additives,
+    is_beverage, unique_scans_n
+"""
+
+
+def catalog_path() -> Path:
+    """Local path to the catalog, downloading it from the Hub if configured."""
+    if CATALOG_REPO:
+        from huggingface_hub import hf_hub_download
+
+        return Path(
+            hf_hub_download(
+                repo_id=CATALOG_REPO, filename=CATALOG_FILENAME, repo_type="dataset"
+            )
+        )
+    return DEFAULT_CATALOG
+
+
+@lru_cache(maxsize=1)
+def _database() -> duckdb.DuckDBPyConnection:
+    """Open the catalog read-only, once per process."""
+    path = catalog_path()
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Catalog not found at {path}. Build it with:\n"
+            "  python pipeline/01_download.py\n"
+            "  python pipeline/02_curate.py\n"
+            "  python pipeline/03_score.py"
+        )
+    con = duckdb.connect(str(path), read_only=True)
+    _try_load_fts(con)
+    return con
+
+
+def _try_load_fts(con: duckdb.DuckDBPyConnection) -> bool:
+    """Best-effort load of the full-text-search extension.
+
+    Must never raise. The extension is present on the machine that builds the
+    catalog but not in a fresh container, and an unconditional `LOAD fts` there
+    takes the whole app down on startup.
+
+    In practice the BM25 macros are persisted inside the catalog file and work
+    without the extension, so this is belt-and-braces: if it cannot be loaded
+    we fall back to a LIKE search rather than failing.
+    """
+    for statement in ("LOAD fts", "INSTALL fts; LOAD fts"):
+        try:
+            con.execute(statement)
+            return True
+        except duckdb.Error:
+            continue
+    return False
+
+
+# Streamlit runs every user session on its own thread, and a DuckDB connection
+# is not safe to share across them: two threads interleaving execute() and
+# fetchdf() will consume each other's result sets, which surfaces as sporadic
+# None results rather than a clean error. Each thread therefore gets its own
+# cursor -- a lightweight handle onto the same open database, with its own
+# result set.
+_local = threading.local()
+
+
+def connect() -> duckdb.DuckDBPyConnection:
+    """Return this thread's cursor onto the catalog."""
+    con = getattr(_local, "con", None)
+    if con is None:
+        con = _database().cursor()
+        _try_load_fts(con)
+        _local.con = con
+    return con
+
+
+def get_product(code: str) -> dict | None:
+    """Fetch one product by barcode, tolerating leading-zero variants.
+
+    OFF stores EAN-13, but a scanner or a user may supply the UPC-A form
+    without the leading zero, so we try both.
+    """
+    code = str(code).strip()
+    con = connect()
+    row = con.execute(
+        f"SELECT {PRODUCT_COLUMNS} FROM catalog WHERE code = ?", [code]
+    ).fetchdf()
+    if row.empty and code.isdigit():
+        variants = [code.lstrip("0"), code.zfill(13), code.zfill(12)]
+        row = con.execute(
+            f"SELECT {PRODUCT_COLUMNS} FROM catalog WHERE code IN "
+            f"({','.join('?' * len(variants))}) LIMIT 1",
+            variants,
+        ).fetchdf()
+    return None if row.empty else row.iloc[0].to_dict()
+
+
+def search(query: str, limit: int = 30) -> list[dict]:
+    """Full-text search over product name and brand.
+
+    Uses the BM25 index built in the pipeline. The app this replaces scanned
+    every row with `str.contains`, which does not rank and cannot use an index.
+    Results are biased toward products we can actually score and toward
+    popular items, so the first page is useful rather than merely matching.
+    """
+    query = (query or "").strip()
+    if not query:
+        return []
+
+    con = connect()
+    # A bare digit string is a barcode, not a search term.
+    if query.isdigit() and len(query) >= 8:
+        product = get_product(query)
+        return [product] if product else []
+
+    try:
+        df = con.execute(
+            f"""
+            WITH scored AS (
+                SELECT code, fts_main_products.match_bm25(code, ?) AS relevance
+                FROM products
+            )
+            SELECT {PRODUCT_COLUMNS}, relevance
+            FROM scored JOIN catalog USING (code)
+            WHERE relevance IS NOT NULL
+            ORDER BY
+                relevance * (CASE WHEN health_score IS NOT NULL THEN 1.0 ELSE 0.4 END)
+                    * (1 + ln(1 + COALESCE(unique_scans_n, 0)) / 10) DESC
+            LIMIT ?
+            """,
+            [query, limit],
+        ).fetchdf()
+        return df.to_dict("records")
+    except duckdb.Error:
+        # The BM25 macros live in the catalog file and normally work without
+        # the extension, but if anything about full-text search is unavailable
+        # a degraded search beats a broken page.
+        return _search_without_fts(query, limit)
+
+
+def _search_without_fts(query: str, limit: int) -> list[dict]:
+    """Substring search fallback, used only when BM25 is unavailable.
+
+    Ranks a name match above a brand match and a prefix above a mid-word hit,
+    then favours popular, scoreable products -- roughly what BM25 gives us,
+    without needing the extension.
+    """
+    pattern = f"%{query.lower()}%"
+    prefix = f"{query.lower()}%"
+    df = connect().execute(
+        f"""
+        SELECT {PRODUCT_COLUMNS}
+        FROM catalog
+        WHERE lower(product_name) LIKE ? OR lower(COALESCE(brands, '')) LIKE ?
+        ORDER BY
+            (CASE WHEN lower(product_name) LIKE ? THEN 2
+                  WHEN lower(product_name) LIKE ? THEN 1
+                  ELSE 0 END) DESC,
+            (CASE WHEN health_score IS NOT NULL THEN 1 ELSE 0 END) DESC,
+            COALESCE(unique_scans_n, 0) DESC
+        LIMIT ?
+        """,
+        [pattern, pattern, prefix, pattern, limit],
+    ).fetchdf()
+    return df.to_dict("records")
+
+
+@lru_cache(maxsize=1)
+def macro_stats() -> dict[str, tuple[float, float]]:
+    """Per-nutrient (mean, std) used to z-score the macro vector."""
+    from pipeline.config import MACRO_COLUMNS
+
+    row = connect().execute("SELECT * FROM macro_stats").fetchdf().iloc[0]
+    return {
+        col: (float(row[f"{col}_mean"]), float(row[f"{col}_std"]) or 1.0)
+        for col in MACRO_COLUMNS
+    }
+
+
+def category_sizes(tags: list[str]) -> dict[str, int]:
+    """How many scored products sit under each of these category tags."""
+    if not tags:
+        return {}
+    placeholders = ",".join("?" * len(tags))
+    rows = connect().execute(
+        f"SELECT tag, n FROM category_sizes WHERE tag IN ({placeholders})", list(tags)
+    ).fetchall()
+    return dict(rows)
+
+
+def stats() -> dict:
+    """Headline catalog numbers, shown on the Insights page."""
+    return connect().execute("""
+        SELECT
+            count(*) AS products,
+            count(health_score) AS scored,
+            count(*) FILTER (WHERE nutriscore_source = 'off') AS graded_by_off,
+            count(*) FILTER (WHERE nutriscore_source = 'nutriweb') AS graded_by_nutriweb,
+            count(*) FILTER (WHERE image_url IS NOT NULL) AS with_image,
+            count(DISTINCT primary_category) AS categories
+        FROM catalog
+    """).fetchdf().iloc[0].to_dict()

nutriweb/profile/__init__.py

@@ -0,0 +1 @@
+"""User profiles and authentication."""

nutriweb/profile/auth.py

@@ -0,0 +1,184 @@
+"""Accounts and profile persistence.
+
+Two changes from the app this replaces:
+
+  * Passwords are hashed with bcrypt. The previous version stored them in
+    plaintext and compared with `user["password"] == login_pw`.
+  * MongoDB is optional. If no connection string is configured the app runs in
+    a session-only demo mode instead of crashing on import, so it can be
+    developed and reviewed without a database.
+
+Set MONGODB_URI as a Hugging Face Space repository secret -- never in a file.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+import bcrypt
+import streamlit as st
+
+from nutriweb.profile.model import UserProfile
+
+# bcrypt hashes at most 72 bytes and raises on anything longer (it used to
+# truncate silently). Truncating here is the standard handling and keeps long
+# passphrases usable.
+BCRYPT_MAX_BYTES = 72
+
+
+def _encode(password: str) -> bytes:
+    return (password or "").encode("utf-8")[:BCRYPT_MAX_BYTES]
+
+
+def _hash(password: str) -> str:
+    return bcrypt.hashpw(_encode(password), bcrypt.gensalt()).decode()
+
+
+@dataclass
+class AuthResult:
+    ok: bool
+    message: str = ""
+    profile: UserProfile | None = None
+
+
+def _uri() -> str:
+    """Read the connection string, environment first.
+
+    Order matters. Hugging Face Space secrets arrive as environment variables,
+    and a stale `.streamlit/secrets.toml` left in the working tree must never
+    be able to override an explicitly-set variable -- reading the file first
+    silently redirected connections to an old cluster, which is exactly the
+    kind of failure that is invisible until it matters.
+    """
+    from_env = os.environ.get("MONGODB_URI", "").strip()
+    if from_env:
+        return from_env
+    try:
+        if "MONGODB_URI" in st.secrets:
+            return str(st.secrets["MONGODB_URI"])
+    except Exception:
+        pass  # no secrets.toml at all is the normal local state
+    return ""
+
+
+@st.cache_resource(show_spinner=False)
+def _collections():
+    """Return (users, history) collections, or (None, None) in demo mode."""
+    uri = _uri()
+    if not uri:
+        return None, None
+    try:
+        from pymongo import MongoClient
+
+        client = MongoClient(uri, serverSelectionTimeoutMS=5000)
+        client.admin.command("ping")
+        db_name = os.environ.get("MONGO_DB_NAME", "nutriweb_db")
+        try:
+            db_name = str(st.secrets.get("MONGO_DB_NAME", db_name))
+        except Exception:
+            pass
+        db = client[db_name]
+        return db["users"], db["history"]
+    except Exception as exc:  # unreachable database must not break the app
+        st.warning(f"Could not reach the account database ({exc}). Running in demo mode.")
+        return None, None
+
+
+def _verify(password: str, hashed: str) -> bool:
+    """Check a password without raising on a missing or malformed hash.
+
+    bcrypt raises on an empty or unrecognised hash string, which would turn a
+    corrupted record into a crash rather than a failed login.
+    """
+    if not hashed:
+        return False
+    try:
+        return bcrypt.checkpw(_encode(password), hashed.encode("utf-8"))
+    except (ValueError, TypeError):
+        return False
+
+
+def demo_mode() -> bool:
+    users, _ = _collections()
+    return users is None
+
+
+def _demo_store() -> dict:
+    return st.session_state.setdefault("_demo_users", {})
+
+
+def register(user_id: str, password: str, profile: UserProfile) -> AuthResult:
+    user_id = (user_id or "").strip()
+    if not user_id or not password:
+        return AuthResult(False, "Pick a username and a password.")
+    if len(password) < 8:
+        return AuthResult(False, "Use at least 8 characters for the password.")
+
+    record = {"_id": user_id, "password_hash": _hash(password), **profile.to_dict()}
+    users, _ = _collections()
+
+    if users is None:
+        store = _demo_store()
+        if user_id in store:
+            return AuthResult(False, "That username is taken.")
+        store[user_id] = record
+    else:
+        from pymongo.errors import DuplicateKeyError
+
+        try:
+            users.insert_one(record)
+        except DuplicateKeyError:
+            return AuthResult(False, "That username is taken.")
+
+    profile.user_id = user_id
+    return AuthResult(True, "Account created.", profile)
+
+
+def login(user_id: str, password: str) -> AuthResult:
+    users, _ = _collections()
+    record = _demo_store().get(user_id) if users is None else users.find_one({"_id": user_id})
+
+    if not record or not _verify(password, record.get("password_hash", "")):
+        # Deliberately vague: distinguishing the two leaks which accounts exist.
+        return AuthResult(False, "Incorrect username or password.")
+
+    return AuthResult(True, "", UserProfile.from_dict(record))
+
+
+def save_profile(profile: UserProfile) -> None:
+    users, _ = _collections()
+    if users is None:
+        store = _demo_store()
+        if profile.user_id in store:
+            store[profile.user_id].update(profile.to_dict())
+    else:
+        users.update_one({"_id": profile.user_id}, {"$set": profile.to_dict()})
+
+
+def log_view(user_id: str, product: dict, verdict_summary: str) -> None:
+    """Record that a user looked at a product, for the history panel."""
+    _, history = _collections()
+    entry = {
+        "user_id": user_id,
+        "code": product.get("code"),
+        "product_name": product.get("product_name"),
+        "brands": product.get("brands"),
+        "health_score": product.get("health_score"),
+        "verdict": verdict_summary,
+    }
+    if history is None:
+        st.session_state.setdefault("_demo_history", []).insert(0, entry)
+    else:
+        from datetime import datetime, timezone
+
+        history.insert_one({**entry, "timestamp": datetime.now(timezone.utc)})
+
+
+def recent_views(user_id: str, limit: int = 25) -> list[dict]:
+    _, history = _collections()
+    if history is None:
+        return st.session_state.get("_demo_history", [])[:limit]
+    return list(
+        history.find({"user_id": user_id}).sort("timestamp", -1).limit(limit)
+    )

nutriweb/profile/model.py

@@ -0,0 +1,93 @@
+"""The user profile that drives filtering and ranking."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# Allergen options, mapped to OFF's canonical allergen tags. Using OFF's tags
+# means we match on the curated `allergens_tags`/`traces_tags` arrays rather
+# than guessing from ingredient text with regexes.
+ALLERGEN_CHOICES: dict[str, str] = {
+    "Gluten": "en:gluten",
+    "Milk / Dairy": "en:milk",
+    "Eggs": "en:eggs",
+    "Peanuts": "en:peanuts",
+    "Tree nuts": "en:nuts",
+    "Soybeans": "en:soybeans",
+    "Fish": "en:fish",
+    "Crustaceans": "en:crustaceans",
+    "Molluscs": "en:molluscs",
+    "Sesame seeds": "en:sesame-seeds",
+    "Celery": "en:celery",
+    "Mustard": "en:mustard",
+    "Sulphites": "en:sulphur-dioxide-and-sulphites",
+    "Lupin": "en:lupin",
+}
+
+DIET_CHOICES = ["Vegetarian", "Vegan", "Palm-oil free"]
+
+# Per-100g ceilings for health conditions.
+#
+# The app this replaces tested `sodium_100g > 5.0` -- five *grams* of sodium per
+# 100 g, a level essentially no food reaches, so the rule never fired. These
+# thresholds come from the FDA "high in" labelling guidance: a food is high in a
+# nutrient at 20% of the Daily Value per serving. Expressed per 100 g against
+# DVs of 2300 mg sodium and 20 g saturated fat.
+SODIUM_CEILING_G_100G = 0.46  # 20% of the 2300 mg DV
+SALT_CEILING_G_100G = SODIUM_CEILING_G_100G * 2.5
+SATURATED_FAT_CEILING_G_100G = 4.0  # 20% of the 20 g DV
+
+
+@dataclass
+class UserProfile:
+    """Everything the engine needs to know about a person.
+
+    Allergens are stored as OFF tags, not display labels, so the filters are
+    exact set operations.
+    """
+
+    user_id: str = ""
+    age: int = 30
+    gender: str = "Prefer not to say"
+    allergens: list[str] = field(default_factory=list)  # OFF tags, e.g. 'en:peanuts'
+    diets: list[str] = field(default_factory=list)  # from DIET_CHOICES
+    high_blood_pressure: bool = False
+    high_cholesterol: bool = False
+    avoid_flagged_additives: bool = False
+
+    @property
+    def wants_vegan(self) -> bool:
+        return "Vegan" in self.diets
+
+    @property
+    def wants_vegetarian(self) -> bool:
+        # Vegan is stricter than vegetarian and implies it.
+        return "Vegetarian" in self.diets or self.wants_vegan
+
+    @property
+    def wants_palm_oil_free(self) -> bool:
+        return "Palm-oil free" in self.diets
+
+    def to_dict(self) -> dict:
+        return {
+            "age": self.age,
+            "gender": self.gender,
+            "allergens": self.allergens,
+            "diets": self.diets,
+            "high_blood_pressure": self.high_blood_pressure,
+            "high_cholesterol": self.high_cholesterol,
+            "avoid_flagged_additives": self.avoid_flagged_additives,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> UserProfile:
+        return cls(
+            user_id=str(data.get("_id", data.get("user_id", ""))),
+            age=int(data.get("age", 30)),
+            gender=data.get("gender", "Prefer not to say"),
+            allergens=list(data.get("allergens", [])),
+            diets=list(data.get("diets", [])),
+            high_blood_pressure=bool(data.get("high_blood_pressure", False)),
+            high_cholesterol=bool(data.get("high_cholesterol", False)),
+            avoid_flagged_additives=bool(data.get("avoid_flagged_additives", False)),
+        )

nutriweb/reco/__init__.py

@@ -0,0 +1 @@
+"""Recommendation engine: candidate generation, profile filters, composite ranking."""

nutriweb/reco/engine.py

@@ -0,0 +1,281 @@
+"""The recommendation engine: healthier, similar, and safe for this person.
+
+Three stages, in order:
+
+  1. Candidate generation — products of the same *kind*. Constrained to a
+     shared category tag, which is what stops a soda from returning a candy
+     bar. Falls back to ingredient overlap for the ~49% of US products that
+     carry no category at all.
+
+  2. Hard filters — allergens, diet, and health-condition ceilings, applied in
+     SQL before the LIMIT so the pool is filtered rather than truncated.
+
+  3. Ranking — a weighted composite of health gain, macro similarity and
+     ingredient overlap, with every component returned so the UI can explain
+     each result rather than assert it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+import pandas as pd
+
+from nutriweb.data import catalog
+from nutriweb.profile.model import UserProfile
+from nutriweb.reco import filters, similarity
+
+# Ranking weights. They sum to 1.0 and live here so they can be justified and
+# tuned in one place rather than being scattered through the query.
+W_HEALTH_GAIN = 0.45
+W_MACRO = 0.30
+W_INGREDIENT = 0.20
+W_POPULARITY = 0.05
+
+# A category tag must cover at least this many scored products to be a usable
+# candidate pool; otherwise we widen to a more general tag.
+MIN_POOL = 12
+
+# Ceiling on how many candidates we pull into Python for ranking. Candidates
+# are ordered by popularity so the cap keeps the well-known products.
+MAX_CANDIDATES = 1500
+
+
+@dataclass
+class Recommendation:
+    product: dict
+    health_gain: float
+    macro_similarity: float
+    ingredient_similarity: float
+    score: float
+    shared_macros: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def why(self) -> str:
+        """One line explaining this specific swap."""
+        parts = [f"+{self.health_gain:.0f} health points"]
+        if self.shared_macros:
+            parts.append("similar " + ", ".join(self.shared_macros[:3]))
+        if self.ingredient_similarity >= 0.3:
+            parts.append(f"{self.ingredient_similarity * 100:.0f}% shared ingredients")
+        return " · ".join(parts)
+
+
+from nutriweb.util import tag_set as _tag_set  # noqa: E402
+
+
+def choose_category(product: dict) -> str | None:
+    """Pick the most specific category tag with a large enough candidate pool.
+
+    `categories_tags` is not reliably ordered general-to-specific, so we rank
+    the product's tags by how many products sit under each and take the
+    smallest that still clears MIN_POOL. Smallest pool == most specific.
+    """
+    tags = [
+        t for t in _tag_set(product.get("categories_tags"))
+        if t not in ("en:null", "en:undefined")
+    ]
+    if not tags:
+        return None
+
+    sizes = catalog.category_sizes(tags)
+    usable = [(n, t) for t, n in sizes.items() if n >= MIN_POOL]
+    if usable:
+        return min(usable)[1]  # smallest qualifying pool
+    # Nothing clears the bar; use the broadest tag we have rather than nothing.
+    return max(((n, t) for t, n in sizes.items()), default=(0, None))[1]
+
+
+def _candidates_by_category(
+    category: str, code: str, min_health: float, where: str, params: list
+) -> pd.DataFrame:
+    return catalog.connect().execute(
+        f"""
+        SELECT {catalog.PRODUCT_COLUMNS}
+        FROM catalog
+        WHERE list_contains(categories_tags, ?)
+          AND code <> ?
+          AND health_score IS NOT NULL
+          AND health_score > ?
+          AND {where}
+        ORDER BY COALESCE(unique_scans_n, 0) DESC
+        LIMIT {MAX_CANDIDATES}
+        """,
+        [category, code, min_health, *params],
+    ).fetchdf()
+
+
+def _candidates_by_ingredients(
+    ingredient_tags: list[str], code: str, min_health: float, where: str, params: list
+) -> pd.DataFrame:
+    """Fallback for products with no category: nearest by ingredient overlap."""
+    if not ingredient_tags:
+        return pd.DataFrame()
+    return catalog.connect().execute(
+        f"""
+        SELECT {catalog.PRODUCT_COLUMNS},
+               len(list_intersect(ingredients_tags, ?::VARCHAR[])) AS overlap
+        FROM catalog
+        WHERE list_has_any(COALESCE(ingredients_tags, []::VARCHAR[]), ?::VARCHAR[])
+          AND code <> ?
+          AND health_score IS NOT NULL
+          AND health_score > ?
+          AND {where}
+        ORDER BY overlap DESC, COALESCE(unique_scans_n, 0) DESC
+        LIMIT {MAX_CANDIDATES}
+        """,
+        [ingredient_tags, ingredient_tags, code, min_health, *params],
+    ).fetchdf()
+
+
+def recommend(
+    product: dict, profile: UserProfile, top_n: int = 8
+) -> tuple[list[Recommendation], dict]:
+    """Return ranked healthier alternatives plus a note on how they were found.
+
+    The second element describes the search (which category was used, how many
+    candidates survived filtering) so the UI can be honest when results are
+    thin rather than silently showing three items.
+    """
+    source_health = product.get("health_score")
+    if source_health is None or pd.isna(source_health):
+        return [], {"reason": "unscored", "message": "This product has no health score, so we cannot compare it."}
+
+    source_health = float(source_health)
+    where, params = filters.sql_exclusions(profile)
+
+    category = choose_category(product)
+    if category:
+        frame = _candidates_by_category(
+            category, product["code"], source_health, where, params
+        )
+        basis = {"mode": "category", "category": category}
+    else:
+        frame = _candidates_by_ingredients(
+            sorted(_tag_set(product.get("ingredients_tags"))),
+            product["code"], source_health, where, params,
+        )
+        basis = {"mode": "ingredients", "category": None}
+
+    basis["pool"] = len(frame)
+    if frame.empty:
+        basis.update(_diagnose_empty(product, source_health, category))
+        return [], basis
+
+    ranked = _rank(product, frame, source_health, profile, top_n)
+    basis["returned"] = len(ranked)
+    return ranked, basis
+
+
+def _diagnose_empty(product: dict, source_health: float, category: str | None) -> dict:
+    """Work out *why* there are no results, so the UI can say something true.
+
+    An empty pool has three quite different causes, and telling a user their
+    filters were too strict when the real answer is "this is already the best
+    product in its category" is simply wrong.
+    """
+    if category is None:
+        return {
+            "reason": "no_candidates",
+            "message": "We couldn't find comparable products to rank this against.",
+        }
+
+    # Is anything in this category healthier at all, ignoring the profile?
+    unfiltered = catalog.connect().execute(
+        """SELECT count(*) FROM catalog
+           WHERE list_contains(categories_tags, ?) AND code <> ?
+             AND health_score IS NOT NULL AND health_score > ?""",
+        [category, product["code"], source_health],
+    ).fetchone()[0]
+
+    if unfiltered == 0:
+        label = str(category).split(":", 1)[-1].replace("-", " ")
+        return {
+            "reason": "already_best",
+            "message": (
+                f"Nothing in {label} scores higher — this is already among the "
+                f"healthiest options we have ({source_health:.0f}/100)."
+            ),
+        }
+
+    return {
+        "reason": "filtered_out",
+        "filtered_out": unfiltered,
+        "message": (
+            f"{unfiltered} healthier option exists, but it did not pass your "
+            f"allergen and diet filters."
+            if unfiltered == 1
+            else f"{unfiltered} healthier options exist, but none passed your "
+                 f"allergen and diet filters."
+        ),
+    }
+
+
+def _rank(
+    product: dict,
+    frame: pd.DataFrame,
+    source_health: float,
+    profile: UserProfile,
+    top_n: int,
+) -> list[Recommendation]:
+    stats = catalog.macro_stats()
+
+    source_macros = similarity.macro_vector(product, stats)
+    candidate_macros = similarity.macro_matrix(frame, stats)
+    macro_sim = similarity.macro_similarity(source_macros, candidate_macros)
+
+    source_ingredients = _tag_set(product.get("ingredients_tags"))
+    ingredient_sim = similarity.jaccard(
+        source_ingredients, [_tag_set(t) for t in frame["ingredients_tags"]]
+    )
+
+    health = frame["health_score"].astype(float).to_numpy()
+    gain = health - source_health
+    # Normalise gain against the best available so weights stay comparable.
+    gain_norm = gain / gain.max() if gain.max() > 0 else np.zeros_like(gain)
+
+    scans = frame["unique_scans_n"].fillna(0).astype(float).to_numpy()
+    popularity = np.log1p(scans)
+    popularity = popularity / popularity.max() if popularity.max() > 0 else popularity
+
+    total = (
+        W_HEALTH_GAIN * gain_norm
+        + W_MACRO * macro_sim
+        + W_INGREDIENT * ingredient_sim
+        + W_POPULARITY * popularity
+    )
+
+    order = np.argsort(-total)[: top_n * 3]
+    results: list[Recommendation] = []
+    seen_names: set[str] = set()
+
+    for i in order:
+        row = frame.iloc[int(i)].to_dict()
+        # OFF holds many near-identical listings of the same item; collapsing on
+        # name keeps the results a real choice rather than one product repeated.
+        key = (str(row.get("product_name") or "").strip().lower(), str(row.get("brands") or "").lower())
+        if key in seen_names:
+            continue
+        seen_names.add(key)
+
+        verdict = filters.evaluate(row, profile)
+        if not verdict.passed:  # belt and braces; SQL should have excluded these
+            continue
+
+        results.append(
+            Recommendation(
+                product=row,
+                health_gain=float(gain[i]),
+                macro_similarity=float(macro_sim[i]),
+                ingredient_similarity=float(ingredient_sim[i]),
+                score=float(total[i]),
+                shared_macros=similarity.shared_macros(product, row),
+                warnings=verdict.warnings,
+            )
+        )
+        if len(results) >= top_n:
+            break
+
+    return results

nutriweb/reco/filters.py

@@ -0,0 +1,153 @@
+"""Hard safety filters — the rules a recommendation must never violate.
+
+These are deliberately separate from ranking. A product that fails any of these
+is removed, never merely demoted, so an allergen can't be outweighed by a good
+health score.
+
+The same functions power the "why this is / isn't for you" panel on the product
+page, so what the user is told always matches what the engine actually did.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from nutriweb.profile.model import (
+    SALT_CEILING_G_100G,
+    SATURATED_FAT_CEILING_G_100G,
+    UserProfile,
+)
+from nutriweb.scoring import additives as additives_mod
+from nutriweb.util import num, tag_set
+
+
+@dataclass
+class Verdict:
+    """Why a product passed or failed, in the user's terms."""
+
+    passed: bool
+    blockers: list[str]
+    warnings: list[str]
+
+    @property
+    def summary(self) -> str:
+        if self.blockers:
+            return "Not suitable for you"
+        if self.warnings:
+            return "Check before buying"
+        return "Fits your profile"
+
+
+def _tags(product: dict, key: str) -> set[str]:
+    return tag_set(product.get(key))
+
+
+def _num(product: dict, key: str) -> float | None:
+    return num(product.get(key))
+
+
+def evaluate(product: dict, profile: UserProfile) -> Verdict:
+    """Check a product against a profile.
+
+    Blockers exclude a product outright. Warnings are surfaced but do not
+    exclude -- traces and health-condition ceilings are advisory, because a
+    "may contain" label and a genuine ingredient are different risks.
+    """
+    blockers: list[str] = []
+    warnings: list[str] = []
+
+    allergens = set(profile.allergens)
+    if allergens:
+        contains = allergens & _tags(product, "allergens_tags")
+        if contains:
+            blockers.append(f"Contains {_label(contains)}")
+
+        traces = allergens & _tags(product, "traces_tags")
+        if traces:
+            warnings.append(f"May contain traces of {_label(traces)}")
+
+    analysis = _tags(product, "ingredients_analysis_tags")
+    if profile.wants_vegan:
+        if "en:non-vegan" in analysis:
+            blockers.append("Not vegan")
+        elif "en:vegan" not in analysis:
+            warnings.append("Vegan status unconfirmed")
+    elif profile.wants_vegetarian:
+        if "en:non-vegetarian" in analysis:
+            blockers.append("Not vegetarian")
+        elif "en:vegetarian" not in analysis:
+            warnings.append("Vegetarian status unconfirmed")
+
+    if profile.wants_palm_oil_free and "en:palm-oil" in analysis:
+        blockers.append("Contains palm oil")
+
+    if profile.high_blood_pressure:
+        salt = _num(product, "salt_derived")
+        if salt is not None and salt > SALT_CEILING_G_100G:
+            warnings.append(f"High in salt ({salt:.1f} g/100 g) — you flagged high blood pressure")
+
+    if profile.high_cholesterol:
+        satfat = _num(product, "saturated_fat_100g")
+        if satfat is not None and satfat > SATURATED_FAT_CEILING_G_100G:
+            warnings.append(
+                f"High in saturated fat ({satfat:.1f} g/100 g) — you flagged high cholesterol"
+            )
+
+    if profile.avoid_flagged_additives:
+        flagged = additives_mod.concerns(list(_tags(product, "additives_tags")))
+        high = [a for a in flagged if a["concern"] == "high"]
+        if high:
+            blockers.append(
+                "Contains additives flagged by EFSA: "
+                + ", ".join(a["name"] for a in high[:3])
+            )
+
+    return Verdict(passed=not blockers, blockers=blockers, warnings=warnings)
+
+
+def _label(tags: set[str]) -> str:
+    """Turn OFF tags into readable text: {'en:peanuts'} -> 'peanuts'."""
+    return ", ".join(sorted(t.split(":", 1)[-1].replace("-", " ") for t in tags))
+
+
+def sql_exclusions(profile: UserProfile) -> tuple[str, list]:
+    """Push the blocking filters into SQL so candidates are excluded up front.
+
+    Mirrors the blockers in `evaluate`. Doing this in the database avoids
+    pulling thousands of rows into Python only to discard them, and keeps the
+    candidate pool honest -- filtering after a LIMIT would silently shrink it.
+    """
+    clauses: list[str] = []
+    params: list = []
+
+    if profile.allergens:
+        clauses.append(
+            "NOT list_has_any(COALESCE(allergens_tags, []::VARCHAR[]), ?::VARCHAR[])"
+        )
+        params.append(list(profile.allergens))
+
+    if profile.wants_vegan:
+        clauses.append(
+            "NOT list_contains(COALESCE(ingredients_analysis_tags, []::VARCHAR[]), 'en:non-vegan')"
+        )
+    elif profile.wants_vegetarian:
+        clauses.append(
+            "NOT list_contains(COALESCE(ingredients_analysis_tags, []::VARCHAR[]), "
+            "'en:non-vegetarian')"
+        )
+
+    if profile.wants_palm_oil_free:
+        clauses.append(
+            "NOT list_contains(COALESCE(ingredients_analysis_tags, []::VARCHAR[]), 'en:palm-oil')"
+        )
+
+    if profile.high_blood_pressure:
+        clauses.append(f"(salt_derived IS NULL OR salt_derived <= {SALT_CEILING_G_100G})")
+
+    if profile.high_cholesterol:
+        clauses.append(
+            f"(saturated_fat_100g IS NULL OR "
+            f"saturated_fat_100g <= {SATURATED_FAT_CEILING_G_100G})"
+        )
+
+    return (" AND ".join(clauses) if clauses else "TRUE"), params

nutriweb/reco/similarity.py

@@ -0,0 +1,94 @@
+"""Similarity between products, on two axes the user cares about.
+
+The app this replaces used sentence-transformer embeddings over ingredient
+text, searched with FAISS. That approach had three problems: the index was
+rebuilt on every query, the embeddings had to be downloaded from Google Drive,
+and the similarity it measured was over free text that OFF has *already*
+canonicalised.
+
+Open Food Facts resolves every ingredient to a taxonomy tag, so set overlap on
+`ingredients_tags` measures the same thing exactly, in microseconds, with no
+model. Macro similarity is a plain distance over the nutrient vector. Both are
+explainable to the user, which embeddings never were.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from nutriweb.util import num
+from pipeline.config import MACRO_COLUMNS
+
+
+def macro_vector(product: dict, stats: dict[str, tuple[float, float]]) -> np.ndarray:
+    """Z-scored nutrient vector. Missing nutrients sit at the mean (z = 0).
+
+    Standardising matters because the raw units are wildly different: energy is
+    hundreds of kcal while salt is under a gram, so an unscaled distance would
+    be energy and nothing else.
+    """
+    out = np.zeros(len(MACRO_COLUMNS), dtype=np.float32)
+    for i, col in enumerate(MACRO_COLUMNS):
+        value = num(product.get(col))
+        if value is None:
+            continue
+        mean, std = stats.get(col, (0.0, 1.0))
+        out[i] = (value - mean) / (std or 1.0)
+    return out
+
+
+def macro_matrix(frame, stats: dict[str, tuple[float, float]]) -> np.ndarray:
+    """Vectorised `macro_vector` over a DataFrame of candidates."""
+    cols = []
+    for col in MACRO_COLUMNS:
+        mean, std = stats.get(col, (0.0, 1.0))
+        values = frame[col].astype("float32").to_numpy()
+        cols.append(np.nan_to_num((values - mean) / (std or 1.0), nan=0.0))
+    return np.column_stack(cols).astype(np.float32)
+
+
+def macro_similarity(source: np.ndarray, candidates: np.ndarray) -> np.ndarray:
+    """Similarity in [0, 1] from Euclidean distance in z-space.
+
+    Distance rather than cosine: for nutrition, *magnitude* matters. Cosine
+    would call a 500 kcal bar and a 50 kcal snack identical if their nutrient
+    ratios matched, which is exactly the swap a user would reject.
+    """
+    distance = np.linalg.norm(candidates - source[None, :], axis=1)
+    # Scaled so a distance of one standard deviation lands near 0.5.
+    return 1.0 / (1.0 + distance / np.sqrt(len(MACRO_COLUMNS)))
+
+
+def jaccard(source_tags: set[str], candidate_tags: list[set[str]]) -> np.ndarray:
+    """Ingredient-set overlap: |A ∩ B| / |A ∪ B| for each candidate."""
+    if not source_tags:
+        return np.zeros(len(candidate_tags), dtype=np.float32)
+    out = np.zeros(len(candidate_tags), dtype=np.float32)
+    for i, tags in enumerate(candidate_tags):
+        if not tags:
+            continue
+        union = len(source_tags | tags)
+        if union:
+            out[i] = len(source_tags & tags) / union
+    return out
+
+
+def shared_macros(source: dict, candidate: dict, tolerance: float = 0.25) -> list[str]:
+    """Which macros are within `tolerance` relative difference — for the "why" line."""
+    labels = {
+        "energy_kcal_100g": "calories",
+        "proteins_100g": "protein",
+        "carbohydrates_100g": "carbs",
+        "fat_100g": "fat",
+        "sugars_100g": "sugar",
+        "fiber_100g": "fibre",
+    }
+    matches = []
+    for col, label in labels.items():
+        a, b = num(source.get(col)), num(candidate.get(col))
+        if a is None or b is None:
+            continue
+        scale = max(abs(a), abs(b), 1e-6)
+        if abs(a - b) / scale <= tolerance:
+            matches.append(label)
+    return matches

nutriweb/scoring/__init__.py

@@ -0,0 +1 @@
+"""Scoring: Nutri-Score 2023, additive concern levels, and the NutriWeb health score."""

nutriweb/scoring/additives.py

@@ -0,0 +1,63 @@
+"""Additive concern lookup, backed by OFF's EFSA/ANSES-sourced taxonomy.
+
+Replaces the substring matching in the old `nutriweb/risk_levels.py`. Lookups
+are exact on OFF's canonical additive tags (`en:e250`), so "sugar-free" can no
+longer be flagged as containing sugar.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+
+DATA_PATH = Path(__file__).resolve().parent.parent.parent / "data" / "additives.json"
+
+# How much each concern level costs in the health score, in points out of 100.
+CONCERN_PENALTY = {"high": 6.0, "moderate": 3.0, "watch": 1.5, "none": 0.0}
+
+# Cap the total additive penalty so a long ingredient list cannot dominate the
+# nutrition signal outright.
+MAX_ADDITIVE_PENALTY = 18.0
+
+
+@lru_cache(maxsize=1)
+def _table() -> dict[str, dict]:
+    if not DATA_PATH.exists():
+        raise FileNotFoundError(
+            f"{DATA_PATH} missing. Run: python pipeline/additives_taxonomy.py"
+        )
+    return json.loads(DATA_PATH.read_text())
+
+
+def lookup(tag: str) -> dict | None:
+    """Return the concern record for an OFF additive tag, or None if unflagged."""
+    return _table().get(tag)
+
+
+def concerns(additives_tags: list[str] | None) -> list[dict]:
+    """Flagged additives in a product, worst first, for display."""
+    order = {"high": 0, "moderate": 1, "watch": 2}
+    found = [
+        {"tag": tag, **meta}
+        for tag in (additives_tags or ())
+        if (meta := lookup(tag)) and meta["concern"] != "none"
+    ]
+    return sorted(found, key=lambda a: order.get(a["concern"], 9))
+
+
+def penalty(additives_tags: list[str] | None) -> float:
+    """Total health-score penalty from a product's additives, capped."""
+    total = sum(CONCERN_PENALTY.get(a["concern"], 0.0) for a in concerns(additives_tags))
+    return min(total, MAX_ADDITIVE_PENALTY)
+
+
+def has_non_nutritive_sweetener(additives_tags: list[str] | None) -> bool:
+    """Whether any additive is a non-nutritive sweetener.
+
+    Drives the Nutri-Score 2023 beverage penalty of 4 negative points.
+    """
+    return any(
+        (meta := lookup(tag)) and meta.get("non_nutritive_sweetener")
+        for tag in (additives_tags or ())
+    )

nutriweb/scoring/health_score.py

@@ -0,0 +1,132 @@
+"""The NutriWeb health score — one 0-100 number used to rank alternatives.
+
+Why a composite rather than the Nutri-Score alone
+-------------------------------------------------
+Nutri-Score grades nutrition but says nothing about processing or additives:
+a diet cola and a sparkling water can land in the same band. NOVA grades
+processing but ignores nutrition entirely. Ranking "healthier" on either one
+alone produces swaps users don't accept.
+
+So the score blends three sourced signals, each weighted and each individually
+explainable in the UI:
+
+  * Nutri-Score 2023 (70) — nutritional quality, computed by us when OFF has
+    no grade, which covers 1.7x more of the US catalog.
+  * NOVA group   (30)     — degree of industrial processing.
+  * Additives    (-18 max) — EFSA/ANSES-flagged additives, subtracted.
+
+Higher is better. The weights are deliberately blunt and declared in one place
+so they can be tuned and justified rather than buried in the ranking code.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from nutriweb.scoring import additives as additives_mod
+
+NUTRISCORE_WEIGHT = 70.0
+NOVA_WEIGHT = 30.0
+
+# Nutri-Score letters map onto the nutrition component linearly.
+GRADE_POINTS = {"a": 1.0, "b": 0.75, "c": 0.5, "d": 0.25, "e": 0.0}
+
+# NOVA 1 (unprocessed) is best, NOVA 4 (ultra-processed) worst.
+NOVA_POINTS = {1: 1.0, 2: 0.75, 3: 0.4, 4: 0.0}
+
+# Neutral prior for products with no NOVA group.
+#
+# The obvious alternative -- rescaling the Nutri-Score component to the full
+# 0-100 range when NOVA is absent -- breaks comparability, which is fatal here
+# because these scores are used to *rank*. It gave a grade-B diet soda with no
+# NOVA data a 75 while a grade-A product known to be NOVA 4 scored 70, so
+# missing metadata beat measured quality. A neutral prior keeps every product
+# on one scale; the cost is visible in `confidence`, not hidden in the number.
+NOVA_PRIOR = 0.5
+
+
+@dataclass
+class HealthScore:
+    value: float
+    nutriscore_component: float | None
+    nova_component: float | None
+    additive_penalty: float
+    confidence: str  # 'high' | 'medium' | 'low'
+
+    def __post_init__(self) -> None:
+        self.value = round(self.value, 1)
+
+
+def compute(
+    *,
+    grade: str | None,
+    nova_group: int | None,
+    additives_tags: list[str] | None,
+    grade_is_computed: bool = False,
+    category_known: bool = True,
+) -> HealthScore | None:
+    """Blend the available signals into a 0-100 score.
+
+    Returns None when neither a Nutri-Score grade nor a NOVA group is known —
+    we would be inventing a number, and an invented number would rank.
+
+    When only one of the two is present its weight is rescaled to the full
+    range, so a product with a grade but no NOVA is not penalised for OFF's
+    missing metadata.
+    """
+    ns_component = (
+        GRADE_POINTS.get(grade.lower()) * NUTRISCORE_WEIGHT
+        if grade and grade.lower() in GRADE_POINTS
+        else None
+    )
+    nova_component = (
+        NOVA_POINTS.get(int(nova_group)) * NOVA_WEIGHT
+        if nova_group is not None and int(nova_group) in NOVA_POINTS
+        else None
+    )
+
+    if ns_component is None and nova_component is None:
+        return None
+
+    # Substitute neutral priors for whichever signal is missing so every
+    # product is scored on the same 0-100 scale and remains comparable.
+    base = (
+        (ns_component if ns_component is not None else 0.5 * NUTRISCORE_WEIGHT)
+        + (nova_component if nova_component is not None else NOVA_PRIOR * NOVA_WEIGHT)
+    )
+
+    penalty = additives_mod.penalty(additives_tags)
+    value = max(0.0, min(100.0, base - penalty))
+
+    return HealthScore(
+        value=value,
+        nutriscore_component=ns_component,
+        nova_component=nova_component,
+        additive_penalty=penalty,
+        confidence=_confidence(
+            has_nutriscore=ns_component is not None,
+            has_nova=nova_component is not None,
+            grade_is_computed=grade_is_computed,
+            category_known=category_known,
+        ),
+    )
+
+
+def _confidence(
+    *,
+    has_nutriscore: bool,
+    has_nova: bool,
+    grade_is_computed: bool,
+    category_known: bool,
+) -> str:
+    """How much to trust this score, surfaced in the UI rather than hidden.
+
+    A grade we computed for a product with no category is the weakest case: we
+    had to assume the general-food variant, and a mis-assumed beverage or fat
+    is graded on the wrong thresholds entirely.
+    """
+    if grade_is_computed and not category_known:
+        return "low"
+    if has_nutriscore and has_nova:
+        return "high"
+    return "medium"

nutriweb/scoring/nutriscore.py

@@ -0,0 +1,311 @@
+"""Nutri-Score 2023 (v2) — a faithful port of Open Food Facts' reference implementation.
+
+Why this exists
+---------------
+58% of US products in Open Food Facts carry `nutriscore_grade = 'unknown'`. Nutri-Score
+is a European scheme and OFF often cannot assign it to US items, usually because the
+category needed to pick the algorithm variant is missing. Ranking "healthier alternatives"
+on OFF's grade alone would therefore silently discard most of the US catalog.
+
+So NutriWeb computes the grade itself wherever the input nutrients exist. We keep OFF's
+own grade alongside ours and never merge the two — the UI always states which is which.
+
+Provenance
+----------
+Ported from `lib/ProductOpener/Nutriscore.pm` (`compute_nutriscore_score_2023`) and the
+category predicates in `lib/ProductOpener/Food.pm`, from openfoodfacts-server @ main.
+Threshold tables are reproduced verbatim; the irregular steps (e.g. beverage energy
+jumping 30/90/150/210 then by 30) are intentional and match upstream.
+
+Reference: Nutri-Score 2023 main algorithm update, Santé publique France.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# --------------------------------------------------------------------------
+# Threshold tables — verbatim from Nutriscore.pm %points_thresholds_2023
+# --------------------------------------------------------------------------
+# A value scores one point per threshold it exceeds (strictly greater than),
+# except saturated_fat_ratio which uses >=.
+
+THRESHOLDS: dict[str, list[float]] = {
+    # negative
+    "energy": [335, 670, 1005, 1340, 1675, 2010, 2345, 2680, 3015, 3350],  # kJ/100g
+    "energy_beverages": [30, 90, 150, 210, 240, 270, 300, 330, 360, 390],
+    "sugars": [3.4, 6.8, 10, 14, 17, 20, 24, 27, 31, 34, 37, 41, 44, 48, 51],  # g/100g
+    "sugars_beverages": [0.5, 2, 3.5, 5, 6, 7, 8, 9, 10, 11],
+    "saturated_fat": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],  # g/100g
+    "salt": [0.2, 0.4, 0.6, 0.8, 1, 1.2, 1.4, 1.6, 1.8, 2,
+             2.2, 2.4, 2.6, 2.8, 3, 3.2, 3.4, 3.6, 3.8, 4],  # g/100g
+    # fats/oils/nuts/seeds variant
+    "energy_from_saturated_fat": [120, 240, 360, 480, 600, 720, 840, 960, 1080, 1200],
+    "saturated_fat_ratio": [10, 16, 22, 28, 34, 40, 46, 52, 58, 64],  # %
+    # positive
+    # 80 repeats so that >80% earns the full 5 points; this is upstream's encoding.
+    "fruits_vegetables_legumes": [40, 60, 80, 80, 80],  # %
+    "fruits_vegetables_legumes_beverages": [40, 40, 60, 60, 80, 80],  # yields 0/2/4/6
+    "fiber": [3.0, 4.1, 5.2, 6.3, 7.4],  # g/100g, AOAC
+    "proteins": [2.4, 4.8, 7.2, 9.6, 12, 14, 17],  # g/100g
+    "proteins_beverages": [1.2, 1.5, 1.8, 2.1, 2.4, 2.7, 3.0],
+}
+
+# Energy density of fat, used to derive energy-from-saturates for the fats variant.
+KJ_PER_G_FAT = 37.0
+
+# --------------------------------------------------------------------------
+# Category predicates — from Food.pm
+# --------------------------------------------------------------------------
+# OFF's `categories_tags` is the *expanded* tag list: it already contains every
+# ancestor category, so a plain membership test is equivalent to upstream's
+# has_tag() walk up the taxonomy.
+
+BEVERAGE_ROOTS = {"en:beverages", "en:beverage-preparations"}
+NOT_BEVERAGES_2023 = {"en:meal-replacement", "en:soups"}
+ALSO_BEVERAGES_2023 = {
+    "en:milks", "en:plant-based-milk-alternatives", "en:dairy-drinks",
+    "en:plant-based-beverages", "en:tea-based-beverages", "en:iced-teas",
+    "en:herbal-tea-beverages", "en:coffee-beverages", "en:coffee-drinks",
+    "en:coffees", "en:herbal-teas", "en:teas",
+}
+FAT_OIL_NUTS_SEEDS_ROOTS = {"en:fats", "en:creams", "en:seeds"}
+
+# Products OFF exempts from Nutri-Score entirely. We honour the same list so we
+# don't invent grades for salt, spices, or alcohol.
+EXEMPTED = {
+    "en:alcoholic-beverages", "en:baby-foods", "en:baby-milks", "en:chewing-gum",
+    "en:food-additives", "en:dietary-supplements", "en:meal-replacements",
+    "en:salts", "en:spices", "en:sugar-substitutes", "en:vinegars",
+    "en:non-food-products",
+}
+NOT_EXEMPTED = {
+    "en:tea-based-beverages", "en:iced-teas", "en:herbal-tea-beverages",
+    "en:coffee-beverages", "en:coffee-drinks",
+}
+
+
+@dataclass
+class CategoryFlags:
+    """Which algorithm variant applies, derived from `categories_tags`."""
+
+    is_beverage: bool = False
+    is_water: bool = False
+    is_cheese: bool = False
+    is_fat_oil_nuts_seeds: bool = False
+    is_red_meat_product: bool = False
+
+
+def category_flags(
+    categories_tags: list[str] | None,
+    fat_oil_nuts_seeds_ids: frozenset[str] = frozenset(),
+    red_meat_ids: frozenset[str] = frozenset(),
+) -> CategoryFlags:
+    """Derive the Nutri-Score variant flags from a product's category tags.
+
+    `fat_oil_nuts_seeds_ids` and `red_meat_ids` come from
+    `pipeline/taxonomy.py`, which resolves the WCO Harmonized-System properties
+    that upstream reads via taxonomy inheritance. Passing empty sets falls back
+    to the explicit root categories only.
+    """
+    tags = set(categories_tags or ())
+
+    is_beverage = bool(tags & BEVERAGE_ROOTS) and not (tags & NOT_BEVERAGES_2023)
+    if tags & ALSO_BEVERAGES_2023:
+        is_beverage = True
+
+    is_water = "en:spring-waters" in tags and not (
+        tags & {"en:flavored-waters", "en:flavoured-waters"}
+    )
+    is_cheese = "en:cheeses" in tags and "fr:fromages-blancs" not in tags
+
+    if "en:chestnuts" in tags:
+        is_fat = False
+    else:
+        is_fat = bool(tags & FAT_OIL_NUTS_SEEDS_ROOTS) or bool(tags & fat_oil_nuts_seeds_ids)
+
+    return CategoryFlags(
+        is_beverage=is_beverage,
+        is_water=is_water,
+        is_cheese=is_cheese,
+        is_fat_oil_nuts_seeds=is_fat,
+        is_red_meat_product=bool(tags & red_meat_ids),
+    )
+
+
+def is_exempt(categories_tags: list[str] | None) -> bool:
+    """True if OFF excludes this product from Nutri-Score (salt, spices, alcohol...)."""
+    tags = set(categories_tags or ())
+    return bool(tags & EXEMPTED) and not (tags & NOT_EXEMPTED)
+
+
+# --------------------------------------------------------------------------
+# Point assignment
+# --------------------------------------------------------------------------
+
+
+def _points(value: float | None, table_key: str) -> int:
+    """One point per threshold exceeded. Missing values score 0, per upstream."""
+    if value is None:
+        return 0
+    table = THRESHOLDS[table_key]
+    # The saturated fat ratio table is the one that uses >= rather than >.
+    if table_key == "saturated_fat_ratio":
+        return sum(1 for t in table if value >= t)
+    return sum(1 for t in table if value > t)
+
+
+def _table(nutrient: str, is_beverage: bool) -> str:
+    """Beverages use their own table where one exists."""
+    key = f"{nutrient}_beverages"
+    return key if is_beverage and key in THRESHOLDS else nutrient
+
+
+@dataclass
+class NutriScoreResult:
+    score: int
+    grade: str
+    negative_points: int
+    positive_points: int
+    counted_proteins: bool
+    detail: dict[str, int] = field(default_factory=dict)
+
+
+def compute(
+    *,
+    energy_kj: float | None,
+    sugars: float | None,
+    saturated_fat: float | None,
+    salt: float | None,
+    fiber: float | None,
+    proteins: float | None,
+    fruits_vegetables_legumes: float | None,
+    fat: float | None = None,
+    has_non_nutritive_sweeteners: bool = False,
+    flags: CategoryFlags | None = None,
+) -> NutriScoreResult | None:
+    """Compute the 2023 Nutri-Score. All nutrients are per 100 g / 100 ml.
+
+    Returns None when there is too little data to score honestly — see
+    `has_sufficient_data`. Absent *optional* nutrients (fiber, fruit content)
+    score 0 points, matching upstream, which is a conservative penalty.
+    """
+    flags = flags or CategoryFlags()
+
+    if not has_sufficient_data(
+        energy_kj=energy_kj, sugars=sugars, saturated_fat=saturated_fat,
+        salt=salt, proteins=proteins,
+    ):
+        return None
+
+    # In the fats/oils/nuts/seeds variant, energy is replaced by energy-from-saturates
+    # and saturated fat by the saturates-to-fat ratio.
+    if flags.is_fat_oil_nuts_seeds:
+        energy_value = (saturated_fat or 0.0) * KJ_PER_G_FAT
+        energy_key = "energy_from_saturated_fat"
+        satfat_value = (
+            (saturated_fat / fat * 100.0) if fat not in (None, 0) and saturated_fat is not None
+            else None
+        )
+        satfat_key = "saturated_fat_ratio"
+    else:
+        energy_value, energy_key = energy_kj, "energy"
+        satfat_value, satfat_key = saturated_fat, "saturated_fat"
+
+    bev = flags.is_beverage
+    detail = {
+        "energy": _points(energy_value, _table(energy_key, bev)),
+        "sugars": _points(sugars, _table("sugars", bev)),
+        "saturated_fat": _points(satfat_value, satfat_key),
+        "salt": _points(salt, "salt"),
+        "fiber": _points(fiber, "fiber"),
+        "proteins": _points(proteins, _table("proteins", bev)),
+        "fruits_vegetables_legumes": _points(
+            fruits_vegetables_legumes, _table("fruits_vegetables_legumes", bev)
+        ),
+    }
+
+    # Red meat products cap protein at 2 points, so a fatty sausage cannot
+    # protein its way to a good grade.
+    if flags.is_red_meat_product:
+        detail["proteins"] = min(detail["proteins"], 2)
+
+    negative = detail["energy"] + detail["sugars"] + detail["saturated_fat"] + detail["salt"]
+    # Beverages carrying non-nutritive sweeteners take 4 extra negative points.
+    if bev:
+        detail["non_nutritive_sweeteners"] = 4 if has_non_nutritive_sweeteners else 0
+        negative += detail["non_nutritive_sweeteners"]
+
+    # Protein only counts when the product isn't already heavily penalised —
+    # otherwise processed meats and cheeses would score as health foods.
+    if bev or flags.is_cheese:
+        count_proteins = True
+    elif flags.is_fat_oil_nuts_seeds:
+        count_proteins = negative < 7
+    else:
+        count_proteins = negative < 11
+
+    positive = detail["fiber"] + detail["fruits_vegetables_legumes"]
+    if count_proteins:
+        positive += detail["proteins"]
+
+    score = negative - positive
+    return NutriScoreResult(
+        score=score,
+        grade=grade_for(score, flags),
+        negative_points=negative,
+        positive_points=positive,
+        counted_proteins=count_proteins,
+        detail=detail,
+    )
+
+
+def grade_for(score: int, flags: CategoryFlags) -> str:
+    """Map a numeric score to a letter. Cutoffs differ by variant."""
+    if flags.is_beverage:
+        if flags.is_water:
+            return "a"  # unflavoured spring water is graded A by definition
+        if score <= 2:
+            return "b"
+        if score <= 6:
+            return "c"
+        if score <= 9:
+            return "d"
+        return "e"
+    if flags.is_fat_oil_nuts_seeds:
+        if score <= -6:
+            return "a"
+        if score <= 2:
+            return "b"
+        if score <= 10:
+            return "c"
+        if score <= 18:
+            return "d"
+        return "e"
+    if score <= 0:
+        return "a"
+    if score <= 2:
+        return "b"
+    if score <= 10:
+        return "c"
+    if score <= 18:
+        return "d"
+    return "e"
+
+
+def has_sufficient_data(
+    *,
+    energy_kj: float | None,
+    sugars: float | None,
+    saturated_fat: float | None,
+    salt: float | None,
+    proteins: float | None,
+) -> bool:
+    """Whether we have enough to compute a grade we're willing to show.
+
+    Upstream treats every missing nutrient as 0 points, which would hand a
+    product with no nutrition data whatsoever a clean 'A'. We require the four
+    negative-side drivers plus protein to be present, so a sparse record is
+    reported as unscored rather than as healthy.
+    """
+    return all(v is not None for v in (energy_kj, sugars, saturated_fat, salt, proteins))

nutriweb/util.py

@@ -0,0 +1,47 @@
+"""Coercion helpers for values coming out of DuckDB via pandas.
+
+DuckDB list and numeric columns surface as several different "missing" sentinels
+depending on the column's type and whether the frame went through Arrow: None,
+float('nan'), and pandas.NA all appear. `pd.NA` in particular raises on both
+`bool()` and `iter()`, so a plain `if value is not None` guard is not enough.
+These two helpers are the single place that knows about it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+
+def is_missing(value: Any) -> bool:
+    """True for None, NaN, and pandas.NA — without raising on arrays."""
+    if value is None:
+        return True
+    try:
+        result = pd.isna(value)
+    except (TypeError, ValueError):
+        return False
+    # pd.isna returns an array for list-likes; a present list is not missing.
+    return bool(result) if isinstance(result, bool) else False
+
+
+def tag_set(value: Any) -> set[str]:
+    """Coerce a DuckDB list column to a set of strings."""
+    if is_missing(value):
+        return set()
+    try:
+        return {str(v) for v in value}
+    except TypeError:
+        return set()
+
+
+def num(value: Any) -> float | None:
+    """Coerce a numeric column to float, mapping every missing form to None."""
+    if is_missing(value):
+        return None
+    try:
+        result = float(value)
+    except (TypeError, ValueError):
+        return None
+    return None if pd.isna(result) else result

pipeline/01_download.py

@@ -0,0 +1,38 @@
+"""Step 1 — fetch the Open Food Facts parquet from the Hugging Face Hub.
+
+The file is ~7.8 GB. It lands in the shared HF cache rather than the repo, so
+re-runs are free and the working tree stays clean. Anonymous access gets
+rate-limited (HTTP 429) on a file this size, so we authenticate: `hf auth login`
+once, or export HF_TOKEN.
+
+Usage:
+    python pipeline/01_download.py
+"""
+
+import os
+import sys
+
+from huggingface_hub import hf_hub_download
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from pipeline.config import SOURCE_FILE, SOURCE_REPO  # noqa: E402
+
+
+def download() -> str:
+    """Download food.parquet and return its local path."""
+    # hf_transfer gives a large speedup on multi-GB files; harmless if absent.
+    os.environ.setdefault("HF_HUB_ENABLE_HF_TRANSFER", "1")
+
+    print(f"Downloading {SOURCE_REPO}/{SOURCE_FILE} (~7.8 GB)...")
+    path = hf_hub_download(
+        repo_id=SOURCE_REPO,
+        filename=SOURCE_FILE,
+        repo_type="dataset",
+    )
+    size_gb = os.path.getsize(path) / 1024**3
+    print(f"Done: {path} ({size_gb:.2f} GB)")
+    return path
+
+
+if __name__ == "__main__":
+    download()

pipeline/02_curate.py

@@ -0,0 +1,208 @@
+"""Step 2 — curate the raw OFF parquet into a compact US catalog.
+
+One DuckDB pass over the 7.2 GB source that:
+  * filters to non-obsolete US products with a usable name,
+  * collapses the multilingual list<struct{lang,text}> fields to one language,
+  * pivots the long-format `nutriments` list into per-100g columns,
+  * derives the primary category and the front-image URL,
+  * keeps OFF's curated tag arrays for set operations downstream.
+
+DuckDB streams the parquet, so peak memory stays well under the file size.
+
+Usage:
+    python pipeline/02_curate.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+
+import duckdb
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from pipeline.config import (  # noqa: E402
+    CATALOG_PATH,
+    COUNTRY_TAG,
+    DATA_DIR,
+    DISQUALIFYING_QUALITY_ERRORS,
+    KJ_PER_KCAL,
+    NUTRIENT_MAP,
+    SALT_PER_SODIUM,
+    SOURCE_FILE,
+    SOURCE_REPO,
+)
+
+
+def source_path() -> str:
+    """Locate the downloaded parquet in the HF cache."""
+    from huggingface_hub import hf_hub_download
+
+    return hf_hub_download(
+        repo_id=SOURCE_REPO, filename=SOURCE_FILE, repo_type="dataset",
+        local_files_only=True,
+    )
+
+
+def _pick_lang(column: str) -> str:
+    """SQL to collapse a list<struct{lang,text}> to a single string.
+
+    Prefers English, then OFF's 'main' pseudo-language, then whatever is first.
+    """
+    def first_where(cond: str) -> str:
+        return (
+            f"list_extract(list_transform(list_filter({column}, x -> {cond}), "
+            f"x -> x.text), 1)"
+        )
+
+    en = first_where("x.lang = 'en'")
+    main = first_where("x.lang = 'main'")
+    any_lang = f"list_extract(list_transform({column}, x -> x.text), 1)"
+    return f"COALESCE({en}, {main}, {any_lang})"
+
+
+def _pivot_nutrient(off_name: str, alias: str) -> str:
+    """SQL to pull one nutrient's per-100g value out of the `nutriments` list."""
+    return (
+        "list_extract(list_transform("
+        f"list_filter(nutriments, x -> x.name = '{off_name}'), x -> x.\"100g\"), 1"
+        f") AS {alias}"
+    )
+
+
+def build_sql(parquet: str) -> str:
+    nutrient_cols = ",\n        ".join(
+        _pivot_nutrient(off, alias) for off, alias in NUTRIENT_MAP.items()
+    )
+    bad_quality = ", ".join(f"'{t}'" for t in DISQUALIFYING_QUALITY_ERRORS)
+
+    return f"""
+    CREATE OR REPLACE TABLE products AS
+    WITH src AS (
+        SELECT
+            code,
+            {_pick_lang('product_name')} AS product_name,
+            {_pick_lang('generic_name')} AS generic_name,
+            {_pick_lang('ingredients_text')} AS ingredients_text,
+            brands,
+            quantity,
+            serving_size,
+            categories_tags,
+            -- The last English tag is usually the most specific one. 'en:null'
+            -- and 'en:undefined' are data-entry artifacts in the source and
+            -- must not be treated as categories.
+            list_extract(
+                list_filter(
+                    categories_tags,
+                    x -> starts_with(x, 'en:')
+                         AND x NOT IN ('en:null', 'en:undefined')
+                ), -1
+            ) AS primary_category,
+            ingredients_tags,
+            allergens_tags,
+            traces_tags,
+            additives_tags,
+            labels_tags,
+            ingredients_analysis_tags,
+            nutrient_levels_tags,
+            additives_n,
+            nova_group,
+            nutriscore_grade AS nutriscore_grade_off,
+            nutriscore_score AS nutriscore_score_off,
+            environmental_score_grade,
+            environmental_score_score,
+            with_non_nutritive_sweeteners,
+            unique_scans_n,
+            popularity_key,
+            completeness,
+            last_modified_t,
+            {nutrient_cols},
+            -- Front image URL. OFF splits barcodes longer than 8 digits into
+            -- 3/3/3/rest path segments on its image CDN.
+            CASE
+                WHEN length(code) > 8
+                    THEN regexp_replace(code, '^(...)(...)(...)(.*)$', '\\1/\\2/\\3/\\4')
+                ELSE code
+            END AS code_path,
+            -- Prefer the English front photo; fall back to any front photo
+            -- (front_fr, front_es, ...) which lifts image coverage materially.
+            COALESCE(
+                list_extract(list_filter(images, i -> i.key = 'front_en'), 1),
+                list_extract(list_filter(images, i -> starts_with(i.key, 'front')), 1)
+            ) AS front_image
+        FROM read_parquet('{parquet}')
+        WHERE NOT obsolete
+          AND list_contains(countries_tags, '{COUNTRY_TAG}')
+          AND NOT list_has_any(
+                COALESCE(data_quality_errors_tags, []::VARCHAR[]),
+                [{bad_quality}]
+          )
+    )
+    SELECT
+        * EXCLUDE (code_path, front_image),
+        CASE
+            WHEN front_image IS NOT NULL AND front_image.rev IS NOT NULL
+                THEN 'https://images.openfoodfacts.org/images/products/'
+                     || code_path || '/' || front_image.key || '.'
+                     || CAST(front_image.rev AS VARCHAR) || '.400.jpg'
+        END AS image_url,
+        -- Nutri-Score works in kJ but US labels report kcal, so derive it.
+        COALESCE(energy_kj_100g, energy_kcal_100g * {KJ_PER_KCAL}) AS energy_kj_derived,
+        -- Salt and sodium are interconvertible; fill whichever is missing.
+        COALESCE(salt_100g, sodium_100g * {SALT_PER_SODIUM}) AS salt_derived,
+        COALESCE(fruits_veg_legumes_100g, fruits_veg_nuts_100g) AS fruits_veg_derived
+    FROM src
+    WHERE product_name IS NOT NULL
+      AND trim(product_name) <> ''
+      -- A product needs ingredients, a category, or nutrition facts to be
+      -- useful. Records with none of the three are empty barcode stubs --
+      -- roughly 209k of the US rows -- and are pure noise in search results.
+      AND (len(COALESCE(ingredients_tags, []::VARCHAR[])) > 0
+           OR len(COALESCE(categories_tags, []::VARCHAR[])) > 0
+           OR energy_kcal_100g IS NOT NULL
+           OR proteins_100g IS NOT NULL)
+    -- The source carries a handful of genuinely duplicated barcodes; keep the
+    -- most recently edited record so the choice is deterministic.
+    QUALIFY row_number() OVER (
+        PARTITION BY code ORDER BY last_modified_t DESC, completeness DESC
+    ) = 1
+    """
+
+
+def main() -> None:
+    parquet = source_path()
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    if CATALOG_PATH.exists():
+        CATALOG_PATH.unlink()
+
+    con = duckdb.connect(str(CATALOG_PATH))
+    con.execute("SET preserve_insertion_order = false")
+    con.execute("SET memory_limit = '6GB'")
+
+    print(f"Curating {parquet}\n     -> {CATALOG_PATH}")
+    start = time.time()
+    con.execute(build_sql(parquet))
+    elapsed = time.time() - start
+
+    n = con.execute("SELECT count(*) FROM products").fetchone()[0]
+    print(f"products: {n:,} rows in {elapsed:.0f}s")
+
+    print("Building indexes...")
+    con.execute("CREATE UNIQUE INDEX idx_products_code ON products(code)")
+    con.execute("CREATE INDEX idx_products_category ON products(primary_category)")
+
+    # Full-text search over name + brand, replacing the old str.contains scan.
+    con.execute("INSTALL fts; LOAD fts;")
+    con.execute(
+        "PRAGMA create_fts_index('products', 'code', 'product_name', 'brands', "
+        "overwrite=1)"
+    )
+
+    con.close()
+    size_mb = CATALOG_PATH.stat().st_size / 1024**2
+    print(f"Done. Catalog is {size_mb:.0f} MB")
+
+
+if __name__ == "__main__":
+    main()

pipeline/03_score.py

@@ -0,0 +1,265 @@
+"""Step 3 — compute Nutri-Score and the NutriWeb health score for every product.
+
+Runs after 02_curate. Reads the catalog in batches, scores each product in
+Python (the algorithm is branchy enough that SQL would obscure it), and writes
+a `scores` table back into the same DuckDB file.
+
+Also validates our Nutri-Score implementation against OFF's own grades on the
+~347k products where OFF published one. That agreement rate is the single most
+important correctness signal in the pipeline, so it is printed every run.
+
+Usage:
+    python pipeline/03_score.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+
+import duckdb
+import pandas as pd
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from nutriweb.scoring import additives as additives_mod  # noqa: E402
+from nutriweb.scoring import health_score, nutriscore  # noqa: E402
+from pipeline import taxonomy  # noqa: E402
+from pipeline.config import CATALOG_PATH  # noqa: E402
+
+BATCH = 100_000
+
+SELECT_COLS = """
+    code, categories_tags, additives_tags, nova_group,
+    nutriscore_grade_off, nutriscore_score_off,
+    energy_kj_derived, sugars_100g, saturated_fat_100g, salt_derived,
+    fiber_100g, proteins_100g, fruits_veg_derived, fat_100g,
+    with_non_nutritive_sweeteners
+"""
+
+
+def _f(value) -> float | None:
+    """Coerce a DuckDB/pandas value to float, mapping NaN and NULL to None."""
+    if value is None or pd.isna(value):
+        return None
+    return float(value)
+
+
+def _list(value) -> list[str]:
+    """Coerce a DuckDB list column to a plain list.
+
+    Missing lists arrive as None, pd.NA, or a NumPy array depending on the
+    column, so `is not None` alone is not enough.
+    """
+    if value is None:
+        return []
+    if isinstance(value, float) or value is pd.NA:
+        return []
+    return list(value)
+
+
+def score_row(row, fat_ids: frozenset[str], red_meat_ids: frozenset[str]) -> dict:
+    tags = _list(row.categories_tags)
+    additive_tags = _list(row.additives_tags)
+    category_known = len(tags) > 0
+
+    flags = nutriscore.category_flags(tags, fat_ids, red_meat_ids)
+
+    # OFF's own boolean is authoritative where present; fall back to reading the
+    # additive list, which is what matters for the beverage sweetener penalty.
+    sweeteners = row.with_non_nutritive_sweeteners
+    if sweeteners is None or pd.isna(sweeteners):
+        has_sweetener = additives_mod.has_non_nutritive_sweetener(additive_tags)
+    else:
+        has_sweetener = int(sweeteners) > 0
+
+    result = None
+    if not nutriscore.is_exempt(tags):
+        result = nutriscore.compute(
+            energy_kj=_f(row.energy_kj_derived),
+            sugars=_f(row.sugars_100g),
+            saturated_fat=_f(row.saturated_fat_100g),
+            salt=_f(row.salt_derived),
+            fiber=_f(row.fiber_100g),
+            proteins=_f(row.proteins_100g),
+            fruits_vegetables_legumes=_f(row.fruits_veg_derived),
+            fat=_f(row.fat_100g),
+            has_non_nutritive_sweeteners=has_sweetener,
+            flags=flags,
+        )
+
+    computed_grade = result.grade if result else None
+    off_grade = row.nutriscore_grade_off
+    if off_grade is None or pd.isna(off_grade):
+        off_grade = None
+    elif str(off_grade) in ("unknown", "not-applicable", ""):
+        off_grade = None
+
+    # Prefer OFF's published grade; ours fills the gap it leaves.
+    effective_grade = off_grade or computed_grade
+    grade_is_computed = off_grade is None and computed_grade is not None
+
+    nova = None if row.nova_group is None or pd.isna(row.nova_group) else int(row.nova_group)
+    hs = health_score.compute(
+        grade=effective_grade,
+        nova_group=nova,
+        additives_tags=additive_tags,
+        grade_is_computed=grade_is_computed,
+        category_known=category_known,
+    )
+
+    return {
+        "code": row.code,
+        "nutriscore_grade_computed": computed_grade,
+        "nutriscore_score_computed": result.score if result else None,
+        "nutriscore_grade": effective_grade,
+        "nutriscore_source": (
+            "off" if off_grade else ("nutriweb" if computed_grade else None)
+        ),
+        "is_beverage": flags.is_beverage,
+        "is_fat_oil_nuts_seeds": flags.is_fat_oil_nuts_seeds,
+        "is_red_meat_product": flags.is_red_meat_product,
+        "health_score": hs.value if hs else None,
+        "health_confidence": hs.confidence if hs else None,
+        "additive_penalty": hs.additive_penalty if hs else None,
+        "n_flagged_additives": len(additives_mod.concerns(additive_tags)),
+    }
+
+
+def main() -> None:
+    if not CATALOG_PATH.exists():
+        raise SystemExit(f"{CATALOG_PATH} missing. Run pipeline/02_curate.py first.")
+
+    fat_ids, red_meat_ids = taxonomy.load()
+    additives_mod._table()  # fail fast if the additives cache is missing
+
+    con = duckdb.connect(str(CATALOG_PATH))
+    total = con.execute("SELECT count(*) FROM products").fetchone()[0]
+    print(f"Scoring {total:,} products...")
+
+    start = time.time()
+    frames: list[pd.DataFrame] = []
+    for offset in range(0, total, BATCH):
+        batch = con.execute(
+            f"SELECT {SELECT_COLS} FROM products LIMIT {BATCH} OFFSET {offset}"
+        ).fetchdf()
+        frames.append(
+            pd.DataFrame(
+                [score_row(r, fat_ids, red_meat_ids) for r in batch.itertuples()]
+            )
+        )
+        print(f"  {min(offset + BATCH, total):,}/{total:,}", end="\r")
+
+    scores = pd.concat(frames, ignore_index=True)
+    print(f"\nScored in {time.time() - start:.0f}s")
+
+    con.execute("DROP TABLE IF EXISTS scores")
+    con.register("scores_df", scores)
+    con.execute("CREATE TABLE scores AS SELECT * FROM scores_df")
+    con.execute("CREATE UNIQUE INDEX idx_scores_code ON scores(code)")
+
+    build_derived_tables(con)
+    report(con)
+    con.close()
+
+
+def build_derived_tables(con: duckdb.DuckDBPyConnection) -> None:
+    """Derived structures the app queries at request time.
+
+    `catalog`        — the single joined view the app reads from.
+    `category_sizes` — how many scored products sit under each category tag.
+                       Candidate generation picks the *smallest* pool that is
+                       still big enough, which is a robust proxy for "most
+                       specific category" -- `categories_tags` is not reliably
+                       ordered general-to-specific, so position cannot be used.
+    `macro_stats`    — per-nutrient mean and standard deviation, used to
+                       z-score the macro vector before comparing products.
+    """
+    print("\nBuilding derived tables...")
+
+    con.execute("""
+        CREATE OR REPLACE VIEW catalog AS
+        SELECT p.*, s.* EXCLUDE (code)
+        FROM products p JOIN scores s USING (code)
+    """)
+
+    con.execute("""
+        CREATE OR REPLACE TABLE category_sizes AS
+        SELECT tag, count(*) AS n
+        FROM (
+            SELECT unnest(categories_tags) AS tag
+            FROM catalog
+            WHERE health_score IS NOT NULL
+        )
+        WHERE tag NOT IN ('en:null', 'en:undefined')
+        GROUP BY tag
+    """)
+    con.execute("CREATE UNIQUE INDEX idx_category_sizes_tag ON category_sizes(tag)")
+
+    from pipeline.config import MACRO_COLUMNS
+
+    stats = ", ".join(
+        f"avg({c}) AS {c}_mean, coalesce(stddev_samp({c}), 1.0) AS {c}_std"
+        for c in MACRO_COLUMNS
+    )
+    con.execute(f"CREATE OR REPLACE TABLE macro_stats AS SELECT {stats} FROM catalog")
+
+    n_cat = con.execute("SELECT count(*) FROM category_sizes").fetchone()[0]
+    print(f"  category_sizes: {n_cat:,} tags")
+
+
+def report(con: duckdb.DuckDBPyConnection) -> None:
+    """Print coverage and, critically, agreement with OFF's published grades."""
+    print("\n" + "=" * 62)
+    print("NUTRI-SCORE COVERAGE")
+    print("=" * 62)
+    print(
+        con.execute("""
+        SELECT
+            count(*) AS products,
+            count(nutriscore_grade) AS graded,
+            count(*) FILTER (WHERE nutriscore_source = 'off') AS from_off,
+            count(*) FILTER (WHERE nutriscore_source = 'nutriweb') AS from_nutriweb,
+            count(health_score) AS with_health_score
+        FROM scores
+        """).fetchdf().T.to_string(header=False)
+    )
+
+    print("\n" + "=" * 62)
+    print("VALIDATION vs OFF's own grades (ground truth)")
+    print("=" * 62)
+    agree = con.execute("""
+        WITH v AS (
+            SELECT p.nutriscore_grade_off AS off, s.nutriscore_grade_computed AS ours,
+                   p.nutriscore_score_off AS off_score, s.nutriscore_score_computed AS our_score
+            FROM products p JOIN scores s USING (code)
+            WHERE p.nutriscore_grade_off NOT IN ('unknown','not-applicable')
+              AND p.nutriscore_grade_off IS NOT NULL
+              AND s.nutriscore_grade_computed IS NOT NULL
+        )
+        SELECT count(*) AS compared,
+               round(100.0 * count(*) FILTER (WHERE off = ours) / count(*), 2) AS exact_grade_pct,
+               round(100.0 * count(*) FILTER (
+                   WHERE abs(ascii(off) - ascii(ours)) <= 1) / count(*), 2) AS within_one_letter_pct,
+               round(100.0 * count(*) FILTER (WHERE off_score = our_score) / count(*), 2) AS exact_score_pct
+        FROM v
+    """).fetchdf()
+    print(agree.T.to_string(header=False))
+
+    print("\nDisagreements by OFF grade:")
+    print(
+        con.execute("""
+        SELECT p.nutriscore_grade_off AS off_grade, s.nutriscore_grade_computed AS our_grade,
+               count(*) AS n
+        FROM products p JOIN scores s USING (code)
+        WHERE p.nutriscore_grade_off NOT IN ('unknown','not-applicable')
+          AND s.nutriscore_grade_computed IS NOT NULL
+          AND p.nutriscore_grade_off <> s.nutriscore_grade_computed
+        GROUP BY 1,2 ORDER BY n DESC LIMIT 10
+        """).fetchdf().to_string(index=False)
+    )
+
+
+if __name__ == "__main__":
+    main()

pipeline/04_audit.py

@@ -0,0 +1,142 @@
+"""Step 4 — measure what is actually in the catalog.
+
+The point of this script is to replace assumptions with numbers. The app makes
+claims ("healthier alternative", "safe for your allergies") that are only as
+good as the coverage underneath them, so coverage is measured rather than
+hoped for. Run it after any pipeline change and read the output before
+trusting a recommendation.
+
+Usage:
+    python pipeline/04_audit.py
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import duckdb
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from pipeline.config import CATALOG_PATH  # noqa: E402
+
+
+def rule(title: str) -> None:
+    print(f"\n{'=' * 66}\n{title}\n{'=' * 66}")
+
+
+def pct(part: int, whole: int) -> str:
+    return f"{part:>9,}  ({part / whole * 100:5.1f}%)" if whole else f"{part:>9,}"
+
+
+def main() -> None:
+    if not CATALOG_PATH.exists():
+        raise SystemExit(f"{CATALOG_PATH} missing. Run steps 01-03 first.")
+
+    con = duckdb.connect(str(CATALOG_PATH), read_only=True)
+    total = con.execute("SELECT count(*) FROM catalog").fetchone()[0]
+
+    rule("CATALOG")
+    print(f"{'products':<42}{total:>9,}")
+    size = CATALOG_PATH.stat().st_size / 1024**2
+    print(f"{'catalog size':<42}{size:>8.0f} MB")
+
+    rule("FIELD COVERAGE")
+    fields = {
+        "product name": "product_name IS NOT NULL",
+        "brand": "brands IS NOT NULL",
+        "front image": "image_url IS NOT NULL",
+        "ingredients text": "ingredients_text IS NOT NULL",
+        "ingredient tags (used for similarity)": "len(COALESCE(ingredients_tags,[]::VARCHAR[])) > 0",
+        "category (used for candidate generation)": "primary_category IS NOT NULL",
+        "allergen tags": "len(COALESCE(allergens_tags,[]::VARCHAR[])) > 0",
+        "energy": "energy_kcal_100g IS NOT NULL",
+        "sugars": "sugars_100g IS NOT NULL",
+        "saturated fat": "saturated_fat_100g IS NOT NULL",
+        "salt or sodium": "salt_derived IS NOT NULL",
+        "protein": "proteins_100g IS NOT NULL",
+        "fibre": "fiber_100g IS NOT NULL",
+        "fruit/veg estimate": "fruits_veg_derived IS NOT NULL",
+        "NOVA group": "nova_group IS NOT NULL",
+        "Eco-Score": "environmental_score_grade IS NOT NULL",
+    }
+    for label, condition in fields.items():
+        n = con.execute(f"SELECT count(*) FROM catalog WHERE {condition}").fetchone()[0]
+        print(f"{label:<42}{pct(n, total)}")
+
+    rule("SCORING — the reason this pipeline exists")
+    off = con.execute(
+        "SELECT count(*) FROM catalog WHERE nutriscore_source = 'off'"
+    ).fetchone()[0]
+    ours = con.execute(
+        "SELECT count(*) FROM catalog WHERE nutriscore_source = 'nutriweb'"
+    ).fetchone()[0]
+    health = con.execute("SELECT count(health_score) FROM catalog").fetchone()[0]
+
+    print(f"{'Nutri-Score published by Open Food Facts':<42}{pct(off, total)}")
+    print(f"{'Nutri-Score computed by NutriWeb':<42}{pct(ours, total)}")
+    print(f"{'total graded':<42}{pct(off + ours, total)}")
+    print(f"{'with a health score':<42}{pct(health, total)}")
+    if off:
+        print(f"\n  Computing grades ourselves increased scored coverage {(off + ours) / off:.2f}x.")
+
+    rule("VALIDATION — computed grades vs Open Food Facts' own")
+    print(
+        con.execute("""
+        WITH v AS (
+            SELECT nutriscore_grade_off AS off, nutriscore_grade_computed AS ours
+            FROM catalog
+            WHERE nutriscore_grade_off NOT IN ('unknown','not-applicable')
+              AND nutriscore_grade_off IS NOT NULL
+              AND nutriscore_grade_computed IS NOT NULL
+        )
+        SELECT count(*) AS compared,
+               round(100.0*count(*) FILTER (WHERE off=ours)/count(*), 2) AS exact_pct,
+               round(100.0*count(*) FILTER (WHERE abs(ascii(off)-ascii(ours))<=1)/count(*), 2)
+                   AS within_one_pct
+        FROM v
+    """).fetchdf().T.to_string(header=False)
+    )
+
+    rule("CONFIDENCE — how much to trust each health score")
+    print(
+        con.execute("""
+        SELECT COALESCE(health_confidence,'unscored') AS confidence, count(*) AS n
+        FROM catalog GROUP BY 1 ORDER BY n DESC
+    """).fetchdf().to_string(index=False)
+    )
+    print(
+        "\n  'low' means the Nutri-Score was computed for a product with no category,\n"
+        "  so the general-food thresholds were assumed. Surfaced in the UI."
+    )
+
+    rule("RECOMMENDABILITY — can we actually serve a swap?")
+    print(
+        con.execute("""
+        SELECT
+            count(*) FILTER (WHERE health_score IS NOT NULL
+                             AND primary_category IS NOT NULL) AS category_path,
+            count(*) FILTER (WHERE health_score IS NOT NULL
+                             AND primary_category IS NULL
+                             AND len(COALESCE(ingredients_tags,[]::VARCHAR[]))>0)
+                AS ingredient_fallback_path,
+            count(*) FILTER (WHERE health_score IS NULL) AS cannot_recommend_from
+        FROM catalog
+    """).fetchdf().T.to_string(header=False)
+    )
+
+    rule("TOP CATEGORIES")
+    print(
+        con.execute("""
+        SELECT replace(split_part(primary_category,':',2),'-',' ') AS category,
+               count(*) AS products, round(avg(health_score),1) AS avg_health
+        FROM catalog WHERE primary_category IS NOT NULL AND health_score IS NOT NULL
+        GROUP BY 1 ORDER BY products DESC LIMIT 12
+    """).fetchdf().to_string(index=False)
+    )
+
+    con.close()
+
+
+if __name__ == "__main__":
+    main()

pipeline/05_publish.py

@@ -0,0 +1,108 @@
+"""Step 5 — publish the curated catalog to the Hugging Face Hub.
+
+The Space must not rebuild from the 7.2 GB source on every cold start, so the
+finished ~400 MB catalog is pushed to a dataset repo and downloaded at startup
+by `nutriweb/data/catalog.py`. That download is in-network on Spaces and takes
+seconds.
+
+This replaces the Google Drive + gdown + zip arrangement the previous version
+used, which had no versioning and no checksum.
+
+Usage:
+    python pipeline/05_publish.py <your-hf-username>/nutriweb-us-catalog
+    python pipeline/05_publish.py <your-hf-username>/nutriweb-us-catalog --private
+
+Repos are created public by default, which is what a Space on the free tier
+needs in order to download the catalog without a token. Pass --private to keep
+it unlisted; the Space will then need an HF_TOKEN secret to read it.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from pipeline.config import CATALOG_PATH  # noqa: E402
+
+CARD = """---
+license: odbl
+tags:
+  - food
+  - nutrition
+  - open-food-facts
+---
+
+# NutriWeb US catalog
+
+A curated, scored subset of the [Open Food Facts product
+database](https://huggingface.co/datasets/openfoodfacts/product-database),
+built by the NutriWeb pipeline. One DuckDB file.
+
+* US products only, non-obsolete, with a resolvable English name and at least
+  ingredients, a category, or nutrition facts.
+* Multilingual fields collapsed to English; `nutriments` pivoted to per-100g columns.
+* Nutri-Score computed with the official 2023 algorithm where Open Food Facts
+  publishes none, which raises scored coverage roughly 1.8x.
+* Tables: `products`, `scores`, `category_sizes`, `macro_stats`; view `catalog`.
+
+Product data (c) Open Food Facts contributors, licensed ODbL. This derived
+catalog carries the same licence.
+
+Rebuild with `pipeline/01_download.py` .. `pipeline/05_publish.py`.
+"""
+
+
+def main() -> None:
+    args = [a for a in sys.argv[1:] if not a.startswith("--")]
+    private = "--private" in sys.argv
+    if not args:
+        raise SystemExit(
+            "Usage: python pipeline/05_publish.py <hf-username>/nutriweb-us-catalog [--private]"
+        )
+    repo_id = args[0]
+
+    if not CATALOG_PATH.exists():
+        raise SystemExit(f"{CATALOG_PATH} missing. Run steps 01-04 first.")
+
+    from huggingface_hub import HfApi
+
+    api = HfApi()
+
+    # Fail early with a clear message rather than a 403 midway through a
+    # 400 MB upload.
+    user = api.whoami().get("name")
+    owner = repo_id.split("/")[0]
+    if owner != user and owner not in {o.get("name") for o in api.whoami().get("orgs", [])}:
+        raise SystemExit(
+            f"You are logged in as '{user}', but the repo id starts with '{owner}'.\n"
+            f"Use '{user}/{repo_id.split('/')[-1]}' instead."
+        )
+
+    size_mb = CATALOG_PATH.stat().st_size / 1024**2
+    visibility = "private" if private else "public"
+    print(f"Publishing {CATALOG_PATH.name} ({size_mb:.0f} MB) to {repo_id} [{visibility}] ...")
+
+    api.create_repo(repo_id, repo_type="dataset", exist_ok=True, private=private)
+    api.upload_file(
+        path_or_fileobj=str(CATALOG_PATH),
+        path_in_repo=CATALOG_PATH.name,
+        repo_id=repo_id,
+        repo_type="dataset",
+    )
+    api.upload_file(
+        path_or_fileobj=CARD.encode(),
+        path_in_repo="README.md",
+        repo_id=repo_id,
+        repo_type="dataset",
+    )
+
+    print(
+        f"Done: https://huggingface.co/datasets/{repo_id}\n\n"
+        f"Point the Space at it by setting this variable:\n"
+        f"  NUTRIWEB_CATALOG_REPO={repo_id}"
+    )
+
+
+if __name__ == "__main__":
+    main()

pipeline/additives_taxonomy.py

@@ -0,0 +1,91 @@
+"""Derive additive concern levels from Open Food Facts' additives taxonomy.
+
+The app this replaces classified additives with a hand-written dictionary of
+~90 substrings (`nutriweb/risk_levels.py`), matched with `if key in name`. That
+produced both false positives ("sugar" matching "sugar-free") and unsourced
+verdicts.
+
+OFF's additives taxonomy carries properties backed by real regulatory
+assessments, which we use instead:
+
+  * `efsa_evaluation_overexposure_risk` — EFSA's finding on whether normal
+    consumption can exceed the acceptable daily intake (high / moderate / no).
+  * `anses_additives_of_interest` — ANSES' watch list.
+  * `non_nutritive_sweetener` — required by the Nutri-Score 2023 beverage
+    penalty, which adds 4 negative points when one is present.
+
+Every verdict the app shows is therefore attributable to a named authority.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from pathlib import Path
+
+TAXONOMY_URL = "https://static.openfoodfacts.org/data/taxonomies/additives.json"
+CACHE_PATH = Path(__file__).resolve().parent.parent / "data" / "additives.json"
+
+
+def _prop(entry: dict, name: str) -> str | None:
+    block = entry.get(name)
+    if isinstance(block, dict):
+        value = block.get("en")
+        return str(value) if value is not None else None
+    return str(block) if block is not None else None
+
+
+def build(force: bool = False) -> dict:
+    """Emit {tag: {name, e_number, concern, reasons[], non_nutritive_sweetener}}."""
+    if CACHE_PATH.exists() and not force:
+        return json.loads(CACHE_PATH.read_text())
+
+    print(f"Fetching additives taxonomy from {TAXONOMY_URL} ...")
+    with urllib.request.urlopen(TAXONOMY_URL, timeout=120) as resp:
+        taxonomy = json.loads(resp.read().decode("utf-8"))
+
+    out: dict[str, dict] = {}
+    for tag, entry in taxonomy.items():
+        overexposure = (_prop(entry, "efsa_evaluation_overexposure_risk") or "").lower()
+        anses = (_prop(entry, "anses_additives_of_interest") or "").lower() == "yes"
+        sweetener = (_prop(entry, "non_nutritive_sweetener") or "").lower() == "yes"
+
+        reasons: list[str] = []
+        if overexposure.endswith("high"):
+            concern = "high"
+            reasons.append("EFSA: high risk of exceeding the acceptable daily intake")
+        elif overexposure.endswith("moderate"):
+            concern = "moderate"
+            reasons.append("EFSA: moderate risk of exceeding the acceptable daily intake")
+        else:
+            concern = "none"
+
+        if anses:
+            reasons.append("On ANSES' list of additives of interest")
+            if concern == "none":
+                concern = "watch"
+
+        # Only keep entries that carry a signal worth surfacing.
+        if concern == "none" and not sweetener:
+            continue
+
+        out[tag] = {
+            "name": _prop(entry, "name") or tag,
+            "e_number": _prop(entry, "e_number"),
+            "concern": concern,
+            "reasons": reasons,
+            "non_nutritive_sweetener": sweetener,
+        }
+
+    CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CACHE_PATH.write_text(json.dumps(out, indent=1, sort_keys=True))
+
+    counts: dict[str, int] = {}
+    for meta in out.values():
+        counts[meta["concern"]] = counts.get(meta["concern"], 0) + 1
+    print(f"Wrote {len(out)} additives to {CACHE_PATH}: {counts}")
+    return out
+
+
+if __name__ == "__main__":
+    build(force=True)

pipeline/config.py

@@ -0,0 +1,78 @@
+"""Shared paths and constants for the NutriWeb data pipeline.
+
+The pipeline runs offline on a workstation. It reads the full Open Food Facts
+parquet (~7.8 GB) and emits a compact DuckDB catalog that the Streamlit app on
+Hugging Face Spaces downloads at startup.
+"""
+
+from pathlib import Path
+
+# Upstream source ---------------------------------------------------------
+SOURCE_REPO = "openfoodfacts/product-database"
+SOURCE_FILE = "food.parquet"
+
+# Local artifacts ---------------------------------------------------------
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DATA_DIR = REPO_ROOT / "data"
+CATALOG_PATH = DATA_DIR / "nutriweb-us.duckdb"
+
+# Scope -------------------------------------------------------------------
+# US + English focus. OFF tags countries canonically, so this is an exact match
+# rather than a string search.
+COUNTRY_TAG = "en:united-states"
+
+# Nutriments we pivot out of the long-format `nutriments` list<struct>.
+# Keys are OFF's own nutrient names; values are the column names we emit.
+NUTRIENT_MAP = {
+    "energy-kcal": "energy_kcal_100g",
+    # Nutri-Score works in kJ; we keep kcal too because that is what US labels show.
+    "energy-kj": "energy_kj_100g",
+    "fat": "fat_100g",
+    "saturated-fat": "saturated_fat_100g",
+    "carbohydrates": "carbohydrates_100g",
+    "sugars": "sugars_100g",
+    "fiber": "fiber_100g",
+    "proteins": "proteins_100g",
+    "salt": "salt_100g",
+    "sodium": "sodium_100g",
+    # Required by the Nutri-Score algorithm's positive-points side. The 2023
+    # algorithm uses the "legumes" variant; the older "nuts" field is kept as a
+    # fallback because some records carry only that one.
+    "fruits-vegetables-legumes-estimate-from-ingredients": "fruits_veg_legumes_100g",
+    "fruits-vegetables-nuts-estimate-from-ingredients": "fruits_veg_nuts_100g",
+}
+
+# US labels report kcal; Nutri-Score needs kJ. Only ~7% of US records carry an
+# explicit energy-kj, so we derive it from kcal with the Codex conversion factor.
+KJ_PER_KCAL = 4.184
+
+# Salt and sodium are interconvertible; OFF uses this factor internally.
+SALT_PER_SODIUM = 2.5
+
+# The macro vector used for similarity ranking, in a fixed order.
+# Uses salt_derived rather than salt_100g so products that report only sodium
+# still contribute a salt value instead of silently sitting at the mean.
+MACRO_COLUMNS = [
+    "energy_kcal_100g",
+    "fat_100g",
+    "saturated_fat_100g",
+    "carbohydrates_100g",
+    "sugars_100g",
+    "fiber_100g",
+    "proteins_100g",
+    "salt_derived",
+]
+
+# Data-quality errors that make a record unusable for recommendation.
+# OFF publishes many quality tags; these are the ones that indicate the
+# nutrition facts themselves are wrong, not merely incomplete.
+DISQUALIFYING_QUALITY_ERRORS = [
+    "en:nutrition-value-total-over-105",
+    "en:nutrition-value-negative-energy",
+    "en:nutrition-value-negative-fat",
+    "en:nutrition-value-negative-carbohydrates",
+    "en:nutrition-value-negative-proteins",
+    "en:nutrition-value-negative-sugars",
+    "en:nutrition-value-negative-salt",
+    "en:energy-value-in-kcal-does-not-match-value-computed-from-other-nutrients",
+]

pipeline/taxonomy.py

@@ -0,0 +1,124 @@
+"""Resolve OFF category-taxonomy properties needed by the Nutri-Score variants.
+
+Two Nutri-Score flags cannot be read off `categories_tags` directly:
+
+  * `is_fat_oil_nuts_seeds` — nuts and seeds are identified by WCO Harmonized
+    System headings (08.01, 08.02, 12.02, 12.04, 12.06, 12.07) and codes
+    (2008.11, 2008.19), not by a single parent category.
+  * `is_red_meat_product` — identified by HS headings 02.01–02.06.
+
+Upstream reads these via taxonomy *inheritance*: a category inherits
+`wco_hs_heading` from its ancestors. We reproduce that by downloading OFF's
+categories taxonomy once and propagating the property down the parent graph.
+
+The result is two flat sets of category ids, cached to JSON so the curate step
+stays offline and deterministic.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from pathlib import Path
+
+TAXONOMY_URL = "https://static.openfoodfacts.org/data/taxonomies/categories.json"
+
+FAT_OIL_NUTS_SEEDS_HEADINGS = {"08.01", "08.02", "12.02", "12.04", "12.06", "12.07"}
+FAT_OIL_NUTS_SEEDS_CODES = {"2008.11", "2008.19"}
+RED_MEAT_HEADINGS = {"02.01", "02.02", "02.03", "02.04", "02.05", "02.06"}
+
+CACHE_PATH = Path(__file__).resolve().parent.parent / "data" / "nutriscore_categories.json"
+
+
+def _download() -> dict:
+    print(f"Fetching category taxonomy from {TAXONOMY_URL} ...")
+    with urllib.request.urlopen(TAXONOMY_URL, timeout=300) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def _direct_property(entry: dict, prop: str) -> str | None:
+    """Read a taxonomy property, which OFF stores as {prop: {lang: value}}."""
+    block = entry.get(prop)
+    if isinstance(block, dict):
+        value = block.get("en")
+        return str(value) if value is not None else None
+    return str(block) if block is not None else None
+
+
+def _resolve_inherited(taxonomy: dict, prop: str) -> dict[str, str]:
+    """Resolve `prop` for every category, walking up parents when unset.
+
+    OFF's taxonomy is a DAG (a category may have several parents), so we memoise
+    and guard against cycles. First parent with a value wins, matching upstream's
+    depth-first get_inherited_property_from_categories_tags.
+    """
+    resolved: dict[str, str] = {}
+    in_progress: set[str] = set()
+
+    def visit(cid: str) -> str | None:
+        if cid in resolved:
+            return resolved[cid]
+        if cid in in_progress:  # cycle guard
+            return None
+        entry = taxonomy.get(cid)
+        if entry is None:
+            return None
+
+        in_progress.add(cid)
+        value = _direct_property(entry, prop)
+        if value is None:
+            for parent in entry.get("parents", []) or []:
+                value = visit(parent)
+                if value is not None:
+                    break
+        in_progress.discard(cid)
+
+        if value is not None:
+            resolved[cid] = value
+        return value
+
+    for cid in taxonomy:
+        visit(cid)
+    return resolved
+
+
+def build(force: bool = False) -> dict[str, list[str]]:
+    """Return {'fat_oil_nuts_seeds': [...], 'red_meat': [...]} category ids."""
+    if CACHE_PATH.exists() and not force:
+        return json.loads(CACHE_PATH.read_text())
+
+    taxonomy = _download()
+    headings = _resolve_inherited(taxonomy, "wco_hs_heading")
+    codes = _resolve_inherited(taxonomy, "wco_hs_code")
+
+    fat_ids = {
+        cid for cid, h in headings.items() if h in FAT_OIL_NUTS_SEEDS_HEADINGS
+    } | {
+        cid for cid, c in codes.items() if c in FAT_OIL_NUTS_SEEDS_CODES
+    }
+    # Chestnuts are explicitly excluded from the fats/nuts/seeds category.
+    fat_ids.discard("en:chestnuts")
+
+    red_meat_ids = {cid for cid, h in headings.items() if h in RED_MEAT_HEADINGS}
+
+    result = {
+        "fat_oil_nuts_seeds": sorted(fat_ids),
+        "red_meat": sorted(red_meat_ids),
+    }
+    CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CACHE_PATH.write_text(json.dumps(result, indent=1))
+    print(
+        f"Resolved {len(fat_ids)} fat/oil/nuts/seeds and "
+        f"{len(red_meat_ids)} red-meat categories -> {CACHE_PATH}"
+    )
+    return result
+
+
+def load() -> tuple[frozenset[str], frozenset[str]]:
+    """Convenience accessor returning the two sets."""
+    data = build()
+    return frozenset(data["fat_oil_nuts_seeds"]), frozenset(data["red_meat"])
+
+
+if __name__ == "__main__":
+    build(force=True)

pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "nutriweb"
+version = "2.0.0"
+description = "Personalised, evidence-backed food recommendations from the Open Food Facts US catalog."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "AGPL-3.0" }
+
+dependencies = [
+    "streamlit>=1.40",
+    "duckdb>=1.1",
+    "pandas>=2.2",
+    "numpy>=2.0",
+    "plotly>=6.0",
+    "huggingface_hub>=0.30",
+    "pymongo>=4.12",
+    "bcrypt>=4.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "hf_transfer"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["nutriweb", "pipeline", "views", "components"]

requirements.txt

@@ -0,0 +1,20 @@
+# Runtime dependencies for the Hugging Face Space.
+#
+# The previous version pulled sentence-transformers, transformers, tokenizers,
+# torch and faiss-cpu -- roughly 2 GB -- to compute ingredient similarity.
+# Open Food Facts already canonicalises ingredients into tags, so set overlap
+# replaces that entirely. See nutriweb/reco/similarity.py.
+
+# Pinned, and kept identical to `sdk_version` in README.md -- Hugging Face
+# Spaces installs the version declared there, not this one. When the two
+# drifted (1.40 on the Space, 1.61 locally) the app crashed on st.button(width=),
+# an argument that only exists in the newer release. tests/test_deploy.py
+# fails if they diverge again.
+streamlit==1.61.1
+duckdb>=1.1
+pandas>=2.2
+numpy>=2.0
+plotly>=6.0
+huggingface_hub>=0.30
+pymongo>=4.12          # optional: account storage, app runs without it
+bcrypt>=4.0            # password hashing (passlib is unmaintained and breaks on bcrypt 5)

styles.css

@@ -0,0 +1,143 @@
+/* NutriWeb — injected once by app.py.
+   Kept in a real .css file rather than scattered st.markdown calls so the
+   design is editable in one place. */
+
+:root {
+  --nw-green: #0F8A5F;
+  --nw-green-dark: #0A6244;
+  --nw-ink: #1A1F1C;
+  --nw-muted: #5F6B64;
+  --nw-line: #E3E8E4;
+  --nw-surface: #FFFFFF;
+  --nw-bg: #FBFBF9;
+
+  /* Official Nutri-Score palette */
+  --ns-a: #038141;
+  --ns-b: #85BB2F;
+  --ns-c: #FECB02;
+  --ns-d: #EE8100;
+  --ns-e: #E63E11;
+
+  --nw-radius: 14px;
+  --nw-shadow: 0 1px 2px rgba(16, 32, 24, .06), 0 4px 16px rgba(16, 32, 24, .05);
+}
+
+/* ---------- layout ---------- */
+.block-container { padding-top: 2.2rem; max-width: 1180px; }
+
+/* ---------- hero ---------- */
+.nw-hero {
+  background: linear-gradient(135deg, var(--nw-green-dark), var(--nw-green) 55%, #3DAF7D);
+  color: #fff;
+  border-radius: var(--nw-radius);
+  padding: 1.6rem 1.8rem;
+  margin-bottom: 1.4rem;
+}
+.nw-hero h1 { margin: 0 0 .3rem; font-size: 1.7rem; font-weight: 700; letter-spacing: -.02em; }
+.nw-hero p  { margin: 0; opacity: .92; font-size: .95rem; }
+
+/* ---------- cards ---------- */
+.nw-card {
+  background: var(--nw-surface);
+  border: 1px solid var(--nw-line);
+  border-radius: var(--nw-radius);
+  padding: 1rem 1.1rem;
+  box-shadow: var(--nw-shadow);
+  height: 100%;
+}
+.nw-card h4 { margin: 0 0 .2rem; font-size: 1rem; line-height: 1.32; color: var(--nw-ink); }
+.nw-brand { color: var(--nw-muted); font-size: .8rem; margin-bottom: .55rem; }
+
+.nw-thumb {
+  width: 100%; height: 132px; object-fit: contain;
+  background: #F4F6F4; border-radius: 10px; margin-bottom: .7rem;
+}
+.nw-thumb-empty {
+  display: flex; align-items: center; justify-content: center;
+  color: #B6C0B9; font-size: 1.9rem;
+}
+
+/* ---------- score badges ---------- */
+.nw-badges { display: flex; gap: .4rem; flex-wrap: wrap; align-items: center; }
+.nw-badge {
+  display: inline-flex; align-items: center; gap: .35rem;
+  border-radius: 999px; padding: .2rem .6rem;
+  font-size: .74rem; font-weight: 650; letter-spacing: .01em;
+  border: 1px solid transparent; white-space: nowrap;
+}
+.nw-badge .k { opacity: .75; font-weight: 500; }
+.ns-a { background: var(--ns-a); color: #fff; }
+.ns-b { background: var(--ns-b); color: #14310A; }
+.ns-c { background: var(--ns-c); color: #3A2E00; }
+.ns-d { background: var(--ns-d); color: #fff; }
+.ns-e { background: var(--ns-e); color: #fff; }
+.nw-badge-neutral { background: #EEF2EF; color: var(--nw-muted); border-color: var(--nw-line); }
+
+/* Provenance chip: whether a grade came from OFF or was computed here. */
+.nw-source {
+  font-size: .68rem; color: var(--nw-muted);
+  background: #F2F5F3; border: 1px solid var(--nw-line);
+  border-radius: 6px; padding: .1rem .4rem; margin-left: .3rem;
+}
+
+/* ---------- health score dial ---------- */
+.nw-health { display: flex; align-items: baseline; gap: .4rem; margin: .55rem 0 .3rem; }
+.nw-health .v { font-size: 1.5rem; font-weight: 700; color: var(--nw-ink); line-height: 1; }
+.nw-health .m { font-size: .74rem; color: var(--nw-muted); }
+.nw-meter { height: 6px; background: #EDF1EE; border-radius: 999px; overflow: hidden; }
+.nw-meter > span { display: block; height: 100%; border-radius: 999px; }
+
+/* ---------- gain pill on recommendations ---------- */
+.nw-gain {
+  display: inline-block; background: #E7F5EE; color: var(--nw-green-dark);
+  border: 1px solid #BFE5D3; border-radius: 999px;
+  padding: .16rem .55rem; font-size: .76rem; font-weight: 650;
+}
+.nw-why { color: var(--nw-muted); font-size: .78rem; margin-top: .45rem; line-height: 1.45; }
+
+/* ---------- verdict panel ---------- */
+.nw-verdict { border-radius: var(--nw-radius); padding: .85rem 1rem; margin: .2rem 0 1rem; border: 1px solid; }
+.nw-verdict h5 { margin: 0 0 .3rem; font-size: .95rem; }
+.nw-verdict ul { margin: .3rem 0 0; padding-left: 1.1rem; font-size: .85rem; }
+.v-ok    { background: #EAF7F0; border-color: #BFE5D3; color: #0A5A3C; }
+.v-warn  { background: #FFF7E6; border-color: #FBE0A2; color: #6B4C00; }
+.v-block { background: #FDECEA; border-color: #F6C7C0; color: #8A1F12; }
+
+/* ---------- chips ---------- */
+.nw-chips { display: flex; flex-wrap: wrap; gap: .3rem; }
+.nw-chip {
+  font-size: .75rem; padding: .18rem .55rem; border-radius: 999px;
+  background: #F2F5F3; border: 1px solid var(--nw-line); color: var(--nw-ink);
+}
+.chip-danger { background: #FDECEA; border-color: #F6C7C0; color: #8A1F12; }
+.chip-warn   { background: #FFF7E6; border-color: #FBE0A2; color: #6B4C00; }
+.chip-good   { background: #EAF7F0; border-color: #BFE5D3; color: #0A5A3C; }
+
+/* ---------- nutrient table ---------- */
+.nw-nutri { width: 100%; border-collapse: collapse; font-size: .86rem; }
+.nw-nutri td { padding: .42rem .2rem; border-bottom: 1px solid var(--nw-line); vertical-align: middle; }
+.nw-nutri td.n { color: var(--nw-muted); width: 34%; }
+.nw-nutri td.v { text-align: right; font-variant-numeric: tabular-nums; font-weight: 600; width: 18%; }
+.nw-bar { background: #EDF1EE; border-radius: 999px; height: 6px; }
+.nw-bar > span { display: block; height: 100%; border-radius: 999px; background: var(--nw-green); }
+.nw-bar > span.over { background: var(--ns-d); }
+
+.nw-sub { color: var(--nw-muted); font-size: .82rem; }
+
+/* ---------- dark mode ---------- */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --nw-ink: #E9EFEB; --nw-muted: #9FAFA6;
+    --nw-line: #2A332E; --nw-surface: #161B18; --nw-bg: #0F1411;
+  }
+  .nw-thumb { background: #1D2320; }
+  .nw-meter, .nw-bar { background: #262E29; }
+  .nw-chip, .nw-source { background: #1D2320; }
+  .v-ok    { background: #10241B; border-color: #1F4634; color: #8FD9B6; }
+  .v-warn  { background: #2A2312; border-color: #4A3D1A; color: #E8C874; }
+  .v-block { background: #2B1512; border-color: #55251E; color: #F0A79B; }
+  .nw-gain { background: #10241B; border-color: #1F4634; color: #8FD9B6; }
+  .chip-danger { background: #2B1512; border-color: #55251E; color: #F0A79B; }
+  .chip-warn   { background: #2A2312; border-color: #4A3D1A; color: #E8C874; }
+  .chip-good   { background: #10241B; border-color: #1F4634; color: #8FD9B6; }
+}

views/__init__.py

@@ -0,0 +1 @@
+"""Streamlit views."""

views/compare.py

@@ -0,0 +1,55 @@
+"""Side-by-side comparison of up to three products."""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from components import badges, cards
+from nutriweb.data import catalog
+from nutriweb.reco import filters
+from views import state
+
+st.markdown(
+    """<div class="nw-hero">
+        <h1>Compare</h1>
+        <p>Put up to three products side by side, scored the same way.</p>
+    </div>""",
+    unsafe_allow_html=True,
+)
+
+codes: list[str] = st.session_state.compare_codes
+
+if not codes:
+    st.info("Nothing to compare yet. Open a product and choose **Add to compare**.")
+    if st.button("Go to Search"):
+        st.switch_page(state.SEARCH)
+    st.stop()
+
+products = [p for code in codes if (p := catalog.get_product(code))]
+profile = state.profile()
+
+columns = st.columns(len(products), gap="large")
+for column, product in zip(columns, products):
+    with column:
+        st.markdown(
+            f'<div class="nw-card">{badges.thumb(product)}'
+            f"<h4>{badges.title_of(product)}</h4>"
+            f'<div class="nw-brand">{badges.brand_of(product) or "&nbsp;"}</div>'
+            f"{badges.badge_row(product)}"
+            f'{badges.health_meter(product.get("health_score"))}</div>',
+            unsafe_allow_html=True,
+        )
+        st.markdown(cards.nutrient_table(product), unsafe_allow_html=True)
+
+        verdict = filters.evaluate(product, profile)
+        if not state.profile_is_empty():
+            cards.verdict_panel(verdict)
+
+        if st.button("Remove", key=f"rm_{product['code']}", width='stretch'):
+            st.session_state.compare_codes.remove(product["code"])
+            st.rerun()
+
+st.divider()
+if st.button("Clear all"):
+    st.session_state.compare_codes = []
+    st.rerun()

views/insights.py

@@ -0,0 +1,167 @@
+"""Data insights — what is actually in the catalog, and how it was built.
+
+This page exists because the honest answer to "how good are these
+recommendations?" is "as good as the coverage underneath them". Rather than
+hide that, it is measured and shown.
+"""
+
+from __future__ import annotations
+
+import plotly.express as px
+import plotly.graph_objects as go
+import streamlit as st
+
+from nutriweb.data import catalog
+
+st.markdown(
+    """<div class="nw-hero">
+        <h1>What's in the catalog</h1>
+        <p>Built from the Open Food Facts product database on Hugging Face,
+        filtered to US products and scored with the official Nutri-Score 2023 algorithm.</p>
+    </div>""",
+    unsafe_allow_html=True,
+)
+
+
+@st.cache_data(show_spinner=False)
+def _stats() -> dict:
+    return catalog.stats()
+
+
+@st.cache_data(show_spinner=False)
+def _grade_distribution():
+    return catalog.connect().execute("""
+        SELECT nutriscore_grade AS grade, nutriscore_source AS source, count(*) AS n
+        FROM catalog WHERE nutriscore_grade IS NOT NULL
+        GROUP BY 1, 2 ORDER BY 1
+    """).fetchdf()
+
+
+@st.cache_data(show_spinner=False)
+def _top_categories(limit: int = 12):
+    return catalog.connect().execute(f"""
+        SELECT replace(split_part(primary_category, ':', 2), '-', ' ') AS category,
+               count(*) AS products, round(avg(health_score), 1) AS avg_health
+        FROM catalog
+        WHERE primary_category IS NOT NULL AND health_score IS NOT NULL
+        GROUP BY 1 HAVING count(*) > 200
+        ORDER BY products DESC LIMIT {limit}
+    """).fetchdf()
+
+
+@st.cache_data(show_spinner=False)
+def _nutrient_profile(limit: int = 8):
+    return catalog.connect().execute(f"""
+        WITH top AS (
+            SELECT primary_category FROM catalog
+            WHERE primary_category IS NOT NULL AND health_score IS NOT NULL
+            GROUP BY 1 ORDER BY count(*) DESC LIMIT {limit}
+        )
+        SELECT replace(split_part(c.primary_category, ':', 2), '-', ' ') AS category,
+               median(c.proteins_100g) AS protein,
+               median(c.carbohydrates_100g) AS carbs,
+               median(c.sugars_100g) AS sugars,
+               median(c.fat_100g) AS fat,
+               median(c.fiber_100g) AS fibre,
+               median(c.salt_derived) AS salt
+        FROM catalog c JOIN top USING (primary_category)
+        GROUP BY 1 ORDER BY 1
+    """).fetchdf()
+
+
+stats = _stats()
+cols = st.columns(4)
+cols[0].metric("US products", f"{stats['products']:,}")
+cols[1].metric("With a health score", f"{stats['scored']:,}")
+cols[2].metric("Graded by NutriWeb", f"{stats['graded_by_nutriweb']:,}",
+               help="Products where Open Food Facts publishes no Nutri-Score and we computed one.")
+cols[3].metric("With a photo", f"{stats['with_image']:,}")
+
+st.divider()
+
+left, right = st.columns(2, gap="large")
+
+with left:
+    st.markdown("#### Nutri-Score distribution, by source")
+    grades = _grade_distribution()
+    grades["source"] = grades["source"].map(
+        {"off": "Published by Open Food Facts", "nutriweb": "Computed by NutriWeb"}
+    )
+    figure = px.bar(
+        grades, x="grade", y="n", color="source",
+        category_orders={"grade": ["a", "b", "c", "d", "e"]},
+        color_discrete_sequence=["#0F8A5F", "#9CC5B4"],
+        labels={"grade": "Nutri-Score", "n": "Products", "source": ""},
+    )
+    figure.update_layout(
+        legend=dict(orientation="h", y=-0.22), margin=dict(l=0, r=0, t=6, b=0), height=340,
+    )
+    st.plotly_chart(figure, width='stretch')
+    st.caption(
+        "Computing grades ourselves lifts scored coverage well beyond what Open "
+        "Food Facts publishes for the US market."
+    )
+
+with right:
+    st.markdown("#### Largest categories")
+    categories = _top_categories()
+    figure = px.bar(
+        categories.sort_values("products"), x="products", y="category",
+        orientation="h", color="avg_health",
+        color_continuous_scale=["#E63E11", "#FECB02", "#038141"],
+        labels={"products": "Products", "category": "", "avg_health": "Avg health"},
+    )
+    figure.update_layout(margin=dict(l=0, r=0, t=6, b=0), height=340)
+    st.plotly_chart(figure, width='stretch')
+    st.caption("Colour shows the average NutriWeb health score for the category.")
+
+st.divider()
+st.markdown("#### Nutrient profile of the largest categories")
+st.caption(
+    "Median grams per 100 g. Axes are clipped at the 95th percentile so a few "
+    "extreme products cannot flatten the shape."
+)
+
+profile_data = _nutrient_profile()
+nutrients = ["protein", "carbs", "sugars", "fat", "fibre", "salt"]
+maxima = {n: max(profile_data[n].max(), 1e-6) for n in nutrients}
+
+radar = go.Figure()
+for _, row in profile_data.iterrows():
+    radar.add_trace(
+        go.Scatterpolar(
+            r=[row[n] / maxima[n] for n in nutrients],
+            theta=[n.capitalize() for n in nutrients],
+            fill="toself",
+            name=str(row["category"])[:28],
+        )
+    )
+radar.update_layout(
+    polar=dict(radialaxis=dict(visible=True, range=[0, 1], showticklabels=False)),
+    height=470, margin=dict(l=40, r=40, t=20, b=20),
+    legend=dict(orientation="h", y=-0.12),
+)
+st.plotly_chart(radar, width='stretch')
+
+st.divider()
+with st.expander("How the health score is built"):
+    st.markdown(
+        """
+**Health score (0–100)** = 70% Nutri-Score 2023 + 30% NOVA processing group,
+minus a capped penalty for additives flagged by EFSA or ANSES.
+
+**Nutri-Score** is computed with the official 2023 algorithm, ported from Open
+Food Facts' reference implementation. Where Open Food Facts already publishes a
+grade we use theirs; where it does not, we compute one and label it. Validated
+against Open Food Facts' own grades on 317,265 products: **98.4% exact agreement**,
+99.7% within one letter.
+
+**Where a signal is missing** a neutral prior is substituted rather than
+rescaling the others, so every product stays on the same scale and remains
+comparable. Products where we had to assume the category are marked *low
+confidence* on the product page.
+
+Data: [openfoodfacts/product-database](https://huggingface.co/datasets/openfoodfacts/product-database),
+licensed ODbL. Product data © Open Food Facts contributors.
+"""
+    )

views/product.py

@@ -0,0 +1,154 @@
+"""Product detail — scores, nutrients, and whether it suits this person."""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from components import badges, cards
+from nutriweb.data import catalog
+from nutriweb.reco import filters
+from nutriweb.scoring import additives as additives_mod
+from nutriweb.util import num, tag_set
+from views import state
+
+code = state.require_selection()
+if not code:
+    st.stop()
+
+
+@st.cache_data(show_spinner=False, ttl=600)
+def _load(code: str) -> dict | None:
+    return catalog.get_product(code)
+
+
+product = _load(code)
+if product is None:
+    st.error(f"No product found for barcode {code}.")
+    st.stop()
+
+profile = state.profile()
+verdict = filters.evaluate(product, profile)
+
+left, right = st.columns([1, 1.55], gap="large")
+
+with left:
+    st.markdown(
+        f'<div class="nw-card">{badges.thumb(product)}'
+        f"{badges.badge_row(product)}"
+        f'{badges.health_meter(product.get("health_score"), product.get("health_confidence"))}'
+        "</div>",
+        unsafe_allow_html=True,
+    )
+    st.write("")
+    if st.button("🔄 Find healthier swaps", type="primary", width='stretch'):
+        state.open_recommendations(code)
+    if st.button("➕ Add to compare", width='stretch'):
+        outcome = state.add_to_compare(code)
+        st.toast(
+            {"added": "Added to compare.",
+             "already": "Already in the compare list.",
+             "full": "Compare holds three products; remove one first."}[outcome]
+        )
+
+with right:
+    st.markdown(f"## {badges.title_of(product)}")
+    brand = badges.brand_of(product)
+    subtitle = " · ".join(
+        x for x in (brand, product.get("quantity") if isinstance(product.get("quantity"), str) else None) if x
+    )
+    if subtitle:
+        st.markdown(f'<div class="nw-sub">{badges.esc(subtitle)}</div>', unsafe_allow_html=True)
+    st.caption(f"Barcode {product['code']}")
+
+    cards.verdict_panel(verdict, profile_is_empty=state.profile_is_empty())
+
+    # Be explicit when the grade is ours rather than Open Food Facts'.
+    if product.get("nutriscore_source") == "nutriweb":
+        confidence = product.get("health_confidence")
+        note = (
+            " Its category is unknown, so the general-food thresholds were assumed —"
+            " treat this grade as indicative."
+            if confidence == "low" else ""
+        )
+        st.info(
+            "Open Food Facts has no Nutri-Score for this product. NutriWeb computed "
+            f"**{str(product.get('nutriscore_grade', '')).upper()}** from the nutrition "
+            f"facts using the official 2023 algorithm.{note}"
+        )
+
+    st.markdown("#### Nutrition per 100 g")
+    st.markdown(cards.nutrient_table(product), unsafe_allow_html=True)
+    st.caption("Bars show the share of an adult reference intake for a 100 g portion.")
+
+st.divider()
+
+col_a, col_b = st.columns(2, gap="large")
+
+with col_a:
+    st.markdown("#### Allergens")
+    allergens = tag_set(product.get("allergens_tags"))
+    traces = tag_set(product.get("traces_tags"))
+    if allergens:
+        st.markdown(badges.chips(sorted(allergens), "chip-danger"), unsafe_allow_html=True)
+    if traces:
+        st.caption("May contain traces of:")
+        st.markdown(badges.chips(sorted(traces), "chip-warn"), unsafe_allow_html=True)
+    if not allergens and not traces:
+        st.caption("No allergens declared by Open Food Facts for this product.")
+
+    st.markdown("#### Diet")
+    analysis = tag_set(product.get("ingredients_analysis_tags"))
+    diet_labels = {
+        "en:vegan": ("Vegan", "chip-good"),
+        "en:non-vegan": ("Not vegan", "chip-danger"),
+        "en:maybe-vegan": ("Vegan status unclear", "chip-warn"),
+        "en:vegetarian": ("Vegetarian", "chip-good"),
+        "en:non-vegetarian": ("Not vegetarian", "chip-danger"),
+        "en:maybe-vegetarian": ("Vegetarian status unclear", "chip-warn"),
+        "en:palm-oil-free": ("Palm-oil free", "chip-good"),
+        "en:palm-oil": ("Contains palm oil", "chip-danger"),
+    }
+    shown = [
+        f'<span class="nw-chip {tone}">{label}</span>'
+        for tag, (label, tone) in diet_labels.items()
+        if tag in analysis
+    ]
+    st.markdown(
+        '<div class="nw-chips">' + "".join(shown) + "</div>" if shown
+        else "<span class='nw-sub'>Not analysed.</span>",
+        unsafe_allow_html=True,
+    )
+
+with col_b:
+    st.markdown("#### Additives")
+    flagged = additives_mod.concerns(sorted(tag_set(product.get("additives_tags"))))
+    if flagged:
+        for item in flagged:
+            tone = {"high": "chip-danger", "moderate": "chip-warn", "watch": ""}[item["concern"]]
+            st.markdown(
+                f'<div style="margin-bottom:.45rem"><span class="nw-chip {tone}">'
+                f'{badges.esc(item["name"])}</span>'
+                f'<div class="nw-sub" style="margin-top:.2rem">'
+                f'{badges.esc("; ".join(item["reasons"]))}</div></div>',
+                unsafe_allow_html=True,
+            )
+        st.caption("Assessments from EFSA and ANSES, via the Open Food Facts additives taxonomy.")
+    else:
+        total = num(product.get("n_flagged_additives"))
+        st.caption(
+            "No additives on the EFSA or ANSES watch lists."
+            if total is not None else "No additive data for this product."
+        )
+
+    st.markdown("#### Ingredients")
+    text = product.get("ingredients_text")
+    if text and isinstance(text, str) and text.strip():
+        st.markdown(f'<div class="nw-sub">{badges.esc(text)}</div>', unsafe_allow_html=True)
+    else:
+        st.caption("No ingredient list available.")
+
+# Record the view for the profile history.
+if profile.user_id:
+    from nutriweb.profile import auth
+
+    auth.log_view(profile.user_id, product, verdict.summary)

views/profile_page.py

@@ -0,0 +1,147 @@
+"""Profile — sign in, and set the preferences that drive every filter."""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from nutriweb.profile import auth
+from nutriweb.profile.model import ALLERGEN_CHOICES, DIET_CHOICES, UserProfile
+from views import state
+
+st.markdown(
+    """<div class="nw-hero">
+        <h1>My profile</h1>
+        <p>Everything here is used as a hard filter: allergens and diet exclude
+        products outright rather than merely ranking them lower.</p>
+    </div>""",
+    unsafe_allow_html=True,
+)
+
+profile: UserProfile = state.profile()
+
+if auth.demo_mode():
+    st.caption(
+        "No account database is configured, so profiles last for this session only. "
+        "Set `MONGODB_URI` as a Space secret to persist them."
+    )
+
+
+def _preferences_form(current: UserProfile, key_prefix: str) -> UserProfile:
+    """The shared preference widgets. Returns a profile built from the inputs."""
+    label_for_tag = {v: k for k, v in ALLERGEN_CHOICES.items()}
+    selected_labels = st.multiselect(
+        "Allergens to avoid",
+        list(ALLERGEN_CHOICES),
+        default=[label_for_tag[t] for t in current.allergens if t in label_for_tag],
+        key=f"{key_prefix}_allergens",
+        help="Matched against Open Food Facts' curated allergen and traces tags.",
+    )
+    diets = st.multiselect(
+        "Dietary preferences",
+        DIET_CHOICES,
+        default=current.diets,
+        key=f"{key_prefix}_diets",
+    )
+    col1, col2 = st.columns(2)
+    with col1:
+        age = st.number_input("Age", 1, 120, current.age, key=f"{key_prefix}_age")
+        high_bp = st.checkbox(
+            "High blood pressure", current.high_blood_pressure, key=f"{key_prefix}_bp",
+            help="Flags and filters products above 1.15 g salt per 100 g.",
+        )
+    with col2:
+        gender = st.selectbox(
+            "Gender",
+            ["Prefer not to say", "Female", "Male", "Other"],
+            index=["Prefer not to say", "Female", "Male", "Other"].index(current.gender)
+            if current.gender in ["Prefer not to say", "Female", "Male", "Other"] else 0,
+            key=f"{key_prefix}_gender",
+        )
+        high_chol = st.checkbox(
+            "High cholesterol", current.high_cholesterol, key=f"{key_prefix}_chol",
+            help="Flags and filters products above 4 g saturated fat per 100 g.",
+        )
+    avoid_additives = st.checkbox(
+        "Exclude products with additives EFSA flags as high-risk",
+        current.avoid_flagged_additives,
+        key=f"{key_prefix}_additives",
+    )
+
+    return UserProfile(
+        user_id=current.user_id,
+        age=int(age),
+        gender=gender,
+        allergens=[ALLERGEN_CHOICES[label] for label in selected_labels],
+        diets=diets,
+        high_blood_pressure=high_bp,
+        high_cholesterol=high_chol,
+        avoid_flagged_additives=avoid_additives,
+    )
+
+
+if profile.user_id:
+    st.success(f"Signed in as **{profile.user_id}**")
+    with st.form("prefs"):
+        updated = _preferences_form(profile, "signed")
+        if st.form_submit_button("Save preferences", type="primary"):
+            updated.user_id = profile.user_id
+            st.session_state.profile = updated
+            auth.save_profile(updated)
+            st.toast("Preferences saved.")
+
+    st.divider()
+    st.markdown("### Recently viewed")
+    history = auth.recent_views(profile.user_id)
+    if not history:
+        st.caption("Nothing viewed yet.")
+    else:
+        for entry in history[:15]:
+            st.markdown(
+                f"- **{entry.get('product_name') or 'Unnamed'}** "
+                f"<span class='nw-sub'>{entry.get('brands') or ''} · "
+                f"{entry.get('verdict') or ''}</span>",
+                unsafe_allow_html=True,
+            )
+    st.stop()
+
+
+tab_guest, tab_login, tab_register = st.tabs(
+    ["Use without an account", "Sign in", "Create account"]
+)
+
+with tab_guest:
+    st.caption(
+        "Set preferences for this session only. Nothing is stored and no account is needed."
+    )
+    with st.form("guest"):
+        guest_profile = _preferences_form(profile, "guest")
+        if st.form_submit_button("Apply", type="primary"):
+            st.session_state.profile = guest_profile
+            st.toast("Preferences applied for this session.")
+            st.rerun()
+
+with tab_login:
+    with st.form("login"):
+        user_id = st.text_input("Username")
+        password = st.text_input("Password", type="password")
+        if st.form_submit_button("Sign in", type="primary"):
+            result = auth.login(user_id, password)
+            if result.ok:
+                st.session_state.profile = result.profile
+                st.rerun()
+            else:
+                st.error(result.message)
+
+with tab_register:
+    with st.form("register"):
+        new_id = st.text_input("Choose a username")
+        new_pw = st.text_input("Choose a password", type="password", help="At least 8 characters.")
+        new_profile = _preferences_form(UserProfile(), "reg")
+        if st.form_submit_button("Create account", type="primary"):
+            result = auth.register(new_id, new_pw, new_profile)
+            if result.ok:
+                st.session_state.profile = result.profile
+                st.success(result.message)
+                st.rerun()
+            else:
+                st.error(result.message)

views/recommend.py

@@ -0,0 +1,107 @@
+"""Healthier swaps for the selected product."""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from components import badges, cards
+from nutriweb.data import catalog
+from nutriweb.reco import engine
+from views import state
+
+code = state.require_selection()
+if not code:
+    st.stop()
+
+product = catalog.get_product(code)
+if product is None:
+    st.error(f"No product found for barcode {code}.")
+    st.stop()
+
+profile = state.profile()
+
+st.markdown(
+    f"""<div class="nw-hero">
+        <h1>Healthier than {badges.title_of(product)}</h1>
+        <p>Same kind of product, better health score, filtered against your profile.</p>
+    </div>""",
+    unsafe_allow_html=True,
+)
+
+col_left, col_right = st.columns([1, 3], gap="large")
+with col_left:
+    st.markdown(
+        f'<div class="nw-card">{badges.thumb(product)}'
+        f"<h4>{badges.title_of(product)}</h4>"
+        f'<div class="nw-brand">{badges.brand_of(product) or "&nbsp;"}</div>'
+        f"{badges.badge_row(product)}"
+        f'{badges.health_meter(product.get("health_score"))}</div>',
+        unsafe_allow_html=True,
+    )
+    if st.button("← Back to product", width='stretch'):
+        state.open_product(code)
+
+with col_right:
+    top_n = st.slider("How many alternatives", 3, 12, 6, key="rec_n")
+
+    with st.spinner("Finding alternatives..."):
+        recommendations, basis = engine.recommend(product, profile, top_n=top_n)
+
+    if state.profile_is_empty():
+        st.info(
+            "You have no profile set, so these results are not filtered for allergens "
+            "or diet. Add them under **My profile** for personalised swaps."
+        )
+
+    if not recommendations:
+        message = basis.get("message", "No healthier alternatives found.")
+        # "Already the best option" is good news, not a failure.
+        if basis.get("reason") == "already_best":
+            st.success(f"✓ {message}")
+        else:
+            st.warning(message)
+            if basis.get("reason") == "filtered_out":
+                st.caption("Relaxing a dietary preference would surface these.")
+        st.stop()
+
+    # Be explicit about how the candidate set was chosen, rather than
+    # presenting results as if they came from nowhere.
+    if basis["mode"] == "category":
+        label = str(basis["category"]).split(":", 1)[-1].replace("-", " ")
+        st.caption(
+            f"Compared against **{basis['pool']}** products in **{label}** that pass your filters."
+        )
+    else:
+        st.caption(
+            f"This product has no category in Open Food Facts, so alternatives were "
+            f"matched by shared ingredients across **{basis['pool']}** candidates."
+        )
+
+    for start in range(0, len(recommendations), 3):
+        row = recommendations[start : start + 3]
+        for column, rec in zip(st.columns(3), row):
+            with column:
+                cards.recommendation_card(
+                    rec,
+                    key=f"rec_{rec.product['code']}",
+                    on_open=state.open_product,
+                )
+
+    with st.expander("How these were ranked"):
+        st.markdown(
+            f"""
+Candidates must be **healthier** than the original and must pass every hard
+filter from your profile — allergens and diet are exclusions, never trade-offs.
+Survivors are then ranked on a weighted blend:
+
+| Signal | Weight | What it measures |
+|---|---|---|
+| Health gain | {engine.W_HEALTH_GAIN:.0%} | Improvement in the 0–100 NutriWeb health score |
+| Macro similarity | {engine.W_MACRO:.0%} | Distance across energy, fat, carbs, sugar, fibre, protein and salt |
+| Ingredient overlap | {engine.W_INGREDIENT:.0%} | Jaccard overlap of Open Food Facts' canonical ingredient tags |
+| Popularity | {engine.W_POPULARITY:.0%} | Scan count, used only to break ties |
+
+The health score itself is 70% Nutri-Score 2023, 30% NOVA processing group,
+minus a penalty for additives flagged by EFSA or ANSES.
+"""
+        )

views/search.py

@@ -0,0 +1,85 @@
+"""Search — the landing page."""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from components import cards
+from nutriweb.data import catalog
+from views import state
+
+st.markdown(
+    """<div class="nw-hero">
+        <h1>Find a product, get a healthier swap</h1>
+        <p>Search by name or scan a barcode. Every result is checked against your
+        allergens, your diet and your health profile before it is recommended.</p>
+    </div>""",
+    unsafe_allow_html=True,
+)
+
+
+@st.cache_data(show_spinner=False, ttl=600)
+def _search(query: str, limit: int) -> list[dict]:
+    return catalog.search(query, limit=limit)
+
+
+@st.cache_data(show_spinner=False)
+def _stats() -> dict:
+    return catalog.stats()
+
+
+def _use_example(example: str) -> None:
+    """Fill the search box from an example chip."""
+    st.session_state.search_box = example
+
+
+query = st.text_input(
+    "Search",
+    placeholder="e.g. peanut butter, greek yogurt, or a barcode like 0049000028911",
+    label_visibility="collapsed",
+    key="search_box",
+)
+
+if not query:
+    stats = _stats()
+    st.caption(
+        f"{stats['products']:,} US products · {stats['scored']:,} with a health score · "
+        f"{stats['graded_by_nutriweb']:,} graded by NutriWeb where Open Food Facts had no grade"
+    )
+    st.markdown("##### Try one of these")
+    examples = ["greek yogurt", "peanut butter", "granola bar", "tortilla chips", "sparkling water"]
+    columns = st.columns(len(examples))
+    for column, example in zip(columns, examples):
+        # Seeding must happen in an on_click callback, not in the button's
+        # if-branch: Streamlit refuses assignment to a widget's key once that
+        # widget has been instantiated this run, and search_box is created
+        # above. Callbacks run before the rerun, so the assignment is legal.
+        column.button(
+            example,
+            width="stretch",
+            key=f"eg_{example}",
+            on_click=_use_example,
+            args=(example,),
+        )
+    st.stop()
+
+with st.spinner("Searching..."):
+    results = _search(query, 24)
+
+if not results:
+    st.warning(
+        f"Nothing matched **{query}**. Try a brand name, a simpler term, or a full barcode."
+    )
+    st.stop()
+
+st.caption(f"{len(results)} results for **{query}**")
+
+for start in range(0, len(results), 4):
+    row = results[start : start + 4]
+    for column, product in zip(st.columns(4), row):
+        with column:
+            cards.product_card(
+                product,
+                key=f"open_{product['code']}",
+                on_open=state.open_product,
+            )

views/state.py

@@ -0,0 +1,71 @@
+"""Shared session state and small navigation helpers."""
+
+from __future__ import annotations
+
+import streamlit as st
+
+from nutriweb.profile.model import UserProfile
+
+# Page paths, so navigation targets are declared in one place.
+SEARCH = "views/search.py"
+PRODUCT = "views/product.py"
+RECOMMEND = "views/recommend.py"
+COMPARE = "views/compare.py"
+PROFILE = "views/profile_page.py"
+
+
+def init() -> None:
+    st.session_state.setdefault("profile", UserProfile())
+    st.session_state.setdefault("selected_code", None)
+    st.session_state.setdefault("compare_codes", [])
+    st.session_state.setdefault("last_query", "")
+
+
+def profile() -> UserProfile:
+    return st.session_state.profile
+
+
+def profile_is_empty() -> bool:
+    """True when the user has told us nothing we could filter on."""
+    p = profile()
+    return not (
+        p.allergens or p.diets or p.high_blood_pressure
+        or p.high_cholesterol or p.avoid_flagged_additives
+    )
+
+
+def open_product(code: str) -> None:
+    st.session_state.selected_code = code
+    st.switch_page(PRODUCT)
+
+
+def open_recommendations(code: str) -> None:
+    st.session_state.selected_code = code
+    st.switch_page(RECOMMEND)
+
+
+def add_to_compare(code: str) -> str:
+    codes: list[str] = st.session_state.compare_codes
+    if code in codes:
+        return "already"
+    if len(codes) >= 3:
+        return "full"
+    codes.append(code)
+    return "added"
+
+
+def sign_out() -> None:
+    st.session_state.profile = UserProfile()
+    st.session_state.selected_code = None
+    st.session_state.compare_codes = []
+
+
+def require_selection() -> str | None:
+    """Guard for pages that need a chosen product."""
+    code = st.session_state.get("selected_code")
+    if not code:
+        st.info("Pick a product from Search first.")
+        if st.button("Go to Search"):
+            st.switch_page(SEARCH)
+        return None
+    return code