Extração

Visão geral

NextPDF\Pro\Extraction percorre uma AST de documento analisada e produz blocos de texto e tabela, cada um carregando uma âncora de citação (índice da página, caixa delimitadora, referência do nó). É um extrator estrutural determinístico para pipelines de atribuição de origem, não um mecanismo de busca ou compreensão.

Disponibilidade e licenciamento

Este recurso é distribuído no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem essa titularidade não carrega as classes do recurso. Nenhum sinalizador de capacidade em tempo de execução restringe este módulo; as classes do Extraction estão disponíveis sempre que nextpdf/pro está instalado. Compare edições e obtenha uma licença.

Instalação

composer require nextpdf/pro:^3

Visão conceitual

Ambos os extratores recebem um NextPDF\Ast\AstDocument — uma árvore de documento analisada produzida pelo subsistema AST do Core. Eles não analisam por conta própria bytes brutos do PDF; a AST é o limite de entrada.

• CitedTextExtractor percorre a árvore e emite um CitedTextBlock para cada nó de texto substantivo (parágrafo, título, item de lista, célula de tabela, código, anotação) cujo texto, após o trim, atinja um comprimento mínimo. Um orçamento opcional de tokens divide textos longos em limites de frase. Cada bloco carrega uma CitationAnchor com id do nó, índice da página, caixa delimitadora e uma confiança lida do nó (padrão 1.0). Nós sem caixa delimitadora recebem uma caixa sentinela de área zero, de modo que a âncora seja sempre válida.
• CitedTableExtractor localiza nós Table, lê suas linhas e células, e constrói uma matriz retangular em ordem de linha (row-major) preenchida até a largura da linha mais larga. Tabelas aninhadas não são percorridas recursivamente. A confiança da célula assume o padrão 0.8 a menos que o nó carregue um valor explícito.

A hierarquia estrutural que esses extratores percorrem corresponde ao modelo de estrutura lógica do PDF (ISO 32000-2:2020 §14.7) e aos elementos de estrutura de tabela (§14.8) quando o documento de origem está marcado (tagged).

Por que funciona assim

O extrator recebe uma AST analisada como seu limite de entrada, não bytes brutos do PDF, de modo que o risco de análise permaneça separado da lógica de extração. A confiança é lida diretamente do nó da AST e repassada sem alteração; o módulo nunca a calcula, ranqueia ou melhora. A saída permanece em ordem de documento, não em ordem de relevância, porque a atribuição de origem precisa de proveniência verificável, e não de um palpite heurístico que o extrator não pode defender. Cada bloco carrega uma âncora de citação — id do nó, índice da página, caixa delimitadora — de modo que um pipeline downstream possa rastrear cada citação de volta à sua origem. Isso mantém deliberadamente o módulo como um extrator estrutural determinístico: ele relata o que a AST afirma e se recusa a inventar qualquer coisa que o documento não declare.

Contexto de design: Uma API que se recusa a adivinhar.

Contrato de comportamento

• Entrada. Um NextPDF\Ast\AstDocument. O módulo não aceita bytes brutos do PDF; produza a AST primeiro com o subsistema AST do Core.
• Saída. list<CitedTextBlock> ou list<CitedTableBlock> em ordem de documento.
• A confiança é passthrough. Ela é lida dos atributos do nó da AST (ou de um padrão fixo). Este módulo não calcula nem melhora a confiança.
• Sem processamento semântico. O extrator não realiza nenhuma incorporação, similaridade vetorial, ranqueamento ou compreensão de documentos. A ordenação da saída é a ordem do documento, não a ordem de relevância.
• Determinismo. Para uma AST idêntica, os blocos produzidos, as âncoras e os índices de chunk são estáveis.

Superfície pública da API

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

Exemplo de código — Início rápido

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

Exemplo de código — Produção

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

Casos extremos e armadilhas

• Documentos sem marcação (untagged) ou mal marcados geram menos nós de texto; a qualidade da AST é o limite superior da qualidade da extração.
• Nós sem caixa delimitadora recebem uma caixa sentinela de área zero BoundingBox(0,0,0,0) — detecte-a via width === 0.0 && height === 0.0 se uma região real for necessária.
• Tabelas aninhadas não são percorridas recursivamente; apenas o nó Table mais externo é emitido.
• Linhas curtas são preenchidas com células sintéticas de confiança zero, de modo que toda linha tenha a mesma contagem de colunas.

Residência de dados e mitigações de PII

Este módulo processa qualquer texto que a AST fornecida contenha e o retorna inalterado dentro dos blocos. Ele não realiza chamadas de rede, armazenamento externo nem registro do conteúdo extraído. O tratamento de PII, a redação e os controles de residência são responsabilidade do chamador sobre os blocos produzidos. Consulte a orientação de tratamento de PII do Core.

Telemetria segura e limpeza de logs

O extrator não emite telemetria e não registra o texto extraído. Se um chamador o envolver com logging, limpe text, metadata e qualquer conteúdo de célula antes de emitir logs.

Desempenho

A extração é uma única passagem pela árvore, linear na contagem de nós. A divisão em chunks acrescenta trabalho proporcional ao comprimento do texto. Consulte performance_budget.

Notas de segurança

A entrada é uma AST pré-analisada, então este módulo não analisa por conta própria bytes de PDF hostis. Trate o texto extraído como não confiável e escape-o para seu destino.

Conformidade

Claim	Spec clause	Status
Travessia de nós de estrutura lógica	ISO 32000-2:2020 §14.7	Verificado (conjunto de testes unitários, AST marcada)
Extração de linha/célula de tabela	ISO 32000-2:2020 §14.8	Verificado (conjunto de testes unitários)
Busca semântica / embeddings	—	Não suportado (fora de escopo)

Fallback / alternativa do Core

O subsistema AST do Core produz o AstDocument consumido aqui; não há equivalente no Core para a própria extração de blocos de citação. Consulte /modules/core/ast/.

Nota sobre o limite do Enterprise

Este módulo é apenas um extrator estrutural. Ele não realiza busca semântica, incorporação vetorial, ranqueamento de similaridade ou inteligência de documentos. Essas capacidades não fazem parte deste módulo e não estão implícitas nele.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública de API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de ticket estão fora de escopo.

Veja também

• Referência do Extraction
• Classifier
• Diff
• Core AST