Merge pull request #204 from echelonts/feat/aroma-37-heads-and-formula

37 aroma heads + molecular-formula identifier + all heads pickable

Author: rvnminers-A-and-N

README.md

@@ -17,15 +17,15 @@ 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 34 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 37 aroma + 6 taste classes labelled.</sub></p>
 
 > **8,393 unique molecules** across the open datasets · **taste + aroma** 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 **1027** · odor
+> Per set (unique molecules): taste training **3,845** · aroma training **1034** · odor
 > corpus **2,255** · documented taste **676** · GRAS reference **2,781** · sweetness
 > intensity **316** · curated character-impact flavors **95 flavors / 77 molecules** · public-domain aroma supplement **102 associations**.
 > Every one of the 8,393 is enriched with names + measured properties from public-domain PubChem.
@@ -59,7 +59,7 @@ is tagged by how it was derived**, so nothing reads as more certain than its sou
   **tasteless** (RandomForests on fingerprint + physicochemical features), plus a
   sweetness-**intensity** regressor. Sour and salty *also* keep a transparent chemistry
   rule (acid group / alkali-salt) as a deterministic cross-check alongside the model.
-- **Aroma** — **34 odor-descriptor heads** (citrus, floral, minty, almond, fatty,
+- **Aroma** — **37 odor-descriptor heads** (citrus, floral, minty, almond, fatty,
   petroleum, earthy, medicinal, sulfurous, camphor, fruity, fishy, garlic, ethereal,
   ammoniacal, pungent, pine, rose, rancid, alcoholic, woody, green, grassy, putrid)
   trained on **public-domain** HSDB odor text + curated character-impact facts, surfaced
@@ -154,7 +154,7 @@ Flavormancer ships as two editions of one method:
 | Edition | Commercial | Academic / open-source *(coming soon)* |
 | License | Apache-2.0 | open-source, **research / NonCommercial** |
 | Data | commercial-clean open data only | adds research odor datasets with **NonCommercial** terms |
-| Aroma | **34 presence/absence descriptor heads ship** (public-domain HSDB); scored **intensity** is trained on your data or a licensed set (PMP 2001) | full open model incl. **intensity** (research odor data) |
+| Aroma | **37 presence/absence descriptor heads ship** (public-domain HSDB); scored **intensity** is trained on your data or a licensed set (PMP 2001) | full open model incl. **intensity** (research odor data) |
 | Use | free to use, sell, run on-prem | research, teaching, advancing the method |
 
 The split is deliberate. The richest aroma data is licensed for research only, so

docs/AROMA-AUDIT.md

@@ -2,12 +2,20 @@
 
 > **Update — supplement applied.** `build_aroma_supplement.py` added a curated **public-domain**
 > character-impact set (`aroma_supplement.csv`, resolved via PubChem) for the sparse descriptors
-> below. Result: **24 → 34 heads** — **10 new**: `coconut` (0.89), `nutty` (0.94), `caramel` (0.91),
+> below. Result: **24 → 37 heads** — **13 new**: `coconut` (0.89), `nutty` (0.94), `caramel` (0.91),
 > `winey` (0.90), `onion` (0.87), `honey` (0.80), `herbal` (0.80), `vanilla` (0.93), `buttery` (0.87),
-> `balsamic` (0.93) — and `grassy` kept above the bar
-> (0.80) with its classic green-leaf volatiles. `coconut` is now *predictable* (γ-nonalactone →
-> coconut 1.0), which closes its earlier data-gate. `spicy` (0.667) and `sweet`-odor (0.646) stayed
-> unlearnable even with more data — a real representation limit (revisit with a GNN). The numbers
+> `balsamic` (0.93), `smoky` (0.99), `cinnamon` (1.00), `spicy` (0.71) — and `grassy` kept above the
+> bar (0.80) with its classic green-leaf volatiles. `coconut` is now *predictable* (γ-nonalactone →
+> coconut 1.0), which closes its earlier data-gate. `spicy` finally crossed (0.71, borderline — it
+> shares character molecules with cinnamon/clove). **Only `sweet`-odor (0.637) remains unlearnable**
+> even with 185 examples — a genuine representation limit (revisit with a GNN).
+>
+> **Small-n caveat (honest):** the *highest*-AUROC new heads are small, structurally-homogeneous
+> classes — e.g. `cinnamon` reaches CV-AUROC **1.00** only because all 10 positives are one
+> cinnamaldehyde-family scaffold the fingerprint separates trivially. That is memorising a scaffold,
+> not a superb general model: these heads are **narrow and high-variance** (like `grassy`/`coffee`)
+> and will sharpen — or get honestly re-scored — with more diverse examples. Treat AUROC on n≈10
+> heads as indicative, not gospel. The numbers
 > below describe the **pre-supplement** baseline + the standing plan.
 
 

docs/AROMA.md

@@ -18,7 +18,7 @@ enumerable via the annotations API. Pipeline:
   physicochemical descriptor block** (`chemfeatures.py`: MW, logP, TPSA, H-bond donors/
   acceptors, rotatable bonds, ring counts, fraction sp3, heteroatoms — the global properties
   bare bits miss). After broadening the vocabulary, folding the curated `flavors.csv` molecules
-  in (825 → **1027** molecules, incl. a curated public-domain supplement), and adding those features, **34 heads clear CV-AUROC ≥ 0.70**
+  in (825 → **1034** molecules, incl. a curated public-domain supplement), and adding those features, **37 heads clear CV-AUROC ≥ 0.70**
   (each score is that descriptor's own held-out AUROC): medicinal 0.97, ammoniacal 0.96,
   petroleum 0.96, citrus 0.94, camphor 0.93, almond 0.92, fatty 0.89, minty 0.88, ethereal 0.87,
   fruity 0.87, fishy 0.86, sulfurous 0.85, garlic 0.84, floral 0.83, pungent 0.81, earthy 0.73.

docs/CAPABILITIES.md

@@ -32,7 +32,7 @@ by how it's derived, and nothing claims more certainty than its source supports.
 - Multitaste — fires when 2+ taste heads are high (**trained**-derived).
 - Known-taste ground truth — verified labels override predictions (**lookup**).
 
-**Aroma** — **34 odor-descriptor heads ship** (**trained**)
+**Aroma** — **37 odor-descriptor heads ship** (**trained**)
 - Presence/absence per descriptor (citrus, floral, minty, almond, fatty, petroleum, earthy,
   medicinal, sulfurous, camphor, fruity, fishy, garlic, ethereal, ammoniacal, pungent) —
   RandomForests on fingerprint + physicochemical features, over public-domain HSDB odor text +

docs/HOW-IT-WORKS.md

@@ -62,7 +62,7 @@ features (trained on SweetenersDB).
 
 ---
 
-## 3. Aroma — 34 descriptor heads from public odor text
+## 3. Aroma — 37 descriptor heads from public odor text
 
 Odor is the hard, licensed part of this field — most rich odor datasets are NonCommercial. Our
 clean route:
@@ -75,7 +75,7 @@ clean route:
    `minty`), producing a presence/absence label per descriptor. We also fold in the curated
    character-impact facts from `flavors.csv`.
 3. **`train_aroma.py`** trains one RandomForest per descriptor (on fingerprint + descriptors) and
-   **keeps only the heads that clear CV-AUROC ≥ 0.70** — an honest bar. **34 heads** survive
+   **keeps only the heads that clear CV-AUROC ≥ 0.70** — an honest bar. **37 heads** survive
    (citrus, floral, minty, almond, fatty, petroleum, earthy, medicinal, sulfurous, camphor,
    fruity, fishy, garlic, ethereal, ammoniacal, pungent, pine, rose, rancid, alcoholic,
    woody, green, grassy, putrid), 0.71–0.98. The lower-population heads (≈10–20 documented

mcp-server/server.py

@@ -69,7 +69,8 @@ def _read_flavor(molecule: str) -> dict:
         taste["salty"] = d["salty_predicted"]
     descriptors = (aroma.get("predicted") or {}).get("descriptors", [])
     return {
-        "name": names.get("common"), "iupac": names.get("iupac"), "smiles": d.get("smiles"),
+        "name": names.get("common"), "iupac": names.get("iupac"),
+        "formula": names.get("formula"), "smiles": d.get("smiles"),
         "taste_probabilities": {k: round(v, 3) for k, v in taste.items()},
         "sour_rule": d.get("sour"), "salty_rule": d.get("salty"),
         "confident_aromas": [x["odor"] for x in descriptors if x.get("confident")],

skills/flavormancer/scripts/flavormancer.py

@@ -75,7 +75,8 @@ def cmd_read(a):
         if isinstance(d.get(k), (int, float)):
             taste[lbl] = round(d[k], 3)
     desc = (aroma.get("predicted") or {}).get("descriptors", [])
-    return {"name": names.get("common"), "iupac": names.get("iupac"), "smiles": d.get("smiles"),
+    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")],
             "gras_status": (d.get("safety") or {}).get("gras_status"),

training/app.py

@@ -323,7 +323,15 @@ def api_names(q: Query):
     # resolves to Title "3-Phenylprop-2-Enal"), which then looks like the IUPAC name repeated.
     if smi and raw and Chem.MolFromSmiles(raw) is None:
         common = raw[:1].upper() + raw[1:]
-    return {"common": common, "iupac": iupac, "smiles": smi}
+    return {"common": common, "iupac": iupac, "smiles": smi, "formula": _formula(smi)}
+
+
+def _formula(smi):
+    """Hill-system molecular formula (e.g. C9H16O2) — a compact 4th identifier alongside
+    common / IUPAC / SMILES. None for an unparseable SMILES."""
+    from rdkit.Chem import rdMolDescriptors
+    m = Chem.MolFromSmiles(smi) if smi else None
+    return rdMolDescriptors.CalcMolFormula(m) if m is not None else None
 
 
 @app.post("/api/structure")
@@ -504,7 +512,8 @@ def font(path, size):
     if iupac and iupac.lower() != name.lower():
         dr.text((x, 206), ("IUPAC  " + iupac)[:64], font=f_body, fill=muted)
     dr.text((x, 232), smi[:58], font=f_mono, fill=muted)
-    dr.text((x, 280), "READS AS", font=f_lab, fill=muted)
+    dr.text((x, 254), "formula  " + (_formula(smi) or ""), font=f_mono, fill=muted)
+    dr.text((x, 282), "READS AS", font=f_lab, fill=muted)
     px, py = x, 306
     for text, c in pill_items:
         w = dr.textlength(text, font=f_pill)
@@ -1160,6 +1169,17 @@ def _precompute_design():
                 continue
             pool.append({"smiles": smi, "name": nm, "tags": tags, "gras": skel in P._GRAS})
             cnt.update(tags)
+        # fold the curated character-impact molecules (supplement + flavors) into the index so
+        # their descriptors (coconut, nutty, vanilla, cinnamon...) are searchable + offerable even
+        # where the industrial-skewed odor corpus is thin on them
+        for note, carriers in _NOTE_CARRIERS.items():
+            for csmi, cnm in carriers:
+                cm = Chem.MolFromSmiles(csmi)
+                if cm is None:
+                    continue
+                pool.append({"smiles": csmi, "name": cnm or "", "tags": {note},
+                             "gras": Chem.MolToInchiKey(cm).split("-")[0] in P._GRAS})
+                cnt.update([note])
         _DESIGN[:] = pool
         _DESIGN_DESCS[:] = sorted(d for d, n in cnt.items() if n >= 5)
     except Exception:  # noqa: BLE001 — no corpus/models; designer just stays empty
@@ -1389,6 +1409,7 @@ def api_nl(q: str = ""):
     {"key": "name", "label": "Common name", "why": "Everyday name (PubChem Title, public domain) where one exists."},
     {"key": "iupac", "label": "IUPAC name", "why": "Systematic IUPAC name (public-domain PubChem) — the unambiguous identity."},
     {"key": "smiles", "label": "SMILES", "why": "The machine-readable structure string the models actually read."},
+    {"key": "formula", "label": "Formula", "why": "Hill-system molecular formula (e.g. C9H16O2) — a compact 4th identifier."},
     {"key": "taste", "label": "Taste", "why": "Documented taste where known, else the model's call — what it tastes like."},
     {"key": "aroma_top", "label": "Aroma", "why": "The strongest predicted odor descriptor — the note it most reads as."},
     {"key": "mw", "label": "MW", "why": "Molecular weight (Da) — size. Heavier molecules are generally less volatile, so aroma fades."},
@@ -1420,6 +1441,7 @@ def _s(v):  # NaN (a truthy float) -> "" ; keep real strings
         iupac = (_NAME_TABLE.get(skel) or (None, None))[1] if isinstance(skel, str) else None
         rows.append({
             "smiles": r["smiles"], "name": _s(r.get("name")), "iupac": iupac or "",
+            "formula": _formula(r["smiles"]) or "",
             "taste": taste, "aroma_top": _s(r.get("aroma_top")),
             "mw": _num(r.get("mw")), "logp": _num(r.get("logp")), "tpsa": _num(r.get("tpsa")),
             "hbd": _num(r.get("hbd")), "hba": _num(r.get("hba")), "rot_bonds": _num(r.get("rot_bonds")),

training/aroma_supplement.csv

@@ -41,6 +41,10 @@ cinnamon,cinnamic acid,O=C(O)C=Cc1ccccc1,aroma-supplement
 cinnamon,methyl cinnamate,COC(=O)C=Cc1ccccc1,aroma-supplement
 cinnamon,ethyl cinnamate,CCOC(=O)C=Cc1ccccc1,aroma-supplement
 cinnamon,cinnamyl acetate,CC(=O)OCC=Cc1ccccc1,aroma-supplement
+cinnamon,alpha-methylcinnamaldehyde,CC(C=O)=Cc1ccccc1,aroma-supplement
+cinnamon,cinnamyl formate,O=COCC=Cc1ccccc1,aroma-supplement
+cinnamon,hydrocinnamaldehyde,O=CCCc1ccccc1,aroma-supplement
+cinnamon,cinnamyl butyrate,CCCC(=O)OCC=Cc1ccccc1,aroma-supplement
 spicy,eugenol,C=CCc1ccc(O)c(OC)c1,aroma-supplement
 spicy,cinnamaldehyde,O=CC=Cc1ccccc1,aroma-supplement
 spicy,zingerone,COc1cc(CCC(C)=O)ccc1O,aroma-supplement
@@ -50,6 +54,9 @@ banana,isoamyl acetate,CC(=O)OCCC(C)C,aroma-supplement
 banana,amyl acetate,CCCCCOC(C)=O,aroma-supplement
 banana,isoamyl butyrate,CCCC(=O)OCCC(C)C,aroma-supplement
 banana,isoamyl isovalerate,CC(C)CCOC(=O)CC(C)C,aroma-supplement
+banana,isoamyl propionate,CCC(=O)OCCC(C)C,aroma-supplement
+banana,isobutyl acetate,CC(=O)OCC(C)C,aroma-supplement
+banana,isoamyl formate,CC(C)CCOC=O,aroma-supplement
 nutty,"2,3-dimethylpyrazine",Cc1nccnc1C,aroma-supplement
 nutty,"2,5-dimethylpyrazine",Cc1cnc(C)cn1,aroma-supplement
 nutty,2-ethylpyrazine,CCc1cnccn1,aroma-supplement
@@ -71,6 +78,10 @@ smoky,"2,6-dimethoxyphenol",COc1cccc(OC)c1O,aroma-supplement
 smoky,4-methylguaiacol,COc1cc(C)ccc1O,aroma-supplement
 smoky,4-ethylguaiacol,CCc1ccc(O)c(OC)c1,aroma-supplement
 smoky,4-vinylguaiacol,C=Cc1ccc(O)c(OC)c1,aroma-supplement
+smoky,phenol,Oc1ccccc1,aroma-supplement
+smoky,p-cresol,Cc1ccc(O)cc1,aroma-supplement
+smoky,o-cresol,Cc1ccccc1O,aroma-supplement
+smoky,"2,6-dimethylphenol",Cc1cccc(C)c1O,aroma-supplement
 anise,anethole,CC=Cc1ccc(OC)cc1,aroma-supplement
 anise,estragole,C=CCc1ccc(OC)cc1,aroma-supplement
 anise,anisaldehyde,COc1ccc(C=O)cc1,aroma-supplement

training/build_aroma_supplement.py

@@ -36,17 +36,17 @@
                  "acetovanillone", "isovanillin", "veratraldehyde", "syringaldehyde"],
     "clove":    ["eugenol", "isoeugenol", "eugenyl acetate", "methyleugenol"],
     "cinnamon": ["cinnamaldehyde", "cinnamyl alcohol", "cinnamic acid", "methyl cinnamate",
-                 "ethyl cinnamate", "cinnamyl acetate"],
+                 "ethyl cinnamate", "cinnamyl acetate", "alpha-methylcinnamaldehyde", "cinnamyl formate", "hydrocinnamaldehyde", "cinnamyl butyrate"],
     "spicy":    ["eugenol", "cinnamaldehyde", "zingerone", "piperonal", "carvacrol"],
-    "banana":   ["isoamyl acetate", "amyl acetate", "isoamyl butyrate", "isoamyl isovalerate"],
+    "banana":   ["isoamyl acetate", "amyl acetate", "isoamyl butyrate", "isoamyl isovalerate", "isoamyl propionate", "isobutyl acetate", "isoamyl formate", "amyl butyrate"],
     "nutty":    ["2,3-dimethylpyrazine", "2,5-dimethylpyrazine", "2-ethylpyrazine",
                  "2-acetylpyrazine", "5-methylfurfural", "2-ethyl-3-methylpyrazine",
                  "2-acetylthiazole", "2,3-diethylpyrazine"],
     "cocoa":    ["2,3,5,6-tetramethylpyrazine", "2,3,5-trimethylpyrazine", "3-methylbutanal",
                  "2-methylbutanal", "isovaleraldehyde"],
     "coffee":   ["furfuryl mercaptan", "guaiacol", "2-acetylpyrazine", "5-methylfurfural"],
     "smoky":    ["guaiacol", "2,6-dimethoxyphenol", "4-methylguaiacol", "4-ethylguaiacol",
-                 "4-vinylguaiacol", "creosol"],
+                 "4-vinylguaiacol", "creosol", "phenol", "p-cresol", "o-cresol", "2,6-dimethylphenol"],
     "anise":    ["anethole", "estragole", "anisaldehyde", "p-anisaldehyde"],
     "balsamic": ["benzyl benzoate", "benzyl cinnamate", "benzoic acid", "benzyl salicylate", "cinnamyl cinnamate"],
     "herbal":   ["thymol", "carvacrol", "eucalyptol", "1,8-cineole", "menthone", "isomenthone"],