seo-generator-server/PIPELINE_VALIDATOR_SPEC.md

# 📋 PIPELINE VALIDATOR - Spécification Technique

## 🎯 OBJECTIF GÉNÉRAL

Créer une interface dédiée de validation qualitative permettant d'évaluer l'évolution du contenu à travers les différentes étapes d'un pipeline, en utilisant des critères LLM objectifs avec notation et justification détaillée.

---

## 🧠 COMPRÉHENSION DU BESOIN

### Workflow utilisateur
1. **Chargement** : Sélectionner une config de pipeline + une personnalité Google Sheets
2. **Exécution** : Run le pipeline complet (identique à pipeline-runner)
3. **Échantillonnage intelligent** : Extraire automatiquement 3 types d'éléments du contenu généré
4. **Évaluation multi-critères** : Chaque critère = 1 appel LLM → note/10 + justification
5. **Visualisation comparative** : Voir l'évolution d'un échantillon à travers toutes les étapes

### Valeur ajoutée
- **Traçabilité** : Comprendre l'impact réel de chaque layer du pipeline
- **Objectivité** : Évaluation quantitative via LLM (pas de subjectivité humaine)
- **Debugging** : Identifier quelle étape dégrade/améliore la qualité
- **Optimisation** : Comparer différentes configs de pipeline scientifiquement

---

## 🏗️ ARCHITECTURE SYSTÈME

### 1. FICHIERS À CRÉER

#### Frontend
- **`public/pipeline-validator.html`** - Interface principale
  - Section chargement (config + personnalité)
  - Zone de contrôle (run, status, progress)
  - Panneau d'échantillonnage (liste des 3 types)
  - Tableau de scores (critères × étapes)
  - Vue détaillée comparative (sélection d'échantillon)

- **`public/pipeline-validator.js`** - Logique frontend
  - Gestion UI (sélections, boutons, modals)
  - Communication WebSocket pour progression temps réel
  - Rendering des scores et graphiques
  - Navigation entre échantillons

- **`public/css/pipeline-validator.css`** - Styles dédiés
  - Layout responsive (sidebar + main content)
  - Cartes de scores avec couleurs (vert>7, orange 5-7, rouge<5)
  - Vue comparative side-by-side ou verticale

#### Backend
- **`lib/validation/ValidatorCore.js`** - Orchestrateur principal
  - Exécution pipeline avec sauvegarde toutes versions
  - Échantillonnage intelligent post-génération
  - Orchestration évaluations LLM par critère
  - Agrégation résultats + génération rapport

- **`lib/validation/SamplingEngine.js`** - Moteur d'échantillonnage
  - Extraction titres (H1, H2, H3, title tags)
  - Sélection paragraphes (longueur moyenne, représentatifs)
  - Extraction FAQ (paires question/réponse)
  - Parsing XML/HTML intelligent

- **`lib/validation/CriteriaEvaluator.js`** - Évaluateur multi-critères
  - Définition des critères d'évaluation (voir section dédiée)
  - Appels LLM avec prompts structurés
  - Parsing réponses LLM (score + justification)
  - Retry logic + gestion erreurs

- **`lib/validation/ValidationAPI.js`** - Endpoints API
  - POST `/api/validation/run` - Lancer validation complète
  - GET `/api/validation/status/:id` - Status temps réel
  - GET `/api/validation/results/:id` - Récupérer résultats
  - GET `/api/validation/sample/:id/:type/:index` - Détail échantillon

#### Modifications à faire
- **`lib/APIController.js`** - Ajouter routes validation
- **`lib/pipeline/PipelineExecutor.js`** - Ajouter flag `saveAllVersions: true` pour forcer sauvegarde toutes étapes intermédiaires
- **`server.js`** - Exposer endpoints validation

---

## 📊 ÉCHANTILLONNAGE INTELLIGENT

### Source des données : Objet `content` (pas de XML)

Après chaque étape du pipeline, on a un simple objet JavaScript :
```javascript
content = {
  "|MC0|": "Texte du mot-clé principal...",
  "|T0|": "Titre principal",
  "|T-1|": "Sous-titre 1",
  "|L-1|": "Texte liste 1...",
  "|FAQ_Q1|": "Question FAQ ?",
  "|FAQ_A1|": "Réponse FAQ...",
  ...
}
```

**Versions sauvegardées** : Chaque step sauvegarde son objet `content` en JSON
- `v1.0.json` (génération initiale)
- `v1.1.json` (après step 1)
- `v1.2.json` (après step 2)
- `v2.0.json` (final)

### Catégories d'échantillons

#### 1. **Titres** (TOUS)
**Sélection** : Toutes les balises contenant `T` dans leur nom
- `|T0|`, `|T-1|`, `|T+1|`, etc.

**Pourquoi tous** : Les titres sont critiques pour SEO et structure, peu nombreux

#### 2. **Contenus principaux** (4 échantillons)
**Sélection** : Balises de contenu long (`MC*`, `L*`)
- Prendre les 4 premières : `|MC0|`, `|MC+1|`, `|L-1|`, `|L+1|`

**Objectif** : Évaluer la qualité rédactionnelle sur échantillon représentatif

#### 3. **FAQ** (4 balises = 2 paires)
**Sélection** : Balises contenant `FAQ`
- 2 paires Q/A = 4 balises : `|FAQ_Q1|`, `|FAQ_A1|`, `|FAQ_Q2|`, `|FAQ_A2|`
- Si <2 paires disponibles, prendre ce qui existe

**Objectif** : Évaluer naturalité question/réponse

### Algorithme d'échantillonnage

```javascript
// Charger version finale
const finalContent = JSON.parse(fs.readFileSync('v2.0.json'));
const allTags = Object.keys(finalContent);

// Catégoriser automatiquement
const samples = {
  titles: allTags.filter(tag => tag.includes('T')),           // Tous
  content: allTags.filter(tag => tag.includes('MC') || tag.includes('L')).slice(0, 4),
  faqs: allTags.filter(tag => tag.includes('FAQ')).slice(0, 4)
};

// Pour chaque échantillon, extraire versions à travers toutes étapes
for (const tag of [...samples.titles, ...samples.content, ...samples.faqs]) {
  const versions = {};

  for (const versionPath of ['v1.0.json', 'v1.1.json', 'v1.2.json', 'v2.0.json']) {
    const versionContent = JSON.parse(fs.readFileSync(versionPath));
    versions[versionPath] = versionContent[tag] || "[Non disponible à cette étape]";
  }

  samplesData[tag] = {
    tag,
    type: tag.includes('T') ? 'title' : tag.includes('FAQ') ? 'faq' : 'content',
    versions
  };
}
```

---

## 🎯 CRITÈRES D'ÉVALUATION LLM

### Principe général
- **1 critère = 1 appel LLM** (parallélisation possible)
- **5 critères universels** applicables à tous types de contenu (titres, paragraphes, FAQ)
- **Prompt structuré** : contexte + critère + échelle notation + demande justification
- **Output attendu** : JSON `{ score: 8, reasoning: "Justification détaillée..." }`
- **LLM utilisé** : Claude Sonnet (objectivité optimale)
- **Temperature** : 0.3 (cohérence entre évaluations)

---

### 1. **Qualité globale** (0-10)

**Évalue** :
- Grammaire, orthographe, syntaxe impeccables
- Cohérence et fluidité du texte
- Pertinence par rapport au contexte (MC0, personnalité)

**Prompt template** :
```
Tu es un évaluateur objectif de contenu SEO.

CONTEXTE:
- Mot-clé principal: {MC0}
- Thématique: {T0}
- Personnalité: {personality.nom}
- Type de contenu: {type} (titre/contenu/faq)

ÉLÉMENT À ÉVALUER:
"{text}"

CRITÈRE: Qualité globale
Évalue la qualité rédactionnelle globale :
- Grammaire et syntaxe impeccables ?
- Texte fluide et cohérent ?
- Pertinent par rapport au mot-clé "{MC0}" ?

ÉCHELLE:
10 = Qualité exceptionnelle, aucune faute
7-9 = Bonne qualité, légères imperfections
4-6 = Qualité moyenne, plusieurs problèmes
1-3 = Faible qualité, nombreuses erreurs
0 = Inutilisable

Réponds en JSON strict:
{
  "score": 7.5,
  "reasoning": "Justification en 2-3 phrases concrètes..."
}
```

---

### 2. **Verbosité / Concision** (0-10)

**Évalue** :
- Densité informationnelle (info utile vs fluff)
- Longueur appropriée au type de contenu
- Évite délayage et remplissage inutile

**Prompt template** :
```
CRITÈRE: Verbosité et concision
Évalue la concision du texte :
- Densité informationnelle élevée (info utile / longueur totale) ?
- Longueur appropriée pour un {type} (ni trop court, ni verbeux) ?
- Absence de fluff et remplissage inutile ?

ÉCHELLE:
10 = Parfaitement concis, chaque mot compte
7-9 = Plutôt concis, peu de superflu
4-6 = Moyennement verbeux, du remplissage
1-3 = Très verbeux, beaucoup de fluff
0 = Délayage excessif

Réponds en JSON strict:
{
  "score": 8.0,
  "reasoning": "..."
}
```

---

### 3. **SEO et mots-clés** (0-10)

**Évalue** :
- Intégration naturelle des mots-clés pertinents
- Structure optimisée (densité, placement)
- Évite sur-optimisation (keyword stuffing)

**Prompt template** :
```
CRITÈRE: SEO et mots-clés
Évalue l'optimisation SEO :
- Mots-clés (notamment "{MC0}") intégrés naturellement ?
- Densité appropriée (ni trop faible, ni keyword stuffing) ?
- Structure SEO-friendly ?

ÉCHELLE:
10 = SEO optimal et naturel
7-9 = Bon SEO, quelques améliorations possibles
4-6 = SEO moyen, manque d'optimisation ou sur-optimisé
1-3 = SEO faible ou contre-productif
0 = Aucune considération SEO

Réponds en JSON strict:
{
  "score": 7.0,
  "reasoning": "..."
}
```

---

### 4. **Répétitions et variations** (0-10)

**Évalue** :
- Évite répétitions lexicales excessives
- Variété du vocabulaire et des formulations
- Usage de synonymes et paraphrases

**Prompt template** :
```
CRITÈRE: Répétitions et variations lexicales
Évalue la variété lexicale :
- Répétitions de mots/expressions évitées ?
- Vocabulaire varié et riche ?
- Paraphrases et synonymes utilisés intelligemment ?

ÉCHELLE:
10 = Très varié, aucune répétition notable
7-9 = Plutôt varié, quelques répétitions mineures
4-6 = Variété moyenne, répétitions visibles
1-3 = Très répétitif, vocabulaire pauvre
0 = Répétitions excessives

Réponds en JSON strict:
{
  "score": 8.5,
  "reasoning": "..."
}
```

---

### 5. **Naturalité humaine** (0-10)

**Évalue** :
- Le texte semble-t-il écrit par un humain (vs IA détectable)
- Variations de style, imperfections réalistes
- Évite patterns LLM typiques

**Prompt template** :
```
CRITÈRE: Naturalité humaine
Évalue si le texte semble écrit par un humain :
- Semble-t-il rédigé par un humain authentique ?
- Présence de variations naturelles et imperfections réalistes ?
- Absence de patterns IA typiques (phrases trop parfaites, formules creuses, superlatifs excessifs) ?

ÉCHELLE:
10 = 100% indétectable, parfaitement humain
7-9 = Très naturel, légères traces IA
4-6 = Moyennement naturel, patterns IA visibles
1-3 = Clairement IA, très artificiel
0 = Robotique et détectable immédiatement

Réponds en JSON strict:
{
  "score": 6.5,
  "reasoning": "..."
}
```

---

### Résumé des 5 critères

| Critère | Objectif | Score 10 = | Score 0 = |
|---------|----------|------------|-----------|
| **Qualité globale** | Vérifier la qualité rédactionnelle | Impeccable | Inutilisable |
| **Verbosité** | Évaluer la concision | Très concis | Délayage excessif |
| **SEO** | Mesurer l'optimisation | Optimal naturel | Aucun SEO |
| **Répétitions** | Vérifier la variété lexicale | Très varié | Très répétitif |
| **Naturalité** | Détecter l'origine humaine vs IA | 100% humain | Robotique |

---

## 🔄 WORKFLOW D'EXÉCUTION

### Phase 1 : INITIALISATION (Frontend)
1. Utilisateur charge config de pipeline (dropdown ou upload JSON)
2. Utilisateur sélectionne personnalité (dropdown depuis Google Sheets)
3. Affichage preview : pipeline steps + personnalité info
4. Bouton "Lancer Validation" → POST `/api/validation/run`

### Phase 2 : EXÉCUTION PIPELINE (Backend - ValidatorCore)
1. Créer UUID unique pour cette validation
2. Appeler PipelineExecutor avec `saveAllVersions: true`
   - Force sauvegarde objet `content` après chaque step
   - Génère versions JSON : v1.0.json (init) → v1.1.json (step1) → v1.2.json (step2) → v2.0.json (final)
3. Stocker toutes versions dans structure :
   ```
   validations/
     {uuid}/
       config.json              # Config pipeline utilisée
       personality.json         # Personnalité sélectionnée
       versions/
         v1.0.json             # { "|MC0|": "...", "|T0|": "...", ... }
         v1.1.json
         v1.2.json
         v2.0.json
       samples/
         all-samples.json      # (à créer après échantillonnage)
       results/
         evaluations.json      # (à créer après évaluations)
   ```
4. WebSocket broadcast progression : "Génération étape 1/4...", "Génération étape 2/4..."

### Phase 3 : ÉCHANTILLONNAGE (Backend - SamplingEngine)
1. Charger `v2.0.json` (version finale)
2. Extraire échantillons par filtrage automatique des balises :
   - Tous titres (balises contenant `T`) → liste `samples.titles`
   - 4 contenus (balises `MC*`, `L*`) → liste `samples.content`
   - 4 FAQ (balises `FAQ*`) → liste `samples.faqs`
3. Pour chaque échantillon, extraire versions à travers toutes étapes :
   ```javascript
   // Exemple pour "|MC0|"
   for (const versionFile of ['v1.0.json', 'v1.1.json', 'v1.2.json', 'v2.0.json']) {
     const versionContent = JSON.parse(fs.readFileSync(versionFile));
     samplesData["|MC0|"].versions[versionFile] = versionContent["|MC0|"];
   }

   // Résultat
   {
     "tag": "|MC0|",
     "type": "content",
     "versions": {
       "v1.0.json": "Texte initial...",
       "v1.1.json": "Texte après step1...",
       "v1.2.json": "Texte après step2...",
       "v2.0.json": "Texte final..."
     }
   }
   ```
4. Sauvegarder `samples/all-samples.json`
5. WebSocket broadcast : "Échantillonnage terminé : X titres, Y contenus, Z FAQ"

### Phase 4 : ÉVALUATION LLM (Backend - CriteriaEvaluator)
1. Pour chaque ÉCHANTILLON (tous types confondus : titres + contenus + FAQ)
2. Pour chaque CRITÈRE (5 critères universels)
3. Pour chaque VERSION (v1.0.json, v1.1.json, v1.2.json, v2.0.json)
4. Faire appel LLM :
   ```
   Prompt structure:
   ---
   Tu es un évaluateur objectif de contenu SEO.

   CONTEXTE:
   - Mot-clé principal: {MC0}
   - Thématique: {T0}
   - Personnalité: {personality.nom}

   ÉLÉMENT À ÉVALUER:
   Type: {type} (titre/paragraphe/FAQ)
   Contenu: "{content}"

   CRITÈRE: {criteriaName}
   Description: {criteriaDescription}

   TÂCHE:
   Évalue cet élément selon le critère ci-dessus.
   Donne une note de 0 à 10 (précision: 0.5).
   Justifie ta notation en 2-3 phrases concrètes.

   RÉPONSE ATTENDUE (JSON strict):
   {
     "score": 7.5,
     "reasoning": "Justification détaillée..."
   }
   ---
   ```
5. Parser réponse LLM, valider JSON, stocker dans :
   ```
   results/
     {sampleId}/
       {criteriaId}/
         v1.0.json
         v1.1.json
         ...
   ```
6. WebSocket broadcast progression : "Évaluation P1 - Critère 1/5 - Étape 2/4"

**Optimisation** : Paralléliser appels LLM (max 5 simultanés pour éviter rate limits)

### Phase 5 : AGRÉGATION (Backend - ValidatorCore)
1. Calculer scores moyens par :
   - Échantillon × Critère × Version → score moyen + justifications combinées
   - Critère × Version → score moyen global
   - Version globale → score moyen tous critères
2. Générer rapport JSON :
   ```json
   {
     "uuid": "...",
     "timestamp": "...",
     "config": {...},
     "personality": {...},
     "samples": {
       "titles": [...],
       "paragraphs": [...],
       "faqs": [...]
     },
     "evaluations": {
       "P1": {
         "qualite_redactionnelle": {
           "v1.0": { "score": 6.5, "reasoning": "..." },
           "v1.1": { "score": 7.0, "reasoning": "..." }
         }
       }
     },
     "aggregated": {
       "byVersion": {
         "v1.0": { "avgScore": 6.2, "breakdown": {...} },
         "v1.1": { "avgScore": 6.8, "breakdown": {...} }
       },
       "byCriteria": {...},
       "overall": { "avgScore": 7.3 }
     }
   }
   ```
3. Sauvegarder : `validations/{uuid}/report.json`
4. WebSocket broadcast : "✅ Validation terminée ! Score global : 7.3/10"

---

## 🎨 INTERFACE UTILISATEUR

### Layout général
```
+---------------------------------------------------------------+
| PIPELINE VALIDATOR                                    [Config]|
+---------------------------------------------------------------+
| [Config: default.json ▼] [Personnalité: Sophie ▼] [🚀 RUN]   |
+---------------------------------------------------------------+
| Progress: ████████████████░░░░ 80% - Évaluation P2...        |
+---------------------------------------------------------------+
|  ÉCHANTILLONS          |  VUE DÉTAILLÉE                       |
|                        |                                      |
|  📋 Titres (5)         |  Échantillon sélectionné: P2        |
|    ☑ T1: Comment...    |  ----------------------------------- |
|    ☐ T2: Les avantages |  📊 SCORES PAR ÉTAPE                |
|    ☐ T3: Guide...      |  v1.0 → v1.1 → v1.2 → v2.0          |
|                        |  6.5    7.2    7.8    8.1  (Qualité)|
|  📝 Paragraphes (4)    |  7.0    7.3    6.8    7.5  (Natural)|
|    ☐ P1: Introduction  |  ...                                 |
|    ☑ P2: Description   |  ----------------------------------- |
|    ☐ P3: Technique     |  📝 CONTENU PAR ÉTAPE               |
|    ☐ P4: Conclusion    |  [v1.0] [v1.1] [v1.2] [v2.0]        |
|                        |  (onglets ou slider)                 |
|  ❓ FAQ (2)            |                                      |
|    ☐ F1: Comment...?   |  Contenu de P2 à l'étape v1.1:      |
|    ☐ F2: Pourquoi...?  |  "Lorem ipsum dolor sit amet..."    |
|                        |                                      |
|                        |  ----------------------------------- |
|                        |  💬 JUSTIFICATIONS CRITÈRE          |
|                        |  Qualité rédactionnelle (v1.1): 7.2 |
|                        |  "La syntaxe est fluide mais..."    |
+---------------------------------------------------------------+
```

### Interactions clés

1. **Sélection échantillon** (sidebar gauche)
   - Click sur échantillon → charge vue détaillée
   - Highlight actif (bordure bleue)
   - Badge avec score moyen global (couleur selon score)

2. **Vue détaillée - Onglet Scores**
   - Graphique ligne : évolution score par critère à travers versions
   - Tableau scores : critères (lignes) × versions (colonnes)
   - Code couleur : 🟢 >7, 🟠 5-7, 🔴 <5
   - Hover sur score → tooltip avec justification courte

3. **Vue détaillée - Onglet Comparaison**
   - Slider ou onglets pour naviguer entre versions
   - Diff highlighting : vert (améliorations), rouge (dégradations) si possible
   - Métadonnées : durée step, module appliqué, LLM utilisé

4. **Vue détaillée - Onglet Justifications**
   - Accordéon : 1 section par critère
   - Pour chaque critère : timeline versions avec score + reasoning

5. **Export rapport**
   - Bouton "📥 Exporter rapport" → télécharge JSON complet
   - Bouton "📊 Exporter CSV scores" → tableau scores pour analyse externe

---

## 🔧 MODIFICATIONS NÉCESSAIRES

### Fichiers existants à modifier

#### 1. `lib/pipeline/PipelineExecutor.js`
**Modifications** :
- Ajouter paramètre config : `saveAllVersions: boolean`
- Si `true` : après chaque step, sauvegarder version intermédiaire
  - Nommer versions : v1.0, v1.1, v1.2, etc.
  - Stocker dans dossier spécifié : `outputDir`
- Retourner array de paths : `versionPaths: ['v1.0.xml', 'v1.1.xml', ...]`

**Pseudo-code** :
```javascript
SI saveAllVersions === true :
  versionPaths = []
  version = 1.0

  sauvegarder(content, `${outputDir}/v${version}.xml`)
  versionPaths.push(...)

  POUR CHAQUE step du pipeline :
    appliquer step
    version += 0.1
    sauvegarder(content, `${outputDir}/v${version}.xml`)
    versionPaths.push(...)

  version = 2.0
  sauvegarder(finalContent, `${outputDir}/v${version}.xml`)

  retourner { content, versionPaths, stats }
```

#### 2. `lib/APIController.js`
**Modifications** :
- Importer ValidatorCore, ValidationAPI
- Ajouter routes :
  ```
  POST   /api/validation/run
  GET    /api/validation/status/:id
  GET    /api/validation/results/:id
  GET    /api/validation/samples/:id
  DELETE /api/validation/:id
  ```
- Déléguer logique à ValidationAPI

#### 3. `server.js`
**Modifications** :
- Exposer routes validation via APIController
- Assurer WebSocket écoute events validation pour broadcast temps réel

#### 4. `lib/Main.js` (optionnel)
**Modifications** :
- Si ValidatorCore appelle handleFullWorkflow, s'assurer compatibilité avec flag saveAllVersions
- OU créer méthode dédiée `handleValidationWorkflow()`

---

## 📦 DÉPENDANCES

### NPM packages (déjà présents)
- `express` - API REST
- `ws` - WebSocket temps réel
- Tous les LLM clients (Anthropic, OpenAI, etc.)
- `uuid` - Génération IDs validation
- `fs` - Lecture/écriture fichiers JSON

### Packages potentiels à ajouter
- `diff` - Highlighting différences entre versions (optionnel, pour UI comparaison)
- Aucune autre dépendance nécessaire (sélection balises = filtrage JavaScript natif)

---

## 🧪 TESTING STRATEGY

### Tests unitaires
1. **SamplingEngine** :
   - Test filtrage titres (object avec balises T*, sans balises T)
   - Test sélection contenus (MC*, L*) avec slice
   - Test extraction FAQ (balises FAQ*, cas <2 paires disponibles)

2. **CriteriaEvaluator** :
   - Mock appels LLM → test parsing réponses
   - Test gestion erreurs (LLM timeout, JSON invalide)
   - Test retry logic

3. **ValidatorCore** :
   - Test orchestration complète (mock PipelineExecutor + SamplingEngine + Evaluator)
   - Test agrégation scores

### Tests d'intégration
1. Validation end-to-end :
   - Config pipeline simple (2 steps) + personnalité test
   - Vérifier génération toutes versions
   - Vérifier échantillonnage correct
   - Vérifier appels LLM réels (1 critère seulement pour rapidité)
   - Vérifier rapport final cohérent

### Tests UI
1. Chargement configs et personnalités
2. Affichage progression temps réel
3. Navigation entre échantillons
4. Affichage scores et graphiques
5. Export rapport

---

## 📈 MÉTRIQUES DE SUCCÈS

### Fonctionnel
- ✅ Exécution pipeline complète avec sauvegarde toutes versions
- ✅ Échantillonnage intelligent (diversité respectée)
- ✅ Évaluation LLM tous critères (100% réussite parsing)
- ✅ Rapport JSON complet et cohérent
- ✅ UI responsive et intuitive

### Performance
- ⏱️ Durée totale validation < 5min (pipeline 4 steps, 9 échantillons, 5 critères = ~180 appels LLM)
- ⏱️ Affichage progression temps réel < 500ms latence
- 💾 Stockage validation < 10MB (JSON + XMLs)

### UX
- 👁️ Clarté visualisation scores (code couleur intuitif)
- 🔍 Facilité navigation entre échantillons
- 📊 Pertinence justifications LLM (human-readable)

---

## 🚀 PHASES DE DÉVELOPPEMENT

### Phase 1 : Backend Core (Priorité 1)
1. Créer `ValidatorCore.js` - orchestration basique
2. Modifier `PipelineExecutor.js` - flag saveAllVersions (sauvegarde JSON après chaque step)
3. Créer `SamplingEngine.js` - filtrage balises simple (T*, MC*, L*, FAQ*)
4. Tester workflow complet sans évaluation LLM

### Phase 2 : Évaluation LLM (Priorité 1)
1. Créer `CriteriaEvaluator.js` - 2 critères seulement (qualité + naturalité)
2. Définir prompts LLM structurés
3. Implémenter parsing + retry logic
4. Tester sur 1 échantillon × 2 critères × 3 versions

### Phase 3 : API & WebSocket (Priorité 2)
1. Créer `ValidationAPI.js` - endpoints CRUD
2. Intégrer dans `APIController.js`
3. WebSocket broadcast progression
4. Tester via Postman/curl

### Phase 4 : Frontend Basique (Priorité 2)
1. Créer `pipeline-validator.html` - layout structure
2. Créer `pipeline-validator.js` - logique UI basique
3. Formulaire run + affichage progression
4. Affichage liste échantillons (sans vue détaillée)

### Phase 5 : Frontend Avancé (Priorité 3)
1. Vue détaillée échantillon (onglets scores/comparaison/justifications)
2. Graphiques évolution scores (Chart.js ou similaire)
3. Diff highlighting versions
4. Export rapport (JSON/CSV)

### Phase 6 : Critères Complets (Priorité 3)
1. Implémenter tous critères (5 par type)
2. Affiner prompts LLM selon résultats tests
3. Ajouter échantillonnage FAQ

### Phase 7 : Polish & Optimisation (Priorité 4)
1. Parallélisation appels LLM (pool workers)
2. Cache résultats évaluations (si re-run même config)
3. UI animations et micro-interactions
4. Documentation utilisateur

---

## ⚠️ POINTS D'ATTENTION

### Challenges techniques

1. **Volume appels LLM** :
   - Exemple : 4 steps × 9 échantillons × 5 critères = 180 appels
   - Solution : Parallélisation + gestion rate limits
   - Alternative : Évaluer seulement versions clés (v1.0, milieu, v2.0)

2. **Sélection balises robuste** :
   - Structures de balises variées selon templates
   - Solution : Filtrage simple par `.includes()` avec fallbacks, gestion balises manquantes

3. **Cohérence évaluations LLM** :
   - Variabilité réponses LLM même prompt
   - Solution : Temperature basse (0.3), prompts très structurés, moyenne sur 2-3 runs ?

4. **Storage validations** :
   - Accumulation fichiers si beaucoup de validations
   - Solution : Cleanup automatique après 7 jours, ou limit stockage 50 validations

### UX considérations

1. **Durée exécution longue** (3-5min)
   - User peut quitter page → validation continue en background
   - Notification email/webhook quand terminé ?
   - OU : Polling API status si user revient

2. **Complexité interface** :
   - Beaucoup d'informations (scores, justifications, versions)
   - Solution : Progressive disclosure (accordéons, onglets), filtres

3. **Interprétation scores** :
   - User peut ne pas comprendre critères
   - Solution : Tooltips explicatifs, guide méthodologie

---

## 🎓 ÉVOLUTIONS FUTURES

### V2 Features
1. **Comparaison multi-validations** :
   - Comparer 2 configs de pipeline côte à côte
   - Graphique : évolution scores Config A vs Config B

2. **Critères personnalisés** :
   - User peut définir ses propres critères d'évaluation
   - Upload JSON ou formulaire UI

3. **Benchmarking automatique** :
   - Base de données scores moyens par secteur/type contenu
   - Afficher percentile (votre score vs moyenne)

4. **Export rapport PDF** :
   - Rapport visuel professionnel (graphiques, tableaux)
   - Pour présentation clients/stakeholders

5. **A/B Testing intégré** :
   - Définir 2+ variants pipeline
   - Run validation sur tous, afficher gagnant selon critères pondérés

---

## ✅ CHECKLIST PRÉ-DÉVELOPPEMENT

Avant de commencer à coder, valider :

- [ ] Comprendre parfaitement workflow utilisateur (run test manuel similaire)
- [ ] Valider structure données échantillons (JSON schema)
- [ ] Tester 1 prompt LLM évaluation manuellement (Claude playground)
- [ ] Vérifier `PipelineExecutor` actuel peut sauvegarder versions intermédiaires
- [ ] Confirmer structure dossiers validations (`validations/{uuid}/...`)
- [ ] Designer mockup UI (Figma/papier) pour valider UX
- [ ] Estimer coût LLM par validation (180 appels × prix Claude)

---

## 💰 ESTIMATION COÛTS LLM

### Hypothèses
- Pipeline : 4 steps → 4 versions (v1.0, v1.1, v1.2, v2.0)
- Échantillons : ~5 titres + 4 contenus + 4 FAQ = **13 balises**
- Critères : **5 critères universels** (applicables à tous)
- Total appels : 13 échantillons × 5 critères × 4 versions = **260 appels**

### Coût par appel (Claude Sonnet)
- Input : ~500 tokens (contexte + prompt + échantillon)
- Output : ~150 tokens (JSON score + reasoning)
- Prix Claude Sonnet 4.5 : $3/M input + $15/M output
- Coût par appel : (500 × $3/1M) + (150 × $15/1M) = $0.0015 + $0.00225 = **~$0.00375**

### Coût total par validation
- 260 appels × $0.00375 = **~$0.98 par validation** (≈ $1)

### Optimisations possibles
1. **Réduire versions évaluées** (seulement v1.0, v1.2, v2.0) → 3 versions au lieu de 4 = **-25% = $0.73**
2. **Critères prioritaires** (3 au lieu de 5 : Qualité, SEO, Naturalité) → **-40% = $0.59**
3. **Échantillonnage réduit** (3 titres, 2 contenus, 2 FAQ = 7 balises) → **-46% = $0.53**
4. **Combiner toutes optimisations** → **~$0.25-$0.35 par validation**

### Recommandation
**Configuration standard** : 260 appels, $1/validation → Bon compromis exhaustivité/coût

**Configuration économique** : 3 critères + 3 versions + 7 balises = 63 appels → **$0.24/validation**

---

## 📝 RÉSUMÉ EXÉCUTIF

### Ce qui sera créé
1. **Interface web complète** : `pipeline-validator.html/.js/.css`
2. **Backend validation** : 4 nouveaux modules (`ValidatorCore`, `SamplingEngine`, `CriteriaEvaluator`, `ValidationAPI`)
3. **Modifications légères** : `PipelineExecutor` (flag saveAllVersions), `APIController` (routes)
4. **Système d'évaluation** : **5 critères universels** LLM (Qualité, Verbosité, SEO, Répétitions, Naturalité), notation 0-10 + justifications
5. **Visualisation avancée** : Scores évolution, comparaison versions, justifications détaillées

### Format de données
- **Entrée** : Objet JavaScript `content = { "|MC0|": "texte", "|T0|": "titre", ... }`
- **Versions sauvegardées** : JSON (`v1.0.json`, `v1.1.json`, `v1.2.json`, `v2.0.json`)
- **Échantillonnage** : Sélection automatique par filtrage de balises (pas de parsing XML)
- **Output** : Rapport JSON complet avec scores et justifications

### Code réutilisé
- 70% logique `pipeline-runner.html/.js` (UI run, progression, WebSocket)
- 100% `PipelineExecutor.js` (juste ajout flag `saveAllVersions`)
- 100% `LLMManager.js` (appels LLM pour évaluations)
- Structure dossiers `configs/`, `personalities` (Google Sheets)

### Complexité
- **Backend** : Moyenne (orchestration simple, sélection balises, appels LLM)
- **Frontend** : Moyenne-Haute (visualisation scores, comparaison versions)
- **Durée développement estimée** : 3-4 jours (phases 1-5)

### Coût opérationnel
- **~$1 par validation** (260 appels LLM Claude Sonnet)
- **Mode économique** : $0.24/validation (63 appels)

### Valeur business
- ✅ **Objectivité** : Validation qualité quantitative (vs jugement subjectif)
- ✅ **Traçabilité** : Impact mesurable de chaque layer pipeline
- ✅ **Optimisation** : Comparaison scientifique de configs (data-driven)
- ✅ **Reporting** : Scores quantitatifs présentables aux clients
- ✅ **Debugging** : Identification précise des étapes qui dégradent/améliorent

---

**DOCUMENT PRÊT POUR VALIDATION AVANT DÉVELOPPEMENT** 🚀