# AI Input Robustness Design

## Goal

Improve the AI trader model input so it is less likely to overreact to weak, stale, incomplete, or contradictory market data. The change is limited to the data context and prompt guidance sent to the predictor; execution risk checks and order placement behavior remain unchanged.

## Current Context

The AI trader builds a market-direction context in `src/binance_quant/ai_trader.py`. The model receives configured symbols, per-symbol market data, raw timeframe arrays, computed indicators, 24h ticker fields, average price, aggregate trade features, realtime websocket features, liquidity features, and a compact `summary`.

The current context intentionally excludes balances, open orders, and execution eligibility. That separation should remain: the model classifies market direction, while local risk engines decide whether a prediction can be executed.

## Proposed Design

Add a per-symbol `data_quality` section and strengthen `summary` with trend and risk flags.

`market[].data_quality` should include:

- `timeframes`: one object per configured interval with `candle_count`, `required_for_sma_20`, `required_for_macd`, and `indicator_ready`.
- `aggregate_trades_status`: `ok` or `unavailable`.
- `realtime_status`: `ok`, `disabled`, or `unavailable`.
- `staleness`: derived from `aggregate_trades.last_trade_age_ms`, with a simple `fresh`, `stale`, or `unknown` status.

`market[].summary.trend` should include:

- `primary_direction`: `bullish`, `bearish`, `mixed`, or `neutral`.
- `supporting_timeframes`: intervals whose latest close and indicator state support the primary direction.
- `conflicting_timeframes`: intervals that point against the primary direction.

`market[].summary.risk_flags` should include stable string flags:

- `insufficient_history` when any configured timeframe lacks enough candles for core indicators.
- `unavailable_order_flow` when aggregate trades are unavailable or realtime data is unavailable.
- `wide_spread` when liquidity reports `wide` or `very_wide`.
- `poor_liquidity` when liquidity reports `poor`.
- `stale_order_flow` when recent aggregate trades are stale.

The prompt should instruct the model to lower confidence or prefer HOLD when these risk flags are present unless independent evidence groups strongly agree.

## Trend Heuristic

The trend summary should stay simple and explainable. For each timeframe:

- Bullish if latest close is above SMA20 and MACD histogram is positive.
- Bearish if latest close is below SMA20 and MACD histogram is negative.
- Neutral if either value is missing or the two checks disagree.

The primary direction is:

- `bullish` if bullish timeframes outnumber bearish timeframes and at least one timeframe is bullish.
- `bearish` if bearish timeframes outnumber bullish timeframes and at least one timeframe is bearish.
- `mixed` if bullish and bearish counts are equal and both are present.
- `neutral` if no timeframe has a directional vote.

## Testing

Add focused tests in `tests/test_ai_trader.py` that verify:

- `market[].data_quality` is present and reports indicator readiness for configured timeframes.
- `summary.trend` reports bullish, bearish, mixed, or neutral direction from existing timeframe features.
- `summary.risk_flags` includes insufficient history, unavailable order flow, stale order flow, wide spread, and poor liquidity when those conditions apply.
- `_build_prompt` tells the model to treat data quality and risk flags as confidence constraints.

## Non-Goals

- Do not change the predictor response schema.
- Do not add balances, holdings, open orders, or execution eligibility to AI input.
- Do not change order execution, auto-buy risk, or auto-sell risk behavior.
- Do not replace the current indicator formulas in this change.