# Rencana Implementasi Skrip Benchmark Extraction Modular

## 1. Judul
**Rencana Implementasi Skrip Benchmark Extraction Modular Berbasis LLM Structured Output dengan Agnostik Provider, Tiktoken Profiling, dan Cost Matrix**

## 2. Tanggal
Kamis, 14 Mei 2026

## 3. Deskripsi
Dokumen ini mendefinisikan rancangan (*blueprint*) untuk pengembangan dan pengujian skrip *benchmarking* mandiri proses "Extraction" pada arsitektur RAG aplikasi. Skrip ini secara khusus akan menguji fungsi `extract_pillars_with_llm` yang berada pada modul `app/services/parser/llm_extractor.py`. Skrip mereplikasi proses perakitan konteks (injeksi metadata + penggabungan *parent chunks*) secara akurat seperti di lingkungan produksi (`ingestion.py`), lalu mengirimkannya ke model LLM.

**Fitur Unggulan Pengujian Ini:**
Skrip dirancang bersifat **Agnostik Provider**, memungkinkan peralihan instan antara Alibaba DashScope dan OpenAI asli melalui sebuah "tombol sakelar" di dalam skrip, **tanpa memodifikasi atau merusak variabel `.env` utama**. Pengujian difokuskan pada pengukuran performa komputasi API (Latensi), konsumsi Token (Input/Output via `tiktoken`), serta kalkulasi otomatis **Biaya Eksekusi (Cost Matrix)** berdasarkan peta harga dinamis.

## 4. Metodologi
Pengujian ini dirancang berdasarkan prinsip berikut:
1. **Pipeline Continuity & True Simulation:** Mensimulasikan persis fungsi deduplikasi dan *Context Stuffing* (termasuk injeksi 1500 karakter awal sebagai judul/metadata).
2. **Agnostic API Invocation:** Fungsi inisialisasi *client* mendeteksi preferensi *provider* (Alibaba vs OpenAI) yang didefinisikan secara lokal di skrip. Klien yang terbentuk lalu disuntikkan (*dependency injection*) ke fungsi ekstraksi.
3. **Precise Profiling & Costing:** Penghitungan jumlah token input dilakukan secara lokal menggunakan pustaka `tiktoken` (*encoder* `cl100k_base`). Token output diambil dari `usage_stats`. Total token ini dikalikan dengan tarif per-model dari sebuah *Pricing Matrix* bawaan untuk menghasilkan *Cost ($)*.
4. **Strict Constraint:** Dilarang melakukan modifikasi kode pada `app/services/parser/llm_extractor.py`. Semua integrasi *prompt* dan validasi model Pydantic di-import langsung dari *source code* utama.
5. **Incremental Profiling (Append-Only):** Penulisan log ke tabel Markdown metrik secara sebaris tiap kali satu dokumen selesai diekstrak.

## 5. Keputusan (Decision Log)
1. **Pemisahan Konfigurasi Lingkungan:** Skrip tidak akan memaksa penambahan variabel baru di file `.env`. Sebagai gantinya, variabel seperti `TESTING_PROVIDER` (contoh: "dashscope" atau "openai") dan `TESTING_MODEL` akan disematkan di bagian atas skrip `benchmark_extraction.py`. Skrip akan cerdas membedakan URL dan Kunci (API Key) mana yang harus ditarik dari `.env` yang sudah ada berdasarkan variabel lokal tersebut.
2. **Pricing Matrix:** Menggunakan *dictionary mapping* untuk harga per 1.000.000 token.
   - `qwen3-30b-a3b-thinking-2507`: In $0.10 / Out $0.30
   - `gpt-4o-mini`: In $0.15 / Out $0.60
3. **Dual Output Format:** Skrip menghasilkan file JSON (`_extraction_results.json`) dan file Markdown ramah baca (`_extraction_human.md`).

## 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 Extraction"]:::init --> InitDirs["Inisialisasi Direktori Output"]:::init
    InitDirs --> SelectProv["Baca Sakelar Skrip: Provider (OpenAI/DashScope)?"]:::logic
    SelectProv --> LoadKeys["Tarik Kunci .env yang Sesuai & Bangun Client"]:::logic
    LoadKeys --> ReadInput["Baca Chunk JSON & Retrieval JSON"]:::io
    ReadInput --> Dedup["Deduplikasi Parent ID dari hasil Retrieval"]:::logic
    Dedup --> Assemble["Gabung Teks Parent + Injeksi 1500 Char Metadata"]:::logic
    Assemble --> Tiktoken["Kalkulasi Token Input via Tiktoken"]:::logic
    Tiktoken --> TimerStart["Mulai Timer API"]:::logic
    TimerStart --> CallLLM["Panggil extract_pillars_with_llm"]:::logic
    
    CallLLM -- Sukses --> Validate["Ekstrak Metadata, Pilar & Token Output"]:::logic
    Validate --> CalcCost["Kalkulasi Cost berdasarkan Pricing Matrix"]:::logic
    CallLLM -- Exception --> LogErr["Tulis Exception ke extraction_errors.log"]:::io
    
    CalcCost --> TimerStop["Hentikan Timer API & Kalkulasi Latensi"]:::logic
    LogErr --> EndFail["Set Status Failed"]:::logic
    EndFail --> WriteMatFail["Append Status Failed ke Matrix"]:::io
    
    TimerStop --> WriteMD["Tulis Output Human Verification (.md)"]:::io
    WriteMD --> WriteJSONOut["Tulis Output Programmatic (.json)"]:::io
    WriteJSONOut --> WriteMatSucc["Append Baris Matriks (Termasuk Cost)"]:::io
    
    WriteMatFail --> NextFile{"Ada File Lain?"}:::logic
    WriteMatSucc --> NextFile
    NextFile -- Ya --> Dedup
    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_extraction.py                  # Skrip utama dengan kapabilitas Agnostik Provider
├── archive/
│   └── Testing-Pipeline/
│       └── benchmark-extraction/
│           ├── Perform-Matrix/
│           │   └── performance_matrix_extraction.md # Tabel metrik dengan kolom COST
│           ├── Log-Error/
│           │   └── extraction_errors.log            
│           ├── Output-JSON/                         
│           │   ├── RAGAS..._extraction_results.json
│           └── Output-Human-Verification/           
│               ├── RAGAS..._extraction_human.md
└── Markdown/
    └── Testing-Pipeline/
        └── Extraction-Benchmark/
            ├── Plan/
            │   └── extraction_benchmark_plan.md     # Dokumen Rencana ini
            ├── Execution-Log/                       
            └── Report/                              
```

## 8. Asumsi & Batasan
1. Asumsi bahwa direktori output dari fase `benchmark-chunking` dan `benchmark-retrieval` telah terisi data yang valid.
2. Skrip diasumsikan berjalan pada lingkungan di mana paket pustaka `openai`, `pydantic`, dan `tiktoken` sudah tersedia.

## 9. Konsep Tabel Metriks
Matriks performa untuk mengevaluasi komputasi Cloud API dan Token Cost:

| TIMESTAMP | DOCUMENT | MODEL | TIKTOKEN INPUT | LLM OUT TOKEN | LATENCY (s) | COST ($) | STATUS | NOTE |
| :--- | :--- | :--- | :---: | :---: | :---: | :---: | :--- | :--- |
| ... | ... | ... | ... | ... | ... | ... | ... | ... |

*Definisi Metrik Khusus:*
* **MODEL:** Nama model aktual yang digunakan (misal: `qwen3-30b...` atau `gpt-4o-mini`).
* **TIKTOKEN INPUT:** Jumlah token yang diestimasi secara lokal oleh `tiktoken` (menggunakan *encoder* `cl100k_base`).
* **LLM OUT TOKEN:** Jumlah token respons (*completion_tokens*) yang dilaporkan kembali oleh API melalui struktur *usage stats*.
* **LATENCY (s):** Waktu respons murni dari pemanggilan API LLM.
* **COST ($):** Kalkulasi: `((TIKTOKEN INPUT * Harga In) + (LLM OUT TOKEN * Harga Out)) / 1.000.000`.

## 10. Tabel Eksekusi Task

Karena adanya perubahan arsitektur besar untuk integrasi *Agnostic Provider* dan *Cost Matrix*, fase *Scripting* dan *Execution* diatur ulang agar dapat ditinjau kembali dari awal.

| Check Box | Fase | Task | Detail Task | Deskripsi | Acceptance Criteria |
| :---: | :--- | :--- | :--- | :--- | :--- |
| [x] | Phase 1: Preparation | 1.1 Create Directories | Membangun hierarki direktori pengujian ekstraksi | Memastikan folder `archive/.../benchmark-extraction/...` dan log siap. | Direktori tujuan telah dibentuk (Telah selesai sebelumnya). |
| [x] | Phase 2: Scripting | 2.1 Skeleton & Agnostic Setup | Persiapan skrip, *Pricing Matrix*, dan logika Sakelar *Provider* | Membangun struktur awal `benchmark_extraction.py`. Menambahkan variabel *switch* lokal (`TESTING_PROVIDER`), peta harga (`PRICING_MATRIX`), dan fungsi `get_llm_client()` yang cerdas mendeteksi `.env`. | Fungsi inisialisasi API sanggup beralih antara URL DashScope dan OpenAI tanpa bergantung pada satu variabel `.env` kaku. |
| [x] | Phase 2: Scripting | 2.2 Context Assembler | Algoritma perakitan konteks & Penghitungan Tiktoken | Melakukan deduplikasi *parent_id*, perakitan `raw_text`, injeksi 1500 char metadata awal, dan validasi jumlah token `cl100k_base` via `tiktoken`. | Teks gabungan dirakit persis seperti produksi, variabel `token_llm_in` akurat. |
| [x] | Phase 2: Scripting | 2.3 LLM Execution & Costing | Pemanggilan LLM dan Kalkulasi Biaya Finansial | Mengeksekusi `extract_pillars_with_llm` dengan proteksi `BoundedSemaphore`. Menghitung matematis nilai `COST ($)` berdasarkan jumlah token masuk/keluar dikalikan dengan tarif *Pricing Matrix*. | Mendapatkan JSON tervalidasi Pydantic dan nilai desimal akurat untuk `cost_usd`. |
| [x] | Phase 2: Scripting | 2.4 Artifacts & Markdown Logger | Penulisan *Output* Ganda dan Tabel Matriks | Membuat berkas JSON, dokumen *Human Verification* MD, serta menulis log baris ke matriks performa yang menyertakan kolom `MODEL` dan `COST ($)`. | Semua bentuk luaran tersimpan rapi tanpa menyebabkan eror penulisan baris. |
| [x] | Phase 3: Execution | 3.1 Dry-Run DashScope | Uji coba *batch* menggunakan Alibaba DashScope | Menyetel *switch* skrip ke `"dashscope"` dan mengeksekusi dokumen `RAGAS` dan `SciLit`. | *Latency* dan *Cost* dari Qwen3 tercatat dengan baik di tabel. |
| [x] | Phase 4: Reporting | 4.1 Log & Report Creation | Merangkum temuan pengujian | Menyusun dokumen *Final Report* mengupas perbedaan performa, kalkulasi biaya, dan stabilitas model. | *Final Report* tersusun komprehensif memuat *Cost Matrix*. |
