PolyHedra / src /polyhedra /services /options_normalizer.py
yf176
fix(options): preserve Yahoo auth errors and add dated chain fallback
c342958
Raw History Blame Contribute Delete
7.54 kB
"""Normalize the existing bounded options snapshot into the V8 contract."""
from __future__ import annotations
from datetime import date, datetime
from polyhedra.agents.quant.options_contracts import (
FlowCandidate, FlowCriterion, FlowRule, OptionContract, OptionsMarketContext,
OptionsTickerResult, ProviderCapabilities,
)
from polyhedra.core.artifacts import DataIssue, DeltaState, EvidenceRef, JsonArtifactRef
from polyhedra.services.options_data import OptionsDataSnapshot
def normalize_options_snapshot(
snapshot: OptionsDataSnapshot,
*,
ticker: str,
output_ref: JsonArtifactRef,
result_index: int,
) -> OptionsTickerResult:
if snapshot.symbol != ticker:
raise ValueError("options snapshot symbol contradicts activation scope")
retrieved_at = datetime.fromisoformat(snapshot.retrieved_at.replace("Z", "+00:00"))
gaps: list[DataIssue] = []
expirations: list[date] = []
for value in snapshot.expirations_checked:
try:
expiration = date.fromisoformat(value)
except ValueError:
gaps.append(_gap(ticker, "INVALID_EXPIRATION", f"Invalid expiration: {value}"))
continue
if expiration not in expirations:
expirations.append(expiration)
contracts: list[OptionContract] = []
source_indexes: list[int] = []
for source_index, item in enumerate(snapshot.contracts):
try:
contract = OptionContract(
contract_symbol=item.contract_symbol or None,
expiration=date.fromisoformat(item.expiration),
strike=item.strike,
option_type=item.option_type.upper(),
bid=item.bid,
ask=item.ask,
last=item.last,
volume=item.volume,
open_interest=item.open_interest,
implied_volatility=item.implied_volatility,
provider=item.provider,
retrieved_at=datetime.fromisoformat(item.retrieved_at.replace("Z", "+00:00")),
delay_or_entitlement_note=item.source_delay_or_entitlement_note or None,
)
except (TypeError, ValueError) as exc:
gaps.append(_gap(
ticker, "INVALID_OPTION_CONTRACT", f"Excluded sampled contract: {exc}",
))
continue
if contract.expiration not in expirations:
gaps.append(_gap(
ticker, "UNCHECKED_EXPIRATION",
f"Excluded contract from unrecorded expiration {contract.expiration}",
))
continue
contracts.append(contract)
source_indexes.append(source_index)
capabilities = ProviderCapabilities(
trade_side=False,
sweep_or_block=False,
opening_or_closing=False,
premium=False,
validated_classifier=False,
delay_or_entitlement_note=snapshot.note or None,
)
if not contracts:
gaps.append(_gap(
ticker,
"OPTIONS_PROVIDER_UNAVAILABLE",
snapshot.note or "Options provider returned no usable sampled contracts",
))
return OptionsTickerResult(
ticker=ticker,
status="UNAVAILABLE",
provider=snapshot.provider,
retrieved_at=retrieved_at,
checked_expirations=expirations,
contracts=[],
market_context=None,
flow_candidates=[],
unusual_flows=[],
capabilities=capabilities,
delta_state=DeltaState.NOT_COMPARED,
data_gaps=gaps,
)
calls = [item for item in contracts if item.option_type == "CALL"]
puts = [item for item in contracts if item.option_type == "PUT"]
call_volume = _known_sum([item.volume for item in calls])
put_volume = _known_sum([item.volume for item in puts])
open_interest = _known_sum([item.open_interest for item in contracts])
iv = [item.implied_volatility for item in contracts if item.implied_volatility is not None]
context = OptionsMarketContext(
contracts_sampled=len(contracts),
call_contracts_sampled=len(calls),
put_contracts_sampled=len(puts),
call_volume=call_volume,
put_volume=put_volume,
total_open_interest=open_interest,
put_call_volume_ratio=(
put_volume / call_volume
if call_volume not in {None, 0} and put_volume is not None else None
),
minimum_implied_volatility=min(iv) if iv else None,
maximum_implied_volatility=max(iv) if iv else None,
)
candidates = [
candidate
for index, (contract, source_index) in enumerate(zip(contracts, source_indexes, strict=True))
if snapshot.provider != "marketdata_historical"
if (candidate := _candidate(
ticker, contract, output_ref, result_index, index, source_index,
)) is not None
]
return OptionsTickerResult(
ticker=ticker,
status="COMPLETE",
provider=snapshot.provider,
retrieved_at=retrieved_at,
checked_expirations=expirations,
contracts=contracts,
market_context=context,
flow_candidates=candidates,
unusual_flows=[],
capabilities=capabilities,
delta_state=DeltaState.NOT_COMPARED,
data_gaps=gaps,
)
def _candidate(
ticker: str,
contract: OptionContract,
output_ref: JsonArtifactRef,
result_index: int,
contract_index: int,
source_index: int,
) -> FlowCandidate | None:
criteria: list[FlowCriterion] = []
if contract.volume is not None and contract.volume >= 5000:
criteria.append(FlowCriterion(
rule=FlowRule.ELEVATED_VOLUME,
observed_value=float(contract.volume),
threshold=5000.0,
unit="CONTRACTS",
))
if (contract.volume is not None and contract.volume >= 500
and contract.open_interest not in {None, 0}):
ratio = contract.volume / contract.open_interest
if ratio >= 1.5:
criteria.append(FlowCriterion(
rule=FlowRule.VOLUME_TO_OPEN_INTEREST,
observed_value=ratio,
threshold=1.5,
unit="RATIO",
))
if contract.implied_volatility is not None and contract.implied_volatility >= 0.6:
criteria.append(FlowCriterion(
rule=FlowRule.ELEVATED_IMPLIED_VOLATILITY,
observed_value=contract.implied_volatility,
threshold=0.6,
unit="DECIMAL_IV",
))
if not criteria:
return None
evidence = EvidenceRef(
artifact=output_ref,
field_path=f"/payload/ticker_results/{result_index}/contracts/{contract_index}",
)
identity = contract.contract_symbol or (
f"{contract.expiration}-{contract.option_type}-{contract.strike:g}-{source_index}"
)
return FlowCandidate(
candidate_id=f"{ticker}-{identity}",
contract_symbol=contract.contract_symbol,
option_type=contract.option_type,
expiration=contract.expiration,
strike=contract.strike,
criteria=criteria,
directional=False,
evidence_refs=[evidence],
)
def _known_sum(values: list[int | None]) -> int | None:
return sum(values) if all(value is not None for value in values) else None
def _gap(ticker: str, code: str, message: str) -> DataIssue:
return DataIssue(component="OPTIONS", code=code, message=message, ticker=ticker)