mixle.evolve.improve module

The one-shot self-improvement driver: propose -> verify -> pick the best verified win (or nothing).

improve is the minimal closed loop. It splits the data once into a train and a held-out verify split, proposes a challenger from every applicable operator on the train split, gates each challenger against the champion on the verify split, and returns the verified challenger with the largest delta (ties broken toward the cheaper operator). If nothing verifies it returns the unchanged champion with verified=False – the anti-regression guarantee: improve can never hand back a worse model.

Every attempt is recorded to the ledger, so the run leaves an honest, serializable trail of what was tried and why it won or lost.

class ImprovementResult(model, verified, operator, delta, verdict, evidence=<factory>, parent_hash=None)[source]

Bases: object

The outcome of an improve() run.

Parameters:

  • model (Any)

  • verified (bool)

  • operator (str | None)

  • delta (float)

  • verdict (Verdict | None)

  • evidence (dict)

  • parent_hash (str | None)

model: Any
verified: bool
operator: str | None
delta: float
verdict: Verdict | None
evidence: dict
parent_hash: str | None = None
improve(model, data, *, objective, operators=None, holdout=0.25, alpha=0.05, min_effect=0.0, budget=None, seed=0, ledger=None, parent_hash=None, require_calibration=True)[source]

Propose challengers, gate them, and return the best verified improvement (or the champion).

Parameters:

  • model (Any) – the champion (a fitted mixle distribution).

  • data (Sequence[Any]) – the raw held-out dataset (split once into train/verify here).

  • objective (Objective) – the Objective to improve on.

  • operators (Sequence[ImprovementOperator] | None) – the proposal moves; defaults to the applicable subset of [Refit, OnlineUpdate, AutoSelect, Recalibrate].

  • holdout (float | tuple) – train/verify split fraction, or an explicit (train, verify) tuple.

  • alpha (float) – significance level for the verify gate.

  • min_effect (float) – practical effect-size floor passed to the gate.

  • budget (float | None) – optional cost ceiling – operators whose cost_hint exceeds the remaining budget are skipped (cheapest-first).

  • seed (int) – RNG seed for the split and the sampled objectives.

  • ledger (EvolutionLedger | None) – optional EvolutionLedger to record every attempt into.

  • parent_hash (str | None) – optional lineage hash for the champion (carried onto candidates and ledger rows).

  • require_calibration (bool) – forward to the gate’s calibration no-regression check.

Returns:

An ImprovementResult. result.verified is True guarantees result.model beat the champion significantly and non-regressively on the verify split.

Return type:

ImprovementResult