Drive Brainstorm Desk from your own code

{
 "task": "review",
 "criteria": "{\"schema_version\":\"1.0\",\"criteria\":[{\"name\":\"information_gain\",\"description\":\"How much the idea would teach us\",\"weight\":3,\"direction\":\"higher\",\"minimum\":1,\"maximum\":5},{\"name\":\"resource_burden\",\"description\":\"Staff time and cost\",\"weight\":2,\"direction\":\"lower\",\"minimum\":1,\"maximum\":5}]}",
 "scores": "idea_id,information_gain,resource_burden\nI1,4,2\nI2,4,3\n",
 "facts": "{\"page\":\"brainstorm-desk\",\"skill_tools\":\"validate_register.py, evaluate_matrix.py (scientific-brainstorming skill, run in the browser)\",\"register\":{\"absent\":true},\"matrix\":{\"exit\":0,\"weight_delta\":0.1,\"criteria\":[{\"name\":\"information_gain\",\"direction\":\"higher\",\"minimum\":1,\"maximum\":5,\"weight\":3,\"normalized_weight\":0.6},{\"name\":\"resource_burden\",\"direction\":\"lower\",\"minimum\":1,\"maximum\":5,\"weight\":2,\"normalized_weight\":0.4}],\"results\":[{\"idea_id\":\"I1\",\"presentation_rank\":1,\"score\":0.75,\"input_interval\":[0.6,0.85],\"weight_sensitivity_scores\":[0.75,0.75],\"weight_sensitivity_ranks\":[1,1],\"in_shortlist\":true},{\"idea_id\":\"I2\",\"presentation_rank\":2,\"score\":0.65,\"input_interval\":[0.5,0.8],\"weight_sensitivity_scores\":[0.6,0.7],\"weight_sensitivity_ranks\":[2,2],\"in_shortlist\":true}],\"warnings\":[],\"decision\":null},\"shortlist\":[\"I1\",\"I2\"],\"flags\":[{\"id\":\"F1\",\"kind\":\"interval_overlap\",\"text\":\"The input intervals of I1 [0.6, 0.85] and I2 [0.5, 0.8] overlap: the rank order may not hold.\"}],\"browser_status\":\"ready_for_decision_owner\"}",
 "notes": "Imaging core sample-prep session; the decision owner is the core manager."
}

{
  "task": "review",
  "status": "ready_for_decision_owner",
  "headline": "I1 ranks first on the sheet, but its interval overlaps I2's, so the order is a weak signal for the decision owner.",
  "flag_responses": [
    {"ref": "F1", "stance": "confirmed", "note": "Intervals [0.6, 0.85] and [0.5, 0.8] overlap; the 0.1 score gap rests on one resource_burden point."}
  ],
  "idea_reviews": [
    {"idea_id": "I1", "strongest_version": "Batch staining on a shared rack cuts hands-on time per sample.",
     "counter_observation": "Batching may lengthen the wait for urgent single samples.",
     "alternative_explanations": ["Perceived gain may come from the proposer's own workload.", "Prep time may be driven by booking, not staining."],
     "measurement_failure": "Ratings are board estimates, not timed runs.",
     "sampling_failure": "Three participants from one lab rated it.",
     "harm_or_misuse": "Cross-contamination between samples on a shared rack.",
     "mitigation": "Time ten preps before and after; label rack positions.",
     "residual_uncertainty": "Effect size on turnaround is unknown.",
     "disposition": "retain", "next_action": "pilot-design"},
    {"idea_id": "I2", "strongest_version": "A pre-booked prep calendar removes queueing.",
     "counter_observation": "Unused slots may block other users.",
     "alternative_explanations": ["Queues may already be short outside peak weeks.", "No-shows, not booking, may cause the delays."],
     "measurement_failure": "No queue data was cited.",
     "sampling_failure": "Core users outside the session were not asked.",
     "harm_or_misuse": "None apparent beyond access fairness.",
     "mitigation": "Pull two months of booking logs first.",
     "residual_uncertainty": "Whether queueing is the bottleneck.",
     "disposition": "revise", "next_action": "further-search"}
  ],
  "fragility": [{"idea_id": "I2", "note": "Its weight-sensitivity scores span 0.6 to 0.7; the rank holds at 2 across the tested weights."}],
  "gates": [{"idea_id": "I1", "gate": "biosafety", "status": "unclear", "note": "Depends on which specimens share the rack."}],
  "criteria_issues": ["No criterion covers turnaround for urgent samples."],
  "missing_perspectives": ["Occasional core users", "Biosafety officer"],
  "questions": ["Which specimen classes would share the batch rack?"],
  "decision": null,
  "not_established": ["That either idea reduces prep time.", "That the rank order would survive re-rating by other users."]
}

{
 "task": "draft",
 "notes": "Session 2026-09-20. Facilitator P1, participants P2 and P3. Question: how can the imaging core cut sample-prep time? Ideas: I1 batch staining on a shared rack (P2); I2 a pre-booked prep-slot calendar (P3); I3 train two more users on the embedder (P1). Criteria: information_gain, higher is better, weight 3; resource_burden, lower is better, weight 2; both rated 1-5. Board ratings: I1 4 and 2; I2 2 and 1; I3 3 and 4."
}

{
  "task": "draft",
  "headline": "Three ideas from a three-person imaging-core session, with the board ratings carried into the sheet.",
  "register": {"schema_version": "1.1", "...": "the complete register: the session, pseudonymous participants P1-P3, and ideas I1-I3 exactly as in the notes"},
  "criteria": {"schema_version": "1.0", "criteria": [
    {"name": "information_gain", "description": "How much the idea would teach us", "weight": 3, "direction": "higher", "minimum": 1, "maximum": 5},
    {"name": "resource_burden", "description": "Staff time and cost", "weight": 2, "direction": "lower", "minimum": 1, "maximum": 5}
  ]},
  "scores_csv": "idea_id,information_gain,resource_burden\nI1,4,2\nI2,2,1\nI3,3,4\n",
  "ratings_source": "notes",
  "assumptions_made": [
    {"field": "criteria[0].description", "value": "How much the idea would teach us", "why": "The notes name the criterion but do not describe it."}
  ],
  "open_questions": ["Who is the decision owner for the shortlist?"],
  "changes": []
}

{"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="brainstorm-desk"
TOKEN="$SKILLSAFE_TOKEN"   # from https://brainstorm-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://brainstorm-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":"brainstorm-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 (see the
# worked examples above). 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 ("draft", "review")
assert all(isinstance(v, str) for v in b.values())
if b["task"] == "review":
    assert b.get("criteria", "").strip() and b.get("scores", "").strip()
    assert isinstance(json.loads(b.get("facts", "")), dict)
else:
    assert b.get("notes", "").strip() or b.get("register", "").strip()
'
INPUT=$(cat body.json)

call estimate "$INPUT"
# {"ok":true,"data":{"model":"...","model_alias":"gpt-terra",
#   "markup_bps":...,"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"])')   # draft or review
KEY="brainstorm-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":"{\"task\":\"review\",\"status\":\"ready_for_decision_owner\",\"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":"{\"task\":\"review\",\"status\":\"ready_for_decision_owner\",\"headline\":\"The"}
# event: done   {"status":"succeeded","charged_credits":...,"truncated":false}

# The reply is a JSON string inside data.output.output (saved as reply.json in step 5):
python3 -c 'import json;r=json.load(open("reply.json"));print(r["task"],r.get("status",""),r["headline"])'
# A draft: save the three files and compute the facts with the skill's own scripts.
python3 -c '
import json
r = json.load(open("reply.json"))
json.dump(r["register"], open("register.json", "w"), indent=2)
json.dump(r["criteria"], open("criteria.json", "w"), indent=2)
open("scores.csv", "w").write(r["scores_csv"])
'
python3 scripts/validate_register.py register.json
python3 scripts/evaluate_matrix.py scores.csv --config criteria.json