# Live AI Trade Batch Command Design

## Goal

Add a separate live AI trading command that can execute more than one AI-approved Spot action in a single run while preserving the existing single-action `live-ai-trade-once` behavior.

## User-Facing Behavior

The new command is `binance-quant live-ai-trade-batch-once`. The PowerShell runner also accepts `.\scripts\run.ps1 -Action live-ai-trade-batch-once`.

The existing `binance-quant live-ai-trade-once` remains unchanged and still performs at most one live action per run.

Batch execution is controlled by a new setting:

```text
BINANCE_AI_TRADER_MAX_ACTIONS_PER_RUN=5
```

The setting is a positive integer. The default is `5`, and users can lower or raise it in `.env` or YAML config.

## Execution Model

The batch command uses the same safety gate as the current AI trader:

- `BINANCE_MODE` must be `live`.
- `BINANCE_LIVE_AI_TRADER_ENABLED` must be `true`.
- Binance API credentials and live Binance REST/stream hosts must pass existing settings validation.

The command loads all configured `BINANCE_AI_TRADER_SYMBOLS`, fetches market context, and calls local `codex exec` once. The model must return one prediction per configured symbol. Each prediction is recorded in the existing AI trade audit table before any order is attempted.

Only `BUY` and `SELL` predictions become candidates. Candidates are sorted by confidence descending, with configured symbol order as the tie-breaker, matching the current single-action command.

The command then walks candidates until either:

- the number of executed actions reaches `ai_trader_max_actions_per_run`, or
- there are no more candidates.

For every candidate, the command re-fetches account state and the candidate symbol context before evaluating risk and placing an order. This prevents stale balances, open orders, and ticker data from being reused after an earlier order in the same batch.

## Risk And Order Handling

Each candidate continues to use the existing local risk and execution code:

- `BUY` uses the AI auto-buy path, quote amount, daily buy limit, cooldown, spread cap, existing base balance check, open protective order check, and protective stop placement.
- `SELL` uses the AI auto-sell path, free balance, daily sell limit, cooldown, open sell order check, exchange filters, quantity rounding, and min-notional validation.

Rejected candidates do not count toward the batch execution limit. Filled buys, filled sells, rollback-completed buys, rollback-failed buys, and sell-failed sells count as attempted executed actions because they submitted live order activity.

After the batch reaches the configured limit, remaining non-HOLD predictions are marked `skipped` with a reason that says the AI batch action limit was reached.

## Result And CLI Output

The Python runner returns a batch result containing:

- total prediction count,
- configured max actions,
- executed action count,
- final status,
- final reason,
- a list of per-symbol `AiTradeExecutionResult` entries.

CLI output prints a compact summary followed by one row per result:

```text
Status: completed
Max actions: 5
Executed actions: 2
Predictions: 10

Run ID  Status     Symbol   Action  Confidence  Reason
...
```

If all actionable predictions are rejected, the batch status is `rejected`. If there are no actionable predictions, the status is `no_action`.

The command exits non-zero if any per-symbol result has one of the current failed AI trade statuses:

- `rollback_failed`
- `rollback_completed`
- `sell_failed`

It also exits non-zero for pre-AI-trade data failure, matching the existing single-action command.

Email notification remains attached only to the existing single-action `live-ai-trade-once` command in this feature. Batch email formatting can be added separately.

## Files To Change

- `src/binance_quant/config.py`: add `ai_trader_max_actions_per_run` with validation.
- `src/binance_quant/ai_trader.py`: add a batch result dataclass and `run_live_ai_trade_batch_once`.
- `src/binance_quant/cli.py`: add `live-ai-trade-batch-once` and summary/table output.
- `scripts/run.ps1`: add the runner action and live safety preflight.
- `README.md`: document the new command and setting.
- `tests/test_config.py`: cover default, parsing, and invalid max-actions config.
- `tests/test_ai_trader.py`: cover multi-action execution, per-candidate state refresh, limit skipping, and unchanged single-action behavior.
- `tests/test_cli.py`: cover CLI output and exit status.
- `tests/test_run_script.py`: cover the new PowerShell action and README references.

## Testing Strategy

Use test-first implementation. Add focused tests before production code:

- config default and validation,
- batch command executes two approved actions in one run,
- batch limit marks later actionable predictions as skipped,
- account/context refresh occurs before each candidate,
- rejected candidates do not consume the action limit,
- single-action command still skips remaining predictions after the first executed action,
- CLI exits non-zero when any batch item has a live execution failure status.

Then run the targeted test files and the full test suite.

## Non-Goals

- Do not change the existing `live-ai-trade-once` behavior.
- Do not let the model place orders or call external tools.
- Do not bypass existing auto-buy or auto-sell risk engines.
- Do not add batch email notification in this change.