# LAPORAN AKHIR PROOF OF CONCEPT (PoC) TASK 2: HYBRID SMART DUAL-PASS OCR & MARKDOWN PARSING

**Status:** Selesai dan Diverifikasi  
**Tanggal Laporan:** 1 Mei 2026

---

## 1. JUDUL DAN IDENTITAS PROYEK

**Judul Proyek:** Proof of Concept Task 2 - Integrasi Hybrid Smart Dual-Pass OCR & Markdown Parsing untuk Neo4j Vector Knowledge Graph  
**Identitas Teknis:** PoC Task 2 Hybrid Parsing Pipeline  
**Versi Aktif:** Parsing_Integration_Plan  
**Status:** Completed dan Production-Ready

---

## 2. DESKRIPSI PROOF OF CONCEPT

Proof of Concept (PoC) ini bertujuan untuk meningkatkan keandalan *pipeline ingestion* Knowledge Graph dalam memproses berbagai format jurnal akademik. Sistem parsing sebelumnya yang hanya berbasis ekstraksi teks PDF lawas memiliki keterbatasan serius dalam membaca tabel, tata letak dua kolom, dan secara total gagal memproses dokumen PDF berjenis hasil pindaian (*scanned images*).

Untuk mengatasi isu tersebut, PoC ini merancang dan mengimplementasikan algoritma **Hybrid Smart Dual-Pass**. Arsitektur ini menggabungkan kecanggihan konversi Markdown terstruktur dari library **PyMuPDF4LLM** (untuk mengekstrak layout kompleks dan tabel) dengan keandalan mesin deteksi teks optik **RapidOCR ONNX Runtime** (untuk memulihkan teks dari dokumen pindaian). 

Sistem ini bersifat otomatis (berkat *Gibberish Detector*) yang memungkinkannya untuk memutuskan secara mandiri apakah sebuah jurnal dapat diekstrak langsung, atau membutuhkan bantuan beban kerja OCR ringan (parsial pada gambar), hingga OCR berat (seluruh halaman). Pendekatan *hybrid* ini memotong waktu komputasi secara ekstrem dibanding melakukan OCR ke semua dokumen, sekaligus memastikan LLM mendapatkan input teks Markdown yang bersih, tanpa *noise* dari *header* maupun *footer*.

---

## 3. ARSITEKTUR PROOF OF CONCEPT

Arsitektur PoC ini menggantikan modul ekstraksi monolitik lama di dalam `orchestrator_ingest.py` dan menempatkan kompleksitas parsing di sebuah modul inti terpisah (`core/parser/hybrid_parser.py`).

Pipeline *Hybrid Parsing* ini terbagi menjadi empat fase utama:
1. **Gibberish Detection (Routing Phase):** Analisis sampel rasio karakter alfabet dibandingkan teks sampah. Jika rasio alfabetis gagal memenuhi batas minimum (60%), dokumen akan diarahkan ke *Full OCR*. Jika memenuhi, diarahkan ke *Digital Extraction*.
2. **Digital Extraction & Formatting:** PDF yang dikenali sebagai dokumen digital dibedah oleh `pymupdf4llm` menggunakan manajemen batas (*margins*) untuk mengeksklusi *header*, *footer*, dan penomoran halaman secara _native_, kemudian direkonstruksi menjadi struktur *Markdown*.
3. **Image Sub-Pass & OCR Injection:** Pada metode PDF digital, jika terdapat blok gambar yang dideteksi, gambar dipindahkan ke memori sementara (*tempfile*). *RapidOCR* lalu membaca gambar tersebut, dan jika ditemukan teks di dalamnya, teks tersebut diinjeksikan kembali ke teks *Markdown* tanpa merusak urutan baca.
4. **Post-Processing (Sanitization):** Hasil mentah *Markdown* kemudian dilewatkan ke pemotong *Bibliography* berbasis Regex (`sanitize_markdown`) sebelum teks akhirnya dikirimkan ke mesin AI (OpenRouter) untuk digenerasikan menjadi node Knowledge Graph.

---

## 4. TEKNOLOGI, ASUMSI, DAN SPESIFIKASI

**Stack Teknologi:**
- **Bahasa:** Python 3.10+
- **Library Parser Utama:** `pymupdf4llm`
- **Library OCR:** `rapidocr-onnxruntime`
- **Library Pendukung:** `PyMuPDF (fitz)`

**Asumsi-Asumsi Kunci:**
1. **Target Dokumen:** Beragam bentuk jurnal ilmiah, termasuk format digital bersih (PDF-A) maupun hasil fotokopi/pindaian kertas.
2. **Keterbatasan VRAM/Memory:** Penggunaan engine OCR dibatasi agar tidak memerlukan akselerasi GPU (CUDA) besar, difasilitasi oleh model _lightweight_ ONNX.
3. **Idempotency Data:** Metode Hashing MD5 untuk *duplicate checking* tetap membaca _binary source_ dari PDF, tidak terganggu oleh jenis format output parser ini.

**Spesifikasi Constraint:**
- **Performance Threshold:** Durasi target eksekusi gabungan ekstraksi dan/atau OCR rata-rata ditekan di bawah 5-10 detik per dokumen normal.
- **Auto-Cleanup Memori:** Semua operasi rendering gambar PDF ke _disk/temp_ harus dihapus dari ruang penyimpanan OS di setiap akhir sesi proses melalui *context manager*.

---

## 5. PENJELASAN CARA KERJA ARSITEKTUR PROOF OF CONCEPT

Eksekusi dimulai saat `orchestrator_ingest.py` mendapatkan giliran file PDF untuk diproses, kemudian `HybridParser.parse_pdf()` dipanggil.

**Fase 1: Gibberish Routing**
Kelas `HybridParser` membuka PDF dengan `fitz` (PyMuPDF standar) dan menginspeksi maksimal 3 halaman pertama. Karakter alfabet dan spasi dihitung rasionya. Jika rasionya < 60%, sistem memutuskan file tersebut adalah hasil pindaian (scan).

**Fase 2a: Full OCR Fallback (Untuk Scanned PDF)**
Dokumen diubah menjadi raster *pixmap* 150 DPI halaman demi halaman. Raster tersebut dibaca oleh `RapidOCR` dan teks gabungannya dirangkai lalu dikembalikan ke Orchestrator.

**Fase 2b: Digital Extraction (Untuk Digital PDF)**
Jika rasio > 60%, `pymupdf4llm.to_markdown` dipanggil dengan parameter `header=False`, `footer=False`, dan `margins=(0, 72, 0, 72)`. Ini sangat krusial agar informasi yang tidak substansial (seperti label lisensi Proceeding atau nomor urut halaman di tepi bawah/atas) otomatis dibuang. Gambar tabel atau grafik ditarik ke `tempfile.TemporaryDirectory()`.

**Fase 2c: OCR Injection (Sub-Proses 2b)**
Sistem menelusuri isi folder `tempfile` dan menjalankan *RapidOCR* ke gambar-gambar tersebut. Hasil deteksi teks lalu disuntikkan ke teks *Markdown* di lokasi gambar asli dengan *tag blockquote*: `> **[Teks Gambar Hasil OCR...]**`. Ketika blok fungsi berakhir, `tempfile` akan hancur dan membersihkan jejak penyimpanannya sendiri.

**Fase 3: Sanitization & Knowledge Delivery**
*Markdown* utuh tiba kembali di Orchestrator. Fungsi `sanitize_markdown()` memotong seluruh referensi daftar pustaka dengan pola Regex yang telah dilatih mengenali *heading markdown* (`## References`, `# Bibliography`, dll.). Hasilnya dikirimkan menuju *LLM Pillar Extraction*.

---

## 6. DIAGRAM ARSITEKTUR HYBRID PARSING PIPELINE

```mermaid
flowchart TD
    classDef init fill:#E3F2FD,stroke:#1565C0,stroke-width:2px,color:#0D47A1,rx:8,ry:8
    classDef llm fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#1B5E20,rx:8,ry:8
    classDef process fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px,color:#E65100,rx:8,ry:8
    classDef fallback fill:#FCE4EC,stroke:#C2185B,stroke-width:2px,color:#880E4F,rx:8,ry:8

    Start([Input Dokumen PDF]):::init
    
    subgraph Phase 1: Routing
        MD5[MD5 Hashing Idempotency]:::process
        Gibberish[Gibberish Detector<br>Threshold < 60%]:::process
    end

    subgraph Phase 2: Processing Engine
        FullOCR[Full Page RapidOCR<br>Image to Text]:::fallback
        PyMuPDF[PyMuPDF4LLM<br>Markdown + No Header/Footer]:::process
        ImageOCR[RapidOCR Injection<br>Tempfile Image Scan]:::process
    end

    subgraph Phase 3: Sanitization
        Sanitize[Bibliography Sanitizer<br>Markdown Regex Cut]:::process
        ExtractLLM[OpenRouter API<br>Pillar Extraction]:::llm
    end

    Start --> MD5
    MD5 --> Gibberish
    
    Gibberish -- Scan/Gambar --> FullOCR
    Gibberish -- Teks Digital --> PyMuPDF
    
    PyMuPDF --> ImageOCR
    
    FullOCR --> Sanitize
    ImageOCR --> Sanitize
    
    Sanitize --> ExtractLLM
```

---

## 7. PENJELASAN DETAIL DIAGRAM ARSITEKTUR

Diagram di atas mendeskripsikan secara linear aliran pemrosesan teks di dalam mesin Ingestion Neo4j Vector.

- **Phase 1 (Routing):** Pengecekan Idempotensi dilakukan paling awal agar file yang pernah diproses tak perlu dihitung ulang. Jika baru, *Gibberish Detector* mengklasifikasikan aliran pemrosesan.
- **Phase 2 (Processing Engine):** Bagian terberat dalam beban kerja. Warna *pink/merah muda* menandakan jalur _fallback_ untuk performa berat, sedangkan *oranye* menunjukkan alur ekstraksi cerdas. Pemotongan _header_ (1-inci margin) secara eksplisit terjadi di `PyMuPDF`.
- **Phase 3 (Sanitization):** Hasil pengerjaan Phase 2 difinalisasi dengan penghapusan referensi, sebelum data hijau diteruskan ke infrastruktur *AI/LLM* untuk proses Knowledge Graph *Reasoning*.

---

## 8. STRUKTUR REPOSITORY RELEVAN

Penambahan pada PoC Task 2 terkait fitur ini (Parsing Integration):

```
poc-task2-neo4j-vector/
│
├─ core/
│  └─ parser/
│     ├─ __init__.py 
│     └─ hybrid_parser.py                   <-- (Modul Smart Dual-Pass OCR)
│
├─ orchestrator_ingest.py                   <-- (Diperbarui dengan Sanitizer Baru)
├─ test_hybrid.py                           <-- (Skrip Uji Coba Sanity Check)
├─ test_performance.py                      <-- (Skrip Uji Coba Durasi Eksekusi & Idempotency)
├─ sample_parsing_output.md                 <-- (Artifact Hasil Uji)
│
├─ Markdown/
│  ├─ Parsing_Integration_Plan.md           <-- (Blueprint Pipeline Parsing)
│  ├─ Final_Report_PoC_Task2_20260501.md    <-- (Laporan Ini)
│  └─ Parsing-Integration/
│     ├─ Task_1_Execution_Log.md            <-- (Audit Log per Fase)
│     ├─ Task_2_Execution_Log.md
│     ├─ Task_3_Execution_Log.md
│     └─ Task_4_Execution_Log.md
```
Final_Report_PoC_Task2_20260501.md
---

## 9. KESIMPULAN

Implementasi sistem integrasi Hybrid Smart Dual-Pass OCR dan Markdown Parsing telah berhasil diselesaikan secara paripurna dengan memenuhi seluruh kriteria dan objektivitas awal:

1. **Efisiensi Token:** Pendekatan *Markdown* dengan pengabaian parameter *Header* dan *Footer* (margin 72 piksel) mengeliminasi sampah teks di setiap pergantian halaman. Pembuangan daftar pustaka memperkuat rasio sinyal terhadap *noise*, menghemat *cost* pemakaian token AI secara ekstrem.
2. **Universality:** Orkestrator tidak akan gagal lagi (crash) saat menemukan jurnal digital lawas atau jurnal pindaian fisik karena fungsi transisi mulus dari PyMuPDF4LLM ke RapidOCR.
3. **Kebersihan Memori:** *Tempfile* terbukti membersihkan artefak gambar secara instan setelah data diolah.
4. **Performa Tangguh:** Pendekatan injeksi ringan secara default menjaga *execution time* mendekati target awal (< 5-10 detik), alih-alih menguras VRAM jika sistem memakai model OCR konvensional murni.

Sistem *Neo4j Vector Knowledge Graph* sekarang memiliki fondasi _Extraction Engine_ paling mutakhir yang siap untuk diuji dengan skala _dataset_ penelitian yang jauh lebih luas secara riil di fase produksi selanjutnya.
