# Rencana Implementasi Skrip Benchmark Retrieval Modular

## 1. Judul
**Rencana Implementasi Skrip Benchmark Retrieval Modular dengan Pendekatan Hybrid (Cosine Score & Human Verification)**

## 2. Tanggal
Rabu, 13 Mei 2026

## 3. Deskripsi
Dokumen ini mendefinisikan rancangan (*blueprint*) untuk pengembangan dan pengujian skrip *benchmarking* mandiri proses "Retrieval" pada arsitektur RAG. Skrip ini secara khusus akan menguji kelas `SemanticRetriever` dan fungsi `find_top_k_parents` yang berada pada modul `app/services/parser/semantic_retriever.py`. Input skrip berasal dari dokumen `.json` hasil *chunking* sebelumnya. Skrip akan mengonversi *Child Chunks* menjadi vektor (*embedding*) menggunakan model lokal *SentenceTransformer* (`all-MiniLM-L6-v2`), lalu membandingkannya dengan 5 kueri pilar (*Latar Belakang, Metodologi, Gap, Tujuan, Future Works*) untuk mencari *Top 3 Parent Chunks* paling relevan secara semantik. Proses ini dievaluasi dengan pendekatan *Hybrid*, di mana model matematis memberikan skor *Cosine Similarity*, sedangkan verifikasi semantik dilakukan oleh manusia melalui *output file* Markdown yang ramah baca (Human Verification).

## 4. Metodologi
Pengujian ini dirancang berdasarkan prinsip berikut:
1. **Modular & Isolated Testing:** Pemisahan *concern* absolut. Skrip *retrieval* berdiri sendiri dan tidak terkoneksi ke *database* eksternal (Supabase/Neo4j). Proses pencarian vektor dilakukan secara *in-memory* menggunakan `numpy`.
2. **Hybrid Verification:** Menggabungkan pencatatan *Cosine Similarity Score* murni dari algoritma, dipadukan dengan pembuatan artifak Markdown khusus untuk memudahkan inspeksi visual (Human Verification) guna membuktikan relevansi semantik.
3. **Strict Constraint:** Dilarang keras melakukan modifikasi atau mutasi *codebase* asli pada direktori `app/`. Semua penyesuaian *output* dilakukan di ranah `scripts/Testing-Pipeline/`.
4. **Real-Time Incremental Logging (Append-Only):** Penulisan log ke tabel Markdown metrik secara sebaris tiap kali satu dokumen selesai di-retrieval, untuk mencegah kehilangan data.
5. **Hardware Profiling:** Penggunaan modul bawaan `psutil` untuk memantau performa sistem secara seketika (*Peak RSS RAM* & *Peak CPU Utilization*), beserta timer presisi untuk proses *embedding* dan *search*.

## 5. Keputusan
1. **Dual Output Format:** Skrip akan menghasilkan dua wujud *output* untuk setiap dokumen:
   - **File JSON (`_retrieval_results.json`):** Berisi data terstruktur untuk persiapan testing selanjutnya.
   - **File Markdown (`_human_verification.md`):** Berisi teks artikel dari 3 *chunk* teratas per pilar untuk dibaca dan dinilai oleh manusia.
2. **Penyederhanaan LLM:** Tidak menggunakan *LLM-as-a-judge* (seperti GPT) untuk menilai relevansi guna menghemat biaya API dan waktu komputasi.
3. **Target Iterasi:** Mengambil *file* input dari direktori `archive/Testing-Pipeline/benchmark-chunking/Output-Chunking/` secara *batch*.
4. **Metrik Skor Gabungan:** Matriks performa akan mencatat nilai rata-rata *Cosine Similarity* dari Top 3 Chunk untuk kelima pilar dalam satu kolom `AVG SCORE (BG/MET/GAP/OBJ/FUT)`.

## 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 Retrieval"]:::init --> InitDirs["Inisialisasi Direktori Output, Matrix, Error"]:::init
    InitDirs --> ReadJSON["Baca File JSON dari Output-Chunking/"]:::io
    ReadJSON --> SetupModel["Load SemanticRetriever & SentenceTransformer"]:::logic
    SetupModel --> TimerEmbed["Mulai Timer Embed"]:::logic
    TimerEmbed --> RunEmbed["Embed Child Chunks ke Vector"]:::logic
    RunEmbed --> TimerSearch["Stop Timer Embed, Mulai Timer Search"]:::logic
    TimerSearch --> CallRetriever["Panggil find_top_k_parents (top_k=3)"]:::logic
    
    CallRetriever -- Sukses --> CalcScore["Hitung Cosine Similarity & Rata-rata Skor per Pilar"]:::logic
    CallRetriever -- Exception --> LogErr["Tulis Exception ke retrieval_errors.log"]:::io
    LogErr --> EndProfilerErr["Hentikan Profiler & Catat Akhir RAM/CPU"]:::logic
    EndProfilerErr --> WriteMatFail["Append Status Failed ke Matrix"]:::io
    
    CalcScore --> MatchParents["Cocokkan ID dengan Teks Parent Chunks Asli"]:::logic
    MatchParents --> WriteMD["Tulis Output Human Verification (.md)"]:::io
    WriteMD --> WriteJSONOut["Tulis Output Programmatic (.json)"]:::io
    WriteJSONOut --> EndProfiler["Hentikan Timer Search & Catat Akhir RAM/CPU"]:::logic
    EndProfiler --> WriteMatSucc["Append Baris Matriks ke performance_matrix_retrieval.md"]:::io
    
    WriteMatFail --> NextFile{"Ada File Lain?"}:::logic
    WriteMatSucc --> NextFile
    NextFile -- Ya --> ReadJSON
    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_retrieval.py                  # Skrip utama yang akan dibangun
├── archive/
│   └── Testing-Pipeline/
│       └── benchmark-retrieval/
│           ├── Perform-Matrix/
│           │   └── performance_matrix_retrieval.md # Tempat penyisipan tabel metrik
│           ├── Log-Error/
│           │   └── retrieval_errors.log            # Log file jika crash
│           ├── Output-JSON/                        # Output terstruktur JSON
│           │   ├── RAGAS..._retrieval_results.json
│           │   └── SciLit..._retrieval_results.json
│           └── Output-Human-Verification/          # Output Markdown ramah baca
│               ├── RAGAS..._human_verification.md
│               └── SciLit..._human_verification.md
└── Markdown/
    └── Testing-Pipeline/
        └── Retrieval-Benchmark/
            ├── Plan/
            │   └── retrieval_benchmark_plan.md     # Dokumen Rencana ini
            ├── Execution-Log/                      # Direktori dokumentasi langkah saat eksekusi
            └── Report/                             # Laporan Akhir setelah eksekusi selesai
```

## 8. Asumsi & Batasan
1. Kelas `SemanticRetriever` pada `app/services/parser/semantic_retriever.py` tidak akan diubah sedikitpun.
2. Proses *embedding* menggunakan CPU lokal (tanpa GPU). Memori (RAM) akan terpantau cukup tinggi saat memuat model *SentenceTransformer* `all-MiniLM-L6-v2`.
3. Validasi kebenaran semantik dilakukan secara manual oleh manusia melalui file `.md` yang dihasilkan. Evaluator manusia yang akan memutuskan apakah konteks yang ditarik oleh algoritma *Cosine Similarity* benar-benar menjawab pilar yang dicari.

## 9. Konsep Tabel Metriks
Matriks performa untuk mengevaluasi komputasi vektor dan performa pencarian:

| TIMESTAMP | DOCUMENT | CHUNKS EMBEDDED | EMBED TIME (s) | SEARCH TIME (s) | AVG SCORE (BG/MET/GAP/OBJ/FUT) | RAM | CPU | STATUS | NOTE |
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :--- | :--- |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |

*Definisi Metrik Khusus:*
* **CHUNKS EMBEDDED:** Total *Child Chunks* dari dokumen yang dikonversi ke dalam vektor *embedding*.
* **EMBED TIME (s):** Waktu murni yang dihabiskan model lokal untuk melakukan *encoding* teks ke vektor.
* **SEARCH TIME (s):** Waktu murni untuk mengalkulasi *Cosine Similarity* antara 5 kueri dengan seluruh vektor *chunk*.
* **AVG SCORE:** Rata-rata dari skor *Cosine Similarity* untuk *Top 3 Parent Chunks* yang terpilih, direpresentasikan dalam format berderet `BG / MET / GAP / OBJ / FUT` (Misal: `0.75 / 0.81 / 0.65 / 0.77 / 0.60`). Ini membantu mengidentifikasi pilar mana yang sering mendapat skor semantik terendah.

## 10. Konsep Prompting (Query Texts)
Meskipun pengujian ini **tidak menggunakan LLM (seperti GPT)** untuk generasi teks, pencarian ruang vektor ini bergantung sepenuhnya pada teks kueri (sebagai *prompt* semantik). Berikut adalah teks yang akan disuntikkan secara harfiah (*hardcoded*) untuk dicari padanannya di dalam *Child Chunks*:

```python
query_texts = [
    "Latar belakang, masalah, dan motivasi penelitian ini. Background, research problem, motivation, context, introduction, underlying issue.",
    "Metode, pendekatan, arsitektur, algoritma, eksperimen, atau dataset yang digunakan. Methodology, proposed method, approach, system architecture, dataset, materials, experimental setup, procedure.",
    "Gap penelitian, keterbatasan, kelemahan, atau masalah yang belum terselesaikan. Research gap, limitations, weakness, unresolved problem, remains a challenge, yet to be explored, however.",
    "Tujuan utama, sasaran, atau pertanyaan penelitian yang ingin dijawab. Main objective, research goal, purpose of this study, aims to investigate, to evaluate, this paper proposes.",
    "Pekerjaan di masa depan, saran untuk peneliti lain, atau langkah selanjutnya. Future work, recommendations, future research directions, next steps, further investigation."
]
```
*(Catatan: Kueri ini dieksekusi secara berurutan: Index 0 = Background, 1 = Methodology, 2 = Gap, 3 = Objective, 4 = Futurework)*

## 11. Langkah Implementasi
1. Inisialisasi struktur *folder* di `archive/` dan `Markdown/`.
2. Pengembangan `benchmark_retrieval.py` yang memuat fungsi pembacaan berkas JSON *output* dari skrip *chunking*.
3. Pembuatan logika ekstraksi skor *Cosine Similarity* independen (mendaur ulang fungsi dari `SemanticRetriever` namun mengembalikan *return* tambahan skor untuk keperluan evaluasi). Karena ada *strict constraint*, modifikasi kalkulasi skor akan dilakukan melalui *wrapper* di dalam skrip penguji tanpa menyentuh *source code* `app`.
4. Pembuatan *generator* dokumen Markdown untuk *Human Verification*.
5. Pengujian *dry-run*, eksekusi keseluruhan (*bulk*), dan penyusunan *Final Report*.

## 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 shell CLI untuk membangun folder JSON, Markdown (*Human Verification*), Matriks Performa, Log Error, dan folder dokumentasi Markdown `Retrieval-Benchmark`. | Direktori tujuan berhasil dibuat tanpa error. |
| [x] | Phase 2: Scripting | 2.1 File Skeleton & Import | Menulis *boilerplate* `benchmark_retrieval.py` | Menginisialisasi *file* Python, *import* `json`, `numpy`, `time`, `psutil`, `logging`. Mengatur `sys.path` dan memanggil kelas `SemanticRetriever` dari `app.services.parser.semantic_retriever`. | Skrip dapat melakukan *import* kelas `SemanticRetriever` tanpa `ModuleNotFoundError`. |
| [x] | Phase 2: Scripting | 2.2 Model & I/O Setup | Setup Model & Pembacaan JSON | Membuat fungsi yang meload berkas `..._chunked.json` dari direktori tahapan sebelumnya, lalu menginisialisasi instance `SemanticRetriever()`. | Model *SentenceTransformer* dapat termuat dengan baik dan data `parent_chunks` serta `child_chunks` terurai ke dalam memori Python. |
| [x] | Phase 2: Scripting | 2.3 Retrieval & Scoring Logic | Eksekusi Pencarian Top 3 & Kalkulasi Avg Score | Membungkus proses *embedding* `_embed_batch` dan *searching* `find_top_k_parents` dengan pencatat waktu (timer) terpisah. Menghitung rata-rata skor kemiripan untuk Top 3 dari tiap 5 Pilar (BG/MET/GAP/OBJ/FUT). | Mendapatkan 5 daftar `parent_id` (masing-masing 3 ID) beserta nilai rata-rata *cosine similarity*-nya. |
| [x] | Phase 2: Scripting | 2.4 Artifact Generation | Membuat Log JSON dan Human Verif Markdown | Menggabungkan teks utuh dari *Parent Chunks* berdasarkan *ID* yang terpilih ke dalam format Markdown vertikal yang ramah dibaca mata. Lalu menulis data *array* murninya ke berkas `.json`. | Menghasilkan dua jenis berkas luaran (`_human_verification.md` dan `_retrieval_results.json`) dengan susunan isi yang tepat sasaran. |
| [x] | Phase 2: Scripting | 2.5 Metrics Logger | Menulis Tabel Append-Only | Meneruskan tradisi *fail-safe logging* dengan menuliskan baris data komputasi memori, CPU, *time*, dan skor *cosine* ke file `performance_matrix_retrieval.md`. | Baris matriks tercetak rapi secara format dan tidak menumpuk *header* tabel. |
| [x] | Phase 3: Execution | 3.1 Dry-Run Single File | Menguji dokumen `RAGAS` | Melakukan eksekusi pada 1 target *file*. Memeriksa apakah OOM terjadi karena model lokal *SentenceTransformer* dan memvalidasi tampilan *output* `.md`. | Pengujian sukses mencatat 1 baris matriks, *file error* kosong. Menghasilkan artefak *Human Verification* yang koheren. |
| [x] | Phase 3: Execution | 3.2 Execute All | Menguji seluruh dokumen *JSON* yang tersedia | Mengeksekusi sisa *file* (seperti `SciLit`). | Seluruh matriks terisi lengkap. Proses stabil dan memori termanajemen dengan baik (tidak *memory leak* dari iterasi ke iterasi). |
| [x] | Phase 4: Reporting | 4.1 Log & Report Creation | Menyusun laporan akhir | Membuat dokumen `Final_Report_Retrieval_Benchmark.md` sesuai format V3, merangkum efisiensi skor semantik, waktu komputasi model, dan evaluasi hasil *Human Verification*. | Final Report terdokumentasi komprehensif, siap untuk dilaporkan. |
