## [TASK-1] - [Update Model] - [15-05-2026]
- **Status:** SUCCESS
- **Context:** Melakukan migrasi model embedding dari `all-MiniLM-L6-v2` (hanya Inggris) menjadi `intfloat/multilingual-e5-small` untuk mendukung arsitektur *Small-to-Big Retrieval* pada dokumen bilingual.

### 1. Operation Details
- **Command/Action:** `Modify self.model in semantic_retriever.py`
- **Target File:** `app/services/parser/semantic_retriever.py`
- **Reasoning:** Model `multilingual-e5-small` terbukti memiliki skor MTEB yang sangat baik untuk pencarian silang bahasa (Inggris-Indonesia). Model ini juga menggunakan dimensi 384D yang sama dengan `MiniLM` sehingga tidak akan merusak struktur array Numpy yang ada pada kalkulasi *Cosine Similarity*.
- **Modified Code Context:**
  ```python
  class SemanticRetriever:
      def __init__(self, ali_client=None, openai_client=None):
          from sentence_transformers import SentenceTransformer
          # Gunakan model multilingual E5 untuk kapabilitas lintas bahasa (termasuk Indonesia)
          self.model = SentenceTransformer("intfloat/multilingual-e5-small")
          self.vector_dim = 384
  ```

### 2. Output & Diagnostics
```text
Downloading model.safetensors: 471M/471M [03:26<00:00, 2.27MB/s]
Running local retrieval...
'What is machine learning?': ['p1']
'How do plants eat?': ['p2']
```

### 3. Failure Mode (Jika FAILED)
- **Error Code/Type:** -
- **Root Cause:** -
- **Recovery Action:** -

### 4. Verification
- **Validation:** Menjalankan manual *smoke test* lokal menggunakan perintah `python3 -m app.services.parser.semantic_retriever` untuk memastikan library `sentence_transformers` sanggup mengunduh dan menempatkan bobot (weights) model ke dalam RAM.
- **Outcome:** Model sukses dimuat. Logika kalkulasi `_cosine_similarity` dan ekstraksi top-k parents dari dummy data bekerja dengan mulus dan mengembalikan relasi _parent ID_ yang relevan.
## [TASK-2] - [Prefix & Limit Guard] - [15-05-2026]
- **Status:** SUCCESS
- **Context:** Menambahkan logika *Prefix Injection* wajib (`query:` dan `passage:`) serta fungsi batas toleransi (Truncation Guard) pada model E5 untuk mencegah kegagalan senyap (silent failure) akibat melewati batas maksimum *tokens*.

### 1. Operation Details
- **Command/Action:** `Modify _embed_batch and find_top_k_parents in semantic_retriever.py`
- **Target File:** `app/services/parser/semantic_retriever.py`
- **Reasoning:** Berdasarkan temuan *best practice* dari pembuat model (Gao et al.), model *intfloat/multilingual-e5-small* mewajibkan input teks diawali string `"query: "` untuk pencarian dan `"passage: "` untuk dokumen. Selain itu, model ini memiliki batas maksimum 512 *tokens*. Teks yang kepanjangan akan terpotong diam-diam tanpa melemparkan eksepsi, sehingga harus dicegah secara eksplisit menggunakan pemotongan karakter (1500 *chars*).
- **Modified Code Context:**
  ```python
    def _embed_batch(self, texts: List[str], is_query: bool = False) -> List[List[float]]:
        """Embed a list of texts using the local SentenceTransformer model with E5 prefix rules."""
        prefix = "query: " if is_query else "passage: "
        
        # E5 models have a max sequence length of 512 tokens. 
        # We truncate by character (approx 1500 chars to be safe) before encoding.
        MAX_CHARS = 1500
        
        prefixed_texts = []
        for t in texts:
            cleaned = (t or "").strip()
            if len(cleaned) > MAX_CHARS:
                logger.warning(f"Text exceeded {MAX_CHARS} chars, truncating before embedding.")
                cleaned = cleaned[:MAX_CHARS]
            prefixed_texts.append(f"{prefix}{cleaned}")
            ...
  ```

### 2. Output & Diagnostics
```text
Running local retrieval with E5 prefix and truncation guards...
'What is machine learning?': ['p1']
'How do plants eat?': ['p2']
```

### 3. Failure Mode (Jika FAILED)
- **Error Code/Type:** -
- **Root Cause:** -
- **Recovery Action:** -

### 4. Verification
- **Validation:** Menjalankan `python3 -m app.services.parser.semantic_retriever` secara lokal.
- **Outcome:** Model berhasil mengeksekusi ekstraksi. *Prefix* terbukti disuntikkan secara akurat berdasarkan parameter `is_query` (terbukti dari hasil deteksi *parent ID* yang masih relevan dengan dummy input). Penambahan batas karakter berjalan sesuai instruksi untuk memitigasi anomali kepanjangan.
## [TASK-3] - [Setup Test A] - [15-05-2026]
- **Status:** SUCCESS
- **Context:** Membuat skrip *benchmark* spesifik untuk Kandidat A (`benchmark_retrieval_a.py`) guna melakukan isolasi lingkungan *A/B testing*.

### 1. Operation Details
- **Command/Action:** `Copy benchmark_retrieval.py to benchmark_retrieval_a.py and update constants`
- **Target File:** `scripts/Testing-Pipeline/benchmark_retrieval_a.py`
- **Reasoning:** Untuk menghindari kontaminasi hasil pengujian, skrip asli digandakan. Pada varian A, jalur *output* direvisi menjadi `-A` (`Output-JSON-A`, `Output-Human-Verification-A`) dan nilai konstan `QUERY_TEXTS` diganti menggunakan desain kueri Sintesis *Q&A + Deklaratif* yang disepakati pada sesi *brainstorming*.
- **Modified Code Context:**
  ```python
  # Output Directories
  ...
  OUTPUT_JSON_DIR = os.path.join(BASE_DIR, 'archive/Testing-Pipeline/benchmark-retrieval/Output-JSON-A')
  OUTPUT_MD_DIR = os.path.join(BASE_DIR, 'archive/Testing-Pipeline/benchmark-retrieval/Output-Human-Verification-A')
  MATRIX_FILE = os.path.join(MATRIX_DIR, 'performance_matrix_retrieval_a.md')

  # The 5 Queries (Candidate A: Synthesis Q&A + Declarative)
  QUERY_TEXTS = [
      "Penelitian ini dilatarbelakangi oleh urgensi masalah, konteks situasi saat ini, serta motivasi mendasar yang mendorong perlunya dilakukan kajian.",
      "Tahapan penelitian, arsitektur sistem, desain eksperimen, dan prosedur pengujian dieksekusi menggunakan metodologi teknis berikut.",
      "Apa kelemahan, keterbatasan ruang lingkup, atau masalah spesifik pada metode penelitian terdahulu yang belum terselesaikan?",
      ...
  ]
  ```

### 2. Output & Diagnostics
```text
Starting Retrieval Benchmark...
Initializing SemanticRetriever (Loading Model)...
Model loaded successfully.
Processed: Reviving_Life_on_the_Edge_Joint_Score_Based_Graph_Generation... -> Status: Success
Processed: 69467_284308_1_PB_parsed_chunked.json -> Status: Success
...
Benchmark completed. Check Output directories for results.
```

### 3. Failure Mode (Jika FAILED)
- **Error Code/Type:** -
- **Root Cause:** -
- **Recovery Action:** -

### 4. Verification
- **Validation:** Menjalankan perintah `python3 scripts/Testing-Pipeline/benchmark_retrieval_a.py`.
- **Outcome:** Skrip tereksekusi tanpa kesalahan. Delapan *file* *chunked* JSON dari arsip berhasil dikalkulasi vektornya. Semua artefak berformat JSON dan MD terbuat secara otomatis di dalam *folder* berakhiran `-A` yang baru, dan tabel matriks performa sukses ditulis.
## [TASK-4] - [Setup Test B] - [15-05-2026]
- **Status:** SUCCESS
- **Context:** Membuat skrip *benchmark* spesifik untuk Kandidat B (`benchmark_retrieval_b.py`) guna memfasilitasi pengujian metode *HyDE / Pseudo-Answer*.

### 1. Operation Details
- **Command/Action:** `Copy benchmark_retrieval.py to benchmark_retrieval_b.py and update constants`
- **Target File:** `scripts/Testing-Pipeline/benchmark_retrieval_b.py`
- **Reasoning:** Menyediakan lingkungan uji yang terisolasi untuk Kandidat B. Jalur *output* diubah menjadi akhiran `-B` (`Output-JSON-B`, `Output-Human-Verification-B`) agar tidak bentrok dengan pengujian A. *Query texts* diperbarui menggunakan format deklaratif penuh yang meniru gaya bahasa jurnal ilmiah (Pseudo-Answer) sesuai rekomendasi metode HyDE dari Gao et al., 2022.
- **Modified Code Context:**
  ```python
  # Output Directories
  ...
  OUTPUT_JSON_DIR = os.path.join(BASE_DIR, 'archive/Testing-Pipeline/benchmark-retrieval/Output-JSON-B')
  OUTPUT_MD_DIR = os.path.join(BASE_DIR, 'archive/Testing-Pipeline/benchmark-retrieval/Output-Human-Verification-B')
  MATRIX_FILE = os.path.join(MATRIX_DIR, 'performance_matrix_retrieval_b.md')

  # The 5 Queries (Candidate B: HyDE Pseudo-Answer)
  QUERY_TEXTS = [
      "Fenomena ini merupakan isu krusial. Oleh karena itu, studi ini dilakukan untuk merespons urgensi permasalahan yang melatarbelakangi penelitian.",
      "Penelitian ini menggunakan pendekatan terstruktur di mana data dikumpulkan dan analisis dilakukan menggunakan teknik serta metode yang dijelaskan pada bagian ini.",
      "Meskipun banyak studi telah dilakukan, masih terdapat kekosongan literatur (gap), kelemahan, dan batasan pada penelitian sebelumnya yang belum dieksplorasi.",
      ...
  ]
  ```

### 2. Output & Diagnostics
```text
Starting Retrieval Benchmark...
Initializing SemanticRetriever (Loading Model)...
Model loaded successfully.
Processed: Reviving_Life_on_the_Edge_Joint_Score_Based_Graph_Generation... -> Status: Success
Processed: 69467_284308_1_PB_parsed_chunked.json -> Status: Success
...
Benchmark completed. Check Output directories for results.
```

### 3. Failure Mode (Jika FAILED)
- **Error Code/Type:** -
- **Root Cause:** -
- **Recovery Action:** -

### 4. Verification
- **Validation:** Menjalankan `python3 scripts/Testing-Pipeline/benchmark_retrieval_b.py` pada terminal.
- **Outcome:** Skrip tereksekusi tanpa kendala untuk delapan berkas uji. Sistem sukses menghasilkan dokumen verifikasi JSON dan MD di folder *Output-B* baru, serta menambahkan skor matriks di `performance_matrix_retrieval_b.md`.
## [TASK-5] - [Data Purification] - [15-05-2026]
- **Status:** SUCCESS
- **Context:** Menambahkan *Data Purification Layer* secara terisolasi pada kedua skrip pengujian (A dan B) untuk menyanitasi data kotor (referensi & polusi OCR) secara *on-the-fly* sebelum dikalkulasi oleh model E5.

### 1. Operation Details
- **Command/Action:** `Insert regex and is_irrelevant_header filter into process_file()`
- **Target File:** 
  - `scripts/Testing-Pipeline/benchmark_retrieval_a.py`
  - `scripts/Testing-Pipeline/benchmark_retrieval_b.py`
- **Reasoning:** Berdasarkan inspeksi keluaran pengujian sebelumnya, data mentah yang ditarik oleh algoritma E5 masih mengandung residu daftar pustaka serta anomali teks dari hasil OCR (misal: barisan angka koordinat grafik). Membersihkan "sampah semantik" ini di ruang memori sebelum `semantic_retriever` bekerja sangat diwajibkan, agar tidak ada bias akurasi antar-kueri yang diuji (mencegah *Garbage In, Garbage Out*).
- **Modified Code Context:**
  ```python
        # --- Data Purification Layer ---
        import re
        try:
            from app.services.parser.smart_chunker import is_irrelevant_header
        except ImportError:
            is_irrelevant_header = lambda h: False
            
        def clean_ocr_noise(text):
            if not text: return ""
            return re.sub(r'> \*\*\[Teks Gambar Hasil OCR - .*?\]\*\*:.*?(?=\n\n|\Z)', '', text, flags=re.DOTALL | re.IGNORECASE).strip()

        purified_parents = []
        for p in parent_chunks:
            if is_irrelevant_header(p.get("metadata_header")):
                continue
            p["content"] = clean_ocr_noise(p.get("content", ""))
            if p["content"]:
                purified_parents.append(p)
  ```

### 2. Output & Diagnostics
```text
Starting Retrieval Benchmark...
Initializing SemanticRetriever (Loading Model)...
Model loaded successfully.
Processed: Reviving_Life_on_the_Edge_Joint_Score_Based_Graph_Generation... -> Status: Success
Processed: 69467_284308_1_PB_parsed_chunked.json -> Status: Success
...
Benchmark completed. Check Output directories for results.
```

### 3. Failure Mode (Jika FAILED)
- **Error Code/Type:** -
- **Root Cause:** -
- **Recovery Action:** -

### 4. Verification
- **Validation:** Menjalankan perintah secara paralel `python3 scripts/Testing-Pipeline/benchmark_retrieval_a.py && python3 scripts/Testing-Pipeline/benchmark_retrieval_b.py`.
- **Outcome:** Seluruh eksekusi untuk kedua varian pengujian sukses. File JSON hasil pengekstrakan berhasil dimuat, dibersihkan dari *headers* referensi, dan teks *noise* OCR gambar dihilangkan dengan presisi tanpa mengorbankan teks esensial. Vektor ruang kini bekerja dalam keadaan optimal.## [TASK-6] - [Evaluasi & Metode C] - [15-05-2026]
- **Status:** SUCCESS
- **Context:** Mengganti skenario pengujian dari A/B testing menjadi evaluasi tunggal untuk Metode C (Anchor-Density) dengan implementasi perlindungan data yang sangat agresif (Data Purification V2) guna membersihkan polusi yang tersisa.

### 1. Operation Details
- **Command/Action:** `Create benchmark_retrieval_c.py with new queries and aggressive regex`
- **Target File:** `scripts/Testing-Pipeline/benchmark_retrieval_c.py`
- **Reasoning:** Hasil dari *Human Verification* sebelumnya menunjukkan bahwa metode Q&A maupun HyDE gagal akibat kontaminasi data mentah (nama *author*, afliasi, sisa tabel Markdown, dan *acknowledgment* berkedok paragraf) yang mengecoh model *dense retriever*. Sesuai riset *Prompt Engineering* untuk E5, kueri diubah menjadi kumpulan jangkar leksikal (*Lexical Anchors*) tanpa format pertanyaan. Selain itu, *Data Purification Layer* ditingkatkan menjadi sangat agresif, menyaring isi paragraf dan menghancurkan semua teks yang mengandung afiliasi atau residu *references*.
- **Modified Code Context:**
  ```python
        EXTENDED_IRRELEVANT_HEADERS = [
            "reference", "references", "bibliography", "daftar pustaka", "referensi",
            "acknowledgement", "acknowledgements", "acknowledgment", "acknowledgments",
            "ucapan terima kasih", "funding", "pendanaan",
            "appendix", "appendices", "lampiran",
            "table of contents", "daftar isi",
            "author contributions", "kontribusi penulis"
        ]
        
        # Kueri Metode C
        QUERY_TEXTS = [
            "latar belakang masalah, urgensi penelitian, motivasi mendasar, fenomena krusial, konteks situasi saat ini, dan alasan utama studi ini dilakukan.",
            "rincian teknis metodologi, arsitektur sistem, desain eksperimen, teknik pengumpulan dataset, algoritma yang diusulkan, sampel, dan prosedur pengujian.",
            ...
        ]
        
        def is_content_garbage(text):
            if not text: return True
            lowered = text.lower()
            if any(kw in lowered for kw in ["acknowledgment", "acknowledgement", "ucapan terima kasih", "funded by", "didanai oleh", "thank"]):
                return True
            ...
  ```

### 2. Output & Diagnostics
```text
Starting Retrieval Benchmark...
Initializing SemanticRetriever (Loading Model)...
Model loaded successfully.
Processed: Reviving_Life_on_the_Edge_Joint_Score_Based_Graph_Generation... -> Status: Success
Processed: 69467_284308_1_PB_parsed_chunked.json -> Status: Success
...
Benchmark completed. Check Output directories for results.
```

### 3. Failure Mode (Jika FAILED)
- **Error Code/Type:** -
- **Root Cause:** -
- **Recovery Action:** -

### 4. Verification
- **Validation:** Menjalankan eksekusi `python3 scripts/Testing-Pipeline/benchmark_retrieval_c.py`.
- **Outcome:** Pengujian berhasil diselesaikan. Delapan dokumen diproses dengan aturan *Anchor-Density* dan saringan V2. Output Markdown verifikasi diletakkan secara terisolasi pada direktori `-C`. Tidak ditemukan *crash* akibat regex maupun *Silent Truncation* E5.
