Candidates and promotion

Candidate is not active

A training run that passes protected tests becomes a candidate. The reference remains authoritative. This gives you time to review its immutable evaluation evidence and observe it on fresh inputs.

const inspection = relevance.inspect();
const candidate = inspection.trainingRuns.find(
  (run) => run.status === "candidate",
);

Shadow evidence

While a candidate exists, every new authoritative result recorded through classify() or logClassification() is queued for candidate inference. SwapAI persists the comparison against that exact candidate without returning its prediction to the caller.

await relevance.classify(freshInput);
await relevance.flush();

const shadow = relevance.inspect().latestTrainingRun?.shadow;

Shadow inspection reports the example count, mean error, pass state, inference-failure count, last failure and last evaluation time. Promotion requires at least one fresh shadow sample, mean error at or below acceptableError, and zero shadow inference failures. A candidate with no fresh observations cannot be promoted.

Review at least:

• total protected error;
• error by result bin and decision boundary;
• collected coverage for each declared facet value;
• failed classifications and malformed outputs;
• dataset revision and artifact SHA-256;
• provider cost, runtime and cleanup result.

SwapAI never returns an unpromoted candidate's answer and shadow results never cause automatic promotion.

Promote one run

await relevance.promoteCandidate(candidate.id);

Promotion names a training run, not "the latest model". SwapAI rechecks that the candidate still belongs to the current dataset revision, its complete artifact matches the stored digest, its protected evaluation passed and its fresh shadow evidence passes the configured error threshold without inference failures.

After promotion, isTrained() becomes true and classify() can use the accepted model. A different candidate cannot become active by appearing in the artifacts directory.

Reject or replace

Do not promote evidence you do not trust. Keep collecting and request another immutable training run. Historical candidates and their evidence remain inspectable until training data is erased under the erasure policy.

Application rollback

Applications should retain a reference fallback. A model-load or inference failure does not turn into an unverified local answer: SwapAI reports the failure and uses the configured reference when available.