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

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:

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

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:

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:

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:

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:

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

Danach als root:

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:

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

Entwicklung

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