feat(training): mouthfeel modality — 5 chemesthesis heads surfaced across the stack (#243)

Mouthfeel is trigeminal, not olfactory, so it ships as its own modality end-to-end
(build_mouthfeel_supplement -> build_mouthfeel_dataset -> train_mouthfeel -> mouthfeel_models/),
mirroring the independent taste subsystem. Five heads clear the honest bar (>=10 public positives
and CV-AUROC >= 0.70): cooling 0.94, pungent 0.98, warming 0.99, astringent 1.00, tingling 1.00.
Bench sanity: capsaicin -> pungent/warming 1.0, menthol -> cooling 1.0.

cooling and pungent exist as BOTH aroma and mouthfeel heads (as sweet is both taste and aroma) —
the aroma head predicts the smell, the mouthfeel head the sensation; the profile index keys them by
dimension so they cannot collide. The flavor-profile vector is now 175 dims (6 taste + 164 aroma +
5 mouthfeel); tox stays out of it deliberately. 187 trained heads total.

Surfaced per the keep-in-sync rule: modal Heads card gained Mouthfeel + Safety groups (every head a
ranked %-bar with CV-AUROC), MCP read_flavor and the CLI skill return mouthfeel_scores + tox_flags,
new MCP list_heads tool over GET /api/heads. Tox21 heads gained a CV-AUROC manifest (0.72-0.90) and
per-molecule storage in master_enrichment (8,847 molecules; 17 previously-missing curated molecules
folded in). Training and index build parallelized process-per-unit (index ~3 min -> ~35 s), worker
counts derived from os.cpu_count(). Models load on a background thread so uvicorn binds instantly
behind a branded warming page instead of a ~90 s startup 502. Flavor-map axes no longer clip.

Closes #232. Closes #235. Closes #237. Closes #239. Closes #242.

Author: rvnminers-A-and-N

README.md

@@ -17,20 +17,21 @@ running entirely on hardware you own.
 <p align="center">
   <img src="docs/assets/flavor-map.png" alt="Flavor-space map in 3D on MW × logP × TPSA axes, colored by taste and aroma" width="900">
 </p>
-<p align="center"><sub>The interactive flavor-space map in 3D on real <b>MW × logP × TPSA</b> axes, colored by <b>taste &amp; aroma</b> — every one of the 164 aroma + 6 taste classes labelled.</sub></p>
+<p align="center"><sub>The interactive flavor-space map in 3D on real <b>MW × logP × TPSA</b> axes, colored by <b>taste &amp; aroma</b> — every one of the 164 aroma + 6 taste classes labelled. <b>187 trained heads</b> in all: 6 taste + 164 aroma + 5 mouthfeel + 12 safety.</sub></p>
 
-> **8,830 unique molecules** across the open datasets · **taste + aroma** prediction from
+> **8,847 unique molecules** across the open datasets · **taste + aroma + mouthfeel** prediction from
 > structure · a **flavor library** (start from a flavor → its character-impact molecule) and
 > **flavor designer** (pick your notes → best food-safe molecules + drop-in swaps) · an
 > interactive 2D/3D **flavor-space map** · **2D & 3D** structure views. All on
 > commercial-clean public data.
 >
 > Per set (unique molecules): taste training **3,845** · aroma training **2,394** · odor
-> corpus **2,255** · documented taste **676** · GRAS reference **2,781** · sweetness
-> intensity **316** · character-impact aroma supplement **602 associations** (open-gov-sourced).
-> Every one of the 8,830 is enriched with names + measured properties from public-domain PubChem.
+> corpus **2,255** · documented taste **676** · mouthfeel training **2,534** · Tox21 (safety)
+> **7,823** · GRAS reference **2,781** · sweetness intensity **316** · character-impact aroma
+> supplement **602 associations** (open-gov-sourced). Every one of the 8,847 is enriched with
+> names + measured properties from public-domain PubChem.
 >
-> *How the universe grows:* the flavor-space map and enrichment table show **8,830 unique
+> *How the universe grows:* the flavor-space map and enrichment table show **8,847 unique
 > structures** (deduped by connectivity skeleton), expanded by ingesting the **full EU/GB
 > flavourings Union List (~2,200 authorised, Open Government Licence v3)** so the browse-able
 > universe is food-forward. Meaningfully-distinct stereoisomers (e.g. R- vs S-limonene) that carry
@@ -70,12 +71,17 @@ is tagged by how it was derived**, so nothing reads as more certain than its sou
   (computed); water solubility (ESOL estimate); volatility tier and pKa ranges
   (qualitative); measured boiling point / vapor pressure when a property table is
   loaded (lookup — structure-based BP was evaluated and declined as too inaccurate).
-- **Stability & chemesthesis** — oxidation / hydrolysis / photo watch-flags;
-  cooling / pungent / astringent class flags.
+- **Mouthfeel** — **five trained chemesthesis heads** (cooling / pungent / warming /
+  astringent / tingling): the *trigeminal* sensation, trained on curated public-domain
+  agents (menthol & WS-coolants, capsaicinoids, tannins, Sichuan-pepper sanshools), each
+  with its held-out CV-AUROC. Distinct from the same-named aroma notes — the sensation, not
+  the smell (menthol *feels* cool; WS-23 cools with almost no odour).
+- **Stability** — oxidation / hydrolysis / photo watch-flags.
 - **Safety (defensive, caution-only)** — a disclaimer + scope on every result,
-  structural tox-alert screening, a preliminary TTC/Cramer concern tier, an optional
-  GRAS cross-reference, and EU declarable-allergen labeling. It **flags for review;
-  it never clears a compound for use.**
+  **twelve Tox21 in-vitro assay heads** (nuclear-receptor + stress-response, each with its
+  CV-AUROC) surfaced as *indicative* review flags, structural tox-alert screening, a
+  preliminary TTC/Cramer concern tier, an optional GRAS cross-reference, and EU
+  declarable-allergen labeling. It **flags for review; it never clears a compound for use.**
 - **Formulation** — a documented dangerous-mixture screen (benzene, nitrosamine,
   acrylamide, ethyl carbamate, furan, and more) and an OAV dosing-balance analysis
   that flags the component about to overpower a blend (quantitative when threshold

docs/CAPABILITIES.md

@@ -6,10 +6,11 @@ shape of the tool. The organizing discipline throughout: **every output is tagge
 by how it's derived, and nothing claims more certainty than its source supports.**
 
 > **Edition note.** This catalogues the **commercial** edition (Apache-2.0,
-> commercial-clean data). **Aroma ships here** as 24 presence/absence odor-descriptor
-> heads trained on public-domain HSDB text — what's still gated is scored **intensity**
-> (*how strong* a note is), which needs research/customer panel data and lives in the
-> **academic edition** (or trains on a customer's own data, on-prem).
+> commercial-clean data). **Aroma ships here** as 164 presence/absence odor-descriptor
+> heads trained on public-domain HSDB text (plus 5 mouthfeel/chemesthesis heads and 12
+> Tox21 safety heads) — what's still gated is scored **intensity** (*how strong* a note
+> is), which needs research/customer panel data and lives in the **academic edition**
+> (or trains on a customer's own data, on-prem).
 
 **Confidence tiers used below**
 - **computed** — exact from structure (RDKit). Not a prediction; a calculation.
@@ -52,16 +53,20 @@ by how it's derived, and nothing claims more certainty than its source supports.
 **Stability**
 - Oxidation / hydrolysis / photodegradation watch-flags (**rule/qualitative**).
 
-**Chemesthesis (trigeminal)**
-- Cooling / pungent / astringent class flags (**rule/lookup**, qualitative).
+**Mouthfeel / chemesthesis (trigeminal)** — **five trained sensation heads ship** (**trained**)
+- Cooling / pungent / warming / astringent / tingling — RandomForests on fingerprint +
+  physicochemical features, over curated public-domain trigeminal agents (menthol & WS-coolants,
+  capsaicinoids, tannins/polyphenols, Sichuan-pepper sanshools). CV-AUROC **0.94–1.00** (narrow,
+  structurally-distinct classes). Its own modality (`mouthfeel_models/`), distinct from the
+  same-named *aroma* odour heads — the sensation, not the smell. See [`MOUTHFEEL.md`](MOUTHFEEL.md).
 
 **Safety (all defensive, caution-only — never a clearance)**
 - Disclaimer + scope on every result.
 - Structural tox-alert screen — nitro/N-nitroso/azo/epoxide (**rule**).
 - GRAS / approved-ingredient cross-reference — FDA SAF, public domain, `build_gras_reference.py` (**lookup**).
 - **In-vitro tox-assay flags** — 12 Tox21 assays (genotoxic-stress SR-p53/SR-ATAD5, AhR,
-  mitochondrial, endocrine), `predict_tox()` (**trained**, Tox21 public domain). INDICATIVE
-  activity for review, **never a determination**.
+  mitochondrial, endocrine), `predict_tox()` (**trained**, Tox21 public domain; CV-AUROC
+  **0.72–0.90**, surfaced per assay). INDICATIVE activity for review, **never a determination**.
 - Preliminary TTC concern tier (**qualitative** heuristic; Toxtree for the real call).
 - EU declarable fragrance-allergen labeling flag — `labeling()` (**lookup**, curated subset).
 

docs/MOUTHFEEL.md

@@ -0,0 +1,60 @@
+# Mouthfeel — a public-domain chemesthesis model
+
+Flavor = taste **+** aroma **+** mouthfeel. Taste and aroma ship as trained heads
+([`AROMA.md`](AROMA.md)); this documents the third modality — **mouthfeel / chemesthesis**,
+the *trigeminal* (somatosensory) sensations in the mouth: cooling, pungency/heat, tingling,
+astringency. It is a **separate modality**, not a slice of aroma — a molecule can *smell* minty
+without *feeling* cool, and WS-23 cools the mouth with almost no odour at all.
+
+## What ships (2026-07)
+
+**Five trained heads**, one RandomForest per sensation on the Morgan fingerprint + physicochemical
+block (the same stack as taste/aroma), in their own `mouthfeel_models/` directory, loaded and tagged
+`mouthfeel` by `predict.py` and folded into the 175-dim flavor-profile vector used for substitutes.
+
+| head | what it is | held-out CV-AUROC |
+|---|---|---|
+| **cooling** | TRPM8 coolants — menthol family + food-authorised WS-agents | 0.94 |
+| **pungent** | TRPV1 / mustard-oil heat & bite — capsaicinoids, isothiocyanates, allium sulfur | 0.98 |
+| **warming** | capsaicinoid & warm-spice heat — chili, pepper, ginger, cinnamon | 0.99 |
+| **astringent** | tannins & polyphenols — the puckering, mouth-drying sensation | 1.00 |
+| **tingling** | paresthesia alkylamides — Sichuan-pepper sanshools, jambu spilanthol, ZP-amides | 1.00 |
+
+The high AUROCs reflect **narrow, structurally-distinct classes** (a capsaicinoid does not look like
+a tannin) trained against a broad random background — honest for what they are, but not a claim of
+fine-grained intensity resolution. Like aroma, this is **presence/absence**, not scored intensity.
+
+## `cooling` / `pungent` exist in **both** aroma and mouthfeel
+
+Deliberately — exactly as `sweet` is both a taste head and an aroma head. The *aroma* `cooling`
+head predicts a molecule that **smells** cool/minty (menthol, eucalyptol); the *mouthfeel* `cooling`
+head predicts the **TRPM8 sensation** (menthol, but also odourless WS-coolants). Same name, different
+modality. The profile index keys them by dimension (`aroma:cooling` vs `mouthfeel:cooling`) so they
+never collide, and the read surfaces each under its own group.
+
+## Pipeline
+
+- `build_mouthfeel_supplement.py` — the curated list: descriptor → well-known public-domain
+  trigeminal-agent **names** (capsaicin, menthol, gallic acid, hydroxy-α-sanshool, …), resolved to
+  authoritative canonical SMILES via PubChem (a SMILES hint is supported where a name isn't a
+  PubChem synonym). Same provenance discipline as the aroma supplement: only measured, public-domain
+  structure→sensation facts (Feist — descriptors aren't copyrightable), never copied from a
+  restricted compilation.
+- `build_mouthfeel_dataset.py` — positives from the supplement + a broad random background from the
+  molecule universe (a molecule with no documented chemesthesis is a negative) → `mouthfeel_train.parquet`.
+- `train_mouthfeel.py` — one head per sensation, honest bar: ≥10 positives **and** 5-fold
+  CV-AUROC ≥ 0.70, else dropped. Kept heads + AUROC → `mouthfeel_models/` (+ `manifest.json`).
+
+## Food safety is separate
+
+A head predicts a **sensation**, not a food-use clearance. Its training molecules are food-present
+naturals (capsaicin in chili, tannins in tea/wine) plus food-authorised agents (nonivamide FL/GRAS,
+tannic acid 21 CFR) — but that a molecule is a good *warming* example does not assert it is a
+flavouring. The per-molecule food-safe flag and the standing IP/food review gate still govern any
+commercial use, exactly as for the aroma corpus.
+
+## Near-misses (documented, not shipped)
+
+`tingling` sits right at the bar — the pure sanshool/spilanthol/ZP-amide class is genuinely small
+(~11 public structures). It ships, but strictly on real paresthesia agents; the Piper long-pepper
+amides that *read pungent* were routed to the aroma `pungent` head instead, not used to pad tingling.

mcp-server/server.py

@@ -68,6 +68,8 @@ def _read_flavor(molecule: str) -> dict:
     if isinstance(d.get("salty_predicted"), (int, float)):
         taste["salty"] = d["salty_predicted"]
     descriptors = (aroma.get("predicted") or {}).get("descriptors", [])
+    mouth = (d.get("mouthfeel") or {}).get("descriptors", [])  # trained trigeminal heads
+    tox = (safety.get("tox_screen") or {}).get("assays", [])   # Tox21 caution-only assay heads
     return {
         "name": names.get("common"), "iupac": names.get("iupac"),
         "formula": names.get("formula"), "smiles": d.get("smiles"),
@@ -76,10 +78,14 @@ def _read_flavor(molecule: str) -> dict:
         "confident_aromas": [x["odor"] for x in descriptors if x.get("confident")],
         "all_aroma_scores": {x["odor"]: round(x["score"], 3) for x in descriptors},
         "aroma_descriptions": {x["odor"]: x["desc"] for x in descriptors if x.get("desc")},
+        "mouthfeel_scores": {x["sensation"]: x["score"] for x in mouth},
+        "confident_mouthfeel": [x["sensation"] for x in mouth if x.get("confident")],
         "gras_status": safety.get("gras_status"),
         "structural_alerts": safety.get("structural_alerts"),
+        "tox_flags": [a["assay"] for a in tox if (a.get("probability") or 0) >= 0.5],
         "in_applicability_domain": (d.get("applicability") or {}).get("in_domain"),
-        "disclaimer": "Flavor prediction only — NOT a safety, GRAS, or regulatory determination.",
+        "disclaimer": "Flavor prediction only — NOT a safety, GRAS, or regulatory determination. "
+                      "Tox flags are indicative in-vitro assay activity, never a toxicity determination.",
     }
 
 
@@ -248,14 +254,25 @@ def _flavor_map(label: str, limit: int, full: bool) -> dict:
 # ── MCP tool surface ─────────────────────────────────────────────────────────
 @mcp.tool()
 def read_flavor(molecule: str) -> dict:
-    """Predict the taste + aroma of a single molecule (name or SMILES).
+    """Predict the flavor of a single molecule (name or SMILES).
 
-    Returns the six taste-head probabilities, confident aromas plus all 24 aroma scores,
-    GRAS status, structural alerts, and applicability-domain flag. Prediction only.
+    Returns the six taste-head probabilities, confident aromas plus all 164 aroma scores, the
+    trained mouthfeel/chemesthesis scores (cooling/pungent/warming/astringent/tingling), GRAS
+    status, structural alerts, caution-only Tox21 flags, and the applicability-domain flag.
+    Prediction only — tox flags are indicative in-vitro activity, never a determination.
     """
     return _read_flavor(molecule)
 
 
+@mcp.tool()
+def list_heads() -> dict:
+    """The full model-head catalog grouped by category — taste / aroma / mouthfeel / safety —
+    each head with its held-out CV-AUROC. Categories are tags, not buckets (a head can appear in
+    more than one). Useful to see the complete predictable dimension set."""
+    with _client() as c:
+        return c.get("/api/heads").json()
+
+
 @mcp.tool()
 def read_full(molecule: str) -> dict:
     """The COMPLETE read of a molecule: everything read_flavor gives PLUS physicochemical
@@ -267,20 +284,22 @@ def read_full(molecule: str) -> dict:
 
 
 @mcp.tool()
-def find_substitutes(molecule: str, k: int = 8) -> dict:
-    """Find the k best SUBSTITUTES — molecules whose predicted taste+aroma PROFILE is closest to
-    the given molecule (cosine over the head scores). These are the drop-in swaps: a molecule that
-    tastes and smells like the target, regardless of structure (e.g. ethyl vanillin for vanillin).
-    Each with its profile_match, known tastes, and aromas.
+def find_substitutes(molecule: str, k: int = 25) -> dict:
+    """Find SUBSTITUTES — molecules whose predicted taste+aroma PROFILE is closest to the given
+    molecule (cosine over the head scores). These are the drop-in swaps: a molecule that tastes
+    and smells like the target, regardless of structure (e.g. ethyl vanillin for vanillin). Returns
+    every match above a profile-similarity floor, ranked, up to k. Each with its profile_match,
+    known tastes, and aromas.
     """
     return _find_substitutes(molecule, k)
 
 
 @mcp.tool()
-def find_structural_neighbors(molecule: str, k: int = 8) -> dict:
-    """Find the k STRUCTURAL neighbors — molecules most similar in structure (Tanimoto / Morgan
+def find_structural_neighbors(molecule: str, k: int = 25) -> dict:
+    """Find STRUCTURAL neighbors — molecules most similar in structure (Tanimoto / Morgan
     fingerprint) to the given molecule. Structural look-alikes (contrast find_substitutes, which
-    matches by taste+aroma profile). Each with its similarity and known tastes.
+    matches by taste+aroma profile). Returns every match above a similarity floor, ranked, up to k.
+    Each with its similarity and known tastes.
     """
     return _find_structural_neighbors(molecule, k)
 

skills/flavormancer/scripts/flavormancer.py

@@ -75,12 +75,17 @@ def cmd_read(a):
         if isinstance(d.get(k), (int, float)):
             taste[lbl] = round(d[k], 3)
     desc = (aroma.get("predicted") or {}).get("descriptors", [])
+    mouth = (d.get("mouthfeel") or {}).get("descriptors", [])
+    tox = ((d.get("safety") or {}).get("tox_screen") or {}).get("assays", [])
     return {"name": names.get("common"), "iupac": names.get("iupac"),
             "formula": names.get("formula"), "smiles": d.get("smiles"),
             "taste_probabilities": taste, "sour_rule": d.get("sour"), "salty_rule": d.get("salty"),
             "confident_aromas": [x["odor"] for x in desc if x.get("confident")],
             "aroma_descriptions": {x["odor"]: x["desc"] for x in desc if x.get("desc")},
+            "mouthfeel": {x["sensation"]: x["score"] for x in mouth},
+            "confident_mouthfeel": [x["sensation"] for x in mouth if x.get("confident")],
             "gras_status": (d.get("safety") or {}).get("gras_status"),
+            "tox_flags": [a["assay"] for a in tox if (a.get("probability") or 0) >= 0.5],
             "in_applicability_domain": (d.get("applicability") or {}).get("in_domain")}
 
 
@@ -202,10 +207,10 @@ def mol(name):
     mol("read-full").set_defaults(fn=cmd_read_full)
     mol("stereoisomers").set_defaults(fn=cmd_stereoisomers)
     s = mol("substitutes")   # taste+aroma profile match (the drop-in swaps)
-    s.add_argument("-k", type=int, default=8)
+    s.add_argument("-k", type=int, default=25, help="max results (every match above a profile floor)")
     s.set_defaults(fn=cmd_substitutes)
     s = mol("structural-neighbors")   # Tanimoto structural look-alikes
-    s.add_argument("-k", type=int, default=8)
+    s.add_argument("-k", type=int, default=25, help="max results (every match above a similarity floor)")
     s.set_defaults(fn=cmd_structural_neighbors)
 
     s = sub.add_parser("formulate")

tests/conftest.py

@@ -2,4 +2,8 @@
 import os
 import sys
 
+# The app loads model heads on a background thread in production (instant bind + warming page).
+# Tests need them present the moment `import predict` returns, so force the synchronous load path.
+os.environ.setdefault("FLAVORMANCER_BLOCKING_LOAD", "1")
+
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "training"))

tests/test_substitute.py

@@ -49,3 +49,23 @@ def test_mixture_to_molecule_rejects_all_bad(monkeypatch):
     monkeypatch.setattr(predict, "_SUB_INDEX", ([], [], [], [], None, []))
     out = predict.mixture_to_molecule(["nope", "xyz"])
     assert "error" in out
+
+
+def test_substitutes_threshold_and_index_lookup(monkeypatch):
+    """substitutes() returns every match above min_match (self excluded), ranked; and an in-corpus
+    query reads its profile straight off the index row (no forests) via _query_profile/_index_row."""
+    import numpy as np
+    mols = ["CCO", "CCCO", "c1ccccc1"]  # ethanol, propanol, benzene
+    canon = [_canon(s) for s in mols]
+    fps = [predict._MORGAN.GetFingerprint(Chem.MolFromSmiles(s)) for s in mols]
+    profiles = np.array([[1.0, 0.0, 0.0], [0.9, 0.1, 0.0], [0.0, 0.0, 1.0]], dtype="float32")
+    dims = ["taste:sweet", "aroma:x", "aroma:y"]
+    monkeypatch.setattr(predict, "_CLASSIFIERS", {"sweet": None})  # 1 taste col, matches the mock width
+    monkeypatch.setattr(predict, "_SUB_INDEX", (fps, canon, [[], [], []], [[], [], []], profiles, dims))
+    predict._PN_CACHE.clear(); predict._SKEL2ROW.clear()
+    # ethanol is in the index -> query profile is its row (no model inference needed)
+    assert predict._index_row(Chem.MolFromSmiles("CCO")) == 0
+    out = predict.substitutes("CCO", k=10, min_match=0.5)
+    subs = out["substitutes"]
+    assert [n["smiles"] for n in subs] == [_canon("CCCO")]  # propanol passes 0.5; benzene (orthogonal) filtered; self excluded
+    assert subs[0]["profile_match"] >= 0.5