# Rencana Integrasi Parsing & OCR (Hybrid Smart Dual-Pass)

**Tanggal:** 01 Mei 2026

## Deskripsi
Dokumen ini merangkum strategi, arsitektur, dan rencana eksekusi untuk memperbarui *pipeline* ekstraksi teks pada sistem *Knowledge Graph* Neo4j (`orchestrator_ingest.py`). Sistem saat ini menggunakan *parser* murni `fitz` yang gagal mempertahankan tata letak (tabel, multi-kolom) dan tidak dapat memproses PDF hasil *scan*. Pembaruan ini akan mengintegrasikan `pymupdf4llm` sebagai ekstraktor *Markdown* utama dan `RapidOCR` untuk pengenalan gambar/teks *scan*, menghasilkan ekstraksi teks berkualitas tinggi yang ramah terhadap LLM (Gemini).

## Metodologi
Pembaruan ini menggunakan arsitektur **Smart Dual-Pass**.
Metodologi ini bekerja dengan mengevaluasi kualitas/kepadatan teks digital pada PDF terlebih dahulu. Jika teks dianggap "sampah" (*gibberish*) atau murni *scan*, sistem melakukan *fallback* ke OCR layar penuh. Jika PDF berupa dokumen digital normal, sistem mengekstrak *Markdown* dengan `pymupdf4llm`, melempar gambar ke penyimpanan sementara, dan melakukan OCR parsial hanya pada gambar tersebut untuk kemudian disisipkan kembali ke dalam *Markdown*.

## Keputusan Strategis (Decision Log)
1. **Mesin Parsing Inti:** Mutlak menggunakan `pymupdf4llm` (tidak ada *overhead* ganda dengan library lain) untuk mengamankan struktur tabel dan multi-kolom.
2. **Mesin OCR:** `RapidOCR` dipilih karena kecepatannya jauh mengungguli Tesseract dan sangat akurat untuk teks padat, mendukung target SLA waktu pemrosesan.
3. **Toleransi Performa:** Maksimal **5 detik per file literatur secara utuh** (atau 1-2 detik per halaman dalam skenario terburuk OCR penuh).
4. **Rumus Matematika:** Dipertahankan sebagai teks/simbol linear bawaan `pymupdf4llm` demi menjaga efisiensi *token* dan waktu eksekusi. Konversi khusus ke `LaTeX` ditiadakan.
5. **Sanitisasi Daftar Pustaka:** Dieksekusi paling akhir (*post-assembly*) agar teks injeksi OCR tidak merusak pola pemotongan.

## Alur Diagram (Data Flow)

```mermaid
flowchart TD
    A["Mulai: Input PDF"] --> B{"Inspeksi Rasio Teks Valid (Gibberish Check)"}
    B -- "Kurang dari 60% Valid (Scan / Korup)" --> C["Fallback: Render Halaman ke Gambar"]
    C --> D["Full RapidOCR"]
    
    B -- "Lebih dari 60% Valid (Digital)" --> E["pymupdf4llm.to_markdown"]
    E --> F["Ekstrak Markdown Teks"]
    E --> G["Dump Gambar ke tempfile"]
    
    G --> H["Loop: RapidOCR per Gambar"]
    H --> I["Injeksi Teks OCR ke Markdown"]
    
    F --> J{"Penggabungan Teks"}
    I --> J
    D --> J
    
    J --> K["Sanitisasi & Potong Daftar Pustaka"]
    K --> L["Smart Chunking (berbasis Heading)"]
    L --> M["Selesai: Siap dikirim ke Gemini"]
```

## Struktur Folder (Tree)
Integrasi ini akan memodifikasi struktur file repositori utama sebagai berikut:

```text
/home/daegir/Desktop/poc-task2-neo4j-vector-(27-04-2026)/
├── orchestrator_ingest.py        # (Akan di-refactor: memanggil parser baru)
├── core/
│   ├── parser/
│   │   ├── __init__.py
│   │   └── hybrid_parser.py      # (MODUL BARU: Logika Smart Dual-Pass & OCR)
├── poc-ekstraksi-hibrida/        # (Referensi fitur smart chunking)
└── Markdown/
    └── Parsing_Integration_Plan.md
```

## Asumsi
1. Lingkungan OS (*environment*) mendukung instalasi `pymupdf4llm` dan pustaka pendukung `rapidocr-onnxruntime`.
2. Python modul `tempfile.TemporaryDirectory()` dapat berjalan optimal untuk pembersihan (*cleanup*) sisa gambar secara otomatis bahkan saat *exception* terjadi.
3. Resolusi dokumen yang masuk cukup baik untuk dibaca oleh RapidOCR (minimal 150 DPI).

## Langkah Implementasi
1. **Instalasi Dependensi:** Memastikan `pymupdf4llm` dan `rapidocr` tersedia di lingkungan `requirements.txt`.
2. **Pembuatan Modul Hybrid:** Menulis skrip `hybrid_parser.py` yang membungkus logika deteksi *gibberish*, *fallback* OCR, dan perakitan *Markdown*.
3. **Refaktor Orchestrator:** Mengganti pemanggilan `extract_clean_text_from_pdf` (yang berbasis `fitz` murni) di `orchestrator_ingest.py` dengan fungsi dari `hybrid_parser.py`.
4. **Sanitisasi & Chunking:** Menyesuaikan ulang (*re-align*) logika pemotongan daftar pustaka dan *smart chunking* pada hasil akhir Markdown.
5. **Validasi Performa:** Uji coba untuk memastikan waktu proses satu file PDF utuh berada di bawah angka maksimal 5 detik.

## Tabel Eksekusi Task

| [ ] | Fase | Task | Detail Task | Deskripsi | Acceptance Criteria |
|:---:|:---|:---|:---|:---|:---|
| [x] | 1. Setup | Instalasi Dependensi | Tambahkan pustaka | Menambahkan `pymupdf4llm` dan `rapidocr-onnxruntime` ke `requirements.txt` jika belum ada. | Dependensi dapat diinstal tanpa konflik. |
| [x] | 2. Dev | Modul `hybrid_parser.py` | Buat detektor *Gibberish* | Menulis fungsi penghitung rasio karakter alfabetis vs non-alfabetis (>60%). | Fungsi mengembalikan boolean `True/False` dengan akurat pada PDF acak. |
| [x] | 2. Dev | Modul `hybrid_parser.py` | Implementasi `pymupdf4llm` | Mengekstrak teks digital ke Markdown dan merender gambar ke `tempfile`. | File markdown sukses terbuat, gambar tersimpan dengan aman di folder sementara. |
| [x] | 2. Dev | Modul `hybrid_parser.py` | Implementasi RapidOCR | Membaca gambar dari folder sementara dan menyuntikkan teks kembali ke Markdown. | Teks OCR berhasil masuk ke string utama. Folder sementara terhapus otomatis di akhir eksekusi. |
| [x] | 3. Integrasi | Refaktor Orchestrator | *Replace Legacy Parser* | Menghubungkan fungsi ekstraksi di `orchestrator_ingest.py` ke modul parser yang baru. | Ekstraksi berjalan mulus dipanggil dari dalam *worker thread* / *main thread* Orchestrator. |
| [x] | 3. Integrasi | Relokasi *Sanitizer* | Pemotongan referensi | Memastikan fungsi pemotong daftar pustaka dieksekusi setelah semua teks tergabung. | Daftar pustaka terpotong bersih dari Markdown final tanpa memotong konten OCR. |
| [x] | 4. Testing | Uji Performa | Eksekusi PDF Uji | Mengukur durasi eksekusi menyeluruh dari 1 file PDF. | Waktu tempuh total ekstraksi + OCR < 5 detik per dokumen. |
| [x] | 4. Testing | Validasi *Idempotency* | Cek *Hashing* MD5 | Memastikan fungsi hashing di orchestrator tidak terganggu oleh perubahan mesin parser. | Sistem tidak memproses ulang PDF yang sudah ada (gating *idempotency* bekerja normal). |
