trader-ml/docs/GETTING_STARTED.md

# 🚀 Guide de Démarrage - Trading AI Secure

## 📋 Table des Matières
1. [Prérequis](#prérequis)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Premier Lancement](#premier-lancement)
5. [Workflow Développement](#workflow-développement)
6. [Tests](#tests)
7. [Troubleshooting](#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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```yaml
# 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

```yaml
# 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

```bash
# 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)

```bash
# 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

```bash
# 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

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

# Ouvrir navigateur sur http://localhost:8501
```

---

## 🔄 Workflow Développement

### Workflow Quotidien

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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é

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](ARCHITECTURE.md)
- [Framework IA](AI_FRAMEWORK.md)
- [Risk Management](RISK_FRAMEWORK.md)
- [Guide Stratégies](STRATEGY_GUIDE.md)
- [Backtesting](BACKTESTING_GUIDE.md)
- [Intégration IG](IG_INTEGRATION.md)

### Tutoriels

```bash
# 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

```bash
# 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](CONTRIBUTING.md) pour guidelines.

---

**Bon trading ! 🚀**