Pro edisi

Extraction — Referensi Mendalam

Sekilas

Halaman ini adalah referensi tingkat kontrak untuk NextPDF\Pro\Extraction. Modul ini berisi lima simbol publik: dua ekstraktor (CitedTextExtractor, CitedTableExtractor) dan tiga value object immutable (CitedTextBlock, CitedTableBlock, CitedTableCell). Kedua ekstraktor mengonsumsi NextPDF\Ast\AstDocument yang telah diparsing; keduanya tidak membaca byte PDF mentah. Ekstraksi bersifat deterministik dan struktural. Tidak ada langkah semantik, embedding, atau ranking di mana pun dalam modul ini. Tampilan berorientasi tugas tersedia di halaman kapabilitas.

Ketersediaan & lisensi

Kapabilitas ini hadir dalam 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-kelasnya tersedia kapan pun nextpdf/pro terpasang dan berlisensi.

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
`CitedTextExtractor::__construct()`	`?int $maxTokensPerChunk = null`, `int $minChunkLength = 10`	Tanpa budget token; teks yang telah di-trim di bawah 10 byte dibuang	`CitedTextExtractor`	Tidak melempar	Budget `null` berarti satu blok per node.
`CitedTextExtractor::extract()`	`AstDocument $document`	Penelusuran depth-first; satu blok per node teks yang memenuhi syarat, dipecah berdasarkan budget token	`list<CitedTextBlock>`	Tidak melempar	Deterministik; `chunkIndex` direset ke 0 pada setiap pemanggilan.
`CitedTextBlock`	lima field readonly	Value object immutable; tanpa metode serializer	—	Tidak melempar	Kunci `metadata`: `nodeType`, `pageIndex`, plus opsional `structType`, `lang`, `alt`, `untagged`.
`CitedTextBlock::estimatedTokens()`	tidak ada	`ceil(byte length / 4)`	`int`	Tidak melempar	Heuristik budget; bukan tokenizer.
`CitedTableExtractor::extract()`	`AstDocument $document`	Mengumpulkan node `Table` terluar dalam urutan dokumen	`list<CitedTableBlock>`	Tidak melempar	Tidak pernah menelusuri subtree tabel.
`CitedTableBlock`	lima field readonly	Matriks sel row-major persegi panjang yang immutable	—	Tidak melempar	Baris pendek diberi padding di sisi kanan saat ekstraksi.
`CitedTableBlock::toArray()`	tidak ada	Menserialisasi ke array biasa snake_case	`array<string, mixed>`	Tidak melempar	Sel bersarang diserialisasi melalui `CitedTableCell::toArray()`.
`CitedTableCell`	tujuh field readonly	Record sel immutable dengan koordinat sitasi	—	Tidak melempar	Sel padding membawa `nodeId` kosong dan confidence 0.0.
`CitedTableCell::toArray()`	tidak ada	Menserialisasi ke array biasa snake_case; `bbox` bersarang atau `null`	`array<string, mixed>`	Tidak melempar	—

final class CitedTextExtractor

public function __construct(
    private readonly ?int $maxTokensPerChunk = null,
    private readonly int $minChunkLength = 10,
)

public function extract(AstDocument $document): array

final class CitedTableExtractor

public function extract(AstDocument $document): array

final readonly class CitedTextBlock

public function __construct(
    public string $text,
    public CitationAnchor $anchor,
    public float $confidence,
    public int $chunkIndex,
    public array $metadata,
)

public function estimatedTokens(): int

final readonly class CitedTableBlock

public function __construct(
    public readonly string $nodeId,
    public readonly int    $pageIndex,
    public readonly int    $rowCount,
    public readonly int    $colCount,
    public readonly array  $matrix,
)

public function toArray(): array

final readonly class CitedTableCell

public function __construct(
    public readonly string       $nodeId,
    public readonly int          $row,
    public readonly int          $col,
    public readonly ?string      $textContent,
    public readonly ?BoundingBox $bbox,
    public readonly int          $pageIndex,
    public readonly float        $confidence,
)

public function toArray(): array

Kontrak perilaku

Pemilihan node. CitedTextExtractor menghasilkan blok untuk node yang tipenya Paragraph, Heading, ListItem, TableCell, Code, atau Annotation. Node dengan teks null dilewati. Sebuah node hanya dihasilkan ketika panjang teks yang telah di-trim minimal minChunkLength (default 10). Semua panjang adalah panjang byte.
Urutan penelusuran. Penelusuran bersifat depth-first dari root dokumen. Node yang memenuhi syarat dihasilkan sebelum anak-anaknya dikunjungi. chunkIndex bertambah sepanjang seluruh penelusuran dokumen dan direset ke 0 pada setiap pemanggilan extract().
Chunking. Dengan maxTokensPerChunk tidak diset, setiap node menghasilkan satu blok. Ketika diset, teks yang lebih panjang dari maxTokensPerChunk * 4 byte dipecah. Splitter lebih memilih batas kalimat — sebuah newline, atau titik yang diikuti spasi — yang ditemukan dengan memindai mundur paling banyak 200 byte dari titik potong yang diinginkan. Jika tidak, ia memotong keras pada budget. Spasi setelah potongan dilewati; chunk kosong dibuang.
Anchor sitasi. CitationAnchor setiap blok membawa node id, indeks halaman, sebuah bounding box, sebuah confidence, dan content hash null. Node tanpa bounding box menerima sentinel bersama berluas nol, BoundingBox(0, 0, 0, 0), sehingga anchor selalu valid secara struktural.
Confidence teks. Confidence membaca atribut confidence node ketika bernilai int atau float; defaultnya adalah 1.0. Nilai atribut non-numerik jatuh kembali ke default.
Metadata blok. metadata selalu membawa nodeType dan pageIndex. structType, lang, dan alt disalin ketika ada pada node. untagged diset ke true ketika node membawa atribut untagged.
Pemilihan tabel. CitedTableExtractor hanya mengumpulkan node Table terluar, dalam urutan dokumen. Setelah sebuah node Table diproses, subtree-nya tidak diperiksa ulang; tabel bersarang tidak didukung.
Bentuk matriks. Baris berasal dari anak TableRow; sel berasal dari anak TableCell-nya. Tipe anak lain diabaikan. colCount adalah jumlah sel maksimum di seluruh baris. Baris pendek diberi padding di sisi kanan hingga colCount dengan sel sintetis: nodeId kosong, teks null, bbox null, indeks halaman tabel, confidence 0.0. Tabel tanpa baris atau tanpa kolom tidak menghasilkan blok.
Confidence sel. Confidence sel nyata membaca atribut confidence-nya ketika bernilai int atau float; defaultnya adalah 0.8. Blok teks default 1.0; sel tabel default 0.8.
Pemetaan struktur. Hierarki yang ditelusuri dipetakan ke model logical-structure PDF (ISO 32000-2:2020 §14.7). Baris tabel dipetakan ke elemen struktur TR (§14.8) ketika sumbernya ditag.

Kasus tepi & mode kegagalan

Tidak ada apa pun pada permukaan ini yang melempar. Kedua metode extract() mengembalikan list kosong untuk dokumen tanpa node yang memenuhi syarat.
Bounding box berluas nol adalah sentinel singleton bersama. Pemanggil yang membutuhkan region nyata harus mendeteksinya secara eksplisit: width === 0.0 && height === 0.0.
Semua pemeriksaan panjang dan pemotongan berbasis byte. Ketika tidak ada batas kalimat dalam jendela 200-byte, potongan keras dapat jatuh di dalam sekuens UTF-8 multibyte.
Angka 4-byte-per-token adalah heuristik budget saja. Ini bukan tokenizer dan tidak cocok dengan tokenisasi model tertentu mana pun. estimatedTokens() menggunakan heuristik yang sama.
String numerik dalam atribut confidence tidak dikoersi; default yang berlaku. Hanya nilai int dan float yang dihormati.
Pelewatan whitespace setelah potongan hanya menghapus spasi biasa. Tab dan newline di awal chunk dipertahankan.
Teks TableCell diekstrak dua kali secara by design: sebagai blok teks oleh CitedTextExtractor, dan di dalam matriks oleh CitedTableExtractor. Deduplikasi di hilir ketika menjalankan kedua ekstraktor atas satu dokumen.
Sel padding dapat diidentifikasi melalui nodeId kosong dan confidence 0.0. Sel yang nyata tetapi kosong mempertahankan nodeId-nya yang tidak kosong.
Tidak ada operasi kriptografis yang terjadi dalam modul ini, sehingga tidak ada perilaku khusus mode FIPS.

Konformansi

Ketika dokumen sumber ditag, AST mencerminkan hierarki logical-structure ISO 32000-2:2020 §14.7, dan node Table/TableRow berkorespondensi dengan elemen struktur Table/TR §14.8. Kualitas ekstraksi dibatasi oleh kualitas tagging; konten yang tidak ditag menghasilkan node yang lebih sedikit atau lebih kasar.

Ini adalah pernyataan keselarasan struktural, bukan hasil uji konformansi. NextPDF tidak memegang sertifikasi apa pun dan tidak memberikannya. Modul ini tidak membuat klaim konformansi sendiri; ia mengonsumsi struktur apa pun yang dihasilkan subsistem Core AST.

Catatan pengembangan

Menggunakan ulang satu instance CitedTextExtractor di berbagai dokumen aman secara sekuensial; extract() mereset chunkIndex sebelum setiap penelusuran.
Setel minChunkLength untuk memfilter node noise (nomor halaman, deretan glyph tersasar) sebelum chunking, bukan sesudahnya.
Untuk CJK dan skrip multibyte lainnya heuristik berbasis byte melebih-lebihkan hitungan token; ukur maxTokensPerChunk sesuai dengan itu.
CitedTableBlock::toArray() dan CitedTableCell::toArray() mengeluarkan kunci snake_case untuk pipeline JSON. CitedTextBlock tidak memiliki serializer; enkode field-nya sendiri.
Field contentHash dari CitationAnchor selalu null pada permukaan ini. Hitung content hash di hilir ketika pipeline membutuhkannya.

Batas publikasi

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