Classificateur

En bref

NextPDF\Pro\Classifier attribue un type de document (facture, contrat, rapport, etc.) et une langue détectée à l’aide d’heuristiques déterministes sur le texte et la structure du document. C’est un système à base de règles, pas un modèle d’apprentissage automatique.

Disponibilité et licence

Cette fonctionnalité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de cette autorisation ne charge pas les classes de la fonctionnalité. Compare les éditions et obtiens une licence.

Aucun indicateur de capacité à l’exécution ne restreint ce module. Les classes du classifieur sont disponibles dès que nextpdf/pro est installé.

Installation

composer require nextpdf/pro:^3

Aperçu conceptuel

DocumentClassifier orchestre trois collaborateurs :

• StructureAnalyzer inspecte le PDF pour en relever le nombre de pages, le nombre d’images et de polices, ainsi que les champs de formulaire et de signature, et produit une StructureAnalysis.
• HeuristicClassifier (le ClassifierInterface par défaut) note le texte par rapport à des dictionnaires de mots-clés propres à chaque type et applique des heuristiques structurelles (par exemple, les documents courts s’éloignent du type « rapport »), ce qui produit un DocumentType et un niveau de confiance.
• LanguageDetector identifie la langue à partir de profils de fréquence de trigrammes de caractères pour dix langues, en se rabattant sur l’anglais en dessous d’un seuil de confiance.

classifyFromText() accepte du texte déjà extrait (avec, en option, des octets PDF bruts pour la structure) ; classifyFromFile() accepte des octets PDF bruts et en extrait le texte en analysant directement les opérateurs d’affichage de texte du §9.4.

Pourquoi cela fonctionne ainsi

La décision structurante consiste à classer à l’aide d’heuristiques déterministes, et non d’un modèle d’apprentissage automatique. Un pipeline à base de règles est une fonction pure de son entrée : des octets identiques produisent toujours un type, une confiance et une langue identiques, sans dérive de modèle ni appel réseau. Ce déterminisme permet au résultat d’exposer une confiance explicite, un garde-fou isConfident() et une carte scores par type, si bien que le module montre comment il a décidé plutôt que de dissimuler ce choix derrière un modèle. Les appelants orientent donc par contrat les documents à faible confiance vers une revue manuelle, et un texte trop court pour être noté se rabat sur en selon la même règle figée. Le compromis est délibéré : la précision est bornée par des profils de mots-clés et de trigrammes figés, en échange de reproductibilité, d’inspectabilité et d’un classifieur qui s’exécute entièrement en cours de processus.

Contexte de conception : Une API qui refuse de deviner.

Contrat de comportement

• Entrée. Texte extrait (classifyFromText) ou octets PDF bruts (classifyFromFile). Une entrée vide est valide et produit un résultat à faible confiance, typiquement DocumentType::Other.
• Sortie. Un ClassificationResult portant le DocumentType, une confiance dans [0.0, 1.0], les caractéristiques structurelles détectées, un code de langue ISO 639-1 et des métadonnées. isConfident(0.7) est l’assistant de seuil documenté.
• Déterminisme. La classification et la détection de langue sont des fonctions pures de l’entrée — même entrée, même résultat, sans aléa ni réseau.
• Périmètre. Douze types de documents et dix profils de langue, tous deux figés dans cette version. Des stratégies personnalisées peuvent être fournies via ClassifierInterface.

Surface d’API publique

Type	Genre	Membres clés
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	implémente 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 cas (Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other) ; label(): string

Exemple de code — Démarrage rapide

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

Exemple de code — Production

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

Cas limites et pièges

• La confiance est heuristique. Traite les résultats sous le seuil comme « incertains » et oriente-les vers une revue manuelle, comme le fait l’exemple de production.
• La détection de langue a besoin de suffisamment de texte ; les chaînes très courtes se rabattent sur l’anglais par conception.
• classifyFromFile() utilise une extraction de texte bornée au niveau des octets ; les PDF fortement compressés ou uniquement composés d’images réduisent le texte disponible pour le scoring.
• Les ensembles de types de documents et de langues sont figés dans cette version ; étends la classification en implémentant ClassifierInterface, pas en modifiant les dictionnaires intégrés.

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

La classification s’exécute en cours de processus, sans appel réseau et sans stockage de l’entrée. Le résultat comprend un DocumentType et un code de langue, pas le texte source. Si les appelants conservent les metadata, relis-les pour y détecter d’éventuelles données personnelles incidentes avant le stockage.

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

Le module n’émet aucune télémétrie et ne journalise aucune entrée. Les appelants qui ajoutent de la journalisation ne devraient enregistrer que le DocumentType et le code de langue obtenus, jamais le texte classé.

Performance

Le scoring par mots-clés et le comptage de trigrammes sont linéaires par rapport à la longueur du texte. L’analyse de structure est linéaire par rapport à la longueur en octets du PDF, avec un plafond de décompression borné. Voir performance_budget.

Notes de sécurité

classifyFromFile() analyse des octets PDF non fiables avec un balayage borné et un plafond de taille de décompression pour résister aux entrées de type bombe de décompression. Aucun script embarqué n’est exécuté.

Conformité

Affirmation	Clause de spécification	Statut
Texte récupéré via Tj pour la classification de fichier	ISO 32000-2:2020 §9.4	Vérifié (suite unitaire)
Texte récupéré via TJ pour la classification de fichier	ISO 32000-2:2020 §9.4	Vérifié (suite unitaire)
Classification par apprentissage automatique / fondée sur un modèle	—	Non pris en charge (heuristique uniquement)

Repli / alternative Core

Aucun équivalent Core n’existe pour la classification de documents ou la détection de langue.

Note de frontière Enterprise

Ce classifieur est à base de règles et déterministe. Il n’effectue aucun plongement (embedding), aucune similarité vectorielle, aucune inférence de modèle ni aucune compréhension sémantique. 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 utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.

Voir aussi

• Classifier — Référence détaillée — l’ensemble de la surface d’API publique, l’ordre du pipeline et les modes de défaillance.
• Extraction
• Filter
• Diff