Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,185 @@
+---
+language:
+  - de
+  - en
+license: apache-2.0
+library_name: transformers
+pipeline_tag: image-text-to-text
+tags:
+  - german
+  - deutsch
+  - ocr
+  - vision
+  - document-ai
+  - invoice
+  - rechnung
+  - structured-extraction
+  - json-extraction
+  - kie
+  - ollama
+  - vllm
+  - llama-cpp
+  - apache-2.0
+inference: true
+---
+
+<p align="center">
+  <img src="https://app.german-ocr.de/icon.png" alt="German-OCR-3" width="128" height="128" />
+</p>
+
+<h1 align="center">German-OCR-3</h1>
+
+<p align="center"><strong>Deutsche Vision-OCR. Kompakt. Lokal. Open Source.</strong></p>
+
+<p align="center">
+  <a href="https://german-ocr.de"><img alt="Site" src="https://img.shields.io/badge/site-german--ocr.de-3B82F6?style=flat-square"/></a>
+  <a href="https://ollama.com/Keyvan/german-ocr-3"><img alt="Ollama" src="https://img.shields.io/badge/Ollama-Keyvan%2Fgerman--ocr--3-orange?style=flat-square"/></a>
+  <a href="https://github.com/Keyvanhardani/German-OCR-3-Dev"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-source-black?style=flat-square"/></a>
+  <a href="LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/License-Apache_2.0-green?style=flat-square"/></a>
+</p>
+
+---
+
+## Was ist German-OCR-3?
+
+**German-OCR-3** ist eine kompakte, schnelle und voll lokal lauffähige **Vision-OCR-Distribution für deutsche Geschäftsdokumente** — Rechnungen, Briefe, Formulare, Quittungen, Bescheide. Aus dem Bild kommt **strikt validiertes JSON nach unserem deutschen Extraktions-Schema**, ohne Cloud-Pflicht, ohne Vendor-Lock-in.
+
+Zwei Editionen, beide Apache-2.0, beide unter 3 GB:
+
+| Edition | Größe (Ollama) | Zielhardware | Stärke |
+|---|---:|---|---|
+| **`german-ocr-3:nano`** | **1.0 GB** | CPU / Edge / Mobile | „läuft überall" |
+| **`german-ocr-3` ⭐** | **2.7 GB** | 4–6 GB VRAM | empfohlene Default-Edition |
+
+⭐ Auf unserem Praxistest mit **19 echten anonymisierten deutschen Rechnungen**: **100 % gültiges JSON · 95 % Sender korrekt erkannt · 0 % Halluzination**.
+
+> **Fine-tuned adapter** für deutsche Geschäftsdokument-Extraktion. Apache 2.0.
+
+## Trainings- und Evaluations-Datensätze
+
+* [`neuralabs/german-synth-ocr`](https://huggingface.co/datasets/neuralabs/german-synth-ocr) — 4 500+ deutsche OCR-Samples (synthetisch, Apache-2.0)
+* `Aoschu/German_invoices_dataset_for_donut` — 129 echte deutsche Rechnungen (Donut-Format)
+* **Eigenes synthetisches DE-Rechnungs-Set** — 100 Rechnungen mit Golden-JSON, deterministisch generiert (`eval/fixtures/synth_de_invoices/`)
+* **IONOS-Praxistest** (anonymisiert) — 19 echte 1&1/IONOS-Rechnungen, intern, nicht im Repo (DSGVO)
+
+---
+
+## Praxistest: 19 deutsche Rechnungen
+
+![IONOS Praxistest](https://raw.githubusercontent.com/Keyvanhardani/German-OCR-3-Dev/main/assets/charts/02_ionos_validity.png)
+
+| Edition | Valid JSON | Sender korrekt | **Halluzination** | Latenz |
+|---|---:|---:|---:|---:|
+| `german-ocr-3-nano` | 16 / 19 (84 %) | 15 / 19 (79 %) | **0 %** | 6.6 s |
+| **`german-ocr-3` ⭐** | **19 / 19 (100 %)** | **18 / 19 (95 %)** | **0 %** | **5.0 s** |
+
+Datenquelle: 19 anonymisierte, real existierende deutsche Rechnungen einer großen DACH-Hosting-Marke. Beide Editionen lesen die echten Daten — Firmenname, USt-IdNr, Kundenadresse, Produkte, Beträge — **statt deutsche Defaults zu raten** (typischer Fehler kleiner Vision-LLMs ohne strict-prompt).
+
+## Größenvergleich
+
+![Modellgrößen](https://raw.githubusercontent.com/Keyvanhardani/German-OCR-3-Dev/main/assets/charts/01_size_vs_competitors.png)
+
+`german-ocr-3` (2.7 GB) ist **6× kleiner** als ein typischer 7B-OCR-VLM, läuft auf einer **8 GB-Gaming-GPU** oder über CPU auf einem normalen Laptop.
+
+---
+
+## Quickstart
+
+### Ollama (empfohlen, eine Zeile)
+
+```bash
+ollama pull Keyvan/german-ocr-3
+ollama run Keyvan/german-ocr-3 "Extrahiere die Rechnung im Bild als JSON." ./meine_rechnung.png
+```
+
+Erwartetes Ergebnis (echter Output):
+
+```json
+{
+  "document_type": "invoice",
+  "language": "de",
+  "invoice_number": "100137157949",
+  "invoice_date": "2024-01-22",
+  "due_date": "2024-01-27",
+  "sender": {
+    "name": "IONOS SE",
+    "address": "Elgendorfer Str. 57, 56410 Montabaur",
+    "vat_id": "DE815563912",
+    "iban": null
+  },
+  "recipient": {
+    "name": "Persepolis Travel e.K.",
+    "address": "Dachauer Straße 32, 80335 München",
+    "customer_id": "583534778"
+  },
+  "line_items": [
+    {"position": 1, "description": "Mail Business 1 Liz.", "quantity": 1,
+     "unit": "Monat", "unit_price_net": 4.20, "amount_net": 4.20, "vat_rate": 19}
+  ],
+  "amount_net": 4.20,
+  "amount_vat": 0.80,
+  "amount_total": 5.00,
+  "currency": "EUR",
+  "notes": ["Entsprechend Ihrem SEPA-Lastschriftmandat ..."]
+}
+```
+
+### Python (via Ollama HTTP API)
+
+```python
+import base64, json, requests
+from pathlib import Path
+
+b64 = base64.b64encode(Path("rechnung.png").read_bytes()).decode()
+resp = requests.post("http://localhost:11434/api/generate", json={
+    "model": "Keyvan/german-ocr-3",
+    "prompt": "Extrahiere die Rechnung im Bild als JSON.",
+    "images": [b64],
+    "stream": False,
+    "options": {"temperature": 0, "num_ctx": 32768},
+})
+data = json.loads(resp.json()["response"])
+print(json.dumps(data, indent=2, ensure_ascii=False))
+```
+
+### Bundle herunterladen
+
+```bash
+huggingface-cli download Keyven/german-ocr-3 --local-dir ./german-ocr-3
+# Enthält: Modelfile · JSON-Schemas · System-Prompt · GGUF-Quants · Charts
+```
+
+### llama.cpp (GGUF direkt)
+
+```bash
+llama-cli -m ./german-ocr-3/german-ocr-3-Q4_K_M.gguf \
+  --system-prompt-file ./german-ocr-3/system_prompt.txt \
+  -p "Extrahiere die Rechnung als JSON:" --temp 0
+```
+
+---
+
+## Zielgruppen
+
+* **Solo-Builder & Indies** die deutsche Dokumente lokal extrahieren wollen, ohne Cloud-OCR-Kosten.
+* **DACH-KMU** mit Datenschutz-Anspruch, die lokal/on-prem hosten wollen.
+* **Agenturen & Studios** die ein Open-Source-Fundament unter ihrer eigenen Pipeline wollen.
+
+Wer es **gemanagt** und mit größeren Modellen will:
+
+> 🌐 **[german-ocr.de](https://german-ocr.de)** — gehostete deutsche OCR-API mit Premium-Modellen, höherer Genauigkeit, ohne eigene Hardware. Daten bleiben in der EU.
+
+## Lizenz
+
+Apache License 2.0. Vollständige Attribution (inkl. Architektur-Credit) in [`NOTICE`](NOTICE).
+
+## Zitation
+
+```bibtex
+@misc{german_ocr_3_2026,
+  title  = {German-OCR-3: A compact German document-OCR distribution},
+  author = {Hardani, Keyvan},
+  year   = {2026},
+  url    = {https://github.com/Keyvanhardani/German-OCR-3-Dev}
+}
+```