grahama1970/batch-quality

Batch Quality Skill

Verhindern Sie verschwendete LLM-Aufrufe, indem Sie die Qualität VOR der Ausführung kompletter Batch-Operationen validieren.

Was dieser Skill tatsächlich tut

Im Gegensatz zu einfachen Dateiprüfungen macht dieser Skill:

1. Führt tatsächlich LLM auf N Stichproben aus mit scillm
2. Validiert JSON-Antwortstruktur (excerpts, source_quality, etc.)
3. Nutzt SPARTA-Verträge für DuckDB-Validierungsabfragen
4. Integriert sich in task-monitor für erzwungene Qualitätstore

Kurzanleitung

cd .pi/skills/batch-quality

# Preflight: 3 Stichproben durch tatsächliches LLM testen
uv run python cli.py preflight \
    --stage 05 \
    --run-id run-recovery-verify \
    --samples 3

# Wenn Preflight bestanden ist, Batch ausführen
# ...Batch-Operation...

# Validieren: DuckDB gegen Vertrag prüfen
uv run python cli.py validate \
    --stage 05 \
    --run-id run-recovery-verify \
    --task-name "sparta-stage-05"

Befehle

preflight

Testet N Stichproben durch tatsächliches LLM, bevor der vollständige Batch ausgeführt wird.

uv run python cli.py preflight \
    --stage <stage-name> \
    --run-id <sparta-run-id> \
    --samples 3 \
    --prompt <optional-prompt-file>

Was es tatsächlich tut:

1. Lädt SPARTA-Vertrag für die Stufe (falls vorhanden)
2. Prüft Umgebungsvariablen (CHUTES_API_KEY, CHUTES_TEXT_MODEL)
3. Stellt Verbindung zu DuckDB für den Run her
4. Zieht N Elemente aus der Eingabewarteschlange
5. Führt jedes Sample durch scillm (tatsächlicher LLM-Aufruf)
6. Validiert JSON-Antwortstruktur
7. Erfordert, dass 50 %+ der Samples bestehen

Exit-Codes:

• 0: BESTANDEN – sicher fortzufahren
• 1: FEHLGESCHLAGEN – zuerst Probleme beheben

validate

Validiert Batch-Ausgabe mit SPARTA-Verträgen.

uv run python cli.py validate \
    --stage <stage-name> \
    --run-id <sparta-run-id> \
    --task-name <task-monitor-name>

Was es tatsächlich tut:

1. Lädt SPARTA-Vertrag (z.B. 05_extract_knowledge.json)
2. Führt alle validation_queries aus dem Vertrag gegen DuckDB aus
3. Prüft jedes Abfrageergebnis gegen expected_min
4. Benachrichtigt task-monitor über Bestehen/Fehlschlagen

Vertragsbeispiel (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

Zeigt aktuellen Preflight-Status an (JSON-Ausgabe).

uv run python cli.py status

clear

Löscht den Preflight-Status (erfordert neuen Preflight).

uv run python cli.py clear

SPARTA-Pipeline-Integration

# 1. Aufgabe mit Validierungsanforderung registrieren
uv run python .pi/skills/task-monitor/monitor.py register \
    --name "sparta-stage-05" \
    --require-validation

# 2. Preflight ausführen (TESTET TATSÄCHLICH LLM)
uv run python .pi/skills/batch-quality/cli.py preflight \
    --stage 05 \
    --run-id run-recovery-verify \
    --samples 3

# 3. Batch ausführen (nur wenn Preflight bestanden)
uv run python -m sparta.pipeline_duckdb.05_extract_knowledge \
    --run-id run-recovery-verify

# 4. Mit Vertragsabfragen validieren
uv run python .pi/skills/batch-quality/cli.py validate \
    --stage 05 \
    --run-id run-recovery-verify \
    --task-name "sparta-stage-05"

Konfiguration

Umgebungsvariablen:

• SPARTA_ROOT: Pfad zum SPARTA-Projekt (Standard: ~/workspace/experiments/sparta)
• CHUTES_API_KEY: API-Schlüssel für LLM-Aufrufe
• CHUTES_API_BASE: API-Basis-URL (Standard: https://llm.chutes.ai/v1)
• CHUTES_TEXT_MODEL: Modell-ID für Textextraktion

Vertragsverzeichnis: $SPARTA_ROOT/tools/pipeline_gates/fixtures/D3-FEV/contracts/

Abhängigkeiten

• typer – CLI-Framework
• duckdb – Datenbankabfragen
• scillm – LLM-Batch-Verarbeitung (für tatsächliche Stichprobentests)

Zwingende Qualitätstore während der Ausführung (NICHT VERHANDELBAR)

Bei langlebigen Batch-Operationen (insbesondere QRA-Generierung, Extraktion usw.) reicht ein Preflight allein nicht aus. Sie MÜSSEN Qualitätstore während der Ausführung durchführen, nicht nur davor.

Der Pause-Assess-Diagnose-Tweak-Resume-Zyklus

Nach jedem N Batch-Checkpoints (z.B. alle 5 KNN-Batches / ~1000 QRAs):

1. PAUSE – SIGSTOP des Generierungsprozesses
2. SNAPSHOT – DuckDB für Offline-Analyse kopieren, SIGCONT sofort
3. SAMPLE – Stratifizierte Zufallsstichprobe (hohe/mittlere/niedrige Grundierungsebenen)
4. ASSESS – Jede Stichprobe prüfen: Entity-Grundierung, Antwortqualität, Begründung
5. DIAGNOSE – Trendanalyse: Nimmt die Grundierung ab? Steigen Entity-Fehler?
6. TWEAK – Bei Verschlechterung: Prompt anpassen, Filters chwellen, Beziehungswerte ändern
7. RESUME – Nur fortsetzen, wenn Qualität Schwellenwerte erfüllt
8. STOP + BENACHRICHTIGEN – Wenn Qualität unter Mindestwert fällt, anhalten und Menschen benachrichtigen

Dies ist nicht optional. Ein Batch, der 100k QRAs ohne Qualitätstore ausführt, produziert Müll, dessen Bereinigung länger dauert als die korrekte Regenerierung.

QRA-Qualitätstor-Skript

# Kontinuierlicher Watchdog (läuft parallel zur QRA-Generierung)
python $SPARTA_ROOT/scripts/qra_quality_gate.py watch \
    --run-id run-recovery-verify \
    --batch-interval 5 \
    --samples 10

# Einmalige Bewertung
python $SPARTA_ROOT/scripts/qra_quality_gate.py assess \
    --run-id run-recovery-verify \
    --samples 20

# Trend über Checkpoints anzeigen
python $SPARTA_ROOT/scripts/qra_quality_gate.py trend \
    --run-id run-recovery-verify

Qualitätsschwellenwerte

Metrik	Warnung	Stopp
Durchschnittliche Grundierung	< 0.65	< 0.55
Entity-Fehler %	> 5 %	> 10 %
Stichproben-Fehlerrate	> 15 %	> 30 %
Grundierungsabnahme (pro Checkpoint)	> 0.05	> 0.10

Warum das wichtig ist

Der QRA-Grundierungswert driftete über Stunden von 0,74 auf 0,62, ohne dass eingegriffen wurde, weil der Watchdog passiv war. Ein ordentliches Qualitätstor hätte den Rückgang bei 0,70 → 0,65 erkannt und diagnostiziert (KNN erschöpft einfache Beziehungen, Prompt-Drift usw.), anstatt ihn bis auf 0,62 abrutschen zu lassen.

Schlüsselprinzip

Preflight ist billig. Fehlgeschlagene Batches sind teuer.

3 Stichproben zu testen kostet ~0,01 $ und dauert 30 Sekunden. 1000 Elemente mit einem defekten Prompt auszuführen kostet ~3 $ und dauert Stunden.

Qualitätstore während der Ausführung sind billiger als Regenerierung. Alle 1000 QRAs für 10 Sekunden anzuhalten, um die Qualität zu überprüfen, kostet nichts. Blind 100k QRAs auszuführen und festzustellen, dass die Hälfte unbrauchbar ist, kostet alles.