Add new indicators: Buy-Side/Sell-Side Liquidity, Liquidity Sweeps, Volume-Gated Trend Ribbon; update Order Blocks and SuperTrend; add tests and images for new indicators.

Author: MDUYN

README.md

@@ -83,6 +83,8 @@ pip install pyindicators
   * [Order Blocks](#order-blocks)
   * [Market Structure Break](#market-structure-break)
   * [Market Structure CHoCH/BOS](#market-structure-chochbos)
+  * [Liquidity Sweeps](#liquidity-sweeps)
+  * [Buyside & Sellside Liquidity](#buyside--sellside-liquidity)
 * [Pattern recognition](#pattern-recognition)
   * [Detect Peaks](#detect-peaks)
   * [Detect Bullish Divergence](#detect-bullish-divergence)
@@ -1678,6 +1680,152 @@ The function returns:
 
 ![MARKET_STRUCTURE_CHOCH_BOS](https://github.com/coding-kitties/PyIndicators/blob/main/static/images/indicators/market_structure_choch_bos.png)
 
+#### Liquidity Sweeps
+
+Liquidity Sweeps is a Smart Money Concept indicator that detects when price momentarily pierces a swing high or swing low—grabbing resting liquidity—before reversing. This behaviour is a hallmark of institutional order flow: stop-loss clusters sitting above swing highs (buyside liquidity) or below swing lows (sellside liquidity) get triggered, and price quickly snaps back.
+
+Three detection modes are available:
+
+- **Wicks** – the candle wick pierces the swing level but the close remains on the original side.
+- **Outbreak / Retest** – price closes beyond the level, then a later candle retests it from the other side while closing back.
+- **All** – combines both wick and outbreak/retest sweeps.
+
+```python
+def liquidity_sweeps(
+    data: Union[PdDataFrame, PlDataFrame],
+    swing_length: int = 5,
+    mode: str = "wicks",
+    high_column: str = "High",
+    low_column: str = "Low",
+    close_column: str = "Close",
+    bullish_sweep_column: str = "liq_sweep_bullish",
+    bearish_sweep_column: str = "liq_sweep_bearish",
+    sweep_high_column: str = "liq_sweep_high",
+    sweep_low_column: str = "liq_sweep_low",
+    sweep_type_column: str = "liq_sweep_type",
+) -> Union[PdDataFrame, PlDataFrame]:
+```
+
+Example
+
+```python
+import pandas as pd
+from pyindicators import (
+    liquidity_sweeps,
+    liquidity_sweep_signal,
+    get_liquidity_sweep_stats
+)
+
+# Create sample OHLC data
+df = pd.DataFrame({
+    'High': [...],
+    'Low': [...],
+    'Close': [...]
+})
+
+# Detect liquidity sweeps (wick-through mode)
+df = liquidity_sweeps(df, swing_length=5, mode="wicks")
+print(df[['liq_sweep_bullish', 'liq_sweep_bearish', 'liq_sweep_high', 'liq_sweep_low']])
+
+# Generate trading signals
+# 1 = bullish sweep, -1 = bearish sweep, 0 = no sweep
+df = liquidity_sweep_signal(df)
+bullish_sweeps = df[df['liq_sweep_signal'] == 1]
+
+# Get statistics
+stats = get_liquidity_sweep_stats(df)
+print(f"Total bullish sweeps: {stats['total_bullish']}")
+print(f"Total bearish sweeps: {stats['total_bearish']}")
+```
+
+The function returns:
+- `liq_sweep_bullish`: 1 when a bullish liquidity sweep is detected (sell-side liquidity grabbed)
+- `liq_sweep_bearish`: 1 when a bearish liquidity sweep is detected (buy-side liquidity grabbed)
+- `liq_sweep_high`: Price level of the swept swing high
+- `liq_sweep_low`: Price level of the swept swing low
+- `liq_sweep_type`: Type of sweep (`"wick"` or `"outbreak_retest"`)
+
+**Trading Strategy:**
+- Bullish sweeps below swing lows indicate potential long entries (smart money accumulation)
+- Bearish sweeps above swing highs indicate potential short entries (smart money distribution)
+- Use the sweep level (`liq_sweep_high` / `liq_sweep_low`) as a reference for stop-loss placement
+
+![LIQUIDITY_SWEEPS](https://github.com/coding-kitties/PyIndicators/blob/main/static/images/indicators/liquidity_sweeps.png)
+
+#### Buyside & Sellside Liquidity
+
+Buyside & Sellside Liquidity is a Smart Money Concept indicator that identifies clustered swing-point liquidity pools, their breaches, and optional liquidity voids.
+
+A *buyside liquidity level* forms when multiple swing highs (≥ `min_cluster_count`) cluster within an ATR-scaled margin band. A *sellside liquidity level* is the mirror image for swing lows. When price breaks through a level, a *breach* is recorded. Optionally, *liquidity voids* (large directional candles with minimal overlap) can be detected as areas price is likely to revisit.
+
+```python
+def buyside_sellside_liquidity(
+    data: Union[PdDataFrame, PlDataFrame],
+    detection_length: int = 7,
+    margin: float = 6.9,
+    buyside_margin: float = 2.3,
+    sellside_margin: float = 2.3,
+    detect_voids: bool = False,
+    atr_period: int = 10,
+    atr_void_period: int = 200,
+    min_cluster_count: int = 3,
+    max_swings: int = 50,
+    high_column: str = "High",
+    low_column: str = "Low",
+    open_column: str = "Open",
+    close_column: str = "Close",
+) -> Union[PdDataFrame, PlDataFrame]:
+```
+
+Example
+
+```python
+import pandas as pd
+from pyindicators import (
+    buyside_sellside_liquidity,
+    buyside_sellside_liquidity_signal,
+    get_buyside_sellside_liquidity_stats
+)
+
+# Create sample OHLC data
+df = pd.DataFrame({
+    'Open': [...],
+    'High': [...],
+    'Low': [...],
+    'Close': [...]
+})
+
+# Detect buyside and sellside liquidity levels
+df = buyside_sellside_liquidity(df, detection_length=7, detect_voids=True)
+print(df[['buyside_liq_level', 'sellside_liq_level', 'buyside_liq_broken', 'sellside_liq_broken']])
+
+# Generate trading signals
+# 1 = sellside breached (may reverse up), -1 = buyside breached (may reverse down)
+df = buyside_sellside_liquidity_signal(df)
+breach_events = df[df['bsl_signal'] != 0]
+
+# Get statistics
+stats = get_buyside_sellside_liquidity_stats(df)
+print(f"Buyside levels: {stats['total_buyside_levels']}")
+print(f"Sellside levels: {stats['total_sellside_levels']}")
+print(f"Total breaches: {stats['total_breaches']}")
+```
+
+The function returns:
+- `buyside_liq_level` / `sellside_liq_level`: Price of the liquidity level
+- `buyside_liq_top` / `buyside_liq_bottom`: Upper and lower bounds of the buyside zone
+- `sellside_liq_top` / `sellside_liq_bottom`: Upper and lower bounds of the sellside zone
+- `buyside_liq_broken` / `sellside_liq_broken`: 1 when the level is breached
+- `liq_void_bullish` / `liq_void_bearish`: 1 when a liquidity void is detected (if `detect_voids=True`)
+- `liq_void_top` / `liq_void_bottom`: Bounds of the void zone
+
+**Trading Strategy:**
+- Buyside levels act as resistance; a breach signals institutional selling (potential reversal down)
+- Sellside levels act as support; a breach signals institutional buying (potential reversal up)
+- Liquidity voids are imbalance zones that price often revisits—use as take-profit targets
+
+![BUYSIDE_SELLSIDE_LIQUIDITY](https://github.com/coding-kitties/PyIndicators/blob/main/static/images/indicators/buy_side_sell_side_liquidity.png)
+
 ### Pattern Recognition
 
 #### Detect Peaks

pyindicators/__init__.py

@@ -23,7 +23,11 @@
     get_supertrend_stats,
     nadaraya_watson_envelope,
     zero_lag_ema_envelope,
-    ema_trend_ribbon
+    ema_trend_ribbon,
+    volume_gated_trend_ribbon,
+    liquidity_sweeps, liquidity_sweep_signal, get_liquidity_sweep_stats,
+    buyside_sellside_liquidity, buyside_sellside_liquidity_signal,
+    get_buyside_sellside_liquidity_stats
 )
 from .exceptions import PyIndicatorException
 from .date_range import DateRange
@@ -113,5 +117,12 @@ def get_version():
     'get_supertrend_stats',
     'nadaraya_watson_envelope',
     'zero_lag_ema_envelope',
-    'ema_trend_ribbon'
+    'ema_trend_ribbon',
+    'volume_gated_trend_ribbon',
+    'liquidity_sweeps',
+    'liquidity_sweep_signal',
+    'get_liquidity_sweep_stats',
+    'buyside_sellside_liquidity',
+    'buyside_sellside_liquidity_signal',
+    'get_buyside_sellside_liquidity_stats'
 ]

pyindicators/indicators/__init__.py

@@ -47,6 +47,14 @@
 from .nadaraya_watson_envelope import nadaraya_watson_envelope
 from .zero_lag_ema_envelope import zero_lag_ema_envelope
 from .ema_trend_ribbon import ema_trend_ribbon
+from .volume_gated_trend_ribbon import volume_gated_trend_ribbon
+from .liquidity_sweeps import (
+    liquidity_sweeps, liquidity_sweep_signal, get_liquidity_sweep_stats
+)
+from .buyside_sellside_liquidity import (
+    buyside_sellside_liquidity, buyside_sellside_liquidity_signal,
+    get_buyside_sellside_liquidity_stats
+)
 
 __all__ = [
     'sma',
@@ -118,5 +126,12 @@
     'get_supertrend_stats',
     'nadaraya_watson_envelope',
     'zero_lag_ema_envelope',
-    'ema_trend_ribbon'
+    'ema_trend_ribbon',
+    'volume_gated_trend_ribbon',
+    'liquidity_sweeps',
+    'liquidity_sweep_signal',
+    'get_liquidity_sweep_stats',
+    'buyside_sellside_liquidity',
+    'buyside_sellside_liquidity_signal',
+    'get_buyside_sellside_liquidity_stats'
 ]