Drive Six-Legged Lodgers from your own code

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

{"task": "trace", "verdict": "check-id | seal-now | wait-them-out", "verdict_reason": "...", "title": "...", "summary": "...",
 "suspect": {"name": "...", "match": "fits | unsure", "why": "..."},
 "bones": [{"id": "gaps", "causes": [{"cause": "...", "evidence": "\"words from the input\"", "weight": "strong | possible | check"}]},
           ... six bones: gaps, pipes, roof, warmth, outside, habits],
 "root_causes": [{"bone": "gaps", "cause": "...", "why": "..."}],
 "fixes": [{"when": "today | this-week | before-next-autumn", "do": "...", "bone": "gaps | ... | none"}],
 "dont": ["Don't ..."], "watch": "..."}

{
 "task": "trace",
 "bug_kind": "stink-bug (shield-shaped, brown, smells when handled)",
 "stage": "arriving (they are gathering on outside walls or only just starting to come in)",
 "warning_signs": "no",
 "sightings": "1. Outside on the back wall, about 30 on the siding in the afternoon\n2. Back bedroom, 4 stink bugs around the window air conditioner\n3. Kitchen, 2 on the door screen\n4. Back bedroom, 3 on the curtain next to the air conditioner",
 "room_tally": "Outside walls: 30 | Bedroom: 7 | Kitchen: 2",
 "house": "Two-storey house with old wooden windows. The window air conditioner in the back bedroom stays in all year. The back wall gets the afternoon sun and there is a row of trees behind the fence. The screen on the kitchen door is torn at the bottom.",
 "clues": "gaps | old wooden windows, screen, torn, siding\npipes | air conditioner\nwarmth | sun\noutside | trees"
}

{
 "task": "trace",
 "verdict": "seal-now",
 "verdict_reason": "Your answers that they are still gathering on the back wall and have only just started coming in are what call for closing up their ways in now.",
 "title": "Back wall stink bugs, time to seal",
 "summary": "Most of the insects so far are on the back wall, with far fewer in the bedroom and kitchen. Since they are only just gathering there and starting to come in, this is the time to seal up their ways in before more arrive.",
 "suspect": {
  "name": "Stink bug",
  "match": "fits",
  "why": "The sightings describe ordinary wall, screen and window gathering spots consistent with the brown, shield-shaped insect described, with nothing suggesting a different kind of insect."
 },
 "bones": [
  {
   "id": "gaps",
   "causes": [
    {
     "cause": "Torn screen on the kitchen door",
     "evidence": "\"screen on the kitchen door is torn at the bottom\"",
     "weight": "strong"
    },
    {
     "cause": "Old wooden windows may have a small crack",
     "evidence": "\"old wooden windows\"",
     "weight": "possible"
    },
    {
     "cause": "Unseen opening in the siding where they gathered",
     "evidence": "\"on the siding\"",
     "weight": "possible"
    }
   ]
  },
  {
   "id": "pipes",
   "causes": [
    {
     "cause": "An opening around the window air conditioner",
     "evidence": "\"window air conditioner in the back bedroom stays in all year\"",
     "weight": "strong"
    }
   ]
  },
  {
   "id": "roof",
   "causes": [
    {
     "cause": "A possible opening around the roofline, eaves or chimney",
     "evidence": "Not mentioned - worth a look.",
     "weight": "check"
    }
   ]
  },
  {
   "id": "warmth",
   "causes": [
    {
     "cause": "Afternoon sun warming the back wall",
     "evidence": "\"back wall gets the afternoon sun\"",
     "weight": "strong"
    }
   ]
  },
  {
   "id": "outside",
   "causes": [
    {
     "cause": "Row of trees close behind the fence",
     "evidence": "\"row of trees behind the fence\"",
     "weight": "strong"
    }
   ]
  },
  {
   "id": "habits",
   "causes": [
    {
     "cause": "Possible open doors or items carried in",
     "evidence": "Not mentioned - worth a look.",
     "weight": "check"
    }
   ]
  }
 ],
 "root_causes": [
  {
   "bone": "gaps",
   "cause": "Torn screen on the kitchen door",
   "why": "Two insects were seen on the kitchen door screen, matching the tear noted there."
  },
  {
   "bone": "pipes",
   "cause": "An opening around the window air conditioner",
   "why": "The bedroom had the highest count indoors, with sightings right around and next to the air conditioner."
  },
  {
   "bone": "warmth",
   "cause": "Afternoon sun warming the back wall",
   "why": "The back wall tally of 30 is the largest count, matching where they were seen gathering in the sun."
  }
 ],
 "fixes": [
  {
   "when": "today",
   "do": "Vacuum up or collect in a jar any insects gathering on the back wall or siding.",
   "bone": "none"
  },
  {
   "when": "this-week",
   "do": "Patch or replace the torn screen on the kitchen door.",
   "bone": "gaps"
  },
  {
   "when": "this-week",
   "do": "Seal the opening around the window air conditioner in the back bedroom with foam or weatherstripping.",
   "bone": "pipes"
  },
  {
   "when": "this-week",
   "do": "Add weatherstripping or caulk around the old wooden windows to close any small openings.",
   "bone": "gaps"
  },
  {
   "when": "before-next-autumn",
   "do": "Check the siding closely and fill any small cracks you find with caulk.",
   "bone": "gaps"
  }
 ],
 "dont": [
  "Don't squash them indoors, since it can leave a smell or a stain.",
  "Don't seal the torn screen or window openings while insects are still behind them, as you could trap them inside."
 ],
 "watch": "Note whether the numbers gathering on the back wall and siding start to drop, and whether fewer turn up by the kitchen door screen or the bedroom air conditioner after you seal things up."
}

{
 "task": "trace",
 "bug_kind": "lady-beetle (round, orange to red, often spotted)",
 "stage": "inside (they are already turning up indoors)",
 "warning_signs": "no",
 "sightings": "1. Attic bedroom, 12 on the skylight on a warm afternoon\n2. Attic bedroom, 5 around the ceiling light\n3. Bathroom, 2 near the extractor fan\n4. Landing, 1 on the window",
 "room_tally": "Attic: 17 | Bathroom: 2 | Hall and stairs: 1",
 "house": "Older house with a converted attic bedroom under the roof and a skylight. The bathroom has an extractor fan that vents through the roof. There is a field behind the house.",
 "clues": "pipes | extractor, vents\nroof | attic, roof, skylight\nwarmth | warm\noutside | field"
}

{
 "task": "trace",
 "verdict": "wait-them-out",
 "verdict_reason": "This is based on you saying the insects are already turning up inside the house, rather than still gathering on the outer walls or waking up and heading for the windows.",
 "title": "Lady beetles gathering around the attic skylight",
 "summary": "Most of the lady beetles are turning up in the attic (17), far more than the bathroom (2) or the hall and stairs (1). Since they are already indoors rather than still gathering on the outer walls, the plan is to remove the ones you see now and gradually seal their ways in, rather than rushing to treat anything.",
 "suspect": {
  "name": "Lady beetle",
  "match": "fits",
  "why": "Nothing in the sightings conflicts with the round, orange to red, often spotted description you gave for the insect."
 },
 "bones": [
  {
   "id": "gaps",
   "causes": [
    {
     "cause": "A window that could be a way in",
     "evidence": "\"1 on the window\"",
     "weight": "possible"
    },
    {
     "cause": "General wear and cracks in an older house",
     "evidence": "\"Older house\"",
     "weight": "possible"
    }
   ]
  },
  {
   "id": "pipes",
   "causes": [
    {
     "cause": "The bathroom extractor fan vent",
     "evidence": "\"extractor fan that vents through the roof\"",
     "weight": "strong"
    }
   ]
  },
  {
   "id": "roof",
   "causes": [
    {
     "cause": "The skylight in the attic bedroom",
     "evidence": "\"a converted attic bedroom under the roof and a skylight\"",
     "weight": "strong"
    }
   ]
  },
  {
   "id": "warmth",
   "causes": [
    {
     "cause": "The ceiling light drawing them in",
     "evidence": "\"5 around the ceiling light\"",
     "weight": "strong"
    },
    {
     "cause": "The warm afternoon near the skylight",
     "evidence": "\"on a warm afternoon\"",
     "weight": "possible"
    }
   ]
  },
  {
   "id": "outside",
   "causes": [
    {
     "cause": "The field behind the house",
     "evidence": "\"There is a field behind the house\"",
     "weight": "strong"
    }
   ]
  },
  {
   "id": "habits",
   "causes": [
    {
     "cause": "Doors or windows left open",
     "evidence": "Not mentioned - worth a look.",
     "weight": "check"
    }
   ]
  }
 ],
 "root_causes": [
  {
   "bone": "roof",
   "cause": "The skylight in the attic bedroom",
   "why": "Twelve of the seventeen insects counted in the attic were seen right on the skylight."
  },
  {
   "bone": "warmth",
   "cause": "The ceiling light drawing them in",
   "why": "Five of the attic sightings were insects gathered right around the ceiling light."
  },
  {
   "bone": "pipes",
   "cause": "The bathroom extractor fan vent",
   "why": "Both insects counted in the bathroom were found near the extractor fan."
  }
 ],
 "fixes": [
  {
   "when": "today",
   "do": "Vacuum up any insects you find, or collect them in a cup of soapy water, rather than squashing them.",
   "bone": "none"
  },
  {
   "when": "this-week",
   "do": "Seal around the ceiling light fitting in the attic bedroom from the inside with caulk or foam.",
   "bone": "warmth"
  },
  {
   "when": "this-week",
   "do": "Seal around the extractor fan cover in the bathroom from the inside.",
   "bone": "pipes"
  },
  {
   "when": "this-week",
   "do": "Seal around the window trim on the landing from the inside with caulk or weatherstripping.",
   "bone": "gaps"
  },
  {
   "when": "before-next-autumn",
   "do": "Have the skylight's outer seal checked and repaired where it meets the roof.",
   "bone": "roof"
  }
 ],
 "dont": [
  "Don't squash them indoors - it can leave a smell or a stain.",
  "Don't seal the cracks around the skylight or ceiling light while insects are still gathered there."
 ],
 "watch": "Note whether fewer insects are seen around the attic skylight and ceiling light after sealing, and whether any keep appearing near the bathroom extractor fan or the landing window."
}

{
 "task": "trace",
 "bug_kind": "not-sure (I don't know what it is)",
 "stage": "inside (they are already turning up indoors)",
 "warning_signs": "yes",
 "sightings": "1. Kitchen, a few small dark beetles in an open bag of flour in the cupboard\n2. Kitchen, 3 on the window sill\n3. Kitchen, 1 on the counter",
 "room_tally": "Kitchen: 7",
 "house": "Ground-floor flat. The kitchen window opens onto the yard and the bins are just outside the back door.",
 "clues": "none found"
}

{
 "task": "trace",
 "verdict": "check-id",
 "verdict_reason": "You weren't sure what kind of insect this was and also flagged one of the warning signs, so getting it identified comes first.",
 "title": "Unidentified Insects Gathering in the Kitchen",
 "summary": "All seven insects counted so far have turned up in the kitchen. Since you're not sure what kind of insect this is and flagged a warning sign, the next step is to get it identified before doing anything else.",
 "suspect": {
  "name": "Not identified yet",
  "match": "unsure",
  "why": "You said you aren't sure what kind of insect this is, so there's nothing yet to compare the sightings against."
 },
 "bones": [
  {
   "id": "gaps",
   "causes": [
    {
     "cause": "The kitchen window as a possible entry point",
     "evidence": "\"3 on the window sill\"",
     "weight": "possible"
    },
    {
     "cause": "The back door, close to the outside bins",
     "evidence": "\"the bins are just outside the back door\"",
     "weight": "possible"
    }
   ]
  },
  {
   "id": "pipes",
   "causes": [
    {
     "cause": "Vents, pipes or cables entering the kitchen",
     "evidence": "Not mentioned - worth a look.",
     "weight": "check"
    }
   ]
  },
  {
   "id": "roof",
   "causes": [
    {
     "cause": "The attic, roof edges or chimney",
     "evidence": "Not mentioned - worth a look.",
     "weight": "check"
    }
   ]
  },
  {
   "id": "warmth",
   "causes": [
    {
     "cause": "Warm sunny walls or outside lights",
     "evidence": "Not mentioned - worth a look.",
     "weight": "check"
    }
   ]
  },
  {
   "id": "outside",
   "causes": [
    {
     "cause": "Trees, plants or woodpiles close to the house",
     "evidence": "Not mentioned - worth a look.",
     "weight": "check"
    }
   ]
  },
  {
   "id": "habits",
   "causes": [
    {
     "cause": "An open bag of food left out",
     "evidence": "\"an open bag of flour in the cupboard\"",
     "weight": "strong"
    }
   ]
  }
 ],
 "root_causes": [
  {
   "bone": "habits",
   "cause": "An open bag of food left out",
   "why": "All seven insects were counted in the kitchen, the same room where the beetles were found inside an open bag of flour."
  },
  {
   "bone": "gaps",
   "cause": "The kitchen window as a possible entry point",
   "why": "Several of the insects were seen sitting on the kitchen window sill, in the same room where all seven were counted."
  },
  {
   "bone": "gaps",
   "cause": "The back door, close to the outside bins",
   "why": "All seven insects turned up in the kitchen, the room next to the back door that sits right by the outside bins."
  }
 ],
 "fixes": [
  {
   "when": "today",
   "do": "Catch one of the insects in a clear jar, or take a sharp close-up photo, and have it identified by a local extension service or a pest professional before doing anything else.",
   "bone": "none"
  },
  {
   "when": "today",
   "do": "Put the open bag of flour in a sealed bag and throw it away.",
   "bone": "none"
  },
  {
   "when": "this-week",
   "do": "Fill any gaps around the kitchen window frame with caulk or weatherstripping.",
   "bone": "gaps"
  },
  {
   "when": "this-week",
   "do": "Check the back door for gaps and seal them with weatherstripping or caulk.",
   "bone": "gaps"
  },
  {
   "when": "before-next-autumn",
   "do": "Once the insect is identified, check other possible entry points such as the roof edges, vents and siding.",
   "bone": "none"
  }
 ],
 "dont": [
  "Don't squash the insects indoors, as this can leave a smell or a stain.",
  "Don't try to get rid of them yourself before the insect has been identified.",
  "Don't seal up the window or door gaps while insects might still be behind them."
 ],
 "watch": "Watch whether the number of insects you see in the kitchen goes down once the food is put away and the window and door gaps are sealed."
}

const K = LodgeKit;
const form = K.form({ bug_kind: "boxelder-bug", stage: "arriving", warning: false,
  sightings: "Porch, about 20 on the sunny wall\nLiving room, 2 on the window", house: "Old wooden windows and a gap under the front door." });
K.sightings(form);                               // one row per line: place, count, insect
K.tally(K.sightings(form));                      // [{name: "Outside walls", count: 20}, {name: "Living room", count: 2}]
K.clues(form);                                   // clue words per bone: gaps, warmth ...
K.expected(form);                                // {verdict: "seal-now", why: [...]} - the page's rule
const built = K.buildInput(form);
const wire = K.toWire(built.input);              // POST this to /estimate and /run
// then: const reply = K.normalize(K.parseReply(job.output.output));
// K.check(reply, built).notes                   // the page's re-check of the reply
// K.md(built, reply)                            // the trace as Markdown

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://six-legged-lodgers.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":"six-legged-lodgers"}' | jq -r '.data.token')

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

# input.json: the run input object - {"task": "trace", "bug_kind": "stink-bug (shield-shaped, brown, smells when handled)", "stage": "arriving (they are gathering on outside walls or only just starting to come in)", "warning_signs": "no", "sightings": "1. Outside on the back wall, about 30 on the siding in the afternoon\n2. Back bedroom, 4 stink bugs around the window air conditioner\n3. Kitchen, 2 on the door screen\n4. Back bedroom, 3 on the curtain next to the air conditioner", "room_tally": "Outside walls: 30 | Bedroom: 7 | Kitchen: 2", "house": "Two-storey house with old wooden windows. The window air conditioner in the back bedroom stays in all year. The back wall gets the afternoon sun and there is a row of trees behind the fence. The screen on the kitchen door is torn at the bottom.", "clues": "gaps | old wooden windows, screen, torn, siding\npipes | air conditioner\nwarmth | sun\noutside | trees"}
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}' 

KEY="six-legged-lodgers:trace:$(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: six-legged-lodgers:trace:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json