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 :

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

// 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 :

   // 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 :

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

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 🚀