lumibot 4.2.5__py3-none-any.whl → 4.2.9__py3-none-any.whl

{lumibot-4.2.5.dist-info → lumibot-4.2.9.dist-info}/RECORD

@@ -7,14 +7,14 @@ lumibot/backtesting/alpha_vantage_backtesting.py,sha256=LR3UNhJrdAKdvadiThVKdKrM
 lumibot/backtesting/backtesting_broker.py,sha256=C0zn__i0aoyd6u147oizRYO2Akqa5JWs8znl6siLd8Y,76003
 lumibot/backtesting/ccxt_backtesting.py,sha256=O-RjuNpx5y4f-hKKwwUbrU7hAVkGEegmnvH_9nQWhAo,246
 lumibot/backtesting/databento_backtesting.py,sha256=zQS6IaamDTQREcjViguk_y4b_HF1xyV3gUrDuHnkUUY,430
-lumibot/backtesting/databento_backtesting_pandas.py,sha256=kK6XXmm9veZSt-z1HBKdEzM_LkrVt2-DVfajtkTDdCI,31229
+lumibot/backtesting/databento_backtesting_pandas.py,sha256=xIQ1SnPo47rxIH7hfrgWzhTuVxxG8LDklY3Z8Tu5idU,32440
 lumibot/backtesting/databento_backtesting_polars.py,sha256=qanSLBsw4aBEFVfMuwSWzTDtaXQlOfcrvp6ERLWkRVo,45786
 lumibot/backtesting/fix_debug.py,sha256=ETHl-O38xK9JOQC2x8IZVJRCQrR1cokk2Vb4vpGMvb8,1204
 lumibot/backtesting/interactive_brokers_rest_backtesting.py,sha256=5HJ_sPX0uOUg-rbfOKDjwYVCLiXevlwtdK_3BcUwqXc,6602
 lumibot/backtesting/pandas_backtesting.py,sha256=m-NvT4o-wFQjaZft6TXULzeZBrskO_7Z-jfy9AIkyAY,388
 lumibot/backtesting/polygon_backtesting.py,sha256=u9kif_2_7k0P4-KDvbHhaMfSoBVejUUX7fh9H3PCVE0,12350
 lumibot/backtesting/thetadata_backtesting.py,sha256=Xcz5f-4zTkKgWWcktNzItH2vrr8CysIMQWKKqLwugbA,345
-lumibot/backtesting/thetadata_backtesting_pandas.py,sha256=3ltwnxqAw4xXG2VOk14G_vpVHAVdnGl10SsveoMoJF0,51844
+lumibot/backtesting/thetadata_backtesting_pandas.py,sha256=4jIxziBASbmCe5MCmjmvQBeo-5EQ90UTmblRpHrAaDE,51829
 lumibot/backtesting/yahoo_backtesting.py,sha256=LT2524mGlrUSq1YSRnUqGW4-Xcq4USgRv2EhnV_zfs4,502
 lumibot/brokers/__init__.py,sha256=MGWKHeH3mqseYRL7u-KX1Jp2x9EaFO4Ol8sfNSxzu1M,404
 lumibot/brokers/alpaca.py,sha256=VQ17idfqiEFb2JCqqdMGmbvF789L7_PpsCbudiFRzmg,61595
@@ -34,7 +34,7 @@ lumibot/components/configs_helper.py,sha256=e4-2jBmjsIDeMQ9fbQ9j2U6WlHCe2z9bIQtJ
 lumibot/components/drift_rebalancer_logic.py,sha256=KL1S9Su5gxibGzl2fw_DH8StzXvjFfFl23sOFGHgIZI,28653
 lumibot/components/grok_helper.py,sha256=vgyPAs63VoNsfZojMoHYRLckb-CFiZkHIlY8HSYZLQs,15382
 lumibot/components/grok_news_helper.py,sha256=7GFtSuRkBo4-3IcUmC6qhuf7iekoVyyP7q5jyUjAWTc,11007
-lumibot/components/options_helper.py,sha256=pUihHFEv5w17pXACE3xw0Tq6tHb9s05fzttlg4hmD7E,64931
+lumibot/components/options_helper.py,sha256=UTMJUrTX9AOq-SPkZR7IFOFc65JQRZDSSrzy6a7ptZY,67371
 lumibot/components/perplexity_helper.py,sha256=0dhAIXunvUnTKIFFdYbFt8adnSIavKRqXkQ91fjsDPI,31432
 lumibot/components/quiver_helper.py,sha256=s0Y-tL1y2S1mYlbtlRTcL5R4WV0HYOgiSJ9hT41Hzrw,14380
 lumibot/components/vix_helper.py,sha256=tsWHFQzOJCjdmSGgmnYIty0K5ua-iAgBiRlyRIpGli0,61940
@@ -104,7 +104,7 @@ lumibot/example_strategies/test_broker_functions.py,sha256=wnVS-M_OtzMgaXVBgshVE
 lumibot/resources/ThetaTerminal.jar,sha256=K6GeeFcN8-gvyL2x5iq5pzD79KfPJvMK8iiezi3TmNQ,11834389
 lumibot/resources/conf.yaml,sha256=rjB9-10JP7saZ_edjX5bQDGfuc3amOQTUUUr-UiMpNA,597
 lumibot/strategies/__init__.py,sha256=jEZ95K5hG0f595EXYKWwL2_UsnWWk5Pug361PK2My2E,79
-lumibot/strategies/_strategy.py,sha256=wWx2te98kwMTuusioKR24KsKW8Djs3yhOb2nNmvgbiU,111467
+lumibot/strategies/_strategy.py,sha256=3Z2MPz3jYgJdAphaFyoEI5OUs_6ClAJgRCrLWy-b2sg,111718
 lumibot/strategies/session_manager.py,sha256=Nze6UYNSPlCsf-tyHvtFqUeL44WSNHjwsKrIepvsyCY,12956
 lumibot/strategies/strategy.py,sha256=toPeL5oIVWmCxBNcfXqIuTCF_EeCfIVj425PrSYImCo,170021
 lumibot/strategies/strategy_executor.py,sha256=AnmXlKD2eMgKXs3TrD1u8T_Zsn_8GnG5KRcM_Pq-JBQ,70749
@@ -113,8 +113,8 @@ lumibot/tools/alpaca_helpers.py,sha256=nhBS-sv28lZfIQ85szC9El8VHLrCw5a5KbsGOOEjm
 lumibot/tools/backtest_cache.py,sha256=A-Juzu0swZI_FP4U7cd7ruYTgJYgV8BPf_WJDI-NtrM,9556
 lumibot/tools/bitunix_helpers.py,sha256=-UzrN3w_Y-Ckvhl7ZBoAcx7sgb6tH0KcpVph1Ovm3gw,25780
 lumibot/tools/black_scholes.py,sha256=TBjJuDTudvqsbwqSb7-zb4gXsJBCStQFaym8xvePAjw,25428
-lumibot/tools/ccxt_data_store.py,sha256=VXLSs0sWcwjRPZzbuEeVPS-3V6D10YnYMfIyoTPTG0U,21225
-lumibot/tools/databento_helper.py,sha256=6jCIh1GlEpdU_copJSNTYmvcIKMXCucaAONwmqQjxCE,43466
+lumibot/tools/ccxt_data_store.py,sha256=PlP3MHPHZP7GisEZsk1OUxeWijoPXwiQbsOBTr7jkQI,21227
+lumibot/tools/databento_helper.py,sha256=WBuQCm9Z7WFpde8qdsJEabtpU0ThGsjjPeK7BI2pUVA,43681
 lumibot/tools/databento_helper_polars.py,sha256=FXvvES_Y-E-IzAmVBtquh1UtQ-eN6i6BEoflcP7y8s0,48674
 lumibot/tools/databento_roll.py,sha256=48HAw3h6OngCK4UTl9ifpjo-ki8qmB6OoJUrHp0gRmE,6767
 lumibot/tools/debugers.py,sha256=ga6npFsS9cpKtTXaygh9t2_txCElg3bfzfeqDBvSL8k,485
@@ -132,7 +132,7 @@ lumibot/tools/polygon_helper_async.py,sha256=YHDXa9kmkkn8jh7hToY6GP5etyXS9Tj-uky
 lumibot/tools/polygon_helper_polars_optimized.py,sha256=NaIZ-5Av-G2McPEKHyJ-x65W72W_Agnz4lRgvXfQp8c,30415
 lumibot/tools/projectx_helpers.py,sha256=EIemLfbG923T_RBV_i6s6A9xgs7dt0et0oCnhFwdWfA,58299
 lumibot/tools/schwab_helper.py,sha256=CXnYhgsXOIb5MgmIYOp86aLxsBF9oeVrMGrjwl_GEv0,11768
-lumibot/tools/thetadata_helper.py,sha256=Guutp_2QAZe22_r6pftCojpTb3DpDp4Ul_szf6N7X1I,80152
+lumibot/tools/thetadata_helper.py,sha256=F5CdaWZkfJYFrParvN8KhowRWc5cRmPL4TnI9SH-VpI,90111
 lumibot/tools/types.py,sha256=x-aQBeC6ZTN2-pUyxyo69Q0j5e0c_swdfe06kfrWSVc,1978
 lumibot/tools/yahoo_helper.py,sha256=htcKKkuktatIckVKfLc_ms0X75mXColysQhrZW244z8,19497
 lumibot/tools/yahoo_helper_polars_optimized.py,sha256=g9xBN-ReHSW4Aj9EMU_OncBXVS1HpfL8LTHit9ZxFY4,7417
@@ -142,7 +142,7 @@ lumibot/traders/trader.py,sha256=KMif3WoZtnSxA0BzoK3kvkTITNELrDFIortx1BYBv8s,967
 lumibot/trading_builtins/__init__.py,sha256=vH2QL5zLjL3slfEV1YW-BvQHtEYLCFkIWTZDfh3y8LE,87
 lumibot/trading_builtins/custom_stream.py,sha256=8_XiPT0JzyXrgnXCXoovGGUrWEfnG4ohIYMPfB_Nook,5264
 lumibot/trading_builtins/safe_list.py,sha256=IIjZOHSiZYK25A4WBts0oJaZNOJDsjZL65MOSHhE3Ig,1975
-lumibot-4.2.5.dist-info/licenses/LICENSE,sha256=fYhGIyxjyNXACgpNQS3xxpxDOaVOWRVxZMCRbsDv8k0,35130
+lumibot-4.2.9.dist-info/licenses/LICENSE,sha256=fYhGIyxjyNXACgpNQS3xxpxDOaVOWRVxZMCRbsDv8k0,35130
 tests/__init__.py,sha256=3-VoT-nAuqMfwufd4ceN6fXaHl_zCfDCSXJOTp1ywYQ,393
 tests/conftest.py,sha256=UBw_2fx7r6TZPKus2b1Qxrzmd4bg8EEBnX1vCHUuSVA,3311
 tests/fixtures.py,sha256=wOHQsh1SGHnXe_PGi6kDWI30CS_Righi7Ig7vwSEKT4,9082
@@ -208,7 +208,7 @@ tests/test_lumibot_logger.py,sha256=76e5yl86NWk4OYtM_be-7yaHnPA-1bO2rBNH-piX8Dk,
 tests/test_market_infinite_loop_bug.py,sha256=p8Wiq2sdNFYOH54Ij9MkDFWBLTC8V3vbJEphcPq6T8g,16181
 tests/test_mes_symbols.py,sha256=Av5AM-pogp1STfWZ4A3bA2NmbaA3E9b0Dg449mfk-Ss,3106
 tests/test_momentum.py,sha256=oakKjgnz5pNQkw0CagbbKKSux0HkOxP_iLW8-Yk0XOo,8492
-tests/test_options_helper.py,sha256=NizH8E9ZnzVWsShsHp5X6qBE8FWJ3sS2eE9bCko7y9U,27352
+tests/test_options_helper.py,sha256=wVXafXP4KfL3T-u9dFjJZbGI9YOHApohW-NfQ36yTuk,29185
 tests/test_options_helper_enhancements.py,sha256=3Ei-vy9IQfg1AnlBqofLNc-kuiQ64vouhJyIuVj3KIg,7324
 tests/test_order.py,sha256=qN_sqsItl8L-WqSQTF0PUN0s2nxm4HKYOA6gYQ6EBJA,12110
 tests/test_order_serialization.py,sha256=zcX5fgcYeo0jm6dlIQnUfuH56svTnKRFPtYCSI7xCJw,3710
@@ -226,7 +226,7 @@ tests/test_projectx_helpers.py,sha256=mKFcWZ7C2ve6UXk2LaJWo1E6QwhU09dkIYht1LElQW
 tests/test_projectx_lifecycle.py,sha256=F7H08wg2b5lYh0vNzKNa5AkQnhCuTrbpPm0YvOZHN6A,3179
 tests/test_projectx_lifecycle_unit.py,sha256=XqktdtFMS4s5RIF2ay9uZNW9Ij1AQL46OUbgStA9rhA,21926
 tests/test_projectx_live_flow.py,sha256=vKnb_VDKCOAbmOdQ5TlyQroCNtNE8UFjHKcd-YpIjXg,412
-tests/test_projectx_timestep_alias.py,sha256=vMf80illnTrwgl09wzGQ99CiTAVgIt2jSfHZELxxEEA,2042
+tests/test_projectx_timestep_alias.py,sha256=Kcq-q9-pB9h9mBSol_qb_VCztVdLItY8xClroGNf3zo,2043
 tests/test_projectx_url_mappings.py,sha256=1E0xZe_cZtGiU-fPIfohbvsrrPjawkblR8F2Mvu_Ct8,10039
 tests/test_quiet_logs_buy_and_hold.py,sha256=GjXGeHBcNrRJoHGWLuc_LkrzcpNVzshiiBkQACczIxI,2681
 tests/test_quiet_logs_comprehensive.py,sha256=QVkZWLAUnPEb04Ec8qKXvLzdDUkp8alez2mU_Y1Umm0,6068
@@ -234,8 +234,9 @@ tests/test_quiet_logs_functionality.py,sha256=MlOBUICuTy1OXCDifOW05uD7hjnZRsQ2xx
 tests/test_quiet_logs_requirements.py,sha256=YoUooSVLrFL8TlWPfxEiqxvSj4d8z6-qg58ja4dtOc0,7856
 tests/test_session_manager.py,sha256=1qygN3aQ2Xe2uh4BMPm0E3V8KXLFNGq5qdL8KkZjef4,11632
 tests/test_strategy_methods.py,sha256=j9Mhr6nnG1fkiVQXnx7gLjzGbeQmwt0UbJr_4plD36o,12539
+tests/test_strategy_price_guard.py,sha256=3GJdlfROwx6-adsSi8ZBrWaLOy9e-0N6V1eqpikj8e4,1540
 tests/test_thetadata_backwards_compat.py,sha256=RzNLhNZNJZ2hPkEDyG-T_4mRRXh5XqavK6r-OjfRASQ,3306
-tests/test_thetadata_helper.py,sha256=l77ksu70knZBudfrMAOwT9zJ91AxX5UgazqvYSrotqM,59346
+tests/test_thetadata_helper.py,sha256=4EdFHoCTTKELU216ZNYGjfo6Uvq-29kK-TVpFLPWT3M,67263
 tests/test_thetadata_pandas_verification.py,sha256=MWUecqBY6FGFslWLRo_C5blGbom_unmXCZikAfZXLks,6553
 tests/test_tradier.py,sha256=iCEM2FTxJSzJ2oLNaRqSx05XaX_DCiMzLx1aEYPANko,33280
 tests/test_tradier_data.py,sha256=1jTxDzQtzaC42CQJVXMRMElBwExy1mVci3NFfKjjVH0,13363
@@ -281,7 +282,7 @@ tests/backtest/test_thetadata.py,sha256=xWYfC9C4EhbMDb29qyZWHO3sSWaLIPzzvcMbHCt5
 tests/backtest/test_thetadata_comprehensive.py,sha256=-gN3xLJcJtlB-k4vlaK82DCZDGDmr0LNZZDzn-aN3l4,26120
 tests/backtest/test_thetadata_vs_polygon.py,sha256=dZqsrOx3u3cz-1onIO6o5BDRjI1ey7U9vIkZupfXoig,22831
 tests/backtest/test_yahoo.py,sha256=2FguUTUMC9_A20eqxnZ17rN3tT9n6hyvJHaL98QKpqY,3443
-lumibot-4.2.5.dist-info/METADATA,sha256=lK1f_O0TcWv79IUVPehgpO2s_dQE1jrsj69_LCqeKM8,12092
-lumibot-4.2.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lumibot-4.2.5.dist-info/top_level.txt,sha256=otUnUjDFVASauEDiTiAzNgMyqQ1B6jjS3QqqP-WSx38,14
-lumibot-4.2.5.dist-info/RECORD,,
+lumibot-4.2.9.dist-info/METADATA,sha256=Bis7WU6RY3Wp7YXHsNa7-xklQzQcXRi5zcJzZhC2j0w,12093
+lumibot-4.2.9.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lumibot-4.2.9.dist-info/top_level.txt,sha256=otUnUjDFVASauEDiTiAzNgMyqQ1B6jjS3QqqP-WSx38,14
+lumibot-4.2.9.dist-info/RECORD,,

tests/test_options_helper.py

@@ -11,7 +11,7 @@ import pytest
 # Add the lumibot path
 sys.path.insert(0, '/Users/robertgrzesik/Documents/Development/lumivest_bot_server/strategies/lumibot')
 
-from lumibot.components.options_helper import OptionsHelper
+from lumibot.components.options_helper import OptionsHelper, OptionMarketEvaluation
 from lumibot.entities import Asset
 from lumibot.entities.chains import OptionsDataFormatError, normalize_option_chains
 from lumibot.brokers.broker import Broker
@@ -311,7 +311,7 @@ class TestOptionsHelper(unittest.TestCase):
         result = self.options_helper.get_expiration_on_or_after_date(target, expiries, "call")
         self.assertEqual(result, _date(2024, 1, 9))
 
-    def test_get_expiration_on_or_after_date_uses_latest_when_needed(self):
+    def test_get_expiration_on_or_after_date_returns_none_when_no_future_available(self):
         from datetime import date as _date
 
         expiries = {
@@ -325,7 +325,7 @@ class TestOptionsHelper(unittest.TestCase):
 
         target = _date(2024, 2, 1)
         result = self.options_helper.get_expiration_on_or_after_date(target, expiries, "call")
-        self.assertEqual(result, _date(2024, 1, 9))
+        self.assertIsNone(result)
 
     def test_chains_backward_compatibility_string_access(self):
         """Test that existing code using string keys still works."""
@@ -676,6 +676,48 @@ class TestOptionsHelper(unittest.TestCase):
         self.assertIsNone(evaluation.sell_price)
         self.assertFalse(evaluation.used_last_price_fallback)
 
+    def test_evaluate_option_market_rejects_non_finite_quotes(self):
+        """NaN or infinite quotes are treated as missing to prevent crashes."""
+        option_asset = Asset(
+            "TEST",
+            asset_type=Asset.AssetType.OPTION,
+            expiration=date.today() + timedelta(days=7),
+            strike=200,
+            right="call",
+            underlying_asset=Asset("TEST", asset_type=Asset.AssetType.STOCK),
+        )
+
+        self.mock_strategy.get_quote.return_value = Mock(bid=float("nan"), ask=float("inf"))
+        self.mock_strategy.get_last_price.return_value = float("nan")
+        self.mock_strategy.broker.data_source.option_quote_fallback_allowed = True
+
+        evaluation = self.options_helper.evaluate_option_market(option_asset, max_spread_pct=0.25)
+
+        self.assertIsNone(evaluation.buy_price)
+        self.assertIn("bid_non_finite", evaluation.data_quality_flags)
+        self.assertIn("ask_non_finite", evaluation.data_quality_flags)
+        self.assertTrue(evaluation.missing_bid_ask)
+        self.assertFalse(OptionsHelper.has_actionable_price(evaluation))
+
+    def test_has_actionable_price_requires_positive_finite_value(self):
+        """has_actionable_price returns False for zero or negative values."""
+        evaluation = OptionMarketEvaluation(
+            bid=0.5,
+            ask=0.6,
+            last_price=0.55,
+            spread_pct=0.18,
+            has_bid_ask=True,
+            spread_too_wide=False,
+            missing_bid_ask=False,
+            missing_last_price=False,
+            buy_price=0.0,
+            sell_price=0.4,
+            used_last_price_fallback=False,
+            max_spread_pct=0.25,
+            data_quality_flags=["buy_price_non_positive"],
+        )
+        self.assertFalse(OptionsHelper.has_actionable_price(evaluation))
+
 if __name__ == "__main__":
     print("🧪 Running enhanced options helper tests...")
     unittest.main(verbosity=2)

tests/test_projectx_timestep_alias.py

@@ -9,7 +9,7 @@ from lumibot.data_sources.projectx_data import ProjectXData
 class DummyClient:
     def history_retrieve_bars(self, contract_id, start_datetime, end_datetime, unit, unit_number, limit, include_partial_bar, live, is_est):
         # Return a minimal DataFrame resembling expected structure
-        idx = pd.date_range(end=end_datetime, periods=unit_number, freq='T')
+        idx = pd.date_range(end=end_datetime, periods=unit_number, freq='min')
         data = {
             'open': [1.0]*len(idx),
             'high': [1.1]*len(idx),
@@ -51,4 +51,3 @@ def test_projectx_get_bars_accepts_timestep_alias(projectx):
     bars_map2 = projectx.get_bars(asset, 1, timestep='minute')
     bars2 = list(bars_map2.values())[0]
     assert bars2 is not None and not bars2.df.empty
-

tests/test_strategy_price_guard.py

@@ -0,0 +1,50 @@
+import math
+from lumibot.components.options_helper import OptionsHelper, OptionMarketEvaluation
+
+
+class _GuardedStrategy:
+    def __init__(self):
+        self.logged = []
+        self.options_helper = OptionsHelper(self)
+
+    def log_message(self, message, color="white"):
+        self.logged.append((color, message))
+
+    def get_cash(self):
+        return 10_000.0
+
+    def size_position(self, evaluation: OptionMarketEvaluation):
+        if evaluation.spread_too_wide or not self.options_helper.has_actionable_price(evaluation):
+            self.log_message(
+                f"Skipping trade due to invalid quotes (flags={evaluation.data_quality_flags}).",
+                color="yellow",
+            )
+            return 0
+
+        buy_price = float(evaluation.buy_price)
+        budget = self.get_cash() * 0.1
+        return math.floor(budget / (buy_price * 100.0))
+
+
+def test_strategy_guard_skips_non_finite_prices():
+    strategy = _GuardedStrategy()
+    evaluation = OptionMarketEvaluation(
+        bid=None,
+        ask=None,
+        last_price=None,
+        spread_pct=None,
+        has_bid_ask=False,
+        spread_too_wide=False,
+        missing_bid_ask=True,
+        missing_last_price=True,
+        buy_price=float("nan"),
+        sell_price=None,
+        used_last_price_fallback=False,
+        max_spread_pct=None,
+        data_quality_flags=["buy_price_non_finite"],
+    )
+
+    contracts = strategy.size_position(evaluation)
+
+    assert contracts == 0
+    assert any("invalid quotes" in msg for _, msg in strategy.logged)

tests/test_thetadata_helper.py

@@ -138,7 +138,11 @@ def test_get_price_data_partial_cache_hit(mock_build_cache_filename, mock_load_c
     assert df is not None
     assert len(df) == 10  # Combined cached and fetched data
     mock_get_historical_data.assert_called_once()
-    pd.testing.assert_frame_equal(df, updated_data.drop(columns="missing"))
+    pd.testing.assert_frame_equal(
+        df,
+        updated_data.drop(columns="missing"),
+        check_dtype=False,
+    )
     mock_update_cache.assert_called_once()
 
 
@@ -452,7 +456,7 @@ def test_get_price_data_invokes_remote_cache_manager(tmp_path, monkeypatch):
 
     df = pd.DataFrame(
         {
-            "datetime": pd.date_range("2024-01-01 09:30:00", periods=2, freq="T", tz=pytz.UTC),
+            "datetime": pd.date_range("2024-01-01 09:30:00", periods=2, freq="min", tz=pytz.UTC),
             "open": [100.0, 101.0],
             "high": [101.0, 102.0],
             "low": [99.5, 100.5],
@@ -1330,83 +1334,276 @@ class TestThetaDataProcessHealthCheck:
         assert thetadata_helper.is_process_alive() is True, "New process should be alive"
 
 
-@pytest.mark.apitest
 class TestThetaDataChainsCaching:
-    """Test option chain caching matches Polygon pattern - ZERO TOLERANCE."""
+    """Unit coverage for historical chain caching and normalization."""
+
+    def test_chains_cached_basic_structure(self, tmp_path, monkeypatch):
+        asset = Asset("TEST", asset_type="stock")
+        test_date = date(2024, 11, 7)
+
+        sample_chain = {
+            "Multiplier": 100,
+            "Exchange": "SMART",
+            "Chains": {
+                "CALL": {"2024-11-15": [100.0, 105.0]},
+                "PUT": {"2024-11-15": [90.0, 95.0]},
+            },
+        }
 
-    def test_chains_cached_basic_structure(self):
-        """Test chain caching returns correct structure."""
-        username = os.environ.get("THETADATA_USERNAME")
-        password = os.environ.get("THETADATA_PASSWORD")
+        calls = []
 
-        asset = Asset("SPY", asset_type="stock")
-        test_date = date(2025, 9, 15)
+        def fake_builder(**kwargs):
+            calls.append(kwargs)
+            return sample_chain
 
-        chains = thetadata_helper.get_chains_cached(username, password, asset, test_date)
+        monkeypatch.setattr(thetadata_helper, "build_historical_chain", fake_builder)
+        monkeypatch.setattr(thetadata_helper, "LUMIBOT_CACHE_FOLDER", str(tmp_path))
 
-        assert chains is not None, "Chains should not be None"
-        assert "Multiplier" in chains, "Missing Multiplier"
-        assert chains["Multiplier"] == 100, f"Multiplier should be 100, got {chains['Multiplier']}"
-        assert "Exchange" in chains, "Missing Exchange"
-        assert "Chains" in chains, "Missing Chains"
-        assert "CALL" in chains["Chains"], "Missing CALL chains"
-        assert "PUT" in chains["Chains"], "Missing PUT chains"
+        result = thetadata_helper.get_chains_cached("user", "pass", asset, test_date)
 
-        # Verify at least one expiration exists
-        assert len(chains["Chains"]["CALL"]) > 0, "Should have at least one CALL expiration"
-        assert len(chains["Chains"]["PUT"]) > 0, "Should have at least one PUT expiration"
+        assert result == sample_chain
+        assert len(calls) == 1
+        builder_call = calls[0]
+        assert builder_call["asset"] == asset
+        assert builder_call["as_of_date"] == test_date
 
-        print(f"✓ Chain structure valid: {len(chains['Chains']['CALL'])} expirations")
+    def test_chains_cache_reuse(self, tmp_path, monkeypatch):
+        asset = Asset("REUSE", asset_type="stock")
+        test_date = date(2024, 11, 8)
 
-    def test_chains_cache_reuse(self):
-        """Test that second call reuses cached data (no API call)."""
-        import time
-        from pathlib import Path
-        from lumibot.constants import LUMIBOT_CACHE_FOLDER
+        sample_chain = {
+            "Multiplier": 100,
+            "Exchange": "SMART",
+            "Chains": {"CALL": {"2024-11-22": [110.0]}, "PUT": {"2024-11-22": [95.0]}},
+        }
 
-        username = os.environ.get("THETADATA_USERNAME")
-        password = os.environ.get("THETADATA_PASSWORD")
+        call_count = {"total": 0}
 
-        asset = Asset("AAPL", asset_type="stock")
-        test_date = date(2025, 9, 15)
+        def fake_builder(**kwargs):
+            call_count["total"] += 1
+            return sample_chain
 
-        # CLEAR CACHE to ensure first call downloads fresh data
-        # This prevents cache pollution from previous tests in the suite
-        # Chains are stored in: LUMIBOT_CACHE_FOLDER / "thetadata" / "option" / "option_chains"
-        chain_folder = Path(LUMIBOT_CACHE_FOLDER) / "thetadata" / "option" / "option_chains"
-        if chain_folder.exists():
-            # Delete all AAPL chain cache files
-            for cache_file in chain_folder.glob("AAPL_*.parquet"):
-                try:
-                    cache_file.unlink()
-                except Exception:
-                    pass
-
-        # Restart ThetaData Terminal to ensure fresh connection after cache clearing
-        # This is necessary because cache clearing may interfere with active connections
-        thetadata_helper.start_theta_data_client(username, password)
-        time.sleep(3)  # Give Terminal time to fully connect
+        monkeypatch.setattr(thetadata_helper, "build_historical_chain", fake_builder)
+        monkeypatch.setattr(thetadata_helper, "LUMIBOT_CACHE_FOLDER", str(tmp_path))
+
+        first = thetadata_helper.get_chains_cached("user", "pass", asset, test_date)
+        second = thetadata_helper.get_chains_cached("user", "pass", asset, test_date)
+
+        assert first == sample_chain
+        assert second == sample_chain
+        assert call_count["total"] == 1, "Builder should only run once due to cache reuse"
+
+    def test_chain_cache_respects_recent_file(self, tmp_path, monkeypatch):
+        asset = Asset("RECENT", asset_type="stock")
+        test_date = date(2024, 11, 30)
+
+        sample_chain = {
+            "Multiplier": 100,
+            "Exchange": "SMART",
+            "Chains": {"CALL": {"2024-12-06": [120.0]}, "PUT": {"2024-12-06": [80.0]}},
+        }
+
+        monkeypatch.setattr(thetadata_helper, "LUMIBOT_CACHE_FOLDER", str(tmp_path))
+
+        cache_folder = Path(tmp_path) / "thetadata" / "stock" / "option_chains"
+        cache_folder.mkdir(parents=True, exist_ok=True)
+
+        cache_file = cache_folder / f"{asset.symbol}_{test_date.isoformat()}.parquet"
+        pd.DataFrame({"data": [sample_chain]}).to_parquet(cache_file, compression="snappy", engine="pyarrow")
+
+        # Builder should not be invoked because cache hit satisfies tolerance window
+        def fail_builder(**kwargs):
+            raise AssertionError("build_historical_chain should not be called when cache is fresh")
+
+        monkeypatch.setattr(thetadata_helper, "build_historical_chain", fail_builder)
+
+        result = thetadata_helper.get_chains_cached("user", "pass", asset, test_date)
+        assert result == sample_chain
+
+    def test_chains_cached_handles_none_builder(self, tmp_path, monkeypatch, caplog):
+        asset = Asset("NONE", asset_type="stock")
+        test_date = date(2024, 11, 28)
+
+        monkeypatch.setattr(thetadata_helper, "build_historical_chain", lambda **kwargs: None)
+        monkeypatch.setattr(thetadata_helper, "LUMIBOT_CACHE_FOLDER", str(tmp_path))
+        monkeypatch.delenv("BACKTESTING_QUIET_LOGS", raising=False)
+        caplog.set_level(logging.WARNING, logger="lumibot.tools.thetadata_helper")
+
+        with caplog.at_level(logging.WARNING, logger="lumibot.tools.thetadata_helper"):
+            result = thetadata_helper.get_chains_cached("user", "pass", asset, test_date)
+
+        cache_folder = Path(tmp_path) / "thetadata" / "stock" / "option_chains"
+        assert not cache_folder.exists() or not list(cache_folder.glob("*.parquet"))
+
+        assert result == {
+            "Multiplier": 100,
+            "Exchange": "SMART",
+            "Chains": {"CALL": {}, "PUT": {}},
+        }
+        assert "ThetaData returned no option data" in caplog.text
+
+
+def test_build_historical_chain_parses_quote_payload(monkeypatch):
+    asset = Asset("CVNA", asset_type="stock")
+    as_of_date = date(2024, 11, 7)
+    as_of_int = int(as_of_date.strftime("%Y%m%d"))
+
+    def fake_get_request(url, headers, querystring, username, password):
+        if url.endswith("/v2/list/expirations"):
+            return {
+                "header": {"format": ["date"]},
+                "response": [[20241115], [20241205], [20250124]],
+            }
+        if url.endswith("/v2/list/strikes"):
+            exp = querystring["exp"]
+            if exp == "20241115":
+                return {
+                    "header": {"format": ["strike"]},
+                    "response": [[100000], [105000]],
+                }
+            if exp == "20241205":
+                return {
+                    "header": {"format": ["strike"]},
+                    "response": [[110000]],
+                }
+            return {
+                "header": {"format": ["strike"]},
+                "response": [[120000]],
+            }
+        if url.endswith("/list/dates/option/quote"):
+            exp = querystring["exp"]
+            if exp == "20241115":
+                return {
+                    "header": {"format": None, "error_type": "null"},
+                    "response": [as_of_int, as_of_int + 1],
+                }
+            return {
+                "header": {"format": None, "error_type": "NO_DATA"},
+                "response": [],
+            }
+        raise AssertionError(f"Unexpected URL {url}")
+
+    monkeypatch.setattr(thetadata_helper, "get_request", fake_get_request)
+
+    result = thetadata_helper.build_historical_chain("user", "pass", asset, as_of_date)
+
+    assert result["Multiplier"] == 100
+    assert set(result["Chains"].keys()) == {"CALL", "PUT"}
+    assert list(result["Chains"]["CALL"].keys()) == ["2024-11-15"]
+    assert result["Chains"]["CALL"]["2024-11-15"] == [100.0, 105.0]
+    assert result["Chains"]["PUT"]["2024-11-15"] == [100.0, 105.0]
+
+
+def test_build_historical_chain_returns_none_when_no_dates(monkeypatch, caplog):
+    asset = Asset("NONE", asset_type="stock")
+    as_of_date = date(2024, 11, 28)
+
+    as_of_int = int(as_of_date.strftime("%Y%m%d"))
+
+    def fake_get_request(url, headers, querystring, username, password):
+        if url.endswith("/v2/list/expirations"):
+            return {"header": {"format": ["date"]}, "response": [[20241129], [20241206]]}
+        if url.endswith("/v2/list/strikes"):
+            return {"header": {"format": ["strike"]}, "response": [[150000], [155000]]}
+        if url.endswith("/list/dates/option/quote"):
+            return {"header": {"format": None, "error_type": "NO_DATA"}, "response": []}
+        raise AssertionError(f"Unexpected URL {url}")
+
+    monkeypatch.setattr(thetadata_helper, "get_request", fake_get_request)
+    monkeypatch.delenv("BACKTESTING_QUIET_LOGS", raising=False)
+    caplog.set_level(logging.WARNING, logger="lumibot.tools.thetadata_helper")
+
+    with caplog.at_level(logging.WARNING, logger="lumibot.tools.thetadata_helper"):
+        result = thetadata_helper.build_historical_chain("user", "pass", asset, as_of_date)
+
+    assert result is None
+    assert f"No expirations with data found for {asset.symbol}" in caplog.text
+
+def test_build_historical_chain_empty_response(monkeypatch, caplog):
+    asset = Asset("EMPTY", asset_type="stock")
+    as_of_date = date(2024, 11, 9)
+
+    def fake_get_request(url, headers, querystring, username, password):
+        if url.endswith("/v2/list/expirations"):
+            return {"header": {"format": ["date"]}, "response": []}
+        raise AssertionError("Unexpected call after empty expirations")
+
+    monkeypatch.setattr(thetadata_helper, "get_request", fake_get_request)
+    monkeypatch.delenv("BACKTESTING_QUIET_LOGS", raising=False)
+    caplog.set_level(logging.WARNING, logger="lumibot.tools.thetadata_helper")
+
+    with caplog.at_level(logging.WARNING, logger="lumibot.tools.thetadata_helper"):
+        result = thetadata_helper.build_historical_chain("user", "pass", asset, as_of_date)
+
+    assert result is None
+    assert "returned no expirations" in caplog.text
+
+
+class TestThetaDataConnectionSupervision:
+
+    def setup_method(self):
+        thetadata_helper.reset_connection_diagnostics()
+
+    def test_check_connection_recovers_after_restart(self, monkeypatch):
+        statuses = iter(["DISCONNECTED", "DISCONNECTED", "CONNECTED"])
+
+        class FakeResponse:
+            def __init__(self, text):
+                self.text = text
+
+        def fake_get(url, timeout):
+            try:
+                text = next(statuses)
+            except StopIteration:
+                text = "CONNECTED"
+            return FakeResponse(text)
+
+        start_calls = []
+
+        def fake_start(username, password):
+            start_calls.append((username, password))
+            return object()
+
+        monkeypatch.setattr(thetadata_helper.requests, "get", fake_get)
+        monkeypatch.setattr(thetadata_helper, "start_theta_data_client", fake_start)
+        monkeypatch.setattr(thetadata_helper, "is_process_alive", lambda: True)
+        monkeypatch.setattr(thetadata_helper, "CONNECTION_MAX_RETRIES", 2, raising=False)
+        monkeypatch.setattr(thetadata_helper, "MAX_TERMINAL_RESTART_CYCLES", 2, raising=False)
+        monkeypatch.setattr(thetadata_helper, "BOOT_GRACE_PERIOD", 0, raising=False)
+        monkeypatch.setattr(thetadata_helper, "CONNECTION_RETRY_SLEEP", 0, raising=False)
+        monkeypatch.setattr(thetadata_helper.time, "sleep", lambda *args, **kwargs: None)
+
+        client, connected = thetadata_helper.check_connection("user", "pass", wait_for_connection=True)
 
-        # Verify connection is established
-        _, connected = thetadata_helper.check_connection(username, password)
-        assert connected, "ThetaData Terminal failed to connect"
+        assert connected is True
+        assert len(start_calls) == 1
+        assert thetadata_helper.CONNECTION_DIAGNOSTICS["terminal_restarts"] >= 1
 
-        # First call - downloads (now guaranteed to be fresh)
-        start1 = time.time()
-        chains1 = thetadata_helper.get_chains_cached(username, password, asset, test_date)
-        time1 = time.time() - start1
+    def test_check_connection_raises_after_restart_cycles(self, monkeypatch):
+        statuses = iter(["DISCONNECTED"] * 10)
 
-        # Second call - should use cache
-        start2 = time.time()
-        chains2 = thetadata_helper.get_chains_cached(username, password, asset, test_date)
-        time2 = time.time() - start2
+        class FakeResponse:
+            def __init__(self, text):
+                self.text = text
 
-        # Verify same data
-        assert chains1 == chains2, "Cached chains should match original"
+        def fake_get(url, timeout):
+            try:
+                text = next(statuses)
+            except StopIteration:
+                text = "DISCONNECTED"
+            return FakeResponse(text)
 
-        # Second call should be MUCH faster (cached)
-        assert time2 < time1 * 0.1, f"Cache not working: time1={time1:.2f}s, time2={time2:.2f}s (should be 10x faster)"
-        print(f"✓ Cache speedup: {time1/time2:.1f}x faster ({time1:.2f}s -> {time2:.4f}s)")
+        monkeypatch.setattr(thetadata_helper.requests, "get", fake_get)
+        monkeypatch.setattr(thetadata_helper, "start_theta_data_client", lambda *args, **kwargs: object())
+        monkeypatch.setattr(thetadata_helper, "is_process_alive", lambda: True)
+        monkeypatch.setattr(thetadata_helper, "CONNECTION_MAX_RETRIES", 1, raising=False)
+        monkeypatch.setattr(thetadata_helper, "MAX_TERMINAL_RESTART_CYCLES", 1, raising=False)
+        monkeypatch.setattr(thetadata_helper, "BOOT_GRACE_PERIOD", 0, raising=False)
+        monkeypatch.setattr(thetadata_helper, "CONNECTION_RETRY_SLEEP", 0, raising=False)
+        monkeypatch.setattr(thetadata_helper.time, "sleep", lambda *args, **kwargs: None)
+
+        with pytest.raises(thetadata_helper.ThetaDataConnectionError):
+            thetadata_helper.check_connection("user", "pass", wait_for_connection=True)
 
 
 def test_finalize_day_frame_handles_dst_fallback():