Skip to content

solvi.experimental.stream

StreamPromise: an anytime-valid learn-then-test certificate on a threshold grid, earned on the stream (stages 1–2 of 4): one e-process per grid point (a mixture of constant bets, or the aGRAPA bet), fixed-sequence from strict to loose, the threshold only loosens, a missing label counted as a loss; DeltaBudget spends δ over restarts (δ_v = 6δ/(π²v²)). Installed with System.guarantee(question, promise=sp); RiskDetector and the calibration coin (sampling) run inside Dispatcher(audit="adaptive", promise=sp, detector=det); tickets (stage 3a) makes an agent the oracle over MCP — TicketDesk, AgentOracle, solvi serve --mcp --agent-oracle; versions (stage 3b) is the closed learning loop — LearningLoop over a learner (HashedTextLearner, FastHeadLearner). Measured once, with documented limits (see experimental).

solvi.experimental.stream — a promise earned on the stream (experimental; stages 1–3b: the certificate, its detector, the sampling inside the Dispatcher, the agent as the oracle and the closed learning loop).

from solvi.experimental.stream import StreamPromise, DeltaBudget

sp = StreamPromise(max_risk=0.05, delta=0.05)            # joint: P(answered alone and wrong) ≤ 5 %
system.guarantee("intent", promise=sp, signal="act")      # installed as OpenSetGate is; +inf until certified
# Only for a coin independent of the current input and label:
sp.learn(score, would_be_answer, label, sampling_policy="uniform")                   # one labelled sample (label None: missing, a loss)
sp.threshold                                              # the loosest certified grid point (only loosens)
sp.restart("alarm")                                       # uncertified again; next (v, δ_v) at its first sample

An anytime-valid learn-then-test certificate on a threshold grid: one e-process per grid point (a mixture of constant bets, or bets="agrapa" — experimental._evalue.MeanBound mirrored), fixed-sequence over the grid from strict to loose, δ spent over restarts by DeltaBudget (δ_v = experimental.skills.Certificate.delta_at(v)). See stream.certificate for the statement and what is recorded. Clean samples a fresh certificate needs at α = δ = 5 %: 85 (v = 1), 116 (v = 2), 134 (v = 3); 74 for the mixture at the full δ, against 59 for a one-shot binomial test — a floor on labels, not the useful cost metric: the first threshold in force is the strictest certified grid point (how strict is distribution-dependent), so price a coverage-vs-labels curve, not n to the first certification (clean_need).

Stage 2: RiskDetector (a Shiryaev–Roberts e-detector on the deployed risk, stream.detector) and the calibration coin and rate (stream.sampling), run by Dispatcher(audit="adaptive", promise=sp, detector=det, on_drift="recertify", probation=300, secret=key): the coin draws the samples, the slow path labels them, an alarm restarts the certificate and opens probation, every decision records its state and Dispatcher.replay_stream() rebuilds it. The default grid="auto" costs the first grid_from (200) labels — dropped, and under a Dispatcher each paid for as an escalated slow-path call; grid="fixed" for scores already on [0, 1]. Standalone, the caller still draws the samples and calls learn and restart.

Stage 3a: stream.tickets — an agent outside the process as the oracle (AgentOracle, TicketDesk; solvi serve --mcp --agent-oracle): blind tickets, durable in the store, an expired ticket a recorded loss.

Stage 3b: stream.versions.LearningLoop — a live learner (stream.learner: HashedTextLearner, FastHeadLearner) takes the oracle's labels; frozen versions, each with its own StreamPromise calibrated only on samples drawn after its freeze and δ from one DeltaBudget, are promoted when certified and answering alone on ≥ min_share (5 %) of the same samples and ≥ the served version's share + margin (1 point); version 0 may be the fitted System 1 (initial=), a RiskDetector with probation watches the served version, a resolved ticket's verdict is a label (ticket_verdict); every freeze / promote / discard / alarm is in the chain and replay() rebuilds which version served each decision. The gain is unproven; stage 4's stand measures it.

The adapter (LoRA) loop, stage 1: stream.policy — LoopPolicy (the abstract class whose hooks decide what the loop takes, when it trains, what it freezes, promotes, discards and does on an alarm), LoopState (what a hook reads), Budget, and DefaultPolicy; stream.gates — the content-key split and the gate arithmetic.

Stage 2: stream.loop.AdapterLoop — the lane's loop driven by a LoopPolicy: train / calib / holdout labels by content key, online (snapshot) or batch (train(job), TrainJob) learners — HashedTextTrainer is the stand-in batch learner —, the pre-freeze report on held-out labels, promotion on novel samples only (keys the candidate never trained on) with the memorisation probe, two alarm sources (the RiskDetector OR-ed with a score monitor, never the detector alone), controls (pause / resume / train_now / promote / rollback / versions / status); stream.serving — Served, HeadVersion, BaseVersion. LearningLoop is AdapterLoop with DefaultPolicy at the lane's constants (lane_policy).

Stage 3: stream.lora_learner — LoraLearner (a batch learner: a LoRA adapter trained from the base checkpoint for each version, act_guard on the calib labels) and LoraVersion (an adapter with its calibration: scored in shadow, installed with solvi.experimental.lora.swap, which changes the adapter and its thresholds together); stream.runner — where a training runs: SubprocessRunner (the default: nice, capped threads, the device picked with a CPU fallback, the time estimate against max_train_s, a heartbeat log, the result file) and ThreadRunner. Stage 3b: a training runs in the background and its result is applied on a later decision, at a recorded position (deferred apply); close() cancels it; Budget.max_versions_kept evicts old retired versions. Stage 4: stream.checkpoint — AdapterLoop.save(dir) / AdapterLoop.load(dir, learner, ...), the loop's whole state (versions and their files, promises and the detector through dump / restore, policy, budget, the label store, the records) in a signed, hashed, atomically switched folder. Stage 5: AdapterLoop.attach(dispatcher_or_system, learner, ...) — the loop on a Dispatcher (stream mode: every decision through it, the version recorded per decision, replay_all under each decision's version) or a System alone (label mode: teach / outcome labels, the pre-freeze gates only); detach().

Unmeasured: no stand has run yet.

DeltaBudget

DeltaBudget(delta: float = 0.05, schedule: str = 'basel', *, horizon: int | None = None)

schedule="horizon", horizon=T spends delta/T for each of T allocations, then refuses more. Reserve an allocation before seeing its test outcomes. No refund on failure or expiry.

δ spent over the certifications of one promise (one budget per promise; a detector and the versions of the same promise share it). schedule="basel": δ_v = 6δ/(π²v²) (Certificate.delta_at), Σ_v δ_v = δ, so every certification ever made holds together with probability ≥ 1 − δ. next() → (v, δ_v) and moves the index; v is the index last handed out (0 before the first).

spent property

spent: float

Σ δ_u over the indices handed out so far.

next

next() -> tuple

The next certification's index and δ: (v, δ_v).

MirrorBound

MirrorBound(alpha: float, c: float = 0.75)

MeanBound(m = 1 − alpha) fed x = 1 − loss: the aGRAPA bet, certifying "the mean loss is below alpha".

dump

dump() -> dict

The aGRAPA bet's state (log evidence, count, its predictable estimates): restore() gives it back exactly.

Mixture

Mixture(alpha: float, fractions=FRACTIONS, weights=WEIGHTS)

A mixture of constant bets against "the mean loss is at least alpha". update(loss) with loss in [0, 1].

update

update(loss: float) -> float

One loss in [0, 1] → the log wealth of the mixture after it.

dump

dump() -> dict

The process's state (its log wealths and count): restore() on a Mixture of the same alpha, fractions and weights gives it back exactly.

StreamPromise

StreamPromise(max_risk=None, max_error=None, delta=None, *, kind=None, grid='auto', grid_from=200, grid_size=32, bets='mixture', fractions=FRACTIONS, weights=WEIGHTS, c=0.75, budget=None, procedure='fixed')

See the module docstring. The Promise interface (method "stream-ltt", level, delta, threshold, nodes=None, report, promise, stateful, allows, threshold_of, record, fingerprint), so System.guarantee(question, promise=sp) installs it as it installs OpenSetGate: every gated decision is observed (no label), its state recorded with the guard record, and a replay takes the recorded threshold. Labels come in through learn (one labelled sample: the sampling and the oracle are the caller's — a later stage wires them into the Dispatcher). Groups are not supported.

level_now property

level_now

The log-wealth a point needs under the current index (None before the first bet: no δ_v yet).

peak_at

peak_at()

The sample count (n) at which the first uncertified grid point's log-wealth last set a new running maximum (0: never above its start), or None (no grid yet, or every point certified).

certified_at

certified_at(lam) -> bool

Whether the grid point lam is certified (False for a value that is not a grid point, or before the grid).

log_wealth_at

log_wealth_at(lam)

The log-wealth of grid point lam's e-process now (None: not a grid point, or no grid yet).

prime_grid

prime_grid(scores, *, source)

Fix a fresh auto grid from bounded past scores, without labels, bets or a delta charge.

Past scores need not come from the future model: their scale affects utility, not validity of the fixed future grid. No past labels, wealth or certification evidence are imported.

observe

observe(signal, result=None) -> dict

One gated decision (no label): counted, and its score read for the auto grid until it is fixed.

learn

learn(signal, answer, label, floor=None, *, sampling_policy) -> dict

One labelled sample: the decision's score, the answer it would give alone, its label (None: missing — a loss wherever it would have been answered alone). Before the grid is fixed the sample is not read (dropped). floor: grid points below it do not bet on this sample (no wealth or peak change; n counts the sample once) — an additive layer relearning on the rows it owns ({score ≥ Λ}), a biased sample of its zone below Λ.

sampling_policy declares how the caller selected this sample: "uniform" means a coin independent of the current input and label (its rate may depend on the past); "complete" means every decision is labelled. Known "input_dependent" sampling is refused: this unweighted certificate does not implement IPW or DR. The required declaration checks caller intent only; it does NOT detect a hidden slice-dependent coin; the certificate's guarantee still requires the declared sampling assumption to hold. Dispatcher already enforces an input-independent coin and a rate determined from the past in its own sampling path. Invalid declarations are refused before any state change or delta-budget charge.

restart

restart(why=None) -> tuple

A new certification from scratch (an alarm, a person's call): every point uncertified, wealth 1, the threshold +inf; the grid is kept (it was read without labels). Its (v, δ_v) is taken lazily, at its first bet, so this returns (None, None); a restart that never bets spends nothing.

stream_driver

stream_driver(detector=None, **kw)

The per-decision step a Dispatcher runs for this promise (sampling.StreamDriver): how Dispatcher(promise=sp, detector=, audit="adaptive") reaches the experimental code without importing it.

dump

dump() -> dict

Everything a restore needs (JSON data): the configuration's fingerprint, (v, δ_v), the grid (or the scores buffered for the auto grid), the counters, the threshold, each grid point's e-process and certified flag, the event list, and the state's evidence_fp, which restore checks. The budget is not in it: it is the caller's (one DeltaBudget over every version of a loop).

restore

restore(d) -> 'StreamPromise'

The state of dump() on this promise (built with the same configuration; its budget is left as it is) → self. A dump of another configuration, or one whose evidence does not give back its evidence_fp, is refused (ValueError).

RiskDetector

RiskDetector(alpha: float = 0.05, arl: float = 1000.0, scales=SCALES, alternatives=None)

See the module docstring. alpha: the promised rate; arl: the alarm level A (E[run to a false alarm] ≥ A); scales: the bet fractions c_j (λ_j = c_j/α0, each in (0, 1)); alternatives: None (null at α) or rates ≥ 1 (null at min(alternatives)·α).

statistic property

statistic: float

mean_j R_j.

update

update(loss: float) -> bool

One deployed loss in [0, 1] → True when this sample raises the alarm (the flag stays up until reset()).

observe

observe(decision, label=None, question=None) -> dict

A labelled decision → {"drift", "why", "R", "n"}. decision: a dict {"answer", "alone", "label"}, a Dispatched (alone: by "s1"), or anything with .answer and .status ("ok": answered alone). Without a label: ignored.

reset

reset() -> None

Start again: R_j = 0, no flag (the alarm count is kept).

dump

dump() -> dict

The statistic's state (JSON data): the configuration (config(), its fingerprint) and R_j, n, the alarm flag and count. restore() on a detector of the same configuration gives it back exactly.

restore

restore(d) -> 'RiskDetector'

→ self, in the state of dump(); a dump of another configuration is refused (ValueError).

config

config() -> dict

The constructor's arguments: RiskDetector(**det.config()) is a detector of the same configuration.

Budget dataclass

Budget(max_trainings: int | None = None, per_day: int = 24, min_interval_s: float = 600.0, max_train_s: float = 1800.0, cpu_threads: int = 4, device: str = 'auto', free_gpu_mb: int = 3000, max_examples: int = 20000, max_versions_kept: int = 10)

What trainings may cost. max_trainings: over the loop's life (None: no cap); per_day: trainings per 24 h; min_interval_s: between two trainings; max_train_s: one training (estimated before it starts; refused if above; the runner stops a training at its estimate + the runner's grace_s, which must cover what the estimate leaves out: loading the checkpoint, calibration and saving); cpu_threads: torch threads of the runner on a CPU; device: "auto" (cuda when present and ≥ free_gpu_mb free, else cpu), "cpu", "cuda" or "cuda:"; max_examples: rows per training; max_versions_kept: soft retention target for served/retired version-table rows (version 0 counted), not a memory cap. Eligible oldest retired rows are released; their files remain. Version 0, current served and rollback target are protected, so three protected rows may exceed a smaller target. Additive layers are excluded and bounded separately by max_layers (base included); a resident candidate is excluded too. status()["resident_versions"] inventories version-table model references across states, not bytes or unique model/tensor storage. per_day=0 or max_trainings=0 means "never train"; max_trainings counts failed trainings too.

refuse

refuse(started, now: float, estimate_s: float | None = None) -> str | None

Why a training may not start now, or None. started: the wall-clock start times of the trainings so far; estimate_s: the estimated seconds of this one (None: not estimated yet). per_day is a rolling 24 h window (now − t < 86 400 s), no calendar day, no time zone. A start time after now (a clock set back, a checkpoint restored on another machine) counts towards max_trainings but not the window or the interval.

DefaultPolicy

DefaultPolicy(budget: Budget | None = None, *, s2_labels: bool = False, calib: float = 0.15, holdout: float = 0.15, first: int = 300, growth: float = 1.5, window: int = 200, target_share=0.5, min_gain: float = 0.01, min_holdout: int = 100, tolerance: float = 0.02, wilson: float = 0.95, min_novel: int = 100, min_share: float = 0.05, margin: float = 0.01, gap: float = 0.1, probe_min: int = 30, stale: int = 3000, trial: int = 3000, probation: int = 300, r: int = 8, lr: float = 0.0003, min_updates: int = 200, max_updates: int = 3000, refreeze=None, probe: bool = True, pre_freeze: bool = True, novel_risk: bool = True, min_calib: int | None = None, watch: bool = True, watch_min: int = 100, novel_only: bool = True, mature_patience='auto', backlog_max: int | None = None, acquisition: dict | None = None)

Bases: LoopPolicy

See the module docstring for each hook. budget: a Budget (None: the defaults); s2_labels: take slow-path labels; calib / holdout: the split's shares; first, growth: the train labels before the first / a next training (absolute, × the served version's n_train); window, target_share: the improvement signal (target_share 0.5: also short when it answers alone on less than half its held-out labels; None: the error-only signal); min_gain, min_holdout, tolerance: the pre-freeze gates; wilson: the confidence of the Wilson bounds (label mode's paired gain, the probe's discard test); min_novel, min_share, margin: the promotion rule; gap, probe_min: the memorisation probe; stale, trial: the decisions after its freeze at which a candidate not certified / certified and not promotable is discarded (decisions, not coin samples); probation: two alarms closer than this roll back (0: never); r, lr, min_updates, max_updates: the training's settings; refreeze: the lane LearningLoop's retrain floor instead of the largest n_train (None: off); probe: the memorisation probe on (False: off, promotion and discard); pre_freeze: the pre-freeze gates on (False: every training is frozen); min_calib: the calib labels a training waits for (None: the fewest the calib threshold needs at α, 73 at α = 0.05; 0 for a learner with its own threshold); novel_risk: promotion needs the Wilson upper bound (at wilson) of wrong_novel / n_novel ≤ α (False: off); watch, watch_min: label mode's watch after a promotion (False: off; the labels it needs before it may roll back); novel_only: the promotion's paired comparison counts only samples on keys the candidate never trained on (False: every sample, its train keys too — for controls; weakens the guarantee: a memoriser's trained items then count for it). In label mode pre_freeze=False is refused by the loop: there the pre-freeze gates are the only measurement before a version is served. mature_patience, backlog_max: the maturity gate (see the module docstring).

acquisition_status

acquisition_status() -> dict | None

Conservative worst-case extra oracle reservations; refused/duplicate labels still cost a reservation.

why_not_train

why_not_train(st) -> str | None

First currently blocking gate, or None when want_train says yes.

Not an ETA or a complete list: fixing this blocker may expose the next. Labels are accepted outcomes, not decision counts; distinct-key floors and observed acquisition rates determine how slowly the gate can be reached.

maturity_gate

maturity_gate(st) -> dict | None

The maturity gate on st (see the module docstring): None when off (mature_patience None, "auto" in replacement mode, label mode, no gated promise), else its inputs and trigger — "mature", "alarm" (override A), "backlog" (override B) or None (closed: no training).

calib_floor

calib_floor(alpha) -> int

The calib labels a freeze needs: min_calib, or (None) gates.calib_min(alpha, wilson), the fewest with which the calib threshold can exist (0: the learner brings its own threshold).

select

select(st, rows) -> list

One row per content key — a relabelled input keeps only its latest label (by t; on a tie the later row) — then the class-balanced, half-recent sample (see the module docstring).

hyper

hyper(st) -> dict

updates from the train label count capped at max_examples — an approximation of the rows select returns (it does not see them, and a relabelled key counts once there). Seeded by the next version number: a retry after a failed training is the same training (deterministic on purpose).

freeze_gates

freeze_gates(st, report: TrainReport) -> dict

Each pre-freeze gate's result → {"heldout", "act_guard", "honesty", "time"[, "paired_gain"]}, each with "ok" and "why".

promote_checks

promote_checks(st, paired: Paired) -> dict

Each promotion condition → {"certified", "novel", "min_share", "margin", "novel_risk", "probe"}, each with "ok" (novel_risk / probe only when on). The probe passes only with ≥ probe_min alone answers on novel samples (an unmeasured novel side does not promote). Additive mode (st.layers set): the additive gate (decision D1) — certified, novel, novel_risk, probe; no min_share and no margin (nothing to compare with: a layer serves only the zone the layer above escalates); with the loop's usefulness certificate on (st.useful_error set) a fifth check, "useful": the candidate's usefulness certificate (selective error among its alone answers ≤ β, anytime-valid on its own δ budget) holds at its certificate's threshold in force λ_J — a layer whose alone answers are not shown to be right more often than β allows never starts serving.

watch

watch(st, w) -> bool

Label mode: watch_rollback(w, min_n=watch_min, confidence=wilson, min_gain=min_gain) (the e-process at level 1 − wilson); never with watch=False.

rollback_target

rollback_target(st) -> int | None

The highest retired version below the served one with no alarm on record, or None. Conservative: any alarm on record excludes a version, also one on an earlier serving that was recertified and then served well.

LabelRow dataclass

LabelRow(key: str, x: Any, y: Any, source: str, t: int)

One stored label: the input's content key, the input, the label, its source, the decision it came at.

LoopPolicy

LoopPolicy(budget: Budget | None = None)

Bases: ABC

See the module docstring. Subclass and give every hook; budget (a Budget) is read by the loop too.

budget property writable

budget: Budget

The Budget (the defaults when none was set, also for a subclass whose init skips super().init).

sampling_rate

sampling_rate(st: LoopState, base_rate: float) -> float

Predictable uniform coin rate from past state only; legacy default unchanged.

accept abstractmethod

accept(st: LoopState, x, y, source: str) -> bool

Take this label at all.

split abstractmethod

split(st: LoopState, key: str) -> str

"train" | "calib" | "holdout" for a content key; the same key must always get the same split.

want_train abstractmethod

want_train(st: LoopState) -> bool

Ask for a training now.

select abstractmethod

select(st: LoopState, rows) -> list

The train rows (LabelRow) that go into this training.

hyper abstractmethod

hyper(st: LoopState) -> dict

The training's settings: r, lr, updates, seed, ...

freeze abstractmethod

freeze(st: LoopState, report: TrainReport) -> bool

Freeze the trained model as the candidate (the pre-freeze gates on labels it never trained on). In label mode this is the only measurement before a version is served (the candidate is promoted on the next label, and only the watch after it can roll it back): a freeze that measures nothing serves every training.

promote abstractmethod

promote(st: LoopState, paired: Paired | None) -> bool

Serve the candidate now (paired None in label mode; in stream mode a candidate with no sample yet gets Paired(0, 0, 0, 0), not None).

discard abstractmethod

discard(st: LoopState, paired: Paired | None) -> str | None

Why the candidate is discarded now, or None to keep trialling (paired as for promote).

alarm abstractmethod

alarm(st: LoopState, who: str, report: dict) -> str

An alarm on the served version (who: "detector" or "monitor") → "recertify", "rollback:" or "ignore".

watch

watch(st: LoopState, w: Watch) -> bool

Label mode: roll the served version back to w.target now? Called on each calib or held-out label while a watch runs (from a promotion to the next change of the served version). This default returns False: a custom policy has no automatic rollback unless it defines this hook (e.g. return watch_rollback(w), the DefaultPolicy rule). The loop keeps the watch's counts either way (`status()["watch"]).

LoopState dataclass

LoopState(n: int = 0, served: int = 0, candidate: int | None = None, labels: dict = (lambda: {s: 0 for s in gates.SPLITS})(), versions: tuple = (VersionInfo(0, 'served'),), holdout: tuple = (), alpha: float = 0.05, alarms: tuple = (), served_history: tuple = (0,), served_since: int = 0, trainings: tuple = (), job: dict | None = None, now: float = 0.0, paused: bool = False, mode: str = 'stream', promises: dict = dict(), detector: dict | None = None, keys: dict | None = None, layers: tuple | None = None, deepest: int | None = None, deepest_certified: bool | None = None, zone_share: dict | None = None, maturity: dict | None = None, useful_error: float | None = None)

What a hook sees, rebuilt by the loop for every call (changing it changes nothing in the loop). n: decisions so far; served / candidate: version numbers (candidate None: none in trial; since_freeze: the decisions since the candidate's freeze); labels: label counts by split; versions: the versions table; holdout: the served version's [(alone, wrong)] on its latest held-out labels, oldest first; alpha: the promised level; alarms: [{"n", "who", "version"}] so far; served_history: the versions served, in order (a rollback appends); served_since: the decision at which the current serving of served began (a promotion or a rollback sets it); trainings: the wall-clock start times of the trainings so far; job: the training in flight ({"id", "started", "eta"}) or None; now: the wall clock; paused; mode: "stream" (a Dispatcher, the stream promise) or "label" (a System alone: the pre-freeze gates only); promises, detector: their state dumps, for a policy that reads them; keys: the distinct content keys with a label, by split (a relabelled key counts once, as the pre-freeze report's latest label per key; None: a state built without them, labels stands in). maturity: the inputs of DefaultPolicy.maturity_gate — version (the deepest layer in additive mode, else the served version), samples (its promise's samples read), changed_at (the samples at its latest "certified" / "loosened" event since its latest restart; None: none), peak_at (StreamPromise.peak_at), last_freeze (the decision of the latest training's freeze or birth discard, 0: none), labels_since_freeze (accepted labels after it), alarm (an alarm on that version after it); None in label mode or when that version has no promise.

stream.loop.AdapterLoop passes copies of the dict fields and resets holdout at a promotion or a rollback (the new served version does not inherit the old one's errors). The state has dict fields, so hash(st) raises: do not use states as keys.

since_freeze property

since_freeze: int | None

Decisions since the candidate was frozen: n − its frozen_at (None: no candidate, or a candidate row built without frozen_at). DefaultPolicy's stale / trial clocks read it.

Paired dataclass

Paired(n_novel: int, alone_novel: int, wrong_novel: int, alone_served: int, n_seen: int = 0, alone_seen: int = 0, wrong_seen: int = 0, wrong_served: int = 0, alone_served_own: int | None = None, wrong_served_own: int | None = None, thr_s: str | None = None)

The candidate against the served version on the candidate's post-freeze samples (stream mode). Novel: samples whose key is not in the candidate's train_keys — n_novel of them, alone_novel / wrong_novel the candidate's answers alone / alone and wrong there, alone_served / wrong_served the served version's on the same novel samples at the threshold of its comparison certificate (1.4.0: a StreamPromise built on exactly the candidate's samples with the same grid rule and the candidate's δ_v; it only ranks, it never serves) once that certificate is certified, and at the served version's own threshold while it is not (thr_s: "cmp", "own" or "no_model" — a served version without a model never answers alone), alone_served_own / wrong_served_own at the served version's own threshold in force now (the comparison before 1.4.0, kept for the records; None when not counted). Seen: the samples whose key it trained on — n_seen, the candidate's alone_seen / wrong_seen — read only by the memorisation probe. A candidate with no sample yet is Paired(0, 0, 0, 0), not None.

Exact-key identity: a paraphrase of a trained item counts as novel, and calib keys (the threshold was fitted on them) recur as novel — a small optimism on share_k.

share_s_own property

share_s_own: float | None

The served version's share alone at its own threshold (the old comparison); None when not counted.

TrainReport dataclass

TrainReport(n_holdout: int, right: int, wrong: int, served_right: int, served_wrong: int, better: int = 0, worse: int = 0, threshold: float | None = None, honesty_before: dict = dict(), honesty_after: dict = dict(), seconds: float = 0.0, n_train: int = 0, items: tuple = ())

What a training produced, scored on labels the candidate never trained on. n_holdout: held-out labels asked; right / wrong: the candidate's answers alone and right / wrong on them, served_right / served_wrong the served version's; better / worse: held-out labels where the candidate's item score (+1 alone and right, −1 alone and wrong, 0 escalated) beats / trails the served one's; threshold: act_guard's on the calib split (None: none found at the promised risk; in stage 2 a fixed-set stand-in, while the served version answers at its stream threshold, so the held-out comparison sets two kinds of threshold side by side); honesty_before / honesty_after: the served version's and the candidate's solvi.testing.honesty numbers on the held-out labels; seconds: the training's wall time; n_train: rows trained; items: optional per-label scores ((key, candidate score, served score), each +1 / −1 / 0) for a policy that runs its own paired test (McNemar, bootstrap); empty when the loop does not provide them.

VersionInfo dataclass

VersionInfo(version: int, state: str, n_train: int = 0, samples: int = 0, certified: bool = False, threshold: float = math.inf, fingerprint: str | None = None, frozen_at: int | None = None, train_keys: frozenset = frozenset(), discarded_at: int | None = None, layer: int | None = None, routing_thr: float | None = None, learning: bool | None = None, useful: bool | None = None, useful_at_answer: bool | None = None, useful_thr: float | None = None)

One row of the versions table. state: "served", "candidate", "retired", "discarded" or "evicted" (a retired version past Budget.max_versions_kept: released, no longer a rollback target); n_train: the train labels it was trained on (version 0: 0 unless stated); samples: post-freeze samples it has read; certified and threshold: its promise now; frozen_at: the decision it was frozen at (None for version 0); train_keys: the content keys it trained on, a set snapshotted at the freeze (not a digest: novel / seen is membership, key in train_keys, for every post-freeze sample; the learner's key list grows after the freeze and must not be read live). A list or set given is stored as a frozenset. discarded_at: the train labels the loop had when this version was discarded (None: not discarded) — the lane LearningLoop's refreeze floor reads it. Additive mode with the usefulness certificate on (AdapterLoop(useful_error=)): certified / threshold are the version's own certificate's (λ_J), useful whether the usefulness certificate holds at λ_J (the joint point, what the start gate's "useful" check reads), useful_at_answer whether it holds at the composed answer point useful_thr, the threshold it answers at (composed; +inf: no point certified by both).

Watch dataclass

Watch(target: int, n: int = 0, better: int = 0, worse: int = 0, total: int = 0, log_e: float = 0.0)

Label mode, after a promotion: the served version against the version served before it (target, the rollback target) on the same labels since the promotion — calib and held-out labels only (keys no version trained on). Each label scores each version +1 (answered alone and right at its own threshold), −1 (alone and wrong) or 0 (not alone). n: the labels compared; better: those where the target scored higher; worse: those where the served version scored higher; margin: Σ (target − served) / n (0.0 with n = 0). log_e: the log wealth of the watch's e-process (watch_eprocess(), a Mixture(0.5) fed loss 1 when the served version wins a discordant label and 0 when the target wins), 0.0 before the first discordant label.

FastHeadLearner

FastHeadLearner(options, features=None, *, min_fit: int = 20, facts=None, lam=None, refit=2.0, refit_until=2000)

See the module docstring. options: the answers; features: the facts the head may read (None: every key of the first rows); min_fit: labels kept before the first fit; facts: input → facts row (None: the input is the row); lam, refit, refit_until: as FastHead.

for_system classmethod

for_system(system, question, features=None, **kw)

A learner for a System's question: its options, and its facts from the init state (system.facts_for).

FrozenError

Bases: TypeError

A frozen model was asked to learn.

FrozenFast

FrozenFast(head, options, facts)

A frozen copy of a FastHeadLearner (None head: not fitted yet — it answers nothing, score -inf).

of_system classmethod

of_system(system, question)

The fitted answer head of a System's question, frozen (a copy) over the facts of its init state: version 0 of a LearningLoop that starts from System 1 (LearningLoop(initial=FrozenFast.of_system(system, q))).

as_head

as_head(feature=None, options=None)

This version as an answer head over the head's own facts (feature: unused, kept for one signature).

HashedTextLearner

HashedTextLearner(options=None, *, lr: float = 0.5, n_features: int = 2 ** 18, words=(1, 2), chars=(2, 5))

See the module docstring. options: the closed set of answers (None: open, a class per label seen); lr: the SGD step; n_features: hash buckets; words / chars: n-gram ranges.

options property

options

Closed answer vocabulary, or None when new labels are allowed.

HashedTextTrainer

HashedTextTrainer(options=None, *, lr: float = 0.5, n_features: int = 2 ** 18, words=(1, 2), chars=(2, 5), epochs: int = 1)

See the module docstring: a batch learner over HashedTextLearner. options, lr, n_features, words, chars: as HashedTextLearner; epochs: passes over the rows (job.hyper["epochs"] overrides).

options property

options

Closed answer vocabulary, or None when new labels are allowed.

TrainJob dataclass

TrainJob(id: str, version: int, rows: tuple = (), hyper: dict = dict(), trigger: str = 'schedule', started: float = 0.0, state: str = 'running', why: str | None = None, fingerprint: str | None = None, seconds: float = 0.0, frozen: bool | None = None, calib: tuple = (), budget: Any = None, alpha: float | None = None, status: dict | None = None, cancel: Any = None)

One training the adapter loop runs. id: "."; version: the version it would become; rows: the selected train rows (stream.policy.LabelRow; empty for an online learner, which freezes a snapshot); hyper: the policy's settings (r, lr, updates, seed, ...); trigger: "schedule" (the policy's want_train) or "train_now"; started: the wall clock; state: "running", "done", "failed", "refused" or "stale"; why: the refusal or the error; fingerprint and seconds: the frozen model's and the wall time, once done; frozen: whether the pre-freeze gates passed. What the loop also hands a batch learner (stage 3): calib — the calib labels (stream.policy.LabelRow, the latest per key; never trained on: the LoRA learner runs act_guard on them); budget — the policy's Budget (the runner's threads, device and max_train_s); alpha — the loop's promised rate; status — the dict the loop's status()["job"] shows, which a runner updates in place (pid, log, device, eta, last line); cancel — a threading.Event the loop sets when it drops the training (close, an error stop): a runner that takes cancel= stops it.

AdapterLoop

AdapterLoop(learner, *, question, policy=None, max_risk=None, max_error=None, delta=0.05, initial=None, detector=None, monitor='auto', probation=300, source='human', secret=None, seed=0, sampling=None, promise_options=None, storage=None, versions_dir=None, system=None, feature='text', key=None, served=None, clock=None, wait=False, part=None, mode='stream', warn_refused=200, trace_candidate=False, additive=True, max_layers=3, useful_error='auto', delta_use=None, alarm_cascade='layer', trial_serving='escalate', _detector_alone=False, _batch=None)

See the module docstring. learner: an online Learner (snapshot) or a batch one (train(job)); question: the question's name (in the coin, the content key and the records); policy: a LoopPolicy (None: DefaultPolicy()); max_risk= / max_error=, delta: each version's StreamPromise (promise_options: its other keywords); initial: version 0's frozen model (None: no model); detector: a RiskDetector on the served version; monitor: the score monitor ("auto": NumericDrift() when a detector is given, else none); probation: the decisions escalated after an alarm; source: the default source of the oracle's labels; secret, seed: the coin's key and run; sampling: {"floor", "budget", "window"} of the rate; storage: a TraceStorage for the records (None: kept in memory); versions_dir: where frozen versions are saved; system, feature: install the served version on a System (feature: the text fact a text model reads); key: input → content key (None: content_key); served: frozen → Served (None: as_served); clock: the wall clock (None: time.time); wait: True runs every training inside the step or the control (stage 3's blocking form); part: the part whose version lock the loop takes before its own (None: the learner's or initial's part) — from construction on, every decision of that part takes this RLock, whether or not a version is ever swapped; warn_refused: attached to a Dispatcher, after this many labelled decisions in a row whose label the policy refused (none accepted in between) a UserWarning says the loop learns nothing, once (None: never; the count is status()["labels"]["refused"]); trace_candidate: while a candidate is on trial, every decision's records carry its score and would-be answer ("candidate_score" in the stream record, "candidate_would" in the loop payload; the existing "shadow" is filled only where the protocol reads it) — for offline replays of promotion rules; the protocol never reads them (no behaviour change), it costs one candidate scoring per decision; the keys are absent with no candidate or with the option off (default).

additive (default True: additive coverage; additive=False runs the replacement protocol above, unchanged — it lost on the stand: worse than no loop by 11–16 points on 3 of 4 intent datasets, while additive coverage gained on 4 of 4): a candidate serves the escalation zone below the served chain instead of replacing it. The loop serves a chain of layers [L0, L1, …] (L0 = the served version); layer j has its live threshold λ_j (its promise's) and, when it is not the deepest, a frozen routing threshold Λ_j, frozen when the layer below it was attached; a decision walks j = 0, 1, … to the first layer it does not pass (score_j ≥ Λ_j, or the deepest) — its owner; the zones Z_j (the decisions that reach j) are fixed by the Λ. Answering (decision 21): outside a trial zone the first layer on the path, from L0 down, with score ≥ its live λ_j (the owner: ≥ _thr_owner) and not in probation answers alone — so an upstream layer whose λ loosened below its Λ answers inside a deeper zone where the deeper layer escalates; none → the oracle (never a layer deeper than the owner). Every layer keeps learning: certified and not in probation (the base regime), on the decisions of its whole zone whose coin is below the shared base rate; otherwise (the owned regime) on the decisions it owns, with no bet below its Λ. Attach (a freeze in additive mode): Λ_d := λ_d of the deepest layer d (d keeps learning), the candidate's zone is {score_d < Λ_d}; every zone decision is escalated (nobody answers there) and the candidate's promise learns on every one of them (no coin filter; a missing label counts as a loss), it is scored on zone decisions only and has no comparison certificate. A discard drops Λ_d ("unfreeze"). Layering (the policy's promote, DefaultPolicy's additive gate: certified, novel, novel_risk, probe — no share or margin comparison; or the promote() control): the certified candidate becomes the deepest layer from the next decision ("promote" with additive=True). max_layers: the chain's depth cap (base + layers); at the cap, and while the deepest layer is not certified, the schedule starts no training ("train_refused", once per reason) and train_now is refused at the cap. Drift: one RiskDetector per layer on its base-coin samples of its zone (did it answer, was it wrong), the score monitor on L0's scores; an alarm on layer j restarts only j's promise and puts only j in probation (it answers nowhere and relearns in the owned regime until it re-certifies); rollback(j) — a layer index — detaches the layers ≥ j ("detach"), layer j−1 becomes the deepest. Attached to a Dispatcher, a decision answered by a layer below L0 (or, escalated, owned by one) is decided by System 1 with that layer's version installed for the call (serving). alarm_cascade="downstream" explicitly declares that all later additive layers depend on each upstream routing identity/regime. A non-ignored alarm restarts those dependent certificates and probation too, and discards an active trial before its old-zone evidence can be reused. Frozen routing thresholds of retained layers remain fixed. Default "layer" preserves independent layer-local alarms. This is an observation-driven invalidation policy, not a guarantee of detecting hidden model changes. trial_serving="certified" (opt-in, additive stream only) lets existing certified non-probation layers answer inside a trial's fixed zone at their live thresholds. The candidate still never serves: its promise/usefulness and promotion samples read only the input-independent base coin there, at the recorded rho_base, including missing-label losses. Other escalation labels are not candidate samples. Default "escalate" labels every trial-zone decision. All evidence floors and delta levels stay unchanged; the opt-in can collect fewer samples. Needs stream mode and an initial model. Records: owner, layer, zone, path [[v, score, thr in force]], trial_zone, answered_by, answer_layer, answer_thr, base, rho_base in the stream record, every reached layer's answer in the payload's "path_would" — replay recomputes the routing and the answer from them; status() "zones" (per layer Λ, λ, regime, P̂(Z), realised risk; the composite stream-wide risk, reported). Checkpoint: checkpoint.FORMAT_ADDITIVE (v4) with the chain (a replacement loop uses checkpoint.FORMAT, v1). The guarantee is per zone, at level α (one δ budget over every layer and restart). Stream-wide nothing is ≤ α: with max_error= the error among the alone answers is bounded by α·(1 + Σ_{k≥1} P(overlap_k) / P(answered)) (overlap_k: rows layer k would answer that an upstream layer took — the upstream layer answers first), with max_risk= the joint risk by α·(1 + Σ_{j≥1} P(Z_j)); max_risk=α / max_layers keeps the joint one ≤ α (docs/experimental.md, "Additive coverage").

step

step(x, oracle=None, *, source=None, key=None) -> dict

One synchronous decision; an aborted attempt permanently stops optional acquisition.

label

label(x, y, *, source=None, key=None) -> dict

Label mode: one label (x, y) → as step (by "oracle"). The served version is scored on it (the held-out window), a train label reaches the learner, and the policy may start a training, freeze or promote here. An attached System calls it from teach / outcome.

attach classmethod

attach(host, learner=None, *, question=None, dir=None, policy=None, initial='auto', part=None, **kw) -> 'AdapterLoop'

Build a loop for question and attach it to host: a Dispatcher (stream mode: every decision of dispatcher.ask goes through the loop) or a System alone (label mode: the labels of teach / outcome are the loop's; no coin, no stream promise). learner: None — a LoraLearner on the question's model-backed decision part (needs torch and dir=); any Learner (online or batch) otherwise. initial: version 0's model ("auto": the learner's version0() when it has one, else none). part: the decision part (None: found from the question). dir: the loop's folder (the default learner's and versions_dir). The other keywords are the constructor's. Refused: a question answered by a combination (Cascade, Vote, Route) or by a part that is a member of one, a rule with no decision part when no learner is given, a Dispatcher with its own stream certificate.

attach_to

attach_to(host) -> 'AdapterLoop'

Attach this loop to a Dispatcher (stream mode) or a System (label mode) → self. The checks of attach; also refused: a loop already attached, closed or stopped, a host that has a loop (or, a System, an update target), a loop that serves on another System. Dispatcher(..., loop=) calls it.

detach

detach(*, by=None, why=None, timeout=30.0) -> dict | None

Take the loop off its host: a training in flight is cancelled, version 0 (the part as attached) is put back on the System when another version serves, the host's hook is removed and the loop is closed (its records, replay(), versions(), status() and save stay). → the "detach" event (None when not attached). Waits up to timeout seconds for the training's thread after releasing every lock; with wait=True a training in progress holds the locks (a Dispatcher's _learn_lock included) until it ends, so the detach — and the Dispatcher's decisions — wait for it first.

serving

serving(v)

Version v installed on the System for the duration (the Dispatcher's replay of a decision made under it), then the served version again. Holds the part's lock and the loop's for the whole block: the part's decisions and the loop's controls wait.

wait_training

wait_training(timeout=None) -> bool

Wait (outside every lock) until the training in flight has a result, or timeout seconds → whether it has one (True when none is in flight). It is applied on the next decision.

pause

pause(*, by=None, why=None) -> dict | None

No training, freezing or promotion until resume(); serving, labels and promises go on. → the event (None when already paused). The candidate's trial clock runs while paused: a discard by stale / trial still happens (its δ_v stays spent), as do alarms and rollbacks. A training in flight goes on; its result waits for resume() (applied on the first decision after it).

train_now

train_now(*, wait=None) -> TrainJob

One training now, whatever want_train says — within the budget, never while paused, with a candidate in trial or with a training in flight. → the TrainJob. wait (None: the loop's wait): False — a batch learner's training starts and the call returns at once (state "running"; its result is applied on a later decision, see step); an online learner's snapshot is a copy, always taken here (state "done"; the "train_start" event records the wait asked and inline=True); True — the call returns when the training is over and its result applied (state "done", "failed", "refused" or "stale" with why). A RunnerError stops the loop where the result is applied. A train_now refused (paused, a candidate in trial, a training in flight, the budget) writes its control event, a "train" with state "refused".

This control bypasses scheduling/label floors and the improvement signal, not the budget or post-training freeze/promotion gates. A manual run can therefore consume training time and a training-budget slot, then be discarded at birth for insufficient held-out/calibration data. Inspect policy.why_not_train(loop._state()) before overriding the schedule; manual training neither buys labels nor guarantees a frozen candidate.

close

close(*, timeout=30.0) -> dict | None

Stop the loop: a training in flight is cancelled (its runner stops it: a subprocess is killed, a thread runner stops waiting for its thread), step and every control refuse from here on; the served version stays installed. With wait=True a training runs inside a step or a control under the loop's locks, so a training in progress there ends first (a Dispatcher's decisions wait for it too: it holds _learn_lock). Waits up to timeout seconds for the training's thread, outside every lock. → the "close" event (None when already closed). Also with AdapterLoop(...) as loop:.

cancel_training

cancel_training(*, by=None, why=None) -> dict | None

Drop the training in flight (running, or its result waiting to be applied): its runner stops it, nothing is applied, nothing restarts it here; it stays counted against the budget. → the "cancel" event (None when no training is in flight). The policy may start another one on a later decision.

save

save(dir, *, cancel=False) -> dict

Save the loop's whole state to dir (see stream.checkpoint): written to a temporary folder, then switched in atomically, so a crash in the middle leaves the previous checkpoint usable. A training in flight refuses the save (RuntimeError) unless cancel=True, which cancels it first (cancel_training, a "cancel" event). → {"path", "manifest", "n", "files"}. Writes no record otherwise. The save holds the part's version lock and the loop's lock for all its writes (every version's files, each fsynced, included): the part's decisions and the loop's controls wait for it; unmeasured.

load classmethod

load(dir, learner, **kw) -> 'AdapterLoop'

The loop saved in dir, continuing where it was saved (see stream.checkpoint.load_loop for the keywords: system, storage, versions_dir, part, initial, key, served, clock, secret, groups, additive).

promote

promote(v=None, *, force=False, by=None, why=None) -> dict

Serve the candidate now: it must be certified; without force the policy's promote must agree (force skips the promotion rule, never the certificate); refused while paused. Attached to a Dispatcher, every control waits for the decision in flight (its slow path's call included). → the "promote" event.

rollback

rollback(v, *, by=None, why=None) -> dict

Additive mode: v is a layer index ≥ 1 — the layers ≥ v are detached ("detach"; see the class docstring). Otherwise: serve an earlier version again (its certificate and threshold as it left them, unless an alarm came after it retired: then its promise restarts → "restart"; version 0 without a model: nothing alone). A candidate in trial is discarded (its δ_v stays spent); waits for a Dispatcher's decision in flight → the "rollback" event.

replay_all

replay_all(*, rescore=False) -> dict

Alias of replay: check the complete recorded protocol log, including freeze/train controls.

This replays the loop's protocol, not an arbitrary external environment. With rescore=True the saved frozen models also recompute the recorded scores, under replay's existing versions_dir requirements.

replay

replay(rescore=False) -> dict

Re-run the protocol from the records and compare → {"ok", "mismatches": [(n, what, why)], "decisions", "versions"}. The policy is the one the loop was built with (a fresh copy), trainings take their recorded results, controls are re-applied at their recorded place.

status

status() -> dict

{"state", "error", "served", "candidate", "n", "labels": {"train", "calib", "holdout", "refused"}, "trainings", "budget": {...}, "job", "paused", "alarms", "mode", "attached", "guarantee", "watch", "delta_spent", "versions_kept", "resident_versions"} — and "zones" in additive mode (_zones: per layer version, layer, routing_thr Λ, threshold λ, certified, learning, probation, zone_share P̂(Z_v), owned_share, its counts and realised risk on its own coin samples; the chain's deepest, deepest_certified, zone_share, the composite stream-wide joint and selective risk — estimates, reported, not promised — beside the joint kind's bound α·(1 + Σ_{j≥1} P̂(Z_j))). labels: the accepted labels by split and "refused", the labels the policy refused on the attached path (each a missing label). watch: label mode after a promotion, the watch's counts {"target", "n", "better", "worse", "total", "lw"} ("lw": its e-process's log wealths; None otherwise). attached: "dispatcher", "system" or None. state: "detached", "closed", "error" (a hook raised: the loop stopped; error: {"n", "where", "why"}), "training", "paused" or "running". job: the training in flight — id, version, trigger, started (wall clock), started_at (its decision), inline, state ("running"; "ready": its result waits for the next decision), and what the runner fills in (runner, pid, log, device, eta, last, last_t: a heartbeat line's age says whether it is alive).

versions_kept counts served/retired rows only, with protected-row exceptions to the soft retention target. resident_versions is a list of {version, state} for every version-table row whose model is not None, including layers and a candidate. Rows may share model storage: this is a reference inventory, not bytes or unique objects/tensors, and excludes the live learner/runner.

Takes no lock: it answers while a step (or an inline training inside it) runs on another thread. Its fields are read one by one, so two of them may straddle a decision.

fed

fed(v) -> list

The decisions whose samples reached version v's promise, in order.

LoraLearner

LoraLearner(part, dir, *, runner='subprocess', signal='auto', epochs=6, max_risk=0.05)

See the module docstring. part: the question's DecisionPart (torch backend, loaded from a checkpoint folder); dir: where the logs and adapter files go; runner: "subprocess" (default), "thread" or a runner object (stream.runner); signal: act_guard's signal ("auto"); epochs: when the policy's settings give no updates; max_risk: act_guard's risk when the job does not carry the loop's α.

update

update(x, y, *, key=None, source=None) -> None

A train label: counted; the rows of a training come with its job (the loop keeps them).

version0

version0() -> LoraVersion

The part as it is now, as version 0 (the loop's initial=).

train

train(job) -> LoraVersion

One training (see the module docstring) → LoraVersion. Raises stream.runner's TrainingRefused (the estimate is above max_train_s), TrainingFailed (the training raised) or RunnerError (the process died).

LoraVersion

LoraVersion(part, adapter, calibration, *, info=None, signal='auto')

See the module docstring. part: the DecisionPart it serves (None: read from files, not bound yet — bind); adapter: a LoraAdapter or None (the checkpoint itself); calibration: solvi.experimental.lora.calibration's dict; info: what it was trained on; signal: the signal score returns ("auto": the threshold's, as recorded by act_guard).

threshold property

threshold

The act_guard threshold on its signal (escalate_below for "confidence", act_threshold for "act"); None when it has none; inf when act_guard found none at the promised risk.

act_threshold property

act_threshold

The threshold the adapter loop's pre-freeze report applies to score's signal (= threshold).

of_part classmethod

of_part(part, *, signal='auto')

Version 0: the part as it is now — its adapter (or none) and its calibration.

bind

bind(part)

Serve and score on part (its version lock is created; the adapter is staged on its scorer) → self.

release

release()

Unstage the adapter from the scorer (a discarded or retired version; idempotent). It stays when a slot holds it (the version is served); a later bind or score stages it again.

score

score(x)

→ (the answer, the signal): the part's question scored with this version's adapter and its own adaptation on this thread only (no threshold applied), whichever version the part serves; the signal is the one its threshold is on (act or confidence).

install

install(system=None) -> dict

Serve this version on its part (system: unused — the part is the version's own): the atomic swap. → {"from", "to"}: the part's fingerprints.

uninstall

uninstall(system=None) -> None

Back to what install replaced (atomically).

save

save(dir, version: int) -> list

→ [.lora.safetensors (when it has an adapter), .calib.json].

load classmethod

load(dir, version: int, *, expect_fp: str, part=None, groups=None) -> 'LoraVersion'

The version saved by save; ValueError when a file is not the recorded one (the adapter's content against its hash, the calibration's adapter, the version's fingerprint against expect_fp). groups: the grouping function of thresholds per group by a function (version 0 calibrated with act_guard(groups=fn)).

RunnerError

Bases: RuntimeError

The runner itself failed: the training process died without a result, or went silent.

SubprocessRunner

SubprocessRunner(*, nice=10, heartbeat_s=30.0, grace_s=120.0, stall_s=None, python=None, pythonpath=(), poll_s=0.5)

See the module docstring. nice: the process's niceness; heartbeat_s: seconds between heartbeat lines; grace_s: on top of the target's estimate (counted from the estimate line; before it, on top of max_train_s from the start) before the process is killed — it must cover what the estimate does not: loading the checkpoint, calibration, saving; stall_s: no log line for this long → killed, a RunnerError (None: max(10 heartbeats, 300 s)); python: the interpreter (default this one); pythonpath: extra import paths for the target's module (the folder solvi is imported from always comes first); poll_s: how often the process is checked.

ThreadRunner

ThreadRunner(*, heartbeat_s=30.0, grace_s=120.0)

See the module docstring. heartbeat_s: seconds between heartbeat lines; grace_s: past the estimate (max_train_s before one) before a training is reported as over its time. In this runner the LoRA trainer copies the network in the loop's process while holding the scorer's network gate alone, so every decision on that model (every question, not only the loop's) waits while the copy is made; unmeasured. SubprocessRunner, the default, copies in the child and is unaffected.

TrainingCancelled

Bases: RuntimeError

The caller cancelled the training (its cancel event was set): a subprocess is killed; a thread cannot be stopped and is left to end on its own.

TrainingFailed

Bases: RuntimeError

The training ran and failed (the target raised, or it ran past its time and was stopped).

TrainingRefused

Bases: RuntimeError

The training was not started: its estimated time is above the budget's max_train_s.

BaseVersion

BaseVersion(system, question: str)

Version 0 as served on a System: the answer head the System had when the loop was built (None: no head). install puts it back (or removes the question's head); it saves nothing.

HeadVersion

HeadVersion(frozen, question: str, feature: str = 'text')

A frozen model (stream.learner.Frozen with as_head) served as the answer head of question, reading the text fact feature. It scores and fingerprints as the frozen model does.

load classmethod

load(dir, version: int, *, expect_fp: str, question: str = '', feature: str = 'text') -> 'HeadVersion'

The version saved by save; a ValueError when its fingerprint is not expect_fp.

Rate

Rate(floor: float = FLOOR, budget: float = BUDGET, window: int = WINDOW)

ρ_t from the past only. See the module docstring.

StreamDriver

StreamDriver(promise, detector=None, *, on_drift='human', probation=300, floor=FLOOR, budget=BUDGET, window=WINDOW)

The per-decision step of the stream certificate inside a Dispatcher. promise: the StreamPromise installed on System 1's question; detector: a RiskDetector or None; on_drift: "recertify" (an alarm restarts the promise and opens probation), "human" or "accept" (an alarm is the Dispatcher's latched drift flag); probation: live decisions escalated after an alarm (and until re-certified, the stricter of the two).

availability

availability() -> dict

FIFO-consumed label availability and observed deployed error, not a risk certificate.

Missing outcomes keep their original worst-case losses in the certificate and detector. The observed error is conditional on receiving a label and may be selection-biased. A legacy pickled driver without these counters has an unknown historical prefix.

before

before() -> tuple

(ρ_t, in probation) from the past only.

issue

issue(n, sampled)

Decision n begun (its coin drawn): a sampled one is open until its after(n=n); later samples wait for it.

after

after(*, score, would, alone, label, label_source, sampled, free, rho, in_force, probation=None, label_of=None, lost=None, n=None) -> tuple

One decision done → (its record, the stream events it caused, a drift reason for the Dispatcher or None). score: the guard's signal (None: not gated); would: System 1's would-be answer; alone: System 1's answer was given alone (within the threshold in force); label: the slow path's accepted answer on a sampled decision (None: missing); in_force: the threshold the decision was gated at (None: +inf). A decision completed later (a ticket, stage 3): probation — the flag before() gave when it was issued (default: now); label_of — the stored id of the record that holds the label (the ticket's); lost — no verdict came (an expired ticket): a missing label, and the detector's loss is 1 whatever System 1 would have done (the conservative accounting, design §5.4). An oracle's decision records label_of and lost; the others record what stage 2 did. n: the decision's number — with it, a sample waits for every earlier sampled decision issued and not completed (see the module docs); without it, the sample is read at once.

AgentOracle

AgentOracle(system, *, question=None, contract=None)

Bases: SlowPath

The slow path when the slow path is an agent outside the process: answers come only through a TicketDesk. system: the System whose question the agent answers (its options, its contract — usually System 1 itself).

not_applicable

not_applicable(state, question, price=None)

The Thought of a path whose contract does not apply to the input (it is not asked), else None.

verdict

verdict(state, question, label, *, source='s2', ticket=None, of=None, price=None)

The agent's label → the slow path's Thought (accepted unless the contract refuses it).

lost

lost(why, *, ticket=None, price=None)

No verdict (an expired or failed ticket) → the Thought that sends the input to a person.

TicketDesk

TicketDesk(dispatcher, *, ttl: float = TTL, clock=time.time, deduplicate_open=True)

The tickets of one Dispatcher whose slow path is an AgentOracle (see the module docs). ttl: seconds a ticket waits for a verdict; clock: the time source (seconds; tests pass their own). One active desk per persistent store; use close() or a context manager before restarting. Memory/custom stores guard only the same object. deduplicate_open: an identical serialized input with an open ticket returns that ticket before System 1 runs; False opts into independent decisions and forfeits this protection against same-input re-probing.

close

close()

Release ownership without expiring tickets; closed desks cannot be used again.

decide

decide(state, *, request_id=None) -> dict

One input → {"status": "decided", "answer", "by", "stored_id", "trace_hash"} (System 1 answered alone, or a person gets it: by "human", answer None) or a blind ticket (see the module docs). request_id is an optional durable retry key, separate from state. Reusing it returns the original payload (even after resolution/expiry); another state is refused. An interrupted call requires replay of a fresh dispatcher before retry. Storage must durably append, and all decisions must use this desk. By default an identical input reuses its open ticket even under a new request_id; it is not a new sample.

ticket_payload

ticket_payload(ticket, state, expires_in_s=None) -> dict

What the agent sees of a ticket: a function of the ticket id, the question and the input only.

resolve

resolve(ticket, label, source: str = 's2') -> dict

The verdict on an open ticket → {"status": "resolved", "answer" (what the dispatcher gives: on_disagree for a check), "stored_id"}. TicketError: an unknown, expired or already resolved ticket, or a label that is not an answer of the question (the ticket stays open).

expire

expire(ticket, why=None)

Give up an open ticket now (a failed oracle) → its Dispatched: recorded as lost (see the module docs).

sweep

sweep(now=None) -> list

Expire every open ticket past its ttl → their Dispatched (each recorded as lost).

open

open() -> list

The open tickets: [{"ticket", "age_s"}], oldest first (no content, no kind).

client

client()

Trusted request producer capability; deploy separately from the oracle endpoint.

oracle

oracle()

Blind labeler capability: durable pending queue, verdict acknowledgments, no decide.

mcp_tools

mcp_tools() -> list

Decide, resolve, recover open tickets, or explicitly give up.

call_tool

call_tool(name, arguments) -> dict

An MCP tool call → its result (TicketError and ValueError are the agent's errors; KeyError: no such tool).

TicketError

Bases: ValueError

A ticket that cannot be resolved (unknown, expired or already resolved) or a label that is not an answer.

LearningLoop

LearningLoop(learner, *, question, max_risk=None, max_error=None, delta=0.05, freeze_min=300, growth=2.0, stale=3000, trial=None, min_share=0.05, margin=0.01, refreeze=1.5, initial=None, detector=None, probation=300, s2_labels=False, source='human', secret=None, seed=0, sampling=None, promise_options=None, storage=None, versions_dir=None, system=None, feature='text', additive=True, max_layers=3)

Bases: AdapterLoop

See the module docstring. learner: the live Learner; question: the question's name (in the coin and the records); max_risk= / max_error=, delta: each version's StreamPromise (promise_options: its other keywords — grid, grid_from, bets ...); freeze_min, growth, stale, trial, refreeze: the protocol's constants; min_share, margin: the promotion rule (ℓ_k ≥ min_share and ℓ_k ≥ ℓ_s + margin); initial: version 0's frozen model (None: no model); detector, probation: a RiskDetector on the served version and the decisions escalated after its alarm; s2_labels: take slow-path labels; source: the default source of the oracle's labels; secret, seed: the coin's key and run; sampling: {"floor", "budget", "window"} of the rate; storage: a TraceStorage for the records (None: kept in memory for replay); versions_dir: where frozen models are pickled; system, feature: install the served version as the question's answer head (feature: the text fact a text model reads).

refreeze_floor property

refreeze_floor: float

refreeze × the live learner's labels at the latest discard (0 before any).

Verdict

Bases: NamedTuple

What an oracle may return instead of a bare label: the label (None: missing), its source (None: step()'s) and label_of — the stored id of the record that holds it (a ticket's), recorded with the decision.

clean_need

clean_need(alpha: float, delta: float, bets: str = 'mixture', **kw) -> int

Clean samples (loss 0) that take a fresh e-process to 1/delta. A floor on the cost, not the useful metric: it is the n of the first certification, and the first threshold in force is the strictest certified grid point — how strict is distribution-dependent (on zero-loss bets every grid point grows at the same deterministic rate, so they certify together at exactly this n, the loosest of them first in force). What to price on a real stream is the coverage a given number of labels buys (a coverage-vs-labels curve, or a labels-to-coverage target), not n to the first certification.

fixed_grid

fixed_grid(lo: float = 0.0, hi: float = 1.0) -> list

The fixed grid shape {1 − 10^(−e/8), e = 1..32} ∪ {0.05, 0.10, …, 0.95}, mapped onto [lo, hi]; strict → loose.

watch_rollback

watch_rollback(w: Watch, *, min_n: int = 100, confidence: float = 0.95, min_gain: float = 0.01) -> bool

The watch's rule: the served version is shown worse than the target on the labels since its promotion — ≥ min_n labels compared, the e-process's wealth ≥ 1 / (1 − confidence) (w.log_e, watch_eprocess(): 20 at 0.95), better > worse, and the margin (target − served, per label) ≥ min_gain. Anytime-valid: the e-process is a test supermartingale while the served version wins at least half of the discordant labels, so by Ville's inequality P(a rollback ever, at any horizon) ≤ 1 − confidence per promotion when the served version is not worse on the discordant labels; the other conditions only make a rollback rarer.

Simulation, not a stand (2 000 runs per cell; a watched label discordant with probability d ∈ {0.1, 0.3, 0.5}, a discordant one won by the target with probability p, steps 1 or 2): false rollbacks with both versions equally good (p = 0.5) 0.4–1.4 % within 300 watched labels, 0.5–1.9 % within 1 000, 0.8–2.1 % within 3 000; a served version truly worse (p = 0.6, d = 0.1) rolled back in 10 / 28 / 70 % of runs by 300 / 1 000 / 3 000 watched labels.

content_key

content_key(question, x) -> str

The default content key of an input: "question|vhash(x)" (for a dict, the change pipeline's content_key).

pick_device

pick_device(device='auto', free_gpu_mb=3000, *, probe=None, cuda=None, env=None, torch_probe=None) -> tuple

The device a training runs on → (device, why). "cpu": the CPU; "cuda" / "cuda:": that GPU (as asked); "auto": the first GPU with at least free_gpu_mb MB free when torch sees CUDA, else the CPU (the reason is said). The device is torch's ordinal: under CUDA_VISIBLE_DEVICES nvidia-smi's index is mapped to it (when that variable names GPUs by UUID, torch is asked for the free memory instead). probe: () → free MB per GPU by nvidia-smi's index (default gpu_free_mb); cuda: () → whether torch sees CUDA (default: torch's); env: the environment (default os.environ); torch_probe: () → free MB per torch ordinal (default: torch.cuda.mem_get_info).

coin_message

coin_message(question, run, n) -> str

The message of the calibration coin of decision n: no input bytes.

lane_policy

lane_policy(*, freeze_min=300, growth=2.0, stale=3000, trial=None, min_share=0.05, margin=0.01, refreeze=1.5, s2_labels=False) -> DefaultPolicy

The lane LearningLoop's protocol as a DefaultPolicy: every label trains, every training freezes (the stream certificate decides), promotion on certified and ℓ_k ≥ min_share and ℓ_k ≥ ℓ_s + margin, discard stale decisions after the freeze uncertified or trial decisions certified (not coin samples), retrain at ≥ max(freeze_min, growth × the served version's labels, refreeze × the labels at the latest discard), no training budget, no alarm rollback.

ticket_verdict

ticket_verdict(desk, resolved) -> Verdict

A ticket resolved (or expired) on a stage-3a TicketDesk → its Verdict, read from the stored dispatch record. desk: the TicketDesk (or its TraceStorage); resolved: what TicketDesk.resolve returned, or the record's stored id. The agent's verdict has source "s2" (the loop takes it only with s2_labels=True), a person's "human"; a ticket that expired or whose verdict the contract refused has no label.

solvi.experimental.stream.certificate

StreamPromise and DeltaBudget: the certificate itself — one e-process per grid point, fixed-sequence from strict to loose, the threshold only loosens; δ spent over restarts. A promise takes its (v, δ_v) from the budget at its first sample (lazy charge): v / delta_v are None before it, restart() returns (None, None), and a promise that never bet spends nothing.

StreamPromise: an anytime-valid learn-then-test certificate on a threshold grid, earned on the stream (experimental).

One e-process per grid point λ_i (strict → loose) against H0 "the risk at λ_i is above α"; a point is certified once its wealth reaches 1/δ_v (Ville), and betting stops there. The threshold in force λ̂ is the loosest grid point such that every stricter point is certified (fixed-sequence testing: the order is fixed before any label), +inf (answer nothing alone) until the first one. The wealths only grow to certification, so λ̂ only loosens; a model that degrades is never un-certified here — that needs a change detector and restart() (a later stage).

Kinds. joint (max_risk=): the loss of a sample at λ is L = 1{score ≥ λ and the answer is wrong} — "P(answered alone and wrong) ≤ α, a share of all inputs". selective (max_error=): point i reads only samples with score ≥ λ_i, loss W = 1{wrong} — "the error among the answers given alone ≤ α".

Statement. With probability ≥ 1 − δ_v, at every point in time, the risk at the threshold in force is at most α — on a stream whose conditional risk given the past is constant (i.i.d. between change points) and whose labelled samples are drawn by a coin independent of the input. Over restarts, δ_v = DeltaBudget.next() (Basel: 6δ/(π²v²)), so every threshold ever in force holds together with probability ≥ 1 − δ.

Lazy δ charge. A promise takes its (v, δ_v) from the budget at its first learn that bets (the grid fixed), not when it is built or restarted: until then v and delta_v are None, its threshold is +inf (nothing is answered alone under it) and it has spent nothing. The indices stay a fixed function of the order in which they are handed out (the budget's next(), chronological), each is assigned before its certificate's first bet and at most once, and a certificate that never bets (a candidate discarded before its first sample, a restart re-alarmed or rolled away from before its first post-alarm sample) spends no index — the conditions under which Σ δ_v ≤ δ bounds every certificate together hold unchanged (DESIGN_DELTA_CADENCE §1, C1–C3). A finite threshold without an index is refused everywhere (learn, threshold_of, restore).

Maturity. Per grid point the promise keeps the running maximum of its log-wealth and the sample count at which it was last set (peak_at(): that count for the first uncertified point — the one that would loosen next); with the "certified" / "loosened" events' n it tells a policy whether the certificate is still loosening (DefaultPolicy.mature_patience). Kept in dump() (key "peaks"), not in state().

Procedure. "fixed" (the default): the fixed-sequence rule above, each point at level 1/δ_v. "pointwise": each grid point is its own test at level G/δ_v (G the grid's size; Bonferroni: every point's statement holds together with probability ≥ 1 − δ_v), a point is certified as soon as its own wealth reaches it, whatever the stricter points did, and the threshold in force is the loosest certified point (no prefix rule); certified_at(λ) says whether one grid point is. The set of certified points only grows, so the threshold still only loosens. Pointwise pays log G nats per point and never starves on a strict point that almost no sample reaches — the reason the selective kind uses it as an additive layer's usefulness certificate (AdapterLoop(useful_error=)). A "fixed" promise's records, dumps and fingerprint are those of a promise built without the keyword.

A missing label (learn(..., label=None): an expired ticket, a failed oracle) counts as a loss at every point where the sample would have been answered alone: its factor is ≤ 1, so it can only lower the wealth, whatever the reason the label is missing.

The grid. "auto": ltt_grid over the scores of the first grid_from decisions observed (labels unread), at most grid_size points; until then nothing certifies and a labelled sample is not read (counted in dropped). "fixed": fixed_grid() (a fixed shape on [0, 1]). A sequence: those thresholds. +inf is always the "answer nothing" point. The auto grid's price: those first grid_from labels are dropped, and under a Dispatcher (audit="adaptive") every one of them was paid for — the threshold is +inf until the grid is fixed, so each decision is escalated and its slow-path label then dropped (the first grid_from slow-path calls, ~200 by default, buy nothing; the Dispatcher warns). For scores already on [0, 1] prefer grid="fixed": it certifies at the clean need (85 at α = δ = 5 %) with nothing dropped, or take a smaller grid_from.

The data a decision records (state()): v_index, delta_v, threshold, n (samples read), seen (decisions observed), missing, dropped, certified (points), evidence_fp (SHA-256 of the log-wealth vectors rounded to 1e-9 and the certified flags), grid_fp. The same samples in the same order give the same state, so the record can be rebuilt and compared. fingerprint() is the configuration only (what a recorded guard is checked against on replay); the state is not in it.

StreamPromise

StreamPromise(max_risk=None, max_error=None, delta=None, *, kind=None, grid='auto', grid_from=200, grid_size=32, bets='mixture', fractions=FRACTIONS, weights=WEIGHTS, c=0.75, budget=None, procedure='fixed')

See the module docstring. The Promise interface (method "stream-ltt", level, delta, threshold, nodes=None, report, promise, stateful, allows, threshold_of, record, fingerprint), so System.guarantee(question, promise=sp) installs it as it installs OpenSetGate: every gated decision is observed (no label), its state recorded with the guard record, and a replay takes the recorded threshold. Labels come in through learn (one labelled sample: the sampling and the oracle are the caller's — a later stage wires them into the Dispatcher). Groups are not supported.

level_now property

level_now

The log-wealth a point needs under the current index (None before the first bet: no δ_v yet).

peak_at

peak_at()

The sample count (n) at which the first uncertified grid point's log-wealth last set a new running maximum (0: never above its start), or None (no grid yet, or every point certified).

certified_at

certified_at(lam) -> bool

Whether the grid point lam is certified (False for a value that is not a grid point, or before the grid).

log_wealth_at

log_wealth_at(lam)

The log-wealth of grid point lam's e-process now (None: not a grid point, or no grid yet).

prime_grid

prime_grid(scores, *, source)

Fix a fresh auto grid from bounded past scores, without labels, bets or a delta charge.

Past scores need not come from the future model: their scale affects utility, not validity of the fixed future grid. No past labels, wealth or certification evidence are imported.

observe

observe(signal, result=None) -> dict

One gated decision (no label): counted, and its score read for the auto grid until it is fixed.

learn

learn(signal, answer, label, floor=None, *, sampling_policy) -> dict

One labelled sample: the decision's score, the answer it would give alone, its label (None: missing — a loss wherever it would have been answered alone). Before the grid is fixed the sample is not read (dropped). floor: grid points below it do not bet on this sample (no wealth or peak change; n counts the sample once) — an additive layer relearning on the rows it owns ({score ≥ Λ}), a biased sample of its zone below Λ.

sampling_policy declares how the caller selected this sample: "uniform" means a coin independent of the current input and label (its rate may depend on the past); "complete" means every decision is labelled. Known "input_dependent" sampling is refused: this unweighted certificate does not implement IPW or DR. The required declaration checks caller intent only; it does NOT detect a hidden slice-dependent coin; the certificate's guarantee still requires the declared sampling assumption to hold. Dispatcher already enforces an input-independent coin and a rate determined from the past in its own sampling path. Invalid declarations are refused before any state change or delta-budget charge.

restart

restart(why=None) -> tuple

A new certification from scratch (an alarm, a person's call): every point uncertified, wealth 1, the threshold +inf; the grid is kept (it was read without labels). Its (v, δ_v) is taken lazily, at its first bet, so this returns (None, None); a restart that never bets spends nothing.

stream_driver

stream_driver(detector=None, **kw)

The per-decision step a Dispatcher runs for this promise (sampling.StreamDriver): how Dispatcher(promise=sp, detector=, audit="adaptive") reaches the experimental code without importing it.

dump

dump() -> dict

Everything a restore needs (JSON data): the configuration's fingerprint, (v, δ_v), the grid (or the scores buffered for the auto grid), the counters, the threshold, each grid point's e-process and certified flag, the event list, and the state's evidence_fp, which restore checks. The budget is not in it: it is the caller's (one DeltaBudget over every version of a loop).

restore

restore(d) -> 'StreamPromise'

The state of dump() on this promise (built with the same configuration; its budget is left as it is) → self. A dump of another configuration, or one whose evidence does not give back its evidence_fp, is refused (ValueError).

fixed_grid

fixed_grid(lo: float = 0.0, hi: float = 1.0) -> list

The fixed grid shape {1 − 10^(−e/8), e = 1..32} ∪ {0.05, 0.10, …, 0.95}, mapped onto [lo, hi]; strict → loose.

solvi.experimental.stream.detector

RiskDetector: a Shiryaev–Roberts e-detector on the deployed risk; its bound is an expected run length to a false alarm, not a per-horizon probability.

RiskDetector: a Shiryaev–Roberts e-detector on the deployed risk (experimental; stage 2 of the stream certificate).

Input: the deployed loss of one labelled sample, L_t = 1{answered alone and wrong} (an escalated sample contributes 0: it was not answered alone; a missing label on an alone answer is a loss). Null: E[L_t | past] ≤ α0 at every step, with α0 = α (the promise itself, the default) or min(alternatives)·α (alternatives=(1.5, 2.0): a stream at α never alarms, a break below 1.5α is not looked for). Statistic: for bets λ_j = c_j/α0, c ∈ scales,

R_j ← (1 + R_j)·(1 + λ_j·(L_t − α0)),        alarm when mean_j R_j ≥ A (= `arl`).

Under the null each R_j − t is a supermartingale, so is their mean, and E[time to a false alarm] ≥ A (Shin, Ramdas & Rinaldo, e-detectors). This is an expected run length, not a per-horizon probability: unlike solvi.core.guarantees.drift.DriftMonitor ("false flags ≤ alpha within horizon decisions"), a stream running exactly at α alarms about every A samples on average — by construction ("at the promise, prove it again").

Arithmetic in a fixed order (one product per bet, math.fsum for the mean); the recorded R is rounded to 1e-9, so the same losses in the same order give the same record. The Monitor protocol (observe, flagged, reset) is there so Dispatcher(monitor=det) accepts it, but it reads only labelled samples: observe(decision) without a label is ignored. The Dispatcher feeds it with detector= (each sampled decision's deployed loss) — only the coin's samples, so at the sampling rate ρ the detector sees a break about 1/ρ decisions after it happens (≈ 20× at the default floor 0.05, next to a full-stream CUSUM or score monitor's ~10 for a confidence-visible shift; its unique value is a label-only shift). A RiskDetector is never the only alarm: AdapterLoop refuses it without a score monitor (loop.py), and Dispatcher(promise=, detector=) should be given monitor= too — nothing there enforces it.

RiskDetector

RiskDetector(alpha: float = 0.05, arl: float = 1000.0, scales=SCALES, alternatives=None)

See the module docstring. alpha: the promised rate; arl: the alarm level A (E[run to a false alarm] ≥ A); scales: the bet fractions c_j (λ_j = c_j/α0, each in (0, 1)); alternatives: None (null at α) or rates ≥ 1 (null at min(alternatives)·α).

statistic property

statistic: float

mean_j R_j.

update

update(loss: float) -> bool

One deployed loss in [0, 1] → True when this sample raises the alarm (the flag stays up until reset()).

observe

observe(decision, label=None, question=None) -> dict

A labelled decision → {"drift", "why", "R", "n"}. decision: a dict {"answer", "alone", "label"}, a Dispatched (alone: by "s1"), or anything with .answer and .status ("ok": answered alone). Without a label: ignored.

reset

reset() -> None

Start again: R_j = 0, no flag (the alarm count is kept).

dump

dump() -> dict

The statistic's state (JSON data): the configuration (config(), its fingerprint) and R_j, n, the alarm flag and count. restore() on a detector of the same configuration gives it back exactly.

restore

restore(d) -> 'RiskDetector'

→ self, in the state of dump(); a dump of another configuration is refused (ValueError).

config

config() -> dict

The constructor's arguments: RiskDetector(**det.config()) is a detector of the same configuration.

solvi.experimental.stream.sampling

The calibration coin (keyed on the question, run and decision number, never on the input), the sampling rate, and the per-decision step the Dispatcher runs.

Calibration sampling for the stream certificate: the coin, the rate, and the per-decision step the Dispatcher runs (experimental; stage 2).

The coin. u_t = HMAC-SHA256(secret, "sample|{question}|{run}|{n}") read as 52 bits / 2^52 (coin_message, the Dispatcher's keyed hash; run = the Dispatcher's seed, n = the decision's number). No input bytes in the message: the coin does not read the input, so a sample is drawn independently of (x_t, y_t) — Assumption B of the certificate. Without a secret the same message is hashed with plain SHA-256: reproducible, but predictable by whoever knows the seed (the Dispatcher warns once, PredictableDrawWarning). The draw is not recorded (it needs the secret); replay recomputes it where the secret is given.

The rate (Rate). ρ_t = 1 while nothing is certified (the grid not fixed, the threshold +inf) and during probation; otherwise ρ_t = min(1, max(floor, budget / ℓ_{t−1})), ℓ_{t−1} the share of the last window decisions answered alone (clamped below at 1e-3). Every input of ρ_t is from before decision t. Defaults floor = 0.05, budget = 0.05 extra oracle calls per decision, window = 500.

Who pays. An escalated decision that wins the coin is a free sample: the slow path answers it anyway and its accepted answer is the label. An alone decision that wins the coin is an audit: the slow path checks it (one extra call). A sample without an accepted slow-path answer (no slow path, no budget, a person decides, the slow path failed) has no label: a loss wherever it would have been answered alone (StreamPromise.learn(label=None)). For the detector an expired ticket is the sharpest case — a loss whatever System 1 would have done (after(..., lost=True), design §5.4) — so the oracle's expiry rate adds to the rate the detector tests: a stream at risk r seen through an expiry rate e reads as e + (1 − e)·r, and e must sit well below α (at α = 5 %, an oracle that expires 10 % of its tickets alarms by construction on a perfectly clean stream; see stream.tickets).

The step (StreamDriver). Per decision, after System 1 answered (the promise observed it through its guard): before() → (ρ_t, probation) from the past; the Dispatcher draws the coin and dispatches; after(...) → the record this decision carries and the stream events it caused: the sample goes to the promise (learn), its deployed loss to the detector (only while a threshold was in force and outside probation), an alarm is appended to the promise's own event list (with the detector's R and sample count — the detector resets right after, so the event is what a caller without storage reads), restarts the promise (the next (v, δ_v) from its budget at its first post-alarm sample — lazy charge —, threshold +inf) and opens probation (on_drift="recertify"), and the alone flag enters the rate's window. The same records in the same order rebuild the same state (Dispatcher.replay_stream).

Labels in sampling order. A decision completed later (a ticket) may get its label after later decisions: the samples reach the promise and the detector in the order of the decisions' numbers, not in the order the labels arrive. issue(n, sampled) (at Dispatcher.start) opens a sampled decision; its completion (after(n=...)) is held while an earlier sampled decision is still open, and released, with every held sample after it, once that one is completed (resolved, or expired: a missing label). Feeding the labels in arrival order would break the certificate whenever the delay depends on the answer (an oracle slow on the cases System 1 gets wrong: the losses arrive after the clean samples have certified a threshold whose risk is above α; seen in tests/test_stream_order.py). The cost: a ticket that stays open holds every later sample until it is resolved or expires (its ttl bounds the wait).

Rate

Rate(floor: float = FLOOR, budget: float = BUDGET, window: int = WINDOW)

ρ_t from the past only. See the module docstring.

StreamDriver

StreamDriver(promise, detector=None, *, on_drift='human', probation=300, floor=FLOOR, budget=BUDGET, window=WINDOW)

The per-decision step of the stream certificate inside a Dispatcher. promise: the StreamPromise installed on System 1's question; detector: a RiskDetector or None; on_drift: "recertify" (an alarm restarts the promise and opens probation), "human" or "accept" (an alarm is the Dispatcher's latched drift flag); probation: live decisions escalated after an alarm (and until re-certified, the stricter of the two).

availability

availability() -> dict

FIFO-consumed label availability and observed deployed error, not a risk certificate.

Missing outcomes keep their original worst-case losses in the certificate and detector. The observed error is conditional on receiving a label and may be selection-biased. A legacy pickled driver without these counters has an unknown historical prefix.

before

before() -> tuple

(ρ_t, in probation) from the past only.

issue

issue(n, sampled)

Decision n begun (its coin drawn): a sampled one is open until its after(n=n); later samples wait for it.

after

after(*, score, would, alone, label, label_source, sampled, free, rho, in_force, probation=None, label_of=None, lost=None, n=None) -> tuple

One decision done → (its record, the stream events it caused, a drift reason for the Dispatcher or None). score: the guard's signal (None: not gated); would: System 1's would-be answer; alone: System 1's answer was given alone (within the threshold in force); label: the slow path's accepted answer on a sampled decision (None: missing); in_force: the threshold the decision was gated at (None: +inf). A decision completed later (a ticket, stage 3): probation — the flag before() gave when it was issued (default: now); label_of — the stored id of the record that holds the label (the ticket's); lost — no verdict came (an expired ticket): a missing label, and the detector's loss is 1 whatever System 1 would have done (the conservative accounting, design §5.4). An oracle's decision records label_of and lost; the others record what stage 2 did. n: the decision's number — with it, a sample waits for every earlier sampled decision issued and not completed (see the module docs); without it, the sample is read at once.

coin_message

coin_message(question, run, n) -> str

The message of the calibration coin of decision n: no input bytes.

coin_value

coin_value(hexdigest: str) -> float

A hex digest → a number in [0, 1) from its first 52 bits.

Dispatcher.availability() (also StreamDriver.availability()) reports FIFO-consumed samples, received and missing labels, and errors among the deployed answers whose labels arrived. This observed error rate is conditional on receiving a label and may be selection-biased. It is a diagnostic, never a replacement for the certificate or an estimate of latent risk under arbitrary missingness. Expired outcomes retain their worst-case loss of one in the detector. An old pickled driver without these counters reports an unknown historical prefix; new counters cover only its subsequent samples. replay_stream() reconstructs these diagnostics from the recorded outcomes.

solvi.experimental.stream.tickets

Tickets: an agent (or a person) as the oracle of a Dispatcher, over MCP — blind, durable, never silently dropped (experimental; stage 3a).

from solvi.experimental.stream import AgentOracle, TicketDesk

d = Dispatcher(s1, AgentOracle(s1), audit="adaptive", promise=sp, detector=det, on_drift="recertify",
               secret=key, storage=store)
desk = TicketDesk(d, ttl=3600)
out = desk.decide(state)          # {"status": "decided", ...} or a blind ticket {"status": "needs_verdict", ...}
desk.resolve(out["ticket"], "billing")              # the agent's verdict: the decision is completed and recorded

The oracle. AgentOracle is the Dispatcher's slow path when the slow path is an agent outside the process: it never runs in-process (think raises); every decision the slow path would take — an escalation (think) or a check (an audit drawn by the calibration coin, a supervision draw, a drift check) — becomes a ticket.

The ticket (what the agent sees). {"status": "needs_verdict", "ticket", "question", "options", "input", "instructions", "expires_in_s"}: the question's name, all of its options, the input as given, the question's text, the time left. No model guess, no probabilities, no reason, no marker of kind: an audit of an answer System 1 gave alone and an escalation have the same payload fields (the kind is kept server-side only, in the record). This hides the kind in an isolated ticket; it does not make the whole interaction indistinguishable. An oracle with access to decide cannot re-probe an identical input while its ticket is open: by default the desk returns that ticket, without another draw or decision. This also applies across restart and different request ids. After completion or expiry a repeated input is a new decision. deduplicate_open=False restores the old per-call behavior and permits the same-input side channel. Modified unused fields also bypass serialized-input deduplication and can reveal the model guess via fresh decisions. The calibration coin is still drawn per decision, not fixed per input.

Serving boundary. Service(agent_oracle=desk) narrows to desk.oracle(): only open_tickets, resolve and give_up. Service(agent_oracle=desk.client()) exposes decide only. Oracle verdicts return status only, never the completed answer or storage metadata. Both services share one owner desk and its lock; pending work recovers from the journal. Run the two services over separately authenticated/authorized transports: the oracle must not reach the client endpoint, journal or process memory. These views enforce tool access, not transport authentication or Python isolation. Local desk.decide/resolve/call_tool remain trusted combined APIs. A labeler granted those APIs can still probe. Queue membership, input, count and timing remain visible: arbitrary whole-interaction indistinguishability is not supported. This is a trusted-role contract, not a promise against an oracle with arbitrary access.

The certificate assumes that the oracle's label does not depend on whether the decision was sampled. Equal ticket fields alone do not enforce this assumption: the application must account for the oracle's access to repeated decide calls and other information about System 1 when relying on it.

Durability. A ticket is a hash-chained record of kind "pending" written when it is issued: "pending" — {ticket, question, n, created, ttl, kind_hidden, rho, probation, sampled} (KEPT: a redaction leaves it) — and "issue", the decision begun (Dispatcher.start: the input, System 1's response, the decision's number, draws, spend, drift flag and dispatch). The decision's number, its coin and its rate are fixed at issue; the dispatch record (kind "dispatch", with "pending": the ticket) is written when it is completed (Dispatcher.complete). A restart rebuilds everything from the store: a new TicketDesk over a freshly built dispatcher on the same storage resumes it (Dispatcher.resume: numbers, spend, the stream certificate, its detector and rate) and lists the tickets issued and not completed; they resolve as before.

The verdict. resolve(ticket, label, source="s2"): the label must be one of the options (else TicketError, and the ticket stays open); the slow path's contract, if any, applies as it does to an in-process slow path. The verdict is the slow path's Thought (mode "agent"; its record {"oracle": {"ticket", "label_source", "label_of"}}); the dispatcher completes the decision with it as with any slow path (on_disagree for a check, think="agree", ...). label_source: "s2" (the agent is the slow path; the default, and what the MCP tool records) or "human" (a person gave it); label_of: the stored id of the ticket's record. On a sampled decision the label goes to the stream certificate with both, in the order of the decisions' numbers: a verdict that comes before an earlier sampled ticket's waits for it (sampling.StreamDriver), so an agent slow on the hard cases cannot certify on the easy ones first.

Expiry and failure. A ticket not resolved within its ttl (checked on every call and when the desk starts) or given up (expire(ticket, why)) gets a record of kind "pending_expired" and is completed with no verdict: the input goes to a person (by "human", whatever the action was — an audited answer System 1 gave does not stand unchecked) and, on a sampled decision, the label is missing: a loss at every grid point where System 1 would have answered alone, and a loss of 1 for the detector (design §5.4: both factors are ≤ 1 for the wealth and ≥ 1 for the detector, so the certificate and the detector keep their statements under any missingness, adversarial included). That loss of 1 whatever System 1 would have done makes the oracle's expiry rate part of the rate the detector tests — a stream at risk r with expiry rate e reads as e + (1 − e)·r — so the expiry rate must sit well below α: at α = 5 %, an oracle that expires 10 % of its tickets alarms by construction on a clean stream, and each alarm's restart opens probation (ρ = 1: every decision a ticket), which raises the expiry rate further until the loop exhausts the budget (the share-of-expired stop, max_drop, is deferred — see "Not here"). An unsampled expired ticket is not a sample (adding it would raise the wealth at the strict points); it is recorded the same way. A resolve after expiry is refused. Nothing is dropped.

Not here (later stages or not built): the share-of-expired stop (max_drop), repeated tickets for the oracle's self-disagreement (ε̂), several servers on one store (one desk per store and question), the free-text input. A replay of a store with tickets: Dispatcher.replay_all() and replay_stream() (stored=None) with this module imported (the agent's Thoughts are read back by AgentOracle). Unmeasured.

TicketError

Bases: ValueError

A ticket that cannot be resolved (unknown, expired or already resolved) or a label that is not an answer.

AgentOracle

AgentOracle(system, *, question=None, contract=None)

Bases: SlowPath

The slow path when the slow path is an agent outside the process: answers come only through a TicketDesk. system: the System whose question the agent answers (its options, its contract — usually System 1 itself).

not_applicable

not_applicable(state, question, price=None)

The Thought of a path whose contract does not apply to the input (it is not asked), else None.

verdict

verdict(state, question, label, *, source='s2', ticket=None, of=None, price=None)

The agent's label → the slow path's Thought (accepted unless the contract refuses it).

lost

lost(why, *, ticket=None, price=None)

No verdict (an expired or failed ticket) → the Thought that sends the input to a person.

TicketDesk

TicketDesk(dispatcher, *, ttl: float = TTL, clock=time.time, deduplicate_open=True)

The tickets of one Dispatcher whose slow path is an AgentOracle (see the module docs). ttl: seconds a ticket waits for a verdict; clock: the time source (seconds; tests pass their own). One active desk per persistent store; use close() or a context manager before restarting. Memory/custom stores guard only the same object. deduplicate_open: an identical serialized input with an open ticket returns that ticket before System 1 runs; False opts into independent decisions and forfeits this protection against same-input re-probing.

close

close()

Release ownership without expiring tickets; closed desks cannot be used again.

decide

decide(state, *, request_id=None) -> dict

One input → {"status": "decided", "answer", "by", "stored_id", "trace_hash"} (System 1 answered alone, or a person gets it: by "human", answer None) or a blind ticket (see the module docs). request_id is an optional durable retry key, separate from state. Reusing it returns the original payload (even after resolution/expiry); another state is refused. An interrupted call requires replay of a fresh dispatcher before retry. Storage must durably append, and all decisions must use this desk. By default an identical input reuses its open ticket even under a new request_id; it is not a new sample.

ticket_payload

ticket_payload(ticket, state, expires_in_s=None) -> dict

What the agent sees of a ticket: a function of the ticket id, the question and the input only.

resolve

resolve(ticket, label, source: str = 's2') -> dict

The verdict on an open ticket → {"status": "resolved", "answer" (what the dispatcher gives: on_disagree for a check), "stored_id"}. TicketError: an unknown, expired or already resolved ticket, or a label that is not an answer of the question (the ticket stays open).

expire

expire(ticket, why=None)

Give up an open ticket now (a failed oracle) → its Dispatched: recorded as lost (see the module docs).

sweep

sweep(now=None) -> list

Expire every open ticket past its ttl → their Dispatched (each recorded as lost).

open

open() -> list

The open tickets: [{"ticket", "age_s"}], oldest first (no content, no kind).

client

client()

Trusted request producer capability; deploy separately from the oracle endpoint.

oracle

oracle()

Blind labeler capability: durable pending queue, verdict acknowledgments, no decide.

mcp_tools

mcp_tools() -> list

Decide, resolve, recover open tickets, or explicitly give up.

call_tool

call_tool(name, arguments) -> dict

An MCP tool call → its result (TicketError and ValueError are the agent's errors; KeyError: no such tool).

solvi.experimental.stream.versions

The closed learning loop: frozen versions, each with its own stream certificate, promoted under δ-spending (experimental; stage 3b).

from solvi.experimental.stream import HashedTextLearner, LearningLoop

loop = LearningLoop(HashedTextLearner(), question="intent", max_risk=0.05, delta=0.05, secret=key,
                    storage=store, initial=model)
out = loop.step(text, oracle)          # oracle: () → the label (None: missing), called only when one is needed
out["answer"], out["by"]               # "local" (the served version alone), "oracle", or "person" (no label)
loop.versions()                        # [{"version", "state", "certified", "threshold", ...}]
loop.replay()                          # every decision and event rebuilt from the records and compared

Additive coverage is the default: it needs stream mode and an initial model (version 0, above), as in the example; additive=False is the replacement protocol, which lost on the stand (worse than no loop by 11–16 points on 3 of 4 intent datasets; additive coverage gained on 4 of 4).

Versions. Version 0 is "no model" by default: it answers nothing alone, has no certificate and spends no δ (it never certifies). With initial= (opt-in) version 0 is an existing frozen model — the fitted System 1, e.g. FrozenFast.of_system(system, question) over its fitted head — with its own StreamPromise (the first (v, δ_v) of the budget), fed from decision 1 (its freeze is before the stream); its fingerprint is the "start" event of decision 1. The live learner starts empty either way. The live learner (stream.learner.Learner) takes every accepted oracle label and is never served. When no candidate exists and the live learner has taken ≥ max(freeze_min, growth × the served version's labels at its freeze, the refreeze floor) labels (300, 2: constants from the adapted design), a snapshot is frozen as the candidate, with its own StreamPromise drawing the next (v, δ_v) from the loop's one DeltaBudget at its first sample (lazy charge; Σ δ_v ≤ δ over every version ever frozen). Each decision is scored by the served version and, in shadow, by the candidate, before its label is read.

Calibration. A version's promise reads only samples drawn after its freeze: the samples of decision n go to the served version's promise and the candidate's — each frozen before n — and only then does the label reach the live learner; a version frozen at decision n first reads decision n + 1. Nothing is ever scored by a model that saw the label. Samples are drawn by the calibration coin of stage 2 — HMAC(secret, "sample|question|seed|n"), no input bytes — at the rate from the past (1 while the served version is not certified, else min(1, max(floor, budget / the share answered alone))); a decision the served version does not answer alone goes to the oracle anyway and its label trains the live learner, but it reaches a promise only when the coin drew it (escalation-only calibration breaks the promise: the stage-2 control).

Promotion. Once the candidate is certified, on the candidate's own samples (all after its freeze and after the last alarm): ℓ_k = the share with the candidate's score ≥ its threshold, ℓ_s = the share with the served version's score ≥ the threshold of its comparison certificate — a paired comparison on the same samples, both versions certified the same way: the comparison certificate is a StreamPromise for the served version on exactly the candidate's decisions and samples, same grid rule, the candidate's δ_v (1.4.0; before, the served version's own threshold, from an older certificate loosened at a larger δ_v, so a fresh candidate lost on the certificate's age). It only ranks and spends no δ: nothing is answered at its threshold. Promote when ℓ_k ≥ min_share (0.05) AND ℓ_k ≥ ℓ_s + margin (0.01: one point) — the author's rule (2026-10-23): under the joint promise a model of noise certifies at a strict threshold that almost nothing passes, and with margin 0 over a version that answers nothing it was promoted; the floor keeps such a version out (the shuffled-label control: shuffled labels never promote, both kinds). Discard a candidate not certified stale decisions after its freeze (3 000) or certified and not better trial decisions after it (default: stale) — decisions, not coin samples (1.4.0; before, 1 500 samples, at ρ ≈ 0.1 more decisions than a stream holds); the refreeze floor becomes refreeze × the live learner's labels (1.5). A discarded version's δ_v stays spent. Every version's certificate holds together under the budget, so the rule only affects utility, not validity.

The detector (opt-in, detector=RiskDetector(alpha=<the promised rate>), stage 2's class). Each sampled decision whose served version had a threshold in force, outside probation, feeds it the deployed loss as the Dispatcher's driver does (joint: answered alone and wrong; selective: wrong, fed only when answered alone; a missing label is wrong). On an alarm: a "stream" event "alarm" (R, the detector's n, why), the detector is reset, the served version's promise restarts (the next (v, δ_v) from the loop's budget at its first post-alarm sample, threshold +inf), and so does the candidate's, certified or not, its paired samples dropped: the alarm is evidence that the conditional loss moved, so a certificate earned before it is about another regime (seen in the stage-4 smoke: a candidate certified before a shift was promoted at the alarm, ℓ_s being 0, and served the moved world at a true risk above α). Each restart is a "restart" event (why "alarm"). A retired version keeps its certificate until it is rolled back to; a rollback after an alarm restarts it (a retired version reads no samples, so restarting it earlier would only spend δ). Probation opens: the next probation (300) decisions are not answered alone whatever the threshold (ρ = 1), and after that until the served version is certified again — the stricter of the two. Probation belongs to the question, not the version: a certified candidate is promoted at once (ℓ_s is 0 under +inf) but answers alone only after probation. A promotion or a rollback resets the detector.

Labels. Accepted by default: the trusted sources ("human", "outcome", "rule", "audit"; solvi.core.sources). A slow path's answer ("s2", or "verified") is refused (UntrustedLabel, before anything changes) unless s2_labels=True; with it the label is taken and recorded as "s2". The loop is not a Head a System's teach reaches. The oracle may return a Verdict(label, source, label_of) instead of a bare label: its source replaces step()'s and label_of (the stored id of the record that holds the label) is recorded. ticket_verdict(desk, resolved) reads one from a ticket resolved on a stage-3a TicketDesk (the agent's verdict: source "s2", so s2_labels=True; a person's: "human"; an expired or refused ticket: no label).

In the chain. Each decision is a record of kind "loop": "stream" (kept by a redaction) holds n, the served and candidate versions, ρ, sampled, alone, by, label_source, label_of, probation (at issue) and the decisions of it left, the served score and threshold, the candidate's shadow score, both promises' states, the detector's state and the live learner's labels; "loop" (not kept) holds the input, the would-be answers, the label and the answer. Each state change is a record of kind "stream" ({"event": "freeze" | "promote" | "discard" | "rollback" | "start" | "alarm" | "restart" | the promises' "grid" / "certified" / "loosened" / "recertify", "question", "version", "v_index", "delta_v", ...}); a freeze carries the frozen model's fingerprint, its decision and the labels it had seen. With versions_dir=, each frozen model is pickled as <versions_dir>/<version>.pkl. replay() re-runs the protocol from the records alone (the coin recomputed with the secret, the scores read from the records, the live learner replaced by its label count) and compares every decision — which version served it and the certificates' states — and every event; with versions_dir each pickle's fingerprint is checked and, with rescore=True, every recorded score is recomputed by the frozen model that gave it.

With system= a promoted or rolled-back version is installed as the question's answer head (solvi.core.versions.serve_head; version 0 puts back the head the System had when the loop was built, or removes it), so the System's fingerprint and every trace name it.

Since the adapter loop's stage 2 LearningLoop is stream.loop.AdapterLoop driven by DefaultPolicy with the constants above (lane_policy: every label trains — calib and holdout shares 0 —, no pre-freeze gates, no memorisation probe, no novel-risk bar, the refreeze floor, no budget limit, no alarm rollback) and the detector as its only alarm source (the lane's behaviour; AdapterLoop itself never takes the detector alone). Its records gain the decision's content key, split and wall clock, and a "train" event per freeze. The paired comparison counts only samples whose key the candidate never trained on; on streams without repeated inputs that is every sample, as before.

Not built here: the Dispatcher's loop= (the loop drives its own coin and oracle; a ticket's verdict reaches it through ticket_verdict). Unmeasured: the gain is unproven (solvi's prior evidence is against it); the stand (stage 4) measures it.

Verdict

Bases: NamedTuple

What an oracle may return instead of a bare label: the label (None: missing), its source (None: step()'s) and label_of — the stored id of the record that holds it (a ticket's), recorded with the decision.

LearningLoop

LearningLoop(learner, *, question, max_risk=None, max_error=None, delta=0.05, freeze_min=300, growth=2.0, stale=3000, trial=None, min_share=0.05, margin=0.01, refreeze=1.5, initial=None, detector=None, probation=300, s2_labels=False, source='human', secret=None, seed=0, sampling=None, promise_options=None, storage=None, versions_dir=None, system=None, feature='text', additive=True, max_layers=3)

Bases: AdapterLoop

See the module docstring. learner: the live Learner; question: the question's name (in the coin and the records); max_risk= / max_error=, delta: each version's StreamPromise (promise_options: its other keywords — grid, grid_from, bets ...); freeze_min, growth, stale, trial, refreeze: the protocol's constants; min_share, margin: the promotion rule (ℓ_k ≥ min_share and ℓ_k ≥ ℓ_s + margin); initial: version 0's frozen model (None: no model); detector, probation: a RiskDetector on the served version and the decisions escalated after its alarm; s2_labels: take slow-path labels; source: the default source of the oracle's labels; secret, seed: the coin's key and run; sampling: {"floor", "budget", "window"} of the rate; storage: a TraceStorage for the records (None: kept in memory for replay); versions_dir: where frozen models are pickled; system, feature: install the served version as the question's answer head (feature: the text fact a text model reads).

refreeze_floor property

refreeze_floor: float

refreeze × the live learner's labels at the latest discard (0 before any).

ticket_verdict

ticket_verdict(desk, resolved) -> Verdict

A ticket resolved (or expired) on a stage-3a TicketDesk → its Verdict, read from the stored dispatch record. desk: the TicketDesk (or its TraceStorage); resolved: what TicketDesk.resolve returned, or the record's stored id. The agent's verdict has source "s2" (the loop takes it only with s2_labels=True), a person's "human"; a ticket that expired or whose verdict the contract refused has no label.

lane_policy

lane_policy(*, freeze_min=300, growth=2.0, stale=3000, trial=None, min_share=0.05, margin=0.01, refreeze=1.5, s2_labels=False) -> DefaultPolicy

The lane LearningLoop's protocol as a DefaultPolicy: every label trains, every training freezes (the stream certificate decides), promotion on certified and ℓ_k ≥ min_share and ℓ_k ≥ ℓ_s + margin, discard stale decisions after the freeze uncertified or trial decisions certified (not coin samples), retrain at ≥ max(freeze_min, growth × the served version's labels, refreeze × the labels at the latest discard), no training budget, no alarm rollback.

solvi.experimental.stream.learner

What learns in the closed learning loop (experimental; stage 3b): the Learner protocol and two learners.

A Learner is the live model: it takes one oracle label at a time (update(x, y)), is never served, and gives a Frozen copy (snapshot()) that never changes again. A Frozen model scores an input → (its would-be answer, the guard signal) and has a fingerprint; LearningLoop (stream.versions) freezes, certifies and serves those copies.

  • HashedTextLearner — for text streams: hashed word 1–2-grams and character 2–5-grams (CRC-32 into 2^18 buckets, L2-normalised counts) and an online softmax (one SGD step per label, plain numpy, sparse weights); the score is the largest probability. Classes are the given options, or (options=None) every label seen so far, in order of first sight. Re-implemented from a published description; not tuned, unmeasured.
  • FastHeadLearner — for typed-state questions: solvi's own FastHead (the head System.fit builds) over facts; the first min_fit labels are kept and fitted once, every later one is FastHead.teach (a rank-one update; its refit schedule as System.fit's). The score is the head's largest probability. facts= turns an input into the facts row (system.facts_for), so the input can be a System's init state.

  • HashedTextTrainer — a batch learner (the stand-in for the LoRA learner of stage 3, no torch): train(job) fits a fresh HashedTextLearner on the job's rows (shuffled by the job's seed, epochs passes) and freezes it; every version is trained from scratch, never warm-started.

A batch learner has train(job: TrainJob) → Frozen (one training on job.rows, the rows the policy selected); the adapter loop (stream.loop.AdapterLoop) calls it when the policy asks for a training and calls snapshot() on an online learner (one without train). Its update may take key= and source= keywords (read once from its signature). The contract: train(job) trains on job.rows only, or the learner exposes keys() — every content key it has trained on (a learner that keeps the labels update gave it, or warm-starts from an earlier version). The loop records as the version's training keys the keys of the rows it handed over (or, online, of every label it fed) united with keys() when the learner has it; a sample on any of them is "seen", never "novel".

Threads (stage 3b): unless the loop runs with wait=True, a batch learner's train(job) runs on a thread of its own while the decision thread keeps calling update, seen and keys. So train(job) must read job only (or its own state under its own lock), and update / seen / keys must not wait for a training. wait=True restores the serial form (the training inside the step or the control).

Frozen.as_head(feature) wraps a frozen model as an answer head (solvi.core.Head: options, features, predict, contributions, fingerprint; fit and teach refused), which solvi.core.versions.serve_head installs on a System.

TrainJob dataclass

TrainJob(id: str, version: int, rows: tuple = (), hyper: dict = dict(), trigger: str = 'schedule', started: float = 0.0, state: str = 'running', why: str | None = None, fingerprint: str | None = None, seconds: float = 0.0, frozen: bool | None = None, calib: tuple = (), budget: Any = None, alpha: float | None = None, status: dict | None = None, cancel: Any = None)

One training the adapter loop runs. id: "."; version: the version it would become; rows: the selected train rows (stream.policy.LabelRow; empty for an online learner, which freezes a snapshot); hyper: the policy's settings (r, lr, updates, seed, ...); trigger: "schedule" (the policy's want_train) or "train_now"; started: the wall clock; state: "running", "done", "failed", "refused" or "stale"; why: the refusal or the error; fingerprint and seconds: the frozen model's and the wall time, once done; frozen: whether the pre-freeze gates passed. What the loop also hands a batch learner (stage 3): calib — the calib labels (stream.policy.LabelRow, the latest per key; never trained on: the LoRA learner runs act_guard on them); budget — the policy's Budget (the runner's threads, device and max_train_s); alpha — the loop's promised rate; status — the dict the loop's status()["job"] shows, which a runner updates in place (pid, log, device, eta, last line); cancel — a threading.Event the loop sets when it drops the training (close, an error stop): a runner that takes cancel= stops it.

FrozenError

Bases: TypeError

A frozen model was asked to learn.

FrozenText

FrozenText(classes, weights, bias, config)

A frozen copy of a HashedTextLearner (see the module docstring).

as_head

as_head(feature: str = 'text', options=None)

This version as an answer head reading the text fact feature.

HashedTextLearner

HashedTextLearner(options=None, *, lr: float = 0.5, n_features: int = 2 ** 18, words=(1, 2), chars=(2, 5))

See the module docstring. options: the closed set of answers (None: open, a class per label seen); lr: the SGD step; n_features: hash buckets; words / chars: n-gram ranges.

options property

options

Closed answer vocabulary, or None when new labels are allowed.

HashedTextTrainer

HashedTextTrainer(options=None, *, lr: float = 0.5, n_features: int = 2 ** 18, words=(1, 2), chars=(2, 5), epochs: int = 1)

See the module docstring: a batch learner over HashedTextLearner. options, lr, n_features, words, chars: as HashedTextLearner; epochs: passes over the rows (job.hyper["epochs"] overrides).

options property

options

Closed answer vocabulary, or None when new labels are allowed.

FrozenFast

FrozenFast(head, options, facts)

A frozen copy of a FastHeadLearner (None head: not fitted yet — it answers nothing, score -inf).

of_system classmethod

of_system(system, question)

The fitted answer head of a System's question, frozen (a copy) over the facts of its init state: version 0 of a LearningLoop that starts from System 1 (LearningLoop(initial=FrozenFast.of_system(system, q))).

as_head

as_head(feature=None, options=None)

This version as an answer head over the head's own facts (feature: unused, kept for one signature).

FastHeadLearner

FastHeadLearner(options, features=None, *, min_fit: int = 20, facts=None, lam=None, refit=2.0, refit_until=2000)

See the module docstring. options: the answers; features: the facts the head may read (None: every key of the first rows); min_fit: labels kept before the first fit; facts: input → facts row (None: the input is the row); lam, refit, refit_until: as FastHead.

for_system classmethod

for_system(system, question, features=None, **kw)

A learner for a System's question: its options, and its facts from the init state (system.facts_for).

solvi.experimental.stream.policy

The adapter loop's policy (run by AdapterLoop, stage 2): LoopPolicy, the abstract class whose hooks decide what the loop takes, when it trains, what it freezes, promotes and discards and what an alarm does; LoopState, what a hook reads; Budget; DefaultPolicy. Unmeasured.

DefaultPolicy's improvement signal reads coverage as well as error: with target_share=0.5 (the default) the served version is short when it answers alone on less than half of its last window held-out labels, or errs alone there above α. On error alone a weak but certified incumbent would never be retrained — certification keeps its error alone at most α, so it is short in coverage, not in error. The share is read on held-out labels, a selection-biased sample that is mostly deferred decisions, so it reads low (0.09 there against 0.30 on the whole stream in one smoke run whose script is not in the repository); a strong incumbent will usually be retrained too, and the promotion gates (the novel-only paired comparison, the memorisation probe, the novel-risk bar) keep a worse version out. target_share=None restores the error-only signal. Unmeasured; see experimental.

DefaultPolicy's stale and trial (default 3 000 each) count decisions since the candidate's freeze (LoopState.since_freeze), not coin samples — changed in 1.4.0. A candidate not certified stale decisions after its freeze, or certified and not promotable trial decisions after it, is discarded, and training can start again. At a sampling rate of 0.08–0.17 the old 1 500 samples were 9 000–18 000 decisions, so a stalled candidate blocked training for a whole stream. 3 000 leaves room to certify: the grid opens 200 decisions after the freeze and a point with 0–1 % risk needs about 120–280 samples at 6–12 decisions per sample (arithmetic from the certificate's constants, not measured). The clock runs from the freeze; an alarm's restart does not reset it.

The policy of the adapter loop: the abstract class a developer controls the loop with, the state its hooks read, the budget, and the out-of-the-box policy (experimental; the LoRA learning loop, stage 1; stream.loop.AdapterLoop runs it, stage 2).

from solvi.experimental.stream import Budget, DefaultPolicy, LoopPolicy, LoopState

policy = DefaultPolicy(budget=Budget(per_day=6, max_train_s=900))
policy.split(st, key)                 # "train" | "calib" | "holdout": by the content key, fixed forever
policy.want_train(st)                 # growth, the improvement signal, the budget; why_not_train(st) says why not
policy.freeze(st, report)             # the pre-freeze gates on held-out labels (freeze_gates(st, report): each one)
policy.promote(st, paired)            # certified, ≥ 100 novel samples, min_share, margin, the memorisation probe,
                                      # the novel-error bound

LoopPolicy is the abstract class: every hook reads a LoopState (a frozen snapshot the loop rebuilds per call: decisions so far, the served version and the candidate, label counts by split, the versions table, the served version's latest held-out outcomes, alarms, trainings started, the wall clock, paused, the mode) and returns a plain decision. A hook that raises stops the loop (status "error") and the served version keeps serving. A policy keeps its own counters in self and must pickle (the loop's checkpoint saves it).

DefaultPolicy (each number a keyword):

  • accept — a label from the trusted sources ("human", "outcome", "rule", "audit"); "s2" / "verified" only with s2_labels=True.
  • split — stream.gates.split: sha256 of the content key → 70 / 15 / 15 train / calib / holdout.
  • want_train — no candidate in trial, no training in progress, not paused; train labels ≥ first (300) and ≥ growth (1.5) × the largest n_train of any version so far (discarded ones included: a discarded candidate is not retrained on nearly the same labels; with refreeze given instead, the lane LearningLoop's rule: ≥ growth × the served version's n_train and ≥ refreeze × the train labels the loop had at the latest discard); the budget allows one now; and the improvement signal (gates.incumbent_short): on its last window (200) held-out labels the served version answers nothing alone, or errs alone above the promised α, or answers alone on less than target_share (0.5; None: off) of them. Why the share: a certified incumbent keeps its error alone ≤ α, so with the error alone as the only signal a weak but certified incumbent — short in coverage, not in error — is never retrained (one smoke run, its script not in the repository, solvi-base on Banking77: error alone 0.000, share alone 0.090 from about decision 960 to 2 000, no training). The share is read on held-out labels, a selection-biased sample (labels come mostly from deferred decisions), so it reads low (0.09 there against 0.30 on the whole stream in that run), and a strong incumbent will usually be retrained too; the promotion gates (the novel-only paired comparison, the memorisation probe, the novel-risk bar) are what keep a worse version from being served. Unmeasured: the stand will measure the default. target_share=None restores the error-only signal. The signal is read only once the window holds min(min_holdout, window) outcomes of the served version: fewer (the window restarts at a promotion or a rollback) is "no signal yet", not "short", so a new served version is not retrained before it was measured (version 0 without a model fills the window with outcomes answered by nobody, so it is short as soon as the window is full; with holdout=0 there is no window and the signal reads short). With the pre-freeze gates on, a training also waits for the labels those gates need — ≥ min_holdout held-out labels and ≥ the calib labels the calib threshold needs (min_calib; gates.calib_min, 73 at α = 0.05) — since a training with fewer is refused at birth. These are accepted labels, not decisions. For fresh distinct keys and stationary acquisition, the rough total accepted-label requirement is max(T / (1 - calib - holdout), C / calib, H / holdout), where T is the current train floor, C = calib_floor(alpha), H = min_holdout; omit a zero-share split only when its required floor is zero. Defaults at alpha=0.05 give max(300/0.70, 73/0.15, 100/0.15), about 667 accepted labels (about 467 train labels in expectation). Hash-split fluctuations, repeated keys, maturity and improvement-signal gates, and budget limits can delay it further. To estimate decision cost, divide by the measured accepted-labels/decision rate on the relevant stream/window, not by an assumed coverage formula: escalation, coin sampling, missing/refused outcomes and changing traffic all affect that rate. At rate 0.17 the floors alone suggest roughly 3922 decisions; this is an illustration, not a timing guarantee or a promise to train within 2400 decisions. policy.why_not_train(loop._state()) reports the first currently blocking gate, not all blockers or an ETA. train_now() can bypass scheduling floors but still pays training/budget costs and can fail the unchanged post-training freeze gates. No safety floor is reduced to force a run.
  • select — one row per content key (the latest label wins), then a class-balanced sample of ≤ budget.max_examples of them, half from the latest 2 × the served version's n_train rows; seeded by the next version number, so the same rows give the same selection.
  • hyper — r 8, lr 3e-4, updates = clamp(⌈2 n / 8⌉, 200, 3000) (n: the train labels, ≤ max_examples), seed = the next version number, warm_start False (every version is trained from the base checkpoint).
  • freeze — on the held-out labels: ≥ min_holdout (100) of them and (alone & right − alone & wrong) / n ≥ the served version's + min_gain (0.01); act_guard found a threshold; no honesty number worse by more than tolerance (0.02); the training within budget.max_train_s; in label mode also the paired held-out gain's Wilson lower bound > 0. pre_freeze=False freezes every training (the lane LearningLoop's protocol: the stream certificate alone decides); refused in label mode, where the gates are the only measurement before a version is served.
  • promote — the candidate certified, ≥ min_novel (100) post-freeze samples on keys it never trained on, on those share_k ≥ min_share (0.05) and share_k ≥ share_s + margin (0.01) (share_s: the served version certified the same way on the same samples, Paired), and the memorisation probe passes (error alone on novel − on seen ≤ gap, 0.10). The candidate must have ≥ probe_min (30) alone answers on novel samples: a thin novel side is the memoriser's signature (it answers the items it trained on and abstains on the rest), so an unmeasured probe does not promote. The errors are compared once the seen side has ≥ probe_min alone answers too (fewer alone answers on seen keys is not memorising). And the candidate's error on novel samples is within the promise: the Wilson upper bound (at wilson, 95 %; core.store.sysreport.wilson) of wrong_novel / n_novel ≤ α (st.alpha; the joint risk on keys it never trained on — a memoriser is valid on the pool because its trained items dilute the risk; author's decisions 2026-10-23; novel_risk=False drops it). A point estimate looked at on every decision passes a candidate above α by chance (at a true novel risk of 6.4 % in more than half of simulated 1 000-sample trials); the bound holds that near the rate the confidence names (about 5 % of candidates at 5.5 %, 1 % at 6.4 %) and costs some candidates just under α (at 3 % about 6 % are not promoted within 1 000 novel samples). Two limits: the count is at the thresholds in force now, which loosen during a trial, and it is looked at on every decision, so the bound is a stand-in for a fixed-sample test, not an anytime guarantee; the rate of false promotions it allows is what the shuffled-label control of a stand reads. probe=False drops the probe (promotion and discard). Label mode (no paired samples): the pre-freeze gates decided, promote. The novel-risk bar is a joint ratio (wrong alone over every novel sample, alone or not): it never asks whether the alone answers are right. Additive mode (decision D1): five checks — certified, novel, novel_risk, probe and, with the loop's usefulness certificate on (default), useful: the candidate's selective certificate at β (AdapterLoop(useful_error=0.5)) holds at its certified threshold, so a layer that is wrong on most of the few answers it gives alone (a layer trained on noise, whose scores collapse) never starts serving; no min_share and no margin. A certified candidate that is not useful by trial decisions after its freeze is discarded with "useful" among the failed checks.
  • discard — (probe on) the probe shows the gap beyond noise (Wilson lower bound of the novel error − Wilson upper bound of the seen error > gap, at wilson confidence; a point-estimate gap at n = 30 does not discard); not certified stale (3000) decisions after its freeze; certified and not promotable trial (3000) decisions after its freeze (LoopState.since_freeze). Both clocks count decisions, not coin samples (author's decision 14, 2026-10-24): at a rate ρ ≈ 0.08–0.17, 1 500 samples were 9 000–18 000 decisions, so a certified candidate that never cleared the margin stayed in trial for a whole 12 000-decision stream and no later training started. 3 000, not 1 500: the grid opens 200 decisions after the freeze and a 0–1 %-risk point certifies after about 120–280 samples (δ_v of the 2nd–4th version) at 6–12 decisions per sample, i.e. 900–3 600 decisions after the freeze; 1 500 would discard a zero-risk candidate at 12 decisions per sample (≈ 1 700), 3 000 lets a 1 %-risk point of the first candidate certify at any of these rates (≤ 2 840) and the 2nd–4th up to 10 decisions per sample. The clock runs from the freeze: an alarm's restart drops the paired samples but does not restart it.
  • maturity gate (mature_patience, "auto": 150 in additive mode, off in replacement mode; an int: on in both; None: off) — no training while the gated certificate (the deepest layer in additive mode, the served version otherwise) is still loosening: a "certified" / "loosened" event within its last mature_patience coin samples, or its first uncertified grid point's log-wealth set a new running maximum within them (it is still climbing). Freezing a threshold that would still loosen gives up coverage the version would have earned (in additive mode the attach freezes the deepest layer's routing threshold Λ; its answer threshold keeps loosening, so what an early attach changes is who answers, not the coverage — kept as pre-registered). Overrides: an alarm on that version since the latest freeze (drift response unchanged: alarm → restart → train), or ≥ backlog_max (None: 2 × first, 600) accepted labels since the latest freeze (the labels are paid for). The label floors and the budget still apply after it. The gate's inputs and the reason it opened (maturity_gate(st)["trigger"]: "mature" / "alarm" / "backlog") are in why_not_train and in the loop's "train_start" / "train" events ("gate"). On by default in additive mode only: in replacement mode it changes when trainings start, and replacement records stay as before unless asked (DESIGN_DELTA_CADENCE §3).
  • alarm — "recertify"; a second alarm on the current serving of the served version (alarms at n ≥ served_since) within probation (300) decisions → "rollback:", v the highest retired version below the served one with no alarm on record (the versions rolled back from were alarmed); no such version → "recertify".
  • watch — label mode only, from a promotion until the served version changes again: on each calib or held-out label the served version and the version served before it are scored on the same input (+1 alone and right, −1 alone and wrong, 0 not alone, each at its own threshold); after ≥ watch_min (100) such labels the served version is rolled back when an anytime-valid e-process on the discordant labels (Mixture(0.5) fed 1 when the served version wins one, 0 when the target does) reaches wealth 1 / (1 − wilson), the target won more of them, and the margin per label is ≥ min_gain (watch_rollback; watch=False: off). P(a false rollback) ≤ 1 − wilson per promotion at any horizon (Ville); simulated, not a stand: 0.8–2.1 % false rollbacks within 3 000 watched labels, a served version truly worse (p = 0.6, d = 0.1) caught in 70 % of runs by then. The base LoopPolicy.watch returns False (opt-in).

Unmeasured: no stand has run on this policy; its numbers are the design's, not tuned.

Budget dataclass

Budget(max_trainings: int | None = None, per_day: int = 24, min_interval_s: float = 600.0, max_train_s: float = 1800.0, cpu_threads: int = 4, device: str = 'auto', free_gpu_mb: int = 3000, max_examples: int = 20000, max_versions_kept: int = 10)

What trainings may cost. max_trainings: over the loop's life (None: no cap); per_day: trainings per 24 h; min_interval_s: between two trainings; max_train_s: one training (estimated before it starts; refused if above; the runner stops a training at its estimate + the runner's grace_s, which must cover what the estimate leaves out: loading the checkpoint, calibration and saving); cpu_threads: torch threads of the runner on a CPU; device: "auto" (cuda when present and ≥ free_gpu_mb free, else cpu), "cpu", "cuda" or "cuda:"; max_examples: rows per training; max_versions_kept: soft retention target for served/retired version-table rows (version 0 counted), not a memory cap. Eligible oldest retired rows are released; their files remain. Version 0, current served and rollback target are protected, so three protected rows may exceed a smaller target. Additive layers are excluded and bounded separately by max_layers (base included); a resident candidate is excluded too. status()["resident_versions"] inventories version-table model references across states, not bytes or unique model/tensor storage. per_day=0 or max_trainings=0 means "never train"; max_trainings counts failed trainings too.

refuse

refuse(started, now: float, estimate_s: float | None = None) -> str | None

Why a training may not start now, or None. started: the wall-clock start times of the trainings so far; estimate_s: the estimated seconds of this one (None: not estimated yet). per_day is a rolling 24 h window (now − t < 86 400 s), no calendar day, no time zone. A start time after now (a clock set back, a checkpoint restored on another machine) counts towards max_trainings but not the window or the interval.

VersionInfo dataclass

VersionInfo(version: int, state: str, n_train: int = 0, samples: int = 0, certified: bool = False, threshold: float = math.inf, fingerprint: str | None = None, frozen_at: int | None = None, train_keys: frozenset = frozenset(), discarded_at: int | None = None, layer: int | None = None, routing_thr: float | None = None, learning: bool | None = None, useful: bool | None = None, useful_at_answer: bool | None = None, useful_thr: float | None = None)

One row of the versions table. state: "served", "candidate", "retired", "discarded" or "evicted" (a retired version past Budget.max_versions_kept: released, no longer a rollback target); n_train: the train labels it was trained on (version 0: 0 unless stated); samples: post-freeze samples it has read; certified and threshold: its promise now; frozen_at: the decision it was frozen at (None for version 0); train_keys: the content keys it trained on, a set snapshotted at the freeze (not a digest: novel / seen is membership, key in train_keys, for every post-freeze sample; the learner's key list grows after the freeze and must not be read live). A list or set given is stored as a frozenset. discarded_at: the train labels the loop had when this version was discarded (None: not discarded) — the lane LearningLoop's refreeze floor reads it. Additive mode with the usefulness certificate on (AdapterLoop(useful_error=)): certified / threshold are the version's own certificate's (λ_J), useful whether the usefulness certificate holds at λ_J (the joint point, what the start gate's "useful" check reads), useful_at_answer whether it holds at the composed answer point useful_thr, the threshold it answers at (composed; +inf: no point certified by both).

LoopState dataclass

LoopState(n: int = 0, served: int = 0, candidate: int | None = None, labels: dict = (lambda: {s: 0 for s in gates.SPLITS})(), versions: tuple = (VersionInfo(0, 'served'),), holdout: tuple = (), alpha: float = 0.05, alarms: tuple = (), served_history: tuple = (0,), served_since: int = 0, trainings: tuple = (), job: dict | None = None, now: float = 0.0, paused: bool = False, mode: str = 'stream', promises: dict = dict(), detector: dict | None = None, keys: dict | None = None, layers: tuple | None = None, deepest: int | None = None, deepest_certified: bool | None = None, zone_share: dict | None = None, maturity: dict | None = None, useful_error: float | None = None)

What a hook sees, rebuilt by the loop for every call (changing it changes nothing in the loop). n: decisions so far; served / candidate: version numbers (candidate None: none in trial; since_freeze: the decisions since the candidate's freeze); labels: label counts by split; versions: the versions table; holdout: the served version's [(alone, wrong)] on its latest held-out labels, oldest first; alpha: the promised level; alarms: [{"n", "who", "version"}] so far; served_history: the versions served, in order (a rollback appends); served_since: the decision at which the current serving of served began (a promotion or a rollback sets it); trainings: the wall-clock start times of the trainings so far; job: the training in flight ({"id", "started", "eta"}) or None; now: the wall clock; paused; mode: "stream" (a Dispatcher, the stream promise) or "label" (a System alone: the pre-freeze gates only); promises, detector: their state dumps, for a policy that reads them; keys: the distinct content keys with a label, by split (a relabelled key counts once, as the pre-freeze report's latest label per key; None: a state built without them, labels stands in). maturity: the inputs of DefaultPolicy.maturity_gate — version (the deepest layer in additive mode, else the served version), samples (its promise's samples read), changed_at (the samples at its latest "certified" / "loosened" event since its latest restart; None: none), peak_at (StreamPromise.peak_at), last_freeze (the decision of the latest training's freeze or birth discard, 0: none), labels_since_freeze (accepted labels after it), alarm (an alarm on that version after it); None in label mode or when that version has no promise.

stream.loop.AdapterLoop passes copies of the dict fields and resets holdout at a promotion or a rollback (the new served version does not inherit the old one's errors). The state has dict fields, so hash(st) raises: do not use states as keys.

since_freeze property

since_freeze: int | None

Decisions since the candidate was frozen: n − its frozen_at (None: no candidate, or a candidate row built without frozen_at). DefaultPolicy's stale / trial clocks read it.

LabelRow dataclass

LabelRow(key: str, x: Any, y: Any, source: str, t: int)

One stored label: the input's content key, the input, the label, its source, the decision it came at.

TrainReport dataclass

TrainReport(n_holdout: int, right: int, wrong: int, served_right: int, served_wrong: int, better: int = 0, worse: int = 0, threshold: float | None = None, honesty_before: dict = dict(), honesty_after: dict = dict(), seconds: float = 0.0, n_train: int = 0, items: tuple = ())

What a training produced, scored on labels the candidate never trained on. n_holdout: held-out labels asked; right / wrong: the candidate's answers alone and right / wrong on them, served_right / served_wrong the served version's; better / worse: held-out labels where the candidate's item score (+1 alone and right, −1 alone and wrong, 0 escalated) beats / trails the served one's; threshold: act_guard's on the calib split (None: none found at the promised risk; in stage 2 a fixed-set stand-in, while the served version answers at its stream threshold, so the held-out comparison sets two kinds of threshold side by side); honesty_before / honesty_after: the served version's and the candidate's solvi.testing.honesty numbers on the held-out labels; seconds: the training's wall time; n_train: rows trained; items: optional per-label scores ((key, candidate score, served score), each +1 / −1 / 0) for a policy that runs its own paired test (McNemar, bootstrap); empty when the loop does not provide them.

Paired dataclass

Paired(n_novel: int, alone_novel: int, wrong_novel: int, alone_served: int, n_seen: int = 0, alone_seen: int = 0, wrong_seen: int = 0, wrong_served: int = 0, alone_served_own: int | None = None, wrong_served_own: int | None = None, thr_s: str | None = None)

The candidate against the served version on the candidate's post-freeze samples (stream mode). Novel: samples whose key is not in the candidate's train_keys — n_novel of them, alone_novel / wrong_novel the candidate's answers alone / alone and wrong there, alone_served / wrong_served the served version's on the same novel samples at the threshold of its comparison certificate (1.4.0: a StreamPromise built on exactly the candidate's samples with the same grid rule and the candidate's δ_v; it only ranks, it never serves) once that certificate is certified, and at the served version's own threshold while it is not (thr_s: "cmp", "own" or "no_model" — a served version without a model never answers alone), alone_served_own / wrong_served_own at the served version's own threshold in force now (the comparison before 1.4.0, kept for the records; None when not counted). Seen: the samples whose key it trained on — n_seen, the candidate's alone_seen / wrong_seen — read only by the memorisation probe. A candidate with no sample yet is Paired(0, 0, 0, 0), not None.

Exact-key identity: a paraphrase of a trained item counts as novel, and calib keys (the threshold was fitted on them) recur as novel — a small optimism on share_k.

share_s_own property

share_s_own: float | None

The served version's share alone at its own threshold (the old comparison); None when not counted.

Watch dataclass

Watch(target: int, n: int = 0, better: int = 0, worse: int = 0, total: int = 0, log_e: float = 0.0)

Label mode, after a promotion: the served version against the version served before it (target, the rollback target) on the same labels since the promotion — calib and held-out labels only (keys no version trained on). Each label scores each version +1 (answered alone and right at its own threshold), −1 (alone and wrong) or 0 (not alone). n: the labels compared; better: those where the target scored higher; worse: those where the served version scored higher; margin: Σ (target − served) / n (0.0 with n = 0). log_e: the log wealth of the watch's e-process (watch_eprocess(), a Mixture(0.5) fed loss 1 when the served version wins a discordant label and 0 when the target wins), 0.0 before the first discordant label.

LoopPolicy

LoopPolicy(budget: Budget | None = None)

Bases: ABC

See the module docstring. Subclass and give every hook; budget (a Budget) is read by the loop too.

budget property writable

budget: Budget

The Budget (the defaults when none was set, also for a subclass whose init skips super().init).

sampling_rate

sampling_rate(st: LoopState, base_rate: float) -> float

Predictable uniform coin rate from past state only; legacy default unchanged.

accept abstractmethod

accept(st: LoopState, x, y, source: str) -> bool

Take this label at all.

split abstractmethod

split(st: LoopState, key: str) -> str

"train" | "calib" | "holdout" for a content key; the same key must always get the same split.

want_train abstractmethod

want_train(st: LoopState) -> bool

Ask for a training now.

select abstractmethod

select(st: LoopState, rows) -> list

The train rows (LabelRow) that go into this training.

hyper abstractmethod

hyper(st: LoopState) -> dict

The training's settings: r, lr, updates, seed, ...

freeze abstractmethod

freeze(st: LoopState, report: TrainReport) -> bool

Freeze the trained model as the candidate (the pre-freeze gates on labels it never trained on). In label mode this is the only measurement before a version is served (the candidate is promoted on the next label, and only the watch after it can roll it back): a freeze that measures nothing serves every training.

promote abstractmethod

promote(st: LoopState, paired: Paired | None) -> bool

Serve the candidate now (paired None in label mode; in stream mode a candidate with no sample yet gets Paired(0, 0, 0, 0), not None).

discard abstractmethod

discard(st: LoopState, paired: Paired | None) -> str | None

Why the candidate is discarded now, or None to keep trialling (paired as for promote).

alarm abstractmethod

alarm(st: LoopState, who: str, report: dict) -> str

An alarm on the served version (who: "detector" or "monitor") → "recertify", "rollback:" or "ignore".

watch

watch(st: LoopState, w: Watch) -> bool

Label mode: roll the served version back to w.target now? Called on each calib or held-out label while a watch runs (from a promotion to the next change of the served version). This default returns False: a custom policy has no automatic rollback unless it defines this hook (e.g. return watch_rollback(w), the DefaultPolicy rule). The loop keeps the watch's counts either way (`status()["watch"]).

DefaultPolicy

DefaultPolicy(budget: Budget | None = None, *, s2_labels: bool = False, calib: float = 0.15, holdout: float = 0.15, first: int = 300, growth: float = 1.5, window: int = 200, target_share=0.5, min_gain: float = 0.01, min_holdout: int = 100, tolerance: float = 0.02, wilson: float = 0.95, min_novel: int = 100, min_share: float = 0.05, margin: float = 0.01, gap: float = 0.1, probe_min: int = 30, stale: int = 3000, trial: int = 3000, probation: int = 300, r: int = 8, lr: float = 0.0003, min_updates: int = 200, max_updates: int = 3000, refreeze=None, probe: bool = True, pre_freeze: bool = True, novel_risk: bool = True, min_calib: int | None = None, watch: bool = True, watch_min: int = 100, novel_only: bool = True, mature_patience='auto', backlog_max: int | None = None, acquisition: dict | None = None)

Bases: LoopPolicy

See the module docstring for each hook. budget: a Budget (None: the defaults); s2_labels: take slow-path labels; calib / holdout: the split's shares; first, growth: the train labels before the first / a next training (absolute, × the served version's n_train); window, target_share: the improvement signal (target_share 0.5: also short when it answers alone on less than half its held-out labels; None: the error-only signal); min_gain, min_holdout, tolerance: the pre-freeze gates; wilson: the confidence of the Wilson bounds (label mode's paired gain, the probe's discard test); min_novel, min_share, margin: the promotion rule; gap, probe_min: the memorisation probe; stale, trial: the decisions after its freeze at which a candidate not certified / certified and not promotable is discarded (decisions, not coin samples); probation: two alarms closer than this roll back (0: never); r, lr, min_updates, max_updates: the training's settings; refreeze: the lane LearningLoop's retrain floor instead of the largest n_train (None: off); probe: the memorisation probe on (False: off, promotion and discard); pre_freeze: the pre-freeze gates on (False: every training is frozen); min_calib: the calib labels a training waits for (None: the fewest the calib threshold needs at α, 73 at α = 0.05; 0 for a learner with its own threshold); novel_risk: promotion needs the Wilson upper bound (at wilson) of wrong_novel / n_novel ≤ α (False: off); watch, watch_min: label mode's watch after a promotion (False: off; the labels it needs before it may roll back); novel_only: the promotion's paired comparison counts only samples on keys the candidate never trained on (False: every sample, its train keys too — for controls; weakens the guarantee: a memoriser's trained items then count for it). In label mode pre_freeze=False is refused by the loop: there the pre-freeze gates are the only measurement before a version is served. mature_patience, backlog_max: the maturity gate (see the module docstring).

acquisition_status

acquisition_status() -> dict | None

Conservative worst-case extra oracle reservations; refused/duplicate labels still cost a reservation.

why_not_train

why_not_train(st) -> str | None

First currently blocking gate, or None when want_train says yes.

Not an ETA or a complete list: fixing this blocker may expose the next. Labels are accepted outcomes, not decision counts; distinct-key floors and observed acquisition rates determine how slowly the gate can be reached.

maturity_gate

maturity_gate(st) -> dict | None

The maturity gate on st (see the module docstring): None when off (mature_patience None, "auto" in replacement mode, label mode, no gated promise), else its inputs and trigger — "mature", "alarm" (override A), "backlog" (override B) or None (closed: no training).

calib_floor

calib_floor(alpha) -> int

The calib labels a freeze needs: min_calib, or (None) gates.calib_min(alpha, wilson), the fewest with which the calib threshold can exist (0: the learner brings its own threshold).

select

select(st, rows) -> list

One row per content key — a relabelled input keeps only its latest label (by t; on a tie the later row) — then the class-balanced, half-recent sample (see the module docstring).

hyper

hyper(st) -> dict

updates from the train label count capped at max_examples — an approximation of the rows select returns (it does not see them, and a relabelled key counts once there). Seeded by the next version number: a retry after a failed training is the same training (deterministic on purpose).

freeze_gates

freeze_gates(st, report: TrainReport) -> dict

Each pre-freeze gate's result → {"heldout", "act_guard", "honesty", "time"[, "paired_gain"]}, each with "ok" and "why".

promote_checks

promote_checks(st, paired: Paired) -> dict

Each promotion condition → {"certified", "novel", "min_share", "margin", "novel_risk", "probe"}, each with "ok" (novel_risk / probe only when on). The probe passes only with ≥ probe_min alone answers on novel samples (an unmeasured novel side does not promote). Additive mode (st.layers set): the additive gate (decision D1) — certified, novel, novel_risk, probe; no min_share and no margin (nothing to compare with: a layer serves only the zone the layer above escalates); with the loop's usefulness certificate on (st.useful_error set) a fifth check, "useful": the candidate's usefulness certificate (selective error among its alone answers ≤ β, anytime-valid on its own δ budget) holds at its certificate's threshold in force λ_J — a layer whose alone answers are not shown to be right more often than β allows never starts serving.

watch

watch(st, w) -> bool

Label mode: watch_rollback(w, min_n=watch_min, confidence=wilson, min_gain=min_gain) (the e-process at level 1 − wilson); never with watch=False.

rollback_target

rollback_target(st) -> int | None

The highest retired version below the served one with no alarm on record, or None. Conservative: any alarm on record excludes a version, also one on an earlier serving that was recertified and then served well.

watch_eprocess

watch_eprocess()

The watch's e-process: Mixture(0.5) (stream._eprocess), the bet against "the served version wins at least half of the discordant labels". The loop feeds it loss = 1 when the served version scores higher on a calib or held-out label, 0 when the target does (concordant labels are not fed); its wealth is a test supermartingale while the served version is not worse.

watch_rollback

watch_rollback(w: Watch, *, min_n: int = 100, confidence: float = 0.95, min_gain: float = 0.01) -> bool

The watch's rule: the served version is shown worse than the target on the labels since its promotion — ≥ min_n labels compared, the e-process's wealth ≥ 1 / (1 − confidence) (w.log_e, watch_eprocess(): 20 at 0.95), better > worse, and the margin (target − served, per label) ≥ min_gain. Anytime-valid: the e-process is a test supermartingale while the served version wins at least half of the discordant labels, so by Ville's inequality P(a rollback ever, at any horizon) ≤ 1 − confidence per promotion when the served version is not worse on the discordant labels; the other conditions only make a rollback rarer.

Simulation, not a stand (2 000 runs per cell; a watched label discordant with probability d ∈ {0.1, 0.3, 0.5}, a discordant one won by the target with probability p, steps 1 or 2): false rollbacks with both versions equally good (p = 0.5) 0.4–1.4 % within 300 watched labels, 0.5–1.9 % within 1 000, 0.8–2.1 % within 3 000; a served version truly worse (p = 0.6, d = 0.1) rolled back in 10 / 28 / 70 % of runs by 300 / 1 000 / 3 000 watched labels.

solvi.experimental.stream.loop

The adapter loop (stage 2): AdapterLoop, the lane's loop driven by a LoopPolicy — labels split by content key, online or batch learners, promotion on samples whose key the candidate never trained on with the memorisation probe and a Wilson bound on the error there, the RiskDetector OR-ed with a score monitor, controls; a hook that raises after the state changed stops the loop (status "error") with the decision recorded. Stage 3: a batch learner's job also carries the calib labels, the budget, α and the live job status; a training refused by its time estimate is recorded as "refused", a runner that dies stops the loop (status "error", replay exact). Stage 3b: deferred apply — a batch learner's training runs in a thread of its own (its runner beside it) and step / train_now return at once; the loop goes on deciding on the served version, and the result is applied on the first decision after it is in (gates, then freeze or discard, a failure, a refusal or a stop), recorded there (started_at, applied in the "train" event) so that replay() applies it at the same place without reading a clock. wait=True (the constructor's, or train_now(wait=True)) keeps the blocking form; close() cancels a training in flight; wait_training(timeout) waits for a result. Lock order: the part's version lock, then the loop's (no deadlock with a decision of the part that reaches the loop). Budget.max_versions_kept evicts the oldest retired versions ("evict" events, release() called), never the served one, the rollback target or version 0. A result whose training saw the served version change (a rollback) is recorded "stale" and discarded, not gated on a comparison with a version no longer served (served_at_start in "train_start" and "train"). A batch learner's train(job) runs on another thread than update, seen and keys: it must read the job only (or its own state under its own lock). Stage 4: save(dir) / AdapterLoop.load(dir, learner, ...) and cancel_training() (see stream.checkpoint). Stage 5: attach. AdapterLoop.attach(host, learner=None, *, question=None, dir=None, policy=None, initial="auto", part=None, **kw) builds a loop and attaches it — to a Dispatcher (stream mode: every ask is one decision of the loop) or to a System alone (label mode, mode="label": teach / outcome call label(x, y); no coin, no promise, no alarm; a version serves at its own act_guard threshold; a frozen candidate is promoted when it has that threshold and policy.promote(st, None) says so — the promote() control and the automatic promotion check the same; DefaultPolicy( pre_freeze=False) is refused, since the pre-freeze gates are the only measurement before a version is served; status()["guarantee"] is "fixed-set (act_guard on calib labels); no anytime certificate"). Label mode's watch: from a promotion until the served version changes again, each calib or held-out label scores the served version and the one served before it on the same input (+1 alone and right, −1 alone and wrong, 0 not alone); policy.watch(st, Watch) (DefaultPolicy: watch_rollback — ≥ watch_min (100) labels, the e-process policy.watch_eprocess() (a Mixture(0.5) fed 1 when the served version wins a discordant label, 0 when the earlier one does) at wealth ≥ 1 / (1 − wilson), better > worse, and the margin per label ≥ min_gain; the base LoopPolicy.watch returns False: opt-in) returns True to roll back to the earlier version: a "rollback" event with by: "policy", why "watch: …" and the counts under watch, replayed from the recorded scores; status()["watch"] shows the counts and the e-process's log wealths (lw; Watch.log_e), saved by the checkpoint. Anytime-valid: P(a false rollback) ≤ 1 − wilson per promotion at any horizon (Ville); simulated, not a stand: false rollbacks with both versions equally good 0.4–1.4 % within 300 watched labels, 0.5–1.9 % within 1 000 and 0.8–2.1 % within 3 000; a served version truly worse (it wins 40 % of the discordant labels, 10 % of the labels discordant) rolled back in 10 / 28 / 70 % of runs by those horizons, a truly better one in ≤ 0.2 %; watched labels are the calib and held-out ones, about 30 % of all labels at the default split. One more scoring per calib or held-out label while it runs. Without a learner it is a LoraLearner on the question's decision part (dir= required). loop.attach_to(host) attaches a loop built by hand; Dispatcher(..., loop=loop) calls it. detach() cancels a training in flight, puts version 0 back on the System, removes the hooks and closes the loop ("detach" event, replayed). serving(v): version v installed for the duration (the Dispatcher's replay). Refused: a question answered by a combination or a part that is a member of one, a Dispatcher with its own promise=, a second loop on a System or a Dispatcher, start / complete with a loop (use ask), a stream-mode attach whose DefaultPolicy refuses the slow path's labels (the slow path's label_source attribute, "s2" when it has none) — the loop would have no label source and every decision would escalate: give s2_labels=True, a trusted oracle as the slow path (its Thoughts carry {"oracle": {"label_source": "human"}}), or use label mode; refused before any state is set; at run time the labels the policy refuses are counted (status()["labels"]["refused"]) and warn_refused (200) of them in a row with none accepted warn once — and, while a loop serves a part, a Cascade, Vote or Route built over it (refused at construction until detach()). In stream mode the decision is split around the dispatch: the loop reads it (scores, coin, whether its rule answers alone) before System 1 is asked and takes its step after, with the slow path's accepted answer as the label — neither inside the part's call. A Dispatcher's loop decisions run one at a time under its own lock, taken before the part's and the loop's and never while either is held (order: dispatcher → part → loop), the slow path's call included: throughput ≤ 1 / the slow path's latency (measured once on a stand-in: 40 decisions in four threads with a 50 ms slow path, 3.7 × as long as without a loop). The controls take the same lock first: a control waits for the decision in flight. The candidate is scored in shadow only while its grid is not fixed and on coin-sampled decisions (shadow is None in the record otherwise). The dispatch escalates what the loop's rule does not answer alone and checks what its coin draws; each Dispatched records learning (the loop's decision number, the version served and its fingerprint, the candidate, the coin, whether the loop's rule answered alone, the label it took, its events); Dispatcher.replay / replay_all replay each decision with its version installed. A label whose source the policy refuses is a missing label for the loop (the default policy refuses the slow path's "s2" unless s2_labels=True). A loop that stops or fails leaves the dispatch as it would be without it (learning: {"stopped": ...} or "error"). teach in stream mode only stores the correction; without storage a UserWarning says it is lost. Unmeasured.

Additive coverage (experimental): AdapterLoop(..., additive=True, max_layers=3) — a certified candidate serves the zone the served chain escalates instead of replacing it. Routing over the chain of layers by frozen routing thresholds Λ_j (fixed zones, one owner per decision); the first layer on the path, from L0 down, at or above its live λ_j answers alone (an upstream layer inside a deeper zone where that layer escalates; nobody in a trial zone), else the oracle; every layer keeps learning on coin samples of its zone; attach below a certified deepest layer, trial on every zone decision, DefaultPolicy's additive gate, max_layers cap ("train_refused"), one RiskDetector per layer, rollback(j) detaches layer j and the deeper ones. The guarantee is per zone; with max_risk= the stream-wide joint risk is bounded by α·(1 + Σ_{j≥1} P(Z_j)) (status()["zones"]). Records: owner, layer, zone, path, trial_zone, answered_by, answer_layer, answer_thr, base, rho_base, path_would; checkpoint format v3. Semantics: experimental, "Additive coverage".

The adapter loop: frozen versions, each with its own stream certificate, promoted under δ-spending, driven by a LoopPolicy (experimental; the LoRA learning loop, stages 2–5).

from solvi.experimental.stream import AdapterLoop, DefaultPolicy, HashedTextTrainer

loop = AdapterLoop(HashedTextTrainer(), question="intent", policy=DefaultPolicy(), max_risk=0.05, secret=key,
                   additive=False)     # the default is additive coverage, which needs an initial= model; see below
out = loop.step(text, oracle)          # oracle: () → the label (None: missing), called only when one is needed
loop.pause() / loop.resume()           # no training, freezing or promotion while paused; labels and promises go on
loop.train_now(wait=False)             # → TrainJob: ignores want_train, not the budget; returns at once
loop.close()                           # cancels a training in flight; step and the controls refuse after it
loop.promote(force=False) / loop.rollback(v)
loop.versions(), loop.status(), loop.replay()
loop.save(dir) / AdapterLoop.load(dir, learner, ...)   # the checkpoint (stream.checkpoint)

This is the lane's LearningLoop (stream.versions) with its constants turned into LoopPolicy hooks (stream.policy); LearningLoop is now this class with DefaultPolicy set to the lane's constants. The protocol is the lane's: version 0 is "no model" (or initial=, with its own StreamPromise); every version frozen after it gets its own StreamPromise, fed only by coin samples drawn after its freeze, δ from one DeltaBudget (each index taken at the promise's first sample, not at its freeze or restart: a candidate or restart that never reads a sample spends nothing); the calibration coin is HMAC(secret, "sample|question|seed|n"); each decision is scored by the served version and, in shadow, by the candidate before its label is read; labels reach the learner only after the promises read them. See stream.versions for the statement and the records.

What the policy decides, per decision:

  • accept(st, x, y, source) — a label at all; refused → UntrustedLabel before anything changes. A learner's optional options (or its question part's options) is also checked: an out-of-set target raises ValueError before state changes; attached lenient dispatch counts it as a refused, missing label. A slow-path source ("s2", "verified") taken is recorded as "s2".
  • split(st, key) — "train", "calib" or "holdout" by the input's content key (key= of step, else question|vhash(x), the change pipeline's content_key for a dict input); the loop keeps the first split a key got, so a relabelled key never crosses. Only "train" labels reach the learner; "calib" / "holdout" labels are kept for the pre-freeze report; a "holdout" label also records the served version's (alone, wrong) — the improvement signal's window, reset at a promotion or a rollback.
  • want_train(st) — asked when no candidate is in trial, no training is in flight and the loop is not paused. An online learner (no train) is frozen as a snapshot(); a batch learner (train(job)) gets a TrainJob with the rows of select(st, train rows) and the settings of hyper(st). The loop checks policy.budget.refuse before every training (a policy cannot spend past its budget); status()["job"] and LoopState.job show the training while it runs (in process: stage 2 has no runner).
  • freeze(st, report) — the TrainReport scores the trained model and the served one on the held-out labels (latest label per key); the trained model's threshold is its own act_threshold when it has one, else gates.calib_threshold on the calib labels (a fixed-set stand-in for act_guard). Honesty numbers are not computed here (empty: the gate passes; they need a System, stage 5). Refused → the version is recorded "discarded" at birth, with no promise and no δ spent, so the policy's retrain floor counts it.
  • promote(st, paired) / discard(st, paired) — every decision while a candidate is in trial. Paired counts only the candidate's post-freeze coin samples since its last restart, at the thresholds in force now: novel ones (key not in the candidate's train_keys, a frozenset of the keys it was trained on, snapshotted at the freeze) for the comparison, seen ones for the memorisation probe (DefaultPolicy(novel_only=False), for controls: every sample in the comparison; it weakens the guarantee). A missing label counts as wrong.
  • alarm(st, who, report) — two sources, OR-ed: the RiskDetector (as the lane's) and a score monitor (a solvi Monitor, observe(score) → {"drift", "why"}, fed the served version's finite score on every decision outside probation; default NumericDrift). With a detector and no monitor the loop refuses (monitor=None): never the detector alone. who is "detector", "monitor" or "detector+monitor". "recertify" is the lane's alarm: the served and the candidate's promises restart, retired versions start over when rolled back to, probation opens; "rollback:" does that and serves v; "ignore" records the alarm and changes nothing else. The detector is reset and the monitor re-referenced (adapted(), else reset()) on every alarm and on every change of the served version.

Serving: with system=, a promotion or a rollback installs the version through its Served (stream.serving: served= frozen → Served, default as_served: a HeadVersion over the frozen model's as_head(feature)); version 0 is a BaseVersion (the head the System had). With versions_dir=, a frozen version is saved through Served.save and replay() checks each file through Served.load (rescore=True: every recorded score recomputed).

Controls (each writes a "stream" event marked control, which replay() re-applies): pause(), resume(), train_now(wait=None) (its "train_start" event; wait=True returns when the training is over and applied), close(), promote(v=None, force=False) (force skips the policy's promotion rule — novel count, min_share, margin, probe — never the certificate), and rollback(v). A rollback is allowed while paused; a discard and an alarm go on while paused.

Records: as the lane's, plus per decision its content key, its split, and the wall clock t (the budget reads the clock; replay reads the recorded one), and per training a "train" event (job, trigger, rows, settings, fingerprint, the TrainReport, whether it froze, where it started and where it was applied). Replay re-runs the protocol from the records with a fresh copy of the policy as it was built (pickled at construction) and the recorded training results. A train_now refused writes its "train" event too (state "refused").

A hook that raises after a decision (or a control) began to change the state — the policy's, the learner's update, keys or scoring of the held-out labels, the monitor, Served — stops the loop (design §1.2): the decision is recorded with the fields known so far and an "error" event (where: the hook; call: its place in the decision; why), status() says "error", the loop is paused and step and every control refuse from then on; the served version stays installed (the Dispatcher's path is not the loop's). Events of the failing step after the error are not written. Replay raises the recorded error again at the same place, so a transient fault and a deterministic one both replay exactly. A refused label source or a failing policy.accept / split raises before anything changed and does not stop the loop. A failed training (the learner's train raising) is not an error: it is recorded and the served version keeps serving.

Stage 3 (the LoRA learner, stream.lora_learner; the runners, stream.runner): a batch learner's TrainJob also carries the calib labels (the latest per key), the policy's Budget, the loop's α, the live status()["job"] dict, which a runner fills in (runner, pid, log, device, eta, last line), and cancel, an event the loop sets to drop it. What a training ends with: a frozen model (done), TrainingRefused (its time estimate is above max_train_s: a "train" event with state "refused", counted against the budget), any other exception (state "failed"), or RunnerError — the runner itself failed (the process died or went silent) — which stops the loop like a hook that raises (status "error", the hook "learner.train"; replay exact). initial= that has install / uninstall (a LoraVersion.of_part) is version 0's Served too, so a rollback to 0 puts the part as attached back. Replay takes the recorded install fingerprints (the System is not the replay's).

Deferred apply (stage 3b, design §3.2; the author's decision 7): a batch learner's training starts at a decision (or in train_now) — a "train_start" event there — and runs in a thread of its own, its runner beside it; the loop goes on deciding on the served version and no decision waits for it. The pre-freeze report is computed in that thread too, on the calib and held-out labels and the served version of the moment the training started; it stops between two labels when the training is cancelled or the served version changed. When the served version changed during the training (a rollback), the result is not gated on that stale comparison: the "train" event has state "stale" and the candidate is discarded at birth and released ("served_at_start" in "train_start" and "train" names the version compared with). Its result is applied on the first decision after it is in (not while paused: it waits for resume): the gates, then freeze or discard, a failure, a refusal or a stop on a RunnerError — the stage-3 paths — recorded at that decision: the "train" event carries started_at (the decision it started at) and applied ("decision", or "train_now" for train_now(wait=True)). Replay applies each recorded result at the decision (or in the control) the record names, with no clock: the position is the record's. One training at a time; the budget counts it when it starts. wait=True (the constructor's, or train_now(wait=True)) runs the training inside the step or the control, as stage 3 did (scripts, tests); an online learner's snapshot is always taken in the step. close() (a "close" event) cancels the training in flight — a subprocess is killed, a thread runner stops waiting — and so does an error stop; wait_training(timeout) waits for a result outside every lock.

Lock order: the part's version lock (part=, else the learner's or initial's part), then the loop's — in step and every control. A decision of the part that reaches the loop under its own version lock (stage 5's hook) takes them in the same order; the loop never waits for the part's lock while it holds its own (shadow scoring, a swap). The cost: while a step runs, the part's own decisions wait for it (with wait=True, for the whole training).

Eviction: policy.budget.max_versions_kept is a soft target for served/retired table rows only (version 0 counted), not a memory or all-model cap. The oldest eligible retired rows are evicted after a served-version change ("evict", Served.release(), state "evicted", model=None); files remain for replay. Version 0, current served and the rollback target are protected, so up to three protected rows may exceed a target below 3. Additive "layer" rows are outside that count and are bounded separately by max_layers (the active chain, base included); a frozen candidate is also resident but outside versions_kept. status()["resident_versions"] lists version-table model references across every state, including a candidate or retained layer. It is not bytes, distinct model objects, unique tensors, or an accounting of the live learner and an in-flight runner.

Checkpoint (stage 4, stream.checkpoint): additive uses checkpoint.FORMAT_ADDITIVE (currently v4; old additive v2/v3 formats are refused), replacement uses checkpoint.FORMAT (v1). save(dir, cancel=False) writes the whole state — versions and their files, promises and the detector (dump), policy, budget, rate, the label store labels.jsonl, the records — into a new folder, then switches dir/CURRENT to it atomically; AdapterLoop.load(dir, learner, ...) checks the signed manifest and every file's hash, rebuilds the loop, installs the served version and feeds the fresh learner its train labels again. A training in flight refuses the save unless cancel=True (cancel_training(), a "cancel" control event). A loaded loop continues with the same decisions and records as the loop it was saved from, and replays exactly.

Attach (stage 5): AdapterLoop.attach(dispatcher, learner, ...) (stream mode) or AdapterLoop.attach(system, ...) (label mode; mode="label"), or Dispatcher(..., loop=loop) / loop.attach_to(host) for a loop built by hand, and detach(). Stream mode: every dispatcher.ask is one decision of the loop, split around the dispatch — _pre (the served and candidate scores, the coin, whether the loop's rule answers alone) before System 1 is asked, _post (the step, with the slow path's accepted answer as the label) after; the dispatch escalates what the loop's rule does not answer alone and checks what its coin draws; the Dispatched records learning (the version served, its fingerprint, the coin, the loop's events); Dispatcher.replay installs each decision's version for its replay (serving(v)). Neither hook runs inside the part's call, and a Dispatcher's loop decisions run one at a time under its _learn_lock, taken before the part's lock and the loop's and never while either is held: the order is learn → part → loop. A label the policy refuses (the slow path's "s2" under the default policy) is a missing label for the loop. System.teach and outcome with a loop attached learn nothing at once (the part is the loop's): in label mode they are the loop's labels (label(x, y)), in stream mode they are only stored. Label mode has no coin, no promise and no alarm: every call is a labelled step, a version serves at its own act_guard threshold on the calib labels, and a frozen candidate with such a threshold is promoted on the next label when policy.promote(st, None) says so (the default: the pre-freeze gates decided; DefaultPolicy(pre_freeze=False) is refused in label mode; status()["guarantee"] names the fixed-set guarantee). After a promotion a watch scores the served version and the one served before it on each calib or held-out label and rolls back when policy.watch(st, Watch) says so (DefaultPolicy: policy.watch_rollback, an anytime-valid e-process on the discordant labels and the margin; the base LoopPolicy never rolls back); the target's scores are recorded (a train label's target is not scored), so the watch and its e-process replay. Attached to a Dispatcher, labels the policy refuses are counted (status()["labels"]["refused"]) and warn_refused of them in a row with none accepted warn once. The automatic promotion, in both modes, needs the candidate certified, as the promote() control does. The candidate is scored in shadow only while its grid is not fixed and on coin-sampled decisions. The controls take the Dispatcher's _learn_lock first (_locked), so a control waits for the decision in flight. Refused: a question answered by a combination or a part that is a member of one (combinations_of), a combination built over the part while a loop serves it (combine.served_by_loop), a Dispatcher with its own promise=, a second loop on a System, a stream-mode attach whose DefaultPolicy takes no label from the slow path (no label source).

Labels are kept in memory, inputs included (LabelRow.x): with dict inputs the memory grows with the label count (the checkpoint writes them to labels.jsonl). status() takes no lock. Unmeasured: no stand has run on this loop.

Verdict

Bases: NamedTuple

What an oracle may return instead of a bare label: the label (None: missing), its source (None: step()'s) and label_of — the stored id of the record that holds it (a ticket's), recorded with the decision.

AdapterLoop

AdapterLoop(learner, *, question, policy=None, max_risk=None, max_error=None, delta=0.05, initial=None, detector=None, monitor='auto', probation=300, source='human', secret=None, seed=0, sampling=None, promise_options=None, storage=None, versions_dir=None, system=None, feature='text', key=None, served=None, clock=None, wait=False, part=None, mode='stream', warn_refused=200, trace_candidate=False, additive=True, max_layers=3, useful_error='auto', delta_use=None, alarm_cascade='layer', trial_serving='escalate', _detector_alone=False, _batch=None)

See the module docstring. learner: an online Learner (snapshot) or a batch one (train(job)); question: the question's name (in the coin, the content key and the records); policy: a LoopPolicy (None: DefaultPolicy()); max_risk= / max_error=, delta: each version's StreamPromise (promise_options: its other keywords); initial: version 0's frozen model (None: no model); detector: a RiskDetector on the served version; monitor: the score monitor ("auto": NumericDrift() when a detector is given, else none); probation: the decisions escalated after an alarm; source: the default source of the oracle's labels; secret, seed: the coin's key and run; sampling: {"floor", "budget", "window"} of the rate; storage: a TraceStorage for the records (None: kept in memory); versions_dir: where frozen versions are saved; system, feature: install the served version on a System (feature: the text fact a text model reads); key: input → content key (None: content_key); served: frozen → Served (None: as_served); clock: the wall clock (None: time.time); wait: True runs every training inside the step or the control (stage 3's blocking form); part: the part whose version lock the loop takes before its own (None: the learner's or initial's part) — from construction on, every decision of that part takes this RLock, whether or not a version is ever swapped; warn_refused: attached to a Dispatcher, after this many labelled decisions in a row whose label the policy refused (none accepted in between) a UserWarning says the loop learns nothing, once (None: never; the count is status()["labels"]["refused"]); trace_candidate: while a candidate is on trial, every decision's records carry its score and would-be answer ("candidate_score" in the stream record, "candidate_would" in the loop payload; the existing "shadow" is filled only where the protocol reads it) — for offline replays of promotion rules; the protocol never reads them (no behaviour change), it costs one candidate scoring per decision; the keys are absent with no candidate or with the option off (default).

additive (default True: additive coverage; additive=False runs the replacement protocol above, unchanged — it lost on the stand: worse than no loop by 11–16 points on 3 of 4 intent datasets, while additive coverage gained on 4 of 4): a candidate serves the escalation zone below the served chain instead of replacing it. The loop serves a chain of layers [L0, L1, …] (L0 = the served version); layer j has its live threshold λ_j (its promise's) and, when it is not the deepest, a frozen routing threshold Λ_j, frozen when the layer below it was attached; a decision walks j = 0, 1, … to the first layer it does not pass (score_j ≥ Λ_j, or the deepest) — its owner; the zones Z_j (the decisions that reach j) are fixed by the Λ. Answering (decision 21): outside a trial zone the first layer on the path, from L0 down, with score ≥ its live λ_j (the owner: ≥ _thr_owner) and not in probation answers alone — so an upstream layer whose λ loosened below its Λ answers inside a deeper zone where the deeper layer escalates; none → the oracle (never a layer deeper than the owner). Every layer keeps learning: certified and not in probation (the base regime), on the decisions of its whole zone whose coin is below the shared base rate; otherwise (the owned regime) on the decisions it owns, with no bet below its Λ. Attach (a freeze in additive mode): Λ_d := λ_d of the deepest layer d (d keeps learning), the candidate's zone is {score_d < Λ_d}; every zone decision is escalated (nobody answers there) and the candidate's promise learns on every one of them (no coin filter; a missing label counts as a loss), it is scored on zone decisions only and has no comparison certificate. A discard drops Λ_d ("unfreeze"). Layering (the policy's promote, DefaultPolicy's additive gate: certified, novel, novel_risk, probe — no share or margin comparison; or the promote() control): the certified candidate becomes the deepest layer from the next decision ("promote" with additive=True). max_layers: the chain's depth cap (base + layers); at the cap, and while the deepest layer is not certified, the schedule starts no training ("train_refused", once per reason) and train_now is refused at the cap. Drift: one RiskDetector per layer on its base-coin samples of its zone (did it answer, was it wrong), the score monitor on L0's scores; an alarm on layer j restarts only j's promise and puts only j in probation (it answers nowhere and relearns in the owned regime until it re-certifies); rollback(j) — a layer index — detaches the layers ≥ j ("detach"), layer j−1 becomes the deepest. Attached to a Dispatcher, a decision answered by a layer below L0 (or, escalated, owned by one) is decided by System 1 with that layer's version installed for the call (serving). alarm_cascade="downstream" explicitly declares that all later additive layers depend on each upstream routing identity/regime. A non-ignored alarm restarts those dependent certificates and probation too, and discards an active trial before its old-zone evidence can be reused. Frozen routing thresholds of retained layers remain fixed. Default "layer" preserves independent layer-local alarms. This is an observation-driven invalidation policy, not a guarantee of detecting hidden model changes. trial_serving="certified" (opt-in, additive stream only) lets existing certified non-probation layers answer inside a trial's fixed zone at their live thresholds. The candidate still never serves: its promise/usefulness and promotion samples read only the input-independent base coin there, at the recorded rho_base, including missing-label losses. Other escalation labels are not candidate samples. Default "escalate" labels every trial-zone decision. All evidence floors and delta levels stay unchanged; the opt-in can collect fewer samples. Needs stream mode and an initial model. Records: owner, layer, zone, path [[v, score, thr in force]], trial_zone, answered_by, answer_layer, answer_thr, base, rho_base in the stream record, every reached layer's answer in the payload's "path_would" — replay recomputes the routing and the answer from them; status() "zones" (per layer Λ, λ, regime, P̂(Z), realised risk; the composite stream-wide risk, reported). Checkpoint: checkpoint.FORMAT_ADDITIVE (v4) with the chain (a replacement loop uses checkpoint.FORMAT, v1). The guarantee is per zone, at level α (one δ budget over every layer and restart). Stream-wide nothing is ≤ α: with max_error= the error among the alone answers is bounded by α·(1 + Σ_{k≥1} P(overlap_k) / P(answered)) (overlap_k: rows layer k would answer that an upstream layer took — the upstream layer answers first), with max_risk= the joint risk by α·(1 + Σ_{j≥1} P(Z_j)); max_risk=α / max_layers keeps the joint one ≤ α (docs/experimental.md, "Additive coverage").

step

step(x, oracle=None, *, source=None, key=None) -> dict

One synchronous decision; an aborted attempt permanently stops optional acquisition.

label

label(x, y, *, source=None, key=None) -> dict

Label mode: one label (x, y) → as step (by "oracle"). The served version is scored on it (the held-out window), a train label reaches the learner, and the policy may start a training, freeze or promote here. An attached System calls it from teach / outcome.

attach classmethod

attach(host, learner=None, *, question=None, dir=None, policy=None, initial='auto', part=None, **kw) -> 'AdapterLoop'

Build a loop for question and attach it to host: a Dispatcher (stream mode: every decision of dispatcher.ask goes through the loop) or a System alone (label mode: the labels of teach / outcome are the loop's; no coin, no stream promise). learner: None — a LoraLearner on the question's model-backed decision part (needs torch and dir=); any Learner (online or batch) otherwise. initial: version 0's model ("auto": the learner's version0() when it has one, else none). part: the decision part (None: found from the question). dir: the loop's folder (the default learner's and versions_dir). The other keywords are the constructor's. Refused: a question answered by a combination (Cascade, Vote, Route) or by a part that is a member of one, a rule with no decision part when no learner is given, a Dispatcher with its own stream certificate.

attach_to

attach_to(host) -> 'AdapterLoop'

Attach this loop to a Dispatcher (stream mode) or a System (label mode) → self. The checks of attach; also refused: a loop already attached, closed or stopped, a host that has a loop (or, a System, an update target), a loop that serves on another System. Dispatcher(..., loop=) calls it.

detach

detach(*, by=None, why=None, timeout=30.0) -> dict | None

Take the loop off its host: a training in flight is cancelled, version 0 (the part as attached) is put back on the System when another version serves, the host's hook is removed and the loop is closed (its records, replay(), versions(), status() and save stay). → the "detach" event (None when not attached). Waits up to timeout seconds for the training's thread after releasing every lock; with wait=True a training in progress holds the locks (a Dispatcher's _learn_lock included) until it ends, so the detach — and the Dispatcher's decisions — wait for it first.

serving

serving(v)

Version v installed on the System for the duration (the Dispatcher's replay of a decision made under it), then the served version again. Holds the part's lock and the loop's for the whole block: the part's decisions and the loop's controls wait.

wait_training

wait_training(timeout=None) -> bool

Wait (outside every lock) until the training in flight has a result, or timeout seconds → whether it has one (True when none is in flight). It is applied on the next decision.

pause

pause(*, by=None, why=None) -> dict | None

No training, freezing or promotion until resume(); serving, labels and promises go on. → the event (None when already paused). The candidate's trial clock runs while paused: a discard by stale / trial still happens (its δ_v stays spent), as do alarms and rollbacks. A training in flight goes on; its result waits for resume() (applied on the first decision after it).

train_now

train_now(*, wait=None) -> TrainJob

One training now, whatever want_train says — within the budget, never while paused, with a candidate in trial or with a training in flight. → the TrainJob. wait (None: the loop's wait): False — a batch learner's training starts and the call returns at once (state "running"; its result is applied on a later decision, see step); an online learner's snapshot is a copy, always taken here (state "done"; the "train_start" event records the wait asked and inline=True); True — the call returns when the training is over and its result applied (state "done", "failed", "refused" or "stale" with why). A RunnerError stops the loop where the result is applied. A train_now refused (paused, a candidate in trial, a training in flight, the budget) writes its control event, a "train" with state "refused".

This control bypasses scheduling/label floors and the improvement signal, not the budget or post-training freeze/promotion gates. A manual run can therefore consume training time and a training-budget slot, then be discarded at birth for insufficient held-out/calibration data. Inspect policy.why_not_train(loop._state()) before overriding the schedule; manual training neither buys labels nor guarantees a frozen candidate.

close

close(*, timeout=30.0) -> dict | None

Stop the loop: a training in flight is cancelled (its runner stops it: a subprocess is killed, a thread runner stops waiting for its thread), step and every control refuse from here on; the served version stays installed. With wait=True a training runs inside a step or a control under the loop's locks, so a training in progress there ends first (a Dispatcher's decisions wait for it too: it holds _learn_lock). Waits up to timeout seconds for the training's thread, outside every lock. → the "close" event (None when already closed). Also with AdapterLoop(...) as loop:.

cancel_training

cancel_training(*, by=None, why=None) -> dict | None

Drop the training in flight (running, or its result waiting to be applied): its runner stops it, nothing is applied, nothing restarts it here; it stays counted against the budget. → the "cancel" event (None when no training is in flight). The policy may start another one on a later decision.

save

save(dir, *, cancel=False) -> dict

Save the loop's whole state to dir (see stream.checkpoint): written to a temporary folder, then switched in atomically, so a crash in the middle leaves the previous checkpoint usable. A training in flight refuses the save (RuntimeError) unless cancel=True, which cancels it first (cancel_training, a "cancel" event). → {"path", "manifest", "n", "files"}. Writes no record otherwise. The save holds the part's version lock and the loop's lock for all its writes (every version's files, each fsynced, included): the part's decisions and the loop's controls wait for it; unmeasured.

load classmethod

load(dir, learner, **kw) -> 'AdapterLoop'

The loop saved in dir, continuing where it was saved (see stream.checkpoint.load_loop for the keywords: system, storage, versions_dir, part, initial, key, served, clock, secret, groups, additive).

promote

promote(v=None, *, force=False, by=None, why=None) -> dict

Serve the candidate now: it must be certified; without force the policy's promote must agree (force skips the promotion rule, never the certificate); refused while paused. Attached to a Dispatcher, every control waits for the decision in flight (its slow path's call included). → the "promote" event.

rollback

rollback(v, *, by=None, why=None) -> dict

Additive mode: v is a layer index ≥ 1 — the layers ≥ v are detached ("detach"; see the class docstring). Otherwise: serve an earlier version again (its certificate and threshold as it left them, unless an alarm came after it retired: then its promise restarts → "restart"; version 0 without a model: nothing alone). A candidate in trial is discarded (its δ_v stays spent); waits for a Dispatcher's decision in flight → the "rollback" event.

replay_all

replay_all(*, rescore=False) -> dict

Alias of replay: check the complete recorded protocol log, including freeze/train controls.

This replays the loop's protocol, not an arbitrary external environment. With rescore=True the saved frozen models also recompute the recorded scores, under replay's existing versions_dir requirements.

replay

replay(rescore=False) -> dict

Re-run the protocol from the records and compare → {"ok", "mismatches": [(n, what, why)], "decisions", "versions"}. The policy is the one the loop was built with (a fresh copy), trainings take their recorded results, controls are re-applied at their recorded place.

status

status() -> dict

{"state", "error", "served", "candidate", "n", "labels": {"train", "calib", "holdout", "refused"}, "trainings", "budget": {...}, "job", "paused", "alarms", "mode", "attached", "guarantee", "watch", "delta_spent", "versions_kept", "resident_versions"} — and "zones" in additive mode (_zones: per layer version, layer, routing_thr Λ, threshold λ, certified, learning, probation, zone_share P̂(Z_v), owned_share, its counts and realised risk on its own coin samples; the chain's deepest, deepest_certified, zone_share, the composite stream-wide joint and selective risk — estimates, reported, not promised — beside the joint kind's bound α·(1 + Σ_{j≥1} P̂(Z_j))). labels: the accepted labels by split and "refused", the labels the policy refused on the attached path (each a missing label). watch: label mode after a promotion, the watch's counts {"target", "n", "better", "worse", "total", "lw"} ("lw": its e-process's log wealths; None otherwise). attached: "dispatcher", "system" or None. state: "detached", "closed", "error" (a hook raised: the loop stopped; error: {"n", "where", "why"}), "training", "paused" or "running". job: the training in flight — id, version, trigger, started (wall clock), started_at (its decision), inline, state ("running"; "ready": its result waits for the next decision), and what the runner fills in (runner, pid, log, device, eta, last, last_t: a heartbeat line's age says whether it is alive).

versions_kept counts served/retired rows only, with protected-row exceptions to the soft retention target. resident_versions is a list of {version, state} for every version-table row whose model is not None, including layers and a candidate. Rows may share model storage: this is a reference inventory, not bytes or unique objects/tensors, and excludes the live learner/runner.

Takes no lock: it answers while a step (or an inline training inside it) runs on another thread. Its fields are read one by one, so two of them may straddle a decision.

fed

fed(v) -> list

The decisions whose samples reached version v's promise, in order.

ticket_verdict

ticket_verdict(desk, resolved) -> Verdict

A ticket resolved (or expired) on a stage-3a TicketDesk → its Verdict, read from the stored dispatch record. desk: the TicketDesk (or its TraceStorage); resolved: what TicketDesk.resolve returned, or the record's stored id. The agent's verdict has source "s2" (the loop takes it only with s2_labels=True), a person's "human"; a ticket that expired or whose verdict the contract refused has no label.

content_key

content_key(question, x) -> str

The default content key of an input: "question|vhash(x)" (for a dict, the change pipeline's content_key).

solvi.experimental.stream.checkpoint

The checkpoint (stage 4): AdapterLoop.save(dir, cancel=False) writes the loop's whole state — every version (its state, fingerprint, paired samples, the keys it trained on, its StreamPromise through dump()) and the files of the versions that still have a model (through Served.save, version 0 included), the δ budget's index, the training budget's counters, the policy (now and as built), the RiskDetector (dump()), the score monitor, the rate's window, the label store labels.jsonl and the records records.jsonl (or, with a TraceStorage, its chain head) — into dir/ckpt-<n>-<id>/, then replaces dir/CURRENT atomically, so a crash leaves the previous checkpoint usable. manifest.json lists every file's SHA-256 and is signed (manifest.sig, HMAC-SHA256 under the loop's secret, SHA-256 without one). Threat model: the pickles in a checkpoint are run only after the HMAC and every file's hash are verified, so with a secret a file changed or added by someone without it is refused; without a secret there is no tamper protection against a writer of the folder (a plain SHA-256 anyone can recompute), and load warns (CheckpointTrustWarning). load refuses a tampered, missing or unlisted file, a checkpoint saved with a secret loaded without one, another secret, another learner class, a part with other weights, a version file with another fingerprint, a store without the chain head or with records after it; the versions are loaded from the verified bytes (a private copy), never from the folder again after the check. The learner is given fresh and fed the saved train labels again. A training in flight refuses the save unless cancel=True. A loaded loop continues with the same decisions and records as the loop it was saved from and replay() rebuilds every decision before and after the load. A save holds the part's version lock and the loop's lock for all its writes, so the part's decisions wait for it; one loop saves into a directory. Unmeasured. An additive loop saves format v3 (its chain: layers, routing thresholds, a detector per layer; a v2 one is refused by name); a replacement loop's checkpoint stays v1; load(..., additive=) refuses a protocol mismatch.

The adapter loop's checkpoint (experimental; the LoRA learning loop, stage 4): AdapterLoop.save(dir) and AdapterLoop.load(dir, learner, ...).

info = loop.save("loop.ckpt")                       # → {"path", "manifest", "n", "files"}
loop = AdapterLoop.load("loop.ckpt", LoraLearner(part, "loop/"), system=part, secret=key)

What is saved: the loop's whole state at the moment of the save — the decision count, the served version, the candidate and the rollback history; every version (state, fingerprint, frozen_at, the keys it trained on, its paired samples, its StreamPromise through dump()) and the files of every version that still has a model (through its Served.save; version 0 too when it has a model) plus those of discarded and evicted versions found in the loop's versions_dir; the δ budget's index; the training budget's counters (start times, attempts); the policy as it is now and as it was built (pickled; the replay starts from the latter); the RiskDetector through dump(), the score monitor (pickled, now and as built); the adaptive rate's window; the alarms, probation, the held-out window; pause, close and error; the label store labels.jsonl — every accepted label (content key, input, label, source, decision, split; an input or a label that does not round-trip through JSON is pickled in its line); and the event record records.jsonl (when the loop keeps its records in memory; with a TraceStorage, the store's chain head and the count of this loop's records instead).

Layout: dir/CURRENT names the checkpoint folder dir/ckpt-<n>-<id>/, which holds manifest.json (the format, the question, the configuration, the learner's class, the model's weights fingerprint, the store's head and every other file's SHA-256), manifest.sig (HMAC-SHA256 of the manifest under the loop's secret, else its SHA-256), state.json, labels.jsonl, records.jsonl, policy.pkl, policy0.pkl, monitor.pkl, monitor0.pkl and versions/<v>.*. A save writes a new folder under a temporary name, syncs it, renames it, then replaces CURRENT (os.replace): a crash at any point leaves CURRENT naming a complete checkpoint, the previous one until the switch. Older folders are removed after the switch, under the same locks as the save (so a second save of the same loop waits for the first one's cleanup), and the folder CURRENT names is never removed. One loop saves into a directory: two loops sharing one are not serialised against each other. A save holds the part's version lock and the loop's lock for all its writes — the state, the labels, the pickles and every version's files (a LoRA version's adapter), each fsynced — so the part's decisions and the loop's controls wait for the whole save; the cost is unmeasured. load also takes the checkpoint folder itself.

What load refuses (ValueError): a manifest whose signature does not match (tampered, or another secret — the secret is never written), a file whose hash is not the manifest's or that is missing, a file in the folder that the manifest does not list, a checkpoint saved with a secret loaded without one, a learner of another class, a part whose model has other weights, a version file whose fingerprint is not the recorded one, an initial= with another fingerprint, a store that does not contain the checkpoint's chain head or holds records of this loop after it (those decisions are not in the saved state), a store given to a checkpoint saved without one or the other way round, a System missing when the loop served on one, and a learner whose label count after the train labels are fed again is not the saved one.

The learner is not saved: load takes it as built (fresh) and feeds it the saved train labels again, in order, through update — enough for a batch learner (a LoRA learner trains from the base checkpoint every time) and exact for a deterministic online learner. The key function, the served function, the clock and the secret are not saved either: give them again. A training in flight refuses the save unless save(cancel=True), which cancels it first (a "cancel" event; it stays counted against the budget; nothing restarts it — the policy may start another on a later decision). A save and a load write no record: a loaded loop continues the saved records, so it and the loop it was saved from give the same records on the same continuation, and replay() on it rebuilds every decision, before and after the load.

Trust: the pickles (policy, monitor, a HeadVersion's model, a label that is not JSON) are run only after the manifest's signature and every file's hash are verified, and a folder holding a file the manifest does not list is refused; the version files are read from the verified bytes only (written to a private temporary folder the loaders read, so a file swapped in the checkpoint after its hash was checked is never read), and the ones copied into versions_dir are written from them too. With secret= the signature is an HMAC, so a file changed or added by someone without the secret is refused. Without a secret it is a plain SHA-256 that anyone can recompute: a check against accidental damage, with no tamper protection against whoever can write the folder, and load warns (CheckpointTrustWarning). Whether the checkpoint was keyed is recorded inside the signed manifest (keyed), so with the secret a flip of it is caught by the HMAC, and a keyed checkpoint is refused without the secret; nothing written in the folder can stop its writer from forging an unkeyed checkpoint, which is why the unkeyed path warns. Load checkpoints you wrote. Unmeasured: tests on fake learners and a tiny random checkpoint only.

CheckpointTrustWarning

Bases: UserWarning

A checkpoint loaded without a secret: its integrity check detects damage, not tampering.

save_loop

save_loop(loop, dir, *, cancel=False) -> dict

See the module docstring. → {"path": the checkpoint folder, "manifest": its SHA-256, "n", "files"}.

load_loop

load_loop(cls, dir, learner, *, system=None, storage=None, versions_dir=None, part=None, initial=None, key=None, served=None, clock=None, secret=None, groups=None, additive=None)

See the module docstring. learner: the learner as built (fresh: the saved train labels are fed to it again); system: the System (or part) the loop served on, when it had one — the served version is installed on it; storage: the TraceStorage that holds the loop's records, when it had one; versions_dir: where the loop saves new versions (the checkpoint's version files are copied there when missing, so replay(rescore=True) finds them); part: the part whose version lock the loop takes (None: the learner's or version 0's); initial: version 0's model given again instead of read from its file (its fingerprint must be the recorded one); key, served, clock: as the constructor's; secret: the loop's secret (required when it had one); groups: the grouping function of version 0's thresholds per group, when it was calibrated with one; additive: what the caller expects (None: whatever the checkpoint is) — a replacement checkpoint (v1) loaded with additive=True, or an additive one (v4) with additive=False, is refused: a loop never changes its protocol at a load (a replacement loop's chain cannot be rebuilt into layers; start an additive loop from its served version as version 0 instead).

solvi.experimental.stream.lora_learner

The LoRA learner (stage 3): LoraLearner, a batch learner that trains a LoRA adapter on the decider from the base checkpoint for each version, in a runner, and runs act_guard on the calib labels; LoraVersion, an adapter with its calibration — scored in shadow on the scoring thread only, installed and rolled back with solvi.experimental.lora.swap (the adapter and its thresholds change together under the part's version lock), saved as <v>.lora.safetensors and <v>.calib.json. Needs solvi[lora]. Unmeasured.

The LoRA learner of the adapter loop (experimental; stage 3): LoraLearner, a batch learner that trains a LoRA adapter on the decider for one question, and LoraVersion, a frozen version (an adapter and its calibration) that the loop scores, freezes, serves and rolls back. Needs the torch decider and peft (pip install "solvi[lora]").

from solvi.experimental.stream import AdapterLoop
from solvi.experimental.stream.lora_learner import LoraLearner

part = model.decision("intent", "Which intent?", "text", INTENTS)        # DecideModel.load(path, backend="torch")
learner = LoraLearner(part, dir="loop/")                                 # runner="subprocess" by default
loop = AdapterLoop(learner, question="intent", initial=learner.version0(), system=part, versions_dir="loop/",
                   max_risk=0.05, secret=key)

What a training is: train(job) trains an adapter from the base checkpoint every time (no warm start: a warm_start setting is refused) on job.rows only, with the policy's r, lr, updates and seed, in the runner (stream.runner: a subprocess by default — it loads the checkpoint again, nice 10, threads capped at budget.cpu_threads, the device picked by budget.device, "auto": a GPU with free_gpu_mb free, else the CPU; a GPU out of memory falls back to the CPU). Before training it estimates compute time from warm unapplied probes and refuses when the estimate is above budget.max_train_s (the loop records the refusal). Then it runs act_guard at the loop's α on the calib labels (job.calib: labels whose keys are never trained on) on a copy of the part with the new adapter, and returns a LoraVersion whose act_threshold is that threshold. The runner writes train_<job id>.log (a heartbeat every 30 s) and the adapter file train_<job id>.lora.safetensors; the version is staged on the scorer (installed, inactive) when it is read back.

LoraVersion is both the loop's frozen model and its Served: score(x) → (the answer, the signal its threshold is on), computed with its adapter on this thread only (solvi.experimental.lora.scoring: the served part, other questions and the fingerprints are untouched); install(system) is solvi.experimental.lora.swap — the adapter and its thresholds change together under the part's version lock, so no decision of the part sees one without the other — and uninstall swaps back what it replaced. fingerprint() = digest(adapter hash, calibration fingerprint). LoraVersion.of_part(part) is version 0: the part as attached, its adapter (or none) and its thresholds. save(dir, v) writes <v>.lora.safetensors and <v>.calib.json; load(dir, v, expect_fp=, part=, groups=) reads them back (the adapter's content against its hash, the version against expect_fp).

Limits: determinism holds for a fixed device and thread count (the adapter file is bf16 either way, so a GPU-trained adapter loads bit-exact on a CPU); a combination over the part (Cascade, Vote, Route) reads the part's internals without its version lock — the swap's atomicity covers the part's own decisions (call, decide, in_pass); a part's correction memory is not consulted while calibrating; a trained version stays staged on the scorer (about 3 MB for solvi-base) until the loop releases it (release(): a discarded candidate, a retired version past max_versions_kept, the versions a rescore bound again). Unmeasured: no stand has run on the LoRA loop.

LoraVersion

LoraVersion(part, adapter, calibration, *, info=None, signal='auto')

See the module docstring. part: the DecisionPart it serves (None: read from files, not bound yet — bind); adapter: a LoraAdapter or None (the checkpoint itself); calibration: solvi.experimental.lora.calibration's dict; info: what it was trained on; signal: the signal score returns ("auto": the threshold's, as recorded by act_guard).

threshold property

threshold

The act_guard threshold on its signal (escalate_below for "confidence", act_threshold for "act"); None when it has none; inf when act_guard found none at the promised risk.

act_threshold property

act_threshold

The threshold the adapter loop's pre-freeze report applies to score's signal (= threshold).

of_part classmethod

of_part(part, *, signal='auto')

Version 0: the part as it is now — its adapter (or none) and its calibration.

bind

bind(part)

Serve and score on part (its version lock is created; the adapter is staged on its scorer) → self.

release

release()

Unstage the adapter from the scorer (a discarded or retired version; idempotent). It stays when a slot holds it (the version is served); a later bind or score stages it again.

score

score(x)

→ (the answer, the signal): the part's question scored with this version's adapter and its own adaptation on this thread only (no threshold applied), whichever version the part serves; the signal is the one its threshold is on (act or confidence).

install

install(system=None) -> dict

Serve this version on its part (system: unused — the part is the version's own): the atomic swap. → {"from", "to"}: the part's fingerprints.

uninstall

uninstall(system=None) -> None

Back to what install replaced (atomically).

save

save(dir, version: int) -> list

→ [.lora.safetensors (when it has an adapter), .calib.json].

load classmethod

load(dir, version: int, *, expect_fp: str, part=None, groups=None) -> 'LoraVersion'

The version saved by save; ValueError when a file is not the recorded one (the adapter's content against its hash, the calibration's adapter, the version's fingerprint against expect_fp). groups: the grouping function of thresholds per group by a function (version 0 calibrated with act_guard(groups=fn)).

LoraLearner

LoraLearner(part, dir, *, runner='subprocess', signal='auto', epochs=6, max_risk=0.05)

See the module docstring. part: the question's DecisionPart (torch backend, loaded from a checkpoint folder); dir: where the logs and adapter files go; runner: "subprocess" (default), "thread" or a runner object (stream.runner); signal: act_guard's signal ("auto"); epochs: when the policy's settings give no updates; max_risk: act_guard's risk when the job does not carry the loop's α.

update

update(x, y, *, key=None, source=None) -> None

A train label: counted; the rows of a training come with its job (the loop keeps them).

version0

version0() -> LoraVersion

The part as it is now, as version 0 (the loop's initial=).

train

train(job) -> LoraVersion

One training (see the module docstring) → LoraVersion. Raises stream.runner's TrainingRefused (the estimate is above max_train_s), TrainingFailed (the training raised) or RunnerError (the process died).

calibration_from

calibration_from(rec, *, groups=None, nodes=None) -> dict

A calibration record (solvi.experimental.lora.calibration_record) → the calibration a swap restores. The question's adaptation is rebuilt from its parameters (its kept examples are not in the record: a later teach or refit starts without them); thresholds per group are rebuilt as _groups_from says (groups=, nodes= go there). A version the learner trained has neither; version 0 of a part that was fitted or calibrated per group has them.

train_target

train_target(payload, ctx) -> dict

The training itself, in the runner (a subprocess, or a thread): load the checkpoint, rebuild the part, train from the base, act_guard on the calib labels, write the adapter file → what LoraLearner.train reads back.

solvi.experimental.stream.runner

Where a training runs (stage 3): SubprocessRunner (the default — nice 10, threads capped at Budget.cpu_threads, the device picked by pick_device with a CPU fallback, the time estimate refused above Budget.max_train_s, a heartbeat log, the result file) and ThreadRunner (tests, tiny data); TrainingRefused, TrainingFailed, RunnerError and TrainingCancelled (run(..., cancel=event): a subprocess is killed, a thread runner stops waiting). Unmeasured.

Where a training runs (experimental; the adapter (LoRA) loop, stage 3): a runner calls a training function — a target named "module:function" — with a payload and a context, and returns the dict the function returns.

from solvi.experimental.stream.runner import SubprocessRunner, ThreadRunner

out = SubprocessRunner().run("pkg.mod:train", payload, name="train_3.1", workdir=dir, budget=budget)
  • SubprocessRunner (the default): a fresh Python process (python -m solvi.experimental.stream.runner job.pkl), nice 10, its torch / BLAS threads capped at budget.cpu_threads, the device picked by pick_device (budget device="auto": cuda when a GPU has free_gpu_mb free, else the CPU; a training that runs out of GPU memory is the target's to retry on the CPU, as the LoRA target does). It writes <name>.log (a line per phase and a heartbeat every heartbeat_s, 30 s), the payload as <name>.job.pkl and its result as <name>.result.json; the process's own output goes to <name>.err. It isolates the thread count and a crash, and the slice's memory cap applies to it.
  • ThreadRunner: the same target in a thread of this process (tests, tiny data): torch threads are process-global, so a training slows live scoring, and nothing is isolated; the device is picked the same way.

The context the target gets (RunContext): device (picked), threads, budget, log(message) (a line of the log), progress(done, total, **extra) (what the heartbeat says), estimate(seconds) — the target calls it with its estimate of the training's time before training; above budget.max_train_s it raises TrainingRefused, which the runner returns as a refusal.

What a run can end with, as the caller sees it: the target's dict (done); TrainingRefused (the estimate is above max_train_s); TrainingFailed (the target raised, or ran past its estimate + grace_s, counted from the estimate — before the target estimates, max_train_s + grace_s from the start — and was stopped: a subprocess is killed, a thread cannot be and is reported when it ends); RunnerError (the runner itself failed: the process died — a signal, the memory cap, an exit without a result — or wrote no log line for stall_s). The adapter loop records the first three in its "train" event (the served version keeps serving) and stops on a RunnerError (status "error", replay exact).

While a run goes on, status (a dict the caller passes; the loop's status()["job"]) is updated in place: "runner", "pid", "log", "device", "eta" (the wall clock the training should end at, once estimated), "last" (the log's last line) and "last_t" (when it was written). cancel= (a threading.Event): once set, a subprocess is killed and TrainingCancelled raised; a thread runner stops waiting and raises it (the thread ends on its own). Unmeasured.

TrainingRefused

Bases: RuntimeError

The training was not started: its estimated time is above the budget's max_train_s.

TrainingFailed

Bases: RuntimeError

The training ran and failed (the target raised, or it ran past its time and was stopped).

TrainingCancelled

Bases: RuntimeError

The caller cancelled the training (its cancel event was set): a subprocess is killed; a thread cannot be stopped and is left to end on its own.

RunnerError

Bases: RuntimeError

The runner itself failed: the training process died without a result, or went silent.

RunContext

RunContext(budget, device, why, log_path, status=None, heartbeat_s=30.0)

See the module docstring.

estimate

estimate(seconds)

The training's estimated time, before it trains: logged; above budget.max_train_s → TrainingRefused.

ThreadRunner

ThreadRunner(*, heartbeat_s=30.0, grace_s=120.0)

See the module docstring. heartbeat_s: seconds between heartbeat lines; grace_s: past the estimate (max_train_s before one) before a training is reported as over its time. In this runner the LoRA trainer copies the network in the loop's process while holding the scorer's network gate alone, so every decision on that model (every question, not only the loop's) waits while the copy is made; unmeasured. SubprocessRunner, the default, copies in the child and is unaffected.

SubprocessRunner

SubprocessRunner(*, nice=10, heartbeat_s=30.0, grace_s=120.0, stall_s=None, python=None, pythonpath=(), poll_s=0.5)

See the module docstring. nice: the process's niceness; heartbeat_s: seconds between heartbeat lines; grace_s: on top of the target's estimate (counted from the estimate line; before it, on top of max_train_s from the start) before the process is killed — it must cover what the estimate does not: loading the checkpoint, calibration, saving; stall_s: no log line for this long → killed, a RunnerError (None: max(10 heartbeats, 300 s)); python: the interpreter (default this one); pythonpath: extra import paths for the target's module (the folder solvi is imported from always comes first); poll_s: how often the process is checked.

gpu_free_mb

gpu_free_mb()

Free memory of each GPU in MB, read with nvidia-smi (no CUDA context is created) → [mb, ...]; [] when there is no GPU or no nvidia-smi.

pick_device

pick_device(device='auto', free_gpu_mb=3000, *, probe=None, cuda=None, env=None, torch_probe=None) -> tuple

The device a training runs on → (device, why). "cpu": the CPU; "cuda" / "cuda:": that GPU (as asked); "auto": the first GPU with at least free_gpu_mb MB free when torch sees CUDA, else the CPU (the reason is said). The device is torch's ordinal: under CUDA_VISIBLE_DEVICES nvidia-smi's index is mapped to it (when that variable names GPUs by UUID, torch is asked for the free memory instead). probe: () → free MB per GPU by nvidia-smi's index (default gpu_free_mb); cuda: () → whether torch sees CUDA (default: torch's); env: the environment (default os.environ); torch_probe: () → free MB per torch ordinal (default: torch.cuda.mem_get_info).

make_runner

make_runner(runner)

"subprocess" / "thread" / a runner object (with run(target, payload, *, name, workdir, budget, status), and optionally cancel=) → a runner.

solvi.experimental.stream.serving

How a frozen version is put in front of a System: the Served protocol, HeadVersion, BaseVersion.

How a frozen version is put in front of a System (experimental; the adapter (LoRA) loop, stage 2): the Served protocol, HeadVersion (a frozen model served as the question's answer head) and BaseVersion (version 0: what the System had when the loop was built).

from solvi.experimental.stream.serving import HeadVersion

srv = HeadVersion(frozen, question="intent", feature="text")
srv.install(system)                     # → {"from": the head's fingerprint before, "to": this version's}
srv.uninstall(system)                   # back to what install replaced
srv.save(dir, version)                  # [dir / f"{version}.pkl"]: the frozen model, pickled
HeadVersion.load(dir, version, expect_fp=fp, question="intent")   # refused when the fingerprint is not fp

The loop never touches a System except through Served.install: a promotion or a rollback installs the version it serves (version 0 is a BaseVersion, which puts back the head the System had, or removes it). uninstall is for detaching (stage 5). A frozen model that already has install / uninstall (the LoRA version of stage 3) is its own Served; any other one is wrapped in a HeadVersion (solvi.core.versions.serve_head). Optional: release() — free what the version holds outside the loop (a LoRA version unstages its adapter); the loop calls it on a discarded candidate and on the copies it loads to check the version files. Unmeasured.

HeadVersion

HeadVersion(frozen, question: str, feature: str = 'text')

A frozen model (stream.learner.Frozen with as_head) served as the answer head of question, reading the text fact feature. It scores and fingerprints as the frozen model does.

load classmethod

load(dir, version: int, *, expect_fp: str, question: str = '', feature: str = 'text') -> 'HeadVersion'

The version saved by save; a ValueError when its fingerprint is not expect_fp.

BaseVersion

BaseVersion(system, question: str)

Version 0 as served on a System: the answer head the System had when the loop was built (None: no head). install puts it back (or removes the question's head); it saves nothing.

as_served

as_served(frozen, question: str, feature: str = 'text')

A frozen model's Served: itself when it has install / uninstall, else a HeadVersion over it.

solvi.experimental.stream.gates

The content-key split and the gate arithmetic the default policy uses: the held-out gate, the honesty gate, label mode's paired Wilson sign test (safe only together with the held-out gate), the memorisation probe, the improvement signal, the fewest calib labels a calib threshold needs.

The arithmetic of the adapter loop's gates (experimental; the LoRA learning loop, stage 1): the label split, the pre-freeze gates on the held-out labels, the memorisation probe and the improvement signal. Plain functions over counts, no model, no torch; stream.policy.DefaultPolicy calls them.

from solvi.experimental.stream.gates import split, heldout_gate, probe

split("intent|3f2a…")                        # "train" | "calib" | "holdout", the same in every run, forever
heldout_gate(41, 3, 30, 4, 100)               # {"ok", "n", "gain", "why"}: right − wrong alone, candidate vs served
probe(alone_seen=80, wrong_seen=1, alone_novel=60, wrong_novel=30)   # {"ok": False, ...}: a memoriser

The split is copied from the change pipeline's update gates (changes._updates.split_of), not imported (that module is private), with the same salt ("solvi-learning:") and the loop's shares (70 / 15 / 15 train / calib / holdout): a content key's split is a hash of the key alone, so an input seen labelled twice is in the same split both times and a key never crosses. The shared salt makes the two splits nest: the loop's holdout ∪ calib (hash < 0.30) is exactly the change pipeline's holdout (hash < 0.3), so a learner both share never trains, through the loop, on a key the change pipeline evaluates on. The salt must not change once a checkpoint exists. The held-out gate is the same score as the change pipeline's ((answered alone and right − answered alone and wrong) / n); the honesty gate compares solvi.testing.honesty numbers with its compare. Unmeasured: no stand has run on them.

split

split(key, *, calib: float = 0.15, holdout: float = 0.15) -> str

A label's split by a hash of its content key → "holdout", "calib" or "train". A pure function of the key and the shares: the same key always lands in the same split. Shares outside [0, 1), or summing to 1 or more (no label left to train on), are a ValueError. With the default shares (calib + holdout = 0.30) a key the change pipeline holds out (changes._updates.split_of(k) == "holdout") is never "train" here.

heldout_gate

heldout_gate(right, wrong, served_right, served_wrong, n, *, min_gain: float = 0.01, min_holdout: int = 100) -> dict

The candidate against the served version on the same n held-out labels: score = (answered alone and right − answered alone and wrong) / n; ok when n ≥ min_holdout and the candidate's score ≥ the served one's + min_gain. → {"ok", "n", "gain", "min_gain", "candidate", "served", "why"}.

honesty_gate

honesty_gate(before: dict, after: dict, tolerance: float = 0.02) -> dict

The honesty numbers (solvi.testing.honesty.metrics' gated keys) of the served version (before) and the candidate (after) on the held-out labels: ok when none got worse by more than tolerance. Empty before: nothing to compare, ok. → {"ok", "tolerance", "regressions", "why"}.

paired_gain_low

paired_gain_low(better: int, worse: int, confidence: float = 0.95)

The paired held-out comparison of label mode: of the held-out labels where the candidate and the served version score differently (an item scores +1 answered alone and right, −1 alone and wrong, 0 escalated), better favour the candidate and worse the served one. → the Wilson lower bound of 2p − 1, p = better / (better + worse) (> 0: the candidate is better on more of them than chance allows); None with no such label.

This is a sign test over the discordant labels, not a bound on the held-out margin: 60 labels better by +1 and 40 worse by −2 give a positive bound and a negative margin. It is safe only combined (AND) with heldout_gate, whose margin ≥ min_gain the default policy's freeze also requires; do not use it alone.

probe

probe(alone_seen: int, wrong_seen: int, alone_novel: int, wrong_novel: int, *, gap: float = 0.1, min_n: int = 30, confidence: float = 0.95) -> dict

The memorisation probe on post-freeze samples: the candidate's error among its alone answers on inputs whose key it trained on (seen) and on inputs it never saw labelled (novel).

"ok" compares point estimates: False when err_novel − err_seen > gap. Measured only when both sides have ≥ min_n alone answers; unmeasured, "ok" is True and "measured" False — the caller decides what an unmeasured probe means (the default policy does not promote while the novel side has < min_n alone answers, and does not discard). "shown" is the discard test: the gap is shown beyond noise, the Wilson lower bound of err_novel minus the Wilson upper bound of err_seen (at confidence) above gap; False when unmeasured. At n = 30 a point-estimate gap is noise (4 wrong of 30 novel against 0 of 30 seen is 0.133 > 0.10, not shown). → {"ok", "measured", "shown", "err_seen", "err_novel", "gap", "low_gap", "why"}.

calib_threshold

calib_threshold(scored, alpha: float, *, confidence: float = 0.95)

A fixed-set threshold on the calib labels, for a frozen model without its own (act_threshold): scored is [(score, wrong)], one per calib label (wrong: the would-be answer is not the label). From the strictest score down, a threshold t holds when the Wilson upper bound of the joint risk (score ≥ t and wrong, over all n labels) is ≤ alpha; the loosest t reached before the first that fails is returned (fixed sequence), None when none holds — at α = 0.05 and 95 % that needs ≥ 73 calib labels (calib_min). A stand-in for act_guard (stage 3 uses the part's own); no anytime statement.

calib_min

calib_min(alpha: float, *, confidence: float = 0.95) -> int

The fewest calib labels with which calib_threshold can find any threshold: the smallest n whose Wilson upper bound of 0 wrong in n is ≤ alpha (73 at α = 0.05 and 95 %). Fewer labels: no threshold, the act_guard gate refuses every freeze.

incumbent_short

incumbent_short(outcomes, alpha: float, target_share=None, *, min_n: int = 1) -> dict

The improvement signal: is the served version measurably short on its latest held-out labels? outcomes: [(alone, wrong)] of the served version, one per held-out label. Short when it answers nothing alone on them, or its error among the alone answers is above alpha, or (target_share given) its share alone is below target_share. With fewer than min_n held-out labels (none included) there is no evidence that it is strong: short.

The statistic is the conditional error among alone answers against α, while the promise bounds the joint risk (alone and wrong over all decisions): the signal is deliberately stricter than the promise. → {"short", "n", "alone", "error", "share", "why"}.

Bounded initial acquisition

DefaultPolicy(acquisition={"floor": 0.8, "max_extra": 600, "until_decision": 2400}) opts into a predictable uniform audit floor. None preserves the existing rate. The hook LoopPolicy.sampling_rate(state, base_rate) sees past state only, never this decision's input, label, score, owner or split. The same independent coin is used, and additive base and owner paths share this hook.

The controller stops boosting permanently once accepted distinct counts meet the initial training/growth and unchanged calibration/holdout floors, or after the first training. Readiness does not wait for an improvement signal. It never changes key roles, freeze or promotion gates. A missing/refused/repeated label cannot complete a distinct-key floor. Horizon or budget exhaustion leaves an open gap.

status()["acquisition"] reports reserved and remaining: one potential extra oracle call is reserved per boosted decision, even if the coin misses or another path would already have called the oracle. Repeated previews of the same decision share that reservation. A base rate already equal to one needs no reservation. These are conservative potential extras, not actual paid calls. Configuration and reservations survive checkpoint pickle; replay starts from the frozen initial policy. Extra acquisition spends additional oracle budget and does not establish that the original S315 500-label quality/cost requirement has been fixed.

This initial controller supports synchronous step only. Attachment and Dispatcher previews are rejected before issuing queries: multiple pending tickets do not have a supported reservation protocol yet. With acquisition enabled, an aborted step (including an oracle exception or a refused label source) permanently stops the acquisition feature, retains its potential-call reservations and journals an acquisition_stop control. Ordinary base auditing, valid labels and training can continue. The stop and reservation count survive save/load and replay. Missing labels (None) are ordinary completed decisions. Legacy policies keep existing error behavior and avoid extra sampling-state snapshots.