# Universal Blueprint (Template)

## 1. Metadata & Context
* **Title:** Master Plan: Dynamic Retrieval Gate untuk Isolated Knowledge Graph
* **Date:** 16-05-2026
* **Objective:** Menyelesaikan masalah "Paceklik Relasi" (0 Edge terbentuk) pada Knowledge Graph dengan mengganti *threshold cosine similarity* statis menjadi sistem kalibrasi statistik dinamis (Z-Score) yang aman untuk lingkungan *multi-tenant* (Isolated Workspace).
* **Methodology:** 
  Pendekatan ini menggabungkan teori *Information Retrieval* dan *Site Reliability Engineering* (SRE). Kami akan mengganti tebakan angka statis dengan perhitungan probabilitas statistik yang dieksekusi di latar belakang (*background cron job*). Nilai batas lulus (*threshold*) ditentukan dengan menjumlahkan rata-rata kemiripan dokumen acak (*Noise Floor*) dengan 3 kali standar deviasinya, menjamin 99.7% signifikansi semantik. Sistem juga mengaplikasikan pembobotan khusus per-pilar (*Section-Specific Multipliers*) dan memanfaatkan file konfigurasi JSON lokal agar latensi aplikasi tetap 0%.
* **Assumptions & Constraints:** 
  *   **Asumsi:** Distribusi skor dari model `text-embedding-3-small` memiliki *noise floor* yang terpusat dan konsisten untuk populasi data akademik.
  *   **Constraint 1:** Tidak ada penggantian dari *native vector index* Neo4j. Solusi harus bekerja 100% menggunakan fitur Neo4j bawaan.
  *   **Constraint 2:** Sistem memprioritaskan "Isolated Workspace", sehingga pencarian kemiripan *harus* dibatasi per-project/user.
  *   **Scope:** Perubahan ini hanya akan menyentuh cara penentuan *threshold* (Retrieval Gate) dan *query* pencarian Neo4j, tanpa melemahkan *gating system* lain seperti *Coherence* atau *Domain Gate* (LLM DashScope).
* **Strategic Decider:**
  | Option/Decision | Alternatives | Rationale | Status |
  | :--- | :--- | :--- | :--- |
  | Menggunakan Statistical Noise Calibration (Z-Score) | Menggunakan Static Threshold (0.78) | *Threshold* statis tidak berdasar secara matematis dan terbukti menolak kandidat relasi yang sebenarnya valid. Z-Score menjamin tingkat signifikansi statistik (99.7%) di atas tingkat kebisingan acak. | Locked |
  | Section-Specific Multipliers (Pembobotan per Pilar) | Threshold yang sama untuk semua pilar | Bahasa *Methodology* cenderung *formulaic* dan memerlukan toleransi tinggi. Bahasa *Gap/Future Work* menuntut orisinalitas tinggi, sehingga *threshold*-nya harus diperketat. Ini memaksimalkan *Precision* dan *Recall* sesuai konteks pilar. | Locked |
  | Global Noise Calibration, Local Retrieval | Kalibrasi secara lokal per-user | Mengkalibrasi pada kelompok kecil (misal: 3 dokumen milik user A) akan merusak perhitungan statistik. Kita menggunakan seluruh data di database untuk mengkalibrasi *noise floor* (Global), tapi mencari relasi hanya di dalam dokumen milik user yang sama (Local) demi keamanan privasi. | Locked |
  | Skema Hybrid Nightly Update & External JSON Caching | Menghitung Z-Score setiap ada permintaan pencarian | Menghitung Z-Score secara *real-time* akan menyebabkan *database overload* (latensi tinggi). Memisahkannya ke skrip *cron job* yang menimpa file JSON memastikan bahwa aplikasi utama mengambil data *threshold* dengan overhead 0%. | Locked |

* **Knowledge Provenance & Academic Literature:**
  | Research Topic / Literature | Key Findings | Result in Architecture |
  | :--- | :--- | :--- |
  | **OpenAI Blog:** "New embedding models and API updates" (2024) | Model `text-embedding-3` menggunakan *Matryoshka Representation Learning*. Skor absolutnya lebih rendah dan terpusat dibanding `ada-002`. Skor >0.75 sering berarti duplikat identik. | Menjustifikasi bahwa *threshold* `0.78-0.82` cacat secara matematis untuk model ini. |
  | **Teori Statistik:** "The Curse of Dimensionality in Vector Spaces" | Pada dimensi tinggi (1536D), *cosine similarity* vektor acak sangat rapat (deviasi kecil). Penentuan *threshold* harus menggunakan distribusi statistik (seperti Z-Score atau MAD) di atas rata-rata *noise*. | Menjadi landasan utama penggunaan rumus `Mean + 3*StdDev` untuk kalibrasi dinamis. |
  | **Pedoman Publikasi:** "Turnitin & iThenticate Similarity Report" | Bagian *Methodology* sering berulang (toleransi kemiripan hingga 25-30%), sedangkan *Conclusion/Future Work* menuntut orisinalitas (toleransi <5-10%). | Menjustifikasi rancangan **Section-Specific Multipliers** (bobot per pilar akademik). |
  | **Paper KGC:** "FactCheck: Benchmarking Fact-Checking of LLMs" (arXiv:2403.00424) | Pendekatan terbaik KGC adalah *Two-Stage Filtering*: Filter kasar (Vector Search) untuk *recall* kandidat, lalu Filter halus (LLM Reasoning) untuk presisi *Knowledge Graph*. | Mempertahankan *Domain & Coherence Gate* dan melonggarkan *Retrieval Gate* menggunakan Z-Score. |
  | **Paper KGC:** "Factum: A Knowledge Graph Enhancer" (CEUR, 2024) | *Soft matching* (threshold moderat) terbukti lebih optimal saat dipadukan dengan validasi ontologis. | Menyetujui batas *fallback* yang lebih moderat (0.55). |

## 2. Structure & Dependencies
* **Folder Tree:** 
```text
/home/daegir/Documents/PERCOBAAN/backend-sre(prompt-modularization-v3)/backend-sre/
├── config/
│   └── thresholds.json                           # [NEW] Penyimpanan skor threshold cache
├── scripts/
│   ├── update_global_threshold.py                # [NEW] Skrip Cron Job penghitung Z-Score
│   └── Testing-Pipeline/
│       └── calibrate_fallback_threshold.py       # [NEW] Skrip eksperimen untuk mencari fallback awal
└── app/
    └── services/
        └── ingestion.py                          # [MODIFIED] Menghapus hardcode & inject Project_ID
```
* **Dependency Graph:** 
  | Affected File | Main Module | Impact |
  | :--- | :--- | :--- |
  | `ingestion.py` | `app.services.ingestion` | Skrip akan membaca dari `config/thresholds.json`. Fungsi `find_similar_nodes` dimodifikasi dengan penambahan filter `project_id`. Fungsi `create_literature_node` dimodifikasi untuk merekam `project_id`. |
  | `update_global_threshold.py` | Standalone Script | Berinteraksi dengan database Neo4j untuk menghitung *Mean* & *Standard Deviation*, lalu menimpa `config/thresholds.json`. |

## 3. Concept & Logic
* **Flow Diagram (Mermaid):** 
```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;
    
    subgraph S1 [Background Cron Job: Global Calibration]
        direction TB
        A1[Start 02:00 AM]:::init --> A2{New Nodes > 100?}:::logic
        A2 -- Yes --> A3[Query Neo4j: Get N Random Pairs]:::io
        A3 --> A4[Calculate Mean & StdDev]:::logic
        A4 --> A5[Apply Section-Specific Multipliers]:::logic
        A5 --> A6[Overwrite config/thresholds.json]:::io
        A2 -- No --> A7[Abort Job: Maintain Last State]:::init
    end

    subgraph S2 [Runtime Ingestion Pipeline: Local Edge Gen]
        direction TB
        B1[Worker Edge Gen Triggered]:::init --> B2[Read config/thresholds.json]:::io
        B2 --> B3{Is JSON Valid/Exists?}:::logic
        B3 -- No (Cold Start) --> B4[Apply Static Fallback Threshold]:::logic
        B3 -- Yes --> B5[Apply Dynamic Z-Score Threshold]:::logic
        B4 --> B6
        B5 --> B6[Neo4j: find_similar_nodes]:::io
        B6 --> B7[STRICT FILTER: target.project_id == source.project_id]:::logic
        B7 --> B8{Score >= Pillar Threshold?}:::logic
        B8 -- Yes --> B9[Proceed to Coherence & Domain Gates]:::logic
        B8 -- No --> B10[Reject Candidate Edge]:::init
    end
```

* **Execution Synopsis:** 
  | Intent | Goal | Step | Status |
  | :--- | :--- | :--- | :--- |
  | Kalibrasi Statis Awal | Menemukan nilai *Fallback* yang ideal berdasarkan populasi kecil (50 dokumen). | Membuat dan menjalankan skrip `calibrate_fallback_threshold.py` sebelum produksi. | Planned (Sub-task 1) |
  | Pemisahan I/O Threshold | Menghilangkan konfigurasi *hardcoded* dari aplikasi. | Membuat `config/thresholds.json` dan memodifikasi `ingestion.py` agar melakukan pemanggilan baca lokal. | Planned (Sub-task 2) |
  | Isolasi Data User | Menerapkan konsep *Isolated Workspace*. | Memodifikasi fungsi Node dan Retrieval di `ingestion.py` untuk mengikutsertakan parameter `project_id`. | Planned (Sub-task 2) |
  | Otomasi Adaptasi Threshold | Membuat sistem yang memelihara dirinya sendiri berdasarkan pertambahan dokumen global. | Membuat skrip `update_global_threshold.py` dengan logika Z-Score (Mean + 3 * StdDev). | Planned (Sub-task 2) |

* **Data Contract:** 
  *   **Kueri Z-Score (Neo4j):** `Mengambil n pasang dokumen acak -> Menghasilkan sekumpulan nilai cosine similarity murni.`
  *   **File JSON Config:** `{ "background": float, "methodology": float, ... }`
  *   **Retrieval Kueri Neo4j:** `(source_vector, top_k, target_project_id) -> Daftar target_id yang lolos threshold dan memiliki project_id yang sama.`

## 4. Execution & Quality
* **Execution Matrix:**
  *(Note: Detail rinci fase eksekusi akan diuraikan pada dua artefak plan turunannya: Calibration Plan dan Integration Plan.)*
  | Checkbox | Phase | Task | Detail Task | Description | Acceptance Criteria | Input / Output State | Validation Command | Risk |
  | :---: | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
  | [ ] | 1 | Master | Persetujuan Arsitektur | Validasi keseluruhan desain dengan PM / Stakeholders. | Artefak Master Plan disetujui. | - | - | Rendah |
  | [ ] | 2 | Sub-task 1 | Static Fallback | Pencarian dan penetapan nilai Fallback threshold dari 50 literatur. | Ditemukan nilai Z-Score yang akan menjadi *fallback* absolut. | 50 dokumen MOCK -> Angka ambang batas per pilar. | - | Menengah |
  | [ ] | 3 | Sub-task 2 | Integrasi Sistem | Penulisan file konfigurasi JSON, modifikasi `ingestion.py`, dan pembuatan skrip *cron job*. | Aplikasi sukses membaca dari *file* JSON eksternal; relasi berhasil terbentuk dan tersaring khusus *project_id* yang sama. | Aplikasi & Skrip Baru -> Modifikasi Neo4j & Storage | Eksekusi Unit Test | Tinggi |

* **Exit Conditions (Hard Gate):** 
  *   Skrip *cron job* dapat mengeksekusi perhitungan matematis di Neo4j dan menuliskan format JSON secara sempurna ke disk.
  *   Kueri *retrieval* di Neo4j terbukti secara tegas menolak pembuatan *edge* di antara dua jurnal yang berbeda `project_id`, meskipun tingkat kemiripan semantiknya 99%.
  *   Tidak terjadi *error Out-of-Memory* (OOM) atau *divide-by-zero* ketika *database* dikosongkan total.
* **Resource Requirements:** 
  *   Database Neo4j, koneksi internet untuk pilar-pilar ekstraksi, dan minimal RAM 1GB untuk toleransi skrip *cron job* saat *background projection*.
* **Rollback Strategy:** 
  *   *Revert* `ingestion.py` ke bentuk *hardcoded* threshold asli dan *disable* skrip cron job harian. Membatalkan pembaruan tidak akan mempengaruhi dokumen atau *edge* yang sudah ada.