# 1. Judul
**Desain Implementasi PoC Task 2: Migrasi Neo4j Vector Knowledge Graph**

# 2. Tanggal
17 April 2026

# 2A. Status Dokumen
**Legacy (Baseline Awal / Tidak Aktif sebagai acuan utama)**  
Dokumen ini dipertahankan sebagai jejak desain PoC awal. Untuk implementasi aktif saat ini, gunakan `Markdown/redesign_2_PoC_implementation.md`.

# 3. Ringkasan Pemahaman / Desain
Rancangan pembuatan skrip *Proof of Concept* (PoC) berbasis Python yang berdiri sendiri secara lokal. Tujuan PoC ini adalah untuk menguji secara tuntas alur konversi literatur (PDF) murni menjadi entitas Node beserta garisan Edge di dalam basis data Graf (Neo4j). PoC ini tidak berhubungan dengan kode peladen `mcp-sre-main` maupun *front-end* secara langsung, melainkan berfungsi sebagai *blueprint* dan draf uji coba keamanan limitasi *free tier* sebelum diintegrasikan di aplikasi utama.

# 4. Asumsi dan Spesifikasi
*   **Database Graf:** Neo4j AuraDB (lisensi *Free Plan*, limitasi 50k node/175k edge, v5.11+).
*   **AI Engine (Parsing & Summary):** Ekosistem Gemini (penggunaan khusus untuk model `gemini-2.5`).
*   **AI Vector Embedding:** Ekosistem Gemini (khusus model `text-embedding-004` yang memancarkan tepat 768 Dimensi secara *default*).
*   **Ekstraktor Dokumen:** `PyMuPDF` (ringan dan solid untuk *parsing* PDF lokal).
*   **Lingkungan Esksekusi:** Akses murni *Command Line Interface* (CLI) Terminal. Tidak ada pemanggilan API REST HTTP di dalam PoC ini.

# 5. Catatan Keputusan / Decision Log
*   **Desain Skema Graf:** Node bukan murni chunk mentah, melainkan Node Jurnal Utuh yang menggendong 5 lapis *array* vektor komponen.
*   **Pembuatan Edge Jurnal:** Diciptakan saat meng-unggah literatur (*On-Ingestion / Real-Time*) menggunakan utilitas kueri KNN Vector Search dari Neo4j Cypher. Edge yang dihasilkan akan berwujud seperti `[:SIMILAR_METHODOLOGY]`.
*   **Eksistensi Anotasi Edge:** Teks penjelasan (Summary) yang merasionalisasi mengapa suatu Edge ada *("Mengapa jurnal ini mirip?")* dibangkitkan oleh Gemini secara *pre-computed* ketika *Node* baru masuk, lalu ditanam di Neo4j sebagai kolom *properties* Edge untuk melindungi UI dari kelambatan respons di kemudian hari.

# 6. Diagram Alur
```mermaid
flowchart TB
    classDef file fill:#f9f9f9,stroke:#A1662A,stroke-width:2px,color:#232F3E
    classDef compute fill:#fff,stroke:#FF9900,stroke-width:2px,color:#232F3E
    classDef ai fill:#fff,stroke:#9B59B6,stroke-width:2px,color:#232F3E
    classDef db fill:#f9f9f9,stroke:#527FFF,stroke-width:2px,color:#232F3E,shape:cylinder

    subgraph SubLokal ["📁 Local Machine (Terminal Mode)"]
        direction TB
        PDF["📄 Real PDF Literature"]:::file
        Script["⚙️ embed_and_ingest.py<br>(PyMuPDF / Agent)"]:::compute
    end

    subgraph SubAi ["🔮 Gemini Ecosystem"]
        direction TB
        LLMExtract["🧠 Gemini 2.5<br><small>(Extract 5 Components to JSON)</small>"]:::ai
        Embedder["🔢 text-embedding-004<br><small>(768-D Vector Mapper)</small>"]:::ai
        LLMSummary["🧠 Gemini 2.5<br><small>(Generate Edge Summary Text)</small>"]:::ai
    end

    subgraph SubNeo ["💾 Neo4j AuraDB Free"]
        direction TB
        Nodes[("🔷 Jurnal Nodes<br><small>(Store text & 5 vectors)</small>")]:::db
        Search["🔎 Native Vector Search<br><small>(Cosine KNN)</small>"]:::compute
        Edges[("🔗 Jurnal Edges<br><small>(Store weight & summary)</small>")]:::db
    end

    %% Data Flow
    PDF -- "1. Baca Teks" --> Script
    Script -- "2. Kirim Raw Text" --> LLMExtract
    LLMExtract -- "3. Return 5 Intisari" --> Script
    Script -- "4. Kirim 5 Intisari" --> Embedder
    Embedder -- "5. Return 5x 768-D Vectors" --> Script
    Script -- "6. CREATE Node & Vectors" --> Nodes
    
    Script -- "7. Cari Top-K Kemiripan Vektor" --> Search
    Search -- "8. Return Top-K Jurnal Lawas" --> Script
    Script -- "9. Beri Teks 2 Jurnal yang Mirip" --> LLMSummary
    LLMSummary -- "10. Return Alasan Kemiripan (1 Kalimat)" --> Script
    Script -- "11. MERGE Edge" --> Edges

```

# 7. Penjelasan Diagram
1. **Lokal (Klien/Skrip):** Ujung tombak pemegang komando. Mulai dengan melahap PDF murni, mengeksekusi API AI, memegang nilainya di memori RAM Lokal, lalu melakukan kueri ke Neo4j.
2. **Gemini AI Ecosystem:** Skrip harus bolak-balik berinteraksi ke portal AI Gemini untuk tiga fase terpisah: (a) Peringkasan abstraksi literatur, (b) Transformasi vektor angka (768D), dan (c) Penciptaan teks alasan persamaan.
3. **Neo4j AuraDB:** Di ujung belakang, Neo4j pasif menerima *Node*. Ketika diperintah mencari (`CALL db.index.vector.queryNodes(...)`), ia menghitung kosinus kedekatan vektor. Hasil dari itu membantu Skrip lokal untuk memaku *Edge* (relasi fisik di graf).

# 8. Struktur Repository 
Folder root berlokasi di `poc-task2-neo4j-vector/`:
```text
poc-task2-neo4j-vector/
├── Literature/              # Folder khusus merangkum file *.pdf riil / jurnal percontohan.
├── Markdown/                # Ruang ganti dokumen *markdown* aktivitas, *decision log*, dll.
├── .env                     # Variabel Rahasia Utama (GEMINI_API_KEY, NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD).
├── requirements.txt         # Modul paten (neo4j, google-genai, python-dotenv, pymupdf).
├── setup_indexes.py         # Skrip konfigurasi satu-kali (One-time-setup).
├── embed_and_ingest.py      # Pelaku utama Pipa Data Ekstraksi-ke-Graf.
├── query_similarity.py      # Konsol pancingan (Audit Terminal) pengganti Visual UI.
└── README.md                # Catatan indeks untuk pengguna lain yang me-run repo ini.
```

# 9. Desain Skrip
*   **`setup_indexes.py`:** Memastikan database Neo4j yang polos memiliki jaring tangkap. Mengejar eksekusi 5 jenis indeks layaknya `CREATE VECTOR INDEX background_emb IF NOT EXISTS FOR (n:Literature) ON (n.embedding_background) OPTIONS {indexConfig: {dimensions: 768, similarity_function: 'cosine'}}`.
*   **`embed_and_ingest.py`:** Melilit semua prosedur dalam Diagram (Poin 1 hingga 11) beserta *try-except LLM safety catch*. Modul ini akan berjalan sinkron per file PDF di folder `/Literature`.
*   **`query_similarity.py`:** Tidak memasukkan *Node* apa pun. Anda memanggil skrip ini di terminal bersama kueri pertanyaan pencarian biasa (atau merujuk pada salah satu komponen jurnal). Target skrip membuktikan apakah *Vector Index DB* berhasil membacanya secara benar dan memuntahkan skor kecocokan dalam format seragam ke layar terminal.

# 10. Execution Task
Berlandaskan metrik kerja *Small & Verifiable Tasks* dari aturan `@plan-writing`.

| ✅ | ID | Task Name (Perintah / Action) | Indikator Selesai (Verification) |
| :---: | :---: | --- | --- |
| [x] | **01** | **Setup Folder Structure** <br> Buat pohon direktori `poc-task2-neo4j-vector/` beserta sub-folder `Literature/` dan `Markdown/`. Pastikan `.gitignore` mengecualikan `venv/` dan `.env`. | Perintah terminal `tree poc-task2-neo4j-vector -I venv` menampilkan struktur folder sesuai pohon di Blok 8. |
| [x] | **02** | **Pembuatan Kerangka Root** <br> Inisiasi file `.env` (template kosong), `requirements.txt`, dan `README.md` placeholder. | Perintah terminal `ls poc-task2-neo4j-vector` menampilkan `.env`, `requirements.txt`, `README.md`. |
| [x] | **03** | **Kompilasi Modul Dependensi** <br> Buat *Virtual Environment* (`python3 -m venv venv`), aktifkan, lalu `pip install -r requirements.txt`. | Perintah `pip list` di *env* menampakkan `neo4j`, `google-genai`, dan `PyMuPDF`. |
| [x] | **04** | **Skrip Setup Index Neo4j** <br> Buat dan kerjakan `setup_indexes.py` untuk dimensi 768 Cosine. | Saat skrip di-*run*, dan diperiksa melalui AuraDB UI (Kuery `SHOW VECTOR INDEXES`), muncul 5 lajur nama indeks berstatus *ONLINE*. |
| [x] | **05** | **Pengujian Modul PDF** <br> Kodingan awal ekstraksi file lokal di ranah `embed_and_ingest.py`. | Teks mentah PDF yang terbaca berhasil di-*print* (panjang ratusan kata) ke terminal secara bersih. |
| [x] | **06** | **Integrasi Gemini Extractor** <br> Kodingan LLM *Structured Output* mengubah Teks Mentah -> JSON (5 komponen). | Pemanggilan skrip membalikkan objek JSON mutlak berisikan 5 *key* (contoh: `{"background": "...", "method": "..."}`). |
| [x] | **07** | **Integrasi Gemini Embedder** <br> Mengirim JSON ke Ekosistem Embedding untuk dicetak menjadi angka. | Variabel python membuktikan *len(array)* bernilai terkonfirmasi `768 float`. |
| [x] | **08** | **Injeksi Node ke Neo4j** <br> Menembak *kueri MERGE* properti teks mentah & 5 Array Vektor. | Konsol visual AuraDB lewat browser mampu memunculkan bulatan jurnal saat dicek dengan kueri `MATCH (n:Literature) RETURN n`. |
| [x] | **09** | **Pembuktian Vector Search KNN** <br> Di posisi yang sama, cari kemiripan node lama menggunakan kueri *db.index.vector*. | Terminal dapat mencetak output log `Ditemukan node setara ID:xx dengan Cosine Similarity: 0.82`. |
| [x] | **10** | **Integrasi Summary Generator** <br> Mengirim pembandingan komponen 2 buah teks jurnal untuk mencari alasan garis tersebut (*reasoning*). | Kembalian Gemini hanya berwujud 1 hingga 2 baris kalimat *string* yang menjelaskan relevansi metodologinya, tanpa macet. |
| [x] | **11** | **Pengkawinan Garis Edge (MERGE Edge)** <br> Lakukan Cypher Query memaku skor numerik dan *teks summary* sebagai Edge. | Browser AuraDB memunculkan garis panah relasi (contoh: `[:SIMILAR_METHODOLOGY]`), dan diklik muncul data bobot & string narasinya. |
| [x] | **12** | **Finishing Terminal Tools** <br> Selesaikan `query_similarity.py` agar ramah dibaca pengguna manusia. | Skrip dapat dijalankan sejenis `python query_similarity.py` dan mengeksekusi daftar hasil pemadanan yang terformat rapi. |
