q.bt Roadmap

Only open work is listed here. Completed items are removed.

Backend boundaries

q.bt currently provides native LEAN result reporting and an optional Lean CLI adapter. The longer-term design exposes a common research-facing result contract over two independent execution backends:

1. a QRT-owned in-process event kernel shared with q.gym;
2. an optional adapter that orchestrates the standalone Lean CLI and LEAN engine.

The backends may normalize summaries and trade logs, but they must not pretend to have identical execution semantics. Every result records its backend and backend-specific configuration. LEAN remains authoritative for its event loop, subscriptions, orders, fills, fees, buying power, settlement, portfolio state, native result JSON, and Report Creator output.

In-process QRT backend

• Implement an event-driven execution kernel shared by batch backtests and q.gym without depending on Lean CLI or Docker.

• Add q.bt.run(signal, prices, ...) for canonical QRT signals and OHLCV data. Define timing explicitly: signal availability, order submission, execution bar, mark-to-market timestamp, and prevention of look-ahead.

• Define pluggable transaction-cost, spread, slippage, order-sizing, fill, and position-limit interfaces. Default models should be simple and explicit, never silently market-specific.

• Emit the canonical QRT trade-log schema used by q.stats and q.plot, plus equity, cash, exposure, turnover, and rejected-order series.

• Keep the in-process engine useful when Lean CLI is not installed. LEAN integration must not become a dependency of q.bt.run.

LEAN adapter API

• Extend preflight validation beyond the implemented workspace files, writable output directory, and Docker access to cover CLI compatibility, project language, configured data roots, and custom-market prerequisites.

• Extend the immutable, JSON-serializable run specification with typed project parameter schemas, source/config hashes, and explicit data-root identity.

• Support an explicit engine image tag or digest. update_image=False should map to Lean CLI’s no-update behavior for backtests; a digest should be recorded after Docker resolves the image.

• Keep custom market name/ID and data serialization in q.data.lean. q.bt.lean may validate those settings and inject algorithm parameters, but must not maintain a second SID or file-format implementation.

Process lifecycle

• Parse stable progress and diagnostic events from the implemented incremental stdout/stderr capture while retaining the raw streams.

• Cancellation must terminate the CLI process and its run-specific Docker container without killing unrelated LEAN or Docker workloads. Record whether shutdown was graceful or forced.

• Add stable typed diagnostics for interactive authentication and CLI capability failures alongside the implemented Docker/workspace validation. Never request API keys, tokens, passwords, or passphrases through ordinary function parameters that are persisted in run manifests.

• Add an awaitable orchestration API alongside the implemented synchronous wait() interface without tying the core API to notebooks or an event loop owned by the caller.

Result and artifact model

• Parse summary JSON, engine and algorithm logs, order events, data-request reports, and the generated code snapshot into structured views attached to the existing LeanBacktestResult.

• Preserve every native artifact path and checksum. Parsed QRT objects are derived views and must never replace or rewrite the source files.

• Normalize run metadata, statistics, runtime statistics, charts/series, orders, order events, holdings, closed trades, parameters, and errors while retaining unknown fields for forward compatibility.

• Convert LEAN closed trades/order events to QRT’s canonical trade log with a documented mapping. Preserve the original LEAN identifiers and expose conversion warnings when partial fills, assignments, multi-leg orders, or currency conversions cannot be represented losslessly.

• Distinguish process success from research success. A zero CLI exit code can still accompany failed data requests, algorithm ERROR:: messages, invalid orders, unfilled final-session orders, or analyzer failures.

• Add structured diagnostics with stable codes and severities for missing data, custom-market failures, model rejection, Docker problems, result parse drift, and report failures. Retain raw matching log lines as evidence.

• Expose charts and tabular results in backend-neutral forms consumable by q.plot, but do not discard backend-specific chart metadata or precision.

Reports

• Add backend-neutral adapters beyond LEAN result JSON while retaining the native q.bt.BacktestReport contract.

• Add optional PDF export, custom HTML themes, and report-section selection to the native QRT reporter.

• Normalize partial fills, assignments, multi-leg orders, and currency conversions with explicit conversion warnings.

• Wrap lean report with exact result-file selection. Never pass a result directory or infer an arbitrary JSON when several candidates exist.

• Support HTML and PDF destinations, strategy metadata, custom templates, overwrite policy, and local image selection while reflecting the actual Lean CLI options (lean report has --update, not --no-update).

• Detect custom-market SIDs before invoking Report Creator. If compatibility conversion is required, write a derived copy under a separate artifact path and retain a manifest of every transformed field.

• Never mutate the original backtest JSON. Report compatibility should be a pure transformation from source result to derived result plus an audit record.

• Make order omission/aliasing explicit when working around upstream Report replay limitations. Surface which report sections lose reconstruction input, such as asset allocation, while preserving closed-trade statistics and charts.

• Version compatibility transforms by LEAN engine and CLI version so a workaround is not applied after upstream behavior changes.

Reproducibility and provenance

• Store a run manifest containing at least:

  QRT version and adapter schema version
  workspace and algorithm paths
  algorithm source and project-config hashes
  LEAN CLI version
  Docker image tag and digest
  lean.json hash with secrets redacted
  parameters and data-root identity
  q.data.lean generation manifest, when available
  start/end timestamps, host platform, and exit state
  result/log/artifact paths and checksums

• Add result.reproduce() or an exported run specification that checks missing inputs and version drift before launching. Reproduction should not silently update the engine image or reference databases.

• Integrate with q.experiment as an optional artifact/lineage sink while keeping local execution usable without an experiment backend.

• Define retention and cleanup separately from execution. Cleanup must be scoped to one run manifest and never delete shared market data or Docker images by default.

Packaging and compatibility

• Keep Lean CLI/Docker support optional. Importing qrt or q.bt must work when neither is installed; invoking q.bt.lean should produce actionable dependency diagnostics.

• Detect CLI capability/version rather than assuming flags. Maintain a small compatibility matrix for supported CLI and engine versions.

• Avoid importing QuantConnect algorithm classes into QRT’s public result or configuration models. Serialized boundaries should remain plain Python, pandas, and path-like objects.

Testing and acceptance criteria

• Extend the existing command, path, state, result-selection, and native report unit tests with manifest redaction, structured log parsing, and compatibility transforms.

• Use fake subprocesses for cancellation, timeout, partial output, malformed JSON, nonzero exit, and successful-process/failed-research combinations.

• Run Docker integration tests only in an opt-in environment with pinned CLI and image versions.

• Use lean/demo-generated-data as the golden custom-market workflow. The direct-data, universe, and SMA runs must preserve their verification markers, expected data-request counts, orders, and statistics within documented tolerances.

• Verify report generation for an ordinary built-in market and the custom Sweden compatibility path. Assert that source result hashes are unchanged.

• Demonstrate concurrent runs, deterministic artifact association, graceful cancellation, and reproduction from a saved manifest.

Delivery sequence

1. Add manifests, hashes, Docker image identity, and structured diagnostics to the implemented run specification and lifecycle.
2. Parse auxiliary artifacts and produce canonical QRT trade logs.
3. Add awaitable orchestration and run-container-aware cancellation.
4. Add safe Report Creator orchestration and versioned compatibility copies.
5. Integrate q.data.lean manifests and optional q.experiment tracking.
6. Stabilize the public API after pinned Sweden and built-in-market integration suites pass.