phenotypic.gui.tune package#

The /tune/ GUI co-pilot — a read-only view over a tune output dir.

The tune sub-app never re-optimizes; it only reads a finished or in-flight tuning run’s markers, trial journal, and study. This package’s import surface is deliberately optuna-free: importing phenotypic.gui.tune (and its _run_root / _study_read / _app helpers) must not import optuna. A study is read only through the StudyStore protocol / JournalStudyStore; the live OptunaStudyStore is opened lazily inside the Monitor poll callback, never at import / build time.

Exports:

TuneRunRoot: A validated, described handle on a tune output directory. TuneRunRootError: Raised when a directory is not a recognizable tune output. create_app: The Dash app factory (empty-state when root is None).

exception phenotypic.gui.tune.TuneRunRootError[source]#

Bases: ValueError

A directory is not a recognizable tune output.

Raised by TuneRunRoot.discover() when none of the three discovery markers resolves: no run.json, no study URL from a tuning_spec.json, and no trials.parquet.

add_note()#

Exception.add_note(note) – add a note to the exception

with_traceback()#

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#
class phenotypic.gui.tune.TuneRunRoot(path: Path, trials_path: Path | None, storage_url: str | None, study_name: str, directions: list[str] | None, images_dir: Path | None, best_pipeline_path: Path)[source]#

Bases: object

A validated handle on a tune output directory.

Parameters:

  • path (Path) – The tune output directory (the run’s --output root).

  • trials_path (Path | None) – The trial journal trials.parquet, or None when it has not been written yet (a live run discovered via run.json).

  • storage_url (str | None) – The resolved Optuna storage URL, or None when the run is parquet-journal-only.

  • study_name (str) – The study name ("tune_cost_v1").

  • directions (list[str] | None) – The per-objective Optuna directions (length ≥ 2) for a multi-objective run, or None for a single-objective study.

  • images_dir (Path | None) – The calibration image directory, or None when unknown (e.g. discovered from a tuning_spec.json or a legacy root).

  • best_pipeline_path (Path) – Where the tuned winner best_pipeline.json lives (a pure path expression; the file may not exist yet).

classmethod discover(path: Path) → TuneRunRoot[source]#

Validate path as a tune output and describe it.

Reads the three discovery markers in precedence order (run.json → tuning_spec.json → legacy trials.parquet root). Locates the trial journal via trials_parquet_path() and the tuned winner via best_pipeline_path() regardless of which marker matched.

Parameters:

path (Path) – The candidate tune output directory.

Returns:

The validated TuneRunRoot.

Raises:

TuneRunRootError – When path carries none of {run.json, a study URL from a tuning_spec.json, a trials.parquet}.

Return type:

TuneRunRoot

best_pipeline_path: Path#
directions: list[str] | None#
images_dir: Path | None#
path: Path#
storage_url: str | None#
study_name: str#
trials_path: Path | None#
phenotypic.gui.tune.create_app(root: TuneRunRoot | None = None, *, url_prefix: str = '/', sandbox: SandboxRoot | None = None, registry: object | None = None, runner: object | None = None) → dash.Dash[source]#

Build a configured Dash instance for the tune co-pilot.

Parameters:

  • root (Optional[TuneRunRoot]) – Validated tune output handle (see phenotypic.gui.tune.TuneRunRoot.discover()). None mounts the empty state: the page renders the pick-a-run prompt and the run picker, and the user binds a run at runtime (the bind callback writes TUNE_RUN_ROOT_STORE and swaps in the loaded views). A non-None root pre-binds the run (standalone launch / the loaded standalone capture).

  • url_prefix (str) – Mount-point prefix passed to dash.Dash as requests_pathname_prefix; routes_pathname_prefix stays MOUNT_HOME so the DispatcherMiddleware-stripped path matches. Standalone launches collapse to MOUNT_HOME (“/”); phenotypic.gui.shell._app.compose_hub() passes MOUNT_TUNE.

  • sandbox (Optional[SandboxRoot]) – The frozen-at-launch sandbox root. Both the runtime run picker (Chunk C) and the Curate view’s Image Source picker (Chunk B-ii) need it to bound directory selection / plate loads on a shared SSH tunnel; the hub composer passes it. When None both pickers degrade to a note (the standalone-without-sandbox path); a pre-bound root still renders its views.

  • registry (object | None)

  • runner (object | None)

Returns:

A configured dash.Dash; app.run(...) is the caller’s responsibility.

Return type:

dash.Dash

Notes

Callbacks are registered unconditionally (the factory always calls register_callbacks()), even for the empty-state mount. suppress_callback_exceptions=True makes that safe: the loaded views’ components only appear after a run is bound at runtime, but their callbacks must already be wired so they fire once the bind callback swaps the body in. The bind + view callbacks all key off TUNE_RUN_ROOT_STORE, so runtime binding makes them render.