"""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)