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

# 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"
}

# 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"
}

# 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 :

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.