seo-generator-server/lib/validation

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)

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)

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:

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:

curl http://localhost:3000/api/validation/status/{validationId}

Lister toutes les validations:

curl http://localhost:3000/api/validation/list

Récupérer le rapport complet:

curl http://localhost:3000/api/validation/{validationId}/report

Récupérer les évaluations détaillées:

curl http://localhost:3000/api/validation/{validationId}/evaluations

WebSocket - Progression temps réel

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

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

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)

{
  "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)

{
  "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 :

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

Changer LLM évaluateur

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

Modifier dans CriteriaEvaluator.js :

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

Désactiver retry logic

Modifier dans CriteriaEvaluator.js :

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

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

Vérifier échantillons

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

Vérifier évaluations

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:

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

Response (202 Accepted):

{
  "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:

{
  "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

{
  "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