chore: v8.8.0 — re-exports, DI wiring, examples for new features

Bumps version 8.7.3 -> 8.8.0. Wires new BrokerBalanceTracker into the
dependency container and event loop, exposes new public symbols from
package __init__, adds OperationalException for sync errors, updates
docs sidebar, and ships example strategies showcasing TWR metrics,
DCA accumulation, and stop/stop-limit orders.

Author: MDUYN

README.md

@@ -85,7 +85,8 @@ This framework is built around the full loop: **create strategies → vector bac
 - 📄 **[One-Click HTML Report](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/backtest-reports)** — Self-contained file, no server, dark & light theme, shareable
 - 📦 **[Custom `.iafbt` Backtest Bundle Format](https://coding-kitties.github.io/investing-algorithm-framework/Data/backtest_data)** — An explicit, versioned, compressed, language-portable container (zstd + msgpack with magic-byte header) plus a separate parquet index for fast filtering without loading. ~21× smaller and ~27× fewer files than standard filebased directory layouts, with parallel I/O for fast load/save of large amounts of backtests.
 - 🌐 **[Load External Data](https://coding-kitties.github.io/investing-algorithm-framework/Data/external-data)** — Fetch CSV, JSON, or Parquet from any URL with caching and auto-refresh
-- 📝 **[Record Custom Variables](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/recording-variables)** — Track any indicator or metric during backtests with `context.record()`
+- � **[Per-Market Deposit Schedules & Portfolio Sync](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/portfolio-sync)** — Declare recurring or one-shot external cash flows on a market with `deposit_schedule=` / `auto_sync=True`. Backtests simulate the deposits; live mode reconciles with the broker — same `context.sync_portfolio()` API in both modes.
+- �📝 **[Record Custom Variables](https://coding-kitties.github.io/investing-algorithm-framework/Advanced%20Concepts/recording-variables)** — Track any indicator or metric during backtests with `context.record()`
 - 🚀 **[Build → Backtest → Deploy](https://coding-kitties.github.io/investing-algorithm-framework/Getting%20Started/application-setup)** — Local dev, cloud deploy (AWS / Azure), or monetize on Finterion
 
 </details>

docusaurus/sidebars.js

@@ -133,6 +133,10 @@ const sidebars = {
                     type: 'doc',
                     id: 'Advanced Concepts/recording-variables',
                 },
+                {
+                    type: 'doc',
+                    id: 'Advanced Concepts/portfolio-sync',
+                },
                 {
                     type: 'doc',
                     id: 'Advanced Concepts/pipelines',

examples/advanced_tutorials/cross-sectional-pipelines/README.md

@@ -0,0 +1,81 @@
+# Pipeline API examples
+
+This folder showcases the **Pipeline API (Phase 1)** — a declarative way to
+express cross-sectional screens and signals over a panel of symbols, similar
+in spirit to Quantopian / Zipline pipelines.
+
+A `Pipeline` is a small class where you declare the columns you want as
+`Factor` / `Filter` attributes. The engine turns those declarations into a
+single Polars DataFrame on each scheduled run, with no look-ahead, ready for
+your `TradingStrategy` to consume via `data["YourPipelineClassName"]`.
+
+## Examples in this folder
+
+| File | What it shows |
+| --- | --- |
+| [`momentum_screener.py`](momentum_screener.py) | Minimal screener-only example: a `MomentumScreener` ranks 5 EUR pairs by 30‑day return within the top‑3 most liquid names and prints the top‑2 each day. No order placement — useful for understanding the pipeline output format. |
+| [`cross_sectional_momentum_bot.py`](cross_sectional_momentum_bot.py) | End-to-end trading bot: a `MomentumScreener` ranks symbols by 30‑day return within the top‑3 most liquid names, and a `TradingStrategy` rebalances daily into the top‑2 ranked symbols on Bitvavo. Includes a 1‑year backtest. |
+
+## Anatomy of the example
+
+```python
+class MomentumScreener(Pipeline):
+    dollar_volume = AverageDollarVolume(window=30)
+    momentum     = Returns(window=30)
+    universe     = dollar_volume.top(3)        # liquidity filter
+    alpha        = momentum.rank(mask=universe)  # ranked score
+```
+
+That's the whole pipeline. The strategy then consumes it:
+
+```python
+class CrossSectionalMomentumBot(TradingStrategy):
+    pipelines = [MomentumScreener]
+    ...
+
+    def run_strategy(self, context, data):
+        screen = data["MomentumScreener"]            # polars.DataFrame
+        targets = screen.sort("alpha", descending=True).head(TOP_N)
+        # ... rebalance into `targets` ...
+```
+
+## Run a backtest
+
+From the repository root:
+
+```bash
+python examples/cross-sectional-pipelines/cross_sectional_momentum_bot.py
+```
+
+The script:
+
+1. Creates an app pointed at `examples/resources/`.
+2. Registers OHLCV data sources for 7 EUR pairs on Bitvavo.
+3. Runs a 1‑year daily backtest of the momentum rotation.
+4. Prints the full `Backtest` JSON (metrics, trades, snapshots).
+
+For an interactive HTML dashboard, replace the `print(backtest)` line with:
+
+```python
+from investing_algorithm_framework import BacktestReport
+BacktestReport(backtest).show()
+```
+
+## Run it live
+
+Remove the `app.run_backtest(...)` block at the bottom of the file and call
+`app.run()` instead. Bitvavo does not require API keys for market data, so
+the bot will pull live OHLCV out of the box. Add Bitvavo credentials via the
+standard config to enable live order execution.
+
+## Built-in factors / filters used
+
+- `AverageDollarVolume(window=N)` — rolling close × volume over N bars.
+- `Returns(window=N)` — N‑bar percentage change.
+- `Factor.rank(mask=...)` — cross‑sectional rank, optionally restricted to a filter.
+- `Factor.top(n)` / `Factor.bottom(n)` — per‑bar top/bottom‑N selection (returns a `Filter`).
+
+See the framework docs:
+
+- `docusaurus/docs/Advanced Concepts/pipelines.md`
+- `docusaurus/docs/Advanced Concepts/pipelines-event-backtest.md`

examples/advanced_tutorials/cross-sectional-pipelines/cross_sectional_momentum_bot.py

@@ -0,0 +1,210 @@
+"""Pipeline API — cross-sectional momentum trading bot (Phase 1).
+
+This example shows how to turn a :class:`Pipeline` screen into an actual
+trading bot that rebalances a portfolio every day into the top-N
+momentum names within a liquid universe.
+
+What it does on each iteration (once per day):
+
+1. The framework builds a long-form OHLCV panel across the configured
+   symbols.
+2. ``MomentumScreener`` ranks every symbol by 30-day return within the
+   top-3 most liquid names (by 30-day average dollar volume).
+3. ``CrossSectionalMomentumBot.run_strategy`` reads the resulting
+   ``polars.DataFrame`` from ``data["MomentumScreener"]``, picks the
+   top-2 ranked symbols, and rebalances the portfolio:
+     * closes any open position that is no longer in the target set,
+     * opens an equal-weight market order for any new target.
+
+Backtest the bot:
+
+.. code-block:: bash
+
+    python examples/cross-sectional-pipelines/cross_sectional_momentum_bot.py
+
+Run it live by removing the ``app.run_backtest(...)`` block and calling
+``app.run()`` instead. Bitvavo does not require API keys for market
+data, so the backtest works out of the box.
+
+See docs:
+- ``docs/Advanced Concepts/pipelines.md``
+- ``docs/Advanced Concepts/pipelines-event-backtest.md``
+"""
+from __future__ import annotations
+
+import logging.config
+from datetime import datetime, timedelta
+from typing import Any, Dict
+
+from dotenv import load_dotenv
+
+from investing_algorithm_framework import (
+    AverageDollarVolume,
+    BacktestDateRange,
+    Context,
+    DataSource,
+    DEFAULT_LOGGING_CONFIG,
+    OrderSide,
+    OrderType,
+    Pipeline,
+    Returns,
+    TimeUnit,
+    TradingStrategy,
+    create_app,
+)
+
+logging.config.dictConfig(DEFAULT_LOGGING_CONFIG)
+load_dotenv()
+
+
+# Universe
+# A small crypto basket. All symbols quote in EUR so they share the
+# same trading symbol (the portfolio currency below).
+SYMBOLS = [
+    "BTC/EUR",
+    "ETH/EUR",
+    "SOL/EUR",
+    "ADA/EUR",
+    "XRP/EUR",
+    "DOT/EUR",
+    "LINK/EUR",
+]
+
+#: Number of symbols held simultaneously.
+TOP_N = 2
+
+#: Exchange and quote currency for the bot.
+MARKET = "bitvavo"
+TRADING_SYMBOL = "EUR"
+
+
+# Pipeline: declarative cross-sectional screen
+class MomentumScreener(Pipeline):
+    """Rank the most liquid 3 names by 30-day return."""
+
+    # Per-symbol factors. Each becomes an output column.
+    dollar_volume = AverageDollarVolume(window=30)
+    momentum = Returns(window=30)
+
+    # The master mask: only the 3 most liquid names enter ranking.
+    universe = dollar_volume.top(3)
+
+    # Cross-sectional rank within the universe (highest momentum gets
+    # the highest rank).
+    alpha = momentum.rank(mask=universe)
+
+
+# Strategy: rebalance into the top-N pipeline picks
+class CrossSectionalMomentumBot(TradingStrategy):
+    algorithm_id = "pipeline-momentum-bot"
+    time_unit = TimeUnit.DAY
+    interval = 1
+    market = MARKET
+    trading_symbol = TRADING_SYMBOL
+    symbols = SYMBOLS
+
+    # OHLCV data sources, one per symbol. ``warmup_window`` covers the
+    # longest factor lookback (30) plus a buffer so the pipeline starts
+    # producing values from bar 1 of the backtest. Tickers are added so
+    # the bot can read live bid/ask in production — in backtest mode the
+    # framework will fall back to the latest OHLCV close.
+    data_sources = [
+        DataSource(
+            data_type="OHLCV",
+            market=MARKET,
+            symbol=symbol,
+            warmup_window=60,
+            time_frame="1d",
+            identifier=f"{symbol}-ohlcv",
+        )
+        for symbol in SYMBOLS
+    ]
+
+    # Opt-in to the Pipeline API. The framework will compute this every
+    # iteration and place the result under ``data["MomentumScreener"]``.
+    pipelines = [MomentumScreener]
+
+    # Strategy entry point
+    def run_strategy(self, context: Context, data: Dict[str, Any]) -> None:
+        screen = data["MomentumScreener"]
+
+        # Skip iterations where the universe / warmup is not satisfied.
+        if screen.is_empty():
+            return
+
+        # Rank is ascending — highest rank = highest momentum.
+        targets_df = screen.sort("alpha", descending=True).head(TOP_N)
+        targets = {row["symbol"] for row in targets_df.iter_rows(named=True)}
+
+        def _last_close(symbol: str) -> float:
+            ohlcv = data[f"{symbol}-ohlcv"]
+            try:
+                return float(ohlcv["Close"][-1])
+            except (KeyError, TypeError):
+                return float(ohlcv["close"].iloc[-1])
+
+        def _base(symbol: str) -> str:
+            # ``target_symbol`` is just the base asset (e.g. "BTC").
+            return symbol.split("/")[0]
+
+        # 1. Close positions no longer in the target set
+        for symbol in SYMBOLS:
+            if symbol in targets:
+                continue
+            base = _base(symbol)
+            if not context.has_position(base, market=self.market):
+                continue
+            position = context.get_position(base, market=self.market)
+            context.create_order(
+                target_symbol=base,
+                order_side=OrderSide.SELL,
+                order_type=OrderType.LIMIT,
+                price=_last_close(symbol),
+                amount=position.get_amount(),
+            )
+
+        # 2. Open new equal-weight positions for new targets
+        unallocated = context.get_unallocated()
+        new_targets = [
+            sym for sym in targets
+            if not context.has_position(_base(sym), market=self.market)
+        ]
+        if not new_targets:
+            return
+
+        per_target_budget = unallocated / len(new_targets)
+        for symbol in new_targets:
+            price = _last_close(symbol)
+            if price <= 0:
+                continue
+            # 0.5% safety buffer so floating-point rounding does not
+            # push the order total above the available unallocated cash.
+            amount = (per_target_budget * 0.995) / price
+            context.create_order(
+                target_symbol=_base(symbol),
+                order_side=OrderSide.BUY,
+                order_type=OrderType.LIMIT,
+                price=price,
+                amount=amount,
+            )
+
+
+# App wiring
+app = create_app()
+app.add_strategy(CrossSectionalMomentumBot)
+app.add_market(market=MARKET, trading_symbol=TRADING_SYMBOL, initial_balance=1000)
+
+
+if __name__ == "__main__":
+    # Backtest over the last full year. Replace with ``app.run()`` to go
+    # live (requires bitvavo credentials in your .env file).
+    end = datetime.utcnow().replace(hour=0, minute=0, second=0, microsecond=0)
+    start = end - timedelta(days=365)
+    backtest_date_range = BacktestDateRange(start_date=start, end_date=end)
+    backtest = app.run_backtest(
+        backtest_date_range=backtest_date_range,
+    )
+    # Inspect the result interactively with the BacktestReport dashboard:
+    #     from investing_algorithm_framework import BacktestReport
+    #     BacktestReport(backtest).show()
+    print(backtest)