ivolatility-backtesting 2.163__tar.gz → 2.165__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. ivolatility_backtesting-2.165/PKG-INFO +253 -0
  2. ivolatility_backtesting-2.165/README.md +228 -0
  3. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/ivolatility_backtesting/ivolatility_backtesting.py +35 -2
  4. ivolatility_backtesting-2.165/ivolatility_backtesting.egg-info/PKG-INFO +253 -0
  5. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/ivolatility_backtesting.egg-info/SOURCES.txt +3 -0
  6. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/ivolatility_backtesting.egg-info/requires.txt +2 -0
  7. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/pyproject.toml +4 -3
  8. ivolatility_backtesting-2.165/tests/test_2164_stock_price_stops.py +64 -0
  9. ivolatility_backtesting-2.165/tests/test_2165_parquet_engine_error.py +55 -0
  10. ivolatility_backtesting-2.165/tests/test_2165_renamed_symbol.py +115 -0
  11. ivolatility_backtesting-2.163/PKG-INFO +0 -73
  12. ivolatility_backtesting-2.163/README.md +0 -49
  13. ivolatility_backtesting-2.163/ivolatility_backtesting.egg-info/PKG-INFO +0 -73
  14. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/ivolatility_backtesting/__init__.py +0 -0
  15. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/ivolatility_backtesting.egg-info/dependency_links.txt +0 -0
  16. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/ivolatility_backtesting.egg-info/top_level.txt +0 -0
  17. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/setup.cfg +0 -0
  18. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2142_fixes.py +0 -0
  19. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2144_duckdb_dedup.py +0 -0
  20. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2146_vix_vro.py +0 -0
  21. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2147_cents_multiplier.py +0 -0
  22. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2148_loader_memory.py +0 -0
  23. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2149_client_errors.py +0 -0
  24. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2150_prompt_patterns.py +0 -0
  25. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2152_cache_lock_and_rate_limit.py +0 -0
  26. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2153_cache_lock_kept.py +0 -0
  27. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2154_put_atm_legs.py +0 -0
  28. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2155_bar_prefetch.py +0 -0
  29. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2155_intraday_exits.py +0 -0
  30. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2155_ivx_stock_holes.py +0 -0
  31. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2155_key_redaction.py +0 -0
  32. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2155_long_expiry.py +0 -0
  33. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2155_opt_stop_merge.py +0 -0
  34. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2156_phantom_quotes.py +0 -0
  35. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2157_sl_symbol.py +0 -0
  36. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2158_default_path_golden.py +0 -0
  37. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2158_entry_time.py +0 -0
  38. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2159_entry_rule.py +0 -0
  39. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2160_day_price_order.py +0 -0
  40. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2160_exit_rule.py +0 -0
  41. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2160_option_lean_rule.py +0 -0
  42. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2160_prefetch_cancel.py +0 -0
  43. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2161_assignment.py +0 -0
  44. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2162_entry_minute_window.py +0 -0
  45. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_2163_rotation.py +0 -0
  46. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_price_ta_indicators.py +0 -0
  47. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_stock_loader_coverage.py +0 -0
  48. {ivolatility_backtesting-2.163 → ivolatility_backtesting-2.165}/tests/test_vix_percentile_direction.py +0 -0
@@ -0,0 +1,253 @@
1
+ Metadata-Version: 2.4
2
+ Name: ivolatility_backtesting
3
+ Version: 2.165
4
+ Summary: A universal backtesting framework for financial strategies using the IVolatility API.
5
+ Author-email: IVolatility <support@ivolatility.com>
6
+ Project-URL: Homepage, https://ivolatility.com
7
+ Keywords: backtesting,finance,trading,ivolatility
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Programming Language :: Python :: 3.9
10
+ Classifier: Programming Language :: Python :: 3.10
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Operating System :: OS Independent
15
+ Requires-Python: >=3.9
16
+ Description-Content-Type: text/markdown
17
+ Requires-Dist: pandas<3.0,>=1.5.0
18
+ Requires-Dist: numpy<3.0,>=1.21.0
19
+ Requires-Dist: matplotlib>=3.5.0
20
+ Requires-Dist: seaborn>=0.11.0
21
+ Requires-Dist: ivolatility>=1.9.6
22
+ Requires-Dist: psutil>=7.1.0
23
+ Requires-Dist: fastparquet>=2023.1.0
24
+ Requires-Dist: duckdb>=1.0.0
25
+
26
+ # IVolatility Backtesting Framework v1.32
27
+
28
+ A universal options backtesting framework powered by the IVolatility API.
29
+
30
+ ---
31
+
32
+ ## Supported Strategies
33
+
34
+ | Strategy | Description | Use Case |
35
+ |----------|-------------|----------|
36
+ | **STRADDLE** | Long/short ATM call + put | Volatility plays |
37
+ | **STRANGLE** | Long/short OTM call + put | Wide volatility plays |
38
+ | **IRON_CONDOR** | Short strangle + long wings | Range-bound income |
39
+ | **VERTICAL** | Bull/bear call or put spreads | Directional bets |
40
+ | **CALENDAR** | Same strike, different expiry | Time decay plays |
41
+
42
+ ---
43
+
44
+ ## Core Features
45
+
46
+ ### Data & Caching
47
+ - **EOD + Intraday bars** - Both timeframes supported for stocks & options
48
+ - **IVolatility API integration** - Options chains, underlying prices, IV data, earnings calendar
49
+ - **DuckDB caching** - Local storage for fast repeated backtests
50
+ - **ASYNC parallel loading** - ~10x faster data preload
51
+ - **Connection pooling** - ~5x faster API calls
52
+
53
+ ### Run Modes
54
+
55
+ | Mode | Function | Use Case |
56
+ |------|----------|----------|
57
+ | **Single Run** | `run_backtest()` | Test one specific configuration |
58
+ | **Baseline** | `run_optimization(run_baseline=True)` | Reference benchmark (combo_id=0) |
59
+ | **Combinations** | `run_optimization()` | Grid search to find optimal params |
60
+ | **Chunked** | `run_optimization_chunked()` | Large grids with memory management |
61
+
62
+ #### Single Run
63
+ Run one backtest with fixed parameters. Use for testing a specific strategy configuration.
64
+ ```python
65
+ results = run_backtest(strategy_fn, config)
66
+ ```
67
+
68
+ #### Baseline
69
+ Reference run using `base_config` values before testing combinations. Saved as `combo_id=0` for comparison.
70
+ ```python
71
+ all_results = run_optimization(
72
+ base_config=config,
73
+ param_grid=param_grid,
74
+ run_baseline=True # combo_id=0 uses base_config values
75
+ )
76
+ ```
77
+
78
+ #### Combinations
79
+ Grid search across all parameter combinations. Each combo gets a unique `combo_id`.
80
+ ```python
81
+ param_grid = {
82
+ 'z_entry': [-2.0, -1.5, -1.0],
83
+ 'z_exit': [0.5, 1.0],
84
+ 'dte_target': [30, 45]
85
+ }
86
+ # Runs 3 × 2 × 2 = 12 combinations + baseline = 13 total
87
+ all_results = run_optimization(
88
+ base_config=config,
89
+ param_grid=param_grid,
90
+ run_baseline=True
91
+ )
92
+ ```
93
+
94
+ #### Chunked Optimization
95
+ Memory-efficient mode for large parameter spaces. Processes in batches.
96
+ ```python
97
+ run_optimization_chunked(
98
+ base_config=config,
99
+ param_grid=large_grid, # 1000+ combinations
100
+ chunk_size=50,
101
+ run_baseline=True
102
+ )
103
+ ```
104
+
105
+ ### Supported Indicators
106
+
107
+ | Indicator | Source | Description |
108
+ |-----------|--------|-------------|
109
+ | `iv_rank` | Options | Current IV position in historical range (0-100) |
110
+ | `iv_rank_ivx` | IVX API | IV Rank from pre-calculated IVX data (faster) |
111
+ | `iv_percentile_ivx` | IVX API | IV Percentile from IVX data |
112
+ | `iv_lean_zscore` | Options | Call-Put IV spread normalized (mean reversion) |
113
+ | `iv_lean_zscore_ivx` | IVX API | IV Lean Z-score from IVX (faster) |
114
+ | `iv_term_structure` | IVX API | Volatility curve slope across tenors |
115
+ | `iv_skew` | Options | Put/Call IV skew at target delta |
116
+ | `vix_percentile` | VIX | VIX percentile rank over lookback |
117
+ | `realized_vol` | Stock | Historical volatility (annualized) |
118
+
119
+ ### Entry Signals
120
+ - **Threshold-based** - Enter when indicator crosses level
121
+ - **Z-score signals** - Mean reversion entries
122
+ - **Delta-based selection** - Select strikes by delta target
123
+ - **Custom indicators** - Extensible via INDICATOR_REGISTRY
124
+
125
+ ### Position & P&L Management
126
+ - **PositionManager** - Track open positions, calculate real-time P&L
127
+ - **Greeks tracking** - Delta, gamma, theta, vega per leg
128
+ - **Capital at risk** - 1.5x safety buffer for EOD backtests
129
+ - **Multi-leg support** - Spreads, condors, straddles
130
+
131
+ ### Exit Management (StopLossManager)
132
+ - **DTE-based exit** - Close at target days to expiry
133
+ - **Stop-loss types:**
134
+ - Directional (underlying moves X%)
135
+ - P&L-based (position loses X%)
136
+ - Combined (both conditions required)
137
+ - **Profit targets** - Close at X% gain (same manager handles SL + PT)
138
+ - **Intraday monitoring** - Check stops on each bar
139
+ - **Earnings blackout** - Skip entries near earnings dates
140
+
141
+ ### Analytics & Reporting
142
+ - **BacktestAnalyzer** - Sharpe ratio, max drawdown, win rate, profit factor
143
+ - **Equity curve** - Track portfolio value over time
144
+ - **ResultsReporter** - Generate summary tables and statistics
145
+ - **Trade-level details** - Entry/exit prices, Greeks, stop levels
146
+
147
+ ### Visualization (ChartGenerator)
148
+ - **Equity curve charts** - Portfolio growth over time
149
+ - **Drawdown analysis** - Visualize underwater periods
150
+ - **Stop-loss analysis** - Compare exit reasons
151
+ - **Optimization heatmaps** - Parameter sensitivity
152
+ - **Monthly returns** - Calendar view of performance
153
+
154
+ ### Optimization
155
+ - **Parameter grid search** - Test multiple configurations
156
+ - **Parallel execution** - Run combinations concurrently
157
+ - **Memory-efficient chunking** - Handle large parameter spaces
158
+ - **Results comparison** - Side-by-side analysis
159
+
160
+ ---
161
+
162
+ ## Architecture
163
+
164
+ ```
165
+ ┌─────────────────────────────────────────────────────────┐
166
+ │ User Notebook │
167
+ ├─────────────────────────────────────────────────────────┤
168
+ │ run_backtest() / run_backtest_with_stoploss() │
169
+ ├──────────────┬──────────────┬───────────────────────────┤
170
+ │ PositionMgr │ StopLossMgr │ DuckDBIndicatorManager │
171
+ ├──────────────┴──────────────┴───────────────────────────┤
172
+ │ OptionsChunkManager (async) │
173
+ ├─────────────────────────────────────────────────────────┤
174
+ │ DuckDBCacheManager │
175
+ ├─────────────────────────────────────────────────────────┤
176
+ │ APIManager → IVolatility API │
177
+ └─────────────────────────────────────────────────────────┘
178
+ ```
179
+
180
+ ---
181
+
182
+ ## Key Classes
183
+
184
+ | Class | Purpose |
185
+ |-------|---------|
186
+ | `APIManager` | Unified API access with auth |
187
+ | `DuckDBCacheManager` | Persistent data caching (EOD + intraday) |
188
+ | `OptionsChunkManager` | Async parallel data loading |
189
+ | `DuckDBIndicatorManager` | Pre-calculate & cache indicators |
190
+ | `PositionManager` | Track positions, calculate P&L, manage Greeks |
191
+ | `StopLossManager` | Monitor stops + profit targets (intraday capable) |
192
+ | `StrategyRegistry` | Strategy definitions & metadata |
193
+ | `BacktestAnalyzer` | Calculate metrics: Sharpe, drawdown, win rate |
194
+ | `ResultsReporter` | Generate summary tables & statistics |
195
+ | `ChartGenerator` | Create equity curves, heatmaps, analysis charts |
196
+
197
+ ---
198
+
199
+ ## Quick Start
200
+
201
+ ```python
202
+ from ivolatility_backtesting import run_backtest, preload_data
203
+
204
+ # Configure
205
+ config = {
206
+ 'symbol': 'SPY',
207
+ 'start_date': '2024-01-01',
208
+ 'end_date': '2024-12-31',
209
+ 'strategy_type': 'STRADDLE',
210
+ 'dte_target': 30,
211
+ 'entry_signal': 'iv_rank',
212
+ 'entry_threshold': 50,
213
+ }
214
+
215
+ # Preload data (uses async for speed)
216
+ preloaded = preload_data(config)
217
+
218
+ # Run backtest
219
+ results = run_backtest(
220
+ strategy_function=straddle_strategy,
221
+ config={**config, **preloaded}
222
+ )
223
+ ```
224
+
225
+ ---
226
+
227
+ ## Performance
228
+
229
+ | Metric | Before v1.32 | After v1.32 |
230
+ |--------|--------------|-------------|
231
+ | Data preload | ~60s | ~6s (10x faster) |
232
+ | API calls | Sequential | Pooled (5x faster) |
233
+ | Memory usage | High | Chunked (stable) |
234
+ | DuckDB stability | Crashes | Legacy mode (stable) |
235
+
236
+ ---
237
+
238
+ ## Integration with Claude
239
+
240
+ Use `system_straddle_simple_20260206.promt` as a system prompt to have Claude generate backtesting notebooks. Claude will:
241
+
242
+ 1. Ask about strategy parameters
243
+ 2. Generate complete notebook code
244
+ 3. Include stop-loss/profit-target configuration
245
+ 4. Add earnings blackout if requested
246
+
247
+ ---
248
+
249
+ ## Links
250
+
251
+ - **GitLab:** `gitlab.ivolatility.com/ivolatility/ivolatility-backtesting`
252
+ - **API Docs:** `ivolatility.com/api/openapi.yml`
253
+ - **Changelog:** See `CHANGELOG.md` in repo
@@ -0,0 +1,228 @@
1
+ # IVolatility Backtesting Framework v1.32
2
+
3
+ A universal options backtesting framework powered by the IVolatility API.
4
+
5
+ ---
6
+
7
+ ## Supported Strategies
8
+
9
+ | Strategy | Description | Use Case |
10
+ |----------|-------------|----------|
11
+ | **STRADDLE** | Long/short ATM call + put | Volatility plays |
12
+ | **STRANGLE** | Long/short OTM call + put | Wide volatility plays |
13
+ | **IRON_CONDOR** | Short strangle + long wings | Range-bound income |
14
+ | **VERTICAL** | Bull/bear call or put spreads | Directional bets |
15
+ | **CALENDAR** | Same strike, different expiry | Time decay plays |
16
+
17
+ ---
18
+
19
+ ## Core Features
20
+
21
+ ### Data & Caching
22
+ - **EOD + Intraday bars** - Both timeframes supported for stocks & options
23
+ - **IVolatility API integration** - Options chains, underlying prices, IV data, earnings calendar
24
+ - **DuckDB caching** - Local storage for fast repeated backtests
25
+ - **ASYNC parallel loading** - ~10x faster data preload
26
+ - **Connection pooling** - ~5x faster API calls
27
+
28
+ ### Run Modes
29
+
30
+ | Mode | Function | Use Case |
31
+ |------|----------|----------|
32
+ | **Single Run** | `run_backtest()` | Test one specific configuration |
33
+ | **Baseline** | `run_optimization(run_baseline=True)` | Reference benchmark (combo_id=0) |
34
+ | **Combinations** | `run_optimization()` | Grid search to find optimal params |
35
+ | **Chunked** | `run_optimization_chunked()` | Large grids with memory management |
36
+
37
+ #### Single Run
38
+ Run one backtest with fixed parameters. Use for testing a specific strategy configuration.
39
+ ```python
40
+ results = run_backtest(strategy_fn, config)
41
+ ```
42
+
43
+ #### Baseline
44
+ Reference run using `base_config` values before testing combinations. Saved as `combo_id=0` for comparison.
45
+ ```python
46
+ all_results = run_optimization(
47
+ base_config=config,
48
+ param_grid=param_grid,
49
+ run_baseline=True # combo_id=0 uses base_config values
50
+ )
51
+ ```
52
+
53
+ #### Combinations
54
+ Grid search across all parameter combinations. Each combo gets a unique `combo_id`.
55
+ ```python
56
+ param_grid = {
57
+ 'z_entry': [-2.0, -1.5, -1.0],
58
+ 'z_exit': [0.5, 1.0],
59
+ 'dte_target': [30, 45]
60
+ }
61
+ # Runs 3 × 2 × 2 = 12 combinations + baseline = 13 total
62
+ all_results = run_optimization(
63
+ base_config=config,
64
+ param_grid=param_grid,
65
+ run_baseline=True
66
+ )
67
+ ```
68
+
69
+ #### Chunked Optimization
70
+ Memory-efficient mode for large parameter spaces. Processes in batches.
71
+ ```python
72
+ run_optimization_chunked(
73
+ base_config=config,
74
+ param_grid=large_grid, # 1000+ combinations
75
+ chunk_size=50,
76
+ run_baseline=True
77
+ )
78
+ ```
79
+
80
+ ### Supported Indicators
81
+
82
+ | Indicator | Source | Description |
83
+ |-----------|--------|-------------|
84
+ | `iv_rank` | Options | Current IV position in historical range (0-100) |
85
+ | `iv_rank_ivx` | IVX API | IV Rank from pre-calculated IVX data (faster) |
86
+ | `iv_percentile_ivx` | IVX API | IV Percentile from IVX data |
87
+ | `iv_lean_zscore` | Options | Call-Put IV spread normalized (mean reversion) |
88
+ | `iv_lean_zscore_ivx` | IVX API | IV Lean Z-score from IVX (faster) |
89
+ | `iv_term_structure` | IVX API | Volatility curve slope across tenors |
90
+ | `iv_skew` | Options | Put/Call IV skew at target delta |
91
+ | `vix_percentile` | VIX | VIX percentile rank over lookback |
92
+ | `realized_vol` | Stock | Historical volatility (annualized) |
93
+
94
+ ### Entry Signals
95
+ - **Threshold-based** - Enter when indicator crosses level
96
+ - **Z-score signals** - Mean reversion entries
97
+ - **Delta-based selection** - Select strikes by delta target
98
+ - **Custom indicators** - Extensible via INDICATOR_REGISTRY
99
+
100
+ ### Position & P&L Management
101
+ - **PositionManager** - Track open positions, calculate real-time P&L
102
+ - **Greeks tracking** - Delta, gamma, theta, vega per leg
103
+ - **Capital at risk** - 1.5x safety buffer for EOD backtests
104
+ - **Multi-leg support** - Spreads, condors, straddles
105
+
106
+ ### Exit Management (StopLossManager)
107
+ - **DTE-based exit** - Close at target days to expiry
108
+ - **Stop-loss types:**
109
+ - Directional (underlying moves X%)
110
+ - P&L-based (position loses X%)
111
+ - Combined (both conditions required)
112
+ - **Profit targets** - Close at X% gain (same manager handles SL + PT)
113
+ - **Intraday monitoring** - Check stops on each bar
114
+ - **Earnings blackout** - Skip entries near earnings dates
115
+
116
+ ### Analytics & Reporting
117
+ - **BacktestAnalyzer** - Sharpe ratio, max drawdown, win rate, profit factor
118
+ - **Equity curve** - Track portfolio value over time
119
+ - **ResultsReporter** - Generate summary tables and statistics
120
+ - **Trade-level details** - Entry/exit prices, Greeks, stop levels
121
+
122
+ ### Visualization (ChartGenerator)
123
+ - **Equity curve charts** - Portfolio growth over time
124
+ - **Drawdown analysis** - Visualize underwater periods
125
+ - **Stop-loss analysis** - Compare exit reasons
126
+ - **Optimization heatmaps** - Parameter sensitivity
127
+ - **Monthly returns** - Calendar view of performance
128
+
129
+ ### Optimization
130
+ - **Parameter grid search** - Test multiple configurations
131
+ - **Parallel execution** - Run combinations concurrently
132
+ - **Memory-efficient chunking** - Handle large parameter spaces
133
+ - **Results comparison** - Side-by-side analysis
134
+
135
+ ---
136
+
137
+ ## Architecture
138
+
139
+ ```
140
+ ┌─────────────────────────────────────────────────────────┐
141
+ │ User Notebook │
142
+ ├─────────────────────────────────────────────────────────┤
143
+ │ run_backtest() / run_backtest_with_stoploss() │
144
+ ├──────────────┬──────────────┬───────────────────────────┤
145
+ │ PositionMgr │ StopLossMgr │ DuckDBIndicatorManager │
146
+ ├──────────────┴──────────────┴───────────────────────────┤
147
+ │ OptionsChunkManager (async) │
148
+ ├─────────────────────────────────────────────────────────┤
149
+ │ DuckDBCacheManager │
150
+ ├─────────────────────────────────────────────────────────┤
151
+ │ APIManager → IVolatility API │
152
+ └─────────────────────────────────────────────────────────┘
153
+ ```
154
+
155
+ ---
156
+
157
+ ## Key Classes
158
+
159
+ | Class | Purpose |
160
+ |-------|---------|
161
+ | `APIManager` | Unified API access with auth |
162
+ | `DuckDBCacheManager` | Persistent data caching (EOD + intraday) |
163
+ | `OptionsChunkManager` | Async parallel data loading |
164
+ | `DuckDBIndicatorManager` | Pre-calculate & cache indicators |
165
+ | `PositionManager` | Track positions, calculate P&L, manage Greeks |
166
+ | `StopLossManager` | Monitor stops + profit targets (intraday capable) |
167
+ | `StrategyRegistry` | Strategy definitions & metadata |
168
+ | `BacktestAnalyzer` | Calculate metrics: Sharpe, drawdown, win rate |
169
+ | `ResultsReporter` | Generate summary tables & statistics |
170
+ | `ChartGenerator` | Create equity curves, heatmaps, analysis charts |
171
+
172
+ ---
173
+
174
+ ## Quick Start
175
+
176
+ ```python
177
+ from ivolatility_backtesting import run_backtest, preload_data
178
+
179
+ # Configure
180
+ config = {
181
+ 'symbol': 'SPY',
182
+ 'start_date': '2024-01-01',
183
+ 'end_date': '2024-12-31',
184
+ 'strategy_type': 'STRADDLE',
185
+ 'dte_target': 30,
186
+ 'entry_signal': 'iv_rank',
187
+ 'entry_threshold': 50,
188
+ }
189
+
190
+ # Preload data (uses async for speed)
191
+ preloaded = preload_data(config)
192
+
193
+ # Run backtest
194
+ results = run_backtest(
195
+ strategy_function=straddle_strategy,
196
+ config={**config, **preloaded}
197
+ )
198
+ ```
199
+
200
+ ---
201
+
202
+ ## Performance
203
+
204
+ | Metric | Before v1.32 | After v1.32 |
205
+ |--------|--------------|-------------|
206
+ | Data preload | ~60s | ~6s (10x faster) |
207
+ | API calls | Sequential | Pooled (5x faster) |
208
+ | Memory usage | High | Chunked (stable) |
209
+ | DuckDB stability | Crashes | Legacy mode (stable) |
210
+
211
+ ---
212
+
213
+ ## Integration with Claude
214
+
215
+ Use `system_straddle_simple_20260206.promt` as a system prompt to have Claude generate backtesting notebooks. Claude will:
216
+
217
+ 1. Ask about strategy parameters
218
+ 2. Generate complete notebook code
219
+ 3. Include stop-loss/profit-target configuration
220
+ 4. Add earnings blackout if requested
221
+
222
+ ---
223
+
224
+ ## Links
225
+
226
+ - **GitLab:** `gitlab.ivolatility.com/ivolatility/ivolatility-backtesting`
227
+ - **API Docs:** `ivolatility.com/api/openapi.yml`
228
+ - **Changelog:** See `CHANGELOG.md` in repo
@@ -8,6 +8,8 @@
8
8
  # 4. ASYNC parallel chunk loading (~10x faster preload)
9
9
  # ============================================================
10
10
 
11
+ from __future__ import annotations
12
+
11
13
  import atexit
12
14
  import bisect
13
15
  import collections
@@ -8429,7 +8431,25 @@ def _is_client_error(exc):
8429
8431
  return status is not None and 400 <= status < 500 and status != 429
8430
8432
 
8431
8433
 
8432
- def api_call(endpoint, cache_config=None, debug=False, max_retries=3, skip_parquet_cache=False,
8434
+ def _stamp_requested_symbol(normalized, endpoint, params):
8435
+ """API returns the pre-rename symbol in older rows (FB for META); readers key on `symbol`, so stamp the requested one."""
8436
+ if not isinstance(normalized, dict) or '/equities/eod/stock-prices' not in str(endpoint):
8437
+ return normalized
8438
+ sym = params.get('symbol')
8439
+ if not isinstance(sym, str) or not sym.strip() or ',' in sym or ' ' in sym.strip():
8440
+ return normalized
8441
+ data = normalized.get('data')
8442
+ if isinstance(data, pd.DataFrame):
8443
+ if not data.empty:
8444
+ data = data.copy()
8445
+ data['symbol'] = sym
8446
+ normalized = dict(normalized, data=data)
8447
+ elif isinstance(data, list) and data and isinstance(data[0], dict):
8448
+ normalized = dict(normalized, data=[dict(r, symbol=sym) for r in data])
8449
+ return normalized
8450
+
8451
+
8452
+ def api_call(endpoint, cache_config=None, debug=False, max_retries=3, skip_parquet_cache=False,
8433
8453
  _chunk_info=None, **kwargs):
8434
8454
  """
8435
8455
  Make API call with automatic response normalization, caching, and retry logic
@@ -8890,6 +8910,7 @@ def _api_call_internal(endpoint, cache_config, debug, debug_level, skip_parquet_
8890
8910
  # TIMING: Response normalization
8891
8911
  t_normalize_start = time.perf_counter()
8892
8912
  normalized = APIHelper.normalize_response(response, debug=debug)
8913
+ normalized = _stamp_requested_symbol(normalized, endpoint, kwargs)
8893
8914
  t_normalize_elapsed = (time.perf_counter() - t_normalize_start) * 1000 # ms
8894
8915
  _bt_logger.info(f"[DIAG] NORMALIZE END {_ci_str} thread={_tid_diag} elapsed={t_normalize_elapsed:.0f}ms")
8895
8916
 
@@ -14333,11 +14354,14 @@ class PositionManager:
14333
14354
  'symbol': position.get('symbol')
14334
14355
  }
14335
14356
 
14357
+ _st = position.get('strategy_type', 'LONG')
14358
+ if _st in STOCK_STRATEGY_TYPES:
14359
+ _st = 'SHORT' if _st in SHORT_STOCK_TYPES else 'LONG'
14336
14360
  triggered, stop_level, stop_type, intraday_data = self.sl_manager.check_stop(
14337
14361
  position_id=position_id,
14338
14362
  current_price=check_value,
14339
14363
  current_date=current_date,
14340
- position_type=position.get('strategy_type', 'LONG'),
14364
+ position_type=_st,
14341
14365
  **stop_kwargs
14342
14366
  )
14343
14367
 
@@ -14827,6 +14851,7 @@ class PositionManager:
14827
14851
  pnl_pct = (pnl / entry_cost * 100) if entry_cost > 0 else 0
14828
14852
  price_data[pos_id] = {
14829
14853
  'current_price': stock_price,
14854
+ 'price': stock_price,
14830
14855
  'pnl': pnl,
14831
14856
  'pnl_pct': pnl_pct,
14832
14857
  'underlying_price': stock_price,
@@ -29715,6 +29740,10 @@ def get_cache_config(disk_enabled: bool = True, memory_enabled: bool = True,
29715
29740
  # ============================================================
29716
29741
  # CACHE MODES (unified caching architecture)
29717
29742
  # ============================================================
29743
+ _PARQUET_ENGINE_MISSING = ("parquet engine missing: cached chunks cannot be written, so the backtest would run on 0 rows; "
29744
+ "run `pip install fastparquet` (installed with ivolatility_backtesting>=2.165) or `pip install pyarrow`")
29745
+
29746
+
29718
29747
  class CacheMode:
29719
29748
  """Cache mode constants for unified caching architecture."""
29720
29749
  ORIGINAL_PARQUET = 'original_parquet' # pandas reads Parquet one-by-one (legacy)
@@ -30034,6 +30063,8 @@ class UniversalCacheManager:
30034
30063
  df.to_parquet(file_path, compression='snappy')
30035
30064
  else:
30036
30065
  df.to_parquet(file_path)
30066
+ except ImportError as e:
30067
+ raise RuntimeError(_PARQUET_ENGINE_MISSING) from e
30037
30068
  except Exception as e:
30038
30069
  if self.debug:
30039
30070
  print(f"[CACHE] ❌ Error saving to disk: {e}")
@@ -30535,6 +30566,8 @@ class UniversalCacheManager:
30535
30566
  df.to_parquet(filepath, index=False, compression='snappy')
30536
30567
  else:
30537
30568
  df.to_parquet(filepath, index=False)
30569
+ except ImportError as e:
30570
+ raise RuntimeError(_PARQUET_ENGINE_MISSING) from e
30538
30571
  except Exception as e:
30539
30572
  if self.debug:
30540
30573
  print(f"[CACHE] ❌ Error saving chunk: {e}")