trader-ml/src/README.md

📁 Source Code - Trading AI Secure

🎯 Vue d'ensemble

Ce dossier contient tout le code source de l'application Trading AI Secure.

---

📂 Structure

src/
├── __init__.py                 # Package principal
├── main.py                     # Point d'entrée
│
├── core/                       # Modules centraux
│   ├── __init__.py
│   ├── risk_manager.py        # Risk Manager (Singleton)
│   └── strategy_engine.py     # Orchestrateur stratégies
│
├── strategies/                 # Stratégies de trading
│   ├── __init__.py
│   ├── base_strategy.py       # Classe abstraite
│   ├── scalping/              # À créer
│   ├── intraday/              # À créer
│   └── swing/                 # À créer
│
├── data/                       # Connecteurs données (À créer)
├── ml/                         # Machine Learning (À créer)
├── backtesting/                # Backtesting (À créer)
├── ui/                         # Interface (À créer)
├── monitoring/                 # Monitoring (À créer)
└── utils/                      # Utilitaires
    ├── __init__.py
    ├── logger.py              # Système de logging
    └── config_loader.py       # Chargeur configuration

---

🚀 Utilisation

Lancer l'Application

# Backtesting
python src/main.py --mode backtest --strategy intraday --symbol EURUSD

# Paper trading
python src/main.py --mode paper --strategy all

# Optimisation
python src/main.py --mode optimize --strategy scalping

Importer des Modules

# Risk Manager
from src.core.risk_manager import RiskManager

risk_manager = RiskManager()
is_valid, error = risk_manager.validate_trade(...)

# Strategy Engine
from src.core.strategy_engine import StrategyEngine

engine = StrategyEngine(config, risk_manager)
await engine.load_strategy('intraday')
await engine.run()

# Logging
from src.utils.logger import setup_logger, get_logger

setup_logger(level='INFO')
logger = get_logger(__name__)
logger.info("Message")

# Configuration
from src.utils.config_loader import ConfigLoader

config = ConfigLoader.load_all()
risk_limits = config['risk_limits']

---

📚 Modules Détaillés

Core

RiskManager (core/risk_manager.py)

Responsabilités :

• Validation pré-trade (10 vérifications)
• Gestion des positions
• Calcul métriques de risque (VaR, CVaR, drawdown)
• Circuit breakers
• Statistiques

Usage :

risk_manager = RiskManager()
risk_manager.initialize(config)

# Valider trade
is_valid, error = risk_manager.validate_trade(
    symbol='EURUSD',
    quantity=1000,
    price=1.1000,
    stop_loss=1.0950,
    take_profit=1.1100,
    strategy='intraday'
)

# Métriques
metrics = risk_manager.get_risk_metrics()
print(f"VaR: ${metrics.portfolio_var:.2f}")

StrategyEngine (core/strategy_engine.py)

Responsabilités :

• Chargement dynamique des stratégies
• Boucle principale de trading
• Distribution données marché
• Collecte et filtrage signaux
• Exécution ordres

Usage :

engine = StrategyEngine(config, risk_manager)

# Charger stratégies
await engine.load_strategy('scalping')
await engine.load_strategy('intraday')

# Lancer
await engine.run()

Strategies

BaseStrategy (strategies/base_strategy.py)

Classe abstraite pour toutes les stratégies.

Méthodes à implémenter :

• analyze(market_data) : Génère signaux
• calculate_indicators(data) : Calcule indicateurs

Méthodes fournies :

• calculate_position_size() : Kelly Criterion
• update_parameters() : Paramètres adaptatifs
• record_trade() : Enregistrement trades

Usage :

from src.strategies.base_strategy import BaseStrategy

class MyStrategy(BaseStrategy):
    def analyze(self, market_data):
        # Implémenter logique
        df = self.calculate_indicators(market_data)
        
        if condition:
            return Signal(...)
        return None
    
    def calculate_indicators(self, data):
        # Calculer indicateurs
        data['sma_20'] = data['close'].rolling(20).mean()
        return data

Utils

Logger (utils/logger.py)

Fonctionnalités :

• Logs console colorés
• Logs fichiers avec rotation
• Niveaux configurables

Usage :

from src.utils.logger import setup_logger, get_logger

# Setup (une fois au démarrage)
setup_logger(level='INFO', log_dir='logs')

# Utiliser
logger = get_logger(__name__)
logger.info("Info message")
logger.warning("Warning message")
logger.error("Error message")

ConfigLoader (utils/config_loader.py)

Fonctionnalités :

• Chargement YAML
• Accès centralisé

Usage :

from src.utils.config_loader import ConfigLoader

# Charger toute la config
config = ConfigLoader.load_all()

# Ou spécifique
risk_limits = ConfigLoader.get_risk_limits()
strategy_params = ConfigLoader.get_strategy_params('intraday')

---

🧪 Tests

Lancer les Tests

# Tous les tests
pytest tests/

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

# Avec couverture
pytest --cov=src tests/

Écrire des Tests

# tests/unit/test_risk_manager.py

import pytest
from src.core.risk_manager import RiskManager

def test_singleton():
    rm1 = RiskManager()
    rm2 = RiskManager()
    assert rm1 is rm2

def test_validate_trade():
    rm = RiskManager()
    is_valid, error = rm.validate_trade(...)
    assert is_valid is True

---

📝 Conventions de Code

Style

• PEP 8 : Respecter PEP 8
• Type Hints : Obligatoires sur tous les paramètres et retours
• Docstrings : Google style pour toutes les classes et méthodes
• Imports : Organisés (stdlib, third-party, local)

Exemple

"""
Module description.

Detailed explanation of what this module does.
"""

from typing import Dict, List, Optional
import numpy as np

from src.core.risk_manager import RiskManager


class MyClass:
    """
    Brief description.
    
    Detailed description of the class.
    
    Attributes:
        attr1: Description
        attr2: Description
    """
    
    def __init__(self, param1: str, param2: int):
        """
        Initialize MyClass.
        
        Args:
            param1: Description
            param2: Description
        """
        self.attr1 = param1
        self.attr2 = param2
    
    def my_method(self, arg1: float) -> bool:
        """
        Brief description.
        
        Detailed description of what the method does.
        
        Args:
            arg1: Description
            
        Returns:
            Description of return value
            
        Raises:
            ValueError: When something is wrong
        """
        if arg1 < 0:
            raise ValueError("arg1 must be positive")
        
        return True

---

🔧 Développement

Ajouter une Nouvelle Stratégie

1. Créer fichier : src/strategies/my_strategy/my_strategy.py

2. Hériter de BaseStrategy :

from src.strategies.base_strategy import BaseStrategy, Signal

class MyStrategy(BaseStrategy):
    def analyze(self, market_data):
        # Implémenter
        pass
    
    def calculate_indicators(self, data):
        # Implémenter
        pass

3. Ajouter configuration : config/strategy_params.yaml

4. Charger dans StrategyEngine : Modifier strategy_engine.py

5. Tester : Créer tests/unit/test_my_strategy.py

Ajouter un Nouveau Module

1. Créer dossier : src/my_module/

2. Créer __init__.py : Exports du module

3. Créer fichiers : Implémenter fonctionnalités

4. Documenter : Ajouter README dans le module

5. Tester : Créer tests unitaires

---

📊 Métriques de Code

Couverture Actuelle

Module	Fichiers	Lignes	Couverture	Statut
core	2	~1,000	0%	⏳ À tester
strategies	1	~450	0%	⏳ À tester
utils	2	~270	0%	⏳ À tester
TOTAL	5	~1,720	0%	⏳ À tester

Objectif : 85% de couverture

---

🐛 Debugging

Activer Debug Logging

python src/main.py --log-level DEBUG --mode backtest --strategy intraday

Profiling

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

# Memory profiling
python -m memory_profiler src/main.py --mode backtest

---

📚 Ressources

• Documentation Complète
• Guide de Contribution
• Architecture
• Risk Framework

---

Code maintenu par l'équipe Trading AI Secure
Version : 0.1.0-alpha
Dernière mise à jour : 2024-01-15