Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(backtest): align fill-shift edges with the equity convention (review #1299)

cgycoreydd4b03d61cd1
diff --git a/agent/backtest/engines/options_portfolio.py b/agent/backtest/engines/options_portfolio.py
index 66aaad657..825ecafa1 100644
--- a/agent/backtest/engines/options_portfolio.py
+++ b/agent/backtest/engines/options_portfolio.py
@@ -233,13 +233,15 @@ def run_options_backtest(
all_dates = set()
for df in data_map.values():
all_dates.update(df.index)
- dates = sorted(all_dates)
+ full_dates = sorted(all_dates)
# Warm-up bars primed the signal engine above; from here they do not exist,
- # so nothing they contain reaches a fill, the equity curve or a metric.
- warmup_end = evaluation_start_index(config, pd.DatetimeIndex(dates))
- if warmup_end:
- dates = dates[warmup_end:]
+ # so nothing they contain reaches a fill, the equity curve or a metric. The
+ # full range stays available for the previous-bar lookup, so a signal dated
+ # the last warm-up bar fills on the first evaluated bar -- the equity
+ # engines' convention (the warm-up cut is applied after the signal shift).
+ warmup_end = evaluation_start_index(config, pd.DatetimeIndex(full_dates))
+ dates = full_dates[warmup_end:]
# Index signals by date
signal_by_date: Dict[str, List[Dict[str, Any]]] = {}
@@ -255,17 +257,21 @@ def run_options_backtest(
equity_records: List[Dict[str, Any]] = []
for idx, current_date in enumerate(dates):
+ full_idx = idx + warmup_end
ts = pd.Timestamp(current_date)
date_str = str(ts.date()) if hasattr(ts, "date") else str(ts)
# Signals are dated the bar they were computed on and priced/filled on
- # the next bar -- the framework convention the equity engines follow
- # (#1293). A signal dated before the first evaluation bar is never
- # executed, matching how warm-up-dated signals behaved before. Set
- # options_config.same_day_fill to price a signal on its own date.
+ # the next bar's close, executed end-of-day on the bar after the
+ # decision (#1293). Equity engines fill the next bar's open; the
+ # options engine deliberately fills the next close because signals are
+ # computed on end-of-day data. A signal dated the last warm-up bar
+ # fills on the first evaluated bar, matching the equity convention;
+ # only signals dated before the very first loaded bar can never fill.
+ # Set options_config.same_day_fill to price a signal on its own date.
if same_day_fill:
signal_date = date_str
- elif idx > 0:
- prev = pd.Timestamp(dates[idx - 1])
+ elif full_idx > 0:
+ prev = pd.Timestamp(full_dates[full_idx - 1])
signal_date = str(prev.date()) if hasattr(prev, "date") else str(prev)
else:
signal_date = None
@@ -319,32 +325,6 @@ def run_options_backtest(
})
positions.remove(pos)
- # 2b. Handle expiry
- expired = [p for p in positions if p.is_expired(ts)]
- for pos in expired:
- spot = spot_prices.get(pos.underlying_code, 0.0)
- intrinsic = pos.intrinsic_value(spot)
-
- # Expiry: recover intrinsic value (entry_price already deducted at open)
- settlement = intrinsic * pos.qty * contract_multiplier
- cash += settlement
- pnl = (intrinsic - pos.entry_price) * pos.qty * contract_multiplier
-
- side = "exercise" if intrinsic > 0 else "expire"
- trade_records.append({
- "timestamp": date_str,
- "code": pos.underlying_code,
- "option_type": pos.option_type,
- "strike": pos.strike,
- "expiry": str(pos.expiry.date()),
- "side": side,
- "price": round(intrinsic, 4),
- "qty": pos.qty,
- "pnl": round(pnl, 4),
- "entry_date": pos.entry_date,
- })
- positions.remove(pos)
-
# 3. Execute the prior bar's signals at today's prices
day_signals = signal_by_date.get(signal_date, []) if signal_date else []
for sig in day_signals:
@@ -456,7 +436,35 @@ def run_options_backtest(
underlying_code=matched.underlying_code,
)
- # 4. Compute portfolio mark-to-market value and Greeks
+ # 4. Handle expiry. Runs after signal execution so a fill dated the
+ # bar before expiry settles on the expiry bar itself: an option is
+ # never carried past its expiry and never settled a bar late (#1293).
+ expired = [p for p in positions if p.is_expired(ts)]
+ for pos in expired:
+ spot = spot_prices.get(pos.underlying_code, 0.0)
+ intrinsic = pos.intrinsic_value(spot)
+
+ # Expiry: recover intrinsic value (entry_price already deducted at open)
+ settlement = intrinsic * pos.qty * contract_multiplier
+ cash += settlement
+ pnl = (intrinsic - pos.entry_price) * pos.qty * contract_multiplier
+
+ side = "exercise" if intrinsic > 0 else "expire"
+ trade_records.append({
+ "timestamp": date_str,
+ "code": pos.underlying_code,
+ "option_type": pos.option_type,
+ "strike": pos.strike,
+ "expiry": str(pos.expiry.date()),
+ "side": side,
+ "price": round(intrinsic, 4),
+ "qty": pos.qty,
+ "pnl": round(pnl, 4),
+ "entry_date": pos.entry_date,
+ })
+ positions.remove(pos)
+
+ # 5. Compute portfolio mark-to-market value and Greeks
portfolio_value = cash
total_delta = 0.0
total_gamma = 0.0
diff --git a/agent/src/skills/options-strategy/SKILL.md b/agent/src/skills/options-strategy/SKILL.md
index 51456e917..cbe06ff6e 100644
--- a/agent/src/skills/options-strategy/SKILL.md
+++ b/agent/src/skills/options-strategy/SKILL.md
@@ -90,7 +90,8 @@ Iron Condor opening signal:
"options_config": {
"risk_free_rate": 0.05,
"iv_source": "historical",
- "contract_multiplier": 1.0
+ "contract_multiplier": 1.0,
+ "same_day_fill": false
}
}
```
@@ -100,6 +101,7 @@ Key fields:
- `options_config.risk_free_rate`: risk-free rate, default `0.05`
- `options_config.iv_source`: volatility source, currently supports `"historical"` (30-day rolling historical volatility computed from underlying closes)
- `options_config.contract_multiplier`: contract multiplier, default `1.0`
+- `options_config.same_day_fill`: `false` (default) fills a signal dated T on the next bar's close; `true` restores the legacy same-date fill (signal and fill share T's close and IV)
## BS Model Principles
diff --git a/agent/tests/test_options_next_bar_fill.py b/agent/tests/test_options_next_bar_fill.py
index edf41e8b6..72cede0ca 100644
--- a/agent/tests/test_options_next_bar_fill.py
+++ b/agent/tests/test_options_next_bar_fill.py
@@ -42,7 +42,7 @@ class _FlatLoader:
return {"SPY": _BARS.copy()}
-def _signal(date: str):
+def _signal(date: str, expiry: str = _EXPIRY):
class _Engine:
def generate(self, data_map): # noqa: ANN001
return [
@@ -50,7 +50,7 @@ def _signal(date: str):
"date": date,
"action": "open",
"underlying": "SPY",
- "legs": [{"type": "call", "strike": _STRIKE, "expiry": _EXPIRY, "qty": _QTY}],
+ "legs": [{"type": "call", "strike": _STRIKE, "expiry": expiry, "qty": _QTY}],
}
]
@@ -62,7 +62,14 @@ def _fill_price(day: pd.Timestamp, iv: float) -> float:
return bs_price(_BARS.at[day, "close"], _STRIKE, t, 0.0, iv, "call")
-def _run(tmp_path: Path, *, date: str, same_day: bool = False):
+def _run(
+ tmp_path: Path,
+ *,
+ date: str,
+ same_day: bool = False,
+ warmup_bars: int = 0,
+ expiry: str = _EXPIRY,
+):
run_options_backtest(
{
"codes": ["SPY"],
@@ -72,6 +79,7 @@ def _run(tmp_path: Path, *, date: str, same_day: bool = False):
"engine": "options",
"initial_cash": 100_000.0,
"commission": 0.0,
+ **({"warmup_bars": warmup_bars} if warmup_bars else {}),
"options_config": {
"risk_free_rate": 0.0,
"contract_multiplier": 1.0,
@@ -79,7 +87,7 @@ def _run(tmp_path: Path, *, date: str, same_day: bool = False):
},
},
_FlatLoader(),
- _signal(date),
+ _signal(date, expiry=expiry),
tmp_path,
)
return pd.read_csv(tmp_path / "artifacts" / "trades.csv")
@@ -121,3 +129,24 @@ def test_signal_dated_before_first_bar_never_executes(tmp_path: Path) -> None:
def test_signal_on_last_bar_has_no_next_bar_to_fill(tmp_path: Path) -> None:
trades = _run(tmp_path, date="2025-01-06")
assert len(trades) == 0
+
+
+def test_last_warmup_bar_signal_fills_on_first_eval_bar(tmp_path: Path) -> None:
+ """Equity parity: the warm-up cut applies after the signal shift, so a
+ signal dated the last warm-up bar fills on the first evaluated bar."""
+ trades = _run(tmp_path, date="2025-01-01", warmup_bars=1)
+
+ assert len(trades) == 1
+ assert trades.iloc[0]["timestamp"] == "2025-01-02"
+
+
+def test_fill_on_expiry_bar_settles_same_bar_never_a_bar_late(tmp_path: Path) -> None:
+ """Signal dated 2025-01-02 fills 2025-01-03 == expiry: settlement must
+ happen on that bar (entry T floored at 0.001, intrinsic at expiry spot),
+ not on the next bar at the next bar's spot."""
+ trades = _run(tmp_path, date="2025-01-02", expiry="2025-01-03")
+
+ assert list(trades["timestamp"]) == ["2025-01-03", "2025-01-03"]
+ assert trades.iloc[0]["side"] == "buy"
+ assert trades.iloc[1]["side"] == "expire" # K=100 vs close 90: OTM
+ assert trades.iloc[1]["price"] == pytest.approx(0.0)