# Artifact Plan: Sistem Evaluasi Otomatis RAG (Ragas + Qwen DashScope)

## 1. Judul
Rancang Bangun Pipeline Evaluasi Otomatis Chatbot Agentic Graph-RAG Menggunakan Ragas Framework dan Qwen (DashScope)

## 2. Tanggal
Rabu, 6 Mei 2026

## 3. Deskripsi
Dokumen ini merincikan rencana pembangunan *pipeline* evaluasi *offline* untuk mengukur kualitas teknis (RAG Triad) dari Chatbot BRAIN MySRE. Sistem ini menggunakan *framework* *open-source* **Ragas** yang akan bertindak sebagai "Juri Otomatis". Untuk menekan biaya operasional tanpa mengorbankan kualitas penalaran (*reasoning*), *pipeline* ini akan mengintegrasikan model **Qwen** (dari Alibaba DashScope) sebagai mesin penilai (*Judge LLM*). Evaluasi ini dirancang untuk dijalankan secara manual via CLI oleh pengembang (*Fast Iteration for Production*), memisahkan data soal (*dataset*) dari skrip pengujian untuk kemudahan pemeliharaan.

## 4. Metodologi
Sistem evaluasi mengadopsi pengukuran **RAG Triad** dari Ragas:
*   **Faithfulness (Groundedness / Anti-Halusinasi):** Metrik *Reference-Free*. Qwen mengekstrak klaim dari jawaban Chatbot dan memverifikasi silang dengan *chunks* dari Neo4j/Supabase. Skor 1.0 berarti bebas halusinasi.
*   **Answer Relevance:** Metrik *Reference-Free*. Qwen menilai apakah jawaban Chatbot benar-benar menjawab esensi dari pertanyaan (*query*), tanpa bertele-tele.
*   **Context Precision:** Metrik *Reference-Based*. Qwen membandingkan *chunks* yang ditarik oleh `graph_retriever` & `vector_retriever` terhadap "Jawaban Kunci" (*Ground Truth*) yang disiapkan pengembang, untuk menilai seberapa akurat mesin *search* kita bekerja.

## 5. Keputusan (Decision Log)
1.  **Framework Evaluasi:** Menggunakan pustaka `ragas` karena menjadi standar industri untuk *RAG Triad* dan memiliki dukungan penuh integrasi komponen LangChain.
2.  **Model Juri (Evaluator LLM):** Menggunakan **Qwen** (via Alibaba DashScope API) di-*wrap* menggunakan `langchain-community`.
3.  **Metode Eksekusi (NFR):** Opsi A (Manual via CLI Python lokal). Tidak diintegrasikan ke CI/CD (GitHub Actions) pada fase ini agar pengembang memiliki waktu untuk beradaptasi dengan metrik.
4.  **Pemisahan Data:** Pertanyaan uji coba (*queries*) dan jawaban kunci (*ground truth*) dipisahkan secara fisik ke dalam file `eval_dataset.json`. Skrip evaluasi tidak boleh melakukan *hardcode* terhadap pertanyaan ujian.
5.  **Target API:** Skrip evaluasi akan melakukan panggilan HTTP POST ke `http://localhost:8000/api/chat/stream` (atau endpoint chat final) dan menangkap teks *response* serta daftar *references/chunks* yang digunakan Chatbot.

## 6. Alur Diagram
```mermaid
flowchart TD
    subgraph Data_Layer
        JSON[("eval_dataset.json\n(Query, Hash, Ground Truth)")]
    end
    
    subgraph Evaluation_Script ["scripts/evaluate_ragas.py"]
        Runner["🤖 Chatbot API Runner\n(HTTP POST to localhost:8000)"]
        DatasetBuilder["📦 HuggingFace Dataset Builder\n(Assemble Q, A, Contexts, Truth)"]
        RagasEngine["⚖️ Ragas Evaluation Engine"]
    end
    
    subgraph Judge_LLM
        Qwen["🧠 Qwen (DashScope API)\nWrapped via LangChain"]
    end
    
    subgraph Target_System
        MySRE["🚀 BRAIN MySRE\nFastAPI Server"]
    end
    
    JSON --> Runner
    Runner --> |"Send Query & Hash"| MySRE
    MySRE --> |"Return Answer & Chunks"| Runner
    Runner --> DatasetBuilder
    DatasetBuilder --> RagasEngine
    RagasEngine <--> |"Evaluate Faithfulness,\nRelevance, Precision"| Qwen
    RagasEngine --> CSV[("📊 evaluation_results.csv\n(Detailed Scores)")]
```

## 7. Struktur Folder (Tree)
```text
backend-sre-main/
├── data/
│   └── eval_dataset.json          # (File JSON berisi daftar soal/query pengujian)
├── scripts/
│   └── evaluate_ragas.py          # (Skrip utama yang menjalankan Ragas & Qwen)
└── results/
    └── evaluation_results.csv     # (Output hasil penilaian Ragas yang otomatis di-generate)
```

## 8. Asumsi
1.  Aplikasi utama BRAIN MySRE (FastAPI) sudah berjalan sempurna di `localhost:8000` (atau *port* yang dikonfigurasi) saat evaluasi dijalankan.
2.  Pengembang telah memiliki API Key dari Alibaba DashScope (`DASHSCOPE_API_KEY`) yang diletakkan di file `.env`.
3.  Pustaka `ragas`, `langchain-community`, `pandas`, dan `datasets` (dari HuggingFace) diizinkan untuk diinstal di dalam *environment* Python proyek ini.
4.  Endpoint API Chatbot mengembalikan struktur JSON/SSE yang dapat di-*parse* oleh skrip evaluasi (khususnya untuk mengekstrak `response` dan `references` / *chunks* teks murni).

## 9. Konsep Tabel Metriks (Output `evaluation_results.csv`)
Hasil akhir dari *script* akan menghasilkan file CSV dengan kolom berikut untuk setiap pertanyaan:

| Kolom | Deskripsi |
| :--- | :--- |
| `question` | Teks pertanyaan dari *dataset*. |
| `active_hash` | Hash PDF yang digunakan sebagai jangkar. |
| `answer` | Jawaban teks yang di-*generate* oleh Chatbot. |
| `contexts` | *Array of string*, berisi potongan teks (*chunks*) asli dari Neo4j/Supabase yang dipakai Chatbot. |
| `ground_truth` | Jawaban ideal (*opsional*, hanya untuk menilai `context_precision`). |
| `faithfulness` | Skor (0.0 - 1.0). Seberapa bebas jawaban dari halusinasi berdasarkan `contexts`. |
| `answer_relevancy` | Skor (0.0 - 1.0). Seberapa akurat jawaban menjawab `question`. |
| `context_precision`| Skor (0.0 - 1.0). Seberapa relevan `contexts` terhadap `ground_truth`. |

## 10. Konsep Logika Prompting
*   **Prompting di Ragas:** Kita tidak perlu menulis *prompt* manual. Ragas telah memiliki *prompt* internal yang sangat teroptimasi (misal: metode *Self-Correction* dan ekstraksi *Statements*) yang ditujukan untuk Juri LLM.
*   **Konfigurasi Juri:** Di dalam kode `evaluate_ragas.py`, kita hanya perlu mendaftarkan model Qwen melalui antarmuka `ChatOpenAI` dari LangChain, dengan memanipulasi *base URL* agar menunjuk ke server DashScope milik Alibaba, lalu menyuntikkannya ke objek evaluasi Ragas.

## 11. Langkah Implementasi
1.  **Persiapan Lingkungan:** Memperbarui `requirements.txt` (atau instalasi manual) untuk pustaka `ragas`, `langchain-openai`, `pandas`, dan `datasets`.
2.  **Pembuatan Dataset Awal:** Membuat file `data/eval_dataset.json` dan mengisinya dengan 5-10 sampel pertanyaan spesifik, *hash*, dan *ground truth* (contoh uji coba).
3.  **Pengembangan Skrip Evaluasi:** Menulis `scripts/evaluate_ragas.py` yang berisi fungsi untuk:
    *   Membaca file JSON.
    *   Membuat pemanggilan HTTP asinkron ke server FastAPI lokal.
    *   Menginisialisasi *wrapper* Qwen-DashScope.
    *   Menjalankan `evaluate()` dari Ragas.
    *   Mengekspor skor DataFrame ke dalam file CSV.
4.  **Uji Coba & Analisis:** Menjalankan skrip dan memverifikasi apakah Juri AI (Qwen) dapat menilai halusinasi dengan tepat, lalu menyerahkan hasilnya kepada pengembang untuk dianalisis.

## 12. Tabel Eksekusi Task

| Check | Fase | Task | Detail Task | Deskripsi | Acceptance Criteria |
| :---: | :---: | :--- | :--- | :--- | :--- |
| [x] | 1 | **Preparation** | Dependency Update | Instalasi pustaka Ragas & Langchain. | Perintah `pip install ragas langchain-openai pandas datasets` berhasil dijalankan. |
| [x] | 1 | **Preparation** | Mock Dataset | Buat `data/eval_dataset.json`. | File JSON berisi minimal 3 pasang `query`, `active_hash`, dan `ground_truth` yang valid dari database Supabase Anda. |
| [x] | 2 | **Development** | HTTP Runner Logic | Tulis pemanggil API FastAPI di skrip Python. | Fungsi Python di skrip evaluasi mampu melakukan HTTP POST ke `localhost:8000` dan mengekstrak `answer` serta `contexts` (referensi teks). |
| [x] | 2 | **Development** | Qwen Judge Setup | Konfigurasi Langchain Qwen via DashScope. | Objek `ChatOpenAI` berhasil diinisialisasi menggunakan `DASHSCOPE_API_KEY` dan *base URL* Alibaba. |
| [x] | 3 | **Integration** | Ragas Pipeline | Satukan Runner dan Judge ke fungsi `evaluate()`. | Dataset (Q, A, Context, Truth) berhasil dikemas menjadi `Dataset` format HuggingFace dan dimasukkan ke *engine* Ragas. |
| [x] | 3 | **Integration** | CSV Exporter | Logika penyimpanan skor akhir. | Output dari Ragas berhasil diubah menjadi Pandas DataFrame dan disave ke `results/evaluation_results.csv`. |
| [x] | 4 | **Validation** | E2E Testing | Jalankan skrip `evaluate_ragas.py` di terminal. | Skrip selesai tanpa *error*, mencetak skor agregat ke terminal, dan menghasilkan file CSV yang bisa di-*review* oleh manusia. |
