Pro édition

Extraction — Référence approfondie

En bref

Cette page est la référence de niveau contractuel pour NextPDF\Pro\Extraction. Le module contient cinq symboles publics : deux extracteurs (CitedTextExtractor, CitedTableExtractor) et trois objets-valeurs immuables (CitedTextBlock, CitedTableBlock, CitedTableCell). Les deux extracteurs consomment un NextPDF\Ast\AstDocument analysé ; aucun ne lit les octets bruts du PDF. L’extraction est déterministe et structurelle. Aucune étape sémantique, d’embedding ou de classement n’existe où que ce soit dans ce module. La vue orientée tâches se trouve sur la page de capacité.

Disponibilité et licence

Cette capacité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de ce droit ne charge pas les classes de la capacité. Compare les éditions et obtiens une licence.

Aucun indicateur de capacité à l’exécution ne conditionne ce module. Les classes sont disponibles dès que nextpdf/pro est installé et sous licence.

Surface d’API publique

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
`CitedTextExtractor::__construct()`	`?int $maxTokensPerChunk = null`, `int $minChunkLength = 10`	Aucun budget de jetons ; le texte élagué de moins de 10 octets est abandonné	`CitedTextExtractor`	Ne lève pas	Un budget `null` signifie un bloc par nœud.
`CitedTextExtractor::extract()`	`AstDocument $document`	Parcours en profondeur d’abord ; un bloc par nœud de texte admissible, découpé selon le budget de jetons	`list<CitedTextBlock>`	Ne lève pas	Déterministe ; `chunkIndex` est remis à 0 à chaque appel.
`CitedTextBlock`	cinq champs readonly	Objet-valeur immuable ; aucune méthode de sérialisation	—	Ne lève pas	Clés de `metadata` : `nodeType`, `pageIndex`, plus les optionnelles `structType`, `lang`, `alt`, `untagged`.
`CitedTextBlock::estimatedTokens()`	aucun	`ceil(byte length / 4)`	`int`	Ne lève pas	Heuristique de budget ; pas un tokeniseur.
`CitedTableExtractor::extract()`	`AstDocument $document`	Collecte les nœuds `Table` les plus externes dans l’ordre du document	`list<CitedTableBlock>`	Ne lève pas	Ne descend jamais dans un sous-arbre de tableau.
`CitedTableBlock`	cinq champs readonly	Matrice de cellules immuable, rectangulaire, en ordre ligne par ligne	—	Ne lève pas	Les lignes courtes sont complétées à droite au moment de l’extraction.
`CitedTableBlock::toArray()`	aucun	Sérialise vers un tableau simple en snake_case	`array<string, mixed>`	Ne lève pas	Les cellules imbriquées se sérialisent via `CitedTableCell::toArray()`.
`CitedTableCell`	sept champs readonly	Enregistrement de cellule immuable avec coordonnées de citation	—	Ne lève pas	Les cellules de remplissage portent un `nodeId` vide et une confiance de 0.0.
`CitedTableCell::toArray()`	aucun	Sérialise vers un tableau simple en snake_case ; `bbox` s’imbrique ou vaut `null`	`array<string, mixed>`	Ne lève pas	—

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

Contrat de comportement

Sélection des nœuds. CitedTextExtractor émet des blocs pour les nœuds dont le type est Paragraph, Heading, ListItem, TableCell, Code ou Annotation. Un nœud dont le texte est null est ignoré. Un nœud n’est émis que lorsque la longueur de son texte élagué atteint au moins minChunkLength (10 par défaut). Toutes les longueurs sont des longueurs en octets.
Ordre de parcours. Le parcours se fait en profondeur d’abord depuis la racine du document. Un nœud admissible est émis avant que ses enfants ne soient visités. chunkIndex s’incrémente sur l’ensemble du parcours du document et est remis à 0 à chaque appel d’extract().
Découpage. Lorsque maxTokensPerChunk n’est pas défini, chaque nœud produit un bloc. Lorsqu’il est défini, tout texte plus long que maxTokensPerChunk * 4 octets est découpé. Le découpeur privilégie une frontière de phrase — un saut de ligne, ou un point suivi d’une espace — trouvée en balayant vers l’arrière sur 200 octets au plus depuis la coupe souhaitée. Sinon, il effectue une coupure forcée au niveau du budget. Les espaces après une coupe sont ignorés ; les fragments vides sont abandonnés.
Ancre de citation. Le CitationAnchor de chaque bloc porte l’identifiant du nœud, l’index de page, une boîte englobante, une confiance et un hachage de contenu null. Les nœuds sans boîte englobante reçoivent une sentinelle partagée d’aire nulle, BoundingBox(0, 0, 0, 0), de sorte que l’ancre est toujours structurellement valide.
Confiance du texte. La confiance lit l’attribut confidence du nœud lorsqu’il s’agit d’un int ou d’un float ; la valeur par défaut est 1.0. Les valeurs d’attribut non numériques retombent sur la valeur par défaut.
Métadonnées de bloc. metadata porte toujours nodeType et pageIndex. structType, lang et alt sont copiés lorsqu’ils sont présents sur le nœud. untagged est mis à true lorsque le nœud porte un attribut untagged.
Sélection des tableaux. CitedTableExtractor ne collecte que les nœuds Table les plus externes, dans l’ordre du document. Une fois qu’un nœud Table est traité, son sous-arbre n’est pas réexaminé ; les tableaux imbriqués ne sont pas pris en charge.
Forme de la matrice. Les lignes proviennent des enfants TableRow ; les cellules proviennent de leurs enfants TableCell. Les autres types d’enfants sont ignorés. colCount est le nombre maximal de cellules parmi toutes les lignes. Les lignes courtes sont complétées à droite jusqu’à colCount avec des cellules synthétiques : nodeId vide, texte null, bbox null, l’index de page du tableau, confiance de 0.0. Un tableau sans ligne ou sans colonne ne produit aucun bloc.
Confiance des cellules. La confiance d’une cellule réelle lit son attribut confidence lorsqu’il s’agit d’un int ou d’un float ; la valeur par défaut est 0.8. Les blocs de texte ont pour valeur par défaut 1.0 ; les cellules de tableau ont pour valeur par défaut 0.8.
Correspondance de structure. La hiérarchie parcourue correspond au modèle de structure logique du PDF (ISO 32000-2:2020 §14.7). Les lignes de tableau correspondent à l’élément de structure TR (§14.8) lorsque la source est balisée.

Cas limites et modes de défaillance

Rien sur cette surface ne lève d’exception. Les deux méthodes extract() renvoient une liste vide pour un document sans nœud admissible.
La boîte englobante d’aire nulle est une sentinelle singleton partagée. Les appelants qui ont besoin d’une région réelle doivent la détecter explicitement : width === 0.0 && height === 0.0.
Toutes les vérifications de longueur et les découpes sont basées sur les octets. Lorsqu’aucune frontière de phrase n’existe dans la fenêtre de 200 octets, une coupure forcée peut tomber à l’intérieur d’une séquence UTF-8 multi-octets.
Le chiffre de 4 octets par jeton n’est qu’une heuristique de budgétisation. Ce n’est pas un tokeniseur et il ne correspond à la tokenisation d’aucun modèle particulier. estimatedTokens() utilise la même heuristique.
Une chaîne numérique dans un attribut confidence n’est pas convertie ; la valeur par défaut s’applique. Seules les valeurs int et float sont prises en compte.
L’omission des espaces après une coupe ne supprime que les espaces simples. Les tabulations et les sauts de ligne en début de fragment sont préservés.
Le texte des TableCell est extrait deux fois à dessein : sous forme de blocs de texte par CitedTextExtractor, et à l’intérieur des matrices par CitedTableExtractor. Déduplique en aval lorsque tu exécutes les deux extracteurs sur un même document.
Les cellules de remplissage sont identifiables par un nodeId vide et une confiance de 0.0. Une cellule réelle mais vide conserve son nodeId non vide.
Aucune opération cryptographique n’a lieu dans ce module, il n’y a donc aucun comportement spécifique au mode FIPS.

Conformité

Lorsque le document source est balisé, l’AST reflète la hiérarchie de structure logique de l’ISO 32000-2:2020 §14.7, et les nœuds Table/TableRow correspondent aux éléments de structure Table/TR du §14.8. La qualité de l’extraction est bornée par la qualité du balisage ; un contenu non balisé produit des nœuds moins nombreux ou plus grossiers.

Ce sont des affirmations d’alignement structurel, non des résultats de tests de conformité. NextPDF ne détient aucune certification et n’en accorde aucune. Ce module ne formule aucune revendication de conformité propre ; il consomme la structure produite par le sous-système Core AST, quelle qu’elle soit.

Notes de développement

Réutiliser une même instance de CitedTextExtractor sur plusieurs documents est sûr en séquentiel ; extract() remet chunkIndex à zéro avant chaque parcours.
Ajuste minChunkLength pour filtrer les nœuds parasites (numéros de page, suites de glyphes isolées) avant le découpage, pas après.
Pour le CJC et les autres écritures multi-octets, l’heuristique basée sur les octets surcompte les jetons ; dimensionne maxTokensPerChunk en conséquence.
CitedTableBlock::toArray() et CitedTableCell::toArray() émettent des clés en snake_case pour les pipelines JSON. CitedTextBlock n’a pas de sérialiseur ; encode ses champs toi-même.
Le champ contentHash de CitationAnchor est toujours null sur cette surface. Calcule les hachages de contenu en aval lorsque le pipeline en a besoin.

Limite de publication

Cette page ne documente que le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins de namespace internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.