Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(backtest): add calendar-triggered partial rebalancing

thisisjun7867597d185a84d
diff --git a/agent/backtest/engines/base.py b/agent/backtest/engines/base.py
index 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_executed
m["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_arr
self._code_to_col = _code_to_col
self.actual_position_snapshots = []
+ execution_dates = resolve_rebalance_dates(self.rebalance_mask, dates)
+ self.rebalance_bars_executed = 0
for i, ts in enumerate(dates):
self._bar_idx = i
stop_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] = None
logger.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 += 1
target_weights = {}
else:
self._record_dropped_target_adjustments(target_weights, ts)
diff --git a/agent/backtest/rebalance_mask.py b/agent/backtest/rebalance_mask.py
new file mode 100644
index 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_dates
diff --git a/agent/backtest/runner.py b/agent/backtest/runner.py
index 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_mask
logger = 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 None
return v
+ @field_validator("rebalance_mask")
+ @classmethod
+ def valid_rebalance_mask(cls, v: RebalanceMask) -> RebalanceMask:
+ return validate_rebalance_mask(v)
+
@field_validator("interval")
@classmethod
def 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.py
new file mode 100644
index 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")