| Model | Family id you send as model (moves) | Version, a pinned id (never changes) |
|---|---|---|
| DecisionNode | decisionnode | decisionnode-main-0.9.1-rc1 |
| DecisionNode Flash | decisionnode-flash | decisionnode-flash-0.9.1-rc1 |
Family ids and pinned ids#
Two words, used the same way on every page: the family id is the model you send (what the Terms of Service call an alias), and the version is the pinned id the response names. You may also send a version as model, to pin it.
- A family id such as
decisionnodeanswers from its family's current version, the one GET /v1/models names. It moves when we release a version, without notice. During a rollout, while the servers move to a new version, a request may be answered by any version a server of the family reports, so answers can change on the day of a release. - A pinned id such as
decisionnode-main-0.9.1-rc1answers from exactly that version for as long as it is available. The same request gets the same answer every time. See Determinism. - Every response names exactly the version that answered:
modelin the body andx-decisionnode-modelin the headers, whichever id you sent, during a rollout too. - GET /v1/models lists each family id with the pinned
versionit answers from today, and each pinned version being served with its family asalias.
Earlier names still work as aliases: decisionnode-1.0 and decisionnode-latest for decisionnode; decisionnode-1.0-flash and decisionnode-flash-latest for decisionnode-flash. They answer as the family's current release; send the family ids in new code.
How long a version lives#
| Commitment | Value |
|---|---|
| A pinned version stays available | At least 12 months after its successor is released |
| Notice before a pinned version retires | At least 12 months |
| How notice is given | In the console and by email to your account's contact |
| Evaluation and calibration results | We aim to publish them with each new version, before you switch to it |
The binding commitment is section 3.3 of the Terms of Service. A version may be withdrawn sooner only where the law, security or the prevention of harm requires it.
After a version retires#
A call that names a retired pinned id gets 400, with the body every unknown model name gets; nothing is billed. A family id is not retired with a version: it moves to the current one. A batch that names a retired pinned id is refused when you finalize it, with the same error, so move your batch files to the new id with your live code.
{
"detail": {
"error_type": "api_usage_error",
"message": "Unknown model: decisionnode-main-0.9.1-rc1"
}
}Moving to a new version#
- 1
Read what changed#
Each release lists its evaluation and calibration results. Check the suites closest to your work on the Benchmarks page.
- 2
Replay your own requests#
Send requests you have kept with known outcomes to your current pinned id and to the new one, and compare. The program below counts the top answers that change: the choice, the score's nearest level, a truth on the other side of your cut-off, or the number.
import json, os, requests KEY = os.environ["DECISIONNODE_API_KEY"] HEADERS = {"Authorization": f"Bearer {KEY}"} CURRENT = "decisionnode-main-0.9.1-rc1" # the pinned id your code sends today def decide(body: dict, model: str) -> dict: r = requests.post( "https://api.decisionnode.com/v1/decide", json={**body, "model": model}, headers=HEADERS, timeout=10, ) r.raise_for_status() return r.json() # the version the family id answers from now listed = requests.get("https://api.decisionnode.com/v1/models", headers=HEADERS, timeout=10) models = listed.json()["models"] candidate = next(m["version"] for m in models if m["name"] == "decisionnode") TRUE_AT = 0.5 # the cut-off your code acts at on truth answers def top(answer: dict): """What your code acts on: the choice, the level, true or false, the value.""" kind = answer["type"] if kind == "choice": return answer["choice"] if kind == "score": return round(answer["score"]) if kind == "number": return answer["number"] return answer["truth"] >= TRUE_AT # replay requests you have kept with known outcomes, one per line: {"request": {...}} changed = 0 with open("labelled.jsonl") as f: for line in f: if not line.strip(): continue case = json.loads(line) old = decide(case["request"], CURRENT)["answers"] new = decide(case["request"], candidate)["answers"] changed += sum(top(new[key]) != top(old[key]) for key in new) print(f"{candidate}: {changed} top answers differ from {CURRENT}") - 3
Re-tune your thresholds#
Probabilities are calibrated per version, so the same cut-off can act on a different share of traffic. Re-pick each threshold on the new version from your replay, the way you first chose it. See Confidence.
- 4
Switch the pinned id#
Change the id in config with the new thresholds, in one change, so a rollback restores both. Keep the old id until its retirement date for that rollback.