trader-ml/docs/RL_STRATEGY_GUIDE.md

# RL Strategy Guide — Phase 4d (Reinforcement Learning)

## Vue d'ensemble

La Phase 4d introduit une stratégie pilotée par un agent de **Reinforcement Learning (RL)**
basé sur l'algorithme **PPO** (Proximal Policy Optimization). Contrairement aux stratégies
supervisées (XGBoost, CNN) qui s'entraînent sur des labels pré-calculés, l'agent RL apprend
directement par interaction avec un environnement de trading simulé (`TradingEnv`), sans avoir
besoin d'annotations explicites LONG/SHORT/NEUTRAL.

---

## Architecture

### Composants (implémentés par l'agent ml/rl/)

```
src/ml/rl/
├── trading_env.py          # TradingEnv (Gymnasium) — environnement de simulation
├── ppo_model.py            # PPOModel — réseau Actor-Critic (MLP)
└── rl_strategy_model.py    # RLStrategyModel — interface train/predict/save/load
```

### Composants (cette phase)

```
src/strategies/rl_driven/
├── __init__.py             # Export RLDrivenStrategy
└── rl_strategy.py          # RLDrivenStrategy (hérite BaseStrategy)
```

### Pipeline d'entraînement PPO

```
Données OHLCV
    │
    ▼
TradingEnv (Gymnasium)
    ├── Observation space : fenêtre glissante seq_len=20 barres (OHLCV normalisé)
    ├── Action space      : {0=HOLD/NEUTRAL, 1=LONG, 2=SHORT}
    └── Reward            : P&L réalisé − pénalité drawdown − pénalité over-trading
    │
    ▼
PPO Actor-Critic (MLP)
    ├── Actor  : policy π(a|s) → distribution sur les actions
    └── Critic : value function V(s) → estimation de la récompense future
    │
    ▼
Optimisation sur total_timesteps pas
    │
    ▼
RLStrategyModel.save()
    ├── models/rl_strategy/EURUSD_1h.zip   (politique PPO)
    └── models/rl_strategy/EURUSD_1h_meta.json
```

### Architecture Actor-Critic

L'agent PPO utilise un réseau MLP (Multi-Layer Perceptron) à deux têtes :

- **Actor** : prédit la distribution de probabilité sur les 3 actions (LONG/SHORT/NEUTRAL).
  La confiance du signal correspond à `max(probas)`.
- **Critic** : estime la valeur d'état V(s) pour calculer l'avantage (advantage) utilisé
  lors de la mise à jour de la politique.

Hyperparamètres PPO typiques :
| Paramètre     | Valeur par défaut | Description                                  |
|---------------|-------------------|----------------------------------------------|
| `gamma`       | 0.99              | Facteur d'actualisation des récompenses      |
| `clip_range`  | 0.2               | Clipping ratio PPO (stabilité)               |
| `n_steps`     | 2048              | Nombre de pas par rollout                    |
| `batch_size`  | 64                | Taille des mini-batches SGD                  |
| `n_epochs`    | 10                | Passes sur chaque rollout                    |
| `ent_coef`    | 0.01              | Coefficient d'entropie (exploration)         |

---

## Lancer l'entraînement

### Via curl

```bash
# Lancer l'entraînement (tâche de fond)
curl -X POST http://localhost:8100/trading/train-rl \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "EURUSD",
    "timeframe": "1h",
    "period": "2y",
    "total_timesteps": 50000
  }'

# Réponse
{
  "job_id": "a1b2c3d4-...",
  "status": "pending",
  "symbol": "EURUSD",
  "timeframe": "1h"
}
```

```bash
# Suivre l'avancement
curl http://localhost:8100/trading/train-rl/a1b2c3d4-...

# Réponse quand terminé
{
  "job_id": "a1b2c3d4-...",
  "status": "completed",
  "symbol": "EURUSD",
  "timeframe": "1h",
  "avg_reward": 0.042,
  "sharpe_env": 1.23,
  "total_timesteps": 50000,
  "trained_at": "2026-03-10T14:32:00"
}
```

```bash
# Lister les modèles disponibles
curl http://localhost:8100/trading/rl-models

# Réponse
{
  "models": [
    {
      "symbol": "EURUSD",
      "timeframe": "1h",
      "avg_reward": 0.042,
      "sharpe_env": 1.23,
      "total_timesteps": 50000,
      "trained_at": "2026-03-10T14:32:00"
    }
  ],
  "count": 1
}
```

### Paramètres de la requête

| Champ             | Type  | Défaut   | Description                                             |
|-------------------|-------|----------|---------------------------------------------------------|
| `symbol`          | str   | EURUSD   | Paire de trading (ex: EURUSD, BTCUSDT)                 |
| `timeframe`       | str   | 1h       | Timeframe (1m, 5m, 15m, 1h, 4h, 1d)                   |
| `period`          | str   | 2y       | Historique d'entraînement (ex: 6m, 1y, 2y)             |
| `total_timesteps` | int   | 50000    | Nombre total de pas de simulation PPO                  |

**Recommandations `total_timesteps` :**
- 20 000 : entraînement rapide (test, ~5 min CPU)
- 50 000 : entraînement standard (défaut, ~15 min CPU)
- 200 000 : entraînement long, meilleure convergence (~1h CPU)
- 1 000 000 : entraînement poussé si GPU disponible

---

## Interpréter les métriques

### `avg_reward`
Récompense moyenne par pas de simulation sur les derniers rollouts d'évaluation.

- **< 0** : l'agent perd de l'argent en simulation → entraîner plus longtemps ou revoir la fonction de récompense
- **0 à 0.02** : agent neutre, légèrement profitable
- **> 0.05** : bon signal → tester en backtest réel
- **> 0.1** : excellent (attention au sur-apprentissage, vérifier out-of-sample)

### `sharpe_env`
Ratio de Sharpe calculé sur les épisodes de simulation (récompenses / écart-type des récompenses).

- **< 0.5** : insuffisant pour paper trading
- **0.5 – 1.0** : acceptable, à valider en backtest
- **> 1.5** : cible pour activation paper trading (conforme aux seuils du projet)

### Interprétation combinée

| `avg_reward` | `sharpe_env` | Interprétation                                         |
|--------------|--------------|--------------------------------------------------------|
| négatif      | quelconque   | Agent non convergé — relancer avec plus de timesteps   |
| 0 – 0.02     | < 1.0        | Apprentissage partiel — augmenter total_timesteps      |
| > 0.03       | > 1.0        | Bon candidat — valider via POST /trading/backtest      |
| > 0.05       | > 1.5        | Prêt pour paper trading (30 jours minimum)             |

---

## Intégration avec le paper trading

Après l'entraînement, si un paper trading avec la stratégie `rl_driven` est actif,
le modèle est **automatiquement attaché** sans redémarrage.

Pour démarrer un paper trading RL :

```bash
curl -X POST http://localhost:8100/trading/paper/start \
  -H "Content-Type: application/json" \
  -d '{"strategy": "rl_driven", "symbol": "EURUSD"}'
```

La stratégie `RLDrivenStrategy` :
1. Charge le dernier modèle entraîné pour le symbole/timeframe
2. À chaque barre, fournit les 20 dernières bougies à l'agent (`seq_len=20`)
3. Si la confiance de l'agent >= `min_confidence` (défaut: 0.55), émet un signal
4. SL = `sl_atr_mult × ATR` (défaut: 1×ATR), TP = `tp_atr_mult × ATR` (défaut: 2×ATR)

---

## Notes techniques

### Threads PyTorch
L'entraînement fixe `torch.set_num_threads(4)` pour éviter la contention CPU dans
le container Docker. Adapter dans `docker-compose.yml` si le container dispose de plus de cœurs.

### Sauvegarde des modèles
Les modèles sont sauvegardés dans `models/rl_strategy/` (volume Docker monté) :
- `EURUSD_1h.zip` : politique PPO (format stable-baselines3)
- `EURUSD_1h_meta.json` : métadonnées (métriques, hyperparamètres, date)

### Import conditionnel
Le flag `RL_AVAILABLE` est `False` si PyTorch ou stable-baselines3 ne sont pas
installés. La stratégie dégrade gracieusement (aucun signal, aucune exception).
Pour activer : ajouter `stable-baselines3` et `gymnasium` dans `docker/requirements/api.txt`
puis reconstruire le container (`docker compose build --no-cache trading-api`).

---

## Seuils de validation (conforme au projet)

Avant activation du live trading, la stratégie RL doit satisfaire :

| Métrique        | Seuil minimum |
|-----------------|---------------|
| Sharpe Ratio    | ≥ 1.5         |
| Max Drawdown    | ≤ 10%         |
| Win Rate        | ≥ 55%         |
| Paper Trading   | ≥ 30 jours    |

Ces seuils s'appliquent au **backtest out-of-sample** et au **paper trading**, pas
aux métriques de simulation RL (`sharpe_env`) qui sont indicatives uniquement.