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 ¶
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).
MirrorBound ¶
MeanBound(m = 1 − alpha) fed x = 1 − loss: the aGRAPA bet, certifying "the mean loss is below alpha".
dump ¶
The aGRAPA bet's state (log evidence, count, its predictable estimates): restore() gives it back exactly.
Mixture ¶
A mixture of constant bets against "the mean loss is at least alpha". update(loss) with loss in [0, 1].
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
¶
The log-wealth a point needs under the current index (None before the first bet: no δ_v yet).
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 ¶
Whether the grid point lam is certified (False for a value that is not a grid point, or before the grid).
log_wealth_at ¶
The log-wealth of grid point lam's e-process now (None: not a grid point, or no grid yet).
prime_grid ¶
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 ¶
One gated decision (no label): counted, and its score read for the auto grid until it is fixed.
learn ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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)·α).
update ¶
One deployed loss in [0, 1] → True when this sample raises the alarm (the flag stays up until reset()).
observe ¶
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.
dump ¶
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 ¶
→ self, in the state of dump(); a dump of another configuration is refused (ValueError).
config ¶
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 ¶
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 ¶
Conservative worst-case extra oracle reservations; refused/duplicate labels still cost a reservation.
why_not_train ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Each pre-freeze gate's result → {"heldout", "act_guard", "honesty", "time"[, "paired_gain"]}, each with "ok" and "why".
promote_checks ¶
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 ¶
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 ¶
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
¶
One stored label: the input's content key, the input, the label, its source, the decision it came at.
LoopPolicy ¶
Bases: ABC
See the module docstring. Subclass and give every hook; budget (a Budget) is read by the loop too.
budget
property
writable
¶
The Budget (the defaults when none was set, also for a subclass whose init skips super().init).
sampling_rate ¶
Predictable uniform coin rate from past state only; legacy default unchanged.
split
abstractmethod
¶
"train" | "calib" | "holdout" for a content key; the same key must always get the same split.
select
abstractmethod
¶
The train rows (LabelRow) that go into this training.
hyper
abstractmethod
¶
The training's settings: r, lr, updates, seed, ...
freeze
abstractmethod
¶
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
¶
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
¶
Why the candidate is discarded now, or None to keep trialling (paired as for promote).
alarm
abstractmethod
¶
An alarm on the served version (who: "detector" or "monitor") → "recertify", "rollback:
watch ¶
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
¶
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
¶
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
¶
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
¶
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 ¶
A frozen copy of a FastHeadLearner (None head: not fitted yet — it answers nothing, score -inf).
of_system
classmethod
¶
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 ¶
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.
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).
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: "
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 ¶
One synchronous decision; an aborted attempt permanently stops optional acquisition.
label ¶
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 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 ¶
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 ¶
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 (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 ¶
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 ¶
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 ¶
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 ¶
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 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
¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
{"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.
LoraLearner ¶
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 ¶
A train label: counted; the rows of a training come with its job (the loop keeps them).
train ¶
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 ¶
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
¶
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
¶
The threshold the adapter loop's pre-freeze report applies to score's signal (= threshold).
of_part
classmethod
¶
Version 0: the part as it is now — its adapter (or none) and its calibration.
bind ¶
Serve and score on part (its version lock is created; the adapter is staged on its scorer) → self.
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 ¶
→ (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 ¶
Serve this version on its part (system: unused — the part is the version's own): the atomic swap. → {"from", "to"}: the part's fingerprints.
load
classmethod
¶
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 ¶
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 ¶
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 ¶
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 ¶
ρ_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 ¶
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.
issue ¶
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 ¶
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 ¶
The Thought of a path whose contract does not apply to the input (it is not asked), else None.
verdict ¶
The agent's label → the slow path's Thought (accepted unless the contract refuses it).
lost ¶
No verdict (an expired or failed ticket) → the Thought that sends the input to a person.
TicketDesk ¶
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.
decide ¶
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 ¶
What the agent sees of a ticket: a function of the ticket id, the question and the input only.
resolve ¶
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 ¶
Give up an open ticket now (a failed oracle) → its Dispatched: recorded as lost (see the module docs).
sweep ¶
Expire every open ticket past its ttl → their Dispatched (each recorded as lost).
oracle ¶
Blind labeler capability: durable pending queue, verdict acknowledgments, no decide.
call_tool ¶
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 × 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 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 ¶
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 ¶
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 ¶
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 ¶
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
¶
The log-wealth a point needs under the current index (None before the first bet: no δ_v yet).
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 ¶
Whether the grid point lam is certified (False for a value that is not a grid point, or before the grid).
log_wealth_at ¶
The log-wealth of grid point lam's e-process now (None: not a grid point, or no grid yet).
prime_grid ¶
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 ¶
One gated decision (no label): counted, and its score read for the auto grid until it is fixed.
learn ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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)·α).
update ¶
One deployed loss in [0, 1] → True when this sample raises the alarm (the flag stays up until reset()).
observe ¶
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.
dump ¶
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 ¶
→ self, in the state of dump(); a dump of another configuration is refused (ValueError).
config ¶
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 ¶
ρ_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 ¶
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.
issue ¶
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 ¶
The message of the calibration coin of decision n: no input bytes.
coin_value ¶
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 ¶
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 ¶
The Thought of a path whose contract does not apply to the input (it is not asked), else None.
verdict ¶
The agent's label → the slow path's Thought (accepted unless the contract refuses it).
lost ¶
No verdict (an expired or failed ticket) → the Thought that sends the input to a person.
TicketDesk ¶
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.
decide ¶
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 ¶
What the agent sees of a ticket: a function of the ticket id, the question and the input only.
resolve ¶
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 ¶
Give up an open ticket now (a failed oracle) → its Dispatched: recorded as lost (see the module docs).
sweep ¶
Expire every open ticket past its ttl → their Dispatched (each recorded as lost).
oracle ¶
Blind labeler capability: durable pending queue, verdict acknowledgments, no decide.
call_tool ¶
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 × the live learner's labels at the latest discard (0 before any).
ticket_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 ownFastHead(the headSystem.fitbuilds) over facts; the firstmin_fitlabels are kept and fitted once, every later one isFastHead.teach(a rank-one update; its refit schedule asSystem.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 freshHashedTextLearneron the job's rows (shuffled by the job's seed,epochspasses) 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: "
FrozenError ¶
Bases: TypeError
A frozen model was asked to learn.
FrozenText ¶
A frozen copy of a HashedTextLearner (see the module docstring).
as_head ¶
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.
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).
FrozenFast ¶
A frozen copy of a FastHeadLearner (None head: not fitted yet — it answers nothing, score -inf).
of_system
classmethod
¶
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 ¶
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
¶
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; withrefreezegiven 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 lastwindow(200) held-out labels the served version answers nothing alone, or errs alone above the promised α, or answers alone on less thantarget_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 (atwilson, 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 bytrialdecisions 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
wilsonconfidence; a point-estimate gap at n = 30 does not discard); not certifiedstale(3000) decisions after its freeze; certified and not promotabletrial(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 lastmature_patiencecoin 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 −wilsonper 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 baseLoopPolicy.watchreturns 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 ¶
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
¶
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
¶
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
¶
The served version's share alone at its own threshold (the old comparison); None when not counted.
Watch
dataclass
¶
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 ¶
Bases: ABC
See the module docstring. Subclass and give every hook; budget (a Budget) is read by the loop too.
budget
property
writable
¶
The Budget (the defaults when none was set, also for a subclass whose init skips super().init).
sampling_rate ¶
Predictable uniform coin rate from past state only; legacy default unchanged.
split
abstractmethod
¶
"train" | "calib" | "holdout" for a content key; the same key must always get the same split.
select
abstractmethod
¶
The train rows (LabelRow) that go into this training.
hyper
abstractmethod
¶
The training's settings: r, lr, updates, seed, ...
freeze
abstractmethod
¶
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
¶
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
¶
Why the candidate is discarded now, or None to keep trialling (paired as for promote).
alarm
abstractmethod
¶
An alarm on the served version (who: "detector" or "monitor") → "recertify", "rollback:
watch ¶
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 ¶
Conservative worst-case extra oracle reservations; refused/duplicate labels still cost a reservation.
why_not_train ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
Each pre-freeze gate's result → {"heldout", "act_guard", "honesty", "time"[, "paired_gain"]}, each with "ok" and "why".
promote_checks ¶
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 ¶
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 ¶
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 ¶
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 →
UntrustedLabelbefore anything changes. A learner's optionaloptions(or its question part's options) is also checked: an out-of-set target raisesValueErrorbefore 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, elsequestion|vhash(x), the change pipeline'scontent_keyfor 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 asnapshot(); a batch learner (train(job)) gets aTrainJobwith the rows ofselect(st, train rows)and the settings ofhyper(st). The loop checkspolicy.budget.refusebefore every training (a policy cannot spend past its budget);status()["job"]andLoopState.jobshow the training while it runs (in process: stage 2 has no runner). - freeze(st, report) — the
TrainReportscores the trained model and the served one on the held-out labels (latest label per key); the trained model's threshold is its ownact_thresholdwhen it has one, elsegates.calib_thresholdon 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.
Pairedcounts 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'strain_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 solviMonitor,observe(score) → {"drift", "why"}, fed the served version's finite score on every decision outside probation; defaultNumericDrift). 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(), elsereset()) 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 ¶
One synchronous decision; an aborted attempt permanently stops optional acquisition.
label ¶
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 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 ¶
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 ¶
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 (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 ¶
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 ¶
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 ¶
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 ¶
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 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
¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
{"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.
ticket_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 ¶
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 ¶
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 ¶
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
¶
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
¶
The threshold the adapter loop's pre-freeze report applies to score's signal (= threshold).
of_part
classmethod
¶
Version 0: the part as it is now — its adapter (or none) and its calibration.
bind ¶
Serve and score on part (its version lock is created; the adapter is staged on its scorer) → self.
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 ¶
→ (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 ¶
Serve this version on its part (system: unused — the part is the version's own): the atomic swap. → {"from", "to"}: the part's fingerprints.
load
classmethod
¶
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 ¶
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 ¶
A train label: counted; the rows of a training come with its job (the loop keeps them).
train ¶
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 ¶
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 ¶
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),nice10, its torch / BLAS threads capped atbudget.cpu_threads, the device picked bypick_device(budgetdevice="auto": cuda when a GPU hasfree_gpu_mbfree, 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 everyheartbeat_s, 30 s), the payload as<name>.job.pkland 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 ¶
See the module docstring.
estimate ¶
The training's estimated time, before it trains: logged; above budget.max_train_s → TrainingRefused.
ThreadRunner ¶
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 ¶
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 ¶
"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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.