clarification node: converse for out-of-scope molecules / unavailable tasks; per-task availability; no-derivative matching

app.py

@@ -72,7 +72,13 @@ for fp in glob.glob(os.path.join(_HERE, "precomputed", "*.json")):
             _PRECOMPUTED[(slug, task)] = json.load(f)
     except Exception:
         pass
+def _avail(task: str) -> list:
+    return sorted({slug.replace("_", " ") for (slug, t) in _PRECOMPUTED if t == task})
+
+
 SPECTRA_MOLECULES = sorted({slug.replace("_", " ") for (slug, _t) in _PRECOMPUTED})
+TASK_PHRASE = {"energy": "energy", "dipole": "dipole moment",
+               "ir": "IR spectrum", "thermo": "thermochemistry"}
 
 app = FastAPI(title="ChemGraph Loop")
 app.add_middleware(
@@ -127,21 +133,31 @@ def llm_parse_query(text: str) -> dict:
     mols = ", ".join(sorted(MOLECULES.keys()))
     user = (
         f"Allowed molecules (canonical names): {mols}.\n"
-        "Map the user's molecule to exactly one of these by ANY name — common name, "
-        "trivial/trade name, IUPAC name, or chemical formula. Examples: 'H2O' / "
-        "'dihydrogen monoxide' / 'aqua' -> water; 'CO2' / 'dry ice' -> carbon dioxide; "
+        "Map the user's molecule to one of these ONLY if it is the SAME compound, by any "
+        "name — common name, trivial/trade name, IUPAC name, or chemical formula. Examples: "
+        "'H2O' / 'dihydrogen monoxide' / 'aqua' -> water; 'CO2' / 'dry ice' -> carbon dioxide; "
         "'EtOH' / 'ethyl alcohol' / 'grain alcohol' -> ethanol; 'NH3' / 'azane' -> ammonia; "
-        "'benzol' -> benzene. If the molecule is NOT one of the allowed ones, use null "
-        "(do not force a match).\n"
+        "'benzol' -> benzene.\n"
+        "CRITICAL: a substituted or derivative molecule is a DIFFERENT compound — return "
+        "null, do NOT map it to the parent. e.g. dimethoxybenzene / toluene / nitrobenzene / "
+        "phenol / aniline are NOT benzene; acetaldehyde is NOT formaldehyde; propanol is NOT "
+        "ethanol. Never match just because the name contains an allowed molecule's name. If "
+        "the molecule is not EXACTLY one of the allowed ones, use null.\n"
         "Tasks: 'energy' = single-point energy; 'dipole' = dipole moment; 'ir' = "
         "vibrational frequencies / IR spectrum; 'thermo' = thermochemistry (enthalpy, "
         "entropy, Gibbs free energy). Pick the closest task; default to 'energy' if none "
         "is implied.\n"
         "Calculator: 'emt' only if the user explicitly asks for EMT and the task is "
         "energy; otherwise 'tblite'.\n"
+        "When molecule is null, also give: 'nearest' = the single closest allowed molecule "
+        "if the user's is a close relative/derivative (e.g. dimethoxybenzene -> benzene, "
+        "1-propanol -> ethanol, acetone -> null if nothing close), else null; and 'note' = "
+        "ONE short, friendly sentence naming the user's molecule and why it's outside this "
+        "small-molecule demo (e.g. \"Caffeine is too large for this small-molecule demo.\").\n"
         f'User question: "{text}"\n'
         'Reply as JSON: {"molecule": <canonical name or null>, "task": '
-        '"energy|dipole|ir|thermo", "calculator": "emt|tblite"}'
+        '"energy|dipole|ir|thermo", "calculator": "emt|tblite", '
+        '"nearest": <allowed name or null>, "note": <string or null>}'
     )
     resp = _openai().chat.completions.create(
         model=INTENT_MODEL,
@@ -156,7 +172,12 @@ def llm_parse_query(text: str) -> dict:
     task = data.get("task") or "energy"
     task = task.strip().lower() if isinstance(task, str) else "energy"
     if mol not in MOLECULES:
-        return {"error": "no_molecule"}
+        nearest = data.get("nearest")
+        nearest = nearest.strip().lower() if isinstance(nearest, str) else None
+        return {"error": "no_molecule",
+                "note": data.get("note") if isinstance(data.get("note"), str) else None,
+                "nearest": nearest if nearest in MOLECULES else None,
+                "task": task if task in TASKS else "energy"}
     if task not in TASKS:
         task = "energy"
     # calculator isn't "intent": TBLite (real QM) by default; EMT only for an
@@ -212,7 +233,8 @@ def health():
         "molecules": sorted(MOLECULES.keys()),
         "tasks": ["energy", "dipole", "ir", "thermo"],
         "live_tasks": sorted(LIVE_TASKS),
-        "spectra_molecules": SPECTRA_MOLECULES,
+        "ir_molecules": _avail("ir"),
+        "thermo_molecules": _avail("thermo"),
     }
 
 
@@ -244,10 +266,25 @@ async def run(req: Request):
             parsed = {"error": "no_molecule"}
         user_text = None
 
+    # ---- CLARIFICATION NODE: molecule not in the demo's small-molecule set ----
     if parsed.get("error") == "no_molecule":
-        return JSONResponse(
-            {"error": "I couldn't spot a supported molecule in that. Try one of the listed molecules.",
-             "molecules": sorted(MOLECULES.keys())}, status_code=400)
+        note = parsed.get("note") or "That doesn't look like one of the small molecules in this demo."
+        nearest = parsed.get("nearest")
+        want = parsed.get("task", "energy")
+        suggestions = []
+        if nearest:
+            note += f" Did you mean {nearest}?"
+            if want in CACHED_TASKS and nearest in _avail(want):
+                suggestions.append({"label": f"{TASK_PHRASE[want]} of {nearest}",
+                                    "query": f"{TASK_PHRASE[want]} of {nearest}"})
+            suggestions += [{"label": f"energy of {nearest}", "query": f"energy of {nearest}"},
+                            {"label": f"dipole of {nearest}", "query": f"dipole of {nearest}"}]
+        else:
+            suggestions = [{"label": "IR spectrum of water", "query": "IR spectrum of water"},
+                           {"label": "dipole of ammonia", "query": "dipole of ammonia"},
+                           {"label": "energy of benzene", "query": "energy of benzene"}]
+        return JSONResponse({"clarify": True, "message": note,
+                             "molecules": sorted(MOLECULES.keys()), "suggestions": suggestions})
 
     molecule, task, calc = parsed["molecule"], parsed["task"], parsed["calculator"]
     calc_label = CALC_LABEL[calc]
@@ -259,11 +296,19 @@ async def run(req: Request):
         slug = molecule.replace(" ", "_")
         payload = _PRECOMPUTED.get((slug, task))
         if payload is None:
-            return JSONResponse(
-                {"error": f"Spectra / thermochemistry are precomputed for: {', '.join(SPECTRA_MOLECULES)}. "
-                          f"For {molecule}, ask for its energy or dipole (those run live).",
-                 "spectra_molecules": SPECTRA_MOLECULES, "molecule": molecule, "task": task},
-                status_code=422)
+            # CLARIFICATION NODE: molecule is supported, but this heavy task wasn't
+            # precomputed for it — offer its live options + where the task IS available.
+            avail = _avail(task)
+            msg = (f"I don't have a precomputed {TASK_PHRASE[task]} for {molecule} — those need a "
+                   f"slow vibrational (Hessian) run, so they're prepared ahead of time"
+                   + (f" for {', '.join(avail)}" if avail else "") + ". "
+                   f"But I can run {molecule}'s energy or dipole live right now.")
+            suggestions = [{"label": f"energy of {molecule}", "query": f"energy of {molecule}"},
+                           {"label": f"dipole of {molecule}", "query": f"dipole of {molecule}"}]
+            if avail:
+                suggestions.append({"label": f"{TASK_PHRASE[task]} of {avail[0]}",
+                                    "query": f"{TASK_PHRASE[task]} of {avail[0]}"})
+            return JSONResponse({"clarify": True, "message": msg, "suggestions": suggestions})
         out = dict(payload)
         out["display_query"] = display_query
         return JSONResponse(out)