quantbt-engine 1.0.7__py3-none-any.whl

quantbt/optimization/__init__.py

@@ -0,0 +1,94 @@
+"""Domain-agnostic optimization API for QuantBT."""
+
+from .callbacks import JsonlOptimizationLogger, SingleObjectiveEarlyStopping
+from .candidate_selection import CandidateSelector, RobustSelectionConfig, SelectedCandidate, constraints_feasible
+from .config import OptimizationConfig, SamplerConfig
+from .constraints import CONSTRAINTS_USER_ATTR, constraints_from_trial, set_trial_constraints
+from .evaluator import TrialEvaluator
+from .evaluators import (
+    ArbitrageGenericEvaluator,
+    ArbitrageTrialOutput,
+    GenericEndpointEvaluator,
+    GridDCAGenericEvaluator,
+    GridDCATrialOutput,
+    OptionPackageGenericEvaluator,
+    OptionTrialOutput,
+    PreparedIntrabarEvaluator,
+    PreparedNativeEventStrategyEvaluator,
+    PreparedPortfolioEvaluator,
+    PreparedSignalEvaluator,
+)
+from .objectives import (
+    MissingOptimizationMetricError,
+    ReportMetricObjective,
+    SharpeObjective,
+    max_drawdown_constraint,
+    max_margin_utilization_constraint,
+    max_rejection_rate_constraint,
+    max_turnover_constraint,
+    metric_from_result,
+    metrics_from_result,
+    min_trades_constraint,
+    result_full_report,
+)
+from .optimizer import OptunaOptimizer
+from .multiseed import MultiSeedOptimization
+from .result import ObjectiveResult, OptimizationResult, OptimizationTrialRecord
+from .samplers import build_sampler
+from .space import (
+    SearchSpaceInfo,
+    build_grid_search_space,
+    search_space_info,
+    stable_params_key,
+    suggest_parameter,
+    suggest_params,
+)
+
+__all__ = [
+    "CONSTRAINTS_USER_ATTR",
+    "ArbitrageGenericEvaluator",
+    "ArbitrageTrialOutput",
+    "CandidateSelector",
+    "GenericEndpointEvaluator",
+    "GridDCAGenericEvaluator",
+    "GridDCATrialOutput",
+    "JsonlOptimizationLogger",
+    "MissingOptimizationMetricError",
+    "MultiSeedOptimization",
+    "ObjectiveResult",
+    "OptionPackageGenericEvaluator",
+    "OptionTrialOutput",
+    "OptimizationConfig",
+    "OptimizationResult",
+    "OptimizationTrialRecord",
+    "OptunaOptimizer",
+    "PreparedIntrabarEvaluator",
+    "PreparedNativeEventStrategyEvaluator",
+    "PreparedPortfolioEvaluator",
+    "PreparedSignalEvaluator",
+    "ReportMetricObjective",
+    "RobustSelectionConfig",
+    "SamplerConfig",
+    "SearchSpaceInfo",
+    "SelectedCandidate",
+    "SharpeObjective",
+    "SingleObjectiveEarlyStopping",
+    "TrialEvaluator",
+    "build_grid_search_space",
+    "build_sampler",
+    "constraints_feasible",
+    "constraints_from_trial",
+    "max_drawdown_constraint",
+    "max_margin_utilization_constraint",
+    "max_rejection_rate_constraint",
+    "max_turnover_constraint",
+    "metric_from_result",
+    "metrics_from_result",
+    "min_trades_constraint",
+    "search_space_info",
+    "set_trial_constraints",
+    "stable_params_key",
+    "suggest_parameter",
+    "suggest_params",
+    "result_full_report",
+]

quantbt/optimization/callbacks.py

@@ -0,0 +1,116 @@
+"""Callbacks shared by QuantBT optimization workflows."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import time
+from typing import Optional
+
+
+class SingleObjectiveEarlyStopping:
+    """Stop a single-objective Optuna study after best-value stagnation."""
+
+    def __init__(self, patience: int, direction: str, min_delta: float = 1e-4, min_trials: int = 0):
+        if patience <= 0:
+            raise ValueError("patience must be positive")
+        direction = str(direction).lower().strip()
+        if direction not in {"maximize", "minimize"}:
+            raise ValueError("direction must be maximize or minimize")
+        if min_delta < 0.0:
+            raise ValueError("min_delta must be >= 0")
+        if min_trials < 0:
+            raise ValueError("min_trials must be >= 0")
+        self.patience = int(patience)
+        self.direction = direction
+        self.min_delta = float(min_delta)
+        self.min_trials = int(min_trials)
+        self._best: Optional[float] = None
+        self._stale = 0
+        self._completed = 0
+
+    def __call__(self, study, trial) -> None:
+        try:
+            import optuna
+        except Exception:  # pragma: no cover - optuna import guard
+            optuna = None
+        if optuna is not None and trial.state is not optuna.trial.TrialState.COMPLETE:
+            return
+        try:
+            current = float(study.best_value)
+        except Exception:
+            return
+        self._completed += 1
+        if self._is_improved(current):
+            self._best = current
+            self._stale = 0
+        else:
+            self._stale += 1
+        if self._completed >= self.min_trials and self._stale >= self.patience:
+            study.stop()
+
+    def _is_improved(self, current: float) -> bool:
+        if self._best is None:
+            return True
+        if self.direction == "maximize":
+            return current > self._best + self.min_delta
+        return current < self._best - self.min_delta
+
+
+class JsonlOptimizationLogger:
+    """Append parseable JSONL trial records.
+
+    Single-objective studies log when the best trial changes. Multi-objective
+    studies log every completed trial because there is no scalar best value.
+    """
+
+    def __init__(self, path, *, objective_count: int):
+        self.path = Path(path)
+        self.objective_count = int(objective_count)
+        self._previous_best_number: Optional[int] = None
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def __call__(self, study, frozen_trial) -> None:
+        try:
+            import optuna
+        except Exception:  # pragma: no cover - optuna import guard
+            optuna = None
+        if optuna is not None and frozen_trial.state is not optuna.trial.TrialState.COMPLETE:
+            return
+        if self.objective_count == 1:
+            try:
+                best_number = int(study.best_trial.number)
+            except Exception:
+                return
+            if best_number == self._previous_best_number:
+                return
+            self._previous_best_number = best_number
+        row = {
+            "trial": int(frozen_trial.number),
+            "state": str(frozen_trial.state.name),
+            "values": _trial_values(frozen_trial),
+            "params": dict(frozen_trial.user_attrs.get("quantbt_full_params", frozen_trial.params)),
+            "metrics": dict(frozen_trial.user_attrs.get("quantbt_metrics", {})),
+            "constraints": list(frozen_trial.user_attrs.get("quantbt_constraints", ())),
+            "metadata": dict(frozen_trial.user_attrs.get("quantbt_metadata", {})),
+            "duration_seconds": _duration_seconds(frozen_trial),
+            "logged_at_unix": time.time(),
+        }
+        with self.path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(row, sort_keys=True, default=str) + "\n")
+
+
+def _trial_values(frozen_trial) -> list[float]:
+    if getattr(frozen_trial, "values", None) is not None:
+        return [float(value) for value in frozen_trial.values]
+    if getattr(frozen_trial, "value", None) is not None:
+        return [float(frozen_trial.value)]
+    return []
+
+
+def _duration_seconds(frozen_trial) -> Optional[float]:
+    start = getattr(frozen_trial, "datetime_start", None)
+    complete = getattr(frozen_trial, "datetime_complete", None)
+    if start is None or complete is None:
+        return None
+    return float((complete - start).total_seconds())

quantbt/optimization/candidate_selection.py

@@ -0,0 +1,397 @@
+"""Candidate selection helpers for optimization results."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from statistics import median
+from typing import Any, Iterable, Optional
+
+from .result import OptimizationResult, OptimizationTrialRecord
+
+
+def constraints_feasible(constraints: tuple[float, ...]) -> bool:
+    """Return True when all Optuna formal constraints are feasible."""
+
+    return all(float(value) <= 0.0 for value in constraints)
+
+
+@dataclass(frozen=True)
+class SelectedCandidate:
+    """Selected production candidate after feasibility/robustness filtering."""
+
+    params: dict[str, Any]
+    values: tuple[float, ...] = ()
+    metrics: dict[str, float] = field(default_factory=dict)
+    constraints: tuple[float, ...] = ()
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class RobustSelectionConfig:
+    """Configuration for plateau-based production candidate selection.
+
+    The selector is deliberately post-optimization: the sampler still learns
+    from the raw objective surface, while the final production params are
+    selected from a stable feasible neighborhood instead of a single spike.
+    """
+
+    top_quantile: float = 0.10
+    min_trades: Optional[float] = None
+    max_drawdown_pct: Optional[float] = None
+    neighborhood_radius: float = 0.10
+    min_neighbor_count: int = 3
+    seed_consensus: int = 1
+    instability_penalty: float = 0.25
+    worst_weight: float = 0.25
+    drawdown_penalty: float = 0.0
+    size_bonus: float = 0.01
+    ignore_params: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not (0.0 < float(self.top_quantile) <= 1.0):
+            raise ValueError("top_quantile must be in (0, 1]")
+        if float(self.neighborhood_radius) < 0.0:
+            raise ValueError("neighborhood_radius must be non-negative")
+        if int(self.min_neighbor_count) <= 0:
+            raise ValueError("min_neighbor_count must be positive")
+        if int(self.seed_consensus) <= 0:
+            raise ValueError("seed_consensus must be positive")
+        object.__setattr__(self, "ignore_params", tuple(str(name) for name in self.ignore_params))
+
+
+@dataclass(frozen=True)
+class CandidateSelector:
+    """Small public selector interface.
+
+    This is intentionally conservative. Robust WFO plateau selectors can plug
+    into this interface later; Phase 32B provides best/feasible/Pareto policies
+    so Optuna's best trial is not silently treated as production params.
+    """
+
+    mode: str = "feasible_best"
+    objective_index: int = 0
+    config: Optional[RobustSelectionConfig] = None
+
+    def select(self, result: OptimizationResult) -> SelectedCandidate:
+        mode = str(self.mode).lower().strip()
+        if mode in {"best", "single_best"}:
+            return self._single_best(result, require_feasible=False)
+        if mode in {"feasible_best", "best_feasible"}:
+            return self._single_best(result, require_feasible=True)
+        if mode in {"pareto_first", "first_pareto"}:
+            return self._pareto_first(result)
+        if mode in {"robust_plateau", "plateau_robust"}:
+            return self._robust_plateau(result)
+        raise ValueError(f"unsupported candidate selector mode={self.mode!r}")
+
+    def _single_best(self, result: OptimizationResult, *, require_feasible: bool) -> SelectedCandidate:
+        direction = _direction(result, int(self.objective_index))
+        completed = [record for record in result.trials if record.state == "COMPLETE" and len(record.values) > int(self.objective_index)]
+        if require_feasible:
+            completed = [record for record in completed if constraints_feasible(record.constraints)]
+        if not completed:
+            raise ValueError("no completed feasible optimization trials")
+        reverse = direction == "maximize"
+        best = sorted(completed, key=lambda record: record.values[int(self.objective_index)], reverse=reverse)[0]
+        return _selected_from_record(
+            best,
+            metadata={
+                "selector": self.mode,
+                "objective_index": int(self.objective_index),
+                "feasibility_filter": bool(require_feasible),
+            },
+        )
+
+    def _pareto_first(self, result: OptimizationResult) -> SelectedCandidate:
+        pareto = [trial for trial in result.pareto_trials if constraints_feasible(tuple(float(value) for value in trial.user_attrs.get("quantbt_constraints", ())))] 
+        if not pareto:
+            raise ValueError("optimization result has no Pareto trials")
+        trial = pareto[0]
+        params = dict(trial.user_attrs.get("quantbt_full_params", trial.params))
+        return SelectedCandidate(
+            params=params,
+            values=tuple(float(value) for value in (trial.values or ())),
+            metrics=dict(trial.user_attrs.get("quantbt_metrics", {})),
+            constraints=tuple(float(value) for value in trial.user_attrs.get("quantbt_constraints", ())),
+            metadata={
+                "selector": self.mode,
+                "trial_number": int(trial.number),
+                "pareto_count": int(len(result.pareto_trials)),
+                "feasible_pareto_count": int(len(pareto)),
+            },
+        )
+
+    def _robust_plateau(self, result: OptimizationResult) -> SelectedCandidate:
+        config = self.config or RobustSelectionConfig()
+        objective_index = int(self.objective_index)
+        direction = _direction(result, objective_index)
+        feasible = [
+            record
+            for record in result.trials
+            if _record_feasible_for_robust(record, objective_index=objective_index, config=config)
+        ]
+        if not feasible:
+            raise ValueError("no completed feasible optimization trials for robust plateau selection")
+
+        ranked = sorted(
+            feasible,
+            key=lambda record: _signed_objective(record, objective_index, direction),
+            reverse=True,
+        )
+        top_n = max(
+            1,
+            int(math.ceil(len(ranked) * float(config.top_quantile))),
+            min(int(config.min_neighbor_count), len(ranked)),
+        )
+        top_n = min(top_n, len(ranked))
+        top = ranked[:top_n]
+        param_names = _param_names(feasible, ignore=config.ignore_params)
+        fallback_reasons: list[str] = []
+        scored: list[dict[str, Any]] = []
+        for record in top:
+            neighbors = [
+                neighbor
+                for neighbor in top
+                if _param_distance(record.params, neighbor.params, feasible, param_names) <= float(config.neighborhood_radius)
+            ]
+            if not neighbors:
+                neighbors = [record]
+            seed_count = _seed_consensus_count(neighbors)
+            meets_count = len(neighbors) >= int(config.min_neighbor_count)
+            meets_seed = seed_count >= int(config.seed_consensus)
+            if meets_count and meets_seed:
+                scored.append(_score_neighborhood(record, neighbors, objective_index, direction, config, feasible, param_names))
+
+        if not scored:
+            fallback_reasons.append("no_candidate_met_neighbor_or_seed_consensus")
+            for record in top:
+                neighbors = [
+                    neighbor
+                    for neighbor in top
+                    if _param_distance(record.params, neighbor.params, feasible, param_names) <= float(config.neighborhood_radius)
+                ] or [record]
+                scored.append(_score_neighborhood(record, neighbors, objective_index, direction, config, feasible, param_names))
+
+        best_cluster = sorted(scored, key=lambda row: row["plateau_score"], reverse=True)[0]
+        selected_record = _medoid_record(best_cluster["neighbors"], feasible, param_names, objective_index, direction)
+        result.robust_candidates = [
+            {
+                "trial_number": int(row["center"].number),
+                "plateau_score": float(row["plateau_score"]),
+                "neighbor_count": int(len(row["neighbors"])),
+                "seed_consensus_count": int(row["seed_consensus_count"]),
+                "median_objective": float(row["median_objective"]),
+                "worst_objective": float(row["worst_objective"]),
+                "objective_std": float(row["objective_std"]),
+                "params": dict(row["center"].params),
+            }
+            for row in sorted(scored, key=lambda item: item["plateau_score"], reverse=True)
+        ]
+        metadata = {
+            "selector": self.mode,
+            "selected_by": "robust_plateau",
+            "objective_index": objective_index,
+            "top_quantile": float(config.top_quantile),
+            "top_trials": int(top_n),
+            "feasible_trials": int(len(feasible)),
+            "neighborhood_radius": float(config.neighborhood_radius),
+            "min_neighbor_count": int(config.min_neighbor_count),
+            "seed_consensus": int(config.seed_consensus),
+            "seed_consensus_count": int(best_cluster["seed_consensus_count"]),
+            "neighbor_count": int(len(best_cluster["neighbors"])),
+            "plateau_score": float(best_cluster["plateau_score"]),
+            "median_objective": float(best_cluster["median_objective"]),
+            "worst_objective": float(best_cluster["worst_objective"]),
+            "objective_std": float(best_cluster["objective_std"]),
+            "cluster_center_trial": int(best_cluster["center"].number),
+            "medoid_trial_number": int(selected_record.number),
+            "fallback_reasons": fallback_reasons,
+            "param_names": param_names,
+        }
+        return _selected_from_record(selected_record, metadata=metadata)
+
+
+def _selected_from_record(record: OptimizationTrialRecord, *, metadata: Optional[dict[str, Any]] = None) -> SelectedCandidate:
+    merged_metadata = dict(record.metadata)
+    merged_metadata.update(metadata or {})
+    merged_metadata["trial_number"] = int(record.number)
+    return SelectedCandidate(
+        params=dict(record.params),
+        values=tuple(record.values),
+        metrics=dict(record.metrics),
+        constraints=tuple(record.constraints),
+        metadata=merged_metadata,
+    )
+
+
+def _direction(result: OptimizationResult, objective_index: int) -> str:
+    try:
+        directions = tuple(str(direction.name).lower() for direction in result.study.directions)
+    except Exception:
+        directions = ("maximize",)
+    if objective_index < 0 or objective_index >= len(directions):
+        raise ValueError("objective_index out of range for optimization directions")
+    return directions[objective_index]
+
+
+def _record_feasible_for_robust(
+    record: OptimizationTrialRecord,
+    *,
+    objective_index: int,
+    config: RobustSelectionConfig,
+) -> bool:
+    if record.state != "COMPLETE" or len(record.values) <= int(objective_index):
+        return False
+    if not constraints_feasible(record.constraints):
+        return False
+    if config.min_trades is not None:
+        trades = _metric(record, ("num_trades", "trades", "trade_count"))
+        if trades is None or float(trades) < float(config.min_trades):
+            return False
+    if config.max_drawdown_pct is not None:
+        mdd = _metric(record, ("max_drawdown_pct", "mdd_pct", "max_dd_pct"))
+        if mdd is None or float(mdd) > float(config.max_drawdown_pct):
+            return False
+    return True
+
+
+def _metric(record: OptimizationTrialRecord, names: Iterable[str]) -> Optional[float]:
+    for name in names:
+        if name in record.metrics:
+            return float(record.metrics[name])
+    return None
+
+
+def _signed_objective(record: OptimizationTrialRecord, objective_index: int, direction: str) -> float:
+    value = float(record.values[int(objective_index)])
+    if direction == "minimize":
+        return -value
+    return value
+
+
+def _param_names(records: Iterable[OptimizationTrialRecord], *, ignore: tuple[str, ...]) -> list[str]:
+    ignored = set(ignore)
+    names: set[str] = set()
+    for record in records:
+        names.update(str(name) for name in record.params if str(name) not in ignored)
+    return sorted(names)
+
+
+def _param_distance(
+    left: dict[str, Any],
+    right: dict[str, Any],
+    records: Iterable[OptimizationTrialRecord],
+    param_names: list[str],
+) -> float:
+    if not param_names:
+        return 0.0
+    total = 0.0
+    for name in param_names:
+        lv = left.get(name)
+        rv = right.get(name)
+        if _is_numeric(lv) and _is_numeric(rv):
+            span = _numeric_span(records, name)
+            diff = 0.0 if span <= 0.0 else abs(float(lv) - float(rv)) / span
+        else:
+            diff = 0.0 if lv == rv else 1.0
+        total += diff * diff
+    return math.sqrt(total / len(param_names))
+
+
+def _numeric_span(records: Iterable[OptimizationTrialRecord], name: str) -> float:
+    values = [float(record.params[name]) for record in records if name in record.params and _is_numeric(record.params[name])]
+    if not values:
+        return 0.0
+    return float(max(values) - min(values))
+
+
+def _is_numeric(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(float(value))
+
+
+def _seed_labels(records: Iterable[OptimizationTrialRecord]) -> set[str]:
+    labels = set()
+    for record in records:
+        for key in ("quantbt_seed", "seed"):
+            if key in record.metadata:
+                labels.add(str(record.metadata[key]))
+                break
+    return labels
+
+
+def _seed_consensus_count(records: Iterable[OptimizationTrialRecord]) -> int:
+    records = list(records)
+    labels = _seed_labels(records)
+    if labels:
+        return len(labels)
+    return 1 if records else 0
+
+
+def _score_neighborhood(
+    center: OptimizationTrialRecord,
+    neighbors: list[OptimizationTrialRecord],
+    objective_index: int,
+    direction: str,
+    config: RobustSelectionConfig,
+    all_records: list[OptimizationTrialRecord],
+    param_names: list[str],
+) -> dict[str, Any]:
+    signed = [_signed_objective(record, objective_index, direction) for record in neighbors]
+    med = float(median(signed))
+    worst = float(min(signed))
+    std = _std(signed)
+    mdds = [_metric(record, ("max_drawdown_pct", "mdd_pct", "max_dd_pct")) for record in neighbors]
+    mdd_penalty = float(median([float(value) for value in mdds if value is not None])) if any(value is not None for value in mdds) else 0.0
+    score = (
+        med
+        + float(config.worst_weight) * worst
+        - float(config.instability_penalty) * std
+        - float(config.drawdown_penalty) * mdd_penalty
+        + float(config.size_bonus) * math.log1p(len(neighbors))
+    )
+    return {
+        "center": center,
+        "neighbors": neighbors,
+        "plateau_score": float(score),
+        "median_objective": med,
+        "worst_objective": worst,
+        "objective_std": std,
+        "seed_consensus_count": _seed_consensus_count(neighbors),
+        "mean_distance": _mean_distance(center, neighbors, all_records, param_names),
+    }
+
+
+def _std(values: list[float]) -> float:
+    if len(values) <= 1:
+        return 0.0
+    mean = sum(values) / len(values)
+    return math.sqrt(sum((value - mean) ** 2 for value in values) / len(values))
+
+
+def _mean_distance(
+    center: OptimizationTrialRecord,
+    neighbors: list[OptimizationTrialRecord],
+    records: list[OptimizationTrialRecord],
+    param_names: list[str],
+) -> float:
+    if not neighbors:
+        return 0.0
+    return sum(_param_distance(center.params, record.params, records, param_names) for record in neighbors) / len(neighbors)
+
+
+def _medoid_record(
+    neighbors: list[OptimizationTrialRecord],
+    all_records: list[OptimizationTrialRecord],
+    param_names: list[str],
+    objective_index: int,
+    direction: str,
+) -> OptimizationTrialRecord:
+    return sorted(
+        neighbors,
+        key=lambda record: (
+            _mean_distance(record, neighbors, all_records, param_names),
+            -_signed_objective(record, objective_index, direction),
+            int(record.number),
+        ),
+    )[0]

quantbt/optimization/config.py

@@ -0,0 +1,84 @@
+"""Configuration objects for QuantBT domain-agnostic optimization."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional, Tuple, Union
+
+
+Direction = str
+
+
+@dataclass(frozen=True)
+class OptimizationConfig:
+    """Runtime configuration for :class:`OptunaOptimizer`.
+
+    The config intentionally avoids strategy/domain fields. Domain-specific
+    data, endpoints, prepared runners, and metric extraction belong in
+    evaluator adapters.
+    """
+
+    study_name: str
+    n_trials: int = 300
+    directions: Tuple[Direction, ...] = ("maximize",)
+    seed: Optional[int] = 42
+    n_jobs: int = 1
+    early_stopping_rounds: Optional[int] = None
+    early_stopping_min_trials: int = 0
+    early_stopping_min_delta: float = 1e-4
+    show_progress_bar: bool = True
+    storage: Optional[str] = None
+    load_if_exists: bool = True
+    log_path: Optional[Union[str, Path]] = None
+    duplicate_policy: str = "prune"
+    exception_policy: str = "raise"
+
+    def __post_init__(self) -> None:
+        if not str(self.study_name).strip():
+            raise ValueError("study_name must be non-empty")
+        if self.n_trials <= 0:
+            raise ValueError("n_trials must be positive")
+        if not self.directions:
+            raise ValueError("at least one direction is required")
+        directions = tuple(str(direction).lower().strip() for direction in self.directions)
+        invalid = set(directions) - {"maximize", "minimize"}
+        if invalid:
+            raise ValueError(f"invalid directions: {invalid}")
+        object.__setattr__(self, "directions", directions)
+        if self.n_jobs <= 0:
+            raise ValueError("n_jobs must be positive")
+        if self.early_stopping_rounds is not None and self.early_stopping_rounds <= 0:
+            raise ValueError("early_stopping_rounds must be positive when provided")
+        if self.early_stopping_min_trials < 0:
+            raise ValueError("early_stopping_min_trials must be >= 0")
+        if self.early_stopping_min_delta < 0.0:
+            raise ValueError("early_stopping_min_delta must be >= 0")
+        duplicate_policy = str(self.duplicate_policy).lower().strip()
+        if duplicate_policy not in {"allow", "prune", "raise"}:
+            raise ValueError("duplicate_policy must be allow, prune, or raise")
+        object.__setattr__(self, "duplicate_policy", duplicate_policy)
+        exception_policy = str(self.exception_policy).lower().strip()
+        if exception_policy not in {"raise", "fail_trial", "prune"}:
+            raise ValueError("exception_policy must be raise, fail_trial, or prune")
+        object.__setattr__(self, "exception_policy", exception_policy)
+
+
+@dataclass(frozen=True)
+class SamplerConfig:
+    """Optuna sampler selection and sampler-specific kwargs."""
+
+    name: str = "tpe"
+    kwargs: dict[str, Any] = field(default_factory=dict)
+    constraint_mode: str = "sampler"
+
+    def __post_init__(self) -> None:
+        name = str(self.name).lower().strip()
+        if not name:
+            raise ValueError("sampler name must be non-empty")
+        object.__setattr__(self, "name", name)
+        object.__setattr__(self, "kwargs", dict(self.kwargs or {}))
+        constraint_mode = str(self.constraint_mode).lower().strip()
+        if constraint_mode not in {"sampler", "post_filter"}:
+            raise ValueError("constraint_mode must be sampler or post_filter")
+        object.__setattr__(self, "constraint_mode", constraint_mode)