# A. Judul
**Blueprint redesign_2 Implementasi PoC Task 2: Semantic-Gated Neo4j Vector Knowledge Graph**

# B. Tanggal
19 April 2026

# C. Ringkasan Pemahaman
Dokumen ini adalah kelanjutan dari redesign sebelumnya untuk PoC migrasi My-SRE Knowledge Graph berbasis Neo4j vector search. Fokus redesign_2 bukan sekadar mempercepat pipeline, tetapi memperbaiki kualitas makna edge yang dihasilkan. Masalah yang ingin ditangani adalah edge yang terlalu dangkal, false positive lintas domain, dan reasoning yang terasa sekadar pembenaran permukaan.

Pada implementasi sebelumnya, vector search masih terlalu permisif sehingga literatur yang secara semantik tidak sejalan dapat tetap saling terhubung. Kasus seperti literatur budidaya ikan lele yang justru terhubung dengan literatur tentang RAGAS, vector search, dan graph embedding menunjukkan bahwa problem utama bukan hanya di threshold, tetapi juga pada kontrak similarity, coherence gating, dan prompt reasoning. redesign_2 menetapkan bahwa similarity harus lolos pemeriksaan per pilar, edge reasoning harus lebih substantif, dan struktur edge harus tetap konsisten.

# D. Penjelasan Perbedaan antara Plan redesign Saat Ini dengan PoC Implementation Plan yang Lama

| Aspek | PoC Implementation Plan Lama | redesign sebelumnya | redesign_2 | Dampak Signifikan |
| :--- | :--- | :--- | :--- | :--- |
| **Tujuan Utama** | Membuktikan end-to-end pipeline PDF ke Neo4j | Memisahkan node ingest dan edge generation secara async | Memperbaiki kualitas semantik edge dan reasoning | Fokus bergeser dari sekadar berhasil ke benar secara makna |
| **Model Edge** | 1 relasi similarity per pasangan bisa sangat longgar | 5 typed edges per pilar tetap ada | 5 typed edges tetap dipertahankan, tetapi wajib lolos semantic gate | Struktur graf tetap kaya, tetapi tidak mudah bising |
| **Threshold** | Tidak terdefinisi dengan ketat | Threshold naik, tetapi masih relatif longgar | Per-pillar threshold matrix dengan baseline yang lebih ketat | Mengurangi false positive lintas domain |
| **Prompting** | Ekstraksi dan reasoning generik | Lebih rapi, namun reasoning masih dangkal | Mixed-mode prompting dengan aturan anti-halusinasi yang lebih kuat | Reasoning edge menjadi lebih kontekstual dan defensible |
| **Gate Kualitas** | Hampir tidak ada validasi lanjutan | Ada threshold KNN, tetapi belum cukup | Ada coherence gate sebelum merge edge | Edge harus koheren, bukan hanya mirip secara numerik |
| **Penamaan Property** | Beragam dan tidak seragam | Masih ada `reasoning` / `summary` campuran | Seluruh narasi edge distandarkan ke `edge.reasoning` | Kontrak data lebih stabil |
| **Eksekusi** | Sinkron sederhana | Main thread + worker thread | Tetap orchestrator async, tetapi dengan validation layer yang lebih ketat | Pipeline tetap praktis, namun lebih aman |
| **Review Workflow** | Full automatic tanpa kontrol kualitas tambahan | Full automatic | Tetap full automatic, tetapi dengan dry-run internal log untuk tuning | Tidak ada manual review gate, tetapi tetap bisa diaudit |

# E. Asumsi dan Spesifikasi
*   **Database Graf:** Neo4j AuraDB Free Plan, v5.x.
*   **AI Engine untuk ekstraksi dan reasoning:** Gemini family model via `google-genai`.
*   **AI Vector Embedding:** Gemini embedding dengan dimensi 768.
*   **Ekstraktor Dokumen:** PyMuPDF (`fitz`) untuk parsing PDF.
*   **Eksekusi:** CLI terminal dengan satu orchestrator utama.
*   **Model Edge:** Tetap 5 typed edges: `SIMILAR_BACKGROUND`, `SIMILAR_METHODOLOGY`, `SIMILAR_GAP`, `SIMILAR_OBJECTIVE`, `SIMILAR_FUTUREWORK`.
*   **Kontrak reasoning edge:** Hanya memakai `edge.reasoning`.
*   **Kontrak similarity:** Per-pillar threshold matrix, bukan satu angka global tunggal.
*   **Semantic gate:** Kandidat edge harus lolos minimal agreement lintas pilar yang relevan, bukan sekadar lolos satu skor tinggi.
*   **Mode operasional:** Full automatic, tetapi logging harus cukup kaya untuk tuning dan audit.

# F. Decision Log (Log Keputusan)
1. **[DEC-01] Single Authoritative Pipeline:** `orchestrator_ingest.py` tetap menjadi jalur aktif utama. `embed_and_ingest.py` diperlakukan sebagai legacy path yang hanya dipakai sebagai referensi atau fallback terbatas.
2. **[DEC-02] Canonical Edge Narrative Field:** Seluruh narasi edge distandarkan ke `edge.reasoning`. Tidak ada lagi `summary` sebagai properti final.
3. **[DEC-03] Typed Edge Retention:** Struktur 5 typed edges tetap dipertahankan untuk menjaga interpretabilitas per pilar, tetapi edge tidak boleh dibuat hanya karena satu similarity angka yang lemah.
4. **[DEC-04] Per-Pillar Threshold Matrix:** Threshold similarity ditetapkan per pilar agar masing-masing aspek punya tingkat ketat yang sesuai karakter semantiknya.
5. **[DEC-05] Semantic Coherence Gate:** Candidate pair wajib melewati pemeriksaan koherensi lintas pilar sebelum edge di-merge.
6. **[DEC-06] Mixed-Mode Prompting:** System prompt dan stabilitas instruksi memakai English, sedangkan reasoning output dan dokumentasi pengguna boleh tetap bilingual atau Indonesia.
7. **[DEC-07] Full Automatic Pipeline:** Tidak ada manual review queue di jalur inti. Tuning dilakukan lewat logging, dry-run output, dan evaluasi batch.
8. **[DEC-08] Anti-Contamination Rule:** Bagian referensi, bibliography, dan daftar pustaka harus dipotong sebelum ekstraksi agar tidak mencemari ekstraksi pilar dan reasoning.

# G. Penjelasan Cara Kerja Arsitektur redesign_2 secara End-to-End

Sistem berjalan sebagai satu orchestrator CLI yang memiliki dua lapisan kerja.

Lapisan pertama adalah **Main Thread / Ingestion**. Ia memindai folder `Literature/`, menghitung hash file sebagai identitas idempotent, mengecek apakah node sudah ada, lalu memproses PDF yang baru. Sebelum dikirim ke LLM, teks PDF harus dibersihkan dari bagian referensi. Setelah itu main thread mengekstrak 5 pilar jurnal, membuat embedding 768D untuk masing-masing pilar, lalu menyimpan node ke Neo4j. Node yang sukses di-merge kemudian dimasukkan ke antrean internal untuk diproses relasinya.

Lapisan kedua adalah **Worker Thread / Edge Generation**. Worker mengambil node baru dari antrean, lalu melakukan pencarian kandidat untuk kelima pilar. Namun redesign_2 tidak lagi menerima kandidat hanya karena lolos satu nilai similarity. Setiap kandidat harus melewati threshold matrix per pilar, lalu dinilai coherence-nya. Bila candidate pair dianggap layak, worker menyusun `edge.reasoning` yang lebih substantif berdasarkan kesamaan riset yang benar-benar terlihat. Setelah itu edge tetap disimpan sebagai typed edge sesuai pilar, tetapi hanya jika lolos gate kualitas.

Dengan cara ini, edge yang muncul di graf tidak sekadar menunjukkan kemiripan numerik, melainkan benar-benar menyatakan hubungan semantik yang masuk akal secara riset.

# H. Diagram Alur End-to-End (AWS Architectural Style)

```mermaid
flowchart TD
    classDef awsOrange fill:#FF9900,stroke:#232F3E,stroke-width:2px,color:#fff,rx:5,ry:5
    classDef awsNavy fill:#232F3E,stroke:#FF9900,stroke-width:2px,color:#fff,rx:5,ry:5
    classDef awsBlue fill:#EEF6FF,stroke:#0071C5,stroke-width:2px,color:#0071C5,rx:5,ry:5
    classDef awsGreen fill:#eaffea,stroke:#1e8900,stroke-width:2px,color:#1e8900,rx:5,ry:5
    classDef awsGray fill:#f4f4f4,stroke:#666,stroke-width:2px,color:#333,rx:5,ry:5

    subgraph S_Local ["Local Machine - Python CLI Orchestrator"]
        direction TB
        PDF["PDF Literature Folder"]:::awsGray

        subgraph S_Ingest ["Main Thread - Node Ingestion"]
            HashCheck["MD5 Hash Check"]:::awsBlue
            Sanitize["PDF Sanitizer - Remove References"]:::awsBlue
            Extract["Gemini Extraction - 5 Pillars"]:::awsOrange
            Embed["Gemini Embedding - 768D per Pillar"]:::awsOrange
            NodeDB["Neo4j MERGE Node"]:::awsNavy
            Queue["In-Memory Queue - New Node IDs"]:::awsGray
        end

        subgraph S_Worker ["Worker Thread - Edge Generation"]
            Candidate["Per-Pillar KNN Candidate Search"]:::awsBlue
            Threshold["Per-Pillar Threshold Matrix"]:::awsGreen
            Coherence["Semantic Coherence Gate"]:::awsGreen
            Reasoning["LLM Edge Reasoning - edge.reasoning"]:::awsOrange
            EdgeDB["Neo4j MERGE Typed Edge"]:::awsNavy
        end
    end

    PDF -->|Read PDF| HashCheck
    HashCheck -->|New File| Sanitize
    HashCheck -->|Existing File Skip| Queue
    Sanitize -->|Clean Text| Extract
    Extract -->|5 Structured Pillars| Embed
    Embed -->|5x 768D Vector Arrays| NodeDB
    NodeDB -->|Push Node ID| Queue

    Queue -->|Pop Node ID| Candidate
    Candidate -->|Raw Similarity Scores| Threshold
    Threshold -->|Passing Candidates| Coherence
    Coherence -->|Qualified Pair| Reasoning
    Reasoning -->|Substantive Explanation| EdgeDB
```

# I. Penjelasan Diagram
1. **S_Local:** Seluruh orkestrasi berjalan di mesin lokal sebagai CLI pipeline, bukan service web.
2. **Main Thread - Node Ingestion:** Bertugas memastikan file baru diproses sekali saja, membersihkan teks, mengekstrak 5 pilar, lalu menulis node ke Neo4j.
3. **Queue:** Menjadi penghubung antara ingest cepat dan edge generation yang lebih mahal secara reasoning.
4. **Worker Thread - Edge Generation:** Menentukan apakah kandidat cukup layak untuk menjadi relasi graf.
5. **Per-Pillar Threshold Matrix:** Filter pertama untuk mencegah kandidat yang lemah atau tidak relevan.
6. **Semantic Coherence Gate:** Filter kedua yang menilai apakah kandidat benar-benar konsisten antar pilar, bukan hanya cocok secara permukaan.
7. **edge.reasoning:** Properti narasi final yang menjelaskan mengapa edge dibuat, tetapi hanya untuk pasangan yang sudah lolos gate kualitas.
8. **Typed Edge Merge:** Edge tetap dibuat per pilar agar penelusuran tetap jelas, tetapi logika pembuatannya lebih ketat.

# J. Struktur Repository PoC
```text
poc-task2-neo4j-vector/
├── Literature/                     # Target file PDF jurnal / literatur
├── Markdown/                       # Dokumen desain, plan, dan log eksekusi
│   ├── PoC_implementation_plan.md
│   ├── redesign_PoC_Implementation.md
│   └── redesign_2_PoC_implementation.md
├── .env                            # Kredensial API dan Neo4j
├── requirements.txt                # Dependensi Python
├── setup_indexes.py                # Inisialisasi 5 vector index Neo4j
├── orchestrator_ingest.py          # Jalur utama redesign async
├── embed_and_ingest.py             # Jalur legacy / referensi
├── query_similarity.py             # Inspector / explorer graph terminal
└── README.md                       # Entry point dokumentasi repo
```

# K. Design Skrip (Versi redesign_2 untuk `orchestrator_ingest.py`)

File orchestrator akan menjadi pusat implementasi redesign_2 dan berisi komponen berikut:

1. `class KnowledgeGraphCore:`
   * Mengelola koneksi Neo4j dan client Gemini.
   * Menyediakan helper untuk sanitasi, ekstraksi, embedding, similarity search, dan edge merge.

2. `def process_sync_pdf(filepath):`
   * Menghitung hash file.
   * Mengecek idempotensi node.
   * Melakukan sanitasi teks sebelum LLM.
   * Mengekstrak 5 pilar.
   * Melakukan embedding 768D untuk masing-masing pilar.
   * MERGE node ke Neo4j.
   * Mengembalikan `node_id` ke antrean worker.

3. `def search_candidates_by_pillar(node_id):`
   * Menjalankan KNN untuk setiap pilar.
   * Mengambil kandidat top-k yang lolos threshold matrix.
   * Menyimpan skor per pilar sebagai evidence.

4. `def validate_semantic_coherence(candidate_bundle):`
   * Menghitung apakah kandidat cukup koheren lintas pilar.
   * Menolak kandidat yang hanya kuat di satu pilar tetapi lemah di pilar lain yang seharusnya terkait.
   * Menjadi gate sebelum reasoning dan edge merge.

5. `def generate_edge_reasoning(source, target, pillar_bundle):`
   * Menghasilkan `edge.reasoning`.
   * Prompt harus menjelaskan alasan semantik yang spesifik, bukan generik.
   * Output dibatasi ke 1-2 kalimat tetapi wajib substantif.

6. `def merge_typed_edge(...)`:
   * Menyimpan relasi sesuai pilar.
   * Menulis `score`, `edge.reasoning`, `matched_pillars`, dan metadata audit yang dibutuhkan.

7. `def worker_edge_generator(q):`
   * Mengambil node dari queue.
   * Menjalankan search, gate, reasoning, dan merge.
   * Menandai hasil reject di log agar tuning mudah.

8. `def main():`
   * Menjalankan worker daemon.
   * Memproses seluruh PDF di `Literature/`.
   * Menutup worker setelah queue selesai.

# L. Execution Task dalam Bentuk Tabel
Berikut daftar task eksekusi yang cukup detail untuk developer maupun agentic AI code.

| ✅ | ID | Task Name (Perintah / Action) | Indikator Selesai (Verification) |
| :---: | :---: | --- | :--- |
| [x] | **R2-01** | **Lock Single Active Pipeline** <br> Tetapkan `orchestrator_ingest.py` sebagai jalur aktif utama, dan tandai `embed_and_ingest.py` sebagai legacy path. | Dokumentasi dan log eksekusi hanya mengarahkan user ke satu pipeline utama. |
| [x] | **R2-02** | **Standardize Edge Contract** <br> Samakan seluruh property narasi edge menjadi `edge.reasoning`, serta pastikan query tool kompatibel dengan data lama selama migrasi. | Tidak ada lagi penggunaan `summary` sebagai field final pada edge baru. |
| [x] | **R2-03** | **Define Per-Pillar Threshold Matrix** <br> Tetapkan threshold awal per pilar, misalnya background, methodology, gap, objective, dan futurework memiliki ambang yang terdokumentasi jelas. | Konfigurasi threshold tampil jelas di kode dan dapat dituning per pilar tanpa mengubah logika inti. |
| [x] | **R2-04** | **Implement Semantic Coherence Gate** <br> Tambahkan pemeriksaan koherensi lintas pilar sebelum edge disimpan. Kandidat yang hanya mirip secara permukaan harus ditolak. | Log worker menunjukkan candidate bundle yang ditolak karena tidak koheren. |
| [x] | **R2-05** | **Strengthen PDF Sanitizer** <br> Perbaiki sanitasi agar daftar pustaka, bibliography, dan referensi benar-benar terpotong sebelum ekstraksi LLM. | Output ekstraksi tidak lagi terkontaminasi sitasi atau daftar referensi. |
| [x] | **R2-06** | **Harden Extraction Prompt** <br> Rework prompt ekstraksi agar lebih eksplisit terhadap definisi 5 pilar dan anti-hallucination rules. | JSON hasil ekstraksi lebih stabil, lebih spesifik, dan tidak terlalu generik. |
| [x] | **R2-07** | **Harden Edge Reasoning Prompt** <br> Buat prompt reasoning yang menuntut alasan yang spesifik, misalnya persamaan objek riset, metode, evaluasi, atau gap. | `edge.reasoning` berisi alasan substantif, bukan kalimat dangkal yang bisa dipakai ke semua pasangan. |
| [x] | **R2-08** | **Preserve Typed Edge Structure** <br> Tetap simpan 5 typed edges per pilar, tetapi hanya jika hasil similarity dan coherence gate memenuhi syarat. | Edge per pilar tetap terlihat di Neo4j, namun jumlah false positive turun signifikan. |
| [x] | **R2-09** | **Improve Query Contract** <br> Pastikan `query_similarity.py` dapat membaca edge baru dan edge lama, lalu menampilkan evidence secara konsisten. | Query explorer menampilkan skor, reasoning, dan tipe edge tanpa mismatch field. |
| [x] | **R2-10** | **Add Dry-Run Audit Logging** <br> Tambahkan mode log audit internal untuk menampilkan candidate yang lolos dan yang ditolak selama tuning, tanpa manual review queue. | Developer dapat melihat mengapa edge dibuat atau ditolak dari terminal. |
| [x] | **R2-11** | **Create Regression Corpus Check** <br> Uji dengan set literatur lintas domain, termasuk kasus lele vs RAGAS/vector search, untuk memastikan false positive tidak muncul. | Jurnal yang semestinya tidak relevan tidak lagi saling terhubung. |
| [x] | **R2-12** | **Edge Reasoning Quality Gate Test** <br> Verifikasi bahwa reasoning tidak generik dan harus mengandung elemen spesifik yang membedakan pasangan paper. | Edge reasoning lolos hanya jika menyebutkan kemiripan substantif secara jelas. |
| [x] | **R2-13** | **Idempotent Rerun Validation** <br> Jalankan pipeline berulang pada korpus yang sama untuk memastikan node dan edge tidak berlipat ganda. | Rerun tidak menambah node atau edge duplikat. |
| [x] | **R2-14** | **Finalize Documentation Sync** <br> Sinkronkan README dan dokumen plan agar jelas mana desain lama, mana redesign, dan mana redesign_2. | Tidak ada kebingungan antara plan lama, redesign, dan redesign_2 di dokumentasi repo. |

# Catatan Tambahan Desain Prompt untuk redesign_2

Agar alasan edge tidak dangkal, prompt reasoning perlu diarahkan untuk memaksa model menjawab pertanyaan seperti:
* Apa aspek riset yang benar-benar sama?
* Apakah keduanya memakai metode, evaluasi, atau tujuan yang sejenis?
* Apakah similarity muncul di level substansi atau hanya overlap kata?

Jika model hanya bisa menghasilkan alasan generik seperti "kedua dokumen sama-sama membahas knowledge graph" tanpa bukti yang lebih spesifik, maka output reasoning itu seharusnya dianggap lemah untuk edge quality gate.
