# CLAUDE.md — Klarbildbot

Kontext für künftige Sessions.

## Was ist das
Self-hosted Telegram-Bot (`@Klarbildbot`) für AI-Bildaufbereitung: Upscaling (Klarbild), Freistellen, beides. Alles lokal auf CPU, keine US-APIs (HD-Regel). Optional Picdrop-Batch via SFTP.

## Architektur
- `app/bot.py` — Telegram (python-telegram-bot, **Polling**). Bild → Inline-Menü → Job im `ThreadPoolExecutor(max_workers=1)` (serialisiert, Speicherschutz). Health-Server (aiohttp) auf `:8080/health` im selben Prozess.
- `app/enhance.py` — Bildlogik. Upscale = OpenCV `dnn_superres` (FSRCNN default / EDSR optional), **gekachelt** mit Überlappung. Freistellen = `rembg` (isnet-general-use, Alpha-Matting). `cutout_then_upscale` skaliert RGB + Alpha getrennt.
- `app/picdrop.py` — paramiko-SFTP: list/find/download/upload. `/picdrop`-Command.
- `app/config.py` — alle ENV.
- `scripts/fetch_models.sh` — lädt SR-.pb von **raw.githubusercontent.com** (github.com wird in mancher Sandbox geblockt!).

## Modelle (beim Docker-Build gebacken, NICHT im Git)
- SR: `EDSR_x2/x4.pb`, `FSRCNN_x2/x4.pb` (Saafke-Repos, raw.githubusercontent).
- rembg: `isnet-general-use.onnx` vom HuggingFace-Mirror `tomjackson2023/rembg` (unabhängig von github-Releases).

## Deployment
- Repo: Gitea `till/klarbildbot` (git.heidrich-digital.de).
- Coolify: Projekt **heidrich-betrieb** (`h7bvq4s9eg3e3mginl515wrp`), Env production (`xvdo831merpuzhqb4sf3szkr`), Server localhost/CX33. Dockerfile-Build. Erstmal Coolify-eigene URL.
- Pflicht-ENV: `BOT_TOKEN`. Empfohlen: `ALLOWED_USER_IDS` (eigene TG-ID). Für Picdrop: `PICDROP_USER/PASSWORD`.

## Wichtige Erkenntnisse
- **EDSR auf CPU ist unbrauchbar langsam** (~40 s schon für 256px). Default = **FSRCNN**.
- Telegram-File-Limit **20 MB** (Bots). Fotos sind komprimiert → für volle Qualität als *Datei* senden.
- CX33: 8 GB, keine GPU, OOM-Risiko → `MAX_INPUT_EDGE=1600`, `TILE_SIZE=256`, ein Job gleichzeitig.
- Bot ist Polling → braucht keinen öffentlichen Webhook; Coolify-Domain nur für Health.

## Backlog / offen
- `ALLOWED_USER_IDS` auf Tills echte TG-ID setzen (nach erstem `/start`).
- Optional Real-ESRGAN-ONNX-Backend (`ENABLE_REALESRGAN=1`) für bessere Foto-Qualität auf stärkerer Box.
- Picdrop-Batch erst nach Deploy real getestet (SFTP aus Cloud-Sandbox geblockt).
- Custom-Domain (z. B. klarbild.heidrich-digital.de) später via Coolify-UI.