Resolve names from master_enrichment, the one base table (#276)

* refactor(data): resolve names from master_enrichment, the one base table (#224)

app.py built its own name lookup from properties.parquet and then merged iupac_backfill.parquet
itself. build_enrichment.py had already done that work — and better — so the two diverged in three
ways, all silent:

  1. The enrichment build resolves a name curated-list-first, then PubChem common name, then IUPAC
     name, then a molecular-formula fallback, un-inverting CAS-style ordering along the way. None
     of that reached app.py's table.
  2. The merge read only `iupac_name` from the backfill and ignored the `common_name` column, so
     every PubChem Title the crawler recovered was thrown away on arrival.
  3. Nothing carried the formula fallback, so the molecules that only have one resolved to nothing.

Measured before the change: 754 molecules had a name in master_enrichment that app._NAME_TABLE did
not know — and not obscure ones. cedrol, fenchyl alcohol, hydroxycitronellal and musk ketone all
rendered by name in the grid and came back empty from the UI's own lookup. After: 0.

Sourcing the resolved name straight off the base table makes the grid and the lookup agree by
construction instead of by coincidence, and deletes a whole merge function rather than adding one.
That is what #224 is actually asking for, applied where the duplication genuinely was.

Note what is deliberately NOT folded in. profile_index.npz is an 8,850 x 183 matrix — that 183 is
the FLAVOUR-PROFILE vector (6 taste + 172 aroma + 5 mouthfeel), not the head count, which is 195.
The 12 Tox21 heads are excluded on purpose: safety is not a flavour-match dimension and must never
steer "what tastes similar". flavor_map.parquet is a UMAP embedding. Different shapes serving
different questions; forcing either into a row-oriented molecule table would be worse, not tidier.
odor_notes/taste_notes are documented-text SOURCES the enrichment build consumes — upstream of the
base table, not competitors to it.

Signed-off-by: Austin L. <86896075+rvnminers-A-and-N@users.noreply.github.com>

* docs: sweep every head and profile-dimension number to the live roster

Prompted by a fair question — "don't we have more heads now?" — which turned out to be pointing at
a genuinely ambiguous line. Two different numbers had been drifting:

  195  trained heads       6 taste + 172 aroma + 5 mouthfeel + 12 safety
  183  profile dimensions  6 taste + 172 aroma + 5 mouthfeel  (tox EXCLUDED, deliberately)

Tox is kept out of the flavour-profile vector on purpose: safety is not a flavour-match dimension,
and if it were in there two molecules could rank as "similar tasting" partly because they share a
liver-toxicity signature. That is wrong in a formulation tool and dangerous in a food one.

The stale numbers were spread across the schema, six docs and three source files — 175/177/178-dim
profiles and 166/167-head rosters, each correct at some point in the last two days. The pgvector
column was the worst of them: vector(177) would have rejected every insert of a 183-dim profile at
runtime, and nothing would have caught it until the first real docker compose up.

Also corrects a comment in predict.py that was not merely stale but actively wrong. It claimed the
model load "is fanned out across cores (joblib.load releases the GIL)". Both halves are false —
unpickling is GIL-bound, which is why threads measured ~2.5x SLOWER, and the process pool that IS
faster deadlocks because loading runs during module import. Anyone optimising from that comment
would have re-walked the exact path #225 documents as a dead end.

Signed-off-by: Austin L. <86896075+rvnminers-A-and-N@users.noreply.github.com>

---------

Signed-off-by: Austin L. <86896075+rvnminers-A-and-N@users.noreply.github.com>

Author: rvnminers-A-and-N

CHANGELOG.md

@@ -31,7 +31,7 @@ exists to install it somewhere other than the machine it was built on.
 - Numbers glossary in `HOW-IT-WORKS.md` and in the app's own How-it-works panel.
 
 ### Changed
-- Aroma roster **164 → 166 heads**; confident-capable heads **94 → 108**.
+- Aroma roster **164 → 172 heads**; confident-capable heads **94 → 108**.
 - Chip families (flavor / note / taste / mouthfeel) share one visual language instead of four
   accidental ones, and each studio section explains what its dimension *is*.
 - Every molecule has a display name: names fall back to molecular formula, with multi-component

docs/ACCURACY.md

@@ -128,7 +128,7 @@ because of it, and the reasoning is recorded in `train_aroma._calibrate` so nobo
 half the time when they fire.
 
 They are **not deleted, disabled, or hidden.** They keep their score, their column in the
-178-dimension flavor profile, their chips in search, their colour on the map, and every molecule
+183-dimension flavor profile, their chips in search, their colour on the map, and every molecule
 they find. What changes is one word: they are reported as **indicative** rather than *confident*,
 and the UI hatches their bar so you can see it at a glance.
 

docs/AROMA-AUDIT.md

@@ -2,7 +2,7 @@
 
 > **Update — supplement applied, then made food-only.** `build_aroma_supplement.py` adds a curated
 > **public-domain** character-impact set (`aroma_supplement.csv`, resolved via PubChem) for the sparse
-> descriptors below. Result: **42 → 167 heads** (food-safe core + non-food aroma-only tier; see the
+> descriptors below. Result: **42 → 172 heads** (food-safe core + non-food aroma-only tier; see the
 > multi-industry note below), after open-government sourcing (see below) took the
 > curated supplement to **~1,994 labelled molecules**. New heads include `coconut`, `nutty`, `caramel`,
 > `winey`, `onion`, `honey`, `herbal`, `vanilla`, `buttery`, `balsamic`, `smoky`, `cinnamon`, `spicy`,
@@ -28,10 +28,10 @@
 > 2-phenylethanol) instead of the E/Z terpene twins (nerol/geraniol) that dedupe to one row under the
 > connectivity-skeleton key. That was the **food-safe** ceiling at ~86.
 >
-> **Then we walked the road past it — the non-food aroma-only descriptor space — to 167 heads.** The
+> **Then we walked the road past it — the non-food aroma-only descriptor space — to 172 heads.** The
 > corpus is now deliberately **multi-industry**, not food-only: odor is physical, so to read
 > structure→smell well the corpus should include the fragrance space, and a per-molecule **safety flag**
-> (open-gov food registers) — not corpus membership — gates edibility per mode. The same 167 heads serve
+> (open-gov food registers) — not corpus membership — gates edibility per mode. The same 172 heads serve
 > every "Mancer" mode: **Flavormancer** (food chemistry), **Beveragemancer** (beverage), **Aromamancer**
 > (fragrance), **Vapemancer** (inhalation), **Oilmancer** (essential oils). Molecule names are resolved
 > to structures through PubChem and folded in flagged non-food. New heads cleared across several

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 → **2403** molecules, incl. a curated public-domain supplement), and adding those features, **167 heads clear CV-AUROC ≥ 0.70**
+  in (825 → **2403** molecules, incl. a curated public-domain supplement), and adding those features, **172 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

@@ -6,7 +6,7 @@ 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 167 presence/absence odor-descriptor
+> commercial-clean data). **Aroma ships here** as 172 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**
@@ -33,7 +33,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** — **167 odor-descriptor heads ship** (**trained**)
+**Aroma** — **172 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/DATA-PIPELINE.md

@@ -45,8 +45,8 @@ local compute.
 **Verify it worked** (this is the honest end-to-end check, not just "the server started"):
 
 ```bash
-curl -s localhost:8000/api/status                      # {"ready":true,"total":190,...}  (190 artifacts = 189 heads + the intensity regressor)
-curl -s localhost:8000/api/heads | jq '.aroma | length' # 166
+curl -s localhost:8000/api/status                      # {"ready":true,"total":190,...}  (190 artifacts = 195 heads + the intensity regressor)
+curl -s localhost:8000/api/heads | jq '.aroma | length' # 172
 # vanillin — the vanilla head should fire at 1.0, confident, with its calibrated threshold
 curl -s -X POST localhost:8000/api/predict \
   -H 'Content-Type: application/json' \

docs/HOW-IT-WORKS.md

@@ -98,7 +98,7 @@ features (trained on SweetenersDB).
 
 ---
 
-## 3. Aroma — 167 descriptor heads from public odor text
+## 3. Aroma — 172 descriptor heads from public odor text
 
 Odor is the hard, licensed part of this field — most rich odor datasets are NonCommercial. Our
 clean route:
@@ -111,7 +111,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. **167 heads** survive
+   **keeps only the heads that clear CV-AUROC ≥ 0.70** — an honest bar. **172 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

docs/METHODS.md

@@ -136,8 +136,8 @@ the thin heads — a genuine pine match could land at 0.42 and never be shown.
   recall climbs faster than precision falls. **A high AUROC does not protect you** — AUROC is
   computed on ranking and is insensitive to class imbalance; precision is not. `coffee` has
   AUROC 0.960 and out-of-fold precision **0.46**; both are true of the same head.
-- **Heads that cannot clear the floor are `indicative`, not deleted.** 73 of 167 aroma heads never
-  reach 50% precision at any threshold. They keep their score, their place in the 178-dim profile,
+- **Heads that cannot clear the floor are `indicative`, not deleted.** 65 of 172 aroma heads never
+  reach 50% precision at any threshold. They keep their score, their place in the 183-dim profile,
   their chips and their map colour — firing well above base rate is real evidence. They are simply
   never presented as a *confident* call: the UI marks them, and the read returns `indicative: true`
   plus the head's measured precision. Hiding them would delete reach to paper over a labelling

docs/MOUTHFEEL.md

@@ -10,7 +10,7 @@ without *feeling* cool, and WS-23 cools the mouth with almost no odour at all.
 
 **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.
+`mouthfeel` by `predict.py` and folded into the 183-dim flavor-profile vector used for substitutes.
 
 | head | what it is | held-out CV-AUROC |
 |---|---|---|

docs/TOX.md

@@ -16,7 +16,7 @@ assay** heads that act as a *defensive screen*.
 |---|---|---|
 | label source | **documented + curated** sensory facts (a molecule is *known to be perceived* as X) | **experimental wet-lab screening** (a molecule *measurably was* active in an assay) |
 | what a positive means | people report this percept | this well lit up in a dish |
-| in the substitute-match vector? | **yes** (175 dims) | **no** — deliberately |
+| in the substitute-match vector? | **yes** (183 dims) | **no** — deliberately |
 | framing | prediction | **caution-only review flag** |
 
 Tox is excluded from the flavor-profile vector on purpose: you do not want reformulation