Extraction

Sekilas pandang

NextPDF\Pro\Extraction menelusuri AST dokumen terurai dan menghasilkan blok teks dan tabel, masing-masing membawa anchor sitasi (indeks halaman, bounding box, referensi node). Ini adalah ekstraktor struktural deterministik untuk pipeline atribusi-sumber, bukan mesin pencarian atau pemahaman.

Ketersediaan & lisensi

Kapabilitas ini dikirim dalam NextPDF Pro (nextpdf/pro) dan diaktifkan dengan envelope lisensi tier Pro. Deployment tanpa entitlement tersebut tidak memuat kelas kapabilitas ini. Tidak ada flag kapabilitas runtime yang menggerbangi modul ini; kelas Extraction tersedia setiap kali nextpdf/pro terpasang. Bandingkan edisi dan dapatkan lisensi.

Pemasangan

composer require nextpdf/pro:^3

Tinjauan konseptual

Kedua ekstraktor mengambil sebuah NextPDF\Ast\AstDocument — pohon dokumen terurai yang dihasilkan oleh subsistem AST Core. Keduanya tidak mengurai byte PDF mentah sendiri; AST adalah batas input.

• CitedTextExtractor menelusuri pohon dan memancarkan sebuah CitedTextBlock untuk setiap node teks substantif (paragraf, heading, item daftar, sel tabel, kode, anotasi) yang teks ter-trim-nya memenuhi panjang minimum. Token budget opsional memecah teks panjang pada batas kalimat. Setiap blok membawa sebuah CitationAnchor dengan id node, indeks halaman, bounding box, dan keyakinan yang dibaca dari node (default 1.0). Node tanpa bounding box menerima sebuah sentinel box berarea-nol sehingga anchor selalu valid.
• CitedTableExtractor menemukan node Table, membaca baris dan selnya, dan membangun matriks row-major persegi yang dipad hingga baris terlebar. Tabel bersarang tidak direkursi. Keyakinan sel secara default 0.8 kecuali node membawa nilai eksplisit.

Hierarki struktural yang ditelusuri ekstraktor ini berkorespondensi dengan model struktur-logis PDF (ISO 32000-2:2020 §14.7) dan elemen struktur tabel (§14.8) ketika dokumen sumber diberi tag.

Mengapa cara kerjanya seperti ini

Ekstraktor mengambil AST terurai sebagai batas input-nya, bukan byte PDF mentah, sehingga risiko penguraian tetap terpisah dari logika ekstraksi. Keyakinan dibaca langsung dari node AST dan diteruskan tanpa perubahan; modul tidak pernah menghitung, merangking, atau memperbaikinya. Output tetap dalam urutan dokumen, bukan urutan relevansi, karena atribusi-sumber membutuhkan provenans yang dapat diverifikasi ketimbang tebakan heuristik yang tidak dapat dipertahankan ekstraktor. Setiap blok membawa anchor sitasi — id node, indeks halaman, bounding box — sehingga pipeline hilir dapat melacak setiap kutipan kembali ke asalnya. Ini secara sengaja menjaga modul tetap sebagai ekstraktor struktural deterministik: ia melaporkan apa yang diklaim AST dan menolak mengarang apa pun yang tidak dinyatakan dokumen.

Latar belakang desain: API yang menolak menebak.

Kontrak perilaku

• Input. Sebuah NextPDF\Ast\AstDocument. Modul ini tidak menerima byte PDF mentah; hasilkan AST dengan subsistem AST Core terlebih dahulu.
• Output. list<CitedTextBlock> atau list<CitedTableBlock> dalam urutan dokumen.
• Keyakinan bersifat passthrough. Ia dibaca dari atribut node AST (atau default tetap). Modul ini tidak menghitung atau meningkatkan keyakinan.
• Tanpa pemrosesan semantik. Ekstraktor tidak melakukan embedding, kemiripan vektor, perangkingan, atau pemahaman dokumen. Urutan keluaran adalah urutan dokumen, bukan urutan relevansi.
• Determinisme. Untuk AST yang identik, blok, anchor, dan indeks chunk yang dihasilkan bersifat stabil.

Permukaan API publik

Type	Kind	Key members
NextPDF\Pro\Extraction\CitedTextExtractor	final class	__construct(?int $maxTokensPerChunk = null, int $minChunkLength = 10), extract(AstDocument $document): list<CitedTextBlock>
NextPDF\Pro\Extraction\CitedTableExtractor	final class	extract(AstDocument $document): list<CitedTableBlock>
NextPDF\Pro\Extraction\CitedTextBlock	final readonly class	string $text, CitationAnchor $anchor, float $confidence, int $chunkIndex, array $metadata, estimatedTokens(): int
NextPDF\Pro\Extraction\CitedTableBlock	final readonly class	string $nodeId, int $pageIndex, int $rowCount, int $colCount, array $matrix
NextPDF\Pro\Extraction\CitedTableCell	final readonly class	int $row, int $col, ?string $textContent, float $confidence

Contoh kode — Mulai cepat

<?php

declare(strict_types=1);

use NextPDF\Pro\Extraction\CitedTextExtractor;

/** @var \NextPDF\Ast\AstDocument $ast */
$blocks = (new CitedTextExtractor())->extract($ast);

foreach ($blocks as $block) {
    printf(
        "p%d chunk#%d (%d tokens): %s\n",
        $block->anchor->pageIndex,
        $block->chunkIndex,
        $block->estimatedTokens(),
        $block->text,
    );
}

Contoh kode — Produksi

<?php

declare(strict_types=1);

use NextPDF\Pro\Extraction\CitedTextExtractor;

function chunkForCitation(\NextPDF\Ast\AstDocument $ast): array
{
    // Token-bounded chunks for downstream citation storage.
    $extractor = new CitedTextExtractor(
        maxTokensPerChunk: 400,
        minChunkLength: 16,
    );

    $rows = [];
    foreach ($extractor->extract($ast) as $block) {
        $rows[] = [
            'text'      => $block->text,
            'page'      => $block->anchor->pageIndex,
            'node_id'   => $block->anchor->nodeId,
            'chunk'     => $block->chunkIndex,
        ];
    }

    return $rows;
}

Kasus tepi & jebakan

• Dokumen yang tidak diberi tag atau diberi tag dengan buruk menghasilkan lebih sedikit node teks; kualitas AST adalah batas atas kualitas ekstraksi.
• Node tanpa bounding box mendapat sentinel berarea-nol BoundingBox(0,0,0,0) — deteksi via width === 0.0 && height === 0.0 jika region nyata diperlukan.
• Tabel bersarang tidak direkursi; hanya node Table terluar yang dipancarkan.
• Baris pendek dipad dengan sel sintetik berkeyakinan-nol sehingga setiap baris memiliki jumlah kolom yang sama.

Residensi Data & Mitigasi PII

Modul ini memproses teks apa pun yang dimuat AST yang disediakan dan mengembalikannya tanpa perubahan di dalam blok. Ia tidak melakukan panggilan jaringan, tidak ada penyimpanan eksternal, dan tidak ada logging konten yang diekstrak. Penanganan PII, redaksi, dan kontrol residensi adalah tanggung jawab pemanggil atas blok yang dihasilkan. Lihat panduan penanganan PII Core.

Telemetri Aman & Pembersihan Log

Ekstraktor tidak memancarkan telemetri dan tidak mencatat teks yang diekstrak. Jika pemanggil membungkusnya dengan logging, bersihkan text, metadata, dan konten sel apa pun sebelum memancarkan log.

Performa

Ekstraksi adalah satu penelusuran pohon, linear terhadap jumlah node. Pemecahan chunk menambahkan pekerjaan sebanding dengan panjang teks. Lihat performance_budget.

Catatan keamanan

Input adalah AST yang sudah diurai, sehingga modul ini tidak mengurai byte PDF yang bermusuhan sendiri. Perlakukan teks yang diekstrak sebagai tidak tepercaya dan escape untuk tujuannya.

Konformansi

Claim	Spec clause	Status
Logical-structure node traversal	ISO 32000-2:2020 §14.7	Verified (unit suite, tagged AST)
Table row/cell extraction	ISO 32000-2:2020 §14.8	Verified (unit suite)
Semantic search / embeddings	—	Not supported (out of scope)

Fallback / alternatif Core

Subsistem AST Core menghasilkan AstDocument yang dikonsumsi di sini; tidak ada padanan Core untuk ekstraksi blok-sitasi itu sendiri. Lihat /modules/core/ast/.

Catatan batas Enterprise

Modul ini hanyalah ekstraktor struktural. Ia tidak melakukan pencarian semantik, embedding vektor, perangkingan kemiripan, atau intelijen dokumen. 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

• Referensi Extraction
• Classifier
• Diff
• Core AST