phenotypic.tune.ScreeningController#

class phenotypic.tune.ScreeningController(spec: TuningSpec, *, config: ScreeningConfig = ScreeningConfig(free_param_floor=6, freeze_epsilon=0.1, warmup_floor=20, warmup_c=3, top_k=10), importance_report_fn: Callable[[Any], ImportanceReport] | None = None, engine_factory: Callable[[TuningSpec, Any], Any] | None = None, _focused_score_penalty: float = 0.0)[source]#

Bases: object

Orchestrate the explore → freeze → focused two-round screening flow.

The controller is engine-opt-in: a caller hands it a TuningSpec and a ScreeningConfig, and run() returns a ScreeningResult with the winner, the freeze decision, and the honesty flags. Both rounds’ stores are exposed (explore_store, focused_store) for the CLI to journal and for the winner-across-both-rounds rule.

Parameters:

  • spec (TuningSpec) – The tuning recipe (its search_space is the explore space; the focused round runs the reduced space).

  • config (ScreeningConfig) – The freeze thresholds.

  • importance_report_fn (Optional[Callable[[Any], ImportanceReport]]) – Override for the importance computation (defaults to compute_param_importance_report()); injected in tests to force a deterministic freeze decision.

  • engine_factory (Optional[Callable[[TuningSpec, Any], Any]]) – Builds a tuning engine from (spec, store); defaults to the real TuningEngine. Injectable for tests.

  • _focused_score_penalty (float) – Test seam — add this to every fresh focused-round score (raise its cost) to exercise the wrong-freeze recovery path. Never set in production (default 0.0).

Methods

__init__

run

Run the (possibly two-round) screening flow over images.
run(images: list) → ScreeningResult[source]#

Run the (possibly two-round) screening flow over images.

Parameters:

images (list) – The calibration images (non-empty).

Returns:

The ScreeningResult (winner across both rounds, the freeze decision, and the honesty flags).

Return type:

ScreeningResult