PDAI-Dateiformat und Ablagestruktur

TippPDAI-Ablage in einem Satz

Jeder Scanlauf erzeugt ein in sich geschlossenes, archivfestes Dokumentbündel: ein Verzeichnis mit dem unveränderlichen Sensor-Master, den verarbeiteten Seiten und vollständigen Metadaten in einem offenen JSON-Format.

Die PDAI-Ablage (Portable Document AI) ist das Speicherformat, das Famulus Repro für alle erfassten Dokumente verwendet. Ein PDAI-Dokumentbündel enthält alles, was nötig ist, um das Dokument vollständig zu rekonstruieren, anzuzeigen und mit PDAI-Werkzeugen weiterzuverarbeiten: den Rohdaten-Master, die verarbeiteten Seiten, alle Metadaten der Verarbeitungskette und die Partitur-Ergebnisse.

1 Speicherort

Die Scan-Bibliothek liegt unter:

~/Documents/Scans/

Famulus Repro läuft nicht in einer App-Sandbox — es greift direkt auf ~/Documents/Scans/ zu (Security-Scope-Bookmark in ScanFolderBookmark). Ein alternativer Ordner kann im Inspektor unter “Ablage → Ordner wählen…” gesetzt werden; der Bookmark wird persistent gespeichert.

2 Verzeichnisstruktur — Buchmodell

~/Documents/Scans/
  Dokument_2026-09-03_08-42/        ← frei gewählter Dokumentname
    masters/
      master_001.heic               ← unveränderter 48-MP-Sensor-Master
      master_002.heic
    page_001/                       ← linke Seite aus Master 001
      page_001.jpg                  ← rektifiziertes + tonwertoptimiertes Seiten-JPEG
      page_001.txt                  ← Vision-OCR Rohtranskript (Flachtext)
      page_001.json                 ← GeometryReport + ToneReport + OCRResult + Quality-Gates
      page_001.ext.xml              ← Extended-OCR: DTD-konformes Buch-XML
      page_001.ext.txt              ← Flachtext aus ext.xml
    page_002/                       ← rechte Seite (analog)
      page_002.jpg
      page_002.txt
      page_002.json
      page_002.ext.xml
    metadata/
      page_selection.json           ← Pagenum-Overrides und Reihenfolge (nie direkt im XML)
    archive/                        ← archivierte Duplikate (nie gelöscht, nur verschoben)
    document.json                   ← Dokumentregister, Partitur-Status, Modell-Historie
    ocr_extended.status.json        ← Extended-OCR-Gesamtstatus (pending/running/done)

Jeder Master erzeugt im Buchmode zwei Seiten (page_N und page_N+1), im Einzelblattmode eine.

3 Verzeichnisstruktur — Einzelblatt (Belege)

Einzelblatt-Ordner werden nach der OCR-Klassifizierung umbenannt. Das Dokumentverzeichnis erhält einen kanonischen Stem:

~/Documents/Scans/QUITTUNGEN/        ← übergeordneter Sammelordner (Name bleibt)
  [parking]-Schadowstrasse-15-08-2026-3.50-EUR/
    masters/
      master_001.heic
    [parking]-Schadowstrasse-15-08-2026-3.50-EUR/
      [parking]-Schadowstrasse-15-08-2026-3.50-EUR.jpg    ← Seitenbild
      [parking]-Schadowstrasse-15-08-2026-3.50-EUR.txt    ← Vision-OCR
      [parking]-Schadowstrasse-15-08-2026-3.50-EUR.json   ← Seitenprotokoll
      [parking]-Schadowstrasse-15-08-2026-3.50-EUR.ext.xml   ← DTD-konformes Beleg-XML
      [parking]-Schadowstrasse-15-08-2026-3.50-EUR.ext.txt
      [parking]-Schadowstrasse-15-08-2026-3.50-EUR.receipt.json  ← Flat-JSON (alle DTD-Attribute)
    document.json
    ocr_extended.status.json

Das [klasse]-Firma-Datum-Betrag-Währung-Namensschema wird von ReceiptClassifier + PDAIBackendPipeline.renamePageArtefacts() erzeugt. Die Klasse kann sein: parking, Taxi, pharma, Bahn, hotel, fuel, restaurant oder leer (offene Klasse).

Der übergeordnete Sammelordner (z. B. QUITTUNGEN) erhält keinen automatischen neuen Namen.

4 Dateibeschreibungen

4.1 masters/master_NNN.heic

Der unveränderte Sensorabzug in voller Auflösung (48 MP). Diese Datei wird von Famulus Repro nie modifiziert oder überschrieben. Sie bildet die archivfeste Grundlage, aus der jederzeit alle verarbeiteten Seiten mit anderen Parametern neu erzeugt werden können.

4.2 page_NNN/page_NNN.jpg

Das Ergebnis der vollständigen Verarbeitungskette:

  1. Perspektivkorrektur und Ausrichtung (aus dem masters/-Bild)
  2. Seitentrennung (Buchmode)
  3. Deskew und Tight-Crop
  4. Flat-Field, Tonwert-Normierung, S-Kurve, Schärfung

Das JPEG wird mit Qualitätsstufe 90 kodiert. Die Abmessungen ergeben sich aus dem Satzspiegel nach dem Tight-Crop und variieren je nach Dokument.

4.3 page_NNN/page_NNN.txt

Der Flachtext-Transkript der Seite, erzeugt von OCRService. Zeilenumbrüche entsprechen den Absatzgrenzen des RecognizeDocumentsRequest-Ergebnisses.

4.4 page_NNN/page_NNN.ext.xml

DTD-konformes Extended-OCR-XML, erzeugt vom ai-agent-orchestrator (Gemini Batch oder Sync-Ollama). Buchseiten folgen repro_page.dtd, Belege folgen repro_receipt.dtd. Die Datei ist die autoritative Quelle für das formatierte XML im Backstage-Tab.

4.5 page_NNN/page_NNN.receipt.json

Flat-JSON-Contract aller DTD-Attribute aus repro_receipt.dtd (nur Einzelblatt). Enthält dtd_valid, dtd_errors, pidx sowie alle Belegfelder (Händler, Positionen, Steuern, Zahlung, TSE-Daten). Wird von der Mac-App für den Daten-Tab und für ReceiptClassifier verbraucht.

4.6 metadata/page_selection.json

Pagenum-Overrides und Reihenfolge-Korrekturen, die über Rechtsklick → „Seitennum ändern” in der Seitenleiste gesetzt werden. Schreibt nie in die OCR-XML-Dateien. Format:

{
  "page_001": {"pagenum": "23", "override_source": "manual"},
  "page_002": {"pagenum": "24", "override_source": "manual"}
}

4.7 archive/

Archivierte Duplikate nach „Behalten / Archivieren” aus DuplicateSelectionView. Dateien werden hierher verschoben, nie gelöscht.

4.8 ocr_extended.status.json

Gesamtstatus der Extended-OCR für das Dokument:

{
  "status": "done",
  "model": "gemini-3.8-flash",
  "batch_mode": true,
  "pages_total": 34,
  "pages_ok": 34,
  "pages_pending": 0,
  "last_updated": "2026-09-06T14:22:11Z"
}

4.9 page_NNN (Strukturiertes Vision-XML — Legacy)

Strukturiertes XML mit allen erkannten Textblöcken aus Vision-OCR (paragraph, title, list, table, line) mit normierten Bounding-Box-Koordinaten. Diese Datei heißt seit Sep 2026 page_NNN.json-eingebettet; die Separate .xml wurde durch .ext.xml abgelöst.

4.10 page_NNN/page_NNN.json

Das vollständige Seitenprotokoll ist die reichhaltigste Datei des Bündels. Sie enthält alle Messdaten der Verarbeitungskette und ermöglicht es, jede Entscheidung der Pipeline nachzuvollziehen.

page_001.json — vollständiges Seitenprotokoll (Auszug)

{
  "pidx": 1,
  "docTitle": "Dokument_2026-09-03_08-42",
  "timestamp": "2026-09-03T08:42:17Z",
  "masterFile": "masters/master_001.heic",
  "pageImageFile": "page_001/page_001.jpg",
  "width": 2680,
  "height": 3520,
  "side": "left",
  "geometry": {
    "sourceWidth": 8064,
    "sourceHeight": 6048,
    "quad": [[0.10, 0.08], [0.92, 0.06], [0.94, 0.94], [0.08, 0.95]],
    "quadSource": "mac-segmentation",
    "quadConfidence": 0.97,
    "perspectiveApplied": true,
    "rotationDegrees": 90,
    "gutterFraction": 0.502,
    "gutterMethod": "projection-minimum",
    "deskewDegrees": 0.25,
    "textBlockCrop": {"x": 0.04, "y": 0.03, "width": 0.92, "height": 0.94},
    "outputWidth": 2680,
    "outputHeight": 3520
  },
  "tone": {
    "measureRect": {"x": 0.20, "y": 0.20, "width": 0.60, "height": 0.60},
    "inkPoint": 0.042,
    "paperPoint": 0.931,
    "medianLuminance": 0.871,
    "inkTarget": 0.04,
    "paperTarget": 0.96,
    "measured": true,
    "flatFieldApplied": true,
    "enhancerApplied": true,
    "sharpened": true,
    "monochrome": false
  },
  "ocr": {
    "transcript": "Kapitel III\nDie Kausaltheorie\n\nAls Ursache gilt...",
    "engine": "vision-documents",
    "languages": ["de-DE"],
    "meanConfidence": 0.947
  },
  "blocks": [
    {"order": 0, "kind": "title", "text": "Kapitel III",
     "boundingBox": {"x": 0.08, "y": 0.87, "width": 0.30, "height": 0.04}},
    {"order": 2, "kind": "paragraph", "text": "Als Ursache gilt...",
     "boundingBox": {"x": 0.08, "y": 0.72, "width": 0.84, "height": 0.09}}
  ],
  "partitur": {
    "scanIndex": 1,
    "printedPage": "42",
    "runningHead": "Die Kausaltheorie",
    "headings": ["Die Kausaltheorie"],
    "hasFootnotes": true,
    "hasFigureOrTable": false,
    "firstWords": "Als Ursache gilt",
    "language": "de-DE",
    "pageType": "body"
  }
}

Das Feld side gibt an, ob es sich um die linke oder rechte Seite einer Doppelseite handelt ("left", "right" oder null für Einzelblätter). Der pidx-Wert ist der fortlaufende 1-basierte Seitenindex über das gesamte Dokument.

4.11 document.json

Das Dokumentregister enthält die Seitenliste mit pidx, Dateinamen und Zeitstempel. Es wird bei jedem Auslösevorgang aktualisiert.

4.12 partitur.json

Die Partitur-Ergebnisse auf Dokumentebene (Bibliographiedaten, Regest, etc.) — beschrieben in Partitur-Nachbearbeitung.

5 Weiterverarbeitung mit PDAI-Werkzeugen

Das Dokumentbündel ist direkt mit den PDAI-Werkzeugen der lettreai-Plattform kompatibel:

  • ai-scholar: Indexierung und semantische Suche über den Dokumentinhalt
  • ai-viewer: Anzeige des Transkripts mit Faksimile-Synchronisation
  • ai-lemma-index: Aufbau von Lemma-Indizes und Stanza-Korpora

Das Format setzt keine Netzwerkverbindung oder proprietäre Software voraus — alle Dateien sind Standard-JPEG, -JSON, -XML und -TXT.