OCDocker.OCScore.Optimization.StagedTrainProtocol module¶

Structured YAML protocol files for staged OCScore training.

Protocols define replicas, trial budgets, split/scaling policy, and reporting artifacts. The train CLI loads a protocol file and applies it without preset flags or CLI hyperparameter overrides.

class OCDocker.OCScore.Optimization.StagedTrainProtocol.AblationProtocolSection(enabled, variants)[source]¶

Bases: object

Feature-policy ablation variants to run after baseline replicas.

Parameters:

enabled (bool)
variants (tuple[Literal['ligand_only', 'sf_only', 'ligand_sf', 'receptor_sf'], ...])

enabled: bool¶

variants: tuple[Literal['ligand_only', 'sf_only', 'ligand_sf', 'receptor_sf'], ...]¶

class OCDocker.OCScore.Optimization.StagedTrainProtocol.StagedTrainProtocol(name, description, replicas, seed, pdbbind, dudez, runtime, reporting, ablation, source_path, production_claim=None, raw=<factory>)[source]¶

Bases: object

Structured staged-training protocol loaded from YAML.

Parameters:

name (str)
description (str)
replicas (int)
seed (int)
pdbbind (PDBbindProtocolSection)
dudez (DUDEzProtocolSection)
runtime (RuntimeProtocolSection)
reporting (ReportingProtocolSection)
ablation (AblationProtocolSection)
source_path (Path)
production_claim (ProductionClaimRequirements | None)
raw (dict[str, Any])

name: str¶

description: str¶

replicas: int¶

seed: int¶

pdbbind: PDBbindProtocolSection¶

dudez: DUDEzProtocolSection¶

runtime: RuntimeProtocolSection¶

reporting: ReportingProtocolSection¶

ablation: AblationProtocolSection¶

source_path: Path¶

production_claim: ProductionClaimRequirements | None = None¶

raw: dict[str, Any]¶

pdbbind_split_config()[source]¶

Build the PDBbind split configuration implied by this protocol.

Returns:: Split strategy and sizes for PDBbind regression rows.
Return type:: PDBbindSplitConfig

budget_dict()[source]¶

Serialize replica and trial budgets for provenance metadata.

Returns:: Budget fields written into training provenance bundles.
Return type:: dict[str, Any]

validate_production_claim_budget()[source]¶

Raise when configured budgets fall below production-claim thresholds.

Raises:: ValueError – If production_claim.enforce is true and replicas or trials are too low.
Return type:: None

OCDocker.OCScore.Optimization.StagedTrainProtocol.bundled_protocol_names()[source]¶

List bundled protocol stems shipped under OCScore/Protocols/.

Returns:: Sorted protocol names without file extensions.
Return type:: tuple[str, …]

OCDocker.OCScore.Optimization.StagedTrainProtocol.load_staged_train_protocol(path)[source]¶

Load and validate a staged train protocol YAML file.

Parameters:: path (pathlib.Path) – Protocol YAML path on disk.
Returns:: Parsed template ready for the train CLI and Optuna orchestration.
Return type:: StagedTrainProtocol
Raises:: ValueError – If required fields are missing or budgets fail production-claim checks.

OCDocker.OCScore.Optimization.StagedTrainProtocol.normalize_ablation_variant_name(value)[source]¶

Normalize CLI or YAML ablation variant aliases to canonical names.

Parameters:: value (str) – Raw variant label from protocol YAML or CLI flags.
Returns:: Canonical ablation variant identifier.
Return type:: AblationVariantName
Raises:: ValueError – If value does not match a known alias.

OCDocker.OCScore.Optimization.StagedTrainProtocol.resolve_protocol_path(spec)[source]¶

Resolve a user path or bundled protocol name to an on-disk YAML file.

Parameters:: spec (str) – Filesystem path or bundled protocol stem (for example production).
Returns:: Absolute path to the resolved protocol YAML file.
Return type:: pathlib.Path
Raises:: ValueError – If neither a file nor a bundled protocol matches spec.