seo-generator-server/lib/validation/README.md

# Pipeline Validator - Backend Core

## 📋 Description

Système de validation qualitative pour évaluer objectivement l'évolution du contenu généré à travers les différentes étapes d'un pipeline via évaluations LLM.

## 🎯 Fonctionnalités

- **Exécution pipeline** avec sauvegarde automatique de toutes les versions (v1.0, v1.1, v1.2, v2.0)
- **Échantillonnage intelligent** : sélection automatique des balises représentatives
  - Tous les titres (balises `T*`)
  - 4 contenus principaux (balises `MC*`, `L*`)
  - 4 FAQ (balises `FAQ*`)
- **Évaluation LLM** selon 5 critères universels :
  1. **Qualité globale** - Grammaire, syntaxe, cohérence
  2. **Verbosité** - Concision vs fluff
  3. **SEO** - Intégration naturelle des mots-clés
  4. **Répétitions** - Variété lexicale
  5. **Naturalité humaine** - Détection vs IA
- **Agrégation scores** : moyennes par version et par critère
- **Rapport complet** : JSON structuré avec tous les résultats

## 📁 Architecture

```
lib/validation/
├── ValidatorCore.js          # Orchestrateur principal
├── SamplingEngine.js          # Échantillonnage automatique
├── CriteriaEvaluator.js       # Évaluations LLM multi-critères
├── test-validator.js          # Test Phase 1 (sans LLM)
├── test-validator-phase2.js   # Test Phase 2 (avec LLM)
└── README.md                  # Ce fichier

validations/{uuid}/            # Dossier généré par validation
├── config.json               # Configuration utilisée
├── report.json               # Rapport final
├── versions/
│   ├── v1.0.json            # Contenu après génération
│   ├── v1.1.json            # Contenu après step 1
│   ├── v1.2.json            # Contenu après step 2
│   └── v2.0.json            # Contenu final
├── samples/
│   ├── all-samples.json     # Échantillons extraits
│   └── summary.json         # Résumé échantillons
└── results/
    └── evaluations.json     # Évaluations LLM complètes
```

## 🚀 Utilisation

### Test Phase 1 (sans évaluations LLM)

```bash
node lib/validation/test-validator.js
```

**Durée** : ~2-3 minutes (génération + échantillonnage)

**Résultat** : Validation avec pipeline exécuté et échantillons extraits, SANS évaluations LLM.

### Test Phase 2 (avec évaluations LLM)

```bash
node lib/validation/test-validator-phase2.js
```

**Durée** : ~3-5 minutes (génération + échantillonnage + évaluations)

**Résultat** : Validation COMPLÈTE avec scores LLM pour chaque échantillon et version.

### Phase 3 (API & WebSocket) - Utilisation REST API

**Démarrer une validation**:
```bash
curl -X POST http://localhost:3000/api/validation/start \
  -H "Content-Type: application/json" \
  -d '{
    "pipelineConfig": {
      "name": "Test Pipeline",
      "pipeline": [
        { "step": 1, "module": "generation", "mode": "simple", "intensity": 1.0 }
      ]
    },
    "rowNumber": 2
  }'
```

**Récupérer le statut**:
```bash
curl http://localhost:3000/api/validation/status/{validationId}
```

**Lister toutes les validations**:
```bash
curl http://localhost:3000/api/validation/list
```

**Récupérer le rapport complet**:
```bash
curl http://localhost:3000/api/validation/{validationId}/report
```

**Récupérer les évaluations détaillées**:
```bash
curl http://localhost:3000/api/validation/{validationId}/evaluations
```

### WebSocket - Progression temps réel

Connecter un client WebSocket sur `ws://localhost:8081`:

```javascript
const ws = new WebSocket('ws://localhost:8081');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === 'validation_progress') {
    console.log(`[${data.progress.percentage}%] ${data.progress.phase}: ${data.progress.message}`);
  }
};
```

### Utilisation programmatique

```javascript
const { ValidatorCore } = require('./lib/validation/ValidatorCore');

const validator = new ValidatorCore();

const pipelineConfig = {
  name: 'Mon Pipeline',
  pipeline: [
    { step: 1, module: 'generation', mode: 'simple', intensity: 1.0 },
    { step: 2, module: 'selective', mode: 'lightEnhancement', intensity: 0.5 }
  ]
};

const result = await validator.runValidation(
  {},              // config validation (optionnel)
  pipelineConfig,  // config pipeline
  2                // rowNumber Google Sheets
);

if (result.success) {
  console.log('✅ Validation réussie');
  console.log(`Score global: ${result.report.evaluations.overallScore}/10`);
  console.log(`Dossier: ${result.validationDir}`);
}
```

## 📊 Format du rapport

### Rapport JSON (`report.json`)

```json
{
  "validationId": "uuid",
  "timestamp": "2025-...",
  "status": "completed",
  "pipeline": {
    "name": "Pipeline name",
    "totalSteps": 2,
    "successfulSteps": 2,
    "totalDuration": 125000
  },
  "versions": {
    "count": 3,
    "paths": ["v1.0.json", "v1.1.json", "v2.0.json"]
  },
  "samples": {
    "total": 9,
    "titles": 5,
    "content": 4,
    "faqs": 0
  },
  "evaluations": {
    "totalEvaluations": 135,
    "overallScore": 7.3,
    "byVersion": {
      "v1.0": { "avgScore": 6.5, "count": 45 },
      "v1.1": { "avgScore": 7.2, "count": 45 },
      "v2.0": { "avgScore": 7.8, "count": 45 }
    },
    "byCriteria": {
      "qualite": { "avgScore": 8.1, "count": 27 },
      "verbosite": { "avgScore": 7.5, "count": 27 },
      "seo": { "avgScore": 7.8, "count": 27 },
      "repetitions": { "avgScore": 7.2, "count": 27 },
      "naturalite": { "avgScore": 6.0, "count": 27 }
    }
  }
}
```

### Évaluations détaillées (`results/evaluations.json`)

```json
{
  "evaluations": {
    "|T0|": {
      "qualite": {
        "v1.0": { "score": 8.0, "reasoning": "Titre clair..." },
        "v1.1": { "score": 8.5, "reasoning": "Amélioration..." }
      },
      "naturalite": {
        "v1.0": { "score": 6.5, "reasoning": "Légère..." },
        "v1.1": { "score": 7.0, "reasoning": "Plus naturel..." }
      }
    }
  },
  "aggregated": {
    "byVersion": {...},
    "byCriteria": {...},
    "overall": { "avgScore": 7.3, "totalEvaluations": 135 }
  }
}
```

## 🎯 Critères d'évaluation

### 1. Qualité globale (0-10)
- Grammaire, orthographe, syntaxe
- Cohérence et fluidité
- Pertinence contextuelle

### 2. Verbosité / Concision (0-10)
- Densité informationnelle
- Longueur appropriée
- Absence de fluff

### 3. SEO et mots-clés (0-10)
- Intégration naturelle mots-clés
- Densité appropriée
- Structure SEO-friendly

### 4. Répétitions et variations (0-10)
- Évite répétitions lexicales
- Vocabulaire varié
- Usage synonymes

### 5. Naturalité humaine (0-10)
- Semble écrit par humain
- Variations naturelles
- Évite patterns IA

## ⚙️ Configuration

### Limiter concurrence évaluations LLM

Par défaut : 3 évaluations en parallèle.

Modifier dans `ValidatorCore.js` :

```javascript
const evaluations = await this.criteriaEvaluator.evaluateBatch(samples, context, 5);
//                                                                            ^^^ maxConcurrent
```

### Changer LLM évaluateur

Par défaut : `claude-sonnet-4-5`

Modifier dans `CriteriaEvaluator.js` :

```javascript
this.defaultLLM = 'gpt-4o';  // Ou autre LLM
```

### Désactiver retry logic

Modifier dans `CriteriaEvaluator.js` :

```javascript
this.maxRetries = 0;  // Pas de retry
```

## 💰 Coûts estimés

### Configuration standard
- Pipeline : 4 steps → 4 versions
- Échantillons : ~13 balises
- Critères : 5 critères
- **Total appels LLM** : 13 × 5 × 4 = **260 appels**
- **Coût** : ~$1.00 par validation (Claude Sonnet 4.5)

### Configuration économique
- Pipeline : 2 steps → 2 versions
- Échantillons : ~7 balises
- Critères : 3 critères prioritaires
- **Total appels LLM** : 7 × 3 × 2 = **42 appels**
- **Coût** : ~$0.16 par validation

## 🐛 Debugging

### Logs détaillés

Les logs incluent :
- `[INFO]` Progression phases
- `[DEBUG]` Détails échantillonnage et évaluations
- `[ERROR]` Erreurs avec stack trace

### Vérifier contenu versions

```bash
cat validations/{uuid}/versions/v1.0.json | jq
```

### Vérifier échantillons

```bash
cat validations/{uuid}/samples/all-samples.json | jq
```

### Vérifier évaluations

```bash
cat validations/{uuid}/results/evaluations.json | jq '.aggregated'
```

## 🔧 Développement

### Ajouter un nouveau critère

1. Modifier `CRITERIA` dans `CriteriaEvaluator.js`
2. Ajouter prompt détails dans `getCriteriaPromptDetails()`

### Modifier algorithme échantillonnage

Modifier méthodes dans `SamplingEngine.js` :
- `extractSamples()` - Logique principale
- `extractVersionsForTag()` - Extraction versions

### Ajouter nouvelle phase validation

Modifier `ValidatorCore.js` :
- Ajouter méthode `runMyPhase()`
- Insérer appel dans workflow `runValidation()`
- Ajouter sauvegarde dans `generateReport()`

## 🌐 API Endpoints (Phase 3)

### POST /api/validation/start
Démarre une nouvelle validation en arrière-plan.

**Body**:
```json
{
  "pipelineConfig": {
    "name": "Pipeline Name",
    "pipeline": [...]
  },
  "rowNumber": 2,
  "config": {}
}
```

**Response** (202 Accepted):
```json
{
  "success": true,
  "data": {
    "validationId": "uuid-xxx",
    "status": "running",
    "message": "Validation démarrée en arrière-plan"
  }
}
```

### GET /api/validation/status/:id
Récupère le statut et la progression d'une validation.

**Response**:
```json
{
  "success": true,
  "data": {
    "validationId": "uuid-xxx",
    "status": "running",
    "progress": {
      "phase": "evaluation",
      "message": "Évaluation LLM des échantillons...",
      "percentage": 65
    },
    "duration": 120000,
    "pipelineName": "Test Pipeline",
    "result": null
  }
}
```

### POST /api/validation/stop/:id
Arrête une validation en cours (marque comme stopped, le processus continue en arrière-plan).

### GET /api/validation/list
Liste toutes les validations (actives + historique).

**Query Params**:
- `status`: Filtrer par statut (running, completed, error)
- `limit`: Nombre max de résultats (défaut: 50)

### GET /api/validation/:id/report
Récupère le rapport complet JSON d'une validation terminée.

### GET /api/validation/:id/evaluations
Récupère les évaluations LLM détaillées avec scores par version et critère.

## 📡 WebSocket Events (Phase 3)

**Type: `validation_progress`**
```json
{
  "type": "validation_progress",
  "validationId": "uuid-xxx",
  "status": "running",
  "progress": {
    "phase": "pipeline|sampling|evaluation|saving|report",
    "message": "Description de l'étape en cours",
    "percentage": 65
  },
  "timestamp": "2025-01-13T..."
}
```

---

**Statut** : ✅ Phase 3 complète et opérationnelle (API + WebSocket)
**Version** : 1.1.0
**Date** : 2025-01-13