Extractie

In het kort

NextPDF\Pro\Extraction doorloopt een geparseerde document-AST en produceert tekst- en tabelblokken, elk met een citatieanker (paginaindex, bounding box, nodeverwijzing). Het is een deterministische structurele extractor voor bron- attributiepijplijnen, geen zoek- of begripsengine.

Beschikbaarheid en licentie

Deze mogelijkheid wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelop van het Pro-niveau. Een implementatie zonder die rechten laadt de klassen van de mogelijkheid niet. Geen runtime- mogelijkheidsvlag bewaakt deze module; de Extraction-klassen zijn beschikbaar zodra nextpdf/pro is geïnstalleerd. Vergelijk edities en vraag een licentie aan.

Installatie

composer require nextpdf/pro:^3

Conceptueel overzicht

Beide extractors nemen een NextPDF\Ast\AstDocument — een geparseerde documentboom geproduceerd door het Core-AST-subsysteem. Ze parseren zelf geen ruwe PDF-bytes; de AST is de invoergrens.

• CitedTextExtractor doorloopt de boom en zendt een CitedTextBlock uit voor elke substantiële tekstnode (alinea, kop, lijstitem, tabelcel, code, annotatie) waarvan de getrimde tekst een minimumlengte haalt. Een optioneel tokenbudget splitst lange tekst op zinsgrenzen. Elk blok bevat een CitationAnchor met node-id, paginaindex, bounding box en een betrouwbaarheid die uit de node wordt gelezen (standaard 1.0). Nodes zonder bounding box krijgen een sentinel-vak met nul-oppervlak zodat het anker altijd geldig is.
• CitedTableExtractor vindt Table-nodes, leest de rijen en cellen ervan, en bouwt een rechthoekige rij-major-matrix die wordt aangevuld tot de breedste rij. Geneste tabellen worden niet recursief doorlopen. De celbetrouwbaarheid valt standaard terug op 0.8 tenzij de node een expliciete waarde draagt.

De structurele hiërarchie die deze extractors doorlopen, komt overeen met het PDF- logische-structuurmodel (ISO 32000-2:2020 §14.7) en de tabelstructuur- elementen (§14.8) wanneer het brondocument is getagd.

Waarom het zo werkt

De extractor neemt een geparseerde AST als invoergrens, niet ruwe PDF-bytes, zodat parseerrisico gescheiden blijft van extractielogica. Betrouwbaarheid wordt rechtstreeks uit de AST-node gelezen en ongewijzigd doorgegeven; de module berekent, rangschikt of verbetert deze nooit. De uitvoer blijft in documentvolgorde, niet in relevantievolgorde, omdat bronattributie verifieerbare herkomst nodig heeft in plaats van een heuristische gok die de extractor niet kan verdedigen. Elk blok bevat een citatieanker — node- id, paginaindex, bounding box — zodat een downstreampijplijn elk citaat kan herleiden tot zijn oorsprong. Dit houdt de module bewust een deterministische structurele extractor: hij rapporteert wat de AST beweert en weigert iets te verzinnen dat het document niet vermeldt.

Ontwerpachtergrond: Een API die weigert te gokken.

Gedragscontract

• Invoer. Een NextPDF\Ast\AstDocument. De module accepteert geen ruwe PDF- bytes; produceer eerst de AST met het Core-AST-subsysteem.
• Uitvoer. list<CitedTextBlock> of list<CitedTableBlock> in document- volgorde.
• Betrouwbaarheid is passthrough. Deze wordt gelezen uit de AST-node-attributen (of een vaste standaard). Deze module berekent of verbetert de betrouwbaarheid niet.
• Geen semantische verwerking. De extractor voert geen embedding, vector- gelijkenis, rangschikking of documentbegrip uit. De uitvoervolgorde is document- volgorde, geen relevantievolgorde.
• Determinisme. Voor een identieke AST zijn de geproduceerde blokken, ankers en chunkindices stabiel.

Publiek API-oppervlak

Type	Soort	Belangrijkste leden
NextPDF\Pro\Extraction\CitedTextExtractor	final class	__construct(?int $maxTokensPerChunk = null, int $minChunkLength = 10), extract(AstDocument $document): list<CitedTextBlock>
NextPDF\Pro\Extraction\CitedTableExtractor	final class	extract(AstDocument $document): list<CitedTableBlock>
NextPDF\Pro\Extraction\CitedTextBlock	final readonly class	string $text, CitationAnchor $anchor, float $confidence, int $chunkIndex, array $metadata, estimatedTokens(): int
NextPDF\Pro\Extraction\CitedTableBlock	final readonly class	string $nodeId, int $pageIndex, int $rowCount, int $colCount, array $matrix
NextPDF\Pro\Extraction\CitedTableCell	final readonly class	int $row, int $col, ?string $textContent, float $confidence

Codevoorbeeld — Snelstart

<?php

declare(strict_types=1);

use NextPDF\Pro\Extraction\CitedTextExtractor;

/** @var \NextPDF\Ast\AstDocument $ast */
$blocks = (new CitedTextExtractor())->extract($ast);

foreach ($blocks as $block) {
    printf(
        "p%d chunk#%d (%d tokens): %s\n",
        $block->anchor->pageIndex,
        $block->chunkIndex,
        $block->estimatedTokens(),
        $block->text,
    );
}

Codevoorbeeld — Productie

<?php

declare(strict_types=1);

use NextPDF\Pro\Extraction\CitedTextExtractor;

function chunkForCitation(\NextPDF\Ast\AstDocument $ast): array
{
    // Token-bounded chunks for downstream citation storage.
    $extractor = new CitedTextExtractor(
        maxTokensPerChunk: 400,
        minChunkLength: 16,
    );

    $rows = [];
    foreach ($extractor->extract($ast) as $block) {
        $rows[] = [
            'text'      => $block->text,
            'page'      => $block->anchor->pageIndex,
            'node_id'   => $block->anchor->nodeId,
            'chunk'     => $block->chunkIndex,
        ];
    }

    return $rows;
}

Randgevallen en valkuilen

• Niet-getagde of slecht getagde documenten leveren minder tekstnodes op; de AST-kwaliteit is de bovengrens van de extractiekwaliteit.
• Nodes zonder bounding box krijgen een sentinel-BoundingBox(0,0,0,0) met nul-oppervlak — detecteer het via width === 0.0 && height === 0.0 als een echte regio vereist is.
• Geneste tabellen worden niet recursief doorlopen; alleen de buitenste Table-node wordt uitgezonden.
• Korte rijen worden aangevuld met synthetische cellen met nul-betrouwbaarheid zodat elke rij hetzelfde aantal kolommen heeft.

Datalocatie en PII-mitigaties

Deze module verwerkt alle tekst die de aangeleverde AST bevat en retourneert deze onveranderd binnen blokken. Deze doet geen netwerkoproepen, geen externe opslag en geen logging van geëxtraheerde inhoud. PII-verwerking, redactie en locatie- controles zijn de verantwoordelijkheid van de caller op de geproduceerde blokken. Zie de Core- richtlijn voor PII-verwerking.

Veilige telemetrie en logopschoning

De extractor zendt geen telemetrie uit en logt geen geëxtraheerde tekst. Als een caller deze met logging omwikkelt, schoon dan text, metadata en alle celinhoud op voordat je logs uitzendt.

Prestaties

Extractie is één enkele boomdoorloop, lineair in het aantal nodes. Chunk-splitsing voegt werk toe dat evenredig is met de tekstlengte. Zie performance_budget.

Beveiligingsnotities

De invoer is een vooraf geparseerde AST, dus deze module parseert zelf geen vijandige PDF-bytes. Behandel geëxtraheerde tekst als niet-vertrouwd en escape deze voor de bestemming.

Conformiteit

Claim	Spec-clausule	Status
Doorlopen van logische-structuurnodes	ISO 32000-2:2020 §14.7	Geverifieerd (unit suite, getagde AST)
Tabelrij-/celextractie	ISO 32000-2:2020 §14.8	Geverifieerd (unit suite)
Semantisch zoeken / embeddings	—	Niet ondersteund (buiten bereik)

Core-fallback / alternatief

Het Core-AST-subsysteem produceert de AstDocument die hier wordt verbruikt; er is geen Core-equivalent voor de citatieblokextractie zelf. Zie /modules/core/ast/.

Enterprise-grensnotitie

Deze module is alleen een structurele extractor. Deze voert geen semantisch zoeken, vectorembedding, gelijkenisrangschikking of document intelligence uit. Die mogelijkheden maken geen deel uit van deze module en worden er niet door geïmpliceerd.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten bereik.

Zie ook

• Extractie-referentie
• Classifier
• Diff
• Core AST