README.md

---
title: ChemGraph Loop
emoji: 🧪
colorFrom: green
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
short_description: Real agentic chemistry workflow — resolve, simulate, verify
---

# ChemGraph Loop

A guarded, **natural-language API around the real ChemGraph agent** — Argonne
Leadership Computing Facility's agentic computational-chemistry framework
(LangGraph + ASE), running the workflow-correctness hardening by **Lu Zhang**.

Backs the live demo at **sciencesloop.com/agent** (frontend =
`lu-zhang-site/src/components/ChemGraphDemo.astro`).

- **GitHub (source):** `github.com/rockyzl/chemgraph-loop` (private)
- **Deploy target:** HF Space `rockyaaos/chemgraph-loop` (Docker, free CPU-basic)
- **Upstream ChemGraph:** https://github.com/argonne-lcf/ChemGraph (Apache-2.0)

## How it works (request lifecycle)

1. **LLM intent router** (`llm_parse_query`, PRIMARY) — one `gpt-4o-mini` JSON
   call reads the plain-language question and returns `{molecule, task,
   calculator}`, resolving the molecule by ANY name/synonym/formula
   ("dihydrogen monoxide"/"H2O"/"NH3"/"CO2"/"EtOH"/"benzol" → canonical). It
   refuses to match derivatives to a parent (dimethoxybenzene ≠ benzene) and
   emits `nearest`/`note` for out-of-scope molecules. `keyword_fallback`
   (token match, no regex) runs ONLY if the model call fails. This is
   intentionally agentic, not a rule engine.
2. **Route by physics cost:**
   - `energy` / `dipole` = single-point (~12–25 s) → run the **real ChemGraph
     agent LIVE** on a canonical, guard-matched query built from the intent.
   - `ir` / `thermo` = finite-difference Hessian (too slow for free CPU) →
     served from **precomputed real agent runs** in `precomputed/`
     (`cached:true`, shown as "precomputed real run").
3. **Extract** (`cg_extract.extract`) → unified rich payload: molecule/formula/
   smiles, `structure.atoms` (parsed from molecule.xyz, drives the 3D viewer),
   `steps[]` (tool calls + folded detail), task-specific `result`
   (energy / dipole vector+magnitude / ir.modes / thermo H,S,G), `verified`.
4. **Clarification node** — out-of-scope molecule or an unavailable heavy task
   returns `{clarify:true, message, suggestions:[{label,query}]}` (HTTP 200),
   NOT an error. The frontend renders it as a conversational bubble + chips.

## Endpoints

```
GET  /            → health: molecules, tasks, live_tasks, ir_molecules, thermo_molecules
POST /run  { "query": "IR spectrum of water" }          # natural-language (primary)
POST /run  { "molecule": "water", "calculator": "emt" }  # legacy, energy only
```

`/run` returns one of: a rich result payload · a `clarify` payload · an error
(`429` rate limit · `504` timeout · `500` agent error).

## Coverage & reliability (IMPORTANT)

- **energy / dipole:** LIVE for all 10 allow-listed molecules (water, methane,
  ammonia, methanol, ethanol, carbon dioxide, benzene, acetic acid,
  formaldehyde, hydrogen peroxide).
- **thermochemistry:** precomputed for **all 10** (thermo uses plain
  `Vibrations`; works for large molecules).
- **IR / vibrations:** precomputed for **≤4-atom molecules only** — water,
  ammonia, carbon dioxide, formaldehyde, hydrogen peroxide. The ASE `Infrared`
  intensity step returns **empty modes for ≥5-atom molecules** (methane,
  methanol, ethanol, acetic acid, benzene all fail — confirmed). Do NOT add
  ≥5-atom IR; the clarification node covers them.
- Guard-matched queries only (single-point / dipole / ir / thermo). "geometry
  optimization" phrasing makes the agent loop — never expose it.
- Display-layer IR filter: keep modes with `cm1 ≥ 100` & `intensity > 1e-3`
  (drops spurious near-zero / translation-rotation modes).

## Files

| File | Role |
|---|---|
| `app.py` | FastAPI: intent router, routing, clarification node, guards (CORS, rate limit, timeout) |
| `cg_extract.py` | shared payload extractor (structure/steps/results) — used by app + precompute |
| `precompute.py` | offline heavy-task generator: `python precompute.py <molecule...>` |
| `precomputed/<slug>__<task>.json` | bundled real agent runs for ir/thermo |
| `Dockerfile` | CPU torch → `pip install .[calculators]` → copies wrappers LAST (fast layer-cached rebuilds) |
| `src/` | vendored copy of Lu's hardened ChemGraph fork |

## Deploy / operate

The HF Space builds from its own git; push files with `huggingface_hub`
(`~/.local` env at `/tmp/hfenv/bin/python` on Lu's box) — `upload_file` /
`upload_folder` / `delete_file` each trigger a rebuild (~2–4 min, layer-cached
since wrappers copy late). `OPENAI_API_KEY` is a Space **secret**.

```python
from huggingface_hub import HfApi
HfApi().upload_file(path_or_fileobj="app.py", path_in_repo="app.py",
                    repo_id="rockyaaos/chemgraph-loop", repo_type="space",
                    commit_message="...")
```

**Add a spectrum/thermo molecule:** run `precompute.py <name>`, validate the IR
modes are non-empty & physical (`cm1≥100`), `upload_file` the JSON, let the Space
rebuild (its `_avail(task)` picks it up automatically). Only ≤4-atom molecules
get valid IR.

CORS allows `sciencesloop.com`, `*.vercel.app`, and `localhost:4321`.