feat: add Lorenz Formula indicator applying chaos theory to market analysis

- Implement LORENZIndicator class with dynamic parameter calculation from OHLCV data
- Add comprehensive test suite with 15 tests following TDD methodology
- Create detailed documentation with trading strategies and examples
- Add example script demonstrating usage with signal generation
- Update version to v3.5.4 across all documentation
- Update indicator count from 58+ to 59+ indicators

The Lorenz Formula indicator adapts chaos theory equations to trading:
- Calculates sigma (volatility), rho (trend), beta (dissipation) from market data
- Uses Euler method for differential equation integration
- Outputs x, y, z values for market regime detection
- Supports multiple trading strategies including Z-value momentum and divergence

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: TexasCoding

.secrets.baseline

@@ -133,7 +133,7 @@
         "filename": "CHANGELOG.md",
         "hashed_secret": "89a6cfe2a229151e8055abee107d45ed087bbb4f",
         "is_verified": false,
-        "line_number": 2073
+        "line_number": 2107
       }
     ],
     "README.md": [
@@ -325,5 +325,5 @@
       }
     ]
   },
-  "generated_at": "2025-08-31T14:52:37Z"
+  "generated_at": "2025-08-31T20:27:03Z"
 }

CHANGELOG.md

@@ -14,6 +14,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migration guides will be provided for all breaking changes
 - Semantic versioning (MAJOR.MINOR.PATCH) is strictly followed
 
+## [3.5.4] - 2025-01-31
+
+### 🚀 Added
+
+**New Lorenz Formula Indicator**:
+- **Chaos Theory Trading**: Added Lorenz Formula indicator applying chaos theory to market analysis
+- **Dynamic Parameter Calculation**: Automatically adjusts sigma (volatility), rho (trend), and beta (volume) based on market conditions
+- **Three-Component Output**: Provides X (rate of change), Y (momentum), and Z (primary signal) components
+- **Market Regime Detection**: Identifies stable, transitional, and chaotic market conditions
+- **Full Integration**: TA-Lib style interface with both class-based and function-based APIs
+
+### 📝 Documentation
+
+**Lorenz Indicator Documentation**:
+- **Comprehensive Guide**: Created detailed documentation at `docs/indicators/lorenz.md` with mathematical foundation
+- **Trading Strategies**: Multiple signal generation strategies including Z-value momentum, crossovers, and divergence
+- **Parameter Tuning**: Complete guidelines for adjusting dt, window, and volatility_scale parameters
+- **Integration Examples**: Added to main indicators guide with practical usage examples
+- **Complete Trading System**: Full example with position sizing, stops, and multi-indicator confluence
+
+### ✅ Testing
+
+**Lorenz Indicator Tests**:
+- **15 Comprehensive Tests**: Full test coverage following TDD principles
+- **Parameter Validation**: Tests for custom parameters, window sizes, and time steps
+- **Chaos Properties**: Verification of chaotic behavior and sensitivity to initial conditions
+- **Edge Cases**: Handling of empty data, missing columns, and single-row inputs
+- **Integration**: Example script (`examples/33_lorenz_indicator.py`) demonstrating all features
+
+### 🔧 Changed
+
+- **Indicator Count**: Updated from 58+ to 59+ indicators across all documentation
+- **Pattern Recognition**: Enhanced with chaos theory-based market analysis
+
 ## [3.5.3] - 2025-01-31
 
 ### 🐛 Fixed

README.md

@@ -82,11 +82,11 @@ suite = await TradingSuite.create(\"MNQ\")
 - **Risk Management**: Portfolio analytics and risk metrics
 
 ### Advanced Features
-- **58+ Technical Indicators**: Full TA-Lib compatibility with Polars optimization including new pattern indicators
+- **59+ Technical Indicators**: Full TA-Lib compatibility with Polars optimization including new pattern indicators
 - **Level 2 OrderBook**: Depth analysis, iceberg detection, spoofing detection with 6 pattern types
 - **Real-time WebSockets**: Async streaming for quotes, trades, and account updates
 - **Performance Optimized**: Connection pooling, intelligent caching, memory management
-- **Pattern Recognition**: Fair Value Gaps, Order Blocks, and Waddah Attar Explosion indicators
+- **Pattern Recognition**: Fair Value Gaps, Order Blocks, Waddah Attar Explosion, and Lorenz Formula indicators
 - **Market Manipulation Detection**: Advanced spoofing detection with confidence scoring
 - **Financial Precision**: All calculations use Decimal type for exact precision
 - **Enterprise Error Handling**: Production-ready error handling with decorators and structured logging
@@ -588,7 +588,7 @@ if health_score < 70:
 
 ### Technical Indicators
 
-All 58+ indicators work with async data pipelines:
+All 59+ indicators work with async data pipelines:
 ```python
 import polars as pl
 from project_x_py.indicators import RSI, SMA, MACD, FVG, ORDERBLOCK, WAE

docs/guide/indicators.md

@@ -68,6 +68,7 @@ from project_x_py.indicators import (
     FVG,        # Fair Value Gap
     ORDERBLOCK, # Order Block Detection
     WAE,        # Waddah Attar Explosion
+    LORENZ,     # Lorenz Formula (Chaos Theory)
 )
 ```
 
@@ -867,6 +868,106 @@ async def wae_analysis():
         print(f"Recent bearish explosions - Avg: {avg_down:.1f}, Max: {max_down:.1f}")
 ```
 
+### Lorenz Formula (Chaos Theory)
+
+The Lorenz Formula indicator applies chaos theory to market analysis, creating a dynamic attractor that responds to volatility, trend, and volume.
+
+```python
+async def lorenz_analysis():
+    suite = await TradingSuite.create("MNQ")
+    data = await suite.data.get_data("15min", bars=200)
+
+    # Lorenz Formula with default parameters
+    lorenz_data = data.pipe(LORENZ,
+        window=14,              # Rolling window for parameters
+        dt=0.1,                 # Time step (smaller = more stable)
+        volatility_scale=0.02   # Expected volatility
+    )
+
+    # Lorenz provides three components:
+    # - lorenz_x: Rate of change in the system
+    # - lorenz_y: Momentum accumulation
+    # - lorenz_z: Primary trading signal (height)
+
+    latest = lorenz_data.tail(1)
+    z_value = latest['lorenz_z'][0]
+
+    # Basic signal interpretation
+    if z_value > 0:
+        print(f"Bullish bias (Z = {z_value:.2f})")
+    elif z_value < 0:
+        print(f"Bearish bias (Z = {z_value:.2f})")
+    else:
+        print("Neutral/Transitional")
+
+    # Calculate chaos magnitude for regime detection
+    lorenz_data = lorenz_data.with_columns([
+        (pl.col("lorenz_x")**2 +
+         pl.col("lorenz_y")**2 +
+         pl.col("lorenz_z")**2).sqrt().alias("chaos_magnitude")
+    ])
+
+    # Classify market regime
+    lorenz_data = lorenz_data.with_columns([
+        pl.when(pl.col("chaos_magnitude") < 10)
+        .then(pl.lit("STABLE"))
+        .when(pl.col("chaos_magnitude") < 50)
+        .then(pl.lit("TRANSITIONAL"))
+        .otherwise(pl.lit("CHAOTIC"))
+        .alias("market_regime")
+    ])
+
+    latest_regime = lorenz_data.tail(1)
+    regime = latest_regime['market_regime'][0]
+    magnitude = latest_regime['chaos_magnitude'][0]
+
+    print(f"Market Regime: {regime} (Magnitude: {magnitude:.2f})")
+
+    # Z-value crossover strategy
+    lorenz_data = lorenz_data.with_columns([
+        pl.col("lorenz_z").rolling_mean(window_size=10).alias("z_ma")
+    ])
+
+    # Detect crossovers
+    current = lorenz_data.tail(1)
+    previous = lorenz_data.tail(2).head(1)
+
+    z_current = current['lorenz_z'][0]
+    z_ma_current = current['z_ma'][0]
+    z_previous = previous['lorenz_z'][0] if len(previous) > 0 else z_current
+    z_ma_previous = previous['z_ma'][0] if len(previous) > 0 else z_ma_current
+
+    # Check for crossover signals
+    if z_previous <= z_ma_previous and z_current > z_ma_current:
+        print("🔺 Bullish Z crossover detected!")
+    elif z_previous >= z_ma_previous and z_current < z_ma_current:
+        print("🔻 Bearish Z crossover detected!")
+
+    # Advanced: Combine with other indicators
+    from project_x_py.indicators import RSI
+
+    combined = lorenz_data.pipe(RSI, period=14)
+    latest = combined.tail(1)
+
+    z = latest['lorenz_z'][0]
+    rsi = latest['rsi_14'][0]
+
+    # Strong signals when both align
+    if z > 0 and rsi < 35:
+        print("💪 STRONG BUY: Bullish Lorenz + Oversold RSI")
+    elif z < 0 and rsi > 65:
+        print("💪 STRONG SELL: Bearish Lorenz + Overbought RSI")
+```
+
+Key features of the Lorenz indicator:
+- **Chaos Theory Application**: Adapts atmospheric modeling to markets
+- **Three Components**: X (rate of change), Y (momentum), Z (signal)
+- **Dynamic Parameters**: Automatically adjusts to market conditions
+- **Regime Detection**: Identifies stable, transitional, and chaotic markets
+- **Early Warning System**: Detects instability before major moves
+
+For detailed documentation and advanced strategies, see [Lorenz Indicator Documentation](../indicators/lorenz.md).
+
 ## Real-time Indicator Updates
 
 ### Streaming Indicator Calculations

docs/index.md

@@ -93,7 +93,7 @@ asyncio.run(main())
 - Async historical OHLCV data with multiple timeframes
 - Real-time market data feeds via async WebSocket
 - **Level 2 orderbook analysis** with institutional-grade features
-- **58+ Technical Indicators** with TA-Lib compatibility (RSI, MACD, Bollinger Bands, Pattern Recognition, etc.)
+- **59+ Technical Indicators** with TA-Lib compatibility (RSI, MACD, Bollinger Bands, Pattern Recognition, Lorenz Formula, etc.)
 - **Advanced market microstructure** analysis (iceberg detection, order flow, volume profile)
 - **Market Manipulation Detection**: 6 spoofing pattern types with regulatory compliance features
 - **100% Async Statistics System**: Health monitoring, multi-format export, component tracking
@@ -161,8 +161,8 @@ mnq_context = suite["MNQ"]  # Access specific instrument
 - **Event System**: Unified EventBus for cross-component communication
 
 **Technical Analysis**
-- **58+ Indicators**: TA-Lib compatible with Polars DataFrames
-- **Pattern Recognition**: Fair Value Gaps, Order Blocks, Waddah Attar
+- **59+ Indicators**: TA-Lib compatible with Polars DataFrames
+- **Pattern Recognition**: Fair Value Gaps, Order Blocks, Waddah Attar, Lorenz Formula
 - **Advanced Patterns**: Iceberg detection, market manipulation
 
 **Statistics & Monitoring (v3.3.0)**
@@ -184,7 +184,7 @@ mnq_context = suite["MNQ"]  # Access specific instrument
 - [Order Management](guide/orders.md) - Placing and managing orders
 - [Position Tracking](guide/positions.md) - Portfolio management
 - [Real-time Data](guide/realtime.md) - WebSocket streaming
-- [Technical Indicators](guide/indicators.md) - 58+ analysis tools
+- [Technical Indicators](guide/indicators.md) - 59+ analysis tools
 - [Risk Management](guide/risk.md) - Position sizing and limits
 - [Order Book](guide/orderbook.md) - Level 2 market depth