Merge pull request #557 from coding-kitties/dev

Release: order convenience functions, vector backtest bundle fix, scenario CI optimizations

Author: MDUYN

docusaurus/docs/Getting Started/orders.md

@@ -166,6 +166,69 @@ In an event-driven backtest, the trigger condition is evaluated against each can
 - A **STOP_LIMIT** that triggers becomes a resting limit order at `price` from the triggering candle onwards, and fills under the normal limit-fill rules (`Low <= price` for BUY, `High >= price` for SELL).
 - The triggering timestamp is stored on the order as `triggered_at` for auditability.
 
+## Convenience Helpers
+
+For common sizing patterns the framework exposes five high-level helpers on `Context` (also available as `self.*` from a `TradingStrategy`). They all produce **LIMIT** orders and require an explicit `price`, delegating internally to `create_limit_order`. The `order_target*` family looks up the current position and submits a BUY or SELL for the difference (no order is placed when the position already matches the target).
+
+| Helper | Computes | Use case |
+|--------|----------|----------|
+| `order_value(symbol, value, side, price)` | `amount = value / price` | Fixed currency-amount orders (e.g. DCA) |
+| `order_percent(symbol, percent, side, price)` | `(net_size * percent / 100) / price` | Allocate a % of portfolio net size |
+| `order_target(symbol, target_amount, price)` | `target_amount - current_amount` | Reach an exact position size in units |
+| `order_target_value(symbol, target_value, price)` | `(target_value / price) - current_amount` | Reach an exact position value |
+| `order_target_percent(symbol, target_percent, price)` | `((net_size * target_percent / 100) / price) - current_amount` | Portfolio rebalancing |
+
+```python
+from investing_algorithm_framework import OrderSide, TradingStrategy
+
+class RebalanceStrategy(TradingStrategy):
+
+    def apply_strategy(self, context, data):
+        price = data["BTC/EUR"]["close"].iloc[-1]
+
+        # Spend exactly 500 EUR on BTC
+        context.order_value(
+            target_symbol="BTC",
+            value=500,
+            order_side=OrderSide.BUY,
+            price=price,
+        )
+
+        # Allocate 25% of portfolio to ETH
+        context.order_percent(
+            target_symbol="ETH",
+            percent=25,
+            order_side=OrderSide.BUY,
+            price=data["ETH/EUR"]["close"].iloc[-1],
+        )
+
+        # End up holding exactly 1.5 BTC (buys or sells the difference)
+        context.order_target(
+            target_symbol="BTC",
+            target_amount=1.5,
+            price=price,
+        )
+
+        # Rebalance BTC to 10% of portfolio
+        context.order_target_percent(
+            target_symbol="BTC",
+            target_percent=10,
+            price=price,
+        )
+```
+
+**Validation**
+
+- `value`, `percent`, `price` must be positive.
+- `target_amount`, `target_value`, `target_percent` must be non-negative.
+- `order_target*` returns `None` (no order placed) when the current position already matches the target.
+
+All helpers accept the same optional `market`, `precision` and `metadata` parameters as `create_limit_order`.
+
+:::tip MARKET variant & auto-price
+The helpers currently require an explicit `price` and always produce LIMIT orders. A future enhancement (tracked as a follow-up to #440) will add `order_type=OrderType.MARKET` support and fall back to `context.get_latest_price()` when `price` is omitted.
+:::
+
 ## Order Parameters
 
 ### Market Order Parameters

investing_algorithm_framework/app/context.py

@@ -673,6 +673,245 @@ def create_limit_buy_order(
             market=market,
         )
 
+    def order_value(
+        self,
+        target_symbol,
+        value,
+        order_side,
+        price,
+        market=None,
+        precision=None,
+        metadata=None,
+    ) -> Order:
+        """
+        Place a LIMIT order for a fixed currency amount.
+
+        The order amount is computed as ``value / price``.
+
+        Args:
+            target_symbol: The symbol of the asset to trade.
+            value: Currency amount to spend (BUY) or to sell (SELL).
+            order_side: ``OrderSide.BUY`` or ``OrderSide.SELL``.
+            price: Limit price.
+            market: Optional market identifier.
+            precision: Optional decimal precision to round the
+              computed amount down.
+            metadata: Optional order metadata.
+
+        Returns:
+            Order: The created order.
+        """
+        if value is None or value <= 0:
+            raise OperationalException(
+                "`value` must be a positive number."
+            )
+        if price is None or price <= 0:
+            raise OperationalException(
+                "`price` must be a positive number."
+            )
+        amount = value / price
+        if precision is not None:
+            amount = RoundingService.round_down(amount, precision)
+        return self.create_limit_order(
+            target_symbol=target_symbol,
+            price=price,
+            order_side=order_side,
+            amount=amount,
+            market=market,
+            metadata=metadata,
+        )
+
+    def order_percent(
+        self,
+        target_symbol,
+        percent,
+        order_side,
+        price,
+        market=None,
+        precision=None,
+        metadata=None,
+    ) -> Order:
+        """
+        Place a LIMIT order for ``percent`` of the portfolio's net size.
+
+        Args:
+            target_symbol: The symbol of the asset to trade.
+            percent: Percentage (0-100) of portfolio net size to allocate.
+            order_side: ``OrderSide.BUY`` or ``OrderSide.SELL``.
+            price: Limit price.
+            market: Optional market identifier.
+            precision: Optional decimal precision to round the
+              computed amount down.
+            metadata: Optional order metadata.
+
+        Returns:
+            Order: The created order.
+        """
+        if percent is None or percent <= 0:
+            raise OperationalException(
+                "`percent` must be a positive number."
+            )
+        portfolio = self.portfolio_service.find({"market": market})
+        net_size = portfolio.get_net_size()
+        value = net_size * (percent / 100.0)
+        return self.order_value(
+            target_symbol=target_symbol,
+            value=value,
+            order_side=order_side,
+            price=price,
+            market=market,
+            precision=precision,
+            metadata=metadata,
+        )
+
+    def order_target(
+        self,
+        target_symbol,
+        target_amount,
+        price,
+        market=None,
+        precision=None,
+        metadata=None,
+    ) -> Order:
+        """
+        Adjust the position in ``target_symbol`` to hold exactly
+        ``target_amount`` units.
+
+        The difference between the current position size and
+        ``target_amount`` is submitted as a BUY (positive diff) or
+        SELL (negative diff) LIMIT order. If the position already
+        matches the target, no order is placed.
+
+        Args:
+            target_symbol: The symbol of the asset to adjust.
+            target_amount: Desired position size in units.
+            price: Limit price.
+            market: Optional market identifier.
+            precision: Optional decimal precision to round the diff down.
+            metadata: Optional order metadata.
+
+        Returns:
+            Order: The created order, or ``None`` if no adjustment
+              was required.
+        """
+        if target_amount is None or target_amount < 0:
+            raise OperationalException(
+                "`target_amount` must be a non-negative number."
+            )
+        if price is None or price <= 0:
+            raise OperationalException(
+                "`price` must be a positive number."
+            )
+        portfolio = self.portfolio_service.find({"market": market})
+        try:
+            position = self.position_service.find(
+                {"symbol": target_symbol, "portfolio": portfolio.id}
+            )
+            current_amount = position.get_amount() \
+                if position is not None else 0
+        except OperationalException:
+            current_amount = 0
+        diff = target_amount - current_amount
+        if precision is not None:
+            sign = 1 if diff >= 0 else -1
+            diff = sign * RoundingService.round_down(abs(diff), precision)
+        if diff == 0:
+            return None
+        order_side = OrderSide.BUY if diff > 0 else OrderSide.SELL
+        return self.create_limit_order(
+            target_symbol=target_symbol,
+            price=price,
+            order_side=order_side,
+            amount=abs(diff),
+            market=market,
+            metadata=metadata,
+        )
+
+    def order_target_value(
+        self,
+        target_symbol,
+        target_value,
+        price,
+        market=None,
+        precision=None,
+        metadata=None,
+    ) -> Order:
+        """
+        Adjust the position in ``target_symbol`` so its market value at
+        ``price`` equals ``target_value``.
+
+        Args:
+            target_symbol: The symbol of the asset to adjust.
+            target_value: Desired position market value in trading currency.
+            price: Limit price.
+            market: Optional market identifier.
+            precision: Optional decimal precision to round the diff down.
+            metadata: Optional order metadata.
+
+        Returns:
+            Order: The created order, or ``None`` if no adjustment
+              was required.
+        """
+        if target_value is None or target_value < 0:
+            raise OperationalException(
+                "`target_value` must be a non-negative number."
+            )
+        if price is None or price <= 0:
+            raise OperationalException(
+                "`price` must be a positive number."
+            )
+        target_amount = target_value / price
+        return self.order_target(
+            target_symbol=target_symbol,
+            target_amount=target_amount,
+            price=price,
+            market=market,
+            precision=precision,
+            metadata=metadata,
+        )
+
+    def order_target_percent(
+        self,
+        target_symbol,
+        target_percent,
+        price,
+        market=None,
+        precision=None,
+        metadata=None,
+    ) -> Order:
+        """
+        Adjust the position in ``target_symbol`` so its market value
+        equals ``target_percent`` of the portfolio's net size.
+
+        Args:
+            target_symbol: The symbol of the asset to adjust.
+            target_percent: Desired position size as a percentage (0-100)
+              of portfolio net size.
+            price: Limit price.
+            market: Optional market identifier.
+            precision: Optional decimal precision to round the diff down.
+            metadata: Optional order metadata.
+
+        Returns:
+            Order: The created order, or ``None`` if no adjustment
+              was required.
+        """
+        if target_percent is None or target_percent < 0:
+            raise OperationalException(
+                "`target_percent` must be a non-negative number."
+            )
+        portfolio = self.portfolio_service.find({"market": market})
+        net_size = portfolio.get_net_size()
+        target_value = net_size * (target_percent / 100.0)
+        return self.order_target_value(
+            target_symbol=target_symbol,
+            target_value=target_value,
+            price=price,
+            market=market,
+            precision=precision,
+            metadata=metadata,
+        )
+
     def get_portfolio(self, market=None) -> Portfolio:
         """
         Function to get the portfolio of the algorithm. This function

investing_algorithm_framework/infrastructure/services/backtesting/backtest_service.py

@@ -1672,9 +1672,61 @@ def _batch_save_and_checkpoint(
         if len(backtests) == 0:
             return
 
+        # When iterating across multiple date ranges, a bundle for the
+        # same ``algorithm_id`` may already exist on disk from a previous
+        # iteration. ``save_bundle`` keys solely on ``algorithm_id``, so
+        # a naive save would overwrite the prior bundle and lose its
+        # backtest_runs. Merge with the existing bundle so all date
+        # ranges' runs end up in the single per-algorithm bundle.
+        backtests_to_save: List[Backtest] = []
+        for bt in backtests:
+            existing_path = resolve_backtest_path(
+                storage_directory, bt.algorithm_id
+            )
+            if existing_path is None:
+                backtests_to_save.append(bt)
+                continue
+
+            try:
+                existing = Backtest.open(existing_path)
+            except Exception as e:
+                logger.warning(
+                    f"Could not open existing bundle for "
+                    f"{bt.algorithm_id} at {existing_path}: {e}; "
+                    "overwriting."
+                )
+                backtests_to_save.append(bt)
+                continue
+
+            # If the existing bundle already contains a run for one of
+            # the new date ranges (e.g. a forced rerun), drop the
+            # overlapping runs from the existing bundle before merging
+            # so we don't end up with duplicates.
+            new_ranges = {
+                (run.backtest_start_date, run.backtest_end_date)
+                for run in bt.get_all_backtest_runs()
+            }
+            kept_runs = [
+                run for run in existing.get_all_backtest_runs()
+                if (run.backtest_start_date, run.backtest_end_date)
+                not in new_ranges
+            ]
+            existing.backtest_runs = kept_runs
+
+            if kept_runs:
+                merged = combine_backtests([existing, bt])
+                # Preserve the freshly produced backtest's metadata /
+                # parameters by letting the new backtest's values win
+                # on key conflicts (combine_backtests uses dict update
+                # in iteration order — ``bt`` is second so its values
+                # already win).
+                backtests_to_save.append(merged)
+            else:
+                backtests_to_save.append(bt)
+
         # Save backtests to disk
         save_backtests_to_directory(
-            backtests=backtests,
+            backtests=backtests_to_save,
             directory_path=storage_directory,
             show_progress=show_progress
         )