Pro Edition

Extraktion — Tiefenreferenz

Auf einen Blick

Diese Seite ist die Referenz auf Vertragsebene für NextPDF\Pro\Extraction. Das Modul enthält fünf öffentliche Symbole: zwei Extraktoren (CitedTextExtractor, CitedTableExtractor) und drei unveränderliche Wertobjekte (CitedTextBlock, CitedTableBlock, CitedTableCell). Beide Extraktoren verarbeiten ein geparstes NextPDF\Ast\AstDocument; keiner liest rohe PDF-Bytes. Die Extraktion ist deterministisch und strukturell. Es gibt an keiner Stelle in diesem Modul einen semantischen Schritt, einen Embedding-Schritt oder einen Ranking-Schritt. Die aufgabenorientierte Sicht finden Sie auf der Fähigkeitsseite.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit ist Teil von NextPDF Pro (nextpdf/pro) und wird mit einem License-Envelope der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und eine Lizenz erwerben.

Kein Laufzeit-Capability-Flag schützt dieses Modul. Die Klassen sind immer dann verfügbar, wenn nextpdf/pro installiert und lizenziert ist.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`CitedTextExtractor::__construct()`	`?int $maxTokensPerChunk = null`, `int $minChunkLength = 10`	Kein Token-Budget; getrimmter Text unter 10 Bytes wird verworfen	`CitedTextExtractor`	Wirft nicht	Ein `null`-Budget bedeutet einen Block pro Knoten.
`CitedTextExtractor::extract()`	`AstDocument $document`	Tiefensuche; ein Block pro qualifizierendem Textknoten, aufgeteilt nach dem Token-Budget	`list<CitedTextBlock>`	Wirft nicht	Deterministisch; `chunkIndex` wird bei jedem Aufruf auf 0 zurückgesetzt.
`CitedTextBlock`	fünf readonly-Felder	Unveränderliches Wertobjekt; keine Serializer-Methode	—	Wirft nicht	`metadata`-Schlüssel: `nodeType`, `pageIndex`, plus optional `structType`, `lang`, `alt`, `untagged`.
`CitedTextBlock::estimatedTokens()`	keine	`ceil(byte length / 4)`	`int`	Wirft nicht	Budget-Heuristik; kein Tokenizer.
`CitedTableExtractor::extract()`	`AstDocument $document`	Sammelt die äußersten `Table`-Knoten in Dokumentreihenfolge	`list<CitedTableBlock>`	Wirft nicht	Steigt niemals in einen Tabellen-Teilbaum hinab.
`CitedTableBlock`	fünf readonly-Felder	Unveränderliche rechteckige zeilenweise Zellenmatrix	—	Wirft nicht	Kurze Zeilen werden zur Extraktionszeit rechts aufgefüllt.
`CitedTableBlock::toArray()`	keine	Serialisiert in ein einfaches snake_case-Array	`array<string, mixed>`	Wirft nicht	Verschachtelte Zellen werden über `CitedTableCell::toArray()` serialisiert.
`CitedTableCell`	sieben readonly-Felder	Unveränderlicher Zellendatensatz mit Zitatkoordinaten	—	Wirft nicht	Auffüllzellen tragen eine leere `nodeId` und Konfidenz 0.0.
`CitedTableCell::toArray()`	keine	Serialisiert in ein einfaches snake_case-Array; `bbox` verschachtelt oder ist `null`	`array<string, mixed>`	Wirft nicht	—

final class CitedTextExtractor

public function __construct(
    private readonly ?int $maxTokensPerChunk = null,
    private readonly int $minChunkLength = 10,
)

public function extract(AstDocument $document): array

final class CitedTableExtractor

public function extract(AstDocument $document): array

final readonly class CitedTextBlock

public function __construct(
    public string $text,
    public CitationAnchor $anchor,
    public float $confidence,
    public int $chunkIndex,
    public array $metadata,
)

public function estimatedTokens(): int

final readonly class CitedTableBlock

public function __construct(
    public readonly string $nodeId,
    public readonly int    $pageIndex,
    public readonly int    $rowCount,
    public readonly int    $colCount,
    public readonly array  $matrix,
)

public function toArray(): array

final readonly class CitedTableCell

public function __construct(
    public readonly string       $nodeId,
    public readonly int          $row,
    public readonly int          $col,
    public readonly ?string      $textContent,
    public readonly ?BoundingBox $bbox,
    public readonly int          $pageIndex,
    public readonly float        $confidence,
)

public function toArray(): array

Verhaltensvertrag

Knotenauswahl. CitedTextExtractor gibt Blöcke für Knoten aus, deren Typ Paragraph, Heading, ListItem, TableCell, Code oder Annotation ist. Ein Knoten mit null-Text wird übersprungen. Ein Knoten wird nur dann ausgegeben, wenn seine getrimmte Textlänge mindestens minChunkLength (Standard 10) beträgt. Alle Längen sind Byte-Längen.
Traversierungsreihenfolge. Der Durchlauf erfolgt als Tiefensuche von der Dokumentwurzel aus. Ein qualifizierender Knoten wird ausgegeben, bevor seine Kinder besucht werden. chunkIndex erhöht sich über den gesamten Dokumentdurchlauf und wird bei jedem extract()-Aufruf auf 0 zurückgesetzt.
Chunking. Ohne gesetztes maxTokensPerChunk liefert jeder Knoten einen Block. Wenn gesetzt, wird Text, der länger als maxTokensPerChunk * 4 Bytes ist, aufgeteilt. Der Splitter bevorzugt eine Satzgrenze – einen Zeilenumbruch oder einen Punkt gefolgt von einem Leerzeichen –, die durch Rückwärtssuche von höchstens 200 Bytes vor dem bevorzugten Schnitt gefunden wird. Andernfalls bricht er hart am Budget um. Leerzeichen nach einem Schnitt werden übersprungen; leere Chunks werden verworfen.
Zitat-Anker. Der CitationAnchor jedes Blocks trägt die Knoten-ID, den Seitenindex, eine Bounding-Box, eine Konfidenz und einen null-Inhaltshash. Knoten ohne Bounding-Box erhalten einen gemeinsamen Sentinel mit Nullfläche, BoundingBox(0, 0, 0, 0), sodass der Anker immer strukturell gültig ist.
Textkonfidenz. Die Konfidenz liest das confidence-Attribut des Knotens, wenn es ein int oder float ist; der Standard ist 1.0. Nicht-numerische Attributwerte fallen auf den Standard zurück.
Block-Metadaten. metadata trägt immer nodeType und pageIndex. structType, lang und alt werden kopiert, wenn sie am Knoten vorhanden sind. untagged wird auf true gesetzt, wenn der Knoten ein untagged-Attribut trägt.
Tabellenauswahl. CitedTableExtractor sammelt nur die äußersten Table-Knoten in Dokumentreihenfolge. Sobald ein Table-Knoten verarbeitet wurde, wird sein Teilbaum nicht erneut untersucht; verschachtelte Tabellen werden nicht unterstützt.
Matrixform. Zeilen stammen aus TableRow-Kindern; Zellen stammen aus deren TableCell-Kindern. Andere Kindtypen werden ignoriert. colCount ist die maximale Zellenanzahl über alle Zeilen. Kurze Zeilen werden mit synthetischen Zellen auf colCount rechts aufgefüllt: leere nodeId, null-Text, null-bbox, der Seitenindex der Tabelle, Konfidenz 0.0. Eine Tabelle ohne Zeilen oder ohne Spalten liefert keinen Block.
Zellenkonfidenz. Die Konfidenz einer echten Zelle liest ihr confidence-Attribut, wenn es ein int oder float ist; der Standard ist 0.8. Textblöcke haben den Standard 1.0; Tabellenzellen haben den Standard 0.8.
Strukturzuordnung. Die durchlaufene Hierarchie wird auf das logische Strukturmodell von PDF abgebildet (ISO 32000-2:2020 §14.7). Tabellenzeilen werden auf das TR-Strukturelement (§14.8) abgebildet, wenn die Quelle getaggt ist.

Grenzfälle & Fehlermodi

Nichts auf dieser Oberfläche wirft. Beide extract()-Methoden geben für ein Dokument ohne qualifizierende Knoten eine leere Liste zurück.
Die Bounding-Box mit Nullfläche ist ein gemeinsamer Singleton-Sentinel. Aufrufer, die eine echte Region benötigen, müssen ihn explizit erkennen: width === 0.0 && height === 0.0.
Alle Längenprüfungen und Aufteilungen sind byte-basiert. Wenn innerhalb des 200-Byte-Fensters keine Satzgrenze existiert, kann ein harter Umbruch innerhalb einer Mehrbyte-UTF-8-Sequenz liegen.
Der Wert von 4 Bytes pro Token ist lediglich eine Budgetierungs-Heuristik. Es ist kein Tokenizer und stimmt mit der Tokenisierung keines bestimmten Modells überein. estimatedTokens() verwendet dieselbe Heuristik.
Eine numerische Zeichenkette in einem confidence-Attribut wird nicht umgewandelt; es gilt der Standard. Nur int- und float-Werte werden berücksichtigt.
Das Überspringen von Leerraum nach einem Schnitt entfernt nur einfache Leerzeichen. Tabulatoren und Zeilenumbrüche am Chunk-Anfang bleiben erhalten.
TableCell-Text wird per Design zweimal extrahiert: als Textblöcke durch CitedTextExtractor und innerhalb von Matrizen durch CitedTableExtractor. Deduplizieren Sie nachgelagert, wenn Sie beide Extraktoren über ein Dokument laufen lassen.
Auffüllzellen sind an einer leeren nodeId und Konfidenz 0.0 erkennbar. Eine echte, aber leere Zelle behält ihre nicht-leere nodeId.
In diesem Modul findet keine kryptografische Operation statt, daher gibt es kein FIPS-Modus-spezifisches Verhalten.

Konformität

Wenn das Quelldokument getaggt ist, spiegelt das AST die logische Strukturhierarchie von ISO 32000-2:2020 §14.7 wider, und Table/TableRow-Knoten entsprechen den Table/TR-Strukturelementen aus §14.8. Die Extraktionsqualität ist durch die Tagging-Qualität begrenzt; ungetaggter Inhalt erzeugt weniger oder gröbere Knoten.

Dies sind Aussagen zur strukturellen Ausrichtung, keine Ergebnisse von Konformitätstests. NextPDF besitzt keine Zertifizierung und gewährt keine. Dieses Modul erhebt keinen eigenen Konformitätsanspruch; es verarbeitet die Struktur, die das Core-AST-Subsystem erzeugt hat.

Entwicklungshinweise

Die Wiederverwendung einer CitedTextExtractor-Instanz über mehrere Dokumente hinweg ist sequenziell sicher; extract() setzt chunkIndex vor jedem Durchlauf zurück.
Stellen Sie minChunkLength so ein, dass Störknoten (Seitenzahlen, versprengte Glyphenfolgen) vor dem Chunking gefiltert werden, nicht danach.
Bei CJK und anderen Mehrbyte-Schriften überzählt die byte-basierte Heuristik Tokens; dimensionieren Sie maxTokensPerChunk entsprechend.
CitedTableBlock::toArray() und CitedTableCell::toArray() geben snake_case-Schlüssel für JSON-Pipelines aus. CitedTextBlock hat keinen Serializer; kodieren Sie seine Felder selbst.
Das contentHash-Feld von CitationAnchor ist auf dieser Oberfläche immer null. Berechnen Sie Inhaltshashes nachgelagert, wenn die Pipeline sie benötigt.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.