"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(backtest): add calendar-triggered partial rebalancing
thisisjun7867597d185a84d
diff --git a/agent/backtest/engines/base.py b/agent/backtest/engines/base.pyindex 218f1be4d..ef910a104 100644--- a/agent/backtest/engines/base.py+++ b/agent/backtest/engines/base.py@@ -43,6 +43,11 @@ from backtest.metrics import (calc_metrics,)from backtest.models import EquitySnapshot, FillRecord, Position, TradeRecord+from backtest.rebalance_mask import (+ RebalanceMask,+ resolve_rebalance_dates,+ validate_rebalance_mask,+)def _json_safe_scalar_metrics(metrics: Dict[str, Any]) -> Dict[str, Any]:@@ -463,6 +468,14 @@ class BaseEngine(ABC):self.position_adjustment = str(config.get("position_adjustment", "hold")).lower()if self.position_adjustment not in {"hold", "rebalance"}:raise ValueError("position_adjustment must be 'hold' or 'rebalance'")+ self.rebalance_mask: RebalanceMask = validate_rebalance_mask(+ config.get("rebalance_mask")+ )+ if self.rebalance_mask is not None and self.position_adjustment != "rebalance":+ raise ValueError(+ "rebalance_mask requires position_adjustment='rebalance'"+ )+ self.rebalance_bars_executed = 0# Relative drift band around the target weight. Zero reproduces the# historical behaviour, where the only thing separating "resize" from# "leave it alone" was the slippage width -- measured, a 0.01% daily@@ -958,6 +971,9 @@ class BaseEngine(ABC):m["total_return"] - benchmark_metadata["benchmark_return"], 6)m.update(self._plan_rejection_metrics())+ if self.rebalance_mask is not None:+ m["rebalance_mask"] = self.rebalance_mask+ m["rebalance_bars_executed"] = self.rebalance_bars_executedm["by_symbol"] = by_symbol_stats(self.trades)m["by_exit_reason"] = by_exit_reason_stats(self.trades)@@ -1088,11 +1104,14 @@ class BaseEngine(ABC):self._close_arr = _close_arrself._code_to_col = _code_to_colself.actual_position_snapshots = []+ execution_dates = resolve_rebalance_dates(self.rebalance_mask, dates)+ self.rebalance_bars_executed = 0for i, ts in enumerate(dates):self._bar_idx = istop_run = self.before_rebalance_bar(ts, data_map, codes)+ execute_targets = execution_dates is None or ts in execution_dates# a. Value the book at prices observable when orders execute.# Rebalances happen at the bar open, so using close_df[ts] here@@ -1103,14 +1122,20 @@ class BaseEngine(ABC):try:val = _target_arr[i, _code_to_col[c]]target_weights[c] = (- None if stop_run else (float(val) if not np.isnan(val) else 0.0)+ None+ if stop_run or not execute_targets+ else (float(val) if not np.isnan(val) else 0.0))except Exception as exc:target_weights[c] = Nonelogger.warning("Target weight failed for %s at %s: %s", c, ts, exc)if self.position_adjustment == "rebalance":- self._execute_target_rebalance(target_weights, data_map, ts, equity, codes)+ if execute_targets and not stop_run:+ self._execute_target_rebalance(+ target_weights, data_map, ts, equity, codes+ )+ self.rebalance_bars_executed += 1target_weights = {}else:self._record_dropped_target_adjustments(target_weights, ts)diff --git a/agent/backtest/rebalance_mask.py b/agent/backtest/rebalance_mask.pynew file mode 100644index 000000000..67db191df--- /dev/null+++ b/agent/backtest/rebalance_mask.py@@ -0,0 +1,81 @@+"""Execution-date contract for calendar-triggered portfolio rebalancing."""++from __future__ import annotations++from bisect import bisect_left+from datetime import date+from typing import TypeAlias++import pandas as pd+from pandas.tseries.frequencies import to_offset++RebalanceMask: TypeAlias = str | list[str] | None+++def validate_rebalance_mask(value: RebalanceMask) -> RebalanceMask:+ """Validate the configured schedule without consulting a trading calendar."""+ if value is None:+ return None+ if isinstance(value, str):+ if not value.strip():+ raise ValueError("rebalance_mask offset alias must not be empty")+ try:+ _ = to_offset(value)+ except ValueError:+ raise ValueError(+ f"rebalance_mask must be a pandas offset alias or ISO date list, got {value!r}"+ ) from None+ return value+ if not isinstance(value, list) or not value:+ raise ValueError(+ "rebalance_mask must be a non-empty pandas offset alias or ISO date list"+ )+ for item in value:+ if not isinstance(item, str):+ raise ValueError("rebalance_mask date entries must be ISO date strings")+ try:+ parsed = date.fromisoformat(item)+ except ValueError:+ raise ValueError(f"invalid rebalance_mask date: {item!r}") from None+ if parsed.isoformat() != item:+ raise ValueError(+ f"invalid rebalance_mask date: {item!r} (expected YYYY-MM-DD)"+ )+ return value+++def resolve_rebalance_dates(+ value: RebalanceMask,+ dates: pd.DatetimeIndex,+) -> frozenset[pd.Timestamp] | None:+ """Resolve an optional schedule to executable bars in the aligned calendar."""+ validated = validate_rebalance_mask(value)+ if validated is None:+ return None+ if len(dates) == 0:+ raise ValueError("rebalance_mask does not intersect the aligned trading dates")++ if isinstance(validated, str):+ observed = pd.Series(dates, index=dates)+ selected = []+ for item in observed.resample(validated).first().dropna().tolist():+ timestamp = pd.Timestamp(item)+ assert isinstance(timestamp, pd.Timestamp)+ selected.append(timestamp)+ else:+ selected = []+ for item in validated:+ requested = pd.Timestamp(item)+ assert isinstance(requested, pd.Timestamp)+ if dates.tz is not None:+ requested = requested.tz_localize(dates.tz)+ index = bisect_left(dates.asi8.tolist(), requested.value)+ if index < len(dates):+ timestamp = dates[index]+ assert isinstance(timestamp, pd.Timestamp)+ selected.append(timestamp)++ execution_dates = frozenset(selected)+ if not execution_dates:+ raise ValueError("rebalance_mask does not intersect the aligned trading dates")+ return execution_datesdiff --git a/agent/backtest/runner.py b/agent/backtest/runner.pyindex 68f8f9450..646bfa59a 100644--- a/agent/backtest/runner.py+++ b/agent/backtest/runner.py@@ -39,6 +39,7 @@ from backtest.engines._market_hooks import ( # noqa: F401 (re-exported)_detect_submarket,_is_china_futures,)+from backtest.rebalance_mask import RebalanceMask, validate_rebalance_masklogger = logging.getLogger(__name__)@@ -71,6 +72,7 @@ class BacktestConfigSchema(BaseModel):interval: str = "1D"engine: str = "daily"position_adjustment: Literal["hold", "rebalance"] = "hold"+ rebalance_mask: RebalanceMask = None# Under "rebalance", a resize executes only once the held weight has# drifted further than this fraction of its target -- the tolerance band# practitioners describe as "rebalance when weights move more than X".@@ -126,6 +128,11 @@ class BacktestConfigSchema(BaseModel):) from Nonereturn v+ @field_validator("rebalance_mask")+ @classmethod+ def valid_rebalance_mask(cls, v: RebalanceMask) -> RebalanceMask:+ return validate_rebalance_mask(v)+@field_validator("interval")@classmethoddef valid_interval(cls, v: str) -> str:@@ -179,6 +186,10 @@ class BacktestConfigSchema(BaseModel):@model_validator(mode="after")def start_before_end(self) -> "BacktestConfigSchema":+ if self.rebalance_mask is not None and self.position_adjustment != "rebalance":+ raise ValueError(+ "rebalance_mask requires position_adjustment='rebalance'"+ )if pd.Timestamp(self.start_date) > pd.Timestamp(self.end_date):raise ValueError(f"start_date ({self.start_date}) must be <= end_date ({self.end_date})"diff --git a/agent/tests/test_rebalance_mask.py b/agent/tests/test_rebalance_mask.pynew file mode 100644index 000000000..d01bfda34--- /dev/null+++ b/agent/tests/test_rebalance_mask.py@@ -0,0 +1,136 @@+"""Calendar/explicit-date execution mask for partial portfolio rebalancing."""++from __future__ import annotations++import pandas as pd+import pytest++from backtest.engines.base import BaseEngine+++class _MaskEngine(BaseEngine):+ """Frictionless engine exposing execution-mask behavior."""++ def __init__(self, **overrides):+ config = {+ "initial_cash": 1_000.0,+ "position_adjustment": "rebalance",+ }+ config.update(overrides)+ super().__init__(config)+ self.bar_sizes: list[float | None] = []++ def can_execute(self, symbol, direction, bar):+ return True++ def round_size(self, raw_size, price):+ return raw_size++ def calc_commission(self, size, price, direction, is_open):+ return 0.0++ def apply_slippage(self, price, direction):+ return price++ def after_rebalance_bar(self, timestamp, data_map, codes):+ position = self.positions.get("AAPL.US")+ self.bar_sizes.append(None if position is None else position.size)+ return False+++def _run_masked(+ engine: _MaskEngine,+ weights: list[float],+ *,+ dates: pd.DatetimeIndex | None = None,+) -> pd.DatetimeIndex:+ if dates is None:+ dates = pd.bdate_range("2026-01-02", periods=len(weights))+ bars = pd.DataFrame({"open": 100.0, "close": 100.0}, index=dates)+ engine._execute_bars(+ dates,+ {"AAPL.US": bars},+ pd.DataFrame({"AAPL.US": 100.0}, index=dates),+ pd.DataFrame({"AAPL.US": weights}, index=dates),+ ["AAPL.US"],+ )+ return dates+++def test_mask_false_bar_keeps_position_quantity_unchanged() -> None:+ engine = _MaskEngine(rebalance_mask=["2026-01-02"])++ _run_masked(engine, [0.2, 0.8, 0.2])++ assert engine.bar_sizes == pytest.approx([2.0, 2.0, 2.0])+ assert [fill.action for fill in engine.fill_records[:-1]] == ["open"]+++def test_mask_true_bar_partially_resizes_same_direction_position() -> None:+ engine = _MaskEngine(+ rebalance_mask=["2026-01-02", "2026-01-05"],+ )++ _run_masked(engine, [0.2, 0.8, 0.2])++ assert engine.bar_sizes == pytest.approx([2.0, 8.0, 8.0])+ assert [fill.action for fill in engine.fill_records[:-1]] == ["open", "increase"]+++def test_mask_true_zero_target_explicitly_exits_position() -> None:+ engine = _MaskEngine(+ rebalance_mask=["2026-01-02", "2026-01-05"],+ )++ _run_masked(engine, [0.5, 0.0, 0.0])++ assert engine.bar_sizes == [5.0, None, None]+ assert [fill.action for fill in engine.fill_records] == ["open", "close"]+++def test_missing_mask_preserves_every_bar_legacy_rebalance() -> None:+ engine = _MaskEngine()++ _run_masked(engine, [0.2, 0.8, 0.2])++ assert engine.bar_sizes == pytest.approx([2.0, 8.0, 2.0])+ assert [fill.action for fill in engine.fill_records[:-1]] == [+ "open",+ "increase",+ "reduce",+ ]+++def test_mask_is_rejected_with_hold_mode() -> None:+ with pytest.raises(ValueError, match="rebalance_mask.*position_adjustment"):+ _MaskEngine(+ position_adjustment="hold",+ rebalance_mask=["2026-01-02"],+ )+++def test_monthly_alias_executes_first_trading_bar_of_each_month() -> None:+ dates = pd.DatetimeIndex(+ [+ pd.Timestamp("2026-01-30"),+ pd.Timestamp("2026-02-02"),+ pd.Timestamp("2026-02-03"),+ ]+ )+ engine = _MaskEngine(rebalance_mask="MS")++ _run_masked(engine, [0.2, 0.8, 0.2], dates=dates)++ assert engine.bar_sizes == pytest.approx([2.0, 8.0, 8.0])+++def test_mask_without_trading_date_intersection_is_rejected() -> None:+ engine = _MaskEngine(rebalance_mask=["2030-01-01"])++ with pytest.raises(ValueError, match="rebalance_mask.*intersect"):+ _run_masked(engine, [0.2, 0.8, 0.2])+++def test_invalid_mask_alias_is_rejected() -> None:+ with pytest.raises(ValueError, match="rebalance_mask"):+ _MaskEngine(rebalance_mask="monthly")