Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(backtest): add a drift tolerance band to rebalance mode

Haozhe Wu56369112e5bd
diff --git a/agent/backtest/engines/base.py b/agent/backtest/engines/base.py
index 5d0ebc54d..2c36ecdd1 100644
--- a/agent/backtest/engines/base.py
+++ b/agent/backtest/engines/base.py
@@ -392,6 +392,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'")
+ # 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
+ # move re-pinned the position on 19 of 30 bars, which is noise being
+ # traded, not a decision being executed.
+ self.rebalance_tolerance = float(config.get("rebalance_tolerance", 0.0) or 0.0)
+ if not math.isfinite(self.rebalance_tolerance) or self.rebalance_tolerance < 0.0:
+ raise ValueError("rebalance_tolerance must be a finite, non-negative fraction")
# Markets that clear at or below zero (e.g. EU day-ahead power) opt in
# to opening on negative-price bars. Default False preserves the legacy
# "reject any open_price <= 0" behavior. An exactly-zero open is always
@@ -818,6 +826,7 @@ class BaseEngine(ABC):
# book. Say which ones, rather than leaving the reader to reconcile a
# rebalance count against a trade log that does not match it (#918).
m["position_adjustment"] = self.position_adjustment
+ m["rebalance_tolerance"] = self.rebalance_tolerance
m["dropped_target_adjustment_count"] = len(self.dropped_target_adjustments)
m["dropped_target_adjustments"] = [
{
@@ -1396,6 +1405,23 @@ class BaseEngine(ABC):
for price in prices
)
self._validate_rebalance_values(*prices, *sizes)
+ # Tolerance band. The held size is compared against the size the
+ # target implies at the unslipped price -- keeping the slippage side
+ # out of a drift question is the principled choice, though its
+ # practical effect is one slippage width and only reaches the
+ # outcome within that distance of the band edge, which is why no
+ # test pins it: such a test would assert a coincidence.
+ # A changed target moves this reference far past any sane band, so
+ # target changes still execute at every tolerance.
+ if self.rebalance_tolerance > 0.0:
+ reference_size = self.round_size(
+ self._calc_raw_size(symbol, target_notional, raw_price), raw_price
+ )
+ if abs(before.size - reference_size) <= self.rebalance_tolerance * abs(
+ reference_size
+ ):
+ continue
+
increase = sizes[0] > before.size + 1e-9
reduction = sizes[1] < before.size - 1e-9
# Both or neither means the target lies inside the fill-price band.
diff --git a/agent/backtest/runner.py b/agent/backtest/runner.py
index f41b83f48..bf4476b34 100644
--- a/agent/backtest/runner.py
+++ b/agent/backtest/runner.py
@@ -71,6 +71,14 @@ class BacktestConfigSchema(BaseModel):
interval: str = "1D"
engine: str = "daily"
position_adjustment: Literal["hold", "rebalance"] = "hold"
+ # 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".
+ # 0.0 is the historical behaviour and stays the default: without a band the
+ # resize test is decided by the slippage width alone, which re-pins a
+ # position on a one-basis-point move. A CHANGED target breaches any sane
+ # band on its own, so target changes always execute whatever this is set to.
+ rebalance_tolerance: float = Field(default=0.0, ge=0.0, allow_inf_nan=False)
# Returns divide by initial_cash, so a non-positive value yields inf/NaN
# metrics (total_return, annual_return, ...). Reject it at the config
# boundary instead of letting the run produce non-finite results.
diff --git a/agent/src/skills/strategy-generate/SKILL.md b/agent/src/skills/strategy-generate/SKILL.md
index d9baf3c51..2a7c2344a 100644
--- a/agent/src/skills/strategy-generate/SKILL.md
+++ b/agent/src/skills/strategy-generate/SKILL.md
@@ -127,6 +127,7 @@ Self-check after writing `signal_engine.py`:
"optimizer_params": {},
"engine": "daily",
"position_adjustment": "rebalance",
+ "rebalance_tolerance": 0.05,
"validation": null
}
```
@@ -146,6 +147,7 @@ Self-check after writing `signal_engine.py`:
- `"rebalance"` executes every target change with market fills and weighted-average entry accounting. It also re-sizes whenever the held weight has drifted from the target, and a strategy restates its target on every bar, so a constant target means a fill on every bar: measured on a 40-bar rising series, a constant 20% target produced **40 fills instead of 1**, with the fees, slippage and transaction taxes that follow. A strategy that rebalances on its own schedule (e.g. `rebalance_freq=20`) will still trade daily here.
- `"hold"` keeps a same-direction position until it exits or reverses, so the weight drifts with price and a requested resize is **not executed**. Dropped requests are counted in the report as `dropped_target_adjustment_count`, with the first twenty listed, so a rebalance count that does not match the trade log is explained rather than silent.
- Rule of thumb: `"rebalance"` when the target weight itself carries the strategy (optimizers, risk budgets, continuous scaling); `"hold"` when entries and exits carry it and the weight in between is incidental.
+- `rebalance_tolerance`: drift band around the target, as a fraction of it, used only under `"rebalance"`. A resize executes once the held weight has moved further than this from its target; a **changed** target breaches any sane band on its own, so target changes always execute. Default `0.0` means no band, and then the resize test is decided by the slippage width alone — measured on a constant 20% target over 60 bars, `0.0` produced 60 fills, `0.02` produced 12, and `0.05` produced 5 while the weight never left 0.21. **State it for any strategy with its own rebalance cadence**, otherwise a `rebalance_freq=20` strategy still trades every bar. `0.05` is a reasonable starting point, not a recommendation with evidence behind it — it is your modelling choice and the report records the value the run used.
- `initial_cash`: default 1,000,000
- `commission`: default 0.1%
- `validation`: optional statistical validation after backtest completes. Omit to skip. Example:
diff --git a/agent/tests/test_rebalance_tolerance.py b/agent/tests/test_rebalance_tolerance.py
new file mode 100644
index 000000000..d8c33f4f7
--- /dev/null
+++ b/agent/tests/test_rebalance_tolerance.py
@@ -0,0 +1,105 @@
+"""A drift band decides when a resize is worth trading (#918 follow-on).
+
+Without one, the only thing separating "resize" from "leave it alone" under
+``position_adjustment="rebalance"`` was the slippage width: a 0.01% daily move
+re-pinned the position on 19 of 30 bars. That is noise being traded, and it
+overrode whatever rebalance cadence the strategy had written for itself.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+import pytest
+
+from backtest.engines.base import BaseEngine
+
+
+class _Engine(BaseEngine):
+ def can_execute(self, symbol, direction, bar):
+ return True
+
+ def round_size(self, raw_size, price):
+ return float(int(raw_size))
+
+ def calc_commission(self, size, price, direction, is_open):
+ return 0.0
+
+ def apply_slippage(self, price, direction):
+ return price * (1 + 0.0005 * direction)
+
+
+_BARS = 60
+
+
+def _rising_series() -> tuple[pd.DatetimeIndex, pd.DataFrame, pd.DataFrame]:
+ dates = pd.bdate_range("2026-01-05", periods=_BARS)
+ prices = [100.0 * (1.005**i) for i in range(_BARS)]
+ bars = pd.DataFrame({"open": prices, "close": prices}, index=dates)
+ return dates, bars, pd.DataFrame({"A": bars["close"]}, index=dates)
+
+
+def _run(tolerance: float, targets: list[float], mode: str = "rebalance") -> _Engine:
+ dates, bars, close_df = _rising_series()
+ engine = _Engine(
+ {
+ "initial_cash": 10_000_000.0,
+ "position_adjustment": mode,
+ "rebalance_tolerance": tolerance,
+ }
+ )
+ engine._execute_bars(
+ dates, {"A": bars}, close_df, pd.DataFrame({"A": targets}, index=dates), ["A"]
+ )
+ return engine
+
+
+def test_the_default_band_is_zero_and_changes_nothing() -> None:
+ """Existing runs must not be rewritten by the introduction of the band."""
+ engine = _Engine({"initial_cash": 10_000_000.0, "position_adjustment": "rebalance"})
+ assert engine.rebalance_tolerance == 0.0
+
+ fills = len(_run(0.0, [0.20] * _BARS).trades)
+ assert fills == _BARS # every bar, which is the behaviour being preserved
+
+
+def test_a_band_stops_trading_the_drift_without_losing_the_target() -> None:
+ """The point is fewer fills at a weight that is still on target."""
+ counts = {tol: len(_run(tol, [0.20] * _BARS).trades) for tol in (0.0, 0.02, 0.05, 0.10)}
+
+ assert counts[0.0] > counts[0.02] > counts[0.05] >= counts[0.10]
+ assert counts[0.05] <= counts[0.0] / 5
+
+ weights = [
+ snapshot.get("A", 0.0)
+ for _, snapshot in _run(0.05, [0.20] * _BARS).actual_position_snapshots
+ ]
+ # Fewer trades, and the position never wanders far from the 20% it targets.
+ assert max(weights[:-1]) < 0.21
+
+
+def test_a_real_target_change_executes_at_any_band() -> None:
+ """A changed target moves the reference far past any sane tolerance."""
+ targets = [0.20] * 30 + [0.60] * (_BARS - 30)
+
+ for tolerance in (0.0, 0.05, 0.25):
+ engine = _run(tolerance, targets)
+ weights = [s.get("A", 0.0) for _, s in engine.actual_position_snapshots]
+ assert weights[30] == pytest.approx(0.60, abs=0.01), tolerance
+
+
+def test_the_band_does_not_apply_to_hold_mode() -> None:
+ """Hold mode never resizes, so a band there would be a silent no-op."""
+ engine = _run(0.05, [0.20] * _BARS, mode="hold")
+
+ # Exactly one round trip: opened once, never resized on the way, closed by
+ # the end of the backtest rather than by any rebalance decision.
+ assert len(engine.trades) == 1
+ assert engine.trades[0].exit_reason == "end_of_backtest"
+ assert engine.rebalance_tolerance == 0.05
+
+
[email protected]("value", [-0.01, float("nan"), float("inf")])
+def test_an_unusable_band_is_refused(value: float) -> None:
+ """A band is a modelling choice; a meaningless one must not be assumed away."""
+ with pytest.raises(ValueError, match="rebalance_tolerance"):
+ _Engine({"initial_cash": 1_000.0, "rebalance_tolerance": value})