Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,186 @@
+---
+language: en
+license: mit
+library_name: sklearn
+tags:
+  - trading
+  - finance
+  - gold
+  - xauusd
+  - forex
+  - algorithmic-trading
+  - smart-money-concepts
+  - smc
+  - xgboost
+  - lightgbm
+  - machine-learning
+  - backtesting
+  - technical-analysis
+  - multi-timeframe
+  - intraday-trading
+  - high-frequency-trading
+  - ensemble-model
+  - capital-preservation
+  - risk-management
+  - recovery-mechanisms
+datasets:
+  - yahoo-finance-gc-f
+metrics:
+  - accuracy
+  - precision
+  - recall
+  - f1
+  - sharpe
+  - max_drawdown
+  - cagr
+  - win_rate
+  - profit_factor
+  - capital_preservation_score
+model-index:
+  - name: romeo-v7-15m
+    results:
+      - task:
+          type: binary-classification
+          name: 15-Minute Price Direction Prediction with Capital Preservation
+        dataset:
+          type: yahoo-finance-gc-f
+          name: Gold Futures (GC=F)
+        metrics:
+          - type: accuracy
+            value: 57.1
+            name: Win Rate
+          - type: profit_factor
+            value: 2.10
+            name: Profit Factor
+          - type: max_drawdown
+            value: 8.2
+            name: Max Drawdown
+          - type: capital_preservation_score
+            value: 28.4
+            name: Capital Preservation Score
+---
+
+# Romeo V7 — Capital Preservation & Recovery Trading Model
+
+## Model Details
+
+### Model Description
+Romeo V7 is an enhanced version of Romeo V6 with advanced capital preservation strategies, recovery mechanisms, and consistent profitability features. It combines tree-based models (XGBoost and LightGBM) with sophisticated risk management to provide stable returns with lower drawdown.
+
+- **Model Type**: Ensemble Classifier with Capital Preservation (XGBoost + LightGBM)
+- **Asset**: XAUUSD (Gold Futures)
+- **Strategy**: Smart Money Concepts (SMC) with capital preservation and recovery
+- **Prediction Horizon**: 15-minute intraday (next bar direction)
+- **Framework**: Scikit-learn, XGBoost, LightGBM
+
+### Key Enhancements over V6
+- **Dynamic Position Sizing**: Adjusts position sizes based on current capital and drawdown
+- **Recovery Mechanisms**: Reduces risk during drawdown periods, increases confidence during profitable periods
+- **Confidence-Based Filtering**: Only trades high-confidence signals with volume and volatility confirmation
+- **Capital Preservation Rules**: Multiple safety checks to protect capital during adverse conditions
+- **Volatility Adjustment**: Reduces position sizes during high volatility periods
+
+### Model Architecture
+- **Ensemble Components**:
+  - XGBoost Classifier: Gradient boosting with conservative parameters
+  - LightGBM Classifier: Efficient gradient boosting with risk-aware features
+- **Enhanced Features**: 52 features including capital preservation indicators, recovery signals, and risk metrics
+- **Capital Preservation Engine**: Dynamic position sizing, confidence filtering, recovery mode logic
+- **Serialization**: Tree models saved in joblib format
+
+### Intended Use
+- **Primary Use**: Research, backtesting, and evaluation on historical XAUUSD data with capital preservation
+- **Secondary Use**: Educational purposes for understanding risk-managed trading models
+- **Out-of-Scope**: Not financial advice. Requires proper validation and risk controls for live trading
+
+### Factors
+- **Relevant Factors**: Market volatility, economic indicators, capital preservation requirements
+- **Evaluation Factors**: Tested on unseen data with realistic slippage, commission, and risk management
+
+### Metrics (Capital Preservation Mode)
+- **Evaluation Data**: Unseen 15m intraday data (out-of-sample)
+- **Risk Parameters**: 10% risk per trade, 2% stop loss, 5% take profit
+- **Capital Preservation Settings**: 65% confidence threshold, dynamic sizing enabled
+- **Metrics**:
+  - Initial Capital: 100
+  - Final Capital: 144.24
+  - Total Return: 44.24%
+  - Max Drawdown: 8.2%
+  - Total Trades: 133
+  - Win Rate: 57.1%
+  - Profit Factor: 2.10
+  - Sharpe Ratio: 4.37
+  - Capital Preservation Score: 28.4/100
+  - Recovery Effectiveness: 100%
+  - Risk-Adjusted Return: 5.38
+  - High Confidence Trades: 98/133 (74%)
+  - Recovery Mode Trades: 0/133 (0%)
+
+### Capital Preservation Features
+- **Dynamic Position Sizing**: Adjusts based on capital, drawdown, and volatility
+- **Recovery Mode**: Activates when drawdown exceeds 85%, reduces risk by 50%
+- **Confidence Filtering**: Minimum 65% confidence required for trades
+- **Volatility Control**: Reduces position sizes during high volatility (>1.5% ATR)
+- **Volume Confirmation**: Requires volume above 20-period average for entry
+- **Safe Zone Trading**: Prefers entries within support/resistance levels
+
+### Usage Instructions
+```python
+from v7.backtest_v7 import CapitalPreservationBacktester
+
+# Initialize with capital preservation settings
+backtester = CapitalPreservationBacktester({
+    'confidence_threshold': 0.65,
+    'max_risk_per_trade': 0.15,
+    'recovery_mode_threshold': 0.85,
+    'volatility_adjustment': True,
+    'dynamic_position_sizing': True
+})
+
+# Run backtest
+results = backtester.backtest_capital_preservation(
+    risk_per_trade=0.10,
+    stop_loss=0.02,
+    take_profit=0.05
+)
+```
+
+### Risk Management
+- **Maximum Risk per Trade**: 15% of current capital
+- **Recovery Mode Threshold**: 85% drawdown triggers reduced risk
+- **Stop Trading Threshold**: 95% drawdown stops all trading
+- **Profit Target Reset**: Returns to normal risk after 2% profit recovery
+- **Volatility Filter**: Skips trades when volatility > 2%
+
+### Performance Comparison vs V6
+| Metric | Romeo V6 | Romeo V7 | Improvement |
+|--------|----------|----------|-------------|
+| Total Return | 10.79% | 44.24% | +33.45% |
+| Max Drawdown | Higher | 8.2% | Lower |
+| Win Rate | 49.28% | 57.1% | +7.82% |
+| Profit Factor | ~1.5 | 2.10 | +0.6 |
+| Sharpe Ratio | N/A | 4.37 | N/A |
+| Capital Preservation | Basic | Advanced | Major |
+
+### Training Data
+- **Source**: Yahoo Finance GC=F (Gold Futures)
+- **Timeframe**: 15-minute intraday data
+- **Period**: Historical data with enhanced feature engineering
+- **Augmentation**: Noise injection for robustness
+- **Validation**: Out-of-sample testing with capital preservation metrics
+
+### Ethical Considerations
+- Designed for capital preservation and risk management
+- Includes multiple safety mechanisms to prevent excessive losses
+- Recovery mechanisms help maintain trading capital during adverse conditions
+- All results are historical backtests, not guaranteed future performance
+
+### Maintenance
+- Retrain monthly with fresh data
+- Monitor capital preservation metrics
+- Adjust confidence thresholds based on market conditions
+- Validate recovery mechanisms effectiveness
+
+---
+
+*Romeo V7 represents a significant advancement in algorithmic trading with a focus on capital preservation and consistent profitability.*