okx-codex-trader/docs/superpowers/plans/2026-04-17-multi-strategy-sampled-report-architecture.md

Multi-Strategy Sampled Report Architecture 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: Extract one shared sampled-report shell, migrate BBMR and BBSB onto it without behavior change, and add three new sampled-report strategies with explicit CLI parameters.

Architecture: Keep each strategy’s segment loop local to its own module. Extract only the duplicated sampled-report shell into one shared module that owns sampling, aggregate metrics, plotting, HTML rendering, and file writing. Each new strategy then adds only its own segment runner, thin wrapper, tests, and explicit CLI flags.

Tech Stack: Python 3.11+, pandas, bokeh, existing OKX public candle client, existing CLI test harness, plain HTML/CSS/JS

---

File Structure

• Create: /home/lxy/okx-codex-trader/okx_codex_trader/sampled_report.py
• Modify: /home/lxy/okx-codex-trader/okx_codex_trader/bbmr_report.py
• Modify: /home/lxy/okx-codex-trader/okx_codex_trader/bbsb_report.py
• Create: /home/lxy/okx-codex-trader/okx_codex_trader/donchian_report.py
• Create: /home/lxy/okx-codex-trader/okx_codex_trader/rsi2_report.py
• Create: /home/lxy/okx-codex-trader/okx_codex_trader/ema_pullback_report.py
• Modify: /home/lxy/okx-codex-trader/okx_codex_trader/cli.py
• Create: /home/lxy/okx-codex-trader/tests/test_sampled_report.py
• Modify: /home/lxy/okx-codex-trader/tests/test_bbmr_report.py
• Modify: /home/lxy/okx-codex-trader/tests/test_bbsb_report.py
• Modify: /home/lxy/okx-codex-trader/tests/test_cli.py
• Create: /home/lxy/okx-codex-trader/tests/test_donchian_report.py
• Create: /home/lxy/okx-codex-trader/tests/test_rsi2_report.py
• Create: /home/lxy/okx-codex-trader/tests/test_ema_pullback_report.py

Task 1: Shared Sampled Report Shell

Files:

• Create: /home/lxy/okx-codex-trader/tests/test_sampled_report.py

• Create: /home/lxy/okx-codex-trader/okx_codex_trader/sampled_report.py

• [ ] Step 1: Write the failing shared-shell tests

def test_sample_segments_is_deterministic():
    ...


def test_sample_segments_rejects_invalid_sampling_result():
    ...


def test_generate_sampled_report_aggregates_metrics():
    ...


def test_render_sampled_report_includes_strategy_params():
    ...


def test_build_segment_plot_embeds_entry_exit_markers():
    ...

• Step 2: Run test to verify it fails

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_sampled_report.py -q Expected: FAIL on missing shared-shell behavior, not import/setup failure

• Step 3: Write minimal shared shell

@dataclass(frozen=True)
class SampledSegment: ...


@dataclass(frozen=True)
class SegmentResult: ...

def sample_segments(...): ...
def trade_equity(...): ...
def mark_to_market(...): ...
def build_segment_plot(...): ...
def render_sampled_report(...): ...
def generate_sampled_report(...): ...

• Step 4: Run test to verify it passes

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_sampled_report.py -q Expected: PASS

Task 2: Migrate BBMR To Shared Shell

Files:

• Modify: /home/lxy/okx-codex-trader/tests/test_bbmr_report.py

• Modify: /home/lxy/okx-codex-trader/okx_codex_trader/bbmr_report.py

• [ ] Step 1: Add one failing wrapper-contract test

def test_generate_bbmr_sampled_report_uses_shared_shell(monkeypatch, tmp_path):
    ...

• Step 2: Run BBMR tests to verify red

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_bbmr_report.py -q Expected: FAIL on the new wrapper contract test while current behavior tests still define the expected contract

• Step 3: Replace local BBMR shell with a thin wrapper

def generate_bbmr_sampled_report(...):
    return generate_sampled_report(
        ...,
        strategy_label="BBMR",
        strategy_description="...",
        strategy_params={...},
        run_segment=run_bbmr_segment,
    )

• Step 4: Run BBMR tests to verify green

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_bbmr_report.py -q Expected: PASS

Task 3: Migrate BBSB To Shared Shell

Files:

• Modify: /home/lxy/okx-codex-trader/tests/test_bbsb_report.py

• Modify: /home/lxy/okx-codex-trader/okx_codex_trader/bbsb_report.py

• [ ] Step 1: Add one failing wrapper-contract test

def test_generate_bbsb_sampled_report_uses_shared_shell(monkeypatch, tmp_path):
    ...

• Step 2: Run BBSB tests to verify red

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_bbsb_report.py -q Expected: FAIL on the new wrapper contract test while current behavior tests still define the expected contract

• Step 3: Replace local BBSB shell with a thin wrapper

def generate_bbsb_sampled_report(...):
    return generate_sampled_report(
        ...,
        strategy_label="BBSB",
        strategy_description="...",
        strategy_params={...},
        run_segment=run_bbsb_segment,
    )

• Step 4: Run BBSB tests to verify green

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_bbsb_report.py -q Expected: PASS

Task 4: Preservation Checks For Migrated Commands

Files:

• Modify: /home/lxy/okx-codex-trader/tests/test_cli.py

• [ ] Step 1: Add explicit unchanged-summary assertions

def test_backtest_bbmr_report_summary_shape_is_unchanged(): ...
def test_backtest_bbsb_report_summary_shape_is_unchanged(): ...

• Step 2: Run tests to verify they pass

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_cli.py -k "bbmr or bbsb" -q Expected: PASS

Task 5: Donchian Strategy And CLI

Files:

• Create: /home/lxy/okx-codex-trader/tests/test_donchian_report.py
• Create: /home/lxy/okx-codex-trader/okx_codex_trader/donchian_report.py
• Modify: /home/lxy/okx-codex-trader/tests/test_cli.py

• Modify: /home/lxy/okx-codex-trader/okx_codex_trader/cli.py

• [ ] Step 1: Write the failing Donchian strategy and CLI tests

def test_run_donchian_segment_produces_long_trade(): ...
def test_run_donchian_segment_produces_short_trade(): ...
def test_run_donchian_segment_stop_loss_takes_precedence(): ...
def test_run_donchian_segment_does_not_generate_entry_from_final_bar(): ...
def test_run_donchian_segment_marks_open_position_to_market(): ...
def test_backtest_donchian_report_dispatches_generator(): ...

• Step 2: Run tests to verify red

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_donchian_report.py tests/test_cli.py -k donchian -q Expected: FAIL on missing Donchian behavior and missing CLI dispatch, not import/setup failure

• Step 3: Write minimal Donchian module and CLI entry

@dataclass(frozen=True)
class DonchianConfig:
    entry_window: int = 20
    exit_window: int = 10
    stop_loss_pct: float = 0.01

def run_donchian_segment(...): ...
def generate_donchian_sampled_report(...): ...
def _add_sampled_report_parser(...): ...
SAMPLED_REPORT_COMMANDS = {
    "backtest-donchian-report": {
        "generator": generate_donchian_sampled_report,
        "parser_args": (...),
        "strategy_params": (...),
    },
}

• Step 4: Run tests to verify green

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_donchian_report.py tests/test_cli.py -k donchian -q Expected: PASS

Task 6: RSI2 Strategy And CLI

Files:

• Create: /home/lxy/okx-codex-trader/tests/test_rsi2_report.py
• Create: /home/lxy/okx-codex-trader/okx_codex_trader/rsi2_report.py
• Modify: /home/lxy/okx-codex-trader/tests/test_cli.py

• Modify: /home/lxy/okx-codex-trader/okx_codex_trader/cli.py

• [ ] Step 1: Write the failing RSI2 strategy and CLI tests

def test_run_rsi2_segment_produces_long_trade(): ...
def test_run_rsi2_segment_produces_short_trade(): ...
def test_run_rsi2_segment_exit_priority_is_correct(): ...
def test_run_rsi2_segment_does_not_generate_entry_from_final_bar(): ...
def test_run_rsi2_segment_marks_open_position_to_market(): ...
def test_backtest_rsi2_report_dispatches_generator(): ...

• Step 2: Run tests to verify red

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_rsi2_report.py tests/test_cli.py -k rsi2 -q Expected: FAIL on missing RSI2 behavior and missing CLI dispatch, not import/setup failure

• Step 3: Write minimal RSI2 module and CLI entry

@dataclass(frozen=True)
class RSI2Config:
    trend_sma: int = 50
    rsi_length: int = 2
    rsi_long_threshold: float = 10.0
    rsi_short_threshold: float = 90.0
    exit_rsi: float = 50.0

def run_rsi2_segment(...): ...
def generate_rsi2_sampled_report(...): ...

• Step 4: Run tests to verify green

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_rsi2_report.py tests/test_cli.py -k rsi2 -q Expected: PASS

Task 7: EMA Pullback Strategy And CLI

Files:

• Create: /home/lxy/okx-codex-trader/tests/test_ema_pullback_report.py
• Create: /home/lxy/okx-codex-trader/okx_codex_trader/ema_pullback_report.py
• Modify: /home/lxy/okx-codex-trader/tests/test_cli.py

• Modify: /home/lxy/okx-codex-trader/okx_codex_trader/cli.py

• [ ] Step 1: Write the failing EMA pullback strategy and CLI tests

def test_run_ema_pullback_segment_produces_long_trade(): ...
def test_run_ema_pullback_segment_produces_short_trade(): ...
def test_run_ema_pullback_segment_stop_priority_is_correct(): ...
def test_run_ema_pullback_segment_does_not_generate_entry_from_final_bar(): ...
def test_run_ema_pullback_segment_marks_open_position_to_market(): ...
def test_backtest_ema_pullback_report_dispatches_generator(): ...

• Step 2: Run tests to verify red

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_ema_pullback_report.py tests/test_cli.py -k ema_pullback -q Expected: FAIL on missing EMA pullback behavior and missing CLI dispatch, not import/setup failure

• Step 3: Write minimal EMA pullback module and CLI entry

@dataclass(frozen=True)
class EMAPullbackConfig:
    fast_ema: int = 20
    slow_ema: int = 50
    stop_buffer_pct: float = 0.005

def run_ema_pullback_segment(...): ...
def generate_ema_pullback_sampled_report(...): ...

• Step 4: Run tests to verify green

Run: cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_ema_pullback_report.py tests/test_cli.py -k ema_pullback -q Expected: PASS

Task 8: Full Verification

Files:

• None

• [ ] Step 1: Run focused and full verification

Run:

cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_sampled_report.py -q
cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_bbmr_report.py tests/test_bbsb_report.py -q
cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_donchian_report.py tests/test_rsi2_report.py tests/test_ema_pullback_report.py -q
cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest tests/test_cli.py -k "bbmr or bbsb or donchian or rsi2 or ema_pullback" -q
cd /home/lxy/okx-codex-trader && .venv/bin/python -m pytest -q

Expected:

• all new focused suites pass
• migrated BBMR/BBSB suites stay green

• full suite stays green

• [ ] Step 2: Generate one real report per new strategy

Run:

cd /home/lxy/okx-codex-trader && .venv/bin/python -m okx_codex_trader.cli backtest-donchian-report --symbol BTC-USDT-SWAP --bar 3m --history-limit 5000 --leverage 2 --segments 8 --window-size 300 --output-file donchian-sampled-report.html
cd /home/lxy/okx-codex-trader && .venv/bin/python -m okx_codex_trader.cli backtest-rsi2-report --symbol BTC-USDT-SWAP --bar 3m --history-limit 5000 --leverage 2 --segments 8 --window-size 300 --output-file rsi2-sampled-report.html
cd /home/lxy/okx-codex-trader && .venv/bin/python -m okx_codex_trader.cli backtest-ema-pullback-report --symbol BTC-USDT-SWAP --bar 3m --history-limit 5000 --leverage 2 --segments 8 --window-size 300 --output-file ema-pullback-sampled-report.html

Expected:

• each command exits 0
• each report file exists
• each JSON summary prints report_file, segment_count, window_size, aggregate_trade_count, average_return