Classifier — référence approfondie

En bref

Cette page est la référence de niveau contractuel du classificateur de documents de NextPDF Pro. La surface se compose d’un orchestrateur, NextPDF\Pro\Classifier\DocumentClassifier, et de ses collaborateurs : StructureAnalyzer, LanguageDetector et la stratégie ClassifierInterface avec son HeuristicClassifier par défaut. Les résultats arrivent sous la forme d’un ClassificationResult immuable portant un DocumentType, une confiance dans [0.0, 1.0], des valeurs ClassificationFeature détectées et un code de langue ISO 639-1. La classification est basée sur des règles et déterministe : aucune inférence de modèle, aucun aléa, aucun appel réseau, aucun accès au système de fichiers. Cette page énonce l’API publique, le contrat de comportement observable et les modes de défaillance.

Disponibilité et licence

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

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

Surface d’API publique

Symbole	Paramètres	Comportement par défaut	Retour	Lève ou échoue avec	Notes
DocumentClassifier	constructeur : StructureAnalyzer, LanguageDetector, ClassifierInterface	Orchestre l’analyse de structure, la classification par stratégie et la détection de langue	—	—	final ; injecte des collaborateurs uniquement pour des stratégies personnalisées
DocumentClassifier::create()	aucun	Construit les collaborateurs par défaut avec HeuristicClassifier comme stratégie	self	—	Configuration par défaut déterministe
DocumentClassifier::classifyFromText()	$text, $pdfData = ''	Un $pdfData vide utilise une structure vide ; des octets bruts non vides ajoutent des signaux structurels	ClassificationResult	Ne lève pas ; une entrée pauvre abaisse la confiance	La détection de langue s’exécute toujours sur $text
DocumentClassifier::classifyFromFile()	string $pdfData	Analyse les flux de contenu, récupère le texte §9.4, analyse la structure, classe	ClassificationResult	Ne lève pas ; les flux illisibles réduisent le texte récupéré	Balayage d’octets borné, pas une analyse PDF complète
ClassifierInterface::classify()	$text, StructureAnalysis $structure	Contrat de stratégie consommé par l’orchestrateur	ClassificationResult	Défini par l’implémentation	Point d’extension pour des stratégies de classification personnalisées
ClassifierInterface::supports()	string $contentType	Sonde de type de contenu pour les classificateurs composites	bool	—	Reçoit un type MIME ou un descripteur de contenu
HeuristicClassifier	aucun	Stratégie par défaut : dictionnaires de mots-clés et heuristiques structurelles	—	Ne lève pas	final ; supports() accepte application/pdf et text/plain
StructureAnalyzer::analyze()	string $pdfData	Balayage regex des octets bruts ; pas d’analyse PDF complète	StructureAnalysis	Ne lève pas	Compte les pages, images, polices ; détecte les champs de formulaire et de signature
LanguageDetector::detect()	string $text	Correspondance de profil par trigrammes avec pré-vérification de plage d’écriture CJK	code ISO 639-1 non-empty-string	Ne lève pas	Se replie sur en sous le seuil d’acceptation
LanguageDetector::detectWithConfidence()	string $text	Comme detect(), avec la confiance exposée	array{language: non-empty-string, confidence: float}	Ne lève pas	Un texte court renvoie en avec une confiance de 0.0
ClassificationResult	constructeur : $type, $confidence, $features, $language, $metadata = []	Objet valeur immuable	—	—	final readonly ; metadata porte scores et method
ClassificationResult::isConfident()	float $threshold = 0.7	Compare la confiance au seuil	bool	—	Point de contrôle documenté pour le routage vers révision manuelle
StructureAnalysis	constructeur : $pageCount, $imageCount, $fontCount, $hasFormFields, $hasSignatureFields, $imageDensity, $detectedFeatures	Objet valeur immuable produit par StructureAnalyzer	—	—	final readonly ; imageDensity correspond aux images par page
DocumentType	énumération à valeurs de type string, 12 cas	Cas : Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other	valeurs sous-jacentes invoice … other	—	label() renvoie un nom lisible par un humain
ClassificationFeature	énumération à valeurs de type string, 7 cas	Cas : HasTables, HasHeaders, HasSignatures, HasLogos, HasBarcodes, HasForms, IsScanned	valeurs sous-jacentes has_tables … is_scanned	—	Signaux structurels injectés dans la classification

Signatures des points d’entrée

public static function create(): self

public function classifyFromText(string $text, string $pdfData = ''): ClassificationResult

public function classifyFromFile(string $pdfData): ClassificationResult

public function classify(string $text, StructureAnalysis $structure): ClassificationResult;

public function supports(string $contentType): bool;

public function analyze(string $pdfData): StructureAnalysis

public function detect(string $text): string

public function detectWithConfidence(string $text): array

public function __construct(
    public DocumentType $type,
    public float $confidence,
    public array $features,
    public string $language,
    public array $metadata = [],
) {}

public function isConfident(float $threshold = 0.7): bool

Contrat de comportement

Ordre du pipeline

DocumentClassifier exécute l’analyse de structure, puis la classification par stratégie, puis la détection de langue, et assemble un ClassificationResult. La stratégie fournit le type, la confiance, les caractéristiques et les métadonnées ; le détecteur fournit la langue. classifyFromText() sans octets PDF substitue une structure vide : zéro page, zéro compteur, aucune caractéristique. classifyFromFile() dérive à la fois la structure et le texte des mêmes octets bruts.

Scoring heuristique

HeuristicClassifier score le texte en minuscules par rapport à des dictionnaires de mots-clés propres à chaque type de document, normalisés par la longueur du texte. Les dictionnaires, poids et seuils spécifiques relèvent du détail d’implémentation et ne sont pas publiés. Les signaux structurels ajustent ensuite les scores : les valeurs ClassificationFeature correspondantes renforcent les types associés ; les documents au-delà d’un seuil de pages s’écartent de Letter et Receipt ; les documents multipages avec en-têtes et tableaux reçoivent un renfort Report ; une caractéristique de formulaire détectée ajoute un fort signal Form. Le score le plus élevé l’emporte et se mappe sur un DocumentType. Une normalisation bornée mappe le score brut dans [0.0, 1.0]. Un score sous le minimum donne DocumentType::Other avec un petit plancher de confiance non nul. Les metadata du résultat portent la carte scores par type et method: heuristic. HeuristicClassifier seul rapporte la langue en ; DocumentClassifier la remplace par la sortie du détecteur.

Détection de langue

Une vérification de plage d’écriture pour le texte CJK s’exécute avant le scoring par trigrammes. La dominance du hangul sélectionne ko ; tout kana sélectionne ja ; sinon, un ratio d’idéogrammes suffisant sélectionne zh. Tout autre texte est scoré par fréquence de trigrammes de caractères par rapport à dix profils intégrés. Les valeurs de retour possibles sont les codes ISO 639-1 en, zh, ja, ko, de, fr, es, pt, it et nl. Un texte sous une longueur minimale renvoie en avec une confiance de 0.0. Un résultat sous le seuil d’acceptation avec une marge étroite renvoie également en. La confiance reflète la marge entre le meilleur et le deuxième meilleur score de profil.

Récupération du texte des fichiers

classifyFromFile() balaie les octets bruts à la recherche de segments stream/endstream. Chaque segment est tenté comme donnée Flate sous un plafond d’inflation borné ; en cas d’échec, les octets bruts du segment sont utilisés. Lorsque le dictionnaire de flux adjacent déclare un prédicteur PNG dans /DecodeParms, l’inversion honore les paramètres Predictor, Columns, Colors et BitsPerComponent conformément à ISO 32000-2:2020 §7.4.4.4, en utilisant les classes DecodeParms et PngPredictor du module Filter. Le texte est ensuite récupéré à partir des opérateurs d’affichage de texte §9.4 : chaînes littérales affichées avec Tj et chaînes littérales à l’intérieur des tableaux TJ. Le classificateur score le texte récupéré ; il ne dépend pas de la mise en page visuelle.

Analyse de structure

StructureAnalyzer::analyze() compte les jetons de page, d’image et de police dans les octets bruts, détecte /AcroForm et les champs de signature, et dérive la densité d’images. La détection de caractéristiques est heuristique : un tracé répété de rectangles suggère des tableaux, de grandes déclarations de taille de police suggèrent des en-têtes, et une densité d’images élevée avec peu de polices suggère un document numérisé. Les compteurs reflètent les jetons visibles dans les octets bruts ; les structures sérialisées à l’intérieur de flux d’objets compressés ne sont pas comptées.

Déterminisme

L’ensemble du pipeline est une fonction pure de ses octets d’entrée. Une entrée identique produit un ClassificationResult identique. Il n’y a aucune inférence de modèle, aucun aléa, aucun appel réseau et aucun accès au système de fichiers.

Cas limites et modes de défaillance

• Un texte vide ou quasi vide donne par conception un DocumentType::Other à faible confiance. Branche sur isConfident() plutôt que sur le type seul.
• Aucune méthode publique de ce module ne lève d’exception. Les flux dont la décompression échoue sont balayés bruts ; les paramètres de prédicteur malformés ou non pris en charge se replient sur les octets non filtrés.
• La récupération de texte ne correspond qu’aux formes de chaînes littérales Tj et TJ. Les chaînes hexadécimales, le texte contenu dans du contenu chiffré et les opérateurs répartis sur plusieurs flux ne sont pas récupérés, ce qui réduit le texte disponible à scorer.
• Le plafond de décompression borne la mémoire pendant l’inflation des flux et résiste aux entrées de type bombe de décompression. Le contenu au-delà du plafond n’est pas décompressé.
• Les PDF composés uniquement d’images ou fortement compressés récupèrent peu de texte ; attends-toi à des résultats à faible confiance et achemine-les vers une révision manuelle.
• La détection de langue en dessous de la longueur de texte minimale renvoie en avec une confiance de 0.0 ; les chaînes très courtes ne produisent jamais un résultat non anglais.
• Les douze types de documents et les dix profils de langue sont fixes pour cette version. L’extension passe par une implémentation ClassifierInterface personnalisée, non par la modification des données intégrées.
• Aucune opération cryptographique n’a lieu dans ce module, il n’y a donc aucun comportement spécifique au mode FIPS.

Conformité

Affirmation	Norme	Clause
La classification de fichier récupère le texte affiché avec l’opérateur Tj.	ISO 32000-2:2020	§9.4
La classification de fichier récupère les chaînes littérales à l’intérieur des opérateurs de tableau TJ.	ISO 32000-2:2020	§9.4
L’inversion du prédicteur PNG honore les paramètres de filtre Predictor, Columns, Colors et BitsPerComponent.	ISO 32000-2:2020	§7.4.4.4

Les codes de langue suivent ISO 639-1 ; il s’agit d’une déclaration ancrée dans le produit sur le format de sortie, non d’une revendication de conformité citée. Toutes les clauses sont paraphrasées ; NextPDF ne reproduit pas le texte normatif. Ce sont des déclarations de capacité, non des certifications. NextPDF ne détient aucune certification et n’en accorde aucune. La classification est heuristique et au mieux : le module affirme le déterminisme, non l’exactitude, et les appelants sont responsables du seuil de décision.

Notes de développement

• Disponible depuis nextpdf/pro 2.2.0 ; actuel dans nextpdf/pro 3.1.0.
• Utilise DocumentClassifier::create() pour le pipeline par défaut. N’injecte des collaborateurs que pour fournir une stratégie ClassifierInterface personnalisée.
• Traite les résultats sous le seuil comme incertains et achemine-les vers une révision manuelle ; isConfident() avec sa valeur par défaut 0.7 est le point de contrôle documenté.
• Le module ne stocke rien, n’émet aucune télémétrie et ne journalise aucune entrée. Si les appelants persistent metadata, qu’ils l’examinent d’abord au regard de leur propre politique de traitement des données.
• Le scoring de mots-clés et le comptage de trigrammes sont linéaires en fonction de la longueur du texte. L’analyse de structure est linéaire en fonction de la longueur en octets du PDF sous le plafond de décompression borné. Le budget de la page est de 1000 ms de temps réel et 64 Mo de mémoire de pointe.

Périmètre de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms 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 (capacité) — installation, démarrage rapide et exemples de routage en production.
• Extraction — référence approfondie — la surface complète d’extraction de texte pour un texte d’entrée plus riche.
• Filter — référence approfondie — DecodeParms et PngPredictor, utilisés pendant la classification de fichier.
• Diff — référence approfondie — la surface sœur de comparaison de documents au niveau des octets.