orc-renaming/README.md

# ORC Renaming

Datenschutzfreundliche Verarbeitung gescannter Eingangspost:

- PDFs per Nextcloud-WebDAV herunterladen
- vorhandenen OCR-Text lokal auslesen
- Rechnungen und Korrespondenz mit Regeln und optional lokalem Ollama klassifizieren
- kontrollierte Dateinamen erzeugen
- Originalname, Ergebnis, Sicherheit und Fehler in SQLite und Excel protokollieren
- Ergebnisse zurück nach Nextcloud übertragen

Die Schreibweise `orc-renaming` folgt dem Namen des bestehenden Repositorys. Inhaltlich
geht es um **OCR**-Dokumente.

## Dateinamensregeln

```text
yymmdd_RE_Firma-Immobilie.pdf
yymmdd_RE_Firma-priv.pdf
yymmdd_Firma-Topic.pdf
```

Das verwendete Datum ist bei Rechnungen das Rechnungsdatum, ansonsten das
Brief-/Dokumentdatum. Kann das System ein Pflichtfeld nicht sicher bestimmen, kommt
das Dokument in `manuell-pruefen` und wird nicht automatisch als privat eingestuft.

## Sicherheitsprinzip

`dry_run` ist in der Beispielkonfiguration eingeschaltet. In diesem Modus werden PDFs
heruntergeladen und analysiert, aber **keine Dateien oder Berichte auf Nextcloud
geschrieben und keine Originale verschoben**. Das lokale Protokoll wird trotzdem unter
`state/protokoll.xlsx` erzeugt.

Erst nach Prüfung der Namensvorschläge sollte in `config.yaml` stehen:

```yaml
processing:
  dry_run: false
```

Zugangsdaten gehören ausschließlich in Umgebungsvariablen. Für Nextcloud empfiehlt
sich ein eigenes App-Passwort mit Zugriff nur auf den vorgesehenen Bereich.
Umgebungsvariablen für HTTP-Proxys werden standardmäßig ignoriert (`trust_env: false`),
damit interne Dokumentdaten nicht unbeabsichtigt über einen Proxy laufen.

## Ablauf

1. Die oberste Ebene von `input_folder` wird nach PDFs durchsucht.
2. Jede Datei wird lokal in einem temporären Arbeitsverzeichnis verarbeitet.
3. Regeln suchen Rechnungsmerkmale, Datum, gepflegte Firmen und Immobilienmerkmale.
4. Sind Angaben unvollständig oder unsicher, wird das lokale Ollama befragt.
5. Nur vollständige Ergebnisse oberhalb von `confidence_threshold` werden automatisch
   nach `output_folder` geladen.
6. Unsichere Ergebnisse landen mit dem Präfix `PRUEFEN_` in `review_folder`.
7. Nach erfolgreichem Upload wird das Original optional nach `archive_folder`
   verschoben.
8. `protokoll.xlsx` wird im Ausgabeordner aktualisiert.

SHA-256-Prüfsummen und SQLite verhindern, dass erfolgreich verarbeitete Inhalte
erneut verarbeitet werden. Bestehende Zieldateien werden nicht überschrieben; bei
Kollisionen wird `_02`, `_03` usw. ergänzt. Eine Prozesssperre verhindert parallele
Läufe auf derselben Installation.

## Installation auf einer Linux-VM

Voraussetzungen:

- Debian/Ubuntu oder vergleichbares Linux
- Python 3.11 oder neuer
- Netzwerkzugriff auf Nextcloud
- optional Netzwerkzugriff auf den internen Ollama-Host

```bash
git clone https://gitea.muehlberger.net/JMORG/orc-renaming.git
cd orc-renaming
python3 -m venv .venv
.venv/bin/pip install .
cp config.example.yaml config.yaml
cp .env.example .env
```

`config.yaml` mit den Nextcloud-Pfaden, Immobilien, Firmen und dem Ollama-Host
ausfüllen. Anschließend das Nextcloud-Passwort setzen:

```bash
export NEXTCLOUD_PASSWORD='NEXTCLOUD-APP-PASSWORT'
.venv/bin/orc-renaming --config config.yaml check-config
.venv/bin/orc-renaming --config config.yaml run
```

Die Shell-History kann Passwörter speichern. Im Dauerbetrieb deshalb die
Environment-Datei aus dem systemd-Beispiel verwenden und auf Dateirechte `0600`
setzen.

## Ollama

Voreingestellt ist:

```yaml
ollama:
  enabled: true
  base_url: "http://ollama.intern:11434"
  model: "qwen3.5:9b"
```

Die Anwendung nutzt `/api/chat`, Temperatur `0` und ein festes JSON-Schema. An Ollama
geht nur der lokal aus dem PDF extrahierte Text. Reichen die Regeln bereits für ein
vollständiges, sicheres Ergebnis aus, wird Ollama nicht aufgerufen.

Wenn der Ollama-Host nicht erreichbar ist, wird die Datei nicht falsch benannt:
Unvollständige Ergebnisse gehen in die manuelle Prüfung und der Fehler erscheint im
Protokoll.

## Docker

Nach dem Anlegen von `.env` und `config.yaml`:

```bash
mkdir -p state work
sudo chown 10001:10001 state work
docker compose build
docker compose run --rm app
```

Der Container führt genau einen Lauf aus. Für einen regelmäßigen Betrieb kann ein
systemd-Timer `docker compose run --rm app` aufrufen. Auf einer kleinen VM ist die
direkte Python-/systemd-Installation meist übersichtlicher.

## systemd-Timer

Die Dateien in `deploy/systemd/` sind Vorlagen. Sie gehen von folgenden Pfaden aus:

- Anwendung: `/opt/orc-renaming`
- Konfiguration: `/etc/orc-renaming.yaml`
- Geheimnisse: `/etc/orc-renaming.env`
- Zustandsdaten: `/var/lib/orc-renaming`

In der produktiven Konfiguration deshalb setzen:

```yaml
processing:
  state_directory: "/var/lib/orc-renaming"
  work_directory: "/var/lib/orc-renaming/work"
```

Danach als `root`:

```bash
useradd --system --home /var/lib/orc-renaming --create-home orc-renaming
install -m 0644 deploy/systemd/orc-renaming.service /etc/systemd/system/
install -m 0644 deploy/systemd/orc-renaming.timer /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now orc-renaming.timer
```

Status und Logs:

```bash
systemctl list-timers orc-renaming.timer
journalctl -u orc-renaming.service
```

## Entwicklung

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/ruff check .
.venv/bin/pytest
```

Noch nicht Teil des ersten MVP:

- OCR für bildbasierte PDFs ohne eingebettete Textebene
- visuelle Analyse einzelner Seiten durch ein multimodales Modell
- Weboberfläche für Freigaben
- automatische Benachrichtigungen