OCDocker.Workbench.OptunaDashboard module

Local Optuna dashboard launcher used by the Workbench server and CLI. When dashboard ports are not configured explicitly, slot count follows the resolved OCScore replica count (clamped between 1 and 50) and each dashboard binds to the first free port after the Workbench server port.

Local Optuna dashboard launcher for the OCScore Workbench.

exception OCDocker.Workbench.OptunaDashboard.OptunaDashboardError(message, *, status_code=400)[source]

Bases: Exception

Raised when Optuna dashboard launch or lookup fails.

Parameters:

  • message (str)

  • status_code (int)

Return type:

None

class OCDocker.Workbench.OptunaDashboard.OptunaDashboardManager(root, *, host='127.0.0.1', server_port=None, port_start=None, port_end=None, slot_count)[source]

Bases: object

Launch and track local Optuna dashboard processes for replica databases.

Parameters:

  • root (str | Path)

  • host (str)

  • server_port (int | None)

  • port_start (int | None)

  • port_end (int | None)

  • slot_count (int)

static is_available()[source]

Return whether an Optuna dashboard launcher is available locally.

Return type:

bool

static resolve_replica_storage(replica_path)[source]

Return the Optuna SQLite database for one replica directory.

Parameters:

replica_path (pathlib.Path) – Replica output directory.

Returns:

Resolved Optuna database path.

Return type:

pathlib.Path

allowed_roots()[source]

Return filesystem roots that may host replica Optuna databases.

Return type:

tuple[Path, …]

validate_replica_path(replica_path)[source]

Resolve and authorize one replica directory path.

Parameters:

replica_path (pathlib.Path) – Requested replica directory.

Returns:

Resolved replica directory.

Return type:

pathlib.Path

start(replica_path)[source]

Launch or reuse an Optuna dashboard for one replica.

Parameters:

replica_path (str or pathlib.Path) – Replica directory containing optuna.db.

Returns:

JSON-safe session payload.

Return type:

dict[str, Any]

status(replica_path=None)[source]

Return dashboard session status for one replica or all sessions.

Parameters:

replica_path (str, pathlib.Path, or None) – Optional replica directory filter.

Returns:

JSON-safe status payload.

Return type:

dict[str, Any]

stop(replica_path)[source]

Stop a running Optuna dashboard for one replica.

Parameters:

replica_path (str or pathlib.Path) – Replica directory.

Returns:

JSON-safe stop result.

Return type:

dict[str, Any]

stop_all()[source]

Stop every tracked Optuna dashboard process.

Return type:

None

cleanup_dead()[source]

Drop sessions whose child processes have already exited.

Return type:

None

class OCDocker.Workbench.OptunaDashboard.OptunaDashboardSession(replica_path, storage_path, host, port, pid, url)[source]

Bases: object

One locally launched Optuna dashboard process.

Parameters:

  • replica_path (str)

  • storage_path (str)

  • host (str)

  • port (int)

  • pid (int)

  • url (str)

replica_path: str
storage_path: str
host: str
port: int
pid: int
url: str
OCDocker.Workbench.OptunaDashboard.discover_free_ports(host, start, count, *, max_probe=256)[source]

Return the first count free TCP ports at or above start.

Parameters:

  • host (str) – Bind host to probe.

  • start (int) – First candidate port.

  • count (int) – Number of free ports to discover.

  • max_probe (int) – Maximum number of candidate ports to inspect.

Returns:

Discovered free ports in ascending order.

Return type:

list[int]