Estrazione

In breve

NextPDF\Pro\Extraction percorre un AST di documento analizzato e produce blocchi di testo e di tabella, ciascuno dotato di un’ancora di citazione (indice di pagina, bounding box, riferimento al nodo). È un estrattore strutturale deterministico per pipeline di attribuzione delle fonti, non un motore di ricerca o di comprensione.

Disponibilità e licenza

Questa funzionalità è distribuita in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Nessun flag di capacità a runtime governa questo modulo; le classi dell’Extraction sono disponibili ogni volta che nextpdf/pro è installato. Confronta le edizioni e ottieni una licenza.

Installazione

composer require nextpdf/pro:^3

Panoramica concettuale

Entrambi gli estrattori prendono un NextPDF\Ast\AstDocument — un albero di documento analizzato prodotto dal sottosistema AST del Core. Non analizzano essi stessi i byte PDF grezzi; l’AST è il confine di input.

• CitedTextExtractor percorre l’albero ed emette un CitedTextBlock per ciascun nodo di testo sostanziale (paragrafo, intestazione, elemento di elenco, cella di tabella, codice, annotazione) il cui testo, una volta rifilato, raggiunge una lunghezza minima. Un budget di token opzionale suddivide il testo lungo ai confini di frase. Ogni blocco è dotato di un CitationAnchor con id del nodo, indice di pagina, bounding box e una confidenza letta dal nodo (default 1.0). I nodi privi di bounding box ricevono un box sentinella ad area zero, così che l’ancora sia sempre valida.
• CitedTableExtractor individua i nodi Table, ne legge righe e celle e costruisce una matrice rettangolare in ordine di riga, riempita fino alla riga più larga. Le tabelle annidate non vengono percorse ricorsivamente. La confidenza delle celle è 0.8 per impostazione predefinita, a meno che il nodo non riporti un valore esplicito.

La gerarchia strutturale percorsa da questi estrattori corrisponde al modello di struttura logica del PDF (ISO 32000-2:2020 §14.7) e agli elementi di struttura delle tabelle (§14.8) quando il documento di origine è dotato di tag.

Perché funziona così

L’estrattore prende un AST già analizzato come proprio confine di input, non i byte PDF grezzi, così il rischio di parsing resta separato dalla logica di estrazione. La confidenza è letta direttamente dal nodo AST e trasmessa invariata; il modulo non la calcola, non la classifica e non la migliora mai. L’output resta in ordine di documento, non in ordine di pertinenza, perché l’attribuzione delle fonti richiede una provenienza verificabile anziché una supposizione euristica che l’estrattore non potrebbe difendere. Ogni blocco è dotato di un’ancora di citazione — id del nodo, indice di pagina, bounding box — così che una pipeline a valle possa ricondurre ogni citazione alla sua origine. Questo mantiene deliberatamente il modulo un estrattore strutturale deterministico: riporta ciò che l’AST asserisce e rifiuta di inventare qualsiasi cosa il documento non affermi.

Contesto di progettazione: Un’API che rifiuta di indovinare.

Contratto di comportamento

• Input. Un NextPDF\Ast\AstDocument. Il modulo non accetta byte PDF grezzi; produrre prima l’AST con il sottosistema AST del Core.
• Output. list<CitedTextBlock> o list<CitedTableBlock> in ordine di documento.
• La confidenza è passthrough. Viene letta dagli attributi del nodo AST (o da un default fisso). Questo modulo non calcola né migliora la confidenza.
• Nessuna elaborazione semantica. L’estrattore non esegue alcun embedding, similarità vettoriale, ranking o comprensione dei documenti. L’ordinamento dell’output è l’ordine di documento, non l’ordine di pertinenza.
• Determinismo. Per un AST identico, i blocchi, le ancore e gli indici di chunk prodotti sono stabili.

Superficie API pubblica

Type	Kind	Key members
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

Esempio di codice — Avvio rapido

<?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,
    );
}

Esempio di codice — Produzione

<?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;
}

Casi limite e insidie

• I documenti privi di tag o con tag di scarsa qualità producono meno nodi di testo; la qualità dell’AST è il limite superiore della qualità dell’estrazione.
• I nodi privi di bounding box ricevono un box sentinella ad area zero BoundingBox(0,0,0,0) — rilevarlo tramite width === 0.0 && height === 0.0 se è richiesta una regione reale.
• Le tabelle annidate non vengono percorse ricorsivamente; viene emesso solo il nodo Table più esterno.
• Le righe brevi vengono riempite con celle sintetiche a confidenza zero, così che ogni riga abbia lo stesso numero di colonne.

Residenza dei dati e mitigazioni delle PII

Questo modulo elabora qualunque testo l’AST fornito contenga e lo restituisce invariato all’interno dei blocchi. Non effettua alcuna chiamata di rete, nessuna memorizzazione esterna e nessun logging del contenuto estratto. La gestione della PII, il mascheramento e i controlli di residenza sono responsabilità del chiamante sui blocchi prodotti. Vedere le linee guida del Core sulla gestione della PII.

Telemetria sicura e pulizia dei log

L’estrattore non emette alcuna telemetria e non registra il testo estratto. Se un chiamante lo avvolge con il logging, sanificare text, metadata e qualunque contenuto delle celle prima di emettere i log.

Prestazioni

L’estrazione è un’unica percorrenza dell’albero, lineare rispetto al numero di nodi. La suddivisione in chunk aggiunge lavoro proporzionale alla lunghezza del testo. Vedere performance_budget.

Note sulla sicurezza

L’input è un AST già analizzato, quindi questo modulo non analizza esso stesso byte PDF ostili. Trattare il testo estratto come non attendibile e sottoporlo a escape per la sua destinazione.

Conformità

Claim	Spec clause	Status
Logical-structure node traversal	ISO 32000-2:2020 §14.7	Verified (unit suite, tagged AST)
Table row/cell extraction	ISO 32000-2:2020 §14.8	Verified (unit suite)
Semantic search / embeddings	—	Not supported (out of scope)

Core fallback / alternativa

Il sottosistema AST del Core produce l’AstDocument consumato qui; non esiste alcun equivalente Core per l’estrazione dei blocchi di citazione vera e propria. Vedere /modules/core/ast/.

Nota sul confine Enterprise

Questo modulo è solo un estrattore strutturale. Non esegue ricerca semantica, embedding vettoriale, ranking di similarità o document intelligence. Tali capacità non fanno parte di questo modulo e non sono implicate da esso.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie pubblica dell’API supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Vedere anche

• Extraction reference
• Classifier
• Diff
• Core AST