Pengklasifikasi

Sekilas pandang

NextPDF\Pro\Classifier menetapkan sebuah tipe dokumen (faktur, kontrak, laporan, dan seterusnya) serta bahasa yang terdeteksi menggunakan heuristik deterministik atas teks dan struktur dokumen. Ini berbasis aturan, bukan model pembelajaran mesin.

Ketersediaan & lisensi

Kapabilitas ini hadir di NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tier Pro. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag kapabilitas runtime yang menggerbangi modul ini. Kelas-kelas classifier tersedia setiap kali nextpdf/pro terpasang.

Pemasangan

composer require nextpdf/pro:^3

Tinjauan konseptual

DocumentClassifier mengorkestrasi tiga kolaborator:

• StructureAnalyzer memeriksa PDF untuk jumlah halaman, jumlah gambar dan fon, serta bidang formulir/tanda tangan, menghasilkan sebuah StructureAnalysis.
• HeuristicClassifier (ClassifierInterface default) menilai teks terhadap kamus kata kunci per tipe dan menerapkan heuristik struktural (misalnya, dokumen pendek cenderung menjauh dari “report”), menghasilkan sebuah DocumentType dan tingkat keyakinan.
• LanguageDetector mengidentifikasi bahasa dari profil frekuensi trigram-karakter untuk sepuluh bahasa, dengan fallback ke bahasa Inggris di bawah ambang keyakinan.

classifyFromText() menerima teks yang sudah diekstrak (dengan byte PDF mentah opsional untuk struktur); classifyFromFile() menerima byte PDF mentah dan mengekstrak teks dengan mengurai operator pemunculan-teks §9.4 secara langsung.

Mengapa dirancang seperti ini

Keputusan penopang utama adalah mengklasifikasikan dengan heuristik deterministik, bukan model pembelajaran mesin. Pipeline berbasis aturan adalah fungsi murni dari inputnya: byte yang identik selalu menghasilkan tipe, tingkat keyakinan, dan bahasa yang identik, tanpa model drift dan tanpa panggilan jaringan. Determinisme itu memungkinkan hasil mengekspos tingkat keyakinan eksplisit, gerbang isConfident(), dan peta scores per tipe, sehingga modul menunjukkan bagaimana ia memutuskan alih-alih menyembunyikan pilihan di balik sebuah model. Karena itu pemanggil merutekan dokumen berkeyakinan rendah ke peninjauan manual secara kontraktual, dan teks yang terlalu pendek untuk dinilai jatuh kembali ke en di bawah aturan tetap yang sama. Kompromi ini disengaja: akurasi dibatasi oleh profil kata kunci dan trigram yang tetap, sebagai ganti reproduksibilitas, keterinspeksian, dan classifier yang berjalan sepenuhnya in-process.

Latar belakang desain: API yang menolak menebak.

Kontrak perilaku

• Input. Teks yang diekstrak (classifyFromText) atau byte PDF mentah (classifyFromFile). Input kosong valid dan menghasilkan hasil berkeyakinan rendah, biasanya DocumentType::Other.
• Output. Sebuah ClassificationResult dengan DocumentType, tingkat keyakinan dalam [0.0, 1.0], fitur struktural yang terdeteksi, kode bahasa ISO 639-1, dan metadata. isConfident(0.7) adalah helper ambang yang terdokumentasi.
• Determinisme. Klasifikasi dan deteksi bahasa adalah fungsi murni dari input — input yang sama, hasil yang sama, tanpa keacakan, tanpa jaringan.
• Cakupan. Dua belas tipe dokumen dan sepuluh profil bahasa, keduanya tetap di rilis ini. Strategi kustom dapat disediakan melalui ClassifierInterface.

Permukaan API publik

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

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

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

Kasus tepi & jebakan

• Keyakinan bersifat heuristik. Perlakukan hasil di bawah ambang sebagai “tidak pasti” dan rutekan ke peninjauan manual, sebagaimana yang dilakukan contoh produksi.
• Deteksi bahasa membutuhkan teks yang cukup; string yang sangat pendek jatuh kembali ke bahasa Inggris sesuai desain.
• classifyFromFile() menggunakan ekstraksi teks tingkat byte yang terbatas; PDF yang sangat terkompresi atau hanya berupa gambar mengurangi teks yang tersedia untuk dinilai.
• Himpunan tipe-dokumen dan bahasa bersifat tetap di rilis ini; perluas klasifikasi dengan mengimplementasikan ClassifierInterface, bukan dengan memutasi kamus bawaan.

Residensi Data & Mitigasi PII

Klasifikasi berjalan in-process tanpa panggilan jaringan dan tanpa penyimpanan input. Hasil mencakup sebuah DocumentType dan kode bahasa, bukan teks sumber. Jika pemanggil mempersistensi metadata, tinjau untuk PII insidental sebelum penyimpanan.

Telemetri Aman & Pembersihan Log

Modul ini tidak memancarkan telemetri dan tidak mencatat input. Pemanggil yang menambahkan logging sebaiknya hanya merekam DocumentType dan kode bahasa yang dihasilkan, jangan pernah teks yang diklasifikasikan.

Performa

Penilaian kata kunci dan pencacahan trigram bersifat linear terhadap panjang teks. Analisis struktur bersifat linear terhadap panjang byte PDF dengan batas dekompresi. Lihat performance_budget.

Catatan keamanan

classifyFromFile() mengurai byte PDF yang tidak tepercaya dengan pemindaian terbatas dan batas ukuran dekompresi untuk menahan input decompression-bomb. Tidak ada skrip tertanam yang dieksekusi.

Konformansi

Claim	Spec clause	Status
Text recovered via Tj for file classification	ISO 32000-2:2020 §9.4	Verified (unit suite)
Text recovered via TJ for file classification	ISO 32000-2:2020 §9.4	Verified (unit suite)
Machine-learning / model-based classification	—	Not supported (heuristic only)

Fallback / alternatif Core

Tidak ada padanan Core untuk klasifikasi dokumen atau deteksi bahasa.

Catatan batas Enterprise

Classifier ini berbasis aturan dan deterministik. Ia tidak melakukan embedding, kemiripan vektor, inferensi model, atau pemahaman semantik. Kapabilitas tersebut bukan bagian dari modul ini dan tidak tersirat olehnya.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Classifier — Referensi Mendalam — permukaan API publik lengkap, urutan pipeline, dan mode kegagalan.
• Extraction
• Filter
• Diff