Module bandit 

UCB1 start-rung bandit: predict-to-start, verify-to-serve.

Science

Every request currently starts the escalation ladder at rung 0 (cheapest model). Many contexts (task kind × prompt-size bucket) have a learned empirical pass rate per rung: if rung 0 almost never passes for a given context, always starting there wastes money. This module learns a per-context start rung that minimises expected cost while the enforce gate still verifies the chosen rung’s output before serving.

The invariant (predict-to-start, verify-to-serve): the bandit only controls where the ladder starts. Gating, escalation, budget, and speculation are untouched. If the predicted start rung’s output fails the gate, the ladder continues upward as normal — no downward retry. Prediction errors can cost money (latency, slightly higher expected cost when the estimate is wrong) but can never cause a wrong answer to be served.

Algorithm

UCB1 (Auer et al. 2002) applied to cost-sensitive start-rung selection. For each candidate start s, the expected cost is:

E[s] = Σ_{r=s}^{top-1}  price_r · P(reach r | start s)
P(reach r | start s) = Π_{q=s}^{r-1} (1 − p̂_q)
p̂_q = clamp(successes_q / n_q  +  c · √(ln N / n_q),  0, 1)

where N is the total gate-verdict observations in this context, n_q is the observations at rung q, and c is the exploration constant (default 1.0). Prices are evaluated at nominal fixed tokens (1 000 in / 500 out) — relative prices are what matters for start-rung comparison. Tie → lower s (conservative).

Cold-start safety: if the context has fewer than min_observations total gate verdicts, the bandit returns rung 0 (byte-identical to today’s behavior). Abstain verdicts are not counted (only clear Pass/Fail gate outcomes are informative).

State

ponytail: in-memory Mutex, per-process. Survives restarts via warm-start replay of the trace store at startup. No persistence of its own — the trace store is the durable record.

Structs

ContextBucket

The context bucket that keys the bandit’s per-arm statistics.

StartRungBandit

Online UCB1 bandit for start-rung selection.

Enums

Algorithm