Classifier

Visão geral

NextPDF\Pro\Classifier atribui um tipo de documento (fatura, contrato, relatório e assim por diante) e um idioma detectado usando heurísticas determinísticas sobre o texto e a estrutura do documento. É baseado em regras, não um modelo de aprendizado de máquina.

Disponibilidade e licenciamento

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

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

Instalação

composer require nextpdf/pro:^3

Visão conceitual

DocumentClassifier orquestra três colaboradores:

• StructureAnalyzer inspeciona o PDF quanto à contagem de páginas, à contagem de imagens e fontes e aos campos de formulário/assinatura, produzindo uma StructureAnalysis.
• HeuristicClassifier (a ClassifierInterface padrão) pontua o texto em relação a dicionários de palavras-chave por tipo e aplica heurísticas estruturais (por exemplo, documentos curtos tendem a evitar “report”), gerando um DocumentType e uma confiança.
• LanguageDetector identifica o idioma a partir de perfis de frequência de trigramas de caracteres para dez idiomas, recorrendo ao inglês abaixo de um limiar de confiança.

classifyFromText() aceita texto já extraído (com bytes brutos opcionais do PDF para a estrutura); classifyFromFile() aceita bytes brutos do PDF e extrai o texto analisando diretamente os operadores de exibição de texto da §9.4.

Por que funciona dessa forma

A decisão determinante é classificar com heurísticas determinísticas, não com um modelo de aprendizado de máquina. Um pipeline baseado em regras é uma função pura de sua entrada: bytes idênticos sempre produzem um tipo, uma confiança e um idioma idênticos, sem desvio de modelo e sem chamada de rede. Esse determinismo permite que o resultado exponha uma confiança explícita, um portão isConfident() e um mapa de scores por tipo, de modo que o módulo mostra como decidiu em vez de esconder a escolha por trás de um modelo. Assim, os chamadores encaminham documentos de baixa confiança para revisão manual por contrato, e texto curto demais para ser pontuado recorre a en sob a mesma regra fixa. O compromisso é deliberado: a precisão é limitada por perfis fixos de palavras-chave e trigramas, em troca de reprodutibilidade, inspecionabilidade e um classificador que roda inteiramente em processo.

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

Contrato de comportamento

• Entrada. Texto extraído (classifyFromText) ou bytes brutos do PDF (classifyFromFile). Uma entrada vazia é válida e gera um resultado de baixa confiança, normalmente DocumentType::Other.
• Saída. Um ClassificationResult com o DocumentType, uma confiança em [0.0, 1.0], características estruturais detectadas, um código de idioma ISO 639-1 e metadados. isConfident(0.7) é o helper de limiar documentado.
• Determinismo. A classificação e a detecção de idioma são funções puras da entrada — mesma entrada, mesmo resultado, sem aleatoriedade, sem rede.
• Escopo. Doze tipos de documento e dez perfis de idioma, ambos fixos nesta versão. Estratégias personalizadas podem ser fornecidas via ClassifierInterface.

Superfície pública da API

Type	Kind	Key members
NextPDF\Pro\Classifier\DocumentClassifier	final class	static create(): self, classifyFromText(string $text, string $pdfData = ''): ClassificationResult, classifyFromFile(string $pdfData): ClassificationResult
NextPDF\Pro\Classifier\ClassifierInterface	interface	classify(string $text, StructureAnalysis $structure): ClassificationResult, supports(string $contentType): bool
NextPDF\Pro\Classifier\HeuristicClassifier	final class	implements ClassifierInterface
NextPDF\Pro\Classifier\StructureAnalyzer	final class	analyze(string $pdfData): StructureAnalysis
NextPDF\Pro\Classifier\LanguageDetector	final class	detect(string $text): string
NextPDF\Pro\Classifier\ClassificationResult	final readonly class	DocumentType $type, float $confidence, array $features, string $language, isConfident(float $threshold = 0.7): bool
NextPDF\Pro\Classifier\DocumentType	enum	12 cases (Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other); label(): string

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Classifier\DocumentClassifier;

$result = DocumentClassifier::create()
    ->classifyFromText('Invoice #4471 — Amount due: $1,200.00');

printf(
    "%s (%.0f%% confidence), lang=%s\n",
    $result->type->label(),
    $result->confidence * 100,
    $result->language,
);

Exemplo de código — Produção

<?php

declare(strict_types=1);

use NextPDF\Pro\Classifier\DocumentClassifier;
use NextPDF\Pro\Classifier\DocumentType;

function routeDocument(string $pdfBytes): string
{
    $result = DocumentClassifier::create()->classifyFromFile($pdfBytes);

    if (! $result->isConfident(0.7)) {
        return 'manual-review';
    }

    return match ($result->type) {
        DocumentType::Invoice, DocumentType::Receipt => 'accounts-payable',
        DocumentType::Contract, DocumentType::Legal   => 'legal-intake',
        default                                       => 'general-inbox',
    };
}

Casos extremos e armadilhas

• A confiança é heurística. Trate os resultados abaixo do limiar como “incertos” e encaminhe-os para revisão manual, como faz o exemplo de produção.
• A detecção de idioma precisa de texto suficiente; strings muito curtas recorrem ao inglês por design.
• classifyFromFile() usa extração de texto em nível de byte limitada; PDFs muito comprimidos ou apenas com imagens reduzem o texto disponível para pontuar.
• Os conjuntos de tipos de documento e de idiomas são fixos nesta versão; estenda a classificação implementando ClassifierInterface, não mutando os dicionários internos.

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

A classificação é executada no processo, sem chamadas de rede e sem armazenamento da entrada. O resultado inclui um DocumentType e o código de idioma, não o texto de origem. Se os chamadores persistirem metadata, revise-os quanto a PII incidental antes do armazenamento.

Telemetria segura e limpeza de logs

O módulo não emite telemetria e não registra a entrada. Os chamadores que adicionarem logging devem registrar apenas o DocumentType resultante e o código de idioma, nunca o texto classificado.

Desempenho

A pontuação de palavras-chave e a contagem de trigramas são lineares no comprimento do texto. A análise de estrutura é linear no comprimento em bytes do PDF, com um limite de descompressão. Consulte performance_budget.

Notas de segurança

classifyFromFile() analisa bytes de PDF não confiáveis com varredura limitada e um limite de tamanho de descompressão para resistir a entradas com bombas de descompressão. Nenhum script incorporado é executado.

Conformidade

Claim	Spec clause	Status
Texto recuperado via Tj para classificação de arquivo	ISO 32000-2:2020 §9.4	Verificado (conjunto de testes unitários)
Texto recuperado via TJ para classificação de arquivo	ISO 32000-2:2020 §9.4	Verificado (conjunto de testes unitários)
Classificação por aprendizado de máquina / baseada em modelo	—	Não suportado (apenas heurístico)

Fallback / alternativa no Core

Não existe equivalente no Core para classificação de documentos ou detecção de idioma.

Nota sobre o limite do Enterprise

Este classificador é baseado em regras e determinístico. Ele não realiza nenhuma incorporação (embedding), similaridade vetorial, inferência de modelo ou compreensão semântica. 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 da API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismo, nomes de arquivos de runbook e prefixos de tickets estão fora do escopo.

Veja também

• Classifier — Referência detalhada — a superfície completa da API pública, a ordem do pipeline e os modos de falha.
• Extraction
• Filter
• Diff