robottraderslab-envelope 0.1.0__tar.gz

robottraderslab_envelope-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: robottraderslab-envelope
+Version: 0.1.0
+Summary: Envelope trading strategy plugin for the RobotTradersLab engine
+License-Expression: Apache-2.0
+Requires-Dist: robottraderslab>=0.2.1
+Requires-Dist: pandas>=3.0.0
+Requires-Dist: numpy>=2.4.2
+Requires-Python: >=3.13, <3.14
+Project-URL: Homepage, https://robottraders.io/lab/envelope
+Project-URL: Documentation, https://robottraders.io/lab/docs/envelope.html
+Project-URL: Repository, https://github.com/RobotTraders/RobotTradersLab-Envelope
+Description-Content-Type: text/markdown
+
+# robottraderslab-envelope
+
+Mean reversion strategy plugin for the RobotTradersLab engine, registered under the name `envelope`.
+
+## Documentation
+
+The strategy, its parameters and an example config are on its page at [robottraders.io/lab/docs/envelope](https://robottraders.io/lab/docs/envelope.html).
+
+## Disclaimer
+
+Nothing in this software constitutes financial, investment, or trading advice, nor a recommendation of any trading strategy. Trading involves substantial risk: deployed capital can be lost entirely, and backtested results do not predict live performance. The software is used at your own risk; the authors and affiliates accept no responsibility for trading results.
+
+Use of this software is subject to the [Disclaimer](https://robottraders.io/disclaimer).
+
+## License
+
+Distributed under the [Apache License 2.0](LICENSE).

robottraderslab_envelope-0.1.0/README.md

@@ -0,0 +1,17 @@
+# robottraderslab-envelope
+
+Mean reversion strategy plugin for the RobotTradersLab engine, registered under the name `envelope`.
+
+## Documentation
+
+The strategy, its parameters and an example config are on its page at [robottraders.io/lab/docs/envelope](https://robottraders.io/lab/docs/envelope.html).
+
+## Disclaimer
+
+Nothing in this software constitutes financial, investment, or trading advice, nor a recommendation of any trading strategy. Trading involves substantial risk: deployed capital can be lost entirely, and backtested results do not predict live performance. The software is used at your own risk; the authors and affiliates accept no responsibility for trading results.
+
+Use of this software is subject to the [Disclaimer](https://robottraders.io/disclaimer).
+
+## License
+
+Distributed under the [Apache License 2.0](LICENSE).

robottraderslab_envelope-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "robottraderslab-envelope"
+version = "0.1.0"
+description = "Envelope trading strategy plugin for the RobotTradersLab engine"
+readme = "README.md"
+requires-python = ">=3.13,<3.14"
+license = "Apache-2.0"
+dependencies = [
+    "robottraderslab>=0.2.1",
+    "pandas>=3.0.0",
+    "numpy>=2.4.2",
+]
+
+[project.urls]
+Homepage = "https://robottraders.io/lab/envelope"
+Documentation = "https://robottraders.io/lab/docs/envelope.html"
+Repository = "https://github.com/RobotTraders/RobotTradersLab-Envelope"
+
+[project.entry-points."robot_traders_lab.strategies"]
+envelope = "robottraderslab_envelope:EnvelopeStrategy"
+
+[project.entry-points."robot_traders_lab.indicators"]
+envelope = "robottraderslab_envelope.chart_indicators:get_lightweight_chart_indicators"
+
+[project.entry-points."robot_traders_lab.examples"]
+envelope = "robottraderslab_envelope"
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "robottraderslab_envelope"

robottraderslab_envelope-0.1.0/pyproject.toml.orig

@@ -0,0 +1,34 @@
+[project]
+name = "robottraderslab-envelope"
+version = "0.1.0"
+description = "Envelope trading strategy plugin for the RobotTradersLab engine"
+readme = "README.md"
+requires-python = ">=3.13,<3.14"
+license = "Apache-2.0"
+dependencies = [
+  "robottraderslab>=0.2.1",
+  "pandas>=3.0.0",
+  "numpy>=2.4.2",
+]
+
+[project.urls]
+Homepage = "https://robottraders.io/lab/envelope"
+Documentation = "https://robottraders.io/lab/docs/envelope.html"
+Repository = "https://github.com/RobotTraders/RobotTradersLab-Envelope"
+
+[project.entry-points."robot_traders_lab.strategies"]
+envelope ="robottraderslab_envelope:EnvelopeStrategy"
+
+[project.entry-points."robot_traders_lab.indicators"]
+envelope = "robottraderslab_envelope.chart_indicators:get_lightweight_chart_indicators"
+
+[project.entry-points."robot_traders_lab.examples"]
+envelope = "robottraderslab_envelope"
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+
+[tool.uv.build-backend]
+module-name = "robottraderslab_envelope"

robottraderslab_envelope-0.1.0/src/robottraderslab_envelope/__init__.py

@@ -0,0 +1,5 @@
+from .envelope import EnvelopeStrategy
+
+__all__ = [
+    "EnvelopeStrategy",
+]

robottraderslab_envelope-0.1.0/src/robottraderslab_envelope/book_rungs.py

@@ -0,0 +1,124 @@
+from collections.abc import Callable
+
+from robottraderslab.strategies import (
+    BookKeeper,
+    OrderProtocol,
+    OrderSide,
+)
+from robottraderslab.strategies.futures import (
+    BatchableOrderAction,
+    FuturesAccount,
+    OrderModification,
+)
+
+from .profile_config import ProfileConfig
+from .profile_snapshot import ProfileSnapshot
+from .rungs import WantedRung, rung_band_index
+
+type RungUpdater = Callable[
+    [
+        FuturesAccount,
+        ProfileConfig,
+        ProfileSnapshot,
+        list[WantedRung],
+        BookKeeper,
+    ],
+    None,
+]
+
+
+def book_cancel_and_place(
+    account: FuturesAccount,
+    profile: ProfileConfig,
+    profile_snapshot: ProfileSnapshot,
+    wanted: list[WantedRung],
+    bookkeeper: BookKeeper,
+) -> None:
+    """Drop the resting rungs and place the wanted set once they are gone."""
+    symbol = profile.symbol
+    if profile_snapshot.position is None:
+        cancels = [bookkeeper.add(account.cancel_orders(symbol), after=())]
+    else:
+        cancels = [
+            bookkeeper.add(
+                account.cancel_order(symbol, rung.order_id),
+                after=(),
+            )
+            for rung in profile_snapshot.pending_rungs
+        ]
+
+    orders: list[BatchableOrderAction] = [rung.order for rung in wanted]
+    if orders:
+        bookkeeper.add(account.place_orders(orders), after=cancels)
+
+
+def book_modify_in_place(
+    account: FuturesAccount,
+    profile: ProfileConfig,
+    profile_snapshot: ProfileSnapshot,
+    wanted: list[WantedRung],
+    bookkeeper: BookKeeper,
+) -> None:
+    """Move each resting rung to its own band, so the book is never empty."""
+    symbol = profile.symbol
+    holding = profile_snapshot.position is not None
+
+    modifications: list[OrderModification] = []
+    cancel_ids: list[str] = [] if holding else list(profile_snapshot.stray_order_ids)
+    missing: list[BatchableOrderAction] = []
+    for side in (OrderSide.BUY, OrderSide.SELL):
+        resting, unclaimed = _resting_by_band(profile_snapshot.pending_rungs, side)
+        cancel_ids.extend(unclaimed)
+        for rung in wanted:
+            if rung.order.side != side:
+                continue
+            claimed = resting.pop(rung.band_index, None)
+            if claimed is None:
+                missing.append(rung.order)
+            else:
+                modifications.append(
+                    OrderModification(order_id=claimed.order_id, order=rung.order)
+                )
+        cancel_ids.extend(rung.order_id for rung in resting.values())
+
+    if modifications:
+        bookkeeper.add(account.modify_orders(modifications), after=())
+    cancels = [
+        bookkeeper.add(account.cancel_order(symbol, order_id), after=())
+        for order_id in cancel_ids
+    ]
+    if missing:
+        bookkeeper.add(account.place_orders(missing), after=cancels)
+
+
+def book_cancel_entries(
+    account: FuturesAccount,
+    profile: ProfileConfig,
+    profile_snapshot: ProfileSnapshot,
+    bookkeeper: BookKeeper,
+) -> None:
+    """Clear the resting rungs without placing anything in their place."""
+    if profile_snapshot.position is None:
+        bookkeeper.add(account.cancel_orders(profile.symbol), after=())
+        return
+    for rung in profile_snapshot.pending_rungs:
+        bookkeeper.add(
+            account.cancel_order(profile.symbol, rung.order_id),
+            after=(),
+        )
+
+
+def _resting_by_band(
+    pending_rungs: list[OrderProtocol], side: OrderSide
+) -> tuple[dict[int, OrderProtocol], list[str]]:
+    resting: dict[int, OrderProtocol] = {}
+    unclaimed: list[str] = []
+    for rung in pending_rungs:
+        if rung.side != side:
+            continue
+        band_index = rung_band_index(rung.client_order_id)
+        if band_index is None or band_index in resting:
+            unclaimed.append(rung.order_id)
+        else:
+            resting[band_index] = rung
+    return resting, unclaimed

robottraderslab_envelope-0.1.0/src/robottraderslab_envelope/chart_indicators.py

@@ -0,0 +1,49 @@
+from typing import Any
+
+from robottraderslab.strategies import Candles, ChartLine, PositionSide
+
+from .envelope_indicator import compute_envelope, compute_reference
+from .profile_config import BAND_LABEL, AverageType, envelopes_by_side
+
+_BAND_COLOUR = {PositionSide.LONG: "green", PositionSide.SHORT: "red"}
+
+
+def get_lightweight_chart_indicators(
+    candles: Candles,
+    indicator_params: dict[str, Any],
+) -> list[ChartLine]:
+    """Draw the reference average and the band a rung rests on beside the candles.
+
+    Args:
+        indicator_params: `average_type`, `average_period` and either
+            `envelopes` or `long_envelopes` / `short_envelopes`, spelled as a
+            profile spells them.
+    """
+    average_type = AverageType(indicator_params["average_type"])
+    average_period = indicator_params["average_period"]
+    reference = compute_reference(
+        candles.close,
+        candles.high,
+        candles.low,
+        average_type,
+        average_period,
+    )
+    levels = compute_envelope(reference, envelopes_by_side(indicator_params))
+
+    lines = [
+        ChartLine(
+            name=f"Reference {average_type} {average_period}",
+            values=levels.reference,
+            colour="orange",
+        )
+    ]
+    for side, bands in levels.bands.items():
+        for index, band in enumerate(bands, start=1):
+            lines.append(
+                ChartLine(
+                    name=f"Band {index} {BAND_LABEL[side]}",
+                    values=band,
+                    colour=_BAND_COLOUR[side],
+                )
+            )
+    return lines

robottraderslab_envelope-0.1.0/src/robottraderslab_envelope/entry_order.py

@@ -0,0 +1,25 @@
+from robottraderslab.strategies import OrderType
+from robottraderslab.strategies.futures import FuturesOrderBuilder
+
+
+class LimitEntryOrder:
+    def matches(self, order_kind: OrderType | None) -> bool:
+        return order_kind == OrderType.LIMIT
+
+    def rest_at_band(
+        self, entry: FuturesOrderBuilder, band_price: float
+    ) -> FuturesOrderBuilder:
+        return entry.limit(price=band_price)
+
+
+class TriggerEntryOrder:
+    def matches(self, order_kind: OrderType | None) -> bool:
+        return order_kind == OrderType.TRIGGER
+
+    def rest_at_band(
+        self, entry: FuturesOrderBuilder, band_price: float
+    ) -> FuturesOrderBuilder:
+        return entry.trigger(price=band_price)
+
+
+type EntryOrder = LimitEntryOrder | TriggerEntryOrder

robottraderslab_envelope-0.1.0/src/robottraderslab_envelope/envelope.py

@@ -0,0 +1,256 @@
+import logging
+from collections import Counter
+from collections.abc import Sequence
+from datetime import datetime
+from typing import ClassVar, Literal
+
+from robottraderslab import Symbol
+from robottraderslab.exceptions import StrategyCriticalError
+from robottraderslab.strategies import (
+    AccountSnapshots,
+    BookKeeper,
+    Execution,
+    MarketType,
+    OHLCVs,
+    OrderType,
+    ProfileStrategy,
+    StrategyRequirements,
+)
+from robottraderslab.strategies.futures import (
+    FuturesAccount,
+    MarginSettings,
+    TotalBalanceRatio,
+)
+
+from .book_rungs import (
+    RungUpdater,
+    book_cancel_and_place,
+    book_cancel_entries,
+    book_modify_in_place,
+)
+from .entry_order import EntryOrder, LimitEntryOrder, TriggerEntryOrder
+from .envelope_indicator import compute_envelope, compute_reference
+from .position_protection import book_position_protections
+from .profile_config import ProfileConfig
+from .profile_snapshot import ProfileSnapshot
+from .reentry_guard import ReentryGuard
+from .rungs import (
+    entered_side,
+    rung_band_index,
+    wanted_while_flat,
+    wanted_while_holding,
+)
+
+logger = logging.getLogger(__name__)
+
+_REFERENCE_EXIT_REASON = "moving average reached"
+_ENTRY_ORDERS: dict[str, EntryOrder] = {
+    "limit": LimitEntryOrder(),
+    "trigger": TriggerEntryOrder(),
+}
+_RUNG_UPDATERS: dict[str, RungUpdater] = {
+    "modify": book_modify_in_place,
+    "cancel_replace": book_cancel_and_place,
+}
+_WHOLE_BALANCE = 1.0
+
+
+class EnvelopeStrategy(ProfileStrategy[ProfileConfig]):
+    """Mean-reversion envelope strategy: rests one entry rung per band around a
+    moving average.
+
+    The `entry_order` setting chooses what a rung rests as: "trigger" fires a
+    market order once price reaches the band, "limit" rests at the band price
+    and fills there or better.
+
+    The `update_mode` setting chooses how the resting rungs follow the bands:
+    "modify" moves each resting rung to its band so the book is never empty,
+    "cancel_replace" cancels the resting set and places the wanted one afresh.
+    """
+
+    market_type: ClassVar[MarketType] = "futures"
+
+    account: FuturesAccount
+    entry_order: Literal["trigger", "limit"] = "trigger"
+    update_mode: Literal["modify", "cancel_replace"] = "modify"
+
+    _entry_order: EntryOrder
+    _profiles_by_symbol: dict[Symbol, ProfileConfig]
+    _reentry_guard: ReentryGuard
+    _update_rungs: RungUpdater
+
+    async def setup(self, requirements: StrategyRequirements) -> None:
+        """Resolve the settings, validate the profiles and declare the OHLCV and
+        account state requirements.
+        """
+        self._entry_order = _ENTRY_ORDERS[self.entry_order]
+        self._update_rungs = _RUNG_UPDATERS[self.update_mode]
+        self._reentry_guard = ReentryGuard()
+        self._profiles_by_symbol = {
+            profile.symbol: profile for profile in self.profiles
+        }
+        _validate_profiles(self.profiles)
+        if self.account.capabilities.reserves_margin_on_pending_orders:
+            logger.info(
+                "The exchange reserves margin on pending orders; the envelope "
+                "keeps many resting orders open at once, so only the rungs "
+                "covered by free margin will fill."
+            )
+        _warn_when_resting_rungs_outgrow_the_balance(self.profiles)
+        for profile in self.profiles:
+            requirements.ohlcv.add(
+                profile.symbol, profile.timeframe, profile.average_period
+            )
+        requirements.account.add(
+            self.account,
+            symbols=[profile.symbol for profile in self.profiles],
+            positions=True,
+            open_orders=True,
+            balances=True,
+            sizing=[profile.sizing for profile in self.profiles],
+            executions=True,
+            notify_entry_fills=True,
+            describe_fills=self._describe_fill,
+            margin_targets=_margin_targets(self.profiles),
+        )
+
+    def generate_profile_signals(self, profile: ProfileConfig, ohlcvs: OHLCVs) -> None:
+        """Compute the profile's reference moving average and envelope bands."""
+        symbol = profile.symbol
+        timeframe = profile.timeframe
+        reference = compute_reference(
+            ohlcvs.column(symbol, timeframe, "close"),
+            ohlcvs.column(symbol, timeframe, "high"),
+            ohlcvs.column(symbol, timeframe, "low"),
+            profile.average_type,
+            profile.average_period,
+        )
+        levels = compute_envelope(reference, profile.offsets_by_side)
+        ohlcvs.add_column(symbol, timeframe, profile.reference_column, levels.reference)
+        for side, columns in profile.band_columns.items():
+            for column, band in zip(columns, levels.bands[side], strict=True):
+                ohlcvs.add_column(symbol, timeframe, column, band)
+
+    def book_profile_actions(
+        self,
+        profile: ProfileConfig,
+        ohlcvs: OHLCVs,
+        account_snapshots: AccountSnapshots,
+        timestamp: datetime,
+        bookkeeper: BookKeeper,
+    ) -> None:
+        """Emit the profile's rung-update, entry and protection actions."""
+        account_snapshot = account_snapshots.of(self.account)
+        profile_snapshot = ProfileSnapshot.build(
+            profile, ohlcvs, account_snapshot, self._entry_order
+        )
+        if profile_snapshot.has_nan_levels:
+            logger.warning(
+                f"{profile.profile_id} ({profile.symbol}): envelope levels are NaN, "
+                "cancelling entries and waiting for data to recover"
+            )
+            book_cancel_entries(self.account, profile, profile_snapshot, bookkeeper)
+            return
+
+        reentry_state = self._reentry_guard.state_for(
+            profile.symbol,
+            profile.timeframe,
+            profile.reference_column,
+            ohlcvs,
+            account_snapshot.stop_loss_fills(profile.symbol),
+            timestamp,
+        )
+        position = profile_snapshot.position
+        if position is not None:
+            book_position_protections(
+                self.account,
+                profile,
+                profile_snapshot,
+                position,
+                bookkeeper,
+            )
+            wanted = wanted_while_holding(
+                self.account,
+                profile,
+                profile_snapshot,
+                position,
+                reentry_state,
+                account_snapshot,
+                self._entry_order,
+            )
+        else:
+            wanted = wanted_while_flat(
+                self.account,
+                profile,
+                profile_snapshot,
+                reentry_state,
+                account_snapshot,
+                self._entry_order,
+            )
+
+        self._update_rungs(
+            self.account,
+            profile,
+            profile_snapshot,
+            wanted,
+            bookkeeper,
+        )
+
+    def _describe_fill(self, fill: Execution) -> str | None:
+        """A take-profit sits at the reference, so its fill is the envelope's exit.
+
+        The venue reports every fill on the symbol, so a fill of the configured
+        entry kind is one of the envelope's rungs only when the tag on its
+        client order id says so.
+        """
+        if fill.kind == OrderType.TAKE_PROFIT:
+            return _REFERENCE_EXIT_REASON
+        if not self._entry_order.matches(fill.kind):
+            return None
+        band_index = rung_band_index(fill.client_order_id)
+        if band_index is None:
+            return None
+        offsets = self._profiles_by_symbol[fill.symbol].offsets_by_side
+        return f"entry rung {band_index} of {len(offsets[entered_side(fill.side)])}"
+
+
+def _validate_profiles(profiles: Sequence[ProfileConfig]) -> None:
+    counts = Counter(profile.symbol for profile in profiles)
+    duplicated = sorted(str(symbol) for symbol, count in counts.items() if count > 1)
+    if duplicated:
+        raise StrategyCriticalError(
+            f"Envelope strategy accepts one profile per symbol, "
+            f"got several for: {', '.join(duplicated)}."
+        )
+
+
+def _warn_when_resting_rungs_outgrow_the_balance(
+    profiles: Sequence[ProfileConfig],
+) -> None:
+    share = sum(_resting_balance_share(profile) for profile in profiles)
+    if share > _WHOLE_BALANCE:
+        logger.warning(
+            f"The resting rungs of every profile lock {share:.0%} of the "
+            "balance; the venue refuses the rungs beyond it."
+        )
+
+
+def _resting_balance_share(profile: ProfileConfig) -> float:
+    """A resting rung locks the margin of what it would open, and only a
+    share of the total balance is known before the first candle.
+    """
+    if not isinstance(profile.sizing, TotalBalanceRatio):
+        return 0.0
+    traded_sides = len(profile.rung_counts)
+    return profile.sizing.ratio * traded_sides / profile.leverage
+
+
+def _margin_targets(
+    profiles: Sequence[ProfileConfig],
+) -> dict[Symbol, MarginSettings]:
+    return {
+        profile.symbol: MarginSettings(
+            leverage=profile.leverage, margin_mode=profile.margin_mode
+        )
+        for profile in profiles
+    }

robottraderslab_envelope-0.1.0/src/robottraderslab_envelope/envelope_indicator.py

@@ -0,0 +1,56 @@
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+
+import numpy as np
+import numpy.typing as npt
+
+from robottraderslab.indicators import MAType, donchian_midline, moving_average
+from robottraderslab.strategies import PositionSide
+
+from .profile_config import AverageType
+
+
+@dataclass(frozen=True, slots=True)
+class EnvelopeLevels:
+    """Each side's bands keep the order of the offsets they were computed from."""
+
+    reference: npt.NDArray[np.float64]
+    bands: dict[PositionSide, list[npt.NDArray[np.float64]]]
+
+
+def compute_envelope(
+    reference: npt.NDArray[np.float64],
+    envelopes: Mapping[PositionSide, Iterable[float]],
+) -> EnvelopeLevels:
+    """A band at offset `e` is a fall of `e` in price: from the reference down
+    to the long band, and from the short band back down to the reference, so
+    the short band sits `e / (1 - e)` above the reference.
+    """
+    return EnvelopeLevels(
+        reference=reference,
+        bands={
+            side: [_band(reference, side, offset) for offset in offsets]
+            for side, offsets in envelopes.items()
+        },
+    )
+
+
+def compute_reference(
+    close: npt.NDArray[np.float64],
+    high: npt.NDArray[np.float64],
+    low: npt.NDArray[np.float64],
+    average_type: AverageType,
+    period: int,
+) -> npt.NDArray[np.float64]:
+    """Return the reference the bands sit around, of the kind the profile asks for."""
+    if average_type is AverageType.DCM:
+        return donchian_midline(high, low, period)
+    return moving_average(close, period, MAType(average_type.value))
+
+
+def _band(
+    reference: npt.NDArray[np.float64], side: PositionSide, offset: float
+) -> npt.NDArray[np.float64]:
+    if side is PositionSide.LONG:
+        return reference * (1 - offset)
+    return reference / (1 - offset)

robottraderslab_envelope-0.1.0/src/robottraderslab_envelope/examples/envelope-bot-example.toml

@@ -0,0 +1,34 @@
+[strategy]
+strategy_class = "envelope"
+
+[backtest]
+initial_balance = { USDT = 1000.0 }
+maker_fee_rate = 0.0002
+taker_fee_rate = 0.0005
+start_date = "2025-09-01"
+end_date = "2026-09-01"
+
+[backtest.ohlcv_provider]
+ohlcv_provider = "ccxt_bitget"
+
+[live.ohlcv_provider]
+ohlcv_provider = "bitget"
+
+[live.trading_account]
+exchange = "bitget"
+demo_trading = true
+secret_name = "envelope-example"
+
+[report]
+reference_symbol = "SOL/USDT:USDT"
+
+[[strategy.profiles]]
+symbol = "SOL/USDT:USDT"
+timeframe = "4h"
+total_balance_ratio = 1.0
+leverage = 1.0
+margin_mode = "isolated"
+average_type = "DCM"
+average_period = 5
+envelopes = [0.07, 0.11, 0.15]
+stop_loss_pct = 0.25