robottraderslab-impulse 0.1.0__tar.gz

robottraderslab_impulse-0.1.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: robottraderslab-impulse
+Version: 0.1.0
+Summary: Impulse trading strategy plugin for the RobotTradersLab engine
+License-Expression: Apache-2.0
+Requires-Dist: robottraderslab>=0.1.0
+Requires-Dist: pandas>=3.0.0
+Requires-Python: >=3.13, <3.14
+Project-URL: Homepage, https://robottraders.io/lab/impulse
+Project-URL: Documentation, https://robottraders.io/lab/docs/impulse.html
+Project-URL: Repository, https://github.com/RobotTraders/RobotTradersLab-Impulse
+Description-Content-Type: text/markdown
+
+# robottraderslab-impulse
+
+Trend following momentum strategy plugin for the RobotTradersLab engine, based on the TRIX indicator and registered under the name `impulse`.
+
+## Documentation
+
+The strategy, its parameters and an example config are on its page at [robottraders.io/lab/docs/impulse](https://robottraders.io/lab/docs/impulse.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_impulse-0.1.0/README.md

@@ -0,0 +1,17 @@
+# robottraderslab-impulse
+
+Trend following momentum strategy plugin for the RobotTradersLab engine, based on the TRIX indicator and registered under the name `impulse`.
+
+## Documentation
+
+The strategy, its parameters and an example config are on its page at [robottraders.io/lab/docs/impulse](https://robottraders.io/lab/docs/impulse.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_impulse-0.1.0/pyproject.toml

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

robottraderslab_impulse-0.1.0/pyproject.toml.orig

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

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/__init__.py

@@ -0,0 +1,5 @@
+from .impulse import ImpulseStrategy
+
+__all__ = [
+    "ImpulseStrategy",
+]

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/chart_indicators.py

@@ -0,0 +1,62 @@
+from typing import Any
+
+from robottraderslab.indicators import MAType, moving_average, trix
+from robottraderslab.strategies import Candles, ChartLine
+
+from .profile_config import (
+    DEFAULT_SIGNAL_TYPE,
+    DEFAULT_TREND_LENGTH,
+    DEFAULT_TREND_TYPE,
+)
+
+
+def get_lightweight_chart_indicators(
+    candles: Candles,
+    indicator_params: dict[str, Any],
+) -> list[ChartLine]:
+    """Draw the trend average beside the candles and TRIX below them.
+
+    Args:
+        indicator_params: `trix_length` and `signal_length` as a profile
+            requires them; `signal_type`, `trend_length` and `trend_type`
+            fall back to the profile defaults.
+    """
+    close = candles.close
+    trix_length = indicator_params["trix_length"]
+    signal_length = indicator_params["signal_length"]
+    signal_type = MAType(indicator_params.get("signal_type", DEFAULT_SIGNAL_TYPE))
+    trend_length = indicator_params.get("trend_length", DEFAULT_TREND_LENGTH)
+    trend_type = MAType(indicator_params.get("trend_type", DEFAULT_TREND_TYPE))
+
+    indicator = trix(
+        close,
+        trix_length,
+        signal_length,
+        signal_type=signal_type,
+    )
+    return [
+        ChartLine(
+            name=f"Trend {trend_type} {trend_length}",
+            values=moving_average(close, trend_length, trend_type),
+            colour="orange",
+        ),
+        ChartLine(
+            name="TRIX",
+            values=indicator.trix,
+            colour="blue",
+            pane="separate",
+        ),
+        ChartLine(
+            name="Signal",
+            values=indicator.signal,
+            colour="red",
+            pane="separate",
+        ),
+        ChartLine(
+            name="Histogram",
+            values=indicator.histogram,
+            colour="gray",
+            pane="separate",
+            shape="histogram",
+        ),
+    ]

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/examples/impulse-bot-example.toml

@@ -0,0 +1,89 @@
+[strategy]
+strategy_class = "impulse"
+
+[backtest]
+initial_balance = { USDT = 1000.0 }
+maker_fee_rate = 0.0002
+taker_fee_rate = 0.0005
+start_date = "2025-04-01"
+end_date = "2026-04-01"
+
+[backtest.ohlcv_provider]
+ohlcv_provider = "ccxt_bitget"
+
+[live.ohlcv_provider]
+ohlcv_provider = "bitget"
+
+[live.trading_account]
+exchange = "bitget"
+demo_trading = true
+secret_name = "impulse-example"
+
+[report]
+reference_symbol = "ETH/USDT:USDT"
+
+[[strategy.profiles]]
+symbol = "ETH/USDT:USDT"
+timeframe = "4h"
+tag = "alpha"
+total_balance_ratio = 0.15
+leverage = 1.0
+trix_length = 8
+signal_length = 12
+trend_length = 180
+trend_type = "EMA"
+
+[[strategy.profiles]]
+symbol = "ETH/USDT:USDT"
+timeframe = "4h"
+tag = "beta"
+total_balance_ratio = 0.15
+leverage = 1.0
+trix_length = 37
+signal_length = 42
+trend_length = 180
+trend_type = "EMA"
+
+[[strategy.profiles]]
+symbol = "ETH/USDT:USDT"
+timeframe = "2h"
+tag = "alpha"
+total_balance_ratio = 0.15
+leverage = 1.0
+trix_length = 15
+signal_length = 27
+trend_length = 360
+trend_type = "EMA"
+
+[[strategy.profiles]]
+symbol = "ETH/USDT:USDT"
+timeframe = "2h"
+tag = "beta"
+total_balance_ratio = 0.15
+leverage = 1.0
+trix_length = 43
+signal_length = 16
+trend_length = 360
+trend_type = "EMA"
+
+[[strategy.profiles]]
+symbol = "ETH/USDT:USDT"
+timeframe = "1h"
+tag = "alpha"
+total_balance_ratio = 0.15
+leverage = 1.0
+trix_length = 30
+signal_length = 45
+trend_length = 720
+trend_type = "EMA"
+
+[[strategy.profiles]]
+symbol = "ETH/USDT:USDT"
+timeframe = "1h"
+tag = "beta"
+total_balance_ratio = 0.15
+leverage = 1.0
+trix_length = 32
+signal_length = 33
+trend_length = 720
+trend_type = "EMA"

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/examples/impulse-optimisation-example.toml

@@ -0,0 +1,38 @@
+[strategy]
+strategy_class = "impulse"
+
+[backtest]
+initial_balance = { USDT = 1000.0 }
+maker_fee_rate = 0.0002
+taker_fee_rate = 0.0005
+start_date = "2025-04-01"
+end_date = "2026-04-01"
+
+[backtest.ohlcv_provider]
+ohlcv_provider = "ccxt_bitget"
+
+[[strategy.profiles]]
+symbol = "ETH/USDT:USDT"
+timeframe = "4h"
+total_balance_ratio = 1.0
+leverage = 1.0
+trix_length = 8
+signal_length = 12
+trend_length = 180
+trend_type = "EMA"
+
+[optimisation]
+
+[[optimisation.parameter_configs]]
+parameter = "strategy.profiles.trix_length"
+sampling = "linear"
+min = 5.0
+max = 50.0
+num_samples = 10
+
+[[optimisation.parameter_configs]]
+parameter = "strategy.profiles.signal_length"
+sampling = "linear"
+min = 5.0
+max = 50.0
+num_samples = 10

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/examples/registry.example.toml

@@ -0,0 +1,3 @@
+[[bot]]
+config = "impulse-bot-example/impulse-bot-example.toml"
+timeframes = ["1h", "2h", "4h"]

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/examples/run_backtest.ipynb

@@ -0,0 +1,141 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "7fb27b941602401d91542211134fc71a",
+   "metadata": {},
+   "source": [
+    "# Impulse Strategy — Backtest\n",
+    "\n",
+    "Runs the strategy defined in `impulse-bot-example.toml` over historical data and reviews the results."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "acae54e37e7d407bbb7b55eff062a284",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from robottraderslab import BotConfig, run_backtest"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9a63283cbaf04dbcab1f6479b197f3a8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = run_backtest(BotConfig.from_file(\"impulse-bot-example.toml\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8dd0d8092fe74a7c96281538738b07e2",
+   "metadata": {},
+   "source": [
+    "## Performance Overview"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "72eea5119410473aa328ad9291626812",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "analyser = results.create_analyser()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8edb47106e1a46a883d545849b8ab81b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "analyser.plot_performance_summary()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "10185d26023b46108eb7d9f57d49d2b3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "analyser.print_performance_summary()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8763a12b2bbd4a93a75aff182afb95dc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "analyser.plot_equity_curve()\n",
+    "analyser.plot_drawdown()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7623eae2785240b9bd12b16a66d81610",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "analyser.plot_cumulative_pnl_by_trade()\n",
+    "analyser.plot_monthly_performance(year=\"all\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "7cdc8c89c7104fffa095e18ddfef8986",
+   "metadata": {},
+   "source": [
+    "## Indicator Chart"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b118ea5561624da68c537baed56e602f",
+   "metadata": {},
+   "outputs": [],
+   "source": "analyser.plot_candlesticks(indicators_name=\"impulse\")"
+  },
+  {
+   "cell_type": "markdown",
+   "id": "938c804e27f84196a10c8828c723f798",
+   "metadata": {},
+   "source": [
+    "## Trades"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "504fb2a444614c0babb325280ed9130a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "analyser.trades"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/examples/run_optimisation.ipynb

@@ -0,0 +1,92 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "7fb27b941602401d91542211134fc71a",
+   "metadata": {},
+   "source": [
+    "# Impulse Strategy — Parameter Optimisation\n",
+    "\n",
+    "Grid-searches the parameter ranges in `impulse-optimisation-example.toml` and plots the results."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "acae54e37e7d407bbb7b55eff062a284",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from robottraderslab import BotConfig, run_grid_search"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9a63283cbaf04dbcab1f6479b197f3a8",
+   "metadata": {},
+   "source": [
+    "## Run Grid Search"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8dd0d8092fe74a7c96281538738b07e2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = run_grid_search(BotConfig.from_file(\"impulse-optimisation-example.toml\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "72eea5119410473aa328ad9291626812",
+   "metadata": {},
+   "source": [
+    "## Parameter Heatmaps"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8edb47106e1a46a883d545849b8ab81b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results.plot_heatmap_summary(smoothing=1.0)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "10185d26023b46108eb7d9f57d49d2b3",
+   "metadata": {},
+   "source": [
+    "## Export Results"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8763a12b2bbd4a93a75aff182afb95dc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "csv_path = results.to_csv()\n",
+    "print(f\"Exported to {csv_path}\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/examples/secrets.example.toml

@@ -0,0 +1,5 @@
+[[secrets]]
+name = "impulse-example"
+api_key = ""
+secret_key = ""
+passphrase = ""

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/impulse.py

@@ -0,0 +1,209 @@
+from collections.abc import Sequence
+from datetime import datetime
+from typing import ClassVar
+
+from robottraderslab import Symbol, TimeFrame
+from robottraderslab.exceptions import StrategyCriticalError
+from robottraderslab.strategies import (
+    AccountSnapshots,
+    BookKeeper,
+    MarketType,
+    OHLCVs,
+    PositionTracker,
+    ProfileStrategy,
+    StrategyRequirements,
+    SymbolTimeframe,
+    TrackingId,
+)
+from robottraderslab.strategies.futures import FuturesAccount, MarginSettings
+
+from .impulse_indicator import compute_signals
+from .position_orders import book_entry, book_exit, wanted_entry_side, wants_exit
+from .position_protection import book_position_protections
+from .position_tracking import tags_by_profile_id, tracked_symbols
+from .profile_config import ProfileConfig
+from .profile_snapshot import ProfileSnapshot
+
+
+class ImpulseStrategy(ProfileStrategy[ProfileConfig]):
+    """Momentum strategy: enters on a TRIX crossover that agrees with the trend.
+
+    Each profile covers one symbol on one timeframe. Profiles may stack on the
+    same symbol, each opening and closing its own position independently.
+    """
+
+    market_type: ClassVar[MarketType] = "futures"
+
+    account: FuturesAccount
+    _position_tracker: PositionTracker
+    _closing_profile_ids: set[TrackingId]
+
+    async def setup(self, requirements: StrategyRequirements) -> None:
+        """
+        Raises:
+            StrategyCriticalError: If a profile's tag is too long, or two
+                profiles on the same symbol resolve to the same tag or disagree
+                on stop_loss_pct, leverage or margin_mode.
+        """
+        _validate_stop_loss_agreement(self.profiles)
+        margin_targets = _margin_targets(self.profiles)
+
+        lookbacks = _lookbacks_by_timeframe(self.profiles)
+        for symbol_timeframe in _symbol_timeframes(self.profiles):
+            requirements.ohlcv.add(
+                symbol_timeframe.symbol,
+                symbol_timeframe.timeframe,
+                lookbacks[symbol_timeframe.timeframe],
+            )
+
+        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],
+            margin_targets=margin_targets,
+        )
+        self._position_tracker = requirements.tracker.add(
+            account=self.account,
+            symbols=tracked_symbols(self.profiles),
+            tags=tags_by_profile_id(self.profiles),
+        )
+
+    def generate_profile_signals(self, profile: ProfileConfig, ohlcvs: OHLCVs) -> None:
+        """Compute the profile's TRIX entry and exit signal columns."""
+        symbol = profile.symbol
+        timeframe = profile.timeframe
+        signals = compute_signals(
+            ohlcvs.column(symbol, timeframe, "close"),
+            profile.trix_length,
+            profile.signal_length,
+            profile.signal_type,
+            profile.trend_length,
+            profile.trend_type,
+        )
+        ohlcvs.add_column(
+            symbol, timeframe, profile.long_entry_column, signals.long_entry
+        )
+        ohlcvs.add_column(
+            symbol, timeframe, profile.long_exit_column, signals.long_exit
+        )
+        ohlcvs.add_column(
+            symbol, timeframe, profile.short_entry_column, signals.short_entry
+        )
+        ohlcvs.add_column(
+            symbol, timeframe, profile.short_exit_column, signals.short_exit
+        )
+
+    def book_general_actions(
+        self,
+        ohlcvs: OHLCVs,
+        account_snapshots: AccountSnapshots,
+        timestamp: datetime,
+        bookkeeper: BookKeeper,
+        triggered_timeframes: list[TimeFrame],
+    ) -> None:
+        self._closing_profile_ids = set()
+
+    def book_profile_actions(
+        self,
+        profile: ProfileConfig,
+        ohlcvs: OHLCVs,
+        account_snapshots: AccountSnapshots,
+        timestamp: datetime,
+        bookkeeper: BookKeeper,
+    ) -> None:
+        """Emit the profile's entry or exit action for the current candle."""
+        profile_snapshot = ProfileSnapshot.build(
+            profile, ohlcvs, self._position_tracker
+        )
+        if profile_snapshot.has_no_price:
+            return
+
+        position = profile_snapshot.position
+        if position is not None:
+            if wants_exit(position, profile_snapshot):
+                self._closing_profile_ids.add(profile.profile_id)
+                book_exit(self.account, profile, position, bookkeeper)
+            return
+
+        side = wanted_entry_side(profile, profile_snapshot)
+        if side is None:
+            return
+        book_entry(
+            self.account,
+            profile,
+            side,
+            profile_snapshot,
+            account_snapshots.of(self.account),
+            bookkeeper,
+        )
+
+    def book_final_actions(
+        self,
+        ohlcvs: OHLCVs,
+        account_snapshots: AccountSnapshots,
+        timestamp: datetime,
+        bookkeeper: BookKeeper,
+        triggered_timeframes: list[TimeFrame],
+    ) -> None:
+        """Protect every open position, sparing the ones closing this candle."""
+        book_position_protections(
+            self.account,
+            self.profiles,
+            self._position_tracker,
+            account_snapshots.of(self.account),
+            self._closing_profile_ids,
+            bookkeeper,
+        )
+
+
+def _validate_stop_loss_agreement(profiles: Sequence[ProfileConfig]) -> None:
+    percentages_by_symbol: dict[Symbol, set[float | None]] = {}
+    for profile in profiles:
+        percentages_by_symbol.setdefault(profile.symbol, set()).add(
+            profile.stop_loss_pct
+        )
+    for symbol, percentages in percentages_by_symbol.items():
+        if len(percentages) > 1:
+            raise StrategyCriticalError(
+                f"Profiles on {symbol} set conflicting stop_loss_pct values. A symbol "
+                f"has a single net position with one stop-loss, so stacked profiles "
+                f"must all use the same stop_loss_pct (or all leave it unset)."
+            )
+
+
+def _margin_targets(profiles: Sequence[ProfileConfig]) -> dict[Symbol, MarginSettings]:
+    targets: dict[Symbol, MarginSettings] = {}
+    for profile in profiles:
+        wanted = MarginSettings(
+            leverage=profile.leverage, margin_mode=profile.margin_mode
+        )
+        declared = targets.setdefault(profile.symbol, wanted)
+        if declared != wanted:
+            raise StrategyCriticalError(
+                f"Profiles on {profile.symbol} set conflicting leverage or "
+                f"margin_mode values. A symbol trades at one leverage in one "
+                f"margin mode, so stacked profiles must all use the same ones."
+            )
+    return targets
+
+
+def _lookbacks_by_timeframe(profiles: Sequence[ProfileConfig]) -> dict[TimeFrame, int]:
+    lookbacks: dict[TimeFrame, int] = {}
+    for profile in profiles:
+        needed = max(profile.trix_length, profile.signal_length, profile.trend_length)
+        lookbacks[profile.timeframe] = max(lookbacks.get(profile.timeframe, 0), needed)
+    return lookbacks
+
+
+def _symbol_timeframes(profiles: Sequence[ProfileConfig]) -> list[SymbolTimeframe]:
+    unique: dict[tuple[Symbol, TimeFrame], SymbolTimeframe] = {}
+    for profile in profiles:
+        key = (profile.symbol, profile.timeframe)
+        unique.setdefault(
+            key,
+            SymbolTimeframe(symbol=profile.symbol, timeframe=profile.timeframe),
+        )
+    return list(unique.values())

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/impulse_indicator.py

@@ -0,0 +1,62 @@
+from dataclasses import dataclass
+
+import numpy as np
+import numpy.typing as npt
+
+from robottraderslab.indicators import MAType, moving_average, trix
+
+
+@dataclass(frozen=True, slots=True)
+class ImpulseSignals:
+    """The candles a side may be entered or exited on, one boolean per candle."""
+
+    long_entry: npt.NDArray[np.bool_]
+    long_exit: npt.NDArray[np.bool_]
+    short_entry: npt.NDArray[np.bool_]
+    short_exit: npt.NDArray[np.bool_]
+
+
+def compute_signals(
+    close: npt.NDArray[np.float64],
+    trix_length: int,
+    signal_length: int,
+    signal_type: MAType,
+    trend_length: int,
+    trend_type: MAType,
+) -> ImpulseSignals:
+    """Return the entry and exit candles for both sides.
+
+    A side is open while the TRIX histogram agrees with price sitting the
+    same side of the trend average, so a run of agreeing candles trades once.
+    """
+    indicator = trix(
+        close,
+        trix_length,
+        signal_length,
+        signal_type=signal_type,
+    )
+    trend = moving_average(close, trend_length, trend_type)
+
+    long_open = (indicator.histogram > 0) & (close > trend)
+    short_open = (indicator.histogram < 0) & (close < trend)
+
+    return ImpulseSignals(
+        long_entry=_starts(long_open),
+        long_exit=_ends(long_open),
+        short_entry=_starts(short_open),
+        short_exit=_ends(short_open),
+    )
+
+
+def _starts(open_bars: npt.NDArray[np.bool_]) -> npt.NDArray[np.bool_]:
+    return open_bars & ~_previous(open_bars)
+
+
+def _ends(open_bars: npt.NDArray[np.bool_]) -> npt.NDArray[np.bool_]:
+    return ~open_bars & _previous(open_bars)
+
+
+def _previous(open_bars: npt.NDArray[np.bool_]) -> npt.NDArray[np.bool_]:
+    shifted = np.roll(open_bars, 1)
+    shifted[0] = False
+    return shifted

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/position_orders.py

@@ -0,0 +1,84 @@
+from robottraderslab.strategies import (
+    AccountSnapshot,
+    BookKeeper,
+    PositionSide,
+    TrackedPosition,
+)
+from robottraderslab.strategies.futures import FuturesAccount
+
+from .position_protection import stop_loss_trigger_price
+from .profile_config import ProfileConfig
+from .profile_snapshot import ProfileSnapshot
+
+_ENTRY_REASONS = {
+    PositionSide.LONG: "impulse long entry",
+    PositionSide.SHORT: "impulse short entry",
+}
+_EXIT_REASONS = {
+    PositionSide.LONG: "impulse long exit",
+    PositionSide.SHORT: "impulse short exit",
+}
+
+
+def wanted_entry_side(
+    profile: ProfileConfig, profile_snapshot: ProfileSnapshot
+) -> PositionSide | None:
+    """Return the side this profile wants to open on this candle, or None.
+
+    A profile decides alone. Profiles stacked on one symbol may disagree, and
+    the venue nets their orders into the single position it holds.
+    """
+    if not profile.short_only and profile_snapshot.long_entry:
+        return PositionSide.LONG
+    if not profile.long_only and profile_snapshot.short_entry:
+        return PositionSide.SHORT
+    return None
+
+
+def wants_exit(position: TrackedPosition, profile_snapshot: ProfileSnapshot) -> bool:
+    """Report whether the held position's own side is being told to leave."""
+    if position.side == PositionSide.LONG:
+        return profile_snapshot.long_exit
+    return profile_snapshot.short_exit
+
+
+def book_entry(
+    account: FuturesAccount,
+    profile: ProfileConfig,
+    side: PositionSide,
+    profile_snapshot: ProfileSnapshot,
+    account_snapshot: AccountSnapshot,
+    bookkeeper: BookKeeper,
+) -> None:
+    symbol = profile.symbol
+    entry = (
+        account.long_entry(symbol)
+        if side == PositionSide.LONG
+        else account.short_entry(symbol)
+    )
+    entry = (
+        entry.size(profile.sizing, profile_snapshot.price, account_snapshot)
+        .tag(profile.order_tag)
+        .reason(_ENTRY_REASONS[side])
+    )
+    if profile.stop_loss_pct is not None:
+        entry = entry.stop_loss(
+            price=stop_loss_trigger_price(
+                side, profile_snapshot.price, profile.stop_loss_pct
+            )
+        )
+    bookkeeper.add(entry.build())
+
+
+def book_exit(
+    account: FuturesAccount,
+    profile: ProfileConfig,
+    position: TrackedPosition,
+    bookkeeper: BookKeeper,
+) -> None:
+    exit_order = (
+        account.close_tracked_position(profile.symbol, position)
+        .tag(profile.order_tag)
+        .reason(_EXIT_REASONS[position.side])
+    )
+    bookkeeper.add(exit_order.build())

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/position_protection.py

@@ -0,0 +1,86 @@
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from robottraderslab import Symbol
+from robottraderslab.strategies import (
+    AccountSnapshot,
+    BookKeeper,
+    PositionSide,
+    PositionTracker,
+    TrackingId,
+)
+from robottraderslab.strategies.futures import FuturesAccount
+
+from .profile_config import ProfileConfig
+
+
+@dataclass(frozen=True, slots=True)
+class _Protection:
+    """The stop-loss one symbol's open profiles ask for, and who is asking."""
+
+    stop_loss_pct: float
+    profile_ids: frozenset[TrackingId]
+
+
+def book_position_protections(
+    account: FuturesAccount,
+    profiles: Sequence[ProfileConfig],
+    position_tracker: PositionTracker,
+    account_snapshot: AccountSnapshot,
+    closing_profile_ids: set[TrackingId],
+    bookkeeper: BookKeeper,
+) -> None:
+    """Move each held position's stop-loss to its configured distance.
+
+    A symbol whose every open profile is closing this candle keeps no position
+    to protect, so its stop-loss is cancelled.
+    """
+    for symbol, protection in _protections(profiles, position_tracker).items():
+        if protection.profile_ids <= closing_profile_ids:
+            for order in account_snapshot.stop_loss_orders(symbol):
+                bookkeeper.add(account.cancel_order(symbol, order.order_id))
+            continue
+        position = account_snapshot.position(symbol)
+        if position is None:
+            continue
+        bookkeeper.add(
+            account.move_stop_loss(
+                symbol,
+                stop_loss_trigger_price(
+                    position.side,
+                    position.average_entry_price,
+                    protection.stop_loss_pct,
+                ),
+            )
+        )
+
+
+def stop_loss_trigger_price(
+    side: PositionSide, reference_price: float, stop_loss_pct: float
+) -> float:
+    """Return the trigger price a stop-loss sits at, on either side."""
+    if side == PositionSide.LONG:
+        return reference_price * (1 - stop_loss_pct)
+    return reference_price * (1 + stop_loss_pct)
+
+
+def _protections(
+    profiles: Sequence[ProfileConfig], position_tracker: PositionTracker
+) -> dict[Symbol, _Protection]:
+    """Collect the stop-loss each symbol holding a position asks for.
+
+    Profiles sharing a symbol are validated to agree on the distance, so the
+    first of them speaks for all.
+    """
+    open_profiles: dict[Symbol, list[ProfileConfig]] = {}
+    for profile in profiles:
+        if position_tracker.get(profile.profile_id) is not None:
+            open_profiles.setdefault(profile.symbol, []).append(profile)
+    return {
+        symbol: _Protection(
+            stop_loss_pct=stop_loss_pct,
+            profile_ids=frozenset(profile.profile_id for profile in on_symbol),
+        )
+        for symbol, on_symbol in open_profiles.items()
+        if (stop_loss_pct := on_symbol[0].stop_loss_pct) is not None
+    }

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/position_tracking.py

@@ -0,0 +1,18 @@
+from collections.abc import Sequence
+
+from robottraderslab import Symbol
+from robottraderslab.strategies import ProfileTag, TrackingId
+
+from .profile_config import ProfileConfig
+
+
+def tags_by_profile_id(
+    profiles: Sequence[ProfileConfig],
+) -> dict[TrackingId, ProfileTag]:
+    """Return the tag each profile's own orders carry."""
+    return {profile.profile_id: profile.order_tag for profile in profiles}
+
+
+def tracked_symbols(profiles: Sequence[ProfileConfig]) -> dict[TrackingId, Symbol]:
+    """Return the symbol each profile's tracked position trades."""
+    return {profile.profile_id: profile.symbol for profile in profiles}

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/profile_config.py

@@ -0,0 +1,72 @@
+from dataclasses import dataclass
+from functools import cached_property
+
+from robottraderslab.exceptions import StrategyCriticalError
+from robottraderslab.indicators import MAType
+from robottraderslab.strategies import Profile
+from robottraderslab.strategies.futures import (
+    MarginMode,
+    SizingRule,
+)
+
+DEFAULT_SIGNAL_TYPE = MAType.SMA
+DEFAULT_TREND_LENGTH = 200
+DEFAULT_TREND_TYPE = MAType.SMA
+
+
+@dataclass(frozen=True, kw_only=True)
+class TrixParameters:
+    """The lengths and averages the TRIX signals are built from."""
+
+    trix_length: int
+    signal_length: int
+    signal_type: MAType = DEFAULT_SIGNAL_TYPE
+    trend_length: int = DEFAULT_TREND_LENGTH
+    trend_type: MAType = DEFAULT_TREND_TYPE
+
+
+@dataclass(frozen=True, kw_only=True)
+class ProfileConfig(Profile, TrixParameters):
+    """One symbol traded on one timeframe, with its own TRIX settings and sizing.
+
+    Profiles may stack on the same symbol, each holding its own position.
+    """
+
+    sizing: SizingRule
+    leverage: float = 1.0
+    margin_mode: MarginMode = MarginMode.ISOLATED
+    long_only: bool = False
+    short_only: bool = False
+    stop_loss_pct: float | None = None
+
+    def __post_init__(self) -> None:
+        """
+        Raises:
+            StrategyCriticalError: If both direction flags are set, or the
+                stop-loss is not a fraction of the entry price.
+        """
+        if self.long_only and self.short_only:
+            raise StrategyCriticalError(
+                "long_only and short_only cannot both be true; leave both out to "
+                "trade both directions"
+            )
+        if self.stop_loss_pct is not None and not 0 < self.stop_loss_pct < 1:
+            raise StrategyCriticalError(
+                f"stop_loss_pct must be in (0, 1), got {self.stop_loss_pct}"
+            )
+
+    @cached_property
+    def long_entry_column(self) -> str:
+        return f"{self.profile_id}_long_entry"
+
+    @cached_property
+    def long_exit_column(self) -> str:
+        return f"{self.profile_id}_long_exit"
+
+    @cached_property
+    def short_entry_column(self) -> str:
+        return f"{self.profile_id}_short_entry"
+
+    @cached_property
+    def short_exit_column(self) -> str:
+        return f"{self.profile_id}_short_exit"

robottraderslab_impulse-0.1.0/src/robottraderslab_impulse/profile_snapshot.py

@@ -0,0 +1,42 @@
+import math
+from dataclasses import dataclass
+from typing import Self
+
+from robottraderslab.strategies import OHLCVs, PositionTracker, TrackedPosition
+
+from .profile_config import ProfileConfig
+
+
+@dataclass(frozen=True, slots=True)
+class ProfileSnapshot:
+    """Per-profile view of the current candle: its signals plus tracked state."""
+
+    price: float
+    long_entry: bool
+    long_exit: bool
+    short_entry: bool
+    short_exit: bool
+    position: TrackedPosition | None
+
+    @classmethod
+    def build(
+        cls,
+        profile: ProfileConfig,
+        ohlcvs: OHLCVs,
+        position_tracker: PositionTracker,
+    ) -> Self:
+        """Read one profile's signals and tracked position for the current candle."""
+        symbol = profile.symbol
+        timeframe = profile.timeframe
+        return cls(
+            price=ohlcvs.current(symbol, timeframe, "close"),
+            long_entry=ohlcvs.signal(symbol, timeframe, profile.long_entry_column),
+            long_exit=ohlcvs.signal(symbol, timeframe, profile.long_exit_column),
+            short_entry=ohlcvs.signal(symbol, timeframe, profile.short_entry_column),
+            short_exit=ohlcvs.signal(symbol, timeframe, profile.short_exit_column),
+            position=position_tracker.get(profile.profile_id),
+        )
+
+    @property
+    def has_no_price(self) -> bool:
+        return math.isnan(self.price)