# 1. Judul
**Blueprint Rencana Implementasi Neo4j GDS PageRank untuk Pembobotan Node Visual**

# 2. Tanggal
26 April 2026

# 3. Deskripsi
Dokumen ini merupakan panduan implementasi penambahan modul *post-processing* ke dalam repositori *Proof of Concept* (`poc-task2-neo4j-vector`). Tujuan utamanya adalah untuk menghitung nilai sentralitas atau tingkat kepentingan akademis dari masing-masing literatur pada graf menggunakan algoritma **Neo4j GDS PageRank**. Nilai hasil kalkulasi akan dinormalisasi ke rentang ukuran tertentu (misal: 10-50) agar siap dikonsumsi sebagai pengatur ukuran bola (*node size*) oleh sistem visualisasi antarmuka *frontend* (Vis.js). Skrip ini berjalan secara terpisah dari *pipeline ingestion* utama demi melindungi batas penggunaan memori.

# 4. Metodologi
*   **Batch Processing**: Kalkulasi dijalankan hanya setelah seluruh proses *ingestion* PDF dan pembentukan *edge* selesai.
*   **Memory Efficiency (RAM Guardian)**: Menggunakan metode *Anonymous Graph Projection* dari library GDS yang bersifat sementara (*ephemeral*) lalu langsung dihancurkan setelah selesai untuk menghindari *Out Of Memory* (OOM).
*   **Weighted Edge Aggregation**: Algoritma menjumlahkan skor/bobot (*weight*) dari seluruh tipe pilar kemiripan (`SIMILAR_*`) yang menghubungkan dua *node*.
*   **Database-Side Normalization**: Proses *Min-Max Scaling* (penskalaan matematika) dilakukan secara penuh di dalam mesin Neo4j menggunakan kueri Cypher yang dilindungi dari kasus pembagian dengan nol (*Division by Zero*).

# 5. Keputusan
*   **[DEC-01]** Membuat skrip mandiri dengan nama `calculate_pagerank.py` yang terlepas dari `orchestrator_ingest.py`.
*   **[DEC-02]** Menggunakan rentang angka 10 hingga 50 sebagai batas ukuran normalisasi awal (bisa dikalibrasi kemudian).
*   **[DEC-03]** GDS tidak dibedakan per pilar, namun membaca kelima tipe relasi (`SIMILAR_BACKGROUND`, `SIMILAR_METHODOLOGY`, `SIMILAR_GAP`, `SIMILAR_OBJECTIVE`, `SIMILAR_FUTUREWORK`) yang memiliki properti `score`.
*   **[DEC-04]** Mengunci hasil akhir di properti permanen bernama `visual_pagerank_size`.

# 6. Alur Diagram

```mermaid
flowchart TD
    classDef db fill:#EEF6FF,stroke:#0071C5,stroke-width:2px,color:#0071C5,rx:5,ry:5
    classDef ram fill:#fff3e0,stroke:#FF9900,stroke-width:2px,color:#FF9900,rx:5,ry:5
    classDef math fill:#eaffea,stroke:#1e8900,stroke-width:2px,color:#1e8900,rx:5,ry:5
    
    A[Neo4j Database: Nodes & Edges]:::db --> B(Anonymous Graph Projection)
    B -->|Sum 'score' from 5 edges| C[GDS PageRank Algorithm RAM]:::ram
    C -->|gds.pageRank.write| D(Node Property: pagerank_raw)
    D --> E[Cypher: Find Global Min & Max]:::math
    E --> F[Cypher: Min-Max Scaling Math 10-50]:::math
    F -->|Zero Division Guard| G[Node Property: visual_pagerank_size]:::db
    G --> H[Drop pagerank_raw property]:::db
```

# 7. Struktur Folder (Tree)
Implementasi ini tidak akan mengubah banyak struktur, hanya penambahan satu skrip khusus di level *root* direktori PoC.

```text
poc-task2-neo4j-vector/
├── Literature/
├── Markdown/
│   ├── redesign_2_PoC_implementation.md
│   ├── Final_Report_PoC_Task2_20260420.md
│   └── GDS_PageRank_Implementation_Plan.md  <-- (File ini)
├── orchestrator_ingest.py
├── query_similarity.py
├── setup_indexes.py
├── calculate_pagerank.py                    <-- (Skrip Baru yang akan dibuat)
└── .env
```

# 8. Asumsi
*   Anda beroperasi menggunakan Neo4j Community Edition (Self-Hosted).
*   Fitur *Plugin* GDS (`graph-data-science`) telah di- *install* dan berhasil diaktivasi pada *docker-compose*.
*   Batas RAM yang dialokasikan sangat rendah: *Heap* 1GB dan *Pagecache* 1GB.
*   Proses penanaman dasar (*Ingest*) LLM tetap menggunakan infrastruktur Gemini 768D (tidak berpindah ke Nebius Qwen3 hari ini).
*   Data relasi yang ada di Neo4j telah memiliki *property* bernilai numerik dengan *key* `score`.

# 9. Konsep Tabel Metriks
| Parameter | Jenis Metrik | Aturan / Nilai | Penjelasan |
| :--- | :--- | :--- | :--- |
| `weightProperty` | Input GDS | `score` | Nilai *Cosine Similarity* antara 0 - 1.0 yang menempel di setiap *edge*. |
| `pagerank_raw` | Output GDS Sementara | *Float* bebas | Skor orisinal keluaran rumus PageRank dari GDS. |
| `visual_pagerank_size` | Output Final | `10.0` - `50.0` | Hasil skala dari `pagerank_raw`. Semakin banyak pilar kemiripan dengan jurnal populer, angkanya akan condong ke 50.0. |

# 10. Konsep Logika Prompting
**Status Ekstraksi: N/A (Murni Matematis)**.
Pada fase kalkulasi *PageRank* ini, **tidak ada panggilan ke API LLM (Gemini maupun Qwen3)**, dan tidak diperlukan *prompting*. Seluruh eksekusi dan rasionalisasi mengandalkan perhitungan statistik jaringan (*Network Science Math*) murni di dalam Neo4j GDS. Alasan semantik (*Reasoning*) telah diproses di fase sebelumnya oleh `orchestrator_ingest.py`.

# 11. Langkah Implementasi
1.  **Inisiasi File**: Membuat `calculate_pagerank.py` dengan muatan konektor *driver* Neo4j dan variabel `.env`.
2.  **Menulis Fungsi GDS**: Merangkai kueri Cypher untuk pemanggilan `gds.pageRank.write` via *anonymous projection* yang spesifik meminta agregasi `score` tanpa melihat *node label* atau *edge type* tertentu secara eksklusif (merata ke seluruh tipe graf literatur).
3.  **Menulis Fungsi Penskalaan (Min-Max)**: Merangkai dua *chain query* (mencari titik *Min/Max* dari seluruh graf, lalu memodifikasi *node* lewat `SET` kueri proteksi *Zero-Division* untuk mengubah nilai menjadi `visual_pagerank_size`).
4.  **Logging Audit Terminal**: Memberikan keluaran pelaporan di terminal yang menjabarkan jumlah milidetik (*computeMillis*) proses GDS dan rentang skor (ukuran minimum dan maksimum) yang baru saja berhasil ditulis.
5.  **Pengujian Independen (Dry-Run)**: Menjalankan skrip terhadap *database* Neo4j saat ini.

# 12. Tabel Eksekusi Task

| ✅ | Fase | Task | Detail Task | Deskripsi | Acceptance Criteria |
| :---: | :--- | :--- | :--- | :--- | :--- |
| [x] | **Fase 1: Setup** | **PR-01** | *File Creation* | Pembuatan `calculate_pagerank.py` dan kerangka koneksi ke Neo4j via *official driver*. | Skrip bisa merespons perintah eksekusi CLI dan terhubung ke DB tanpa error autentikasi. |
| [x] | **Fase 2: GDS Core** | **PR-02** | *Anonymous Projection Query* | Pembuatan kueri `gds.pageRank.write` dengan parameter `nodeProjection` dan `relationshipProjection` yang mengenali properti `score`. | Neo4j tidak OOM dan properti `pagerank_raw` sukses tercatat pada node `Literature`. |
| [x] | **Fase 3: Normalization** | **PR-03** | *Min-Max Extraction* | Pencarian nilai tertinggi dan terendah `pagerank_raw` lintas *database*. | Sistem dapat mengambil 2 angka absolut (Max dan Min) dari database. |
| [x] | **Fase 3: Normalization** | **PR-04** | *Scaling Math & Zero Guard* | Kalkulasi skor ke rentang 10-50, disertai perlindungan kueri `CASE WHEN max=min`. | Seluruh node `Literature` memiliki `visual_pagerank_size` bernilai antara 10-50, tidak ada error pembagian 0. |
| [x] | **Fase 3: Normalization** | **PR-05** | *Cleanup Property* | Menghapus properti sampah `pagerank_raw` setelah normalisasi tuntas. | `pagerank_raw` menghilang dari *schema* Neo4j demi kebersihan data. |
| [x] | **Fase 4: Testing** | **PR-06** | *Terminal Logging* | Penambahan output pelaporan eksekusi GDS dan metrik ke *console*. | Console UI mencetak waktu eksekusi GDS dan sampel rentang ukuran *node*. |
