gwoe-antragspruefer/docs/adr/0003-citation-property-tests.md

0003 — Sub-D Property-Verification: Zitate als Substring der zitierten PDF-Seite

Status	accepted
Datum	2026-04-10
Refs	Issues #50, #54, #60; tests/integration/test_citations_substring.py

Kontext

Der LLM-Output enthält pro Assessment N Zitate, jedes mit text, quelle (z.B. "GRÜNE NRW Wahlprogramm 2022, S. 58") und url. Wahrscheinlich korrekt — aber wie verifizieren wir das, ohne jedes einzeln händisch nachzuschlagen?

Die naheliegenden Test-Optionen sind alle unbefriedigend:

• Mock-LLM-Tests: prüfen das Schema, sagen aber nichts über die inhaltliche Korrektheit.
• Snapshot-Tests der LLM-Outputs: drift mit jedem Modell-Update.
• Manuelles Stichprobenchecken: skaliert nicht über mehrere BLs.

Optionen

Option A — Schema-only Tests (was wir vorher hatten)

Pydantic validiert dass jedes Zitat die Felder text, quelle, url hat und url mit /static/referenzen/ beginnt. Erkennt syntaktische Korruption, aber keine Halluzinationen.

Option B — Property-Test gegen die echten PDFs

Pro Zitat in der Prod-DB:

1. quelle per Token-Coverage-Match auf den PROGRAMME-Eintrag mappen.
2. Seitennummer aus quelle extrahieren.
3. Per fitz die PDF-Seite lesen, Whitespace + Soft-Hyphen normalisieren.
4. text muss als Substring (oder 5-Wort-Anker) in der Seite vorkommen.
5. Bug-Klasse 17 (Cross-Bundesland-Zitat): das aufgelöste Programm muss zum Bundesland des Antrags passen, oder ein Grundsatzprogramm sein.

Vorteile: prüft die einzige Eigenschaft die wirklich zählt — "war das was zitiert wird auch wirklich da". Findet Halluzinationen direkt.

Nachteile: braucht eine lokale Kopie der gwoe-antraege.db und der Wahlprogramm-PDFs. Test ist Pydantic-Schema-übergreifend (Integration, nicht Unit). Skipped sauber wenn DB nicht gemounted ist.

Option C — Online-Verifikation pro Assessment-Insert

Im analyze_antrag-Flow direkt nach LLM-Call jedes Zitat verifizieren und bei Failure abbrechen oder retry.

Vorteile: kein "stale data in DB"-Risiko.

Nachteile: fügt Latenz und Komplexität in den Hot-Path. Die Verifikation ist O(N×M), wo N=Zitate und M=Wahlprogramm-Pages.

Entscheidung

Option B als pytest-Integration-Test — tests/integration/test_citations_substring.py, parametrisiert per _load_recent_assessments(limit_per_bl=5) × _flat_zitate().

Strict substring als Default-Match (Whitespace + Soft-Hyphen normalisiert, LLM-Truncation-Marker ... toleriert), 5-Wort-Anker als Fallback für geringfügige Wort-Drift wie "LLM hat mittendrin gekürzt". Min-Length-Guard von 20 Zeichen verhindert false-positive Matches auf trivialen Snippets.

Marker pytestmark = pytest.mark.integration — der Test läuft nicht in der Default-Suite, sondern explizit per pytest -m integration. Skipped wenn webapp/data/gwoe-antraege.db nicht existiert (Dev-Setup ohne DB-Kopie).

Match-Helpers (_normalize, _is_substring, _resolve_quelle_to_programm_id, _extract_page_number) sind eigene Unit-Tests in TestHelpers — die Match- Logik selbst ist nicht-trivial und braucht ihre Eigenkontrolle.

Konsequenzen

Positiv

• Findet Halluzinationen direkt: Issue #60 wurde durch den ersten Live-Lauf dieses Tests entdeckt (3 von 36 Citations failed), ohne dass ein Mensch Wahlprogramm-PDFs aufmachen musste.
• Re-runnable als Regression-Gate: nach jedem Deploy einmal pytest -m integration gegen die DB → 0 Failures = OK.
• Test-Logik = Production-Logik: ADR 0001 Option B (reconstruct_zitate) nutzt identische Match-Heuristiken (find_chunk_for_text, _normalize_for_match). Damit kann der Test nichts fangen, was die Production nicht auch fangen würde, und umgekehrt — kein Test-/Prod-Drift.

Negativ

• Lokale DB-Kopie nötig: vor jedem Sub-D-Run muss data/gwoe-antraege.db vom Container gepullt werden. CI-Integration steht aus.
• Test ist langsam-ish: ~50 Citations × ein PDF-Open pro Programm ist bei den ~30 indexierten Programmen ~250ms im Ganzen, nicht trivial aber nicht prohibitiv.
• Token-Coverage-Heuristik für Quelle-zu-Programm-Mapping kann false- positive bei sehr ähnlichen Programmen werden (z.B. CDU NRW 2022 vs. CDU Niedersachsen 2022 — würde durch Bundesland-Bonus-Check abgefangen).

Folgen für andere ADRs

• ADR 0001 ist von ADR 0003 abhängig — wenn dieser Test entfernt würde, hätte der LLM-Citation-Postprocess keinen Backstop und neue Halluzinations- Bug-Klassen würden still durchrutschen.