coleman.spec.models¶

Typed Pydantic v2 models for the run specification.

coleman.spec.models ¶

Pydantic v2 models for the Coleman run specification.

Each model corresponds to a section in the configuration, providing type-safe defaults and validation.

AlgorithmSpec ¶

Bases: BaseModel

Per-algorithm hyper-parameter block.

Accepts arbitrary nested keys so that any algorithm can store its own parameter map (e.g. frrmab.window_sizes, ucb.timerank.c).

BudgetSpec ¶

Bases: BaseModel

Generic budget model for experiment execution.

Parameters:

Name	Type	Description	Default
`mode`	`BudgetMode`	Budget interpretation mode.	required
`values`	`list[float]`	Budget values for sweep execution.	required

validate_values ¶

validate_values()

Validate values according to selected budget mode.

CheckpointSpec ¶

Bases: BaseModel

Checkpoint persistence settings.

Parameters:

Name	Type	Description	Default
`enabled`	`bool`	Whether checkpointing is active.	required
`interval`	`int`	Steps between checkpoints.	required
`base_dir`	`str`	Directory for checkpoint files.	required

ContextualConfigSpec ¶

Bases: BaseModel

Contextual information configuration.

Parameters:

Name	Type	Description	Default
`previous_build`	`list[str]`	Column names from the previous build.	required

ContextualFeatureGroupSpec ¶

Bases: BaseModel

Feature group configuration.

Parameters:

Name	Type	Description	Default
`feature_group_name`	`str`	Name of the feature group.	required
`feature_group_values`	`list[str]`	Column names in the feature group.	required

ContextualInformationSpec ¶

Bases: BaseModel

Contextual information settings.

Parameters:

Name	Type	Description	Default
`config`	`ContextualConfigSpec`	Previous build column configuration.	required
`feature_group`	`ContextualFeatureGroupSpec`	Feature group configuration.	required

ExecutionSpec ¶

Bases: BaseModel

Execution-level settings.

Parameters:

Name	Type	Description	Default
`parallel_pool_size`	`int`	Number of parallel worker processes.	required
`independent_executions`	`int`	How many independent repetitions to run.	required
`seed`	`int \| None`	Random seed for this execution (`None` = use default/global behavior).	required
`verbose`	`bool`	Enable verbose logging.	required
`force_sequential_under_scalene`	`bool`	When `True` and Scalene is active, force `parallel_pool_size=1`. This improves profiling stability and avoids multiprocessing issues observed on Python 3.14.	required

ExperimentSpec ¶

Bases: BaseModel

Experiment-level settings.

Parameters:

Name	Type	Description	Default
`budget`	`BudgetSpec`	Generic budget definition.	required
`datasets_dir`	`str`	Root directory containing dataset files.	required
`datasets`	`list[str]`	Dataset identifiers (`org@project` format).	required
`experiment_dir`	`str`	Directory where experiment artefacts are stored.	required
`rewards`	`list[str]`	Reward function names.	required
`policies`	`list[str]`	Bandit policy names.	required

HCSConfigurationSpec ¶

Bases: BaseModel

HCS-specific flags.

Parameters:

Name	Type	Description	Default
`wts_strategy`	`bool`	Whether to use the WTS strategy.	required

HooksSpec ¶

Bases: BaseModel

Runner lifecycle hook configuration.

Parameters:

Name	Type	Description	Default
`fail_fast`	`bool`	If `True`, stop run execution on hook failures. If `False`, hook failures are logged and execution continues.	required
`plugins`	`list[str]`	Dotted paths to hook plugins (class or function).	required

ResultsSpec ¶

Bases: BaseModel

Results sink settings.

Parameters:

Name	Type	Description	Default
`enabled`	`bool`	Whether result persistence is active.	required
`sink`	`str`	Sink backend (`"parquet"` or `"clickhouse"`).	required
`out_dir`	`str`	Output directory for result files.	required
`batch_size`	`int`	Rows per write batch.	required
`top_k_prioritization`	`int`	Top-k value for prioritisation metrics (0 = disabled).	required
`clickhouse`	`dict[str, Any]`	Optional ClickHouse sink kwargs (e.g., `host`, `port`, `secure`).	required
`duckdb`	`dict[str, Any]`	Optional DuckDB sink kwargs (e.g., `file_count`, `base_name`, `shard_key`).	required
`manifest_enabled`	`bool`	When `True`, generate `manifest.json` under each run root.	required

RunSpec ¶

Bases: BaseModel

Top-level experiment specification.

Composes every sub-spec into a single validated object that fully describes one experiment run. When serialised to canonical JSON the result is deterministic and can be hashed to produce a stable run_id.

Parameters:

Name	Type	Description	Default
`execution`	`ExecutionSpec`	Execution-level settings.	required
`experiment`	`ExperimentSpec`	Experiment-level settings.	required
`algorithm`	`AlgorithmSpec`	Per-algorithm hyper-parameters (free-form, extra keys allowed).	required
`hcs_configuration`	`HCSConfigurationSpec`	HCS-specific flags.	required
`contextual_information`	`ContextualInformationSpec`	Contextual feature configuration.	required
`results`	`ResultsSpec`	Results sink settings.	required
`checkpoint`	`CheckpointSpec`	Checkpoint persistence settings.	required
`telemetry`	`TelemetrySpec`	Telemetry export settings.	required
`hooks`	`HooksSpec`	Optional lifecycle hook plugin configuration.	required
`extensions`	`dict[str, Any]`	Namespaced custom config passthrough for domain workflows.	required

TelemetrySpec ¶

Bases: BaseModel

OpenTelemetry export settings.

Parameters:

Name	Type	Description	Default
`enabled`	`bool`	Whether telemetry export is active.	required
`otlp_endpoint`	`str`	OTLP collector endpoint.	required
`service_name`	`str`	Reported service name.	required
`export_interval_millis`	`int`	Export interval in milliseconds.	required
`resource_attributes`	`dict[str, str]`	Extra OTel resource attributes (e.g. `execution_id`, `run_id`). These are attached to the OTel Resource, not to individual metric labels, avoiding high-cardinality issues.	required