feat(entry): IV richness gate (§2.9) + golden config bump 1.0.0 → 1.1.0
Aggiunge il filtro a maggior impatto sul win-rate atteso: l'entry
salta se la IV implicita non sta pagando un margine misurabile sopra
la realized vol. La letteratura short-vol systematic indica che
l'edge sostenibile della strategia esiste solo quando IV30g − RV30g
supera una soglia di alcuni punti vol; senza questo gate il selling
vol nudo è strutturalmente neutro a win-rate 70-72%.
Implementazione end-to-end:
- `EntryConfig`: due nuovi campi `iv_minus_rv_min` e
`iv_minus_rv_filter_enabled`, con default `0` / `false` per non
rompere setup pre-calibrazione.
- `validate_entry`: §2.9 hard gate che blocca l'entry se
`iv_minus_rv < iv_minus_rv_min` (skip silenzioso quando il dato è
`None`, coerente con il pattern §2.8 dei filtri quant).
- `entry_cycle._gather_snapshot`: nuovo `_safe_iv_minus_rv` che
legge `deribit.realized_vol("ETH")["iv_minus_rv_30d"]` in
best-effort e lo propaga via `_MarketSnapshot.iv_minus_rv` →
`EntryContext.iv_minus_rv` → audit `inputs.snapshot.iv_minus_rv`.
- `tests/unit/test_entry_validator.py`: 5 nuovi casi (default
permissivo, gate sotto/sopra/uguale soglia, dato mancante).
- `tests/integration/test_entry_cycle.py`: stub `get_realized_vol`
nel mock helper così tutti gli scenari di happy/edge path
continuano a passare.
Configurazione di profili coerente con la disciplina:
- `strategy.yaml` (golden 1.1.0) e `strategy.conservativa.yaml`:
gate `enabled=false, min=0`. Manteniamo i lunedì pre-calibrazione
per accumulare dati sulla distribuzione di `iv_minus_rv`.
- `strategy.aggressiva.yaml` (1.1.0-aggressiva): gate
`enabled=true, min=3`. Coerente con la filosofia del profilo —
size più grande pretende win-rate più alto. La soglia 3 è
conservativa; la documentazione raccomanda 5 dopo 4-8 settimane di
calibrazione.
Doc + GUI:
- `docs/13-strategia-spiegata.md` §4-quater: spiega gate, parametri,
default per profilo, effetto atteso sul P/L (trade/anno scendono
ma E[trade] sale → APR cresce comunque), roadmap di hardening
(soglia adattiva, vol-of-vol guard, multi-asset).
- pagina `📚 Strategia`: la riga "IV − RV" passa da informativa a
pass/fail reale; mostra "filtro DISABILITATO (info-only)" quando
spento, ✅/❌ contro la soglia di config quando acceso.
Bump versioni e hash di tutti e tre i file YAML
(`config_version: 1.1.0`, hash ricalcolato). Test pinning aggiornato
(`test_load_repo_strategy_yaml`).
Suite: 410 passed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
root
@@ -75,6 +75,15 @@ class EntryConfig(BaseModel):
|
||||
dealer_gamma_filter_enabled: bool = True
|
||||
liquidation_filter_enabled: bool = True
|
||||
|
||||
# IV richness filter (§2.9). `iv_minus_rv_min` è la soglia in
|
||||
# punti vol che la IV implicita 30g deve eccedere la RV30g per
|
||||
# ammettere l'entry. Letteratura short-vol systematic: l'edge
|
||||
# sostenibile esiste solo con un margine misurabile fra IV e RV.
|
||||
# Default disabilitato + soglia 0 per non bloccare l'avvio finché
|
||||
# non si è calibrato sui dati raccolti (vedi `📐 Calibrazione`).
|
||||
iv_minus_rv_min: Decimal = Field(default=Decimal("0"))
|
||||
iv_minus_rv_filter_enabled: bool = False
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Structure
|
||||
|
||||
@@ -44,6 +44,12 @@ class EntryContext(BaseModel):
|
||||
dealer_net_gamma: Decimal | None = None
|
||||
liquidation_squeeze_risk_high: bool | None = None
|
||||
|
||||
# IV richness gate (§2.9). Differenza IV30g − RV30g in punti vol.
|
||||
# Optional, stessa logica best-effort dei filtri quant: ``None``
|
||||
# significa "dato non disponibile" e fa saltare il gate (non
|
||||
# invalida l'entry).
|
||||
iv_minus_rv: Decimal | None = None
|
||||
|
||||
|
||||
class EntryDecision(BaseModel):
|
||||
"""Result of :func:`validate_entry`. ``reasons`` holds *all* blocking reasons."""
|
||||
@@ -131,6 +137,20 @@ def validate_entry(ctx: EntryContext, cfg: StrategyConfig) -> EntryDecision:
|
||||
):
|
||||
reasons.append("imminent liquidation squeeze risk")
|
||||
|
||||
# §2.9: IV richness gate. Vendere vol senza un margine misurabile
|
||||
# fra IV e RV è statisticamente neutro: l'edge della strategia
|
||||
# esiste solo quando il premio è "ricco" rispetto a quanto il
|
||||
# mercato si è effettivamente mosso.
|
||||
if (
|
||||
entry_cfg.iv_minus_rv_filter_enabled
|
||||
and ctx.iv_minus_rv is not None
|
||||
and ctx.iv_minus_rv < entry_cfg.iv_minus_rv_min
|
||||
):
|
||||
reasons.append(
|
||||
f"IV richness below floor "
|
||||
f"(IV-RV={ctx.iv_minus_rv} < {entry_cfg.iv_minus_rv_min} vol pts)"
|
||||
)
|
||||
|
||||
return EntryDecision(accepted=not reasons, reasons=reasons)
|
||||
|
||||
|
||||
|
||||
@@ -280,26 +280,56 @@ def _build_gates(
|
||||
)
|
||||
)
|
||||
|
||||
# --- IV − RV (richness) — solo informativo --------------------
|
||||
# --- IV − RV (richness) — gate §2.9 ---------------------------
|
||||
rv = (
|
||||
float(snap.realized_vol_30d) if snap.realized_vol_30d is not None else None
|
||||
)
|
||||
iv_minus_rv = (
|
||||
float(snap.iv_minus_rv) if snap.iv_minus_rv is not None else None
|
||||
)
|
||||
rows.append(
|
||||
_GateRow(
|
||||
"IV − RV (richness)",
|
||||
(
|
||||
f"{iv_minus_rv:+.2f} pt vol"
|
||||
if iv_minus_rv is not None
|
||||
else "—"
|
||||
),
|
||||
"info, > 0 = premio ricco",
|
||||
"pass" if (iv_minus_rv is not None and iv_minus_rv > 0) else "n/a",
|
||||
f"RV30={rv:.2f}" if rv is not None else "",
|
||||
)
|
||||
iv_min = float(getattr(entry, "iv_minus_rv_min", 0.0)) if entry else 0.0
|
||||
iv_enabled = (
|
||||
bool(getattr(entry, "iv_minus_rv_filter_enabled", False)) if entry else False
|
||||
)
|
||||
if not iv_enabled:
|
||||
rows.append(
|
||||
_GateRow(
|
||||
"IV − RV (richness)",
|
||||
(
|
||||
f"{iv_minus_rv:+.2f} pt vol"
|
||||
if iv_minus_rv is not None
|
||||
else "—"
|
||||
),
|
||||
"filtro DISABILITATO (info-only)",
|
||||
"n/a",
|
||||
f"RV30={rv:.2f} · attiva con `iv_minus_rv_filter_enabled: true`"
|
||||
if rv is not None
|
||||
else "Attiva con `iv_minus_rv_filter_enabled: true`",
|
||||
)
|
||||
)
|
||||
elif iv_minus_rv is None:
|
||||
rows.append(
|
||||
_GateRow(
|
||||
"IV − RV ≥ soglia",
|
||||
"—",
|
||||
f"≥ {iv_min:.1f} pt vol",
|
||||
"n/a",
|
||||
"Dato non disponibile in questo tick (best-effort skip).",
|
||||
)
|
||||
)
|
||||
else:
|
||||
ok = iv_minus_rv >= iv_min
|
||||
rows.append(
|
||||
_GateRow(
|
||||
"IV − RV ≥ soglia",
|
||||
f"{iv_minus_rv:+.2f} pt vol",
|
||||
f"≥ {iv_min:.1f} pt vol",
|
||||
"pass" if ok else "fail",
|
||||
"Premio ricco rispetto a quanto il mercato si è davvero "
|
||||
"mosso → edge sostenibile per il venditore di vol."
|
||||
+ (f" RV30={rv:.2f}" if rv is not None else ""),
|
||||
)
|
||||
)
|
||||
|
||||
return rows
|
||||
|
||||
|
||||
@@ -94,6 +94,7 @@ class _MarketSnapshot:
|
||||
portfolio_eur: Decimal
|
||||
dealer_net_gamma: Decimal | None
|
||||
liquidation_squeeze_risk_high: bool | None
|
||||
iv_minus_rv: Decimal | None
|
||||
|
||||
|
||||
async def _gather_snapshot(
|
||||
@@ -159,6 +160,9 @@ async def _gather_snapshot(
|
||||
liquidation_t: asyncio.Task[bool | None] = asyncio.create_task(
|
||||
_safe_liquidation_squeeze(sentiment)
|
||||
)
|
||||
iv_rv_t: asyncio.Task[Decimal | None] = asyncio.create_task(
|
||||
_safe_iv_minus_rv(deribit)
|
||||
)
|
||||
|
||||
await asyncio.gather(
|
||||
spot_t,
|
||||
@@ -172,6 +176,7 @@ async def _gather_snapshot(
|
||||
portfolio_t,
|
||||
dealer_t,
|
||||
liquidation_t,
|
||||
iv_rv_t,
|
||||
)
|
||||
return _MarketSnapshot(
|
||||
spot_eth_usd=spot_t.result(),
|
||||
@@ -185,6 +190,7 @@ async def _gather_snapshot(
|
||||
portfolio_eur=portfolio_t.result(),
|
||||
dealer_net_gamma=dealer_t.result(),
|
||||
liquidation_squeeze_risk_high=liquidation_t.result(),
|
||||
iv_minus_rv=iv_rv_t.result(),
|
||||
)
|
||||
|
||||
|
||||
@@ -196,6 +202,20 @@ async def _safe_dealer_gamma(deribit: DeribitClient) -> Decimal | None:
|
||||
return snap.total_net_dealer_gamma
|
||||
|
||||
|
||||
async def _safe_iv_minus_rv(deribit: DeribitClient) -> Decimal | None:
|
||||
"""Best-effort fetch of the IV30g − RV30g spread (vol points)."""
|
||||
try:
|
||||
rv = await deribit.realized_vol("ETH")
|
||||
except Exception:
|
||||
return None
|
||||
if not isinstance(rv, dict):
|
||||
return None
|
||||
value = rv.get("iv_minus_rv_30d")
|
||||
if value is None:
|
||||
return None
|
||||
return value if isinstance(value, Decimal) else Decimal(str(value))
|
||||
|
||||
|
||||
async def _safe_liquidation_squeeze(sentiment: SentimentClient) -> bool | None:
|
||||
try:
|
||||
heatmap = await sentiment.liquidation_heatmap("ETH")
|
||||
@@ -353,6 +373,7 @@ async def run_entry_cycle(
|
||||
next_macro_event_in_days=snap.macro_days_to_event,
|
||||
has_open_position=False,
|
||||
dealer_net_gamma=snap.dealer_net_gamma,
|
||||
iv_minus_rv=snap.iv_minus_rv,
|
||||
liquidation_squeeze_risk_high=snap.liquidation_squeeze_risk_high,
|
||||
)
|
||||
decision = validate_entry(entry_ctx, cfg)
|
||||
@@ -370,6 +391,9 @@ async def run_entry_cycle(
|
||||
"eth_holdings_pct": str(snap.eth_holdings_pct),
|
||||
"portfolio_eur": str(snap.portfolio_eur),
|
||||
"capital_usd": str(capital_usd),
|
||||
"iv_minus_rv": (
|
||||
str(snap.iv_minus_rv) if snap.iv_minus_rv is not None else None
|
||||
),
|
||||
}
|
||||
}
|
||||
if not decision.accepted:
|
||||
|
||||
Reference in New Issue
Block a user