Pro editie

Extraction — Diepe referentie

In een oogopslag

Deze pagina is de referentie op contractniveau voor NextPDF\Pro\Extraction. De module bevat vijf publieke symbolen: twee extractors (CitedTextExtractor, CitedTableExtractor) en drie immutable value objects (CitedTextBlock, CitedTableBlock, CitedTableCell). Beide extractors consumeren een geparseerde NextPDF\Ast\AstDocument; geen van beide leest ruwe PDF-bytes. Extractie is deterministisch en structureel. Er bestaat nergens in deze module een semantische, embedding- of rangschikkingsstap. De taakgerichte weergave staat op de capaciteitspagina.

Beschikbaarheid en licentiëring

Deze capaciteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelop van het Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de capaciteit niet. Vergelijk edities en vraag een licentie aan.

Geen runtime-capaciteitsflag gate’t deze module. De klassen zijn beschikbaar zodra nextpdf/pro is geïnstalleerd en gelicentieerd.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`CitedTextExtractor::__construct()`	`?int $maxTokensPerChunk = null`, `int $minChunkLength = 10`	Geen token-budget; getrimde tekst onder 10 bytes wordt weggegooid	`CitedTextExtractor`	Gooit niet	Een `null`-budget betekent één blok per knoop.
`CitedTextExtractor::extract()`	`AstDocument $document`	Depth-first-wandeling; één blok per kwalificerende tekstknoop, gesplitst door het token-budget	`list<CitedTextBlock>`	Gooit niet	Deterministisch; `chunkIndex` wordt bij elke aanroep teruggezet naar 0.
`CitedTextBlock`	vijf readonly velden	Immutable value object; geen serializer-methode	—	Gooit niet	`metadata`-sleutels: `nodeType`, `pageIndex`, plus optioneel `structType`, `lang`, `alt`, `untagged`.
`CitedTextBlock::estimatedTokens()`	geen	`ceil(byte length / 4)`	`int`	Gooit niet	Budget-heuristiek; geen tokenizer.
`CitedTableExtractor::extract()`	`AstDocument $document`	Verzamelt buitenste `Table`-knopen in documentvolgorde	`list<CitedTableBlock>`	Gooit niet	Daalt nooit af in een tabel-subtree.
`CitedTableBlock`	vijf readonly velden	Immutable rechthoekige row-major celmatrix	—	Gooit niet	Korte rijen worden bij extractie rechts aangevuld.
`CitedTableBlock::toArray()`	geen	Serialiseert naar een snake_case plain array	`array<string, mixed>`	Gooit niet	Geneste cellen serialiseren via `CitedTableCell::toArray()`.
`CitedTableCell`	zeven readonly velden	Immutable cel-record met citaatcoördinaten	—	Gooit niet	Opvulcellen dragen een lege `nodeId` en confidence 0.0.
`CitedTableCell::toArray()`	geen	Serialiseert naar een snake_case plain array; `bbox` nest of is `null`	`array<string, mixed>`	Gooit niet	—

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

Gedragscontract

Knoopselectie. CitedTextExtractor levert blokken op voor knopen waarvan het type Paragraph, Heading, ListItem, TableCell, Code of Annotation is. Een knoop met null-tekst wordt overgeslagen. Een knoop wordt alleen opgeleverd wanneer de getrimde tekstlengte minstens minChunkLength is (standaard 10). Alle lengtes zijn byte-lengtes.
Traversalvolgorde. De wandeling is depth-first vanaf de documentwortel. Een kwalificerende knoop wordt opgeleverd voordat zijn kinderen worden bezocht. chunkIndex loopt op over de hele documentwandeling en wordt bij elke extract()-aanroep teruggezet naar 0.
Chunking. Wanneer maxTokensPerChunk niet is ingesteld, levert elke knoop één blok op. Wanneer ingesteld, wordt tekst die langer is dan maxTokensPerChunk * 4 bytes gesplitst. De splitter geeft de voorkeur aan een zinsgrens — een nieuwe regel, of een punt gevolgd door een spatie — die wordt gevonden door hoogstens 200 bytes achterwaarts te scannen vanaf de voorkeurssnede. Anders breekt hij hard af op het budget. Spaties na een snede worden overgeslagen; lege chunks worden weggegooid.
Citaatanker. De CitationAnchor van elk blok draagt de knoop-id, pagina-index, een bounding box, een confidence en een null content-hash. Knopen zonder bounding box krijgen een gedeelde sentinel met oppervlakte nul, BoundingBox(0, 0, 0, 0), zodat het anker altijd structureel geldig is.
Tekstconfidence. Confidence leest het confidence-attribuut van de knoop wanneer dat een int of float is; de standaard is 1.0. Niet-numerieke attribuutwaarden vallen terug op de standaard.
Blok-metadata. metadata draagt altijd nodeType en pageIndex. structType, lang en alt worden gekopieerd wanneer ze op de knoop aanwezig zijn. untagged wordt op true gezet wanneer de knoop een untagged-attribuut draagt.
Tabelselectie. CitedTableExtractor verzamelt alleen de buitenste Table-knopen, in documentvolgorde. Zodra een Table-knoop is verwerkt, wordt zijn subtree niet opnieuw onderzocht; geneste tabellen worden niet ondersteund.
Matrixvorm. Rijen komen van TableRow-kinderen; cellen komen van hun TableCell-kinderen. Andere kindtypen worden genegeerd. colCount is het maximale aantal cellen over alle rijen. Korte rijen worden rechts aangevuld tot colCount met synthetische cellen: lege nodeId, null-tekst, null-bbox, de pagina-index van de tabel, confidence 0.0. Een tabel zonder rijen of zonder kolommen levert geen blok op.
Celconfidence. De confidence van een echte cel leest zijn confidence-attribuut wanneer dat een int of float is; de standaard is 0.8. Tekstblokken hebben standaard 1.0; tabelcellen hebben standaard 0.8.
Structuurmapping. De doorlopen hiërarchie wordt gemapt op het logische-structuurmodel van PDF (ISO 32000-2:2020 §14.7). Tabelrijen worden gemapt op het TR-structuurelement (§14.8) wanneer de bron is getagd.

Randgevallen en foutmodi

Niets op dit oppervlak gooit. Beide extract()-methoden retourneren een lege lijst voor een document zonder kwalificerende knopen.
De bounding box met oppervlakte nul is een gedeelde singleton-sentinel. Callers die een echte regio nodig hebben, moeten deze expliciet detecteren: width === 0.0 && height === 0.0.
Alle lengtecontroles en splitsingen zijn byte-gebaseerd. Wanneer er binnen het venster van 200 bytes geen zinsgrens bestaat, kan een harde breuk binnen een multibyte-UTF-8-sequentie vallen.
Het cijfer van 4 bytes per token is alleen een budgetteringsheuristiek. Het is geen tokenizer en komt niet overeen met de tokenisatie van een specifiek model. estimatedTokens() gebruikt dezelfde heuristiek.
Een numerieke string in een confidence-attribuut wordt niet omgezet; de standaard is van toepassing. Alleen int- en float-waarden worden gehonoreerd.
Het overslaan van witruimte na een snede verwijdert alleen gewone spaties. Tabs en nieuwe regels aan het begin van een chunk blijven behouden.
TableCell-tekst wordt met opzet tweemaal geëxtraheerd: als tekstblokken door CitedTextExtractor, en binnen matrices door CitedTableExtractor. Dedupliceer stroomafwaarts wanneer je beide extractors over één document draait.
Opvulcellen zijn herkenbaar aan een lege nodeId en confidence 0.0. Een echte maar lege cel behoudt zijn niet-lege nodeId.
In deze module vindt geen cryptografische bewerking plaats, dus er is geen FIPS-modusspecifiek gedrag.

Conformiteit

Wanneer het brondocument is getagd, weerspiegelt de AST de logische-structuurhiërarchie van ISO 32000-2:2020 §14.7, en komen Table/TableRow-knopen overeen met de §14.8-Table/TR-structuurelementen. De extractiekwaliteit wordt begrensd door de tagging-kwaliteit; ongetagde inhoud levert minder of grovere knopen op.

Dit zijn uitspraken over structurele afstemming, geen resultaten van conformiteitstests. NextPDF bezit geen certificering en verleent er geen. Deze module doet geen eigen conformiteitsclaim; het consumeert welke structuur het Core-AST-subsysteem ook heeft geproduceerd.

Ontwikkelnotities

Het hergebruiken van één CitedTextExtractor-instance over documenten is sequentieel veilig; extract() zet chunkIndex terug vóór elke wandeling.
Stem minChunkLength af om ruisknopen (paginanummers, losse glyph-reeksen) vóór het chunken te filteren, niet erna.
Voor CJK en andere multibyte-schriften telt de byte-gebaseerde heuristiek te veel tokens; dimensioneer maxTokensPerChunk dienovereenkomstig.
CitedTableBlock::toArray() en CitedTableCell::toArray() leveren snake_case-sleutels op voor JSON-pipelines. CitedTextBlock heeft geen serializer; codeer de velden zelf.
Het contentHash-veld van CitationAnchor is op dit oppervlak altijd null. Bereken content-hashes stroomafwaarts wanneer de pipeline ze nodig heeft.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-klassen, mechanismetabellen, runbook-bestandsnamen en ticket-prefixes vallen buiten de scope.