Drive Hull Desk from your own code

{
  "settings": {
    "chemical_system": "Li-O",
    "elements": ["Li", "O"],
    "entry_count": 6,
    "stable_entry_count": 4,
    "input_format": "table",
    "energies_entered_per_atom": false,
    "dataset_provenance": {"source": "illustrative toy numbers"},
    "methods": [],
    "pymatgen": "2026.5.4 / pymatgen-core 2026.7.16",
    "kT_298K_eV": 0.025693,
    "show_unstable_eV": 0.2
  },
  "elemental_references": [
    {"element": "Li", "entry_id": "li", "energy_eV_per_atom": -1.907},
    {"element": "O", "entry_id": "o2", "energy_eV_per_atom": -4.933}
  ],
  "entries": [
    {"entry_id": "li", "formula": "Li", "energy_eV_per_atom": -1.907,
     "formation_energy_eV_per_atom": 0, "energy_above_hull_eV_per_atom": 0, "on_hull": true},
    {"entry_id": "o2", "formula": "O2", "energy_eV_per_atom": -4.933,
     "formation_energy_eV_per_atom": 0, "energy_above_hull_eV_per_atom": 0, "on_hull": true},
    {"entry_id": "li2o", "formula": "Li2O", "energy_eV_per_atom": -4.771,
     "formation_energy_eV_per_atom": -1.855333333, "energy_above_hull_eV_per_atom": 0, "on_hull": true},
    {"entry_id": "li2o2", "formula": "Li2O2", "energy_eV_per_atom": -4.957,
     "formation_energy_eV_per_atom": -1.537, "energy_above_hull_eV_per_atom": 0, "on_hull": true},
    {"entry_id": "li2o_b", "formula": "Li2O", "energy_eV_per_atom": -4.75,
     "formation_energy_eV_per_atom": -1.834333333, "energy_above_hull_eV_per_atom": 0.021,
     "on_hull": false,
     "decomposes_to": [{"entry_id": "li2o", "formula": "Li2O", "fraction": 1}]},
    {"entry_id": "lio2", "formula": "LiO2", "energy_eV_per_atom": -4.5,
     "formation_energy_eV_per_atom": -0.5756666667, "energy_above_hull_eV_per_atom": 0.449,
     "on_hull": false,
     "decomposes_to": [
       {"entry_id": "li2o2", "formula": "Li2O2", "fraction": 0.666667},
       {"entry_id": "o2", "formula": "O2", "fraction": 0.333333}
     ]}
  ],
  "rows_total": 6,
  "composition_analyses": [
    {"query": "Li3O2", "reduced_formula": "Li3O2", "matching_entries": [],
     "decomposition": [
       {"entry_id": "li2o", "formula": "Li2O", "fraction": 0.6},
       {"entry_id": "li2o2", "formula": "Li2O2", "fraction": 0.4}
     ]}
  ],
  "metrics": [
    {"id": "M1", "metric": "stable_entries", "value": 4, "fraction": 0.6667,
     "basis": "entries on the computed convex hull (vertices), elemental references included, of 6 entries"},
    {"id": "M2", "metric": "lowest_formation_energy", "value": -1.855333333, "entry": "li2o",
     "formula": "Li2O", "basis": "eV/atom relative to the elemental references"},
    {"id": "M3", "metric": "near_hull_unstable", "value": 1, "entries": ["li2o_b"],
     "basis": "unstable entries within kT at 298.15 K (0.025693 eV/atom) of the hull"},
    {"id": "M4", "metric": "far_above_hull", "value": 1,
     "basis": "entries more than 0.2 eV/atom above the hull (the script's plotting cut-off)"},
    {"id": "M5", "metric": "polymorph_compositions", "value": 1, "formulas": ["Li2O"],
     "basis": "reduced formulas with more than one entry; only the lowest of each can be on the hull"}
  ],
  "flags": [
    {"id": "F1", "severity": "medium", "category": "method_not_stated",
     "message": "No calculation method is stated for the dataset or any entry, so nothing shows that the energies share one functional and correction scheme.",
     "refs": []},
    {"id": "F2", "severity": "low", "category": "near_hull",
     "message": "1 unstable entry is within kT at 298.15 K (25.7 meV/atom) of the hull. ...",
     "refs": ["li2o_b"]}
  ],
  "browser_verdict": "caveated",
  "expected": {
    "stable_entry_count": 4,
    "formation_energy__li2o": -1.855333333,
    "formation_energy__li2o2": -1.537,
    "e_above_hull__li2o_b": 0.021,
    "e_above_hull__lio2": 0.449
  },
  "expected_count": 5,
  "clipped": []
}

// make-body.js - build the exact body the page sends, with the page's own code.
// Save https://hull-desk.skillsafe.ai/hullkit.js, hull.js and chem.js next to this file, then:
//   node make-body.js entries.csv interpret "Li-O hull" "notes" "question" "Li3O2" > body.json
// entries.csv is "id, formula, energy_eV" rows (total energy of the formula as written),
// or the skill's strict entries JSON, or a JSON list of pymatgen ComputedEntry dicts.
const fs = require("fs");
const K = require("./hullkit.js");
const [file, lane = "interpret", title = "", context = "", question = "", queries = "", decision = ""] = process.argv.slice(2);
const set = { lane, title, context, question, queries, decision, basis: "total", data: fs.readFileSync(file, "utf8") };
const X = K.analyze(set);
if (X.empty) throw new Error(X.errors.join("; ") || "no entries");
const body = K.mustBeObject(K.buildInput(X, set));
fs.writeFileSync("entries.json", K.entriesJson(X));   // the dataset the script lane reads
console.error("browser verdict:", X.hint, "| stable:", X.stable.length, "of", X.entries.length, "| flags:", X.flags.map(f => f.id + " " + f.category).join(", "));
console.error("idempotency key: hull-desk:" + body.task + ":" + K.hashInput(body) + ":a1");
process.stdout.write(JSON.stringify(body));

# Or build the body in any language from a facts object you already hold, for example the
# "browser" key of the page's "Download .json" export. facts must go in as a STRING.
import json

export = json.load(open("toy-li-o-interpret.json"))   # the page's .json download
facts = export["browser"]
body = {
    "task": "interpret",
    "title": "Toy Li-O hull",
    "context": "Illustrative toy energies, not real DFT values. ...",
    "question": "Is Li2O2 on the computed hull, and what does Li3O2 decompose to?",
    "facts": json.dumps(facts, separators=(",", ":")),
}
json.dump(body, open("body.json", "w"))

{"ok": true, "data": {"job_id": "job_...", "status": "queued"}}
{"ok": false, "error": {"code": "payment_required", "message": "..."}}

# Every call is the same three things: the base URL, your bearer token,
# and a JSON body. Keep the token in a shell variable.
BASE="https://api.skillsafe.ai/v1/app-api"
SLUG="hull-desk"
TOKEN="$SKILLSAFE_TOKEN"   # from https://hull-desk.skillsafe.ai/tokens.html

call() {                  # call <path> [json-body]
  if [ -n "$2" ]; then
    curl -sS -X POST "$BASE/$1" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d "$2"
  else
    curl -sS "$BASE/$1" -H "Authorization: Bearer $TOKEN"
  fi
}

# The token page is the shortest path. It shows the token this browser holds and
# hands you a ready-made shell export:
#
#   https://hull-desk.skillsafe.ai/tokens.html
#   export SKILLSAFE_TOKEN="..."
#
# To mint a guest token from the command line instead. A guest token is enough
# for /me and /estimate; a run needs a personal token from signing in.
curl -sS -X POST "https://api.skillsafe.ai/v1/app-api/guest" \
  -H "Content-Type: application/json" -d '{"slug":"hull-desk"}'
# {"ok":true,"data":{"token":"…","subject_type":"guest"}}

call me
# {"ok":true,"data":{"subject_type":"user","username":"you","credits":51234}}

# body.json is the input object itself - no {"input": ...} wrapper. Build it with
# make-body.js above, or by hand. estimate does not validate it, so check the shape first:
python3 -c 'import json;b=json.load(open("body.json"));assert isinstance(b,dict) and b.get("task") in ("interpret","script") and all(isinstance(v,str) for v in b.values()) and all(b.get(k,"").strip() for k in ("facts",)) and isinstance(json.loads(b["facts"]),dict)'
INPUT=$(cat body.json)

call estimate "$INPUT"
# {"ok":true,"data":{"model":"...","model_alias":"gpt-terra",
#   "markup_bps":1000,"hold_credits":...,"min_credits":...,"sponsor_enabled":false,
#   "warnings":[]}}
#
# estimate creates no job and charges nothing. hold_credits is RESERVED, not the
# price; charged_credits after the run is the actual cost, usually far lower.

# Always send an Idempotency-Key derived from the input. A retried request with
# the same key returns the SAME job instead of billing a second run.
LANE=$(printf '%s' "$INPUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["task"])')   # interpret or script
KEY="hull-desk:$LANE:$(printf '%s' "$INPUT" | shasum -a 256 | cut -c1-16):a1"

JOB=$(curl -sS -X POST "$BASE/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d "$INPUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["job_id"])')

while :; do
  OUT=$(call "jobs/$JOB")
  STATUS=$(printf '%s' "$OUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["status"])')
  [ "$STATUS" = "succeeded" ] && break
  [ "$STATUS" = "failed" ] && echo "$OUT" && exit 1
  sleep 2
done

# {"ok":true,"data":{"job_id":"job_...","status":"succeeded",
#   "output":{"output":"{\"lane\":\"interpret\",\"verdict\":\"caveated\",\"headline\":\"...\", ...}"},
#   "charged_credits":...,"truncated":false}}
printf '%s' "$OUT" | python3 -c 'import sys,json;print(json.load(sys.stdin)["data"]["output"]["output"])' > reply.json

# Server-sent events. `delta` events carry chunks of the reply; `done` carries the
# status, charged_credits and the truncated flag. Ignore `tick` heartbeats.
curl -N -X POST "$BASE/run-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -H "Accept: text/event-stream" \
  -d "$INPUT"

# event: job    {"job_id":"job_..."}
# event: delta  {"text":"{\"lane\":\"interpret\",\"verdict\":\"caveated\",\"headline\":\"The"}
# event: done   {"status":"succeeded","charged_credits":...,"truncated":false}

# The reply is a JSON string inside data.output.output. Pull it out and parse it:
printf '%s' "$JOB" | python3 -c 'import sys,json;r=json.loads(json.load(sys.stdin)["output"]["output"]);print(r["verdict"],r["headline"])'

{
  "lane": "interpret" | "script",
  "verdict": "sound" | "caveated" | "unreliable",
  "headline": "one sentence",
  "tldr": ["2-5 bullets; one starts \"Answer:\" when a question was asked"],
  // interpret:
  "metrics": [{"id": "M1", "reading": "..."}],          // one per facts.metrics item, same order
  "phases": ["1-5 strings: compounds on the hull, how the closest unstable entries decompose, each asked composition"],
  "claims": [{"claim": "...", "support": "supported|partly|not_supported", "why": "..."}],
  "cautions": ["1-4 strings on what the hull cannot show"],
  // script:
  "fixes": [{"fix": "...", "why": "...", "refs": "F1"}],  // 1-6; refs "" for a plain step
  "script": "import json\nimport math\n...",              // one complete Python script, under 9000 characters
  "assumptions": ["1-4 strings"],
  "checks": ["1-4 strings"],
  // both:
  "next_steps": ["1-5 concrete actions"],
  "prescan_responses": [{"ref": "F1", "verdict": "confirmed|dismissed", "note": "..."}]
}

{
 "task": "interpret",
 "title": "Toy Li-O hull",
 "context": "Illustrative toy energies, not real DFT values. I want to say that Li2O and Li2O2 are the only computed-stable compounds and that LiO2 is far from the hull.",
 "question": "Is Li2O2 on the computed hull, and what does Li3O2 decompose to?",
 "facts": "{\"settings\":{\"chemical_system\":\"Li-O\",\"elements\":[\"Li\",\"O\"],\"entry_count\":6,\"stable_entry_count\":4,\"...\":\"more\"},\"elemental_references\":[...],\"entries\":[...],\"rows_total\":6,\"composition_analyses\":[{\"query\":\"Li3O2\",\"...\":\"...\"}],\"metrics\":[...],\"flags\":[{\"id\":\"F1\",\"severity\":\"medium\",\"category\":\"method_not_stated\",\"...\":\"...\"},{\"id\":\"F2\",\"severity\":\"low\",\"category\":\"near_hull\",\"...\":\"...\"}],\"browser_verdict\":\"caveated\",\"expected\":{\"stable_entry_count\":4,\"...\":\"4 more\"},\"expected_count\":5,\"clipped\":[]}"
}

{
  "lane": "interpret",
  "verdict": "caveated",
  "headline": "On this toy entry set Li2O and Li2O2 are the only compounds on the computed hull, but no method is stated for the energies.",
  "tldr": [
    "4 of 6 entries are on the computed hull: Li, O2, Li2O (li2o) and Li2O2 (li2o2).",
    "LiO2 (lio2) sits 0.449 eV/atom above the hull and decomposes to Li2O2 and O2.",
    "Answer: yes, Li2O2 is on the computed hull; Li3O2 decomposes to 0.6 Li2O + 0.4 Li2O2 in atom fractions."
  ],
  "metrics": [
    {"id": "M1", "reading": "4 of 6 entries (0.667) are vertices of the computed hull, the two elemental references included."},
    {"id": "M2", "reading": "Li2O (li2o) has the lowest formation energy, -1.86 eV/atom relative to the elemental references."},
    {"id": "M3", "reading": "One unstable entry, li2o_b, lies within kT at 298.15 K of the hull (21 meV/atom)."},
    {"id": "M4", "reading": "One entry, lio2, is more than 0.2 eV/atom above the hull."},
    {"id": "M5", "reading": "Li2O has two entries; only the lower one, li2o, can be on the hull."}
  ],
  "phases": [
    "The computed hull runs Li - Li2O - Li2O2 - O2.",
    "li2o_b is a higher-energy Li2O entry and decomposes entirely to li2o.",
    "Li3O2 has no entry of its own and decomposes to 0.6 Li2O + 0.4 Li2O2 (atom fractions)."
  ],
  "claims": [
    {"claim": "Li2O and Li2O2 are the only computed-stable compounds.", "support": "supported", "why": "They are the only compounds with on_hull true."},
    {"claim": "LiO2 is far from the hull.", "support": "supported", "why": "lio2 is 0.449 eV/atom above the hull, beyond the 0.2 eV/atom cut-off (M4)."}
  ],
  "cautions": [
    "The hull covers only these six entries; a missing competing phase could change it.",
    "It is a 0 K energy hull with no temperature, pressure or entropy terms."
  ],
  "next_steps": ["State the functional and correction scheme for every entry.", "..."],
  "prescan_responses": [
    {"ref": "F1", "verdict": "confirmed", "note": "Neither the facts nor the notes name a method."},
    {"ref": "F2", "verdict": "confirmed", "note": "li2o_b is 0.021 eV/atom above the hull, inside kT."}
  ]
}

{
 "task": "script",
 "title": "Toy Li-O hull",
 "context": "Illustrative toy energies, not real DFT values. I want to say that Li2O and Li2O2 are the only computed-stable compounds and that LiO2 is far from the hull.",
 "decision": "Verdict: caveated.\nOn this toy entry set Li2O and Li2O2 are the only compounds on the computed hull, ...\n- M1: 4 of 6 entries ...\n...\nNext steps:\n- ...",
 "facts": "{\"settings\":{\"chemical_system\":\"Li-O\",\"...\":\"more\"},\"...\":\"as in the interpret example\",\"browser_verdict\":\"caveated\",\"expected\":{\"stable_entry_count\":4,\"formation_energy__li2o\":-1.855333333,\"formation_energy__li2o2\":-1.537,\"e_above_hull__li2o_b\":0.021,\"e_above_hull__lio2\":0.449},\"expected_count\":5,\"clipped\":[]}"
}

{
  "lane": "script",
  "verdict": "caveated",
  "headline": "The script rebuilds the toy Li-O hull from entries.json, checks all 5 expected values, then drops li2o_b to show it does not move the hull.",
  "tldr": ["The reproduction check covers stable_entry_count, 2 formation energies and 2 energies above hull.", "..."],
  "fixes": [
    {"fix": "Rebuild the diagram without li2o_b and print how the other entries' energies above hull change.", "why": "It is within kT of the hull; removing it shows whether the stable set depends on it.", "refs": "F2"},
    {"fix": "Print get_equilibrium_reaction_energy for each stable compound.", "why": "Shows how deep each compound sits below its neighbours.", "refs": ""}
  ],
  "script": "import json\nimport math\nfrom pathlib import Path\n...",
  "assumptions": ["entries.json is the file the page wrote for this entry set.", "The energies share one method (F1: not stated)."],
  "checks": ["The reproduction prints no MISMATCH line.", "The stable set is unchanged after dropping li2o_b."],
  "next_steps": ["Save the page's entries.json next to hull_check.py and run python hull_check.py.", "..."],
  "prescan_responses": [
    {"ref": "F1", "verdict": "confirmed", "note": "No method is named; the script cannot check compatibility."},
    {"ref": "F2", "verdict": "confirmed", "note": "Answered by the first fix."}
  ]
}

# hull_check.py - reproduce the browser's hull from entries.json (abbreviated reply script)
import json
import math
from pathlib import Path

from pymatgen.analysis.phase_diagram import PhaseDiagram
from pymatgen.core import Composition
from pymatgen.entries.computed_entries import ComputedEntry

ENTRIES_PATH = "entries.json"

EXPECTED = {
    "stable_entry_count": 4,
    "formation_energy__li2o": -1.855333333,
    "formation_energy__li2o2": -1.537,
    "e_above_hull__li2o_b": 0.021,
    "e_above_hull__lio2": 0.449,
}


def load_entries(path):
    rows = json.loads(Path(path).read_text(encoding="utf-8"))["entries"]
    return [
        ComputedEntry(Composition(row["composition"], strict=True), float(row["energy_eV"]), entry_id=row["entry_id"])
        for row in rows
    ]


def main():
    path = Path(ENTRIES_PATH)
    if not path.is_file():
        raise SystemExit(f"{ENTRIES_PATH} not found: save it from the Hull Desk page first")
    entries = load_entries(path)
    diagram = PhaseDiagram(entries)
    by_id = {e.entry_id: e for e in entries}

    got = {"stable_entry_count": len(diagram.stable_entries)}
    for key in EXPECTED:
        if key.startswith("formation_energy__"):
            got[key] = diagram.get_form_energy_per_atom(by_id[key.split("__", 1)[1]])
        elif key.startswith("e_above_hull__"):
            got[key] = diagram.get_e_above_hull(by_id[key.split("__", 1)[1]])
    bad = [k for k, want in EXPECTED.items() if not math.isclose(got[k], want, rel_tol=1e-6, abs_tol=1e-6)]
    for k in bad:
        print(f"MISMATCH {k}: got {got[k]!r}, expected {EXPECTED[k]!r}")
    print("reproduction:", "OK" if not bad else f"{len(bad)} mismatch(es)")

    # Fix 1 (F2): rebuild without li2o_b.
    reduced = PhaseDiagram([e for e in entries if e.entry_id != "li2o_b"])
    print("stable without li2o_b:", sorted(e.entry_id for e in reduced.stable_entries))
    # Fix 2: equilibrium reaction energy of each stable compound.
    for e in diagram.stable_entries:
        if len(e.composition.elements) > 1:
            print(e.entry_id, diagram.get_equilibrium_reaction_energy(e))


if __name__ == "__main__":
    main()