aether-quant 0.0.1__py3-none-any.whl

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 (99) hide show
  1. aether_quant-0.0.1.dist-info/METADATA +7 -0
  2. aether_quant-0.0.1.dist-info/RECORD +99 -0
  3. aether_quant-0.0.1.dist-info/WHEEL +5 -0
  4. aether_quant-0.0.1.dist-info/entry_points.txt +2 -0
  5. aether_quant-0.0.1.dist-info/licenses/LICENSE +133 -0
  6. aether_quant-0.0.1.dist-info/top_level.txt +13 -0
  7. analyzer/README.md +69 -0
  8. analyzer/__init__.py +17 -0
  9. analyzer/market_analyzer.py +521 -0
  10. aq_cli.py +3633 -0
  11. audit/README.md +47 -0
  12. audit/__init__.py +38 -0
  13. audit/hash_chain.py +52 -0
  14. audit/postgres_audit.py +61 -0
  15. audit/postgres_worker.py +402 -0
  16. audit/redis_queue.py +124 -0
  17. audit/status_export.py +62 -0
  18. data_pipeline/README.md +257 -0
  19. data_pipeline/__init__.py +6 -0
  20. data_pipeline/bar_synthesis.py +97 -0
  21. data_pipeline/dividend_backfill.py +243 -0
  22. data_pipeline/factor_file_backfill.py +276 -0
  23. data_pipeline/fetch.py +206 -0
  24. data_pipeline/fred_backfill.py +435 -0
  25. data_pipeline/ib_backfill.py +287 -0
  26. data_pipeline/v2_manifest.py +75 -0
  27. data_pipeline/yfinance_backfill.py +501 -0
  28. evaluation/README.md +152 -0
  29. evaluation/__init__.py +73 -0
  30. evaluation/ablation.py +310 -0
  31. evaluation/benchmark_comparison.py +195 -0
  32. evaluation/confidence_threshold_calibration.py +157 -0
  33. evaluation/factor_neutralization_check.py +94 -0
  34. evaluation/feature_parity.py +321 -0
  35. evaluation/feature_reconciliation.py +286 -0
  36. evaluation/impact_model.py +77 -0
  37. evaluation/kill_switch_replay.py +186 -0
  38. evaluation/limit_fill_simulator.py +152 -0
  39. evaluation/model_predictions.py +192 -0
  40. evaluation/monte_carlo.py +161 -0
  41. evaluation/public_benchmarks.py +117 -0
  42. evaluation/rank_book_simulator.py +494 -0
  43. evaluation/rank_ic_core.py +204 -0
  44. evaluation/rank_signal_calibration.py +690 -0
  45. evaluation/rolling_ic_gate_calibration.py +190 -0
  46. evaluation/rolling_ic_gate_replay.py +138 -0
  47. execution/README.md +281 -0
  48. execution/__init__.py +80 -0
  49. execution/config_cache.py +48 -0
  50. execution/cost_model.py +213 -0
  51. execution/lean_config_render.py +131 -0
  52. execution/live_credentials.py +38 -0
  53. execution/live_credentials_io.py +52 -0
  54. execution/order_gate.py +388 -0
  55. execution/paper_readiness.py +181 -0
  56. execution/paper_readiness_io.py +54 -0
  57. execution/paper_readiness_report.py +103 -0
  58. execution/paper_readiness_scheduler.py +137 -0
  59. execution/reconciliation.py +160 -0
  60. execution/runtime_config_io.py +38 -0
  61. execution/secret_scan.py +73 -0
  62. features/README.md +77 -0
  63. features/__init__.py +137 -0
  64. features/alt_data_features.py +154 -0
  65. features/bond_features.py +275 -0
  66. features/cross_asset_sensitivity.py +79 -0
  67. features/derivatives_macro_features.py +72 -0
  68. features/macro_features.py +79 -0
  69. features/options_greeks.py +329 -0
  70. features/sector_map.py +53 -0
  71. features/technical_indicators.py +185 -0
  72. generate_backtest_report.py +311 -0
  73. generate_evaluation_report.py +712 -0
  74. inference/README.md +105 -0
  75. inference/__init__.py +36 -0
  76. inference/exported_model.py +929 -0
  77. inference/parallel_inference.py +160 -0
  78. inference/strategy_selector_inference.py +75 -0
  79. json_safety.py +130 -0
  80. portfolio/README.md +447 -0
  81. portfolio/__init__.py +41 -0
  82. portfolio/book_construction.py +786 -0
  83. portfolio/book_neutrality.py +178 -0
  84. portfolio/hrp_allocation.py +159 -0
  85. portfolio/options_arbitrage_detector.py +232 -0
  86. portfolio/options_assignment_risk.py +119 -0
  87. portfolio/options_margin_sizing.py +333 -0
  88. portfolio/options_strategy.py +1999 -0
  89. portfolio/rank_signal.py +219 -0
  90. portfolio/rolling_ic_gate.py +183 -0
  91. risk/README.md +275 -0
  92. risk/__init__.py +38 -0
  93. risk/asset_class_router.py +584 -0
  94. risk/forex_risk.py +158 -0
  95. risk/futures_risk.py +202 -0
  96. risk/kill_switch.py +261 -0
  97. risk/manual_override.py +118 -0
  98. risk/position_sizing.py +303 -0
  99. risk/rl_sizing.py +189 -0
@@ -0,0 +1,494 @@
1
+ """Cost-aware offline simulation of the cross-sectional rank book (V5.1
2
+ Phase 0). Reuses the EXACT selection/neutrality machinery main.py's live
3
+ decision path uses - portfolio.book_construction.build_rank_based_book()
4
+ and portfolio.book_neutrality.apply_book_neutrality() - so this module's
5
+ numbers are the offline mirror of live behavior, not an independently
6
+ re-derived approximation. Both of those are pure Python/dataclasses (no
7
+ torch, no pandas), so importing them here does not compromise this
8
+ package's torch-free contract (see evaluation/__init__.py's docstring).
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import math
14
+ from dataclasses import asdict, dataclass, field, replace
15
+
16
+ import numpy as np
17
+ import pandas as pd
18
+
19
+ from portfolio.book_construction import BookAllocation, build_rank_based_book
20
+ from portfolio.book_neutrality import apply_book_neutrality
21
+
22
+ DEFAULT_SECTOR_MAX_NET_WEIGHT = 0.05
23
+
24
+
25
+ @dataclass(frozen=True)
26
+ class RankBookSimulationResult:
27
+ gross_sharpe: float
28
+ net_sharpe: float
29
+ gross_total_return: float
30
+ net_total_return: float
31
+ net_max_drawdown: float
32
+ annualized_turnover: float
33
+ cost_drag_annual_bps: float
34
+ num_rebalances: int
35
+ num_dates_used: int
36
+ mean_names_long: float
37
+ mean_names_short: float
38
+ per_date_net_return: list = field(default_factory=list)
39
+ per_date: list = field(default_factory=list)
40
+
41
+ def to_dict(self) -> dict:
42
+ return asdict(self)
43
+
44
+
45
+ def _annualized_sharpe(returns: np.ndarray, trading_days_per_year: int) -> float:
46
+ """Same convention as train.py::compute_strategy_metrics() -
47
+ (mean/std) * sqrt(trading_days_per_year) - kept identical so this
48
+ simulator's Sharpe is directly comparable to every other Sharpe number
49
+ already reported by this codebase."""
50
+ if len(returns) < 2:
51
+ return 0.0
52
+ std = float(returns.std(ddof=1))
53
+ if std <= 0.0:
54
+ return 0.0
55
+ return float(returns.mean() / std) * math.sqrt(trading_days_per_year)
56
+
57
+
58
+ def _empty_result(trading_days_per_year: int) -> RankBookSimulationResult:
59
+ return RankBookSimulationResult(
60
+ gross_sharpe=0.0,
61
+ net_sharpe=0.0,
62
+ gross_total_return=0.0,
63
+ net_total_return=0.0,
64
+ net_max_drawdown=0.0,
65
+ annualized_turnover=0.0,
66
+ cost_drag_annual_bps=0.0,
67
+ num_rebalances=0,
68
+ num_dates_used=0,
69
+ mean_names_long=0.0,
70
+ mean_names_short=0.0,
71
+ per_date_net_return=[],
72
+ per_date=[],
73
+ )
74
+
75
+
76
+ def _simulate_rank_book_core(
77
+ frame: pd.DataFrame,
78
+ *,
79
+ prediction_column: str,
80
+ forward_return_column: str = "target_return_1d",
81
+ ticker_column: str = "ticker",
82
+ date_column: str = "date",
83
+ top_n: int,
84
+ bottom_n: int,
85
+ rebalance_every_bars: int,
86
+ cost_bps_per_side: float,
87
+ commission_bps: float,
88
+ gross_exposure: float,
89
+ dollar_neutral: bool,
90
+ sector_neutral: bool,
91
+ sector_by_ticker: dict[str, str] | None = None,
92
+ hysteresis_rank_margin: float = 0.0,
93
+ max_weight_per_name: float,
94
+ min_universe_size: int = 20,
95
+ sector_max_net_weight: float = DEFAULT_SECTOR_MAX_NET_WEIGHT,
96
+ trading_days_per_year: int = 252,
97
+ entry_lag_bars: int = 0,
98
+ min_commission_usd: float = 0.0,
99
+ assumed_portfolio_value_usd: float = 0.0,
100
+ impact_model_config: dict | None = None,
101
+ ) -> tuple[RankBookSimulationResult, dict[str, int]]:
102
+ """The real implementation, shared by simulate_rank_book() (public,
103
+ returns just the result) and capacity_curve() (needs held_days_by_ticker
104
+ too, to estimate which held name is the liquidity bottleneck). See
105
+ simulate_rank_book()'s docstring for the full parameter/behavior
106
+ contract - this function is not itself part of the public API.
107
+
108
+ Per date, in sorted order: dates with fewer than min_universe_size
109
+ eligible (non-NaN prediction AND forward-return) rows are SKIPPED
110
+ entirely (no selection, no return accrual) - same convention as
111
+ train.py::build_cross_sectional_rank_targets()'s min_universe_size
112
+ gate; the book silently carries over across a skipped date, as if it
113
+ did not exist for accounting purposes. On a rebalance date (every
114
+ rebalance_every_bars-th non-skipped date, first date always rebalances),
115
+ predictions are handed to build_rank_based_book() (with hysteresis
116
+ against the previous allocation) for top/bottom-N selection, each leg
117
+ is equal-weighted to gross_exposure/2, then apply_book_neutrality()
118
+ applies the sector/dollar/gross constraints. Cost
119
+ (cost_bps_per_side + commission_bps, in bps) is charged on the turnover
120
+ of that single rebalance event only - held-and-unchanged positions
121
+ between rebalances accrue zero cost, matching main.py's own
122
+ hold-until-next-rebalance contract (portfolio/book_construction.py::
123
+ should_rebalance_this_bar()).
124
+
125
+ entry_lag_bars (V5.2.1, development/Problems.md - default 0, today's
126
+ exact behavior): a Daily-resolution market order decided off bar N's
127
+ close fills at bar N+1's open, not bar N's close (main.py's own
128
+ documented behavior) - this function previously credited a newly-
129
+ selected position with that SAME date's forward return, an implicit
130
+ zero-lag fill assumption no live system can achieve. When > 0, return
131
+ accrual for a given date reads the book state as it stood
132
+ entry_lag_bars dates EARLIER (a rolling snapshot history), not the
133
+ state as of the current date's own rebalance - so a position selected
134
+ today does not start earning return until entry_lag_bars dates from
135
+ now, mirroring the live fill delay. Affects ONLY which return a held
136
+ weight earns; turnover/cost accounting stays keyed to the unlagged
137
+ rebalance transition (cost is incurred at order-submission time, not
138
+ fill time). A position held unchanged across the lag window has an
139
+ identical snapshot at both indices, so nothing is falsely penalized -
140
+ only genuinely CHANGED positions are affected.
141
+
142
+ min_commission_usd / assumed_portfolio_value_usd (default 0.0 - a
143
+ no-op, today's exact bps-of-turnover-only cost model): an
144
+ honestly-approximate per-order minimum-commission floor, layered on
145
+ top of the existing cost_bps_per_side/commission_bps bps-of-turnover
146
+ term. Real broker commissions are often floor-dominated for small
147
+ orders (see execution/cost_model.py's own min_commission_usd), which a
148
+ pure bps-of-notional model never captures. Requires an assumed NAV to
149
+ convert a per-order dollar floor into a return-fraction - a deliberate
150
+ approximation (uniform order size, fixed NAV across the whole run),
151
+ not a precision claim, same "honestly-approximate" convention
152
+ capacity_curve()'s own docstring uses. Only applied on rebalance
153
+ dates, charged once per name whose weight actually changed."""
154
+ sector_by_ticker = sector_by_ticker or {}
155
+ working = frame.dropna(subset=[prediction_column]).copy()
156
+ unique_dates = sorted(working[date_column].unique())
157
+
158
+ held_weights: dict[str, float] = {}
159
+ held_allocations: dict[str, BookAllocation] = {}
160
+ held_days_by_ticker: dict[str, int] = {}
161
+
162
+ gross_returns: list[float] = []
163
+ net_returns: list[float] = []
164
+ per_date_used: list = []
165
+ names_long_series: list[int] = []
166
+ names_short_series: list[int] = []
167
+ total_turnover = 0.0
168
+ total_cost_return = 0.0
169
+ num_rebalances = 0
170
+ rebalance_counter = 0
171
+ # V5.2.1 - one held_weights snapshot per processed date, appended AFTER
172
+ # that date's own rebalance (if any) - see entry_lag_bars's docstring.
173
+ weights_history: list[dict[str, float]] = []
174
+
175
+ net_cumprod = 1.0
176
+ gross_cumprod = 1.0
177
+ net_running_peak = 1.0
178
+ net_max_drawdown = 0.0
179
+
180
+ for date in unique_dates:
181
+ date_frame = working[working[date_column] == date]
182
+ eligible = date_frame.dropna(subset=[forward_return_column])
183
+ if len(eligible) < min_universe_size:
184
+ continue
185
+
186
+ is_rebalance = (rebalance_counter % max(1, rebalance_every_bars)) == 0
187
+ rebalance_counter += 1
188
+ cost_this_date = 0.0
189
+
190
+ if is_rebalance:
191
+ book_candidates = {
192
+ str(ticker): {"predicted_rank_20d": float(rank), "trading_eligible": True, "asset_class": None}
193
+ for ticker, rank in zip(eligible[ticker_column], eligible[prediction_column])
194
+ }
195
+ # min_rank_confidence_spread=0.0 is DELIBERATE, not an
196
+ # oversight: this simulator measures book QUALITY (what would
197
+ # this rank prediction have earned, net of costs) uncapped by
198
+ # the live entry gate's conviction filter - those are two
199
+ # different questions. Do not "fix" this into reading
200
+ # phase_v2.portfolio_book.min_rank_confidence_spread to try to
201
+ # mirror live engagement; that number is calibrated
202
+ # specifically for the RAW pre-normalization score scale
203
+ # (aq evaluate --calibrate-book-spread, portfolio/rank_signal.py),
204
+ # which this function's `prediction_column` is not guaranteed
205
+ # to be (callers may pass an already-normalized column). A
206
+ # healthy net_sharpe here is evidence the RANKING has value,
207
+ # never evidence the live gate will engage on any given day.
208
+ allocations = build_rank_based_book(
209
+ book_candidates,
210
+ top_n=top_n,
211
+ bottom_n=bottom_n,
212
+ min_rank_confidence_spread=0.0,
213
+ previous_allocations=held_allocations or None,
214
+ hysteresis_rank_margin=hysteresis_rank_margin,
215
+ )
216
+
217
+ if allocations:
218
+ long_symbols = [symbol for symbol, allocation in allocations.items() if allocation.role == "long"]
219
+ short_symbols = [symbol for symbol, allocation in allocations.items() if allocation.role == "short"]
220
+ raw_weights: dict[str, float] = {}
221
+ if long_symbols:
222
+ per_name = (gross_exposure / 2.0) / len(long_symbols)
223
+ raw_weights.update({symbol: per_name for symbol in long_symbols})
224
+ if short_symbols:
225
+ per_name = (gross_exposure / 2.0) / len(short_symbols)
226
+ raw_weights.update({symbol: -per_name for symbol in short_symbols})
227
+
228
+ new_weights, _diagnostics = apply_book_neutrality(
229
+ raw_weights,
230
+ sector_by_symbol=sector_by_ticker,
231
+ dollar_neutral=dollar_neutral,
232
+ sector_neutral=sector_neutral,
233
+ gross_exposure_cap=gross_exposure,
234
+ max_weight_per_name=max_weight_per_name,
235
+ sector_max_net_weight=sector_max_net_weight,
236
+ )
237
+ held_allocations = {
238
+ symbol: replace(allocation, target_weight=new_weights.get(symbol, 0.0))
239
+ for symbol, allocation in allocations.items()
240
+ }
241
+ else:
242
+ new_weights = {}
243
+ held_allocations = {}
244
+
245
+ all_symbols = set(new_weights) | set(held_weights)
246
+ deltas_by_symbol = {
247
+ symbol: new_weights.get(symbol, 0.0) - held_weights.get(symbol, 0.0) for symbol in all_symbols
248
+ }
249
+ turnover_this_rebalance = sum(abs(delta) for delta in deltas_by_symbol.values())
250
+ total_turnover += turnover_this_rebalance
251
+ cost_this_date = turnover_this_rebalance * (cost_bps_per_side + commission_bps) / 1e4
252
+ # V5.2.1 (development/Problems.md) - honestly-approximate
253
+ # per-order minimum-commission floor, see this function's own
254
+ # docstring. No-op (0.0) unless both inputs are configured.
255
+ if min_commission_usd > 0.0 and assumed_portfolio_value_usd > 0.0:
256
+ names_traded = sum(1 for delta in deltas_by_symbol.values() if delta != 0.0)
257
+ cost_this_date += names_traded * min_commission_usd / assumed_portfolio_value_usd
258
+ total_cost_return += cost_this_date
259
+
260
+ # V5.4.2 - Almgren-style impact model (optional, off by default).
261
+ # Simplified date-level estimate: uses aggregate turnover and a
262
+ # configured daily vol + eta to approximate sqrt-impact cost.
263
+ if impact_model_config and impact_model_config.get("enabled", False):
264
+ from evaluation.impact_model import compute_sqrt_impact_bps
265
+
266
+ eta = float(impact_model_config.get("eta", 0.5))
267
+ daily_vol = float(impact_model_config.get("daily_volatility", 0.02))
268
+ adv = float(impact_model_config.get("avg_daily_dollar_volume", 50_000_000))
269
+ pv = assumed_portfolio_value_usd if assumed_portfolio_value_usd > 0 else 1e6
270
+ impact_bps = compute_sqrt_impact_bps(
271
+ trade_size_fraction=turnover_this_rebalance,
272
+ daily_volatility=daily_vol,
273
+ avg_daily_dollar_volume=adv,
274
+ portfolio_value=pv,
275
+ eta=eta,
276
+ )
277
+ impact_cost = impact_bps / 1e4
278
+ cost_this_date += impact_cost
279
+ total_cost_return += impact_cost
280
+
281
+ num_rebalances += 1
282
+ held_weights = new_weights
283
+
284
+ for symbol in held_weights:
285
+ held_days_by_ticker[symbol] = held_days_by_ticker.get(symbol, 0) + 1
286
+ names_long_series.append(sum(1 for weight in held_weights.values() if weight > 0.0))
287
+ names_short_series.append(sum(1 for weight in held_weights.values() if weight < 0.0))
288
+
289
+ date_returns = dict(zip(eligible[ticker_column], eligible[forward_return_column]))
290
+ # V5.2.1 - entry_lag_bars=0 (default) uses held_weights directly,
291
+ # byte-identical to before this parameter existed. > 0 looks back
292
+ # into weights_history instead - see this function's own docstring.
293
+ if entry_lag_bars > 0:
294
+ lag_index = len(weights_history) - entry_lag_bars
295
+ effective_weights = weights_history[lag_index] if lag_index >= 0 else {}
296
+ else:
297
+ effective_weights = held_weights
298
+ bar_return = sum(
299
+ weight * float(date_returns.get(symbol, 0.0)) for symbol, weight in effective_weights.items()
300
+ )
301
+ net_return = bar_return - cost_this_date
302
+
303
+ gross_returns.append(bar_return)
304
+ net_returns.append(net_return)
305
+ per_date_used.append(str(date))
306
+ weights_history.append(dict(held_weights))
307
+ gross_cumprod *= 1.0 + bar_return
308
+ net_cumprod *= 1.0 + net_return
309
+ net_running_peak = max(net_running_peak, net_cumprod)
310
+ net_max_drawdown = min(net_max_drawdown, net_cumprod / net_running_peak - 1.0)
311
+
312
+ if not per_date_used:
313
+ return _empty_result(trading_days_per_year), held_days_by_ticker
314
+
315
+ num_dates_used = len(per_date_used)
316
+ years = num_dates_used / trading_days_per_year
317
+ gross_array = np.asarray(gross_returns, dtype=float)
318
+ net_array = np.asarray(net_returns, dtype=float)
319
+
320
+ result = RankBookSimulationResult(
321
+ gross_sharpe=_annualized_sharpe(gross_array, trading_days_per_year),
322
+ net_sharpe=_annualized_sharpe(net_array, trading_days_per_year),
323
+ gross_total_return=float(gross_cumprod - 1.0),
324
+ net_total_return=float(net_cumprod - 1.0),
325
+ net_max_drawdown=float(net_max_drawdown),
326
+ annualized_turnover=float(total_turnover / years) if years > 0 else 0.0,
327
+ cost_drag_annual_bps=float(total_cost_return / years * 10_000.0) if years > 0 else 0.0,
328
+ num_rebalances=num_rebalances,
329
+ num_dates_used=num_dates_used,
330
+ mean_names_long=float(np.mean(names_long_series)) if names_long_series else 0.0,
331
+ mean_names_short=float(np.mean(names_short_series)) if names_short_series else 0.0,
332
+ per_date_net_return=[float(value) for value in net_returns],
333
+ per_date=per_date_used,
334
+ )
335
+ return result, held_days_by_ticker
336
+
337
+
338
+ def simulate_rank_book(frame: pd.DataFrame, **kwargs) -> RankBookSimulationResult:
339
+ """Public entry point - see _simulate_rank_book_core()'s docstring for
340
+ the full algorithm. Discards held_days_by_ticker (only capacity_curve()
341
+ needs it)."""
342
+ result, _held_days_by_ticker = _simulate_rank_book_core(frame, **kwargs)
343
+ return result
344
+
345
+
346
+ def capacity_curve(
347
+ frame: pd.DataFrame,
348
+ *,
349
+ dollar_volume_column: str = "liquidity_log_dollar_volume",
350
+ participation_cap: float,
351
+ base_kwargs: dict,
352
+ top_n_sweep: list[int],
353
+ ) -> dict:
354
+ """Breadth + capacity check (V5.1 Phase 0, an addition beyond the
355
+ original roadmap table - see the V5.1 plan's own §1 "one thing missing
356
+ from the list"): sweeps top_n==bottom_n across top_n_sweep, holding
357
+ every other simulate_rank_book() kwarg fixed via base_kwargs, so a
358
+ rank-IC concentrated in a handful of names (net_sharpe collapses as
359
+ top_n shrinks toward the extreme) is visibly distinguishable from one
360
+ genuinely spread across the cross-section.
361
+
362
+ capacity_usd is a deliberately simple, honestly-approximate estimate,
363
+ not a precision claim: among names actually held during the BASE run
364
+ (base_kwargs's own top_n/bottom_n), the one with the lowest average
365
+ dollar volume (dollar_volume_column, a log1p value - inverted with
366
+ expm1 here, the correct inverse) is the binding constraint; scaling its
367
+ average dollar volume by participation_cap and by the number of held
368
+ names gives a rough total-book capacity ceiling. binding_ticker names
369
+ exactly which held name limits it, so this is auditable rather than a
370
+ black-box number.
371
+
372
+ A held ticker with dollar_volume_column == 0.0 exactly (e.g. a forex
373
+ pair - Yahoo Finance reports no real Volume for FX, so
374
+ log1p(close*volume) is always 0.0 for them, see development/Problems.md)
375
+ is EXCLUDED from the binding-ticker search: a true zero here means "no
376
+ real liquidity signal for this asset," not "zero capacity," and letting
377
+ it win the minimum would make one data-quality artifact dictate the
378
+ whole book's capacity regardless of every other held name's real
379
+ liquidity. If every held ticker lacks real volume data, this honestly
380
+ degrades to capacity_usd=0.0 / binding_ticker=None, the same "can't
381
+ estimate" result already returned when the base run holds nothing."""
382
+ per_top_n: list[dict] = []
383
+ base_held_days: dict[str, int] | None = None
384
+ base_top_n = base_kwargs.get("top_n")
385
+
386
+ for n in top_n_sweep:
387
+ sweep_kwargs = dict(base_kwargs)
388
+ sweep_kwargs["top_n"] = n
389
+ sweep_kwargs["bottom_n"] = n
390
+ result, held_days = _simulate_rank_book_core(frame, **sweep_kwargs)
391
+ per_top_n.append({"top_n": n, "net_sharpe": result.net_sharpe})
392
+ if n == base_top_n:
393
+ base_held_days = held_days
394
+
395
+ if base_held_days is None:
396
+ _, base_held_days = _simulate_rank_book_core(frame, **base_kwargs)
397
+
398
+ if not base_held_days:
399
+ return {"capacity_usd": 0.0, "binding_ticker": None, "per_top_n": per_top_n}
400
+
401
+ ticker_column = base_kwargs.get("ticker_column", "ticker")
402
+ avg_log_dollar_volume = frame.groupby(ticker_column)[dollar_volume_column].mean()
403
+ held_avg_dollar_volume = {
404
+ ticker: float(np.expm1(avg_log_dollar_volume.get(ticker, 0.0))) for ticker in base_held_days
405
+ }
406
+ if not held_avg_dollar_volume:
407
+ return {"capacity_usd": 0.0, "binding_ticker": None, "per_top_n": per_top_n}
408
+
409
+ # Zero means "no real volume data for this ticker" (e.g. forex - see
410
+ # this function's own docstring), not "zero liquidity" - exclude it
411
+ # from the binding-ticker search so a data-quality artifact can't
412
+ # dictate the whole book's capacity.
413
+ tickers_with_real_volume = {ticker: value for ticker, value in held_avg_dollar_volume.items() if value > 0.0}
414
+ if not tickers_with_real_volume:
415
+ return {"capacity_usd": 0.0, "binding_ticker": None, "per_top_n": per_top_n}
416
+
417
+ binding_ticker = min(tickers_with_real_volume, key=tickers_with_real_volume.get)
418
+ capacity_usd = float(tickers_with_real_volume[binding_ticker] * participation_cap * len(held_avg_dollar_volume))
419
+ return {"capacity_usd": capacity_usd, "binding_ticker": binding_ticker, "per_top_n": per_top_n}
420
+
421
+
422
+ def stress_test_costs(frame: pd.DataFrame, *, base_kwargs: dict, cost_multipliers: tuple = (1.0, 2.0, 3.0)) -> list[dict]:
423
+ """One simulate_rank_book() run per cost multiplier, scaling BOTH
424
+ cost_bps_per_side and commission_bps - answers "does the edge survive
425
+ if real-world costs turn out to be 2x/3x the calibrated estimate",
426
+ the robustness check item 12 of the V5.1 roadmap asks for."""
427
+ results = []
428
+ for multiplier in cost_multipliers:
429
+ stressed_kwargs = dict(base_kwargs)
430
+ stressed_kwargs["cost_bps_per_side"] = float(base_kwargs.get("cost_bps_per_side", 0.0)) * multiplier
431
+ stressed_kwargs["commission_bps"] = float(base_kwargs.get("commission_bps", 0.0)) * multiplier
432
+ result = simulate_rank_book(frame, **stressed_kwargs)
433
+ results.append({"cost_multiplier": multiplier, **result.to_dict()})
434
+ return results
435
+
436
+
437
+ def _bootstrap_mean_confidence_interval(
438
+ values: list[float], n_resamples: int = 2000, confidence: float = 0.95, seed: int = 42
439
+ ) -> dict:
440
+ """Torch-free duplicate of train.py::bootstrap_ic_confidence_interval()'s
441
+ resample-with-replacement bootstrap over a plain float series - same
442
+ algorithm and defaults, deliberately reimplemented here (not imported)
443
+ since train.py imports torch and this package must stay torch-free (see
444
+ evaluation/__init__.py's docstring)."""
445
+ if not values:
446
+ return {"lower_bound": 0.0, "upper_bound": 0.0, "mean": 0.0}
447
+ rng = np.random.default_rng(seed)
448
+ array = np.asarray(values, dtype=float)
449
+ resampled_means = np.empty(n_resamples)
450
+ for i in range(n_resamples):
451
+ resampled_means[i] = rng.choice(array, size=len(array), replace=True).mean()
452
+ alpha = (1.0 - confidence) / 2.0
453
+ return {
454
+ "lower_bound": float(np.quantile(resampled_means, alpha)),
455
+ "upper_bound": float(np.quantile(resampled_means, 1.0 - alpha)),
456
+ "mean": float(array.mean()),
457
+ }
458
+
459
+
460
+ def summarize_metric_stability(per_window_values: list[float], *, min_windows: int, max_sign_flip_fraction: float) -> dict:
461
+ """Cross-window stability summary (used by Phase 4's walk-forward
462
+ evaluation and Phase 5's ablation) - mirrors
463
+ train.py::assess_ranking_quality()'s era-sign-instability check, one
464
+ level up: a window whose sign disagrees with the overall mean's sign is
465
+ a "flip", same concept as an opposite-sign era. num_windows below
466
+ min_windows or a sign-flip fraction above max_sign_flip_fraction both
467
+ fail "stable"."""
468
+ values = [float(value) for value in per_window_values]
469
+ num_windows = len(values)
470
+ if num_windows == 0:
471
+ return {
472
+ "num_windows": 0, "mean": 0.0, "sign_flip_fraction": 0.0, "stable": False,
473
+ "failures": ["no_windows"], "bootstrap": _bootstrap_mean_confidence_interval([]),
474
+ }
475
+
476
+ mean_value = float(np.mean(values))
477
+ overall_positive = mean_value >= 0.0
478
+ flips = sum(1 for value in values if (value >= 0.0) != overall_positive)
479
+ sign_flip_fraction = flips / num_windows
480
+
481
+ failures = []
482
+ if num_windows < min_windows:
483
+ failures.append("insufficient_windows")
484
+ if sign_flip_fraction > max_sign_flip_fraction:
485
+ failures.append("sign_flip_fraction_above_gate")
486
+
487
+ return {
488
+ "num_windows": num_windows,
489
+ "mean": mean_value,
490
+ "sign_flip_fraction": sign_flip_fraction,
491
+ "stable": not failures,
492
+ "failures": failures,
493
+ "bootstrap": _bootstrap_mean_confidence_interval(values),
494
+ }