mixle.system.meta module

Heuristic allocation of improvement effort against a held-out scorecard.

Given a System and a set of ImprovementOption actions, each with an estimated cost and estimated recoverable scorecard quality, this module spends the budget on the highest estimated gain-per-dollar option first. Only realized gain is trusted: evaluate() remeasures the scorecard before and after each option runs, and detect_regression() stops the allocation immediately when a round regresses.

This module provides a deterministic heuristic baseline. A learned meta-policy should replace it only after it demonstrates better realized scorecard gain per dollar under the same measurement protocol.

class ImprovementOption(name, cost, run, estimated_regret)[source]

Bases: object

Candidate improvement action with estimated cost and recoverable quality gain.

cost must be finite and nonnegative and estimated_regret finite. Neither was checked, so under budget=0 an option costing -5 ran and reported spent=-5 (running work created budget), and a NaN-cost option ran too, because the over-budget comparison spent + cost > budget is false for NaN – the ceiling failed open – and left spent=NaN behind.

Parameters:
property regret_per_dollar: float

Estimated recoverable gain per unit cost.

class MetaImprovementReport(order=<factory>, skipped=<factory>, scorecard_before=None, scorecard_after=None, realized_gain_per_dollar=<factory>, spent=0.0, stopped_on_regression=None)[source]

Bases: object

Execution report for a budgeted meta-improvement run.

Parameters:

  • order (list[str])

  • skipped (list[str])

  • scorecard_before (SystemScorecard | None)

  • scorecard_after (SystemScorecard | None)

  • realized_gain_per_dollar (dict[str, float])

  • spent (float)

  • stopped_on_regression (RegressionReport | None)

improve_by_regret(system, question_set, options, *, budget)[source]

Run options by estimated gain per dollar and stop on measured regression.

budget must be finite and nonnegative, and option names must be unique – order, skipped and realized_gain_per_dollar are all keyed by name, so duplicates silently overwrite each other’s measured result.

Note what this does NOT do: opt.run() mutates the live system before any measurement, and a regression detected afterwards only stops further options – the regressing change stays applied. Callers who need rejection to restore the previous state must run options against a system they can themselves discard. report.stopped_on_regression names the round that regressed so that decision can be made.

Parameters:
Return type:

MetaImprovementReport