cache, pivots wip

WILLIAMS_PIVOT_SYSTEM.md

@@ -0,0 +1,116 @@
+# Williams Market Structure Pivot System
+
+## Overview
+The dashboard now displays the complete Williams Market Structure analysis with **5 recursive levels of pivot points** and **trend analysis** (higher highs/higher lows for uptrends).
+
+## What's Displayed
+
+### 1. Five Levels of Recursive Pivots
+Each level analyzes pivot points at different timeframes:
+
+- **Level 1** (Short-term): Direct swing highs/lows from 1-minute OHLCV data
+  - Small red/blue triangles (size 6)
+  - Most granular view of market structure
+  
+- **Level 2** (Medium-short): Pivots from Level 1 pivots
+  - Medium orange/light blue triangles (size 8)
+  - Filters out noise from Level 1
+  
+- **Level 3** (Medium): Pivots from Level 2 pivots
+  - Light orange/lighter blue triangles (size 10)
+  - Intermediate trend structure
+  
+- **Level 4** (Medium-long): Pivots from Level 3 pivots
+  - Yellow/very light blue triangles (size 12)
+  - Longer-term swing points
+  
+- **Level 5** (Long-term): Pivots from Level 4 pivots
+  - Bright yellow/pale blue triangles (size 14)
+  - Broadest market structure view
+
+### 2. Trend Analysis (For Each Level)
+The system calculates trend direction using classic Williams methodology:
+
+- **Uptrend** ↑: Higher highs AND higher lows
+- **Downtrend** ↓: Lower highs AND lower lows  
+- **Sideways** →: Mixed or insufficient pattern
+
+### 3. Trend Strength (0-100%)
+Each level also provides a trend strength score based on:
+- Consistency of pivot point progression
+- Average strength of individual pivots
+- Number of confirming pivots
+
+## Dashboard Display
+
+### Pivot Markers
+- **High Pivots**: Triangle pointing DOWN (potential resistance)
+- **Low Pivots**: Triangle pointing UP (potential support)
+- **Color/Size**: Larger and brighter = higher level = longer-term significance
+
+### Trend Annotation (Top-left corner)
+Shows all 5 levels of trend analysis:
+```
+Williams Trends:
+L1: ↑ 75%   (Short-term uptrend, strong)
+L2: ↑ 68%   (Medium-short uptrend, strong)
+L3: → 52%   (Medium sideways)
+L4: ↓ 61%   (Medium-long downtrend, moderate)
+L5: ↓ 71%   (Long-term downtrend, strong)
+```
+
+The border color indicates the **Level 5 (longest-term) trend**:
+- Green border = Long-term uptrend
+- Red border = Long-term downtrend
+- Orange border = Long-term sideways
+
+## How It Works
+
+### Recursive Calculation
+1. **Level 1**: Find swing highs/lows in raw 1m OHLCV data
+2. **Level 2**: Treat Level 1 pivots as "candles" and find swing points among them
+3. **Level 3**: Treat Level 2 pivots as "candles" and find swing points
+4. **Level 4**: Treat Level 3 pivots as "candles" and find swing points
+5. **Level 5**: Treat Level 4 pivots as "candles" and find swing points
+
+### Trend Detection
+For each level, the system:
+1. Gets the last 10 pivot points (or all if < 10)
+2. Separates into highs and lows
+3. Compares most recent highs/lows to previous ones
+4. Determines if forming higher highs/higher lows (uptrend) or lower highs/lower lows (downtrend)
+
+## Usage
+
+### Toggle Pivots On/Off
+Use the **"Show Pivot Points"** toggle in the Session Controls panel.
+
+### Interpret Multiple Levels
+- **All levels aligned**: Strong directional move
+  - Example: L1↑ L2↑ L3↑ L4↑ L5↑ = Strong sustained uptrend
+  
+- **Lower levels diverging**: Potential reversal
+  - Example: L1↓ L2↓ L3→ L4↑ L5↑ = Short-term correction in long-term uptrend
+  
+- **Mixed signals**: Market indecision or transition
+  - Example: L1↑ L2→ L3↓ L4→ L5↑ = Choppy market within long-term uptrend
+
+### Trading Applications
+- **Level 1-2**: Scalping entries/exits
+- **Level 3**: Intraday swing trades
+- **Level 4-5**: Position trading, trend confirmation
+
+## Data Source
+- Uses last **2000 candles** of 1-minute data
+- Recalculated on each chart refresh
+- Cached in pivot bounds system (refreshes daily)
+
+## Technical Details
+- **Algorithm**: Larry Williams Market Structure Analysis
+- **Minimum pivot distance**: 3 candles (configurable)
+- **Pivot strength**: Based on distance from surrounding highs/lows, volume, and formation duration
+- **Files**:
+  - `core/williams_market_structure.py`: Core algorithm
+  - `core/data_provider.py`: Data integration
+  - `web/clean_dashboard.py`: Visualization
+