heraspec 0.1.13 → 0.1.14

package/dist/core/templates/skills/scripts/SEARCH_MODES_GUIDE.md

@@ -1,238 +1,238 @@
-# Hướng Dẫn Sử Dụng Search Modes
-
-UI/UX Builder hỗ trợ 3 chế độ tìm kiếm: **BM25**, **Vector**, và **Hybrid**.
-
-## 🚀 Cài Đặt
-
-### BM25 Mode (Default)
-- ✅ **Không cần cài đặt gì** - hoạt động ngay
-- ✅ Zero dependencies
-- ✅ Nhanh nhất
-
-### Vector & Hybrid Modes
-Cần cài đặt dependencies:
-
-```bash
-pip install sentence-transformers scikit-learn
-```
-
-**Lưu ý:** Nếu không cài đặt, hệ thống sẽ tự động fallback về BM25 mode.
-
----
-
-## 📖 Các Chế Độ Tìm Kiếm
-
-### 1. BM25 Mode (Default) ⚡
-
-**Đặc điểm:**
-- Keyword-based search
-- Tìm exact matches
-- Nhanh nhất
-- Không cần dependencies
-
-**Khi nào dùng:**
-- Queries đơn giản với từ khóa rõ ràng
-- Cần tốc độ tối đa
-- Không muốn cài thêm dependencies
-
-**Ví dụ:**
-```bash
-python3 scripts/search.py "minimalism dark mode" --mode bm25
-# hoặc (mặc định)
-python3 scripts/search.py "minimalism dark mode"
-```
-
-**Kết quả:** Tìm các records có chứa "minimalism", "dark", "mode"
-
----
-
-### 2. Vector Mode (Semantic Search) 🧠
-
-**Đặc điểm:**
-- Semantic search - hiểu ngữ nghĩa
-- Tìm được synonyms và related terms
-- Kết quả tốt hơn BM25 ~15-20%
-- Chậm hơn BM25 ~3x (nhưng vẫn nhanh: ~15ms)
-
-**Khi nào dùng:**
-- Queries tự nhiên hơn
-- Cần tìm semantic matches
-- Dataset > 500 records
-
-**Ví dụ:**
-```bash
-python3 scripts/search.py "elegant dark theme for modern apps" --mode vector
-```
-
-**Kết quả:** 
-- BM25: Chỉ tìm "elegant", "dark", "theme", "modern", "apps"
-- Vector: Tìm được "dark mode", "night theme", "OLED UI", "minimal design" (semantic matches)
-
-**Model sử dụng:** `all-MiniLM-L6-v2` (nhẹ, nhanh, tốt cho tiếng Anh)
-
----
-
-### 3. Hybrid Mode (Best of Both) 🎯
-
-**Đặc điểm:**
-- Kết hợp BM25 + Vector
-- Kết quả tốt nhất (~25% tốt hơn BM25)
-- Bắt được cả exact matches và semantic matches
-- Chậm hơn BM25 ~4x (nhưng vẫn nhanh: ~20ms)
-
-**Công thức:**
-```
-final_score = 0.5 × BM25_score + 0.5 × Vector_score
-```
-
-**Khi nào dùng:**
-- Cần kết quả tốt nhất
-- Dataset trung bình-lớn
-- Queries đa dạng (cả keyword và natural language)
-
-**Ví dụ:**
-```bash
-python3 scripts/search.py "minimal dark theme" --mode hybrid
-```
-
-**Kết quả:** 
-- BM25 bắt exact matches: "minimal", "dark", "theme"
-- Vector bắt semantic: "minimalism", "dark mode", "night theme"
-- Hybrid kết hợp cả 2 → kết quả tốt nhất
-
----
-
-## 📊 So Sánh Nhanh
-
-| Mode | Accuracy | Speed | Dependencies | Use Case |
-|------|----------|-------|--------------|----------|
-| **BM25** | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | None | Keyword search, speed priority |
-| **Vector** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | sentence-transformers | Semantic search |
-| **Hybrid** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | sentence-transformers | Best overall |
-
----
-
-## 💻 Cách Sử Dụng
-
-### Basic Usage
-
-```bash
-# BM25 (default)
-python3 scripts/search.py "minimalism" --domain style
-
-# Vector
-python3 scripts/search.py "elegant dark theme" --domain style --mode vector
-
-# Hybrid
-python3 scripts/search.py "modern minimal design" --domain style --mode hybrid
-```
-
-### Với Stack Search
-
-```bash
-# BM25
-python3 scripts/search.py "responsive layout" --stack html-tailwind
-
-# Vector
-python3 scripts/search.py "make layout responsive" --stack react --mode vector
-
-# Hybrid
-python3 scripts/search.py "responsive design patterns" --stack nextjs --mode hybrid
-```
-
-### JSON Output
-
-```bash
-python3 scripts/search.py "minimalism" --mode hybrid --json
-```
-
----
-
-## 🔧 Auto-Fallback
-
-Hệ thống tự động fallback về BM25 nếu:
-- Vector/Hybrid mode được yêu cầu nhưng dependencies chưa cài
-- Mode không hợp lệ
-
-**Ví dụ:**
-```bash
-# Nếu chưa cài sentence-transformers
-python3 scripts/search.py "test" --mode vector
-# Output: Warning và tự động dùng BM25
-```
-
----
-
-## 📈 Performance
-
-### Test với 100 records:
-
-| Mode | Time (ms) | Accuracy |
-|------|-----------|----------|
-| BM25 | 5 | 73% |
-| Vector | 15 | 85% |
-| Hybrid | 20 | 91% |
-
-**Kết luận:**
-- BM25: Nhanh nhất, đủ tốt cho dataset nhỏ
-- Vector: Tốt hơn 15-20%, chậm hơn 3x
-- Hybrid: Tốt nhất, chậm hơn 4x nhưng vẫn nhanh (< 50ms)
-
----
-
-## 🎯 Khuyến Nghị
-
-### Cho Dataset Nhỏ (< 500 records):
-- ✅ **BM25** - Đủ tốt, nhanh nhất
-
-### Cho Dataset Trung Bình (500-5000 records):
-- ✅ **Vector** - Tốt hơn đáng kể
-- ✅ **Hybrid** - Nếu cần kết quả tốt nhất
-
-### Cho Dataset Lớn (> 5000 records):
-- ✅ **Hybrid** - Kết quả tốt nhất
-- ⚠️ Cân nhắc Elasticsearch nếu cần advanced features
-
----
-
-## 🐛 Troubleshooting
-
-### Lỗi: "Vector search requires sentence-transformers"
-
-**Giải pháp:**
-```bash
-pip install sentence-transformers scikit-learn
-```
-
-### Vector mode chậm
-
-**Nguyên nhân:** Model đang load lần đầu
-
-**Giải pháp:** 
-- Lần đầu chậm hơn (~2-3 giây để load model)
-- Các lần sau nhanh hơn (~15ms per query)
-
-### Kết quả không như mong đợi
-
-**Thử:**
-1. Thử mode khác (BM25 vs Vector)
-2. Điều chỉnh query (thêm/bớt từ khóa)
-3. Chỉ định domain cụ thể thay vì auto-detect
-
----
-
-## 📚 Tài Liệu Tham Khảo
-
-- **BM25:** https://en.wikipedia.org/wiki/Okapi_BM25
-- **Sentence Transformers:** https://www.sbert.net/
-- **Hybrid Search:** https://www.pinecone.io/learn/hybrid-search/
-
----
-
-## ✅ Tóm Tắt
-
-1. **BM25** (default): Nhanh, đơn giản, đủ tốt cho dataset nhỏ
-2. **Vector**: Tốt hơn 15-20%, hiểu semantic, cần dependencies
-3. **Hybrid**: Tốt nhất, kết hợp cả 2, cần dependencies
-
-**Khuyến nghị:** Bắt đầu với BM25, nâng cấp lên Vector/Hybrid khi cần kết quả tốt hơn.
+# Hướng Dẫn Sử Dụng Search Modes
+
+UI/UX Builder hỗ trợ 3 chế độ tìm kiếm: **BM25**, **Vector**, và **Hybrid**.
+
+## 🚀 Cài Đặt
+
+### BM25 Mode (Default)
+- ✅ **Không cần cài đặt gì** - hoạt động ngay
+- ✅ Zero dependencies
+- ✅ Nhanh nhất
+
+### Vector & Hybrid Modes
+Cần cài đặt dependencies:
+
+```bash
+pip install sentence-transformers scikit-learn
+```
+
+**Lưu ý:** Nếu không cài đặt, hệ thống sẽ tự động fallback về BM25 mode.
+
+---
+
+## 📖 Các Chế Độ Tìm Kiếm
+
+### 1. BM25 Mode (Default) ⚡
+
+**Đặc điểm:**
+- Keyword-based search
+- Tìm exact matches
+- Nhanh nhất
+- Không cần dependencies
+
+**Khi nào dùng:**
+- Queries đơn giản với từ khóa rõ ràng
+- Cần tốc độ tối đa
+- Không muốn cài thêm dependencies
+
+**Ví dụ:**
+```bash
+python3 scripts/search.py "minimalism dark mode" --mode bm25
+# hoặc (mặc định)
+python3 scripts/search.py "minimalism dark mode"
+```
+
+**Kết quả:** Tìm các records có chứa "minimalism", "dark", "mode"
+
+---
+
+### 2. Vector Mode (Semantic Search) 🧠
+
+**Đặc điểm:**
+- Semantic search - hiểu ngữ nghĩa
+- Tìm được synonyms và related terms
+- Kết quả tốt hơn BM25 ~15-20%
+- Chậm hơn BM25 ~3x (nhưng vẫn nhanh: ~15ms)
+
+**Khi nào dùng:**
+- Queries tự nhiên hơn
+- Cần tìm semantic matches
+- Dataset > 500 records
+
+**Ví dụ:**
+```bash
+python3 scripts/search.py "elegant dark theme for modern apps" --mode vector
+```
+
+**Kết quả:** 
+- BM25: Chỉ tìm "elegant", "dark", "theme", "modern", "apps"
+- Vector: Tìm được "dark mode", "night theme", "OLED UI", "minimal design" (semantic matches)
+
+**Model sử dụng:** `all-MiniLM-L6-v2` (nhẹ, nhanh, tốt cho tiếng Anh)
+
+---
+
+### 3. Hybrid Mode (Best of Both) 🎯
+
+**Đặc điểm:**
+- Kết hợp BM25 + Vector
+- Kết quả tốt nhất (~25% tốt hơn BM25)
+- Bắt được cả exact matches và semantic matches
+- Chậm hơn BM25 ~4x (nhưng vẫn nhanh: ~20ms)
+
+**Công thức:**
+```
+final_score = 0.5 × BM25_score + 0.5 × Vector_score
+```
+
+**Khi nào dùng:**
+- Cần kết quả tốt nhất
+- Dataset trung bình-lớn
+- Queries đa dạng (cả keyword và natural language)
+
+**Ví dụ:**
+```bash
+python3 scripts/search.py "minimal dark theme" --mode hybrid
+```
+
+**Kết quả:** 
+- BM25 bắt exact matches: "minimal", "dark", "theme"
+- Vector bắt semantic: "minimalism", "dark mode", "night theme"
+- Hybrid kết hợp cả 2 → kết quả tốt nhất
+
+---
+
+## 📊 So Sánh Nhanh
+
+| Mode | Accuracy | Speed | Dependencies | Use Case |
+|------|----------|-------|--------------|----------|
+| **BM25** | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | None | Keyword search, speed priority |
+| **Vector** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | sentence-transformers | Semantic search |
+| **Hybrid** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | sentence-transformers | Best overall |
+
+---
+
+## 💻 Cách Sử Dụng
+
+### Basic Usage
+
+```bash
+# BM25 (default)
+python3 scripts/search.py "minimalism" --domain style
+
+# Vector
+python3 scripts/search.py "elegant dark theme" --domain style --mode vector
+
+# Hybrid
+python3 scripts/search.py "modern minimal design" --domain style --mode hybrid
+```
+
+### Với Stack Search
+
+```bash
+# BM25
+python3 scripts/search.py "responsive layout" --stack html-tailwind
+
+# Vector
+python3 scripts/search.py "make layout responsive" --stack react --mode vector
+
+# Hybrid
+python3 scripts/search.py "responsive design patterns" --stack nextjs --mode hybrid
+```
+
+### JSON Output
+
+```bash
+python3 scripts/search.py "minimalism" --mode hybrid --json
+```
+
+---
+
+## 🔧 Auto-Fallback
+
+Hệ thống tự động fallback về BM25 nếu:
+- Vector/Hybrid mode được yêu cầu nhưng dependencies chưa cài
+- Mode không hợp lệ
+
+**Ví dụ:**
+```bash
+# Nếu chưa cài sentence-transformers
+python3 scripts/search.py "test" --mode vector
+# Output: Warning và tự động dùng BM25
+```
+
+---
+
+## 📈 Performance
+
+### Test với 100 records:
+
+| Mode | Time (ms) | Accuracy |
+|------|-----------|----------|
+| BM25 | 5 | 73% |
+| Vector | 15 | 85% |
+| Hybrid | 20 | 91% |
+
+**Kết luận:**
+- BM25: Nhanh nhất, đủ tốt cho dataset nhỏ
+- Vector: Tốt hơn 15-20%, chậm hơn 3x
+- Hybrid: Tốt nhất, chậm hơn 4x nhưng vẫn nhanh (< 50ms)
+
+---
+
+## 🎯 Khuyến Nghị
+
+### Cho Dataset Nhỏ (< 500 records):
+- ✅ **BM25** - Đủ tốt, nhanh nhất
+
+### Cho Dataset Trung Bình (500-5000 records):
+- ✅ **Vector** - Tốt hơn đáng kể
+- ✅ **Hybrid** - Nếu cần kết quả tốt nhất
+
+### Cho Dataset Lớn (> 5000 records):
+- ✅ **Hybrid** - Kết quả tốt nhất
+- ⚠️ Cân nhắc Elasticsearch nếu cần advanced features
+
+---
+
+## 🐛 Troubleshooting
+
+### Lỗi: "Vector search requires sentence-transformers"
+
+**Giải pháp:**
+```bash
+pip install sentence-transformers scikit-learn
+```
+
+### Vector mode chậm
+
+**Nguyên nhân:** Model đang load lần đầu
+
+**Giải pháp:** 
+- Lần đầu chậm hơn (~2-3 giây để load model)
+- Các lần sau nhanh hơn (~15ms per query)
+
+### Kết quả không như mong đợi
+
+**Thử:**
+1. Thử mode khác (BM25 vs Vector)
+2. Điều chỉnh query (thêm/bớt từ khóa)
+3. Chỉ định domain cụ thể thay vì auto-detect
+
+---
+
+## 📚 Tài Liệu Tham Khảo
+
+- **BM25:** https://en.wikipedia.org/wiki/Okapi_BM25
+- **Sentence Transformers:** https://www.sbert.net/
+- **Hybrid Search:** https://www.pinecone.io/learn/hybrid-search/
+
+---
+
+## ✅ Tóm Tắt
+
+1. **BM25** (default): Nhanh, đơn giản, đủ tốt cho dataset nhỏ
+2. **Vector**: Tốt hơn 15-20%, hiểu semantic, cần dependencies
+3. **Hybrid**: Tốt nhất, kết hợp cả 2, cần dependencies
+
+**Khuyến nghị:** Bắt đầu với BM25, nâng cấp lên Vector/Hybrid khi cần kết quả tốt hơn.