Drive Sim Desk from your own code

{
  "settings": {
    "time_unit": "minutes",
    "target_relative_half_width": 0.05,
    "simpy_version": "4.1.2",
    "schema_version": "1.1",
    "seed_rule": "derive_seed(base_seed, replication, 'arrivals'|'service') = BLAKE2b digest_size 8 of 'simpy-skill-v1|{base_seed}|{replication}|{stream}', big-endian"
  },
  "config": {
    "model": {
      "analysis_mode": "terminating", "horizon": 480, "warm_up": 0,
      "servers": 2, "queue_capacity": 20, "mean_interarrival": 4, "mean_service": 6,
      "base_seed": "20260723", "max_entities": 10000, "max_events": 200000
    },
    "replications": 20,
    "confidence": 0.95
  },
  "offered": {"arrival_rate": 0.25, "service_rate": 0.166667, "offered_load": 1.5, "rho_per_server": 0.75, "system_capacity": 22},
  "totals": {"arrivals": 2492, "rejected": 0, "admitted": 2492, "completed": 2404, "observed_completed": 2404,
             "unfinished": 88, "replications_with_unfinished": 20, "entity_limit_hits": 0, "no_completions": 0,
             "max_events_used": 832, "event_limit": 200000},
  "intervals": {
    "average_wait": {"mean": 6.40839, "lower": 4.78338, "upper": 8.0334, "half_width": 1.62501, "relative_half_width": 0.2536},
    "average_queue_length": {"mean": 1.70105, "lower": 1.25627, "upper": 2.14583, "half_width": 0.444783, "relative_half_width": 0.2615},
    "server_utilization": {"mean": 0.758245, "lower": 0.710961, "upper": 0.805528, "half_width": 0.0472836, "relative_half_width": 0.06236},
    "...": "average_system_time, loss_probability, throughput_per_time_unit"
  },
  "spread_across_replications": {"average_wait": {"min": 0.792059, "max": 15.0574}, "...": "5 more"},
  "t_critical": 2.0930241,
  "precision": {
    "target": 0.05,
    "rows": [
      {"metric": "average_queue_length", "relative_half_width": 0.2615, "replications_needed": 547},
      {"metric": "average_wait", "relative_half_width": 0.2536, "replications_needed": 515},
      "... 3 more"
    ],
    "negligible_wait_excluded": false
  },
  "benchmark": {
    "method": "M/M/c/K steady state (exponential arrivals and service, c servers, capacity c + queue_capacity)",
    "applies": false,
    "values": {"average_wait": 7.58296, "loss_probability": 0.00051044, "...": "7 more"},
    "within_interval": {"average_wait": true, "loss_probability": false, "...": "4 more"}
  },
  "windows": {"count": 20, "window_length": 24, "queue_length_mean": [0.347, 0.7081, 0.8365, "... 17 more"],
              "warm_up_window": 0, "first_post_warm_up": 0.347, "later_average": 1.684},
  "comparison": {
    "method": "paired differences B - A across replications with common random numbers",
    "changes": {"servers": {"a": 2, "b": 3}},
    "pairs": 20,
    "scenario_b": {"model": {"servers": 3, "...": "as config.model"}, "replications": 20, "confidence": 0.95},
    "benchmark_b": {"...": "as benchmark.values, for B"},
    "intervals_b": {"...": "as intervals, for B"},
    "rows": [
      {"metric": "average_wait", "a_mean": 6.40839, "b_mean": 0.924186, "diff_mean": -5.4842,
       "diff_lower": -6.90669, "diff_upper": -4.06171, "excludes_zero": true, "better": "b"},
      {"metric": "server_utilization", "a_mean": 0.758245, "b_mean": 0.513716, "diff_mean": -0.244529,
       "diff_lower": -0.259383, "diff_upper": -0.229675, "excludes_zero": true, "better": "not_judged"},
      "... 4 more"
    ],
    "browser_call": "b_better"
  },
  "metrics": [
    {"id": "M1", "metric": "offered load per server (rho)", "value": 0.75,
     "basis": "mean_service / (servers x mean_interarrival) = 6 / (2 x 4); at or above 1 the queue can only be held by its cap of 20"},
    {"id": "M4", "metric": "average wait in queue", "value": 6.40839, "lower": 4.78338, "upper": 8.0334,
     "half_width": 1.62501, "relative_half_width": 0.2536,
     "basis": "95% Student-t interval across 20 replications, completed customers who arrived at or after warm-up"},
    {"id": "M9", "metric": "worst relative half-width", "value": 0.2615, "metric_name": "average_queue_length",
     "replications_needed": 547, "target": 0.05, "basis": "..."},
    "... M2, M3, M5-M8, M10-M14"
  ],
  "flags": [
    {"id": "F1", "severity": "low", "category": "censoring",
     "message": "88 admitted customers (3.53% of those admitted and tracked) were still waiting or in service at the horizon and are left out of the wait averages, which biases them low only slightly.",
     "refs": "M8"},
    {"id": "F2", "severity": "medium", "category": "precision",
     "message": "The average queue length interval is +/-26.1% of its mean, wider than the 5% target; about 547 replications would reach it.",
     "refs": "M9"}
  ],
  "browser_verdict": "caveated",
  "expected": {
    "arrival_seed_rep0": "4022215348497587693",
    "service_seed_rep0": "14857552695425099618",
    "total_arrivals": 2492,
    "total_rejected": 0,
    "total_completed": 2404,
    "t_critical": 2.0930240544083016,
    "mean_average_wait": 6.4083885867886154,
    "half_width_average_wait": 1.6250106068402077,
    "diff_mean_average_wait": -5.4842023119996774,
    "...": "12 more: mean_ and half_width_ of every interval metric, diff_mean_server_utilization, diff_mean_loss_probability"
  },
  "expected_count": 21,
  "clipped": []
}

// make-body.js - build the exact body the page sends, with the page's own code.
// Save https://sim-desk.skillsafe.ai/deskkit.js and https://sim-desk.skillsafe.ai/simkit.js next to
// this file, edit the form values below, then:   node make-body.js > body.json
const K = require("./deskkit.js");
const set = {
  lane: "interpret", title: "Walk-in vaccination clinic", time_unit: "minutes",
  context: "Walk-in vaccination clinic open 8 hours. ... I think two nurses keep the average wait under 5 minutes.",
  question: "Is a third nurse worth it?", decision: "",
  servers: "2", queue_capacity: "20", mean_interarrival: "4", mean_service: "6", horizon: "480",
  analysis_mode: "terminating", warm_up: "0", base_seed: "20260723", max_entities: "10000", max_events: "200000",
  replications: "20", confidence: "0.95",
  b_servers: "3",                           // scenario B: leave every b_ field out for no comparison
};
const pl = K.plan(set);                     // validates exactly as replication_runner.py does
if (!pl.ok) throw new Error(pl.errors.join("; "));
const a = K.runAll(pl.a), b = pl.b ? K.runAll(pl.b) : null;
const X = K.analyze(set, pl, a, b);
const body = K.mustBeObject(K.buildInput(X, set));
console.error("browser verdict:", X.hint, "| flags:", X.flags.map(f => f.id + " " + f.category).join(", "));
console.error("idempotency key: sim-desk:" + body.task + ":" + K.hashInput(body) + ":a1");
console.log(JSON.stringify(body));

# Or build the body in any language from a facts object you already hold (for example one you
# assembled from replication_runner.py's report). facts must go in as a STRING.
#   python3 build_body.py facts.json > body.json
import json, sys

facts = json.load(open(sys.argv[1]))
body = {
    "task": "interpret",
    "title": "Walk-in vaccination clinic",
    "context": "Walk-in vaccination clinic open 8 hours. ... I think two nurses keep the average wait under 5 minutes.",
    "question": "Is a third nurse worth it?",
    "facts": json.dumps(facts, separators=(",", ":")),
}
print(json.dumps(body))

{"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="sim-desk"
TOKEN="$SKILLSAFE_TOKEN"   # from https://sim-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://sim-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":"sim-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="sim-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"])'

# 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' "$OUT" | python3 -c 'import sys,json;r=json.loads(json.load(sys.stdin)["data"]["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
  "study": ["1-3 strings: terminating or steady state, horizon and warm-up, replications, what the intervals cover"],
  "comparison": {"call": "b_better|a_better|trade_off|no_clear_difference|not_run", "reading": "..."},
  "claims": [{"claim": "...", "support": "supported|partly|not_supported", "why": "..."}],
  "cautions": ["1-4 strings on what the study cannot show"],
  // script:
  "fixes": [{"fix": "...", "why": "...", "refs": "F2"}],  // 1-5; refs "" for a plain reproduction step
  "script": "import hashlib\nimport math\nimport random\nimport simpy\n...",
  "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": "Walk-in vaccination clinic",
 "context": "Walk-in vaccination clinic open 8 hours. People arrive about every 4 minutes and a shot takes about 6 minutes; the waiting room holds 20. We want to know whether a third nurse is worth it. I think two nurses keep the average wait under 5 minutes.",
 "question": "Is a third nurse worth it?",
 "facts": "{\"settings\":{\"time_unit\":\"minutes\",\"target_relative_half_width\":0.05,\"simpy_version\":\"4.1.2\",\"...\":\"more\"},\"config\":{\"model\":{\"analysis_mode\":\"terminating\",\"horizon\":480,\"warm_up\":0,\"servers\":2,\"queue_capacity\":20,\"mean_interarrival\":4,\"mean_service\":6,\"base_seed\":\"20260723\",\"max_entities\":10000,\"max_events\":200000},\"replications\":20,\"confidence\":0.95},\"offered\":{\"arrival_rate\":0.25,\"service_rate\":0.166667,\"offered_load\":1.5,\"rho_per_server\":0.75,\"system_capacity\":22},\"totals\":{\"arrivals\":2492,\"rejected\":0,\"completed\":2404,\"unfinished\":88,\"...\":\"more\"},\"intervals\":{\"average_wait\":{\"mean\":6.40839,\"lower\":4.78338,\"upper\":8.0334,\"half_width\":1.62501,\"relative_half_width\":0.2536},\"...\":\"5 more\"},\"...\":\"spread_across_replications, t_critical, precision, benchmark, windows, metrics M1-M14 as above\",\"comparison\":{\"changes\":{\"servers\":{\"a\":2,\"b\":3}},\"pairs\":20,\"rows\":[\"... 6 rows\"],\"browser_call\":\"b_better\"},\"flags\":[{\"id\":\"F1\",\"severity\":\"low\",\"category\":\"censoring\",\"message\":\"88 admitted customers (3.53% of those admitted and tracked) were still waiting or in service at the horizon and are left out of the wait averages, which biases them low only slightly.\",\"refs\":\"M8\"},{\"id\":\"F2\",\"severity\":\"medium\",\"category\":\"precision\",\"message\":\"The average queue length interval is +/-26.1% of its mean, wider than the 5% target; about 547 replications would reach it.\",\"refs\":\"M9\"}],\"browser_verdict\":\"caveated\",\"expected\":{\"arrival_seed_rep0\":\"4022215348497587693\",\"total_arrivals\":2492,\"...\":\"19 more\"},\"expected_count\":21,\"clipped\":[]}"
}

{
 "lane": "interpret",
 "verdict": "caveated",
 "headline": "In this terminating 480-minute, 2-nurse clinic model average wait is 6.41 minutes and queue length 1.70 with a wide (about 26%) precision margin, while a paired 3-nurse scenario shows meaningfully shorter waits, queues and system time at lower utilization (b_better).",
 "tldr": [
  "Answer: In this model, moving from 2 to 3 nurses (scenario B) lowers average wait, queue length and time in system, each with a paired interval that excludes zero (browser_call b_better), at the cost of lower server utilization (75.8% to 51.4%); this is a within-model comparison, not a real-world guarantee.",
  "With 2 nurses, average wait is estimated at 6.41 minutes (95% CI 4.78 to 8.03), above the user's 5-minute target, though the CI's lower edge does dip under it.",
  "..."
 ],
 "metrics": [
  {
   "id": "M4",
   "reading": "Those same customers waited an average of 6.41 minutes before being seen (95% CI 4.78 to 8.03 minutes)."
  },
  "... M1-M3, M5-M14"
 ],
 "study": [
  "This is a terminating-horizon study: all 20 replications start empty and run for exactly 480 minutes with no warm-up (warm_up = 0), so the results describe this single 8-hour opening, not a long-run average.",
  "..."
 ],
 "comparison": {
  "call": "b_better",
  "reading": "Scenario B (3 servers) shows lower average queue length, average system time and average wait, and higher throughput, each with a paired 95% interval that excludes zero; server utilization is also lower with a non-zero interval but is not itself better or worse, and loss probability shows no clear difference (both estimated at 0)."
 },
 "claims": [
  {
   "claim": "Two nurses keep the average wait under 5 minutes.",
   "support": "partly",
   "why": "The average_wait point estimate for the 2-server model is 6.41 minutes, above 5, but its 95% CI (4.78 to 8.03) spans both sides of 5 minutes, so the facts lean against the claim without ruling it out at the current precision."
  }
 ],
 "cautions": [
  "This model assumes exponential (memoryless) interarrival and service times and a single pool of interchangeable nurses; it does not show how real patients or a specific clinic layout would behave under other distributions.",
  "..."
 ],
 "next_steps": [
  "If tighter precision on average queue length is needed, run about 547 replications (precision.rows), since the current interval is about +/-26.1% of the mean.",
  "..."
 ],
 "prescan_responses": [
  {
   "ref": "F1",
   "verdict": "confirmed",
   "note": "totals.unfinished is 88 across the 20 replications, matching the flag's count of admitted-but-not-completed customers, and these are indeed excluded from the wait and time-in-system averages, so the concern applies."
  },
  {
   "ref": "F2",
   "verdict": "confirmed",
   "note": "intervals.average_queue_length.relative_half_width is 0.2615 (about 26.1%), matching the flag, well above precision.target of 0.05, so the concern applies."
  }
 ]
}

{
 "task": "script",
 "title": "Walk-in vaccination clinic",
 "context": "Walk-in vaccination clinic open 8 hours. People arrive about every 4 minutes and a shot takes about 6 minutes; the waiting room holds 20. We want to know whether a third nurse is worth it. I think two nurses keep the average wait under 5 minutes.",
 "decision": "Verdict: caveated.\nIn this terminating 480-minute, 2-nurse clinic model average wait is 6.41 minutes ...\n- M1: ...\n- M14: ...\nComparison: b_better. ...\nNext steps:\n- ...",
 "facts": "{... the same study's facts string ...}"
}