builders

orchard.optimization.orchestrator.builders

Factory Functions for Optuna Components.

Provides builder functions that construct Optuna samplers, pruners, and callbacks based on the Optuna configuration sub-model. Centralizes the instantiation logic and provides clear error messages for invalid configurations.

Functions:

• build_sampler: Create Optuna sampler from type string
• build_pruner: Create Optuna pruner from config
• build_callbacks: Construct optimization callbacks list

build_sampler(optuna_cfg)

Create Optuna sampler from configuration.

Parameters:

Name	Type	Description	Default
optuna_cfg	OptunaConfig	Optuna sub-config with sampler_type	required

Returns:

Type	Description
BaseSampler	Configured Optuna sampler instance

Raises:

Type	Description
ValueError	If sampler_type is not in SAMPLER_REGISTRY

Source code in orchard/optimization/orchestrator/builders.py

def build_sampler(optuna_cfg: OptunaConfig) -> optuna.samplers.BaseSampler:
    """
    Create Optuna sampler from configuration.

    Args:
        optuna_cfg: Optuna sub-config with sampler_type

    Returns:
        Configured Optuna sampler instance

    Raises:
        ValueError: If sampler_type is not in SAMPLER_REGISTRY
    """
    sampler_cls = SAMPLER_REGISTRY.get(optuna_cfg.sampler_type)
    if sampler_cls is None:
        raise ValueError(
            f"Unknown sampler: {optuna_cfg.sampler_type}. "
            f"Valid options: {list(SAMPLER_REGISTRY.keys())}"
        )
    return cast(optuna.samplers.BaseSampler, sampler_cls())

build_pruner(optuna_cfg)

Create Optuna pruner from configuration.

Parameters:

Name	Type	Description	Default
optuna_cfg	OptunaConfig	Optuna sub-config with enable_pruning and pruner_type	required

Returns:

Type	Description
MedianPruner | PercentilePruner | HyperbandPruner | NopPruner	Configured Optuna pruner instance (NopPruner if disabled)

Raises:

Type	Description
ValueError	If pruner_type is not in PRUNER_REGISTRY

Source code in orchard/optimization/orchestrator/builders.py

def build_pruner(
    optuna_cfg: OptunaConfig,
) -> MedianPruner | PercentilePruner | HyperbandPruner | NopPruner:
    """
    Create Optuna pruner from configuration.

    Args:
        optuna_cfg: Optuna sub-config with enable_pruning and pruner_type

    Returns:
        Configured Optuna pruner instance (NopPruner if disabled)

    Raises:
        ValueError: If pruner_type is not in PRUNER_REGISTRY
    """
    if not optuna_cfg.enable_pruning:
        return NopPruner()

    pruner_factory = PRUNER_REGISTRY.get(optuna_cfg.pruner_type)
    if pruner_factory is None:
        raise ValueError(
            f"Unknown pruner: {optuna_cfg.pruner_type}. "
            f"Valid options: {list(PRUNER_REGISTRY.keys())}"
        )
    # type narrowing: PRUNER_REGISTRY values are concrete pruner factories
    return cast(MedianPruner | PercentilePruner | HyperbandPruner | NopPruner, pruner_factory())

build_callbacks(optuna_cfg, monitor_metric)

Construct list of optimization callbacks from configuration.

Currently supports:

- Early stopping callback (based on metric threshold)

Parameters:

Name	Type	Description	Default
optuna_cfg	OptunaConfig	Optuna sub-config with early stopping parameters	required
monitor_metric	str	Target metric name (from training.monitor_metric)	required

Returns:

Type	Description
list[Any]	list of Optuna callback objects (may be empty)

Example

callbacks = build_callbacks(optuna_cfg, "auc") len(callbacks) # 0 or 1 depending on early_stopping config

Source code in orchard/optimization/orchestrator/builders.py

def build_callbacks(optuna_cfg: OptunaConfig, monitor_metric: str) -> list[Any]:
    """
    Construct list of optimization callbacks from configuration.

    Currently supports:

        - Early stopping callback (based on metric threshold)

    Args:
        optuna_cfg: Optuna sub-config with early stopping parameters
        monitor_metric: Target metric name (from ``training.monitor_metric``)

    Returns:
        list of Optuna callback objects (may be empty)

    Example:
        >>> callbacks = build_callbacks(optuna_cfg, "auc")
        >>> len(callbacks)  # 0 or 1 depending on early_stopping config
    """
    early_stop_callback = get_early_stopping_callback(
        direction=optuna_cfg.direction,
        threshold=optuna_cfg.early_stopping_threshold,
        patience=optuna_cfg.early_stopping_patience,
        enabled=optuna_cfg.enable_early_stopping,
        metric_name=monitor_metric,
    )

    return [early_stop_callback] if early_stop_callback else []