# Integrating Replay Core

Keep this edition in its own project/virtual environment. Its import root is
`core`; do not combine it blindly with another Python package named `core`.

The included `examples/replay_csv.py` is the smallest complete integration:

1. Construct validated `ReplayCandle` objects, using aware opening timestamps.
2. Supply an asynchronous `load_history(config)` returning a mapping of symbol
   to candles. The example sorts input before replay; do not mix different
   timestamp conventions or unqualified higher-timeframe series.
3. Build `ReplayConfig` with the intended symbols, time window, costs and
   account assumptions.
4. Construct `ReplayBroker` and `AsyncEventBus`, then `ReplayEngine`.
5. Connect your own strategy/state/control components. The example uses
   `on_candle` to submit scheduled `OrderIntent` objects directly, and an empty
   strategy list/state placeholder. This intentionally bypasses the full
   FALBI risk and TA workflow; it is not an account risk-control example.
6. Await `engine.run()`; reject a missing/error result. The example checks that
   simulated positions and pending orders are empty at completion.

The broker is updated before the example callback. A callback sees the closed
candle; it must not inspect a later candle to decide an earlier order. The
example loader holds the complete fixture in memory for simplicity. Your
strategy must respect information availability independently of storage.

`ReplayConfig` supports cost inputs and optional integration models. The
bundled symbol specification defaults are illustrative. Your deployment must
qualify actual tick sizes/values, volume steps, contract sizes, account currency
conversion, trading sessions, spread/slippage and other applicable costs.

Cost-unit detail: in the supplied ReplayBroker API, the fields named
`spread_points` and `slippage_points` are added as absolute price offsets,
not multiplied by a broker point size. The example sets `spread_points=0.0001`
for EURUSD/GBPUSD (a total spread of 0.0001 in quoted price, split between entry
and exit). Setting it to `1` would mean a whole unit of quoted price. Use a
qualified per-symbol cost model for instruments with different quote scales.

There is no MetaApi connection in this edition. No sample command places live
orders, fetches broker history or calls an external service. No market-data
entitlements are granted. Only use data you are entitled to process.

Python 3.12/Linux is the target environment. Windows/macOS, large-data
performance and third-party application integration are not qualified by the
included small offline verification.
