Champollion - Architecture S3

Version: 1.0.0 (Sprint 9) Date: Janvier 2026 Status: Production Ready

---

Table des Matières

1. Vue d'Ensemble
2. Configuration S3
3. Buckets et Structure
4. Services Utilisant S3
5. API et SDK
6. Patterns d'Utilisation
7. Sécurité et Authentification
8. Bonnes Pratiques

---

1. Vue d'Ensemble

Champollion utilise Amazon S3 comme backend de stockage principal pour : - Artefacts MLflow : Modèles, métriques, pipelines sérialisés - Cache Feature Engineering : Datasets préprocessés - Feature Store : Données offline Feast (Parquet) - Données brutes : Features enrichies avant labellisation

Principe Fondamental

Aucune écriture locale permanente - Tout le stockage passe par : - PostgreSQL : Métadonnées, index, registres (MLflow tracking, Feast registry) - S3 : Fichiers binaires, artefacts, données volumineuses

---

2. Configuration S3

2.1 Variables d'Environnement

# .env
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=eu-west-3

# Buckets
S3_BUCKET_NAME=champollion
MLFLOW_ARTIFACT_ROOT=s3://cvntrade-mlflow-artifacts/

# MLflow Backend (PostgreSQL)
MLFLOW_TRACKING_URI=postgresql://mlflow:mlflow@localhost:5432/champollion

2.2 Buckets Utilisés

Bucket	Usage	Region
champollion	Cache FE, features brutes, données training	eu-west-3
cvntrade-mlflow-artifacts	Artefacts MLflow (modèles, métriques)	eu-west-3

---

3. Buckets et Structure

3.1 Bucket champollion

Structure des répertoires :

champollion/
├── cache/
│   ├── fe/                           # Cache Feature Engineering
│   │   ├── fe_BTCUSDT_1h_v2.5.joblib
│   │   ├── fe_ETHUSDT_1h_v2.5.joblib
│   │   └── ...
│   │
│   ├── labels/                       # Cache Labels
│   │   ├── labels_BTCUSDT_1h.joblib
│   │   └── ...
│   │
│   ├── hpo/                          # Cache HPO
│   │   ├── hpo_xgboost_BTCUSDT.joblib
│   │   └── ...
│   │
│   └── models/                       # Modèles sérialisés
│       ├── xgboost_gate_BTCUSDT.pkl
│       └── ...
│
├── features/                         # Features brutes
│   ├── BTCUSDT_features.parquet
│   ├── ETHUSDT_features.parquet
│   └── ...
│
├── training_patterns/                # Patterns de training
│   ├── BTCUSDT/
│   │   ├── pattern_analysis.json
│   │   └── ...
│   └── ...
│
└── feast_offline/                    # Feast offline store
    └── feature_repo/
        └── data/
            ├── raw_ohlcv.parquet
            ├── momentum_indicators.parquet
            └── ...

3.2 Bucket cvntrade-mlflow-artifacts

Structure MLflow standard :

cvntrade-mlflow-artifacts/
├── <experiment_id>/
│   └── <run_id>/
│       └── artifacts/
│           ├── model/                 # Modèle sklearn/xgboost
│           │   ├── model.pkl
│           │   ├── MLmodel
│           │   └── requirements.txt
│           │
│           ├── feature_engineering_pipeline_2D/
│           │   └── fe_pipeline.joblib
│           │
│           ├── column_filter/
│           │   └── colonnes_retenues.json
│           │
│           ├── datasets/
│           │   └── BTCUSDT/
│           │       ├── BTCUSDT_1h-60m_train.npz
│           │       ├── BTCUSDT_1h-60m_val.npz
│           │       └── BTCUSDT_1h-60m_test.npz
│           │
│           ├── shap/
│           │   ├── shap_local_BTCUSDT.npy
│           │   └── shap_global_BTCUSDT.csv
│           │
│           └── metrics/
│               └── classification_report.json

---

4. Services Utilisant S3

4.1 CVNTrade_MLFlowManager

Fichier : src/commun/mlflow/cvntrade_mlflow_manager.py

Point d'entrée centralisé pour toutes les opérations MLflow/S3 :

from commun.mlflow.cvntrade_mlflow_manager import CVNTrade_MLFlowManager

mlflow_manager = CVNTrade_MLFlowManager("CVNTrade_Gate")

# Log artefact vers S3
mlflow_manager.log_artifact(
    local_path="/tmp/model.pkl",
    artifact_path="model",
    run_id=run_id
)

# Télécharger depuis S3
local_path = mlflow_manager.download_artifacts(
    run_id=run_id,
    artifact_path="model/model.pkl",
    dst_path="/tmp"
)

# Sérialisation directe
mlflow_manager.log_serialized_artifact(
    obj=pipeline,
    artifact_name="fe_pipeline.joblib",
    artifact_path="feature_engineering",
    run_id=run_id,
    method="joblib"
)

4.2 CVNTrade_CacheManager

Fichier : src/commun/cache/cvntrade_cache_manager.py

Gestion du cache FE sur S3 :

from commun.cache.cvntrade_cache_manager import CVNTrade_CacheManager

cache = CVNTrade_CacheManager("feature_engineering")

# Sauvegarder cache sur S3
cache.save_joblib_cache(data, "fe", "fe_BTCUSDT_1h_v2.5")

# Charger cache depuis S3
data = cache.load_joblib_cache("fe", "fe_BTCUSDT_1h_v2.5")

4.3 CVNTrade_S3Manager

Fichier : src/commun/s3/cvntrade_s3_manager.py

Opérations S3 bas niveau :

from commun.s3.cvntrade_s3_manager import CVNTrade_S3Manager

s3 = CVNTrade_S3Manager()

# Upload fichier
s3.upload_file("/tmp/data.parquet", "features/BTCUSDT_features.parquet")

# Download fichier
s3.download_file("features/BTCUSDT_features.parquet", "/tmp/data.parquet")

# Lister objets
objects = s3.list_objects("cache/fe/")

# Vérifier existence
exists = s3.object_exists("features/BTCUSDT_features.parquet")

4.4 CVNTrade_ETLPipeline

Fichier : src/ETL/cvntrade_etl_pipeline.py

Export features vers S3 :

from ETL.cvntrade_etl_pipeline import CVNTrade_ETLPipeline

etl = CVNTrade_ETLPipeline(mode="froid", coin="BTCUSDT")

# Sauvegarde features sur S3
etl.save_features_to_s3(df_features)

# Chargement features depuis S3
df = etl.get_features_from_s3("BTCUSDT")

4.5 Feast Offline Store

Fichier : feature_repo/feature_store.yaml

Feast utilise S3 via le provider Dask :

offline_store:
  type: dask
  # Les fichiers Parquet sont stockés sur S3

---

5. API et SDK

5.1 boto3 (SDK AWS)

Champollion utilise boto3 pour toutes les opérations S3 :

import boto3

# Client S3
s3_client = boto3.client(
    's3',
    aws_access_key_id=os.getenv('AWS_ACCESS_KEY_ID'),
    aws_secret_access_key=os.getenv('AWS_SECRET_ACCESS_KEY'),
    region_name=os.getenv('AWS_DEFAULT_REGION', 'eu-west-3')
)

# Opérations courantes
s3_client.upload_file(local_path, bucket, key)
s3_client.download_file(bucket, key, local_path)
s3_client.list_objects_v2(Bucket=bucket, Prefix=prefix)
s3_client.delete_object(Bucket=bucket, Key=key)

5.2 MLflow S3 Backend

MLflow utilise S3 comme artifact store via URI :

import mlflow

# Configuration automatique via MLFLOW_ARTIFACT_ROOT
mlflow.set_tracking_uri(os.getenv("MLFLOW_TRACKING_URI"))

# Les artefacts sont automatiquement stockés sur S3
mlflow.log_artifact("model.pkl")

---

6. Patterns d'Utilisation

6.1 Pattern Tempfile → S3

Pour éviter toute écriture locale permanente :

import tempfile

def save_to_s3(data, s3_path):
    with tempfile.TemporaryDirectory() as tmpdir:
        # Écriture temporaire
        local_path = f"{tmpdir}/data.joblib"
        joblib.dump(data, local_path)

        # Upload vers S3
        s3_manager.upload_file(local_path, s3_path)

    # Fichier local automatiquement supprimé

6.2 Pattern Cache-or-Generate avec S3

def get_features(symbol: str) -> pd.DataFrame:
    cache_key = f"features/{symbol}_features.parquet"

    # 1. Vérifier cache S3
    if s3_manager.object_exists(cache_key):
        return s3_manager.download_parquet(cache_key)

    # 2. Générer features
    df = generate_features(symbol)

    # 3. Sauvegarder sur S3
    s3_manager.upload_parquet(df, cache_key)

    return df

6.3 Pattern MLflow Artifact Logging

def save_model_artifacts(model, run_id: str):
    with tempfile.TemporaryDirectory() as tmpdir:
        # 1. Sérialiser modèle
        model_path = f"{tmpdir}/model.pkl"
        mlflow_manager.serialize_object(model, model_path, method="pickle")

        # 2. Log vers MLflow (→ S3)
        mlflow_manager.log_artifact(
            model_path,
            artifact_path="model",
            run_id=run_id
        )

---

7. Sécurité et Authentification

7.1 Méthode d'Authentification

Champollion utilise les IAM Credentials via variables d'environnement :

AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...

7.2 Permissions Requises

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::champollion/*",
                "arn:aws:s3:::champollion",
                "arn:aws:s3:::cvntrade-mlflow-artifacts/*",
                "arn:aws:s3:::cvntrade-mlflow-artifacts"
            ]
        }
    ]
}

7.3 Bonnes Pratiques Sécurité

1. Ne jamais committer les credentials - Utiliser .env (dans .gitignore)
2. Rotation régulière - Changer les clés tous les 90 jours
3. Principe du moindre privilège - Limiter aux buckets nécessaires
4. Encryption at rest - Activer SSE-S3 sur les buckets

---

8. Bonnes Pratiques

8.1 Organisation des Données

Type	Bucket	Préfixe	Format
Cache FE	champollion	cache/fe/	joblib
Cache Labels	champollion	cache/labels/	joblib
Cache HPO	champollion	cache/hpo/	joblib
Features brutes	champollion	features/	parquet
Modèles MLflow	cvntrade-mlflow-artifacts	<exp>/<run>/artifacts/model/	pkl
Pipelines FE	cvntrade-mlflow-artifacts	<exp>/<run>/artifacts/feature_engineering/	joblib
SHAP	cvntrade-mlflow-artifacts	<exp>/<run>/artifacts/shap/	npy/csv

8.2 Nommage des Clés

Convention de nommage des objets S3 :

cache/fe/fe_{SYMBOL}_{TIMEFRAME}_v{VERSION}.joblib
features/{SYMBOL}_features.parquet

Exemples : - cache/fe/fe_BTCUSDT_1h_v2.5.joblib - features/BTCUSDT_features.parquet

8.3 Gestion du Cycle de Vie

# Expiration automatique des caches anciens
CACHE_TTL_DAYS = 7  # Variable d'environnement

# Nettoyage manuel via CVNTradeCacheIndex
from commun.cache.cvntrade_cache_index import CVNTradeCacheIndex
cache_index = CVNTradeCacheIndex()
cache_index.cleanup_old_entries(max_age_days=30)

8.4 Force Refresh

Pour invalider le cache S3 :

# Variable d'environnement
export CVN_FORCE_REFRESH=1

# Ou via code
cache_manager = CVNTrade_CacheManager("feature_engineering")
if cache_manager.is_refresh_enabled():
    # Régénérer les données
    pass

---

Références

• architecture/OVERVIEW.md - Vue d'ensemble
• architecture/CACHE.md - Système de cache
• architecture/MLFLOW.md - Design MLflow
• AWS S3 Documentation
• boto3 Documentation

---

Dernière mise à jour : Janvier 2026