docs(specs): IV-RV adaptive gate design
Spec del gate IV-RV adattivo (P25 rolling 60g + Vol-of-Vol guard 5pt 24h) — riprende roadmap §4-quater di 13-strategia-spiegata.md punti 1 e 2 e li promuove a design pronto per implementazione. Decisioni emerse dal brainstorming: - Hybrid (percentile rolling + VoV guard), non regime detection - Window target 60g, min 30g, sotto usa storia disponibile (warmup) - Floor assoluto via vecchio iv_minus_rv_min (backwards compat) - Inline nel validator, stateless, no DB cache - GUI Calibrazione: pannello informativo, slider esistenti invariati - Fail-open su tutti i casi di dato mancante Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
root
@@ -0,0 +1,288 @@
|
|||||||
|
# IV-RV adaptive entry gate — design
|
||||||
|
|
||||||
|
**Status**: drafted, awaiting implementation plan
|
||||||
|
**Date**: 2026-05-08
|
||||||
|
**Author**: brainstorming session (operator + Claude)
|
||||||
|
**Roadmap origin**: `docs/13-strategia-spiegata.md` §4-quater, hardening punti 1 e 2
|
||||||
|
|
||||||
|
## 1. Problema
|
||||||
|
|
||||||
|
Il gate IV-richness in `core/entry_validator.py:140-152` confronta `ctx.iv_minus_rv` con la soglia statica `entry.iv_minus_rv_min` (config). I dati raccolti in `market_snapshots` mostrano due problemi sul campione 2026-05-01 → 2026-05-08:
|
||||||
|
|
||||||
|
| metrica | ETH | BTC |
|
||||||
|
|---|---|---|
|
||||||
|
| IV-RV p25 | 1.87 | 5.48 |
|
||||||
|
| IV-RV p50 | 2.70 | 6.88 |
|
||||||
|
| IV-RV p90 | 8.52 | 8.26 |
|
||||||
|
| Pearson(\|drift%\|, IV-RV mean) | **−0.02** | **+0.54** |
|
||||||
|
| Trend giornaliero IV-RV mean | 1.64 → 8.96 (+5.4×) | 4.78 → 8.11 (+1.7×) |
|
||||||
|
|
||||||
|
ETH mostra un IV richening monotono **decoupled dal drift realised** — la soglia statica `min=3` (profilo Aggressiva) avrebbe escluso il 50%+ dei tick nei primi 4 giorni e il 0% degli ultimi 3, sopra una distribuzione che non è stazionaria. Su BTC è meno drammatico ma il problema è strutturale: il regime di IV cambia, la soglia no.
|
||||||
|
|
||||||
|
## 2. Obiettivo
|
||||||
|
|
||||||
|
Sostituire la soglia statica con un meccanismo adattivo che si auto-calibra al regime corrente, senza richiedere intervento manuale dell'operatore. Il gate deve restare semanticamente "non vendere vol senza margine misurabile sopra la RV", solo che il "margine misurabile" è ora derivato dalla distribuzione storica recente invece che hardcoded.
|
||||||
|
|
||||||
|
## 3. Approccio scelto: Hybrid (P25 rolling + Vol-of-Vol guard)
|
||||||
|
|
||||||
|
Decisione presa nel brainstorming dopo aver scartato:
|
||||||
|
- **Solo percentile rolling**: insufficiente, non protegge da regime shift bruschi (DVOL salta di 5+ pt in 24h)
|
||||||
|
- **Solo regime detection (HMM/cluster)**: troppo opaco e ad alto rischio di overfit con 8 giorni di dati
|
||||||
|
|
||||||
|
L'hybrid bilancia due controlli additivi:
|
||||||
|
1. **Soglia adattiva** = P25 di IV-RV nella finestra rolling
|
||||||
|
2. **Vol-of-Vol guard** = blocco se |ΔDVOL_24h| ≥ 5 pt (regime shift detector)
|
||||||
|
|
||||||
|
## 4. Comportamento del gate
|
||||||
|
|
||||||
|
```
|
||||||
|
def validate_iv_richness_adaptive(ctx, cfg, repo):
|
||||||
|
if not cfg.entry.iv_minus_rv_filter_enabled:
|
||||||
|
return PASS # gate off
|
||||||
|
|
||||||
|
# 1) Soglia adattiva
|
||||||
|
history = repo.iv_rv_history(asset=ctx.asset, max_days=cfg.window_target_days)
|
||||||
|
n_days = len(history) / 96 # 96 tick/giorno
|
||||||
|
|
||||||
|
if n_days < 1:
|
||||||
|
return PASS # warmup hard: <1g, no gate
|
||||||
|
|
||||||
|
if n_days >= cfg.window_target_days:
|
||||||
|
window = history[-cfg.window_target_days*96:] # ≥60g → finestra fissa 60g
|
||||||
|
elif n_days >= cfg.window_min_days:
|
||||||
|
window = history[-cfg.window_min_days*96:] # 30-60g → finestra fissa 30g
|
||||||
|
else:
|
||||||
|
window = history # 1-30g → tutta la storia disponibile
|
||||||
|
|
||||||
|
threshold = max(percentile(window, cfg.percentile),
|
||||||
|
cfg.absolute_floor)
|
||||||
|
|
||||||
|
if ctx.iv_minus_rv < threshold:
|
||||||
|
return SKIP("IV richness below P25 rolling")
|
||||||
|
|
||||||
|
# 2) Vol-of-vol guard (additivo)
|
||||||
|
if cfg.vol_of_vol_guard_enabled:
|
||||||
|
dvol_24h_ago = repo.dvol_lookback(asset=ctx.asset, hours=24)
|
||||||
|
if dvol_24h_ago is not None and \
|
||||||
|
abs(ctx.dvol - dvol_24h_ago) >= cfg.vol_of_vol_threshold:
|
||||||
|
return SKIP("DVOL shifted ≥5pt in 24h")
|
||||||
|
|
||||||
|
return PASS
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.1 Warmup behavior
|
||||||
|
|
||||||
|
| storia disponibile | finestra usata | comportamento |
|
||||||
|
|---|---|---|
|
||||||
|
| < 1 giorno (96 tick) | — | gate disabled (PASS), log `GATE_WARMUP_INSUFFICIENT` |
|
||||||
|
| 1 g ≤ storia < 30 g | tutta la storia | percentile della finestra disponibile (decisione utente) |
|
||||||
|
| 30 g ≤ storia < 60 g | ultimi 30 g | finestra fissa 30g |
|
||||||
|
| ≥ 60 g | ultimi 60 g | finestra fissa 60g (target) |
|
||||||
|
|
||||||
|
### 4.2 Soglia = `max(P25, floor)`
|
||||||
|
|
||||||
|
`floor` è il vecchio `iv_minus_rv_min` riutilizzato come *absolute floor*. Permette:
|
||||||
|
- backwards compat: se `adaptive_enabled=False`, comportamento identico ad oggi
|
||||||
|
- safety: anche se P25 storico fosse ≈0 (regime IV bassa persistente), l'operatore può tenere un floor minimo (es. 1 vol pt) per evitare di vendere vol mai
|
||||||
|
|
||||||
|
## 5. Schema config (`config/schema.py`)
|
||||||
|
|
||||||
|
Aggiunte alla classe `EntryConfig`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
class EntryConfig(BaseModel):
|
||||||
|
# campi esistenti
|
||||||
|
iv_minus_rv_filter_enabled: bool = False
|
||||||
|
iv_minus_rv_min: Decimal = Decimal("0") # ora è absolute_floor
|
||||||
|
|
||||||
|
# nuovi — gate adattivo
|
||||||
|
iv_minus_rv_adaptive_enabled: bool = False
|
||||||
|
iv_minus_rv_percentile: Decimal = Decimal("0.25")
|
||||||
|
iv_minus_rv_window_target_days: int = 60
|
||||||
|
iv_minus_rv_window_min_days: int = 30
|
||||||
|
|
||||||
|
# nuovi — vol-of-vol guard
|
||||||
|
vol_of_vol_guard_enabled: bool = False
|
||||||
|
vol_of_vol_threshold_pt: Decimal = Decimal("5")
|
||||||
|
vol_of_vol_lookback_hours: int = 24
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.1 Profili predefiniti
|
||||||
|
|
||||||
|
**Conservativa / golden** (`config/golden.yaml`):
|
||||||
|
```yaml
|
||||||
|
entry:
|
||||||
|
iv_minus_rv_filter_enabled: false
|
||||||
|
iv_minus_rv_adaptive_enabled: false
|
||||||
|
vol_of_vol_guard_enabled: false
|
||||||
|
```
|
||||||
|
Comportamento invariato rispetto a oggi.
|
||||||
|
|
||||||
|
**Aggressiva** (`config/aggressive.yaml`):
|
||||||
|
```yaml
|
||||||
|
entry:
|
||||||
|
iv_minus_rv_filter_enabled: true
|
||||||
|
iv_minus_rv_adaptive_enabled: true
|
||||||
|
iv_minus_rv_min: 0 # floor 0, lascia decidere il P25 rolling
|
||||||
|
iv_minus_rv_percentile: 0.25
|
||||||
|
iv_minus_rv_window_target_days: 60
|
||||||
|
iv_minus_rv_window_min_days: 30
|
||||||
|
vol_of_vol_guard_enabled: true
|
||||||
|
vol_of_vol_threshold_pt: 5
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 Backwards compat
|
||||||
|
|
||||||
|
Se `iv_minus_rv_adaptive_enabled=False` e `iv_minus_rv_filter_enabled=True`, il validator usa il path legacy `iv_rv < iv_minus_rv_min` esattamente come oggi. Nessuna regressione comportamentale per chi non ha attivato l'adaptive.
|
||||||
|
|
||||||
|
## 6. Architettura
|
||||||
|
|
||||||
|
### 6.1 Nuovo modulo `core/adaptive_threshold.py`
|
||||||
|
|
||||||
|
Funzione pura, testabile senza I/O:
|
||||||
|
|
||||||
|
```python
|
||||||
|
def compute_adaptive_threshold(
|
||||||
|
history: list[Decimal],
|
||||||
|
*,
|
||||||
|
percentile: Decimal,
|
||||||
|
absolute_floor: Decimal,
|
||||||
|
min_days: int,
|
||||||
|
target_days: int,
|
||||||
|
) -> Decimal | None:
|
||||||
|
"""Ritorna None se warmup hard (<96 tick), altrimenti max(P_q, floor)."""
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6.2 Repository (`state/repository.py`)
|
||||||
|
|
||||||
|
Due nuovi metodi su `MarketSnapshotRepository`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
def iv_rv_history(self, *, asset: str, max_days: int) -> list[Decimal]:
|
||||||
|
"""IV-RV ordinato ASC, finestra max_days, fetch_ok=1, NULL filtrati."""
|
||||||
|
|
||||||
|
def dvol_lookback(self, *, asset: str, hours: int) -> Decimal | None:
|
||||||
|
"""DVOL del tick più vicino a now-hours, ±15min tolerance. None se gap."""
|
||||||
|
```
|
||||||
|
|
||||||
|
Usa l'index esistente `idx_market_snapshots_asset_ts`. Nessuna nuova migration.
|
||||||
|
|
||||||
|
### 6.3 Inline nel validator
|
||||||
|
|
||||||
|
`core/entry_validator.py` chiama `compute_adaptive_threshold` con i dati dal repo. Nessun caching, stateless. La query per finestra 60g (5760 righe per asset) costa ms-level con index — non vale la pena introdurre cache da invalidare.
|
||||||
|
|
||||||
|
### 6.4 Audit / logging
|
||||||
|
|
||||||
|
Ogni entry cycle scrive in `decisions`:
|
||||||
|
- `inputs_json`: `{iv_rv_now, threshold_used, dvol_now, dvol_24h_ago, n_history, window_used_days}`
|
||||||
|
- `outputs_json`: `{gate: "iv_richness_adaptive", verdict: PASS|SKIP, reason}`
|
||||||
|
|
||||||
|
Permette ricostruzione ex-post: perché un trade è stato saltato e con quali numeri.
|
||||||
|
|
||||||
|
## 7. GUI Calibrazione (`pages/6_📐_Calibrazione.py`)
|
||||||
|
|
||||||
|
Aggiunta sezione "Gate adattivo" sopra ai percentili statici esistenti — questi ultimi NON vengono modificati (restano per analisi).
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─ 🎯 Gate IV-RV adattivo ──────────────────────────────────┐
|
||||||
|
│ Status: 🟢 Attivo (Aggressiva) | 🟡 Warmup (n=8/30g) │
|
||||||
|
│ │
|
||||||
|
│ Soglia P25 rolling (corrente) 2.74 vol pts │
|
||||||
|
│ IV-RV ultimo tick 8.96 vol pts ✅ │
|
||||||
|
│ Floor assoluto 0.00 vol pts │
|
||||||
|
│ │
|
||||||
|
│ Evoluzione 7g (sparkline) ▁▂▂▃▄▆▇ │
|
||||||
|
│ │
|
||||||
|
│ ── VoV guard ── │
|
||||||
|
│ ΔDVOL ultime 24h 0.43 pt ✅ │
|
||||||
|
│ Soglia VoV 5.00 pt │
|
||||||
|
│ │
|
||||||
|
│ Decisione hypothetical: PASS │
|
||||||
|
└──────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
La GUI usa la stessa funzione `compute_adaptive_threshold` del validator → unica fonte di verità. Refresh manuale al page load (coerente con resto GUI).
|
||||||
|
|
||||||
|
## 8. Error handling
|
||||||
|
|
||||||
|
Principio: **fail-open** in tutti i casi di dato mancante. Il gate adattivo è additivo sopra ai gate hard esistenti (delta band, credit, ecc.); il dato mancante non deve trasformare un trade non voluto in trade fatto, ma neppure deve bloccare entry valide se è il dato del gate stesso a mancare.
|
||||||
|
|
||||||
|
| Scenario | Comportamento | Loggato come |
|
||||||
|
|---|---|---|
|
||||||
|
| `iv_rv_history` ritorna 0 righe | gate = PASS | `GATE_WARMUP_NO_DATA` |
|
||||||
|
| Storia < 96 tick (1g) | gate = PASS, threshold None | `GATE_WARMUP_INSUFFICIENT` |
|
||||||
|
| `dvol_lookback` = None (gap dati 24h fa) | VoV guard = PASS | `VOV_GUARD_NO_LOOKBACK` |
|
||||||
|
| `ctx.iv_minus_rv` = None | gate bypassato (riga 146 esistente) | invariato |
|
||||||
|
| `ctx.dvol` = None | VoV guard bypassato, gate adattivo prosegue | invariato |
|
||||||
|
|
||||||
|
## 9. Testing strategy
|
||||||
|
|
||||||
|
### 9.1 Unit — `core/adaptive_threshold.py`
|
||||||
|
|
||||||
|
- Warmup: history vuota → None
|
||||||
|
- Warmup: history < 96 tick → None
|
||||||
|
- Sotto min_days: 200 tick → P25 sui 200
|
||||||
|
- Tra min e target: 4000 tick → P25 sui 4000
|
||||||
|
- Oltre target: 10000 tick → P25 sugli ultimi `target_days*96`
|
||||||
|
- Floor binding: P25=0.5, floor=3 → 3
|
||||||
|
- Floor non binding: P25=5, floor=0 → 5
|
||||||
|
- Percentile diverso: percentile=0.5 → mediana
|
||||||
|
- Boundary: esattamente min_days → window = min_days
|
||||||
|
|
||||||
|
### 9.2 Unit — `core/entry_validator.py`
|
||||||
|
|
||||||
|
Mock repo, focus sul flusso decisionale:
|
||||||
|
- Adaptive disabled, statico passa → PASS legacy
|
||||||
|
- Adaptive disabled, statico fail → SKIP legacy
|
||||||
|
- Adaptive enabled, IV-RV sopra P25 → PASS
|
||||||
|
- Adaptive enabled, IV-RV sotto P25 sopra floor → SKIP("rolling")
|
||||||
|
- VoV guard ON, ΔDVOL=6 pt → SKIP("vov")
|
||||||
|
- VoV guard ON, ΔDVOL=4 pt, gate principale pass → PASS
|
||||||
|
- VoV guard ON, dvol_lookback=None → guard bypass
|
||||||
|
- ctx.iv_minus_rv=None → bypass
|
||||||
|
- decisions log popolato con threshold, n_history, dvol_lookback
|
||||||
|
|
||||||
|
### 9.3 Integration — `tests/integration/test_entry_cycle_adaptive.py`
|
||||||
|
|
||||||
|
SQLite temp + fixture market_snapshots con 5760 tick (60g):
|
||||||
|
- Aggressiva con flag adattivo → entry passa solo nei tick sopra P25 della fixture
|
||||||
|
- Golden → invariato
|
||||||
|
- Warmup: DB con 50 tick → tutti pass, log `GATE_WARMUP_INSUFFICIENT`
|
||||||
|
- Regime shift fixture: DVOL salta da 50 a 56 in 24h → VoV guard scatta
|
||||||
|
|
||||||
|
### 9.4 Backtest sanity
|
||||||
|
|
||||||
|
Aggiunta nel report del CLI `backtest`: count distinto skip-reasons (`iv_rv_static`, `iv_rv_rolling`, `vov_guard`) per analisi ex-post.
|
||||||
|
|
||||||
|
### 9.5 GUI smoke
|
||||||
|
|
||||||
|
Manuale al deploy:
|
||||||
|
- Calibrazione carica con `enabled=False` (fallback grafico)
|
||||||
|
- Calibrazione mostra warmup status quando DB < 30g
|
||||||
|
- Refresh ricalcola coerente
|
||||||
|
|
||||||
|
### 9.6 Cosa NON testiamo
|
||||||
|
|
||||||
|
- Performance query (5760 righe con index = trascurabile)
|
||||||
|
- Concorrenza entry cycle / GUI (WAL abilitato)
|
||||||
|
- Migrazione (nessuna tabella nuova)
|
||||||
|
|
||||||
|
## 10. Out of scope
|
||||||
|
|
||||||
|
- Regime detection avanzato (HMM, cluster) — esplicitamente scartato per opacità
|
||||||
|
- Soglie per-asset diverse — il P25 si calibra naturalmente per asset (history filtrata per asset)
|
||||||
|
- Auto-attivazione adaptive su Conservativa quando warmup è completo — l'operatore decide manualmente quando passare al profilo aggressivo
|
||||||
|
- Multi-asset (ETH+BTC simultanei) — già scope §4-ter, indipendente da questo design
|
||||||
|
- Override manuale soglia da GUI — explicit no, l'obiettivo è autocalibrante
|
||||||
|
|
||||||
|
## 11. Decisioni prese durante brainstorming
|
||||||
|
|
||||||
|
| # | Domanda | Scelta |
|
||||||
|
|---|---|---|
|
||||||
|
| 1 | Approccio | Hybrid (percentile + VoV guard) |
|
||||||
|
| 2 | Warmup | Percentile della finestra disponibile (anche se <30g) |
|
||||||
|
| 3 | Percentile | P25 (allineato roadmap) |
|
||||||
|
| 4 | Window | Target 60g, attivazione a 30g, sotto usa quel che c'è |
|
||||||
|
| 5 | VoV soglia | 5 pt vol in 24h |
|
||||||
|
| 6 | Architettura | Inline nel validator, stateless, no cache DB |
|
||||||
|
| 7 | GUI | Pannello informativo aggiunto, slider esistenti invariati |
|
||||||
Reference in New Issue
Block a user