ivolatility-backtesting 1.34__tar.gz → 1.36__tar.gz

{ivolatility_backtesting-1.34 → ivolatility_backtesting-1.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ivolatility_backtesting
-Version: 1.34
+Version: 1.36
 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-1.34 → ivolatility_backtesting-1.36}/ivolatility_backtesting/__init__.py

@@ -19,7 +19,8 @@ from .ivolatility_backtesting import (
     _process_options_df,
     precalculate_indicators_from_config, build_indicator_lookup,
     INDICATOR_REGISTRY, auto_calculate_lookback_period,
-    calculate_iv_lean_from_ivx, preload_ivx_zscore_cache
+    calculate_iv_lean_from_ivx, preload_ivx_zscore_cache,
+    calculate_iv_percentile_from_ivx  # For earnings strategies
 )
 
 __all__ = [
@@ -45,5 +46,6 @@ __all__ = [
     'precalculate_indicators_from_config', 'build_indicator_lookup',
     'INDICATOR_REGISTRY', 'auto_calculate_lookback_period',
     # IV Lean / Z-Score functions
-    'calculate_iv_lean_from_ivx', 'preload_ivx_zscore_cache'
+    'calculate_iv_lean_from_ivx', 'preload_ivx_zscore_cache',
+    'calculate_iv_percentile_from_ivx'  # For earnings strategies
 ]

{ivolatility_backtesting-1.34 → ivolatility_backtesting-1.36}/ivolatility_backtesting/ivolatility_backtesting.py

@@ -2365,7 +2365,9 @@ class StrategyRegistry:
         strategy = cls.get(strategy_type)
         
         if not strategy or 'legs' not in strategy:
-            return pos_data  # Fallback: pass everything as-is
+            # Fallback: filter out fields passed explicitly to close_position()
+            excluded = ['pnl', 'pnl_pct', 'price', 'exit_reason', 'close_reason', 'position_id']
+            return {k: v for k, v in pos_data.items() if k not in excluded}
         
         kwargs = {}
         
@@ -3023,7 +3025,8 @@ class StrategyRegistry:
         if not strategy or 'legs' not in strategy:
             # Fallback: return all pos_data (for backward compatibility)
             # BUT exclude fields that are ALWAYS passed explicitly to close_position()
-            kwargs = {k: v for k, v in pos_data.items() if k not in ['pnl', 'pnl_pct', 'price']}
+            excluded_fields = ['pnl', 'pnl_pct', 'price', 'exit_reason', 'close_reason', 'position_id']
+            kwargs = {k: v for k, v in pos_data.items() if k not in excluded_fields}
             return kwargs
         
         kwargs = {}
@@ -3656,10 +3659,10 @@ def _api_call_internal(endpoint, cache_config, debug, debug_level, **kwargs):
                 elif debug or cache_config.get('debug', False):
                     print(f"[CACHE] ✓ Cache hit: {endpoint} ({len(cached_data) if hasattr(cached_data, '__len__') else '?'} records)")
                 
-                # ✅ OPTIMIZED: Return DataFrame directly without conversion!
-                # Flag '_is_dataframe' tells caller to skip pd.DataFrame() creation
+                # ✅ CONSISTENT: Always return list format for backward compatibility
+                # This ensures `if not response.get('data')` works correctly in all strategies
                 if isinstance(cached_data, pd.DataFrame):
-                    return {'data': cached_data, 'status': 'success', '_is_dataframe': True}
+                    return {'data': cached_data.to_dict('records'), 'status': 'success'}
                 return cached_data
             
             if debug_level >= 3:
@@ -3773,6 +3776,84 @@ def _api_call_internal(endpoint, cache_config, debug, debug_level, **kwargs):
         return None
 
 
+# ============================================================
+# API RESPONSE HELPERS
+# ============================================================
+def get_api_data(response, as_dataframe=True):
+    """
+    Universal helper to extract data from api_call response.
+    Works with both list and DataFrame formats from cache.
+    
+    Args:
+        response: Response dict from api_call()
+        as_dataframe: If True (default), always return DataFrame. 
+                      If False, return list of dicts.
+    
+    Returns:
+        DataFrame/list or None if no valid data
+    
+    Example:
+        # Get stock data as DataFrame
+        stock_df = get_api_data(api_call('/equities/eod/stock-prices', ...))
+        if stock_df is None:
+            print("No data!")
+        
+        # Get as list of dicts
+        records = get_api_data(response, as_dataframe=False)
+    """
+    if response is None:
+        return None
+    
+    data = response.get('data')
+    if data is None:
+        return None
+    
+    # Handle DataFrame (from cache)
+    if isinstance(data, pd.DataFrame):
+        if data.empty:
+            return None
+        return data if as_dataframe else data.to_dict('records')
+    
+    # Handle list (from API)
+    if not data:  # empty list
+        return None
+    
+    return pd.DataFrame(data) if as_dataframe else data
+
+
+def is_api_response_valid(response):
+    """
+    Check if api_call response contains valid non-empty data.
+    Works with both list and DataFrame formats.
+    
+    Args:
+        response: Response dict from api_call()
+    
+    Returns:
+        bool: True if response contains valid non-empty data
+    
+    Example:
+        response = api_call('/equities/eod/stock-prices', ...)
+        if not is_api_response_valid(response):
+            print("No data available!")
+            return
+        
+        # Safe to use response['data'] now
+        df = pd.DataFrame(response['data'])
+    """
+    if response is None:
+        return False
+    
+    data = response.get('data')
+    if data is None:
+        return False
+    
+    if isinstance(data, pd.DataFrame):
+        return not data.empty
+    
+    return bool(data)
+
+
 # ============================================================
 # OPTIONS DATA HELPERS
 # ============================================================
@@ -4764,6 +4845,39 @@ class PositionManager:
             self.sl_config = None
             self.sl_manager = None
     
+    # ================================================================
+    # ENTRY COST CALCULATION (wrapper for StrategyRegistry)
+    # ================================================================
+    def calculate_entry_cost(self, leg_data, contracts=1, is_short=None):
+        """
+        Calculate entry cost for current strategy (uses strategy_type from config).
+        
+        This is a convenience wrapper around StrategyRegistry.calculate_entry_cost()
+        that automatically uses strategy_type from self.config.
+        
+        Args:
+            leg_data: Dict with option data at entry
+            contracts: Number of contracts (default=1 for per-contract calculation)
+            is_short: Override for SHORT detection (True = sell to open, False = buy to open)
+                     Required for strategies like STRADDLE/IV_LEAN where leg names don't have 'short_' prefix
+        
+        Returns:
+            dict: {
+                'total': Total cost (positive for DEBIT, negative for CREDIT),
+                'per_leg': {leg_name: cost, ...},
+                'net_credit': bool,
+            }
+        
+        Example:
+            entry_cost = position_mgr.calculate_entry_cost(
+                {'call': call_data, 'put': put_data},
+                contracts=2,
+                is_short=True
+            )
+        """
+        strategy_type = self.config.get('strategy_type', 'STRADDLE')
+        return StrategyRegistry.calculate_entry_cost(strategy_type, leg_data, contracts, is_short)
+    
     # ================================================================
     # UNIVERSAL INTRINSIC VALUE CALCULATION METHOD
     # ================================================================
@@ -5422,16 +5536,26 @@ class PositionManager:
                     # Determine stop_type: 'expiration' (market data) or 'expiration_intrinsic' (no data)
                     stop_type = 'expiration_intrinsic' if used_intrinsic else 'expiration'
                     
-                    to_close.append({
+                    # ✅ AUTO-GENERATE close kwargs (so strategy code doesn't need to call generate_close_position_kwargs)
+                    strategy_type = position.get('strategy_type', 'STRADDLE')
+                    pos_data = price_data.get(position_id, {})
+                    close_kwargs = StrategyRegistry.generate_close_position_kwargs(strategy_type, pos_data)
+                    
+                    stop_info = {
                         'position_id': position_id,
                         'symbol': position['symbol'],
                         'stop_type': stop_type,
+                        'close_reason': stop_type,  # ✅ For strategy stats
+                        'stat_key': 'expiration_exits',  # ✅ For strategy stats
                         'stop_level': None,
                         'current_price': current_price,
                         'pnl': current_pnl,
                         'pnl_pct': current_pnl_pct,
-                        'settlement_type': 'intrinsic' if used_intrinsic else 'market'
-                    })
+                        'settlement_type': 'intrinsic' if used_intrinsic else 'market',
+                        **close_kwargs  # ✅ Include leg exit data automatically
+                    }
+                    
+                    to_close.append(stop_info)
                     
                     if self.debug:
                         print(f"[PositionManager] 📅 EXPIRATION: {position_id} expired on {expiration}")
@@ -5628,6 +5752,10 @@ class PositionManager:
                     # For other stop types: generic reason
                     stop_info['exit_reason'] = f"stop_loss_{stop_type}"
                 
+                # ✅ ADD close_reason and stat_key for strategy stats
+                stop_info['close_reason'] = stop_info['exit_reason']
+                stop_info['stat_key'] = 'stoploss_triggered'
+                
                 # ✅ ADD stop-loss metadata for CSV export (stop_threshold, actual_value)
                 # These fields are needed for detailed analysis of stop-loss triggers
                 if stop_type == 'pl_loss':
@@ -5653,6 +5781,12 @@ class PositionManager:
                     # Just merge them into stop_info (no need for second mapping!)
                     stop_info.update(intraday_data)
                 
+                # ✅ AUTO-GENERATE close kwargs (so strategy code doesn't need to call generate_close_position_kwargs)
+                strategy_type = position.get('strategy_type', 'STRADDLE')
+                pos_data = price_data.get(position_id, {})
+                close_kwargs = StrategyRegistry.generate_close_position_kwargs(strategy_type, pos_data)
+                stop_info.update(close_kwargs)
+                
                 to_close.append(stop_info)
                 
                 if self.debug:
@@ -5661,6 +5795,148 @@ class PositionManager:
         
         return to_close
     
+    def build_price_data(self, current_date, stock_price, options_df, get_option_func, 
+                        indicators=None, extra_fields_callback=None):
+        """
+        Build price_data dict for all open positions.
+        
+        Args:
+            current_date: Current backtest date
+            stock_price: Current underlying price
+            options_df: Options data for current date
+            get_option_func: Function to get option by (strike, exp, type)
+            indicators: Optional dict of indicators for current date
+                       All fields will be added to price_data with 'exit_' prefix
+                       (e.g., z_score → exit_z_score, iv_percentile → exit_iv_percentile)
+            extra_fields_callback: Optional function(position, price_data) to add custom fields
+                                  (e.g., directional stop fields, earnings data)
+        
+        Returns:
+            Dict[position_id, price_data] for all open positions
+        """
+        price_data = {}
+        
+        for position in self.get_open_positions():
+            # Get leg data from current market prices
+            leg_data = StrategyRegistry.get_leg_data_for_position(
+                position, options_df, get_option_func
+            )
+            
+            if leg_data is not None:
+                # Get strategy type
+                strategy_type = position.get('strategy_type', self.config.get('strategy_type', 'STRADDLE'))
+                
+                # Auto-generate price_data (framework calculates P&L automatically!)
+                price_data[position['id']] = StrategyRegistry.generate_price_data(
+                    strategy_type=strategy_type,
+                    leg_data=leg_data,
+                    underlying_price=stock_price,
+                    position=position
+                )
+                
+                # Add ALL indicators with 'exit_' prefix (universal for any strategy)
+                if indicators:
+                    for indicator_name, indicator_value in indicators.items():
+                        if indicator_value is not None:
+                            # Add with exit_ prefix if not already prefixed
+                            field_name = f'exit_{indicator_name}' if not indicator_name.startswith('exit_') else indicator_name
+                            price_data[position['id']][field_name] = indicator_value
+                
+                # Add custom fields via callback (e.g., directional stop fields)
+                if extra_fields_callback:
+                    extra_fields = extra_fields_callback(position, price_data[position['id']])
+                    if extra_fields:
+                        price_data[position['id']].update(extra_fields)
+        
+        return price_data
+    
+    def close_remaining_positions(self, final_date, stock_price, options_df, get_option_func, 
+                                  indicators=None):
+        """
+        Close all remaining open positions at end of backtest.
+        
+        Args:
+            final_date: Final backtest date
+            stock_price: Final underlying price
+            options_df: Options data for final date
+            get_option_func: Function to get option by (strike, exp, type)
+            indicators: Optional dict of indicators for final date
+        
+        Returns:
+            Total P&L from closing positions
+        """
+        if len(self.get_open_positions()) == 0:
+            return 0
+        
+        if self.debug:
+            print(f"\n⚠️  Closing {len(self.get_open_positions())} remaining open positions...")
+        
+        # Build price_data for all open positions
+        price_data = self.build_price_data(
+            final_date, stock_price, options_df, get_option_func, indicators
+        )
+        
+        # Close all positions
+        self.close_all_positions(final_date, price_data, 'end_of_backtest')
+        
+        # Calculate total P&L
+        total_pnl = sum(data.get('pnl', 0) for data in price_data.values())
+        
+        if self.debug:
+            print(f"  ✓ Closed {len(price_data)} positions at end of period")
+        
+        return total_pnl
+    
+    def close_position_by_signal(self, position_id, exit_date, price_data, close_reason='signal_exit'):
+        """
+        Close position manually by signal (z-score exit, earnings exit, etc.).
+        
+        This is a convenience method that handles all the boilerplate:
+        - Gets position data from price_data
+        - Generates close kwargs automatically
+        - Closes the position
+        - Returns pnl for capital update
+        
+        Args:
+            position_id: ID of position to close
+            exit_date: Current date
+            price_data: Dict from build_price_data() or check_positions() context
+            close_reason: Reason for closing (e.g., 'z_score_exit', 'earnings_exit')
+        
+        Returns:
+            float: P&L of the closed position
+            
+        Example:
+            if abs(z_score) <= config['z_score_exit']:
+                pnl = position_mgr.close_position_by_signal(
+                    position['id'], current_date, price_data, 'z_score_exit'
+                )
+                stats['signal_exits'] += 1
+                capital += pnl
+        """
+        # Get position data
+        pos_data = price_data.get(position_id, {})
+        pnl = pos_data.get('pnl', 0)
+        pnl_pct = pos_data.get('pnl_pct', 0)
+        
+        # Generate close kwargs automatically
+        strategy_type = self.config.get('strategy_type', 'STRADDLE')
+        kwargs = StrategyRegistry.generate_close_position_kwargs(strategy_type, pos_data)
+        
+        # Close position
+        self.close_position(
+            position_id=position_id,
+            exit_date=exit_date,
+            exit_price=0.0,
+            close_reason=close_reason,
+            pnl=pnl,
+            pnl_pct=pnl_pct,
+            stat_key='signal_exits',  # For consistency with other exits
+            **kwargs
+        )
+        
+        return pnl
+    
     def check_profit_target(self, current_date, stock_price, options_df, get_option_func):
         """
         Check all positions for profit target achievement.
@@ -5754,6 +6030,8 @@ class PositionManager:
                 to_close.append({
                     'position_id': position_id,
                     'symbol': position['symbol'],
+                    'close_reason': 'profit_target',  # ✅ For strategy stats
+                    'stat_key': 'profit_target_exits',  # ✅ For strategy stats
                     'pnl': current_pnl,
                     'pnl_pct': pnl_pct,
                     'target_pct': target_pct,
@@ -7404,6 +7682,138 @@ class ChartGenerator:
             print(f"Chart saved: {filename}")
         
         return filename
+    
+    @staticmethod
+    def create_optimization_summary(results_df, metric='sharpe', filename='optimization_summary.png', 
+                                    show_plots=True, silent=False):
+        """
+        Create 6-panel optimization summary chart.
+        
+        Panels:
+            1. Sharpe vs Return (colored by drawdown, sized by trades)
+            2. Win Rate vs Profit Factor (colored by Sharpe)
+            3. Sharpe distribution histogram
+            4. Trade counts distribution
+            5. Top 10 combinations by metric
+            6. Parameter heatmap (if exactly 2 params)
+        
+        Args:
+            results_df: DataFrame with optimization results
+            metric: Optimization metric ('sharpe', 'total_return', etc.)
+            filename: Output filename
+            show_plots: If True, display chart
+            silent: If True, suppress print output
+        
+        Returns:
+            str: Path to saved chart, or None if failed
+        
+        Example:
+            chart_path = ChartGenerator.create_optimization_summary(
+                results_df, metric='sharpe',
+                filename=os.path.join(folder, 'optimization_summary.png')
+            )
+        """
+        try:
+            import matplotlib.pyplot as plt
+            import seaborn as sns
+            sns.set_style("whitegrid")
+            
+            # Create figure with 6 subplots
+            fig = plt.figure(figsize=(20, 12))
+            fig.suptitle('Optimization Results Summary', fontsize=16, fontweight='bold', y=0.995)
+            
+            # 1. Sharpe vs Return (colored by drawdown, sized by trades)
+            ax1 = plt.subplot(2, 3, 1)
+            scatter1 = ax1.scatter(results_df['total_return'], results_df['sharpe'], 
+                                  c=results_df['max_drawdown'], s=results_df['total_trades']*5,
+                                  cmap='RdYlGn_r', alpha=0.6, edgecolors='black', linewidth=0.5)
+            ax1.set_xlabel('Total Return (%)')
+            ax1.set_ylabel('Sharpe Ratio')
+            ax1.set_title('Sharpe vs Return (size=trades, color=drawdown)')
+            plt.colorbar(scatter1, ax=ax1, label='Max Drawdown (%)')
+            ax1.grid(True, alpha=0.3)
+            
+            # 2. Win Rate vs Profit Factor (colored by Sharpe)
+            ax2 = plt.subplot(2, 3, 2)
+            scatter2 = ax2.scatter(results_df['win_rate'], results_df['profit_factor'],
+                                  c=results_df['sharpe'], s=100, cmap='viridis',
+                                  alpha=0.6, edgecolors='black', linewidth=0.5)
+            ax2.set_xlabel('Win Rate (%)')
+            ax2.set_ylabel('Profit Factor')
+            ax2.set_title('Win Rate vs Profit Factor (color=Sharpe)')
+            plt.colorbar(scatter2, ax=ax2, label='Sharpe Ratio')
+            ax2.grid(True, alpha=0.3)
+            
+            # 3. Distribution of Sharpe Ratios
+            ax3 = plt.subplot(2, 3, 3)
+            ax3.hist(results_df['sharpe'], bins=20, color='steelblue', alpha=0.7, edgecolor='black')
+            ax3.axvline(results_df['sharpe'].mean(), color='red', linestyle='--', 
+                       label=f'Mean: {results_df["sharpe"].mean():.2f}')
+            ax3.axvline(results_df['sharpe'].median(), color='green', linestyle='--', 
+                       label=f'Median: {results_df["sharpe"].median():.2f}')
+            ax3.set_xlabel('Sharpe Ratio')
+            ax3.set_ylabel('Frequency')
+            ax3.set_title('Distribution of Sharpe Ratios')
+            ax3.legend()
+            ax3.grid(True, alpha=0.3)
+            
+            # 4. Distribution of Trade Counts
+            ax4 = plt.subplot(2, 3, 4)
+            ax4.hist(results_df['total_trades'], bins=20, color='coral', alpha=0.7, edgecolor='black')
+            ax4.set_xlabel('Total Trades')
+            ax4.set_ylabel('Frequency')
+            ax4.set_title('Distribution of Trade Counts')
+            ax4.grid(True, alpha=0.3)
+            
+            # 5. Top 10 Combinations by metric
+            ax5 = plt.subplot(2, 3, 5)
+            top10 = results_df.nlargest(10, metric)
+            top10_labels = [f"#{i+1}" for i in range(len(top10))]
+            bars = ax5.barh(top10_labels, top10[metric], color='green', alpha=0.7, edgecolor='black')
+            ax5.set_xlabel(metric.replace('_', ' ').title())
+            ax5.set_title(f'Top 10 Combinations by {metric.replace("_", " ").title()}')
+            ax5.invert_yaxis()
+            ax5.grid(True, alpha=0.3, axis='x')
+            
+            # 6. Heatmap of parameter combinations (if exactly 2 params)
+            ax6 = plt.subplot(2, 3, 6)
+            # Identify parameter columns (exclude metric columns)
+            metric_cols = ['combination_id', 'is_valid', 'invalid_reason', 'total_return', 
+                          'sharpe', 'sortino', 'calmar', 'max_drawdown', 'win_rate', 
+                          'profit_factor', 'total_trades', 'avg_win', 'avg_loss',
+                          'volatility', 'stop_loss_type', 'stop_loss_value']
+            param_cols = [col for col in results_df.columns if col not in metric_cols]
+            
+            if len(param_cols) == 2:
+                # Create pivot table for heatmap
+                pivot = results_df.pivot_table(values=metric, index=param_cols[0], 
+                                            columns=param_cols[1], aggfunc='mean')
+                sns.heatmap(pivot, annot=True, fmt='.3f', cmap='RdYlGn', ax=ax6, 
+                           cbar_kws={'label': metric.replace('_', ' ').title()})
+                ax6.set_title(f'{metric.replace("_", " ").title()} Heatmap')
+            else:
+                ax6.text(0.5, 0.5, f'Heatmap requires\nexactly 2 parameters\n(found {len(param_cols)})', 
+                        ha='center', va='center', fontsize=14, transform=ax6.transAxes)
+                ax6.set_title(f'{metric.replace("_", " ").title()} Heatmap')
+                ax6.axis('off')
+            
+            plt.tight_layout()
+            plt.savefig(filename, dpi=150, bbox_inches='tight')
+            
+            if show_plots:
+                plt.show()
+            else:
+                plt.close()
+            
+            if not silent:
+                print(f"✓ Optimization chart saved: {filename}")
+            
+            return filename
+            
+        except Exception as e:
+            if not silent:
+                print(f"⚠️ Could not create optimization charts: {e}")
+            return None
 
 
 def create_stoploss_charts(analyzer, filename='stoploss_analysis.png', show_plots=True):
@@ -7707,8 +8117,13 @@ def format_params_string(config):
     # ═══════════════════════════════════════════════════════════════════════
     # 2. AUTOMATIC STRATEGY DETECTION (from STRATEGIES registry)
     # ═══════════════════════════════════════════════════════════════════════
+    # First try signature-based detection
     strategy_type_lower = detect_strategy_type(config)
     
+    # ✅ Fallback: Use explicit strategy_type from config if detection failed
+    if not strategy_type_lower and config.get('strategy_type'):
+        strategy_type_lower = config['strategy_type'].lower()
+    
     # Debug: Show detection result
     if config.get('debuginfo', 0) >= 2:
         print(f"[DEBUG format_params_string] Detected strategy: {strategy_type_lower}")
@@ -7729,15 +8144,32 @@ def format_params_string(config):
                 except Exception as e:
                     pass  # Will be handled below
             
+            # ✅ Helper: Get value from config OR nested configs (earnings_config, stop_loss_config)
+            def get_param_value(key):
+                """Get parameter value from config, earnings_config, or stop_loss_config"""
+                if key in config:
+                    return config[key]
+                # Check earnings_config
+                earnings_cfg = config.get('earnings_config', {})
+                if key in earnings_cfg:
+                    return earnings_cfg[key]
+                # Check stop_loss_config
+                sl_cfg = config.get('stop_loss_config', {})
+                if key in sl_cfg:
+                    return sl_cfg[key]
+                if key == 'stop_loss_pct' and 'value' in sl_cfg:
+                    return sl_cfg['value']
+                return None
+            
             # Format strategy-specific parameters
             for param_def in strategy['file_naming']['format']:
                 key = param_def['key']
                 code = param_def['code']
                 format_func = param_def['formatter']
                 
-                if key in config:
+                value = get_param_value(key)
+                if value is not None:
                     try:
-                        value = config[key]
                         formatted = format_func(value)
                         if code:
                             parts.append(f"{code}{formatted}")
@@ -7748,6 +8180,28 @@ def format_params_string(config):
                 # Debug: Show missing keys
                 elif config.get('debuginfo', 0) >= 2:
                     print(f"[DEBUG format_params_string] Missing key '{key}' in config for strategy {strategy_type_upper}")
+            
+            # ═══════════════════════════════════════════════════════════════════
+            # AUTO-FORMAT EARNINGS PARAMS (if earnings_config exists)
+            # ═══════════════════════════════════════════════════════════════════
+            earnings_cfg = config.get('earnings_config', {})
+            if earnings_cfg.get('mode') in ['trade_around', 'avoid']:
+                earnings_formats = [
+                    ('entry_days_before', 'ED', lambda x: f"{int(x)}"),
+                    ('exit_days_after', 'XD', lambda x: f"{int(x)}"),
+                    ('iv_percentile_min', 'IV', lambda x: f"{int(x)}" if x else None),
+                    ('min_implied_move', 'IM', lambda x: f"{int(x*100)}" if x else None),
+                ]
+                for key, code, fmt in earnings_formats:
+                    # Check both root config and earnings_config
+                    value = config.get(key) or earnings_cfg.get(key)
+                    if value is not None:
+                        try:
+                            formatted = fmt(value)
+                            if formatted and code:
+                                parts.append(f"{code}{formatted}")
+                        except:
+                            pass
         
         # Add stop-loss (if enabled)
         if config.get('stop_loss_enabled') and 'stop_loss_config' in config:
@@ -8512,6 +8966,80 @@ class StopLossConfig:
         return merged
 
 
+# ============================================================
+# BASELINE STOP-LOSS CONFIGURATION HELPER
+# ============================================================
+def configure_baseline_stop_loss(base_config, stop_loss_config, optimization_config, verbose=True):
+    """
+    Configure stop-loss for baseline test with pre-defined variables.
+    
+    Simplifies baseline configuration by:
+    1. Pre-defining ALL stop-loss variables (avoids NameError)
+    2. Using flat if/elif/else structure (avoids indentation errors)
+    3. Printing stop-loss info (if verbose)
+    4. Returning properly configured config
+    
+    Args:
+        base_config: Base configuration dict (e.g., optimized_config)
+        stop_loss_config: STOP_LOSS_CONFIG dict
+        optimization_config: OPTIMIZATION_CONFIG dict with param_grid
+        verbose: If True, print stop-loss configuration info
+    
+    Returns:
+        tuple: (configured_config, sl_values)
+            - configured_config: Config with proper stop_loss_config
+            - sl_values: Dict with extracted SL values for reference
+    
+    Example:
+        baseline_config, sl_values = configure_baseline_stop_loss(
+            optimized_config, STOP_LOSS_CONFIG, OPTIMIZATION_CONFIG
+        )
+    """
+    param_grid = optimization_config.get('param_grid', {})
+    sl_enabled = stop_loss_config.get('enable_in', {}).get('baseline', False)
+    
+    # Pre-define ALL stop-loss variables (avoids NameError in any branch)
+    sl_values = {
+        'simple': param_grid.get('stop_loss_values', [0.04])[0],
+        'pl_loss': param_grid.get('combined_pl_loss', [0.10])[0],
+        'directional': param_grid.get('combined_directional', [0.04])[0],
+        'logic': stop_loss_config.get('combined_settings', {}).get('logic', 'and'),
+        'enabled': sl_enabled,
+        'type': stop_loss_config.get('type', 'none')
+    }
+    
+    # Print info (if verbose)
+    if verbose:
+        if not sl_enabled:
+            print("Stop-Loss: DISABLED")
+        elif stop_loss_config.get('type') == 'combined':
+            logic_upper = sl_values['logic'].upper()
+            print(f"Stop-Loss: Combined {logic_upper} (P&L {sl_values['pl_loss']*100:.0f}% {logic_upper} Directional {sl_values['directional']*100:.0f}%) - ENABLED")
+        else:
+            sl_type = stop_loss_config.get('type', 'directional')
+            print(f"Stop-Loss: {sl_values['simple']*100:.0f}% {sl_type} - ENABLED")
+    
+    # Create configured config
+    configured_config = base_config.copy()
+    configured_config['stop_loss_enabled'] = sl_enabled
+    
+    # Configure stop_loss_config based on type (flat structure)
+    if not sl_enabled:
+        configured_config['stop_loss_config'] = {'enabled': False, 'type': 'none', 'value': 0}
+    elif stop_loss_config.get('type') == 'combined':
+        configured_config['stop_loss_config'] = stop_loss_config.copy()
+        configured_config['stop_loss_config']['combined_settings'] = {
+            'pl_loss': sl_values['pl_loss'],
+            'directional': sl_values['directional'],
+            'logic': sl_values['logic']
+        }
+    else:
+        configured_config['stop_loss_config'] = stop_loss_config.copy()
+        configured_config['stop_loss_config']['value'] = sl_values['simple']
+    
+    return configured_config, sl_values
+
+
 def create_stoploss_comparison_chart(results, filename='stoploss_comparison.png', show_plots=True):
     """Create comparison chart"""
     try:
@@ -8918,11 +9446,7 @@ def preload_data_universal(config, data_requests=None, debug=False):
                 
                 response = api_call(endpoint, cache_config, debug=debuginfo, **params)
                 if response and 'data' in response:
-                    # ✅ OPTIMIZED: Skip DataFrame creation if already DataFrame (from memory cache)
-                    if response.get('_is_dataframe'):
-                        df = response['data']
-                    else:
-                        df = pd.DataFrame(response['data'])
+                    df = pd.DataFrame(response['data'])
                     if len(df) > 0:
                         all_data.append(df)
         
@@ -8983,11 +9507,7 @@ def preload_data_universal(config, data_requests=None, debug=False):
                     
                     response = api_call(endpoint, cache_config, debug=debuginfo, **params)
                     if response and 'data' in response:
-                        # ✅ OPTIMIZED: Skip DataFrame creation if already DataFrame (from memory cache)
-                        if response.get('_is_dataframe'):
-                            df = response['data']  # Already a DataFrame!
-                        else:
-                            df = pd.DataFrame(response['data'])
+                        df = pd.DataFrame(response['data'])
                         if len(df) > 0:
                             # Add cp type if not in response
                             if cp_type and 'type' not in df.columns and 'optionType' not in df.columns:
@@ -9009,11 +9529,7 @@ def preload_data_universal(config, data_requests=None, debug=False):
             params = base_params.copy()
             response = api_call(endpoint, cache_config, debug=debuginfo, **params)
             if response and 'data' in response:
-                # ✅ OPTIMIZED: Skip DataFrame creation if already DataFrame (from memory cache)
-                if response.get('_is_dataframe'):
-                    df = response['data']
-                else:
-                    df = pd.DataFrame(response['data'])
+                df = pd.DataFrame(response['data'])
                 if len(df) > 0:
                     all_data.append(df)
         
@@ -9259,6 +9775,27 @@ def _auto_detect_requests(config):
         }
     })
     
+    # ========================================================
+    # AUTO-DETECT EARNINGS CALENDAR
+    # ========================================================
+    # Load earnings calendar if earnings_config is specified
+    # Works with ANY strategy type (STRADDLE, IRON_CONDOR, etc.)
+    earnings_config = config.get('earnings_config', {})
+    earnings_mode = earnings_config.get('mode')
+    
+    if earnings_mode in ['trade_around', 'avoid']:
+        print(f"   📅 Earnings mode: {earnings_mode} - loading earnings calendar")
+        requests.append({
+            'name': 'earnings',
+            'endpoint': '/equities/eod/history-earnings-calendar',
+            'params': {
+                'symbols': config['symbol'],
+                'startDate': config['start_date'],
+                'endDate': config['end_date']
+            },
+            'chunking': {'enabled': False}  # Single request (lightweight)
+        })
+    
     return requests
 
 
@@ -9579,6 +10116,82 @@ def _auto_process_dates(df):
     return df
 
 
+# ============================================================================
+# EARNINGS STRATEGY HELPERS
+# ============================================================================
+
+def parse_earnings_calendar(earnings_df):
+    """
+    Parse preloaded earnings DataFrame to list of dicts for strategy use.
+    
+    Framework loads earnings via _auto_detect_requests() when earnings_config['mode'] 
+    is set. This helper converts the DataFrame to a sorted list for iteration.
+    
+    Args:
+        earnings_df: Preloaded DataFrame from config.get('_preloaded_earnings')
+    
+    Returns:
+        list: [{'date': datetime.date, 'estimate': float, 'reported': float, 
+                'time_of_day': str}, ...]
+        Sorted by date ascending.
+    
+    Usage in strategy:
+        earnings_df = config.get('_preloaded_earnings', pd.DataFrame())
+        earnings_events = parse_earnings_calendar(earnings_df)
+        
+        for event in earnings_events:
+            earning_date = event['date']
+            # ... process event
+    """
+    from datetime import datetime
+    
+    if earnings_df is None or earnings_df.empty:
+        return []
+    
+    earnings_events = []
+    for _, record in earnings_df.iterrows():
+        earning_date = record.get('earning_date')
+        if earning_date:
+            # Handle both string and date formats
+            if isinstance(earning_date, str):
+                date_obj = datetime.strptime(earning_date, '%Y-%m-%d').date()
+            elif hasattr(earning_date, 'date'):
+                date_obj = earning_date.date()
+            else:
+                date_obj = earning_date
+            
+            earnings_events.append({
+                'date': date_obj,
+                'estimate': record.get('estimate'),
+                'reported': record.get('reported_earning'),
+                'time_of_day': record.get('time_of_day_code', 'UNK')
+            })
+    
+    return sorted(earnings_events, key=lambda x: x['date'])
+
+
+def find_next_trading_day(trading_days, target_date):
+    """
+    Find the next available trading day on or after target_date.
+    
+    Args:
+        trading_days: Sorted list of trading days (datetime.date objects)
+        target_date: Target date to find trading day for
+    
+    Returns:
+        datetime.date: Next trading day, or None if not found
+    
+    Usage:
+        trading_days = sorted(stock_df['date'].unique())
+        entry_day = find_next_trading_day(trading_days, earning_date - timedelta(days=1))
+        exit_day = find_next_trading_day(trading_days, earning_date + timedelta(days=1))
+    """
+    for day in trading_days:
+        if day >= target_date:
+            return day
+    return None
+
+
 # ============================================================================
 # INDICATOR PRE-CALCULATION SYSTEM - Universal helpers
 # ============================================================================
@@ -10052,6 +10665,10 @@ def optimize_parameters(base_config, param_grid, strategy_function,
     optimization_start_time = datetime.now()
     start_time_str = optimization_start_time.strftime('%Y-%m-%d %H:%M:%S')
     
+    # Detect preloaded data
+    preloaded_keys = [k for k in base_config.keys() if k.startswith('_preloaded_')]
+    has_preloaded_data = len(preloaded_keys) > 0
+    
     print("\n" + "="*80)
     print(" "*20 + "PARAMETER OPTIMIZATION")
     print("="*80)
@@ -10059,9 +10676,11 @@ def optimize_parameters(base_config, param_grid, strategy_function,
     print(f"Period: {base_config.get('start_date')} to {base_config.get('end_date')}")
     print(f"Optimization Metric: {optimization_metric}")
     print(f"Min Trades: {min_trades}")
-    print(f"🕐 Started: {start_time_str}")
     if max_drawdown_limit:
         print(f"Max Drawdown Limit: {max_drawdown_limit*100:.0f}%")
+    if has_preloaded_data:
+        print(f"✅ Preloaded data: {', '.join([k.replace('_preloaded_', '') for k in preloaded_keys])}")
+    print(f"🕐 Started: {start_time_str}")
     print("="*80 + "\n")
     
     # Generate all combinations
@@ -10201,6 +10820,42 @@ def optimize_parameters(base_config, param_grid, strategy_function,
             # ✨ CRITICAL: Enable stop-loss when combined_* params are used
             test_config['stop_loss_enabled'] = True
         
+        # ═══════════════════════════════════════════════════════════════════
+        # EARNINGS CONFIG SUPPORT (v2.22+)
+        # ═══════════════════════════════════════════════════════════════════
+        # If param_grid contains earnings-related parameters, automatically
+        # update earnings_config with them
+        # ✅ Use .get() NOT .pop() - keep params in test_config for format_params_string!
+        earnings_params = {}
+        if 'entry_days_before' in test_config:
+            earnings_params['entry_days_before'] = test_config['entry_days_before']
+        if 'exit_days_after' in test_config:
+            earnings_params['exit_days_after'] = test_config['exit_days_after']
+        if 'min_implied_move' in test_config:
+            earnings_params['min_implied_move'] = test_config['min_implied_move']
+        if 'iv_percentile_min' in test_config:
+            earnings_params['iv_percentile_min'] = test_config['iv_percentile_min']
+        if 'earnings_buffer_days' in test_config:
+            earnings_params['buffer_days'] = test_config['earnings_buffer_days']
+        
+        # If any earnings params exist, update earnings_config
+        if earnings_params:
+            if 'earnings_config' not in test_config:
+                test_config['earnings_config'] = {}
+            
+            # Merge earnings_params into earnings_config
+            test_config['earnings_config'].update(earnings_params)
+        
+        # ═══════════════════════════════════════════════════════════════════
+        # STOP-LOSS CONFIG SUPPORT
+        # ═══════════════════════════════════════════════════════════════════
+        # If param_grid contains stop_loss_pct, update stop_loss_config['value']
+        if 'stop_loss_pct' in test_config:
+            if 'stop_loss_config' not in test_config:
+                test_config['stop_loss_config'] = {}
+            test_config['stop_loss_config']['value'] = test_config['stop_loss_pct']
+            test_config['stop_loss_enabled'] = True
+        
         # Update name
         param_str = "_".join([f"{k}={v}" for k, v in zip(param_names, param_combo)])
         test_config['strategy_name'] = f"{base_config.get('strategy_name', 'Strategy')} [{param_str}]"
@@ -11217,7 +11872,7 @@ class UniversalCacheManager:
 __all__ = [
     'BacktestResults', 'BacktestAnalyzer', 'ResultsReporter',
     'ChartGenerator', 'ResultsExporter', 'run_backtest', 'run_backtest_with_stoploss',
-    'init_api', 'api_call', 'APIHelper', 'APIManager',
+    'init_api', 'api_call', 'get_api_data', 'is_api_response_valid', 'APIHelper', 'APIManager',
     'ResourceMonitor', 'create_progress_bar', 'update_progress', 'format_time',
     'StopLossManager', 'PositionManager', 'StopLossConfig',
     'calculate_stoploss_metrics', 'print_stoploss_section', 'create_stoploss_charts',

{ivolatility_backtesting-1.34 → ivolatility_backtesting-1.36}/ivolatility_backtesting.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ivolatility_backtesting
-Version: 1.34
+Version: 1.36
 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-1.34 → ivolatility_backtesting-1.36}/pyproject.toml

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