draft, runs in shadow mode against production traffic to validate its predictive power without affecting business decisions, gets promoted to challenger to take a slice of real traffic via the champion-challenger split, and finally replaces the active model as the new champion.
Lifecycle states
Allowed transitions
400 Bad Request with code = "invalid_transition". Promoting a candidate to champion automatically demotes the prior champion in the same family to archived in the same database transaction.
POST /api/v1/algorithm-models//promote
Change a model’s lifecycle status. The endpoint enforces transition legality, the “one champion per family” invariant, the auto-rollback guard (W6.2), and records the change in the audit trail.Path parameters
Request body
The
family is not accepted in the request body — the endpoint derives it from the model’s stored registryFamily (falling back to the model name). The “one champion per (tenantId, family)” invariant still applies; you cannot override the family at promotion time here.actor recorded in the audit trail is taken from the x-user-id request header (defaults to "system"), not from the body.
Response 200
Error codes
GET /api/v1/algorithm-models/resolve-lifecycle
Returns the active champion + challengers + shadow models for the tenant, optionally scoped byfamily. The UI uses this to materialize a Score node config in one click.
Query parameters
Response 200
warnings contains soft-validation messages — e.g., when more than one champion exists for a family (a hard invariant violation that promoteModel prevents going forward, but legacy data may still trip it).
Shadow scoring
When a Score node config hasshadowModelKeys set (or models with registryStatus = "shadow" are wired in via the UI’s “Apply lifecycle to flow” action), every shadow model also scores each candidate alongside the active model. Shadow scores are recorded under scoringResults[].shadowScores in the decision trace and never affect ranking, candidate.score, or business outcomes.
In shadow mode, a candidate model receives production traffic for evaluation purposes only — its scores are recorded but never affect business outcomes. Promotion to challenger or champion happens after the operator is satisfied with the candidate’s performance.
Trace shape
experimentAssignment.variant records which model actually drove the decision (champion or one of the challengers). shadowScores records what the shadow models would have scored — useful for offline AUC comparison before promotion.
Untrained model behavior
For Bayesian and logistic-regression model types, the propensity for every (action, customer) pair starts at 0.5 (a coin flip) until the model has accumulated enough labelled outcomes to differentiate. The 0.5 prior is the standard Bayesian non-informative starting point — without observed outcomes the model has no signal to predict from, so every action gets the same neutral propensity until evidence accumulates. Kaireon tracks evidence per-offer in the model’s interaction-count state and applies hierarchical fallback (offer → category → channel → global priors) via stored adaptations once the evidence threshold is met. Until then the 0.5 prior is intentional, not a bug.Roles
admin, editor for promote / resolve-lifecycle. viewer is allowed for resolve-lifecycle (read-only).