jiawood2006/hermes-skills

Doc-OCR Dokumentenerkennung + Strukturierung

PDF / Scan / Bild → bearbeitbarer Text → strukturierte Daten. PDFs mit Textebene werden direkt extrahiert, Scans automatisch per OCR verarbeitet (macOS Vision integriert, Chinesisch/Englisch), Layout-Wiederherstellung (mehrspaltige/komplexe Layouts werden in Lesereihenfolge neu angeordnet, nicht als rohe Zeilen ausgegeben). Nach der OCR können mit LLM Rechnungs-/Vertragsfelder extrahiert oder in Tabellen umgewandelt werden.

📁 Installation: hermes skills install jiawood2006/hermes-skills/skills/doc-ocr oder gemäß README Methode 2 kopieren → standardmäßig in ~/.hermes/skills/utilities/doc-ocr/. Die folgenden Befehle basieren auf diesem Pfad.

Auslösebedingungen

Benutzer stellt PDF/Bilddatei bereit mit der Anforderung:

• "Text extrahieren", "In Text umwandeln", "OCR"
• Verarbeitung von Scans, Verträgen, Rechnungen, Buchseiten, Screenshots
• "Rechnungsinformationen extrahieren", "Vertragspunkte", "In Tabelle umwandeln" (strukturiert)

Nutzungsschritte

1. Einzelne Datei → Text

python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py Vertrag.pdf
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py Rechnung.jpg

Ausgabe wird als <Eingabename>_ocr.txt gespeichert.

2. Batch-Verzeichnis (fehlertolerant pro Datei, fehlerhafte Dateien unterbrechen nicht)

python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py ./Scans/ -o Alle.txt
# Batch-Ausgabe: Zusammenfassung Erfolg N/M + Fehlerliste (fehlerhafte Dateien separat protokolliert, Batch wird nicht abgebrochen)

3. Markdown-Ausgabe / Layout-Wiederherstellung für mehrspaltige PDFs erzwingen

python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py Buch.pdf --md
# Wenn die Textebene in mehrspaltigen PDFs durcheinander ist, OCR mit Layout-Wiederherstellung erzwingen:
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py ZweispaltigeArbeit.pdf --md --force-ocr

4. Strukturierte Extraktion (Rechnung/Vertrag/Tabelle, erfordert LLM-Schlüssel)

# Zuerst OCR, dann Felder extrahieren
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py Rechnung.jpg
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py Rechnung_ocr.txt --type invoice

# Vertragsfelder (Auftraggeber/Auftragnehmer/Betrag/Laufzeit/Vertragsstrafen)
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py Vertrag_ocr.txt --type contract

# Tabelle → CSV
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/docstruct.py Tabelle_ocr.txt --type table -o Tabelle.csv

• --type invoice: Rechnungsnummer/Datum/Betrag/Steuerbetrag/Bruttobetrag/Käufer/Verkäufer/Steuernummer
• --type contract: Vertragsname/Parteien/Unterzeichnungsdatum/Betrag/Zahlungsweise/Laufzeit/Vertragsstrafen
• --type table: Automatische Erkennung von Zeilen-/Spaltenstruktur → CSV
• Ausgabe benutzerfreundlich + speicherbar als JSON/CSV (mit -o)

Abhängigkeiten (bei erster Nutzung installieren)

pip3 install pymupdf pyobjc-framework-Vision
# Strukturierte Extraktion erfordert LLM-Schlüssel (Umgebungsvariable LLM_API_KEY oder ~/.deai_writer.conf)

Hinweis: OCR ist abhängig von macOS Vision (nur macOS verfügbar). Unter Linux muss zusätzlich tesseract oder eine andere Engine installiert werden.

Bekannte Fallstricke

• Scan-Erkennung: PDFs mit weniger als 20 Zeichen in der Textebene werden automatisch per OCR verarbeitet, normale PDFs direkt extrahiert.
• Layout-Wiederherstellung: Vision OCR ordnet Text basierend auf Textrahmenkoordinaten neu an (von oben nach unten, innerhalb einer Zeile von links nach rechts); zweispaltige Druckschrift wird als "zuerst linke Spalte, dann rechte Spalte" behandelt, geeignet für Arbeiten/Berichte, bei Zeitschriften-Layouts kann es zu Unordnung kommen – mit --force-ocr und Sichtprüfung arbeiten.
• Handschrift: Vision liefert gute Ergebnisse für Druckschrift und klare Handschrift, bei unleserlicher Handschrift keine Garantie.
• Datenschutzvorteil: Dateien werden lokal verarbeitet, nicht an Dritte hochgeladen (strukturierte Extraktion ruft LLM-API auf, bei sensiblen Dateien beachten).
• Fehlende Felder: docstruct füllt fehlende Felder mit null und erfindet nichts; bei schlechter OCR-Qualität können Felder fehlen.
• Batch-Fehlertoleranz: Im Verzeichnismodus werden einzelne Dateifehler protokolliert, ohne den gesamten Batch abzubrechen.

Schnelltest / Smoke Test

# Installation überprüfen (auch ohne Dokument möglich)
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py --help
# Echter Test mit einem beliebigen PDF/Bild
python3 ~/.hermes/skills/utilities/doc-ocr/scripts/dococr.py BeliebigesDokument.pdf --md
# Erwartet: Ausgabe *_ocr.md mit bearbeitbarem Text