grahama1970/batch-quality

Compétence Batch Quality

Évitez les appels LLM gaspillés en validant la qualité AVANT d'exécuter des opérations par lots complètes.

Ce que fait réellement cette compétence

Contrairement à de simples vérifications d'existence de fichiers, cette compétence :

1. Exécute réellement le LLM sur N échantillons via scillm
2. Valide la structure des réponses JSON (extraits, source_quality, etc.)
3. Utilise les contrats SPARTA pour les requêtes de validation DuckDB
4. S'intègre avec task-monitor pour des contrôles qualité obligatoires

Démarrage rapide

cd .pi/skills/batch-quality

# Pré-vol : Tester 3 échantillons via le LLM réel
uv run python cli.py preflight \
    --stage 05 \
    --run-id run-recovery-verify \
    --samples 3

# Si le pré-vol réussit, exécutez votre lot
# ...opération par lots...

# Validation : Vérifier DuckDB par rapport au contrat
uv run python cli.py validate \
    --stage 05 \
    --run-id run-recovery-verify \
    --task-name "sparta-stage-05"

Commandes

preflight

Tester N échantillons via le LLM réel avant d'exécuter le lot complet.

uv run python cli.py preflight \
    --stage <nom-étape> \
    --run-id <id-exécution-sparta> \
    --samples 3 \
    --prompt <fichier-prompt-optionnel>

Ce qu'il fait réellement :

1. Charge le contrat SPARTA pour l'étape (s'il existe)
2. Vérifie les variables d'environnement (CHUTES_API_KEY, CHUTES_TEXT_MODEL)
3. Se connecte à DuckDB pour l'exécution
4. Échantillonne N éléments depuis la file d'entrée
5. Exécute chaque échantillon via scillm (appel LLM réel)
6. Valide la structure de la réponse JSON
7. Nécessite que 50 %+ des échantillons réussissent

Codes de sortie :

• 0 : RÉUSSI - sûr de continuer
• 1 : ÉCHEC - corrigez d'abord les problèmes

validate

Valider la sortie du lot à l'aide des contrats SPARTA.

uv run python cli.py validate \
    --stage <nom-étape> \
    --run-id <id-exécution-sparta> \
    --task-name <nom-moniteur-tâche>

Ce qu'il fait réellement :

1. Charge le contrat SPARTA (par exemple, 05_extract_knowledge.json)
2. Exécute toutes les validation_queries du contrat sur DuckDB
3. Vérifie chaque résultat de requête par rapport à expected_min
4. Notifie task-monitor du succès/échec

Exemple de contrat (05_extract_knowledge.json) :

{
  "validation_queries": [
    {"name": "url_knowledge_count", "query": "SELECT COUNT(*) FROM url_knowledge", "expected_min": 10},
    {"name": "urls_processed", "query": "SELECT COUNT(*) FROM url_extraction_log WHERE ok = true", "expected_min": 5}
  ]
}

status

Vérifier l'état actuel du pré-vol (sortie JSON).

uv run python cli.py status

clear

Effacer l'état du pré-vol (nécessite un nouveau pré-vol).

uv run python cli.py clear

Intégration du pipeline SPARTA

# 1. Enregistrer la tâche avec exigence de validation
uv run python .pi/skills/task-monitor/monitor.py register \
    --name "sparta-stage-05" \
    --require-validation

# 2. Exécuter le pré-vol (TESTE RÉELLEMENT le LLM)
uv run python .pi/skills/batch-quality/cli.py preflight \
    --stage 05 \
    --run-id run-recovery-verify \
    --samples 3

# 3. Exécuter le lot (uniquement si le pré-vol a réussi)
uv run python -m sparta.pipeline_duckdb.05_extract_knowledge \
    --run-id run-recovery-verify

# 4. Valider à l'aide des requêtes du contrat
uv run python .pi/skills/batch-quality/cli.py validate \
    --stage 05 \
    --run-id run-recovery-verify \
    --task-name "sparta-stage-05"

Configuration

Variables d'environnement :

• SPARTA_ROOT : Chemin vers le projet SPARTA (par défaut ~/workspace/experiments/sparta)
• CHUTES_API_KEY : Clé API pour les appels LLM
• CHUTES_API_BASE : URL de base de l'API (par défaut https://llm.chutes.ai/v1)
• CHUTES_TEXT_MODEL : Identifiant du modèle pour l'extraction de texte

Emplacement des contrats : $SPARTA_ROOT/tools/pipeline_gates/fixtures/D3-FEV/contracts/

Dépendances

• typer - Infrastructure CLI
• duckdb - Requêtes de base de données
• scillm - Traitement par lots LLM (pour les tests d'échantillons réels)

Contrôles Qualité Obligatoires En Vol (NON-NÉGOCIABLES)

Pour les opérations par lots longues (en particulier la génération QRA, l'extraction, etc.), le pré-vol seul est insuffisant. Vous DEVEZ exécuter des contrôles qualité pendant l'exécution, pas seulement avant.

La Boucle Pause-Évaluer-Diagnostiquer-Ajuster-Reprendre

Après chaque N points de contrôle du lot (par exemple, tous les 5 lots KNN / ~1000 QRA) :

1. PAUSE — SIGSTOP le processus de génération
2. INSTANTANÉ — Copier DuckDB pour analyse hors ligne, SIGCONT immédiatement
3. ÉCHANTILLON — Échantillon aléatoire stratifié (strates d'ancrage élevé/moyen/faible)
4. ÉVALUER — Vérifier chaque échantillon : ancrage des entités, qualité des réponses, raisonnement
5. DIAGNOSTIQUER — Analyse des tendances : l'ancrage diminue-t-il ? Les échecs d'entités augmentent-ils ?
6. AJUSTER — Si dégradation : ajuster le prompt, les seuils de filtre, les scores de relation
7. REPRENDRE — Uniquement si la qualité atteint les seuils
8. ARRÊTER + NOTIFIER — Si la qualité est inférieure au seuil, arrêter et notifier un humain

Ceci n'est pas optionnel. Un lot qui s'exécute jusqu'à 100 000 QRA sans contrôles qualité produira des déchets qui prendront plus de temps à nettoyer qu'à régénérer correctement.

Script de Contrôle Qualité QRA

# Surveillant continu (s'exécute parallèlement à la génération QRA)
python $SPARTA_ROOT/scripts/qra_quality_gate.py watch \
    --run-id run-recovery-verify \
    --batch-interval 5 \
    --samples 10

# Évaluation unique
python $SPARTA_ROOT/scripts/qra_quality_gate.py assess \
    --run-id run-recovery-verify \
    --samples 20

# Voir la tendance sur les points de contrôle
python $SPARTA_ROOT/scripts/qra_quality_gate.py trend \
    --run-id run-recovery-verify

Seuils de Qualité

Métrique	Avertissement	Arrêt
Ancrage moyen	< 0.65	< 0.55
% d'échecs d'entités	> 5 %	> 10 %
Taux d'échec des échantillons	> 15 %	> 30 %
Baisse d'ancrage (par point de contrôle)	> 0.05	> 0.10

Pourquoi c'est important

Le score d'ancrage QRA a dérivé de 0.74 à 0.62 sur des heures sans intervention car le surveillant était passif. Un contrôle qualité approprié aurait détecté la baisse à 0.70 → 0.65 et l'aurait diagnostiquée (KNN épuisant les relations faciles, dérive du prompt, etc.) au lieu de la laisser glisser jusqu'à 0.62.

Principe Clé

Le pré-vol est bon marché. Les lots échoués sont coûteux.

Tester 3 échantillons coûte ~0.01 $ et prend 30 secondes. Exécuter 1000 éléments avec un prompt cassé coûte ~3 $ et prend des heures.

Les contrôles en vol sont moins chers que la régénération. Pause de 10 secondes toutes les 1000 QRA pour vérifier la qualité ne coûte rien. Exécuter 100 000 QRA à l'aveugle et découvrir que la moitié est inutilisable coûte tout.