PythagorasGoal/scripts/analysis/options_chain.py

"""Loader + lookup PREZZI REALI della catena opzioni (da cerbero-bite, data/options/).

Fonte: scripts/analysis/options_fetcher.py importa lo storico per-strike reale di
cerbero-bite (bid/ask/mid/IV/greche/OI/vol, BTC+ETH, dal 2026-05-01, cadenza ~12min)
in data/options/{eth,btc}_chain.parquet.

NB granularita': cerbero-bite snapshotta una FETTA ROTANTE della catena (~1 scadenza
per volta). Quindi:
  - gli AGGREGATI (curva di skew, livelli di premio per moneyness/tenor) sono ROBUSTI
    e sono l'uso principale -> skew_curve(), premium_levels();
  - il lookup per-trade quote() e' BEST-EFFORT con una finestra di staleness
    (default 48h) e ritorna il flag staleness_h: un backtest per-trade preciso e'
    limitato dalla sparsita', usalo con cautela.

Uso:
    from scripts.analysis.options_chain import OptionChain
    oc = OptionChain("ETH")
    oc.premium_levels()                 # tabella premi reali per moneyness x tenor
    q = oc.quote(ts_ms, spot=1700, otm=0.10, opt_type="P", min_tenor_d=5, max_tenor_d=14)
    # q = dict(ask_pct, iv, atm_iv, skew, spread_pct, oi, delta, strike, tenor_d, staleness_h)
"""
from __future__ import annotations

import sys
from pathlib import Path

import numpy as np
import pandas as pd

PROJECT_ROOT = Path(__file__).resolve().parents[2]
sys.path.insert(0, str(PROJECT_ROOT))
OPT_DIR = PROJECT_ROOT / "data" / "options"

_NUM = ["strike", "bid", "ask", "mid", "iv", "delta", "gamma", "theta", "vega"]


def load_chain(asset: str) -> pd.DataFrame:
    df = pd.read_parquet(OPT_DIR / f"{asset.lower()}_chain.parquet")
    for c in _NUM:
        df[c] = pd.to_numeric(df[c], errors="coerce")
    for c in ("open_interest", "volume_24h"):
        df[c] = pd.to_numeric(df[c], errors="coerce")
    df["ts"] = pd.to_datetime(df["timestamp"], utc=True)
    df["exp"] = pd.to_datetime(df["expiry"], utc=True)
    df["ts_ms"] = (df["ts"].astype("int64") // 10**6)
    df["tenor_d"] = (df["exp"] - df["ts"]).dt.total_seconds() / 86400.0
    return df.sort_values("ts_ms").reset_index(drop=True)


_MKT_NUM = ["spot", "dvol", "realized_vol_30d", "iv_minus_rv", "funding_perp_annualized",
            "funding_cross_annualized", "dealer_net_gamma", "gamma_flip_level",
            "oi_delta_pct_4h", "macro_days_to_event"]


def load_market(asset: str | None = None) -> pd.DataFrame:
    """Pannello regime REALE pre-calcolato da cerbero-bite (market_snapshots, dal 2026-03-26,
    ~15min): spot, dvol, realized_vol_30d, iv_minus_rv (VRP), funding perp/cross,
    dealer_net_gamma (net-GEX), gamma_flip_level, oi_delta_pct_4h, liquidation_long/short_risk.
    asset=None -> tutti. Restituisce ordinato per ts con colonne ts (UTC) e ts_ms."""
    df = pd.read_parquet(OPT_DIR / "market_snapshots.parquet")
    if asset is not None:
        df = df[df["asset"] == asset].copy()
    for c in _MKT_NUM:
        if c in df.columns:
            df[c] = pd.to_numeric(df[c], errors="coerce")
    df["ts"] = pd.to_datetime(df["timestamp"], utc=True, format="ISO8601")
    df["ts_ms"] = df["ts"].astype("int64") // 10**6
    return df.sort_values("ts_ms").reset_index(drop=True)


class OptionChain:
    def __init__(self, asset: str):
        self.asset = asset
        self.df = load_chain(asset)
        self._ts = self.df["ts_ms"].values

    # ---------------- aggregati robusti ----------------
    def _spot_proxy(self) -> pd.Series:
        """spot ~ strike del put con delta piu' vicino a -0.5, per snapshot."""
        puts = self.df[self.df["option_type"] == "P"].copy()
        puts["d_atm"] = (puts["delta"] + 0.5).abs()
        atm = puts.sort_values("d_atm").groupby("timestamp").first()
        return atm["strike"]

    def skew_curve(self, opt_type: str = "P") -> pd.DataFrame:
        """IV mediana / IV-ATM per banda di moneyness (strike/spot)."""
        spot = self._spot_proxy()
        d = self.df[self.df["option_type"] == opt_type].copy()
        d["spot"] = d["timestamp"].map(spot)
        d = d.dropna(subset=["spot", "iv"])
        d["m"] = d["strike"] / d["spot"]
        atm_iv = d.assign(da=(d["delta"].abs() - 0.5).abs()).sort_values("da").groupby("timestamp")["iv"].first()
        d["atm_iv"] = d["timestamp"].map(atm_iv)
        d["skew"] = d["iv"] / d["atm_iv"]
        bins = [0.7, 0.85, 0.9, 0.95, 1.0, 1.05, 1.1, 1.15, 1.3]
        d["band"] = pd.cut(d["m"], bins)
        g = d.groupby("band", observed=True).agg(
            n=("skew", "size"), iv_med=("iv", "median"), skew_med=("skew", "median"),
            spread_med=("ask", lambda s: float("nan")))
        # spread% mediano
        d["spread_pct"] = (d["ask"] - d["bid"]) / ((d["ask"] + d["bid"]) / 2) * 100
        g["spread_med%"] = d.groupby("band", observed=True)["spread_pct"].median()
        g["oi_med"] = d.groupby("band", observed=True)["open_interest"].median()
        return g.drop(columns=["spread_med"])

    def premium_levels(self, opt_type: str = "P") -> pd.DataFrame:
        """premio reale mediano (ask, %spot) per banda moneyness x tenor."""
        spot = self._spot_proxy()
        d = self.df[self.df["option_type"] == opt_type].copy()
        d["spot"] = d["timestamp"].map(spot)
        d = d.dropna(subset=["spot", "ask"])
        d["m"] = d["strike"] / d["spot"]
        d["ask_pct"] = d["ask"] * 100.0                      # ask quotato in coin -> %spot = ask*100
        d["tenor_b"] = pd.cut(d["tenor_d"], [0, 3.5, 14, 45, 400],
                              labels=["1-3d", "4-14d", "15-45d", ">45d"])
        d["m_b"] = pd.cut(d["m"], [0.7, 0.85, 0.9, 0.95, 1.05, 1.15, 1.3],
                          labels=["<-10%", "-10%", "-7%", "ATM", "+7%", "+10%"])
        g = d.groupby(["m_b", "tenor_b"], observed=True).agg(
            n=("ask_pct", "size"), prem_pct=("ask_pct", "median"),
            iv=("iv", "median"), oi=("open_interest", "median"))
        return g

    # ---------------- lookup per-trade (best effort) ----------------
    def quote(self, ts_ms: int, spot: float, otm: float = 0.10, opt_type: str = "P",
              min_tenor_d: float = 5.0, max_tenor_d: float = 14.0,
              max_staleness_h: float = 48.0) -> dict | None:
        """Quote REALE piu' fresca <= ts_ms per la protezione a `otm` OTM e tenor nel range.
        put: strike target = spot*(1-otm); call: spot*(1+otm). None se nulla nella finestra."""
        lo = ts_ms - int(max_staleness_h * 3600 * 1000)
        i1 = np.searchsorted(self._ts, ts_ms, "right")
        i0 = np.searchsorted(self._ts, lo, "left")
        if i1 <= i0:
            return None
        w = self.df.iloc[i0:i1]
        w = w[w["option_type"] == opt_type]
        w = w[(w["tenor_d"] >= min_tenor_d) & (w["tenor_d"] <= max_tenor_d)]
        if w.empty:
            return None
        # ultima quota per strumento, poi strike piu' vicino al target
        w = w.sort_values("ts_ms").groupby("instrument_name").tail(1)
        target = spot * (1 - otm) if opt_type == "P" else spot * (1 + otm)
        row = w.iloc[(w["strike"] - target).abs().argmin()]
        atm = w.iloc[(w["delta"].abs() - 0.5).abs().argmin()]
        ask, bid = float(row["ask"]), float(row["bid"])
        return dict(
            ask_pct=ask * 100.0, iv=float(row["iv"]), atm_iv=float(atm["iv"]),
            skew=float(row["iv"]) / float(atm["iv"]) if atm["iv"] else float("nan"),
            spread_pct=(ask - bid) / ((ask + bid) / 2) * 100 if (ask + bid) > 0 else float("nan"),
            oi=int(row["open_interest"] or 0), delta=float(row["delta"]),
            strike=float(row["strike"]), tenor_d=float(row["tenor_d"]),
            staleness_h=(ts_ms - int(row["ts_ms"])) / 3600000.0,
            instrument=row["instrument_name"])


if __name__ == "__main__":
    for asset in ("ETH", "BTC"):
        oc = OptionChain(asset)
        print(f"\n===== {asset} — {len(oc.df)} righe, {oc.df['ts'].min().date()} -> {oc.df['ts'].max().date()} =====")
        print("\n--- curva di skew (put, IV mediana / IV-ATM) ---")
        print(oc.skew_curve("P").to_string())
        print("\n--- premi reali mediani (ask %spot) per moneyness x tenor ---")
        print(oc.premium_levels("P").to_string())
        # quote demo: ultimo ts disponibile, 10% OTM put settimanale
        ts = int(oc.df["ts_ms"].iloc[-1]); sp = float(oc._spot_proxy().iloc[-1])
        q = oc.quote(ts, spot=sp, otm=0.10, opt_type="P", min_tenor_d=5, max_tenor_d=14)
        print(f"\n--- quote demo: put 10%OTM settimanale ~spot {sp:.0f} ---\n  {q}")