quantbt-engine 1.0.7__py3-none-any.whl

quantbt/optimization/constraints.py

@@ -0,0 +1,22 @@
+"""Formal constraint helpers for Optuna-backed optimization."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+
+CONSTRAINTS_USER_ATTR = "quantbt_constraints"
+
+
+def set_trial_constraints(trial, constraints: Sequence[float]) -> tuple[float, ...]:
+    """Store constraints on an Optuna trial using QuantBT's canonical key."""
+
+    values = tuple(float(value) for value in constraints)
+    trial.set_user_attr(CONSTRAINTS_USER_ATTR, values)
+    return values
+
+
+def constraints_from_trial(frozen_trial) -> tuple[float, ...]:
+    """Optuna sampler callback returning trial constraints."""
+
+    return tuple(float(value) for value in frozen_trial.user_attrs.get(CONSTRAINTS_USER_ATTR, ()))

quantbt/optimization/evaluator.py

@@ -0,0 +1,21 @@
+"""Evaluator protocol for domain-specific optimization adapters."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Protocol
+
+from .result import ObjectiveResult
+
+
+class TrialEvaluator(Protocol):
+    """Protocol implemented by domain adapters.
+
+    The optimizer only sees parameters and an ObjectiveResult. Signal,
+    intrabar, portfolio, arbitrage, grid/DCA, and options details must remain
+    inside evaluator implementations.
+    """
+
+    def evaluate(self, params: Mapping[str, Any]) -> ObjectiveResult:
+        """Evaluate one parameter set and return objective values."""
+
+        ...

quantbt/optimization/evaluators/__init__.py

@@ -0,0 +1,32 @@
+"""Domain-specific optimization evaluators.
+
+Phase 32A intentionally keeps this namespace empty except for package
+discovery. Prepared signal/intrabar/portfolio and generic endpoint evaluators
+are implemented in Phase 32B.
+"""
+
+__all__: list[str] = []
+"""Domain evaluator adapters for QuantBT optimization."""
+
+from .arbitrage import ArbitrageGenericEvaluator, ArbitrageTrialOutput
+from .generic import GenericEndpointEvaluator
+from .grid_dca import GridDCAGenericEvaluator, GridDCATrialOutput
+from .intrabar import PreparedIntrabarEvaluator
+from .native_event import PreparedNativeEventStrategyEvaluator
+from .options import OptionPackageGenericEvaluator, OptionTrialOutput
+from .portfolio import PreparedPortfolioEvaluator
+from .signal import PreparedSignalEvaluator
+
+__all__ = [
+    "ArbitrageGenericEvaluator",
+    "ArbitrageTrialOutput",
+    "GenericEndpointEvaluator",
+    "GridDCAGenericEvaluator",
+    "GridDCATrialOutput",
+    "OptionPackageGenericEvaluator",
+    "OptionTrialOutput",
+    "PreparedIntrabarEvaluator",
+    "PreparedNativeEventStrategyEvaluator",
+    "PreparedPortfolioEvaluator",
+    "PreparedSignalEvaluator",
+]

quantbt/optimization/evaluators/arbitrage.py

@@ -0,0 +1,22 @@
+"""Generic arbitrage optimization adapter contracts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .generic import GenericEndpointEvaluator
+
+
+@dataclass(frozen=True)
+class ArbitrageTrialOutput:
+    """Domain output contract for arbitrage trial builders."""
+
+    signal: Any
+    hedge_ratios: Any = None
+    run_overrides: dict[str, Any] = field(default_factory=dict)
+
+
+class ArbitrageGenericEvaluator(GenericEndpointEvaluator):
+    """Generic fallback for arbitrage endpoints until specialized evaluators exist."""
+

quantbt/optimization/evaluators/generic.py

@@ -0,0 +1,34 @@
+"""Generic QuantBT endpoint evaluator fallback."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping
+
+from ..result import ObjectiveResult
+
+
+ObjectiveBuilder = Callable[[Any, Mapping[str, Any]], ObjectiveResult]
+
+
+@dataclass
+class GenericEndpointEvaluator:
+    """Evaluate params by building endpoint inputs and calling a run function."""
+
+    build_run_inputs: Callable[[Mapping[str, Any]], Mapping[str, Any]]
+    run_func: Callable[..., Any]
+    objective_builder: ObjectiveBuilder
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    last_result: Any = field(default=None, init=False)
+    last_run_inputs: dict[str, Any] = field(default_factory=dict, init=False)
+
+    def evaluate(self, params: Mapping[str, Any]) -> ObjectiveResult:
+        run_inputs = dict(self.build_run_inputs(params))
+        result = self.run_func(**run_inputs)
+        objective = self.objective_builder(result, params)
+        if not isinstance(objective, ObjectiveResult):
+            raise TypeError("objective_builder must return ObjectiveResult")
+        self.last_run_inputs = run_inputs
+        self.last_result = result
+        return objective

quantbt/optimization/evaluators/grid_dca.py

@@ -0,0 +1,22 @@
+"""Generic grid/DCA optimization adapter contracts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .generic import GenericEndpointEvaluator
+
+
+@dataclass(frozen=True)
+class GridDCATrialOutput:
+    """Domain output contract for structural grid/DCA trial builders."""
+
+    levels: Any = None
+    order_plan: Any = None
+    run_overrides: dict[str, Any] = field(default_factory=dict)
+
+
+class GridDCAGenericEvaluator(GenericEndpointEvaluator):
+    """Generic fallback for grid/DCA endpoints until prepared adapters exist."""
+

quantbt/optimization/evaluators/intrabar.py

@@ -0,0 +1,54 @@
+"""Prepared intrabar evaluator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, Optional
+
+import pandas as pd
+
+from ..result import ObjectiveResult
+from .generic import ObjectiveBuilder
+
+
+@dataclass
+class PreparedIntrabarEvaluator:
+    """Replay intrabar strategy intents through a prepared intrabar runner."""
+
+    runner: Any
+    strategy_func: Callable[..., Any]
+    objective_builder: ObjectiveBuilder
+    intent_builder: Optional[Callable[[Any, Mapping[str, Any]], Any]] = None
+    report_level: str = "minimal"
+    pass_runner: bool = False
+    pass_market: bool = False
+
+    last_result: Any = field(default=None, init=False)
+    last_intent: Any = field(default=None, init=False)
+
+    def evaluate(self, params: Mapping[str, Any]) -> ObjectiveResult:
+        if self.pass_runner:
+            output = self.strategy_func(self.runner, params)
+        elif self.pass_market:
+            output = self.strategy_func(self.runner.market, params)
+        else:
+            output = self.strategy_func(params)
+        intent = self._to_intent(output, params)
+        result = self.runner.run(intent, report_level=self.report_level)
+        objective = self.objective_builder(result, params)
+        if not isinstance(objective, ObjectiveResult):
+            raise TypeError("objective_builder must return ObjectiveResult")
+        self.last_intent = intent
+        self.last_result = result
+        return objective
+
+    def _to_intent(self, output: Any, params: Mapping[str, Any]) -> Any:
+        from ...core.intrabar_reference import IntrabarIntentTape
+
+        if self.intent_builder is not None:
+            return self.intent_builder(output, params)
+        if isinstance(output, IntrabarIntentTape):
+            return output
+        if isinstance(output, pd.DataFrame):
+            return IntrabarIntentTape.from_frame(output)
+        raise TypeError("intrabar strategy must return IntrabarIntentTape or DataFrame, or provide intent_builder")

quantbt/optimization/evaluators/native_event.py

@@ -0,0 +1,51 @@
+"""Prepared native-event strategy evaluator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping
+
+from ..result import ObjectiveResult
+from ...backends.native_event import NativeEventScoreRequirements
+from .generic import ObjectiveBuilder
+
+
+@dataclass
+class PreparedNativeEventStrategyEvaluator:
+    """Evaluate reactive native-event strategies through a prepared runner."""
+
+    runner: Any
+    strategy_factory: Callable[[Mapping[str, Any]], Any]
+    objective_builder: ObjectiveBuilder
+    trading_days: int = 365
+    retain_last: bool = False
+    score_requirements: NativeEventScoreRequirements = field(
+        default_factory=NativeEventScoreRequirements.scalar_score_contract
+    )
+
+    last_result: Any = field(default=None, init=False)
+    last_strategy: Any = field(default=None, init=False)
+
+    def evaluate(self, params: Mapping[str, Any]) -> ObjectiveResult:
+        strategy = self.strategy_factory(params)
+        requirements = NativeEventScoreRequirements.from_strategy(
+            strategy,
+            base=self.score_requirements,
+        )
+        result = self.runner.score(
+            strategy,
+            trading_days=self.trading_days,
+            score_requirements=requirements,
+        )
+        objective = self.objective_builder(result, params)
+        if not isinstance(objective, ObjectiveResult):
+            raise TypeError("objective_builder must return ObjectiveResult")
+        if self.retain_last:
+            self.last_strategy = strategy
+            self.last_result = result
+        else:
+            # Optimization can run thousands of trials. Retaining a strategy
+            # and score result pins their arrays until the evaluator dies.
+            self.last_strategy = None
+            self.last_result = None
+        return objective

quantbt/optimization/evaluators/options.py

@@ -0,0 +1,22 @@
+"""Generic option-package optimization adapter contracts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .generic import GenericEndpointEvaluator
+
+
+@dataclass(frozen=True)
+class OptionTrialOutput:
+    """Domain output contract for option package trial builders."""
+
+    package: Any = None
+    hedge_plan: Any = None
+    run_overrides: dict[str, Any] = field(default_factory=dict)
+
+
+class OptionPackageGenericEvaluator(GenericEndpointEvaluator):
+    """Generic fallback for option package endpoints until prepared adapters exist."""
+

quantbt/optimization/evaluators/portfolio.py

@@ -0,0 +1,42 @@
+"""Prepared native portfolio evaluator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, Optional
+
+from ..result import ObjectiveResult
+from .generic import ObjectiveBuilder
+
+
+@dataclass
+class PreparedPortfolioEvaluator:
+    """Replay strategy position matrices through a prepared portfolio context."""
+
+    prepared_context: Any
+    strategy_func: Callable[..., Any]
+    objective_builder: ObjectiveBuilder
+    pass_context: bool = False
+    positions_key: Optional[str] = None
+
+    last_result: Any = field(default=None, init=False)
+    last_positions: Any = field(default=None, init=False)
+
+    def evaluate(self, params: Mapping[str, Any]) -> ObjectiveResult:
+        output = self.strategy_func(self.prepared_context, params) if self.pass_context else self.strategy_func(params)
+        positions = _extract_positions(output, positions_key=self.positions_key)
+        result = self.prepared_context.backtest(positions=positions)
+        objective = self.objective_builder(result, params)
+        if not isinstance(objective, ObjectiveResult):
+            raise TypeError("objective_builder must return ObjectiveResult")
+        self.last_positions = positions
+        self.last_result = result
+        return objective
+
+
+def _extract_positions(output: Any, *, positions_key: Optional[str]) -> Any:
+    if positions_key is None:
+        return output
+    if isinstance(output, Mapping):
+        return output[positions_key]
+    return getattr(output, positions_key)

quantbt/optimization/evaluators/signal.py

@@ -0,0 +1,43 @@
+"""Prepared single-symbol signal evaluator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Mapping, Optional
+
+from ..result import ObjectiveResult
+from .generic import ObjectiveBuilder
+
+
+@dataclass
+class PreparedSignalEvaluator:
+    """Replay strategy signals through a prepared single-symbol context."""
+
+    prepared_context: Any
+    strategy_func: Callable[..., Any]
+    objective_builder: ObjectiveBuilder
+    pass_context: bool = False
+    signal_key: Optional[str] = None
+    signal_col: Optional[str] = None
+
+    last_result: Any = field(default=None, init=False)
+    last_signal: Any = field(default=None, init=False)
+
+    def evaluate(self, params: Mapping[str, Any]) -> ObjectiveResult:
+        output = self.strategy_func(self.prepared_context, params) if self.pass_context else self.strategy_func(params)
+        signal = _extract_signal(output, signal_key=self.signal_key)
+        result = self.prepared_context.backtest(signal=signal, signal_col=self.signal_col)
+        objective = self.objective_builder(result, params)
+        if not isinstance(objective, ObjectiveResult):
+            raise TypeError("objective_builder must return ObjectiveResult")
+        self.last_signal = signal
+        self.last_result = result
+        return objective
+
+
+def _extract_signal(output: Any, *, signal_key: Optional[str]) -> Any:
+    if signal_key is None:
+        return output
+    if isinstance(output, Mapping):
+        return output[signal_key]
+    return getattr(output, signal_key)

quantbt/optimization/multiseed.py

@@ -0,0 +1,176 @@
+"""Multi-seed optimization orchestration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import Any, Callable, Mapping, Optional, Sequence
+
+from .candidate_selection import CandidateSelector, RobustSelectionConfig
+from .config import OptimizationConfig, SamplerConfig
+from .evaluator import TrialEvaluator
+from .optimizer import OptunaOptimizer, _apply_baseline_floor, _is_better
+from .result import OptimizationResult, OptimizationTrialRecord
+
+
+@dataclass(frozen=True)
+class MultiSeedOptimization:
+    """Run the same search across several sampler seeds and aggregate trials.
+
+    This is a search-quality tool, not a different objective. Each seed still
+    optimizes the same evaluator; the aggregate result then selects production
+    params from regions that survive multiple random trajectories.
+    """
+
+    evaluator: TrialEvaluator
+    config: OptimizationConfig
+    sampler_config: SamplerConfig = field(default_factory=SamplerConfig)
+    seeds: Sequence[Optional[int]] = (None, 41, 42, 43, 44)
+    trials_per_seed: Optional[int] = None
+
+    def optimize(
+        self,
+        *,
+        param_ranges: Mapping[str, Any],
+        fixed_params: Optional[Mapping[str, Any]] = None,
+        initial_trials: Optional[Sequence[Mapping[str, Any]]] = None,
+        effective_params_builder: Optional[Callable[[Mapping[str, Any]], Mapping[str, Any]]] = None,
+        candidate_selector: Optional[CandidateSelector] = None,
+    ) -> OptimizationResult:
+        if not self.seeds:
+            raise ValueError("MultiSeedOptimization.seeds must be non-empty")
+
+        seed_results: list[OptimizationResult] = []
+        combined_trials: list[OptimizationTrialRecord] = []
+        seed_summaries: list[dict[str, Any]] = []
+        global_number = 0
+        for seed_index, seed in enumerate(self.seeds):
+            seed_label = "none" if seed is None else str(seed)
+            config = replace(
+                self.config,
+                seed=seed,
+                n_trials=int(self.trials_per_seed or self.config.n_trials),
+                study_name=f"{self.config.study_name}_seed_{seed_label}",
+            )
+            result = OptunaOptimizer(
+                evaluator=self.evaluator,
+                config=config,
+                sampler_config=self.sampler_config,
+            ).optimize(
+                param_ranges=param_ranges,
+                fixed_params=fixed_params,
+                initial_trials=initial_trials,
+                effective_params_builder=effective_params_builder,
+            )
+            seed_results.append(result)
+            seed_summaries.append(_seed_summary(result, seed=seed, seed_index=seed_index))
+            for record in result.trials:
+                metadata = dict(record.metadata)
+                metadata.update(
+                    {
+                        "quantbt_seed": seed_label,
+                        "quantbt_seed_index": int(seed_index),
+                        "quantbt_original_trial_number": int(record.number),
+                    }
+                )
+                combined_trials.append(
+                    OptimizationTrialRecord(
+                        number=int(global_number),
+                        state=str(record.state),
+                        params=dict(record.params),
+                        values=tuple(record.values),
+                        metrics=dict(record.metrics),
+                        constraints=tuple(record.constraints),
+                        metadata=metadata,
+                    )
+                )
+                global_number += 1
+
+        study_view = _StudyDirectionsView(seed_results[0].study.directions)
+        aggregate = OptimizationResult(
+            study=study_view,
+            best_params=None,
+            best_values=None,
+            pareto_trials=[],
+            trials=combined_trials,
+            trials_frame=None,
+        )
+        aggregate.baseline_trials = [
+            record
+            for record in combined_trials
+            if record.metadata.get("quantbt_source") == "warm_start"
+        ]
+        aggregate.seed_results = seed_summaries
+        _set_best_from_trials(aggregate)
+
+        selector = candidate_selector or CandidateSelector(
+            mode="robust_plateau",
+            config=RobustSelectionConfig(seed_consensus=min(2, len(self.seeds))),
+        )
+        selected = selector.select(aggregate)
+        aggregate.selected_params = dict(selected.params)
+        aggregate.selection_metadata = dict(selected.metadata)
+        aggregate.selection_metadata.update(
+            {
+                "selected_by_multiseed": True,
+                "seed_count": int(len(self.seeds)),
+            }
+        )
+        aggregate.search_diagnostics = {
+            "seed_count": int(len(self.seeds)),
+            "seed_results": seed_summaries,
+            "completed_trials": int(sum(1 for record in combined_trials if record.state == "COMPLETE")),
+            "pruned_trials": int(sum(1 for record in combined_trials if record.state == "PRUNED")),
+            "failed_trials": int(sum(1 for record in combined_trials if record.state == "FAIL")),
+            "top_parameter_frequency": _top_parameter_frequency(combined_trials),
+        }
+        _apply_baseline_floor(aggregate)
+        return aggregate
+
+
+def _set_best_from_trials(result: OptimizationResult) -> None:
+    try:
+        direction = str(result.study.directions[0].name).lower()
+    except Exception:
+        direction = "maximize"
+    completed = [record for record in result.trials if record.state == "COMPLETE" and record.values]
+    if not completed:
+        return
+    best = completed[0]
+    for record in completed[1:]:
+        if _is_better(record.values[0], best.values[0], direction):
+            best = record
+    result.best_params = dict(best.params)
+    result.best_values = tuple(best.values)
+
+
+def _seed_summary(result: OptimizationResult, *, seed: Optional[int], seed_index: int) -> dict[str, Any]:
+    return {
+        "seed": None if seed is None else int(seed),
+        "seed_index": int(seed_index),
+        "best_params": None if result.best_params is None else dict(result.best_params),
+        "best_values": None if result.best_values is None else tuple(float(value) for value in result.best_values),
+        "selected_params": None if result.selected_params is None else dict(result.selected_params),
+        "search_regression": bool(result.search_regression),
+        "baseline_rank": list(result.search_diagnostics.get("baseline_rank", [])),
+        "completed_trials": int(result.search_diagnostics.get("completed_trials", 0)),
+    }
+
+
+def _top_parameter_frequency(records: Sequence[OptimizationTrialRecord]) -> dict[str, dict[str, int]]:
+    completed = [record for record in records if record.state == "COMPLETE" and record.values]
+    if not completed:
+        return {}
+    ranked = sorted(completed, key=lambda record: record.values[0], reverse=True)
+    top_n = max(1, len(ranked) // 10)
+    counts: dict[str, dict[str, int]] = {}
+    for record in ranked[:top_n]:
+        for name, value in record.params.items():
+            bucket = counts.setdefault(str(name), {})
+            label = str(value)
+            bucket[label] = bucket.get(label, 0) + 1
+    return counts
+
+
+class _StudyDirectionsView:
+    def __init__(self, directions: Sequence[Any]):
+        self.directions = tuple(directions)