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,190 @@
|
|
|
1
|
+
"""Calibrates `phase_v2.rolling_ic_gate.min_rolling_mean_ic` from real data
|
|
2
|
+
(V5.3.5, development/Problems.md #102) - the same "derive the number,
|
|
3
|
+
don't guess it" discipline `aq evaluate --calibrate-book-spread` already
|
|
4
|
+
established for `min_rank_confidence_spread`, applied to this round's new
|
|
5
|
+
gate so its shipped floor is never a hand-guessed constant either.
|
|
6
|
+
|
|
7
|
+
Deliberately reuses, never re-derives: `portfolio.rolling_ic_gate.
|
|
8
|
+
compute_rolling_ic_state()` (the exact aggregation the live gate and
|
|
9
|
+
`evaluation/rolling_ic_gate_replay.py` both call) and `evaluation.
|
|
10
|
+
rank_ic_core.resolve_realized_rank_ic_observations()` beneath it. A
|
|
11
|
+
calibrated floor computed here can never silently disagree with what the
|
|
12
|
+
live gate means by "rolling IC," because it is the same code, not a
|
|
13
|
+
parallel approximation.
|
|
14
|
+
|
|
15
|
+
WALK-FORWARD, NOT A SINGLE FULL-HISTORY READING: naively calling
|
|
16
|
+
`compute_rolling_ic_state()` once on the dataset's entire event history
|
|
17
|
+
would let observations whose resolution only became known LATE in the
|
|
18
|
+
dataset leak into a rolling-window reading nominally "as of" an EARLIER
|
|
19
|
+
sample date - a real lookahead bug, since `resolve_realized_rank_ic_observations()`
|
|
20
|
+
resolves every observation using the full buffer's own future close
|
|
21
|
+
prices, not bounded to any particular "as of" date. This module avoids
|
|
22
|
+
that by sampling a strided sequence of dates and, at each one, slicing
|
|
23
|
+
the event buffer to only events dated on-or-before that sample date
|
|
24
|
+
before calling `compute_rolling_ic_state()` - exactly what a live buffer
|
|
25
|
+
would contain by that date, never more. `evaluation/rolling_ic_gate_replay.py`
|
|
26
|
+
shares this same buffer-slicing discipline (see that module's own
|
|
27
|
+
docstring) since it needs the identical no-lookahead guarantee for a
|
|
28
|
+
different purpose (a per-date engagement decision instead of a
|
|
29
|
+
calibration distribution).
|
|
30
|
+
|
|
31
|
+
`sample_stride_days=5` (not every single date) keeps this an O(num_samples
|
|
32
|
+
x average_buffer_size) offline computation rather than O(num_dates^2) -
|
|
33
|
+
acceptable for a tool run once, by hand, never on any per-bar live path.
|
|
34
|
+
"""
|
|
35
|
+
|
|
36
|
+
from __future__ import annotations
|
|
37
|
+
|
|
38
|
+
import bisect
|
|
39
|
+
|
|
40
|
+
import numpy as np
|
|
41
|
+
import pandas as pd
|
|
42
|
+
|
|
43
|
+
from portfolio.rolling_ic_gate import compute_rolling_ic_state
|
|
44
|
+
|
|
45
|
+
_ROLLING_IC_DISTRIBUTION_PERCENTILES = {"p10": 0.10, "p25": 0.25, "median": 0.50, "p75": 0.75}
|
|
46
|
+
|
|
47
|
+
# Same sentinel value as portfolio.rolling_ic_gate's own (private,
|
|
48
|
+
# module-local) _NEVER_BELOW - kept as an independent local copy rather
|
|
49
|
+
# than a cross-module import of a private name, matching how
|
|
50
|
+
# risk/kill_switch.py's own _NEVER_BELOW is never imported elsewhere
|
|
51
|
+
# either. Only meaningful as "the gate's own never-trips floor value";
|
|
52
|
+
# never compared against the other module's copy directly.
|
|
53
|
+
_NEVER_BELOW = -1e12
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def build_event_buffer(
|
|
57
|
+
dataset: pd.DataFrame,
|
|
58
|
+
*,
|
|
59
|
+
raw_score_column: str,
|
|
60
|
+
ticker_column: str = "ticker",
|
|
61
|
+
date_column: str = "date",
|
|
62
|
+
close_column: str = "close",
|
|
63
|
+
) -> list[dict]:
|
|
64
|
+
"""Converts `dataset` into the flat, date-sorted event-dict shape
|
|
65
|
+
`compute_rolling_ic_state()`/`resolve_realized_rank_ic_observations()`
|
|
66
|
+
expect - the offline equivalent of main.py's Pass 1c buffer append,
|
|
67
|
+
reused by both this module and `evaluation/rolling_ic_gate_replay.py`
|
|
68
|
+
so the two tools can never disagree about what an "event" is. Rows
|
|
69
|
+
missing either the raw score or the close price are skipped (mirrors
|
|
70
|
+
`resolve_realized_rank_ic_observations()`'s own "model still warming
|
|
71
|
+
up" skip contract), never fabricated."""
|
|
72
|
+
ordered = dataset.sort_values(date_column, kind="stable")
|
|
73
|
+
events: list[dict] = []
|
|
74
|
+
for ticker, date, score, close in zip(
|
|
75
|
+
ordered[ticker_column], ordered[date_column], ordered[raw_score_column], ordered[close_column]
|
|
76
|
+
):
|
|
77
|
+
if score is None or (isinstance(score, float) and np.isnan(score)):
|
|
78
|
+
continue
|
|
79
|
+
if close is None or (isinstance(close, float) and np.isnan(close)):
|
|
80
|
+
continue
|
|
81
|
+
events.append(
|
|
82
|
+
{
|
|
83
|
+
"ticker": str(ticker),
|
|
84
|
+
"created_at": f"{date}T00:00:00Z",
|
|
85
|
+
"resolved_predicted_rank_20d": float(score),
|
|
86
|
+
"close_price": float(close),
|
|
87
|
+
}
|
|
88
|
+
)
|
|
89
|
+
return events
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def calibrate_rolling_ic_floor(
|
|
93
|
+
dataset: pd.DataFrame,
|
|
94
|
+
*,
|
|
95
|
+
raw_score_column: str,
|
|
96
|
+
ticker_column: str = "ticker",
|
|
97
|
+
date_column: str = "date",
|
|
98
|
+
close_column: str = "close",
|
|
99
|
+
horizon_days: int,
|
|
100
|
+
rolling_window_days: int,
|
|
101
|
+
percentile: float = 0.10,
|
|
102
|
+
sample_stride_days: int = 5,
|
|
103
|
+
min_names_per_date: int = 10,
|
|
104
|
+
) -> dict:
|
|
105
|
+
"""Walk-forward: at every `sample_stride_days`-th unique date in
|
|
106
|
+
`dataset`, computes the rolling IC state a live buffer would have had
|
|
107
|
+
by that date (event buffer sliced to <= that date, via
|
|
108
|
+
`build_event_buffer()` + `compute_rolling_ic_state()`), collects every
|
|
109
|
+
non-None `rolling_mean_ic` reading into a distribution, and returns
|
|
110
|
+
the `percentile`-th quantile as the calibrated floor.
|
|
111
|
+
|
|
112
|
+
Sample dates before enough history has accumulated (compute_rolling_ic_state()
|
|
113
|
+
returns `rolling_mean_ic=None`) are EXCLUDED from the distribution, not
|
|
114
|
+
counted as a 0.0 reading - a cold-start gap is missing data, not
|
|
115
|
+
evidence of zero skill.
|
|
116
|
+
|
|
117
|
+
`min_names_per_date` (V5.3.5, development/Problems.md #102) - passed
|
|
118
|
+
through to `compute_rolling_ic_state()`. Defaults to 10, well above
|
|
119
|
+
`compute_rolling_ic_state()`'s own pure-function default of 2: a real
|
|
120
|
+
run against this project's historical dataset found the p10-percentile
|
|
121
|
+
floor dominated by spurious +-1.0 readings from origin dates where
|
|
122
|
+
only 2-3 names had resolved (thin-universe/model-warmup dates,
|
|
123
|
+
mathematically forced to an extreme correlation regardless of real
|
|
124
|
+
skill) - excluding them here is what makes the resulting distribution
|
|
125
|
+
represent genuine cross-sectional skill rather than early-history
|
|
126
|
+
noise. See evaluation.rank_ic_core.rank_ic_from_arrays()'s own
|
|
127
|
+
docstring for the full mechanism.
|
|
128
|
+
|
|
129
|
+
Returns:
|
|
130
|
+
{"calibrated_min_rolling_mean_ic": float,
|
|
131
|
+
"percentile": float,
|
|
132
|
+
"num_samples_used": int,
|
|
133
|
+
"num_samples_skipped_insufficient_history": int,
|
|
134
|
+
"rolling_ic_distribution": {"min", "p10", "p25", "median", "p75", "max"}}
|
|
135
|
+
|
|
136
|
+
An empty/all-thin dataset returns calibrated_min_rolling_mean_ic=_NEVER_BELOW
|
|
137
|
+
(portfolio.rolling_ic_gate's own "gate never trips" sentinel) and an
|
|
138
|
+
all-None distribution, never raises."""
|
|
139
|
+
events = build_event_buffer(
|
|
140
|
+
dataset, raw_score_column=raw_score_column, ticker_column=ticker_column,
|
|
141
|
+
date_column=date_column, close_column=close_column,
|
|
142
|
+
)
|
|
143
|
+
if not events:
|
|
144
|
+
return {
|
|
145
|
+
"calibrated_min_rolling_mean_ic": _NEVER_BELOW,
|
|
146
|
+
"percentile": percentile,
|
|
147
|
+
"num_samples_used": 0,
|
|
148
|
+
"num_samples_skipped_insufficient_history": 0,
|
|
149
|
+
"rolling_ic_distribution": {"min": None, "p10": None, "p25": None, "median": None, "p75": None, "max": None},
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
event_dates = [str(event["created_at"])[:10] for event in events]
|
|
153
|
+
unique_dates = sorted(set(event_dates))
|
|
154
|
+
sample_dates = unique_dates[::sample_stride_days] if sample_stride_days > 0 else unique_dates
|
|
155
|
+
|
|
156
|
+
readings: list[float] = []
|
|
157
|
+
num_samples_skipped_insufficient_history = 0
|
|
158
|
+
for sample_date in sample_dates:
|
|
159
|
+
cutoff_index = bisect.bisect_right(event_dates, sample_date)
|
|
160
|
+
buffer_up_to_date = events[:cutoff_index]
|
|
161
|
+
state = compute_rolling_ic_state(
|
|
162
|
+
buffer_up_to_date, horizon_days=horizon_days, rolling_window_days=rolling_window_days,
|
|
163
|
+
min_names_per_date=min_names_per_date,
|
|
164
|
+
)
|
|
165
|
+
if state["rolling_mean_ic"] is None:
|
|
166
|
+
num_samples_skipped_insufficient_history += 1
|
|
167
|
+
continue
|
|
168
|
+
readings.append(state["rolling_mean_ic"])
|
|
169
|
+
|
|
170
|
+
if not readings:
|
|
171
|
+
return {
|
|
172
|
+
"calibrated_min_rolling_mean_ic": _NEVER_BELOW,
|
|
173
|
+
"percentile": percentile,
|
|
174
|
+
"num_samples_used": 0,
|
|
175
|
+
"num_samples_skipped_insufficient_history": num_samples_skipped_insufficient_history,
|
|
176
|
+
"rolling_ic_distribution": {"min": None, "p10": None, "p25": None, "median": None, "p75": None, "max": None},
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
readings_array = np.array(readings, dtype=np.float64)
|
|
180
|
+
distribution = {"min": float(np.min(readings_array)), "max": float(np.max(readings_array))}
|
|
181
|
+
for name, quantile in _ROLLING_IC_DISTRIBUTION_PERCENTILES.items():
|
|
182
|
+
distribution[name] = float(np.quantile(readings_array, quantile))
|
|
183
|
+
|
|
184
|
+
return {
|
|
185
|
+
"calibrated_min_rolling_mean_ic": float(np.quantile(readings_array, percentile)),
|
|
186
|
+
"percentile": percentile,
|
|
187
|
+
"num_samples_used": len(readings),
|
|
188
|
+
"num_samples_skipped_insufficient_history": num_samples_skipped_insufficient_history,
|
|
189
|
+
"rolling_ic_distribution": distribution,
|
|
190
|
+
}
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
"""Day-by-day OFFLINE replay of `portfolio.rolling_ic_gate`'s two decision
|
|
2
|
+
functions against a historical dataset (V5.3.5, development/Problems.md
|
|
3
|
+
#102) - the direct sibling of `evaluation/kill_switch_replay.py`'s
|
|
4
|
+
day-by-day, no-lookahead, walk-forward structure, for this round's new
|
|
5
|
+
rolling-IC gate instead of the kill switch.
|
|
6
|
+
|
|
7
|
+
This is the critical pre-`main.py` checkpoint the V5.3.5 plan calls out:
|
|
8
|
+
run this against the historical dataset with `evaluation/
|
|
9
|
+
rolling_ic_gate_calibration.py`'s calibrated floor and confirm
|
|
10
|
+
disengagement concentrates in the three known bad eras (Apr-Sep 2019,
|
|
11
|
+
Dec 2019-Mar 2020, Jun-Sep 2020) rather than spreading uniformly across
|
|
12
|
+
the whole run - entirely offline, before `main.py` is touched at all. A
|
|
13
|
+
uniform reduction would mean this gate is just a redundant second
|
|
14
|
+
dispersion floor, not a genuine skill signal, and is the signal to stop
|
|
15
|
+
and revisit before A6 wires anything into the live path.
|
|
16
|
+
|
|
17
|
+
NO-LOOKAHEAD DISCIPLINE - the single most important property this module
|
|
18
|
+
has to get right: at each rebalance date, the event buffer passed to
|
|
19
|
+
`compute_rolling_ic_state()` is built from `evaluation.
|
|
20
|
+
rolling_ic_gate_calibration.build_event_buffer()` and then sliced to only
|
|
21
|
+
events dated on-or-before that date (the same technique, and the same
|
|
22
|
+
reason, that module's own docstring explains) - a decision "as of" date D
|
|
23
|
+
must never see a row dated after D, exactly matching what main.py's own
|
|
24
|
+
live in-memory buffer could possibly contain by that point in a real run.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
from __future__ import annotations
|
|
28
|
+
|
|
29
|
+
import bisect
|
|
30
|
+
|
|
31
|
+
from evaluation.rolling_ic_gate_calibration import build_event_buffer
|
|
32
|
+
from portfolio.rolling_ic_gate import compute_rolling_ic_state, evaluate_rolling_ic_gate
|
|
33
|
+
|
|
34
|
+
# development/Problems.md #102's own three named bad eras, found from this
|
|
35
|
+
# round's research into rolling IC vs. the model's per-era IC diagnostic
|
|
36
|
+
# (#71) - used only by summarize_rolling_ic_gate_replay()'s per-era
|
|
37
|
+
# breakdown, so the offline report can be read directly against them
|
|
38
|
+
# without a throwaway script re-deriving these boundaries by hand.
|
|
39
|
+
KNOWN_ERAS = {
|
|
40
|
+
"era_0_good": ("2019-01-01", "2019-04-01"),
|
|
41
|
+
"era_1_bad_apr_sep_2019": ("2019-04-01", "2019-09-01"),
|
|
42
|
+
"era_2_bad_dec2019_mar2020": ("2019-12-01", "2020-03-01"),
|
|
43
|
+
"era_3_bad_jun_sep_2020": ("2020-06-01", "2020-09-01"),
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def replay_rolling_ic_gate_over_dataset(
|
|
48
|
+
dataset,
|
|
49
|
+
*,
|
|
50
|
+
raw_score_column: str,
|
|
51
|
+
ticker_column: str = "ticker",
|
|
52
|
+
date_column: str = "date",
|
|
53
|
+
close_column: str = "close",
|
|
54
|
+
rebalance_dates: list[str],
|
|
55
|
+
horizon_days: int,
|
|
56
|
+
rolling_window_days: int,
|
|
57
|
+
gate_config: dict,
|
|
58
|
+
min_names_per_date: int = 10,
|
|
59
|
+
) -> list[dict]:
|
|
60
|
+
"""Builds the full event buffer once (`build_event_buffer()`), then for
|
|
61
|
+
each date in `rebalance_dates` (must already be sorted - callers own
|
|
62
|
+
that, same convention as `rank_book_simulator.py`'s unique_dates loop;
|
|
63
|
+
should be the SAME cadence a real book rebalance uses, not necessarily
|
|
64
|
+
every calendar date, matching main.py's own gate-is-only-consulted-on-
|
|
65
|
+
rebalance-bars design) slices the buffer to events dated <= that date
|
|
66
|
+
and evaluates the gate exactly as `portfolio.book_construction.
|
|
67
|
+
_select_book_group()` would.
|
|
68
|
+
|
|
69
|
+
`min_names_per_date` (V5.3.5, development/Problems.md #102) - passed
|
|
70
|
+
through to `compute_rolling_ic_state()`; defaults to 10 for the same
|
|
71
|
+
reason `evaluation/rolling_ic_gate_calibration.py::
|
|
72
|
+
calibrate_rolling_ic_floor()` does (see that function's own
|
|
73
|
+
docstring) - a real replay run at this module's own default of 2
|
|
74
|
+
showed the calibrated floor barely engaging during two of three known
|
|
75
|
+
historically-bad eras, traced to thin-universe origin dates forcing
|
|
76
|
+
spurious +-1.0 IC readings into the rolling mean.
|
|
77
|
+
|
|
78
|
+
Returns one dict per rebalance date: {"date", "engaged", "reason",
|
|
79
|
+
"observed_rolling_mean_ic", "min_rolling_mean_ic", "num_resolved_dates"}
|
|
80
|
+
- `evaluate_rolling_ic_gate()`'s own result dict plus "date"."""
|
|
81
|
+
events = build_event_buffer(
|
|
82
|
+
dataset, raw_score_column=raw_score_column, ticker_column=ticker_column,
|
|
83
|
+
date_column=date_column, close_column=close_column,
|
|
84
|
+
)
|
|
85
|
+
event_dates = [str(event["created_at"])[:10] for event in events]
|
|
86
|
+
|
|
87
|
+
records = []
|
|
88
|
+
for date in rebalance_dates:
|
|
89
|
+
cutoff_index = bisect.bisect_right(event_dates, str(date))
|
|
90
|
+
buffer_up_to_date = events[:cutoff_index]
|
|
91
|
+
state = compute_rolling_ic_state(
|
|
92
|
+
buffer_up_to_date, horizon_days=horizon_days, rolling_window_days=rolling_window_days,
|
|
93
|
+
min_names_per_date=min_names_per_date,
|
|
94
|
+
)
|
|
95
|
+
result = evaluate_rolling_ic_gate(state, gate_config)
|
|
96
|
+
records.append({"date": str(date), **result})
|
|
97
|
+
|
|
98
|
+
return records
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _era_for_date(date: str) -> str | None:
|
|
102
|
+
for era_name, (start, end) in KNOWN_ERAS.items():
|
|
103
|
+
if start <= date < end:
|
|
104
|
+
return era_name
|
|
105
|
+
return None
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def summarize_rolling_ic_gate_replay(records: list[dict]) -> dict:
|
|
109
|
+
"""Aggregate engaged/disengaged fractions overall and per known era
|
|
110
|
+
(`KNOWN_ERAS` above), mirroring `evaluation/kill_switch_replay.py::
|
|
111
|
+
summarize_kill_switch_replay()`'s aggregation shape. Dates outside
|
|
112
|
+
every named era are still counted in `"overall"` but not attributed to
|
|
113
|
+
any `"by_era"` entry - `KNOWN_ERAS` deliberately doesn't cover the
|
|
114
|
+
whole historical window, only the four eras this round's research
|
|
115
|
+
already characterized."""
|
|
116
|
+
total_dates = len(records)
|
|
117
|
+
disengaged = [record for record in records if not record["engaged"]]
|
|
118
|
+
disengaged_by_floor = [record for record in records if record["reason"] == "rolling_ic_below_floor"]
|
|
119
|
+
|
|
120
|
+
by_era: dict[str, dict] = {}
|
|
121
|
+
for era_name in KNOWN_ERAS:
|
|
122
|
+
era_records = [record for record in records if _era_for_date(record["date"]) == era_name]
|
|
123
|
+
era_disengaged = [record for record in era_records if not record["engaged"]]
|
|
124
|
+
by_era[era_name] = {
|
|
125
|
+
"total_dates": len(era_records),
|
|
126
|
+
"disengaged_days": len(era_disengaged),
|
|
127
|
+
"disengaged_day_fraction": (len(era_disengaged) / len(era_records)) if era_records else None,
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
return {
|
|
131
|
+
"overall": {
|
|
132
|
+
"total_dates": total_dates,
|
|
133
|
+
"disengaged_days": len(disengaged),
|
|
134
|
+
"disengaged_day_fraction": (len(disengaged) / total_dates) if total_dates else 0.0,
|
|
135
|
+
"disengaged_days_below_floor": len(disengaged_by_floor),
|
|
136
|
+
},
|
|
137
|
+
"by_era": by_era,
|
|
138
|
+
}
|
execution/README.md
ADDED
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
# execution
|
|
2
|
+
|
|
3
|
+
Pure, Lean-free order gating, cost/slippage math, and paper/live readiness
|
|
4
|
+
checks shared between `main.py` and the test suite. Nothing here imports
|
|
5
|
+
`AlgorithmImports`/`QCAlgorithm` — every module is unit-testable without a
|
|
6
|
+
Lean runtime; `main.py` is the only place that touches Lean's runtime types
|
|
7
|
+
and wires these modules to it.
|
|
8
|
+
|
|
9
|
+
## Core order gating (`order_gate.py`)
|
|
10
|
+
|
|
11
|
+
- `resolve_runtime_mode(raw_mode)` — normalizes `phase_v2.runtime.mode`,
|
|
12
|
+
failing safe to `"observation"`. Valid modes: `backtest`, `observation`,
|
|
13
|
+
`paper`, `live`.
|
|
14
|
+
- `resolve_order_permission(mode, allow_live_orders, broker_config_present,
|
|
15
|
+
risk_locks_healthy)` — the mode → real-vs-simulated order decision table.
|
|
16
|
+
`observation` always returns `False` regardless of other flags (the one
|
|
17
|
+
safety invariant this phase depends on); `backtest` always unrestricted;
|
|
18
|
+
`paper`/`live` need the matching flags AND healthy risk locks
|
|
19
|
+
(V5.4.5, Problems.md #116 — paper previously ignored the kill switch).
|
|
20
|
+
- `simulate_fill(close_price, target_weight, equity, slippage_bps=0.0)` —
|
|
21
|
+
hypothetical fill-price/quantity/notional math used by
|
|
22
|
+
`experience/simulated_portfolio.py`. `fill_price = close_price +
|
|
23
|
+
slippage_amount(...)`; quantity/notional = `target_weight * equity` at
|
|
24
|
+
that price. All-zero for non-positive `close_price`.
|
|
25
|
+
- `is_real_order_placement(execution_note, orders_allowed)` — classifies an
|
|
26
|
+
execution note as a genuine real order vs. simulated (`"simulated_"`
|
|
27
|
+
prefix) or a known no-op (denylists `_NO_OP_EXECUTION_NOTES` +
|
|
28
|
+
`_NO_OP_EXECUTION_NOTE_SUFFIXES`). Backs the real-order audit-log hook in
|
|
29
|
+
`on_data()`'s Pass 2.
|
|
30
|
+
|
|
31
|
+
## Expected-net-edge cost model (`cost_model.py`)
|
|
32
|
+
|
|
33
|
+
Entry-decision side of cost-awareness (sibling to, not a replacement for,
|
|
34
|
+
the fill/pricing math below): does this trade's expected edge clear its
|
|
35
|
+
expected cost.
|
|
36
|
+
|
|
37
|
+
- `estimate_round_trip_cost_bps(liquidity_payload, *, commission_bps_per_side,
|
|
38
|
+
min_commission_usd, order_value, extra_slippage_bps)` — reads
|
|
39
|
+
`liquidity_payload["estimated_round_trip_cost"]`, **never recomputes
|
|
40
|
+
slippage**; adds a commission leg (bps of order value) covering BOTH
|
|
41
|
+
round-trip sides — per side = `max(rate leg, min_commission_usd floor)`
|
|
42
|
+
(V5.4.5, Problems.md #116 — one side was charged against a round-trip
|
|
43
|
+
contract) — plus an optional `extra_slippage_bps` buffer. Non-finite
|
|
44
|
+
estimates fail the gate closed with an explicit reason (#117).
|
|
45
|
+
- `expected_edge_bps(predicted_rank, *, edge_bps_per_rank_unit, holding_bars,
|
|
46
|
+
horizon_days, trade_direction=1)` — linear in rank deviation from the
|
|
47
|
+
median (0.5), scaled down when `holding_bars` < the rank head's forward
|
|
48
|
+
horizon. `trade_direction` (+1 long/-1 short) must be the sign of the
|
|
49
|
+
trade being evaluated — measures edge in the direction of the trade, not
|
|
50
|
+
just the long-side edge.
|
|
51
|
+
`None` prediction → `0.0`.
|
|
52
|
+
- `build_net_edge_decision(predicted_rank, liquidity_payload, order_value,
|
|
53
|
+
cost_config, *, trade_direction=1)` — consumed by
|
|
54
|
+
`analyzer/market_analyzer.py`'s Priority 6.5 tier and
|
|
55
|
+
`risk/position_sizing.py::cost_sizing_multiplier()`. **Fail-open,
|
|
56
|
+
always**: `passes=True` when the gate is disabled, `edge_bps_per_rank_unit`
|
|
57
|
+
is uncalibrated (`0.0`), or the rank prediction is missing. Config:
|
|
58
|
+
`phase_v2.costs` (`enabled: false` until calibrated via
|
|
59
|
+
`aq evaluate --calibrate-edge`).
|
|
60
|
+
|
|
61
|
+
## Position reconciliation (`reconciliation.py`)
|
|
62
|
+
|
|
63
|
+
`reconcile_positions(expected_by_symbol, actual_by_symbol, *,
|
|
64
|
+
weight_tolerance, value_tolerance_usd, portfolio_value,
|
|
65
|
+
max_tolerated_drift=None) -> ReconciliationReport` — compares the book's
|
|
66
|
+
intended weights against what a broker (or simulated portfolio) actually
|
|
67
|
+
holds. Classifies each symbol `matched` (within both `weight_tolerance` and
|
|
68
|
+
`value_tolerance_usd`), `drifted` (outside tolerance), `orphan_broker`
|
|
69
|
+
(held, not in book) or `missing_broker` (in book, not held).
|
|
70
|
+
`max_abs_weight_drift` = largest drift among non-matched symbols;
|
|
71
|
+
`breach=True` past `max_tolerated_drift`. `main.py` calls it once per bar
|
|
72
|
+
(portfolio-book path); a breach feeds `risk/kill_switch.py`'s trigger
|
|
73
|
+
inputs, so it can actually stop trading, not just log.
|
|
74
|
+
|
|
75
|
+
## Real fill slippage
|
|
76
|
+
|
|
77
|
+
`liquidity/market_liquidity.py`'s `estimated_round_trip_cost` was
|
|
78
|
+
sizing/routing input only; now wired into real and simulated fills too.
|
|
79
|
+
|
|
80
|
+
- `resolve_slippage_bps(symbol_key, slippage_bps_by_symbol, max_bps=
|
|
81
|
+
MAX_LIQUIDITY_SLIPPAGE_BPS)` — lookup + clamp. Missing symbol → `0.0`;
|
|
82
|
+
clamp default `MAX_LIQUIDITY_SLIPPAGE_BPS = 500.0` (5%, a guard against a
|
|
83
|
+
degenerate estimate — normal participation never approaches it).
|
|
84
|
+
- `slippage_amount(reference_price, slippage_bps)` — the one bps→price
|
|
85
|
+
formula in the codebase, shared by real and simulated fills.
|
|
86
|
+
- `resolve_fill_slippage(symbol_key, reference_price, slippage_bps_by_symbol,
|
|
87
|
+
max_bps=...)` — composes the two above; used by `main.py`'s real Lean
|
|
88
|
+
fill path.
|
|
89
|
+
- `liquidity_cost_fraction(liquidity_payload, source)` — picks
|
|
90
|
+
`estimated_round_trip_cost` vs `estimated_slippage` per config.
|
|
91
|
+
`resolve_fill_slippage_source(raw_source)` normalizes/fails-safe (same
|
|
92
|
+
pattern as `resolve_runtime_mode()`).
|
|
93
|
+
|
|
94
|
+
Config `phase_v2.liquidity.fill_slippage` (`main.py::_ensure_ready()`):
|
|
95
|
+
`source` (default `"round_trip"` = impact+spread combined — the default
|
|
96
|
+
because Lean's own fill model has no bid-ask awareness, so this is the only
|
|
97
|
+
place spread cost ever reaches a fill price; `"impact_only"` = impact
|
|
98
|
+
alone), `max_bps` (default `500.0`).
|
|
99
|
+
|
|
100
|
+
**Real Lean fills**: `_LiquidityAwareSlippageModel` (`main.py`, duck-typed
|
|
101
|
+
against Lean's `ISlippageModel.GetSlippageApproximation(asset, order)`) is
|
|
102
|
+
attached per-security via `security.SetSlippageModel(...)` in `_add_asset()`;
|
|
103
|
+
reads `self.latest_liquidity_slippage_bps` (refreshed every bar in
|
|
104
|
+
`on_data()` Pass 2) and delegates to `resolve_fill_slippage()`.
|
|
105
|
+
**Observation-mode fills**: `simulated_portfolio.py::enter_long()` takes
|
|
106
|
+
`slippage_bps: float = 0.0` threaded to `simulate_fill()`; every `main.py`
|
|
107
|
+
call site passes `resolve_slippage_bps(...)` so real and simulated fills
|
|
108
|
+
charge the identical estimate.
|
|
109
|
+
|
|
110
|
+
## Real limit orders
|
|
111
|
+
|
|
112
|
+
Config-gated alternative to market orders (`phase_v2.limit_orders.enabled`):
|
|
113
|
+
the code default is `false` (a global kill switch — disabling it makes every
|
|
114
|
+
routing call site byte-for-byte identical to the plain market-order path),
|
|
115
|
+
but the shipped `config.json` turns it **on** for all 5 asset classes,
|
|
116
|
+
where it has been extensively exercised in real backtests since 2026-07-20
|
|
117
|
+
(development/Problems.md #34/#96: 45 real `order-events.json` files show
|
|
118
|
+
continuous limit-order activity, 2,370-4,103 fills per run in several).
|
|
119
|
+
|
|
120
|
+
**Casing convention**: this codebase calls the Lean API in **PascalCase**
|
|
121
|
+
(`self.MarketOrder`, `self.SetHoldings`, `self.SetSlippageModel`) but
|
|
122
|
+
overrides Lean's virtual callbacks in **snake_case** (`initialize`,
|
|
123
|
+
`on_data`). Limit-order code follows the same split:
|
|
124
|
+
PascalCase calls (`self.LimitOrder(...)`, `ticket.Cancel()`,
|
|
125
|
+
`OrderStatus.Filled`), snake_case override (`on_order_event`).
|
|
126
|
+
|
|
127
|
+
- `resolve_limit_price(reference_price, spread_fraction, is_buy,
|
|
128
|
+
offset_multiplier=1.0)` — reuses `liquidity_payload["spread_proxy"]`. Buy
|
|
129
|
+
limits below reference price, sell/short above, offset by half the
|
|
130
|
+
spread × `offset_multiplier`. Fails safe to the unchanged reference price
|
|
131
|
+
for non-positive price/spread.
|
|
132
|
+
- `classify_order_status(status_name)` — classifies into `"pending"` /
|
|
133
|
+
`"filled"` / `"canceled"` / `"unknown"` (unrecognized → `"unknown"`,
|
|
134
|
+
treated as pending). Backed by three tuples (one-line spelling fix if
|
|
135
|
+
Lean's real enum differs):
|
|
136
|
+
- `PENDING_ORDER_STATUS_NAMES` = `New`, `Submitted`, `PartiallyFilled`,
|
|
137
|
+
`UpdateSubmitted`, `CancelPending`
|
|
138
|
+
- `TERMINAL_FILLED_STATUS_NAMES` = `Filled`
|
|
139
|
+
- `TERMINAL_CANCELED_STATUS_NAMES` = `Canceled`, `Invalid`
|
|
140
|
+
|
|
141
|
+
All spellings verified against real `order-events.json` exports
|
|
142
|
+
(`CancelPending` appeared 23 times, 1:1 with confirmed unfilled-timeout
|
|
143
|
+
cancels).
|
|
144
|
+
|
|
145
|
+
Config `phase_v2.limit_orders` (`main.py::_ensure_ready()`): `enabled`
|
|
146
|
+
(default `false`, global kill switch), `asset_classes` (default all 5),
|
|
147
|
+
`offset_multiplier` (default `1.0`; `<1.0` more aggressive/likely to fill,
|
|
148
|
+
`>1.0` more passive), `unfilled_timeout_bars` (default `3`),
|
|
149
|
+
`fallback_to_market_on_timeout` — **per-asset-class dict**, not a single
|
|
150
|
+
bool (mirrors `exposure_caps_by_asset_class`): `true` for equity/crypto/bond
|
|
151
|
+
(fallback = what `SetHoldings` would've placed anyway), `false` for
|
|
152
|
+
future/option (a silent fallback fill is a real, model-unchosen position
|
|
153
|
+
under margin/expiry mechanics — safer to stay flat).
|
|
154
|
+
|
|
155
|
+
**Real Lean fills** (`main.py`): `_try_submit_limit_order()` — shared helper
|
|
156
|
+
called from every real-order branch in `_apply_signal()`/
|
|
157
|
+
`_apply_option_order()`; returns `False` immediately when disabled/asset
|
|
158
|
+
class not configured (caller's market-order call runs instead). Quantity
|
|
159
|
+
from the caller's already-computed
|
|
160
|
+
`_futures_contract_count_for_weight()`/`options_decision.contracts`, or
|
|
161
|
+
`self.CalculateOrderQuantity(symbol, target_weight)` for equity/crypto/bond.
|
|
162
|
+
`OrderTicket` tracked in `self.pending_limit_orders` (keyed by `str(symbol)`).
|
|
163
|
+
`_process_pending_limit_order_timeouts()` runs once per bar (right after
|
|
164
|
+
`_refresh_risk_state()`): cancels anything past `unfilled_timeout_bars`, and
|
|
165
|
+
per the fallback flag optionally places a real `MarketOrder()`.
|
|
166
|
+
`on_order_event(self, order_event)` is Lean's fill/cancel callback — maps
|
|
167
|
+
back to the `pending_limit_orders` entry via
|
|
168
|
+
`self.symbol_key_by_option_contract_symbol` for options (fires on the
|
|
169
|
+
contract symbol) or `str(order_event.Symbol)` otherwise; fill stamps
|
|
170
|
+
`last_trade_bar_by_symbol` and clears the entry, cancel just clears it.
|
|
171
|
+
|
|
172
|
+
**Cooldown-timing change (feature-on only)**: `last_trade_bar_by_symbol`
|
|
173
|
+
normally stamps at order-placement time; with limit orders enabled it
|
|
174
|
+
stamps at confirmed-fill time instead, so a flipped signal isn't blocked by
|
|
175
|
+
a cooldown for a trade that never happened. Disabled: no change. Risk: if
|
|
176
|
+
`on_order_event` never fires, the cooldown stamp is silently skipped.
|
|
177
|
+
|
|
178
|
+
**Observation-mode fills untouched** — `_try_submit_limit_order()` only
|
|
179
|
+
runs inside `if orders_allowed:`, unreachable from simulated `enter_long()`;
|
|
180
|
+
no fill-uncertainty modeling was added to `SimulatedPortfolioState`.
|
|
181
|
+
|
|
182
|
+
## Config-read caching (`config_cache.py`)
|
|
183
|
+
|
|
184
|
+
`read_cached(config_path, loader)` — shared, mtime-gated cache used by
|
|
185
|
+
`paper_readiness_io.py::read_paper_trading_config()`,
|
|
186
|
+
`runtime_config_io.py::read_runtime_mode()`, and (outside this package)
|
|
187
|
+
`risk/manual_override.py::read_manual_trade_lock_override()`. Avoids
|
|
188
|
+
redundant `open()`+`json.load()` on every call while still picking up an
|
|
189
|
+
edit as soon as the file's mtime changes.
|
|
190
|
+
|
|
191
|
+
**Cache key is `(config_path, loader)`, not just `config_path`** — several
|
|
192
|
+
readers share `config.json` within the same bar
|
|
193
|
+
(`main.py::_refresh_risk_state()` calls the manual-override and
|
|
194
|
+
paper-trading readers back-to-back); a path-only cache let one reader's
|
|
195
|
+
value leak into another's result. See `development/Problems.md` #13,
|
|
196
|
+
`tests/test_config_cache.py::test_two_different_loaders_on_the_same_path_do_not_collide`.
|
|
197
|
+
|
|
198
|
+
## Paper/live broker readiness
|
|
199
|
+
|
|
200
|
+
- `paper_readiness.py` (pure) — `evaluate_broker_config()` is the single
|
|
201
|
+
entrypoint `main.py` calls regardless of mode; dispatches to
|
|
202
|
+
`evaluate_paper_broker_config()` (Lean's built-in `PaperBrokerage`, no
|
|
203
|
+
real credentials — brokerage/live-data-provider/manual-review
|
|
204
|
+
attestation flags only) or `evaluate_live_broker_config()` (real
|
|
205
|
+
credentials + `evaluate_live_risk_posture()`). Also
|
|
206
|
+
`evaluate_observation_readiness()`, codifying
|
|
207
|
+
`development/infrastructure.md`'s readiness checklist.
|
|
208
|
+
- `paper_readiness_io.py` (IO) — mtime-cached `read_paper_trading_config()`
|
|
209
|
+
of `phase_v2.paper_trading`, plus `fetch_observation_mode_events()`
|
|
210
|
+
(first `mode='observation'`-filtered `experience_events` query).
|
|
211
|
+
- `paper_readiness_report.py` — offline report (`aq paper-readiness`,
|
|
212
|
+
`build_paper_readiness_view()`/`write_paper_readiness_file()`); writes
|
|
213
|
+
`visualization/grafana/paper_readiness_report.json` (`main.py` has no
|
|
214
|
+
Postgres connection to compute this itself).
|
|
215
|
+
- `live_credentials.py` (pure: `credentials_present()`,
|
|
216
|
+
`describe_missing_fields()`, `postgres_dsn_is_live_safe()`) +
|
|
217
|
+
`live_credentials_io.py` (IO: `load_live_credentials()`,
|
|
218
|
+
`load_postgres_dsn()`) — pre-flight validation for real broker
|
|
219
|
+
credentials (`ib_config.py` or `AETHER_IB_*` via `.env.live`). Does not
|
|
220
|
+
wire Lean itself — Lean reads `ib-*` fields directly from `lean.json`.
|
|
221
|
+
- `runtime_config_io.py::read_runtime_mode()` — mtime-cached read of
|
|
222
|
+
`phase_v2.runtime.mode`, used by `retraining/worker.py`'s
|
|
223
|
+
auto-promote-blocked-in-live-mode safety net (separate process from
|
|
224
|
+
`main.py`).
|
|
225
|
+
|
|
226
|
+
See the Paper Trading Readiness Contract (V2-21) and Live Deployment
|
|
227
|
+
Contract (V2-22) in `development/architecture.md` for the full picture.
|
|
228
|
+
|
|
229
|
+
## Scheduled readiness reporting (`paper_readiness_scheduler.py`)
|
|
230
|
+
|
|
231
|
+
`PaperReadinessScheduler` — periodic loop around
|
|
232
|
+
`build_paper_readiness_view()`/`write_paper_readiness_file()`, so the
|
|
233
|
+
readiness report (already dashboard-visible via `monitoring/api_server.py`'s
|
|
234
|
+
`/api/state` merge + `get_paper_readiness()` endpoint) doesn't go stale
|
|
235
|
+
between manual `aq paper-readiness` runs. Mirrors
|
|
236
|
+
`performance/trigger_worker.py::TriggerWorker`: sync-only, DSN via
|
|
237
|
+
`AETHER_POSTGRES_DSN`, `--once` flag, `_pg_conn` injection for tests. Run as
|
|
238
|
+
its own process: `python -m execution.paper_readiness_scheduler
|
|
239
|
+
--poll-interval 3600` (not folded into `retraining/worker.py`'s loop —
|
|
240
|
+
different cadence). Purely additive — never touches
|
|
241
|
+
`phase_v2.paper_trading` config or order-routing behavior.
|
|
242
|
+
|
|
243
|
+
## Secret handling (`secret_scan.py`, `lean_config_render.py`)
|
|
244
|
+
|
|
245
|
+
The tracked `lean.json` ships as the stock Lean template with every
|
|
246
|
+
brokerage/API-secret field empty; these keep it that way while still
|
|
247
|
+
letting live/paper deployment use real credentials.
|
|
248
|
+
|
|
249
|
+
- `secret_scan.py` — backs `aq secrets-check` / `.githooks/pre-commit`.
|
|
250
|
+
`find_populated_secret_fields(lean_config)` flags any field whose name
|
|
251
|
+
looks like a credential (`is_secret_field()`, suffix match on
|
|
252
|
+
`-api-key`/`-password`/etc. plus IB identity fields) and is non-empty.
|
|
253
|
+
`is_tracked_env_secret(filename)` flags a `.env`-style filename that
|
|
254
|
+
isn't a committed `*.example` template. Pure — only field names are ever
|
|
255
|
+
returned, never values.
|
|
256
|
+
- `lean_config_render.py` — Lean does not expand env vars inside
|
|
257
|
+
`lean.json` (read literally), so `render_lean_config()` (pure) overlays
|
|
258
|
+
real values from `.env.live`/`AETHER_*` env vars (`SECRET_ENV_MAP`) onto
|
|
259
|
+
the empty template; `write_rendered_config()` (IO) writes a gitignored
|
|
260
|
+
`lean.live.json` that live/paper deployment points Lean at via
|
|
261
|
+
`--lean-config`. Backtests use the plain `lean.json` untouched.
|
|
262
|
+
`load_env_file()`/`parse_env_file()` handle `.env.live` parsing.
|
|
263
|
+
|
|
264
|
+
## Activating real paper-trading fills — manual step
|
|
265
|
+
|
|
266
|
+
Everything here today produces **synthetic** fills
|
|
267
|
+
(`order_gate.py::simulate_fill()`, via `simulated_portfolio.py`'s
|
|
268
|
+
`enter_long()`/`exit()`/`liquidate_all()`), never a real Lean
|
|
269
|
+
`PaperBrokerage` fill event. Switching the fill *source* to real fills is a
|
|
270
|
+
distinct, deliberately unbuilt follow-up ("Phase 7b") — the rest of the
|
|
271
|
+
pipeline (experience store, triggers, retraining, `rank_ic_monitor.py`)
|
|
272
|
+
needs no change when that happens.
|
|
273
|
+
|
|
274
|
+
The manual gate already exists as config, not code:
|
|
275
|
+
`paper_readiness.py::evaluate_paper_broker_config()` blocks activation
|
|
276
|
+
until a human sets, in `config.json`,
|
|
277
|
+
`phase_v2.paper_trading.live_data_provider_configured: true` and
|
|
278
|
+
`phase_v2.paper_trading.manual_review_confirmed: true`. Neither is touched
|
|
279
|
+
by any automated process — both stay `false` until a human flips them, and
|
|
280
|
+
`aq paper-readiness`/`PaperReadinessScheduler` keep reporting `ready: false`
|
|
281
|
+
(via `blocking_reasons`) until they do.
|