Add supertrend to readme

Author: MDUYN

README.md

@@ -29,6 +29,8 @@ pip install pyindicators
   * [Weighted Moving Average (WMA)](#weighted-moving-average-wma)
   * [Simple Moving Average (SMA)](#simple-moving-average-sma)
   * [Exponential Moving Average (EMA)](#exponential-moving-average-ema)
+  * [SuperTrend Clustering](#supertrend-clustering)
+  * [SuperTrend Basic](#supertrend-basic)
 * [Momentum and Oscillators](#momentum-and-oscillators)
   * [Moving Average Convergence Divergence (MACD)](#moving-average-convergence-divergence-macd)
   * [Relative Strength Index (RSI)](#relative-strength-index-rsi)
@@ -904,6 +906,118 @@ pd_df.tail(10)
 
 ![NADARAYA_WATSON_ENVELOPE](https://github.com/coding-kitties/PyIndicators/blob/main/static/images/indicators/nadaraya_watson_envelope.png)
 
+### Trend Following
+
+Indicators that combine trend detection with adaptive trailing stops.
+
+#### SuperTrend Clustering
+
+The SuperTrend Clustering indicator uses K-means clustering to optimize the ATR multiplier factor for the SuperTrend calculation. It computes multiple SuperTrend variations with different factors, evaluates their performance, and clusters them into "best", "average", and "worst" groups. The best-performing factor is then used to generate an adaptive trailing stop with buy/sell signals.
+
+Based on the LuxAlgo SuperTrend AI indicator concept.
+
+```python
+def supertrend_clustering(
+    data: Union[PdDataFrame, PlDataFrame],
+    atr_length: int = 10,
+    min_mult: float = 1.0,
+    max_mult: float = 5.0,
+    step: float = 0.5,
+    perf_alpha: float = 10.0,
+    from_cluster: str = 'best',
+    max_iter: int = 1000,
+    max_data: int = 10000
+) -> Union[PdDataFrame, PlDataFrame]:
+```
+
+Returns the following columns:
+- `supertrend`: The optimized SuperTrend trailing stop
+- `supertrend_trend`: Current trend (1=bullish, 0=bearish)
+- `supertrend_ama`: Adaptive moving average of SuperTrend
+- `supertrend_perf_idx`: Performance index (0–1 scale)
+- `supertrend_factor`: Currently used ATR factor
+- `supertrend_signal`: 1=buy signal, -1=sell signal, 0=no signal
+
+Example
+
+```python
+from investing_algorithm_framework import download
+
+from pyindicators import supertrend_clustering, get_supertrend_stats
+
+pd_df = download(
+    symbol="btc/eur",
+    market="binance",
+    time_frame="1d",
+    start_date="2023-12-01",
+    end_date="2023-12-25",
+    pandas=True,
+    save=True,
+    storage_path="./data"
+)
+
+# Calculate SuperTrend Clustering
+pd_df = supertrend_clustering(
+    pd_df,
+    atr_length=14,
+    min_mult=2.0,
+    max_mult=6.0,
+    step=0.5,
+    perf_alpha=14.0,
+    from_cluster='best',
+    max_data=500
+)
+
+# Get statistics
+stats = get_supertrend_stats(pd_df)
+print(stats)
+pd_df.tail(10)
+```
+
+![SUPERTREND_CLUSTERING](https://github.com/coding-kitties/PyIndicators/blob/main/static/images/indicators/supertrend_clustering.png)
+
+#### SuperTrend Basic
+
+The basic SuperTrend indicator uses a fixed ATR multiplier factor to create a trend-following trailing stop. When the price is above the SuperTrend line the trend is bullish; when below, bearish. Trend changes generate buy/sell signals.
+
+```python
+def supertrend_basic(
+    data: Union[PdDataFrame, PlDataFrame],
+    atr_length: int = 10,
+    factor: float = 3.0
+) -> Union[PdDataFrame, PlDataFrame]:
+```
+
+Returns the following columns:
+- `supertrend`: The SuperTrend trailing stop value
+- `supertrend_trend`: Current trend (1=bullish, 0=bearish)
+- `supertrend_upper`: Upper band
+- `supertrend_lower`: Lower band
+- `supertrend_signal`: 1=buy signal, -1=sell signal, 0=no signal
+
+Example
+
+```python
+from investing_algorithm_framework import download
+
+from pyindicators import supertrend_basic
+
+pd_df = download(
+    symbol="btc/eur",
+    market="binance",
+    time_frame="1d",
+    start_date="2023-12-01",
+    end_date="2023-12-25",
+    pandas=True,
+    save=True,
+    storage_path="./data"
+)
+
+# Calculate basic SuperTrend
+pd_df = supertrend_basic(pd_df, atr_length=10, factor=3.0)
+pd_df.tail(10)
+```
+
 ### Support and Resistance
 
 Indicators that help identify potential support and resistance levels in the market.