semantic-layer-business-context-for-nl2sql

name	Semantic Layer — Business Context for NL2SQL
description	Skill hướng dẫn xây dựng và vận hành Semantic Layer (Lớp ngữ nghĩa doanh nghiệp). Giúp AI hiểu các khái niệm nghiệp vụ đặc thù (KPI, thuật ngữ, logic tính toán) mà Database Schema không thể hiện rõ. Bao gồm: Glossary, Value Profiles, Synonym Dictionary, Few-shot Samples. Triggers: Khi AI sinh SQL sai do không hiểu thuật ngữ nghiệp vụ, khi onboard DB mới.

Semantic Layer Skill

🎯 Semantic Layer là gì?

Semantic Layer là lớp dịch thuật ngữ doanh nghiệp → ngôn ngữ DB mà AI cần hiểu trước khi sinh SQL.

Người dùng hỏi: "Khách hàng tiềm năng tháng này"
                           │
              Không có Semantic Layer:
              LLM đoán "tiềm năng" = có_đơn_hàng → SQL SAI
                           │
              Có Semantic Layer:
              "Khách hàng tiềm năng" = orders > 3 AND total > 5M
              → LLM sinh SQL ĐÚNG 100%

---

🏗️ Cấu trúc Semantic Layer của Agent SQL

Thành phần 1 — Synonym Dictionary (Pillar 1)

File: services/nl2sql-service/core/schema_retriever.py → SYNONYMS

SYNONYMS = {
    # === Ánh xạ thuật ngữ Việt → Tên bảng ===
    "khách hàng": ["users"],
    "doanh thu": ["orders", "order_items"],
    "sản phẩm": ["products"],
    
    # === Thêm thuật ngữ nghiệp vụ tùy chỉnh ===
    "khách VIP": ["users"],           # users.is_vip = true
    "hàng tồn kho": ["products"],     # products.stock_quantity
    "đơn thành công": ["orders"],     # orders.status = 'delivered'
}

Cách thêm: Mỗi khi Admin dùng thuật ngữ nghiệp vụ mới, thêm vào đây.

---

Thành phần 2 — Value Profiles (Pillar 2)

File: services/nl2sql-service/core/prompts.py → Schema text

### Status Values for orders.status
- Valid values: 'pending', 'processing', 'shipped', 'delivered', 'cancelled'
- 'Đơn thành công' = status = 'delivered'
- 'Đơn đang giao' = status = 'shipped'
- Use EXACTLY these values in WHERE clauses.

### Product Categories
- Valid values: 'Electronics', 'Clothing', 'Food & Beverage', 'Books'
- 'Hàng điện tử' = category = 'Electronics'

---

Thành phần 3 — Business KPI Glossary

File: docs_mainengine/skills/semantic-layer/glossary.md (file này)

Đây là từ điển Business Logic mà LLM phải nắm trước khi sinh SQL:

Thuật ngữ nghiệp vụ	Định nghĩa kỹ thuật	SQL tương ứng
Khách hàng tiềm năng	≥ 3 đơn hàng thành công VÀ tổng chi tiêu > 5 triệu	COUNT(orders) >= 3 AND SUM(total_amount) > 5000000
Đơn thành công	status = 'delivered'	WHERE status = 'delivered'
Doanh thu thuần	Tổng tiền - chiết khấu	SUM(total_amount - discount)
Tỷ lệ hoàn hàng	Đơn cancelled / Tổng đơn	COUNT(cancelled) / COUNT(*)
Sản phẩm chủ lực	Doanh số > 100 đơn/tháng	COUNT(order_items) > 100 per month
Khách VIP	Tổng chi tiêu > 20 triệu	SUM(total_amount) > 20000000

---

Thành phần 4 — Few-shot Examples (SQL Samples)

Few-shot giúp LLM học cách viết SQL theo đúng convention của dự án:

### Few-shot Example 1: Tính doanh thu theo tháng
Q: "Doanh thu tháng trước là bao nhiêu?"
SQL:
SELECT SUM(total_amount) as doanh_thu
FROM orders
WHERE status = 'delivered'
  AND DATE_TRUNC('month', created_at) = DATE_TRUNC('month', CURRENT_DATE - INTERVAL '1 MONTH')

### Few-shot Example 2: Top khách hàng
Q: "5 khách hàng mua nhiều tiền nhất"
SQL:
SELECT u.name, SUM(o.total_amount) as tong_chi_tieu
FROM orders o JOIN users u ON o.user_id = u.id
WHERE o.status = 'delivered'
GROUP BY u.id, u.name
ORDER BY tong_chi_tieu DESC
LIMIT 5

---

🔧 Hướng dẫn vận hành

Khi onboard DB/Domain mới:

1. Bước 1 — Khám phá schema:

   SELECT table_name FROM information_schema.tables WHERE table_schema = 'public';
   SELECT DISTINCT status FROM orders;  -- Khám phá Value Profiles
   

2. Bước 2 — Cập nhật SYNONYMS: Mở schema_retriever.py → thêm tất cả thuật ngữ domain vào SYNONYMS

3. Bước 3 — Viết Value Profiles: Mở prompts.py → thêm ### Status Values for ... cho mọi cột enum

4. Bước 4 — Cập nhật Glossary: Mở file này → thêm thuật ngữ nghiệp vụ vào bảng KPI Glossary

5. Bước 5 — Viết Few-shot Examples: Thêm 3-5 cặp Q&SQL mẫu vào PROMPTS.py cho domain mới

6. Bước 6 — Test:

   python test_pipeline.py
   # Expect: Tất cả câu hỏi domain mới PASS
   

Checklist Semantic Layer hoàn chỉnh:

• SYNONYMS có đầy đủ thuật ngữ Việt-Anh của domain
• Value Profiles cho TẤT CẢ cột enum/categorical
• Glossary định nghĩa rõ các KPI quan trọng
• Few-shot examples cho các dạng câu hỏi phức tạp nhất
• Test pipeline chạy PASS 100%

---

🚀 Lộ trình nâng cấp: Vector-based Semantic Layer

Hiện tại Semantic Layer dùng Keyword Matching. Lộ trình nâng cấp:

Hiện tại:  SYNONYMS dictionary → Keyword scoring (Pillar 1)
    │
    ▼ Nâng cấp Phase 2:
Vector Embedding → pgvector (Supabase) → Cosine Similarity thực sự
    │
    ▼ Nâng cấp Phase 3:
RAG Pipeline → Glossary + Business Logic → LLM Context Injection

Khi nào nâng cấp: Khi DB có > 50 bảng hoặc domain có > 100 thuật ngữ nghiệp vụ.