AlgoTradeKit 0.7.2__tar.gz → 0.7.3__tar.gz

{algotradekit-0.7.2 → algotradekit-0.7.3}/CHANGELOG.md

@@ -7,6 +7,65 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ---
 
+## [0.7.3] — 2026-06-21
+
+### Added
+
+#### `strategy` module
+- **`Signal.risk_multiplier`** — new optional field (default `1.0`) that scales
+  the size/risk a single signal receives relative to the run's global
+  `SimulateConfig` sizing (`risk_percent` / `fixed_amount` / `fixed_lot`).
+  Lets a strategy vary risk per signal instead of using one fixed sizing
+  rule for every trade in a backtest — e.g. half size on a tentative
+  "limit" entry vs. full size on a confirmed one, or splitting one trade
+  idea into several sub-positions whose sizes sum to one risk unit
+  (three signals at `1/3` each, targeting 1R/2R/3R, to emulate scaling out
+  of a position). Default `1.0` is fully backward compatible.
+
+#### `simulate` module
+- **`SimulateConfig.tp_level_close_fractions`** — optional list, parallel to
+  `tp_levels`, that turns on **true partial closes** for `tp_mode="multi_rr"`.
+  Each entry is the fraction of the position's *original* size to realise
+  when the corresponding level is reached, instead of only moving the SL.
+  `None` (default) preserves the exact pre-0.7.3 behaviour (SL-only
+  advancement, single full close at the final level). When set:
+  - fractions summing to `1.0` give a full progressive scale-out
+    (e.g. `[1/3, 1/3, 1/3]`) — profit is banked level by level instead of
+    all-or-nothing at the end.
+  - all-zero fractions give a "let it run" position: the SL just walks
+    through every level and the full size stays open, trailing at the
+    last level's price, until eventually stopped out.
+  - any mix is valid — partially bank some levels, let others purely
+    advance the SL.
+
+  Each partial close produces its own `ClosedTrade` sharing the position's
+  `trade_id`, so `SimulateReport` statistics (win rate, profit factor,
+  equity curve) count every realised slice on its own line, the same way
+  a real scaled-out position would appear on a broker statement.
+  Commission (pre-charged once, in full, at entry) is split proportionally
+  across every slice so the total charged across one position's full
+  lifetime never changes.
+- **`CLOSE_REASON_TP_PARTIAL`** is now exported from `AlgoTradeKit.simulate`.
+  It existed on `ClosedTrade` since an earlier release (with `is_tp`
+  already wired to recognise it) but no code path had ever produced it
+  until `tp_level_close_fractions` above.
+- `run_multi()` gained the identical partial-close handling as the
+  single-pair `Simulate` engine, so shared-wallet multi-symbol portfolios
+  behave the same way; `run_batch()` needed no changes (it only wraps
+  `Simulate(cfg).run()`).
+
+### Tests
+- `tests/test_strategy.py` — `TestSignal` extended with 5 tests for
+  `risk_multiplier` (default, custom value, `<= 0` validation, positional-
+  construction backward compatibility).
+- `tests/test_simulate.py` — new `TestEngineRiskMultiplier` (4 tests) and
+  `TestEngineMultiRRPartialClose` (8 tests, including a hand-derived PnL
+  ground truth and an end-to-end wallet-conservation check) and
+  `TestSimulateConfigPartialTPValidation` (8 tests). All 171 pre-existing
+  tests in these two files continue to pass unmodified.
+
+---
+
 ## [0.7.2] — 2026-06-20
 
 ### Added

{algotradekit-0.7.2 → algotradekit-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AlgoTradeKit
-Version: 0.7.2
+Version: 0.7.3
 Summary: Algorithmic Trading Toolkit — data collection, indicators, strategy, simulation, and live trading
 Project-URL: Homepage, https://github.com/AmirMohammadBazdar/AlgoTradeKit
 Project-URL: Repository, https://github.com/AmirMohammadBazdar/AlgoTradeKit
@@ -308,12 +308,48 @@ report = Simulate(config).run(strategy_result)
 | `tp_mode` | `"signal"` | `"signal"/"fixed_rr"/"multi_rr"/"none"` |
 | `tp_rr` | 2.0 | R:R ratio for `fixed_rr` mode |
 | `tp_levels` | [1,2,3] | R levels for `multi_rr` mode |
+| `tp_level_close_fractions` | `None` | **v0.7.3** Fraction of original size to realise at each `tp_levels` entry (`multi_rr` only) — see below |
 | `sl_mode` | `"signal"` | `"signal"` or `"trailing"` |
 | `risk_free_enabled` | False | Move SL to break-even at `risk_free_at_rr` |
 | `show_chart` | **False** | **v0.7.0** Open candle chart after run |
 | `report_mode` | **`"none"`** | **v0.7.0** Post-run report rendering |
 | `report_save_path` | `"report.html"` | **v0.7.0** HTML save path |
 
+### Per-Signal Sizing & Partial Take-Profit (v0.7.3)
+
+`Signal.risk_multiplier` scales one signal's size relative to the run's
+sizing config — useful for varying risk by context, or for splitting one
+trade idea into several sub-positions whose sizes sum to one risk unit:
+
+```python
+# Three signals at the same candle, each risking 1/3 of a normal trade,
+# targeting 1R / 2R / 3R — equivalent to scaling out of one position.
+for i, tp_r in enumerate([1, 2, 3], start=1):
+    signals.append(Signal(
+        direction="long", entry_price=entry, stop_loss=sl,
+        take_profit=entry + tp_r * (entry - sl),
+        timestamp=ts, candle_index=idx, timeframe="1h",
+        risk_multiplier=1 / 3,
+    ))
+```
+
+`SimulateConfig.tp_level_close_fractions` turns `multi_rr` into a true
+scale-out — each level realises a real, partial close instead of only
+moving the SL:
+
+```python
+config = SimulateConfig(
+    ...,
+    tp_mode="multi_rr",
+    tp_levels=[1.0, 2.0, 3.0],
+    tp_level_close_fractions=[1 / 3, 1 / 3, 1 / 3],  # bank 1/3 at each level
+)
+```
+
+Set every fraction to `0.0` instead to get the opposite pattern — SL walks
+through every level but nothing closes until the position is eventually
+stopped out, letting winners run with a trailing stop and no fixed target.
+
 ### Batch Sweep
 
 ```python
@@ -562,9 +598,20 @@ Two browser tabs open:
 |---|---|---|
 | `TP_MODE_SIGNAL` | `"signal"` | Use Signal's take_profit |
 | `TP_MODE_FIXED_RR` | `"fixed_rr"` | entry ± `tp_rr` × SL distance |
-| `TP_MODE_MULTI_RR` | `"multi_rr"` | Multiple levels, SL trails |
+| `TP_MODE_MULTI_RR` | `"multi_rr"` | Multiple levels, SL trails (and optionally partially closes — see `tp_level_close_fractions` *(v0.7.3)*) |
 | `TP_MODE_NONE` | `"none"` | No TP |
 
+### Close Reason Constants
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `CLOSE_REASON_SL` | `"sl"` | Stop loss hit |
+| `CLOSE_REASON_TP` | `"tp"` | Take profit hit — nothing left open afterwards |
+| `CLOSE_REASON_TP_PARTIAL` | `"tp_rr"` | **v0.7.3** Intermediate `multi_rr` level partially realised — position still open with reduced size |
+| `CLOSE_REASON_RF` | `"rf"` | Risk-free / trailed SL hit |
+| `CLOSE_REASON_FC` | `"force_close"` | Closed by an `ExitSignal` |
+| `CLOSE_REASON_EOD` | `"end_of_data"` | Still open when data ran out |
+
 ### SL Mode Constants
 
 | Constant | Value | Behaviour |

{algotradekit-0.7.2 → algotradekit-0.7.3}/README.md

@@ -252,12 +252,48 @@ report = Simulate(config).run(strategy_result)
 | `tp_mode` | `"signal"` | `"signal"/"fixed_rr"/"multi_rr"/"none"` |
 | `tp_rr` | 2.0 | R:R ratio for `fixed_rr` mode |
 | `tp_levels` | [1,2,3] | R levels for `multi_rr` mode |
+| `tp_level_close_fractions` | `None` | **v0.7.3** Fraction of original size to realise at each `tp_levels` entry (`multi_rr` only) — see below |
 | `sl_mode` | `"signal"` | `"signal"` or `"trailing"` |
 | `risk_free_enabled` | False | Move SL to break-even at `risk_free_at_rr` |
 | `show_chart` | **False** | **v0.7.0** Open candle chart after run |
 | `report_mode` | **`"none"`** | **v0.7.0** Post-run report rendering |
 | `report_save_path` | `"report.html"` | **v0.7.0** HTML save path |
 
+### Per-Signal Sizing & Partial Take-Profit (v0.7.3)
+
+`Signal.risk_multiplier` scales one signal's size relative to the run's
+sizing config — useful for varying risk by context, or for splitting one
+trade idea into several sub-positions whose sizes sum to one risk unit:
+
+```python
+# Three signals at the same candle, each risking 1/3 of a normal trade,
+# targeting 1R / 2R / 3R — equivalent to scaling out of one position.
+for i, tp_r in enumerate([1, 2, 3], start=1):
+    signals.append(Signal(
+        direction="long", entry_price=entry, stop_loss=sl,
+        take_profit=entry + tp_r * (entry - sl),
+        timestamp=ts, candle_index=idx, timeframe="1h",
+        risk_multiplier=1 / 3,
+    ))
+```
+
+`SimulateConfig.tp_level_close_fractions` turns `multi_rr` into a true
+scale-out — each level realises a real, partial close instead of only
+moving the SL:
+
+```python
+config = SimulateConfig(
+    ...,
+    tp_mode="multi_rr",
+    tp_levels=[1.0, 2.0, 3.0],
+    tp_level_close_fractions=[1 / 3, 1 / 3, 1 / 3],  # bank 1/3 at each level
+)
+```
+
+Set every fraction to `0.0` instead to get the opposite pattern — SL walks
+through every level but nothing closes until the position is eventually
+stopped out, letting winners run with a trailing stop and no fixed target.
+
 ### Batch Sweep
 
 ```python
@@ -506,9 +542,20 @@ Two browser tabs open:
 |---|---|---|
 | `TP_MODE_SIGNAL` | `"signal"` | Use Signal's take_profit |
 | `TP_MODE_FIXED_RR` | `"fixed_rr"` | entry ± `tp_rr` × SL distance |
-| `TP_MODE_MULTI_RR` | `"multi_rr"` | Multiple levels, SL trails |
+| `TP_MODE_MULTI_RR` | `"multi_rr"` | Multiple levels, SL trails (and optionally partially closes — see `tp_level_close_fractions` *(v0.7.3)*) |
 | `TP_MODE_NONE` | `"none"` | No TP |
 
+### Close Reason Constants
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `CLOSE_REASON_SL` | `"sl"` | Stop loss hit |
+| `CLOSE_REASON_TP` | `"tp"` | Take profit hit — nothing left open afterwards |
+| `CLOSE_REASON_TP_PARTIAL` | `"tp_rr"` | **v0.7.3** Intermediate `multi_rr` level partially realised — position still open with reduced size |
+| `CLOSE_REASON_RF` | `"rf"` | Risk-free / trailed SL hit |
+| `CLOSE_REASON_FC` | `"force_close"` | Closed by an `ExitSignal` |
+| `CLOSE_REASON_EOD` | `"end_of_data"` | Still open when data ran out |
+
 ### SL Mode Constants
 
 | Constant | Value | Behaviour |

{algotradekit-0.7.2 → algotradekit-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "AlgoTradeKit"
-version = "0.7.2"
+version = "0.7.3"
 description = "Algorithmic Trading Toolkit — data collection, indicators, strategy, simulation, and live trading"
 readme = "README.md"
 license = { file = "LICENSE" }

{algotradekit-0.7.2 → algotradekit-0.7.3}/src/AlgoTradeKit/__init__.py

@@ -1,4 +1,4 @@
 """AlgoTradeKit — Algorithmic Trading Toolkit"""
 
-__version__ = "0.7.2"
+__version__ = "0.7.3"
 __author__ = "Amir Mohammad Bazdar"

{algotradekit-0.7.2 → algotradekit-0.7.3}/src/AlgoTradeKit/simulate/__init__.py

@@ -99,6 +99,7 @@ from ._position import (
     CLOSE_REASON_RF,
     CLOSE_REASON_SL,
     CLOSE_REASON_TP,
+    CLOSE_REASON_TP_PARTIAL,
     ClosedTrade,
 )
 from ._report import (
@@ -139,6 +140,7 @@ __all__ = [
     "ClosedTrade",
     "CLOSE_REASON_SL",
     "CLOSE_REASON_TP",
+    "CLOSE_REASON_TP_PARTIAL",
     "CLOSE_REASON_RF",
     "CLOSE_REASON_FC",
     "CLOSE_REASON_EOD",

{algotradekit-0.7.2 → algotradekit-0.7.3}/src/AlgoTradeKit/simulate/_config.py

@@ -121,6 +121,37 @@ class SimulateConfig:
         For ``"multi_rr"`` mode: list of R-multiples at which TP levels sit
         (default: ``[1.0, 2.0, 3.0]``).  After each level is hit, SL moves
         to the previous level (0.0 = entry, 1.0 = first TP, etc.).
+    tp_level_close_fractions : list[float] | None
+        For ``"multi_rr"`` mode only.  Optional list, same length as
+        ``tp_levels``, giving the fraction of the position's **original**
+        size to actually realise (partially close) when each corresponding
+        level is reached.  Each value must be in ``[0.0, 1.0]`` and the
+        values must sum to ``<= 1.0``.
+
+        ``None`` (default) preserves the exact pre-v0.7.3 behaviour: no
+        level closes anything — the position's SL simply walks forward
+        through the levels, and only the *final* level fully closes the
+        position.  This default is unchanged for full backward compatibility.
+
+        When provided, every level (including the last) closes **only**
+        the fraction you specify — there is no automatic "close everything"
+        special-case for the final level anymore.  Two common patterns:
+
+        * **Scale out completely** — fractions summing to ``1.0``
+          (e.g. ``[1/3, 1/3, 1/3]`` for ``tp_levels=[1, 2, 3]``) realises
+          profit progressively and leaves nothing open after the last level.
+        * **Trail forever, never auto-realise** — all-zero fractions
+          (e.g. ``[0.0] * 20`` for ``tp_levels=[1, 2, ..., 20]``) never
+          partially closes anything; the SL just keeps stepping up through
+          every level and the full size stays open, trailing at the last
+          level's price, until it is eventually stopped out, force-closed,
+          or hits end-of-data.
+
+        Each partial close produces its own ``ClosedTrade`` (sharing the
+        same ``trade_id`` as the rest of that position's closes), so
+        ``SimulateReport`` statistics count each realised slice separately
+        — matching how a real scaled-out position would show up on a
+        broker statement.
     sl_mode : str
         Stop-loss mode: ``"signal"`` (use SL from Signal) or ``"trailing"``
         (default: ``"signal"``).
@@ -199,6 +230,7 @@ class SimulateConfig:
     tp_mode: str = TP_MODE_SIGNAL
     tp_rr: float = 2.0
     tp_levels: list[float] = field(default_factory=lambda: [1.0, 2.0, 3.0])
+    tp_level_close_fractions: list[float] | None = None
 
     # ------------------------------------------------------------------
     # Stop-loss
@@ -291,6 +323,26 @@ class SimulateConfig:
             raise ValueError(
                 "SimulateConfig.tp_levels must be a non-empty list when tp_mode='multi_rr'."
             )
+        if self.tp_level_close_fractions is not None:
+            if self.tp_mode != TP_MODE_MULTI_RR:
+                raise ValueError(
+                    "SimulateConfig.tp_level_close_fractions requires tp_mode='multi_rr'."
+                )
+            if len(self.tp_level_close_fractions) != len(self.tp_levels):
+                raise ValueError(
+                    "SimulateConfig.tp_level_close_fractions must be the same length as "
+                    f"tp_levels ({len(self.tp_levels)}), got "
+                    f"{len(self.tp_level_close_fractions)}."
+                )
+            if any(not (0.0 <= f <= 1.0) for f in self.tp_level_close_fractions):
+                raise ValueError(
+                    "SimulateConfig.tp_level_close_fractions values must all be in [0.0, 1.0]."
+                )
+            if sum(self.tp_level_close_fractions) > 1.0 + 1e-9:
+                raise ValueError(
+                    "SimulateConfig.tp_level_close_fractions must sum to <= 1.0, got "
+                    f"{sum(self.tp_level_close_fractions)!r}."
+                )
         if not self.config_id:
             self.config_id = self._auto_id()
         if self.report_mode not in (