mixle.inference.reproduce module

Reproducibility receipts – record a fit so it can be replayed and its content re-checked (N2).

A fitted model is only reproducible if someone else can re-derive it from the same complete request. fit_and_record() executes one materialized request; record_fit() binds an existing result to the exact ordered data, estimator code and state, optimizer code, seed and fit policy, dependency/source environment, and returned model. verify_reproducible() re-executes that request and requires every declared identity and observed result to match.

The legacy data_fingerprint and param_fingerprint remain tolerance-equivalent diagnostics: floats are rounded to _NDIGITS (10) decimal places. The v2 receipt additionally carries full exact SHA-256 data and model digests. Therefore:

  • last-bit drift may retain the diagnostic fingerprint but fails exact data/model or environment checks;

  • a real content, executable, policy, dependency, or source-tree change fails its named check;

  • a verdict cannot pass merely because an expected check was omitted.

A matching replay certifies identity and execution under the recorded contract, not statistical correctness; calibration and model-quality claims require their own evidence.

data_fingerprint(data, *, ndigits=_NDIGITS)[source]

A stable hash of a training dataset (order-sensitive; floats rounded) – identifies the exact input.

Parameters:
Return type:

str

param_fingerprint(model, *, ndigits=_NDIGITS)[source]

A stable hash of a fitted model’s parameters, via its to_json state (floats rounded).

Parameters:
Return type:

str

class ReproReceipt(data_fingerprint, n, seed, estimator, param_fingerprint, max_its=10, delta=1e-09, schema_version='mixle-repro-v2', data_digest='', model_digest='', estimator_implementation_digest='', estimator_state_digest='', optimizer_implementation_digest='', dependency_digest='', environment=<factory>, fit_policy=<factory>, fit_policy_digest='', execution_digest='', receipt_digest='')[source]

Bases: object

The complete executable recipe and observed result needed to re-derive a fit.

max_its/delta must match whatever was actually passed to the original optimize() call that produced the fingerprinted model (they default to optimize()’s own defaults). Without these, verify_reproducible() cannot replay the same fit – an iterative estimator refit with a different iteration budget or convergence tolerance can land at a different (if nearby) optimum and spuriously report reproducible: False for a fit that would have reproduced exactly under its own original settings.

Parameters:

  • data_fingerprint (str)

  • n (int)

  • seed (int)

  • estimator (str)

  • param_fingerprint (str)

  • max_its (int)

  • delta (float | None)

  • schema_version (str)

  • data_digest (str)

  • model_digest (str)

  • estimator_implementation_digest (str)

  • estimator_state_digest (str)

  • optimizer_implementation_digest (str)

  • dependency_digest (str)

  • environment (dict[str, Any])

  • fit_policy (dict[str, Any])

  • fit_policy_digest (str)

  • execution_digest (str)

  • receipt_digest (str)

as_dict()[source]

Return the receipt as JSON-compatible data.

Return type:

dict[str, Any]

matches_data(data)[source]

Whether data is the exact dataset this fit was recorded on.

Parameters:

data (Any)

Return type:

bool

matches_model(model)[source]

Whether model has the exact parameters this receipt fingerprinted.

Parameters:

model (Any)

Return type:

bool

record_fit(model, data, *, seed, estimator=None, max_its=10, delta=1.0e-9, fit_options=None)[source]

Record a ReproReceipt for a model fitted on data with seed (see module docstring).

Pass the same max_its/delta actually used for the fit being recorded (they default to optimize()’s own defaults); verify_reproducible() replays the fit with these exact values.

Parameters:
Return type:

ReproReceipt

fit_and_record(data, estimator, *, seed, max_its=10, delta=1.0e-9, fit_options=None)[source]

Execute one materialized fit and return the model with its complete replay receipt.

Parameters:
Return type:

tuple[Any, ReproReceipt]

verify_reproducible(estimator, data, receipt, *, seed=None, max_its=None)[source]

Refit estimator on data and check the fit reproduces receipt (data + parameters).

Returns {reproducible, data_matches, params_match, refit_fingerprint}. reproducible is True iff BOTH the data fingerprint and the refit’s parameter fingerprint match the receipt – i.e. the exact fit can be recovered from the recorded recipe. seed defaults to the receipt’s seed. max_its defaults to the receipt’s own recorded value (the iteration budget the original fit actually used); delta always replays the receipt’s recorded value – a refit run with a different iteration budget or convergence tolerance than the original fit can land at a different (if nearby) optimum and spuriously report reproducible: False for a fit that would have reproduced exactly under its own original settings.

Parameters:

  • estimator (Any)

  • data (Any)

  • receipt (ReproReceipt)

  • seed (int | None)

  • max_its (int | None)

Return type:

dict[str, Any]