ivolatility-backtesting 2.144__tar.gz → 2.146__tar.gz

{ivolatility_backtesting-2.144 → ivolatility_backtesting-2.146}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ivolatility_backtesting
-Version: 2.144
+Version: 2.146
 Summary: A universal backtesting framework for financial strategies using the IVolatility API.
 Author-email: IVolatility <support@ivolatility.com>
 Project-URL: Homepage, https://ivolatility.com

{ivolatility_backtesting-2.144 → ivolatility_backtesting-2.146}/ivolatility_backtesting/__init__.py

@@ -1,7 +1,7 @@
 from .ivolatility_backtesting import (
     BacktestResults, BacktestAnalyzer, ResultsReporter,
     ChartGenerator, ResultsExporter, run_backtest, run_backtest_with_stoploss,
-    run_backtest_notebook, print_signals_table,
+    run_backtest_notebook, print_signals_table, enable_output_logging,
     init_api, api_call, APIHelper, APIManager,
     ResourceMonitor, create_progress_bar, update_progress, format_time,
     StopLossManager, PositionManager, StopLossConfig,
@@ -33,7 +33,7 @@ from .ivolatility_backtesting import (
 __all__ = [
     'BacktestResults', 'BacktestAnalyzer', 'ResultsReporter',
     'ChartGenerator', 'ResultsExporter', 'run_backtest', 'run_backtest_with_stoploss',
-    'run_backtest_notebook', 'print_signals_table',
+    'run_backtest_notebook', 'print_signals_table', 'enable_output_logging',
     'init_api', 'api_call', 'APIHelper', 'APIManager',
     'ResourceMonitor', 'create_progress_bar', 'update_progress', 'format_time',
     'StopLossManager', 'PositionManager', 'StopLossConfig',

{ivolatility_backtesting-2.144 → ivolatility_backtesting-2.146}/ivolatility_backtesting/ivolatility_backtesting.py

@@ -179,8 +179,29 @@ _API_LOG_FILE = None  # Track API log file path for summary printing
 # ============================================================
 from typing import Optional, Dict, Any, Tuple
 
+_NUMERIC_COERCE_WARNED = False
+
+
+def _as_data_row(source):
+    """Normalize a stock/data row to a single record.
+
+    Callers legitimately pass either a row (``df.iloc[0]``) or a one-row slice
+    (``df[df['date'] == d]``). Only a 2-D object needs ``.iloc[0]``: applying it
+    to a Series would collapse it to its first cell.
+    """
+    if source is None:
+        return None
+    try:
+        if getattr(source, 'ndim', 1) > 1:
+            return source.iloc[0] if len(source) > 0 else None
+    except Exception:
+        return source
+    return source
+
+
 def _first_valid_numeric_value(source, columns) -> Optional[float]:
     """Return the first usable numeric value from source[column] in priority order."""
+    source = _as_data_row(source)
     if source is None:
         return None
     for col in columns:
@@ -196,7 +217,16 @@ def _first_valid_numeric_value(source, columns) -> Optional[float]:
             if value is None or pd.isna(value):
                 continue
             return float(value)
-        except Exception:
+        except Exception as exc:
+            # Shape errors here used to vanish silently and surface later as a
+            # wrong number (fallback instead of the real price). Warn once per
+            # run so the cause is visible without flooding the notebook output.
+            global _NUMERIC_COERCE_WARNED
+            if not _NUMERIC_COERCE_WARNED:
+                _NUMERIC_COERCE_WARNED = True
+                print(f"\u26a0\ufe0f  Could not read numeric field '{col}' from the data row "
+                      f"({type(exc).__name__}: {exc}). Falling back to defaults — "
+                      f"check that stock_row is a row or a one-row slice.")
             continue
     return None
 
@@ -266,14 +296,7 @@ def _resolve_runtime_underlying_price(stock_price=None, stock_row=None, options_
     Resolve the best option-aligned underlying price for runtime P&L / SL logic.
     Priority: stock_row runtime fields -> options underlying_price -> passed scalar.
     """
-    row_obj = None
-    try:
-        if stock_row is not None and hasattr(stock_row, 'iloc') and len(stock_row) > 0:
-            row_obj = stock_row.iloc[0]
-        elif stock_row is not None:
-            row_obj = stock_row
-    except Exception:
-        row_obj = stock_row
+    row_obj = _as_data_row(stock_row)
 
     value = _first_valid_numeric_value(
         row_obj,
@@ -297,14 +320,7 @@ def _resolve_runtime_underlying_price(stock_price=None, stock_row=None, options_
 
 def _resolve_runtime_stock_range(stock_row=None, fallback_price=None) -> Tuple[Optional[float], Optional[float]]:
     """Resolve runtime high/low in the same coordinate system as runtime price."""
-    row_obj = None
-    try:
-        if stock_row is not None and hasattr(stock_row, 'iloc') and len(stock_row) > 0:
-            row_obj = stock_row.iloc[0]
-        elif stock_row is not None:
-            row_obj = stock_row
-    except Exception:
-        row_obj = stock_row
+    row_obj = _as_data_row(stock_row)
 
     high = _first_valid_numeric_value(row_obj, ('runtime_high', 'high'))
     low = _first_valid_numeric_value(row_obj, ('runtime_low', 'low'))
@@ -1515,6 +1531,7 @@ def report_results_folder(
     return {"folder": folder, "strategies": strategies}
 
 
+
 def run_backtest_notebook(
     base_config: dict,
     strategy_fn,
@@ -12125,12 +12142,59 @@ def _is_am_settled_position(position):
     if style == 'PM':
         return False
     root = str(position.get('opt_root') or position.get('symbol') or '').upper()
+    if root == 'VIX':
+        # Every VIX expiration (Wednesday, or Tue/Thu when shifted) is cash-settled
+        # on the morning VRO print; the open is only the fallback proxy.
+        return True
     if root not in _AM_SETTLED_INDEX_ROOTS:
         return False
     exp = _as_date_obj(position.get('expiration'))
     return exp is not None and exp.weekday() == 4 and 15 <= exp.day <= 21
 
 
+# Max calendar gap between a VIX expiration date and the VRO print that settles it.
+# Normal case: same day; an unscheduled exchange closure moves the print to the next trading day.
+_VRO_MAX_SHIFT_DAYS = 5
+
+
+def _vro_settlement_for(config, expiration):
+    """VRO settlement value for a VIX expiration, or None when unavailable.
+
+    The settling print is the first VRO row dated >= expiration (VIX expiry
+    dates in the option data already carry the Tue/Wed shift; only unscheduled
+    closures move the print to a later day). Returns None when config has no
+    '_preloaded_vro' frame, the date is unparsable, or the nearest print is
+    more than _VRO_MAX_SHIFT_DAYS away.
+    """
+    exp = _as_date_obj(expiration)
+    if exp is None or config is None:
+        return None
+    vro = config.get('_preloaded_vro')
+    if vro is None:
+        # Safety net for strategies that never went through preload_data_universal:
+        # fetch once and keep it on the shared config (empty frame on failure).
+        try:
+            vro = _load_vro_series(config.get('start_date'), config.get('end_date'), config)
+        except Exception:
+            vro = pd.DataFrame(columns=['date', 'vro'])
+        config['_preloaded_vro'] = vro
+    if getattr(vro, 'empty', True):
+        return None
+    try:
+        dates = pd.to_datetime(vro['date']).dt.date
+        mask = dates >= exp
+        if not mask.any():
+            return None
+        first_idx = dates[mask].idxmin()          # earliest print on/after expiration
+        first_date = dates.loc[first_idx]
+        if (first_date - exp).days > _VRO_MAX_SHIFT_DAYS:
+            return None
+        value = float(vro.loc[first_idx, 'vro'])
+        return value if value > 0 else None
+    except Exception:
+        return None
+
+
 class PositionManager:
     """Universal Position Manager with automatic mode detection"""
 
@@ -12139,6 +12203,7 @@ class PositionManager:
         self.closed_trades = []
         self.config = config
         self.debug = debug
+        self._vro_missing_warned = set()   # VIX expirations already reported as settled without VRO
         self.debuginfo = config.get('debuginfo', 0)  # Add debuginfo level
         
         # AUTO-DETECT strategy_type if missing
@@ -12936,10 +13001,29 @@ class PositionManager:
                             position.get('underlying_entry_price', 0)
                         )
 
-                    # AM-settled index monthlies settle on the MORNING open
-                    # (SOQ), not the close; expiration-day open is the proxy
-                    if (underlying_price and self.config.get('am_settlement_open', True)
+                    # Settlement reference, in priority order:
+                    #   1. exact settlement print (VIX -> VRO), set by build_price_data
+                    #   2. AM-settled index (SPX/NDX/... 3rd Friday, VIX any date):
+                    #      expiration-day OPEN as the SOQ proxy
+                    #   3. close (everything else)
+                    settlement_source = 'close'
+                    _settle_px = None
+                    if position_id in price_data and isinstance(price_data[position_id], dict):
+                        _settle_px = price_data[position_id].get('settlement_price')
+                    if _settle_px and _settle_px > 0 and self.config.get('am_settlement_open', True):
+                        if self.debug and underlying_price and abs(_settle_px - underlying_price) > 1e-9:
+                            print(f"[SETTLEMENT] {position_id}: using settlement print "
+                                  f"{_settle_px:.2f} (VRO) instead of close {underlying_price:.2f}")
+                        underlying_price = _settle_px
+                        settlement_source = 'vro'
+                    elif (underlying_price and self.config.get('am_settlement_open', True)
                             and _is_am_settled_position(position)):
+                        if str(position.get('opt_root') or position.get('symbol') or '').upper() == 'VIX':
+                            _exp_key = str(position.get('expiration'))[:10]
+                            if _exp_key not in self._vro_missing_warned:
+                                self._vro_missing_warned.add(_exp_key)
+                                print(f"WARNING: no VRO settlement print for VIX expiration {_exp_key} - "
+                                      f"settling on the expiration-day open (SOQ proxy)")
                         _open_px = None
                         if position_id in price_data and isinstance(price_data[position_id], dict):
                             _open_px = price_data[position_id].get('underlying_open')
@@ -12948,6 +13032,7 @@ class PositionManager:
                                 print(f"[AM SETTLEMENT] {position_id}: using expiration-day "
                                       f"OPEN {_open_px:.2f} (SOQ proxy) instead of close {underlying_price:.2f}")
                             underlying_price = _open_px
+                            settlement_source = 'open'
 
                     strike         = position.get('strike', 0)
                     strategy_type  = position.get('strategy_type', '')
@@ -13049,7 +13134,11 @@ class PositionManager:
                         'pnl': current_pnl,
                         'pnl_pct': current_pnl_pct,
                         'settlement_type': 'intrinsic' if used_intrinsic else 'market',
-                        **close_kwargs  # Include leg exit data automatically
+                        **close_kwargs,  # Include leg exit data automatically
+                        # after close_kwargs: a custom strategy's generic kwargs must not
+                        # overwrite what the settlement actually used
+                        'settlement_source': settlement_source,
+                        'settlement_price': underlying_price if used_intrinsic else None,
                     }
                     
                     to_close.append(stop_info)
@@ -13715,19 +13804,23 @@ class PositionManager:
                 if stock_row is not None:
                     # runtime_open = split-aligned open (REFERENCE §4a) — the
                     # AM-settlement reference must not use the adjusted series
-                    _stock_open = None
-                    for _oc in ('runtime_open', 'open'):
-                        try:
-                            _ov = stock_row.get(_oc) if hasattr(stock_row, 'get') else stock_row[_oc]
-                        except (KeyError, IndexError, TypeError):
-                            _ov = None
-                        if _ov is not None and not pd.isna(_ov) and float(_ov) > 0:
-                            _stock_open = float(_ov)
-                            break
+                    # stock_row may arrive as a single-row slice (stock_df[mask]) —
+                    # take the row itself, otherwise .get() yields a Series and any
+                    # boolean/float use of it raises ValueError.
+                    _stock_open = _first_valid_numeric_value(stock_row, ('runtime_open', 'open'))
+                    if _stock_open is not None and _stock_open <= 0:
+                        _stock_open = None
+                    _settle_px = None
+                    if str(position.get('opt_root') or position.get('symbol') or '').upper() == 'VIX':
+                        _exp_d = _as_date_obj(position.get('expiration'))
+                        _cur_d = _as_date_obj(current_date)
+                        if _exp_d is not None and _cur_d is not None and _cur_d >= _exp_d:
+                            _settle_px = _vro_settlement_for(self.config, position.get('expiration'))
                     price_data[pos_id].update({
                         'underlying_high': stock_high,
                         'underlying_low': stock_low,
                         'underlying_open': _stock_open,
+                        'settlement_price': _settle_px,
                         'underlying_entry_price': position.get('underlying_entry_price', stock_price),
                         'current_date': current_date,
                         'symbol': position.get('symbol')
@@ -15265,6 +15358,24 @@ class BacktestAnalyzer:
         self.metrics['avg_loss'] = losing['pnl'].mean() if len(losing) > 0 else 0
         self.metrics['best_trade'] = trades_df['pnl'].max()
         self.metrics['worst_trade'] = trades_df['pnl'].min()
+
+        # Requested vs realized tenor. A wide dte_tolerance (or a symbol with only
+        # weekly expirations) can silently turn "1 DTE" into a ~6 DTE test.
+        _dte_target = (getattr(getattr(self, 'results', None), 'config', None) or {}).get('dte_target')
+        if 'entry_dte' in trades_df.columns:
+            _dte = pd.to_numeric(trades_df['entry_dte'], errors='coerce').dropna()
+            if len(_dte) > 0:
+                self.metrics['dte_target'] = _dte_target
+                self.metrics['dte_realized_median'] = float(_dte.median())
+                self.metrics['dte_realized_min'] = int(_dte.min())
+                self.metrics['dte_realized_max'] = int(_dte.max())
+                try:
+                    _t = float(_dte_target)
+                    # dte_target 0 means "nearest expiration after the exit" (earnings
+                    # pattern) - realized DTE is expected to float there, no check.
+                    self.metrics['dte_mismatch'] = _t > 0 and abs(float(_dte.median()) - _t) > max(1.0, _t)
+                except (TypeError, ValueError):
+                    self.metrics['dte_mismatch'] = False
         
         if len(winning) > 0 and len(losing) > 0 and self.metrics['avg_loss'] != 0:
             self.metrics['avg_win_loss_ratio'] = abs(self.metrics['avg_win'] / self.metrics['avg_loss'])
@@ -15708,6 +15819,25 @@ class ResultsReporter:
         print("TRADING STATISTICS")
         print("-"*80)
         print(f"Total Trades:            {m['total_trades']:>15}")
+        if m.get('dte_realized_median') is not None:
+            _tgt = m.get('dte_target')
+            try:
+                _tgt_s = f"{int(float(_tgt))}"
+            except (TypeError, ValueError):
+                _tgt_s = "n/a"
+            print(f"DTE Target / Realized:   {_tgt_s:>6} / median {m['dte_realized_median']:.0f}"
+                  f"  (range {m['dte_realized_min']}-{m['dte_realized_max']} days at entry)")
+            if m.get('dte_mismatch'):
+                print("WARNING: realized DTE differs from the requested dte_target - the tenor actually")
+                print("         traded is not the one asked for (check dte_tolerance / expiration calendar)")
+        if not m.get('total_trades'):
+            # 0 trades is almost never a real result — it usually means the entry
+            # signal never fired (unread config key, indicators not computed).
+            print("\u26a0\ufe0f  0 trades: the entry signal never fired — this is not a "
+                  "result, it is a run that never entered. Check that indicators were "
+                  "computed (look for 'Processing N cached indicators' — 0 means the "
+                  "signal could not be evaluated) and that the data loaded (a locked "
+                  "DuckDB cache or a failed fetch also ends in 0 trades).")
         print(f"Winning Trades:          {m['winning_trades']:>15}")
         print(f"Losing Trades:           {m['losing_trades']:>15}")
         print(f"Win Rate:                {m['win_rate']:>15.2f}%  (% profitable trades)")
@@ -16755,6 +16885,17 @@ class ResultsExporter:
             f.write(f"Sharpe: {m['sharpe']:.2f}\n")
             f.write(f"Max DD: {m['max_drawdown']:.2f}%\n")
             f.write(f"Trades: {m['total_trades']}\n")
+            if m.get('dte_realized_median') is not None:
+                _tgt = m.get('dte_target')
+                try:
+                    _tgt_s = f"{int(float(_tgt))}"
+                except (TypeError, ValueError):
+                    _tgt_s = "n/a"
+                f.write(f"DTE Target / Realized: {_tgt_s} / median {m['dte_realized_median']:.0f}"
+                        f" (range {m['dte_realized_min']}-{m['dte_realized_max']} days at entry)\n")
+                if m.get('dte_mismatch'):
+                    f.write("WARNING: realized DTE differs from the requested dte_target - "
+                            "the tenor actually traded is not the one asked for\n")
         
         exported_files.append((f'{prefix}_summary.txt', ""))
         if not silent:
@@ -18932,6 +19073,7 @@ def _try_read_from_duckdb_storage(config, cache_config, symbol, extended_start,
                         }
 
                         _load_futures_for_hedge(config, preloaded)
+                        _attach_vro_settlement(config, preloaded)
                         return preloaded
             else:
                 _rich_print(f"           ℹ️ Legacy mode — running full gap detection")
@@ -19473,6 +19615,7 @@ def _try_read_from_duckdb_storage(config, cache_config, symbol, extended_start,
 
             # DON'T close conn - ChunkManager needs it!
             _load_futures_for_hedge(config, preloaded)
+            _attach_vro_settlement(config, preloaded)
             return preloaded
             
         else:
@@ -19615,6 +19758,7 @@ def _try_read_from_duckdb_storage(config, cache_config, symbol, extended_start,
         }
 
         _load_futures_for_hedge(config, preloaded)
+        _attach_vro_settlement(config, preloaded)
         return preloaded
 
     except Exception as e:
@@ -19993,6 +20137,7 @@ def _preload_duckdb_SSD_storage(config, cache_config):
     }
 
     _load_futures_for_hedge(config, preloaded)
+    _attach_vro_settlement(config, preloaded)
     return preloaded
 
 
@@ -20887,6 +21032,7 @@ def _try_duckdb_preload(config, cache_config, debug=False):
     }
 
     _load_futures_for_hedge(config, preloaded)
+    _attach_vro_settlement(config, preloaded)
     return preloaded
 
 
@@ -23098,6 +23244,48 @@ def _preload_futures_to_duckdb(config, cache_config):
 # ============================================================
 # UNIVERSAL DATA PRELOADER V2 (NEW!)
 # ============================================================
+def _vro_window_end(end_date):
+    """end_date + _VRO_MAX_SHIFT_DAYS as 'YYYY-MM-DD' (a print shifted past the last backtest day must still load)."""
+    d = _as_date_obj(end_date)
+    if d is None:
+        return str(end_date)[:10]
+    import datetime as _d
+    return (d + _d.timedelta(days=_VRO_MAX_SHIFT_DAYS)).strftime('%Y-%m-%d')
+
+
+def _load_vro_series(start_date, end_date, config=None):
+    """VRO (VIX settlement print) as a DataFrame[date, vro]; empty frame on any failure."""
+    if not start_date or not end_date:
+        return pd.DataFrame(columns=['date', 'vro'])
+    try:
+        raw = get_api_data(api_call(MarketDataManager.ENDPOINT_STOCK_EOD,
+                                    cache_config=(config or {}).get('cache_config'),
+                                    symbol='VRO', from_=str(start_date)[:10], to=_vro_window_end(end_date)))
+        if raw is None or raw.empty or 'date' not in raw.columns or 'close' not in raw.columns:
+            print("WARNING: VRO settlement series unavailable - VIX expirations will settle on the open (SOQ proxy)")
+            return pd.DataFrame(columns=['date', 'vro'])
+        out = raw[['date', 'close']].rename(columns={'close': 'vro'}).copy()
+        out['date'] = pd.to_datetime(out['date'])
+        out = out.sort_values('date').drop_duplicates('date').reset_index(drop=True)
+        print(f"VRO settlement series loaded: {len(out)} prints ({out['date'].min().date()} .. {out['date'].max().date()})")
+        return out
+    except Exception as e:
+        print(f"WARNING: VRO settlement series failed to load ({e}) - VIX expirations will settle on the open (SOQ proxy)")
+        return pd.DataFrame(columns=['date', 'vro'])
+
+
+def _attach_vro_settlement(config, preloaded):
+    """VIX only: put the VRO settlement series into preloaded['_preloaded_vro'] (idempotent)."""
+    try:
+        if str((config or {}).get('symbol', '')).upper() != 'VIX':
+            return
+        if '_preloaded_vro' in preloaded or '_preloaded_vro' in config:
+            return
+        preloaded['_preloaded_vro'] = _load_vro_series(config.get('start_date'), config.get('end_date'), config)
+    except Exception as e:
+        print(f"WARNING: VRO settlement series not attached ({e})")
+
+
 def preload_data_universal(config, data_requests=None, debug=False):
     """
     🚀 TRULY UNIVERSAL DATA PRELOADER - Works with ANY API endpoint!
@@ -23279,6 +23467,7 @@ def preload_data_universal(config, data_requests=None, debug=False):
                 set_option_patch_context(OptionPatchContext(symbol, _fetch_opt_intraday))
 
         _activate_runtime_stock_shim(config, config)
+        _attach_vro_settlement(config, config)
         return config
     
     # Start timing for data loading
@@ -24113,6 +24302,7 @@ def preload_data_universal(config, data_requests=None, debug=False):
 
     _activate_runtime_stock_shim(config, preloaded)
     _load_futures_for_hedge(config, preloaded)
+    _attach_vro_settlement(config, preloaded)
     return preloaded
 
 
@@ -25550,7 +25740,7 @@ def print_signals_table(config, indicator_cache, stock_df, save_path=None, silen
     expected_ivx_key = ('iv_lean_zscore_ivx', (_cfg_dte, int(_cfg_lb))) if _cfg_lb is not None else None
 
     if expected_raw_key is not None and expected_raw_key not in indicator_cache and should_print:
-        present_lbs = sorted({k[1][0] for k in indicator_cache if k[0] == 'iv_lean_zscore' and isinstance(k[1], tuple)})
+        present_lbs = sorted({k[1][0] for k in indicator_cache if k[0] == 'iv_lean_zscore' and isinstance(k[1], tuple) and k[1]})
         print(f"⚠️  print_signals_table: no iv_lean_zscore cache for lookback={_cfg_lb} "
               f"(cache has: {present_lbs}). Table will be empty for active config.")
 
@@ -26803,6 +26993,7 @@ def run_optimization(base_config, param_grid, strategy_function,
         (combined_results_df, baselines_dict, results_folder)
         baselines_dict: {symbol: metrics_dict}
     """
+
     import copy as _copy
 
     if symbols is None:

{ivolatility_backtesting-2.144 → ivolatility_backtesting-2.146}/ivolatility_backtesting.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ivolatility_backtesting
-Version: 2.144
+Version: 2.146
 Summary: A universal backtesting framework for financial strategies using the IVolatility API.
 Author-email: IVolatility <support@ivolatility.com>
 Project-URL: Homepage, https://ivolatility.com

{ivolatility_backtesting-2.144 → ivolatility_backtesting-2.146}/ivolatility_backtesting.egg-info/SOURCES.txt

@@ -9,4 +9,5 @@ ivolatility_backtesting.egg-info/dependency_links.txt
 ivolatility_backtesting.egg-info/requires.txt
 ivolatility_backtesting.egg-info/top_level.txt
 tests/test_2142_fixes.py
-tests/test_2144_duckdb_dedup.py
+tests/test_2144_duckdb_dedup.py
+tests/test_2146_vix_vro.py

{ivolatility_backtesting-2.144 → ivolatility_backtesting-2.146}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ivolatility_backtesting"
-version = "2.144"
+version = "2.146"
 description = "A universal backtesting framework for financial strategies using the IVolatility API."
 readme = "README.md"
 authors = [

ivolatility_backtesting-2.146/tests/test_2146_vix_vro.py

@@ -0,0 +1,205 @@
+# Tests for 2.146: VIX options settle against VRO (Cboe settlement print),
+# not the VIX close; report shows requested vs realized DTE.
+#
+# Runs standalone (no pytest needed):  python3 tests/test_2146_vix_vro.py
+# Also pytest-compatible for CI:       pytest tests/test_2146_vix_vro.py
+import os
+import sys
+import traceback
+from datetime import date
+
+import matplotlib
+matplotlib.use('Agg')
+import pandas as pd
+
+_REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.join(_REPO, 'ivolatility_backtesting'))
+import ivolatility_backtesting as lib  # noqa: E402
+
+
+def _vro_frame():
+    # Real VRO prints (restapi stock-prices symbol=VRO): Wed 2024-12-18, the
+    # holiday-shifted Thu 2018-12-06 (expiration was Wed 2018-12-05).
+    return pd.DataFrame({
+        'date': pd.to_datetime(['2018-12-06', '2024-12-11', '2024-12-18', '2024-12-24']),
+        'vro': [24.60, 13.20, 15.66, 14.10],
+    })
+
+
+def _open_short_vix_call(pm, pid='p1', strike=17.0, credit=6.0, exp=date(2024, 12, 18)):
+    # 1 contract sold at $0.06 -> total_cost 6.0 (credit); entry_price 0 marks SHORT
+    pm.open_position(position_id=pid, strategy_type='CALL', symbol='VIX',
+                     entry_date=date(2024, 12, 16), entry_price=0.0,
+                     quantity=100, contracts=1, total_cost=credit,
+                     strike=strike, expiration=exp,
+                     underlying_entry_price=14.69, opt_type='call')
+
+
+def test_vix_is_am_settled_any_date():
+    assert lib._is_am_settled_position({'symbol': 'VIX', 'expiration': date(2024, 12, 18)}) is True   # Wed
+    assert lib._is_am_settled_position({'symbol': 'VIX', 'expiration': date(2024, 12, 24)}) is True   # Tue
+    assert lib._is_am_settled_position({'opt_root': 'VIX', 'expiration': date(2018, 12, 5)}) is True
+    assert lib._is_am_settled_position({'symbol': 'VIX', 'expiration': date(2024, 12, 18),
+                                        'settlement_style': 'PM'}) is False
+    # unchanged for the existing roots
+    assert lib._is_am_settled_position({'symbol': 'SPX', 'expiration': date(2025, 7, 25)}) is False
+
+
+def test_vro_lookup_same_day_and_holiday_shift():
+    cfg = {'_preloaded_vro': _vro_frame()}
+    assert lib._vro_settlement_for(cfg, date(2024, 12, 18)) == 15.66
+    assert lib._vro_settlement_for(cfg, '2024-12-18') == 15.66
+    assert lib._vro_settlement_for(cfg, pd.Timestamp('2024-12-24')) == 14.10
+    # expiration on an unscheduled closure -> next print
+    assert lib._vro_settlement_for(cfg, date(2018, 12, 5)) == 24.60
+    # too far from any print -> None (no silent fallback to a wrong week)
+    assert lib._vro_settlement_for(cfg, date(2024, 11, 1)) is None
+    assert lib._vro_settlement_for(cfg, date(2025, 1, 1)) is None
+    assert lib._vro_settlement_for({}, date(2024, 12, 18)) is None
+    assert lib._vro_settlement_for({'_preloaded_vro': pd.DataFrame(columns=['date', 'vro'])},
+                                   date(2024, 12, 18)) is None
+
+
+def test_vro_lookup_unsorted_frame():
+    vro = pd.DataFrame({'date': pd.to_datetime(['2024-12-24', '2024-12-18', '2024-12-11']),
+                        'vro': [14.10, 15.66, 13.20]})
+    assert lib._vro_settlement_for({'_preloaded_vro': vro}, date(2024, 12, 18)) == 15.66
+    assert lib._vro_settlement_for({'_preloaded_vro': vro}, date(2024, 12, 13)) == 15.66   # 5-day shift allowed
+    assert lib._vro_settlement_for({'_preloaded_vro': vro}, date(2024, 12, 12)) is None    # 6 days: too far
+
+
+def test_am_settlement_open_false_disables_vro_too():
+    pm = lib.PositionManager({'strategy_type': 'CALL', 'symbol': 'VIX', 'am_settlement_open': False}, debug=False)
+    _open_short_vix_call(pm)
+    pd_data = {'p1': {'underlying_price': 27.62, 'underlying_open': 15.57, 'settlement_price': 15.66}}
+    si = pm.check_positions(date(2024, 12, 18), pd_data)[0]
+    assert abs(si['pnl'] - (6.0 - (27.62 - 17.0) * 100)) < 1e-6, si['pnl']
+    assert si['settlement_source'] == 'close'
+
+
+def test_settlement_uses_vro_over_close_and_open():
+    pm = lib.PositionManager({'strategy_type': 'CALL', 'symbol': 'VIX'}, debug=False)
+    _open_short_vix_call(pm)
+    # 2024-12-18: VIX open 15.57, close 27.62, VRO 15.66 -> strike 17 expires worthless
+    pd_data = {'p1': {'underlying_price': 27.62, 'underlying_open': 15.57, 'settlement_price': 15.66}}
+    si = pm.check_positions(date(2024, 12, 18), pd_data)[0]
+    assert abs(si['pnl'] - 6.0) < 1e-6, si['pnl']
+    assert si['settlement_source'] == 'vro', si.get('settlement_source')
+
+
+def test_settlement_vro_in_the_money():
+    pm = lib.PositionManager({'strategy_type': 'CALL', 'symbol': 'VIX'}, debug=False)
+    _open_short_vix_call(pm, strike=19.0, credit=10.0, exp=date(2018, 12, 5))
+    # settled Thu 2018-12-06 at VRO 24.60 (close was 21.19): loss = 10 - (24.60-19)*100 = -550
+    pd_data = {'p1': {'underlying_price': 21.19, 'underlying_open': 23.53, 'settlement_price': 24.60}}
+    si = pm.check_positions(date(2018, 12, 6), pd_data)[0]
+    assert abs(si['pnl'] - (-550.0)) < 1e-6, si['pnl']
+    assert si['settlement_source'] == 'vro'
+
+
+def test_settlement_falls_back_to_open_without_vro():
+    import io, contextlib
+    pm = lib.PositionManager({'strategy_type': 'CALL', 'symbol': 'VIX'}, debug=False)
+    _open_short_vix_call(pm)
+    pd_data = {'p1': {'underlying_price': 27.62, 'underlying_open': 15.57, 'settlement_price': None}}
+    buf = io.StringIO()
+    with contextlib.redirect_stdout(buf):
+        si = pm.check_positions(date(2024, 12, 18), pd_data)[0]
+    assert abs(si['pnl'] - 6.0) < 1e-6, si['pnl']
+    assert si['settlement_source'] == 'open'
+    assert 'no VRO settlement print for VIX expiration 2024-12-18' in buf.getvalue(), buf.getvalue()
+
+
+def test_settlement_close_for_equity_unchanged():
+    pm = lib.PositionManager({'strategy_type': 'CALL', 'symbol': 'AAPL'}, debug=False)
+    pm.open_position(position_id='p1', strategy_type='CALL', symbol='AAPL',
+                     entry_date=date(2025, 5, 2), entry_price=1000.0,
+                     quantity=100, contracts=1, total_cost=1000.0,
+                     strike=200.0, expiration=date(2025, 7, 18),
+                     underlying_entry_price=201.0, opt_type='call')
+    pd_data = {'p1': {'underlying_price': 230.0, 'underlying_open': 225.0}}
+    si = pm.check_positions(date(2025, 7, 18), pd_data)[0]
+    assert abs(si['pnl'] - ((230.0 - 200.0) * 100 - 1000.0)) < 1.0, si['pnl']
+    assert si['settlement_source'] == 'close'
+
+
+def test_build_price_data_attaches_vro_for_vix():
+    cfg = {'strategy_type': 'CALL', 'symbol': 'VIX', '_preloaded_vro': _vro_frame()}
+    pm = lib.PositionManager(cfg, debug=False)
+    _open_short_vix_call(pm)
+    stock_row = pd.Series({'date': pd.Timestamp('2024-12-18'), 'open': 15.57, 'high': 28.32,
+                           'low': 15.0, 'close': 27.62})
+    options_df = pd.DataFrame({'strike': [17.0], 'expiration': [pd.Timestamp('2024-12-18')],
+                               'opt_type': ['C'], 'bid': [10.5], 'ask': [10.7], 'price': [10.6]})
+
+    def _get_opt(*a, **k):
+        return {'bid': 10.5, 'ask': 10.7, 'price': 10.6, 'mid': 10.6}
+
+    pdata = pm.build_price_data(date(2024, 12, 18), 27.62, options_df, _get_opt, stock_row=stock_row)
+    assert pdata['p1'].get('settlement_price') == 15.66, pdata['p1'].get('settlement_price')
+    assert pdata['p1'].get('underlying_open') == 15.57
+    # before expiration the print is not exposed (no look-ahead field on live bars)
+    pre = pm.build_price_data(date(2024, 12, 17), 14.7, options_df, _get_opt, stock_row=stock_row)
+    assert pre['p1'].get('settlement_price') is None
+
+
+def test_enable_output_logging_is_exported():
+    # the master prompt tells generated scripts to `from ivolatility_backtesting import enable_output_logging`
+    from ivolatility_backtesting import enable_output_logging  # noqa: F401
+    assert callable(enable_output_logging)
+
+
+def test_vro_window_end_extends_past_end_date():
+    assert lib._vro_window_end(date(2018, 12, 5)) == '2018-12-10'
+    assert lib._vro_window_end('2018-12-05') == '2018-12-10'
+
+
+def test_dte_realized_metrics_and_warning():
+    trades = [
+        {'pnl': 10.0, 'entry_dte': 6, 'entry_date': date(2024, 1, 4), 'exit_date': date(2024, 1, 10)},
+        {'pnl': -5.0, 'entry_dte': 6, 'entry_date': date(2024, 1, 11), 'exit_date': date(2024, 1, 17)},
+        {'pnl': 8.0, 'entry_dte': 1, 'entry_date': date(2024, 1, 23), 'exit_date': date(2024, 1, 24)},
+    ]
+    res = lib.BacktestResults(equity_curve=[100000, 100010, 100005, 100013],
+                              equity_dates=[date(2024, 1, 2), date(2024, 1, 10), date(2024, 1, 17), date(2024, 1, 24)],
+                              trades=trades, initial_capital=100000,
+                              config={'dte_target': 1, 'dte_tolerance': 7})
+    an = lib.BacktestAnalyzer(res)
+    an.calculate_all_metrics()
+    m = an.metrics
+    assert m['dte_target'] == 1 and m['dte_realized_median'] == 6 and m['dte_realized_min'] == 1 \
+        and m['dte_realized_max'] == 6, m
+    assert m['dte_mismatch'] is True
+
+    res2 = lib.BacktestResults(equity_curve=[100000, 100010], equity_dates=[date(2024, 1, 2), date(2024, 1, 10)],
+                               trades=[{'pnl': 1.0, 'entry_dte': 30, 'entry_date': date(2024, 1, 2), 'exit_date': date(2024, 1, 10)}],
+                               initial_capital=100000, config={'dte_target': 30})
+    an2 = lib.BacktestAnalyzer(res2)
+    an2.calculate_all_metrics()
+    assert an2.metrics['dte_mismatch'] is False
+
+    # earnings pattern: dte_target 0 = nearest expiration after exit -> never a mismatch
+    res3 = lib.BacktestResults(equity_curve=[100000, 100010], equity_dates=[date(2024, 1, 2), date(2024, 1, 10)],
+                               trades=[{'pnl': 1.0, 'entry_dte': 12, 'entry_date': date(2024, 1, 2), 'exit_date': date(2024, 1, 10)}],
+                               initial_capital=100000, config={'dte_target': 0, 'dte_tolerance': 29})
+    an3 = lib.BacktestAnalyzer(res3)
+    an3.calculate_all_metrics()
+    assert an3.metrics['dte_mismatch'] is False and an3.metrics['dte_realized_median'] == 12
+
+
+# ---------------------------------------------------------------- runner
+
+if __name__ == '__main__':
+    tests = [(n, f) for n, f in sorted(globals().items())
+             if n.startswith('test_') and callable(f)]
+    failed = []
+    for name, fn in tests:
+        try:
+            fn()
+            print(f"PASS  {name}")
+        except Exception:
+            failed.append(name)
+            print(f"FAIL  {name}")
+            traceback.print_exc()
+    print(f"\n{len(tests) - len(failed)}/{len(tests)} passed")
+    sys.exit(1 if failed else 0)