quantark 0.1.0__py3-none-any.whl

quantark/priceenv/pricing_environment.py

@@ -0,0 +1,196 @@
+"""
+Pricing environment that bundles all market data.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+from datetime import datetime
+from quantark.param import SpotQuote, VolatilitySurface, RateCurve, DividendYield, BasisYield
+from quantark.util.exceptions import MarketDataError
+from quantark.util.calendar import Calendar, DayCountConvention
+from quantark.util.numerical import safe_sqrt
+
+
+@dataclass
+class PricingEnvironment:
+    """
+    Pricing environment containing all market data required for pricing.
+
+    This class bundles together all market parameters needed for derivative pricing:
+    spot price, volatility surface, risk-free rate curve, and dividend yield.
+
+    For bond pricing, only rate_curve and valuation_date are required.
+    For equity derivatives, spot_quote and vol_surface are also required.
+
+    Attributes:
+        rate_curve: Risk-free rate curve (required)
+        valuation_date: Date of valuation (required)
+        spot_quote: Current spot price of the underlying (optional, required for equity)
+        vol_surface: Volatility surface (optional, required for equity derivatives)
+        div_yield: Dividend yield (optional, defaults to zero)
+        basis_yield: Annualized basis yield for futures (optional, defaults to None)
+        day_count_convention: Convention for calculating year fractions (default: CALENDAR_DAYS)
+        bus_days_in_year: Number of business days per year for business day convention (default: 252)
+        calendar: Optional business day calendar (used when day_count_convention is BUSINESS_DAYS)
+    """
+
+    rate_curve: RateCurve
+    valuation_date: datetime
+    spot_quote: Optional[SpotQuote] = None
+    vol_surface: Optional[VolatilitySurface] = None
+    div_yield: Optional[DividendYield] = None
+    basis_yield: Optional[BasisYield] = None
+    day_count_convention: DayCountConvention = DayCountConvention.CALENDAR_DAYS
+    bus_days_in_year: int = 252
+    calendar: Optional[Calendar] = None
+
+    def __post_init__(self):
+        """Validate pricing environment."""
+        if self.rate_curve is None:
+            raise MarketDataError("Rate curve is required")
+        if self.valuation_date is None:
+            raise MarketDataError("Valuation date is required")
+        if self.bus_days_in_year <= 0:
+            raise MarketDataError(
+                f"Business days per year must be positive, got {self.bus_days_in_year}"
+            )
+
+    @property
+    def spot(self) -> float:
+        """
+        Get current spot price.
+
+        Raises:
+            MarketDataError: If spot quote is not available
+        """
+        if self.spot_quote is None:
+            raise MarketDataError(
+                "Spot quote not available in this pricing environment"
+            )
+        return self.spot_quote.spot
+
+    def get_vol(self, strike: float, time_to_maturity: float) -> float:
+        """
+        Get volatility for given strike and maturity.
+
+        Args:
+            strike: Strike price
+            time_to_maturity: Time to maturity in years
+
+        Returns:
+            Implied volatility
+
+        Raises:
+            MarketDataError: If volatility surface is not available
+        """
+        if self.vol_surface is None:
+            raise MarketDataError(
+                "Volatility surface not available in this pricing environment"
+            )
+        if self.spot_quote is None:
+            raise MarketDataError(
+                "Spot quote not available in this pricing environment"
+            )
+        return self.vol_surface.get_vol(strike, time_to_maturity, self.spot)
+
+    def get_step_volatility(
+        self, strike: float, t_start: float, t_end: float
+    ) -> float:
+        """
+        Get effective volatility for a time step from implied vol term structure.
+
+        Uses total variance difference:
+            sigma_step = sqrt((w(t_end) - w(t_start)) / (t_end - t_start))
+        where:
+            w(t) = sigma_imp(strike, t)^2 * t
+
+        Args:
+            strike: Reference strike for volatility lookup (often spot)
+            t_start: Start time in years from valuation
+            t_end: End time in years from valuation
+
+        Returns:
+            Effective step volatility (annualized)
+        """
+        dt = t_end - t_start
+        if dt <= 0:
+            return self.get_vol(strike, max(t_end, 0.001))
+
+        vol_end = self.get_vol(strike, t_end)
+        w_end = vol_end * vol_end * t_end
+
+        if t_start <= 0:
+            w_start = 0.0
+        else:
+            vol_start = self.get_vol(strike, t_start)
+            w_start = vol_start * vol_start * t_start
+
+        var_step = max(0.0, w_end - w_start)
+        return safe_sqrt(var_step / dt)
+
+    def get_rate(self, time_to_maturity: float) -> float:
+        """
+        Get risk-free rate for given maturity.
+
+        Args:
+            time_to_maturity: Time to maturity in years
+
+        Returns:
+            Risk-free rate
+        """
+        return self.rate_curve.get_rate(time_to_maturity)
+
+    def get_discount_factor(self, time_to_maturity: float) -> float:
+        """
+        Get discount factor for given maturity.
+
+        Args:
+            time_to_maturity: Time to maturity in years
+
+        Returns:
+            Discount factor
+        """
+        return self.rate_curve.get_discount_factor(time_to_maturity)
+
+    def get_div_yield(self, time_to_maturity: float) -> float:
+        """
+        Get dividend yield for given maturity.
+
+        Args:
+            time_to_maturity: Time to maturity in years
+
+        Returns:
+            Dividend yield (0 if not specified)
+        """
+        if self.div_yield is None:
+            return 0.0
+        return self.div_yield.get_yield(time_to_maturity)
+
+    def get_basis_yield(self, time_to_maturity: float) -> float:
+        """
+        Get basis yield for given maturity.
+
+        Args:
+            time_to_maturity: Time to maturity in years
+
+        Returns:
+            Basis yield (0 if not specified)
+        """
+        if self.basis_yield is None:
+            return 0.0
+        return self.basis_yield.get_basis_yield(time_to_maturity)
+
+    def __repr__(self):
+        parts = [f"valuation_date={self.valuation_date.date()}"]
+
+        if self.spot_quote is not None:
+            parts.append(f"spot={self.spot:.2f}")
+
+        parts.append(f"rate={self.rate_curve.get_rate(1.0):.2%}")
+
+        if self.vol_surface is not None and self.spot_quote is not None:
+            parts.append(
+                f"vol={self.vol_surface.get_vol(self.spot, 1.0, self.spot):.2%}"
+            )
+
+        return f"PricingEnvironment({', '.join(parts)})"

quantark/rfq/__init__.py

@@ -0,0 +1,32 @@
+"""
+RFQ module for equity OTC quote solving.
+"""
+
+from quantark.rfq.models import (
+    RFQEngineSpec,
+    RFQInputMode,
+    RFQObjectInput,
+    RFQQuote,
+    RFQQuoteStatus,
+    RFQRequest,
+    RFQTarget,
+    RFQTargetLabel,
+    RFQTermsheetInput,
+    RFQUnknownSpec,
+)
+from quantark.rfq.service import RFQService, quote_rfq
+
+__all__ = [
+    "RFQEngineSpec",
+    "RFQInputMode",
+    "RFQObjectInput",
+    "RFQQuote",
+    "RFQQuoteStatus",
+    "RFQRequest",
+    "RFQTarget",
+    "RFQTargetLabel",
+    "RFQTermsheetInput",
+    "RFQUnknownSpec",
+    "RFQService",
+    "quote_rfq",
+]

quantark/rfq/builders.py

@@ -0,0 +1,102 @@
+"""
+Normalization helpers for term-sheet RFQ inputs.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict
+
+from quantark.param import (
+    ContinuousDividendYield,
+    FlatRateCurve,
+    FlatVolSurface,
+    SpotQuote,
+)
+from quantark.priceenv import PricingEnvironment
+from quantark.rfq.models import RFQTermsheetInput
+from quantark.rfq.registry import ENGINE_BUILDERS, PRODUCT_BUILDERS
+from quantark.util.exceptions import ValidationError
+
+
+def build_product_from_termsheet(termsheet: RFQTermsheetInput) -> Any:
+    """Build product instance from term-sheet input."""
+    return PRODUCT_BUILDERS.build(termsheet.product_type, termsheet.product_kwargs)
+
+
+def build_engine_from_termsheet(termsheet: RFQTermsheetInput) -> Any:
+    """Build engine instance from term-sheet engine spec."""
+    return ENGINE_BUILDERS.build(termsheet.engine_spec)
+
+
+def build_pricing_env_from_market_kwargs(market_kwargs: Dict[str, Any]) -> PricingEnvironment:
+    """Build pricing environment from a normalized market kwargs mapping."""
+    allowed = {
+        "valuation_date",
+        "rate_curve",
+        "rate",
+        "spot_quote",
+        "spot",
+        "asset_name",
+        "vol_surface",
+        "volatility",
+        "div_yield",
+        "dividend_yield",
+        "q",
+        "basis_yield",
+        "day_count_convention",
+        "bus_days_in_year",
+        "calendar",
+    }
+    unknown = set(market_kwargs) - allowed
+    if unknown:
+        unknown_list = ", ".join(sorted(unknown))
+        raise ValidationError(f"Unsupported market_kwargs: {unknown_list}")
+
+    valuation_date = market_kwargs.get("valuation_date")
+    if valuation_date is None:
+        raise ValidationError("market_kwargs.valuation_date is required")
+    if not isinstance(valuation_date, datetime):
+        raise ValidationError("market_kwargs.valuation_date must be datetime")
+
+    rate_curve = market_kwargs.get("rate_curve")
+    if rate_curve is None:
+        rate = market_kwargs.get("rate")
+        if rate is None:
+            raise ValidationError(
+                "market_kwargs requires either rate_curve or rate"
+            )
+        rate_curve = FlatRateCurve(rate=float(rate))
+
+    spot_quote = market_kwargs.get("spot_quote")
+    if spot_quote is None and "spot" in market_kwargs:
+        spot_quote = SpotQuote(
+            spot=float(market_kwargs["spot"]),
+            timestamp=valuation_date,
+            asset_name=market_kwargs.get("asset_name"),
+        )
+
+    vol_surface = market_kwargs.get("vol_surface")
+    if vol_surface is None and "volatility" in market_kwargs:
+        vol_surface = FlatVolSurface(volatility=float(market_kwargs["volatility"]))
+
+    div_yield = market_kwargs.get("div_yield")
+    if div_yield is None:
+        if "dividend_yield" in market_kwargs:
+            div_yield = ContinuousDividendYield(
+                div_yield=float(market_kwargs["dividend_yield"])
+            )
+        elif "q" in market_kwargs:
+            div_yield = ContinuousDividendYield(div_yield=float(market_kwargs["q"]))
+
+    return PricingEnvironment(
+        rate_curve=rate_curve,
+        valuation_date=valuation_date,
+        spot_quote=spot_quote,
+        vol_surface=vol_surface,
+        div_yield=div_yield,
+        basis_yield=market_kwargs.get("basis_yield"),
+        day_count_convention=market_kwargs.get("day_count_convention"),
+        bus_days_in_year=market_kwargs.get("bus_days_in_year", 252),
+        calendar=market_kwargs.get("calendar"),
+    )

quantark/rfq/models.py

@@ -0,0 +1,214 @@
+"""
+Data models for RFQ quote solving.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, Optional
+
+from quantark.asset.equity.engine.base_engine import BaseEngine
+from quantark.priceenv import PricingEnvironment
+from quantark.util.exceptions import ValidationError
+from quantark.util.numerical import is_close
+
+
+class RFQInputMode(Enum):
+    """Supported RFQ request input modes."""
+
+    OBJECT = "object"
+    TERMSHEET = "termsheet"
+
+
+class RFQTargetLabel(Enum):
+    """Target labels supported by the RFQ solver."""
+
+    PRICE = "price"
+    PREMIUM = "premium"
+    REOFFER = "reoffer"
+
+
+class RFQQuoteStatus(Enum):
+    """RFQ quote lifecycle status for v1."""
+
+    SUCCESS = "success"
+
+
+@dataclass(frozen=True)
+class RFQUnknownSpec:
+    """Describe the single unknown value to solve for."""
+
+    field_path: str
+    lower_bound: float
+    upper_bound: float
+    initial_guess: Optional[float] = None
+    display_label: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if not self.field_path:
+            raise ValidationError("field_path is required")
+        if self.lower_bound >= self.upper_bound:
+            raise ValidationError(
+                "lower_bound must be strictly less than upper_bound"
+            )
+        if self.initial_guess is not None:
+            if not (self.lower_bound <= self.initial_guess <= self.upper_bound):
+                raise ValidationError(
+                    "initial_guess must lie within [lower_bound, upper_bound]"
+                )
+
+
+@dataclass(frozen=True)
+class RFQTarget:
+    """Explicit target price objective."""
+
+    label: RFQTargetLabel
+    value: float
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.label, RFQTargetLabel):
+            raise ValidationError(f"Invalid RFQ target label: {self.label}")
+
+
+@dataclass(frozen=True)
+class RFQObjectInput:
+    """Object-based RFQ input path."""
+
+    product: Any
+    pricing_env: PricingEnvironment
+    engine: BaseEngine
+
+    def __post_init__(self) -> None:
+        if self.product is None:
+            raise ValidationError("product is required for object RFQ input")
+        if self.pricing_env is None:
+            raise ValidationError("pricing_env is required for object RFQ input")
+        if self.engine is None:
+            raise ValidationError("engine is required for object RFQ input")
+
+
+@dataclass(frozen=True)
+class RFQEngineSpec:
+    """Term-sheet engine selection."""
+
+    engine_name: str
+    params_type: Optional[str] = None
+    params_kwargs: Dict[str, Any] = field(default_factory=dict)
+    method: Optional[Any] = None
+    engine_kwargs: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.engine_name:
+            raise ValidationError("engine_name is required in engine_spec")
+
+
+@dataclass(frozen=True)
+class RFQTermsheetInput:
+    """Term-sheet RFQ input path."""
+
+    product_type: str
+    product_kwargs: Dict[str, Any]
+    market_kwargs: Dict[str, Any]
+    engine_spec: RFQEngineSpec
+
+    def __post_init__(self) -> None:
+        if not self.product_type:
+            raise ValidationError("product_type is required for term-sheet RFQ input")
+        if self.product_kwargs is None:
+            raise ValidationError("product_kwargs is required for term-sheet RFQ input")
+        if self.market_kwargs is None:
+            raise ValidationError("market_kwargs is required for term-sheet RFQ input")
+        if self.engine_spec is None:
+            raise ValidationError("engine_spec is required for term-sheet RFQ input")
+
+
+@dataclass(frozen=True)
+class RFQRequest:
+    """Canonical RFQ request."""
+
+    input_mode: RFQInputMode
+    unknown: RFQUnknownSpec
+    target: RFQTarget
+    object_input: Optional[RFQObjectInput] = None
+    termsheet_input: Optional[RFQTermsheetInput] = None
+    valid_until: Optional[datetime] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.input_mode, RFQInputMode):
+            raise ValidationError(f"Invalid RFQ input mode: {self.input_mode}")
+        if self.unknown is None:
+            raise ValidationError("unknown is required")
+        if self.target is None:
+            raise ValidationError("target is required")
+
+        if self.input_mode == RFQInputMode.OBJECT:
+            if self.object_input is None:
+                raise ValidationError("object_input is required when input_mode=OBJECT")
+            if self.termsheet_input is not None:
+                raise ValidationError(
+                    "termsheet_input must not be supplied when input_mode=OBJECT"
+                )
+        elif self.input_mode == RFQInputMode.TERMSHEET:
+            if self.termsheet_input is None:
+                raise ValidationError(
+                    "termsheet_input is required when input_mode=TERMSHEET"
+                )
+            if self.object_input is not None:
+                raise ValidationError(
+                    "object_input must not be supplied when input_mode=TERMSHEET"
+                )
+
+
+@dataclass(frozen=True)
+class RFQQuote:
+    """Successful RFQ quote response."""
+
+    quote_id: str
+    quoted_at: datetime
+    status: RFQQuoteStatus
+    field_path: str
+    field_label: str
+    solved_value: float
+    target_label: RFQTargetLabel
+    target_value: float
+    achieved_price: float
+    residual: float
+    engine_summary: Dict[str, Any]
+    request_summary: Dict[str, Any]
+    valid_until: Optional[datetime] = None
+
+    def __post_init__(self) -> None:
+        if not self.quote_id:
+            raise ValidationError("quote_id is required")
+        if not isinstance(self.status, RFQQuoteStatus):
+            raise ValidationError(f"Invalid RFQ quote status: {self.status}")
+        if not isinstance(self.target_label, RFQTargetLabel):
+            raise ValidationError(f"Invalid RFQ target label: {self.target_label}")
+
+    @property
+    def converged(self) -> bool:
+        """Whether the solved price matches the target within tight tolerance."""
+        return is_close(self.achieved_price, self.target_value, abs_tol=1e-8)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize quote payload for reporting and tests."""
+        return {
+            "quote_id": self.quote_id,
+            "quoted_at": self.quoted_at.isoformat(),
+            "status": self.status.value,
+            "field_path": self.field_path,
+            "field_label": self.field_label,
+            "solved_value": self.solved_value,
+            "target_label": self.target_label.value,
+            "target_value": self.target_value,
+            "achieved_price": self.achieved_price,
+            "residual": self.residual,
+            "engine_summary": dict(self.engine_summary),
+            "request_summary": dict(self.request_summary),
+            "valid_until": (
+                self.valid_until.isoformat() if self.valid_until is not None else None
+            ),
+        }