Models Reference¶

Pydantic data models and typing definitions for COT Bias API responses.

InferenceSchema ¶

Bases: BaseModel

Current week's AI positioning regime and macro attribution.

Classification attributes use relaxed str types (backed by Known* typing aliases) and extra="allow" to prevent upstream schema drift from breaking client applications.

Attributes:

Name	Type	Description
`symbol`	`str`	Asset ticker symbol (e.g. `'ES'`).
`report_date`	`str`	Date of the corresponding CFTC report Tuesday (YYYY-MM-DD).
`ai_bias_score`	`str`	High-level directional bias classification (`'Bullish'`, `'Bearish'`, etc.).
`regime_status`	`str`	Structural alignment state (`'Bullish Alignment'`, `'Transitioning'`, etc.).
`primary_driver`	`str`	Market participant group dominating the current weekly positioning shift.
`momentum`	`str`	Open interest flow dynamic (`'New Longs'`, `'Short Covering'`, etc.).
`cot_positioning`	`str`	Speculative vs Commercial divergence status.
`hedging_pressure`	`str`	State of commercial hedging activity (`'Elevated'`, `'Conservative'`).
`historical_percentile`	`str`	Long-term historical positioning percentile ranking.
`crowdedness_risk`	`str`	Squeeze or liquidation risk assessment (`'High Liquidation Risk'`, etc.).
`smart_money_divergence`	`str`	Aggressiveness of smart money accumulation/distribution.
`dumb_money_index`	`str`	Speculative crowd sentiment index (`'Euphoria'`, `'Fear'`, `'Neutral'`).
`qualitative_attribution`	`QualitativeAttribution`	In-depth commentary explaining the positioning drivers.

QualitativeAttribution ¶

Bases: BaseModel

Macro and structural qualitative commentary synthesized by AI.

Attributes:

Name	Type	Description
`flow_dynamic_summary`	`str`	Synthesis of weekly capital flow transitions across participant groups.
`macro_rationale`	`str`	Underlying macro catalysts driving commercial and speculative positioning.
`structural_vulnerability`	`str`	Potential vulnerabilities (e.g. illiquid basis, squeeze susceptibility).

MarketMetadata ¶

Bases: BaseModel

Metadata describing a tracked futures contract.

Attributes:

Name	Type	Description
`symbol`	`str`	Ticker symbol (e.g. `'ES'`, `'GC'`).
`name`	`str`	Full contract description name.
`cftc_code`	`str`	Official CFTC commodity code.
`sector`	`str`	Asset class sector (`'Commodity'`, `'Equity'`, `'FX'`, `'Rates'`).
`report_type`	`str`	Default report type.
`has_options`	`bool`	Whether combined options delta data is available.
`available_reports`	`list[str]`	List of CFTC report families published for this market.

MarketsResponse ¶

Bases: BaseModel

Response payload containing a list of market metadata items.

Attributes:

Name	Type	Description
`markets`	`list[MarketMetadata]`	List of tracked market contracts.

ScreenerResponse ¶

Bases: BaseModel

Response payload containing matching screen results.

Attributes:

Name	Type	Description
`total_matches`	`int`	Count of contracts matching the query filters.
`results`	`list[ScreenerResultItem]`	List of matched market items.

ScreenerResultItem ¶

Bases: BaseModel

A matched market returned by a screener query.

Attributes:

Name	Type	Description
`symbol`	`str`	Market ticker symbol.
`ai_bias_score`	`str`	Directional bias classification.
`regime_status`	`str`	Structural alignment regime.
`crowdedness_risk`	`str`	Squeeze or liquidation risk.
`primary_driver`	`str`	Dominant participant group.
`momentum`	`str`	Open interest flow dynamic.
`cot_52w_commercial`	`float \| None`	52-week normalized commercial COT Index.

TimeseriesResponse ¶

Bases: BaseModel

Response payload containing metadata and historical positioning rows.

Attributes:

Name	Type	Description
`symbol`	`str`	Ticker symbol (e.g. `'ES'`).
`cftc_code`	`str`	CFTC commodity identification code.
`contract_type`	`str`	Position breakdown type (`'fut'`, `'futopt'`, `'opt'`).
`report`	`str`	CFTC report family (`'legacy'`, `'disaggregated'`, `'tff'`, `'supplemental'`).
`count`	`int`	Number of weekly records returned.
`data`	`list[TimeseriesRow]`	List of weekly positioning rows in chronological order.

TimeseriesRow ¶

Bases: BaseModel

A single weekly report row in the positioning timeseries.

Attributes:

Name	Type	Description
`report_date`	`str`	Date of the CFTC Tuesday report (YYYY-MM-DD).
`open_interest`	`int \| None`	Aggregate total open interest across all participants.
`delta_open_interest`	`int \| None`	Week-over-week change in aggregate open interest.
`commercial_long`	`int \| None`	Commercial / Producer-Merchant long contracts.
`commercial_short`	`int \| None`	Commercial / Producer-Merchant short contracts.
`commercial_net`	`int \| None`	Commercial net positioning (long minus short).
`commercial_net_pct_oi`	`float \| None`	Commercial net position as percentage of open interest.
`noncommercial_net`	`int \| None`	Non-Commercial / Speculative net positioning.
`noncommercial_net_pct_oi`	`float \| None`	Speculative net position as percentage of open interest.
`cot_52w_commercial`	`float \| None`	52-week normalized COT Index (0 to 100).
`z_score_156w_commercial`	`float \| None`	3-year rolling Z-score of commercial net positioning.
`dumb_money_index`	`float \| None`	Dumb money positioning index.
`smart_money_divergence_index`	`float \| None`	Indicator of divergence between smart and dumb money.
`commercial_hedging_pressure`	`float \| None`	Institutional commercial hedging pressure ratio.
`conc_top4_net_short`	`float \| None`	Concentration ratio of the 4 largest net short traders.