Merge pull request #42 from AKKI0511/implement-drawdown-protection-system

feat(trading): add drawdown guard risk management

Author: AKKI0511

README.md

@@ -19,10 +19,11 @@
 ## Key Features
 
 - 📊 Data: YFinance/AlphaVantage loaders, caching, validation
-- 🧪 Features: technical indicators, custom signals, optional LLM sentiment
-- 🤖 Models: ensemble VotingClassifier (LR, RF, XGBoost) with Optuna tuning
+- 🧪 Features: technical indicators, custom signals, optional LLM sentiment
+- 🤖 Models: ensemble VotingClassifier (LR, RF, XGBoost) with Optuna tuning
 - 📈 Backtesting: execution costs, slippage, liquidity limits, market impact modeling, portfolio helpers
-- 🛠️ CLI: end‑to‑end pipeline, evaluation, and model backtest in one place
+- 🛡️ Risk management: drawdown and turnover guards
+- 🛠️ CLI: end‑to‑end pipeline, evaluation, and model backtest in one place
 
 ## Quickstart
 
@@ -61,10 +62,11 @@ Artifacts are written to:
 
 ## Configuration
 
-- `config/model_config.yaml`: symbols, date ranges, caching, training, trading
-- `config/features_config.yaml`: pipeline steps, indicators, selection, sentiment
-- `config/backtest_config.yaml`: execution costs, slippage, liquidity
-- `config/streaming.yaml`: providers, auth, subscriptions (optional)
+- `config/model_config.yaml`: symbols, date ranges, caching, training, trading
+- `config/features_config.yaml`: pipeline steps, indicators, selection, sentiment
+- `config/backtest_config.yaml`: execution costs, slippage, liquidity
+- `config/risk_config.yaml`: drawdown protection and turnover limits
+- `config/streaming.yaml`: providers, auth, subscriptions (optional)
 
 Time‑aware evaluation rules:
 - If `data.test_start` and `data.test_end` set: train = dates < `test_start`; test = `test_start` ≤ dates ≤ `test_end`

config/risk_config.yaml

@@ -0,0 +1,14 @@
+risk_management:
+  drawdown_protection:
+    enabled: true
+    max_drawdown_pct: 0.15
+    max_drawdown_absolute: 50000
+    warning_threshold: 0.8
+    soft_stop_threshold: 0.9
+    hard_stop_threshold: 1.0
+    emergency_stop_threshold: 1.1
+    lookback_periods: [1, 7, 30]
+  turnover_limits:
+    daily_max: 2.0
+    weekly_max: 5.0
+    monthly_max: 15.0

docs/README.md

@@ -56,7 +56,7 @@ The [Quick Reference Guide](quick-reference.md) includes:
 - **Common Patterns** - Data loading, feature engineering, model training, backtesting
 - **Technical Indicators** - Usage examples for all technical indicators
 - **Custom Features** - Momentum score and volatility breakout functions
-- **Risk Management** - Stop-loss, take-profit, and position sizing
+- **Risk Management** - Stop-loss, take-profit, drawdown guard, and position sizing
 - **Performance Metrics** - Classification and trading metrics
 - **Visualization** - Price charts and performance plots
 - **Configuration Examples** - Model and feature configuration templates
@@ -83,15 +83,18 @@ QuantTradeAI/
 │   │   └── classifier.py    # Voting classifier
 │   ├── backtest/            # Backtesting
 │   │   └── backtester.py    # Trade simulation
-│   ├── trading/             # Trading utilities
-│   │   └── risk.py          # Risk management
+│   ├── trading/             # Trading utilities
+│   │   ├── drawdown_guard.py # Drawdown protection
+│   │   ├── portfolio.py     # Portfolio operations
+│   │   └── risk_manager.py  # Risk coordination
 │   └── utils/               # Utilities
 │       ├── metrics.py       # Performance metrics
 │       ├── visualization.py # Plotting functions
 │       └── config_schemas.py # Configuration validation
-├── config/                  # Configuration files
-│   ├── model_config.yaml    # Model parameters
-│   └── features_config.yaml # Feature engineering settings
+├── config/                  # Configuration files
+│   ├── model_config.yaml    # Model parameters
+│   ├── features_config.yaml # Feature engineering settings
+│   └── risk_config.yaml     # Drawdown and turnover limits
 └── docs/                    # Documentation
     ├── api/                 # API documentation
     ├── quick-reference.md   # Quick reference guide
@@ -134,11 +137,11 @@ QuantTradeAI/
 - **Market impact modeling** for execution cost realism
 - **Position sizing** based on risk parameters
 
-### Risk Management
-- **Stop-loss and take-profit** rules
-- **Position sizing** calculations
-- **Risk-adjusted returns** analysis
-- **Drawdown monitoring**
+### Risk Management
+- **Stop-loss and take-profit** rules
+- **Position sizing** calculations
+- **Risk-adjusted returns** analysis
+- **Drawdown and turnover guards**
 
 ## 📊 Supported Assets
 

docs/configuration.md

@@ -10,6 +10,7 @@ The framework uses several configuration files:
 - **`config/features_config.yaml`** - Feature engineering settings
 - **`config/backtest_config.yaml`** - Execution settings for backtests
 - **`config/impact_config.yaml`** - Market impact parameters by asset class
+- **`config/risk_config.yaml`** - Drawdown protection and turnover limits
 
 ## 🔧 Model Configuration
 
@@ -89,7 +90,7 @@ trading:
   transaction_cost: 0.001
 ```
 
-### Backtest Execution
+### Backtest Execution
 
 ```yaml
 execution:
@@ -130,7 +131,7 @@ parameter sets per asset class can be defined in `config/impact_config.yaml`.
 price_features:
   sma_periods: [5, 10, 20, 50, 200]
   ema_periods: [5, 10, 20, 50, 200]
-```
+```
 
 ### Momentum Features
 
@@ -230,8 +231,28 @@ pipeline:
     - handle_missing_values
     - remove_outliers
     - scale_features
-    - select_features
-```
+    - select_features
+```
+
+## 🛡️ Risk Management
+
+```yaml
+risk_management:
+  drawdown_protection:
+    enabled: true
+    max_drawdown_pct: 0.15
+    warning_threshold: 0.8
+    soft_stop_threshold: 0.9
+    hard_stop_threshold: 1.0
+  turnover_limits:
+    daily_max: 2.0
+    weekly_max: 5.0
+    monthly_max: 15.0
+```
+
+**Key Parameters:**
+- `drawdown_protection`: monitors portfolio equity and halts trading at specified levels
+- `turnover_limits`: caps how frequently positions may change over each period
 
 ## 🎯 Common Configurations
 

docs/quick-reference.md

@@ -116,25 +116,26 @@ stoch_df = ta.stochastic(df['High'], df['Low'], df['Close'])
 
 ## 🛡️ Risk Management
 
-```python
-from quanttradeai import apply_stop_loss_take_profit, position_size
+```python
+from quanttradeai import apply_stop_loss_take_profit, position_size
 
 # Apply risk rules
 df_with_risk = apply_stop_loss_take_profit(df, stop_loss_pct=0.02, take_profit_pct=0.04)
 
 # Calculate position size
-qty = position_size(capital=10000, risk_per_trade=0.02, stop_loss_pct=0.05, price=150.0)
-```
-
-```python
-from quanttradeai import PortfolioManager
-
-# Allocate capital across multiple symbols
-pm = PortfolioManager(10000)
-pm.open_position('AAPL', price=150, stop_loss_pct=0.05)
-pm.open_position('TSLA', price=250, stop_loss_pct=0.05)
-print(f"Portfolio exposure: {pm.risk_exposure:.2%}")
-```
+qty = position_size(capital=10000, risk_per_trade=0.02, stop_loss_pct=0.05, price=150.0)
+```
+
+```python
+from quanttradeai.trading import DrawdownGuard, PortfolioManager
+
+# Allocate capital across multiple symbols with drawdown protection
+guard = DrawdownGuard(config_path="config/risk_config.yaml")
+pm = PortfolioManager(10000, drawdown_guard=guard)
+pm.open_position('AAPL', price=150, stop_loss_pct=0.05)
+pm.open_position('TSLA', price=250, stop_loss_pct=0.05)
+print(f"Portfolio exposure: {pm.risk_exposure:.2%}")
+```
 
 ## 📈 Performance Metrics
 

quanttradeai/backtest/backtester.py

@@ -17,10 +17,11 @@
     ```
 """
 
-import pandas as pd
-from quanttradeai.utils.metrics import sharpe_ratio, max_drawdown
-from quanttradeai.trading.risk import apply_stop_loss_take_profit
-from quanttradeai.trading.portfolio import PortfolioManager
+import pandas as pd
+from quanttradeai.utils.metrics import sharpe_ratio, max_drawdown
+from quanttradeai.trading.risk import apply_stop_loss_take_profit
+from quanttradeai.trading.portfolio import PortfolioManager
+from quanttradeai.trading.drawdown_guard import DrawdownGuard
 
 
 def _simulate_single(
@@ -190,13 +191,14 @@ def _simulate_single(
 
 def simulate_trades(
     df: pd.DataFrame | dict[str, pd.DataFrame],
-    stop_loss_pct: float | None = None,
-    take_profit_pct: float | None = None,
-    transaction_cost: float = 0.0,
-    slippage: float = 0.0,
-    execution: dict | None = None,
-    portfolio: PortfolioManager | None = None,
-) -> pd.DataFrame | dict[str, pd.DataFrame]:
+    stop_loss_pct: float | None = None,
+    take_profit_pct: float | None = None,
+    transaction_cost: float = 0.0,
+    slippage: float = 0.0,
+    execution: dict | None = None,
+    portfolio: PortfolioManager | None = None,
+    drawdown_guard: DrawdownGuard | None = None,
+) -> pd.DataFrame | dict[str, pd.DataFrame]:
     """Simulate trades using label signals.
 
     Parameters
@@ -270,14 +272,23 @@ def simulate_trades(
         results["portfolio"] = pd.DataFrame(
             {"strategy_return": combined, "equity_curve": portfolio_curve}
         )
-        return results
-    else:
-        return _simulate_single(
-            df,
-            stop_loss_pct=stop_loss_pct,
-            take_profit_pct=take_profit_pct,
-            execution=exec_cfg,
-        )
+        if drawdown_guard is not None:
+            curve = results["portfolio"]["equity_curve"]
+            for t, v in zip(curve.index, curve):
+                drawdown_guard.update_portfolio_value(float(v), t)
+        return results
+    else:
+        res = _simulate_single(
+            df,
+            stop_loss_pct=stop_loss_pct,
+            take_profit_pct=take_profit_pct,
+            execution=exec_cfg,
+        )
+        if drawdown_guard is not None:
+            curve = res["equity_curve"]
+            for t, v in zip(curve.index, curve):
+                drawdown_guard.update_portfolio_value(float(v), t)
+        return res
 
 
 def compute_metrics(data: pd.DataFrame, risk_free_rate: float = 0.0) -> dict:

quanttradeai/trading/__init__.py

@@ -14,7 +14,15 @@
     ```
 """
 
-from .portfolio import PortfolioManager
-from .risk import apply_stop_loss_take_profit, position_size
-
-__all__ = ["PortfolioManager", "apply_stop_loss_take_profit", "position_size"]
+from .portfolio import PortfolioManager
+from .risk import apply_stop_loss_take_profit, position_size
+from .drawdown_guard import DrawdownGuard
+from .risk_manager import RiskManager
+
+__all__ = [
+    "PortfolioManager",
+    "apply_stop_loss_take_profit",
+    "position_size",
+    "DrawdownGuard",
+    "RiskManager",
+]