trader-ml/docs/GETTING_STARTED.md

🚀 Guide de Démarrage - Trading AI Secure

📋 Table des Matières

1. Prérequis
2. Installation
3. Configuration
4. Premier Lancement
5. Workflow Développement
6. Tests
7. Troubleshooting

---

💻 Prérequis

Système

• OS : Windows 10/11, Linux (Ubuntu 20.04+), macOS 11+
• Python : 3.11 ou supérieur
• RAM : 8 GB minimum (16 GB recommandé)
• Disque : 10 GB espace libre
• Internet : Connexion stable pour données temps réel

Logiciels

# Python 3.11+
python --version  # Doit afficher 3.11.x ou supérieur

# pip (gestionnaire de paquets)
pip --version

# Git
git --version

# (Optionnel) Docker
docker --version

Connaissances Recommandées

• ✅ Python intermédiaire
• ✅ Bases de trading (ordres, stop-loss, etc.)
• ✅ Notions de machine learning (optionnel)
• ✅ Git basique

---

📥 Installation

Étape 1 : Cloner le Repository

# Cloner le projet
git clone https://github.com/votre-username/trading-ai-secure.git
cd trading-ai-secure

# Vérifier structure
ls -la

Étape 2 : Créer Environnement Virtuel

# Windows
python -m venv venv
venv\Scripts\activate

# Linux/macOS
python3 -m venv venv
source venv/bin/activate

# Vérifier activation (prompt doit afficher (venv))

Étape 3 : Installer Dépendances

# Mettre à jour pip
pip install --upgrade pip

# Installer dépendances
pip install -r requirements.txt

# Vérifier installation
pip list

Étape 4 : Installer Dépendances Optionnelles

# Pour développement
pip install -r requirements-dev.txt

# Pour backtesting avancé
pip install -r requirements-backtest.txt

# Pour production
pip install -r requirements-prod.txt

---

⚙️ Configuration

Étape 1 : Copier Fichiers de Configuration

# Copier templates de configuration
cp config/risk_limits.example.yaml config/risk_limits.yaml
cp config/strategy_params.example.yaml config/strategy_params.yaml
cp config/data_sources.example.yaml config/data_sources.yaml

# NE PAS copier ig_config (contient credentials sensibles)
# Créer manuellement si nécessaire

Étape 2 : Configurer Sources de Données

# config/data_sources.yaml

data_sources:
  # Yahoo Finance (gratuit, illimité)
  yahoo_finance:
    enabled: true
    priority: 1
    
  # Alpha Vantage (gratuit, 500 calls/jour)
  alpha_vantage:
    enabled: true
    api_key: "YOUR_API_KEY_HERE"  # Obtenir sur https://www.alphavantage.co/support/#api-key
    priority: 2
    rate_limit: 500  # calls per day
    
  # Twelve Data (gratuit, 800 calls/jour)
  twelve_data:
    enabled: false
    api_key: "YOUR_API_KEY_HERE"  # Obtenir sur https://twelvedata.com/
    priority: 3
    rate_limit: 800

Étape 3 : Obtenir Clés API Gratuites

Alpha Vantage (Recommandé)

1. Aller sur https://www.alphavantage.co/support/#api-key
2. Entrer email
3. Copier clé API
4. Coller dans config/data_sources.yaml

Twelve Data (Optionnel)

1. Créer compte sur https://twelvedata.com/
2. Aller dans Dashboard → API
3. Copier clé
4. Coller dans config

Étape 4 : Configurer Risk Limits

# config/risk_limits.yaml

global_limits:
  max_portfolio_risk: 0.02        # 2% du capital max
  max_position_size: 0.05         # 5% par position max
  max_correlation: 0.7            # Corrélation max entre positions
  max_drawdown: 0.10              # 10% drawdown max
  daily_loss_limit: 0.03          # 3% perte journalière max

strategy_limits:
  scalping:
    max_trades_per_day: 50
    risk_per_trade: 0.005         # 0.5% par trade
    max_holding_time: 1800        # 30 minutes
    
  intraday:
    max_trades_per_day: 10
    risk_per_trade: 0.015         # 1.5% par trade
    max_holding_time: 86400       # 1 jour
    
  swing:
    max_trades_per_week: 5
    risk_per_trade: 0.025         # 2.5% par trade
    max_holding_time: 432000      # 5 jours

Étape 5 : Variables d'Environnement

# Créer fichier .env
touch .env

# Ajouter variables (NE PAS COMMITER)
echo "ENVIRONMENT=development" >> .env
echo "LOG_LEVEL=INFO" >> .env
echo "INITIAL_CAPITAL=10000" >> .env

---

🎬 Premier Lancement

Mode 1 : Backtesting (Recommandé pour débuter)

# Lancer backtesting sur données historiques
python src/main.py --mode backtest --strategy intraday --symbol EURUSD --period 1y

# Avec paramètres personnalisés
python src/main.py \
  --mode backtest \
  --strategy all \
  --symbol EURUSD,GBPUSD,USDJPY \
  --period 2y \
  --initial-capital 10000

Sortie attendue :

[INFO] Loading historical data for EURUSD...
[INFO] Backtesting intraday strategy...
[INFO] Walk-forward analysis: 12 periods
[INFO] Results:
  - Total Return: 15.3%
  - Sharpe Ratio: 1.82
  - Max Drawdown: 7.2%
  - Win Rate: 58.3%
  - Total Trades: 127

Mode 2 : Paper Trading

# Lancer paper trading (simulation temps réel)
python src/main.py --mode paper --strategy intraday

# Avec dashboard
python src/main.py --mode paper --strategy all --dashboard

Mode 3 : Dashboard Uniquement

# Lancer dashboard Streamlit
streamlit run src/ui/dashboard.py

# Ouvrir navigateur sur http://localhost:8501

---

🔄 Workflow Développement

Workflow Quotidien

# 1. Activer environnement
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# 2. Mettre à jour code
git pull origin main

# 3. Installer nouvelles dépendances si nécessaire
pip install -r requirements.txt

# 4. Lancer tests
pytest tests/

# 5. Développer nouvelle feature
# ... éditer code ...

# 6. Tester localement
python src/main.py --mode backtest --strategy your_strategy

# 7. Commit et push
git add .
git commit -m "feat: add new strategy"
git push origin your-branch

Structure Développement

Développement d'une nouvelle stratégie:

1. Créer fichier stratégie
   src/strategies/your_strategy/your_strategy.py

2. Hériter de BaseStrategy
   class YourStrategy(BaseStrategy):
       ...

3. Implémenter méthodes requises
   - calculate_indicators()
   - analyze()
   - _calculate_confidence()

4. Créer tests
   tests/test_your_strategy.py

5. Backtester
   python src/main.py --mode backtest --strategy your_strategy

6. Valider métriques
   - Sharpe > 1.5
   - Max DD < 10%
   - Win Rate > 55%

7. Paper trading 30 jours
   python src/main.py --mode paper --strategy your_strategy

---

🧪 Tests

Lancer Tests Unitaires

# Tous les tests
pytest

# Tests spécifiques
pytest tests/test_risk_manager.py
pytest tests/test_strategies.py

# Avec couverture
pytest --cov=src tests/

# Avec rapport HTML
pytest --cov=src --cov-report=html tests/
# Ouvrir htmlcov/index.html

Tests d'Intégration

# Tests intégration données
pytest tests/integration/test_data_sources.py

# Tests intégration IG (nécessite credentials)
pytest tests/integration/test_ig_api.py --ig-demo

Tests de Performance

# Benchmark stratégies
python tests/benchmark/benchmark_strategies.py

# Profiling
python -m cProfile -o profile.stats src/main.py --mode backtest
python -m pstats profile.stats

---

🐛 Troubleshooting

Problème : Installation Dépendances Échoue

# Erreur: "Could not find a version that satisfies the requirement..."

# Solution 1: Mettre à jour pip
pip install --upgrade pip setuptools wheel

# Solution 2: Installer individuellement
pip install numpy pandas scikit-learn

# Solution 3: Utiliser conda (si disponible)
conda install -c conda-forge numpy pandas scikit-learn

Problème : Erreur Import Module

# Erreur: "ModuleNotFoundError: No module named 'src'"

# Solution: Ajouter projet au PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)"  # Linux/macOS
set PYTHONPATH=%PYTHONPATH%;%CD%          # Windows

# Ou installer en mode développement
pip install -e .

Problème : API Rate Limit Dépassé

# Erreur: "API rate limit exceeded"

# Solution 1: Utiliser cache
# Éditer config/data_sources.yaml
cache:
  enabled: true
  ttl: 3600  # 1 heure

# Solution 2: Alterner sources
# Activer multiple sources dans config

# Solution 3: Réduire fréquence requêtes
# Augmenter timeframe ou réduire nombre de symboles

Problème : Backtesting Trop Lent

# Solution 1: Réduire période
python src/main.py --mode backtest --period 6m  # 6 mois au lieu de 2 ans

# Solution 2: Utiliser données cached
# Activer cache dans config

# Solution 3: Paralléliser
python src/main.py --mode backtest --parallel --workers 4

Problème : Dashboard Ne Se Lance Pas

# Erreur: "streamlit: command not found"

# Solution: Réinstaller streamlit
pip install --upgrade streamlit

# Vérifier installation
streamlit --version

# Lancer avec chemin complet
python -m streamlit run src/ui/dashboard.py

Problème : Credentials IG Invalides

# Erreur: "Authentication failed"

# Vérifications:
# 1. API key correcte
# 2. Username/password corrects
# 3. Compte démo activé
# 4. Pas de caractères spéciaux dans password

# Tester connexion
python tests/test_ig_connection.py

---

📚 Ressources Supplémentaires

Documentation

• Architecture Détaillée
• Framework IA
• Risk Management
• Guide Stratégies
• Backtesting
• Intégration IG

Tutoriels

# Tutoriel 1: Créer première stratégie
python tutorials/01_create_strategy.py

# Tutoriel 2: Backtesting avancé
python tutorials/02_advanced_backtesting.py

# Tutoriel 3: Optimisation paramètres
python tutorials/03_parameter_optimization.py

Exemples

# Exemples de stratégies
ls examples/strategies/

# Exemples de backtests
ls examples/backtests/

# Exemples de configurations
ls examples/configs/

---

🎯 Prochaines Étapes

Semaine 1 : Familiarisation

• Installer et configurer environnement
• Lancer premier backtest
• Explorer dashboard
• Lire documentation

Semaine 2 : Expérimentation

• Tester différentes stratégies
• Ajuster paramètres risk
• Analyser résultats backtests
• Comprendre métriques

Semaine 3 : Développement

• Créer première stratégie custom
• Implémenter tests
• Backtester sur multiple périodes
• Optimiser paramètres

Semaine 4 : Validation

• Walk-forward analysis
• Monte Carlo simulation
• Paper trading
• Documenter résultats

---

💬 Support

Obtenir de l'Aide

1. Documentation : Lire docs/ en premier
2. Issues GitHub : Créer issue si bug
3. Discussions : Forum communauté
4. Discord : Chat temps réel

Contribuer

Voir CONTRIBUTING.md pour guidelines.

---

Bon trading ! 🚀