Plugin neuheiten: optionale LLM-Hilfsstufe für den Web-Quellen-Crawler

Neues Modul quellen/ki_hilfe.py (konsistent zum dedup-LLM-Muster):
- Struktur-Erkennung: bei verdächtig leerem Parser-Ergebnis schlägt das
  LLM Pagination-/Filter-Folge-URLs vor; hart gefiltert auf gleiche
  Domain, max. 20 je Seite, nicht erreichbare Vorschläge brechen den
  Lauf nicht ab.
- Feld-Extraktion: nur unsichere Treffer (fehlender Verlag, verdächtiger
  Titel); korrigiert ausschließlich titel/verlag/autor, niemals die URL.
- Env-Konfiguration SPIELE_NEUHEITEN_KI_* (AKTIV default 0,
  KONFIDENZ_MIN default 0.7), OpenAI-kompatible Chat-Completions via
  httpx mit Timeout und genau einem Retry.
- Fallback-Pflicht: ohne Konfiguration oder bei jedem Fehler läuft exakt
  der klassische Crawler; KI-Fehler blockieren den Sync nie.
- Audit: KI-Eingriffe je Quelle und Lauf ins audit-log (Modell,
  Konfidenz, korrigierte Felder, verfolgte Folge-URLs).

20 neue Tests (gemocktes HTTP/LLM): Fallback-Fälle, Konfidenz-Schwelle,
Domain-Filter, Max-20-Grenze, URL-Unveränderbarkeit, Audit.
This commit is contained in:
Flo Hartmann
2026-08-23 01:07:18 +00:00
parent c6f9b19f6b
commit f27940db8e
7 changed files with 1321 additions and 7 deletions

View File

@@ -65,6 +65,12 @@ Beim ersten Start wird automatisch ein Admin-Konto angelegt:
| `SPIELE_DEDUP_LLM_MODELL` | *(leer)* | Modellname, z. B. `gpt-4o-mini` |
| `SPIELE_DEDUP_LLM_KONFIDENZ_MIN` | `0.7` | Mindest-Konfidenz; darunter wird das LLM-Ergebnis verworfen und nur der Regelbefund angezeigt |
| `SPIELE_DEDUP_LLM_TIMEOUT_SEKUNDEN` | `20` | Timeout je LLM-Aufruf; Netzwerk-/Server-Fehler werden genau einmal wiederholt |
| `SPIELE_NEUHEITEN_KI_AKTIV` | `0` | Optionale LLM-Hilfsstufe des Web-Quellen-Crawlers an (`1`) oder aus (`0`) |
| `SPIELE_NEUHEITEN_KI_BASIS_URL` | *(leer)* | Basis-URL einer OpenAI-kompatiblen Chat-Completions-API, z. B. `https://api.openai.com/v1` |
| `SPIELE_NEUHEITEN_KI_API_KEY` | *(leer)* | API-Key, wird als `Authorization: Bearer …` gesendet |
| `SPIELE_NEUHEITEN_KI_MODELL` | *(leer)* | Modellname, z. B. `gpt-4o-mini` |
| `SPIELE_NEUHEITEN_KI_KONFIDENZ_MIN` | `0.7` | Mindest-Konfidenz; darunter wird das KI-Ergebnis verworfen und der klassische Parser-Befund behalten |
| `SPIELE_NEUHEITEN_KI_TIMEOUT_SEKUNDEN` | `20` | Timeout je LLM-Aufruf; Netzwerk-/Server-Fehler werden genau einmal wiederholt |
| `SPIELE_ARCHIV_JOB_AKTIV` | `1` | Täglicher Archivierungs-Job an (`1`) oder aus (`0`) |
| `SPIELE_ARCHIV_JOB_UHRZEIT` | `03:00` | Tageszeit des täglichen Archiv-Laufs im Format `HH:MM` |
| `SPIELE_ERINNERUNG_JOB_AKTIV` | `1` | Täglicher Erinnerungs-Check an (`1`) oder aus (`0`) |
@@ -331,6 +337,44 @@ Autor, Erscheinungsjahr, Status, aktualisiert am):
- Jeder Titel verlinkt direkt auf den BGG-Eintrag.
- Sync-Steuerung nur für Rolle Admin/Redakteur.
### Web-Quellen-Crawler mit optionaler KI-Hilfsstufe
Neben BGG crawlt das Plugin zusätzlich redaktionell gepflegte Web-Quellen
(spielbox.de, brettspielbox.de, spiel-essen.de, cliquenabend.de) über je einen
Adapter in `plugins/neuheiten/quellen/` — mit Rate-Limit (1 Request/s),
Retry/Backoff, konditionalen Requests (ETag/304), Fehler-Isolation pro Quelle
und Duplikat-Gate gegen die BGG-Liste. Der Crawler arbeitet standardmäßig rein
regelbasiert.
Optional kann eine **LLM-Hilfsstufe** (`plugins/neuheiten/quellen/ki_hilfe.py`)
zugeschaltet werden — konsistent zur Dedup-KI über die
`SPIELE_NEUHEITEN_KI_*`-Variablen (siehe Tabelle oben). Das LLM wird nur in
zwei Situationen genutzt:
- **Struktur-Erkennung:** Liefert der Regel-Parser keine oder verdächtig wenige
Einträge (0 Treffer; 12 Treffer auf einer sehr linkreichen Seite), darf das
LLM aus dem gelieferten HTML Pagination-/Filter-Folge-URLs vorschlagen.
Der Vorschlag wird im Code hart gefiltert: nur URLs derselben Domain wie die
geparste Seite, maximal 20 je Seite, bereits besuchte/geplante URLs werden
übersprungen, nicht erreichbare Vorschläge brechen den Lauf nicht ab —
Schutz vor Rate-Limit-Überlastung und Domain-Ausbruch.
- **Feld-Extraktion:** Einzelne Treffer sind unsicher (fehlender Verlag oder
verdächtiger/generischer Titel). Nur solche Treffer gehen ans LLM, das
höchstens `titel`, `verlag` und `autor` korrigiert — die URL ist strukturell
nicht änderbar.
Unter der Mindest-Konfidenz (`SPIELE_NEUHEITEN_KI_KONFIDENZ_MIN`,
Standard 0.7) wird jedes KI-Ergebnis verworfen; der klassische Parser-Befund
bleibt dann unverändert bestehen.
- **Fallback-Pflicht:** Standardmäßig aus (`SPIELE_NEUHEITEN_KI_AKTIV=0`).
Ohne vollständige Konfiguration oder bei jedem Fehler (Timeout,
Server-Störung nach genau einem Retry, kaputtes JSON) läuft EXAKT der
klassische Crawler — ein KI-Fehler kann den Sync nie blockieren.
- **Audit:** KI-Eingriffe eines Sync-Laufs landen gebündelt im audit-log
(`korrigiert` / `neuheiten_ki_crawler`) mit Quelle, Modell, Konfidenz und
den jeweils korrigierten Feldern sowie den verfolgten KI-Folge-URLs.
## Plugin „dedup“ (implementiert)
Dedup-Prüfungen bei Import und händigem Eintrag. Die Prüf-Logik liegt