# 1. Judul
**Blueprint Optimasi Edge Generation: Dynamic Domain Filtering & Structured Reasoning Architecture**

# 2. Tanggal
Selasa, 12 Mei 2026

# 3. Deskripsi
Dokumen ini merupakan cetak biru (*blueprint*) komprehensif untuk merefaktor prasyarat pembuatan relasi antar-jurnal (*Edge Generation Gates*) di dalam `app/services/ingestion.py`. Tujuan utama perombakan ini adalah:
1. Menghapus *hardcoded keywords* lintas-domain (seperti `AI_DOMAIN_KEYWORDS` dan `FISHERY_DOMAIN_KEYWORDS`) dan menggantinya dengan evaluasi LLM dinamis berdasarkan ekstraksi *keywords* literatur yang disebut **Gate 3 (Domain Matcher)**.
2. Memperbarui daftar kata kunci penalaran (*reasoning*) agar lebih universal dan tidak bias pada ranah Ilmu Komputer/IT.
3. Memperketat kualitas output **Gate 4 (Edge Reasoning)** dengan memaksa LLM menghasilkan paragraf penalaran (*reasoning*) yang kohesif, mengalir natural untuk dibaca manusia, menggabungkan konteks sumber dan target secara terstruktur dalam **satu paragraf per pilar** alih-alih JSON bersarang yang kaku.

# 4. Metodologi
1. **LLM as a Judge (Gate 3):** Memanfaatkan LLM untuk membandingkan semantik antara array `keyword_source` dan `keyword_target`. Ini mengeliminasi masalah *Latent Semantic Gap* (misalnya singkatan vs kepanjangan, terjemahan lintas bahasa) tanpa membutuhkan biaya komputasi yang besar berkat batasan output JSON *boolean* dan *ultra-concise reasoning*.
2. **Instruction Hierarchy (Gate 4):** Menulis ulang *prompt* Edge Reasoning dengan struktur yang sangat spesifik, memaksa LLM untuk mematuhi nada akademik, menggunakan kosakata wajib (*Specificity Keywords*), menghindari kata generik (*Generic Patterns*), dan merangkai kesimpulan dalam format paragraf kohesif. Output untuk masing-masing pilar merupakan satu string tunggal (*single string*).
3. **Regex Trapping:** Memperluas daftar `REASONING_GENERIC_PATTERNS` untuk menjebak respons LLM yang menghindar atau malas (misal: "tidak ada bukti eksplisit") jika tidak disertai dengan bukti/penghubung yang kuat.

# 5. Keputusan (Decision Log)
1. **Penghapusan Gate 3 Lama:** Kode lama Python murni untuk fungsi `detect_domain_mismatch` dihapus total.
2. **Ekstraksi Keyword dari Neo4j:** Kueri Cypher pada tahapan *Edge Generator Worker* akan dimodifikasi untuk ikut menarik properti `keywords` dari *Source Node* dan *Target Node* agar dapat dikirim ke prompt LLM Gate 3.
3. **Prompt Multibahasa:** Menolak ide *Few-Shot Example* untuk menghemat *input token*, dan menggantinya dengan aturan lintas-bahasa secara eksplisit di dalam *System Rules* LLM.
4. **Cohesive Paragraph Reasoning:** Meninggalkan format 4-Keys JSON bersarang yang menghasilkan teks robotik/kaku, beralih pada format di mana LLM mengembalikan tepat 1 string paragraf yang luwes dan enak dibaca manusia untuk setiap pilar, mencakup persinggungan, bukti spesifik sumber, bukti spesifik target, dan konvergensi akhirnya.

# 6. Alur Diagram
```mermaid
flowchart TD
    classDef process fill:#f9f2f4,stroke:#333,stroke-width:2px;
    classDef llm fill:#e1f5fe,stroke:#0277bd,stroke-width:2px;
    classDef db fill:#fff3e0,stroke:#f57c00,stroke-width:2px;
    classDef reject fill:#ffebee,stroke:#c62828,stroke-width:2px;

    A[Neo4j Node Source] -->|Extract Text & Keywords| B(Gate 1: Vector Search)
    B -->|Top-K Matches| C(Gate 2: Semantic Coherence)
    
    C -->|If Matches >= 3 Pillars| D{Gate 3: LLM Domain Matcher}:::llm
    D -->|Keywords A vs Keywords B| E{JSON: is_compatible?}
    
    E -->|False| F[REJECT: Cross-Domain Mismatch]:::reject
    E -->|True| G{Gate 4: LLM Edge Reasoning}:::llm
    
    G -->|Pillars Text Comparison| H[Cohesive Paragraph JSON]
    H --> I{Regex Validation}:::process
    
    I -->|Generic/No Evidence| J[REJECT: Reasoning Quality Fail]:::reject
    I -->|Pass| K[(Merge Edges in Neo4j)]:::db
```

# 7. Struktur Folder (Tree)
```text
/home/daegir/Documents/PERCOBAAN/backend-sre/
├── app/
│   └── services/
│       └── ingestion.py                 # File utama yang akan dimodifikasi (Gate 3 & Gate 4)
└── Markdown/
    └── dynamic-domain-filtering/          
        ├── Plan/
        │   └── dynamic-domain-filtering-plan.md  # File dokumen INI
        └── Execution-Log/                        # Laporan eksekusi
```

# 8. Asumsi & Batasan
*   **Asumsi:** Array `keywords` selalu ada di dalam Neo4j (karena telah diekstrak di fase `llm_extractor.py` sebelumnya). Jika bernilai `null` atau `[]`, LLM tetap diberikan array kosong.
*   **Batasan:** `extract_pillars_with_llm` dan alur *Chunking* / *Neo4j Insertion* sama sekali tidak disentuh. Perubahan eksklusif diisolasi pada fungsi *Edge Generation Worker*.

# 9. Konsep Tabel Metriks
| Metrik Evaluasi | Ekspektasi Parameter | Tujuan |
| :--- | :--- | :--- |
| **Akurasi Domain Match** | LLM mampu mengenali *intersection* lintas disiplin (misal: "IoT" & "Sensor"). | Meniadakan *False Negatives* akibat *exact string matching*. |
| **Kualitas Edge Reasoning** | Tidak ada lagi alasan generik seperti "sama-sama membahas". | Deskripsi relasi di Graph DB tajam, terstruktur (4 kunci), dan sangat informatif. |
| **Latensi Ekstra API** | Panggilan Gate 3 sangat ringkas (< 2 detik). | Eksekusi *Edge Generator* secara keseluruhan tetap wajar. |

# 10. Konsep Prompting & Variabel Regex

Bagian ini memetakan seluruh *prompt* dan *keyword list* secara utuh sebagai *Single Source of Truth* bagi fase implementasi.

### A. List Konstanta Validasi (Gate 4)
```python
REASONING_SPECIFICITY_KEYWORDS = {
    "metode", "metodologi", "pendekatan", "teknik", "strategi", "mekanisme", "prosedur",
    "eksperimen", "pengujian", "analisis", "observasi", "survei", "simulasi", "skenario",
    "evaluasi", "hasil", "metrik", "indikator", "parameter", "kriteria", "kinerja", "efisiensi", "akurasi", "efektivitas",
    "tujuan", "sasaran", "hipotesis", "fokus", "gap", "keterbatasan", "masalah", "kendala", "tantangan", "kelemahan",
    "variabel", "faktor", "pengaruh", "korelasi", "dampak", "penggunaan", "pemanfaatan", "implementasi", "sampel", "dataset", "data"
}

REASONING_GENERIC_PATTERNS = [
    r"\bsama[- ]?sama membahas\b",
    r"\bkeduanya membahas\b",
    r"\bmemiliki kemiripan\b",
    r"\bsecara umum\b",
    r"\btopik serupa\b",
    r"\bkeduanya berfokus pada\b",
    r"\bdalam konteks yang sama\b",
    r"\bhanya memberikan\b",
    r"\btidak ada bukti eksplisit\b",
]

REASONING_NATURAL_CONNECTORS = [
    "Berangkat dari fokus yang sama pada",
    "Sebagai titik temu, kedua studi ini",
    "Sementara literatur pertama mengeksplorasi",
    "literatur kedua melengkapinya dengan",
    "Keduanya terkonvergensi dalam upaya",
    "Pendekatan yang ditawarkan oleh sumber diperluas oleh target melalui",
    "Secara spesifik, sumber menyoroti",
    "yang sejalan dengan temuan target mengenai",
    "Irisan utama terletak pada",
    "Hal ini ditegaskan kembali oleh literatur target yang",
    "berbeda dengan target yang menerapkan",
    "Namun, keduanya bermuara pada kesimpulan bahwa"
]
```

### B. Prompt Gate 3: Domain Compatibility Matcher
*(Fungsi pemanggilan LLM baru yang menerima argumen `keyword_source` dan `keyword_target`)*
```python
# System Role
"You are an expert academic domain classifier."

# Task Instruction & Rules
"Compare two sets of research keywords. Determine if they share the same overarching academic domain or have a strong interdisciplinary intersection.

Rules:
1. Focus on latent semantic meaning, not exact string matches.
2. Treat concepts in different languages as identical if their meanings align.
3. Resolve abbreviations to their full concepts."

# Output Format
"Return ONLY a valid JSON object with exactly two keys:
- reason: Ultra-concise explanation of their relationship or mismatch (under 10 words).
- is_compatible: boolean (true if domains intersect/match, false if unrelated)."

# Input Injection
"Source Keywords: {keyword_source}
Target Keywords: {keyword_target}"
```

### C. Prompt Gate 4: Edge Reasoning Generator
*(Modifikasi dari prompt yang ada di dalam `generate_edge_reasoning` menggunakan *Prompt Engineering Patterns: Instruction Hierarchy & Few-Shot Learning*)*
```python
# System Role
"You are an expert academic synthesizer. Your task is to analyze excerpts from two research papers and write a highly cohesive, natural-sounding Indonesian paragraph explaining their semantic intersection for building a Knowledge Graph."

# Task Instruction & Constraints
prompt = f"""
## ROLE & CONTEXT
You are an expert academic synthesizer. Your task is to analyze excerpts from two research papers and write a highly cohesive, natural-sounding Indonesian paragraph explaining their semantic intersection for building a Knowledge Graph.

## TASK
Generate highly specific reasoning justifying the semantic similarity between the Source and Target excerpts for the requested pillars: {categories}.

## STYLE & TONE GUIDELINES
1. ONE PARAGRAPH ONLY: Write a single, flowing paragraph per pillar (maximum 60 words). DO NOT use bullet points, lists, or nested JSON objects.
2. NATURAL FLOW: Avoid robotic, template-like sentence structures.
3. SYNTHESIS, NOT LISTING: Integrate the relevance, source evidence, target evidence, and conclusion into a seamless narrative.

## VOCABULARY & CONNECTORS
You MUST weave at least one of these analytical terms: [metode, evaluasi, analisis, dataset, variabel, mekanisme, efisiensi, metrik, parameter, korelasi, pendekatan, gap, masalah, hasil].

To ensure a natural academic flow, highly consider using these connector phrases (or variations of them):
- "Berangkat dari fokus yang sama pada..."
- "Sementara literatur pertama mengeksplorasi [X], literatur kedua melengkapinya dengan [Y]..."
- "Keduanya terkonvergensi dalam upaya..."
- "Pendekatan yang ditawarkan oleh sumber diperluas oleh target melalui..."
- "Sebagai titik temu, kedua studi ini..."
- "Irisan utama terletak pada..."
- "Secara spesifik, sumber menyoroti [X], yang sejalan dengan temuan target mengenai [Y]..."

## EXAMPLES (FEW-SHOT)
[BAD / ROBOTIC]
Relevansi terlihat melalui pendekatan evaluasi. Literatur sumber mengadopsi RAG dengan LitQA benchmark. Sementara itu target mengimplementasikan pipeline dua tahap. Konvergensi terlihat pada evaluasi metode.

[GOOD / NATURAL]
Berangkat dari fokus yang sama pada evaluasi sistem RAG, literatur sumber secara spesifik menguji performa menggunakan benchmark LitQA. Sementara itu, literatur kedua melengkapinya dengan mengimplementasikan kerangka kerja RAGAS tanpa referensi. Sebagai titik temu, kedua studi ini terkonvergensi dalam upaya memvalidasi keandalan dan metrik pencarian informasi pada arsitektur berbasis LLM.

## GLOBAL CONSTRAINTS & FORMAT
- ZERO HALLUCINATION: Extract ONLY from the provided excerpts.
- BANNED PHRASES: Never use generic fillers like "sama-sama membahas" atau "keduanya berfokus pada".
- INSUFFICIENT EVIDENCE: If the excerpts only share a broad topic but lack overlapping technical specifics, return EXACTLY the phrase "Tidak ada bukti eksplisit" for that pillar.
- Output MUST be a valid JSON object where keys are the pillar names and values are the cohesive reasoning string.

Source Title: {source_title}
Target Title: {target_title}

Compiled Text Excerpts:
{pillars_text}
"""
```

# 11. Langkah Implementasi
1. **Pemurnian Kode Lama:** Menghapus set variabel domain *hardcoded* (`AI_DOMAIN_KEYWORDS` dll) dan menghapus fungsi `detect_domain_mismatch`.
2. **Pembaruan Cypher Queries:** Di dalam `worker_edge_generator`, menambahkan pemanggilan atribut `.keywords` pada blok pengambilan data Source dan Target dari Neo4j.
3. **Penyuntikan Gate 3:** Membuat fungsi baru `evaluate_domain_compatibility_with_llm` dan meletakkannya tepat setelah evaluasi *Coherence* dan sebelum evaluasi *Reasoning* berjalan.
4. **Pembaruan Gate 4:** Mengganti parameter Prompt lama di `generate_edge_reasoning` dengan Prompt baru (paragraf kohesif + Few Shot Example + Natural Connectors).
5. **Penyesuaian Validator JSON:** Menyesuaikan `validate_edge_reasoning_quality` karena formatnya kembali menjadi string paragraf tunggal per pilar, lalu melakukan *regex matching*.
6. **Penyesuaian Kueri Penyimpanan Edge:** Menyesuaikan `create_lexicographical_edges_batch` karena reasoning_data kembali berupa string.

# 12. Tabel Eksekusi Task

| Check Box | Fase | Task | Detail Task | Deskripsi | Acceptance Criteria |
| :---: | :---: | :---: | :--- | :--- | :--- |
| [x] | 1 - Cleanup | Hapus Hardcoded Keyword | Bersihkan array `AI_DOMAIN_KEYWORDS` dan `FISHERY_DOMAIN_KEYWORDS` beserta fungsi `detect_domain_mismatch`. | Membuang logika lama dari `ingestion.py` agar tidak menjadi beban kode. | Fungsi dan variabel lama tidak lagi eksis di dalam skrip `ingestion.py`. |
| [x] | 2 - Constants Update | Update Universal Reasoning Keywords | Mengganti isi dari `REASONING_SPECIFICITY_KEYWORDS` dan menambahkan elemen pada `REASONING_GENERIC_PATTERNS`. Tambahkan list `REASONING_NATURAL_CONNECTORS`. | Menyalin daftar konstanta universal dari Blueprint ini ke dalam `ingestion.py`. | Konstanta termutakhir sesuai persis dengan daftar pada poin 10-A Blueprint ini. |
| [x] | 3 - Cypher Mod | Ambil Array Keywords dari DB | Modifikasi pemanggilan cypher query di dalam `worker_edge_generator`. | Pastikan kueri mengembalikan properti `n.keywords` untuk source, dan `target.keywords` untuk node target. | Data `keyword_source` dan `keyword_target` berhasil diekstrak dan masuk ke dalam memori Python. |
| [x] | 4 - LLM Gate 3 | Buat Modul Evaluator Domain | Buat fungsi `evaluate_domain_compatibility_with_llm`. | Membuat pemanggilan API LLM (menggunakan DashScope) yang menerima *prompt* Gate 3 dari Blueprint 10-B dan mengembalikan JSON Boolean. | Fungsi sukses mengembalikan tuple/dict `{"is_compatible": True/False, "reason": "..."}`. |
| [x] | 5 - Orchestration | Sisipkan Gate 3 di Pipeline | Letakkan pemanggilan `evaluate_domain_compatibility_with_llm` di dalam *loop* `worker_edge_generator`. | Jika `is_compatible` adalah False, *continue* loop dan lompat ke kandidat jurnal berikutnya. | Fungsi pembentuk Relasi berhasil mencegah kandidat lintas domain secara dinamis. |
| [x] | 6 - LLM Gate 4 | Update Prompt Edge Reasoning | Timpa blok *prompt* di `generate_edge_reasoning` dengan versi paragraf kohesif dari Blueprint 10-C. | Mengimplementasikan batasan kata, *Few-Shot Examples*, dan gaya bahasa yang mengalir ke dalam pemanggilan LLM. | LLM menghasilkan format string kohesif per pilar. |
| [x] | 7 - Validator Fix | Update `validate_edge_reasoning_quality` | Sesuaikan validasi dengan struktur string tunggal. | Jalankan Regex dan Specificity Check langsung pada string paragraf. | Validator berhasil mendeteksi "Tidak ada bukti eksplisit" atau kata-kata generik pada respons paragraf. |
| [x] | 8 - DB Injection | Serialisasi Output JSON Edge | Update `create_lexicographical_edges_batch`. | Kembalikan logika ke penyimpanan string (bukan dict json.dumps()) untuk di- *inject* sebagai properti Neo4j. | Properti `reasoning` pada edge di Neo4j berbentuk String paragraf yang bisa dibaca manusia. |
| [x] | 9 - Testing | Dry-Run & Edge Audit | Eksekusi pipeline terhadap jurnal dan cek CLI log-nya. | Uji performa dan kualitas *reasoning* dari Edge yang dihasilkan; amati keputusan "Gate 3". | Terdapat log "REJECT: Cross-Domain Mismatch" atau Log "Pass" dengan reasoning paragraf kohesif. |
| [x] | 10 - Reporting | Buat Laporan Eksekusi | Buat laporan di `Execution-Log`. | Dokumentasikan hasil dari eksekusi ini. | Dokumen Final Report tersedia di direktori *Markdown*. |