OCDocker.Workbench.Models module

Declarative models for the OCDocker experiment workbench.

class OCDocker.Workbench.Models.ExportedArtifact(*, name, source_path, export_path=None, kind='other', role='', description='', exists=False, copied=False)

Bases: WorkbenchModel

Artifact entry prepared for a publishable Workbench export.

Parameters:

• name (str)

• source_path (Path)

• export_path (Path | None)

• kind (Literal['json', 'csv', 'html', 'markdown', 'pdf', 'image', 'database', 'log', 'directory', 'other'])

• role (str)

• description (str)

• exists (bool)

• copied (bool)

name: str

source_path: Path

export_path: Path | None

kind: ArtifactKind

role: str

description: str

exists: bool

copied: bool

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.FeaturePolicySelection(*, names=(), policy_dirs=(), policy_ymls=(), run_all=False)

Bases: WorkbenchModel

Feature-policy selection for OCScore optimization or ablation runs.

Parameters:

• names (tuple[str, ...])

• policy_dirs (tuple[Path, ...])

• policy_ymls (tuple[Path, ...])

• run_all (bool)

names

Model field.

Type:

tuple[str, …]

policy_dirs

Model field.

Type:

tuple[Path, …]

policy_ymls

Model field.

Type:

tuple[Path, …]

run_all

Model field.

Type:

bool

names: tuple[str, ...]

policy_dirs: tuple[Path, ...]

policy_ymls: tuple[Path, ...]

run_all: bool

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.InventoryIssue(*, path, message)

Bases: WorkbenchModel

Non-fatal issue found while scanning a Workbench root.

Parameters:

• path (Path)

• message (str)

path: Path

message: str

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.MetricLeaderboardEntry(*, manifest_path, run_id, status, metric_name, metric_value=None, rank=None, metrics=<factory>, artifact_count=0, missing_artifact_count=0, included=False, exclusion_reason='')

Bases: WorkbenchModel

One result-manifest row in a metric leaderboard.

Parameters:

• manifest_path (Path)

• run_id (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• metric_name (str)

• metric_value (float | None)

• rank (int | None)

• metrics (dict[str, Any])

• artifact_count (int)

• missing_artifact_count (int)

• included (bool)

• exclusion_reason (str)

manifest_path: Path

run_id: str

status: RunStatus

metric_name: str

metric_value: float | None

rank: int | None

metrics: dict[str, Any]

artifact_count: int

missing_artifact_count: int

included: bool

exclusion_reason: str

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.MetricMatrixRow(*, manifest_path, run_id, status, metric_values=<factory>, raw_metrics=<factory>, missing_metrics=(), non_numeric_metrics=(), artifact_count=0, missing_artifact_count=0)

Bases: WorkbenchModel

One result-manifest row in a metric matrix.

Parameters:

• manifest_path (Path)

• run_id (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• metric_values (dict[str, float])

• raw_metrics (dict[str, Any])

• missing_metrics (tuple[str, ...])

• non_numeric_metrics (tuple[str, ...])

• artifact_count (int)

• missing_artifact_count (int)

manifest_path: Path

run_id: str

status: RunStatus

metric_values: dict[str, float]

raw_metrics: dict[str, Any]

missing_metrics: tuple[str, ...]

non_numeric_metrics: tuple[str, ...]

artifact_count: int

missing_artifact_count: int

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.MetricMatrix(*, root, max_depth=6, scanned_at=<factory>, metric_names=(), rows=(), result_manifest_count=0, issue_count=0, issues=())

Bases: WorkbenchModel

Read-only matrix of numeric metrics across result manifests.

Parameters:

• root (Path)

• max_depth (int)

• scanned_at (datetime)

• metric_names (tuple[str, ...])

• rows (tuple[MetricMatrixRow, ...])

• result_manifest_count (int)

• issue_count (int)

• issues (tuple[InventoryIssue, ...])

root: Path

max_depth: int

scanned_at: datetime

metric_names: tuple[str, ...]

rows: tuple[MetricMatrixRow, ...]

result_manifest_count: int

issue_count: int

issues: tuple[InventoryIssue, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.MetricLeaderboard(*, root, metric_name, mode='max', max_depth=6, scanned_at=<factory>, ranked_entries=(), skipped_entries=(), best_entry=None, issue_count=0, issues=())

Bases: WorkbenchModel

Read-only ranking of result manifests by one numeric metric.

Parameters:

• root (Path)

• metric_name (str)

• mode (Literal['min', 'max'])

• max_depth (int)

• scanned_at (datetime)

• ranked_entries (tuple[MetricLeaderboardEntry, ...])

• skipped_entries (tuple[MetricLeaderboardEntry, ...])

• best_entry (MetricLeaderboardEntry | None)

• issue_count (int)

• issues (tuple[InventoryIssue, ...])

root: Path

metric_name: str

mode: MetricSortMode

max_depth: int

scanned_at: datetime

ranked_entries: tuple[MetricLeaderboardEntry, ...]

skipped_entries: tuple[MetricLeaderboardEntry, ...]

best_entry: MetricLeaderboardEntry | None

issue_count: int

issues: tuple[InventoryIssue, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.ParetoFront(*, root, max_depth=6, scanned_at=<factory>, objectives, front_entries=(), dominated_entries=(), skipped_entries=(), result_manifest_count=0, issue_count=0, issues=())

Bases: WorkbenchModel

Read-only multi-objective Pareto-front summary.

Parameters:

• root (Path)

• max_depth (int)

• scanned_at (datetime)

• objectives (tuple[ParetoObjective, ...])

• front_entries (tuple[ParetoEntry, ...])

• dominated_entries (tuple[ParetoEntry, ...])

• skipped_entries (tuple[ParetoEntry, ...])

• result_manifest_count (int)

• issue_count (int)

• issues (tuple[InventoryIssue, ...])

root: Path

max_depth: int

scanned_at: datetime

objectives: tuple[ParetoObjective, ...]

front_entries: tuple[ParetoEntry, ...]

dominated_entries: tuple[ParetoEntry, ...]

skipped_entries: tuple[ParetoEntry, ...]

result_manifest_count: int

issue_count: int

issues: tuple[InventoryIssue, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.ParetoEntry(*, manifest_path, run_id, status, metric_values=<factory>, missing_metrics=(), non_numeric_metrics=(), dominated_by=(), included=False)

Bases: WorkbenchModel

One result-manifest entry considered for a Pareto front.

Parameters:

• manifest_path (Path)

• run_id (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• metric_values (dict[str, float])

• missing_metrics (tuple[str, ...])

• non_numeric_metrics (tuple[str, ...])

• dominated_by (tuple[str, ...])

• included (bool)

manifest_path: Path

run_id: str

status: RunStatus

metric_values: dict[str, float]

missing_metrics: tuple[str, ...]

non_numeric_metrics: tuple[str, ...]

dominated_by: tuple[str, ...]

included: bool

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.ParetoObjective(*, metric_name, mode='max')

Bases: WorkbenchModel

One metric objective used to build a Pareto front.

Parameters:

• metric_name (str)

• mode (Literal['min', 'max'])

metric_name: str

mode: MetricSortMode

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.MetricCatalog(*, root, max_depth=6, scanned_at=<factory>, result_manifest_count=0, metric_count=0, metrics=(), issue_count=0, issues=())

Bases: WorkbenchModel

Read-only coverage catalog for metrics across result manifests.

Parameters:

• root (Path)

• max_depth (int)

• scanned_at (datetime)

• result_manifest_count (int)

• metric_count (int)

• metrics (tuple[MetricCatalogEntry, ...])

• issue_count (int)

• issues (tuple[InventoryIssue, ...])

root: Path

max_depth: int

scanned_at: datetime

result_manifest_count: int

metric_count: int

metrics: tuple[MetricCatalogEntry, ...]

issue_count: int

issues: tuple[InventoryIssue, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.MetricCatalogEntry(*, metric_name, observed_count=0, numeric_count=0, non_numeric_count=0, missing_count=0, min_value=None, max_value=None, mean_value=None)

Bases: WorkbenchModel

Coverage and numeric summary for one discovered metric.

Parameters:

• metric_name (str)

• observed_count (int)

• numeric_count (int)

• non_numeric_count (int)

• missing_count (int)

• min_value (float | None)

• max_value (float | None)

• mean_value (float | None)

metric_name: str

observed_count: int

numeric_count: int

non_numeric_count: int

missing_count: int

min_value: float | None

max_value: float | None

mean_value: float | None

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.OCScoreAblationSpec(*, schema_version=1, type='ocscore_ablation', name, protocol, inputs, output_dir, feature_policies, include_full_reference=True, description='', tags=())

Bases: WorkbenchModel

Feature-policy ablation process backed by ocdocker ocscore train.

Parameters:

• schema_version (int)

• type (Literal['ocscore_ablation'])

• name (str)

• protocol (str | Path)

• inputs (OCScoreInputSpec)

• output_dir (Path)

• feature_policies (FeaturePolicySelection)

• include_full_reference (bool)

• description (str)

• tags (tuple[str, ...])

schema_version

Model field.

Type:

int

type

Model field.

Type:

Literal[‘ocscore_ablation’]

name

Model field.

Type:

str

protocol

Model field.

Type:

str | Path

inputs

Model field.

Type:

OCScoreInputSpec

output_dir

Model field.

Type:

Path

feature_policies

Model field.

Type:

FeaturePolicySelection

include_full_reference

Model field.

Type:

bool

description

Model field.

Type:

str

tags

Model field.

Type:

tuple[str, …]

schema_version: int

type: Literal['ocscore_ablation']

name: str

protocol: str | Path

inputs: OCScoreInputSpec

output_dir: Path

feature_policies: FeaturePolicySelection

include_full_reference: bool

description: str

tags: tuple[str, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchOCScoreWorkspace(*, root, scanned_at=<factory>, expected_replica_count=5, max_depth=6, baseline_study, ablation_studies=(), external_baselines=(), study_count=0, replica_count=0, completed_count=0, failed_count=0, missing_count=0, metric_names=(), issue_count=0, issues=(), protocol=None, run_context=None)

Bases: WorkbenchModel

Strict OCScore workspace payload used by the Workbench dashboard.

Parameters:

• root (Path)

• scanned_at (datetime)

• expected_replica_count (int)

• max_depth (int)

• baseline_study (WorkbenchOCScoreStudy)

• ablation_studies (tuple[WorkbenchOCScoreStudy, ...])

• external_baselines (tuple[WorkbenchOCScoreExternalBaseline, ...])

• study_count (int)

• replica_count (int)

• completed_count (int)

• failed_count (int)

• missing_count (int)

• metric_names (tuple[str, ...])

• issue_count (int)

• issues (tuple[InventoryIssue, ...])

• protocol (WorkbenchOCScoreProtocolSummary | None)

• run_context (WorkbenchOCScoreRunContext | None)

root: Path

scanned_at: datetime

expected_replica_count: int

max_depth: int

baseline_study: WorkbenchOCScoreStudy

ablation_studies: tuple[WorkbenchOCScoreStudy, ...]

external_baselines: tuple[WorkbenchOCScoreExternalBaseline, ...]

study_count: int

replica_count: int

completed_count: int

failed_count: int

missing_count: int

metric_names: tuple[str, ...]

issue_count: int

issues: tuple[InventoryIssue, ...]

protocol: WorkbenchOCScoreProtocolSummary | None

run_context: WorkbenchOCScoreRunContext | None

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchOCScoreStudy(*, role, study_name, policy_name, path, expected_replica_count=5, detected_replica_count=0, completed_count=0, failed_count=0, missing_count=0, replicas=(), figures=(), metric_summary=<factory>, cross_validation=None, protocol=None)

Bases: WorkbenchModel

A strict OCScore baseline or ablation study summary.

Parameters:

• role (Literal['baseline', 'ablation'])

• study_name (str)

• policy_name (str)

• path (Path)

• expected_replica_count (int)

• detected_replica_count (int)

• completed_count (int)

• failed_count (int)

• missing_count (int)

• replicas (tuple[WorkbenchOCScoreReplica, ...])

• figures (tuple[WorkbenchOCScoreFigure, ...])

• metric_summary (dict[str, dict[str, Any]])

• cross_validation (WorkbenchOCScoreCrossValidation | None)

• protocol (WorkbenchOCScoreProtocolSummary | None)

role: OCScoreWorkspaceRole

study_name: str

policy_name: str

path: Path

expected_replica_count: int

detected_replica_count: int

completed_count: int

failed_count: int

missing_count: int

replicas: tuple[WorkbenchOCScoreReplica, ...]

figures: tuple[WorkbenchOCScoreFigure, ...]

metric_summary: dict[str, dict[str, Any]]

cross_validation: WorkbenchOCScoreCrossValidation | None

protocol: WorkbenchOCScoreProtocolSummary | None

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchOCScoreReplica(*, role, study_name, policy_name, replica_name, replica_index, path, exists=False, status='missing', optuna_storage_path=None, metrics=(), figures=(), log_files=(), issues=())

Bases: WorkbenchModel

One baseline or ablation replica in the strict OCScore layout.

Parameters:

• role (Literal['baseline', 'ablation'])

• study_name (str)

• policy_name (str)

• replica_name (str)

• replica_index (int)

• path (Path)

• exists (bool)

• status (Literal['missing', 'empty', 'running', 'completed', 'failed', 'unknown'])

• optuna_storage_path (Path | None)

• metrics (tuple[WorkbenchOCScoreMetric, ...])

• figures (tuple[WorkbenchOCScoreFigure, ...])

• log_files (tuple[Path, ...])

• issues (tuple[str, ...])

role: OCScoreWorkspaceRole

study_name: str

policy_name: str

replica_name: str

replica_index: int

path: Path

exists: bool

status: OCScoreReplicaStatus

optuna_storage_path: Path | None

metrics: tuple[WorkbenchOCScoreMetric, ...]

figures: tuple[WorkbenchOCScoreFigure, ...]

log_files: tuple[Path, ...]

issues: tuple[str, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchOCScoreMetric(*, name, label='', direction='max', value, observation_count=1, source_paths=())

Bases: WorkbenchModel

One curated OCScore metric value for a replica.

Parameters:

• name (str)

• label (str)

• direction (Literal['max', 'min'])

• value (float)

• observation_count (int)

• source_paths (tuple[Path, ...])

name: str

label: str

direction: OCScoreMetricDirection

value: float

observation_count: int

source_paths: tuple[Path, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchOCScoreFigure(*, path, role='figure', dataset='', metric_name='', policy_name='', replica_name='', suffix='', size_bytes=None, modified_at=None)

Bases: WorkbenchModel

One figure discovered for a strict OCScore study or replica.

Parameters:

• path (Path)

• role (str)

• dataset (str)

• metric_name (str)

• policy_name (str)

• replica_name (str)

• suffix (str)

• size_bytes (int | None)

• modified_at (datetime | None)

path: Path

role: str

dataset: str

metric_name: str

policy_name: str

replica_name: str

suffix: str

size_bytes: int | None

modified_at: datetime | None

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.OCScoreInputSpec(*, raw_input_dir=None, merged_input=None, pdbbind_input=None, dudez_input=None)

Bases: WorkbenchModel

Raw unreduced input selection for ocdocker ocscore train.

Parameters:

• raw_input_dir (Path | None)

• merged_input (Path | None)

• pdbbind_input (Path | None)

• dudez_input (Path | None)

raw_input_dir

Model field.

Type:

Path | None

merged_input

Model field.

Type:

Path | None

pdbbind_input

Model field.

Type:

Path | None

dudez_input

Model field.

Type:

Path | None

raw_input_dir: Path | None

merged_input: Path | None

pdbbind_input: Path | None

dudez_input: Path | None

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.OCScoreStudySpec(*, schema_version=1, type='ocscore_study', name, protocol, inputs, output_dir, feature_policies=<factory>, description='', tags=())

Bases: WorkbenchModel

Single OCScore staged Optuna study definition.

Parameters:

• schema_version (int)

• type (Literal['ocscore_study'])

• name (str)

• protocol (str | Path)

• inputs (OCScoreInputSpec)

• output_dir (Path)

• feature_policies (FeaturePolicySelection)

• description (str)

• tags (tuple[str, ...])

schema_version

Model field.

Type:

int

type

Model field.

Type:

Literal[‘ocscore_study’]

name

Model field.

Type:

str

protocol

Model field.

Type:

str | Path

inputs

Model field.

Type:

OCScoreInputSpec

output_dir

Model field.

Type:

Path

feature_policies

Model field.

Type:

FeaturePolicySelection

description

Model field.

Type:

str

tags

Model field.

Type:

tuple[str, …]

schema_version: int

type: Literal['ocscore_study']

name: str

protocol: str | Path

inputs: OCScoreInputSpec

output_dir: Path

feature_policies: FeaturePolicySelection

description: str

tags: tuple[str, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.PreflightCheck(*, code, severity, passed, message, path=None, subject='')

Bases: WorkbenchModel

One read-only preflight check for a Workbench spec.

Parameters:

• code (str)

• severity (Literal['info', 'warning', 'error'])

• passed (bool)

• message (str)

• path (Path | None)

• subject (str)

code: str

severity: PreflightSeverity

passed: bool

message: str

path: Path | None

subject: str

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.PreflightReport(*, spec_path=None, spec_type, name, ready, planned_command, checks=(), error_count=0, warning_count=0, info_count=0)

Bases: WorkbenchModel

Read-only preflight report for a Workbench spec.

Parameters:

• spec_path (Path | None)

• spec_type (Literal['vs_campaign', 'ocscore_study', 'ocscore_ablation'])

• name (str)

• ready (bool)

• planned_command (tuple[str, ...])

• checks (tuple[PreflightCheck, ...])

• error_count (int)

• warning_count (int)

• info_count (int)

spec_path: Path | None

spec_type: WorkbenchSpecType

name: str

ready: bool

planned_command: tuple[str, ...]

checks: tuple[PreflightCheck, ...]

error_count: int

warning_count: int

info_count: int

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.PlannedCommand(*, label, command, cwd=None, env=<factory>, writes=(), destructive=False)

Bases: WorkbenchModel

Command plan generated from a workbench spec without executing it.

Parameters:

• label (str)

• command (tuple[str, ...])

• cwd (Path | None)

• env (dict[str, str])

• writes (tuple[Path, ...])

• destructive (bool)

label

Model field.

Type:

str

command

Model field.

Type:

tuple[str, …]

cwd

Model field.

Type:

Path | None

env

Model field.

Type:

dict[str, str]

writes

Model field.

Type:

tuple[Path, …]

destructive

Model field.

Type:

bool

label: str

command: tuple[str, ...]

cwd: Path | None

env: dict[str, str]

writes: tuple[Path, ...]

destructive: bool

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.PublicationExport(*, root, source_manifest_path, run_id, status, readme_path, publication_manifest_path, artifacts=(), metrics=<factory>, generated_at=<factory>)

Bases: WorkbenchModel

Publishable export scaffold generated from a Workbench manifest.

Parameters:

• root (Path)

• source_manifest_path (Path)

• run_id (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• readme_path (Path)

• publication_manifest_path (Path)

• artifacts (tuple[ExportedArtifact, ...])

• metrics (dict[str, Any])

• generated_at (datetime)

root: Path

source_manifest_path: Path

run_id: str

status: RunStatus

readme_path: Path

publication_manifest_path: Path

artifacts: tuple[ExportedArtifact, ...]

metrics: dict[str, Any]

generated_at: datetime

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.ResourceSpec(*, cores=1, memory_mb=None, gpus=0)

Bases: WorkbenchModel

Runtime resources requested by a planned run.

Parameters:

• cores (int)

• memory_mb (int | None)

• gpus (int)

cores

Model field.

Type:

int

memory_mb

Model field.

Type:

int | None

gpus

Model field.

Type:

int

cores: int

memory_mb: int | None

gpus: int

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.ResultArtifact(*, name, path, kind='other', role='', description='')

Bases: WorkbenchModel

One result artifact recorded for a completed or partial run.

Parameters:

• name (str)

• path (Path)

• kind (Literal['json', 'csv', 'html', 'markdown', 'pdf', 'image', 'database', 'log', 'directory', 'other'])

• role (str)

• description (str)

name

Model field.

Type:

str

path

Model field.

Type:

Path

kind

Model field.

Type:

ArtifactKind

role

Model field.

Type:

str

description

Model field.

Type:

str

name: str

path: Path

kind: ArtifactKind

role: str

description: str

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.ResultArtifactStatus(*, path, exists, is_file=False, is_dir=False, name='', role='', kind='other', description='')

Bases: RunPathStatus

Filesystem status plus metadata for one declared result artifact.

Parameters:

• path (Path)

• exists (bool)

• is_file (bool)

• is_dir (bool)

• name (str)

• role (str)

• kind (Literal['json', 'csv', 'html', 'markdown', 'pdf', 'image', 'database', 'log', 'directory', 'other'])

• description (str)

kind: ArtifactKind

description: str

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.ResultManifest(*, schema_version=1, run_id, status, artifacts=(), metrics=<factory>, generated_at=<factory>)

Bases: WorkbenchModel

Summary manifest for publishable and machine-readable run outputs.

Parameters:

• schema_version (int)

• run_id (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• artifacts (tuple[ResultArtifact, ...])

• metrics (dict[str, Any])

• generated_at (datetime)

schema_version

Model field.

Type:

int

run_id

Model field.

Type:

str

status

Model field.

Type:

RunStatus

artifacts

Model field.

Type:

tuple[ResultArtifact, …]

metrics

Model field.

Type:

dict[str, Any]

generated_at

Model field.

Type:

datetime

schema_version: int

run_id: str

status: RunStatus

artifacts: tuple[ResultArtifact, ...]

metrics: dict[str, Any]

generated_at: datetime

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.ResultSummary(*, source_manifest_path, source_type, run_id, status, generated_at=None, metrics=<factory>, artifacts=(), artifact_count=0, existing_artifact_count=0, missing_artifact_count=0)

Bases: WorkbenchModel

Read-only summary of artifacts and metrics declared by a manifest.

Parameters:

• source_manifest_path (Path)

• source_type (Literal['run_manifest', 'result_manifest'])

• run_id (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• generated_at (datetime | None)

• metrics (dict[str, Any])

• artifacts (tuple[ResultArtifactStatus, ...])

• artifact_count (int)

• existing_artifact_count (int)

• missing_artifact_count (int)

source_manifest_path: Path

source_type: Literal['run_manifest', 'result_manifest']

run_id: str

status: RunStatus

generated_at: datetime | None

metrics: dict[str, Any]

artifacts: tuple[ResultArtifactStatus, ...]

artifact_count: int

existing_artifact_count: int

missing_artifact_count: int

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.RunBundle(*, root, spec_path, plan_path, run_manifest_path, bundle_manifest_path, run_id, spec_type, name, command, created_at=<factory>)

Bases: WorkbenchModel

Prepared Workbench run bundle written without executing a command.

Parameters:

• root (Path)

• spec_path (Path)

• plan_path (Path)

• run_manifest_path (Path)

• bundle_manifest_path (Path)

• run_id (str)

• spec_type (Literal['vs_campaign', 'ocscore_study', 'ocscore_ablation'])

• name (str)

• command (tuple[str, ...])

• created_at (datetime)

root: Path

spec_path: Path

plan_path: Path

run_manifest_path: Path

bundle_manifest_path: Path

run_id: str

spec_type: WorkbenchSpecType

name: str

command: tuple[str, ...]

created_at: datetime

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.RunInventoryItem(*, manifest_path, run_id, spec_type, name, status, workspace, updated_at, artifact_count=0, missing_artifacts=())

Bases: WorkbenchModel

Compact summary of one discovered run manifest.

Parameters:

• manifest_path (Path)

• run_id (str)

• spec_type (Literal['vs_campaign', 'ocscore_study', 'ocscore_ablation'])

• name (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• workspace (Path)

• updated_at (datetime)

• artifact_count (int)

• missing_artifacts (tuple[Path, ...])

manifest_path: Path

run_id: str

spec_type: WorkbenchSpecType

name: str

status: RunStatus

workspace: Path

updated_at: datetime

artifact_count: int

missing_artifacts: tuple[Path, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.RunLogFilePreview(*, path, exists, is_file=False, is_dir=False, name='', role='', encoding='utf-8', size_bytes=0, read_bytes=0, returned_line_count=0, truncated=False, lines=(), text='', error='')

Bases: RunPathStatus

Bounded text preview for one declared Workbench log file.

Parameters:

• path (Path)

• exists (bool)

• is_file (bool)

• is_dir (bool)

• name (str)

• role (str)

• encoding (str)

• size_bytes (int)

• read_bytes (int)

• returned_line_count (int)

• truncated (bool)

• lines (tuple[str, ...])

• text (str)

• error (str)

encoding: str

size_bytes: int

read_bytes: int

returned_line_count: int

truncated: bool

lines: tuple[str, ...]

text: str

error: str

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.RunLogPreview(*, manifest_path, run_id, spec_type, name, status, line_limit=80, byte_limit=65536, encoding='utf-8', logs=())

Bases: WorkbenchModel

Bounded read-only log preview for one Workbench run manifest.

Parameters:

• manifest_path (Path)

• run_id (str)

• spec_type (Literal['vs_campaign', 'ocscore_study', 'ocscore_ablation'])

• name (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• line_limit (int)

• byte_limit (int)

• encoding (str)

• logs (tuple[RunLogFilePreview, ...])

manifest_path: Path

run_id: str

spec_type: WorkbenchSpecType

name: str

status: RunStatus

line_limit: int

byte_limit: int

encoding: str

logs: tuple[RunLogFilePreview, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.RunLaunchPlan(*, manifest_path, run_id, spec_type, name, status, workspace, cwd, command, shell_command, foreground_command, background_command, log_dir, stdout_log, stderr_log, pid_file, script_path=None, script_written=False)

Bases: WorkbenchModel

Non-executing launch envelope for a prepared Workbench run.

Parameters:

• manifest_path (Path)

• run_id (str)

• spec_type (Literal['vs_campaign', 'ocscore_study', 'ocscore_ablation'])

• name (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• workspace (Path)

• cwd (Path)

• command (tuple[str, ...])

• shell_command (str)

• foreground_command (str)

• background_command (str)

• log_dir (Path)

• stdout_log (Path)

• stderr_log (Path)

• pid_file (Path)

• script_path (Path | None)

• script_written (bool)

manifest_path: Path

run_id: str

spec_type: WorkbenchSpecType

name: str

status: RunStatus

workspace: Path

cwd: Path

command: tuple[str, ...]

shell_command: str

foreground_command: str

background_command: str

log_dir: Path

stdout_log: Path

stderr_log: Path

pid_file: Path

script_path: Path | None

script_written: bool

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.RunManifest(*, schema_version=1, run_id, spec_type, name, status='defined', workspace, created_at=<factory>, updated_at=<factory>, command=(), pid=None, log_files=(), artifacts=(), metadata=<factory>)

Bases: WorkbenchModel

Workbench run state intended for GUI, CLI, and future automation layers.

Parameters:

• schema_version (int)

• run_id (str)

• spec_type (Literal['vs_campaign', 'ocscore_study', 'ocscore_ablation'])

• name (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• workspace (Path)

• created_at (datetime)

• updated_at (datetime)

• command (tuple[str, ...])

• pid (int | None)

• log_files (tuple[Path, ...])

• artifacts (tuple[ResultArtifact, ...])

• metadata (dict[str, Any])

schema_version

Model field.

Type:

int

run_id

Model field.

Type:

str

spec_type

Model field.

Type:

WorkbenchSpecType

name

Model field.

Type:

str

status

Model field.

Type:

RunStatus

workspace

Model field.

Type:

Path

created_at

Model field.

Type:

datetime

updated_at

Model field.

Type:

datetime

command

Model field.

Type:

tuple[str, …]

pid

Model field.

Type:

int | None

log_files

Model field.

Type:

tuple[Path, …]

artifacts

Model field.

Type:

tuple[ResultArtifact, …]

metadata

Model field.

Type:

dict[str, Any]

schema_version: int

run_id: str

spec_type: WorkbenchSpecType

name: str

status: RunStatus

workspace: Path

created_at: datetime

updated_at: datetime

command: tuple[str, ...]

pid: int | None

log_files: tuple[Path, ...]

artifacts: tuple[ResultArtifact, ...]

metadata: dict[str, Any]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.RunPathStatus(*, path, exists, is_file=False, is_dir=False, name='', role='')

Bases: WorkbenchModel

Filesystem status for one path referenced by a Workbench run.

Parameters:

• path (Path)

• exists (bool)

• is_file (bool)

• is_dir (bool)

• name (str)

• role (str)

path: Path

exists: bool

is_file: bool

is_dir: bool

name: str

role: str

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.RunStatusReport(*, manifest_path, run_id, spec_type, name, status, workspace, workspace_status, updated_at, command=(), pid=None, pid_alive=None, result_manifest_path=None, result_manifest_exists=False, log_files=(), artifacts=())

Bases: WorkbenchModel

Read-only status report for one Workbench run manifest.

Parameters:

• manifest_path (Path)

• run_id (str)

• spec_type (Literal['vs_campaign', 'ocscore_study', 'ocscore_ablation'])

• name (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• workspace (Path)

• workspace_status (RunPathStatus)

• updated_at (datetime)

• command (tuple[str, ...])

• pid (int | None)

• pid_alive (bool | None)

• result_manifest_path (Path | None)

• result_manifest_exists (bool)

• log_files (tuple[RunPathStatus, ...])

• artifacts (tuple[RunPathStatus, ...])

manifest_path: Path

run_id: str

spec_type: WorkbenchSpecType

name: str

status: RunStatus

workspace: Path

workspace_status: RunPathStatus

updated_at: datetime

command: tuple[str, ...]

pid: int | None

pid_alive: bool | None

result_manifest_path: Path | None

result_manifest_exists: bool

log_files: tuple[RunPathStatus, ...]

artifacts: tuple[RunPathStatus, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.SnakemakeWorkflowSpec(*, snakefile, workdir=None, profile=None, targets=(), config=<factory>, resources=<factory>, use_conda=True, keep_going=False, rerun_incomplete=True, dry_run=False)

Bases: WorkbenchModel

Snakemake workflow configuration used by VS campaign execution.

Parameters:

• snakefile (Path)

• workdir (Path | None)

• profile (str | Path | None)

• targets (tuple[str, ...])

• config (dict[str, Any])

• resources (ResourceSpec)

• use_conda (bool)

• keep_going (bool)

• rerun_incomplete (bool)

• dry_run (bool)

snakefile

Model field.

Type:

Path

workdir

Model field.

Type:

Path | None

profile

Model field.

Type:

str | Path | None

targets

Model field.

Type:

tuple[str, …]

config

Model field.

Type:

dict[str, Any]

resources

Model field.

Type:

ResourceSpec

use_conda

Model field.

Type:

bool

keep_going

Model field.

Type:

bool

rerun_incomplete

Model field.

Type:

bool

dry_run

Model field.

Type:

bool

snakefile: Path

workdir: Path | None

profile: str | Path | None

targets: tuple[str, ...]

config: dict[str, Any]

resources: ResourceSpec

use_conda: bool

keep_going: bool

rerun_incomplete: bool

dry_run: bool

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.VSInputSpec(*, sample, receptor, ligand, box, engines=('vina', 'smina', 'plants'), rescoring_engines=None)

Bases: WorkbenchModel

One receptor/ligand/box input set for a virtual-screening campaign.

Parameters:

• sample (str)

• receptor (Path)

• ligand (Path)

• box (Path)

• engines (tuple[str, ...])

• rescoring_engines (tuple[str, ...] | None)

sample

Model field.

Type:

str

receptor

Model field.

Type:

Path

ligand

Model field.

Type:

Path

box

Model field.

Type:

Path

engines

Model field.

Type:

tuple[str, …]

rescoring_engines

Model field.

Type:

tuple[str, …] | None

sample: str

receptor: Path

ligand: Path

box: Path

engines: tuple[str, ...]

rescoring_engines: tuple[str, ...] | None

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.VSCampaignSpec(*, schema_version=1, type='vs_campaign', name, workspace, workflow, inputs, description='', tags=())

Bases: WorkbenchModel

High-level virtual-screening campaign definition.

Parameters:

• schema_version (int)

• type (Literal['vs_campaign'])

• name (str)

• workspace (Path)

• workflow (SnakemakeWorkflowSpec)

• inputs (tuple[VSInputSpec, ...])

• description (str)

• tags (tuple[str, ...])

schema_version

Model field.

Type:

int

type

Model field.

Type:

Literal[‘vs_campaign’]

name

Model field.

Type:

str

workspace

Model field.

Type:

Path

workflow

Model field.

Type:

SnakemakeWorkflowSpec

inputs

Model field.

Type:

tuple[VSInputSpec, …]

description

Model field.

Type:

str

tags

Model field.

Type:

tuple[str, …]

schema_version: int

type: Literal['vs_campaign']

name: str

workspace: Path

workflow: SnakemakeWorkflowSpec

inputs: tuple[VSInputSpec, ...]

description: str

tags: tuple[str, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchAblationAnalysis(*, root, max_depth=6, scanned_at=<factory>, baseline_run_id, baseline_policy_name, baseline_manifest_path, baseline_source_path=None, metrics=(), result_manifest_count=0, detected_ablation_count=0, candidate_count=0, candidates=(), best_candidate=None, issue_count=0, issues=())

Bases: WorkbenchModel

Read-only OCScore ablation comparison against a reference run.

Parameters:

• root (Path)

• max_depth (int)

• scanned_at (datetime)

• baseline_run_id (str)

• baseline_policy_name (str)

• baseline_manifest_path (Path)

• baseline_source_path (Path | None)

• metrics (tuple[ParetoObjective, ...])

• result_manifest_count (int)

• detected_ablation_count (int)

• candidate_count (int)

• candidates (tuple[WorkbenchAblationCandidate, ...])

• best_candidate (WorkbenchAblationCandidate | None)

• issue_count (int)

• issues (tuple[InventoryIssue, ...])

root: Path

max_depth: int

scanned_at: datetime

baseline_run_id: str

baseline_policy_name: str

baseline_manifest_path: Path

baseline_source_path: Path | None

metrics: tuple[ParetoObjective, ...]

result_manifest_count: int

detected_ablation_count: int

candidate_count: int

candidates: tuple[WorkbenchAblationCandidate, ...]

best_candidate: WorkbenchAblationCandidate | None

issue_count: int

issues: tuple[InventoryIssue, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchAblationCandidate(*, policy_name, run_id, status, manifest_path, source_path=None, metrics=(), improved_count=0, regressed_count=0, unchanged_count=0, incomplete_count=0, net_score=0, artifact_count=0, missing_artifact_count=0)

Bases: WorkbenchModel

One ablation policy compared against a reference run.

Parameters:

• policy_name (str)

• run_id (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• manifest_path (Path)

• source_path (Path | None)

• metrics (tuple[WorkbenchComparisonMetric, ...])

• improved_count (int)

• regressed_count (int)

• unchanged_count (int)

• incomplete_count (int)

• net_score (int)

• artifact_count (int)

• missing_artifact_count (int)

policy_name: str

run_id: str

status: RunStatus

manifest_path: Path

source_path: Path | None

metrics: tuple[WorkbenchComparisonMetric, ...]

improved_count: int

regressed_count: int

unchanged_count: int

incomplete_count: int

net_score: int

artifact_count: int

missing_artifact_count: int

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchAblationProtocolClusterSummary(*, cluster_id, policy_names=(), mean_metric=None, metric_count=0, missing_metric_count=0)

Bases: WorkbenchModel

Aggregate outcome for one feature-similarity cluster.

Parameters:

• cluster_id (int)

• policy_names (tuple[str, ...])

• mean_metric (float | None)

• metric_count (int)

• missing_metric_count (int)

cluster_id: int

policy_names: tuple[str, ...]

mean_metric: float | None

metric_count: int

missing_metric_count: int

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchAblationProtocolFamilyState(*, family_id, present=False, member_count=0, total_members=0)

Bases: WorkbenchModel

Presence of one feature family in an expanded ablation protocol.

Parameters:

• family_id (str)

• present (bool)

• member_count (int)

• total_members (int)

family_id: str

present: bool

member_count: int

total_members: int

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchAblationProtocolReferenceDiff(*, policy_name='', added_features=(), removed_features=(), added_families=(), removed_families=(), shared_feature_count=0)

Bases: WorkbenchModel

Feature and family differences versus a reference protocol.

Parameters:

• policy_name (str)

• added_features (tuple[str, ...])

• removed_features (tuple[str, ...])

• added_families (tuple[str, ...])

• removed_families (tuple[str, ...])

• shared_feature_count (int)

policy_name: str

added_features: tuple[str, ...]

removed_features: tuple[str, ...]

added_families: tuple[str, ...]

removed_families: tuple[str, ...]

shared_feature_count: int

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchAblationProtocolSimilarity(*, root, layout_root, scanned_at=<factory>, candidate_source=None, preview_available=False, reference_policy='full_ocscore', metric='', include_catalog_only=False, protocol_count=0, protocols=(), protocol_order=(), similarity_matrix=(), cluster_labels=(), cluster_summaries=(), reference_diffs=(), issue_count=0, issues=(), message='')

Bases: WorkbenchModel

Expanded feature-set similarity across ablation protocols.

Returned by OCDocker.Workbench.AblationProtocolSimilarity.build_ablation_protocol_similarity_analysis() and serialized by GET /api/ablation-protocol-similarity.

Parameters:

• root (Path)

• layout_root (Path)

• scanned_at (datetime)

• candidate_source (str | None)

• preview_available (bool)

• reference_policy (str)

• metric (str)

• include_catalog_only (bool)

• protocol_count (int)

• protocols (tuple[WorkbenchAblationProtocolSimilarityEntry, ...])

• protocol_order (tuple[str, ...])

• similarity_matrix (tuple[tuple[float, ...], ...])

• cluster_labels (tuple[int, ...])

• cluster_summaries (tuple[WorkbenchAblationProtocolClusterSummary, ...])

• reference_diffs (tuple[WorkbenchAblationProtocolReferenceDiff, ...])

• issue_count (int)

• issues (tuple[InventoryIssue, ...])

• message (str)

root: Path

layout_root: Path

scanned_at: datetime

candidate_source: str | None

preview_available: bool

reference_policy: str

metric: str

include_catalog_only: bool

protocol_count: int

protocols: tuple[WorkbenchAblationProtocolSimilarityEntry, ...]

protocol_order: tuple[str, ...]

similarity_matrix: tuple[tuple[float, ...], ...]

cluster_labels: tuple[int, ...]

cluster_summaries: tuple[WorkbenchAblationProtocolClusterSummary, ...]

reference_diffs: tuple[WorkbenchAblationProtocolReferenceDiff, ...]

issue_count: int

issues: tuple[InventoryIssue, ...]

message: str

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchAblationProtocolSimilarityEntry(*, policy_name, description='', source_kind='bundled', source_path=None, expanded_feature_count=0, run_id=None, study_present=False, metric_value=None, families=())

Bases: WorkbenchModel

One ablation protocol resolved to an expanded feature set.

Parameters:

• policy_name (str)

• description (str)

• source_kind (str)

• source_path (Path | None)

• expanded_feature_count (int)

• run_id (str | None)

• study_present (bool)

• metric_value (float | None)

• families (tuple[WorkbenchAblationProtocolFamilyState, ...])

policy_name: str

description: str

source_kind: str

source_path: Path | None

expanded_feature_count: int

run_id: str | None

study_present: bool

metric_value: float | None

families: tuple[WorkbenchAblationProtocolFamilyState, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchAnalysisReport(*, root, max_depth=6, recent_limit=20, top_n=5, scanned_at=<factory>, overview, metrics_catalog, metric_matrix=None, leaderboards=(), pareto_front=None, findings=(), issue_count=0, markdown='')

Bases: WorkbenchModel

Composed read-only analysis report for GUI and publication workflows.

Parameters:

• root (Path)

• max_depth (int)

• recent_limit (int)

• top_n (int)

• scanned_at (datetime)

• overview (WorkspaceOverview)

• metrics_catalog (MetricCatalog)

• metric_matrix (MetricMatrix | None)

• leaderboards (tuple[MetricLeaderboard, ...])

• pareto_front (ParetoFront | None)

• findings (tuple[WorkbenchReportFinding, ...])

• issue_count (int)

• markdown (str)

root: Path

max_depth: int

recent_limit: int

top_n: int

scanned_at: datetime

overview: WorkspaceOverview

metrics_catalog: MetricCatalog

metric_matrix: MetricMatrix | None

leaderboards: tuple[MetricLeaderboard, ...]

pareto_front: ParetoFront | None

findings: tuple[WorkbenchReportFinding, ...]

issue_count: int

markdown: str

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchArtifactEntry(*, source_type, source_manifest_path, run_id, status, name, path, kind='other', role='', description='', exists=False, is_file=False, is_dir=False, suffix='', size_bytes=None, modified_at=None)

Bases: WorkbenchModel

One artifact row in a cross-run Workbench artifact index.

Parameters:

• source_type (Literal['run_manifest', 'result_manifest'])

• source_manifest_path (Path)

• run_id (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• name (str)

• path (Path)

• kind (Literal['json', 'csv', 'html', 'markdown', 'pdf', 'image', 'database', 'log', 'directory', 'other'])

• role (str)

• description (str)

• exists (bool)

• is_file (bool)

• is_dir (bool)

• suffix (str)

• size_bytes (int | None)

• modified_at (datetime | None)

source_type: Literal['run_manifest', 'result_manifest']

source_manifest_path: Path

run_id: str

status: RunStatus

name: str

path: Path

kind: ArtifactKind

role: str

description: str

exists: bool

is_file: bool

is_dir: bool

suffix: str

size_bytes: int | None

modified_at: datetime | None

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchArtifactIndex(*, root, max_depth=6, scanned_at=<factory>, filters=<factory>, run_manifest_count=0, result_manifest_count=0, artifact_count=0, existing_artifact_count=0, missing_artifact_count=0, kind_counts=<factory>, role_counts=<factory>, entries=(), issue_count=0, issues=())

Bases: WorkbenchModel

Read-only cross-run index of declared Workbench artifacts.

Parameters:

• root (Path)

• max_depth (int)

• scanned_at (datetime)

• filters (dict[str, Any])

• run_manifest_count (int)

• result_manifest_count (int)

• artifact_count (int)

• existing_artifact_count (int)

• missing_artifact_count (int)

• kind_counts (dict[str, int])

• role_counts (dict[str, int])

• entries (tuple[WorkbenchArtifactEntry, ...])

• issue_count (int)

• issues (tuple[InventoryIssue, ...])

root: Path

max_depth: int

scanned_at: datetime

filters: dict[str, Any]

run_manifest_count: int

result_manifest_count: int

artifact_count: int

existing_artifact_count: int

missing_artifact_count: int

kind_counts: dict[str, int]

role_counts: dict[str, int]

entries: tuple[WorkbenchArtifactEntry, ...]

issue_count: int

issues: tuple[InventoryIssue, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchEvidenceEntry(*, run_id, status, manifest_path, source_path=None, path, kind='other', role='', dataset='', policy_name='', replica='', figure_name='', comparison_key='', suffix='', size_bytes=None, modified_at=None, column_count=None, metric_names=())

Bases: WorkbenchModel

One discovered OCScore evidence artifact or table.

Parameters:

• run_id (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• manifest_path (Path)

• source_path (Path | None)

• path (Path)

• kind (Literal['performance', 'optimization', 'shap', 'figure', 'prediction', 'other'])

• role (str)

• dataset (str)

• policy_name (str)

• replica (str)

• figure_name (str)

• comparison_key (str)

• suffix (str)

• size_bytes (int | None)

• modified_at (datetime | None)

• column_count (int | None)

• metric_names (tuple[str, ...])

run_id: str

status: RunStatus

manifest_path: Path

source_path: Path | None

path: Path

kind: EvidenceKind

role: str

dataset: str

policy_name: str

replica: str

figure_name: str

comparison_key: str

suffix: str

size_bytes: int | None

modified_at: datetime | None

column_count: int | None

metric_names: tuple[str, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchEvidenceIndex(*, root, max_depth=6, source_depth=6, scanned_at=<factory>, result_manifest_count=0, evidence_count=0, kind_counts=<factory>, role_counts=<factory>, entries=(), performance_points=(), optimization_points=(), shap_features=(), issue_count=0, issues=())

Bases: WorkbenchModel

Read-only index of OCScore evidence discovered from adopted sources.

Parameters:

• root (Path)

• max_depth (int)

• source_depth (int)

• scanned_at (datetime)

• result_manifest_count (int)

• evidence_count (int)

• kind_counts (dict[str, int])

• role_counts (dict[str, int])

• entries (tuple[WorkbenchEvidenceEntry, ...])

• performance_points (tuple[dict[str, Any], ...])

• optimization_points (tuple[dict[str, Any], ...])

• shap_features (tuple[dict[str, Any], ...])

• issue_count (int)

• issues (tuple[InventoryIssue, ...])

root: Path

max_depth: int

source_depth: int

scanned_at: datetime

result_manifest_count: int

evidence_count: int

kind_counts: dict[str, int]

role_counts: dict[str, int]

entries: tuple[WorkbenchEvidenceEntry, ...]

performance_points: tuple[dict[str, Any], ...]

optimization_points: tuple[dict[str, Any], ...]

shap_features: tuple[dict[str, Any], ...]

issue_count: int

issues: tuple[InventoryIssue, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchJobRecord(*, schema_version=1, job_id, kind, command=(), cwd, status='defined', pid=None, stdout_log, stderr_log, returncode_path, manifest_path, created_at=<factory>, updated_at=<factory>, finished_at=None, return_code=None)

Bases: WorkbenchModel

Tracked Workbench job launched and monitored via the API.

Parameters:

• schema_version (int)

• job_id (str)

• kind (Literal['vs', 'pipeline', 'ocscore_train', 'ocscore_reduce', 'vs_campaign'])

• command (tuple[str, ...])

• cwd (Path)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• pid (int | None)

• stdout_log (Path)

• stderr_log (Path)

• returncode_path (Path)

• manifest_path (Path)

• created_at (datetime)

• updated_at (datetime)

• finished_at (datetime | None)

• return_code (int | None)

schema_version

Model field.

Type:

int

job_id

Model field.

Type:

str

kind

Model field.

Type:

WorkbenchJobKind

command

Model field.

Type:

tuple[str, …]

cwd

Model field.

Type:

Path

status

Model field.

Type:

RunStatus

pid

Model field.

Type:

int | None

stdout_log

Model field.

Type:

Path

stderr_log

Model field.

Type:

Path

returncode_path

Model field.

Type:

Path

manifest_path

Model field.

Type:

Path

created_at

Model field.

Type:

datetime

updated_at

Model field.

Type:

datetime

finished_at

Model field.

Type:

datetime | None

return_code

Model field.

Type:

int | None

schema_version: int

job_id: str

kind: WorkbenchJobKind

command: tuple[str, ...]

cwd: Path

status: RunStatus

pid: int | None

stdout_log: Path

stderr_log: Path

returncode_path: Path

manifest_path: Path

created_at: datetime

updated_at: datetime

finished_at: datetime | None

return_code: int | None

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchComparison(*, root, max_depth=6, scanned_at=<factory>, baseline_run_id, baseline_manifest_path, baseline_status, baseline_artifact_count=0, baseline_missing_artifact_count=0, metrics=(), result_manifest_count=0, candidate_count=0, candidates=(), best_candidate=None, issue_count=0, issues=())

Bases: WorkbenchModel

Read-only comparison of candidate result manifests against a baseline.

Parameters:

• root (Path)

• max_depth (int)

• scanned_at (datetime)

• baseline_run_id (str)

• baseline_manifest_path (Path)

• baseline_status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• baseline_artifact_count (int)

• baseline_missing_artifact_count (int)

• metrics (tuple[ParetoObjective, ...])

• result_manifest_count (int)

• candidate_count (int)

• candidates (tuple[WorkbenchComparisonCandidate, ...])

• best_candidate (WorkbenchComparisonCandidate | None)

• issue_count (int)

• issues (tuple[InventoryIssue, ...])

root: Path

max_depth: int

scanned_at: datetime

baseline_run_id: str

baseline_manifest_path: Path

baseline_status: RunStatus

baseline_artifact_count: int

baseline_missing_artifact_count: int

metrics: tuple[ParetoObjective, ...]

result_manifest_count: int

candidate_count: int

candidates: tuple[WorkbenchComparisonCandidate, ...]

best_candidate: WorkbenchComparisonCandidate | None

issue_count: int

issues: tuple[InventoryIssue, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchComparisonCandidate(*, run_id, status, manifest_path, metrics=(), improved_count=0, regressed_count=0, unchanged_count=0, incomplete_count=0, net_score=0, artifact_count=0, missing_artifact_count=0)

Bases: WorkbenchModel

Comparison summary for one candidate run against a baseline.

Parameters:

• run_id (str)

• status (Literal['defined', 'built', 'dry_run', 'running', 'completed', 'failed', 'cancelled'])

• manifest_path (Path)

• metrics (tuple[WorkbenchComparisonMetric, ...])

• improved_count (int)

• regressed_count (int)

• unchanged_count (int)

• incomplete_count (int)

• net_score (int)

• artifact_count (int)

• missing_artifact_count (int)

run_id: str

status: RunStatus

manifest_path: Path

metrics: tuple[WorkbenchComparisonMetric, ...]

improved_count: int

regressed_count: int

unchanged_count: int

incomplete_count: int

net_score: int

artifact_count: int

missing_artifact_count: int

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchComparisonMetric(*, metric_name, mode='max', baseline_value=None, candidate_value=None, delta=None, percent_delta=None, direction='incomplete', improved=False, regressed=False, baseline_missing=False, candidate_missing=False, baseline_non_numeric=False, candidate_non_numeric=False)

Bases: WorkbenchModel

One metric delta between a baseline and candidate run.

Parameters:

• metric_name (str)

• mode (Literal['min', 'max'])

• baseline_value (float | None)

• candidate_value (float | None)

• delta (float | None)

• percent_delta (float | None)

• direction (Literal['improved', 'regressed', 'unchanged', 'incomplete'])

• improved (bool)

• regressed (bool)

• baseline_missing (bool)

• candidate_missing (bool)

• baseline_non_numeric (bool)

• candidate_non_numeric (bool)

metric_name: str

mode: MetricSortMode

baseline_value: float | None

candidate_value: float | None

delta: float | None

percent_delta: float | None

direction: ComparisonDirection

improved: bool

regressed: bool

baseline_missing: bool

candidate_missing: bool

baseline_non_numeric: bool

candidate_non_numeric: bool

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchPlot(*, root, plot_kind, title, metric_names=(), data=(), layout=<factory>, config=<factory>, included_count=0, skipped_count=0, issue_count=0, issues=(), metadata=<factory>)

Bases: WorkbenchModel

Plot-ready payload for GUI and notebook rendering.

Parameters:

• root (Path)

• plot_kind (Literal['leaderboard_bar', 'metric_scatter', 'parallel_coordinates', 'pareto_scatter'])

• title (str)

• metric_names (tuple[str, ...])

• data (tuple[dict[str, Any], ...])

• layout (dict[str, Any])

• config (dict[str, Any])

• included_count (int)

• skipped_count (int)

• issue_count (int)

• issues (tuple[InventoryIssue, ...])

• metadata (dict[str, Any])

root: Path

plot_kind: WorkbenchPlotKind

title: str

metric_names: tuple[str, ...]

data: tuple[dict[str, Any], ...]

layout: dict[str, Any]

config: dict[str, Any]

included_count: int

skipped_count: int

issue_count: int

issues: tuple[InventoryIssue, ...]

metadata: dict[str, Any]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkspaceInventory(*, root, max_depth=6, scanned_at=<factory>, runs=(), result_manifests=(), issues=())

Bases: WorkbenchModel

Read-only inventory of Workbench manifests below a root path.

Parameters:

• root (Path)

• max_depth (int)

• scanned_at (datetime)

• runs (tuple[RunInventoryItem, ...])

• result_manifests (tuple[Path, ...])

• issues (tuple[InventoryIssue, ...])

root: Path

max_depth: int

scanned_at: datetime

runs: tuple[RunInventoryItem, ...]

result_manifests: tuple[Path, ...]

issues: tuple[InventoryIssue, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkspaceOverview(*, root, max_depth=6, scanned_at=<factory>, run_count=0, result_manifest_count=0, issue_count=0, missing_artifact_count=0, status_counts=<factory>, spec_type_counts=<factory>, recent_runs=(), issues=())

Bases: WorkbenchModel

Read-only dashboard overview of a Workbench workspace.

Parameters:

• root (Path)

• max_depth (int)

• scanned_at (datetime)

• run_count (int)

• result_manifest_count (int)

• issue_count (int)

• missing_artifact_count (int)

• status_counts (dict[str, int])

• spec_type_counts (dict[str, int])

• recent_runs (tuple[RunInventoryItem, ...])

• issues (tuple[InventoryIssue, ...])

root: Path

max_depth: int

scanned_at: datetime

run_count: int

result_manifest_count: int

issue_count: int

missing_artifact_count: int

status_counts: dict[str, int]

spec_type_counts: dict[str, int]

recent_runs: tuple[RunInventoryItem, ...]

issues: tuple[InventoryIssue, ...]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchModel

Bases: BaseModel

Base model with strict fields for workbench schemas.

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class OCDocker.Workbench.Models.WorkbenchReportFinding(*, kind, severity='info', title, message, run_id='', metric_name='', metric_value=None, manifest_path=None, metadata=<factory>)

Bases: WorkbenchModel

One decision-support finding in a Workbench analysis report.

Parameters:

• kind (Literal['best_metric', 'incomplete_metric', 'missing_artifact', 'no_results', 'pareto_candidate', 'pareto_skipped', 'workspace_issue'])

• severity (Literal['info', 'warning', 'error'])

• title (str)

• message (str)

• run_id (str)

• metric_name (str)

• metric_value (float | None)

• manifest_path (Path | None)

• metadata (dict[str, Any])

kind: WorkbenchReportFindingKind

severity: PreflightSeverity

title: str

message: str

run_id: str

metric_name: str

metric_value: float | None

manifest_path: Path | None

metadata: dict[str, Any]

model_config = {'extra': 'forbid', 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].