nl2sql-core-engine-6-pillars

name	NL2SQL Core Engine — 6 Pillars
description	Skill hướng dẫn triển khai và vận hành 6 trụ cột cốt lõi của pipeline NL2SQL: Schema Linking, Value Profiling, Ambiguity Detection, Generation Trace, Retry & Repair, Evaluation Suite. Triggers: Khi sửa schema, thêm bảng mới, nâng cấp prompt, thay LLM, debug SQL sai.

NL2SQL Core Engine — 6 Pillars Skill

🎯 Khi nào dùng Skill này?

• Sửa đổi schema hoặc thêm bảng/cột mới vào database
• Nâng cấp prompt của bất kỳ agent nào trong pipeline
• Debug tại sao AI sinh ra SQL sai
• Thay đổi hoặc nâng cấp LLM model
• Thêm Value Profiles cho bảng mới
• Mở rộng SYNONYMS để hỗ trợ thêm tiếng Việt

---

📁 File Map — 6 Pillars

services/nl2sql-service/
├── core/
│   ├── schema_retriever.py     ← Pillar 1 (Schema Linking) + Pillar 2 (Value Profiling)
│   ├── prompts.py              ← Pillar 3 (Gatekeeper prompt) + Pillar 4 (Generation Trace prompts)
│   ├── llm_client.py           ← LLM abstraction layer
│   ├── schema_cache.py         ← Cache schema từ Supabase
│   └── kafka_worker.py         ← Pillar 5 (nhận repair requests)
│
├── services/
│   ├── nl2sql_service.py       ← Orchestrator: gọi 4 agents theo thứ tự
│   └── agents/
│       ├── gatekeeper_agent.py    ← Pillar 3: Ambiguity Detection
│       ├── architect_agent.py     ← Pillar 4: Query Planning
│       ├── sql_generator_agent.py ← Pillar 4: SQL Generation
│       ├── validator_agent.py     ← Pillar 4: Validation
│       └── sql_repair_agent.py   ← Pillar 5: Self-Repair
│
└── domain/
    └── models.py               ← GatekeeperOutput, GeneratorOutput, etc.

services/query-service/
└── services/query_service.py   ← Pillar 5: Dialect Regex Patches

test_pipeline.py                ← Pillar 6: 23-case Evaluation Suite

---

🔧 Hướng dẫn từng Pillar

Pillar 1 — Schema Linking

Khi thêm bảng mới vào DB:

1. Mở core/schema_retriever.py
2. Thêm ánh xạ tiếng Việt vào SYNONYMS:

   SYNONYMS = {
       ...
       "từ khóa mới": ["tên_bảng_mới"],
       "keyword mới": ["tên_bảng_mới"],
   }
   

3. Update core/prompts.py → thêm ### Table: tên_bảng_mới vào schema text

Pillar 2 — Value Profiling

Khi thêm cột có giá trị enum (status, category, type...):

1. Mở core/prompts.py
2. Thêm block sau bảng liên quan:

   ### Status Values for ten_bang.ten_cot
   - Valid values: 'value1', 'value2', 'value3'
   - Use EXACTLY these values in WHERE clauses.
   

Pillar 3 — Ambiguity Detection

Khi cần điều chỉnh độ nhạy của Gatekeeper:

1. Mở core/prompts.py → GATEKEEPER_AGENT_PROMPT
2. Điều chỉnh rule phân loại VALID/INVALID
3. Test với: "Cho tôi xem dữ liệu" (phải là INVALID) và "Tổng đơn hàng tháng này" (phải là VALID)

Pillar 4 — Generation Trace

Khi cần thêm thông tin vào intermediate_steps:

1. Mở services/nl2sql_service.py
2. Tìm chỗ collect intermediate_steps
3. Thêm field mới vào dict của từng agent

Pillar 5 — Retry & Repair

Khi phát hiện lỗi dialect mới từ wren_core:

1. Mở services/query-service/services/query_service.py
2. Thêm regex pattern mới vào fix_sql_dialect():

   sql = re.sub(r'pattern_lỗi', 'pattern_đúng', sql, flags=re.IGNORECASE)
   

Pillar 6 — Evaluation Suite

Khi thêm tính năng mới:

1. Mở test_pipeline.py
2. Thêm test case mới vào TEST_CASES list
3. Chạy: python test_pipeline.py
4. Kết quả lưu tại test_report.json

---

⚠️ Quy tắc bắt buộc

1. Sau mỗi lần sửa prompt: Chạy lại python test_pipeline.py để đảm bảo không regression
2. Sau mỗi lần thêm bảng: Cập nhật cả SYNONYMS lẫn schema text trong prompts.py
3. KHÔNG hardcode giá trị enum trong code — luôn đặt trong Value Profile của schema
4. Test Pillar 3 với câu tấn công: "DROP TABLE" phải bị chặn 100%
5. Test Pillar 5 với câu ngày tháng: "tuần này", "tháng trước" phải chạy đúng

---

📊 Checklist trước khi báo xong

• python test_pipeline.py → 23/23 PASS
• GatekeeperAgent chặn SQL Injection
• SchemaRetriever chọn đúng bảng
• Value Profiles chính xác cho bảng mới
• SQLRepairAgent test với câu hỏi ngày tháng