PolyHedra / tests /test_options_contracts.py
yf176
fix: accept historical options without implied volatility
e11b6ac
Raw History Blame Contribute Delete
11.7 kB
"""OptionsFlowWatcher typed contract tests."""
import copy
import json
import pytest
from pydantic import ValidationError
from polyhedra.agents.quant.options_contracts import (
FlowCandidate, OptionsFlowWatcherInput, OptionsFlowWatcherOutput,
OptionsMarketContext,
OptionsTickerResult, UnusualOptionFlow,
)
from polyhedra.core.artifacts import JsonArtifactRef
AT = "2026-09-10T12:00:00Z"
EXPIRY = "2026-09-18"
def artifact_ref(producer="OptionsFlowWatcher", run="run1", path=None, artifact_id="options"):
names = {
"OptionsFlowWatcher": "options_flow.json", "RiskAnalyst": "risk_assessment.json",
"QuantStrategist": "trade_proposals.json", "Publisher": "post.json",
"DataFetcher": "data_fetch.json",
}
return JsonArtifactRef(
schema_version="8.0", session_id="session1", run_id=run, producer=producer,
artifact_id=artifact_id, path=path or f"quant/runs/{run}/{names[producer]}",
)
def evidence():
return {"artifact": artifact_ref().model_dump(mode="json"), "field_path": "/payload/ticker_results/0/contracts/0"}
def contract(**updates):
data = dict(
contract_symbol="SPY260918C00650000", expiration=EXPIRY, strike=650.0,
option_type="CALL", bid=1.2, ask=1.3, last=1.25, volume=9000,
open_interest=2000, implied_volatility=0.31, provider="yfinance",
retrieved_at=AT, delay_or_entitlement_note="Delayed; trade-side metadata unavailable",
)
return {**data, **updates}
def context(**updates):
data = dict(
contracts_sampled=1, call_contracts_sampled=1, put_contracts_sampled=0,
call_volume=9000, put_volume=0, total_open_interest=2000,
put_call_volume_ratio=0.0, minimum_implied_volatility=0.31,
maximum_implied_volatility=0.31,
)
return {**data, **updates}
def test_market_context_allows_both_iv_bounds_absent():
model = OptionsMarketContext.model_validate(context(
minimum_implied_volatility=None, maximum_implied_volatility=None,
))
assert model.minimum_implied_volatility is None
assert model.maximum_implied_volatility is None
def test_market_context_rejects_only_one_iv_bound():
with pytest.raises(ValidationError, match="implied-volatility range requires both bounds"):
OptionsMarketContext.model_validate(context(minimum_implied_volatility=None))
def candidate(**updates):
data = dict(
candidate_id="candidate-1", contract_symbol="SPY260918C00650000",
option_type="CALL", expiration=EXPIRY, strike=650.0, directional=False,
criteria=[dict(rule="ELEVATED_VOLUME", observed_value=9000.0,
threshold=5000.0, unit="CONTRACTS")],
evidence_refs=[evidence()],
)
return {**data, **updates}
def capabilities(**updates):
data = dict(
trade_side=False, sweep_or_block=False, opening_or_closing=False,
premium=False, validated_classifier=False,
delay_or_entitlement_note="Free delayed chain; flow metadata unavailable",
)
return {**data, **updates}
def result(**updates):
data = dict(
ticker="SPY", status="COMPLETE", provider="yfinance", retrieved_at=AT,
checked_expirations=[EXPIRY], contracts=[contract()], market_context=context(),
flow_candidates=[candidate()], unusual_flows=[], capabilities=capabilities(),
delta_state="NOT_COMPARED", data_gaps=[],
)
return {**data, **updates}
def output(**updates):
data = dict(
schema_version="8.0", artifact_id="options", run_id="run1", session_id="session1",
producer="OptionsFlowWatcher", ticker_scope=["SPY"], created_at=AT,
status="COMPLETE", input_refs=[], baseline_refs=[], data_gaps=[], render_ref=None,
payload={"ticker_results": [result()],
"sampling_policy": {"maximum_expirations": 2, "maximum_contracts_per_side": 25}},
)
data.update(updates)
return data
def test_delayed_chain_context_and_candidate_are_valid_but_not_unusual_flow():
model = OptionsFlowWatcherOutput.model_validate_json(json.dumps(output()), strict=True)
ticker = model.payload.ticker_results[0]
assert ticker.flow_candidates[0].directional is False
assert ticker.unusual_flows == []
assert ticker.capabilities.trade_side is False
assert OptionsFlowWatcherOutput.model_validate_json(model.model_dump_json(), strict=True) == model
def test_input_is_root_options_scope_with_bounded_cutoff():
data = dict(
run_id="run1", session_id="session1", run_mode="BASELINE", as_of=AT,
ticker_scope=["SPY", "GLD"], dependencies={},
optional_context={"provider_fetch_cutoff": AT}, baseline_refs=[],
)
assert OptionsFlowWatcherInput.model_validate(data).ticker_scope == ["SPY", "GLD"]
for changes in (
{"ticker_scope": ["BTC"]}, {"dependencies": {"data_fetch": {}}},
{"optional_context": {"provider_fetch_cutoff": "2026-09-11T00:00:00Z"}},
):
with pytest.raises(ValidationError):
OptionsFlowWatcherInput.model_validate({**data, **changes})
def test_input_baseline_refs_are_prior_and_acl_limited():
data = dict(
run_id="run1", session_id="session1", run_mode="DELTA", as_of=AT,
ticker_scope=["SPY"], dependencies={}, optional_context={"provider_fetch_cutoff": AT},
)
allowed = [artifact_ref(name, run="prior", artifact_id=name)
for name in ("OptionsFlowWatcher", "RiskAnalyst", "QuantStrategist", "Publisher")]
assert len(OptionsFlowWatcherInput.model_validate({**data, "baseline_refs": allowed}).baseline_refs) == 4
with pytest.raises(ValidationError, match="ACL"):
OptionsFlowWatcherInput.model_validate({
**data, "baseline_refs": [artifact_ref("DataFetcher", run="prior")],
})
@pytest.mark.parametrize("changes", [
{"bid": 2.0, "ask": 1.0}, {"strike": 0}, {"volume": -1},
{"open_interest": 2.5}, {"implied_volatility": float("nan")},
{"option_type": "BUY"}, {"retrieved_at": "2026-09-10T12:00:00"},
])
def test_invalid_contracts(changes):
data = output()
data["payload"]["ticker_results"][0]["contracts"][0].update(changes)
with pytest.raises(ValidationError):
OptionsFlowWatcherOutput.model_validate(data)
@pytest.mark.parametrize("criterion,valid_criterion", [
({"rule": "ELEVATED_VOLUME", "observed_value": 4999.0, "threshold": 5000.0,
"unit": "CONTRACTS"}, False),
({"rule": "ELEVATED_VOLUME", "observed_value": 9000.0, "threshold": 5000.0,
"unit": "RATIO"}, False),
({"rule": "VOLUME_TO_OPEN_INTEREST", "observed_value": 4.4, "threshold": 1.5,
"unit": "RATIO"}, True),
])
def test_candidate_rule_must_be_true_and_match_contract(criterion, valid_criterion):
data = candidate(criteria=[criterion])
if valid_criterion:
model = FlowCandidate.model_validate(data)
assert model.criteria
full = output()
full["payload"]["ticker_results"][0]["flow_candidates"] = [data]
with pytest.raises(ValidationError, match="contradicts"):
OptionsFlowWatcherOutput.model_validate(full)
else:
with pytest.raises(ValidationError):
FlowCandidate.model_validate(data)
def test_candidate_cannot_be_directional_or_reference_absent_contract():
for changes in ({"directional": True}, {"strike": 640.0}, {"criteria": []}):
data = output()
data["payload"]["ticker_results"][0]["flow_candidates"] = [candidate(**changes)]
with pytest.raises(ValidationError):
OptionsFlowWatcherOutput.model_validate(data)
def test_unusual_flow_requires_supported_capabilities():
unusual = dict(
flow_id="flow-1", candidate_id="candidate-1", classification="Opening call sweep",
direction="BULLISH", evidence_types=["SWEEP_OR_BLOCK", "OPENING_OR_CLOSING"],
evidence_refs=[evidence()], rationale="Feed identifies an opening sweep",
)
assert UnusualOptionFlow.model_validate(unusual).direction == "BULLISH"
data = output()
data["payload"]["ticker_results"][0]["unusual_flows"] = [unusual]
with pytest.raises(ValidationError, match="unsupported"):
OptionsFlowWatcherOutput.model_validate(data)
data["payload"]["ticker_results"][0]["capabilities"].update(
sweep_or_block=True, opening_or_closing=True,
)
assert len(OptionsFlowWatcherOutput.model_validate(data).payload.ticker_results[0].unusual_flows) == 1
def test_unavailable_options_are_a_data_result_not_a_market_conclusion():
gap = dict(component="OPTIONS", code="PROVIDER_RATE_LIMITED", message="No chain", ticker="SPY")
unavailable = result(
status="UNAVAILABLE", checked_expirations=[], contracts=[], market_context=None,
flow_candidates=[], unusual_flows=[], data_gaps=[gap], delta_state="NOT_COMPARED",
)
data = output(status="UNAVAILABLE", data_gaps=[gap])
data["payload"]["ticker_results"] = [unavailable]
model = OptionsFlowWatcherOutput.model_validate(data)
assert model.status == "UNAVAILABLE"
dumped = model.model_dump(mode="json")
assert "outcome" not in dumped and "next_role" not in dumped
data["payload"]["ticker_results"][0]["data_gaps"] = []
with pytest.raises(ValidationError):
OptionsFlowWatcherOutput.model_validate(data)
@pytest.mark.parametrize("mutation", [
"wrong_scope", "duplicate_ticker", "wrong_status", "current_input", "future_contract",
"wrong_provider", "wrong_expiry", "wrong_counts", "wrong_volume", "wrong_iv",
"unknown_candidate", "too_many_expirations", "too_many_contracts",
])
def test_contradictory_output_is_rejected(mutation):
data = copy.deepcopy(output())
ticker = data["payload"]["ticker_results"][0]
if mutation == "wrong_scope":
data["ticker_scope"] = ["QQQ"]
elif mutation == "duplicate_ticker":
data["ticker_scope"] = ["SPY", "QQQ"]
data["payload"]["ticker_results"].append(ticker)
elif mutation == "wrong_status":
data["status"] = "PARTIAL"
elif mutation == "current_input":
data["input_refs"] = [artifact_ref("DataFetcher").model_dump(mode="json")]
elif mutation == "future_contract":
ticker["contracts"][0]["retrieved_at"] = "2026-09-11T00:00:00Z"
elif mutation == "wrong_provider":
ticker["contracts"][0]["provider"] = "other"
elif mutation == "wrong_expiry":
ticker["contracts"][0]["expiration"] = "2026-09-25"
elif mutation == "wrong_counts":
ticker["market_context"]["call_contracts_sampled"] = 0
elif mutation == "wrong_volume":
ticker["market_context"]["call_volume"] = 0
elif mutation == "wrong_iv":
ticker["market_context"]["minimum_implied_volatility"] = 0.2
elif mutation == "unknown_candidate":
ticker["unusual_flows"] = [dict(
flow_id="flow", candidate_id="absent", classification="Classifier",
direction="UNKNOWN", evidence_types=["VALIDATED_CLASSIFIER"],
evidence_refs=[evidence()], rationale="Model output",
)]
ticker["capabilities"]["validated_classifier"] = True
elif mutation == "too_many_expirations":
ticker["checked_expirations"] = ["2026-09-18", "2026-09-25", "2026-10-02"]
else:
data["payload"]["sampling_policy"]["maximum_contracts_per_side"] = 1
second = contract(contract_symbol="SPY260918C00660000", strike=660.0, volume=100)
ticker["contracts"].append(second)
ticker["market_context"].update(contracts_sampled=2, call_contracts_sampled=2,
call_volume=9100, total_open_interest=4000)
with pytest.raises(ValidationError):
OptionsFlowWatcherOutput.model_validate(data)