"""Typed contracts for trend, sentiment, event context, detection, and assignment.""" import copy import pytest from pydantic import ValidationError from polyhedra.agents.quant.analysis_contracts import ( EventRouterInput, EventRouterOutput, MacroContextWatcherInput, MacroContextWatcherOutput, MarketEventWatcherOutput, SentimentAnalystOutput, TrendAnalystInput, TrendAnalystOutput, UnusualEventDetectorOutput, ) from polyhedra.agents.quant.market_data_contracts import DataFetcherOutput, MarketDataArtifact from polyhedra.agents.quant.options_contracts import OptionsFlowWatcherOutput from polyhedra.core.artifacts import JsonArtifactRef AT = "2026-09-10T12:00:00Z" def ref(producer, run="run1", ticker=None, artifact_id=None): names = { "DataFetcher": f"raw/{ticker}.json" if ticker else "data_fetch.json", "TrendAnalyst": "trend_analysis.json", "SentimentAnalyst": "sentiment_analysis.json", "MarketEventWatcher": "market_events.json", "OptionsFlowWatcher": "options_flow.json", "MacroContextWatcher": "macro_context.json", "UnusualEventDetector": "unusual_events.json", "EventRouter": "event_route.json", } return JsonArtifactRef( schema_version="8.0", artifact_id=artifact_id or f"{producer}-{ticker or run}", run_id=run, session_id="session1", producer=producer, path=f"quant/runs/{run}/{names[producer]}", ) def evidence(producer="DataFetcher", path="/ohlcv/0/close"): return {"artifact": ref(producer, ticker="SPY" if producer == "DataFetcher" else None), "field_path": path} def envelope(producer, payload, scope=("SPY",), inputs=(), status="COMPLETE", gaps=(), run="run1"): return dict( schema_version="8.0", artifact_id=f"{producer}-{run}", run_id=run, session_id="session1", producer=producer, ticker_scope=list(scope), created_at=AT, status=status, input_refs=[ref(item) for item in inputs], baseline_refs=[], data_gaps=list(gaps), payload=payload, render_ref=None, ) def trend(scope=("SPY",), run="run1"): analyses = [dict( ticker=ticker, price_direction="BULLISH", price_change_percentage=1.5, measurement_days=5, support_levels=[], resistance_levels=[], volume_state="NORMAL", sma_20_state="ABOVE", ema_20_state="ABOVE", moving_average_crossover="BULLISH", rsi_14_state="NEUTRAL", macd_state="BULLISH", confidence="MEDIUM", evidence_refs=[evidence()], delta_state="NOT_COMPARED", data_gaps=[], ) for ticker in scope] return TrendAnalystOutput.model_validate(envelope( "TrendAnalyst", {"ticker_analyses": analyses}, scope, ("DataFetcher",), run=run, )) def options(scope=("SPY",)): results = [] gaps = [] for ticker in scope: gap = dict(component="OPTIONS", code="PROVIDER_UNAVAILABLE", message="No chain", ticker=ticker) gaps.append(gap) results.append(dict( ticker=ticker, status="UNAVAILABLE", provider="yfinance", retrieved_at=AT, checked_expirations=[], contracts=[], market_context=None, flow_candidates=[], unusual_flows=[], capabilities=dict( trade_side=False, sweep_or_block=False, opening_or_closing=False, premium=False, validated_classifier=False, delay_or_entitlement_note="Delayed chain", ), delta_state="NOT_COMPARED", data_gaps=[gap], )) return OptionsFlowWatcherOutput.model_validate(envelope( "OptionsFlowWatcher", {"ticker_results": results, "sampling_policy": { "maximum_expirations": 2, "maximum_contracts_per_side": 25, }}, scope, (), "UNAVAILABLE", gaps, )) def market_events(scope=("SPY",), run="run1"): contexts = [] for ticker in scope: gap = dict(component="EVENT_FEED", code="EXTERNAL_EVENT_FEED_NOT_CONFIGURED", message="No approved external feed", ticker=ticker) contexts.append(dict( ticker=ticker, observed_changes=[], relevant_catalysts=[], source_refs=[], checked_at=AT, external_event_feed_status="NOT_CONFIGURED", external_event_feed_provider=None, delta_state="NOT_COMPARED", data_gaps=[gap], )) return MarketEventWatcherOutput.model_validate(envelope( "MarketEventWatcher", {"ticker_contexts": contexts}, scope, ("DataFetcher",), run=run, )) def macro(scope=("SPY",), run="run1"): inputs = ["MarketEventWatcher"] if set(scope) & {"SPY", "QQQ", "GLD"}: inputs.append("OptionsFlowWatcher") return MacroContextWatcherOutput.model_validate(envelope( "MacroContextWatcher", dict( main_line="UNCLEAR", drivers=[], affected_tickers=list(scope), confidence="UNKNOWN", uncertainties=["Insufficient macro evidence"], contradictions=[], delta_state="NOT_COMPARED", data_gaps=[], ), scope, inputs, run=run, )) def unusual(scope=("SPY",), event=True, run="run1"): inputs = ["MarketEventWatcher", "MacroContextWatcher"] if set(scope) & {"SPY", "QQQ", "GLD"}: inputs.append("OptionsFlowWatcher") events = [dict( event_id="event-1", event_type="PRICE", affected_tickers=[scope[0]], significance=0.7, confidence="MEDIUM", evidence_refs=[evidence()], missing_evidence=[], delta_state="NEW", )] if event else [] return UnusualEventDetectorOutput.model_validate(envelope( "UnusualEventDetector", {"meaningful_events": events, "suppressed_events": [], "monitoring_conditions": []}, scope, inputs, run=run, )) def event_route(scope=("SPY",), assigned=True): assignments = [dict( event_id="event-1", ticker=scope[0], relevance=0.8, evidence_refs=[evidence()], rationale="Direct price evidence", )] if assigned else [] return EventRouterOutput.model_validate(envelope( "EventRouter", {"assignments": assignments, "unassigned_event_ids": [] if assigned else ["event-1"]}, scope, ("UnusualEventDetector",), )) def market_artifact(ticker="SPY"): return MarketDataArtifact.model_validate(dict( schema_version="8.0", artifact_id=f"DataFetcher-{ticker}", session_id="session1", run_id="run1", producer="DataFetcher", ticker=ticker, retrieved_at=AT, market_date="2026-09-09", status="PARTIAL", ohlcv=[dict(market_date="2026-09-09", open=100.0, high=105.0, low=99.0, close=103.0, adjusted_close=None, volume=1000.0)], indicators={"points": [dict(market_date="2026-09-09", sma_20=None, ema_20=None, rsi_14=None, macd=None, macd_signal=None, macd_histogram=None)]}, news=[], earnings=[], quality_issues=[dict( component="INDICATORS", code="INSUFFICIENT_HISTORY", message="Warmup", ticker=ticker)], provenance=[ dict(component="OHLCV", provider="test", retrieved_at=AT, source_observed_at=AT, freshness="FRESH", availability="AVAILABLE", record_count=1), dict(component="INDICATORS", provider="computed", retrieved_at=AT, source_observed_at=None, freshness="UNKNOWN", availability="UNAVAILABLE", record_count=0), dict(component="NEWS", provider="test", retrieved_at=AT, source_observed_at=None, freshness="UNKNOWN", availability="AVAILABLE", record_count=0), dict(component="EARNINGS", provider=None, retrieved_at=AT, source_observed_at=None, freshness="UNKNOWN", availability="NOT_APPLICABLE", record_count=0), ], baseline_ref=None, )) def fetch_manifest(ticker="SPY"): return DataFetcherOutput.model_validate(dict( schema_version="8.0", artifact_id="DataFetcher-run1", run_id="run1", session_id="session1", producer="DataFetcher", completed_at=AT, ticker_scope=[ticker], overall_status="PARTIAL", ticker_results=[dict( ticker=ticker, status="PARTIAL", market_data_ref=ref("DataFetcher", ticker=ticker), summary_ref=None, available_components=["OHLCV"], unavailable_components=["INDICATORS"], empty_components=["NEWS"], not_applicable_components=["EARNINGS"], errors=[dict(component="INDICATORS", code="INSUFFICIENT_HISTORY", message="Warmup", ticker=ticker)], )], )) def test_trend_has_fixed_fields_and_no_routing_authority(): model = trend() assert model.payload.ticker_analyses[0].measurement_days == 5 data = model.model_dump(mode="json") data["payload"]["ticker_analyses"][0]["next_role"] = "QuantResearcher" with pytest.raises(ValidationError): TrendAnalystOutput.model_validate(data) data = model.model_dump(mode="json") data["ticker_scope"] = ["QQQ"] with pytest.raises(ValidationError, match="exactly one"): TrendAnalystOutput.model_validate(data) def test_trend_input_requires_matching_typed_fetch_outputs(): data = dict( run_id="run1", session_id="session1", run_mode="BASELINE", as_of=AT, ticker_scope=["SPY"], dependencies={"data_fetch": fetch_manifest(), "market_data": [market_artifact()]}, optional_context={}, baseline_refs=[], ) assert TrendAnalystInput.model_validate(data).dependencies.market_data[0].ticker == "SPY" changed = copy.deepcopy(data) changed["ticker_scope"] = ["QQQ"] with pytest.raises(ValidationError): TrendAnalystInput.model_validate(changed) def sentiment_analysis(sufficiency="SUFFICIENT", direction="NEUTRAL"): sufficient = sufficiency == "SUFFICIENT" return dict( ticker="AAPL", source_coverage=[dict(source="wire", article_count=2, scored_count=2 if sufficient else 0)], article_count=2, scored_count=2 if sufficient else 0, unscored_count=0 if sufficient else 2, evidence_sufficiency=sufficiency, aggregate_sentiment=direction, themes=[dict( theme="Demand", direction="NEUTRAL", evidence_refs=[evidence()], )] if sufficient else [], earnings_sentiment=None, trend_alignment="NOT_ASSESSED", incremental_signal_value=sufficient, confidence="MEDIUM" if sufficient else "UNKNOWN", evidence_refs=[evidence()] if sufficient else [], delta_state="NOT_COMPARED", data_gaps=[], ) def test_sentiment_distinguishes_insufficient_evidence_from_neutral(): valid = SentimentAnalystOutput.model_validate(envelope( "SentimentAnalyst", {"ticker_analyses": [sentiment_analysis()]}, ("AAPL",), ("DataFetcher",), )) assert valid.payload.ticker_analyses[0].aggregate_sentiment == "NEUTRAL" insufficient = sentiment_analysis("MOSTLY_UNSCORED", "UNKNOWN") assert SentimentAnalystOutput.model_validate(envelope( "SentimentAnalyst", {"ticker_analyses": [insufficient]}, ("AAPL",), ("DataFetcher",), )) insufficient["aggregate_sentiment"] = "NEUTRAL" with pytest.raises(ValidationError, match="insufficient"): SentimentAnalystOutput.model_validate(envelope( "SentimentAnalyst", {"ticker_analyses": [insufficient]}, ("AAPL",), ("DataFetcher",), )) def test_sentiment_rejects_specialized_scope_and_bad_counts(): with pytest.raises(ValidationError, match="GENERAL"): SentimentAnalystOutput.model_validate(envelope( "SentimentAnalyst", {"ticker_analyses": [{**sentiment_analysis(), "ticker": "SPY"}]}, ("SPY",), ("DataFetcher",), )) analysis = sentiment_analysis() analysis["article_count"] = 3 with pytest.raises(ValidationError, match="coverage"): SentimentAnalystOutput.model_validate(envelope( "SentimentAnalyst", {"ticker_analyses": [analysis]}, ("AAPL",), ("DataFetcher",), )) def test_market_event_feed_not_configured_is_explicit(): model = market_events() assert model.payload.ticker_contexts[0].external_event_feed_status == "NOT_CONFIGURED" data = model.model_dump(mode="json") data["payload"]["ticker_contexts"][0]["data_gaps"] = [] with pytest.raises(ValidationError, match="explicit"): MarketEventWatcherOutput.model_validate(data) data = model.model_dump(mode="json") context = data["payload"]["ticker_contexts"][0] context.update(external_event_feed_status="AVAILABLE", external_event_feed_provider=None) with pytest.raises(ValidationError, match="provider"): MarketEventWatcherOutput.model_validate(data) def test_macro_requires_options_only_for_scope_overlap(): spy_input = dict( run_id="run1", session_id="session1", run_mode="BASELINE", as_of=AT, ticker_scope=["SPY"], dependencies={"market_events": market_events(), "options_flow": options()}, optional_context={}, baseline_refs=[], ) assert MacroContextWatcherInput.model_validate(spy_input) with pytest.raises(ValidationError, match="requires Options"): MacroContextWatcherInput.model_validate({ **spy_input, "dependencies": {"market_events": market_events(), "options_flow": None}, }) btc_input = { **spy_input, "ticker_scope": ["BTC"], "dependencies": {"market_events": market_events(("BTC",)), "options_flow": None}, } assert MacroContextWatcherInput.model_validate(btc_input) assert macro(("BTC",)).payload.main_line == "UNCLEAR" def test_macro_driver_cannot_expand_scope_or_exist_without_evidence(): data = macro().model_dump(mode="json") data["payload"]["main_line"] = "Rates dominate" with pytest.raises(ValidationError, match="UNCLEAR"): MacroContextWatcherOutput.model_validate(data) data["payload"]["drivers"] = [dict( driver_id="rates", description="Rates rising", direction="BEARISH", relevance_weight=0.8, affected_tickers=["QQQ"], evidence_refs=[evidence()], )] with pytest.raises(ValidationError, match="expands"): MacroContextWatcherOutput.model_validate(data) def test_event_detection_separates_meaningful_and_suppressed(): model = unusual() assert model.payload.meaningful_events[0].significance == 0.7 data = model.model_dump(mode="json") event = data["payload"]["meaningful_events"][0] data["payload"]["suppressed_events"] = [dict( event_id="event-1", affected_tickers=["SPY"], reason="DUPLICATE", rationale="Duplicate", evidence_refs=[evidence()], )] with pytest.raises(ValidationError, match="meaningful and suppressed"): UnusualEventDetectorOutput.model_validate(data) data = model.model_dump(mode="json") data["payload"]["meaningful_events"][0]["affected_tickers"] = ["QQQ"] with pytest.raises(ValidationError, match="scope"): UnusualEventDetectorOutput.model_validate(data) def test_event_router_accounts_for_every_meaningful_event_without_routing_agents(): source = unusual() route = event_route() inputs = EventRouterInput.model_validate(dict( run_id="run1", session_id="session1", run_mode="BASELINE", as_of=AT, ticker_scope=["SPY"], dependencies={"unusual_events": source}, optional_context={"market_events": market_events(), "options_flow": options()}, baseline_refs=[], )) route.validate_for_input(inputs) data = route.model_dump(mode="json") data["payload"]["next_role"] = "SPYAnalyst" with pytest.raises(ValidationError): EventRouterOutput.model_validate(data) incomplete = event_route(assigned=False).model_copy( update={"payload": event_route(assigned=False).payload.model_copy(update={"unassigned_event_ids": []})} ) with pytest.raises(ValueError, match="every and only"): incomplete.validate_for_input(inputs) def test_unavailable_analysis_requires_data_gap(): data = trend().model_dump(mode="json") data["status"] = "UNAVAILABLE" with pytest.raises(ValidationError, match="explicit"): TrendAnalystOutput.model_validate(data) def test_outputs_require_declared_dependency_references(): cases = [ (trend(), TrendAnalystOutput), (market_events(), MarketEventWatcherOutput), (macro(), MacroContextWatcherOutput), (unusual(), UnusualEventDetectorOutput), (event_route(), EventRouterOutput), ] for valid, model in cases: data = valid.model_dump(mode="json") data["input_refs"] = [] with pytest.raises(ValidationError, match="dependency references"): model.model_validate(data)