mixle.doe.oracle module

Verifiable oracle boundary for de novo optimization.

Given a design goal for which there is no data yet but there IS a way to check a candidate (a simulator, an executable test, held-out truth, an assay), optimize_under_oracle() proposes candidates, verifies them against the oracle, and keeps a full receipted history of what was tried and why – the design-test-learn loop, made accountable, rather than “synthesize data and train” with no account of what verified it.

The one hard precondition, checked before anything else: there must be a verifiable oracle. VerifiableOracle rejects a “self-graded by a model” tier at CONSTRUCTION – that is the banned reward this boundary exists to forbid – and optimize_under_oracle() refuses to run at all without one (oracle=None -> the explicit “no verifiable objective; cannot optimize” refusal, never a fabricated candidate).

This is a first, deliberately narrow slice: continuous/low-dimensional candidate spaces only, using the GP Bayesian-optimization loop already in mixle.doe (BayesianOptimizer) as the proposal model, validated here against a low-cost closed-form oracle before any domain oracle exists. Not in this slice: structured/discrete candidate spaces (a protein sequence, a program), amortizing the oracle into a calibrated surrogate, the shared expected-information- gain acquisition, and full receipt objects – each is a separate surface and is left explicit rather than half-built here.

class OracleResult(score, receipt=<factory>, cost=1.0)[source]

Bases: object

One candidate’s verification outcome: its score, a receipt of how it was scored, and its cost.

Parameters:
class VerifiableOracle(name, tier, score_fn, fidelity=None, timeout=None)[source]

Bases: object

A callable candidate -> OracleResult that declares its verifiability tier and fidelity.

score_fn does the actual verification (wrap a simulator, an executable check, a held-out ground-truth lookup, or a real measurement pipeline; mixle.task.toolcall’s ToolCaller is the same “external check as a callable” shape for tool calls). Construction raises if tier is not one of VERIFIABILITY_TIERS – “self-graded by a model” is not a valid tier and is rejected here, not silently accepted and discovered later.

Parameters:
class DesignCandidate(x, result)[source]

Bases: object

One proposed-and-verified candidate: the point tried and what the oracle said about it.

Parameters:

  • x (ndarray)

  • result (OracleResult)

class DesignRun(oracle_name, oracle_tier, oracle_fidelity, history=<factory>)[source]

Bases: object

The full receipted history of a design loop: every candidate tried, and the oracle’s identity.

Parameters:

  • oracle_name (str)

  • oracle_tier (str)

  • oracle_fidelity (str | None)

  • history (list[DesignCandidate])

property oracle_calls: int

Return the number of candidates scored by the oracle.

property best: DesignCandidate

Return the highest-scoring candidate in the run history.

scores()[source]

Return the run’s oracle scores in chronological order.

Return type:

ndarray

report()[source]

Named receipt of the run: which oracle, at what tier/fidelity, the best candidate found.

Return type:

dict[str, Any]

optimize_under_oracle(oracle, bounds, *, n_init=5, n_iter=15, seed=None, **bo_kwargs)[source]

Run a propose-verify-refit design loop under a fixed oracle budget.

The loop proposes candidates, verifies each one with oracle, keeps the receipted history, refits the proposal model on every observation, and repeats under an n_init + n_iter budget.

oracle=None raises immediately with the explicit refusal (“no verifiable objective; cannot optimize”) – the hard precondition checked before any candidate is proposed. Continuous/low-dimensional bounds only (see module docstring); the proposal model is BayesianOptimizer, maximizing the oracle’s score.

Parameters:
Return type:

DesignRun