# Rencana Debugging: Masalah Parsing PDF dan Parameter Sensitivity

## 1. Judul
**Systematic Debugging Plan untuk Root Cause Analysis: PyMuPDF4LLM Parsing Failures dan OCR Integration Issues**

---

## 2. Tanggal
**04 Mei 2026**

---

## 3. Deskripsi

Pada eksekusi production pipeline `orchestrator_ingest.py` pada tanggal 04 Mei 2026, ditemukan kegagalan parsing pada 4 dari 9 file PDF (44.4% success rate). Kegagalan ini ditandai dengan error:
```
TypeError: 'NoneType' object is not iterable
```

Error terjadi di dalam `pymupdf4llm.to_markdown()` saat library mencoba mengiterasi hasil OCR internal. File-file yang bermasalah:
1. `Reviving Life on the Edge Joint Score-Based Graph Generation of Rich Edge Attributes.pdf` [1/9]
2. `Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks.pdf` [6/9]
3. `SciLit Joint Literature Discovery...` [7/9]
4. `Proses Pembuatan Pupuk Kompos...` [9/9]

Hipotesis awal: masalahnya bukan file rusak, melainkan **kombinasi parameter konfigurasi** (`header=False`, `footer=False`, `margins=(0, 72, 0, 72)`) yang tidak cocok untuk subset PDF tertentu, mengakibatkan library mengembalikan `None` atau melakukan error handling internal yang tidak robust pada OCR sub-process.

Rencana ini dirancang untuk **isolasi root cause** melalui pengujian berlapis dengan tiga harness debugging independen:
1. **PyMuPDF Raw (Baseline)** — Verify file validity
2. **PyMuPDF4LLM Variants** — Test parameter sensitivity
3. **Per-Page OCR** — Evaluate fallback viability

Output dari debugging ini akan menentukan arah perbaikan yang tepat (parameter adjustment, library workaround, atau fallback strategy change).

---

## 4. Metodologi

### Approach: Layered Boundary Testing
Debugging dilakukan pada tiga boundary layer dengan tujuan mengisolasi error:

```
Layer 1: File Validity (PyMuPDF Raw)
   ↓ [Verifiy: Is file readable?]
   
Layer 2: Parser Parameter Sensitivity (PyMuPDF4LLM Variants)
   ↓ [Test: Which config works? Which fails?]
   
Layer 3: Fallback Performance (Per-Page OCR)
   ↓ [Measure: How long? How reliable?]
```

### Decision Logic
Hasil dari setiap layer akan feed ke next layer:
- **Layer 1 FAIL** → File has real issue, evaluate OCR only
- **Layer 1 PASS, Layer 2 ALL FAIL** → Library bug atau version issue
- **Layer 1 PASS, Layer 2 PARTIAL** → Parameter sensitivity → adjust config
- **Layer 1 PASS, Layer 2 ALL PASS** → Edge case handling needed
- **Layer 3 SLOW/FAIL** → OCR fallback tidak viable, gunakan raw text

### Success Criteria
Debugging dianggap berhasil jika:
1. ✅ Dapat mengidentifikasi parameter mana yang menyebabkan failure
2. ✅ Dapat membuktikan file-file bermasalah sebenarnya valid (PyMuPDF raw berhasil)
3. ✅ Dapat mengukur performance OCR fallback per-halaman
4. ✅ Dapat membuat keputusan engineering: fix parameter vs fallback strategy

---

## 5. Keputusan

Berdasarkan hasil debugging (akan dianalisis setelah harness selesai), keputusan akan diambil dari matrix berikut:

| Layer 1 Status | Layer 2 Status                | Layer 3 Status      | Keputusan                                          |
|---|---|---|---|
| ✅ PASS | ❌ ALL FAIL | — | Gunakan PyMuPDF raw + custom Markdown formatter (bypass pymupdf4llm sepenuhnya) |
| ✅ PASS | ⚠️  PARTIAL (1-3 work) | < 3s/page | Hardcode config yang work, gunakan OCR fallback untuk edge case |
| ✅ PASS | ✅ ALL/MOST PASS | < 3s/page | Tambah try-except di pymupdf4llm call, fallback ke raw text jika None |
| ✅ PASS | ✅ ALL/MOST PASS | > 5s/page | Gunakan raw text fallback, jangan OCR (terlalu mahal) |
| ❌ FAIL | — | — | File memiliki issue serius, skip file atau isolasi per-halaman |

---

## 6. Struktur Folder

Direktori debugging akan terstruktur sebagai berikut:

```
Markdown/chunking-integration/
├─ chunking-debugging-plan.md              (dokumen ini)
├─ debugging-harness/
│  ├─ __init__.py
│  ├─ harness1_pymupdf_raw.py             (Baseline: PyMuPDF raw text extraction)
│  ├─ harness2_pymupdf4llm_variants.py    (Parameter sensitivity testing)
│  ├─ harness3_perpage_ocr.py             (OCR fallback performance)
│  ├─ common.py                            (Shared utilities: logging, file helpers)
│  └─ README.md                            (Instruksi menjalankan harness)
│
├─ debugging-results/
│  ├─ harness1_[FILENAME]_results.log
│  ├─ harness2_[FILENAME]_results.log
│  ├─ harness3_[FILENAME]_results.log
│  └─ analysis_summary.md                  (Ringkasan hasil & keputusan)
│
└─ (existing files)
   ├─ Error-Analysis-and-Solutions.md
   ├─ Phase-1-Fixes-Implementation.md
   └─ ...
```

---

## 7. Asumsi

1. **File PDF Valid**
   - File dapat dibuka di PDF viewer (Adobe, Preview, etc.)
   - File bukan corrupted pada layer fisik
   - File memiliki struktur internal yang reasonable

2. **Dependency Installed**
   - `PyMuPDF` (fitz) v1.23+
   - `pymupdf4llm` v0.x
   - `rapidocr-onnxruntime` v0.x

3. **Single File Debugging**
   - Harness dijalankan pada **satu file bermasalah** terlebih dahulu (rekomendasi: file [1/9])
   - Hasil dapat kemudian di-generalisasi ke file lain

4. **Network Available**
   - Tidak ada pembatasan OCR API (RapidOCR lokal)
   - Tidak ada out-of-memory issue (file size < 100 MB)

5. **Current Code State**
   - `core/parser/hybrid_parser.py` versi dengan defensive checks (dari Phase 1 Fixes)
   - Parameter konfigurasi di line 68 masih `margins=(0, 72, 0, 72)`, `header=False`, `footer=False`

---

## 8. Langkah Implementasi

### Phase 1: Persiapan (Task 1-2)
**Objectives:**
- Setup debugging folder structure
- Buat common utilities untuk logging dan file handling
- Identifikasi satu file target untuk debugging

### Phase 2: Harness Development (Task 3-5)
**Objectives:**
- Implementasikan Harness 1 (PyMuPDF raw baseline)
- Implementasikan Harness 2 (PyMuPDF4LLM variants)
- Implementasikan Harness 3 (Per-page OCR)

### Phase 3: Harness Execution (Task 6-8)
**Objectives:**
- Jalankan ketiga harness pada file target
- Dokumentasikan output lengkap
- Lakukan preliminary analysis

### Phase 4: Analysis & Decision (Task 9-10)
**Objectives:**
- Analisis hasil harness menggunakan decision matrix
- Tentukan solusi spesifik (parameter fix vs fallback strategy)
- Dokumentasikan rekomendasi implementasi

### Phase 5: Implementation (Task 11+, di plan terpisah)
**Objectives:**
- Implementasikan fix ke codebase
- Validate dengan full pipeline run
- Dokumentasikan hasil

---

## 9. Tabel Eksekusi Task

| ☐ | Fase | Task | Detail Task | Deskripsi | Acceptance Criteria |
|:---:|:---|:---|:---|:---|:---|
| ✓ | Setup | Task 1: Create Folder Structure | Buat `debugging-harness/` dan `debugging-results/` | Persiapan direktori untuk harness dan output hasil debugging | Folder terbuat, `__init__.py` dan `README.md` ada |
| ✓ | Setup | Task 2: Identify Target File | Pilih 1 file bermasalah untuk baseline debugging | Fokus debugging pada file [1/9] atau file lain yang problem | File dipilih, path dicatat, file dapat dibuka dengan fitz |
| ✓ | Development | Task 3: Build Harness 1 (PyMuPDF Raw) | Implementasi `harness1_pymupdf_raw.py` untuk baseline testing | Ekstrak text page-by-page, log char count, detect empty pages | Script jalan, output page-by-page char count, total chars > 0 |
| ✓ | Development | Task 4: Build Harness 2 (PyMuPDF4LLM Variants) | Implementasi `harness2_pymupdf4llm_variants.py` dengan 5 parameter config | Test config: current, no margins, with headers, ignore images, ignore graphics | Script jalan, show status ✅/❌ untuk masing-masing config |
| ✓ | Development | Task 5: Build Harness 3 (Per-Page OCR) | Implementasi `harness3_perpage_ocr.py` dengan page-by-page OCR timing | Render 150 DPI, jalankan RapidOCR, log timing & success rate | Script jalan, show duration per page, total time, failed page count |
| ✓ | Development | Task 6: Create Common Utilities | Implement `common.py` dengan logging helper, file utils | Shared logger, result formatter, exception handler | Module importable, logging output structured |
| ✓ | Execution | Task 7: Run Harness 1 on Target File | Jalankan `harness1_pymupdf_raw.py` pada target file | Verify baseline: apakah PyMuPDF raw bisa ekstrak content | Output menunjukkan total chars > 0, atau clear answer tentang file state |
| ✓ | Execution | Task 8: Run Harness 2 on Target File | Jalankan `harness2_pymupdf4llm_variants.py` pada target file | Test parameter sensitivity: identifikasi config mana yang work | Output menunjukkan 5 config results, minimal 1 clear winner atau semua ❌ |
| ✓ | Execution | Task 9: Run Harness 3 on Target File | Jalankan `harness3_perpage_ocr.py` pada target file | Measure OCR fallback viability: timing & reliability | Output menunjukkan per-page duration, total time, failed pages % |
| ✓ | Analysis | Task 10: Collect & Organize Results | Simpan output ketiga harness ke `debugging-results/` | Dokumentasi terstruktur untuk reference | File `.log` tersimpan, readable dengan clear structure |
| ✓ | Analysis | Task 11: Preliminary Analysis | Buat `preliminary_analysis.md` berisi hasil harness + decision tree evaluation | Analisis hasil berdasarkan methodology decision matrix | Doc jelas menunjukkan: mana config work, OCR timing apakah viable |
| ✓ | Analysis | Task 12: Final Recommendation | Buat `analysis_summary.md` dengan final keputusan & recommended actions | Tentukan: parameter fix, library workaround, atau fallback strategy | Rekomendasi specific (mis: "gunakan margins=(0,0,0,0)") |

---

## Catatan Eksekusi

- **Durasi Target:** Phase 1-4 selesai dalam satu session (1-2 jam untuk full debug)
- **Output Expected:** 3 file hasil harness + 2 markdown analysis
- **Next Phase:** Implementasi fix akan diplan terpisah berdasarkan hasil debugging ini
- **File Target Contoh:** `Literature/Reviving Life on the Edge Joint Score-Based Graph Generation of Rich Edge Attributes.pdf`

---

**Status: READY FOR EXECUTION**

Tunggu instruksi Anda untuk memulai development harness (Task 1 harus dikerjakan terlebih dahulu).
