feat: Tox21 caution-only tox-assay heads (public domain) + value rationale (#60)

The one "could-add" item that's commercial-clean: Tox21 (NIH/NCATS · EPA · FDA · NTP)
toxicity-assay data is public domain. Adds:
- train_tox.py: 12 RandomForest heads (genotoxic-stress SR-p53/SR-ATAD5, AhR,
  mitochondrial, endocrine) on Morgan fingerprints — CV-AUROC 0.72–0.90.
- predict.py predict_tox(): INDICATIVE, caution-only flags wired into safety.tox_screen
  ("active in an in-vitro assay → review", NEVER a determination). Honest available:False
  until trained; tested (ethanol benign, estragole/safrole show modest receptor activity).
- workbench: tox-assay caution chips in the Behavior & safety card.
- tests + CAPABILITIES + SOURCES updated.

README "Why it's built this way": neutral product rationale (prediction-not-lookup;
on-prem privacy; one integrated read; sharpens on your own data) — no prospect names,
not a directed pitch.

BitterDB (CC-BY-NC) and Kovats RI (no clean open set / paid NIST) stay out of the
commercial edition, as documented.

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

Author: rvnminers-A-and-N

README.md

@@ -67,6 +67,23 @@ rule), **estimate** (published QSPR with known error), **lookup** (from a loaded
 reference table), and **qualitative** (a class/flag, not a number). Full map in
 [docs/CAPABILITIES.md](docs/CAPABILITIES.md).
 
+## Why it's built this way
+
+The value isn't any single number — those you can look up. It's four design choices:
+
+- **Prediction, not lookup.** The trained models read a molecule from its *structure*,
+  so they answer for a **novel or unmeasured** compound that's in no database — not just
+  for known ones.
+- **On-premise, behind your firewall.** Proprietary candidate structures **never leave
+  your network**. You can screen confidential molecules without exposing your direction
+  to any external service — something no public web tool can offer.
+- **One integrated read.** Taste, behaviour, safety, and substitution in a single
+  confidence-tagged screen, instead of stitching together half a dozen databases and
+  manual checks per molecule.
+- **It sharpens on your own data.** The open-data models are the floor. Trained on a
+  user's *own* formulation and sensory data — on the same on-prem box — they become
+  specific to that user's products, which no public dataset can be.
+
 ## Two editions
 
 Flavormancer ships as two editions of one method:

docs/CAPABILITIES.md

@@ -54,7 +54,10 @@ by how it's derived, and nothing claims more certainty than its source supports.
 **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 (**lookup**, data-gated).
+- 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**.
 - Preliminary TTC concern tier (**qualitative** heuristic; Toxtree for the real call).
 - EU declarable fragrance-allergen labeling flag — `labeling()` (**lookup**, curated subset).
 

docs/SOURCES.md

@@ -64,7 +64,9 @@ record of provenance, not legal advice. Get an IP/OSS-license review before ship
   ~$2,850 single-seat) — *not used* (paywall); RI deferred to customer/licensed data. (RI
   is **not** in PubChem — verified by probe.)
 - **Tox21** (NIH/NCATS · EPA · FDA · NTP) — public toxicity-assay data (public domain, on
-  PubChem / data.gov). A **clean candidate** for caution-only tox flags; **not yet built**.
+  PubChem / data.gov; MoleculeNet mirror of the Tox21 Challenge set). **In use** — 12
+  caution-only RandomForest tox-assay heads (`train_tox.py` → `predict_tox()`),
+  CV-AUROC 0.72–0.90. INDICATIVE in-vitro flags, never a determination.
 
 ---
 

tests/test_predict.py

@@ -22,3 +22,10 @@ def test_predict_aroma_is_honest_placeholder():
     out = predict.predict_aroma("CCO")
     assert out["available"] is False
     assert "AROMA.md" in out["note"]
+
+
+def test_predict_includes_tox_screen():
+    # tox_screen is always present and well-formed (honest available:False with no models, as in CI)
+    out = predict.predict("CCO")
+    assert "tox_screen" in out["safety"]
+    assert isinstance(out["safety"]["tox_screen"]["available"], bool)

training/predict.py

@@ -185,6 +185,14 @@ def _ik1(*smiles):
         else:
             _CLASSIFIERS[name] = joblib.load(p)
 
+# Caution-only toxicity-assay heads (Tox21, public domain). Loaded if trained.
+# INDICATIVE in-vitro signals — never a toxicity determination.
+_TOX = {}
+_TOX_DIR = Path("tox_models")
+if _TOX_DIR.exists():
+    for p in _TOX_DIR.glob("*_rf.joblib"):
+        _TOX[p.stem.replace("_rf", "")] = joblib.load(p)
+
 # Known-label lookup: ground truth for molecules we actually have data on. This
 # is how the salty/sour data works as a FLAG without a model — if a queried
 # molecule is in our labeled set, we report the verified fact instead of a guess.
@@ -598,6 +606,37 @@ def predict_aroma(smiles, top_k=8):
             "note": "aroma deferred — needs licensed/customer odor data; see docs/AROMA.md"}
 
 
+# Plain-language meaning of each Tox21 assay, for caution context.
+_TOX_MEANING = {
+    "NR-AhR": "aryl-hydrocarbon receptor (xenobiotic / dioxin-like activity)",
+    "NR-AR": "androgen receptor", "NR-AR-LBD": "androgen receptor (LBD)",
+    "NR-Aromatase": "aromatase (estrogen synthesis)",
+    "NR-ER": "estrogen receptor", "NR-ER-LBD": "estrogen receptor (LBD)",
+    "NR-PPAR-gamma": "PPAR-γ (metabolic)",
+    "SR-ARE": "oxidative-stress response (ARE)",
+    "SR-ATAD5": "ATAD5 — genotoxicity / DNA damage",
+    "SR-HSE": "heat-shock response", "SR-MMP": "mitochondrial toxicity",
+    "SR-p53": "p53 — DNA-damage response (genotoxic stress)",
+}
+
+
+def predict_tox(mol, threshold=0.5):
+    """Caution-only in-vitro tox-assay activity (Tox21 models). INDICATIVE flags for
+    review — NEVER a toxicity/safety determination. Honest/empty if heads untrained."""
+    if not _TOX:
+        return {"available": False,
+                "note": "tox heads not trained — run train_tox.py (Tox21, public domain)"}
+    x = _fp(mol)
+    assays = []
+    for name, clf in sorted(_TOX.items()):
+        p = round(float(clf.predict_proba(x)[0, 1]), 3)
+        assays.append({"assay": name, "meaning": _TOX_MEANING.get(name, name), "probability": p})
+    flags = [a["assay"] for a in assays if a["probability"] >= threshold]
+    return {"available": True, "assays": assays, "flags": flags,
+            "note": "INDICATIVE in-vitro tox-assay activity (Tox21 RandomForest heads) — "
+                    "caution-only, NOT a toxicity/safety determination; confirm with a toxicologist."}
+
+
 def _taste_profile(out):
     """Trained taste heads ranked by probability (descending) — the 'order of
     dominance' view. Sour is a small-data indicative head; the deterministic
@@ -707,6 +746,7 @@ def predict(smiles: str, include_aroma: bool = False) -> dict:
     out["labeling"] = labeling(mol)
     out["safety"] = _safety(mol)
     out["safety"]["ttc_hint"] = ttc_hint(mol)
+    out["safety"]["tox_screen"] = predict_tox(mol)
     if include_aroma:
         out["aroma"] = predict_aroma(smiles)
     return out

training/train_tox.py

@@ -0,0 +1,66 @@
+"""
+train_tox.py — caution-only toxicity-assay heads from Tox21 (public domain).
+
+Tox21 (NIH/NCATS · EPA · FDA · NTP) screened ~8k compounds against 12 in-vitro assays
+(nuclear-receptor + stress-response, incl. genotoxic-stress SR-p53 / SR-ATAD5 and AhR).
+This trains one RandomForest per assay on Morgan fingerprints — **INDICATIVE, caution-only**
+flags ("active in an in-vitro tox assay → review"), **NEVER a toxicity determination**.
+Reports honest 5-fold CV AUROC; saves to tox_models/.
+
+Data: tox21.csv — the MoleculeNet mirror of the NCATS public-domain Tox21 Challenge set.
+"""
+from pathlib import Path
+
+import joblib
+import numpy as np
+import pandas as pd
+from rdkit import Chem
+from rdkit.Chem import DataStructs, rdFingerprintGenerator
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.model_selection import cross_val_score
+
+FP_BITS, FP_RADIUS = 2048, 2
+_MORGAN = rdFingerprintGenerator.GetMorganGenerator(radius=FP_RADIUS, fpSize=FP_BITS)
+TASKS = ["NR-AR", "NR-AR-LBD", "NR-AhR", "NR-Aromatase", "NR-ER", "NR-ER-LBD",
+         "NR-PPAR-gamma", "SR-ARE", "SR-ATAD5", "SR-HSE", "SR-MMP", "SR-p53"]
+OUT = Path("tox_models")
+OUT.mkdir(exist_ok=True)
+for s in OUT.glob("*_rf.joblib"):
+    s.unlink()
+
+
+def fp(smiles):
+    m = Chem.MolFromSmiles(smiles)
+    if m is None:
+        return None
+    bv = _MORGAN.GetFingerprint(m)
+    arr = np.zeros((FP_BITS,), dtype=np.int8)
+    DataStructs.ConvertToNumpyArray(bv, arr)
+    return arr
+
+
+df = pd.read_csv("tox21.csv")
+feats, idx = [], []
+for i, s in enumerate(df["smiles"]):
+    f = fp(s)
+    if f is not None:
+        feats.append(f)
+        idx.append(i)
+X = np.array(feats)
+df = df.iloc[idx].reset_index(drop=True)
+
+print(f"training caution-only tox heads on {len(df)} molecules:")
+kept = 0
+for t in TASKS:
+    y = df[t].values
+    mask = ~np.isnan(y)
+    Xd, yd = X[mask], y[mask].astype(int)
+    if yd.sum() < 30:
+        print(f"  {t:14s} too few positives — skip")
+        continue
+    clf_args = dict(n_estimators=200, n_jobs=-1, random_state=42, class_weight="balanced")
+    auc = cross_val_score(RandomForestClassifier(**clf_args), Xd, yd, cv=5, scoring="roc_auc").mean()
+    joblib.dump(RandomForestClassifier(**clf_args).fit(Xd, yd), OUT / f"{t}_rf.joblib")
+    kept += 1
+    print(f"  {t:14s} n={int(mask.sum()):5d} pos={int(yd.sum()):4d}  CV-AUROC={auc:.3f}")
+print(f"\nkept {kept}/{len(TASKS)} tox heads -> tox_models/  (caution-only, Tox21 public domain)")

training/workbench.html

@@ -221,6 +221,8 @@ <h2>Aroma</h2>
   let html = '<div class="kv">'+rows.map(r=>`<div class="k">${r[0]}</div><div class="v">${r[1]}</div>`).join('')+'</div>';
   const alerts = sf.structural_alerts||[];
   if(alerts.length) html += '<div class="chips">'+alerts.map(a=>`<span class="chip" style="background:#FBEDE9;color:#8A3A22;border-color:#E7C4B8">⚠ ${a}</span>`).join('')+'</div>';
+  const tox = sf.tox_screen||{};
+  if(tox.available && (tox.flags||[]).length) html += '<div class="chips">'+tox.flags.map(f=>`<span class="chip" style="background:#FBEDE9;color:#8A3A22;border-color:#E7C4B8">⚠ tox-assay: ${f}</span>`).join('')+'</div>';
   html += '<div class="empty" style="font-size:12px">Defensive screen — flags for review, never a clearance.</div>';
   $('behavior').innerHTML = html;
 }