morphiq-sdk 0.1.0__py3-none-any.whl

morphiq_sdk/market_data.py

@@ -0,0 +1,91 @@
+"""Provider-neutral price data. No data fetching or optional dependencies live here."""
+
+from dataclasses import dataclass
+from datetime import UTC, date, datetime
+from math import isfinite
+from typing import Literal, Protocol
+
+PriceInterval = Literal["1d", "1m", "5m", "15m", "30m", "60m"]
+PriceAdjustment = Literal["split", "split_and_dividend", "unadjusted"]
+
+
+@dataclass(frozen=True)
+class PriceBar:
+    """A close with a session date or timezone-aware bar-start label.
+
+    The label is not an exact quote/close timestamp. A final intraday bar may
+    still be forming; it must not automatically become a regime request's as_of.
+    """
+
+    time: date | datetime
+    close: float
+
+    def __post_init__(self) -> None:
+        if not isfinite(self.close) or self.close <= 0:
+            raise ValueError("Close must be finite and positive")
+        if not isinstance(self.time, date):
+            raise ValueError("A price label must be a date or datetime")
+        if isinstance(self.time, datetime) and self.time.utcoffset() is None:
+            raise ValueError("Intraday timestamps must include a timezone")
+
+
+@dataclass(frozen=True)
+class PriceHistory:
+    """Nonempty, oldest-first prices with explicit provider and adjustment identity.
+
+    Gaps between bars are preserved. No interpolation, resampling or currency
+    conversion is implied. Prices retain the source's quoted units.
+    """
+
+    symbol: str
+    interval: PriceInterval
+    adjustment: PriceAdjustment
+    source: str
+    bars: tuple[PriceBar, ...]
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.bars, tuple) or not self.bars:
+            raise ValueError("History requires a nonempty tuple of bars")
+        if self.interval not in ("1d", "1m", "5m", "15m", "30m", "60m"):
+            raise ValueError("Unsupported price interval")
+        if self.adjustment not in ("split", "split_and_dividend", "unadjusted"):
+            raise ValueError("Unknown price adjustment")
+        if not self.symbol.strip() or not self.source.strip():
+            raise ValueError("Symbol and source are required")
+        for bar in self.bars:
+            intraday_label = isinstance(bar.time, datetime)
+            if intraday_label != (self.interval != "1d"):
+                raise ValueError("Daily bars need session dates; intraday bars need datetimes")
+        labels = [
+            bar.time.astimezone(UTC) if isinstance(bar.time, datetime) else bar.time
+            for bar in self.bars
+        ]
+        if any(left >= right for left, right in zip(labels, labels[1:], strict=False)):
+            raise ValueError("Price labels must be unique and ordered oldest to newest")
+
+    @property
+    def prices(self) -> tuple[float, ...]:
+        return tuple(bar.close for bar in self.bars)
+
+    @property
+    def latest(self) -> PriceBar:
+        return self.bars[-1]
+
+
+class PriceProvider(Protocol):
+    """Optional source of regular-session price bars, separate from the API client.
+
+    Date bounds use the instrument's exchange calendar: start inclusive, end
+    exclusive. Providers declare adjustments in the result and raise on invalid
+    or unavailable data. Available history can be shorter than the requested
+    date range; callers enforce their own required observation count.
+    """
+
+    def history(
+        self,
+        symbol: str,
+        *,
+        start: date,
+        end: date,
+        interval: PriceInterval = "1d",
+    ) -> PriceHistory: ...

morphiq_sdk/models.py

@@ -0,0 +1,442 @@
+"""API wire models for the reviewed HTTP contract; no pricing logic lives here."""
+
+from typing import Annotated, Any, Generic, Literal, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field, FiniteFloat, PrivateAttr
+
+ExerciseStyle = Literal["european", "american"]
+OptionType = Literal["call", "put"]
+PricingModel = Literal[
+    "auto", "black_scholes_merton", "bjerksund_stensland_2002", "bjerksund_stensland_1993"
+]
+
+
+class _Request(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True, allow_inf_nan=False, frozen=True)
+
+
+class DividendEvent(_Request):
+    """Cash per share at an ex-dividend time expressed in years from valuation."""
+
+    ex_time_years: FiniteFloat
+    cash_amount: FiniteFloat
+
+
+class _OptionRequest(_Request):
+    """Common option inputs. Rates and yield are decimals; time is in years.
+
+    Numeric/model-domain validation belongs to the service. The SDK rejects
+    malformed wire types and non-finite values without clamping or repricing.
+    """
+
+    exercise_style: ExerciseStyle
+    option_type: OptionType
+    spot: FiniteFloat
+    strike: FiniteFloat
+    time_to_expiry_years: FiniteFloat
+    risk_free_rate: FiniteFloat
+    dividend_yield: FiniteFloat
+    pricing_model: PricingModel = "auto"
+    model_version: str | None = None
+    dividend_schedule: list[DividendEvent] = Field(default_factory=list, max_length=16)
+
+    def to_wire(self) -> dict[str, Any]:
+        """Validate current inputs, preserving omission and explicit null/empty values."""
+        values = self.model_dump(exclude={"dividend_schedule"}, exclude_unset=True)
+        # Freezing the model does not freeze lists or track their in-place edits.
+        # Include nonempty schedules and revalidate edits before JSON serialization.
+        if self.dividend_schedule or "dividend_schedule" in self.model_fields_set:
+            values["dividend_schedule"] = self.dividend_schedule
+        validated = type(self).model_validate(values)
+        result = validated.model_dump(mode="json", exclude_unset=True)
+        # This required wire field has a convenience default in Python.
+        result["pricing_model"] = self.pricing_model
+        return result
+
+
+class PriceRequest(_OptionRequest):
+    """Price an option at a supplied annual volatility, expressed as a decimal."""
+
+    volatility: FiniteFloat
+
+
+class ImpliedVolatilityRequest(_OptionRequest):
+    """Solve volatility from a per-share market price in the spot/strike currency.
+
+    Volatility is an output, not a request field. The service validates premiums
+    and numerical domains without SDK-side clamping or local solving.
+    """
+
+    market_price: FiniteFloat
+
+
+class _Response(BaseModel):
+    # Retain additive fields. A new resolved model name must not break decoding.
+    model_config = ConfigDict(extra="allow", strict=True, allow_inf_nan=False)
+
+
+class GreeksRequest(PriceRequest):
+    """Price and all ten Greeks at a supplied volatility, using the pricing inputs.
+
+    Cash-dividend schedules are forwarded unchanged. The service owns model
+    selection, schedule support and numerical-domain validation.
+    """
+
+
+class AnalyticsRequest(PriceRequest):
+    """Price and Greeks, optionally evaluated at IV solved from a market premium.
+
+    The wire contract requires volatility even with a premium; the service uses
+    it only when market_price is absent or null. Preserve both fields unchanged.
+    """
+
+    market_price: FiniteFloat | None = None
+
+
+class Greeks(_Response):
+    """Unscaled API values: time derivatives per year; volatility/rates per unit.
+
+    No calendar-day, percentage-point or contract-multiplier conversion occurs.
+    """
+
+    delta: FiniteFloat
+    gamma: FiniteFloat
+    theta: FiniteFloat
+    vega: FiniteFloat
+    rho: FiniteFloat
+    vanna: FiniteFloat
+    volga: FiniteFloat
+    charm: FiniteFloat
+    veta: FiniteFloat
+    color: FiniteFloat
+
+
+class GreeksResult(_Response):
+    price: FiniteFloat
+    greeks: Greeks
+    pricing_model: str
+    model_version: str
+
+
+class ImpliedVolatilityResult(_Response):
+    """Unmodified solver diagnostics. Volatility is a decimal fraction.
+
+    Known residual bases are ``forward_normalised_price`` and ``option_price``;
+    retain future basis names without interpreting or converting their values.
+    ``used_fallback`` describes the algorithm, not solution quality.
+    """
+
+    implied_volatility: FiniteFloat
+    iterations: int = Field(ge=0)
+    used_fallback: bool
+    residual: FiniteFloat
+    residual_basis: str
+    pricing_model: str
+    model_version: str
+
+
+class AnalyticsResult(GreeksResult):
+    """Combined result; the nested IV solve has no separate commercial charge."""
+
+    implied_volatility: ImpliedVolatilityResult | None = None
+
+
+class EngineIdentity(_Response):
+    name: str
+    version: str
+    revision: str
+
+
+class PolicyMetadata(_Response):
+    snapshot_id: str
+    revision: str
+    plan: str
+    records: list[str]
+
+
+class _CommercialMetadata(_Response):
+    fcu_quoted: int | None = Field(default=None, ge=0)
+    fcu_charged: int | None = Field(default=None, ge=0)
+    fcu_schedule_id: str | None = None
+    fcu_schedule_version: str | None = None
+    policy: PolicyMetadata | None = None
+    remaining_fcu_instance_estimate: int | None = Field(default=None, ge=0)
+    budget_period: str | None = None
+    budget_reset_at: str | None = None
+
+
+class ResponseMetadata(_CommercialMetadata):
+    """Server provenance and optional commercial CU evidence.
+
+    ``units_charged`` is an internal compute weight, not a commercial CU charge.
+    Missing ``fcu_charged`` means unreported, not zero.
+    """
+
+    request_id: str
+    api_version: str
+    engine_version: str
+    engines: list[EngineIdentity]
+    units_charged: int = Field(ge=0)
+    compute_schedule_version: str
+
+
+class ServiceErrorMetadata(_CommercialMetadata):
+    request_id: str
+    api_version: str
+    service_version: str
+
+
+class PriceResult(_Response):
+    price: FiniteFloat
+    exercise_style: ExerciseStyle
+    option_type: OptionType
+    pricing_model: str
+    model_version: str
+
+
+class _EvidenceResponse(_Response):
+    _raw_body: bytes = PrivateAttr(default=b"")
+    _headers: dict[str, str] = PrivateAttr(default_factory=dict)
+
+    @property
+    def raw_body(self) -> bytes:
+        """JSON response bytes, with any reflected API key redacted."""
+        return self._raw_body
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """HTTP response headers without retaining a credential-bearing request."""
+        return self._headers.copy()
+
+
+class PriceResponse(_EvidenceResponse):
+    result: PriceResult
+    metadata: ResponseMetadata
+
+
+class GreeksResponse(_EvidenceResponse):
+    result: GreeksResult
+    metadata: ResponseMetadata
+
+
+class ImpliedVolatilityResponse(_EvidenceResponse):
+    result: ImpliedVolatilityResult
+    metadata: ResponseMetadata
+
+
+class AnalyticsResponse(_EvidenceResponse):
+    result: AnalyticsResult
+    metadata: ResponseMetadata
+
+
+class RegimeRequest(_Request):
+    """Comparable positive prices, oldest first; no sampling interval is assumed.
+
+    V1 requires 512 prices and consumes the latest 507. Supply split-adjusted
+    closes without cash-dividend total-return adjustment. The service validates
+    timestamp/domain semantics and request byte limits; no cropping occurs here.
+    """
+
+    prices: list[Annotated[FiniteFloat, Field(gt=0)]] = Field(min_length=512)
+    as_of: str | None = Field(default=None, max_length=64)
+
+    def to_wire(self) -> dict[str, Any]:
+        # Revalidate mutable price lists without dropping explicit null timestamps.
+        values = self.model_dump(exclude={"prices"}, exclude_unset=True)
+        values["prices"] = self.prices
+        validated = type(self).model_validate(values)
+        return validated.model_dump(mode="json", exclude_unset=True)
+
+
+RegimeDecisionLabel = Literal["not_eligible", "supported", "unsupported", "unresolved"]
+RegimeDirectionLabel = Literal["UP", "DOWN", "NEUTRAL"]
+RegimeStateLabel = Literal["LOWER_VOL", "HIGHER_VOL"]
+_Label = TypeVar("_Label")
+_Prediction = TypeVar("_Prediction")
+
+
+class RegimeScore(_Response, Generic[_Label]):
+    label: _Label
+    value: FiniteFloat = Field(ge=0, le=1)
+
+
+class RegimePrediction(_Response, Generic[_Label]):
+    label: _Label
+    scores: list[RegimeScore[_Label]]
+    selection: Literal["argmax"]
+
+
+class RegimeDecisionPrediction(RegimePrediction[RegimeDecisionLabel]):
+    scores: list[RegimeScore[RegimeDecisionLabel]] = Field(min_length=4, max_length=4)
+
+
+class RegimeDirectionPrediction(RegimePrediction[RegimeDirectionLabel]):
+    scores: list[RegimeScore[RegimeDirectionLabel]] = Field(min_length=3, max_length=3)
+
+
+class RegimeStatePrediction(RegimePrediction[RegimeStateLabel]):
+    scores: list[RegimeScore[RegimeStateLabel]] = Field(min_length=2, max_length=2)
+
+
+class RegimeBasis(_Response):
+    target: Literal[
+        "reference_procedure_outcome",
+        "selected_state_tendency",
+        "filtered_scale_order_membership",
+    ]
+
+
+class RegimeAvailable(_Response, Generic[_Prediction]):
+    status: Literal["available"]
+    basis: RegimeBasis
+    prediction: _Prediction
+
+
+class RegimeNotApplicable(_Response):
+    status: Literal["not_applicable"]
+    basis: RegimeBasis
+    prediction: None
+    reason_code: Literal["predicted_not_eligible"]
+
+
+class RegimeUnavailable(_Response):
+    status: Literal["unavailable"]
+    basis: RegimeBasis
+    prediction: None
+    reason_code: Literal["prediction_unavailable"]
+
+
+class RegimeScoreContract(_Response):
+    kind: Literal["uncalibrated_softmax"]
+    version: str
+    sum_tolerance: FiniteFloat
+
+
+class RegimeResult(_Response):
+    score_contract: RegimeScoreContract
+    decision: Annotated[
+        RegimeAvailable[RegimeDecisionPrediction] | RegimeNotApplicable | RegimeUnavailable,
+        Field(discriminator="status"),
+    ]
+    direction: Annotated[
+        RegimeAvailable[RegimeDirectionPrediction] | RegimeNotApplicable | RegimeUnavailable,
+        Field(discriminator="status"),
+    ]
+    state: Annotated[
+        RegimeAvailable[RegimeStatePrediction] | RegimeNotApplicable | RegimeUnavailable,
+        Field(discriminator="status"),
+    ]
+
+
+class RegimeProvenance(_Response):
+    model_id: str
+    model_status: str
+    model_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+    preprocessing: str
+    teacher_executed: bool
+
+
+class RegimeConsumedPriceRange(_Response):
+    start_index: int = Field(ge=0)
+    end_index_exclusive: int = Field(ge=0)
+
+
+class RegimeMetadata(_CommercialMetadata):
+    response_contract_version: str
+    request_id: str
+    api_version: str
+    service_version: str
+    engines: list[EngineIdentity]
+    provenance: RegimeProvenance
+    received_price_count: int = Field(ge=0)
+    window_price_count: int = Field(ge=0)
+    price_count: int = Field(ge=0)
+    return_count: int = Field(ge=0)
+    consumed_price_range: RegimeConsumedPriceRange
+    observation_index: int = Field(ge=0)
+    input_price_index: int = Field(ge=0)
+    as_of: str | None
+    return_type: Literal["log"]
+    return_unit: Literal["fraction"]
+    inference_time_us: int = Field(ge=0)
+    all_prices_consumed: bool
+
+
+class RegimeResponse(_EvidenceResponse):
+    result: RegimeResult
+    metadata: RegimeMetadata
+
+
+class ErrorDetails(_Response):
+    code: str
+    message: str
+    field: str | None = None
+
+
+class ErrorEnvelope(_Response):
+    error: ErrorDetails
+    metadata: ResponseMetadata | ServiceErrorMetadata
+
+
+_OptionRequestType = TypeVar("_OptionRequestType", bound=_OptionRequest)
+_OptionResultType = TypeVar("_OptionResultType", bound=_Response)
+
+
+class _BatchRequest(_Request, Generic[_OptionRequestType]):
+    # This is the reviewed wire limit, not an account/plan limit.
+    requests: list[_OptionRequestType] = Field(min_length=1, max_length=1024)
+
+    def to_wire(self) -> dict[str, Any]:
+        validated = type(self).model_validate({"requests": self.requests})
+        return {"requests": [request.to_wire() for request in validated.requests]}
+
+
+class BatchPriceRequest(_BatchRequest[PriceRequest]):
+    """One explicit batch of pricing requests in caller order."""
+
+
+class BatchGreeksRequest(_BatchRequest[GreeksRequest]):
+    """One explicit batch of price-and-Greeks requests."""
+
+
+class BatchImpliedVolatilityRequest(_BatchRequest[ImpliedVolatilityRequest]):
+    """One explicit batch of IV solves."""
+
+
+class BatchAnalyticsRequest(_BatchRequest[AnalyticsRequest]):
+    """One explicit batch of combined analytics requests."""
+
+
+class BatchSuccess(_Response, Generic[_OptionResultType]):
+    index: int = Field(ge=0)
+    status: Literal["success"]
+    result: _OptionResultType
+
+
+class BatchFailure(_Response):
+    index: int = Field(ge=0)
+    status: Literal["error"]
+    error: ErrorDetails
+
+
+class _BatchResponse(_EvidenceResponse, Generic[_OptionResultType]):
+    metadata: ResponseMetadata
+    results: list[
+        Annotated[BatchSuccess[_OptionResultType] | BatchFailure, Field(discriminator="status")]
+    ]
+
+
+class BatchPriceResponse(_BatchResponse[PriceResult]):
+    """Ordered outcomes and one metadata/charge block for the entire batch."""
+
+
+class BatchGreeksResponse(_BatchResponse[GreeksResult]):
+    """Ordered Greeks outcomes and batch-level charge evidence."""
+
+
+class BatchImpliedVolatilityResponse(_BatchResponse[ImpliedVolatilityResult]):
+    """Ordered IV outcomes and batch-level charge evidence."""
+
+
+class BatchAnalyticsResponse(_BatchResponse[AnalyticsResult]):
+    """Ordered combined analytics outcomes and batch-level charge evidence."""