> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Decisioning Autopilot

> A governed closed loop that turns experiment results and model drift into reviewable — or automatically applied — configuration changes.

## Overview

The Decisioning Autopilot watches your experiments and models in the background and proposes concrete configuration changes. Every proposal lands in the **Recommendation Inbox** (AI > Insights) as an `AiRecommendation`; what happens next is controlled by a per-tenant **autonomy mode**.

The decision path itself stays fully deterministic — the Autopilot only tunes *configuration*, through the same review and audit machinery a human would use.

## What it proposes

The Autopilot sweep runs every 6 hours (`GET /api/v1/cron/ai-autopilot`, CRON\_SECRET-gated, registered in the in-process maintenance scheduler). Per tenant it produces two kinds of proposals:

| Proposal                                    | Source                                                                   | Trigger                                                                                                                                                                                                        |
| ------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Promote challenger** (`type: experiment`) | `evaluateAutoPromote()` over active experiments with `autoPromote: true` | Challenger beats the champion with statistical significance: AUC improvement ≥ `promoteThreshold`, Bonferroni-corrected p-value, ≥ 5% relative lift, ≥ 100 samples per variant, and `promoteAfterDays` elapsed |
| **Retrain model** (`type: model`)           | `detectModelDrift()` over active models                                  | Drift severity `significant` (AUC dropped > 0.1 from peak)                                                                                                                                                     |

Proposals are deduplicated: a re-run never creates a second open recommendation with the same type and title.

## Autonomy modes

Configured in **Settings > AI Configuration > AI Autonomy** (stored on `tenant_settings.aiAutopilot`, editable via `PUT /api/v1/tenant-settings` with `{"aiAutopilot": {"mode": "..."}}`):

| Mode                | Behavior                                                                                                                                                              |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `suggest` (default) | Proposals wait in the Recommendation Inbox for an admin to Apply or Dismiss.                                                                                          |
| `auto_gated`        | Additionally opens an **Approval Request** per proposal (`entityType: ai_recommendation`, requester `autopilot`). Four-eyes reviewers see it in Settings > Approvals. |
| `auto`              | Applies each proposal immediately through the shared apply executor. Every application is audit-logged (`ai_recommendation` / `autopilot: true`).                     |

## Applying a proposal

Whether applied by hand or by the Autopilot, all applications flow through the same executor:

* `experiment` — flips `championModelId` on the (tenant-scoped) experiment and sets it active — the same operation as the `playbook_promote_challenger_if_winning` playbook.
* `model` with `action: retrain` — runs the shared retrain-and-persist path (same as `POST /api/v1/algorithm-models/[id]/train`): version snapshot, metrics history, model update.
* `model` with `action: pause` — sets the model status to `paused`.
* `weights` — updates a ranking profile's weights and bumps its version.

A failed application returns an error and the recommendation stays open — a recommendation is never marked `applied` unless the change actually happened.

## Relationship to scheduled retrains

The existing `scheduled-retrains` cron (auto-retrain on `autoLearn` models) is unchanged. The Autopilot adds *drift-triggered* retrain proposals and the experiment promotion loop on top — the promotion evaluator (`evaluateAutoPromote`) previously existed as configuration only, with nothing running it.