Drive Blame the Thing from your own code

{ "ok": true,  "data":  { ... } }
{ "ok": false, "error": { "code": "...", "message": "..." } }

{"task": "diagnose", "headline": "...", "rows": [{"id": "discover", "ok": false, "note": "..."}, {"id": "mapping", "ok": true, "note": "..."}, ...], "score": 4, "verdict": "the-thing", "culprit": "discover", "error_type": "mistake", "error_why": "...", "label": "PUSH", "label_where": "...", "for_you": "...", "for_maker": "..."}

{
 "task": "diagnose",
 "thing": "the glass door into the office",
 "goal": "Get through the door into the office in the morning",
 "happened": "It has the same big bar handle on both sides, so I pull it. It needs a push. There is no sign saying push or pull, and nothing stops me pulling. When I pull, the door just doesn't budge and gives no click or sign, so I can't tell if it is locked or if I am doing it wrong.",
 "often": "every time",
 "others": "others too",
 "cues": "discover: \"no sign\"\nconstraints: \"nothing stops\"\nfeedback: \"no click\""
}

{
 "task": "diagnose",
 "headline": "The glass door into the office let you down, not the other way round.",
 "rows": [
  {
   "id": "discover",
   "ok": false,
   "note": "There is no sign saying push or pull, and the same bar handle sits on both sides."
  },
  {
   "id": "mapping",
   "ok": true,
   "note": "The description does not say whether the handle lines up with what it does to the door."
  },
  {
   "id": "constraints",
   "ok": false,
   "note": "Nothing stops you from pulling, even though the door needs a push instead."
  },
  {
   "id": "feedback",
   "ok": false,
   "note": "The door gives no click or sign when you pull, so you cannot tell if it is locked or wrong."
  },
  {
   "id": "recover",
   "ok": true,
   "note": "The description does not mention whether you could undo the pull or try again differently."
  }
 ],
 "score": 4,
 "verdict": "the-thing",
 "culprit": "discover",
 "error_type": "mistake",
 "error_why": "You wanted to get into the office, but you pulled the bar handle because it seemed to mean pull, when the door needed a push.",
 "label": "PUSH TO OPEN",
 "label_where": "Ask whoever manages the office first, then stick the label on the door above the handle.",
 "for_you": "Next time, try pushing the bar handle instead of pulling it, since pulling does not open the door.",
 "for_maker": "Add a sign on the door that says push or pull, so the handle's direction is clear before anyone pulls it."
}

{
 "task": "diagnose",
 "thing": "the self-checkout at the supermarket",
 "goal": "Pay for a few things without help",
 "happened": "I put my own bag on the bagging area before scanning anything, because that is what I do at the till. The screen kept saying unexpected item in the bagging area and would not let me scan. There was no message about where my bag should go, and in the end I had to wait for an assistant to come and reset it.",
 "often": "first time",
 "others": "not sure",
 "cues": "feedback: \"no message\"\nrecover: \"had to wait for an assistant\""
}

{
 "task": "diagnose",
 "headline": "The self-checkout at the supermarket didn't show where your bag should go, and a familiar habit led you astray.",
 "rows": [
  {
   "id": "discover",
   "ok": false,
   "note": "You say there was no message about where your bag should go, so nothing showed you that before you put it down."
  },
  {
   "id": "mapping",
   "ok": true,
   "note": "You didn't mention anything about whether the self-checkout's buttons or controls matched what they changed."
  },
  {
   "id": "constraints",
   "ok": true,
   "note": "The self-checkout stopped you from scanning once it flagged the unexpected item, so the wrong move could not carry on."
  },
  {
   "id": "feedback",
   "ok": true,
   "note": "The screen did tell you straight away, saying unexpected item in the bagging area, so you knew something needed fixing."
  },
  {
   "id": "recover",
   "ok": false,
   "note": "You had to wait for an assistant to come and reset it, with no way to clear it yourself."
  }
 ],
 "score": 6,
 "verdict": "a-bit-of-both",
 "culprit": "discover",
 "error_type": "slip",
 "error_why": "You wanted to pay for a few things without help, but you put your bag down out of habit from the till, before scanning.",
 "label": "SCAN BEFORE BAGGING",
 "label_where": "Ask staff before sticking it, then place it beside the bagging area, clear of any display or control.",
 "for_you": "Next time, wait to set your bag down until after scanning an item, then bag things as you go.",
 "for_maker": "Whoever installs these machines could add a clear sign or on-screen note showing customers where to put their bag before scanning."
}

{
 "task": "diagnose",
 "thing": "the hob in my kitchen",
 "goal": "Heat a pan on the back right ring",
 "happened": "The four knobs are in a row along the front and I turned the second one, which I thought was the back right. The front left ring started glowing instead. I spotted the glow straight away and turned it off, then tried the next knob along.",
 "often": "now and then",
 "others": "just me",
 "cues": "mapping: \"in a row\""
}

{
 "task": "diagnose",
 "headline": "The hob's knobs don't show which ring they control, and that gap caught you this time.",
 "rows": [
  {
   "id": "discover",
   "ok": true,
   "note": "The description doesn't mention whether anything showed you what each knob was for."
  },
  {
   "id": "mapping",
   "ok": false,
   "note": "You turned the knob you thought matched the back right ring, but the front left ring lit up instead."
  },
  {
   "id": "constraints",
   "ok": true,
   "note": "The description doesn't mention anything stopping the wrong knob from being turned."
  },
  {
   "id": "feedback",
   "ok": true,
   "note": "The glow let you see straight away that the wrong ring had come on."
  },
  {
   "id": "recover",
   "ok": true,
   "note": "You turned off the glowing ring and were able to try another knob straight after."
  }
 ],
 "score": 8,
 "verdict": "a-bit-of-both",
 "culprit": "mapping",
 "error_type": "mistake",
 "error_why": "You believed the second knob controlled the back right ring, so you turned it expecting that ring to heat up.",
 "label": "MARK KNOB TO RING",
 "label_where": "Stick it on the front of the hob, beside the knobs, not on any knob, control or marking.",
 "for_you": "Turn one knob at a time, and check that the back right ring glows before you place the pan on it.",
 "for_maker": "Add clear markings or a diagram above the knobs showing which knob controls which ring."
}

{
 "task": "diagnose",
 "thing": "my kettle",
 "goal": "Boil water for a cup of tea",
 "happened": "I filled it, put it on its base and sat back down, then found it still cold when I went back. The switch has a blue light that comes on when it is boiling, and the light was off. I had just not pressed the switch.",
 "often": "first time",
 "others": "just me",
 "cues": "none"
}

{
 "task": "diagnose",
 "headline": "Your kettle was working fine, pressing the switch was the step that didn't happen this time.",
 "rows": [
  {
   "id": "discover",
   "ok": true,
   "note": "The description does not say whether it was clear what to do and where."
  },
  {
   "id": "mapping",
   "ok": true,
   "note": "The description does not say anything about mixing up which control does what."
  },
  {
   "id": "constraints",
   "ok": true,
   "note": "The description does not mention any wrong move being allowed or hard to avoid."
  },
  {
   "id": "feedback",
   "ok": true,
   "note": "The blue light stayed off exactly because the switch had not been pressed, matching the kettle's real state."
  },
  {
   "id": "recover",
   "ok": true,
   "note": "The description does not mention any trouble getting the kettle going again once this was noticed."
  }
 ],
 "score": 10,
 "verdict": "a-slip",
 "culprit": "",
 "error_type": "slip",
 "error_why": "You wanted to boil water for tea, filled the kettle and set it on its base, but pressing the switch didn't happen.",
 "label": "PRESS SWITCH TO START",
 "label_where": "Stick it on the kettle's body just beside the switch, not covering the blue light.",
 "for_you": "Press the switch, then look for the blue light before walking away.",
 "for_maker": "Add a short beep when the switch is pressed, so missing that step is easier to notice before walking away."
}

const K = FaultKit, R = ReplyKit;
const built = K.buildInput({ thing: "the glass door into the office", goal: "Get into the office",
  happened: "Same handle on both sides, so I pulled. It needed a push. No sign either way.",
  often: "every", others: "others" });  // built.ok is false, with built.note, when the form is too thin
const wire = K.toWire(built.input);     // POST this to /estimate and /run; built.facts.cues holds the page's cues
// then: const reply = R.normalize(R.parseReply(job.output.output));
// R.settle(reply)                      // the score, verdict and culprit worked out from the rows
// R.check(reply, built).notes          // the page's re-check of the reply
// R.md(built, reply, K.title(built.form))   // the diagnosis as Markdown

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://blame-the-thing.skillsafe.ai/tokens.html
api() { # api METHOD PATH [JSON-BODY]
  curl -s -X "$1" "$BASE$2" -H "Content-Type: application/json" \
    ${TOKEN:+-H "Authorization: Bearer $TOKEN"} ${3:+--data "$3"}
}

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN=$(curl -s -X POST "$BASE/guest" -H "Content-Type: application/json" -d '{"slug":"blame-the-thing"}' | jq -r '.data.token')

api GET /me | jq '.data | {subject_type, credits}' 

# input.json: the run input object - {"task": "diagnose", "thing": "the glass door into the office", "goal": "...", "happened": "...", "often": "every time", "others": "others too", "cues": "...", ...}
# - see the field table
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}' 

KEY="blame-the-thing:diagnose:$(shasum -a 256 input.json | cut -c1-16):a1"
JOB=$(curl -s -X POST "$BASE/run" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $KEY" --data @input.json | jq -r '.data.job_id')
while :; do
  J=$(api GET "/jobs/$JOB"); S=$(echo "$J" | jq -r '.data.status')
  case "$S" in succeeded|failed|cancelled) break;; esac; sleep 2
done
echo "$J" | jq -r '.data.output.output' > reply.json   # one JSON object, the reply contract
echo "$J" | jq '.data | {charged_credits, truncated}' 

# Server-Sent Events: tick/delta events while the job runs, then a final event with the job
curl -N -s -X POST "$BASE/run-stream" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: blame-the-thing:diagnose:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json