Add IBKR benchmark history runtime helpers

Author: Pigbibi

src/quant_platform_kit/ibkr/__init__.py

@@ -1,21 +1,28 @@
 from .connection import connect_ib, ensure_event_loop
 from .execution import submit_order_intent
-from .market_data import fetch_historical_price_series, fetch_quote_snapshots
+from .market_data import (
+    fetch_historical_price_candles,
+    fetch_historical_price_series,
+    fetch_quote_snapshots,
+)
 from .portfolio import fetch_portfolio_snapshot
 from .runtime_inputs import (
+    build_benchmark_history_inputs,
     build_ibkr_strategy_context,
     build_market_history_inputs,
     build_semiconductor_rotation_indicators,
     build_semiconductor_rotation_inputs,
 )
 
 __all__ = [
+    "build_benchmark_history_inputs",
     "build_ibkr_strategy_context",
     "build_market_history_inputs",
     "build_semiconductor_rotation_indicators",
     "build_semiconductor_rotation_inputs",
     "connect_ib",
     "ensure_event_loop",
+    "fetch_historical_price_candles",
     "submit_order_intent",
     "fetch_historical_price_series",
     "fetch_quote_snapshots",

src/quant_platform_kit/ibkr/market_data.py

@@ -65,6 +65,45 @@ def fetch_historical_price_series(
     return PriceSeries(symbol=symbol, currency=currency, points=points)
 
 
+def fetch_historical_price_candles(
+    ib: Any,
+    symbol: str,
+    *,
+    duration: str = "2 Y",
+    bar_size: str = "1 day",
+    exchange: str = "SMART",
+    currency: str = "USD",
+    stock_factory: Callable[..., Any] | None = None,
+) -> list[dict[str, Any]]:
+    contract = _build_stock_contract(
+        symbol,
+        exchange=exchange,
+        currency=currency,
+        stock_factory=stock_factory,
+    )
+    ib.qualifyContracts(contract)
+    bars = ib.reqHistoricalData(
+        contract,
+        endDateTime="",
+        durationStr=duration,
+        barSizeSetting=bar_size,
+        whatToShow="ADJUSTED_LAST",
+        useRTH=True,
+        formatDate=1,
+    )
+    return [
+        {
+            "as_of": _coerce_as_of(bar.date),
+            "open": float(getattr(bar, "open", bar.close)),
+            "high": float(getattr(bar, "high", bar.close)),
+            "low": float(getattr(bar, "low", bar.close)),
+            "close": float(bar.close),
+            "volume": float(getattr(bar, "volume", 0.0) or 0.0),
+        }
+        for bar in bars or ()
+    ]
+
+
 def _coerce_positive_price(value: Any) -> float | None:
     if value is None:
         return None

src/quant_platform_kit/ibkr/runtime_inputs.py

@@ -19,6 +19,24 @@ def build_market_history_inputs(
     return {"market_history": historical_close_loader}
 
 
+def build_benchmark_history_inputs(
+    ib: Any,
+    historical_candle_loader: Callable[..., Any],
+    *,
+    benchmark_symbol: str,
+    duration: str = "2 Y",
+    bar_size: str = "1 day",
+) -> dict[str, Any]:
+    return {
+        "benchmark_history": historical_candle_loader(
+            ib,
+            benchmark_symbol,
+            duration=duration,
+            bar_size=bar_size,
+        )
+    }
+
+
 def build_ibkr_strategy_context(
     *,
     entrypoint: StrategyEntrypoint,

tests/test_ibkr_market_data.py

@@ -4,7 +4,11 @@
 from datetime import date
 import unittest
 
-from quant_platform_kit.ibkr.market_data import fetch_historical_price_series, fetch_quote_snapshots
+from quant_platform_kit.ibkr.market_data import (
+    fetch_historical_price_candles,
+    fetch_historical_price_series,
+    fetch_quote_snapshots,
+)
 
 
 @dataclass
@@ -18,6 +22,10 @@ class FakeContract:
 class FakeBar:
     date: date
     close: float
+    open: float = 0.0
+    high: float = 0.0
+    low: float = 0.0
+    volume: float = 0.0
 
 
 class FakeTicker:
@@ -52,8 +60,8 @@ def reqHistoricalData(self, contract, **kwargs):
         self.last_history_contract = contract
         self.last_history_kwargs = kwargs
         return [
-            FakeBar(date=date(2026, 3, 27), close=100.5),
-            FakeBar(date=date(2026, 3, 28), close=101.0),
+            FakeBar(date=date(2026, 3, 27), open=100.0, high=101.0, low=99.5, close=100.5, volume=1000.0),
+            FakeBar(date=date(2026, 3, 28), open=100.5, high=101.5, low=100.0, close=101.0, volume=1200.0),
         ]
 
     def reqMktData(self, contract, *_args):
@@ -78,6 +86,20 @@ def test_fetch_historical_price_series_builds_price_points(self) -> None:
         self.assertEqual(ib.last_history_contract.symbol, "SPY")
         self.assertEqual(ib.last_history_kwargs["durationStr"], "2 Y")
 
+    def test_fetch_historical_price_candles_exposes_ohlc_fields(self) -> None:
+        ib = FakeIB()
+        candles = fetch_historical_price_candles(
+            ib,
+            "QQQ",
+            stock_factory=FakeContract,
+        )
+
+        self.assertEqual(candles[-1]["close"], 101.0)
+        self.assertEqual(candles[-1]["open"], 100.5)
+        self.assertEqual(candles[-1]["high"], 101.5)
+        self.assertEqual(candles[-1]["low"], 100.0)
+        self.assertEqual(candles[-1]["volume"], 1200.0)
+
     def test_fetch_quote_snapshots_returns_last_price(self) -> None:
         ib = FakeIB()
         snapshots = fetch_quote_snapshots(

tests/test_ibkr_runtime_inputs.py

@@ -4,6 +4,7 @@
 
 from quant_platform_kit.strategy_contracts import StrategyManifest, StrategyRuntimeAdapter
 from quant_platform_kit.ibkr.runtime_inputs import (
+    build_benchmark_history_inputs,
     build_ibkr_strategy_context,
     build_market_history_inputs,
     build_semiconductor_rotation_indicators,
@@ -21,6 +22,22 @@ def loader(*_args, **_kwargs):
         self.assertEqual(set(payload), {"market_history"})
         self.assertIs(payload["market_history"], loader)
 
+    def test_build_benchmark_history_inputs_loads_candles_for_symbol(self) -> None:
+        observed = {}
+
+        def loader(_ib, symbol, duration="2 Y", bar_size="1 day"):
+            observed["call"] = (symbol, duration, bar_size)
+            return [{"close": 1.0, "high": 1.1, "low": 0.9}]
+
+        payload = build_benchmark_history_inputs(
+            "fake-ib",
+            loader,
+            benchmark_symbol="QQQ",
+        )
+
+        self.assertEqual(observed["call"], ("QQQ", "2 Y", "1 day"))
+        self.assertEqual(payload["benchmark_history"][0]["close"], 1.0)
+
     def test_build_ibkr_strategy_context_uses_required_inputs_and_portfolio(self) -> None:
         entrypoint = type(
             "Entrypoint",