Classifier — Diepe referentie

In één oogopslag

Deze pagina is de referentie op contractniveau voor de NextPDF Pro-documentclassifier. Het oppervlak is één orchestrator, NextPDF\Pro\Classifier\DocumentClassifier, en zijn collaborators: StructureAnalyzer, LanguageDetector en de ClassifierInterface-strategie met zijn standaard HeuristicClassifier. Resultaten komen terug als een immutable ClassificationResult die een DocumentType, een confidence in [0.0, 1.0], gedetecteerde ClassificationFeature-waarden en een ISO 639-1-taalcode draagt. Classificatie is regelgebaseerd en deterministisch: geen model-inferentie, geen willekeur, geen netwerkaanroep, geen bestandssysteemtoegang. Deze pagina beschrijft de publieke API, het observeerbare gedragscontract en de faalmodi.

Beschikbaarheid en licentie

Deze capability wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een Pro-tier license envelope. Een deployment zonder die entitlement laadt de klassen van de capability niet. Vergelijk edities en vraag een licentie aan.

Geen runtime capability flag gate’t deze module. De classifier-klassen zijn beschikbaar zodra nextpdf/pro is geïnstalleerd.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Opmerkingen
DocumentClassifier	constructor: StructureAnalyzer, LanguageDetector, ClassifierInterface	Orkestreert structuuranalyse, strategieclassificatie en taaldetectie	—	—	final; injecteer collaborators alleen voor aangepaste strategieën
DocumentClassifier::create()	geen	Bouwt standaard-collaborators met HeuristicClassifier als strategie	self	—	Deterministische standaardconfiguratie
DocumentClassifier::classifyFromText()	$text, $pdfData = ''	Lege $pdfData gebruikt een lege structuur; niet-lege raw bytes voegen structurele signalen toe	ClassificationResult	Werpt niet; schaarse invoer verlaagt de confidence	Taaldetectie draait altijd op $text
DocumentClassifier::classifyFromFile()	string $pdfData	Scant content streams, herstelt §9.4-tekst, analyseert structuur, classificeert	ClassificationResult	Werpt niet; onleesbare streams verminderen de herstelde tekst	Begrensde byte-scan, geen volledige PDF-parse
ClassifierInterface::classify()	$text, StructureAnalysis $structure	Strategiecontract dat door de orchestrator wordt geconsumeerd	ClassificationResult	Implementatie-gedefinieerd	Uitbreidingspunt voor aangepaste classificatiestrategieën
ClassifierInterface::supports()	string $contentType	Content-type-probe voor samengestelde classifiers	bool	—	Ontvangt een MIME-type of content-descriptor
HeuristicClassifier	geen	Standaardstrategie: keyword-dictionaries plus structurele heuristieken	—	Werpt niet	final; supports() accepteert application/pdf en text/plain
StructureAnalyzer::analyze()	string $pdfData	Regex-scan van raw bytes; geen volledige PDF-parse	StructureAnalysis	Werpt niet	Telt pagina’s, afbeeldingen, fonts; detecteert form- en signature-velden
LanguageDetector::detect()	string $text	Trigram-profielmatch met CJK-script-range-pre-check	non-empty-string ISO 639-1-code	Werpt niet	Valt terug op en onder de acceptatiedrempel
LanguageDetector::detectWithConfidence()	string $text	Zoals detect(), met de confidence blootgesteld	array{language: non-empty-string, confidence: float}	Werpt niet	Korte tekst retourneert en met confidence 0.0
ClassificationResult	constructor: $type, $confidence, $features, $language, $metadata = []	Immutable value object	—	—	final readonly; metadata draagt scores en method
ClassificationResult::isConfident()	float $threshold = 0.7	Vergelijkt de confidence met de drempel	bool	—	Gedocumenteerde gate voor routing naar handmatige review
StructureAnalysis	constructor: $pageCount, $imageCount, $fontCount, $hasFormFields, $hasSignatureFields, $imageDensity, $detectedFeatures	Immutable value object geproduceerd door StructureAnalyzer	—	—	final readonly; imageDensity is afbeeldingen per pagina
DocumentType	string-backed enum, 12 cases	Cases: Invoice, Contract, Form, Report, Letter, Receipt, Legal, Medical, Financial, Technical, Academic, Other	backing-waarden invoice … other	—	label() retourneert een leesbare naam
ClassificationFeature	string-backed enum, 7 cases	Cases: HasTables, HasHeaders, HasSignatures, HasLogos, HasBarcodes, HasForms, IsScanned	backing-waarden has_tables … is_scanned	—	Structurele signalen die de classificatie voeden

Entry-point-signaturen

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

Gedragscontract

Pijplijnvolgorde

DocumentClassifier draait structuuranalyse, dan strategieclassificatie, dan taaldetectie, en assembleert een ClassificationResult. De strategie levert het type, de confidence, de features en de metadata; de detector levert de taal. classifyFromText() zonder PDF-bytes vervangt dit door een lege structuur: nul pagina’s, nul tellingen, geen features. classifyFromFile() leidt zowel de structuur als de tekst af uit dezelfde raw bytes.

Heuristische scoring

HeuristicClassifier scoort tekst in kleine letters tegen keyword-dictionaries per documenttype, genormaliseerd op tekstlengte. De specifieke dictionaries, gewichten en drempels zijn implementatiedetail en worden niet gepubliceerd. Structurele signalen passen vervolgens de scores aan: overeenkomende ClassificationFeature-waarden versterken de bijbehorende typen; documenten boven een pagina-drempel neigen weg van Letter en Receipt; documenten met meerdere pagina’s met headers en tabellen krijgen een Report-boost; een gedetecteerde form-feature voegt een sterk Form-signaal toe. De hoogste score wint en wordt gemapt op een DocumentType. Een begrensde normalisatie mapt de ruwe score naar [0.0, 1.0]. Een score onder het minimum levert DocumentType::Other op met een kleine confidence-ondergrens die niet nul is. De metadata van het resultaat draagt de scores-map per type en method: heuristic. HeuristicClassifier alleen rapporteert taal en; DocumentClassifier overschrijft dit met de output van de detector.

Taaldetectie

Een script-range-check voor CJK-tekst draait vóór de trigram-scoring. Hangul-dominantie selecteert ko; elke kana selecteert ja; anders selecteert een voldoende ideogram-verhouding zh. Alle overige tekst wordt gescoord op karaktertrigram-frequentie tegen tien ingebouwde profielen. De mogelijke retourwaarden zijn de ISO 639-1-codes en, zh, ja, ko, de, fr, es, pt, it en nl. Tekst onder een minimale lengte retourneert en met confidence 0.0. Een resultaat onder de acceptatiedrempel met een smalle marge retourneert eveneens en. De confidence weerspiegelt de marge tussen de beste en op één na beste profielscores.

Bestandstekstherstel

classifyFromFile() scant de raw bytes op stream/endstream-segmenten. Elk segment wordt geprobeerd als Flate-data onder een begrensde inflation-cap; bij mislukking worden de ruwe segment-bytes gebruikt. Wanneer het aangrenzende stream-dictionary een PNG-predictor declareert in /DecodeParms, respecteert de omkering de parameters Predictor, Columns, Colors en BitsPerComponent volgens ISO 32000-2:2020 §7.4.4.4, met gebruik van de DecodeParms- en PngPredictor-klassen van de Filter-module. Vervolgens wordt tekst hersteld uit de §9.4-text-showing-operatoren: literal strings getoond met Tj en literal strings binnen TJ-arrays. De classifier scoort de herstelde tekst; hij hangt niet af van visuele lay-out.

Structuuranalyse

StructureAnalyzer::analyze() telt pagina-, afbeelding- en font-tokens in de raw bytes, detecteert /AcroForm- en signature-velden en leidt de afbeeldingsdichtheid af. Feature-detectie is heuristisch: herhaald tekenen van rechthoeken duidt op tabellen, grote font-size-declaraties duiden op headers, en een hoge afbeeldingsdichtheid met weinig fonts duidt op een gescand document. Tellingen weerspiegelen tokens die zichtbaar zijn in de raw bytes; structuren geserialiseerd binnen gecomprimeerde object streams worden niet geteld.

Determinisme

De hele pijplijn is een pure functie van zijn invoer-bytes. Identieke invoer produceert een identiek ClassificationResult. Er is geen model-inferentie, geen willekeur, geen netwerkaanroep en geen bestandssysteemtoegang.

Randgevallen en faalmodi

• Lege of bijna-lege tekst levert van ontwerp een lage-confidence DocumentType::Other op. Vertak op isConfident() in plaats van op het type alleen.
• Geen enkele publieke methode van deze module werpt. Streams die decompressie niet doorstaan worden ruw gescand; misvormde of niet-ondersteunde predictor-parameters vallen terug op de ongefilterde bytes.
• Tekstherstel matcht alleen de literal-string-vormen Tj en TJ. Hexadecimale strings, tekst binnen versleutelde content en operatoren die over streams zijn gesplitst worden niet hersteld, wat de beschikbare tekst om te scoren vermindert.
• De decompressie-cap begrenst het geheugen tijdens stream-inflation en weerstaat decompression-bomb-invoer. Content voorbij de cap wordt niet geïnflateerd.
• PDF’s met alleen afbeeldingen of zware compressie herstellen weinig tekst; verwacht lage-confidence-resultaten en stuur ze naar handmatige review.
• Taaldetectie onder de minimale tekstlengte retourneert en met confidence 0.0; zeer korte strings produceren nooit een niet-Engels resultaat.
• De twaalf documenttypen en tien taalprofielen liggen vast voor deze release. Uitbreiding gebeurt via een aangepaste ClassifierInterface-implementatie, niet door het bewerken van ingebouwde data.
• Er treedt geen cryptografische bewerking op in deze module, dus er is geen FIPS-modusspecifiek gedrag.

Conformiteit

Claim	Standaard	Clausule
Bestandsclassificatie herstelt tekst getoond met de Tj-operator.	ISO 32000-2:2020	§9.4
Bestandsclassificatie herstelt literal strings binnen TJ-array-operatoren.	ISO 32000-2:2020	§9.4
PNG-predictor-omkering respecteert de filterparameters Predictor, Columns, Colors en BitsPerComponent.	ISO 32000-2:2020	§7.4.4.4

Taalcodes volgen ISO 639-1; dit is een productgebaseerde uitspraak over het uitvoerformaat, geen geciteerde conformiteitsclaim. Alle clausules zijn geparafraseerd; NextPDF reproduceert geen normatieve tekst. Dit zijn capability-uitspraken, geen certificeringen. NextPDF bezit geen certificering en verleent er geen. Classificatie is heuristisch en best-effort: de module garandeert determinisme, geen nauwkeurigheid, en aanroepers zijn eigenaar van de beslissingsdrempel.

Ontwikkelnotities

• Beschikbaar sinds nextpdf/pro 2.2.0; actueel in nextpdf/pro 3.1.0.
• Gebruik DocumentClassifier::create() voor de standaardpijplijn. Injecteer collaborators alleen om een aangepaste ClassifierInterface-strategie te leveren.
• Behandel resultaten onder de drempel als onzeker en stuur ze naar handmatige review; isConfident() met zijn standaard 0.7 is de gedocumenteerde gate.
• De module slaat niets op, verstuurt geen telemetrie en logt geen invoer. Als aanroepers metadata persisteren, toets die dan eerst aan hun eigen databeleid.
• Keyword-scoring en trigram-telling zijn lineair in de tekstlengte. Structuuranalyse is lineair in de PDF-bytelengte onder de begrensde decompressie-cap. Het paginabudget is 1000 ms wall time en 64 MB piekgeheugen.

Publicatiegrens

Deze pagina documenteert alleen extern observeerbaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-klassen, mechanismetabellen, runbook-bestandsnamen en ticket-prefixen vallen buiten de scope.

Zie ook

• Classifier (capability) — installatie, snelstart en productie-routing-voorbeelden.
• Extraction — Diepe referentie — het volledige tekstextractie-oppervlak voor rijkere invoertekst.
• Filter — Diepe referentie — DecodeParms en PngPredictor, gebruikt tijdens bestandsclassificatie.
• Diff — Diepe referentie — het zusteroppervlak voor byte-niveau documentvergelijking.