Extraction

En bref

NextPDF\Pro\Extraction parcourt un AST de document analysé et produit des blocs de texte et de tableau, chacun portant une ancre de citation (indice de page, boîte englobante, référence de nœud). C’est un extracteur structurel déterministe pour les pipelines d’attribution de source, pas un moteur de recherche ni de compréhension.

Disponibilité et licence

Cette fonctionnalité est livrée 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 fonctionnalité. Aucun indicateur de capacité à l’exécution ne restreint ce module ; les classes Extraction sont disponibles dès que nextpdf/pro est installé. Compare les éditions et obtiens une licence.

Installation

composer require nextpdf/pro:^3

Aperçu conceptuel

Les deux extracteurs prennent un NextPDF\Ast\AstDocument — un arbre de document analysé produit par le sous-système AST de Core. Ils n’analysent pas eux-mêmes les octets PDF bruts ; l’AST est la frontière d’entrée.

• CitedTextExtractor parcourt l’arbre et émet un CitedTextBlock pour chaque nœud de texte substantiel (paragraphe, titre, élément de liste, cellule de tableau, code, annotation) dont le texte rogné atteint une longueur minimale. Un budget de jetons optionnel découpe les longs textes aux frontières de phrase. Chaque bloc porte une CitationAnchor avec l’id de nœud, l’indice de page, la boîte englobante et une confiance lue depuis le nœud (par défaut 1.0). Les nœuds sans boîte englobante reçoivent une boîte sentinelle d’aire nulle, afin que l’ancre soit toujours valide.
• CitedTableExtractor trouve les nœuds Table, lit leurs lignes et cellules, et construit une matrice rectangulaire en ordre ligne par ligne, complétée à la largeur de la ligne la plus large. Les tableaux imbriqués ne font pas l’objet de récursion. La confiance des cellules vaut 0.8 par défaut, sauf si le nœud porte une valeur explicite.

La hiérarchie structurelle que ces extracteurs parcourent correspond au modèle de structure logique du PDF (ISO 32000-2:2020 §14.7) et aux éléments de structure de tableau (§14.8) lorsque le document source est balisé.

Pourquoi ça fonctionne ainsi

L’extracteur prend un AST analysé comme frontière d’entrée, et non des octets PDF bruts, de sorte que le risque lié à l’analyse reste distinct de la logique d’extraction. La confiance est lue directement depuis le nœud de l’AST et transmise telle quelle ; le module ne la calcule, ne la classe ni ne l’améliore jamais. La sortie reste dans l’ordre du document, et non dans l’ordre de pertinence, car l’attribution de source exige une provenance vérifiable plutôt qu’une estimation heuristique que l’extracteur ne pourrait pas défendre. Chaque bloc porte une ancre de citation — id de nœud, indice de page, boîte englobante — afin qu’un pipeline en aval puisse retracer chaque citation jusqu’à son origine. Cela maintient délibérément le module comme un extracteur structurel déterministe : il rapporte ce que l’AST affirme et se refuse à inventer quoi que ce soit que le document n’énonce pas.

Contexte de conception : Une API qui refuse de deviner.

Contrat de comportement

• Entrée. Un NextPDF\Ast\AstDocument. Le module n’accepte pas les octets PDF bruts ; produis d’abord l’AST avec le sous-système AST de Core.
• Sortie. list<CitedTextBlock> ou list<CitedTableBlock> dans l’ordre du document.
• La confiance est transmise telle quelle. Elle est lue depuis les attributs du nœud de l’AST (ou une valeur par défaut fixe). Ce module ne calcule ni n’améliore la confiance.
• Aucun traitement sémantique. L’extracteur n’effectue aucun plongement (embedding), aucune similarité vectorielle, aucun classement ni aucune compréhension de document. L’ordre de sortie est l’ordre du document, pas l’ordre de pertinence.
• Déterminisme. Pour un AST identique, les blocs produits, les ancres et les indices de fragment (chunk) sont stables.

Surface d’API publique

Type	Genre	Membres clés
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

Exemple de code — Démarrage rapide

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

Exemple de code — Production

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

Cas limites et pièges

• Les documents non balisés ou mal balisés produisent moins de nœuds de texte ; la qualité de l’AST est la borne supérieure de la qualité d’extraction.
• Les nœuds sans boîte englobante reçoivent une boîte sentinelle d’aire nulle BoundingBox(0,0,0,0) — détecte-la via width === 0.0 && height === 0.0 si une région réelle est requise.
• Les tableaux imbriqués ne font pas l’objet de récursion ; seul le nœud Table le plus externe est émis.
• Les lignes courtes sont complétées par des cellules synthétiques à confiance nulle, afin que chaque ligne ait le même nombre de colonnes.

Résidence des données et atténuations des données personnelles

Ce module traite le texte que contient l’AST fourni et le renvoie inchangé à l’intérieur des blocs. Il n’effectue aucun appel réseau, aucun stockage externe et aucune journalisation du contenu extrait. La gestion des données personnelles, le caviardage et les contrôles de résidence relèvent de la responsabilité de l’appelant sur les blocs produits. Voir les recommandations de gestion des données personnelles de Core.

Télémétrie sûre et nettoyage des journaux

L’extracteur n’émet aucune télémétrie et ne journalise pas le texte extrait. Si un appelant l’enveloppe de journalisation, nettoie text, metadata et tout contenu de cellule avant d’émettre les journaux.

Performance

L’extraction est un parcours d’arbre unique, linéaire par rapport au nombre de nœuds. Le découpage en fragments ajoute un travail proportionnel à la longueur du texte. Voir performance_budget.

Notes de sécurité

L’entrée est un AST pré-analysé ; ce module n’analyse donc pas lui-même des octets PDF hostiles. Traite le texte extrait comme non fiable et échappe-le pour sa destination.

Conformité

Affirmation	Clause de spécification	Statut
Parcours de nœuds de structure logique	ISO 32000-2:2020 §14.7	Vérifié (suite unitaire, AST balisé)
Extraction de lignes/cellules de tableau	ISO 32000-2:2020 §14.8	Vérifié (suite unitaire)
Recherche sémantique / plongements (embeddings)	—	Non pris en charge (hors périmètre)

Repli / alternative Core

Le sous-système AST de Core produit l’AstDocument consommé ici ; il n’existe aucun équivalent Core pour l’extraction de blocs de citation elle-même. Voir /modules/core/ast/.

Note de frontière Enterprise

Ce module est uniquement un extracteur structurel. Il n’effectue aucune recherche sémantique, aucun plongement vectoriel, aucun classement par similarité ni aucune intelligence documentaire. Ces capacités ne font pas partie de ce module et n’y sont pas sous-entendues.

Frontière 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 d’assistance, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de ticket sont hors périmètre.

Voir aussi

• Référence Extraction
• Classifier
• Diff
• AST de Core