GifariKemal
f36123ccaf
Implement industrial-standard semantic versioning (SemVer 2.0.0) with automated feature detection and comprehensive changelog management. New Features: - VERSION file: Single source of truth for base version (0.0.0) - src/version.py: Centralized version manager with auto-detection - CHANGELOG.md: Keep a Changelog format for all changes - Auto-versioning: Features increment MINOR version automatically - Version display: Shows in startup banner and logs Predictive Intelligence (v6.3) Complete: - src/trajectory_predictor.py: Forecast profit 1-5 minutes ahead - src/momentum_persistence.py: Detect momentum continuation (0-1 score) - src/recovery_detector.py: Analyze recovery strength from losses - src/fuzzy_exit_logic.py: Fuzzy logic exit confidence (0-1) - src/kalman_filter.py: Kalman filter for velocity smoothing - src/kelly_position_scaler.py: Kelly criterion position scaling Version Calculation: Base 0.0.0 + Kalman(0.1) + Fuzzy(0.1) + Kelly(0.1) + Trajectory(0.1) + Momentum(0.1) + Recovery(0.1) = v0.6.0 Modified: - CLAUDE.md: Added comprehensive versioning documentation - main_live.py: Display version in startup banner - src/smart_risk_manager.py: Use centralized versioning Documentation: - CLAUDE.md: Full versioning guidelines (SemVer, workflows, examples) - CHANGELOG.md: Initial release documentation with feature tracking - VERSION: Base version 0.0.0 Benefits: - Professional version management (industry standard) - Automatic feature tracking and version updates - Complete change history with Keep a Changelog format - Clear upgrade paths (MAJOR.MINOR.PATCH) Version: v0.6.0 (Kalman + Fuzzy + Kelly + Predictive) Exit Strategy: v6.3 Predictive Intelligence Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
278 lines
10 KiB
Markdown
278 lines
10 KiB
Markdown
# CLAUDE.md — XAUBot AI
|
|
|
|
## Project Overview
|
|
|
|
XAUBot AI is an automated XAUUSD (Gold) trading bot that combines Machine Learning (XGBoost), Smart Money Concepts (SMC), and Hidden Markov Model (HMM) regime detection. It runs on MetaTrader 5 via an async Python loop, executing trades on M15 candles.
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
.
|
|
├── main_live.py # Main async trading orchestrator
|
|
├── train_models.py # Model training script
|
|
├── Dockerfile # Docker image (must be at root)
|
|
├── docker-compose.yml # Docker orchestration (must be at root)
|
|
├── .dockerignore # Docker build exclusions (must be at root)
|
|
├── src/ # Core modules
|
|
│ ├── config.py # Trading configuration & capital modes
|
|
│ ├── mt5_connector.py # MetaTrader 5 connection layer
|
|
│ ├── smc_polars.py # Smart Money Concepts (Polars-based)
|
|
│ ├── ml_model.py # XGBoost trading model
|
|
│ ├── feature_eng.py # Feature engineering (37 features)
|
|
│ ├── regime_detector.py # HMM market regime detection
|
|
│ ├── risk_engine.py # Risk calculations & validation
|
|
│ ├── smart_risk_manager.py # Dynamic risk management
|
|
│ ├── session_filter.py # Trading session filter (Sydney/London/NY)
|
|
│ ├── position_manager.py # Open position management
|
|
│ ├── dynamic_confidence.py # Adaptive confidence thresholds
|
|
│ ├── auto_trainer.py # Auto-retraining pipeline
|
|
│ ├── news_agent.py # Economic news filtering
|
|
│ ├── telegram_notifier.py # Telegram alerts
|
|
│ ├── trade_logger.py # Trade logging to DB
|
|
│ ├── utils.py # Utility functions
|
|
│ └── db/ # Database schemas
|
|
├── backtests/ # Backtesting scripts
|
|
│ ├── backtest_live_sync.py # Main backtest (synced with live logic)
|
|
│ └── archive/ # Old backtest versions
|
|
├── scripts/ # Utility scripts
|
|
│ ├── check_market.py # Quick SMC market analysis
|
|
│ ├── check_positions.py # View open positions
|
|
│ ├── check_status.py # Account status check
|
|
│ ├── close_positions.py # Close all positions
|
|
│ ├── modify_tp.py # Modify take-profit levels
|
|
│ └── get_trade_history.py # Pull trade history from MT5
|
|
├── tests/ # Test scripts
|
|
│ ├── test_modules.py # Module integration tests
|
|
│ ├── test_mt5_connection.py# MT5 connection test
|
|
│ └── test_risk_settings.py # Risk settings test
|
|
├── models/ # Trained models (.pkl)
|
|
├── data/ # Market data & trade logs
|
|
├── docs/ # Documentation
|
|
│ ├── arsitektur-ai/ # Architecture docs (23 components)
|
|
│ └── research/ # Research & analysis files
|
|
├── web-dashboard/ # Next.js monitoring dashboard
|
|
├── docker/ # Docker configuration
|
|
│ ├── .env.docker.example # Docker environment template
|
|
│ ├── requirements-docker.txt # Docker-specific Python deps
|
|
│ ├── init-db/ # Database init scripts
|
|
│ ├── scripts/ # Docker helper scripts (.bat/.sh)
|
|
│ └── docs/ # Docker documentation
|
|
├── archive/ # Deprecated files (gitignored)
|
|
└── logs/ # Runtime logs
|
|
```
|
|
|
|
## Key Commands
|
|
|
|
```bash
|
|
# Run the live trading bot
|
|
python main_live.py
|
|
|
|
# Train/retrain ML models
|
|
python train_models.py
|
|
|
|
# Run backtest with threshold tuning
|
|
python backtests/backtest_live_sync.py --tune
|
|
|
|
# Run backtest with specific threshold
|
|
python backtests/backtest_live_sync.py --threshold 0.50 --save
|
|
|
|
# Run module tests
|
|
python tests/test_modules.py
|
|
|
|
# Check market status
|
|
python scripts/check_market.py
|
|
```
|
|
|
|
## Architecture
|
|
|
|
The bot runs an **async candle-based loop** on M15 timeframe:
|
|
|
|
1. **Data Fetch** — Pull OHLCV from MT5, convert to Polars DataFrame
|
|
2. **Feature Engineering** — Calculate 37 technical features (RSI, ATR, MACD, Bollinger, etc.)
|
|
3. **SMC Analysis** — Detect Order Blocks, Fair Value Gaps, BOS, CHoCH
|
|
4. **Regime Detection** — HMM classifies market as trending/ranging/volatile
|
|
5. **ML Prediction** — XGBoost outputs BUY/SELL/HOLD with confidence score
|
|
6. **Entry Filtering** — 11 entry filters must pass (session, regime, spread, cooldown, etc.)
|
|
7. **Risk Sizing** — ATR-based SL, dynamic position sizing, Kelly criterion
|
|
8. **Trade Execution** — Send order to MT5 with broker-level SL/TP
|
|
9. **Position Management** — 10 exit conditions (trailing SL, time exit, regime change, etc.)
|
|
10. **Logging** — Trade logged to PostgreSQL + Telegram notification
|
|
|
|
## Tech Stack
|
|
|
|
- **Python 3.11+** — Main runtime
|
|
- **Polars** — Data engine (not Pandas)
|
|
- **XGBoost** — ML model for signal prediction
|
|
- **hmmlearn** — Hidden Markov Model for regime detection
|
|
- **MetaTrader5** — Broker connection
|
|
- **asyncio + aiohttp** — Async execution & HTTP
|
|
- **loguru** — Structured logging
|
|
- **PostgreSQL** — Trade database
|
|
- **Next.js** — Web dashboard (optional)
|
|
|
|
## Configuration
|
|
|
|
All secrets in `.env`:
|
|
- `MT5_LOGIN`, `MT5_PASSWORD`, `MT5_SERVER`, `MT5_PATH` — Broker credentials
|
|
- `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` — Notifications
|
|
- `CAPITAL` — Trading capital
|
|
- `SYMBOL` — Default: XAUUSD
|
|
|
|
Capital modes auto-configure risk parameters:
|
|
- **MICRO** (<$500): 2% risk/trade
|
|
- **SMALL** ($500-$10k): 1.5% risk/trade
|
|
- **MEDIUM** ($10k-$100k): 0.5% risk/trade
|
|
- **LARGE** (>$100k): 0.25% risk/trade
|
|
|
|
## Important Notes
|
|
|
|
- All data processing uses **Polars**, not Pandas
|
|
- The bot targets **< 50ms per loop** iteration
|
|
- Models are stored as `.pkl` files in `models/`
|
|
- Backtest logic is **synced with live** (`backtest_live_sync.py` mirrors `main_live.py`)
|
|
- Scripts in `scripts/` and `tests/` include `sys.path` fix so they work from any directory
|
|
|
|
---
|
|
|
|
## Versioning System
|
|
|
|
### **Semantic Versioning (SemVer)**
|
|
|
|
XAUBot AI uses **Semantic Versioning 2.0.0**: `MAJOR.MINOR.PATCH`
|
|
|
|
- **MAJOR**: Incompatible API changes, breaking changes (e.g., 1.0.0 → 2.0.0)
|
|
- **MINOR**: New features, backward compatible (e.g., 0.1.0 → 0.2.0)
|
|
- **PATCH**: Bug fixes, backward compatible (e.g., 0.1.0 → 0.1.1)
|
|
|
|
### **Version Files**
|
|
|
|
1. **`VERSION`** - Single source of truth (base version)
|
|
2. **`CHANGELOG.md`** - Detailed change history (Keep a Changelog format)
|
|
3. **`src/version.py`** - Centralized version manager
|
|
|
|
### **Auto-Versioning**
|
|
|
|
Version is **automatically calculated** based on enabled features:
|
|
|
|
```python
|
|
# Base version from VERSION file
|
|
Base: 0.0.0
|
|
|
|
# Feature increments (cumulative):
|
|
+ Kalman Filter → +0.1.0 = 0.1.0
|
|
+ Fuzzy Logic → +0.1.0 = 0.2.0
|
|
+ Kelly Criterion → +0.1.0 = 0.3.0
|
|
+ Trajectory Predictor → +0.1.0 = 0.4.0
|
|
+ Momentum Persistence → +0.1.0 = 0.5.0
|
|
+ Recovery Detector → +0.1.0 = 0.6.0
|
|
|
|
# Effective version: v0.6.0 (Kalman + Fuzzy + Kelly + Predictive)
|
|
```
|
|
|
|
### **Feature Detection**
|
|
|
|
Features auto-detected from:
|
|
- **Environment variables**: `KALMAN_ENABLED`, `ADVANCED_EXITS_ENABLED`, `PREDICTIVE_ENABLED`
|
|
- **Import availability**: Modules in `src/` directory
|
|
- **Runtime checks**: Component initialization
|
|
|
|
### **Version Display**
|
|
|
|
```python
|
|
from src.version import get_version, get_detailed_version
|
|
|
|
print(get_version()) # "0.6.0"
|
|
print(get_detailed_version()) # "v0.6.0 (Kalman + Fuzzy + Kelly + Predictive)"
|
|
```
|
|
|
|
### **Changelog Management**
|
|
|
|
All changes documented in `CHANGELOG.md`:
|
|
|
|
```markdown
|
|
## [0.6.0] - 2026-02-11
|
|
### Added
|
|
- Trajectory Predictor for profit forecasting
|
|
- Momentum Persistence Detector
|
|
- Recovery Strength Analyzer
|
|
|
|
### Changed
|
|
- Exit strategy version: v6.2 → v6.3
|
|
- Fuzzy threshold now dynamic (85-98%)
|
|
|
|
### Fixed
|
|
- ExitReason.STOP_LOSS → POSITION_LIMIT
|
|
```
|
|
|
|
### **Version Update Workflow**
|
|
|
|
1. **Add new feature** → Automatically increments MINOR version
|
|
2. **Fix bug** → Manually increment PATCH in `VERSION` file
|
|
3. **Breaking change** → Manually increment MAJOR in `VERSION` file
|
|
4. **Update CHANGELOG.md** → Document all changes
|
|
5. **Commit** → Version updates committed with changes
|
|
|
|
### **When to Update VERSION File**
|
|
|
|
**Auto-incremented** (no manual change needed):
|
|
- Adding new predictive modules
|
|
- Enabling/disabling feature flags
|
|
- Adding new exit strategies
|
|
|
|
**Manual increment required**:
|
|
- Bug fixes → Increment PATCH (0.6.0 → 0.6.1)
|
|
- Breaking changes → Increment MAJOR (0.6.0 → 1.0.0)
|
|
- Resetting versions → Edit `VERSION` file directly
|
|
|
|
### **Example Version History**
|
|
|
|
```
|
|
v0.0.0 - Initial release (baseline)
|
|
v0.1.0 - Added Kalman Filter
|
|
v0.2.0 - Added Fuzzy Logic Controller
|
|
v0.3.0 - Added Kelly Criterion
|
|
v0.4.0 - Added Trajectory Predictor
|
|
v0.5.0 - Added Momentum Persistence
|
|
v0.6.0 - Added Recovery Detector (v6.3 Predictive Intelligence complete)
|
|
v0.6.1 - Fixed variable scope bug (PATCH)
|
|
v0.7.0 - Added new session filter (MINOR)
|
|
v1.0.0 - Complete rewrite with new ML architecture (MAJOR)
|
|
```
|
|
|
|
### **Version in Logs**
|
|
|
|
```
|
|
============================================================
|
|
XAUBOT AI v0.6.0 (Kalman + Fuzzy + Kelly + Predictive)
|
|
Strategy: Exit v6.3 Predictive Intelligence
|
|
============================================================
|
|
SMART RISK MANAGER v0.6.0 (Exit v6.3 Predictive Intelligence) INITIALIZED
|
|
[OK] Fuzzy Exit Controller initialized
|
|
[OK] Kelly Position Scaler initialized
|
|
[OK] Trajectory Predictor initialized
|
|
[OK] Momentum Persistence initialized
|
|
[OK] Recovery Detector initialized
|
|
Advanced Exits: ENABLED (Kalman + Fuzzy + Kelly + Predictive)
|
|
============================================================
|
|
```
|
|
|
|
### **Best Practices**
|
|
|
|
1. **Always update CHANGELOG.md** when making changes
|
|
2. **Use semantic commit messages**: `feat:`, `fix:`, `docs:`, `refactor:`
|
|
3. **Version tags in git**: `git tag v0.6.0` after stable release
|
|
4. **Document breaking changes** clearly in CHANGELOG
|
|
5. **Test version detection**: `python src/version.py` to verify
|
|
|
|
### **Quick Reference**
|
|
|
|
| Action | Version Impact | Example |
|
|
|--------|---------------|---------|
|
|
| Add feature | +0.1.0 (MINOR) | Predictive Intelligence |
|
|
| Fix bug | +0.0.1 (PATCH) | Variable scope fix |
|
|
| Breaking change | +1.0.0 (MAJOR) | API redesign |
|
|
| Enable feature flag | Auto-detected | `PREDICTIVE_ENABLED=1` |
|
|
| Disable feature | Auto-detected | `KALMAN_ENABLED=0` |
|
|
|
|
---
|