# 📄 Enterprise PDF-zu-XRechnung-Konverter (Hybrid-Architektur)

Dieses Tool ist ein hochpräziser, datenschutzkonformer Konverter, der herkömmliche B2B-Rechnungen im PDF-Format vollautomatisch in gesetzeskonforme **XRechnung-XMLs (UBL-Standard, Version 3.0)** transformiert.

Das System setzt auf einen **innovativen Hybrid-Ansatz**: Es kombiniert die semantische Flexibilität eines modernen, lokalen Large Language Models (LLM) für unstrukturierte Kopfdaten mit der unfehlbaren mathematischen Präzision von nativem Python-Code für die Positionstabelle.

---

## 🚀 Key Features

* **100 % Lokale Ausführung & DSGVO-konform:** Keine Cloud-APIs (kein OpenAI, Anthropic etc.). Alle Daten verbleiben vollständig auf der eigenen Hardware. Absolute Datensouveränität für sensible Finanzdaten.

* **Kugelsichere Tabellen-Extraktion:** Positionen, Mengen, Einheiten und Einzelpreise werden mittels optimierter regulärer Ausdrücke (Regex) fehlerfrei ausgelesen – komplett immun gegen KI-Halluzinationen oder Token-Abbrüche.

* **Finanzmathematische Präzision:** Berechnung aller Netto-, MwSt- und Bruttosummen mittels Pythons decimal-Modul inklusive striktem **kaufmännischen Runden (ROUND\_HALF\_UP)**. Keine Floating-Point-Ungenauigkeiten.

* **Human-in-the-Loop Frontend:** Eine interaktive Streamlit-Oberfläche erlaubt die sofortige visuelle Kontrolle und manuelle Korrektur aller extrahierten Daten vor dem finalen Export.

* **Validierte XML-Ausgabe:** Generiert valides UBL-2.1-Invoice-XML, das die strengen Konformitätsprüfungen der offiziellen Koordinierungsstelle für IT-Standards (KoSIT) fehlerfrei (**0 Fehler**) besteht.

---

## 🛠 Wie es funktioniert (Hybrid-Architektur)

Das Tool teilt die Extraktion in zwei spezialisierte Verarbeitungsstufen auf:

\[PDF Dokument] 

      │

      ├──> Stufe 1: Lokale KI (Qwen3.5-Instruct) ──> Extraktion von Metadaten (Kunde, Adresse, Datum, Referenz)

      │

      └──> Stufe 2: Pure Python Engine (Regex)   ──> Extraktion der Artikel (Beschreibung, Menge, Einheit, Preis)

1. **Stufe 1: Stammdaten via Lokaler KI (LLM)**

Kopfdaten wie Rechnungsnummer, Datumsangaben, Bestell-Referenzen und Kundenadressen wandern auf Rechnungen visuell stark hin und her. Hier glänzt das lokale KI-Modell: Es versteht den Kontext des gesamten Texts und extrahiert diese unstrukturierten Metadaten zuverlässig. Um strukturelle Fehler zu vermeiden, wird die KI über eine strikte JSON-Schema-Grammatik (LlamaGrammar) gezwungen, die Daten exakt in ein vordefiniertes Pydantic-Schema zu gießen.

2. **Stufe 2: Positionen via Python-Regex**

Finanztabellen erfordern 0 % Fehlertoleranz. Statt das LLM mit langen Tabellen zu überfordern (Gefahr von Abbrüchen oder Zahlendrehern), scannt ein robuster Python-Algorithmus den extrahierten Textstrom nach Mustern von Mengenangaben und Einheiten (z. B. 1,375 Tag(e) oder 2 Std.). Er greift sich nachgelagerte Preise, isoliert den zugehörigen Beschreibungstext (auch bei komplexen mehrzeiligen Umbrüchen) und filtert irrelevante Systemtexte automatisch heraus.

---

## 🤖 Das KI-Modell

Das Tool ist exakt auf das folgende Open-Weights-Modell optimiert:

* **Modell:** Qwen3.5-4B-Instruct

* **Format:** GGUF (optimiert für CPU/GPU-Inferenz via llama-cpp)

* **Quantisierung:** Q8\_0 (Hohe Genauigkeit bei exzellenter Performance)

**Wichtig:** Es muss zwingend die **Instruct**-Version des Modells verwendet werden (Qwen3.5-4B-Instruct-Q8\_0.gguf), da das reine Base-Modell nicht in der Lage ist, strukturierte Systemanweisungen und JSON-Grammatiken korrekt zu befolgen.

---

## 💻 Installation & Setup

### 1. Repository klonen & Ordnerstruktur vorbereiten

git clone \[https://github.com/dein-username/pdf-to-xrechnung.git](https://github.com/dein-username/pdf-to-xrechnung.git)

cd pdf-to-xrechnung

mkdir -p models

### 2. Lokales Modell herrichten

Lade das GGUF-Modell von Hugging Face (z. B. aus dem Repository von bartowski) herunter und platziere es im models-Ordner:

* **Pfad:** models/Qwen3.5-4B-Instruct-Q8\_0.gguf

### 3. Requirements erstellen (requirements.txt)

Für ein sauberes und schlankes Repository erstelle eine requirements.txt mit folgendem minimalen Inhalt:

streamlit==1.58.0

llama\_cpp\_python==0.3.32

pydantic==2.13.4

pymupdf==1.28.0

### 4. Abhängigkeiten installieren (inkl. GPU-Beschleunigung)

Aktiviere deine virtuelle Umgebung (venv) und führe den passenden Befehl aus, damit das KI-Modell deine Nvidia-Grafikkarte (CUDA) für rasend schnelle Antworten nutzt:

**Unter Windows (PowerShell):**

$env:GGML\_CUDA="1"; pip install -r requirements.txt --force-reinstall --no-cache-dir

**Unter Linux / macOS:**

GGML\_CUDA=1 pip install -r requirements.txt --force-reinstall --no-cache-dir

---

## 🎈 Benutzung

Starte die Applikation über dein Terminal:

streamlit run app.py

1. **PDF hochladen:** Ziehe eine herkömmliche Rechnungs-PDF per Drag-and-Drop in die left Spalte der Streamlit-Oberfläche.

2. **Daten extrahieren:** Klicke auf 🚀 Daten extrahieren. Im Hintergrund analysiert die hybride Engine das Dokument.

3. **Prüfen & Editieren:** In der rechten Spalte erscheinen alle erkannten Kopfdaten sowie die editierbare Positionstabelle. Du kannst jeden Wert manuell anpassen, Zeilen löschen oder hinzufügen.

4. **Exportieren:** Klicke auf 🔒 XRechnung exportieren. Das Tool berechnet kaufmännisch alle Summen und stellt dir die fertige, konforme XML-Datei direkt als Download (📥 Download XML) bereit.

---

## ⚖️ Rechtliche & Finanzmathematische Hinweise

* **GoBD-Konformität:** Dieses Tool generiert das strukturierte XML-Format. Der Nutzer ist selbst dafür verantwortlich, sowohl die Original-PDF als auch die generierte XML-Datei gemäß den GoBD-Richtlinien revisionssicher für 10 Jahre zu archivieren.

* **Prüfpflicht:** Das Tool arbeitet nach dem Prinzip *„Human-in-the-Loop“*. Vor dem XML-Export ist eine kurze visuelle Endkontrolle der extrahierten Daten im Streamlit-Frontend durch den Sachbearbeiter zwingend empfohlen.