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,286 @@
1
+ """V5.3.5 Workstream B (development/Problems.md #91/#100) - the XOM
2
+ feature-level investigation's pure diff core.
3
+
4
+ `reconcile_feature_snapshot()` compares a single symbol's logged LIVE
5
+ feature values (the `feature_snapshot.base_features` dict main.py's
6
+ book-history diagnostic captured for that bar) against the same symbol/
7
+ date row from `ml/datasets/full_dataset.csv` - the precomputed feature
8
+ columns `train.py::engineer_features()` wrote from the same underlying
9
+ `features/technical_indicators.py` functions the live path also calls.
10
+ A divergence between the two for the same (ticker, date) is the concrete
11
+ root cause this tool exists to surface or rule out: XOM is the one tracked
12
+ ticker whose live-vs-offline book-selection mismatch never resolved across
13
+ #91/#97/#99/#100 (140 appearances across 9 real runs, 77% mismatch, the
14
+ worst of the five tracked tickers), and the existing
15
+ `book_history.jsonl` records `raw_rank_score`/`feature_ready`/
16
+ `trading_eligible` per symbol but no raw feature values - so nothing to
17
+ diff against the offline dataset until this field exists.
18
+
19
+ Pure: no I/O, no `self`, never raises on well-formed inputs - same
20
+ shaping-only convention `reconcile_book_history_date()`'s own
21
+ `_build_reconciliation_result()` already established. The CLI
22
+ (`aq evaluate --reconcile-features`) owns the dataset load, the run-
23
+ segmenting, the (ticker, date) join, and the per-date loop calling this
24
+ function; this module only computes the diff, so it is unit-testable
25
+ without a Lean backtest or a real dataset.
26
+
27
+ What this function compares and what it deliberately does NOT:
28
+ - Compares ONLY features present in the logged `base_features` snapshot
29
+ (main.py::_build_model_input()'s output - the price/volume-derived
30
+ technicals, regime/topology/liquidity signals, and peer-return features
31
+ the model actually saw live). The offline dataset has MORE columns
32
+ (expanded one-hot `regime_trend_*`/`topology_risk_*`/`bond_*`/`alt_*`/
33
+ `sens_*`/`macro_*`/`futures_*`/`options_*` - each derived in
34
+ `_build_regime_payload`/`_build_topology_payload` and flattened into
35
+ separate dataset columns by `train.py::engineer_features()`); those
36
+ appear in `features_only_in_offline` (informational, not a divergence)
37
+ since the live path carries them as structured sub-payloads, not as
38
+ the flat keys this function compares.
39
+ - A feature present in the snapshot but NOT in the offline row is a
40
+ `features_only_in_logged` entry (informational - the live path computed
41
+ something the offline pipeline didn't, e.g. a feature added after the
42
+ dataset was built), NOT a divergence either.
43
+ - Only the INTERSECTION is diffed, with `abs_delta` and `relative_delta`
44
+ per feature, sorted by `abs_delta` desc so the worst offender is first.
45
+ - `offline_value` is read via `.get()` - a NaN/None column in the offline
46
+ row for that date degrades to `None`, same convention the existing
47
+ reconciliation uses for missing raw scores.
48
+ """
49
+
50
+ from __future__ import annotations
51
+
52
+ from collections.abc import Mapping
53
+ from typing import Any
54
+
55
+ DEFAULT_ABS_TOLERANCE = 1e-9
56
+ DEFAULT_REL_TOLERANCE = 1e-6
57
+ _RELATIVE_EPS = 1e-12
58
+
59
+
60
+ def _coerce_float(value: Any) -> float | None:
61
+ """Coerce a dataset value to float, returning None for NaN/None/
62
+ non-numeric - the offline dataset stores features as CSV strings that
63
+ pandas reads as float64 but may carry NaN for warmup-period rows.
64
+ Mirrors the degrade-on-missing convention every other reconciliation
65
+ field uses, never raises."""
66
+ if value is None:
67
+ return None
68
+ try:
69
+ as_float = float(value)
70
+ except (TypeError, ValueError):
71
+ return None
72
+ if as_float != as_float: # NaN - the only float != itself
73
+ return None
74
+ return as_float
75
+
76
+
77
+ def reconcile_feature_snapshot(
78
+ logged_feature_snapshot: Mapping[str, Any],
79
+ offline_dataset_row: Mapping[str, Any],
80
+ *,
81
+ abs_tolerance: float = DEFAULT_ABS_TOLERANCE,
82
+ rel_tolerance: float = DEFAULT_REL_TOLERANCE,
83
+ ) -> dict:
84
+ """Compare one logged feature snapshot (one symbol, one date's
85
+ `base_features` dict) against the matching offline dataset row for
86
+ the same (ticker, date).
87
+
88
+ Args:
89
+ logged_feature_snapshot: the `base_features` dict main.py's
90
+ `_build_model_input()` built for that bar, as captured in the
91
+ `feature_snapshot` field of one `book_history.jsonl` record's
92
+ per-symbol entry. Only the feature names present here are
93
+ diffed - the live path is the source of truth for what the
94
+ model actually saw.
95
+ offline_dataset_row: the matching `full_dataset.csv` row (a
96
+ pandas Series or dict) for the same ticker/date, keyed by
97
+ column name. Missing/NaN columns degrade to None, not a crash.
98
+ abs_tolerance: features whose `abs_delta` is at or below this are
99
+ considered matched (float reconstruction noise). Default
100
+ 1e-9 - the live and offline paths both call the same pure
101
+ `features/technical_indicators.py` functions, so a genuine
102
+ match should be bit-identical up to float order noise; this
103
+ default is deliberately tight so even small systematic drift
104
+ surfaces.
105
+ rel_tolerance: features whose `relative_delta` is at or below
106
+ this are also considered matched (covers the case where
107
+ abs_delta is tiny in absolute terms but the offline value is
108
+ also tiny - a rel floor avoids noise on near-zero features).
109
+
110
+ Returns:
111
+ {"features_compared": int,
112
+ "features_matched": int,
113
+ "features_diverged": int,
114
+ "max_abs_delta": float | None,
115
+ "feature_deltas": list[dict], sorted by abs_delta desc, each
116
+ {"feature", "logged_value", "offline_value", "abs_delta",
117
+ "relative_delta", "diverged": bool},
118
+ "features_only_in_logged": sorted list[str],
119
+ "features_only_in_offline": sorted list[str]}
120
+
121
+ `max_abs_delta` is None only when zero features were compared (the
122
+ snapshot and the row share no feature names); 0.0 when all compared
123
+ features match exactly. `features_diverged` counts features whose
124
+ abs_delta exceeds BOTH tolerances (abs AND rel, not either - a near-
125
+ zero offline value with a tiny abs_delta but large relative_delta is
126
+ noise, not a real divergence).
127
+ """
128
+ logged_keys = set(logged_feature_snapshot.keys())
129
+ offline_keys = set(offline_dataset_row.keys())
130
+ common = sorted(logged_keys & offline_keys)
131
+
132
+ feature_deltas: list[dict] = []
133
+ max_abs_delta: float | None = None
134
+ matched = 0
135
+ diverged = 0
136
+
137
+ for feature in common:
138
+ logged_value = _coerce_float(logged_feature_snapshot.get(feature))
139
+ offline_value = _coerce_float(offline_dataset_row.get(feature))
140
+ # Either side missing/NaN: no comparison possible for this feature
141
+ # - degrade to None rather than a spurious "diverged" or "matched".
142
+ if logged_value is None or offline_value is None:
143
+ feature_deltas.append({
144
+ "feature": feature,
145
+ "logged_value": logged_value,
146
+ "offline_value": offline_value,
147
+ "abs_delta": None,
148
+ "relative_delta": None,
149
+ "diverged": False,
150
+ })
151
+ continue
152
+
153
+ abs_delta = abs(offline_value - logged_value)
154
+ relative_delta = abs_delta / max(abs(offline_value), _RELATIVE_EPS)
155
+ is_diverged = abs_delta > abs_tolerance and relative_delta > rel_tolerance
156
+
157
+ feature_deltas.append({
158
+ "feature": feature,
159
+ "logged_value": logged_value,
160
+ "offline_value": offline_value,
161
+ "abs_delta": abs_delta,
162
+ "relative_delta": relative_delta,
163
+ "diverged": is_diverged,
164
+ })
165
+ if is_diverged:
166
+ diverged += 1
167
+ else:
168
+ matched += 1
169
+ if max_abs_delta is None or abs_delta > max_abs_delta:
170
+ max_abs_delta = abs_delta
171
+
172
+ feature_deltas.sort(key=lambda entry: (entry["abs_delta"] is None, -(entry["abs_delta"] or 0.0)))
173
+
174
+ return {
175
+ "features_compared": len(common),
176
+ "features_matched": matched,
177
+ "features_diverged": diverged,
178
+ "max_abs_delta": max_abs_delta,
179
+ "feature_deltas": feature_deltas,
180
+ "features_only_in_logged": sorted(logged_keys - offline_keys),
181
+ "features_only_in_offline": sorted(offline_keys - logged_keys),
182
+ }
183
+
184
+
185
+ def summarize_feature_reconciliation(per_date_results: list[dict]) -> dict:
186
+ """Aggregate a list of per-date `reconcile_feature_snapshot()` results
187
+ (one per logged record for the target symbol) into a single report,
188
+ mirroring `summarize_book_history_reconciliation()`'s shape: an empty
189
+ list returns a defined all-zero summary, never raises.
190
+
191
+ Surfaces WHICH specific features diverge most often and by how much -
192
+ the XOM investigation's entire point (a per-feature root cause, not a
193
+ single "mismatch" number). A feature that diverges on 77% of XOM's
194
+ appearances but 0% of every other tracked ticker's is the concrete
195
+ signal this tool exists to produce.
196
+
197
+ Returns:
198
+ {"num_dates": int,
199
+ "num_dates_with_comparison": int,
200
+ "num_features_compared_per_date": {"min": int|None, "max": int|None,
201
+ "mean": float|None},
202
+ "total_divergences": int,
203
+ "dates_with_any_divergence": int,
204
+ "features_diverged_most_often": list[{"feature", "diverged_count",
205
+ "diverged_fraction", "max_abs_delta", "mean_abs_delta"}]
206
+ sorted by diverged_count desc, capped at 20,
207
+ "features_never_compared": sorted list[str] - features present in
208
+ every logged snapshot but missing from the offline row every
209
+ time (e.g. a feature added live after the dataset was built).}
210
+ """
211
+ num_dates = len(per_date_results)
212
+ if num_dates == 0:
213
+ return {
214
+ "num_dates": 0,
215
+ "num_dates_with_comparison": 0,
216
+ "num_features_compared_per_date": {"min": None, "max": None, "mean": None},
217
+ "total_divergences": 0,
218
+ "dates_with_any_divergence": 0,
219
+ "features_diverged_most_often": [],
220
+ "features_never_compared": [],
221
+ }
222
+
223
+ compared_counts: list[int] = []
224
+ dates_with_any_divergence = 0
225
+ total_divergences = 0
226
+ feature_divergence_counts: dict[str, list[float]] = {}
227
+ feature_presence_in_logged: dict[str, int] = {}
228
+ feature_compared_count: dict[str, int] = {}
229
+ only_in_logged_accumulator: dict[str, int] = {}
230
+
231
+ for result in per_date_results:
232
+ compared = result.get("features_compared", 0)
233
+ compared_counts.append(compared)
234
+ diverged = result.get("features_diverged", 0)
235
+ total_divergences += diverged
236
+ if diverged > 0:
237
+ dates_with_any_divergence += 1
238
+ for entry in result.get("feature_deltas", []):
239
+ feature = entry["feature"]
240
+ feature_compared_count[feature] = feature_compared_count.get(feature, 0) + 1
241
+ if entry.get("diverged"):
242
+ feature_divergence_counts.setdefault(feature, []).append(entry["abs_delta"])
243
+ for feature in result.get("features_only_in_logged", []):
244
+ only_in_logged_accumulator[feature] = only_in_logged_accumulator.get(feature, 0) + 1
245
+ # Only count a feature as "present in logged snapshot" if it was in
246
+ # that snapshot at all (common or only_in_logged), so
247
+ # features_never_compared doesn't penalize a feature that simply
248
+ # wasn't logged for a given date (e.g. a warmup-bar snapshot with
249
+ # fewer keys).
250
+ for entry in result.get("feature_deltas", []):
251
+ feature = entry["feature"]
252
+ feature_presence_in_logged[feature] = feature_presence_in_logged.get(feature, 0) + 1
253
+ for feature in result.get("features_only_in_logged", []):
254
+ feature_presence_in_logged[feature] = feature_presence_in_logged.get(feature, 0) + 1
255
+
256
+ features_diverged_most_often = [
257
+ {
258
+ "feature": feature,
259
+ "diverged_count": len(deltas),
260
+ "diverged_fraction": len(deltas) / num_dates,
261
+ "max_abs_delta": max(deltas),
262
+ "mean_abs_delta": sum(deltas) / len(deltas),
263
+ }
264
+ for feature, deltas in feature_divergence_counts.items()
265
+ ]
266
+ features_diverged_most_often.sort(key=lambda item: item["diverged_count"], reverse=True)
267
+ features_diverged_most_often = features_diverged_most_often[:20]
268
+
269
+ features_never_compared = sorted(
270
+ feature for feature, present in feature_presence_in_logged.items()
271
+ if present == num_dates and feature_compared_count.get(feature, 0) == 0
272
+ )
273
+
274
+ return {
275
+ "num_dates": num_dates,
276
+ "num_dates_with_comparison": sum(1 for count in compared_counts if count > 0),
277
+ "num_features_compared_per_date": {
278
+ "min": min(compared_counts) if compared_counts else None,
279
+ "max": max(compared_counts) if compared_counts else None,
280
+ "mean": (sum(compared_counts) / len(compared_counts)) if compared_counts else None,
281
+ },
282
+ "total_divergences": total_divergences,
283
+ "dates_with_any_divergence": dates_with_any_divergence,
284
+ "features_diverged_most_often": features_diverged_most_often,
285
+ "features_never_compared": features_never_compared,
286
+ }
@@ -0,0 +1,77 @@
1
+ """V5.4.2 - Almgren-style sqrt market-impact model.
2
+
3
+ Replaces flat bps-per-side costs with a volume-participation-dependent
4
+ impact estimate when enabled. The core formula follows Almgren et al.
5
+ (2005): temporary price impact scales with the square root of the
6
+ participation rate (trade size / average daily volume), modulated by
7
+ the asset's own daily volatility.
8
+
9
+ impact_bps = eta × sigma_daily × sqrt(|trade_size / ADV|)
10
+
11
+ where:
12
+ - eta: calibrated impact coefficient (higher = more illiquid asset class)
13
+ - sigma_daily: rolling daily volatility of the asset (fraction, not %)
14
+ - trade_size / ADV: participation rate (fraction of daily volume consumed)
15
+
16
+ Pure: numpy only, no I/O, deterministic given inputs."""
17
+
18
+ from __future__ import annotations
19
+
20
+ import math
21
+
22
+
23
+ def compute_sqrt_impact_bps(
24
+ *,
25
+ trade_size_fraction: float,
26
+ daily_volatility: float,
27
+ avg_daily_dollar_volume: float,
28
+ portfolio_value: float,
29
+ eta: float = 0.5,
30
+ ) -> float:
31
+ """Computes temporary market impact in basis points.
32
+
33
+ Args:
34
+ trade_size_fraction: absolute weight change (e.g. 0.05 = 5% of book).
35
+ daily_volatility: rolling daily return std (e.g. 0.02 = 2%).
36
+ avg_daily_dollar_volume: asset's ADV in dollars (e.g. 50_000_000).
37
+ portfolio_value: total book value in dollars.
38
+ eta: impact coefficient — higher for less liquid assets.
39
+ Calibrated defaults: equity ~0.5, crypto ~1.0, bond ETF ~0.3.
40
+
41
+ Returns:
42
+ Impact cost in basis points (always >= 0). Zero when any input is
43
+ degenerate (zero size, zero ADV, zero vol)."""
44
+ if trade_size_fraction <= 0 or avg_daily_dollar_volume <= 0 or portfolio_value <= 0:
45
+ return 0.0
46
+ if daily_volatility <= 0:
47
+ return 0.0
48
+
49
+ trade_dollars = trade_size_fraction * portfolio_value
50
+ participation_rate = abs(trade_dollars / avg_daily_dollar_volume)
51
+
52
+ impact_fraction = eta * daily_volatility * math.sqrt(participation_rate)
53
+ return max(0.0, impact_fraction * 1e4)
54
+
55
+
56
+ def compute_participation_rate(
57
+ *,
58
+ trade_size_fraction: float,
59
+ portfolio_value: float,
60
+ avg_daily_dollar_volume: float,
61
+ ) -> float:
62
+ """Fraction of the asset's ADV consumed by this trade (0 when degenerate)."""
63
+ if avg_daily_dollar_volume <= 0 or portfolio_value <= 0:
64
+ return 0.0
65
+ return abs(trade_size_fraction * portfolio_value / avg_daily_dollar_volume)
66
+
67
+
68
+ # Per-security-type default eta values (calibrated from literature ranges;
69
+ # refine per-asset once real fill data exists).
70
+ DEFAULT_ETA_BY_SECURITY_TYPE: dict[str, float] = {
71
+ "equity": 0.5,
72
+ "crypto": 1.0,
73
+ "bond": 0.3,
74
+ "forex": 0.1,
75
+ "future": 0.4,
76
+ "option": 0.8,
77
+ }
@@ -0,0 +1,186 @@
1
+ """V5.2.8 (development/Problems.md #94) - a day-by-day OFFLINE replay of
2
+ main.py's kill-switch + sticky-trade-lock state machine, against a
3
+ purely offline return series (e.g. evaluation/rank_book_simulator.py::
4
+ simulate_rank_book()'s own per_date_net_return output) - the first
5
+ offline counterpart to any of live's ~10 risk/execution gates
6
+ (development/Problems.md #92's own finding was that NONE of them had one
7
+ before this). Follows the exact three-tier pattern already established by
8
+ evaluation/rank_signal_calibration.py's reconcile_book_history_date()/
9
+ replay_book_history_reconciliation()/summarize_book_history_reconciliation()
10
+ - a new, additive sibling module, never touching rank_book_simulator.py's
11
+ own simulate_rank_book() (that function's own docstring explicitly warns
12
+ against conflating raw ranking quality with live gate engagement - this
13
+ module answers a different question and lives separately on purpose).
14
+
15
+ APPROXIMATION, NOT GROUND TRUTH (read before trusting this module's
16
+ numbers - see development/Problems.md #94 for the full caveat and the
17
+ named follow-up this does NOT attempt): real live state at any given date
18
+ depends on the ACTUAL trade-lock/liquidation path taken on every PRIOR
19
+ date (main.py's own session-rollover block, main.py:6140-6345) - this
20
+ replay mechanically reproduces that same state machine, but only ever
21
+ sees the offline return series, never the live book's own realized
22
+ (gate-diverged) history. It models exactly two of evaluate_kill_switch()'s
23
+ 7 runtime_metrics inputs (recent_bar_returns via a rolling deque,
24
+ drawdown_velocity_pct_per_bar via a running peak) plus
25
+ risk_controls.py::assess_drawdown_lock()'s daily/total drawdown breach -
26
+ both feed the SAME sticky trade-lock reason space main.py's own
27
+ session-rollover clearing logic uses. It does NOT model live_rank_ic,
28
+ consecutive_losses, slippage_divergence_bps, model_age_days, or
29
+ reconciliation_breach (no offline equivalent exists for any of these) -
30
+ they stay None throughout, which evaluate_kill_switch()'s own documented
31
+ None-skip contract degrades cleanly rather than fabricating a value for.
32
+ No bypass flags (bypass_sticky_trade_lock etc.) are modeled either - this
33
+ replay always represents the honest, non-bypassed sticky behavior."""
34
+
35
+ from __future__ import annotations
36
+
37
+ from collections import deque
38
+ from dataclasses import asdict, dataclass, field
39
+
40
+ from risk.kill_switch import evaluate_kill_switch
41
+ from risk_controls import assess_drawdown_lock
42
+
43
+ _RETURN_HISTORY_MAXLEN = 252
44
+
45
+
46
+ @dataclass(frozen=True)
47
+ class KillSwitchReplayRecord:
48
+ date: str
49
+ tripped: bool
50
+ severity: str
51
+ triggers: list = field(default_factory=list)
52
+ sticky_reason_active: bool = False
53
+ trade_lock_reason: str | None = None
54
+ would_be_locked: bool = False
55
+
56
+ def to_dict(self) -> dict:
57
+ return asdict(self)
58
+
59
+
60
+ def _is_sticky_reason(reason: str | None) -> bool:
61
+ """Byte-identical predicate to main.py:6178-6180's
62
+ trade_lock_reason_is_sticky check - kept as its own function so it
63
+ can never silently drift from the live condition it mirrors."""
64
+ return reason == "total_drawdown_limit_breached" or str(reason or "").startswith("kill_switch_")
65
+
66
+
67
+ def replay_kill_switch_over_dataset(
68
+ dates: list,
69
+ daily_portfolio_returns: dict,
70
+ kill_switch_config: dict,
71
+ *,
72
+ max_daily_drawdown_pct: float,
73
+ max_total_drawdown_pct: float,
74
+ starting_portfolio_value: float = 1.0,
75
+ ) -> list:
76
+ """Day-by-day, in `dates` order (must already be sorted - callers own
77
+ that, same convention as rank_book_simulator.py's unique_dates loop).
78
+
79
+ daily_portfolio_returns: {date: net_return} - reuse simulate_rank_book()'s
80
+ own per_date_net_return/per_date pair directly (dict(zip(per_date,
81
+ per_date_net_return))) rather than inventing a second return series.
82
+ A date missing from this dict defaults to 0.0 return (a flat/no-trade
83
+ day), never KeyError.
84
+
85
+ Mirrors main.py:6140-6345's exact per-date sequence: (1) sticky-lock
86
+ clear/keep using the reason carried over from the PRIOR date, (2)
87
+ portfolio_value/peak_equity/drawdown update from this date's return,
88
+ (3) return-history + drawdown-velocity update, (4)
89
+ assess_drawdown_lock() check, (5) evaluate_kill_switch() check - in
90
+ that exact order, since main.py's own ordering determines which
91
+ reason wins when more than one would fire the same date. Returns one
92
+ dict (KillSwitchReplayRecord.to_dict()) per date."""
93
+ return_history: deque = deque(maxlen=_RETURN_HISTORY_MAXLEN)
94
+ previous_portfolio_value = None
95
+ previous_total_drawdown = None
96
+ portfolio_value = float(starting_portfolio_value)
97
+ peak_equity = portfolio_value
98
+ trade_lock_active = False
99
+ trade_lock_reason = None
100
+
101
+ records = []
102
+
103
+ for date in dates:
104
+ # (1) sticky-lock clear/keep, using the reason carried over from
105
+ # the PRIOR date - byte-identical predicate to main.py's own.
106
+ if trade_lock_active and not _is_sticky_reason(trade_lock_reason):
107
+ trade_lock_active = False
108
+ trade_lock_reason = None
109
+
110
+ # (2) portfolio value / peak / drawdown, from the offline return
111
+ # series. No separate session/day-open concept exists offline -
112
+ # daily_drawdown collapses to this date's own one-bar return
113
+ # (main.py's own daily_drawdown is itself session-open-to-now,
114
+ # effectively the same figure at Daily resolution where a new
115
+ # session starts every bar in backtest mode).
116
+ net_return = float(daily_portfolio_returns.get(date, 0.0))
117
+ portfolio_value *= 1.0 + net_return
118
+ peak_equity = max(peak_equity, portfolio_value)
119
+ total_drawdown = portfolio_value / max(peak_equity, 1e-9) - 1.0
120
+ daily_drawdown = net_return
121
+
122
+ # (3) return history + drawdown velocity, same deque convention
123
+ # as main.py's self._kill_switch_return_history.
124
+ if previous_portfolio_value is not None and previous_portfolio_value > 0:
125
+ return_history.append(portfolio_value / previous_portfolio_value - 1.0)
126
+ drawdown_velocity = (
127
+ abs(total_drawdown) - abs(previous_total_drawdown) if previous_total_drawdown is not None else None
128
+ )
129
+ previous_portfolio_value = portfolio_value
130
+ previous_total_drawdown = total_drawdown
131
+
132
+ # (4) drawdown-lock breach (risk_controls.py, byte-identical call
133
+ # to main.py's own).
134
+ breach_active, breach_reason = assess_drawdown_lock(
135
+ daily_drawdown, total_drawdown, max_daily_drawdown_pct, max_total_drawdown_pct
136
+ )
137
+ if breach_active:
138
+ trade_lock_active = True
139
+ trade_lock_reason = breach_reason
140
+
141
+ # (5) the kill switch itself - only the two dataset-derivable
142
+ # runtime_metrics inputs are populated; every other input stays
143
+ # None (evaluate_kill_switch()'s own documented None-skip
144
+ # contract handles this cleanly, never fabricates a value).
145
+ runtime_metrics = {
146
+ "recent_bar_returns": list(return_history),
147
+ "drawdown_velocity_pct_per_bar": drawdown_velocity,
148
+ "live_rank_ic": None,
149
+ "consecutive_losses": None,
150
+ "slippage_divergence_bps": None,
151
+ "model_age_days": None,
152
+ "reconciliation_breach": False,
153
+ }
154
+ decision = evaluate_kill_switch(runtime_metrics, kill_switch_config)
155
+ if decision.tripped:
156
+ trade_lock_active = True
157
+ trade_lock_reason = decision.reason
158
+
159
+ records.append(
160
+ KillSwitchReplayRecord(
161
+ date=str(date),
162
+ tripped=decision.tripped,
163
+ severity=decision.severity,
164
+ triggers=list(decision.triggers),
165
+ sticky_reason_active=_is_sticky_reason(trade_lock_reason),
166
+ trade_lock_reason=trade_lock_reason,
167
+ would_be_locked=trade_lock_active,
168
+ ).to_dict()
169
+ )
170
+
171
+ return records
172
+
173
+
174
+ def summarize_kill_switch_replay(records: list) -> dict:
175
+ """Aggregate trip-count / total-locked-days / locked-day fraction,
176
+ mirroring evaluation/rank_signal_calibration.py::
177
+ summarize_book_history_reconciliation()'s aggregation shape."""
178
+ total_dates = len(records)
179
+ trip_count = sum(1 for record in records if record["tripped"])
180
+ locked_days = sum(1 for record in records if record["would_be_locked"])
181
+ return {
182
+ "total_dates": total_dates,
183
+ "trip_count": trip_count,
184
+ "locked_days": locked_days,
185
+ "locked_day_fraction": (locked_days / total_dates) if total_dates else 0.0,
186
+ }