# Save.TV Film-Enricher — Dokumentation

## Übersicht

Automatische KI-Anreicherung von Save.TV-Filmarchiv mit Beschreibungen, Darstellern, Land, Jahr und Genre.

## Komponenten

### 1. savetv_enrich.py (im Git)
- **Pfad CT 116:** `/opt/homelab-ai-bot/savetv_enrich.py`
- **Cronjob:** `0 */3 * * *` (alle 3 Stunden)
- **KI-Modell:** `qwen2.5:14b` (Primary), `qwen3:30b-a3b` (Fallback)
- **API:** Ollama native `/api/chat` mit `think=False`, `num_predict=1024`
- **Cache:** `/mnt/savetv/.filminfo_cache.json`
- **Schutz:** `fcntl.flock` File-Lock gegen parallele Instanzen
- **Sleep:** 0.5s zwischen Anfragen

### 2. savetv_web.py (im Git)
- **Pfad CT 116:** `/opt/homelab-ai-bot/savetv_web.py`
- **Port:** 8765, Service: `savetv-web`
- **Sortierung:** Neueste Filme zuerst (nach `DSTARTDATE` absteigend)
- **Anzeige:** Aufnahmedatum, KI-Beschreibung, Darsteller, Genre, Land, Jahr
- **Tailscale:** `http://100.123.47.7:8765`
- **Cloudflare:** `https://savetv.orbitalo.net`

### 3. savetv_extra_routes.py (NICHT im Git, nur lokal CT 116)
- **Pfad:** `/opt/savetv_extra_routes.py`
- **Umbenennung:** `_rename_to_jellyfin` → `Titel (Jahr).mp4`
- **Fuzzy-Match:** `_find_cache_match` normalisiert Sonderzeichen (Apostrophe, Doppelpunkte, Kommas) für Cache-Lookup
- **Downloads:** `/files/<filename>` zum Browser-Download
- **Wikidata:** Fallback für Jahr-Lookup wenn nicht im KI-Cache

### 4. Auto-Qualitätsfilter
- **Datei:** `tools/savetv_country_filter.py`
- **Zielprofil:** Jellyfin-ähnliche Kinofilme, vor allem Action, Thriller, Krimi, Abenteuer, Sci-Fi, Western, Horror und starke Dramen.
- **Blockiert automatisch:** Deutschland/Frankreich-Produktionen, Doku-/Musik-/Familien-/TV-Film-Genres, typische öffentlich-rechtliche TV-Film-Titel und unerkannte ÖR-/Regionaltitel ohne Cache.
- **Erlaubt automatisch:** internationale Kinofilme aus USA/UK/Kanada/Australien/Japan/Südkorea/Hongkong mit passendem Genre oder klar erkennbarem Kino-Titel.
- **Konsequenz:** Unbekannte RBB/MDR/hr/WDR/BR/SWR/ZDF/ARD/arte/ONE-Titel werden nicht mehr automatisch aufgenommen oder heruntergeladen, bis sie angereichert sind oder eindeutig als Kinofilm erkannt werden.

### 5. Wunschfilm-Liste
- **Datei:** `tools/savetv.py`, Konstante `WISHLIST_MOVIES`
- **Ziel:** Hochwertige Klassiker und Reihen automatisch aufnehmen, auch wenn Save.TV-Score oder Qualitätsfilter sie sonst nur vorschlagen würden.
- **Aktive Startliste:** `Der Clou`, `Déjà Vu`, `Die üblichen Verdächtigen`, `L.A. Confidential`, `Chinatown`, `French Connection`, `Bullitt`, `Serpico`, `Der Pate`, `GoodFellas`, `Casino`, `Scarface`, `Departed`, Western-Klassiker, Sci-Fi-Klassiker, starke Kriegs-/Politthriller, Gerichts-/Drama-Klassiker sowie Reihen wie `Jesse Stone`, `Columbo`, `Wallander`, `Jack Reacher`, `Bourne`, `Mission Impossible`, `Indiana Jones` und `James Bond`.
- **Schutz gegen Fehlgriffe:** Mehrdeutige Ein-Wort-Titel laufen nur mit Kontext. `Sting` wird nur mit Paul-Newman/Robert-Redford/1930er-Hinweisen als `Der Clou` akzeptiert; `Heat` braucht De-Niro/Pacino/Mann-Kontext; `Crash` braucht Haggis/Don-Cheadle/Los-Angeles-Kontext.

## Erfahrungen / Gotchas

- `qwen2.5:14b` ist zuverlässiger für JSON-Output als `qwen3:30b-a3b`
- `qwen3` füllt `reasoning`-Feld statt `content` → native API mit `think=False` nutzen
- `_is_mostly_latin` Filter gegen chinesische Beschreibungen
- `_normalize_actors` wandelt dict-Actors `{"name": "..."}` in Strings um
- Parallele Enricher-Prozesse verursachen leere Ollama-Antworten → File-Lock pflicht
- Dateinamen verlieren Sonderzeichen (`I, Tonya` → `I  Tonya`) → Fuzzy-Match nötig

## Änderungen 27.03.2026

- Enricher: File-Lock, Debug-Logging, Sleep 2.0→0.5s, atomarer Cache-Save
- Web-UI: Sortierung neueste zuerst, Aufnahmedatum in Film-Karten
- Extra-Routes: Fuzzy-Match für Jahres-Lookup bei Umbenennung
- 8 fehlende Jahreszahlen per KI nachgeholt und Dateien umbenannt