Versions and release gates

await pensieve.releases.stop("rel_grade_audit_v8"); // sandbox only: v8 is already in a shadow run there
const release = await pensieve.releases.shadow("grade-audit", { version: "v8" });
await pensieve.releases.signoff(release.id, { note: "Matches our reviewers on the Rust tasks." });
await pensieve.releases.split(release.id, { percent: 10 });
await pensieve.releases.promote(release.id, { expect: "v7" }); // only if v7 is still live

// And back, in seconds:
await pensieve.releases.rollback("grade-audit", { expect: "v8", reason: "Agreement dropped." });

client.releases.stop("rel_grade_audit_v8")  # sandbox only: v8 is already in a shadow run there
release = client.releases.shadow("grade-audit", version="v8")
client.releases.signoff(release.id, note="Matches our reviewers on the Rust tasks.")
client.releases.split(release.id, percent=10)
client.releases.promote(release.id, expect="v7")  # only if v7 is still live

# And back, in seconds:
client.releases.rollback("grade-audit", expect="v8", reason="Agreement dropped.")

# Sandbox only: v8 is already in a shadow run there
curl -X POST https://api.pensievelabs.co/v1/releases/rel_grade_audit_v8/stop -H "Authorization: Bearer $PENSIEVE_API_KEY"

curl https://api.pensievelabs.co/v1/models/grade-audit/releases \
  -H "Authorization: Bearer $PENSIEVE_API_KEY" -H "Content-Type: application/json" \
  -d '{"version": "v8", "shadow_days": 7}'
# then POST /v1/releases/{id}/signoff, /split, /promote, and POST /v1/models/grade-audit/rollback

In the sandbox, grade-audit’s v8 is already on day 3 of a 7-day shadow run, so the first line stops it before starting a new one. Leave that line out in a live workspace. The sandbox skips the wait, so the code above runs from top to bottom.

The gates

Experiments keep improving the recipe. When the best recipe so far is worth shipping, it is trained into a candidate version. A version goes live only when it has passed its gates, in order:

It beats the live version on your test, if there is one.
It beats the best frontier model on your test. A model that isn’t ahead of the frontier doesn’t ship, however long it has been building.
It passes a shadow run. It answers a copy of live traffic for a set number of days, 7 by default, and nothing it answers reaches your users. Its answers are checked against your experts and the outcomes.
An expert signs it off. The people named for sign-off in the app’s Settings see the shadow run’s results and approve, or send it back. In the sandbox, anyone can sign off.

Each release lists its gates, which have passed, and when.

Rolling out

After sign-off, choose how the version reaches your users:

split sends a share of calls to the new version and the rest to the live one. Raise it as you gain confidence. Routing’s split mode is a different thing: it shares calls between the model and your own code.
promote makes it the live version. It takes expect, the version you believe is live now, and refuses with conflict if someone else changed it first.
rollback moves traffic back to the previous version, which stays warm. It also takes expect.

Release states

State	Meaning
`pending`	A candidate that hasn’t passed the first two gates
`shadow`	In its shadow run
`ready_for_signoff`	The shadow run is over; waiting for an expert
`signed_off`	Approved, not yet taking traffic
`split`	Taking the share of traffic you set
`live`	The live version
`superseded`	Went live, and a later release replaced it
`rolled_back`	Went live, then the model went back to the version before
`stopped`	Stopped before going live

A version’s own status is candidate, live, standby (the previous version, kept warm for rollback) or retired.

A model’s status is building (no version beats the frontier yet), shadow (a version runs beside live traffic), live (a version takes traffic), paused (taken off traffic in the app, so your code answers every call until it is resumed) or archived (retired in the app: it answers no calls, and lists leave it out unless you ask for status=archived).