retrainopt 0.2.0__py3-none-any.whl

retrainopt/__init__.py

@@ -0,0 +1,31 @@
+"""RetrainOpt public package.
+
+RetrainOpt provides cost-aware retraining planning for time-sliced datasets.
+The public API is intentionally small:
+
+- ``TimelineDataset`` describes the retraining timeline.
+- ``ModelAdapter`` abstracts model fitting and evaluation.
+- ``PlannerConfig`` controls the search space and planning objective.
+- ``RetrainingPlanner`` produces retraining decision sequences.
+"""
+
+from importlib.metadata import version
+
+from .config import PlannerConfig
+from .interfaces import EvaluationProvider, ModelAdapter, TimelineDataset
+from .planner import RetrainingPlanner
+from .types import CandidateEvaluation, Decision, DecisionAction, PlanResult
+
+__version__ = version("retrainopt")
+
+__all__ = [
+    "Decision",
+    "CandidateEvaluation",
+    "DecisionAction",
+    "EvaluationProvider",
+    "ModelAdapter",
+    "PlannerConfig",
+    "PlanResult",
+    "RetrainingPlanner",
+    "TimelineDataset",
+]

retrainopt/__main__.py

@@ -0,0 +1,8 @@
+"""Module entry point for ``python -m retrainopt``."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

retrainopt/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""Built-in timeline and model adapters."""
+
+from .model import PrototypeModelAdapter, SklearnModelAdapter, TorchModelAdapter
+from .timeline import ArrayTimelineAdapter, BinaryTimelineAdapter, TorchTimelineAdapter
+
+__all__ = [
+    "ArrayTimelineAdapter",
+    "BinaryTimelineAdapter",
+    "PrototypeModelAdapter",
+    "SklearnModelAdapter",
+    "TorchModelAdapter",
+    "TorchTimelineAdapter",
+]

retrainopt/adapters/model.py

@@ -0,0 +1,216 @@
+"""Built-in model adapters."""
+
+from __future__ import annotations
+
+from numbers import Integral
+from typing import Any, Callable, Iterable, List, Sequence, Tuple
+
+from ..interfaces import ModelAdapter
+
+
+def _split_labeled_block(block: Any) -> Tuple[List[Any], List[int]]:
+    features: List[Any] = []
+    labels: List[int] = []
+    for item in block:
+        if not isinstance(item, Sequence) or len(item) != 2:
+            raise ValueError("Expected labeled items shaped like (features, label).")
+        features.append(item[0])
+        labels.append(int(item[1]))
+    return features, labels
+
+
+class SklearnModelAdapter(ModelAdapter):
+    """ModelAdapter for sklearn classifiers."""
+
+    def __init__(self, model_factory: Callable[[], Any] | Any):
+        self.model_factory = model_factory
+
+    def fit(self, train_data: Any, *, step: int, n_samples: int, random_seed: int) -> Any:
+        estimator = self._build_estimator()
+        if hasattr(estimator, "get_params"):
+            seed_params = {
+                name: int(random_seed) % (2 ** 32)
+                for name, value in estimator.get_params(deep=True).items()
+                if (name == "random_state" or name.endswith("__random_state")) and value is None
+            }
+            if seed_params:
+                estimator.set_params(**seed_params)
+        features, labels = _split_labeled_block(train_data)
+        estimator.fit(features, labels)
+        return estimator
+
+    def evaluate(self, model: Any, eval_data: Any, *, step: int) -> float:
+        try:
+            from sklearn.metrics import log_loss
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise RuntimeError("SklearnModelAdapter requires the `sklearn` extra.") from exc
+
+        features, labels = _split_labeled_block(eval_data)
+        if not features:
+            raise ValueError("Evaluation data must not be empty.")
+        if hasattr(model, "predict_proba"):
+            probabilities = model.predict_proba(features)
+            return float(log_loss(labels, probabilities, labels=list(model.classes_)))
+        predictions = model.predict(features)
+        mistakes = sum(int(prediction != label) for prediction, label in zip(predictions, labels))
+        return mistakes / max(1, len(labels))
+
+    def _build_estimator(self) -> Any:
+        try:
+            from sklearn.base import clone
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise RuntimeError("SklearnModelAdapter requires the `sklearn` extra.") from exc
+
+        if callable(self.model_factory):
+            return self.model_factory()
+        return clone(self.model_factory)
+
+
+class PrototypeModelAdapter(ModelAdapter):
+    """Dependency-free prototype classifier for small structured datasets."""
+
+    def fit(self, train_data: Any, *, step: int, n_samples: int, random_seed: int) -> Any:
+        if not train_data:
+            return {"prototypes": {}, "majority": 0}
+
+        grouped = {}
+        counts = {}
+        for features, label in train_data:
+            feature_vector = self._flatten_features(features)
+            grouped.setdefault(int(label), []).append(feature_vector)
+            counts[int(label)] = counts.get(int(label), 0) + 1
+
+        prototypes = {}
+        for label, vectors in grouped.items():
+            dimension = len(vectors[0])
+            mean_vector = []
+            for index in range(dimension):
+                mean_vector.append(sum(vector[index] for vector in vectors) / len(vectors))
+            prototypes[label] = tuple(mean_vector)
+
+        majority = max(counts.items(), key=lambda item: item[1])[0]
+        return {"prototypes": prototypes, "majority": majority}
+
+    def evaluate(self, model: Any, eval_data: Any, *, step: int) -> float:
+        if not eval_data:
+            raise ValueError("Evaluation data must not be empty.")
+
+        mistakes = 0
+        prototypes = model.get("prototypes", {})
+        majority = model.get("majority", 0)
+        for features, label in eval_data:
+            feature_vector = self._flatten_features(features)
+            if prototypes:
+                predicted = min(
+                    prototypes.items(),
+                    key=lambda item: self._squared_distance(item[1], feature_vector),
+                )[0]
+            else:
+                predicted = majority
+            if int(predicted) != int(label):
+                mistakes += 1
+        return mistakes / len(eval_data)
+
+    @staticmethod
+    def _flatten_features(features: Any) -> Tuple[float, ...]:
+        if isinstance(features, (list, tuple)):
+            return tuple(float(value) for value in features)
+        return (float(features),)
+
+    @staticmethod
+    def _squared_distance(left: Sequence[float], right: Sequence[float]) -> float:
+        return sum((float(lv) - float(rv)) ** 2 for lv, rv in zip(left, right))
+
+
+class TorchModelAdapter(ModelAdapter):
+    """ModelAdapter for PyTorch classifiers."""
+
+    def __init__(
+        self,
+        model_factory: Callable[[], Any],
+        *,
+        optimizer_factory: Callable[[Iterable[Any]], Any] | None = None,
+        epochs: int = 5,
+        batch_size: int = 64,
+        device: str = "cpu",
+    ):
+        self.model_factory = model_factory
+        self.optimizer_factory = optimizer_factory
+        for name, value in (("epochs", epochs), ("batch_size", batch_size)):
+            if isinstance(value, bool) or not isinstance(value, Integral) or value < 1:
+                raise ValueError(f"{name} must be a positive integer.")
+        self.epochs = int(epochs)
+        self.batch_size = int(batch_size)
+        self.device = device
+
+    def fit(self, train_data: Any, *, step: int, n_samples: int, random_seed: int) -> Any:
+        try:
+            import torch
+            from torch.utils.data import DataLoader
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise RuntimeError("TorchModelAdapter requires the `torch` extra.") from exc
+
+        device = torch.device(self.device)
+        device_type = device.type if device.type in {"cuda", "mps"} else "cuda"
+        devices = []
+        if device.type in {"cuda", "mps"}:
+            devices = [device.index or 0]
+        with torch.random.fork_rng(devices=devices, device_type=device_type):
+            torch.random.default_generator.manual_seed(random_seed)
+            if device.type == "cuda":
+                with torch.cuda.device(devices[0]):
+                    torch.cuda.manual_seed(random_seed)
+            elif device.type == "mps":
+                torch.mps.manual_seed(random_seed)
+            model = self.model_factory().to(self.device)
+            optimizer = (
+                self.optimizer_factory(model.parameters())
+                if self.optimizer_factory is not None
+                else torch.optim.Adam(model.parameters(), lr=1e-3)
+            )
+            criterion = torch.nn.CrossEntropyLoss()
+            generator = torch.Generator().manual_seed(random_seed)
+            train_loader = DataLoader(train_data, batch_size=self.batch_size, shuffle=True, generator=generator)
+
+            model.train()
+            for _ in range(self.epochs):
+                for inputs, targets in train_loader:
+                    inputs = inputs.to(self.device)
+                    targets = targets.to(self.device)
+                    optimizer.zero_grad()
+                    outputs = model(inputs)
+                    loss = criterion(outputs, targets)
+                    loss.backward()
+                    optimizer.step()
+            if device.type == "cuda":
+                torch.cuda.synchronize(device)
+            elif device.type == "mps":
+                torch.mps.synchronize()
+
+        return model
+
+    def evaluate(self, model: Any, eval_data: Any, *, step: int) -> float:
+        try:
+            import torch
+            from torch.utils.data import DataLoader
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise RuntimeError("TorchModelAdapter requires the `torch` extra.") from exc
+
+        loader = DataLoader(eval_data, batch_size=self.batch_size, shuffle=False, generator=torch.Generator().manual_seed(0))
+        criterion = torch.nn.CrossEntropyLoss()
+        model.eval()
+        total_loss = 0.0
+        total_count = 0
+
+        with torch.no_grad():
+            for inputs, targets in loader:
+                inputs = inputs.to(self.device)
+                targets = targets.to(self.device)
+                outputs = model(inputs)
+                loss = criterion(outputs, targets)
+                total_loss += float(loss.item()) * int(inputs.size(0))
+                total_count += int(inputs.size(0))
+
+        if total_count <= 0:
+            raise ValueError("Evaluation data must not be empty.")
+        return total_loss / total_count

retrainopt/adapters/timeline.py

@@ -0,0 +1,166 @@
+"""Built-in timeline adapters."""
+
+from __future__ import annotations
+
+import json
+import math
+import random
+import struct
+from numbers import Integral
+from pathlib import Path
+from typing import Any, Iterable, List, Sequence
+
+from ..interfaces import TimelineDataset
+
+
+class ArrayTimelineAdapter(TimelineDataset):
+    """Timeline adapter backed by in-memory Python sequences."""
+
+    def __init__(self, train_blocks: Sequence[Sequence[Any]], eval_blocks: Sequence[Sequence[Any]]):
+        if len(train_blocks) != len(eval_blocks):
+            raise ValueError("train_blocks and eval_blocks must have the same number of timesteps.")
+        if len(train_blocks) == 0:
+            raise ValueError("A timeline must contain at least one timestep.")
+        self._train_blocks = [list(block) for block in train_blocks]
+        self._eval_blocks = [list(block) for block in eval_blocks]
+        if any(not block for block in self._eval_blocks):
+            raise ValueError("Evaluation blocks must not be empty.")
+
+    @property
+    def num_steps(self) -> int:
+        return len(self._train_blocks)
+
+    def get_train_block(self, step: int) -> List[Any]:
+        return self._train_blocks[step]
+
+    def get_eval_block(self, step: int) -> List[Any]:
+        return self._eval_blocks[step]
+
+    def train_size(self, step: int) -> int:
+        return len(self._train_blocks[step])
+
+    def sample_train_block(self, step: int, n_samples: int, *, seed: int) -> List[Any]:
+        block = self._train_blocks[step]
+        actual_n = min(max(0, int(n_samples)), len(block))
+        if actual_n >= len(block):
+            return list(block)
+        if actual_n <= 0:
+            return []
+        rng = random.Random(seed)
+        indices = sorted(rng.sample(range(len(block)), actual_n))
+        return [block[idx] for idx in indices]
+
+
+class TorchTimelineAdapter(TimelineDataset):
+    """Timeline adapter for PyTorch datasets or lists of tensor/label pairs."""
+
+    def __init__(self, train_blocks: Sequence[Any], eval_blocks: Sequence[Any]):
+        if len(train_blocks) != len(eval_blocks):
+            raise ValueError("train_blocks and eval_blocks must have the same number of timesteps.")
+        if len(train_blocks) == 0:
+            raise ValueError("A timeline must contain at least one timestep.")
+        self._train_blocks = list(train_blocks)
+        self._eval_blocks = list(eval_blocks)
+        if any(len(block) == 0 for block in self._eval_blocks):
+            raise ValueError("Evaluation blocks must not be empty.")
+
+    @property
+    def num_steps(self) -> int:
+        return len(self._train_blocks)
+
+    def get_train_block(self, step: int) -> Any:
+        return self._train_blocks[step]
+
+    def get_eval_block(self, step: int) -> Any:
+        return self._eval_blocks[step]
+
+    def train_size(self, step: int) -> int:
+        return len(self._train_blocks[step])
+
+    def sample_train_block(self, step: int, n_samples: int, *, seed: int) -> Any:
+        block = self._train_blocks[step]
+        actual_n = min(max(0, int(n_samples)), len(block))
+        if actual_n >= len(block):
+            return block
+        if actual_n <= 0:
+            return []
+
+        try:
+            from torch.utils.data import Subset
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise RuntimeError("TorchTimelineAdapter requires the `torch` extra to sample datasets.") from exc
+
+        rng = random.Random(seed)
+        indices = sorted(rng.sample(range(len(block)), actual_n))
+        return Subset(block, indices)
+
+
+class BinaryTimelineAdapter(ArrayTimelineAdapter):
+    """Load a ``train/*.bin`` and ``test/*.bin`` timeline directory."""
+
+    def __init__(self, root_dir: str | Path, *, num_features: int | None = None):
+        root_path = Path(root_dir)
+        metadata_path = root_path / "metadata.json"
+        if num_features is None and metadata_path.exists():
+            metadata = json.loads(metadata_path.read_text())
+            if not isinstance(metadata, dict):
+                raise ValueError("metadata.json must contain a JSON object.")
+            num_features = metadata.get("num_features")
+        if isinstance(num_features, bool) or not isinstance(num_features, Integral) or num_features < 1:
+            raise ValueError("num_features must be a positive integer, supplied explicitly or in metadata.json.")
+
+        train_dir = root_path / "train"
+        eval_dir = root_path / "test"
+        train_ids = self._block_ids(train_dir)
+        eval_ids = self._block_ids(eval_dir)
+        if train_ids != eval_ids:
+            raise ValueError("Train and evaluation block identifiers must match exactly.")
+        train_blocks = self._load_blocks(train_dir, num_features)
+        eval_blocks = self._load_blocks(eval_dir, num_features)
+        super().__init__(train_blocks=train_blocks, eval_blocks=eval_blocks)
+
+    @staticmethod
+    def _block_ids(directory: Path) -> set[str]:
+        if not directory.is_dir():
+            raise FileNotFoundError(f"Timeline directory not found: {directory}")
+        stems = {path.stem for path in directory.glob("*.bin")}
+        numeric_ids = [int(stem) for stem in stems if stem.lstrip("-").isdigit()]
+        if len(set(numeric_ids)) != len(numeric_ids) or any(value < 0 for value in numeric_ids):
+            raise ValueError(f"Ambiguous or negative timestep identifiers in {directory}.")
+        return stems
+
+    @classmethod
+    def _load_blocks(cls, directory: Path, num_features: int) -> List[List[Any]]:
+        if not directory.exists():
+            raise FileNotFoundError(f"Timeline directory not found: {directory}")
+
+        files = sorted(directory.glob("*.bin"), key=lambda path: cls._sort_key(path.stem))
+        return [cls._read_bin_file(path, num_features) for path in files]
+
+    @staticmethod
+    def _sort_key(stem: str) -> Any:
+        try:
+            return (0, int(stem))
+        except ValueError:
+            return (1, stem)
+
+    @staticmethod
+    def _read_bin_file(path: Path, num_features: int) -> List[Any]:
+        payload = path.read_bytes()
+        values_per_record = num_features + 1
+        record_format = "<" + "f" * values_per_record
+        record_size = struct.calcsize(record_format)
+        if record_size <= 0 or len(payload) % record_size != 0:
+            raise ValueError(f"Unexpected record layout in {path}")
+
+        samples = []
+        for record in struct.iter_unpack(record_format, payload):
+            features = tuple(float(value) for value in record[:-1])
+            label_value = record[-1]
+            if not all(math.isfinite(value) for value in features):
+                raise ValueError(f"Non-finite feature value in {path}.")
+            if not math.isfinite(label_value) or label_value < 0 or not label_value.is_integer():
+                raise ValueError(f"Labels in {path} must be finite nonnegative integers.")
+            label = int(label_value)
+            samples.append((features, label))
+        return samples

retrainopt/cli.py

@@ -0,0 +1,130 @@
+"""CLI entry point for RetrainOpt."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+from typing import List
+
+from .adapters import BinaryTimelineAdapter, PrototypeModelAdapter, SklearnModelAdapter
+from .config import PlannerConfig
+from .planner import RetrainingPlanner
+
+
+def _parse_n_choice(value: str) -> int | float:
+    """Preserve integer-count versus decimal-fraction command-line intent."""
+    try:
+        if re.fullmatch(r"[+-]?\d+", value):
+            count = int(value)
+            if count >= 1:
+                return count
+        else:
+            fraction = float(value)
+            if math.isfinite(fraction) and 0 < fraction <= 1:
+                return fraction
+    except ValueError:
+        pass
+    raise argparse.ArgumentTypeError("Use a positive integer sample count (1) or a decimal fraction in (0, 1] (1.0 means all samples).")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="retrainopt",
+        description="RetrainOpt: Cost-aware retraining planning",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    plan_parser = subparsers.add_parser(
+        "plan",
+        help="Plan a retraining schedule for a train/test binary timeline directory.",
+    )
+    plan_parser.add_argument("--dataset-dir", required=True, help="Path containing train/*.bin and test/*.bin.")
+    plan_parser.add_argument("--num-features", type=int, default=None, help="Feature count if metadata.json is absent.")
+    plan_parser.add_argument("--method", choices=["exact", "bayes"], default="exact")
+    plan_parser.add_argument(
+        "--bayes-backend",
+        choices=["lightweight", "botorch"],
+        default="lightweight",
+        help="Surrogate backend used when --method=bayes.",
+    )
+    plan_parser.add_argument(
+        "--model",
+        choices=["prototype", "logistic_regression", "random_forest", "gradient_boosting"],
+        default="prototype",
+        help="Built-in model factory for CLI usage.",
+    )
+    plan_parser.add_argument(
+        "--n-choice",
+        dest="n_choices",
+        action="append",
+        type=_parse_n_choice,
+        default=None,
+        help="Repeat for integer sample counts or decimal fractions in (0, 1]; 1 means one sample, 1.0 means all.",
+    )
+    plan_parser.add_argument("--min-train-size", type=int, default=1)
+    plan_parser.add_argument("--random-seed", type=int, default=42)
+    plan_parser.add_argument("--time-cost-weight", type=float, default=1.0)
+    plan_parser.add_argument("--loss-cost-weight", type=float, default=1.0)
+    plan_parser.add_argument("--json", action="store_true", help="Emit the result as JSON.")
+    return parser
+
+
+def main(argv: List[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command != "plan":
+        parser.print_help()
+        return 0
+
+    timeline = BinaryTimelineAdapter(args.dataset_dir, num_features=args.num_features)
+    config = PlannerConfig(
+        n_choices=args.n_choices or (0.25, 0.5, 1.0),
+        min_train_size=args.min_train_size,
+        random_seed=args.random_seed,
+        time_cost_weight=args.time_cost_weight,
+        loss_cost_weight=args.loss_cost_weight,
+        bayes_backend=args.bayes_backend,
+    )
+    model_adapter = _build_model_adapter(args.model, args.random_seed)
+    planner = RetrainingPlanner(timeline, model_adapter, config=config)
+    result = planner.plan(method=args.method)
+
+    if args.json:
+        print(json.dumps(result.to_dict(), indent=2, allow_nan=False))
+    else:
+        print(f"RetrainOpt method={result.method} total_cost={result.total_cost:.6f}")
+        for step, decision in enumerate(result.decisions):
+            if decision.action.value == "keep":
+                print(f"t={step}: keep")
+            else:
+                print(f"t={step}: retrain n={decision.n_samples}")
+    return 0
+
+
+def _build_sklearn_factory(model_name: str, random_seed: int):
+    def _factory():
+        try:
+            from sklearn.ensemble import GradientBoostingClassifier, RandomForestClassifier
+            from sklearn.linear_model import LogisticRegression
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise RuntimeError(
+                "The RetrainOpt CLI model presets require the `sklearn` extra."
+            ) from exc
+
+        if model_name == "logistic_regression":
+            return LogisticRegression(max_iter=1000, random_state=random_seed)
+        if model_name == "random_forest":
+            return RandomForestClassifier(n_estimators=100, random_state=random_seed)
+        if model_name == "gradient_boosting":
+            return GradientBoostingClassifier(random_state=random_seed)
+        raise ValueError(f"Unsupported CLI model preset: {model_name}")
+
+    return _factory
+
+
+def _build_model_adapter(model_name: str, random_seed: int):
+    if model_name == "prototype":
+        return PrototypeModelAdapter()
+    return SklearnModelAdapter(_build_sklearn_factory(model_name, random_seed))

retrainopt/config.py

@@ -0,0 +1,106 @@
+"""Configuration objects for RetrainOpt."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import copy
+import math
+from numbers import Integral, Real
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+
+NumberLike = Union[int, float]
+
+
+@dataclass(frozen=True)
+class PlannerConfig:
+    """User-facing planner configuration.
+
+    ``n_choices`` accepts float fractions in ``(0, 1]`` or integer sample
+    counts ``>= 1``. Thus ``1`` means one sample and ``1.0`` means all samples.
+    """
+
+    n_choices: Sequence[NumberLike] = field(default_factory=lambda: (0.25, 0.5, 1.0))
+    min_train_size: int = 1
+    time_cost_weight: float = 1.0
+    loss_cost_weight: float = 1.0
+    random_seed: int = 42
+
+    # If ``None``, the planner synthesizes the initial model by training on the
+    # first timestep with ``initial_model_samples`` or the full first block.
+    initial_loss: Optional[float] = None
+    initial_model_samples: Optional[int] = None
+
+    # Approximate "bayes" mode controls.
+    bayes_iterations: int = 5
+    bayes_initial_samples: int = 6
+    bayes_candidates_per_iteration: int = 1
+    bayes_selection_strategy: str = "sequence"
+    bayes_anchor_steps: Sequence[float] = field(default_factory=lambda: (0.0, 0.5, 1.0))
+    acquisition: str = "expected"
+    bayes_backend: str = "lightweight"
+    exploration_beta: float = 1.0
+    improvement_xi: float = 0.01
+    surrogate_k: int = 5
+    surrogate_uncertainty_floor: float = 0.05
+    bayes_backend_options: Dict[str, Any] = field(default_factory=dict)
+    record_bayes_true_history: bool = False
+
+    def __post_init__(self) -> None:
+        choices = tuple(self.n_choices)
+        if not choices:
+            raise ValueError("n_choices must contain at least one sample count or fraction.")
+        for choice in choices:
+            if isinstance(choice, bool) or not isinstance(choice, Real):
+                raise ValueError("n_choices must contain positive integers or float fractions in (0, 1].")
+            if isinstance(choice, Integral):
+                if choice < 1:
+                    raise ValueError("Integer n_choices must be positive sample counts.")
+            elif not math.isfinite(choice) or not 0 < choice <= 1:
+                raise ValueError("Float n_choices must be finite fractions in (0, 1]; use an integer for a sample count.")
+        object.__setattr__(self, "n_choices", choices)
+        for name, minimum in (
+            ("min_train_size", 1), ("random_seed", 0), ("bayes_iterations", 0),
+            ("bayes_initial_samples", 1), ("bayes_candidates_per_iteration", 1), ("surrogate_k", 1),
+        ):
+            value = getattr(self, name)
+            if isinstance(value, bool) or not isinstance(value, Integral) or value < minimum:
+                raise ValueError(f"{name} must be an integer >= {minimum}.")
+        if self.initial_model_samples is not None and (
+            isinstance(self.initial_model_samples, bool)
+            or not isinstance(self.initial_model_samples, Integral)
+            or self.initial_model_samples < 1
+        ):
+            raise ValueError("initial_model_samples must be a positive integer.")
+        for name in ("time_cost_weight", "loss_cost_weight", "exploration_beta", "improvement_xi", "surrogate_uncertainty_floor", "initial_loss"):
+            value = getattr(self, name)
+            if value is None and name == "initial_loss":
+                continue
+            if isinstance(value, bool) or not isinstance(value, Real) or not math.isfinite(value) or value < 0:
+                raise ValueError(f"{name} must be finite and nonnegative.")
+        anchors = tuple(self.bayes_anchor_steps)
+        if any(isinstance(value, bool) or not isinstance(value, Real) or not math.isfinite(value) or not 0 <= value <= 1 for value in anchors):
+            raise ValueError("bayes_anchor_steps must contain finite fractions in [0, 1].")
+        object.__setattr__(self, "bayes_anchor_steps", anchors)
+        if not isinstance(self.bayes_backend_options, dict):
+            raise ValueError("bayes_backend_options must be a dictionary.")
+        object.__setattr__(self, "bayes_backend_options", copy.deepcopy(self.bayes_backend_options))
+
+    def resolve_n_choices(self, dataset_size: int) -> List[int]:
+        """Resolve configured sample choices for a concrete train block size."""
+        if isinstance(dataset_size, bool) or not isinstance(dataset_size, Integral) or dataset_size < 0:
+            raise ValueError("dataset_size must be a nonnegative integer.")
+        if dataset_size < self.min_train_size:
+            return []
+
+        choices = set()
+        for choice in self.n_choices:
+            if isinstance(choice, Integral):
+                n_value = min(dataset_size, choice)
+            else:
+                n_value = int(dataset_size * float(choice))
+
+            if n_value >= self.min_train_size:
+                choices.add(max(1, n_value))
+
+        return sorted(choices)