# README

## Description

Dieses Tool konvertiert Rechnungen im PDF-Format vollautomatisch in das offizielle XRechnung-XML-Format (UBL-Standard, Version 3.0). Das System verarbeitet sensible Finanzdaten vollständig lokal auf der eigenen Hardware und verzichtet auf externe Cloud-Schnittstellen.

Die Anwendung nutzt eine Hybrid-Architektur:
* **Stammdaten (Kopfdaten):** Ein lokales Large Language Model (LLM) extrahiert unstrukturierte Metadaten wie Rechnungsnummern, Datumsangaben, Bestell-Referenzen und Kundenadressen. Die Steuerung erfolgt über eine strikte JSON-Schema-Grammatik.
* **Positionen (Tabelle):** Ein nativer Python-Algorithmus extrahiert Artikelbeschreibungen, Mengen, Einheiten und Einzelpreise über reguläre Ausdrücke (Regex). Die finale Summenberechnung erfolgt finanzmathematisch präzise über das `decimal`-Modul inklusive kaufmännischem Runden.

## Supported Model

Das System ist auf das folgende Modell optimiert, welches sich im Verzeichnis `models/` befinden muss:

* **Modell:** Qwen3.5-4B-Instruct
* **Format:** GGUF
* **Quantisierung:** Q8_0

Hinweis: Es muss zwingend die Instruct-Variante des Modells verwendet werden. Das Basis-Modell (Base) ist für diese Anwendung nicht kompatibel.

## Installation

### 1. Verzeichnisstruktur vorbereiten
Erstellen Sie im Projektverzeichnis den Ordner für das lokale KI-Modell:
```bash
mkdir models
```

### 2. Virtuelle Umgebung (venv) erstellen und aktivieren
Erstellen Sie eine isolierte Python-Umgebung und aktivieren Sie diese vor der Installation der Pakete.

**Windows (PowerShell):**
```powershell
python -m venv venv
.\venv\Scripts\Activate.ps1
```

**Linux / macOS:**
```bash
python -m venv venv
source venv/bin/activate
```

### 3. Modell platzieren
Laden Sie die Modelldatei `Qwen3.5-4B-Instruct-Q8_0.gguf` herunter und platzieren Sie diese im erstellten Ordner. Der Pfad muss exakt wie folgt lauten:
`models/Qwen3.5-4B-Instruct-Q8_0.gguf`

### 4. Abhängigkeiten installieren
Die Datei `requirements.txt` ist im Repository enthalten. Führen Sie in der aktivierten virtuellen Umgebung den passenden Befehl aus, um die Installation mit GPU-Beschleunigung (Nvidia CUDA) durchzuführen:

**Windows (PowerShell):**
```powershell
$env:GGML_CUDA="1"; pip install -r requirements.txt --force-reinstall --no-cache-dir
```

**Linux / macOS:**
```bash
GGML_CUDA=1 pip install -r requirements.txt --force-reinstall --no-cache-dir
```

## Use

Starten Sie die Applikation über das Terminal:
```bash
streamlit run app.py
```

Der Konversionsprozess gliedert sich in folgende Schritte:
1. **Dokumenten-Upload:** Laden Sie die Rechnungs-PDF über die Weboberfläche hoch.
2. **Extraktion:** Starten Sie die hybride Analyse über den dafür vorgesehenen Button.
3. **Validierung:** Prüfen Sie die extrahierten Kopfdaten und die Positionstabelle in der Benutzeroberfläche. Da alle Felder editierbar sind, können Korrekturen direkt vorgenommen werden.
4. **Export:** Generieren Sie die finale XML-Datei über die Export-Funktion und starten Sie den Download.

## Notes

### Human-in-the-Loop
Das Tool dient als Automations-Assistent. Vor dem finalen XML-Export ist eine visuelle Endkontrolle der extrahierten Daten (insbesondere Rechnungsnummer und Empfängeradresse) durch den Sachbearbeiter zwingend erforderlich, um KI-Fehlinterpretationen auszuschließen.

### GoBD-Konformität
Das Tool generiert ausschließlich das strukturierte XML-Format. Für die Einhaltung der GoBD-Richtlinien (u. a. die revisionssichere Archivierung der Original-PDF sowie der generierten XML-Datei über den gesetzlichen Zeitraum von 10 Jahren) ist der Betreiber der Software selbst verantwortlich.