Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,420 @@
+---
+language: en
+license: mit
+library_name: sklearn
+tags:
+  - trading
+  - finance
+  - gold
+  - xauusd
+  - forex
+  - algorithmic-trading
+  - smart-money-concepts
+  - smc
+  - xgboost
+  - machine-learning
+  - backtesting
+  - technical-analysis
+  - multi-timeframe
+  - intraday-trading
+  - high-frequency-trading
+datasets:
+  - yahoo-finance-gc-f
+metrics:
+  - accuracy
+  - precision
+  - recall
+  - f1
+model-index:
+  - name: xauusd-trading-ai-smc-daily
+    results:
+      - task:
+          type: binary-classification
+          name: Daily Price Direction Prediction
+        dataset:
+          type: yahoo-finance-gc-f
+          name: Gold Futures (GC=F)
+        metrics:
+          - type: accuracy
+            value: 80.3
+            name: Accuracy
+          - type: precision
+            value: 71
+            name: Precision (Class 1)
+          - type: recall
+            value: 81
+            name: Recall (Class 1)
+          - type: f1
+            value: 76
+            name: F1-Score
+  - name: xauusd-trading-ai-smc-15m
+    results:
+      - task:
+          type: binary-classification
+          name: 15-Minute Price Direction Prediction
+        dataset:
+          type: yahoo-finance-gc-f
+          name: Gold Futures (GC=F)
+        metrics:
+          - type: accuracy
+            value: 77.0
+            name: Accuracy
+          - type: precision
+            value: 76
+            name: Precision (Class 1)
+          - type: recall
+            value: 77
+            name: Recall (Class 1)
+          - type: f1
+            value: 76
+            name: F1-Score
+---
+---
+
+# XAUUSD Multi-Timeframe Trading AI Model
+
+## Files Included
+
+### Core Models
+- `trading_model.pkl` - Original daily timeframe XGBoost model (85.4% win rate)
+- `trading_model_15m.pkl` - 15-minute intraday model (77% validation accuracy)
+- `trading_model_1m.pkl` - 1-minute intraday model (partially trained)
+- `trading_model_30m.pkl` - 30-minute intraday model (ready for training)
+
+### Documentation
+- `README.md` - This comprehensive model card
+- `XAUUSD_Trading_AI_Paper.md` - **Research paper with academic structure, literature review, and methodology**
+- `XAUUSD_Trading_AI_Paper.docx` - **Word document version (professional format)**
+- `XAUUSD_Trading_AI_Paper.html` - **HTML web version (styled and readable)**
+- `XAUUSD_Trading_AI_Paper.tex` - **LaTeX source (for academic publishing)**
+- `XAUUSD_Trading_AI_Technical_Whitepaper.md` - **Technical whitepaper with mathematical formulations and implementation details**
+- `XAUUSD_Trading_AI_Technical_Whitepaper.docx` - **Word document version (professional format)**
+- `XAUUSD_Trading_AI_Technical_Whitepaper.html` - **HTML web version (styled and readable)**
+- `XAUUSD_Trading_AI_Technical_Whitepaper.tex` - **LaTeX source (for academic publishing)**
+
+### Performance & Analysis
+- `backtest_report.csv` - Daily model yearly backtesting performance results
+- `backtest_multi_timeframe_results.csv` - Intraday model backtesting results
+- `feature_importance_15m.csv` - 15-minute model feature importance analysis
+
+### Scripts & Tools
+- `train_multi_timeframe.py` - Multi-timeframe model training script
+- `backtest_multi_timeframe.py` - Intraday model backtesting framework
+- `multi_timeframe_summary.py` - Comprehensive performance analysis tool
+- `fetch_data.py` - Enhanced data acquisition for multiple timeframes
+
+### Dataset Files
+- **Daily Data**: `daily_data.csv`, `processed_daily_data.csv`, `smc_features_dataset.csv`, `X_features.csv`, `y_target.csv`
+- **Intraday Data**: `1m_data.csv` (5,204 samples), `15m_data.csv` (3,814 samples), `30m_data.csv` (1,910 samples)
+
+## Recent Enhancements (v2.0)
+
+### Visual Documentation
+- **Dataset Flow Diagram**: Complete data processing pipeline from raw Yahoo Finance data to model training
+- **Model Architecture Diagram**: XGBoost ensemble structure with decision flow visualization
+- **Buy/Sell Workflow Diagram**: End-to-end trading execution process with risk management
+
+### Advanced Formulas & Techniques
+- **Position Sizing Formula**: Risk-adjusted position calculation with Kelly Criterion adaptation
+- **Risk Metrics**: Sharpe Ratio, Sortino Ratio, Calmar Ratio, and Maximum Drawdown calculations
+- **SMC Techniques**: Advanced Order Block detection with volume profile analysis
+- **Dynamic Thresholds**: Market volatility-based prediction threshold adjustment
+- **Ensemble Signals**: Multi-source signal confirmation (ML + Technical + SMC)
+
+### Performance Analytics
+- **Monthly Performance Heatmap**: Visual representation of returns across all test years
+- **Risk-Return Scatter Plot**: Performance comparison across different risk levels
+- **Market Regime Analysis**: Performance breakdown by trending vs sideways markets
+
+### Documentation Updates
+- **Enhanced Technical Whitepaper**: Added comprehensive visual diagrams and mathematical formulations
+- **Enhanced Research Paper**: Added Mermaid diagrams, advanced algorithms, and detailed performance analysis
+- **Professional Exports**: Both documents now available in HTML, Word, and LaTeX formats
+
+## Multi-Timeframe Trading System (Latest Addition)
+
+### Overview
+The system has been extended to support intraday trading across multiple timeframes, enabling higher-frequency trading strategies while maintaining the proven SMC + technical indicator approach.
+
+### Supported Timeframes
+- **1-minute (1m)**: Ultra-short-term scalping opportunities
+- **15-minute (15m)**: Short-term swing trading
+- **30-minute (30m)**: Medium-term position trading
+- **Daily (1d)**: Original baseline model (85.4% win rate)
+
+### Data Acquisition
+- **Source**: Yahoo Finance API with enhanced intraday data fetching
+- **Limitations**: Historical intraday data restricted (recent periods only)
+- **Current Datasets**:
+  - 1m: 5,204 samples (7 days of recent data)
+  - 15m: 3,814 samples (60 days of recent data)
+  - 30m: 1,910 samples (60 days of recent data)
+
+### Model Architecture
+- **Base Algorithm**: XGBoost Classifier (same as daily model)
+- **Features**: 23 features (technical indicators + SMC elements)
+- **Training**: Grid search hyperparameter optimization
+- **Validation**: 80/20 train/test split with stratification
+
+### Training Results
+- **15m Model**: Successfully trained with 77% validation accuracy
+- **Feature Importance**: Technical indicators dominant (SMA_50, EMA_12, BB_lower)
+- **Training Status**: 1m model partially trained, 30m model interrupted (available for completion)
+
+### Backtesting Performance
+- **Framework**: Backtrader with realistic commission modeling
+- **Risk Management**: Fixed stake sizing ($1,000 per trade)
+- **15m Results**: -0.83% return with 1 trade (conservative strategy)
+- **Analysis**: Models show conservative behavior to avoid overtrading
+
+### Key Insights
+- ✅ Successfully scaled daily model architecture to intraday timeframes
+- ✅ Technical indicators remain most important across all timeframes
+- ✅ Conservative prediction thresholds prevent excessive trading
+- ⚠️ Limited historical data affects backtesting statistical significance
+- ⚠️ Yahoo Finance API constraints limit comprehensive validation
+
+### Files Added
+- `train_multi_timeframe.py` - Multi-timeframe model training script
+- `backtest_multi_timeframe.py` - Intraday model backtesting framework
+- `multi_timeframe_summary.py` - Comprehensive performance analysis
+- `trading_model_15m.pkl` - Trained 15-minute model
+- `feature_importance_15m.csv` - Feature importance analysis
+- `backtest_multi_timeframe_results.csv` - Backtesting performance data
+
+### Next Steps
+1. Complete 30m model training
+2. Implement walk-forward optimization
+3. Add extended historical data sources
+4. Deploy best performing intraday model
+5. Compare intraday vs daily performance
+
+## Model Description
+
+This is an AI-powered trading model for XAUUSD (Gold vs US Dollar) futures, trained using Smart Money Concepts (SMC) strategy elements. The model uses machine learning to predict 5-day ahead price movements and generate trading signals with high win rates.
+
+### Key Features
+- **Asset**: XAUUSD (Gold Futures)
+- **Strategy**: Smart Money Concepts (SMC) with technical indicators
+- **Prediction Horizon**: 5-day ahead price direction
+- **Model Type**: XGBoost Classifier
+
+## Romeo (V5) — Ensemble model
+
+Romeo (codename V5) is the latest ensemble model combining tree-based learners (XGBoost / LightGBM) and an optional Keras head. The artifacts live in `models_romeo/` and include a canonical feature list used by the backtester to align unseen data.
+
+Artifacts
+- `models_romeo/trading_model_romeo_daily.pkl` — ensemble artifact (joblib) with `models`, `weights`, and `features` keys.
+- `models_romeo/romeo_keras_daily.keras` — optional Keras model file when included in training.
+- `models_romeo/MODEL_CARD.md` — this model's card with evaluation and transparency notes.
+
+Evaluation (selected run on unseen daily data)
+- Initial capital: 100
+- Final capital: 484.8199
+- CAGR: 0.0444
+- Annual volatility: 0.4118
+- Sharpe: 0.3119
+- Max Drawdown: -47.66%
+- Total trades: 3610
+- Win rate: 49.47%
+
+Uploading to Hugging Face
+-------------------------
+There is a helper script to upload the model artifacts to Hugging Face Hub:
+
+1. Install dependencies:
+```bash
+pip install huggingface_hub
+```
+
+2. Set your HF token in the environment (Windows cmd.exe):
+```cmd
+set HF_TOKEN=hf_YourTokenHere
+```
+
+3. Upload:
+```cmd
+python v5\upload_model_v5_to_hf.py --repo-name your-username/romeo-v5 --model-dir models_romeo
+```
+
+The script will create the repo (if it doesn't exist) and upload all files from `models_romeo/`.
+
+Usage example
+-------------
+Load the artifact and run predictions:
+
+```python
+import joblib
+artifact = joblib.load('models_romeo/trading_model_romeo_daily.pkl')
+features = artifact['features']
+# prepare X matching features
+# model usage depends on artifact['models'] layout; check MODEL_CARD.md for details
+```
+
+Notes & Next Steps
+------------------
+- Position sizing is simplified in the backtester; consider implementing fixed-risk sizing before live use.
+- Consider re-running the robustness scan using the M2M metric as primary evaluation (recommended).
+
+- **Accuracy**: 80.3% on test data
+- **Win Rate**: 85.4% in backtesting
+
+## Intended Use
+
+This model is designed for:
+- Educational purposes in algorithmic trading
+- Research on SMC strategies
+- Backtesting trading strategies
+- Understanding ML applications in financial markets
+
+**⚠️ Warning**: This is not financial advice. Trading involves risk of loss. Use at your own discretion.
+
+## Training Data
+
+- **Source**: Yahoo Finance (GC=F - Gold Futures)
+- **Period**: 2000-2020 (excluding recent months for efficiency)
+- **Features**: 23 features including:
+  - Price data (Open, High, Low, Close, Volume)
+  - Technical indicators (SMA, EMA, RSI, MACD, Bollinger Bands)
+  - SMC features (Fair Value Gaps, Order Blocks, Recovery patterns)
+  - Lag features (Close prices from previous days)
+- **Target**: Binary classification (1 if price rises in 5 days, 0 otherwise)
+- **Dataset Size**: 8,816 samples
+- **Class Distribution**: 54% down, 46% up (balanced with scale_pos_weight)
+
+## Performance Metrics
+
+### Model Performance
+- **Accuracy**: 80.3%
+- **Precision (Class 1)**: 71%
+- **Recall (Class 1)**: 81%
+- **F1-Score**: 76%
+
+### Backtesting Results (2015-2020)
+- **Overall Win Rate**: 85.4%
+- **Total Return**: 18.2%
+- **Sharpe Ratio**: 1.41
+- **Yearly Win Rates**:
+  - 2015: 62.5%
+  - 2016: 100.0%
+  - 2017: 100.0%
+  - 2018: 72.7%
+  - 2019: 76.9%
+  - 2020: 94.1%
+
+## Limitations
+
+- Trained on historical data only (2000-2020)
+- May not perform well in unprecedented market conditions
+- Requires proper risk management
+- No consideration of transaction costs, slippage, or market impact
+- Model predictions are probabilistic, not guaranteed
+
+## Usage
+
+### Prerequisites
+```python
+pip install joblib scikit-learn pandas numpy
+```
+
+### Loading the Model
+```python
+import joblib
+import pandas as pd
+from sklearn.preprocessing import StandardScaler
+
+# Load model
+model = joblib.load('trading_model.pkl')
+
+# Load scalers (you need to recreate or save them)
+# ... preprocessing code ...
+
+# Prepare features
+features = prepare_features(your_data)
+prediction = model.predict(features)
+probability = model.predict_proba(features)
+```
+
+### Features Required
+The model expects 23 features in this order:
+1. Close
+2. High
+3. Low
+4. Open
+5. Volume
+6. SMA_20
+7. SMA_50
+8. EMA_12
+9. EMA_26
+10. RSI
+11. MACD
+12. MACD_signal
+13. MACD_hist
+14. BB_upper
+15. BB_middle
+16. BB_lower
+17. FVG_Size
+18. FVG_Type_Encoded
+19. OB_Type_Encoded
+20. Recovery_Type_Encoded
+21. Close_lag1
+22. Close_lag2
+23. Close_lag3
+
+## Training Details
+
+- **Algorithm**: XGBoost Classifier
+- **Hyperparameters**:
+  - n_estimators: 200
+  - max_depth: 7
+  - learning_rate: 0.2
+  - scale_pos_weight: 1.17 (for class balancing)
+- **Cross-validation**: 3-fold
+- **Optimization**: Grid search on hyperparameters
+
+## SMC Strategy Elements
+
+The model incorporates Smart Money Concepts:
+- **Fair Value Gaps (FVG)**: Price imbalances between candles
+- **Order Blocks (OB)**: Areas of significant buying/selling
+- **Recovery Patterns**: Pullbacks in trending markets
+
+## Upload to Hugging Face
+
+To share this model on Hugging Face:
+
+1. Create a Hugging Face account at https://huggingface.co/join
+2. Generate an access token at https://huggingface.co/settings/tokens with "Write" permissions
+3. Test your token: `python test_token.py YOUR_TOKEN`
+4. Upload: `python upload_to_hf.py YOUR_TOKEN`
+
+The script will upload:
+- `trading_model.pkl` - The trained XGBoost model
+- `README.md` - This model card with metadata
+- All dataset files (CSV format)
+
+## Citation
+
+If you use this model in your research, please cite:
+
+```
+@misc{xauusd-trading-ai,
+  title={XAUUSD Trading AI Model with SMC Strategy},
+  author={AI Trading System},
+  year={2025},
+  url={https://huggingface.co/JonusNattapong/xauusd-trading-ai-smc}
+}
+```
+
+### Academic Paper
+For the complete academic research paper with methodology, results, and analysis:
+
+**arXiv Paper**: [XAUUSD Trading AI: A Machine Learning Approach Using Smart Money Concepts](https://arxiv.org/abs/XXXX.XXXXX)
+
+## License
+
+This model is released under the MIT License. See LICENSE file for details.
+
+## Contact
+
+For questions or issues, please open an issue on the Hugging Face repository.