start_backtest

Start a real OctoBot backtest run in the background and return immediately.

Not confirm-gated (ADR-0003): starts a simulation, never touches live trading or destroys data. Two mutually exclusive modes (all other parameters are mode-specific; unused ones for the chosen mode are ignored):

• mode="data_files" -> OctoBot's start_backtesting action [V]. Requires files (a non-empty list of exact data file names -- there is currently no MCP tool exposing what's available; the agent must already know a valid name, e.g. from OctoBot's own /backtesting page). start_timestamp/end_timestamp are epoch milliseconds (confirmed against source: _start_backtesting divides by 1000 before use), matching this project's convention elsewhere. run_on_common_part_only defaults to True (OctoBot's own default when omitted).

• mode="current_bot_data" -> OctoBot's start_backtesting_with_current_bot_data action [V]. Every field is technically optional at the HTTP layer (confirmed against source), but exchange_id is effectively required unless data_source names an explicit data file: if data_source is omitted or None, OctoBot defaults it to "current_bot_data" (use a live snapshot of the bot's own current exchange data), which requires a valid exchange_id -- omitting exchange_id in that case fails with a generic BacktestStartFailedError, not MissingExchangeIdError (that error is only raised for an actually-provided-but-unrecognized id; see this module's docstring, "Open question #6"). exchange_id is the same value get_exchange_details returns as its exchange_id field. exchange_type accepts None, "use_current_profile", "spot", "inverse_perpetual", "linear_perpetual", or "margin" (any other value raises inside OctoBot, surfaced as BacktestStartFailedError).

source (both modes) is an optional caller-supplied override for OctoBot's own per-run source identifier; if omitted (the expected case), a fresh UUID is generated and stored as the job's octobot_run_source, then reused automatically for the later get_job_result report fetch -- the caller never needs to manage this value.

Output: {"job_id": str, "state": "queued"} -- always "queued" immediately after this call (the background watcher has not yet had a chance to run at all: asyncio.create_task schedules it, it does not run any of it synchronously). Poll get_job_status(job_id) to observe the transition to "running" and then progress_percent advancing; call get_job_result(job_id) once state == "completed".

Progress notifications (milestone 11, ADR-0002 decision point 3): if this call's MCP request carries a progressToken, the watcher also opportunistically emits an MCP progress notification (progress/total on the same 0-100 scale as progress_percent) each time progress_percent changes -- entirely optional, additive, and never a substitute for polling: get_job_status behaves identically whether or not a token was ever supplied. See octobot_mcp.tools.backtesting's own module-level "Milestone 11" comment block for exactly how this is implemented.

Errors: BacktestStartFailedError for an unknown mode, a missing required field for the chosen mode, or any other start failure; MissingExchangeIdError specifically for current_bot_data mode's confirmed exception. Both are raised from the background watcher (not this function) and surface as the job's errors/state="failed" via get_job_status -- start_backtest itself only raises synchronously for input validation caught before any job is created (unknown mode, missing files), so a bad call never leaves a dangling queued job behind.