quantbt-engine 1.0.7__py3-none-any.whl

quantbt/optimization/space.py

@@ -0,0 +1,223 @@
+"""Search-space parsing shared by QuantBT optimization surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import math
+from typing import Any, Mapping, Optional
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class SearchSpaceInfo:
+    """Static facts used by sampler compatibility checks."""
+
+    has_categorical: bool
+    has_continuous: bool
+    has_dynamic_float: bool
+    variable_names: tuple[str, ...]
+    grid_size: Optional[int]
+
+
+def suggest_parameter(trial, name: str, spec: Any) -> Any:
+    """Suggest one parameter from a QuantBT param range spec.
+
+    Supported specs are intentionally compatible with existing alpha notebooks:
+    numeric tuples, categorical lists/tuples, ranges, bool choices, and scalar
+    constants.
+    """
+
+    if _is_bool_choice(spec):
+        return trial.suggest_categorical(name, [True, False])
+    if isinstance(spec, tuple) and len(spec) in (2, 3) and all(_is_number(value) for value in spec):
+        low, high = spec[0], spec[1]
+        step = spec[2] if len(spec) == 3 else None
+        if _looks_int(low) and _looks_int(high) and (step is None or _looks_int(step)):
+            return trial.suggest_int(name, int(low), int(high), step=1 if step is None else int(step))
+        if step is None:
+            return trial.suggest_float(name, float(low), float(high))
+        return trial.suggest_float(name, float(low), float(high), step=float(step))
+    if isinstance(spec, range):
+        values = list(spec)
+        if not values:
+            raise ValueError(f"param_ranges[{name!r}] is empty")
+        return trial.suggest_categorical(name, values)
+    if isinstance(spec, (list, tuple)):
+        if not spec:
+            raise ValueError(f"param_ranges[{name!r}] is empty")
+        return trial.suggest_categorical(name, list(spec))
+    return spec
+
+
+def suggest_params(trial, param_ranges: Mapping[str, Any], fixed_params: Optional[Mapping[str, Any]] = None) -> dict[str, Any]:
+    """Suggest params and merge fixed params.
+
+    Fixed params override `param_ranges` entries by name. Additional fixed
+    params are appended to the final parameter dict.
+    """
+
+    fixed = dict(fixed_params or {})
+    params: dict[str, Any] = {}
+    for name, spec in dict(param_ranges or {}).items():
+        if name in fixed:
+            params[name] = fixed[name]
+        else:
+            params[name] = suggest_parameter(trial, name, spec)
+    for name, value in fixed.items():
+        params.setdefault(name, value)
+    return params
+
+
+def stable_params_key(params: Mapping[str, Any]) -> str:
+    """Return a deterministic key for duplicate-trial detection."""
+
+    return json.dumps(_jsonable(params), sort_keys=True, separators=(",", ":"))
+
+
+def search_space_info(param_ranges: Mapping[str, Any], fixed_params: Optional[Mapping[str, Any]] = None) -> SearchSpaceInfo:
+    """Inspect a QuantBT search space for sampler compatibility."""
+
+    fixed = set(dict(fixed_params or {}))
+    has_categorical = False
+    has_continuous = False
+    has_dynamic_float = False
+    variable_names: list[str] = []
+    grid_size = 1
+    finite_grid = True
+    for name, spec in dict(param_ranges or {}).items():
+        if name in fixed:
+            continue
+        kind = _spec_kind(spec)
+        if kind == "constant":
+            continue
+        variable_names.append(name)
+        if kind == "categorical":
+            has_categorical = True
+        if kind in {"float", "int"}:
+            has_continuous = has_continuous or kind == "float"
+        values = _grid_values(name, spec, allow_dynamic=True)
+        if values is None:
+            finite_grid = False
+            has_dynamic_float = True
+        else:
+            grid_size *= len(values)
+    return SearchSpaceInfo(
+        has_categorical=has_categorical,
+        has_continuous=has_continuous,
+        has_dynamic_float=has_dynamic_float,
+        variable_names=tuple(variable_names),
+        grid_size=grid_size if finite_grid else None,
+    )
+
+
+def build_grid_search_space(
+    param_ranges: Mapping[str, Any],
+    fixed_params: Optional[Mapping[str, Any]] = None,
+    *,
+    max_grid_size: int = 100_000,
+) -> dict[str, list[Any]]:
+    """Build an Optuna GridSampler search space from finite specs."""
+
+    fixed = set(dict(fixed_params or {}))
+    grid: dict[str, list[Any]] = {}
+    size = 1
+    for name, spec in dict(param_ranges or {}).items():
+        if name in fixed:
+            continue
+        values = _grid_values(name, spec, allow_dynamic=False)
+        if values is None:
+            raise ValueError(f"grid sampler requires finite values for {name!r}")
+        if len(values) == 1 and _spec_kind(spec) == "constant":
+            continue
+        grid[name] = values
+        size *= len(values)
+        if size > int(max_grid_size):
+            raise ValueError(f"grid search space has {size:,} combinations, above max_grid_size={int(max_grid_size):,}")
+    if not grid:
+        raise ValueError("grid sampler requires at least one non-fixed finite parameter")
+    return grid
+
+
+def _grid_values(name: str, spec: Any, *, allow_dynamic: bool) -> Optional[list[Any]]:
+    if _is_bool_choice(spec):
+        return [True, False]
+    if isinstance(spec, tuple) and len(spec) in (2, 3) and all(_is_number(value) for value in spec):
+        low, high = spec[0], spec[1]
+        step = spec[2] if len(spec) == 3 else None
+        if _looks_int(low) and _looks_int(high) and (step is None or _looks_int(step)):
+            step_i = 1 if step is None else int(step)
+            if step_i <= 0:
+                raise ValueError(f"integer step for {name!r} must be positive")
+            return list(range(int(low), int(high) + 1, step_i))
+        if step is None:
+            if allow_dynamic:
+                return None
+            raise ValueError(f"grid sampler requires a float step for {name!r}")
+        return _float_grid(float(low), float(high), float(step), name)
+    if isinstance(spec, range):
+        values = list(spec)
+        if not values:
+            raise ValueError(f"param_ranges[{name!r}] is empty")
+        return values
+    if isinstance(spec, (list, tuple)):
+        if not spec:
+            raise ValueError(f"param_ranges[{name!r}] is empty")
+        return list(spec)
+    return [spec]
+
+
+def _float_grid(low: float, high: float, step: float, name: str) -> list[float]:
+    if step <= 0.0:
+        raise ValueError(f"float step for {name!r} must be positive")
+    if high < low:
+        raise ValueError(f"high must be >= low for {name!r}")
+    count = int(math.floor((high - low) / step + 1e-12)) + 1
+    values = [float(low + i * step) for i in range(count)]
+    if values and values[-1] < high and math.isclose(values[-1] + step, high, rel_tol=1e-9, abs_tol=1e-12):
+        values.append(float(high))
+    return values
+
+
+def _spec_kind(spec: Any) -> str:
+    if _is_bool_choice(spec):
+        return "categorical"
+    if isinstance(spec, range):
+        return "categorical"
+    if isinstance(spec, tuple) and len(spec) in (2, 3) and all(_is_number(value) for value in spec):
+        if _looks_int(spec[0]) and _looks_int(spec[1]) and (len(spec) == 2 or _looks_int(spec[2])):
+            return "int"
+        return "float"
+    if isinstance(spec, (list, tuple)):
+        return "categorical"
+    return "constant"
+
+
+def _is_bool_choice(spec: Any) -> bool:
+    return (
+        isinstance(spec, (list, tuple))
+        and len(spec) == 2
+        and all(isinstance(value, bool) for value in spec)
+        and set(spec) == {True, False}
+    )
+
+
+def _looks_int(value: Any) -> bool:
+    return isinstance(value, (int, np.integer)) and not isinstance(value, bool)
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float, np.integer, np.floating)) and not isinstance(value, bool)
+
+
+def _jsonable(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {str(key): _jsonable(val) for key, val in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(item) for item in value]
+    if isinstance(value, np.generic):
+        return value.item()
+    if isinstance(value, np.ndarray):
+        return [_jsonable(item) for item in value.tolist()]
+    return value

quantbt/options/__init__.py

@@ -0,0 +1,215 @@
+"""
+QuantBT options domain package.
+
+Phase 1 exposes schema, convention, and canonical chain-data validation only.
+Pricing, execution, ledger, margin, endpoint wiring, and Nautilus validation are
+added in later phases.
+"""
+
+from .conventions import (
+    OptionVenueConvention,
+    binance_european_options_convention,
+    deribit_inverse_option_convention,
+    deribit_linear_usdc_option_convention,
+)
+from .cache import OptionPreparedRunCache, option_package_cache_key
+from .data import CANONICAL_OPTION_CHAIN_COLUMNS, validate_option_chain_frame
+from .execution import (
+    OptionDepthFidelity,
+    OptionExecutionConfig,
+    OptionLimitFidelity,
+    OptionPackageExecutionResult,
+    execute_option_package,
+)
+from .fees import (
+    OptionFeeResult,
+    OptionFeeSchedule,
+    calculate_option_fee,
+    deribit_inverse_fee_schedule,
+    deribit_linear_usdc_fee_schedule,
+)
+from .greeks import (
+    OptionGreeks,
+    inverse_black76_greeks_base,
+    inverse_black76_greeks_quote,
+    linear_black76_greeks,
+    scale_greeks_to_reporting_currency,
+)
+from .hedging import (
+    HedgeDecision,
+    HedgePathResult,
+    OptionHedgeConfig,
+    OptionHedgePolicyType,
+    compute_net_option_delta,
+    hedge_decision,
+    run_delta_hedge_path,
+)
+from .iv import IVStatus, ImpliedVolResult, implied_vol_black76, implied_vol_inverse_black76_base
+from .ledger import OptionLedger, OptionPosition
+from .lifecycle import (
+    OptionSettlementRepresentation,
+    OptionSettlementResult,
+    option_expiry_payoff_per_unit,
+    settle_option_expiry,
+)
+from .margin import (
+    ExternalOptionMarginValidator,
+    OptionLiquidationAudit,
+    OptionMarginConfig,
+    OptionMarginModel,
+    OptionMarginRequirement,
+    calculate_option_margin,
+    liquidate_option_positions,
+)
+from .packages import (
+    OptionPackageExecutionPolicy,
+    OptionPackageIntent,
+    OptionPackageLeg,
+    compile_option_package_orders,
+)
+from .pricing import (
+    black76_intrinsic,
+    black76_parity_residual,
+    black76_parity_value,
+    black76_price,
+    inverse_black76_intrinsic_base,
+    inverse_black76_parity_residual_base,
+    inverse_black76_parity_value_base,
+    inverse_black76_price_base,
+)
+from .schema import (
+    ExerciseStyle,
+    InstrumentRegistrySignature,
+    OptionDecisionFillPolicy,
+    OptionInstrumentRegistry,
+    OptionInstrumentSpec,
+    OptionKind,
+    PremiumConvention,
+    SettlementStyle,
+)
+from .selectors import (
+    OptionSelection,
+    OptionSelectionFilters,
+    available_option_rows,
+    select_atm_option,
+    select_target_delta_option,
+    select_target_dte_option,
+    select_target_moneyness_option,
+)
+from .surface import SurfaceDiagnostics, TotalVarianceSurface
+from .tape import YEAR_NS, OptionTapeSignature, PreparedOptionTape, prepare_option_tape
+from .strategy import GammaScalpingConfig, OptionStrategyRun, build_gamma_scalping_strategy_run
+from .templates import (
+    butterfly,
+    calendar,
+    collar,
+    condor,
+    covered_call,
+    long_call,
+    long_put,
+    risk_reversal,
+    short_call,
+    short_put,
+    straddle,
+    strangle,
+    vertical,
+)
+
+__all__ = [
+    "CANONICAL_OPTION_CHAIN_COLUMNS",
+    "ExerciseStyle",
+    "ExternalOptionMarginValidator",
+    "HedgeDecision",
+    "HedgePathResult",
+    "GammaScalpingConfig",
+    "InstrumentRegistrySignature",
+    "OptionDecisionFillPolicy",
+    "OptionDepthFidelity",
+    "OptionExecutionConfig",
+    "OptionFeeResult",
+    "OptionFeeSchedule",
+    "OptionHedgeConfig",
+    "OptionHedgePolicyType",
+    "OptionInstrumentRegistry",
+    "OptionInstrumentSpec",
+    "OptionKind",
+    "OptionGreeks",
+    "OptionLimitFidelity",
+    "OptionLiquidationAudit",
+    "OptionMarginConfig",
+    "OptionMarginModel",
+    "OptionMarginRequirement",
+    "OptionPackageExecutionPolicy",
+    "OptionPackageExecutionResult",
+    "OptionPackageIntent",
+    "OptionPackageLeg",
+    "OptionLedger",
+    "OptionVenueConvention",
+    "OptionSelection",
+    "OptionSelectionFilters",
+    "OptionSettlementRepresentation",
+    "OptionSettlementResult",
+    "OptionStrategyRun",
+    "OptionTapeSignature",
+    "OptionPosition",
+    "OptionPreparedRunCache",
+    "PremiumConvention",
+    "PreparedOptionTape",
+    "SettlementStyle",
+    "SurfaceDiagnostics",
+    "TotalVarianceSurface",
+    "YEAR_NS",
+    "binance_european_options_convention",
+    "black76_intrinsic",
+    "black76_parity_residual",
+    "black76_parity_value",
+    "black76_price",
+    "build_gamma_scalping_strategy_run",
+    "calculate_option_fee",
+    "calculate_option_margin",
+    "compile_option_package_orders",
+    "deribit_inverse_option_convention",
+    "deribit_inverse_fee_schedule",
+    "deribit_linear_usdc_option_convention",
+    "deribit_linear_usdc_fee_schedule",
+    "implied_vol_black76",
+    "implied_vol_inverse_black76_base",
+    "inverse_black76_greeks_base",
+    "inverse_black76_greeks_quote",
+    "inverse_black76_intrinsic_base",
+    "inverse_black76_parity_residual_base",
+    "inverse_black76_parity_value_base",
+    "inverse_black76_price_base",
+    "IVStatus",
+    "ImpliedVolResult",
+    "linear_black76_greeks",
+    "available_option_rows",
+    "compute_net_option_delta",
+    "execute_option_package",
+    "hedge_decision",
+    "liquidate_option_positions",
+    "option_expiry_payoff_per_unit",
+    "option_package_cache_key",
+    "prepare_option_tape",
+    "run_delta_hedge_path",
+    "scale_greeks_to_reporting_currency",
+    "select_atm_option",
+    "select_target_delta_option",
+    "select_target_dte_option",
+    "select_target_moneyness_option",
+    "settle_option_expiry",
+    "butterfly",
+    "calendar",
+    "collar",
+    "condor",
+    "covered_call",
+    "long_call",
+    "long_put",
+    "risk_reversal",
+    "short_call",
+    "short_put",
+    "straddle",
+    "strangle",
+    "vertical",
+    "validate_option_chain_frame",
+]

quantbt/options/cache.py

@@ -0,0 +1,116 @@
+"""
+Prepared option run cache.
+
+The cache is explicit and signature-checked. It is designed for service/WFO
+loops where the same option chain tape is replayed with many package choices.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Optional, Tuple
+
+import pandas as pd
+
+from ..core.orders import OrderIntent
+from .packages import OptionPackageIntent, compile_option_package_orders
+from .schema import OptionInstrumentRegistry
+from .tape import PreparedOptionTape, prepare_option_tape
+
+
+@dataclass
+class OptionPreparedRunCache:
+    tape: PreparedOptionTape
+    package_orders: Dict[Tuple, Tuple[OrderIntent, ...]] = field(default_factory=dict)
+    metadata: Dict = field(default_factory=dict)
+
+    @classmethod
+    def from_chain(
+        cls,
+        chain: pd.DataFrame,
+        registry: OptionInstrumentRegistry,
+        *,
+        max_spread_bps: Optional[float] = None,
+        max_source_latency_ns: Optional[int] = None,
+        convention_signature: Optional[Tuple] = None,
+    ) -> "OptionPreparedRunCache":
+        tape = prepare_option_tape(
+            chain,
+            registry,
+            max_spread_bps=max_spread_bps,
+            max_source_latency_ns=max_source_latency_ns,
+            convention_signature=convention_signature,
+        )
+        return cls(
+            tape=tape,
+            metadata={
+                "cache_type": "OptionPreparedRunCache",
+                "snapshot_count": int(tape.snapshot_count),
+                "row_count": int(tape.row_count),
+                "registry_symbols": tuple(registry.symbols),
+                "convention_signature": tape.signature.convention_signature,
+            },
+        )
+
+    def validate(
+        self,
+        registry: OptionInstrumentRegistry,
+        *,
+        timestamps_ns=None,
+        convention_signature: Optional[Tuple] = None,
+    ) -> None:
+        self.tape.validate_compatible(
+            registry_signature=registry.signature,
+            timestamps_ns=timestamps_ns,
+            convention_signature=convention_signature,
+        )
+
+    def compile_package(self, package: OptionPackageIntent) -> Tuple[OrderIntent, ...]:
+        key = option_package_cache_key(package)
+        cached = self.package_orders.get(key)
+        if cached is None:
+            cached = compile_option_package_orders(package)
+            self.package_orders[key] = cached
+        return cached
+
+    @property
+    def package_cache_size(self) -> int:
+        return len(self.package_orders)
+
+
+def option_package_cache_key(package: OptionPackageIntent) -> Tuple:
+    """Return a deterministic key for compiled option package order leaves."""
+    return (
+        int(package.timestamp_ns),
+        str(package.package_id),
+        float(package.quantity),
+        package.execution_policy.value,
+        None if package.max_debit is None else float(package.max_debit),
+        None if package.min_credit is None else float(package.min_credit),
+        tuple(
+            (
+                leg.instrument_id,
+                leg.side.value,
+                float(leg.ratio),
+                leg.order_type.value,
+                None if leg.limit_price is None else float(leg.limit_price),
+                leg.tif.value,
+                leg.role,
+                leg.tag,
+                tuple(sorted((str(k), _stable_value(v)) for k, v in leg.metadata.items())),
+            )
+            for leg in package.legs
+        ),
+        package.tag,
+        tuple(sorted((str(k), _stable_value(v)) for k, v in package.metadata.items())),
+    )
+
+
+def _stable_value(value):
+    if isinstance(value, (str, int, float, bool, type(None))):
+        return value
+    if isinstance(value, dict):
+        return tuple(sorted((str(k), _stable_value(v)) for k, v in value.items()))
+    if isinstance(value, (list, tuple)):
+        return tuple(_stable_value(item) for item in value)
+    return repr(value)