Documentation
Skip to content

Backtest to Live

ml4t-backtest and ml4t-live implement lifecycle version 1 from ml4t-specs. A strategy is portable when its callback trace, information boundary, canonical intent, execution policy, and position-rule state satisfy that contract in both runtimes.

What Stays The Same

  • the Strategy subclass when it uses only portable callbacks and broker operations
  • on_start, causal on_prepare, on_data, and on_end callback semantics
  • CanonicalTargetIntent decisions and versioned position-rule definitions

What Changes

Backtest concept Live equivalent
Engine LiveEngine
historical data feed broker-connected or replay DataFeedProtocol
simulated broker/execution async broker wrapped by SafeBroker
backtest risk assumptions explicit LiveRiskConfig limits
recorded execution policy venue capabilities and live execution policy
offline validation shadow mode, paper trading, staged live rollout

Migration Pattern

  1. Validate the strategy in ml4t-backtest against lifecycle version 1.
  2. Compare callback and canonical-intent traces on one causal tape.
  3. Pick the broker and feed combination that matches the required capabilities.
  4. Wrap the broker in SafeBroker and start with execution_mode="shadow".
  5. Promote to paper trading only after signal, intent, inventory, and order-flow checks pass.
  6. Go live only after separate operational qualification with conservative limits.

Minimal Port

from ml4t.live import LiveEngine, LiveRiskConfig, SafeBroker

safe_broker = SafeBroker(raw_broker, LiveRiskConfig(execution_mode="shadow"))
engine = LiveEngine(strategy, safe_broker, live_feed)
await engine.connect()
await engine.run()

The strategy class may remain the same. Verify callback traces and canonical intents on a shared causal tape. Equal signals alone are insufficient because two runtimes can observe different phases, construct different orders, or apply different position rules after producing the same signal label.

Shared calendar declarations

The current source targets Backtest 0.2.0 and Specs 0.2.1; lifecycle version remains 1. Published Live 0.1.3 requires the older 0.1.x cohort and cannot be installed with these 0.2.x packages. Do not override its dependency resolver to combine them. The runtime integration in this source requires its own qualified release.

Pass the same FeedSpec to the historical feed and the Live engine:

from ml4t.backtest import BacktestConfig, DataFeed, Engine
from ml4t.backtest.config import DataFrequency
from ml4t.specs import FeedSpec, TimestampSemantics

spec = FeedSpec(
    time_contract_version=2,
    calendar="CME_Equity",
    timezone="UTC",
    data_frequency=DataFrequency.HOURLY,
    timestamp_semantics=TimestampSemantics.EVENT_TIME,
)
config = BacktestConfig(enforce_sessions=True)
historical_feed = DataFeed(prices_df=prices, feed_spec=spec)
backtest = Engine(historical_feed, historical_strategy, config)
live = LiveEngine(
    live_strategy, safe_broker, live_feed, strategy_config=config, feed_spec=spec
)

Calendar selection uses an explicit LiveEngine(calendar=...) override, then the shared config/feed resolution, then NYSE. An omitted declaration inherits; explicit calendar=None disables exchange session handling and keeps row-based operation. calendar="24/7" names a continuous calendar and retains calendar session labels. These are distinct declarations in temporal contract version 2. The engine passes a resolved copy to on_prepare without mutating the caller's config or metadata.

Session health and scheduled targets use authoritative exchange sessions, including holidays, early closes, lunch breaks and overnight session labels. A Sunday CME event can belong to Monday's session before UTC midnight. enforce_sessions=True filters strategy events using the same calendar interval convention as Backtest: event-time/left labels include the open and exclude the close; bar-close/right labels exclude the open and include the close. Session-label timestamps select session dates rather than intraday instants. The default remains enforce_sessions=False.

Provider events must still carry aware UTC timestamps. For explicit status-clock arguments, naive timestamps use the declared feed timezone; ambiguous or nonexistent DST times require an aware argument. Unknown calendars fail during construction, before broker connection or feed startup.

The installed comparison below executes the causal strategy, CME overnight target, early-close filter and calendar-health regressions with the actual installed Backtest/Specs versions. Provider order and extended-session qualification remain separate from this offline comparison. This three-library workflow does not establish coinstallation of all seven libraries or venue fill parity.

Portability And Outcome Parity

Lifecycle portability means both engines invoke the same versioned callbacks with the information allowed in each phase. Canonical-intent parity means decision_time, information_cutoff, effective session and phase, target units, rounding, residual policy, reason, and position-rule policy match.

Outcome parity is narrower. Compare outcomes only when execution policy, fees, spread, slippage, liquidity, bar-path policy, venue capabilities, and starting positions are also equivalent. Live safety may reduce or reject a portable intent. It must not silently change its meaning.

Where Divergence Comes From

Technical divergence can arise from:

  • different bar completion or event timing
  • stale or mismatched data fields
  • broker inventory that differs from the simulated portfolio
  • order semantics or venue capabilities that differ from the execution policy
  • safety rules applied in one runtime but not represented in the comparison
  • different lifecycle, dependency, or position-rule versions

ml4t-live separates portable decisions from feed, execution, safety, and operator state. A parity failure can therefore identify the first boundary whose trace differs.

Practical Rollout Pattern

Stage Goal Required checks
Shadow mode Verify the live runtime without venue orders callbacks, intents, positions, restart behavior
Paper trading Verify broker and feed integration capabilities, order lifecycle, reconciliation, timestamps
Small live size Verify operational controls slippage, latency, monitoring, manual overrides

See It In The Book

The unified framework notebook calls both Live and Backtest to compare lifecycle and intent traces. The pipeline verification notebook calls Live to check the research-to-deployment handoff. The crypto funding backtest is a related manual case study; its simulation is not a Live run. See the Book Guide for input and venue differences.

Verify the first port

Run the synthetic shadow quickstart to check callback dispatch, virtual positions, and orderly shutdown without a venue. Then compare the same strategy's lifecycle and canonical intents in Backtest and Live on equivalent input. Record data cutoffs, execution policy, starting positions, fees, and venue capabilities before interpreting outcome differences. The API reference gives the Live engine signature.

Run the installed-candidate comparison

From a Linux checkout of this repository with uv installed, run:

uv run --locked python scripts/qualification/check_dependency_matrix.py

The verifier builds the checkout's Live wheel, installs it into separate minimum, locked, and maximum dependency environments, and runs the shared strategy through the real Engine and LiveEngine contract tests. It also checks canonical order and broker contracts. The output names the installed package versions for each profile; a failed contract or installation returns a nonzero exit status. No provider credentials or venue orders are required.

The published shadow quickstart stack checked on 2026-10-17 was:

Package Version
ml4t-live 0.1.2
ml4t-backtest 0.1.12
ml4t-specs 0.1.5

The complete shadow quickstart passed on that stack. The command above builds the current checkout instead; use its reported versions when recording a new parity or migration result. Neither result establishes equal venue execution or qualifies a later dependency release.

Export execution evidence

Call engine.to_order_trace(fills=reports) at a quiescent checkpoint to combine the canonical target and child records with incremental execution reports. A caller can also supply a replacement-to-original ID mapping and a JSON-compatible account checkpoint. The trace retains unlinked fills and missing fields for later reconciliation. Save the provider's execution IDs across restarts if you want to reconcile an interrupted run.

AlpacaBroker.set_execution_sink(...) can send each streamed incremental fill to a non-blocking callback. Check execution_capture_errors for dropped reports. The stream does not provide commissions. Record fees separately if available. See the credential-free examples/cross_library/order_execution_trace.py for the full workflow with one price-only strategy.