quantbt-engine 1.0.7__py3-none-any.whl

quantbt/options/strategy.py

@@ -0,0 +1,249 @@
+"""Option strategy adapters.
+
+Adapters live above the option execution engine. They convert observable
+option-chain snapshots into package intents and audit tables. They do not own
+fills, premium accounting, margin, settlement, or PnL.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Optional, Sequence
+
+import numpy as np
+import pandas as pd
+
+from ..core.schema import OrderSide
+from .hedging import OptionHedgeConfig
+from .packages import OptionPackageIntent, OptionPackageLeg
+from .schema import OptionInstrumentRegistry
+
+
+@dataclass(frozen=True)
+class OptionStrategyRun:
+    """Package-level strategy output consumed by `QuantBTEndpoint.options`."""
+
+    packages: tuple[OptionPackageIntent, ...]
+    hedge_policy: Optional[OptionHedgeConfig] = None
+    selected_contracts: pd.DataFrame = field(default_factory=pd.DataFrame)
+    metadata: Dict = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class GammaScalpingConfig:
+    """Configuration for a simple ATM straddle gamma-scalping adapter."""
+
+    side: str = "long"
+    quantity: float = 1.0
+    min_dte_days: float = 2.0
+    max_dte_days: float = 45.0
+    roll_dte_days: float = 2.0
+    max_spread_bps: Optional[float] = None
+    min_bid_size: float = 0.0
+    min_ask_size: float = 0.0
+    min_volume: float = 0.0
+    min_open_interest: float = 0.0
+    hedge_policy: Optional[OptionHedgeConfig] = None
+    metadata: Dict = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        side = str(self.side).lower().strip()
+        if side not in {"long", "short"}:
+            raise ValueError("GammaScalpingConfig.side must be long or short")
+        object.__setattr__(self, "side", side)
+        if self.quantity <= 0.0:
+            raise ValueError("GammaScalpingConfig.quantity must be > 0")
+        if self.min_dte_days < 0.0 or self.max_dte_days <= 0.0:
+            raise ValueError("DTE bounds must be non-negative and max_dte_days > 0")
+        if self.min_dte_days > self.max_dte_days:
+            raise ValueError("min_dte_days must be <= max_dte_days")
+        if self.roll_dte_days < 0.0:
+            raise ValueError("roll_dte_days must be >= 0")
+        for name in ("min_bid_size", "min_ask_size", "min_volume", "min_open_interest"):
+            if getattr(self, name) < 0.0:
+                raise ValueError(f"{name} must be >= 0")
+        if self.max_spread_bps is not None and self.max_spread_bps < 0.0:
+            raise ValueError("max_spread_bps must be >= 0")
+
+
+def build_gamma_scalping_strategy_run(
+    chain: pd.DataFrame,
+    instruments: OptionInstrumentRegistry,
+    config: Optional[GammaScalpingConfig] = None,
+) -> OptionStrategyRun:
+    """
+    Build open/roll/close straddle packages from observable chain snapshots.
+
+    Selection is snapshot-local: at each decision timestamp, the adapter only
+    inspects rows with that exact `timestamp_ns`. The selected pair is the
+    valid same-expiry same-strike call/put closest to the observed index price.
+    """
+    cfg = config or GammaScalpingConfig()
+    frame = _canonical_strategy_frame(chain)
+    valid_symbols = set(instruments.symbols)
+    frame = frame[frame["instrument_id"].isin(valid_symbols)].copy()
+    if frame.empty:
+        raise ValueError("gamma scalping adapter found no chain rows matching instrument registry")
+
+    timestamps = [int(ts) for ts in sorted(frame["timestamp_ns"].unique())]
+    packages: list[OptionPackageIntent] = []
+    selected_rows: list[dict] = []
+    active: Optional[dict] = None
+
+    for ts in timestamps:
+        is_last = ts == timestamps[-1]
+        if active is not None:
+            dte = (int(active["expiry_ns"]) - ts) / _DAY_NS
+            if dte <= cfg.roll_dte_days or is_last:
+                if _has_quotes(frame, ts, (active["call_id"], active["put_id"])):
+                    packages.append(_straddle_package(ts, active, cfg, action="close"))
+                    selected_rows.append({**active, "timestamp_ns": ts, "action": "close", "dte_days": float(dte)})
+                active = None
+                if is_last:
+                    break
+
+        if active is None and not is_last:
+            selection = _select_atm_pair(frame, ts, cfg)
+            if selection is None:
+                continue
+            packages.append(_straddle_package(ts, selection, cfg, action="open"))
+            dte = (int(selection["expiry_ns"]) - ts) / _DAY_NS
+            selected_rows.append({**selection, "timestamp_ns": ts, "action": "open", "dte_days": float(dte)})
+            active = selection
+
+    if active is not None:
+        ts = timestamps[-1]
+        if _has_quotes(frame, ts, (active["call_id"], active["put_id"])):
+            packages.append(_straddle_package(ts, active, cfg, action="close"))
+            selected_rows.append(
+                {
+                    **active,
+                    "timestamp_ns": ts,
+                    "action": "close",
+                    "dte_days": float((int(active["expiry_ns"]) - ts) / _DAY_NS),
+                }
+            )
+
+    selected = pd.DataFrame(selected_rows)
+    return OptionStrategyRun(
+        packages=tuple(packages),
+        hedge_policy=cfg.hedge_policy,
+        selected_contracts=selected,
+        metadata={
+            "strategy": "gamma_scalping",
+            "side": cfg.side,
+            "quantity": float(cfg.quantity),
+            "package_count": len(packages),
+            "selection_count": len(selected),
+            **cfg.metadata,
+        },
+    )
+
+
+def _canonical_strategy_frame(chain: pd.DataFrame) -> pd.DataFrame:
+    required = {
+        "timestamp_ns",
+        "instrument_id",
+        "expiry_ns",
+        "strike",
+        "option_kind",
+        "bid_price",
+        "ask_price",
+        "bid_size",
+        "ask_size",
+        "index_price",
+    }
+    missing = sorted(required.difference(chain.columns))
+    if missing:
+        raise ValueError(f"gamma scalping chain missing columns: {missing}")
+    frame = chain.copy()
+    for column in ("timestamp_ns", "expiry_ns"):
+        frame[column] = pd.to_numeric(frame[column], errors="raise").astype("int64")
+    for column in ("strike", "bid_price", "ask_price", "bid_size", "ask_size", "index_price"):
+        frame[column] = pd.to_numeric(frame[column], errors="raise").astype("float64")
+    if "volume" not in frame:
+        frame["volume"] = 0.0
+    if "open_interest" not in frame:
+        frame["open_interest"] = 0.0
+    frame["volume"] = pd.to_numeric(frame["volume"], errors="coerce").fillna(0.0).astype("float64")
+    frame["open_interest"] = pd.to_numeric(frame["open_interest"], errors="coerce").fillna(0.0).astype("float64")
+    frame["option_kind"] = frame["option_kind"].astype(str).str.lower().str.strip()
+    return frame.sort_values(["timestamp_ns", "expiry_ns", "strike", "option_kind", "instrument_id"]).reset_index(drop=True)
+
+
+def _select_atm_pair(frame: pd.DataFrame, timestamp_ns: int, cfg: GammaScalpingConfig) -> Optional[dict]:
+    snap = frame[frame["timestamp_ns"] == int(timestamp_ns)].copy()
+    if snap.empty:
+        return None
+    snap = snap[(snap["bid_price"] > 0.0) & (snap["ask_price"] > 0.0) & (snap["ask_price"] >= snap["bid_price"])]
+    snap = snap[(snap["bid_size"] >= cfg.min_bid_size) & (snap["ask_size"] >= cfg.min_ask_size)]
+    snap = snap[(snap["volume"] >= cfg.min_volume) & (snap["open_interest"] >= cfg.min_open_interest)]
+    dte = (snap["expiry_ns"] - int(timestamp_ns)) / _DAY_NS
+    snap = snap[(dte >= cfg.min_dte_days) & (dte <= cfg.max_dte_days)]
+    if cfg.max_spread_bps is not None:
+        mid = 0.5 * (snap["bid_price"] + snap["ask_price"])
+        spread_bps = np.where(mid > 0.0, (snap["ask_price"] - snap["bid_price"]) / mid * 10_000.0, np.inf)
+        snap = snap[spread_bps <= float(cfg.max_spread_bps)]
+    if snap.empty:
+        return None
+
+    spot = float(snap["index_price"].median())
+    pair_groups = snap.groupby(["expiry_ns", "strike"])
+    candidates = []
+    for (expiry_ns, strike), group in pair_groups:
+        kinds = set(group["option_kind"])
+        if kinds != {"call", "put"}:
+            continue
+        call = group[group["option_kind"] == "call"].iloc[0]
+        put = group[group["option_kind"] == "put"].iloc[0]
+        candidates.append(
+            {
+                "expiry_ns": int(expiry_ns),
+                "strike": float(strike),
+                "spot": spot,
+                "call_id": str(call["instrument_id"]),
+                "put_id": str(put["instrument_id"]),
+                "call_delta": float(call.get("delta", np.nan)),
+                "put_delta": float(put.get("delta", np.nan)),
+                "distance": abs(float(strike) - spot),
+                "dte_days": float((int(expiry_ns) - int(timestamp_ns)) / _DAY_NS),
+            }
+        )
+    if not candidates:
+        return None
+    return min(candidates, key=lambda row: (row["distance"], row["dte_days"]))
+
+
+def _straddle_package(timestamp_ns: int, selection: dict, cfg: GammaScalpingConfig, *, action: str) -> OptionPackageIntent:
+    if action == "open":
+        side = OrderSide.BUY if cfg.side == "long" else OrderSide.SELL
+    elif action == "close":
+        side = OrderSide.SELL if cfg.side == "long" else OrderSide.BUY
+    else:
+        raise ValueError("action must be open or close")
+    return OptionPackageIntent(
+        timestamp_ns=int(timestamp_ns),
+        package_id=f"gamma-{action}:{selection['call_id']}:{selection['put_id']}:{timestamp_ns}",
+        legs=(
+            OptionPackageLeg(selection["call_id"], side, 1.0, role=f"{action}_call"),
+            OptionPackageLeg(selection["put_id"], side, 1.0, role=f"{action}_put"),
+        ),
+        quantity=float(cfg.quantity),
+        tag=f"gamma_scalping_{action}",
+        metadata={
+            "strategy": "gamma_scalping",
+            "action": action,
+            "side": cfg.side,
+            "strike": float(selection["strike"]),
+            "expiry_ns": int(selection["expiry_ns"]),
+            "spot": float(selection["spot"]),
+        },
+    )
+
+
+def _has_quotes(frame: pd.DataFrame, timestamp_ns: int, symbols: Sequence[str]) -> bool:
+    snap_symbols = set(frame.loc[frame["timestamp_ns"] == int(timestamp_ns), "instrument_id"])
+    return all(symbol in snap_symbols for symbol in symbols)
+
+
+_DAY_NS = 24 * 60 * 60 * 1_000_000_000

quantbt/options/surface.py

@@ -0,0 +1,142 @@
+"""
+Minimal option surface diagnostics.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Iterable, Tuple
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class SurfaceDiagnostics:
+    positive_total_variance: bool
+    no_future_timestamps: bool
+    expiries_after_snapshot: bool
+    calendar_total_variance_non_decreasing: bool
+    butterfly_convexity_checked: bool
+    notes: Tuple[str, ...]
+
+    @property
+    def pass_basic(self) -> bool:
+        return (
+            self.positive_total_variance
+            and self.no_future_timestamps
+            and self.expiries_after_snapshot
+            and self.calendar_total_variance_non_decreasing
+        )
+
+
+@dataclass(frozen=True)
+class TotalVarianceSurface:
+    timestamp_ns: int
+    expiry_ns: np.ndarray
+    strike: np.ndarray
+    total_variance: np.ndarray
+
+    def __post_init__(self) -> None:
+        timestamp = int(self.timestamp_ns)
+        expiry = np.asarray(self.expiry_ns, dtype=np.int64)
+        strike = np.asarray(self.strike, dtype=np.float64)
+        variance = np.asarray(self.total_variance, dtype=np.float64)
+        if timestamp <= 0:
+            raise ValueError("timestamp_ns must be > 0")
+        if expiry.ndim != 1 or strike.ndim != 1 or variance.ndim != 1:
+            raise ValueError("surface arrays must be 1-D")
+        if len(expiry) == 0 or len(expiry) != len(strike) or len(expiry) != len(variance):
+            raise ValueError("surface arrays must be non-empty and equal length")
+        if bool((expiry <= timestamp).any()):
+            raise ValueError("surface expiry_ns must be after timestamp_ns")
+        if bool((strike <= 0.0).any()):
+            raise ValueError("surface strikes must be > 0")
+        if bool((~np.isfinite(variance)).any()) or bool((variance < 0.0).any()):
+            raise ValueError("total_variance must be finite and >= 0")
+        order = np.lexsort((strike, expiry))
+        object.__setattr__(self, "timestamp_ns", timestamp)
+        object.__setattr__(self, "expiry_ns", expiry[order])
+        object.__setattr__(self, "strike", strike[order])
+        object.__setattr__(self, "total_variance", variance[order])
+
+    @classmethod
+    def from_snapshot_frame(
+        cls,
+        frame: pd.DataFrame,
+        *,
+        timestamp_ns: int,
+        volatility_column: str = "mark_iv",
+    ) -> "TotalVarianceSurface":
+        required = {"timestamp_ns", "expiry_ns", "strike", volatility_column}
+        missing = sorted(required.difference(frame.columns))
+        if missing:
+            raise ValueError(f"surface frame missing required columns: {missing}")
+        timestamp = int(timestamp_ns)
+        future_rows = frame.loc[pd.to_numeric(frame["timestamp_ns"], errors="raise").astype("int64") > timestamp]
+        if len(future_rows) > 0:
+            raise ValueError("surface calibration cannot include future timestamp rows")
+        snapshot = frame.loc[pd.to_numeric(frame["timestamp_ns"], errors="raise").astype("int64") == timestamp].copy()
+        if snapshot.empty:
+            raise ValueError("surface snapshot has no rows for timestamp_ns")
+        expiry = pd.to_numeric(snapshot["expiry_ns"], errors="raise").astype("int64").to_numpy()
+        strike = pd.to_numeric(snapshot["strike"], errors="raise").astype("float64").to_numpy()
+        vol = pd.to_numeric(snapshot[volatility_column], errors="raise").astype("float64").to_numpy()
+        tau_years = (expiry.astype(np.float64) - float(timestamp)) / (365.0 * 24.0 * 60.0 * 60.0 * 1_000_000_000.0)
+        total_variance = vol * vol * tau_years
+        return cls(timestamp_ns=timestamp, expiry_ns=expiry, strike=strike, total_variance=total_variance)
+
+    @property
+    def expiries(self) -> np.ndarray:
+        return np.unique(self.expiry_ns)
+
+    def interpolate_total_variance(self, *, expiry_ns: int, strike: float) -> float:
+        """Interpolate total variance by strike first, then expiry."""
+        target_expiry = int(expiry_ns)
+        target_strike = float(strike)
+        if target_expiry <= self.timestamp_ns:
+            raise ValueError("target expiry must be after surface timestamp")
+        if target_strike <= 0.0:
+            raise ValueError("target strike must be > 0")
+        expiries = self.expiries
+        per_expiry = np.array([self._interpolate_strike(expiry, target_strike) for expiry in expiries], dtype=np.float64)
+        if len(expiries) == 1:
+            return float(per_expiry[0])
+        return float(np.interp(float(target_expiry), expiries.astype(np.float64), per_expiry))
+
+    def diagnostics(self) -> SurfaceDiagnostics:
+        notes = ["butterfly convexity is placeholder-only in Phase 2"]
+        by_strike = _group_by_strike(self.expiry_ns, self.strike, self.total_variance)
+        calendar_ok = True
+        for rows in by_strike.values():
+            rows_sorted = sorted(rows, key=lambda item: item[0])
+            variances = np.array([item[1] for item in rows_sorted], dtype=np.float64)
+            if len(variances) > 1 and bool((np.diff(variances) < -1e-12).any()):
+                calendar_ok = False
+                break
+        return SurfaceDiagnostics(
+            positive_total_variance=bool((self.total_variance >= 0.0).all()),
+            no_future_timestamps=True,
+            expiries_after_snapshot=bool((self.expiry_ns > self.timestamp_ns).all()),
+            calendar_total_variance_non_decreasing=calendar_ok,
+            butterfly_convexity_checked=False,
+            notes=tuple(notes),
+        )
+
+    def _interpolate_strike(self, expiry_ns: int, strike: float) -> float:
+        mask = self.expiry_ns == int(expiry_ns)
+        strikes = self.strike[mask]
+        variances = self.total_variance[mask]
+        if len(strikes) == 0:
+            raise ValueError("expiry not found")
+        if len(strikes) == 1:
+            return float(variances[0])
+        order = np.argsort(strikes)
+        return float(np.interp(strike, strikes[order], variances[order]))
+
+
+def _group_by_strike(expiry_ns: Iterable[int], strike: Iterable[float], total_variance: Iterable[float]) -> Dict[float, list[tuple[int, float]]]:
+    grouped: Dict[float, list[tuple[int, float]]] = {}
+    for expiry, strike_value, variance in zip(expiry_ns, strike, total_variance):
+        grouped.setdefault(float(strike_value), []).append((int(expiry), float(variance)))
+    return grouped

quantbt/options/tape.py

@@ -0,0 +1,226 @@
+"""
+Prepared ragged option tape.
+
+The canonical option chain remains long-form. This module compiles validated
+rows into CSR-style arrays so later selectors and execution code can scan the
+listed contracts at each observable snapshot without building a dense
+bar-by-contract matrix.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Sequence, Tuple
+
+import numpy as np
+import pandas as pd
+
+from .data import validate_option_chain_frame
+from .schema import InstrumentRegistrySignature, OptionInstrumentRegistry
+
+
+YEAR_NS = 365 * 24 * 60 * 60 * 1_000_000_000
+
+
+@dataclass(frozen=True)
+class OptionTapeSignature:
+    row_count: int
+    snapshot_count: int
+    first_timestamp_ns: int
+    last_timestamp_ns: int
+    instrument_registry_signature: InstrumentRegistrySignature
+    convention_signature: Tuple
+
+
+@dataclass(frozen=True)
+class PreparedOptionTape:
+    timestamp_ns: np.ndarray
+    row_ptr: np.ndarray
+    instrument_code: np.ndarray
+    instrument_id: Tuple[str, ...]
+    expiry_ns: np.ndarray
+    strike: np.ndarray
+    option_kind_code: np.ndarray
+    bid_price: np.ndarray
+    bid_size: np.ndarray
+    ask_price: np.ndarray
+    ask_size: np.ndarray
+    mark_price: np.ndarray
+    index_price: np.ndarray
+    forward_price: np.ndarray
+    mark_iv: np.ndarray
+    bid_iv: np.ndarray
+    ask_iv: np.ndarray
+    delta: np.ndarray
+    gamma: np.ndarray
+    vega: np.ndarray
+    theta: np.ndarray
+    open_interest: np.ndarray
+    volume: np.ndarray
+    source_latency_ns: np.ndarray
+    registry: OptionInstrumentRegistry
+    signature: OptionTapeSignature
+
+    def __post_init__(self) -> None:
+        if self.timestamp_ns.ndim != 1 or self.row_ptr.ndim != 1:
+            raise ValueError("timestamp_ns and row_ptr must be 1-D")
+        if len(self.row_ptr) != len(self.timestamp_ns) + 1:
+            raise ValueError("row_ptr length must equal snapshot_count + 1")
+        if len(self.instrument_code) != self.signature.row_count:
+            raise ValueError("instrument_code length must match row_count")
+        if self.row_ptr[0] != 0 or self.row_ptr[-1] != self.signature.row_count:
+            raise ValueError("row_ptr bounds do not match row_count")
+        if bool((np.diff(self.row_ptr) < 0).any()):
+            raise ValueError("row_ptr must be non-decreasing")
+        if bool((np.diff(self.timestamp_ns) <= 0).any()):
+            raise ValueError("timestamp_ns must be strictly increasing")
+
+    @property
+    def snapshot_count(self) -> int:
+        return len(self.timestamp_ns)
+
+    @property
+    def row_count(self) -> int:
+        return len(self.instrument_code)
+
+    def snapshot_index_at_or_before(self, decision_timestamp_ns: int, *, max_quote_age_ns: Optional[int] = None) -> int:
+        decision_ts = int(decision_timestamp_ns)
+        idx = int(np.searchsorted(self.timestamp_ns, decision_ts, side="right") - 1)
+        if idx < 0:
+            raise ValueError("no option snapshot is observable at or before decision_timestamp_ns")
+        if max_quote_age_ns is not None and decision_ts - int(self.timestamp_ns[idx]) > int(max_quote_age_ns):
+            raise ValueError("latest option snapshot is stale for decision_timestamp_ns")
+        return idx
+
+    def snapshot_slice(self, snapshot_index: int) -> slice:
+        idx = int(snapshot_index)
+        if idx < 0 or idx >= self.snapshot_count:
+            raise IndexError("snapshot_index out of range")
+        return slice(int(self.row_ptr[idx]), int(self.row_ptr[idx + 1]))
+
+    def validate_compatible(
+        self,
+        *,
+        registry_signature: Optional[InstrumentRegistrySignature] = None,
+        convention_signature: Optional[Tuple] = None,
+        timestamps_ns: Optional[Sequence[int]] = None,
+    ) -> None:
+        if registry_signature is not None and registry_signature != self.signature.instrument_registry_signature:
+            raise ValueError("prepared option tape registry signature mismatch")
+        if convention_signature is not None and tuple(convention_signature) != self.signature.convention_signature:
+            raise ValueError("prepared option tape convention signature mismatch")
+        if timestamps_ns is not None:
+            expected = np.asarray(timestamps_ns, dtype=np.int64)
+            if len(expected) != len(self.timestamp_ns) or bool((expected != self.timestamp_ns).any()):
+                raise ValueError("prepared option tape timestamp mismatch")
+
+
+def prepare_option_tape(
+    chain: pd.DataFrame,
+    registry: OptionInstrumentRegistry,
+    *,
+    max_spread_bps: Optional[float] = None,
+    max_source_latency_ns: Optional[int] = None,
+    convention_signature: Optional[Tuple] = None,
+) -> PreparedOptionTape:
+    """
+    Validate long-form chain rows and compile a CSR-style option tape.
+
+    `max_source_latency_ns` checks the per-row venue/source latency column when
+    present. Decision-time quote age is checked later by selectors because it
+    depends on the strategy timestamp.
+    """
+    canonical = validate_option_chain_frame(chain, max_spread_bps=max_spread_bps)
+    registry_symbols = registry.by_symbol
+    unknown = sorted(set(canonical["instrument_id"]).difference(registry_symbols))
+    if unknown:
+        raise ValueError(f"option chain contains instruments not in registry: {unknown}")
+    if max_source_latency_ns is not None:
+        if max_source_latency_ns < 0:
+            raise ValueError("max_source_latency_ns must be >= 0")
+        if "source_latency_ns" not in canonical:
+            raise ValueError("source_latency_ns is required when max_source_latency_ns is set")
+        if bool((canonical["source_latency_ns"].to_numpy(dtype=np.int64) > int(max_source_latency_ns)).any()):
+            raise ValueError("option chain contains stale source latency rows")
+    _validate_registry_static_fields(canonical, registry)
+    timestamps, row_ptr = _build_row_ptr(canonical["timestamp_ns"].to_numpy(dtype=np.int64))
+    ids = tuple(canonical["instrument_id"].astype(str).tolist())
+    code_map = {symbol: code for code, symbol in enumerate(registry.symbols)}
+    instrument_code = np.asarray([code_map[symbol] for symbol in ids], dtype=np.int32)
+    kind_code = np.asarray([0 if kind == "call" else 1 for kind in canonical["option_kind"].astype(str)], dtype=np.int8)
+    convention_sig = tuple(convention_signature) if convention_signature is not None else registry.signature.signature
+    signature = OptionTapeSignature(
+        row_count=len(canonical),
+        snapshot_count=len(timestamps),
+        first_timestamp_ns=int(timestamps[0]),
+        last_timestamp_ns=int(timestamps[-1]),
+        instrument_registry_signature=registry.signature,
+        convention_signature=convention_sig,
+    )
+    return PreparedOptionTape(
+        timestamp_ns=timestamps,
+        row_ptr=row_ptr,
+        instrument_code=instrument_code,
+        instrument_id=ids,
+        expiry_ns=canonical["expiry_ns"].to_numpy(dtype=np.int64),
+        strike=canonical["strike"].to_numpy(dtype=np.float64),
+        option_kind_code=kind_code,
+        bid_price=canonical["bid_price"].to_numpy(dtype=np.float64),
+        bid_size=canonical["bid_size"].to_numpy(dtype=np.float64),
+        ask_price=canonical["ask_price"].to_numpy(dtype=np.float64),
+        ask_size=canonical["ask_size"].to_numpy(dtype=np.float64),
+        mark_price=canonical["mark_price"].to_numpy(dtype=np.float64),
+        index_price=canonical["index_price"].to_numpy(dtype=np.float64),
+        forward_price=canonical["forward_price"].to_numpy(dtype=np.float64),
+        mark_iv=_float_column(canonical, "mark_iv", default=np.nan),
+        bid_iv=_float_column(canonical, "bid_iv", default=np.nan),
+        ask_iv=_float_column(canonical, "ask_iv", default=np.nan),
+        delta=_float_column(canonical, "delta", default=np.nan),
+        gamma=_float_column(canonical, "gamma", default=np.nan),
+        vega=_float_column(canonical, "vega", default=np.nan),
+        theta=_float_column(canonical, "theta", default=np.nan),
+        open_interest=_float_column(canonical, "open_interest", default=0.0),
+        volume=_float_column(canonical, "volume", default=0.0),
+        source_latency_ns=_int_column(canonical, "source_latency_ns", default=0),
+        registry=registry,
+        signature=signature,
+    )
+
+
+def _build_row_ptr(timestamp_ns: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    timestamps, counts = np.unique(timestamp_ns, return_counts=True)
+    row_ptr = np.empty(len(timestamps) + 1, dtype=np.int64)
+    row_ptr[0] = 0
+    row_ptr[1:] = np.cumsum(counts, dtype=np.int64)
+    return timestamps.astype(np.int64), row_ptr
+
+
+def _float_column(frame: pd.DataFrame, column: str, *, default: float) -> np.ndarray:
+    if column not in frame:
+        return np.full(len(frame), default, dtype=np.float64)
+    return frame[column].to_numpy(dtype=np.float64)
+
+
+def _int_column(frame: pd.DataFrame, column: str, *, default: int) -> np.ndarray:
+    if column not in frame:
+        return np.full(len(frame), default, dtype=np.int64)
+    return frame[column].to_numpy(dtype=np.int64)
+
+
+def _validate_registry_static_fields(chain: pd.DataFrame, registry: OptionInstrumentRegistry) -> None:
+    for row in chain.itertuples(index=False):
+        spec = registry.by_symbol[getattr(row, "instrument_id")]
+        if int(getattr(row, "expiry_ns")) != int(spec.expiry_ns):
+            raise ValueError("option chain expiry_ns does not match registry")
+        if abs(float(getattr(row, "strike")) - float(spec.strike)) > 1e-12:
+            raise ValueError("option chain strike does not match registry")
+        if str(getattr(row, "option_kind")).lower() != spec.option_kind.value:
+            raise ValueError("option chain option_kind does not match registry")
+        if str(getattr(row, "venue")).lower() != spec.venue:
+            raise ValueError("option chain venue does not match registry")
+        if str(getattr(row, "underlying_id")).strip() != spec.underlying_id:
+            raise ValueError("option chain underlying_id does not match registry")
+        if str(getattr(row, "quote_currency")).upper() != spec.quote_currency:
+            raise ValueError("option chain quote_currency does not match registry")
+        if str(getattr(row, "settlement_currency")).upper() != spec.settlement_currency:
+            raise ValueError("option chain settlement_currency does not match registry")

quantbt/options/templates/__init__.py

@@ -0,0 +1,33 @@
+"""Option package builder templates."""
+
+from .packages import (
+    butterfly,
+    calendar,
+    collar,
+    condor,
+    covered_call,
+    long_call,
+    long_put,
+    risk_reversal,
+    short_call,
+    short_put,
+    straddle,
+    strangle,
+    vertical,
+)
+
+__all__ = [
+    "butterfly",
+    "calendar",
+    "collar",
+    "condor",
+    "covered_call",
+    "long_call",
+    "long_put",
+    "risk_reversal",
+    "short_call",
+    "short_put",
+    "straddle",
+    "strangle",
+    "vertical",
+]