"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
fix(backtest): judge price limits at execution time, not from the bar's close
Haozhe Wue855a3fc54f4
diff --git a/agent/backtest/engines/base.py b/agent/backtest/engines/base.pyindex eb26405e6..a01ac5aaa 100644--- a/agent/backtest/engines/base.py+++ b/agent/backtest/engines/base.py@@ -379,6 +379,10 @@ class BaseEngine(ABC):self.allow_nonpositive_prices: bool = bool(config.get("allow_nonpositive_prices", False))+ #: Bar fields consulted, in order, for the price-limit base price.+ #: Futures engines put ``pre_settle`` first: exchanges set the band off+ #: the previous settlement, not the previous close.+ self.base_price_fields: tuple[str, ...] = ("pre_close",)self.capital: float = self.initial_capitalself.positions: Dict[str, Position] = {}self.trades: List[TradeRecord] = []@@ -439,6 +443,96 @@ class BaseEngine(ABC):Slipped price."""+ def historical_base_price(self, symbol: str, bar: pd.Series) -> Optional[float]:+ """Return a reference price that is known before this bar's fill.++ Price-limit bands must be derived from a base price the market already+ knew when the order was placed. ``can_execute`` runs before the fill,+ and this engine fills at the CURRENT bar's open, so the current bar's+ close is not available information: using it is lookahead.++ Both sources here are strictly historical:+ 1. the first field of :attr:`base_price_fields` present on the bar —+ ``pre_close`` for cash equity, ``pre_settle`` first for futures,+ whose exchanges set the band off the previous settlement;+ 2. the previous row of the close panel the run pre-extracts, which is+ absent in a cross-market composite run (its sub-engines are+ stateless rule books with no panel of their own).++ Args:+ symbol: Symbol whose base price is wanted.+ bar: Current bar.++ Returns:+ The base price, or None when no historical close is reachable+ (first bar of a run, or a composite sub-engine).+ """+ for field in self.base_price_fields:+ if field in bar.index:+ raw = bar[field]+ if pd.notna(raw) and float(raw) > 0:+ return float(raw)++ close_arr = getattr(self, "_close_arr", None)+ col = getattr(self, "_code_to_col", {}).get(symbol)+ row = getattr(self, "_bar_idx", 0) - 1+ if close_arr is not None and col is not None and row >= 0:+ value = close_arr[row, col]+ if pd.notna(value) and float(value) > 0:+ return float(value)++ # Last resort: reconstruct the prior close from tushare's pct_chg, which+ # is in percentage points. Both inputs sit on the current bar, but their+ # ratio is the PREVIOUS close, so the result is still historical.+ if "pct_chg" in bar.index and "close" in bar.index:+ pct, close = bar["pct_chg"], bar["close"]+ if pd.notna(pct) and pd.notna(close) and float(close) > 0:+ denominator = 1.0 + float(pct) / 100.0+ if denominator > 0:+ return float(close) / denominator+ return None++ def prospective_fill_price(self, bar: pd.Series, direction: int) -> Optional[float]:+ """Return the price this engine would fill at on this bar.++ Mirrors the sizing path: the bar's open, with slippage applied in the+ trade direction. Comparing THIS against a price-limit band keeps the+ simulation from ever transacting outside the exchange's legal range.++ Args:+ bar: Current bar.+ direction: 1 (buy / cover), -1 (sell / short), 0 (close).++ Returns:+ The prospective fill price, or None when the bar has no usable open.+ """+ raw = bar.get("open", bar.get("close"))+ if raw is None or pd.isna(raw):+ return None+ price = float(raw)+ if price <= 0 and not self.allow_nonpositive_prices:+ return None+ return self.apply_slippage(price, direction)++ def limit_band(+ self, symbol: str, bar: pd.Series, limit: float+ ) -> Optional[tuple[float, float]]:+ """Return the (lower, upper) legal price band for this bar.++ Args:+ symbol: Symbol whose band is wanted.+ bar: Current bar.+ limit: Band half-width as a fraction (0.1 for +/-10%).++ Returns:+ The (lower, upper) band, or None when no historical base price is+ reachable — in which case the caller must not fabricate a block.+ """+ base = self.historical_base_price(symbol, bar)+ if base is None or base <= 0 or not limit:+ return None+ return base * (1.0 - float(limit)), base * (1.0 + float(limit))+def on_bar(self, symbol: str, bar: pd.Series, timestamp: pd.Timestamp) -> None:"""Per-bar market-rule hook (funding fees, liquidation, etc.).diff --git a/agent/backtest/engines/china_a.py b/agent/backtest/engines/china_a.pyindex 01ced562d..10664196d 100644--- a/agent/backtest/engines/china_a.py+++ b/agent/backtest/engines/china_a.py@@ -61,14 +61,9 @@ class ChinaAEngine(BaseEngine):if bar_date is not None and entry_date is not None and bar_date == entry_date:return False- # 3. Price limits- pct_chg = _calc_pct_change(bar)- if pct_chg is not None:- limit = _price_limit(symbol)- if direction == 1 and pct_chg >= limit - 0.001:- return False # limit-up: can't buy- if direction == 0 and pct_chg <= -limit + 0.001:- return False # limit-down: can't sell+ # 3. Price limits, tested at execution time (see _blocked_by_limit).+ if _blocked_by_limit(self, symbol, direction, bar, _price_limit(symbol)):+ return Falsereturn True@@ -117,21 +112,59 @@ def _bar_date(bar: pd.Series):return None-# Note: china_futures and global_futures have variants that prioritise-# settle/pre_settle (futures-native); see those modules for the-# futures-specific logic.-def _calc_pct_change(bar: pd.Series):- """Calculate price change percentage from bar data."""- if "pct_chg" in bar.index:- val = bar["pct_chg"]- if pd.notna(val):- return float(val) / 100.0 # tushare pct_chg is in percentage points-- close = bar.get("close")- pre_close = bar.get("pre_close")- if close is not None and pre_close is not None and pre_close > 0:- return (float(close) - float(pre_close)) / float(pre_close)- return None+def _blocked_by_limit(+ engine,+ symbol: str,+ direction: int,+ bar: pd.Series,+ limit: float,+ position_direction: int | None = None,+) -> bool:+ """Whether a price-limit band blocks a fill on this bar.++ Shared by every engine with a daily band (A-share, India, China futures,+ global futures). The band comes from a base price the market knew before+ the order — ``pre_close``, else the prior bar's close — and is compared+ against the price the engine would actually fill at, which is this bar's+ open plus slippage.++ The earlier implementation derived the day's move from the CURRENT bar's+ close, which is lookahead and wrong in both directions: a name that opened+ locked but drifted back by the close was allowed to trade at the locked+ open, and a name that opened freely but closed limit-up was refused a fill+ it would have got.++ Args:+ engine: Engine instance (needs the BaseEngine band helpers).+ symbol: Symbol being traded.+ direction: 1 (buy / open long), -1 (sell short), 0 (close).+ bar: Current bar.+ limit: Band half-width as a fraction (0.1 for +/-10%).+ position_direction: For ``direction == 0``, the direction of the+ position being closed: 1 closes a long (a sell, blocked at the+ lower band), -1 closes a short (a buy, blocked at the upper band).+ Defaults to a long close, which is the cash-equity case.++ Returns:+ True when the band blocks the fill. False when it does not, and also+ when no historical base price is reachable — an unknown band must not+ fabricate a block.+ """+ band = engine.limit_band(symbol, bar, limit)+ if band is None:+ return False+ lower, upper = band+ fill = engine.prospective_fill_price(bar, direction)+ if fill is None:+ return False++ # Relative tolerance: a fill within a rounding step of the band counts as+ # touching it, matching the old check's 0.1pp slack in percentage terms.+ tol = 1e-9 * max(abs(lower), abs(upper), 1.0)+ buying = direction == 1 or (direction == 0 and position_direction == -1)+ if buying:+ return fill >= upper - tol+ return fill <= lower + toldef _price_limit(symbol: str) -> float:diff --git a/agent/backtest/engines/china_futures.py b/agent/backtest/engines/china_futures.pyindex 1c6925162..3bf6fe2f3 100644--- a/agent/backtest/engines/china_futures.py+++ b/agent/backtest/engines/china_futures.py@@ -16,6 +16,7 @@ import reimport pandas as pd+from backtest.engines.china_a import _blocked_by_limitfrom backtest.engines.futures_base import FuturesBaseEngine@@ -151,6 +152,8 @@ class ChinaFuturesEngine(FuturesBaseEngine):leverage = 10.0 # ~10% margin defaultconfig = {**config, "leverage": leverage}super().__init__(config)+ # Futures bands come off the previous settlement, not the previous close.+ self.base_price_fields = ("pre_settle", "pre_close")self.slippage_rate: float = config.get("slippage", 0.0005)self._margin_rate_override = margin_override if margin_override else Noneself._commission_override = config.get("commission_override")@@ -169,24 +172,20 @@ class ChinaFuturesEngine(FuturesBaseEngine):# T+0: no same-day sell restriction# Both long and short allowed- # Price limit check- pct_chg = _calc_pct_change(bar)- if pct_chg is not None:- product = _extract_product(symbol)- limit = _PRICE_LIMIT.get(product, _DEFAULT_PRICE_LIMIT)- if direction == 1 and pct_chg >= limit - 0.001:- return False # limit-up: can't open long / can't buy- if direction == -1 and pct_chg <= -limit + 0.001:- return False # limit-down: can't open short- if direction == 0:- pos = self.positions.get(symbol)- if pos is not None:- # Can't close long at limit-down, can't close short at limit-up- if pos.direction == 1 and pct_chg <= -limit + 0.001:- return False- if pos.direction == -1 and pct_chg >= limit - 0.001:- return False- return True+ # Price limit, tested at execution time (see _blocked_by_limit).+ product = _extract_product(symbol)+ limit = _PRICE_LIMIT.get(product, _DEFAULT_PRICE_LIMIT)+ pos = self.positions.get(symbol) if direction == 0 else None+ if pos is None and direction == 0:+ return True+ return not _blocked_by_limit(+ self,+ symbol,+ direction,+ bar,+ limit,+ position_direction=pos.direction if pos is not None else None,+ )def round_size(self, raw_size: float, price: float) -> float:"""Minimum 1 contract, integer lots only."""@@ -253,33 +252,3 @@ class ChinaFuturesEngine(FuturesBaseEngine):# ── Helpers ──--# Note: china_a uses close/pre_close-only; global_futures prioritises-# close/pre_close before settle. This China-futures variant prefers-# settle/pre_settle because tushare reports settlement as the canonical-# daily price for domestic contracts. See those modules for the equity /-# global-futures equivalents.-def _calc_pct_change(bar: pd.Series):- """Calculate bar price change percentage.-- Priority: settle/pre_settle (futures native) > close/pre_close > pct_chg.- pct_chg from tushare is always in percentage points (0.5 = 0.5%).- """- # Prefer settlement prices (unambiguous for futures)- settle = bar.get("settle")- pre_settle = bar.get("pre_settle")- if settle is not None and pre_settle is not None and pre_settle > 0:- return (float(settle) - float(pre_settle)) / float(pre_settle)-- close = bar.get("close")- pre_close = bar.get("pre_close")- if close is not None and pre_close is not None and pre_close > 0:- return (float(close) - float(pre_close)) / float(pre_close)-- # tushare pct_chg is in percentage points (e.g. 0.5 = 0.5%)- if "pct_chg" in bar.index:- val = bar["pct_chg"]- if pd.notna(val):- return float(val) / 100.0-- return Nonediff --git a/agent/backtest/engines/global_futures.py b/agent/backtest/engines/global_futures.pyindex 6695eece4..9b7666e20 100644--- a/agent/backtest/engines/global_futures.py+++ b/agent/backtest/engines/global_futures.py@@ -16,6 +16,7 @@ import reimport pandas as pd+from backtest.engines.china_a import _blocked_by_limitfrom backtest.engines.futures_base import FuturesBaseEngine@@ -141,6 +142,8 @@ class GlobalFuturesEngine(FuturesBaseEngine):leverage = config.get("leverage", 10.0)config = {**config, "leverage": leverage}super().__init__(config)+ # Futures bands come off the previous settlement, not the previous close.+ self.base_price_fields = ("pre_settle", "pre_close")self.slippage_rate: float = config.get("slippage", 0.0003)self._comm_override = config.get("commission_per_contract")@@ -160,20 +163,18 @@ class GlobalFuturesEngine(FuturesBaseEngine):if limit is None:return True # no price limit for most commodities- pct_chg = _calc_pct_change(bar)- if pct_chg is not None:- if direction == 1 and pct_chg >= limit - 0.001:- return False # limit-up- if direction == -1 and pct_chg <= -limit + 0.001:- return False # limit-down- if direction == 0:- pos = self.positions.get(symbol)- if pos is not None:- if pos.direction == 1 and pct_chg <= -limit + 0.001:- return False- if pos.direction == -1 and pct_chg >= limit - 0.001:- return False- return True+ # Tested at execution time (see _blocked_by_limit).+ pos = self.positions.get(symbol) if direction == 0 else None+ if pos is None and direction == 0:+ return True+ return not _blocked_by_limit(+ self,+ symbol,+ direction,+ bar,+ limit,+ position_direction=pos.direction if pos is not None else None,+ )def round_size(self, raw_size: float, price: float) -> float:"""Integer contracts, minimum 1."""@@ -219,33 +220,3 @@ class GlobalFuturesEngine(FuturesBaseEngine):# ── Helpers ──--# Note: china_a uses close/pre_close-only; china_futures prioritises-# settle/pre_settle. This global-futures variant prefers close/pre_close-# because CME data feeds (yfinance/IB) expose continuous close more-# reliably than settlement. See those modules for the equity /-# China-futures equivalents.-def _calc_pct_change(bar: pd.Series):- """Calculate bar price change percentage.-- Priority: close/pre_close > settle/pre_settle > pct_chg.- Falls back to pct_chg only when price fields are absent.- """- close = bar.get("close")- pre_close = bar.get("pre_close")- if close is not None and pre_close is not None and pre_close > 0:- return (float(close) - float(pre_close)) / float(pre_close)-- settle = bar.get("settle")- pre_settle = bar.get("pre_settle")- if settle is not None and pre_settle is not None and pre_settle > 0:- return (float(settle) - float(pre_settle)) / float(pre_settle)-- if "pct_chg" in bar.index:- val = bar["pct_chg"]- if pd.notna(val):- raw = float(val)- # Heuristic: values > 1 are likely percentage points- return raw / 100.0 if abs(raw) > 1.0 else raw-- return Nonediff --git a/agent/backtest/engines/india_equity.py b/agent/backtest/engines/india_equity.pyindex 53604fc4d..fd50f8814 100644--- a/agent/backtest/engines/india_equity.py+++ b/agent/backtest/engines/india_equity.py@@ -32,7 +32,7 @@ from __future__ import annotationsimport pandas as pdfrom backtest.engines.base import BaseEngine-from backtest.engines.china_a import _calc_pct_change+from backtest.engines.china_a import _blocked_by_limitclass IndiaEquityEngine(BaseEngine):@@ -86,15 +86,11 @@ class IndiaEquityEngine(BaseEngine):if bar_date is not None and entry_date is not None and bar_date == entry_date:return False- # 3. Circuit bands (single configurable band; disabled when falsy).- if self.price_limit:- pct_chg = _calc_pct_change(bar)- if pct_chg is not None:- limit = float(self.price_limit)- if direction == 1 and pct_chg >= limit - 0.001:- return False # upper circuit: can't buy- if direction == 0 and pct_chg <= -limit + 0.001:- return False # lower circuit: can't sell+ # 3. Circuit bands, tested at execution time (see _blocked_by_limit).+ if self.price_limit and _blocked_by_limit(+ self, symbol, direction, bar, float(self.price_limit)+ ):+ return Falsereturn Truediff --git a/agent/tests/test_china_a_engine.py b/agent/tests/test_china_a_engine.pyindex a895eb29a..dcd5061a1 100644--- a/agent/tests/test_china_a_engine.py+++ b/agent/tests/test_china_a_engine.py@@ -18,7 +18,6 @@ import pytestfrom backtest.engines.china_a import (ChinaAEngine,_bar_date,- _calc_pct_change,_price_limit,)from backtest.models import Position@@ -260,20 +259,6 @@ class TestPriceLimit:assert _price_limit(symbol) == expected-class TestCalcPctChange:- def test_from_pct_chg_field(self) -> None:- bar = _make_bar(pct_chg=5.0)- assert _calc_pct_change(bar) == pytest.approx(0.05)-- def test_from_close_and_pre_close(self) -> None:- bar = _make_bar(close=16.5, pre_close=15.0)- assert _calc_pct_change(bar) == pytest.approx(0.1)-- def test_none_when_no_data(self) -> None:- bar = pd.Series({"close": 15.0})- assert _calc_pct_change(bar) is None--class TestBarDate:def test_from_trade_date_col(self) -> None:bar = _make_bar(trade_date="2025-06-10")diff --git a/agent/tests/test_price_limit_lookahead.py b/agent/tests/test_price_limit_lookahead.pynew file mode 100644index 000000000..c7acf361e--- /dev/null+++ b/agent/tests/test_price_limit_lookahead.py@@ -0,0 +1,153 @@+"""Price-limit bands must be judged at execution time, not from the bar's close.++``BaseEngine`` calls ``can_execute`` before filling at the CURRENT bar's open,+so a limit check derived from that bar's close is lookahead. It was wrong in+both directions: a name that opened locked but drifted back by the close was+allowed to trade at the locked open (an optimistic fill that could not have+happened), and a name that opened freely but closed at the limit was refused a+fill it would have got.++Every engine with a daily band is covered here: A-share, India equity, China+futures and global futures.+"""++from __future__ import annotations++import pandas as pd+import pytest++from backtest.engines.china_a import ChinaAEngine+from backtest.engines.china_futures import ChinaFuturesEngine+from backtest.engines.global_futures import GlobalFuturesEngine+from backtest.engines.india_equity import IndiaEquityEngine+from backtest.models import Position++_BASE = 100.0+++def _equity_cases():+ """(engine, symbol, band) for the two cash-equity engines."""+ return [+ (ChinaAEngine({}), "000001.SZ", 0.10),+ (IndiaEquityEngine({}), "RELIANCE.NS", 0.20),+ ]+++def _futures_cases():+ """(engine, symbol, band) for the two futures engines."""+ return [+ (ChinaFuturesEngine({}), "IF2406.CFFEX", 0.10),+ (GlobalFuturesEngine({}), "ESZ4", 0.07),+ ]+++def _bar(open_: float, close: float, base_field: str = "pre_close") -> pd.Series:+ return pd.Series({"open": open_, "high": max(open_, close), "low": min(open_, close),+ "close": close, base_field: _BASE})+++# --------------------------------------------------------------------------- #+# The optimistic failure: opened locked, drifted back by the close+# --------------------------------------------------------------------------- #++[email protected]("engine, symbol, band", _equity_cases())+def test_equity_open_locked_at_upper_band_refuses_the_buy(engine, symbol, band) -> None:+ """Opening AT the upper band means no buy, whatever the close later did."""+ bar = _bar(open_=_BASE * (1 + band), close=_BASE * 1.01)+ assert engine.can_execute(symbol, 1, bar) is False++[email protected]("engine, symbol, band", _futures_cases())+def test_futures_open_locked_at_upper_band_refuses_the_long(engine, symbol, band) -> None:+ bar = _bar(open_=_BASE * (1 + band), close=_BASE * 1.01, base_field="pre_settle")+ assert engine.can_execute(symbol, 1, bar) is False+++# --------------------------------------------------------------------------- #+# The pessimistic failure: opened freely, closed at the band+# --------------------------------------------------------------------------- #++[email protected]("engine, symbol, band", _equity_cases())+def test_equity_open_inside_band_allows_the_buy_even_if_close_locks(engine, symbol, band) -> None:+ """A close at the limit says nothing about whether the open was tradeable."""+ bar = _bar(open_=_BASE * 1.005, close=_BASE * (1 + band))+ assert engine.can_execute(symbol, 1, bar) is True++[email protected]("engine, symbol, band", _futures_cases())+def test_futures_open_inside_band_allows_the_long_even_if_close_locks(engine, symbol, band) -> None:+ bar = _bar(open_=_BASE * 1.005, close=_BASE * (1 + band), base_field="pre_settle")+ assert engine.can_execute(symbol, 1, bar) is True+++# --------------------------------------------------------------------------- #+# Lower band, and futures close-side direction handling+# --------------------------------------------------------------------------- #++[email protected]("engine, symbol, band", _equity_cases())+def test_equity_open_locked_at_lower_band_refuses_the_sell(engine, symbol, band) -> None:+ bar = _bar(open_=_BASE * (1 - band), close=_BASE * 0.99)+ assert engine.can_execute(symbol, 0, bar) is False+++def test_futures_closing_a_long_is_blocked_at_the_lower_band() -> None:+ """Closing a long is a sell, so the LOWER band blocks it."""+ engine = ChinaFuturesEngine({})+ engine.positions["IF2406.CFFEX"] = Position(+ "IF2406.CFFEX", 1, _BASE, pd.Timestamp("2025-06-09"), 1.0,+ )+ bar = _bar(open_=_BASE * 0.90, close=_BASE * 0.99, base_field="pre_settle")+ assert engine.can_execute("IF2406.CFFEX", 0, bar) is False+++def test_futures_closing_a_short_is_blocked_at_the_upper_band() -> None:+ """Closing a short is a buy, so the UPPER band blocks it."""+ engine = ChinaFuturesEngine({})+ engine.positions["IF2406.CFFEX"] = Position(+ "IF2406.CFFEX", -1, _BASE, pd.Timestamp("2025-06-09"), 1.0,+ )+ bar = _bar(open_=_BASE * 1.10, close=_BASE * 1.01, base_field="pre_settle")+ assert engine.can_execute("IF2406.CFFEX", 0, bar) is False+++# --------------------------------------------------------------------------- #+# Base-price resolution+# --------------------------------------------------------------------------- #+++def test_no_reachable_base_price_never_fabricates_a_block() -> None:+ """First bar of a run, or a composite sub-engine: allow rather than invent."""+ engine = ChinaAEngine({})+ bar = pd.Series({"open": 200.0, "close": 100.0}) # no pre_close, no panel+ assert engine.can_execute("000001.SZ", 1, bar) is True+++def test_prior_close_panel_supplies_the_base_price() -> None:+ """With no pre_close on the bar, the run's own close panel is used."""+ engine = ChinaAEngine({})+ engine._close_arr = pd.DataFrame({"a": [_BASE, 0.0]}).values+ engine._code_to_col = {"000001.SZ": 0}+ engine._bar_idx = 1+ bar = pd.Series({"open": _BASE * 1.10, "close": _BASE * 1.01})+ assert engine.can_execute("000001.SZ", 1, bar) is False+++def test_tushare_pct_chg_reconstructs_the_prior_close() -> None:+ """pct_chg + close yields the PREVIOUS close, which is historical."""+ engine = ChinaAEngine({})+ # close 15.0 with pct_chg +10pp implies a prior close of 13.636..., so the+ # upper band is exactly 15.0 and an open there is locked.+ bar = pd.Series({"open": 15.0, "close": 15.0, "pct_chg": 10.0})+ assert engine.can_execute("000001.SZ", 1, bar) is False+++def test_futures_prefer_pre_settle_over_pre_close() -> None:+ """Exchanges set futures bands off the previous settlement."""+ engine = ChinaFuturesEngine({})+ # pre_settle 100 puts the +10% band at 110; pre_close 120 would put it at+ # 132 and would wrongly allow this open.+ bar = pd.Series({"open": 110.0, "close": 101.0, "pre_settle": 100.0, "pre_close": 120.0})+ assert engine.can_execute("IF2406.CFFEX", 1, bar) is False