# Rencana Implementasi Skrip Benchmark Chunking Modular

## 1. Judul
**Rencana Implementasi Skrip Benchmark Chunking Modular untuk Evaluasi Hierarchical (Parent-Child) Text Splitting**

## 2. Tanggal
Rabu, 13 Mei 2026

## 3. Deskripsi
Dokumen ini mendefinisikan rancangan (*blueprint*) untuk pengembangan dan pengujian skrip *benchmarking* mandiri proses "Chunking" pada arsitektur RAG. Skrip ini secara khusus akan menguji fungsi `generate_parent_child_chunks` yang berada pada modul `app/services/parser/smart_chunker.py`. Input skrip berasal dari dokumen `.md` hasil *parsing* sebelumnya, kemudian skrip akan memecah dokumen tersebut menjadi blok-blok besar (*Parent Chunks*) dan blok-blok kecil (*Child Chunks*), dan menyimpannya ke dalam format JSON. Proses ini dilengkapi dengan pemantauan *hardware* (RAM & CPU), durasi eksekusi, serta metrik kualitas struktural (rata-rata ukuran *chunk* dan rasio pelestarian *header*). Tujuan akhir metrik ini adalah memastikan *chunk* yang dihasilkan berkualitas cukup tinggi untuk memfasilitasi proses Retrieval di tahap selanjutnya.

## 4. Metodologi
Pengujian ini dirancang berdasarkan prinsip berikut:
1. **Modular & Isolated Testing:** Pemisahan *concern* absolut. Skrip *chunking* berdiri sendiri dan terpisah dari skrip *retrieval* untuk melokalisir sumber anomali.
2. **Strict Constraint:** Dilarang keras melakukan modifikasi atau mutasi *codebase* asli pada direktori `app/`. Semua implementasi berada murni di dalam ranah `scripts/Testing-Pipeline/`.
3. **Real-Time Incremental Logging (Append-Only):** Penulisan log ke tabel Markdown metrik secara sebaris tiap kali satu dokumen selesai di-chunk, untuk mencegah kehilangan data jika terjadi *crash* memori (OOM).
4. **Hardware Profiling:** Penggunaan modul bawaan `psutil` untuk memantau performa sistem secara seketika (*Peak RSS RAM* & *Peak CPU Utilization*).
5. **Artifact Segregation:** Pemisahan ketat direktori penyimpanan *output* ke dalam tiga entitas: penyimpanan data *chunk* terstruktur (JSON), log *error* sistem, dan log performa matriks (Markdown).

## 5. Keputusan
1. **Pemisahan Skrip:** Skrip Chunking diisolasi dari skrip Retrieval menjadi skrip tunggal `benchmark_chunking.py`.
2. **Target Fungsi:** Memanggil fungsi `generate_parent_child_chunks` dengan nilai parameter standar (Parent size: 1500, overlap: 150. Child size: 200, overlap: 20).
3. **Penyimpanan Format Output:** Hasil pemotongan dari `generate_parent_child_chunks` menghasilkan tuple yang berisi List of Dictionary untuk Parent dan Child. Output akan diserialisasi dan disimpan sebagai format `.json` untuk memudahkan skrip *retrieval* nantinya membaca metadata struktur objek tersebut tanpa *parsing* ulang.
4. **Evaluasi Semantik Header:** Pengenalan metrik `P-HEADER RATE` yang mengkalkulasi persentase dari *Parent Chunks* yang berhasil mempertahankan nilai string non-kosong pada properti `metadata_header`. Ini adalah kunci utama indikator kesuksesan tahapan *chunking*.

## 6. Alur Diagram
```mermaid
flowchart TD
    classDef init fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef logic fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef io fill:#fff3e0,stroke:#f57c00,stroke-width:2px;

    Start[Mulai Benchmark Chunking]:::init --> InitDirs[Inisialisasi Direktori Output, Matrix, Error]:::init
    InitDirs --> ReadMD[Baca File Markdown dari Output-Parsing/]:::io
    ReadMD --> SetupProfiler[Mulai Timer & Catat Awal RAM/CPU]:::logic
    SetupProfiler --> CallChunker[Panggil generate_parent_child_chunks]:::logic
    
    CallChunker -- Sukses --> MeasureChunks[Hitung Ukuran & Rasio Header P-Chunks/C-Chunks]:::logic
    CallChunker -- Exception --> LogErr[Tulis Exception ke chunking_errors.log]:::io
    LogErr --> EndProfilerErr[Hentikan Timer & Catat Akhir RAM/CPU]:::logic
    EndProfilerErr --> WriteMatFail[Append Status Failed ke Matrix]:::io
    
    MeasureChunks --> WriteJSON[Simpan P-Chunks & C-Chunks ke format .json]:::io
    WriteJSON --> EndProfiler[Hentikan Timer & Catat Akhir RAM/CPU]:::logic
    EndProfiler --> WriteMatSucc[Append Baris Matriks ke performance_matrix_chunking.md]:::io
    
    WriteMatFail --> NextFile{Ada File Lain?}:::logic
    WriteMatSucc --> NextFile
    NextFile -- Ya --> ReadMD
    NextFile -- Tidak --> Finish[Selesai]:::init
```

## 7. Struktur Folder (Tree)
```text
/home/daegir/Documents/PERCOBAAN/backend-sre(prompt-modularization-v3)/backend-sre/
├── scripts/
│   └── Testing-Pipeline/
│       └── benchmark_chunking.py           # Skrip utama yang akan dibangun
├── archive/
│   └── Testing-Pipeline/
│       └── benchmark-chunking/
│           ├── Perform-Matrix/
│           │   └── performance_matrix_chunking.md  # Tempat penyisipan tabel metrik
│           ├── Log-Error/
│           │   └── chunking_errors.log             # Log file jika ada fungsi chunker yang crash
│           └── Output-Chunking/                    # Menyimpan hasil fungsi chunk dalam format .json
│               ├── RAGAS_Automated_Evaluation..._chunked.json
│               └── SciLit_Joint_Literature..._chunked.json
└── Markdown/
    └── Testing-Pipeline/
        └── Chunking-Benchmark/
            ├── Plan/
            │   └── chunking_benchmark_plan.md      # Dokumen Rencana ini
            ├── Execution-Log/                      # Direktori dokumentasi langkah saat eksekusi
            └── Report/                             # Laporan Akhir setelah eksekusi selesai
```

## 8. Asumsi & Batasan
1. Fungsi `generate_parent_child_chunks` pada file `app/services/parser/smart_chunker.py` diasumsikan berjalan dengan baik dan stabil secara fungsionalitas, tidak boleh diubah sedikitpun *source code* nya.
2. File *Markdown* yang menjadi target pengujian adalah eksklusif yang terdapat di dalam struktur `archive/Testing-Pipeline/benchmark-parsing/Output-Parsing/`.
3. Keberhasilan retensi konteks semantik sepenuhnya bergantung pada kapabilitas `MarkdownHeaderTextSplitter` dari _library_ `langchain_text_splitters`.
4. Jika perhitungan `P-HEADER RATE` menunjukkan angka yang terlalu rendah (mendekati 0%), maka itu dianggap sebagai sebuah *finding* yang harus didokumentasikan di *Report* akhir, bukan ditambal (*patch*) dengan meretas (*hack*) parameter skrip penguji.

## 9. Konsep Tabel Metriks
Matriks performa menggunakan format yang disepakati untuk kemudahan pembacaan dan analisis struktur data:

| TIMESTAMP | DOCUMENT | TOTAL PARENT CHUNK | TOTAL CHILD CHUNK | P-CHUNK AVERAGE SIZE (CHAR) | C-CHUNK AVERAGE SIZE (CHAR) | P-HEADER RATE | RAM | CPU | TIME (s) | STATUS | NOTE |
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :--- | :--- |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |

*Definisi Metrik:*
* **P-CHUNK AVERAGE SIZE (CHAR):** Total panjang karakter seluruh *content* pada Parent Chunks dibagi jumlah Parent Chunks.
* **C-CHUNK AVERAGE SIZE (CHAR):** Total panjang karakter seluruh *content* pada Child Chunks dibagi jumlah Child Chunks.
* **P-HEADER RATE:** Persentase jumlah *Parent Chunks* yang mana kunci `"metadata_header"` di dalamnya berisi string bukan kosong, dibagi dengan Total Parent Chunks.

## 10. Konsep Prompting
Proses **Chunking** ini bersifat murni prosedural deterministik (*Rule-based*) dengan mengeksekusi algoritma pembagian string menggunakan `MarkdownHeaderTextSplitter` dan `RecursiveCharacterTextSplitter`.
**Oleh karena itu, tidak ada Prompting berbasis LLM (Large Language Model) pada fase Chunking ini.** 

*Catatan untuk Fase Lanjutan (Retrieval):* 
Skrip Chunking ini akan mempersiapkan data (`metadata_header` dan hierarki *Parent-Child*) secara absolut agar dapat dikonsumsi oleh Prompt Evaluasi di fase Retrieval nantinya. Konsep *prompting* yang akan dirancang di fase *retrieval* bertujuan mencari elemen *"Latar Belakang, Gap, Metodologi, Tujuan, Future Works"* dan akan sangat bertumpu pada `metadata_header` yang diamankan pada fase chunking ini. Rancangan Prompt spesifik untuk Retrieval akan dibuat saat kita menyusun *Blueprint Plan* untuk *Retrieval Benchmark*.

## 11. Langkah Implementasi
1. Inisialisasi folder untuk *Output*, *Log*, *Matrix*, dan *Execution Logs* melalui CLI.
2. Pengembangan kode `benchmark_chunking.py` mengadaptasi kerangka kerja `benchmark_parsing.py`.
3. Menyusun modul internal pengekstrakan rata-rata karakter dan penghitungan persentase metadata *header*.
4. Pengujian *dry-run* pertama pada dua *file* .md yang tersedia.
5. Pembuatan Laporan Eksekusi dan Pelaporan Akhir berdasarkan pengamatan terhadap `P-HEADER RATE`.

## 12. Tabel Eksekusi Task

| Check Box | Fase | Task | Detail Task | Deskripsi | Acceptance Criteria |
| :---: | :--- | :--- | :--- | :--- | :--- |
| [x] | Phase 1: Preparation | 1.1 Create Directories | Membangun seluruh hierarki *folder* artifak | Menggunakan `mkdir -p` untuk membuat direktori arsip metrik, arsip *output* (*JSON*), arsip error, log eksekusi, serta log *report* khusus tahap *Chunking Benchmark*. | Direktori `archive/Testing-Pipeline/benchmark-chunking/` dan `Markdown/Testing-Pipeline/Chunking-Benchmark/` berserta anak subdirektorinya berhasil terbuat tanpa error. |
| [x] | Phase 2: Scripting | 2.1 File Skeleton & Import | Menulis *boilerplate* `benchmark_chunking.py` | Menginisialisasi *file* Python di dalam `scripts/Testing-Pipeline/` lalu mengatur modul impor `sys`, `os`, `json`, `time`, `psutil`, `logging`, dan melakukan *relative import* ke modul *smart chunker* aplikasi `app.services.parser.smart_chunker`. | Skrip Python dapat mengeksekusi modul `smart_chunker` dan fungsi `generate_parent_child_chunks` tanpa menimbulkan pesan `ModuleNotFoundError`. |
| [x] | Phase 2: Scripting | 2.2 I/O Handlers | Mengatur *Input* dan *Output* File | Menulis fungsi membaca dokumen `.md` dari direktori `archive/.../Output-Parsing/` dan menyatukan hasilnya menggunakan struktur JSON (`json.dump`) ke direktori `Output-Chunking`. | Teks *Markdown* berhasil dibaca dengan baik, dan file berakhiran `_chunked.json` mampu menyimpan konfigurasi tipe data `List[Dict]` hasil *return* fungsi. |
| [x] | Phase 2: Scripting | 2.3 Profiling Logic | Menyusun fungsi penangkap metrik | Menempatkan *profiler* CPU dan RAM (`psutil.Process()`) dan penghitungan waktu iteratif di sekitar blok fungsi pemanggil `generate_parent_child_chunks`. Menyusun kalkulator rata-rata panjang *string* properti `content` dari struktur *output*, serta menghitung rasio string terisi pada `metadata_header` untuk *Parent Chunks*. | Output perhitungan akurat: `Total P-Chunk`, `Total C-Chunk`, `P/C Average Size`, dan persentase `P-HEADER RATE`. |
| [x] | Phase 2: Scripting | 2.4 Metrics Logger | Menulis *Appending Table Logic* | Membuat fungsi `log_performance_matrix` yang membuat atau menempelkan (append) tabel Markdown dengan struktur kolom berjumlah 12. | Header pada Markdown file tidak mengalami perulangan. Baris iterasi baru langsung tertempel rapi di bagian bawah tabel. |
| [x] | Phase 3: Execution | 3.1 Dry-Run Single File | Menguji eksekusi iterasi ke-1 | Mengarahkan skrip pengujian pada *file* `RAGAS_Automated_..._parsed.md`. Mengobservasi CLI untuk potensi terjadinya *crash*. Mencatat Log Eksekusi. | Dokumen RAGAS memproduksi berkas `_chunked.json`. Log `performance_matrix_chunking.md` ter-append satu baris sukses. |
| [x] | Phase 3: Execution | 3.2 Execute All | Menguji seluruh dokumen *parsing* yang ada | Melakukan eksekusi total untuk *file* sekunder `SciLit_Joint_..._parsed.md`. | Berkas `performance_matrix_chunking.md` terisi penuh baris-baris sesuai dengan iterasi perulangan tanpa kehilangan data jika salah satunya memicu limit memori atau timeout. |
| [x] | Phase 4: Reporting | 4.1 Log & Report Creation | Menyusun dokumen eksekusi dan rilis akhir | Menyalin struktur kerangka *Final Report* dan menguraikan analisa dari rasio `P-HEADER RATE` pada berkas-berkas sampel uji coba tersebut, beserta lonjakan RAM dan CPU. | Dokumen log eksekusi dan `Final_Report_Chunking_Benchmark.md` terbentuk dan ditinjau komprehensif oleh engineer. |
