v4.0.17 no-backtest

docs/contrib/candle_patterns/fractals.md

@@ -1,22 +0,0 @@
-# Fractals
-
-## Table of Contents
-- [fractals](#fractals)
-- [find_bearish_fractal](#fractals.find_bearish_fractal)
-- [find_bullish_fractal](#fractals.find_bullish_fractal)
-
-
-<a id="fractals.find_bearish_fractal"></a>
-### find_bearish_fractal
-```python
-def find_bearish_fractal(candles: Candles) -> Candle | None
-```
-Given a candles object, find the most recent bearish fractal.
-
-
-<a id="fractals.find_bullish_fractal"></a>
-### find_bullish_fractal
-```python
-def find_bullish_fractal(candles: Candles) -> Candle | None
-```
-Given a candles object, find the most recent bullish fractal.

docs/contrib/strategies/chaos.md

@@ -0,0 +1,21 @@
+# chaos
+
+`aiomql.contrib.strategies.chaos` — Random buy/sell demo strategy.
+
+## Overview
+
+The `Chaos` strategy randomly buys or sells on every tick, serving as a minimal
+working example of a `Strategy` subclass. Useful for testing the trading pipeline.
+
+## Classes
+
+### `Chaos`
+
+> Demo strategy that trades randomly.
+
+Inherits from [`Strategy`](../../lib/strategy.md).
+
+#### `trade()`
+
+Generates a random `OrderType` (BUY or SELL) and places a market order via the
+configured trader.

docs/contrib/symbols/forex_symbol.md

@@ -1,90 +1,29 @@
-# ForexSymbol
+# forex_symbol
 
-## Table of Contents
-- [ForexSymbol](#forex_symbol.forex_symbol)
-- [pip](#forex_symbol.pip)
-- [compute_points](#forex_symbol.compute_points)
-- [compute_volume_points](#forex_symbol.compute_volume_points)
-- [compute_volume_sl](#forex_symbol.compute_volume_sl)
+`aiomql.contrib.symbols.forex_symbol` — Forex-specific symbol with pip calculations.
 
+## Overview
 
-<a id="forex_symbol.forex_symbol"></a>
-### ForexSymbol
-```python
-class ForexSymbol(Symbol)
-```
-Subclass of Symbol for Forex Symbols. Handles the computation of stop loss, take profit and volume.
+Extends [`Symbol`](../../lib/symbol.md) with forex-specific logic for pip size,
+pip value, and volume calculations based on currency pairs.
 
-<a id="forex_symbol.pip"></a>
-### pip
-```python
-@property
-def pip()
-```
-Returns the pip value of the symbol. This is ten times the point value for forex symbols.
+## Classes
 
-#### Returns:
-|Type|Description|
-|----|-----------|
-|float|The pip value of the symbol.|
+### `ForexSymbol`
 
-<a id="forex_symbol.compute_points"></a>
-### compute_points
-```python
-def compute_points(*, amount: float, volume: float) -> float
-```
-Compute the number of points required for a trade. Given the amount and the volume of the trade.
+> Symbol subclass tailored for forex instruments.
 
-#### Parameters:
-|Name|Type|Description|
-|----|----|-----------|
-|amount|float|Amount to trade|
-|volume|float|Volume to trade|
+Inherits from [`Symbol`](../../lib/symbol.md).
 
-#### Returns:
-|Type|Description|
-|----|-----------|
-|float|The number of points required for the trade.|
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `pip` | `float` | Pip size for the pair |
 
-<a id="forex_symbol.compute_volume_points"></a>
-### compute_volume_points
-```python
-async def compute_volume_points(*,
-                                amount: float,
-                                points: float,
-                                round_down: bool = False) -> float
-```
-Compute the volume required for a trade. Given the amount and the number of points.
+#### Methods
 
-#### Parameters:
-|Name|Type|Description|
-|----|----|-----------|
-|amount|float|Amount to trade|
-|points|float|Number of points|
-|round_down|bool|round down the computed volume to the nearest step default True|
-
-#### Returns:
-|Type|Description|
-|----|-----------|
-|float|The volume required for the trade.
-
-
-<a id="forex_symbol.compute_volume_sl"></a>
-### compute_volume_sl
-```python
-async def compute_volume_sl(*, amount: float, price: float, sl: float, round_down: bool = False) -> float
-```
-Compute the volume required for a trade. Given the amount, the price and the stop loss.
-
-#### Parameters:
-|Name|Type|Description|
-|----|----|-----------|
-|amount|float|Amount to trade|
-|price|float|Price of the trade|
-|sl|float|Stop loss|
-|round_down|bool|round down the computed volume to the nearest step default True|
-
-#### Returns:
-|Type|Description|
-|----|-----------|
-|float|The volume required for the trade.
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `pip_value(volume)` | `float` | Value of one pip for a given lot size |
+| `pips_to_price(pips)` | `float` | Converts a pip count to a price delta |
+| `price_to_pips(price_delta)` | `float` | Converts a price delta to pips |
+| `calc_volume(amount, pips)` | `float` | Calculates lot size from risk amount and pip distance |

docs/contrib/trackers/open_position.md

@@ -0,0 +1,28 @@
+# open_position
+
+`aiomql.contrib.trackers.open_position` — Open position data container.
+
+## Overview
+
+Defines the `OpenPosition` dataclass that holds the essential details of an open
+MetaTrader 5 position for use by the tracking system.
+
+## Classes
+
+### `OpenPosition`
+
+> Lightweight container for an open position's key fields.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ticket` | `int` | Position ticket number |
+| `symbol` | `str` | Trading instrument |
+| `volume` | `float` | Position volume |
+| `type` | `PositionType` | BUY or SELL |
+| `price_open` | `float` | Entry price |
+| `sl` | `float` | Stop loss level |
+| `tp` | `float` | Take profit level |
+| `profit` | `float` | Current profit |
+| `swap` | `float` | Accumulated swap |
+| `magic` | `int` | EA magic number |
+| `comment` | `str` | Position comment |

docs/contrib/trackers/position_trackers.md

@@ -0,0 +1,46 @@
+# position_trackers
+
+`aiomql.contrib.trackers.position_trackers` — Position and open-positions tracker classes.
+
+## Overview
+
+Provides `PositionTracker` (tracks a single position) and `OpenPositionsTracker`
+(tracks all open positions). Used for executing automated tracking functions
+such as trailing stops and take-profit extensions.
+
+## Classes
+
+### `PositionTracker`
+
+> Tracks a single open position and runs tracking functions.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `position` | `OpenPosition` | The tracked position |
+| `tracker` | `Callable` | The tracking function to execute |
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `track()` | Executes the tracking function for the position |
+| `update()` | Refreshes position data from the terminal |
+
+---
+
+### `OpenPositionsTracker`
+
+> Monitors all open positions and runs trackers on each.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `trackers` | `dict[int, PositionTracker]` | Active trackers keyed by ticket |
+| `tracking_functions` | `dict[str, Callable]` | Registered tracking functions |
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `add_tracking_function(name, func)` | Registers a named tracking function |
+| `track_positions()` | Updates all trackers and runs their tracking functions |
+| `run()` | Main loop — continuously tracks positions |

docs/contrib/trackers/position_tracking_functions.md

@@ -0,0 +1,25 @@
+# position_tracking_functions
+
+`aiomql.contrib.trackers.position_tracking_functions` — Pre-built tracking functions.
+
+## Overview
+
+Provides ready-to-use tracking functions for the [`PositionTracker`](position_trackers.md).
+These functions automate common position-management actions like trailing stops and
+take-profit extensions.
+
+## Functions
+
+### `trailing_stop(position, *, pips, …)`
+
+> Implements a trailing stop loss.
+
+Adjusts the stop loss to trail behind the current price by a specified pip distance.
+Only modifies the stop if the new level is more favourable than the existing one.
+
+### `trailing_take_profit(position, *, pips, …)`
+
+> Extends the take profit as price moves favourably.
+
+Adjusts the take-profit level when the position's profit exceeds a threshold,
+locking in additional gains.

docs/contrib/utils/strategy_tracker.md

@@ -0,0 +1,27 @@
+# strategy_tracker
+
+`aiomql.contrib.utils.strategy_tracker` — Strategy state tracking dataclass.
+
+## Overview
+
+The `StrategyTracker` dataclass keeps track of a strategy's runtime state, including
+trend information, entry prices, and flags.
+
+## Classes
+
+### `StrategyTracker`
+
+> Tracks strategy data and state.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `trend` | `str` | `""` | Current detected trend |
+| `new_trend` | `str` | `""` | Newly detected trend (before confirmation) |
+| `order_type` | `OrderType \| None` | `None` | Current order type |
+| `snooze` | `bool` | `False` | Whether the strategy is in a cool-down period |
+| `entry_price` | `float` | `0.0` | Entry price of the last trade |
+| `exit_price` | `float` | `0.0` | Exit price of the last trade |
+| `sl` | `float` | `0.0` | Current stop loss |
+| `tp` | `float` | `0.0` | Current take profit |
+| `profit` | `float` | `0.0` | Current profit/loss |
+| `*` | … | … | — Additional custom fields —  |