# AI Indicator Methodology Design

## Goal

Improve the AI trader input by making technical indicators less sensitive to short-history startup bias and by documenting the indicator calculation context inside the model payload. The model should receive more trustworthy trend, momentum, and volatility features without increasing prompt size or changing execution risk behavior.

## Current Context

The AI trader builds its model context in `src/binance_quant/ai_trader.py`. Configured `ai_trader_klines` values currently control both how many candles are fetched and how many candles are sent to the model. Indicators such as EMA, MACD, RSI, and ATR are calculated from that same visible history.

This can create avoidable drift from common charting-platform indicator values. EMA and MACD start from the first fetched candle, so short configured windows have little warm-up. RSI and ATR currently use simple averages over the most recent period rather than Wilder smoothing.

The existing design should remain intact in these areas:

- The model still receives market-direction data, not account balances or execution eligibility.
- The response schema remains `symbol`, `action`, `confidence`, and `reason`.
- Local risk engines remain responsible for deciding whether a prediction can be executed.
- `ai_trader_klines` remains the number of candles shown to the model for each interval.

## Proposed Design

Add internal indicator warm-up while preserving the external AI payload size.

For each configured `(interval, limit)`:

- Fetch more candles than `limit` for calculation, using `limit + 50` as the default warm-up target.
- Keep only the last `limit` candles in visible OHLCV arrays sent to the model.
- Calculate EMA, MACD, RSI, ATR, volume ratios, and range features from the full calculation history.
- Use the last visible candle as the current candle for display and summary fields.

Add an `indicator_metadata` object to each timeframe feature:

- `display_candle_count`: number of candles included in visible arrays.
- `calculation_candle_count`: number of candles used for indicator calculations.
- `warmup_candle_count`: extra candles used for warm-up.
- `warmup_requested`: configured warm-up target.
- `rsi_method`: `wilder`.
- `atr_method`: `wilder`.
- `ema_warmup_applied`: true when calculation history is longer than displayed history.

Update the prompt to tell the model that timeframe indicators may use hidden warm-up history, and that visible arrays are the recent display window rather than the full calculation window.

## Indicator Methodology

EMA should continue using the standard multiplier `2 / (period + 1)`, but it should run over the larger calculation history. This keeps the implementation simple while reducing startup bias.

MACD should use the warmed EMA series:

- MACD line: EMA12 minus EMA26.
- Signal line: EMA9 of MACD values.
- Histogram: MACD line minus signal line.

RSI should use Wilder smoothing:

- Compute the first average gain and loss from the first 14 changes.
- Smooth subsequent gain/loss values with `(previous_average * 13 + current_value) / 14`.
- Return 100 when average loss is zero.

ATR should use Wilder smoothing:

- Compute true range from high-low and prior close gaps.
- Compute the first ATR from the first 14 true ranges.
- Smooth subsequent true ranges with `(previous_atr * 13 + current_true_range) / 14`.

When there is insufficient history, indicators should still return `None` as they do today.

## Data Flow

`_load_symbol_context` should request warm-up candles from the exchange. It should preserve the configured display limit separately from the fetched calculation candles so `_model_context` can build visible arrays correctly.

The existing `_SymbolContext.candles_by_interval` can store calculation candles. Add a small companion mapping for configured display limits, or pass display limits through a helper that preserves interval order. The model payload should be the only place where candles are trimmed back to the configured display limit.

## Testing

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

- `_load_symbol_context` requests `limit + 50` candles for each configured timeframe.
- `market[].timeframes[interval]` exposes only the configured number of recent candles.
- `indicator_metadata` reports display count, calculation count, warm-up count, methods, and warm-up status.
- RSI and ATR use Wilder smoothing on multi-period data.
- `_build_prompt` explains that visible arrays are recent windows and indicators may use warm-up history.

Existing AI execution tests should continue to pass without changing predictor output handling or risk checks.

## 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 increase the number of visible candles sent to the model.
- Do not introduce configurable indicator periods in this change.