ai-exchange/README.md

# AI ICT

AI ICT 交易辅助系统第一阶段工程实现。

当前项目已经具备从数据、结构、信号、执行、回测到报告的最小闭环，并提供轻量查询 API、HTTP 调试服务与一键编排入口。

See `docs/` for architecture, database, rule, and migration references.

Database connectivity defaults to a 5 second PostgreSQL connect timeout. Override with `DATABASE_CONNECT_TIMEOUT` when needed.
Set `MIGRATIONS_OUTPUT_JSON=1` when running `run_migrations.py` for a machine-readable migration summary.

## Current closed loop

当前主线可运行链路：

`OKX -> candles -> market_sessions -> swings -> dealing_ranges -> liquidity_pools -> sweep_events -> displacement_events -> MSS -> FVG -> bias_snapshots -> trade_signals -> trade_executions -> backtest_runs -> backtest_results -> reports`

## Training Case Engine milestone index

Training Case Engine is the external-facing product training module. The public milestone state is M1-M40, with current product maturity through M40.

Accepted milestone range: M1-M40, with current product maturity through M40.

Offline validation commands:

- `.venv/bin/python -m unittest discover -s tests/unit -p "test_*.py"`
- `.venv/bin/python scripts/run_offline_checks.py`

Accepted user-facing surfaces:

- Trading Workbench at `/`
- Training Console at `/training`
- public API routes
- offline public package import/export
- public error catalog
- public privacy contract coverage

- Acceptance and offline validation: M35 acceptance posture, Training Case acceptance manifest, focused milestone test suites, offline checks, and public validation.
- Public API and privacy contracts: API contract coverage, error contract coverage, and privacy contract coverage keep public routes audited while public responses scrub private solution material and internal solution details.
- Package smoke and offline registry: offline package smoke covers local import/export with public package, public export, and public output flows; broader offline checks register `training_case_package`.
- Dashboard and public docs privacy: trading workbench syntax validation is registered as `dashboard_js_syntax`, training console syntax validation is registered as `training_console_js_syntax`, and public docs privacy smoke coverage keeps Training content to public case fields only.
- Local Docker guard: single-set local Docker deployment uses the documented rebuild order and Docker smoke guard coverage for one active deployment set, one `ai-ict` container, and `healthy` status.

## Training public error catalog

- Training API validation failures are deterministic public validation errors: `400` with `invalid_json_body`, `400` with `missing_required_json_field:<field>`, `400` with `invalid_json_field:<field>`, `400` with `invalid_path_param:<field>`, or `400` with `invalid_limit_query_param:limit`.
- Missing Training cases return `404` with `not_found`.
- Masked unexpected Training API failures return `500` with `internal_server_error`; the public response masks raw internals, and responses do not echo raw internals.
- Package CLI public errors for invalid input paths and invalid output targets emit one-line JSON with `passed`, `input`, `output`, and `error`; stable public error codes include `input_file_not_found`, `input_path_is_directory`, `output_path_is_directory`, and `output_path_unwritable`.

Public API response examples:

- Malformed or non-object JSON body: `POST /training/attempts` -> HTTP `400`

```json
{"error": "invalid_json_body"}
```

- Missing required JSON field: `POST /training/attempts` with `{}` -> HTTP `400`

```json
{"error": "missing_required_json_field:case_id"}
```

- Invalid JSON field value: `POST /training/attempts` with text `case_id` -> HTTP `400`

```json
{"error": "invalid_json_field:case_id"}
```

- Invalid path identifier: `GET /training/cases/not-an-id` -> HTTP `400`

```json
{"error": "invalid_path_param:case_id"}
```

- Invalid list limit: `GET /training/cases?limit=not-a-number` -> HTTP `400`

```json
{"error": "invalid_limit_query_param:limit"}
```

- Missing case: `GET /training/cases/404` -> HTTP `404`

```json
{"error": "not_found"}
```

- Masked internal server error: any Training route -> HTTP `500`

```json
{"error": "internal_server_error"}
```

Package CLI public error examples:

- Missing input file:

```json
{"passed": false, "input": "missing_training_case_package.json", "output": "training_case_public_export.json", "error": "input_file_not_found"}
```

- Directory input path:

```json
{"passed": false, "input": "training_case_package_dir", "output": "training_case_public_export.json", "error": "input_path_is_directory"}
```

- Directory output target:

```json
{"passed": false, "input": "tests/fixtures/training_case_package_m6.json", "output": "training_case_public_export_dir", "error": "output_path_is_directory"}
```

## Local Docker deployment

Use the single-set local Docker deployment policy for local server deployment:

- Deploy from the deploy directory `/root/deploy/ai-ict`.
- Keep the compose project `ai-ict`, container `ai-ict`, and exactly one active deployment set.
- Keep one active `ai-ict` container; do not create a second local stack or a second `ai-ict` container.
- Before every local rebuild, stop stale services first, then start the same set:

```bash
cd /root/deploy/ai-ict
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml down --remove-orphans
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml up -d --build
```

- After the rebuild, verify the same one active set, one active `ai-ict` container, and Docker `healthy` status:

```bash
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml ps
test "$(docker ps --filter label=com.docker.compose.project=ai-ict --format '{{.Names}}' | wc -l | tr -d ' ')" = "1"
test "$(docker ps --filter name=^/ai-ict$ --format '{{.Names}}' | wc -l | tr -d ' ')" = "1"
test "$(docker inspect -f '{{.State.Health.Status}}' ai-ict)" = "healthy"
```

- Check the documented local demo readiness without starting containers; this offline check does not invoke Docker:

```bash
.venv/bin/python scripts/check_local_demo_readiness.py
```

## Trading Delivery Checklist

Use this locked trading delivery checklist before every market validation or deploy, so the trading module can be promoted without relying on chat memory.

must-run before every market validation or deploy:

```bash
.venv/bin/python -m unittest discover -s tests/unit -p "test_*.py"
.venv/bin/python scripts/run_offline_checks.py
.venv/bin/python scripts/check_local_demo_readiness.py
.venv/bin/python scripts/check_trading_delivery_readiness.py
```

Database gate:

```bash
READINESS_OUTPUT_JSON=1 .venv/bin/python scripts/run_database_readiness.py
HISTORICAL_REPAIR_OUTPUT_JSON=1 .venv/bin/python scripts/run_historical_compatibility_repair.py
.venv/bin/python scripts/run_historical_compatibility_repair.py --apply-safe-repairs
HISTORICAL_REPAIR_OUTPUT_JSON=1 .venv/bin/python scripts/run_historical_compatibility_repair.py
PIPELINE_OUTPUT_JSON=1 BACKTEST_REQUIRE_QUALITY_GATE=1 .venv/bin/python scripts/run_pipeline.py
```

Use `--apply-safe-repairs` only when the dry-run output shows safe candidates. After the second dry-run, manual review is still required for `needs_sweep_reference_migration` and `keep_version_history`, and `backtest_quality_gate.passed` must be `true` before promotion.

Deploy and health check:

```bash
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml down --remove-orphans
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml up -d --build
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml ps
test "$(docker ps --filter label=com.docker.compose.project=ai-ict --format '{{.Names}}' | wc -l | tr -d ' ')" = "1"
test "$(docker ps --filter name=^/ai-ict$ --format '{{.Names}}' | wc -l | tr -d ' ')" = "1"
test "$(docker inspect -f '{{.State.Health.Status}}' ai-ict)" = "healthy"
curl -fsS http://127.0.0.1:8000/health
curl -fsS "http://127.0.0.1:8000/trading/candidates?instrument_id=1&limit=1"
```

Post-deploy observe:

```bash
READINESS_OUTPUT_JSON=1 .venv/bin/python scripts/run_database_readiness.py
REPORTS_OUTPUT_JSON=1 .venv/bin/python scripts/run_reports.py
```

The paper execution boundary remains in force here: `run_pipeline.py` and the execution path are still paper-only, and any API `5xx`, Docker unhealthy state, or non-empty readiness reasons should stop promotion immediately.

For one-command rehearsal orchestration, use `scripts/run_trading_delivery_rehearsal.py`; it runs checklist drift validation, historical repair gating, readiness plus auto-backfill, guarded pipeline, optional deploy/health-check, and post-deploy observe in one scripted flow.

Rollback trigger:

```bash
git rev-parse HEAD
docker compose -p ai-ict -f /root/deploy/ai-ict/docker-compose.yml logs --tail=100 ai-ict
git worktree add /tmp/ai-ict-rollback <last-known-good-sha>
cd /tmp/ai-ict-rollback && ./scripts/deploy_server.exp
rm -rf /tmp/ai-ict-rollback
```

Record the current commit as the last-known-good SHA before deploy. If any gate above fails, capture logs first, then redeploy from the clean rollback worktree rather than mutating the active development checkout.

## Runtime utility scripts

- `python3 scripts/run_dev.py` - start the local development API server and minimal dashboard
- `python3 scripts/show_models.py` - list exported ORM model names
- `python3 scripts/check_db.py` - run a simple database connectivity check
- `python3 scripts/run_migrations.py` - apply SQL files in `migrations/` order
- `python3 scripts/run_okx_backfill.py` - fetch and write sample OKX candles
- `python3 scripts/run_session_generator.py` - generate market sessions
- `python3 scripts/run_swings.py` - rebuild swings
- `python3 scripts/run_ranges.py` - rebuild dealing ranges
- `python3 scripts/run_liquidity.py` - rebuild liquidity pools
- `python3 scripts/run_sweeps.py` - rebuild sweep events
- `python3 scripts/run_displacement.py` - rebuild displacement events
- `python3 scripts/run_mss.py` - rebuild MSS structure events
- `python3 scripts/run_fvg.py` - rebuild FVG zones
- `python3 scripts/run_trading_plans.py` - generate today's structured BTC/ETH trading plans before signal generation; active plans require a Draw and at least one Invalidation
- `python3 scripts/run_trade_plan_candidates.py` - watch the active trading plan for the first executable candidate model: OSOK/Daily Range context, Sweep, MSS, and FVG retrace; missing confirmations are reported instead of promoted to execution
- `python3 scripts/run_signals.py` - generate bias and signals with structural `target_plan` selection; TP1 prefers IRL and TP2 prefers ERL, and signals are skipped when traceable structural targets are missing
- `python3 scripts/run_execution.py` - run paper execution gating, require structural targets plus management rules for modeled signals, create an execution record, then auto-settle the latest execution for that signal
- `python3 scripts/run_execution_ticket.py` - generate a human-confirmation execution ticket, run Risk Governor before ticket creation and before confirmation, and then create either `paper` or `semi_auto` execution only after a valid confirmation step
- `python3 scripts/run_live_adapter.py` - exercise the live broker preparation layer for `submit`, `reconcile`, `cancel_all`, or `kill_switch`; every attempted live operation is audited and real submission stays blocked unless live trading is explicitly enabled and confirmed
- `python3 scripts/run_risk_governor.py` - run the independent market-state and risk governor pre-execution gate
- `python3 scripts/run_backtest.py` - run backtest as `plan_replay` by default, replay active-plan candidates from appearance to confirmation to entry/invalidation, and write target-source traceability plus management rules into result meta
- `python3 scripts/run_autonomous_cycle.py` - run the unattended cycle: offline checks, database probe, readiness checks, then guarded pipeline when the database is available; prints `Next actions` for the next unattended step
- `python3 scripts/run_database_readiness.py` - run read-only database readiness checks for connection, schema, seed data, and candle availability; prints `next_actions` and `action_plan` in JSON mode
- `.venv/bin/python scripts/run_trading_delivery_rehearsal.py` - run the P0 trading delivery rehearsal as one scripted flow: checklist drift check, historical repair decision, readiness/auto-backfill, guarded pipeline, deploy/health-check, and post-deploy observe
- `.venv/bin/python scripts/run_offline_checks.py` - run the broader offline check suite, including the M35 acceptance posture through the Training Case acceptance manifest for focused milestone test suites, the Training Case package smoke registered as `training_case_package`, trading delivery checklist drift guard registered as `trading_delivery_readiness`, trading workbench syntax validation as `dashboard_js_syntax`, training console syntax validation as `training_console_js_syntax`, and dashboard and public docs privacy smoke coverage; this public validation runs as offline checks without external services
- `.venv/bin/python scripts/check_trading_delivery_readiness.py` - verify `README.md` and `RUNBOOK.md` still expose the locked trading delivery checklist for preflight, deploy, observe, and rollback without relying on chat memory
- `.venv/bin/python scripts/run_training_case_package.py --help` - show the offline package smoke help for public package import/export behavior, public export/public output semantics, and stable public error codes for invalid input paths and invalid output targets
- `.venv/bin/python scripts/run_training_case_package.py --input tests/fixtures/training_case_package_m6.json --output /tmp/training_case_public_export.json` - run the Training Case offline package smoke, an import/export smoke with local files, and write public output as the public export in the public package shape; exported public JSON omits internal solution details
- `.venv/bin/python scripts/run_training_case_generator.py --help` - show the offline prototype generator help for read-only Training case draft generation from trading-derived seed events
- `.venv/bin/python scripts/run_training_case_generator.py --input tests/fixtures/training_case_generator_seed_v1.json --output /tmp/generated_training_case_drafts.json` - run the offline Training case generator prototype and write a public draft package without touching Training database tables
- `.venv/bin/python scripts/run_historical_compatibility_repair.py` - scan for older stored signal/FVG/MSS/liquidity compatibility issues in the connected database without applying changes
- `.venv/bin/python scripts/run_historical_compatibility_repair.py --apply-safe-repairs` - apply the safe historical compatibility repairs for signal invalidations, MSS/FVG meta backfills, and liquidity safe merges limited to unreferenced supersets plus exact duplicate rows with identical sweep events; `needs_sweep_reference_migration` and `keep_version_history` groups still require manual review
- `.venv/bin/python scripts/run_historical_compatibility_repair.py --apply-liquidity-reference-migrations` - apply executable liquidity reference migrations for exact duplicate pools with nonidentical sweep events; duplicate sweep timestamp conflicts are blocked instead of auto-merged
- `python3 scripts/run_migration_static_checks.py` - check migration order and required core schema without connecting to the database
- `python3 scripts/run_script_static_checks.py` - check automation scripts for unsafe ambient environment fallback patterns
- `python3 scripts/run_replay_file.py <candles.json|candles.jsonl|candles.csv>` - run offline no-lookahead candle replay without database access
- `python3 scripts/run_reports.py` - build sample reports from current services
- `python3 scripts/run_api_server.py` - start a lightweight HTTP API server on `127.0.0.1:8000`; `/` serves the trading workbench and `/training` serves the training console
- `python3 scripts/run_pipeline.py` - run the current end-to-end closed loop and print a structured summary

Optional report environment variables used by `run_reports.py`:

- `REPORTS_OUTPUT_JSON` - set to `1`, `true`, `yes`, or `on` for machine-readable sample report output

Optional utility JSON output variables:

- `CHECK_DB_OUTPUT_JSON`
- `CHECK_DB_CONNECTION_OUTPUT_JSON`
- `HISTORICAL_REPAIR_OUTPUT_JSON`
- `MIGRATION_CHECKS_OUTPUT_JSON`
- `SCRIPT_CHECKS_OUTPUT_JSON`
- `SHOW_MODELS_OUTPUT_JSON`
- `RISK_GOVERNOR_OUTPUT_JSON`
- `TRADE_PLAN_CANDIDATES_OUTPUT_JSON`
- `TRADING_JOURNAL_OUTPUT_JSON`
- `TRADING_PLANS_OUTPUT_JSON`
- `TRADING_REHEARSAL_OUTPUT_JSON`
- `LIVE_ADAPTER_OUTPUT_JSON`
- `BACKTEST_OUTPUT_JSON`
- `EXECUTION_TICKET_OUTPUT_JSON`

Optional structure script JSON output variables:

- `SESSION_GENERATOR_OUTPUT_JSON`
- `SWINGS_OUTPUT_JSON`
- `RANGES_OUTPUT_JSON`
- `LIQUIDITY_OUTPUT_JSON`
- `SWEEPS_OUTPUT_JSON`
- `DISPLACEMENT_OUTPUT_JSON`
- `MSS_OUTPUT_JSON`
- `FVG_OUTPUT_JSON`

Optional backtest cost environment variables used by `run_backtest.py` and `run_pipeline.py`:

- `BACKTEST_FEE_RATE`
- `BACKTEST_SLIPPAGE_RATE`
- `BACKTEST_FIXED_COST_R`

Optional replay-backed backtest mode variables used by `run_backtest.py` and `run_pipeline.py`:

- `BACKTEST_MODE` - supported values: `entry_then_outcome` or `replay_no_lookahead`
- `BACKTEST_REPLAY_LEFT_BARS`
- `BACKTEST_REPLAY_RIGHT_BARS`

Optional backtest automation gate used by `run_backtest.py` and `run_pipeline.py`:

- `BACKTEST_OUTPUT_JSON` - set to `1`, `true`, `yes`, or `on` for machine-readable `run_backtest.py` output
- `BACKTEST_REQUIRE_QUALITY_GATE` - set to `1`, `true`, `yes`, or `on` to exit with code `2` when the backtest quality gate fails
- `BACKTEST_MIN_TOTAL_SIGNALS`
- `BACKTEST_MIN_EXECUTED_SIGNALS`
- `BACKTEST_MIN_EXPECTANCY_R`
- `BACKTEST_MIN_PROFIT_FACTOR_R`
- `BACKTEST_MAX_DRAWDOWN_R`
- `BACKTEST_MAX_CONSECUTIVE_LOSSES`

Optional pipeline environment variables used by `run_pipeline.py`:

- `PIPELINE_OUTPUT_JSON` - set to `1`, `true`, `yes`, or `on` for machine-readable pipeline error output

Optional replay environment variables used by `run_replay_file.py`:

- `OFFLINE_REPLAY_FILE` - optional candle file path used by `run_offline_checks.py` to include replay validation
- `OFFLINE_CHECKS_OUTPUT_JSON` - set to `1`, `true`, `yes`, or `on` for machine-readable offline check summary output
- `REPLAY_LEFT_BARS`
- `REPLAY_RIGHT_BARS`
- `REPLAY_MIN_CANDLES`
- `REPLAY_MIN_SWINGS`
- `REPLAY_MAX_GAP_MINUTES`
- `REPLAY_OUTPUT_JSON` - set to `1`, `true`, `yes`, or `on` for machine-readable replay summary output

Example offline replay gate:

```bash
OFFLINE_REPLAY_FILE=tests/fixtures/offline_replay_sample.jsonl \
REPLAY_LEFT_BARS=1 REPLAY_RIGHT_BARS=1 \
REPLAY_MIN_CANDLES=5 REPLAY_MIN_SWINGS=2 \
.venv/bin/python scripts/run_offline_checks.py
```

Optional OKX backfill environment variables used by `run_okx_backfill.py`:

- `OKX_BACKFILL_SYMBOL` - defaults to `BTC-USDT`
- `OKX_BACKFILL_INST_ID` - defaults to `<symbol>-SWAP`
- `OKX_BACKFILL_PAGES` - defaults to `20`
- `OKX_BACKFILL_LIMIT` - defaults to `100`
- `OKX_BACKFILL_TIMEFRAMES` - defaults to `1m,5m,15m`
- `OKX_BACKFILL_OUTPUT_JSON` - emit a machine-readable backfill summary

Optional autonomous cycle environment variables used by `run_autonomous_cycle.py`:

- `AUTONOMOUS_OUTPUT_JSON` - emit a machine-readable cycle summary
- `AUTONOMOUS_REQUIRE_DB` - return code `2` when the database is unavailable
- `AUTONOMOUS_RUN_PIPELINE` - set to `0` to stop after a successful database probe
- `AUTONOMOUS_MAX_DB_PROBES` - number of database probe attempts before stopping
- `AUTONOMOUS_PROBE_INTERVAL_SECONDS` - sleep interval between database probe attempts
- `AUTONOMOUS_REQUIRE_SCHEMA` - enabled by default; set to `0` to skip core table readiness checks before the guarded pipeline
- `AUTONOMOUS_APPLY_MIGRATIONS` - enabled by default; when schema is not ready, run migrations, recheck schema, then continue
- `AUTONOMOUS_REQUIRE_DATA_READINESS` - enabled by default; set to `0` to skip read-only seed/candle readiness before the guarded pipeline
- `AUTONOMOUS_BACKFILL_CANDLES` - enabled by default; when readiness only lacks candles, run OKX backfill, recheck readiness, then continue
- The guarded pipeline step defaults `BACKTEST_REQUIRE_QUALITY_GATE=1` and `PIPELINE_OUTPUT_JSON=1` unless explicitly overridden

Current autonomous modes emit machine-readable `next_actions` and `action_plan`, including:

- `waiting_for_database` -> `wait_for_database_recovery`
- `database_schema_not_ready` -> `run_migrations_before_pipeline`
- `migration_failed` -> `inspect_migration_output_and_schema`
- `database_readiness_failed` -> the readiness script's own next action, such as `run_okx_backfill_or_load_replay_sample`
- `backfill_failed` -> `inspect_backfill_output_and_data_readiness`
- `pipeline_failed` -> `inspect_pipeline_output_and_quality_gates`

Each `action_plan` item includes the action name, suggested command, description, and `requires_database`.

Optional database readiness environment variables used by `run_database_readiness.py`:

- `READINESS_OUTPUT_JSON`
- `READINESS_REQUIRED_VENUES`
- `READINESS_REQUIRED_INSTRUMENTS`
- `READINESS_CANDLE_INSTRUMENT_ID`
- `READINESS_CANDLE_TIMEFRAME`
- `READINESS_MIN_CANDLES` - defaults to `50`
- `READINESS_MIN_CANDLE_SPAN_MINUTES` - defaults to `60`
- `READINESS_MAX_CANDLE_AGE_MINUTES` - defaults to `240`

Optional account risk environment variables used by `run_execution.py` and `run_pipeline.py`:

- `EXECUTION_OUTPUT_JSON` - set to `1`, `true`, `yes`, or `on` for machine-readable `run_execution.py` output
- `EXECUTION_SETTLEMENT_OUTPUT_JSON` - set to `1`, `true`, `yes`, or `on` for machine-readable `run_execution_settlement.py` output
- `EXECUTION_KILL_SWITCH`
- `EXECUTION_DAILY_PNL_PCT`
- `EXECUTION_CONSECUTIVE_LOSSES`
- `EXECUTION_OPEN_POSITIONS`
- `EXECUTION_SAME_SIDE_OPEN_POSITIONS`
- `EXECUTION_MAX_DAILY_LOSS_PCT`
- `EXECUTION_MAX_CONSECUTIVE_LOSSES`
- `EXECUTION_MAX_OPEN_POSITIONS`
- `EXECUTION_MAX_SAME_SIDE_POSITIONS`

Optional market-state and risk governor environment variables used by `run_risk_governor.py`:

- `RISK_GOVERNOR_OUTPUT_JSON`
- `RISK_INSTRUMENT_ID`
- `RISK_TIMEFRAME`
- `RISK_EXECUTION_MODE`
- `MARKET_STATE_MAX_CANDLE_AGE_SECONDS`
- `NEWS_WINDOW_ACTIVE`
- `NEWS_WINDOW_ID`
- `NEWS_WINDOW_MINUTES_BEFORE`
- `NEWS_WINDOW_MINUTES_AFTER`
- `OPENING_VOLATILITY_GUARD_MINUTES`
- `BLOCK_OPENING_VOLATILITY`

Optional signal quality environment variables used by `run_signals.py` and `run_pipeline.py`:

- `SIGNALS_OUTPUT_JSON` - set to `1`, `true`, `yes`, or `on` for machine-readable `run_signals.py` output
- `SIGNAL_EVIDENCE_MODE` - `strict` by default, or `minimal` to allow the older reduced evidence set

Optional trading plan environment variables used by `run_trading_plans.py`:

- `TRADING_PLANS_OUTPUT_JSON` - set to `1`, `true`, `yes`, or `on` for machine-readable plan output
- `TRADING_PLAN_SYMBOLS` - comma-separated symbols; defaults to `BTC-USDT,ETH-USDT`
- `TRADING_PLAN_BIAS_TIMEFRAME`
- `TRADING_PLAN_SETUP_TIMEFRAME`
- `TRADING_PLAN_TRIGGER_TIMEFRAME`

Optional backtest replay environment variables used by `run_backtest.py`:

- `BACKTEST_SUBJECT_TYPE` - defaults to `plan_replay`; use `signal` only when you intentionally want the legacy signal-only backtest
- `BACKTEST_TRADING_PLAN_ID` - optional plan scope for replay
- `BACKTEST_CANDIDATE_MODEL_CODE` - optional candidate model filter such as `OSOK_DAILY_RANGE_SWEEP_MSS_FVG_RETRACE`

Optional trade plan candidate environment variables used by `run_trade_plan_candidates.py`:

- `TRADE_PLAN_CANDIDATES_OUTPUT_JSON` - set to `1`, `true`, `yes`, or `on` for machine-readable candidate output
- `TRADE_PLAN_CANDIDATE_SYMBOLS` - comma-separated symbols; defaults to `BTC-USDT,ETH-USDT`
- `TRADE_PLAN_CANDIDATE_SETUP_TIMEFRAME`
- `TRADE_PLAN_CANDIDATE_TRIGGER_TIMEFRAME`

## Lightweight API helpers

The `src/api/` package exposes internal query helpers and HTTP routes for:

- `GET /health`
- `GET /candles?instrument_id=1&timeframe=1m&limit=100`
- `GET /sessions?instrument_id=1&limit=20`
- `GET /trading-plans?instrument_id=1&limit=20`
- `GET /trade-plan-candidates?instrument_id=1&limit=20`
- `GET /signals?instrument_id=1&limit=20`
- `GET /executions?instrument_id=1&limit=20`
- `GET /execution-tickets?instrument_id=1&limit=20`
- `GET /live-operation-audits?execution_ticket_id=1&limit=20`
- `GET /backtests?instrument_id=1&limit=10`

Open `/` in the browser for the minimal dashboard, which now includes health, candles, signals, sessions, executions, and backtests.

## Validation

Unit tests:

- `python3 -m unittest discover -s tests/unit -p "test_*.py"`