Drive FBA Desk from your own code

{
  "settings": {
    "objective": [{"id": "Biomass_Ecoli_core", "coef": 1}],
    "direction": "max",
    "fraction_of_optimum": 1,
    "default_bound": 1000,
    "tolerance": 1e-07,
    "essential_threshold_rule": "growth below 1% of the optimum, or infeasible",
    "format": "text",
    "model_id": "e_coli_core",
    "solver": "browser bounded simplex, checked against cobrapy 0.32.1 with GLPK"
  },
  "model": {
    "reactions": 95,
    "metabolites": 72,
    "genes": 137,
    "boundary_reactions": 20,
    "internal_reactions": 75,
    "compartments": ["c", "e"],
    "metabolites_with_formula": 72,
    "reactions_with_gpr": 69,
    "lines_not_read": 0
  },
  "fba": {"status": "optimal", "objective_value": 0.873922},
  "pfba": {"total_flux": 518.422},
  "medium": [
    {
      "id": "EX_glc__D_e",
      "metabolite": "glc__D_e",
      "bound": -10,
      "unlimited": false,
      "flux": -10
    },
    {"id": "EX_o2_e", "metabolite": "o2_e", "bound": -1000, "unlimited": true, "flux": -21.7995},
    "... 5 more"
  ],
  "exchanges": [
    {"id": "EX_glc__D_e", "metabolite": "glc__D_e", "flux": -10, "direction": "uptake"},
    {"id": "EX_o2_e", "metabolite": "o2_e", "flux": -21.7995, "direction": "uptake"},
    {"id": "EX_co2_e", "metabolite": "co2_e", "flux": 22.8098, "direction": "secretion"},
    "... 4 more"
  ],
  "top_fluxes": [
    {"id": "ATPS4r", "name": "", "flux": 45.514},
    {"id": "CYTBD", "name": "", "flux": 43.599},
    {"id": "NADH16", "name": "", "flux": 38.5346},
    "... 22 more"
  ],
  "fva": {
    "fraction_of_optimum": 1,
    "rows_total": 9,
    "rows": [
      {"id": "EX_co2_e", "min": 22.8098, "max": 22.8098, "boundary": true},
      {"id": "EX_glc__D_e", "min": -10, "max": -10, "boundary": true},
      "..."
    ]
  },
  "blocked": {
    "count": 8,
    "ids": [
      "EX_fru_e",
      "EX_fum_e",
      "EX_gln__L_e",
      "EX_mal__L_e",
      "FRUpts2",
      "FUMt2_2",
      "GLNabc",
      "MALt2_2"
    ]
  },
  "dead_ends": {"count": 4, "ids": ["fru_e (only consumed)", "fum_e (only consumed)", "..."]},
  "knockouts": {
    "threshold": 0.00873922,
    "reactions": {
      "tested": 95,
      "essential": [
        {"id": "ACONTa", "growth": 0, "status": "optimal"},
        {"id": "ACONTb", "growth": 0, "status": "optimal"},
        "... 16 more"
      ],
      "reduced_not_essential": ["..."]
    },
    "genes": {
      "tested": 137,
      "essential": [
        {"id": "b0720", "growth": 0, "status": "optimal"},
        {"id": "b2779", "growth": 0, "status": "optimal"},
        "... 5 more"
      ],
      "reduced_not_essential": ["..."]
    }
  },
  "mass_balance": {
    "checked": 75,
    "imbalanced": [],
    "objective_reaction_imbalanced": ["Biomass_Ecoli_core"],
    "not_checked_missing_formula": 0
  },
  "metrics": [
    {
      "id": "M1",
      "metric": "objective_value",
      "value": 0.873922,
      "basis": "maximise Biomass_Ecoli_core at steady state under the pasted bounds (model.slim_optimize)"
    },
    {
      "id": "M2",
      "metric": "pfba_total_flux",
      "value": 518.422,
      "basis": "sum of absolute fluxes, minimised with the objective held at its optimum (cobra.flux_analysis.pfba)"
    },
    {
      "id": "M9",
      "metric": "objective_at_10x_default_bound",
      "value": 0.873922,
      "basis": "the optimum again with every bound of magnitude 1000 raised tenfold; equal to M1 means the default bound does not limit the objective"
    },
    {
      "id": "M10",
      "metric": "gain_EX_glc__D_e",
      "value": 0.0916647,
      "basis": "change in the objective when the uptake bound of EX_glc__D_e (lower_bound -10) is opened by 1 unit; above 0 means this uptake limits the objective",
      "reaction": "EX_glc__D_e",
      "side": "lower_bound"
    },
    "... M3-M8"
  ],
  "flags": [
    {
      "id": "F1",
      "severity": "medium",
      "category": "range_at_cap",
      "message": "1 internal reaction(s) reach the default bound in FVA at 100% of the optimum (SUCDi): a thermodynamically infeasible cycle, or an uptake limited only by the default bound, lets them carry flux up to the cap. Those FVA ranges are set by the cap; loopless FVA removes the cycle case, a finite uptake bound the other.",
      "refs": ["SUCDi"]
    },
    "... F2-F5 (low)"
  ],
  "browser_verdict": "caveated",
  "expected": {
    "objective_value": 0.873921507,
    "pfba_total_flux": 518.4220855,
    "n_blocked": 8,
    "n_essential_reactions": 18,
    "n_essential_genes": 7,
    "objective_10x_default_bound": 0.873921507,
    "fva_min_EX_h2o_e": 29.17582714,
    "fva_max_EX_h2o_e": 29.17582714,
    "fva_min_EX_co2_e": 22.80983331,
    "fva_max_EX_co2_e": 22.80983331,
    "fva_min_EX_o2_e": -21.79949266,
    "fva_max_EX_o2_e": -21.79949266,
    "gain_EX_glc__D_e": 0.09166474638
  },
  "expected_count": 13,
  "clipped": []
}

// make-body.js - build the exact body the page sends, with the page's own code.
// Save https://fba-desk.skillsafe.ai/fbakit.js and https://fba-desk.skillsafe.ai/lp.js next to this file, then:
//   node make-body.js model.txt interpret "E. coli core on aerobic glucose" "notes" "question" 1 > body.json
// model.txt is cobrapy reaction strings in the page's text form, or a cobrapy JSON model (save_json_model).
const fs = require("fs");
const K = require("./fbakit.js");
const [file, lane = "interpret", title = "", context = "", question = "", fraction = "1", decision = ""] = process.argv.slice(2);
const set = { lane, title, context, question, decision, fraction, model: fs.readFileSync(file, "utf8") };
const X = K.analyze(set);
if (X.empty) throw new Error(X.errors.join("; ") || "no model");
const body = K.mustBeObject(K.buildInput(X, set));
console.error("browser verdict:", X.hint, "| objective:", X.fba.status, X.fba.z, "| flags:", X.flags.map(f => f.id + " " + f.category).join(", "));
console.error("idempotency key: fba-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("e-coli-core-interpret.json"))   # the page's .json download
facts = export["browser"]
body = {
    "task": "interpret",
    "title": "E. coli core on aerobic glucose",
    "context": "The E. coli core model (e_coli_core) exactly as cobrapy bundles it: ...",
    "question": "Which uptake limits growth, and does any single gene deletion stop it?",
    "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="fba-desk"
TOKEN="$SKILLSAFE_TOKEN"   # from https://fba-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://fba-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":"fba-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="fba-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
  "phenotype": ["1-4 strings: uptake and secretion, largest fluxes, lethal deletions"],
  "claims": [{"claim": "...", "support": "supported|partly|not_supported", "why": "..."}],
  "cautions": ["1-4 strings on what the analysis cannot show"],
  // script:
  "fixes": [{"fix": "...", "why": "...", "refs": "F1"}],  // 1-6; refs "" for a plain reproduction step
  "script": "import math\nimport cobra\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": "E. coli core on aerobic glucose",
 "context": "The E. coli core model (e_coli_core) exactly as cobrapy bundles it: aerobic, glucose uptake capped at 10, the biomass reaction as the objective. I want to say that growth is limited by glucose rather than oxygen, and that no single gene deletion stops growth.",
 "question": "Which uptake limits growth, and does any single gene deletion stop it?",
 "facts": "{\"settings\":{\"objective\":[{\"id\":\"Biomass_Ecoli_core\",\"coef\":1}],\"direction\":\"max\",\"fraction_of_optimum\":1,\"default_bound\":1000,\"model_id\":\"e_coli_core\",\"...\":\"more\"},\"fba\":{\"status\":\"optimal\",\"objective_value\":0.873922},\"pfba\":{\"total_flux\":518.422},\"exchanges\":[{\"id\":\"EX_glc__D_e\",\"metabolite\":\"glc__D_e\",\"flux\":-10,\"direction\":\"uptake\"},{\"id\":\"EX_o2_e\",\"metabolite\":\"o2_e\",\"flux\":-21.7995,\"direction\":\"uptake\"},{\"id\":\"EX_co2_e\",\"metabolite\":\"co2_e\",\"flux\":22.8098,\"direction\":\"secretion\"},\"... 4 more\"],\"...\":\"medium, top_fluxes, fva, blocked, dead_ends, knockouts, mass_balance, metrics, flags as above\",\"browser_verdict\":\"caveated\",\"expected\":{\"objective_value\":0.873921507,\"pfba_total_flux\":518.4220855,\"...\":\"11 more\"},\"expected_count\":13,\"clipped\":[]}"
}

{
 "task": "script",
 "title": "E. coli core on aerobic glucose",
 "context": "The E. coli core model (e_coli_core) exactly as cobrapy bundles it: aerobic, glucose uptake capped at 10, the biomass reaction as the objective. I want to say that growth is limited by glucose rather than oxygen, and that no single gene deletion stops growth.",
 "question": "",
 "decision": "Verdict: caveated.\n<headline of the interpret reply>\n- M1: <reading>\n- M2: <reading>\n...\nNext steps:\n- ...",
 "facts": "{\"settings\":{\"objective\":[{\"id\":\"Biomass_Ecoli_core\",\"coef\":1}],\"direction\":\"max\",\"fraction_of_optimum\":1,\"default_bound\":1000,\"model_id\":\"e_coli_core\",\"...\":\"more\"},\"fba\":{\"status\":\"optimal\",\"objective_value\":0.873922},\"pfba\":{\"total_flux\":518.422},\"exchanges\":[{\"id\":\"EX_glc__D_e\",\"metabolite\":\"glc__D_e\",\"flux\":-10,\"direction\":\"uptake\"},{\"id\":\"EX_o2_e\",\"metabolite\":\"o2_e\",\"flux\":-21.7995,\"direction\":\"uptake\"},{\"id\":\"EX_co2_e\",\"metabolite\":\"co2_e\",\"flux\":22.8098,\"direction\":\"secretion\"},\"... 4 more\"],\"...\":\"medium, top_fluxes, fva, blocked, dead_ends, knockouts, mass_balance, metrics, flags as above\",\"browser_verdict\":\"caveated\",\"expected\":{\"objective_value\":0.873921507,\"pfba_total_flux\":518.4220855,\"...\":\"11 more\"},\"expected_count\":13,\"clipped\":[]}"
}