Classifier

In breve

NextPDF\Pro\Classifier assegna un tipo di documento (fattura, contratto, report e così via) e una lingua rilevata tramite euristiche deterministiche sul testo e sulla struttura del documento. È basato su regole, non è un modello di apprendimento automatico.

Disponibilità e licenza

Questa funzionalità viene distribuita in NextPDF Pro (nextpdf/pro) e si attiva con un pacchetto di licenza di livello Pro. Un deployment privo di tale diritto non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Nessun flag di capacità a runtime governa questo modulo. Le classi del classifier sono disponibili ogni volta che nextpdf/pro è installato.

Installazione

composer require nextpdf/pro:^3

Panoramica concettuale

DocumentClassifier coordina tre collaboratori:

• StructureAnalyzer ispeziona il PDF per il numero di pagine, il conteggio di immagini e font e i campi di modulo/firma, producendo una StructureAnalysis.
• HeuristicClassifier (il ClassifierInterface predefinito) valuta il testo a fronte di dizionari di parole chiave per tipo e applica euristiche strutturali (ad esempio, i documenti brevi vengono penalizzati rispetto al tipo “report”), producendo un DocumentType e una confidenza.
• LanguageDetector identifica la lingua a partire dai profili di frequenza dei trigrammi di caratteri per dieci lingue, ricadendo sull’inglese al di sotto di una soglia di confidenza.

classifyFromText() accetta testo già estratto (con byte PDF grezzi opzionali per la struttura); classifyFromFile() accetta byte PDF grezzi ed estrae il testo analizzando direttamente gli operatori di visualizzazione del testo §9.4.

Perché funziona così

La decisione portante è classificare con euristiche deterministiche, non con un modello di apprendimento automatico. Una pipeline basata su regole è una funzione pura del proprio input: byte identici producono sempre un tipo, una confidenza e una lingua identici, senza deriva del modello e senza chiamate di rete. Quel determinismo consente al risultato di esporre una confidenza esplicita, un gate isConfident() e una mappa scores per tipo, così il modulo mostra come ha deciso invece di nascondere la scelta dietro un modello. I chiamanti instradano quindi i documenti a bassa confidenza alla revisione manuale per contratto, e il testo troppo breve per essere valutato ricade su en sotto la stessa regola fissa. Il compromesso è deliberato: l’accuratezza è limitata da profili fissi di parole chiave e trigrammi, in cambio di riproducibilità, ispezionabilità e un classificatore che gira interamente in-process.

Contesto di progettazione: Un’API che si rifiuta di indovinare.

Contratto di comportamento

• Input. Testo estratto (classifyFromText) o byte PDF grezzi (classifyFromFile). Un input vuoto è valido e produce un risultato a bassa confidenza, in genere DocumentType::Other.
• Output. Un ClassificationResult con il DocumentType, una confidenza in [0.0, 1.0], le caratteristiche strutturali rilevate, un codice di lingua ISO 639-1 e metadati. isConfident(0.7) è l’helper di soglia documentato.
• Determinismo. La classificazione e il rilevamento della lingua sono funzioni pure dell’input — stesso input, stesso risultato, nessuna casualità, nessuna rete.
• Ambito. Dodici tipi di documento e dieci profili di lingua, entrambi fissi in questa release. È possibile fornire strategie personalizzate tramite ClassifierInterface.

Superficie dell’API pubblica

Tipo	Genere	Membri chiave
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 casi (Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other); label(): string

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

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

Casi limite e insidie

• La confidenza è euristica. Trattare i risultati al di sotto della soglia come “incerti” e instradarli alla revisione manuale, come fa l’esempio di produzione.
• Il rilevamento della lingua richiede testo a sufficienza; le stringhe molto brevi ricadono sull’inglese per scelta progettuale.
• classifyFromFile() usa un’estrazione del testo a livello di byte e delimitata; i PDF fortemente compressi o composti da sole immagini riducono il testo disponibile per la valutazione.
• Gli insiemi di tipi di documento e di lingue sono fissi in questa release; estendere la classificazione implementando ClassifierInterface, non mutando i dizionari predefiniti.

Residenza dei dati e mitigazioni PII

La classificazione viene eseguita in-process senza chiamate di rete e senza memorizzazione dell’input. Il risultato include un DocumentType e un codice di lingua, non il testo di origine. Se i chiamanti persistono i metadata, verificarli per eventuale PII incidentale prima della memorizzazione.

Telemetria sicura e pulizia dei log

Il modulo non emette alcuna telemetria e non registra alcun input. I chiamanti che aggiungono logging dovrebbero registrare solo il DocumentType risultante e il codice di lingua, mai il testo classificato.

Prestazioni

La valutazione delle parole chiave e il conteggio dei trigrammi sono lineari rispetto alla lunghezza del testo. L’analisi della struttura è lineare rispetto alla lunghezza in byte del PDF con un limite di decompressione delimitato. Vedere performance_budget.

Note sulla sicurezza

classifyFromFile() analizza byte PDF non attendibili con scansione delimitata e un limite di dimensione della decompressione per resistere a input di tipo decompression-bomb. Nessuno script incorporato viene eseguito.

Conformità

Affermazione	Clausola spec	Stato
Testo recuperato tramite Tj per la classificazione da file	ISO 32000-2:2020 §9.4	Verificato (suite unitaria)
Testo recuperato tramite TJ per la classificazione da file	ISO 32000-2:2020 §9.4	Verificato (suite unitaria)
Classificazione con machine learning / basata su modello	—	Non supportato (solo euristico)

Fallback / alternativa Core

Non esiste alcun equivalente Core per la classificazione dei documenti o il rilevamento della lingua.

Nota sui confini Enterprise

Questo classificatore è basato su regole e deterministico. Non esegue alcun embedding, similarità vettoriale, inferenza di modelli o comprensione semantica. Tali capacità non fanno parte di questo modulo e non sono implicate da esso.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie dell’API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.

Vedere anche

• Classifier — Riferimento approfondito — la superficie completa dell’API pubblica, l’ordine della pipeline e le modalità di errore.
• Extraction
• Filter
• Diff