# Universal Blueprint (Template)

## 1. Metadata & Context
* **Title:** Optimasi Multilingual Retrieval & Implementasi Kueri Semantik Kepadatan Jangkar (V3)
* **Date:** 15-05-2026
* **Objective:** Mengganti model embedding lokal ke `intfloat/multilingual-e5-small` dan menerapkan **Metode C (Anchor-Density Strategy)** beserta pemurnian data ekstrem (Data Purification V2) untuk menyelesaikan masalah akurasi retrieval pada literatur multilingual.
* **Methodology:**
  1. Penggantian model embedding di `semantic_retriever.py` dengan prefix injection dinamis (`query:` dan `passage:`).
  2. Implementasi penjagaan batas token (max 512 tokens) sebelum proses embedding untuk menghindari silent truncation.
  3. Mengganti skema A/B testing (yang terbukti gagal) menjadi evaluasi tunggal untuk **Metode C** melalui `benchmark_retrieval_c.py`.
  4. **Data Purification Layer V2:** Sanitasi data secara *on-the-fly* di dalam skrip pengujian menggunakan *Blacklist Header* yang diperluas dan heuristik isi paragraf (anti-afiliasi, anti-referensi, anti-tabel/OCR) demi membersihkan ruang vektor.
* **Assumptions & Constraints:** 
  * RAM server kuat menampung model E5-Small (~470MB). Dimensi ruang vektor tetap 384D sehingga tidak merusak skema numpy yang sudah ada.
  * *Constraint:* Pengujian dilakukan secara offline di lingkungan skrip benchmark, dilarang menyentuh `ingestion.py` utama sampai kandidat C diverifikasi oleh pengguna.
* **Strategic Decider:**
  | Option/Decision | Alternatives | Rationale | Status |
  | :--- | :--- | :--- | :--- |
  | Migrasi ke `intfloat/multilingual-e5-small` | Bertahan di `all-MiniLM-L6-v2` | MiniLM buta terhadap struktur dwibahasa dan hanya optimal untuk Bahasa Inggris murni. | **Locked** |
  | Prefix Injection (`query:` / `passage:`) pada saat Runtime | Hardcode di struktur JSON raw data | Mencegah polusi prefix saat kumpulan *Parent Chunks* disatukan (stuffed) dan dikirim ke LLM (mencegah prompt injection ke Qwen). | **Locked** |
  | Kueri Metode C (Anchor-Density) | Metode A (Q&A) atau Metode B (HyDE statis) | Metode A dan B gagal menangkap pilar Gap dan Future Work akibat gaya bahasa jurnal yang tidak beraturan. Metode C membombardir *dense retriever* dengan kumpulan kata kunci teknis (*Lexical Anchors*) tanpa format kalimat utuh, meringankan beban kognitif model 384D. | **Locked** |
  | Data Purification V2 (Agresif) | Filter Header Biasa | Keterbatasan pengenalan *header* menyebabkan kebocoran *Acknowledgments* dan *References*. Purifikasi V2 menginterogasi isi paragraf untuk menemukan pola daftar pustaka terselubung dan menghancurkannya sebelum di-*embed*. | **Locked** |

* **Knowledge Provenance:**
  | Research Topic | Tool (Context7/MCP) | Key Findings | Result |
  | :--- | :--- | :--- | :--- |
  | Kelemahan Dense Retrieval pada Istilah Teknis | Google Web Search | Model E5-Small mengaburkan istilah teknis ke dalam makna umum. Direkomendasikan untuk menargetkan ruang vektor menggunakan kepadatan kata benda teknis (*Lexical/Semantic Anchors*) ketimbang kalimat naratif. | Formulasi Kueri Metode C (Pilar Metodologi). |
  | Ekstraksi Research Gap | Google Web Search (SciFact/SciEvent) | Gap jarang ditulis secara eksplisit. Gap disembunyikan dalam "Inconclusive Findings". *Skeptical Prompting* dengan *adversarial anchors* ("namun demikian", "belum jelas") diperlukan. | Formulasi Kueri Metode C (Pilar Gap). |

## 2. Structure & Dependencies
* **Folder Tree:** 
```text
/home/daegir/Documents/PERCOBAAN/backend-sre(prompt-modularization-v3)/backend-sre/
├── requirements.txt
├── app/
│   └── services/
│       └── parser/
│           └── semantic_retriever.py    # (TARGET: Update Model & Prefix Logic)
├── scripts/
│   └── Testing-Pipeline/
│       └── benchmark_retrieval_c.py     # (TARGET: Anchor-Density & Data Purification V2)
└── Markdown/
    ├── small-to-big-retrieval/
    │   └── Execution-Log/
    │       └── query-optimization-v3-log.md
    └── Query-Optimization-v3/
        └── Plan/
            └── query-optimization-v3-plan.md  # (FILE INI)
```
* **Dependency Graph:** 
  | Affected File | Main Module | Impact |
  | :--- | :--- | :--- |
  | `semantic_retriever.py` | `app.services.parser` | Mengubah *engine* lokal dan menyisipkan perlindungan *max_length* serta *prefix*. |

## 3. Concept & Logic
* **Flow Diagram (Mermaid):** 
```mermaid
flowchart TD
    classDef test fill:#fff3e0,stroke:#f57c00,stroke-width:2px;
    classDef logic fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    
    A[Child Chunks JSON] --> P[Data Purification V2: Anti-Refs, OCR, & Affiliations]:::logic
    P --> B[Prefix Injection 'passage: ']:::logic
    B --> C[Truncate to Token Limit Guard]:::logic
    C --> D[E5-Small Model Embedding]:::logic
    
    Q["5 Kueri Pilar: Metode C <br> (Lexical Anchors)"] --> E[Prefix Injection 'query: ']:::logic
    E --> F[E5-Small Model Embedding]:::logic
    
    D --> S{Cosine Similarity & Top-K=3}:::logic
    F --> S
    
    S --> T["benchmark_retrieval_c.py<br>Evaluasi Kinerja Metode C"]:::test
```

* **Execution Synopsis:** 
  | Intent | Goal | Step | Status |
  | :--- | :--- | :--- | :--- |
  | Model Swap | Mengganti `MiniLM` ke `multilingual-e5-small`. | Update `semantic_retriever.py`. | Done |
  | Prefix Isolation | Mencegah kontaminasi prefix ke LLM. | Suntik prefix secara *on-the-fly* di metode `_embed_batch`. | Done |
  | Refactor Testing | Mengganti A/B test menjadi evaluasi Metode C. | Setup `benchmark_retrieval_c.py` dengan kueri jangkar. | Done |
  | Data Purification V2 | Membersihkan ruang vektor secara ekstrem. | Terapkan Regex untuk OCR dan *heuristic filtering* (anti-afiliasi & anti-referensi) di skrip pengujian. | Done |
  | Evaluasi C | Memastikan keampuhan *Anchor-Density*. | Jalankan `benchmark_retrieval_c.py` dan periksa *Human Verification*. | In Progress |

* **Prompting Concept:** 
  **[KANDIDAT A] Sintesis Q&A + Deklaratif (Usang):**
  1. `Penelitian ini dilatarbelakangi oleh urgensi masalah, konteks situasi saat ini, serta motivasi mendasar yang mendorong perlunya dilakukan kajian.`
  2. `Tahapan penelitian, arsitektur sistem, desain eksperimen, dan prosedur pengujian dieksekusi menggunakan metodologi teknis berikut.`
  3. `Apa kelemahan, keterbatasan ruang lingkup, atau masalah spesifik pada metode penelitian terdahulu yang belum terselesaikan?`
  4. `Apa tujuan utama, sasaran akhir, atau kontribusi spesifik yang dihasilkan oleh penelitian ini untuk menyelesaikan masalah tersebut?`
  5. `Apa saran, rekomendasi penelitian lanjutan, atau agenda di masa depan yang diusulkan oleh penulis untuk mengatasi keterbatasan studi saat ini?`

  **[KANDIDAT B] HyDE Pseudo-Answer (Usang):**
  1. `Fenomena ini merupakan isu krusial. Oleh karena itu, studi ini dilakukan untuk merespons urgensi permasalahan yang melatarbelakangi penelitian.`
  2. `Penelitian ini menggunakan pendekatan terstruktur di mana data dikumpulkan dan analisis dilakukan menggunakan teknik serta metode yang dijelaskan pada bagian ini.`
  3. `Meskipun banyak studi telah dilakukan, masih terdapat kekosongan literatur (gap), kelemahan, dan batasan pada penelitian sebelumnya yang belum dieksplorasi.`
  4. `Tujuan utama dan sasaran spesifik dari artikel ini adalah untuk memberikan kontribusi baru, mengeksplorasi, dan menyelesaikan permasalahan tersebut.`
  5. `Keterbatasan dalam penelitian ini membuka peluang bagi studi selanjutnya. Penelitian di masa depan disarankan untuk memperluas cakupan dan menyelesaikan isu terkait.`

  **[KANDIDAT C] The Anchor-Density Strategy (Lexical Anchors - Pemenang):**
  1. `latar belakang masalah, urgensi penelitian, motivasi mendasar, fenomena krusial, konteks situasi saat ini, dan alasan utama studi ini dilakukan.`
  2. `rincian teknis metodologi, arsitektur sistem, desain eksperimen, teknik pengumpulan dataset, algoritma yang diusulkan, sampel, dan prosedur pengujian.`
  3. `keterbatasan penelitian terdahulu, kelemahan metode sebelumnya, kekosongan literatur, masalah yang belum terselesaikan, namun demikian, akan tetapi, dan hasil yang belum jelas.`
  4. `tujuan utama penelitian, sasaran spesifik, kontribusi inti makalah, hasil yang ingin dicapai, mengeksplorasi, dan solusi yang diusulkan untuk menyelesaikan masalah.`
  5. `saran untuk penelitian selanjutnya, rekomendasi pekerjaan di masa depan, arah pengembangan masa depan, dan peluang studi berikutnya untuk mengatasi batasan saat ini.`

* **Data Contract:** `Input (Raw Markdown + Method C Queries) -> Extreme Purification V2 -> E5 Embedding with Prefixes -> Output (Top 3 Parent IDs)`

## 4. Execution & Quality
* **Execution Matrix:**
  | Checkbox | Phase | Task | Detail Task | Description | Acceptance Criteria | Input / Output State | Validation Command | Risk |
  | :---: | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
  | [x] | 1 | Update Model | Update `semantic_retriever.py` | Ganti ke model `intfloat/multilingual-e5-small`. | Model berhasil diunduh dan diload ke RAM tanpa *error*. | - | `python -m app.services.parser.semantic_retriever` | Sedang |
  | [x] | 2 | Prefix & Limit Guard | Tambah logika Prefix & Truncation | Modifikasi `_embed_batch` untuk menerima argumen *is_query* dan memastikan teks divalidasi/dipotong sebelum masuk model. | Vektor dikembalikan dengan dimensi 384 tanpa terpotong secara *silent* (diberi peringatan/diproses aman). | `List[str] -> List[List[float]]` | Inspeksi kode manual | Tinggi |
  | [x] | 3 | Setup Test A | Buat `benchmark_retrieval_a.py` | Salin skrip benchmark lama dan pasang daftar kueri Kandidat A. Atur path output log ke spesifik varian A. | Skrip berhasil jalan dan mencetak tabel metrik varian A. | - | `python scripts/Testing-Pipeline/benchmark_retrieval_a.py` | Rendah |
  | [x] | 4 | Setup Test B | Buat `benchmark_retrieval_b.py` | Salin skrip benchmark lama dan pasang daftar kueri Kandidat B. Atur path output log ke spesifik varian B. | Skrip berhasil jalan dan mencetak tabel metrik varian B. | - | `python scripts/Testing-Pipeline/benchmark_retrieval_b.py` | Rendah |
  | [x] | 5 | Data Purification | Sanitasi Skrip Pengujian | Tambahkan logika pembersihan (RegEx untuk OCR dan sanitasi Daftar Pustaka) pada file `benchmark_retrieval_a.py` dan `benchmark_retrieval_b.py`. | Skrip membuang *chunk* referensi dan menghapus teks hasil OCR dari vektor *child chunks* sebelum *retrieval*. | - | `python scripts/Testing-Pipeline/benchmark_retrieval_a.py` | Menengah |
  | [x] | 6 | Evaluasi C & Purifikasi V2 | Buat dan Jalankan `benchmark_retrieval_c.py` | Terapkan Kueri Metode C (*Lexical Anchors*) dan *Data Purification V2* (Anti-Afiliasi & Regex Ekstrem). | Skrip C berjalan lancar tanpa terdistraksi oleh *noise* *acknowledgment* atau tabel markdown. | - | `python scripts/Testing-Pipeline/benchmark_retrieval_c.py` | Rendah |

* **Exit Conditions (Hard Gate):** 
  - Tidak ada kebocoran string `"passage: "` ke prompt LLM Qwen pada sistem utama.
  - Skrip pengujian berhasil mencatat metrik tanpa memodifikasi *database* Neo4j utama (hanya *in-memory* dan log disk lokal).
  - Teks referensi (Daftar Pustaka), afiliasi (*Acknowledgments*), dan polusi tabel/angka dari OCR gambar dibersihkan total sebelum *embedding*.
* **Resource Requirements:** RAM ~500MB untuk *loading* model E5. Tidak ada konsumsi API Eksternal untuk fase ini (100% lokal).
* **Rollback Strategy:** Kembalikan model ke `all-MiniLM-L6-v2` dan hapus penambahan logika *prefix* di `semantic_retriever.py`.