quantbt-engine 1.0.7__py3-none-any.whl

quantbt/options/conventions.py

@@ -0,0 +1,158 @@
+"""
+Versioned option venue conventions.
+
+These conventions are descriptive configuration, not a pricing engine and not a
+claim that venue portfolio margin is exactly replicated.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Tuple
+
+from .schema import ExerciseStyle, PremiumConvention, SettlementStyle
+
+
+@dataclass(frozen=True)
+class OptionVenueConvention:
+    venue: str
+    convention_id: str
+    premium_convention: PremiumConvention
+    exercise_style: ExerciseStyle
+    settlement_style: SettlementStyle
+    premium_currency: str
+    settlement_currency: str
+    quote_currency: str
+    supported_underlyings: Tuple[str, ...] = ()
+    fee_schedule_id: str = ""
+    margin_schedule_id: str = ""
+    exact_venue_margin: bool = False
+    notes: str = ""
+    metadata: Dict = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "venue", str(self.venue).lower().strip())
+        object.__setattr__(self, "premium_convention", _coerce(PremiumConvention, self.premium_convention, "premium_convention"))
+        object.__setattr__(self, "exercise_style", _coerce(ExerciseStyle, self.exercise_style, "exercise_style"))
+        object.__setattr__(self, "settlement_style", _coerce(SettlementStyle, self.settlement_style, "settlement_style"))
+        if not self.venue or not self.convention_id:
+            raise ValueError("venue and convention_id are required")
+        for field_name in ("premium_currency", "settlement_currency", "quote_currency"):
+            value = getattr(self, field_name)
+            if not value:
+                raise ValueError(f"{field_name} is required")
+            object.__setattr__(self, field_name, str(value).upper())
+        object.__setattr__(self, "supported_underlyings", tuple(str(value).upper() for value in self.supported_underlyings))
+        _validate_convention(self)
+
+    @property
+    def signature(self) -> Tuple:
+        return (
+            self.venue,
+            self.convention_id,
+            self.premium_convention.value,
+            self.exercise_style.value,
+            self.settlement_style.value,
+            self.premium_currency,
+            self.settlement_currency,
+            self.quote_currency,
+            self.supported_underlyings,
+            self.fee_schedule_id,
+            self.margin_schedule_id,
+            bool(self.exact_venue_margin),
+        )
+
+
+def deribit_inverse_option_convention(
+    *,
+    underlying: str = "BTC",
+    version: str = "deribit_inverse_v1",
+) -> OptionVenueConvention:
+    base = str(underlying).upper()
+    if base not in {"BTC", "ETH"}:
+        raise ValueError("Deribit inverse convention currently supports BTC or ETH")
+    return OptionVenueConvention(
+        venue="deribit",
+        convention_id=version,
+        premium_convention=PremiumConvention.INVERSE_BASE,
+        exercise_style=ExerciseStyle.EUROPEAN,
+        settlement_style=SettlementStyle.CASH,
+        premium_currency=base,
+        settlement_currency=base,
+        quote_currency="USD",
+        supported_underlyings=(base,),
+        fee_schedule_id=f"deribit_{base.lower()}_inverse_options",
+        margin_schedule_id="deribit_pm_external_or_scenario_approximation",
+        exact_venue_margin=False,
+        notes="Inverse premium and settlement are in base currency; native margin is approximation unless validated externally.",
+    )
+
+
+def deribit_linear_usdc_option_convention(
+    *,
+    underlying: str = "BTC",
+    version: str = "deribit_linear_usdc_v1",
+    settlement_style: SettlementStyle = SettlementStyle.FUTURE_THEN_CASH,
+) -> OptionVenueConvention:
+    base = str(underlying).upper()
+    return OptionVenueConvention(
+        venue="deribit",
+        convention_id=version,
+        premium_convention=PremiumConvention.LINEAR_QUOTE,
+        exercise_style=ExerciseStyle.EUROPEAN,
+        settlement_style=settlement_style,
+        premium_currency="USDC",
+        settlement_currency="USDC",
+        quote_currency="USDC",
+        supported_underlyings=(base,),
+        fee_schedule_id="deribit_linear_usdc_options",
+        margin_schedule_id="deribit_pm_external_or_scenario_approximation",
+        exact_venue_margin=False,
+        notes="Linear USDC option convention supports economic cash or future-then-cash settlement representation.",
+    )
+
+
+def binance_european_options_convention(
+    *,
+    underlying: str = "BTC",
+    version: str = "binance_european_options_v1",
+) -> OptionVenueConvention:
+    base = str(underlying).upper()
+    return OptionVenueConvention(
+        venue="binance",
+        convention_id=version,
+        premium_convention=PremiumConvention.LINEAR_QUOTE,
+        exercise_style=ExerciseStyle.EUROPEAN,
+        settlement_style=SettlementStyle.CASH,
+        premium_currency="USDT",
+        settlement_currency="USDT",
+        quote_currency="USDT",
+        supported_underlyings=(base,),
+        fee_schedule_id="binance_options_versioned_external",
+        margin_schedule_id="binance_options_external_or_scenario_approximation",
+        exact_venue_margin=False,
+        notes="Binance config is schema/convention metadata only until official fee/margin parity tests are added.",
+    )
+
+
+def _coerce(enum_cls, value, field_name: str):
+    if isinstance(value, enum_cls):
+        return value
+    try:
+        return enum_cls(str(value))
+    except ValueError as exc:
+        raise ValueError(f"{field_name} must be one of {[item.value for item in enum_cls]}") from exc
+
+
+def _validate_convention(convention: OptionVenueConvention) -> None:
+    if convention.premium_convention is PremiumConvention.INVERSE_BASE:
+        if convention.premium_currency != convention.settlement_currency:
+            raise ValueError("inverse convention requires premium_currency == settlement_currency")
+        if convention.quote_currency == convention.premium_currency:
+            raise ValueError("inverse convention requires quote_currency distinct from base premium currency")
+    elif convention.premium_convention is PremiumConvention.LINEAR_QUOTE:
+        if convention.premium_currency != convention.quote_currency:
+            raise ValueError("linear convention requires premium_currency == quote_currency")
+    elif convention.premium_convention is PremiumConvention.QUANTO:
+        if convention.premium_currency == convention.settlement_currency == convention.quote_currency:
+            raise ValueError("quanto convention requires at least one distinct currency")

quantbt/options/data.py

@@ -0,0 +1,177 @@
+"""
+Canonical option chain data validation.
+
+The canonical chain is long-form. Phase 1 validates structure only; Phase 3
+will compile this data into a ragged/CSR option tape.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Optional, Sequence
+
+import numpy as np
+import pandas as pd
+
+
+CANONICAL_OPTION_CHAIN_COLUMNS = (
+    "timestamp_ns",
+    "instrument_id",
+    "venue",
+    "underlying_id",
+    "expiry_ns",
+    "strike",
+    "option_kind",
+    "bid_price",
+    "bid_size",
+    "ask_price",
+    "ask_size",
+    "mark_price",
+    "last_price",
+    "index_price",
+    "forward_price",
+    "mark_iv",
+    "bid_iv",
+    "ask_iv",
+    "delta",
+    "gamma",
+    "vega",
+    "theta",
+    "open_interest",
+    "volume",
+    "quote_currency",
+    "settlement_currency",
+    "sequence_id",
+    "source_latency_ns",
+)
+
+REQUIRED_OPTION_CHAIN_COLUMNS = (
+    "timestamp_ns",
+    "instrument_id",
+    "venue",
+    "underlying_id",
+    "expiry_ns",
+    "strike",
+    "option_kind",
+    "bid_price",
+    "bid_size",
+    "ask_price",
+    "ask_size",
+    "mark_price",
+    "index_price",
+    "forward_price",
+    "quote_currency",
+    "settlement_currency",
+)
+
+
+def validate_option_chain_frame(
+    frame: pd.DataFrame,
+    *,
+    required_columns: Sequence[str] = REQUIRED_OPTION_CHAIN_COLUMNS,
+    max_spread_bps: Optional[float] = None,
+    reject_crossed: bool = True,
+) -> pd.DataFrame:
+    """
+    Validate and return a sorted canonical long-form option chain copy.
+
+    This function intentionally avoids filling missing market values. Missing
+    fields must remain visible to later tape compilation and no-lookahead tests.
+    """
+    if not isinstance(frame, pd.DataFrame):
+        raise TypeError("option chain must be a pandas DataFrame")
+    missing = [column for column in required_columns if column not in frame.columns]
+    if missing:
+        raise ValueError(f"option chain missing required columns: {missing}")
+    out = frame.copy()
+    _coerce_int64(out, ("timestamp_ns", "expiry_ns", "sequence_id", "source_latency_ns"), required=set(required_columns))
+    _coerce_float(
+        out,
+        (
+            "strike",
+            "bid_price",
+            "bid_size",
+            "ask_price",
+            "ask_size",
+            "mark_price",
+            "last_price",
+            "index_price",
+            "forward_price",
+            "mark_iv",
+            "bid_iv",
+            "ask_iv",
+            "delta",
+            "gamma",
+            "vega",
+            "theta",
+            "open_interest",
+            "volume",
+        ),
+    )
+    _normalize_strings(out, ("instrument_id", "underlying_id", "quote_currency", "settlement_currency"))
+    out["venue"] = out["venue"].astype(str).str.strip().str.lower()
+    out["option_kind"] = out["option_kind"].astype(str).str.strip().str.lower()
+    _validate_positive(out, ("timestamp_ns", "expiry_ns", "strike", "index_price", "forward_price"))
+    _validate_non_negative(out, ("bid_price", "bid_size", "ask_price", "ask_size", "mark_price"))
+    if reject_crossed and bool((out["bid_price"] > out["ask_price"]).any()):
+        raise ValueError("option chain contains crossed quotes: bid_price > ask_price")
+    if bool((out["bid_price"] <= 0.0).any()):
+        raise ValueError("option chain requires bid_price > 0 in Phase 1 canonical validation")
+    if bool((out["ask_price"] <= 0.0).any()):
+        raise ValueError("option chain requires ask_price > 0 in Phase 1 canonical validation")
+    if max_spread_bps is not None:
+        if max_spread_bps < 0.0:
+            raise ValueError("max_spread_bps must be >= 0")
+        mid = 0.5 * (out["bid_price"].to_numpy() + out["ask_price"].to_numpy())
+        spread_bps = np.divide(
+            out["ask_price"].to_numpy() - out["bid_price"].to_numpy(),
+            mid,
+            out=np.full(len(out), np.inf, dtype=np.float64),
+            where=mid > 0.0,
+        ) * 10_000.0
+        if bool((spread_bps > float(max_spread_bps)).any()):
+            raise ValueError("option chain contains quotes wider than max_spread_bps")
+    if bool((out["expiry_ns"] <= out["timestamp_ns"]).any()):
+        raise ValueError("option chain contains expired quotes")
+    if not set(out["option_kind"].unique()).issubset({"call", "put"}):
+        raise ValueError("option_kind must be call or put")
+    out = out.sort_values(["timestamp_ns", "sequence_id", "instrument_id"] if "sequence_id" in out else ["timestamp_ns", "instrument_id"])
+    out = out.reset_index(drop=True)
+    if bool(out.duplicated(subset=[column for column in ("timestamp_ns", "instrument_id", "sequence_id") if column in out]).any()):
+        raise ValueError("option chain contains duplicate timestamp/instrument/sequence rows")
+    return out
+
+
+def _coerce_int64(frame: pd.DataFrame, columns: Iterable[str], *, required: set[str]) -> None:
+    for column in columns:
+        if column not in frame:
+            if column in required:
+                raise ValueError(f"missing required integer column {column!r}")
+            continue
+        frame[column] = pd.to_numeric(frame[column], errors="raise").astype("int64")
+
+
+def _coerce_float(frame: pd.DataFrame, columns: Iterable[str]) -> None:
+    for column in columns:
+        if column in frame:
+            frame[column] = pd.to_numeric(frame[column], errors="raise").astype("float64")
+
+
+def _normalize_strings(frame: pd.DataFrame, columns: Iterable[str]) -> None:
+    for column in columns:
+        if column in frame:
+            frame[column] = frame[column].astype(str).str.strip()
+    for column in ("quote_currency", "settlement_currency"):
+        if column in frame:
+            frame[column] = frame[column].str.upper()
+
+
+def _validate_positive(frame: pd.DataFrame, columns: Iterable[str]) -> None:
+    for column in columns:
+        if column in frame and bool((frame[column] <= 0).any()):
+            raise ValueError(f"{column} must be > 0")
+
+
+def _validate_non_negative(frame: pd.DataFrame, columns: Iterable[str]) -> None:
+    for column in columns:
+        if column in frame and bool((frame[column] < 0).any()):
+            raise ValueError(f"{column} must be >= 0")