Pro edição

Extraction — Referência Profunda

Visão geral

Esta página é a referência em nível de contrato para NextPDF\Pro\Extraction. O módulo contém cinco símbolos públicos: dois extratores (CitedTextExtractor, CitedTableExtractor) e três value objects imutáveis (CitedTextBlock, CitedTableBlock, CitedTableCell). Ambos os extratores consomem um NextPDF\Ast\AstDocument já parseado; nenhum deles lê bytes brutos de PDF. A extração é determinística e estrutural. Não existe nenhuma etapa semântica, de embedding ou de ranqueamento em lugar algum deste módulo. A visão orientada a tarefas fica na página de capacidade.

Disponibilidade & licenciamento

Esta capacidade é entregue no NextPDF Pro (nextpdf/pro) e é ativada com um envelope de licença do nível Pro. Uma implantação sem esse direito de uso não carrega as classes da capacidade. Compare edições e obtenha uma licença.

Nenhum flag de capacidade em tempo de execução restringe este módulo. As classes ficam disponíveis sempre que nextpdf/pro está instalado e licenciado.

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
`CitedTextExtractor::__construct()`	`?int $maxTokensPerChunk = null`, `int $minChunkLength = 10`	Sem orçamento de tokens; texto aparado com menos de 10 bytes é descartado	`CitedTextExtractor`	Não lança	Um orçamento `null` significa um bloco por nó.
`CitedTextExtractor::extract()`	`AstDocument $document`	Percurso em profundidade; um bloco por nó de texto qualificado, dividido pelo orçamento de tokens	`list<CitedTextBlock>`	Não lança	Determinístico; `chunkIndex` volta a 0 a cada chamada.
`CitedTextBlock`	cinco campos readonly	Value object imutável; sem método serializador	—	Não lança	Chaves de `metadata`: `nodeType`, `pageIndex`, mais os opcionais `structType`, `lang`, `alt`, `untagged`.
`CitedTextBlock::estimatedTokens()`	nenhum	`ceil(byte length / 4)`	`int`	Não lança	Heurística de orçamento; não é um tokenizador.
`CitedTableExtractor::extract()`	`AstDocument $document`	Coleta os nós `Table` mais externos na ordem do documento	`list<CitedTableBlock>`	Não lança	Nunca desce em uma subárvore de tabela.
`CitedTableBlock`	cinco campos readonly	Matriz de células imutável, retangular e em ordem de linha (row-major)	—	Não lança	Linhas curtas recebem preenchimento à direita no momento da extração.
`CitedTableBlock::toArray()`	nenhum	Serializa para um array simples em snake_case	`array<string, mixed>`	Não lança	Células aninhadas serializam via `CitedTableCell::toArray()`.
`CitedTableCell`	sete campos readonly	Registro de célula imutável com coordenadas de citação	—	Não lança	Células de preenchimento carregam um `nodeId` vazio e confiança 0.0.
`CitedTableCell::toArray()`	nenhum	Serializa para um array simples em snake_case; `bbox` aninha ou é `null`	`array<string, mixed>`	Não lança	—

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

Contrato de comportamento

Seleção de nós. CitedTextExtractor emite blocos para nós cujo tipo é Paragraph, Heading, ListItem, TableCell, Code ou Annotation. Um nó com texto null é ignorado. Um nó só é emitido quando o comprimento do seu texto aparado é de pelo menos minChunkLength (padrão 10). Todos os comprimentos são comprimentos em bytes.
Ordem de percurso. O percurso é em profundidade a partir da raiz do documento. Um nó qualificado é emitido antes de seus filhos serem visitados. chunkIndex é incrementado ao longo de todo o percurso do documento e volta a 0 a cada chamada de extract().
Chunking. Com maxTokensPerChunk não definido, cada nó gera um bloco. Quando definido, texto com mais de maxTokensPerChunk * 4 bytes é dividido. O divisor prefere um limite de frase — uma quebra de linha, ou um ponto seguido de um espaço — encontrado ao varrer para trás no máximo 200 bytes a partir do corte preferido. Caso contrário, ele faz uma quebra forçada no orçamento. Espaços após um corte são ignorados; chunks vazios são descartados.
Âncora de citação. A CitationAnchor de cada bloco carrega o id do nó, o índice da página, uma caixa delimitadora, uma confiança e um hash de conteúdo null. Nós sem caixa delimitadora recebem um sentinela compartilhado de área zero, BoundingBox(0, 0, 0, 0), de modo que a âncora seja sempre estruturalmente válida.
Confiança do texto. A confiança lê o atributo confidence do nó quando ele é um int ou float; o padrão é 1.0. Valores de atributo não numéricos recaem no padrão.
Metadados do bloco. metadata sempre carrega nodeType e pageIndex. structType, lang e alt são copiados quando presentes no nó. untagged é definido como true quando o nó carrega um atributo untagged.
Seleção de tabelas. CitedTableExtractor coleta apenas os nós Table mais externos, na ordem do documento. Uma vez que um nó Table é processado, sua subárvore não é reexaminada; tabelas aninhadas não são suportadas.
Formato da matriz. As linhas vêm dos filhos TableRow; as células vêm dos filhos TableCell destes. Outros tipos de filho são ignorados. colCount é a contagem máxima de células entre todas as linhas. Linhas curtas recebem preenchimento à direita até colCount com células sintéticas: nodeId vazio, texto null, bbox null, o índice de página da tabela, confiança 0.0. Uma tabela sem linhas ou sem colunas não gera bloco.
Confiança da célula. A confiança de uma célula real lê seu atributo confidence quando ele é um int ou float; o padrão é 0.8. Blocos de texto usam 1.0 por padrão; células de tabela usam 0.8 por padrão.
Mapeamento de estrutura. A hierarquia percorrida mapeia para o modelo de estrutura lógica do PDF (ISO 32000-2:2020 §14.7). As linhas de tabela mapeiam para o elemento de estrutura TR (§14.8) quando a origem é marcada.

Casos extremos & modos de falha

Nada nesta superfície lança. Ambos os métodos extract() retornam uma lista vazia para um documento sem nós qualificados.
A caixa delimitadora de área zero é um sentinela singleton compartilhado. Chamadores que precisem de uma região real devem detectá-la explicitamente: width === 0.0 && height === 0.0.
Todas as verificações de comprimento e divisões são baseadas em bytes. Quando não existe limite de frase dentro da janela de 200 bytes, uma quebra forçada pode cair dentro de uma sequência UTF-8 multibyte.
O valor de 4 bytes por token é apenas uma heurística de orçamento. Ele não é um tokenizador e não corresponde à tokenização de nenhum modelo específico. estimatedTokens() usa a mesma heurística.
Uma string numérica em um atributo confidence não é coagida; o padrão se aplica. Apenas valores int e float são honrados.
O descarte de espaços em branco após um corte remove apenas espaços comuns. Tabulações e quebras de linha no início de um chunk são preservadas.
O texto de TableCell é extraído duas vezes por design: como blocos de texto por CitedTextExtractor, e dentro de matrizes por CitedTableExtractor. Deduplique a jusante ao rodar ambos os extratores sobre um único documento.
Células de preenchimento são identificáveis por um nodeId vazio e confiança 0.0. Uma célula real, porém vazia, mantém seu nodeId não vazio.
Nenhuma operação criptográfica ocorre neste módulo, portanto não há nenhum comportamento específico de modo FIPS.

Conformidade

Quando o documento de origem é marcado, a AST espelha a hierarquia de estrutura lógica de ISO 32000-2:2020 §14.7, e os nós Table/TableRow correspondem aos elementos de estrutura Table/TR da §14.8. A qualidade da extração é limitada pela qualidade da marcação; conteúdo não marcado produz nós em menor número ou mais grosseiros.

Estas são afirmações de alinhamento estrutural, não resultados de teste de conformidade. A NextPDF não detém nenhuma certificação e não concede nenhuma. Este módulo não faz nenhuma afirmação de conformidade própria; ele consome qualquer estrutura que o subsistema de AST do Core tenha produzido.

Notas de desenvolvimento

Reutilizar uma instância de CitedTextExtractor entre documentos é seguro de forma sequencial; extract() reinicia chunkIndex antes de cada percurso.
Ajuste minChunkLength para filtrar nós de ruído (números de página, sequências avulsas de glifos) antes do chunking, não depois.
Para CJK e outros scripts multibyte, a heurística baseada em bytes superestima os tokens; dimensione maxTokensPerChunk de acordo.
CitedTableBlock::toArray() e CitedTableCell::toArray() emitem chaves em snake_case para pipelines JSON. CitedTextBlock não tem serializador; codifique seus campos você mesmo.
O campo contentHash de CitationAnchor é sempre null nesta superfície. Calcule hashes de conteúdo a jusante quando o pipeline precisar deles.

Limite de publicação

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