quantbt-engine 1.0.7__tar.gz → 1.0.8__tar.gz

{quantbt_engine-1.0.7 → quantbt_engine-1.0.8}/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to `quantbt-engine` are documented here.
 
+## [1.0.8] - 2026-08-12
+
+### Changed
+
+- Added strict nested causal retraining for
+  `mode_1_decay + optimization_schedule="per_fold_causal"`. Mode 1 decay now
+  uses inner IS-only folds while each outer OOS segment remains untouched until
+  its parameters are frozen.
+- Added explicit chronological validation metadata so consumers can distinguish
+  retrospective global calibration, selection-adjusted OOS, and strict outer
+  OOS evaluation without breaking legacy result fields.
+- Added a bounded-RSS release test runner that executes deterministic pytest
+  shards in fresh processes; CI and publish workflows use the same selection.
+
+### Verification
+
+- Root/source mirror, prepared/reference WFO parity, nested-fold causality,
+  and the full non-real-data release suite passed before this version bump.
+
 ## [1.0.7] - 2026-08-04
 
 This is the first independently installable core package release line.

{quantbt_engine-1.0.7/src/quantbt_engine.egg-info → quantbt_engine-1.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantbt-engine
-Version: 1.0.7
+Version: 1.0.8
 Summary: Transparent, high-performance quantitative backtesting engine
 Author-email: Vu Cong Minh <vugioan11022002@gmail.com>
 License-Expression: MIT
@@ -218,6 +218,21 @@ tape. Normal `.backtest(...)` remains defensive and backward-compatible.
 Cython/C++ remains deferred because the larger benchmark still points to
 facade/report overhead rather than pure Numba kernels.
 
+Latest Phase 49B WFO benchmark (1,000 daily bars, identical seeds, folds,
+trials, strategies, account settings, and accounting kernels):
+
+| WFO workload | Phase 49A reference | Phase 49B prepared/scalar | Speedup | Parity |
+|---|---:|---:|---:|---|
+| Portfolio global, 1 study x 16 trials | 0.386s | 0.330s | 1.17x | exact |
+| Single-symbol causal, 6 studies x 16 trials | 4.051s | 1.781s | 2.27x | exact |
+
+Phase 49B prepares aligned WFO fold state once, scores trials directly from
+accounting arrays, and compacts completed Optuna ledgers. It does not cache user
+strategy signals or alter objectives. The isolated warm peak-RSS difference was
+within +/-0.15%, so the result is reported as an RSS plateau rather than a memory
+reduction. Reproduce it with
+`python benchmarks/run_phase49b_wfo_performance.py --rows 1000 --trials 16`.
+
 Latest Phase 31 intrabar execution benchmark:
 
 | Route | Workload | Runtime | Throughput | Ratio | Parity |
@@ -263,7 +278,7 @@ wheel:
 
 | Release artifact | Current status | Backend policy |
 |---|---|---|
-| `quantbt-engine==1.0.7` wheel/sdist | release-ready after local/TestPyPI approval | Python canonical; all existing endpoints remain available |
+| `quantbt-engine==1.0.8` wheel/sdist | release-ready after local/TestPyPI approval | Python canonical; all existing endpoints remain available |
 | `quantbt-native` PyO3 wheel | experimental, not published | explicit `native_backend="rust"` only |
 | `quantbt-engine[native]` | intentionally empty | no dependency is advertised before native certification |
 
@@ -330,7 +345,7 @@ Raw Phase 47D artifacts are kept under
 
 ### Phase 48F final release handoff
 
-The core `quantbt-engine` 1.0.7 artifact gate is now implemented locally and
+The core `quantbt-engine` 1.0.8 artifact gate is now implemented locally and
 in the release workflows: exact version/ref validation, wheel and sdist
 `twine check`, archive allowlist and secret scan, clean import plus `pip check`,
 and a SHA256 release manifest. The TestPyPI workflow is manual and OIDC
@@ -639,15 +654,19 @@ fills, positions, account state, and performance report.
 Install the released core package:
 
 ```bash
-pip install quantbt-engine==1.0.7
+pip install quantbt-engine==1.0.8
 ```
 
-Optional reports and third-party validation:
+Optional optimization, reports, and third-party validation:
 
 ```bash
-pip install "quantbt-engine[reports,validation]==1.0.7"
+pip install "quantbt-engine[optimization,reports,validation]==1.0.8"
 ```
 
+Walk-forward parameter search specifically requires the `optimization` extra.
+Read the [causal WFO guide](docs/walkforward_causal.md) before reporting OOS
+metrics from a fold-local schedule.
+
 Development from this repository:
 
 ```bash
@@ -672,7 +691,7 @@ pip install -e /root/bobby/pool_alpha/quantbt
 ```
 
 After the release is approved, downstream services should use
-`pip install quantbt-engine==1.0.7` and keep the unchanged import
+`pip install quantbt-engine==1.0.8` and keep the unchanged import
 `from quantbt import QuantBTEndpoint`.
 
 ## Quick Start
@@ -803,6 +822,31 @@ result = wf.backtest(data=df, param_ranges=param_ranges)
 wf.show_metrics(scope="auto")
 ```
 
+Multi-fold WFO keeps `optimization_schedule="global"` as the compatible
+default. Phase 49A also exposes two explicit fold-local schedules:
+
+- `mode_1_decay + per_fold_decay`: one study per fold, with same-fold OOS used
+  for final decay candidate selection (`selection_adjusted_oos`);
+- `mode_4_is_only_robust + per_fold_causal`: one study per fold, with strict
+  IS-only selection before outer OOS execution.
+- `mode_1_decay + per_fold_causal`: one outer study per fold, where Mode 1
+  decay is measured only on explicit nested inner folds contained in that
+  outer IS window; outer OOS remains untouched until parameters are frozen.
+
+Both schedules stitch one continuous target tape and run accounting once with
+`fold_boundary_position_policy="carry"`. See the [causal WFO guide]
+(docs/walkforward_causal.md), [docs/endpoint.md](docs/endpoint.md), and
+[methodology/walk_forward.md](methodology/walk_forward.md) for selection claims,
+strictness boundaries, and audit metadata.
+
+Phase 49B keeps this API stable. Endpoint-backed optimization prepares market
+and fold state once and uses scalar-only trial reports by default. Audit the
+lifecycle through `prepared_wfo_context`, `prepared_scoring_cache`,
+`trial_ledger_mode`, and `performance_profile` in walk-forward metadata.
+Nested Mode 1 also records `inner_validation`, `inner_fold_table`, and
+`chronological_validation_claim` so services can distinguish retrospective,
+selection-adjusted, and strict outer-OOS results.
+
 `scope="auto"` reports only the tested/OOS segment for walk-forward and
 train/test runs. Pass `scope="full"` when you need to audit the full stitched
 timeline.
@@ -852,6 +896,7 @@ backend, endpoint, or strategy route to use.
 | Market/limit/stop fill behavior | [Order fill policies](docs/order_fill_policies.md) |
 | Nautilus validation and report bundles | [Nautilus backend](docs/nautilus_backend.md) |
 | Pair, basket, hedge-ratio package behavior | [Pair and basket guide](docs/pair_basket_guide.md) |
+| Causal WFO schedules, outer-OOS claims, and audit metadata | [Causal WFO guide](docs/walkforward_causal.md) |
 | Walk-forward methodology and anti-leakage scoring | [Walk-forward methodology](docs/walkforward_methodology_vi.md) |
 | Runnable smoke templates | [Examples index](examples/README.md) |
 

{quantbt_engine-1.0.7 → quantbt_engine-1.0.8}/README.md

@@ -168,6 +168,21 @@ tape. Normal `.backtest(...)` remains defensive and backward-compatible.
 Cython/C++ remains deferred because the larger benchmark still points to
 facade/report overhead rather than pure Numba kernels.
 
+Latest Phase 49B WFO benchmark (1,000 daily bars, identical seeds, folds,
+trials, strategies, account settings, and accounting kernels):
+
+| WFO workload | Phase 49A reference | Phase 49B prepared/scalar | Speedup | Parity |
+|---|---:|---:|---:|---|
+| Portfolio global, 1 study x 16 trials | 0.386s | 0.330s | 1.17x | exact |
+| Single-symbol causal, 6 studies x 16 trials | 4.051s | 1.781s | 2.27x | exact |
+
+Phase 49B prepares aligned WFO fold state once, scores trials directly from
+accounting arrays, and compacts completed Optuna ledgers. It does not cache user
+strategy signals or alter objectives. The isolated warm peak-RSS difference was
+within +/-0.15%, so the result is reported as an RSS plateau rather than a memory
+reduction. Reproduce it with
+`python benchmarks/run_phase49b_wfo_performance.py --rows 1000 --trials 16`.
+
 Latest Phase 31 intrabar execution benchmark:
 
 | Route | Workload | Runtime | Throughput | Ratio | Parity |
@@ -213,7 +228,7 @@ wheel:
 
 | Release artifact | Current status | Backend policy |
 |---|---|---|
-| `quantbt-engine==1.0.7` wheel/sdist | release-ready after local/TestPyPI approval | Python canonical; all existing endpoints remain available |
+| `quantbt-engine==1.0.8` wheel/sdist | release-ready after local/TestPyPI approval | Python canonical; all existing endpoints remain available |
 | `quantbt-native` PyO3 wheel | experimental, not published | explicit `native_backend="rust"` only |
 | `quantbt-engine[native]` | intentionally empty | no dependency is advertised before native certification |
 
@@ -280,7 +295,7 @@ Raw Phase 47D artifacts are kept under
 
 ### Phase 48F final release handoff
 
-The core `quantbt-engine` 1.0.7 artifact gate is now implemented locally and
+The core `quantbt-engine` 1.0.8 artifact gate is now implemented locally and
 in the release workflows: exact version/ref validation, wheel and sdist
 `twine check`, archive allowlist and secret scan, clean import plus `pip check`,
 and a SHA256 release manifest. The TestPyPI workflow is manual and OIDC
@@ -589,15 +604,19 @@ fills, positions, account state, and performance report.
 Install the released core package:
 
 ```bash
-pip install quantbt-engine==1.0.7
+pip install quantbt-engine==1.0.8
 ```
 
-Optional reports and third-party validation:
+Optional optimization, reports, and third-party validation:
 
 ```bash
-pip install "quantbt-engine[reports,validation]==1.0.7"
+pip install "quantbt-engine[optimization,reports,validation]==1.0.8"
 ```
 
+Walk-forward parameter search specifically requires the `optimization` extra.
+Read the [causal WFO guide](docs/walkforward_causal.md) before reporting OOS
+metrics from a fold-local schedule.
+
 Development from this repository:
 
 ```bash
@@ -622,7 +641,7 @@ pip install -e /root/bobby/pool_alpha/quantbt
 ```
 
 After the release is approved, downstream services should use
-`pip install quantbt-engine==1.0.7` and keep the unchanged import
+`pip install quantbt-engine==1.0.8` and keep the unchanged import
 `from quantbt import QuantBTEndpoint`.
 
 ## Quick Start
@@ -753,6 +772,31 @@ result = wf.backtest(data=df, param_ranges=param_ranges)
 wf.show_metrics(scope="auto")
 ```
 
+Multi-fold WFO keeps `optimization_schedule="global"` as the compatible
+default. Phase 49A also exposes two explicit fold-local schedules:
+
+- `mode_1_decay + per_fold_decay`: one study per fold, with same-fold OOS used
+  for final decay candidate selection (`selection_adjusted_oos`);
+- `mode_4_is_only_robust + per_fold_causal`: one study per fold, with strict
+  IS-only selection before outer OOS execution.
+- `mode_1_decay + per_fold_causal`: one outer study per fold, where Mode 1
+  decay is measured only on explicit nested inner folds contained in that
+  outer IS window; outer OOS remains untouched until parameters are frozen.
+
+Both schedules stitch one continuous target tape and run accounting once with
+`fold_boundary_position_policy="carry"`. See the [causal WFO guide]
+(docs/walkforward_causal.md), [docs/endpoint.md](docs/endpoint.md), and
+[methodology/walk_forward.md](methodology/walk_forward.md) for selection claims,
+strictness boundaries, and audit metadata.
+
+Phase 49B keeps this API stable. Endpoint-backed optimization prepares market
+and fold state once and uses scalar-only trial reports by default. Audit the
+lifecycle through `prepared_wfo_context`, `prepared_scoring_cache`,
+`trial_ledger_mode`, and `performance_profile` in walk-forward metadata.
+Nested Mode 1 also records `inner_validation`, `inner_fold_table`, and
+`chronological_validation_claim` so services can distinguish retrospective,
+selection-adjusted, and strict outer-OOS results.
+
 `scope="auto"` reports only the tested/OOS segment for walk-forward and
 train/test runs. Pass `scope="full"` when you need to audit the full stitched
 timeline.
@@ -802,6 +846,7 @@ backend, endpoint, or strategy route to use.
 | Market/limit/stop fill behavior | [Order fill policies](docs/order_fill_policies.md) |
 | Nautilus validation and report bundles | [Nautilus backend](docs/nautilus_backend.md) |
 | Pair, basket, hedge-ratio package behavior | [Pair and basket guide](docs/pair_basket_guide.md) |
+| Causal WFO schedules, outer-OOS claims, and audit metadata | [Causal WFO guide](docs/walkforward_causal.md) |
 | Walk-forward methodology and anti-leakage scoring | [Walk-forward methodology](docs/walkforward_methodology_vi.md) |
 | Runnable smoke templates | [Examples index](examples/README.md) |
 

{quantbt_engine-1.0.7 → quantbt_engine-1.0.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantbt-engine"
-version = "1.0.7"
+version = "1.0.8"
 description = "Transparent, high-performance quantitative backtesting engine"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"

{quantbt_engine-1.0.7 → quantbt_engine-1.0.8}/src/quantbt/__init__.py

@@ -110,6 +110,7 @@ _LAZY_EXPORTS = {
             "WalkForwardConfig",
             "WalkForwardEngine",
             "WalkForwardFold",
+            "PreparedWalkForwardContext",
             "WalkForwardResult",
             "WalkForwardTrialRecord",
             "benchmark_walkforward_kernels",
@@ -499,7 +500,7 @@ from .metrics import (
 )
 
 
-__version__ = "1.0.7"
+__version__ = "1.0.8"
 __author__  = "quantbt"
 
 __all__ = [
@@ -667,6 +668,7 @@ __all__ = [
     "WalkForwardConfig",
     "WalkForwardEngine",
     "WalkForwardFold",
+    "PreparedWalkForwardContext",
     "WalkForwardResult",
     "WalkForwardTrialRecord",
     "WalkForwardBenchmarkSnapshot",

{quantbt_engine-1.0.7 → quantbt_engine-1.0.8}/src/quantbt/backends/native_portfolio.py

@@ -36,7 +36,7 @@ from ..core.preprocessor import (
     prepare_funding,
     validate_datetime,
 )
-from ..core.results import BacktestResultV2
+from ..core.results import BacktestResultV2, BacktestScalarScoreResult
 from ..core.schema import AccountConfig
 from ..core.schema import ExecutionConfig, InstrumentSpec
 from ..sizing.fast import scale_signal_notional_matrix
@@ -96,7 +96,8 @@ class NativePortfolioBackend:
         min_qty: Optional[Union[float, Dict[str, float]]] = None,
         min_notional: Optional[Union[float, Dict[str, float]]] = None,
         report_level: Optional[str] = None,
-    ) -> BacktestResultV2:
+        _scalar_score_trading_days: Optional[int] = None,
+    ) -> Union[BacktestResultV2, BacktestScalarScoreResult]:
         idx = validate_datetime(datetime_index)
         if positions is None and raw_signal_matrix is None:
             raise ValueError("positions or raw_signal_matrix is required")
@@ -253,6 +254,46 @@ class NativePortfolioBackend:
                 tradable=tradable_mask,
             )
 
+        if _scalar_score_trading_days is not None:
+            from ..metrics.performance import compute_performance_metrics
+
+            returns_arr = np.zeros_like(equity_arr, dtype=np.float64)
+            if len(equity_arr) > 1:
+                returns_arr[1:] = np.divide(
+                    equity_arr[1:] - equity_arr[:-1],
+                    equity_arr[:-1],
+                    out=np.zeros(len(equity_arr) - 1, dtype=np.float64),
+                    where=equity_arr[:-1] != 0.0,
+                )
+            metrics = compute_performance_metrics(
+                timestamps=idx,
+                equity=equity_arr,
+                returns=returns_arr,
+                positions=pos_arr,
+                symbols=symbol_list,
+                initial_capital=float(self.config.account.initial_capital),
+                liquidated=bool(liq_flag),
+                trading_days=int(_scalar_score_trading_days),
+            )
+            final_positions = (
+                np.asarray(pos_arr[-1], dtype=np.float64).copy()
+                if len(pos_arr)
+                else np.zeros(len(symbol_list), dtype=np.float64)
+            )
+            return BacktestScalarScoreResult(
+                final_equity=float(equity_arr[-1]),
+                final_positions=final_positions,
+                metrics=metrics,
+                liquidated=bool(liq_flag),
+                liquidation_bar=int(liq_idx),
+                metadata={
+                    "backend": "native_portfolio",
+                    "score_scalar": True,
+                    "score_pandas_materialized": False,
+                    "trading_days": int(_scalar_score_trading_days),
+                },
+            )
+
         result = self._build_result(
             idx=idx,
             symbol_list=symbol_list,
@@ -292,6 +333,16 @@ class NativePortfolioBackend:
             result.metadata["portfolio_contract_report"] = validate_portfolio_result_contract(result, spec, tolerance=1e-8)
         return result
 
+    def score_signals(self, *, trading_days: int = 365, **kwargs) -> BacktestScalarScoreResult:
+        """Run the portfolio accounting kernel and retain scalar metrics only."""
+        result = self.run_signals(
+            **kwargs,
+            _scalar_score_trading_days=int(trading_days),
+        )
+        if not isinstance(result, BacktestScalarScoreResult):  # pragma: no cover - guarded above
+            raise RuntimeError("native_portfolio scalar score unexpectedly materialized a public result")
+        return result
+
     def prepare_market_arrays(
         self,
         datetime_index: Union[pd.DatetimeIndex, pd.Series],

{quantbt_engine-1.0.7 → quantbt_engine-1.0.8}/src/quantbt/backends/native_vectorized.py

@@ -24,7 +24,7 @@ from ..core.preprocessor import (
     validate_datetime,
 )
 from ..core.constraints import build_quantity_constraints, quantize_target_units_matrix
-from ..core.results import BacktestResultV2
+from ..core.results import BacktestResultV2, BacktestScalarScoreResult
 from ..core.schema import (
     AccountConfig,
     BasketLegSpec,
@@ -276,7 +276,8 @@ class NativeVectorizedBackend:
         market_arrays: Optional[PreparedMarketArrays] = None,
         raw_signal_matrix: Optional[np.ndarray] = None,
         high_low_source: str = "provided",
-    ) -> BacktestResultV2:
+        _scalar_score_trading_days: Optional[int] = None,
+    ) -> Union[BacktestResultV2, BacktestScalarScoreResult]:
         contract_sizes = self._per_symbol_array(contract_size, symbol_list, default=1.0)
         constraints = build_quantity_constraints(
             symbol_list,
@@ -330,6 +331,46 @@ class NativeVectorizedBackend:
             use_funding=bool(self.config.use_funding),
         )
 
+        if _scalar_score_trading_days is not None:
+            from ..metrics.performance import compute_performance_metrics
+
+            returns_arr = np.zeros_like(equity_arr, dtype=np.float64)
+            if len(equity_arr) > 1:
+                returns_arr[1:] = np.divide(
+                    equity_arr[1:] - equity_arr[:-1],
+                    equity_arr[:-1],
+                    out=np.zeros(len(equity_arr) - 1, dtype=np.float64),
+                    where=equity_arr[:-1] != 0.0,
+                )
+            metrics = compute_performance_metrics(
+                timestamps=idx,
+                equity=equity_arr,
+                returns=returns_arr,
+                positions=pos_arr,
+                symbols=symbol_list,
+                initial_capital=float(self.config.account.initial_capital),
+                liquidated=bool(liq_flag),
+                trading_days=int(_scalar_score_trading_days),
+            )
+            final_positions = (
+                np.asarray(pos_arr[-1], dtype=np.float64).copy()
+                if len(pos_arr)
+                else np.zeros(len(symbol_list), dtype=np.float64)
+            )
+            return BacktestScalarScoreResult(
+                final_equity=float(equity_arr[-1]),
+                final_positions=final_positions,
+                metrics=metrics,
+                liquidated=bool(liq_flag),
+                liquidation_bar=int(liq_idx),
+                metadata={
+                    "backend": "native_vectorized",
+                    "score_scalar": True,
+                    "score_pandas_materialized": False,
+                    "trading_days": int(_scalar_score_trading_days),
+                },
+            )
+
         equity = pd.Series(equity_arr, index=idx, name="equity")
         returns = equity.pct_change().fillna(0.0)
         positions = pd.DataFrame(
@@ -413,7 +454,8 @@ class NativeVectorizedBackend:
         min_notional: Optional[Union[float, Dict[str, float]]] = None,
         market_arrays: Optional[PreparedMarketArrays] = None,
         raw_signal_matrix: Optional[np.ndarray] = None,
-    ) -> BacktestResultV2:
+        _scalar_score_trading_days: Optional[int] = None,
+    ) -> Union[BacktestResultV2, BacktestScalarScoreResult]:
         """
         Scale raw position signals into target units, then run the V2 kernel.
 
@@ -487,6 +529,7 @@ class NativeVectorizedBackend:
                 min_qty=min_qty,
                 min_notional=min_notional,
                 high_low_source=high_low_source,
+                _scalar_score_trading_days=_scalar_score_trading_days,
             )
 
         if close_dict is None:
@@ -528,6 +571,21 @@ class NativeVectorizedBackend:
             min_notional=min_notional,
         )
 
+    def score_signals(self, *, trading_days: int = 365, **kwargs) -> BacktestScalarScoreResult:
+        """Score prepared signal-notional targets without pandas report paths."""
+        hedge_type = str(kwargs.get("hedge_type", "signal_notional")).lower().strip()
+        if hedge_type not in {"signal_notional", "signal"}:
+            raise NotImplementedError(
+                "native_vectorized scalar scoring currently supports signal_notional only"
+            )
+        result = self.run_signals(
+            **kwargs,
+            _scalar_score_trading_days=int(trading_days),
+        )
+        if not isinstance(result, BacktestScalarScoreResult):  # pragma: no cover - guarded above
+            raise RuntimeError("native_vectorized scalar score unexpectedly materialized a public result")
+        return result
+
     def run_basis_arbitrage(
         self,
         datetime_index: Union[pd.DatetimeIndex, pd.Series],