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.
- aether_quant-0.0.1.dist-info/METADATA +7 -0
- aether_quant-0.0.1.dist-info/RECORD +99 -0
- aether_quant-0.0.1.dist-info/WHEEL +5 -0
- aether_quant-0.0.1.dist-info/entry_points.txt +2 -0
- aether_quant-0.0.1.dist-info/licenses/LICENSE +133 -0
- aether_quant-0.0.1.dist-info/top_level.txt +13 -0
- analyzer/README.md +69 -0
- analyzer/__init__.py +17 -0
- analyzer/market_analyzer.py +521 -0
- aq_cli.py +3633 -0
- audit/README.md +47 -0
- audit/__init__.py +38 -0
- audit/hash_chain.py +52 -0
- audit/postgres_audit.py +61 -0
- audit/postgres_worker.py +402 -0
- audit/redis_queue.py +124 -0
- audit/status_export.py +62 -0
- data_pipeline/README.md +257 -0
- data_pipeline/__init__.py +6 -0
- data_pipeline/bar_synthesis.py +97 -0
- data_pipeline/dividend_backfill.py +243 -0
- data_pipeline/factor_file_backfill.py +276 -0
- data_pipeline/fetch.py +206 -0
- data_pipeline/fred_backfill.py +435 -0
- data_pipeline/ib_backfill.py +287 -0
- data_pipeline/v2_manifest.py +75 -0
- data_pipeline/yfinance_backfill.py +501 -0
- evaluation/README.md +152 -0
- evaluation/__init__.py +73 -0
- evaluation/ablation.py +310 -0
- evaluation/benchmark_comparison.py +195 -0
- evaluation/confidence_threshold_calibration.py +157 -0
- evaluation/factor_neutralization_check.py +94 -0
- evaluation/feature_parity.py +321 -0
- evaluation/feature_reconciliation.py +286 -0
- evaluation/impact_model.py +77 -0
- evaluation/kill_switch_replay.py +186 -0
- evaluation/limit_fill_simulator.py +152 -0
- evaluation/model_predictions.py +192 -0
- evaluation/monte_carlo.py +161 -0
- evaluation/public_benchmarks.py +117 -0
- evaluation/rank_book_simulator.py +494 -0
- evaluation/rank_ic_core.py +204 -0
- evaluation/rank_signal_calibration.py +690 -0
- evaluation/rolling_ic_gate_calibration.py +190 -0
- evaluation/rolling_ic_gate_replay.py +138 -0
- execution/README.md +281 -0
- execution/__init__.py +80 -0
- execution/config_cache.py +48 -0
- execution/cost_model.py +213 -0
- execution/lean_config_render.py +131 -0
- execution/live_credentials.py +38 -0
- execution/live_credentials_io.py +52 -0
- execution/order_gate.py +388 -0
- execution/paper_readiness.py +181 -0
- execution/paper_readiness_io.py +54 -0
- execution/paper_readiness_report.py +103 -0
- execution/paper_readiness_scheduler.py +137 -0
- execution/reconciliation.py +160 -0
- execution/runtime_config_io.py +38 -0
- execution/secret_scan.py +73 -0
- features/README.md +77 -0
- features/__init__.py +137 -0
- features/alt_data_features.py +154 -0
- features/bond_features.py +275 -0
- features/cross_asset_sensitivity.py +79 -0
- features/derivatives_macro_features.py +72 -0
- features/macro_features.py +79 -0
- features/options_greeks.py +329 -0
- features/sector_map.py +53 -0
- features/technical_indicators.py +185 -0
- generate_backtest_report.py +311 -0
- generate_evaluation_report.py +712 -0
- inference/README.md +105 -0
- inference/__init__.py +36 -0
- inference/exported_model.py +929 -0
- inference/parallel_inference.py +160 -0
- inference/strategy_selector_inference.py +75 -0
- json_safety.py +130 -0
- portfolio/README.md +447 -0
- portfolio/__init__.py +41 -0
- portfolio/book_construction.py +786 -0
- portfolio/book_neutrality.py +178 -0
- portfolio/hrp_allocation.py +159 -0
- portfolio/options_arbitrage_detector.py +232 -0
- portfolio/options_assignment_risk.py +119 -0
- portfolio/options_margin_sizing.py +333 -0
- portfolio/options_strategy.py +1999 -0
- portfolio/rank_signal.py +219 -0
- portfolio/rolling_ic_gate.py +183 -0
- risk/README.md +275 -0
- risk/__init__.py +38 -0
- risk/asset_class_router.py +584 -0
- risk/forex_risk.py +158 -0
- risk/futures_risk.py +202 -0
- risk/kill_switch.py +261 -0
- risk/manual_override.py +118 -0
- risk/position_sizing.py +303 -0
- 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
|
+
}
|