# Live AI Trade Batch Command Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add `live-ai-trade-batch-once`, a separate live AI trading command that can execute up to a configurable number of AI-approved Spot actions per run.

**Architecture:** Reuse the existing AI prediction, audit, risk, and execution functions. Add a batch runner that records all predictions, sorts actionable predictions by confidence, refreshes account and symbol context before each candidate, and stops after `ai_trader_max_actions_per_run` live order attempts.

**Tech Stack:** Python 3.12, Typer CLI, Pydantic settings, pytest, SQLite audit storage, existing Binance Spot client abstractions.

---

### Task 1: Config Setting

**Files:**
- Modify: `src/binance_quant/config.py`
- Test: `tests/test_config.py`

- [ ] **Step 1: Write failing config tests**

Add assertions to `test_ai_trader_defaults_are_disabled_and_conservative`:

```python
assert settings.ai_trader_max_actions_per_run == 5
```

Add to `test_ai_trader_settings_parse_environment`:

```python
monkeypatch.setenv("BINANCE_AI_TRADER_MAX_ACTIONS_PER_RUN", "7")
assert settings.ai_trader_max_actions_per_run == 7
```

Add to `test_ai_trader_rejects_invalid_settings`:

```python
with pytest.raises(ValueError, match="ai_trader_max_actions_per_run must be positive"):
    Settings(_env_file=None, ai_trader_max_actions_per_run=0)
```

- [ ] **Step 2: Verify config tests fail**

Run:

```bash
python -m pytest tests/test_config.py::test_ai_trader_defaults_are_disabled_and_conservative tests/test_config.py::test_ai_trader_settings_parse_environment tests/test_config.py::test_ai_trader_rejects_invalid_settings -q
```

Expected: FAIL because `Settings` has no `ai_trader_max_actions_per_run`.

- [ ] **Step 3: Implement config**

Add this field next to the AI trader settings:

```python
ai_trader_max_actions_per_run: int = Field(default=5, ge=1)
```

Add this validator near the AI confidence validator:

```python
@field_validator("ai_trader_max_actions_per_run")
@classmethod
def positive_ai_trader_max_actions_per_run(cls, value: int) -> int:
    if value <= 0:
        raise ValueError("ai_trader_max_actions_per_run must be positive")
    return value
```

- [ ] **Step 4: Verify config tests pass**

Run:

```bash
python -m pytest tests/test_config.py::test_ai_trader_defaults_are_disabled_and_conservative tests/test_config.py::test_ai_trader_settings_parse_environment tests/test_config.py::test_ai_trader_rejects_invalid_settings -q
```

Expected: PASS.

### Task 2: Batch Runner

**Files:**
- Modify: `src/binance_quant/ai_trader.py`
- Test: `tests/test_ai_trader.py`

- [ ] **Step 1: Write failing batch runner tests**

Import `run_live_ai_trade_batch_once`.

Add tests that prove multiple approved actions can execute, the max-action limit marks later actions as skipped, and account/symbol context is refreshed before each candidate.

- [ ] **Step 2: Verify batch tests fail**

Run:

```bash
python -m pytest tests/test_ai_trader.py::test_run_live_ai_trade_batch_once_executes_multiple_approved_actions tests/test_ai_trader.py::test_run_live_ai_trade_batch_once_skips_after_action_limit tests/test_ai_trader.py::test_run_live_ai_trade_batch_once_refreshes_account_for_each_candidate -q
```

Expected: FAIL because the batch runner does not exist.

- [ ] **Step 3: Implement batch result and runner**

Add `AiTradeBatchExecutionResult` and `run_live_ai_trade_batch_once(...)` beside `run_live_ai_trade_once`. The runner must reuse the single-action prediction and execution helpers, refresh account and symbol context before each candidate, count only live-order activity statuses against the max-actions limit, and mark remaining non-HOLD predictions skipped when the limit is reached.

- [ ] **Step 4: Verify batch tests pass**

Run:

```bash
python -m pytest tests/test_ai_trader.py::test_run_live_ai_trade_batch_once_executes_multiple_approved_actions tests/test_ai_trader.py::test_run_live_ai_trade_batch_once_skips_after_action_limit tests/test_ai_trader.py::test_run_live_ai_trade_batch_once_refreshes_account_for_each_candidate -q
```

Expected: PASS.

### Task 3: CLI Command

**Files:**
- Modify: `src/binance_quant/cli.py`
- Test: `tests/test_cli.py`

- [ ] **Step 1: Write failing CLI tests**

Add tests for `live-ai-trade-batch-once` summary/table output and non-zero exit when any batch item has an execution failure status.

- [ ] **Step 2: Verify CLI tests fail**

Run:

```bash
python -m pytest tests/test_cli.py::test_live_ai_trade_batch_once_command_prints_summary_and_rows tests/test_cli.py::test_live_ai_trade_batch_once_command_exits_nonzero_for_execution_failure -q
```

Expected: FAIL because the command/imports do not exist.

- [ ] **Step 3: Implement CLI**

Import `run_live_ai_trade_batch_once`, add a batch exit-code helper, and add `@app.command("live-ai-trade-batch-once")` that prints summary fields and a Rich table with per-result rows.

- [ ] **Step 4: Verify CLI tests pass**

Run:

```bash
python -m pytest tests/test_cli.py::test_live_ai_trade_batch_once_command_prints_summary_and_rows tests/test_cli.py::test_live_ai_trade_batch_once_command_exits_nonzero_for_execution_failure -q
```

Expected: PASS.

### Task 4: Runner Script And Docs

**Files:**
- Modify: `scripts/run.ps1`
- Modify: `README.md`
- Test: `tests/test_run_script.py`

- [ ] **Step 1: Write failing runner/docs tests**

Add tests that require `live-ai-trade-batch-once` in the PowerShell `ValidateSet`, require a safety preflight before invoking `binance-quant live-ai-trade-batch-once`, and require README documentation for the command and `BINANCE_AI_TRADER_MAX_ACTIONS_PER_RUN=5`.

- [ ] **Step 2: Verify runner/docs tests fail**

Run:

```bash
python -m pytest tests/test_run_script.py::test_run_script_has_live_ai_trade_batch_once_action tests/test_run_script.py -q
```

Expected: FAIL because the action and README text do not exist.

- [ ] **Step 3: Implement runner/docs**

Add `"live-ai-trade-batch-once"` to the PowerShell `ValidateSet`, add a switch case mirroring `live-ai-trade-once` safety preflight, and update README Live AI Trader documentation.

- [ ] **Step 4: Verify runner/docs tests pass**

Run:

```bash
python -m pytest tests/test_run_script.py -q
```

Expected: PASS.

### Task 5: Final Verification

**Files:**
- All changed files.

- [ ] **Step 1: Run targeted tests**

Run:

```bash
python -m pytest tests/test_config.py tests/test_ai_trader.py tests/test_cli.py tests/test_run_script.py -q
```

Expected: PASS.

- [ ] **Step 2: Run full test suite**

Run:

```bash
python -m pytest
```

Expected: PASS.

- [ ] **Step 3: Inspect git diff**

Run:

```bash
git status --short
git diff --stat
git diff -- src/binance_quant/config.py src/binance_quant/ai_trader.py src/binance_quant/cli.py scripts/run.ps1 README.md tests/test_config.py tests/test_ai_trader.py tests/test_cli.py tests/test_run_script.py
```

Expected: only planned files changed, no unrelated edits.