Add API Integration Guide for Triage Health Check endpoint with detailed request and response specifications. Update agent executor to enforce concise and clear response formatting guidelines in Vietnamese, ensuring compliance with medical guidelines and improving user interaction clarity.

API_INTEGRATION.md

@@ -0,0 +1,76 @@
+# API Integration Guide
+
+## Endpoint: Triage Health Check
+
+**URL:** `POST /api/health-check`  
+**Base URL:** `https://medagen-backend.hf.space` (hoặc URL của bạn)
+
+### Request
+
+```json
+{
+  "user_id": "string (required)",
+  "text": "string (optional, required if no image_url)",
+  "image_url": "string (optional, required if no text)",
+  "session_id": "string (optional)",
+  "location": {
+    "lat": "number (optional)",
+    "lng": "number (optional)"
+  }
+}
+```
+
+### Response
+
+```json
+{
+  "triage_level": "emergency|urgent|routine|self-care",
+  "symptom_summary": "string",
+  "red_flags": ["string"],
+  "suspected_conditions": [
+    {
+      "name": "string",
+      "source": "cv_model|guideline|user_report",
+      "confidence": "low|medium|high"
+    }
+  ],
+  "cv_findings": {
+    "model_used": "derm_cv|eye_cv|wound_cv|none",
+    "raw_output": {}
+  },
+  "recommendation": {
+    "action": "string",
+    "timeframe": "string",
+    "home_care_advice": "string",
+    "warning_signs": "string"
+  },
+  "message": "string (markdown response)",
+  "session_id": "string",
+  "nearest_clinic": {
+    "name": "string",
+    "distance_km": "number",
+    "address": "string",
+    "rating": "number"
+  }
+}
+```
+
+### Example
+
+```bash
+curl -X POST https://medagen-backend.hf.space/api/health-check \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": "user123",
+    "text": "đau mũi, có mụt nhọt",
+    "image_url": "https://example.com/image.jpg"
+  }'
+```
+
+### Notes
+
+- `text` hoặc `image_url` phải có ít nhất một
+- `session_id` tự động tạo nếu không có
+- Response `message` chứa markdown tự nhiên từ LLM
+- `triage_level` xác định mức độ khẩn cấp
+

src/agent/agent-executor.ts

@@ -184,38 +184,45 @@ ${formattedGuidelines}
 
 YÊU CẦU VỀ PHONG CÁCH VIẾT:
 1. VIẾT HOÀN TOÀN BẰNG TIẾNG VIỆT - không được dùng tiếng Anh trong response
-2. Viết TỰ NHIÊN, DỄ HIỂU như đang trò chuyện với người dùng
-3. CÓ THỂ biện luận, so sánh, giải thích "tại sao", "như thế nào" một cách tự do
-4. Sử dụng markdown để format (tiêu đề, danh sách, nhấn mạnh) cho dễ đọc
-5. PHẢI sử dụng thông tin từ "Hướng dẫn y tế từ Bộ Y Tế" ở trên - KHÔNG được tự ý tạo thông tin
-6. KHÔNG được tự thêm câu mở đầu kiểu "Based on...", "I've assessed..." hoặc "This is..."
-7. Đây là câu hỏi giáo dục, KHÔNG PHẢI chẩn đoán cá nhân
-8. Luôn nhấn mạnh: "Thông tin chỉ mang tính tham khảo, không thay thế bác sĩ"
-9. KHÔNG kê đơn, KHÔNG khuyến nghị liều thuốc cụ thể
-
-Hãy tạo một phản hồi markdown TỰ NHIÊN, có thể bao gồm:
-- Giải thích về bệnh/triệu chứng dựa trên guidelines (định nghĩa, nguyên nhân, triệu chứng)
-- Giải thích nguyên tắc điều trị từ guidelines (KHÔNG kê đơn cụ thể)
-- Hướng dẫn về phòng ngừa và chăm sóc dựa trên guidelines
-- So sánh với các bệnh tương tự nếu có
-- Disclaimer về tính tham khảo
-
-Ví dụ format markdown (KHÔNG bắt buộc phải theo đúng format này, chỉ là gợi ý):
+2. Viết NGẮN GỌN, CÔ ĐỌNG - tối đa 250-350 từ, tập trung vào thông tin quan trọng nhất
+3. Viết TỰ NHIÊN, DỄ HIỂU như đang trò chuyện với người dùng
+4. CÓ THỂ biện luận, giải thích nhưng NGẮN GỌN, không lan man
+5. Sử dụng markdown để format (tiêu đề, danh sách) cho dễ đọc
+6. PHẢI sử dụng thông tin từ "Hướng dẫn y tế từ Bộ Y Tế" ở trên - KHÔNG được tự ý tạo thông tin
+7. KHÔNG được tự thêm câu mở đầu kiểu "Based on...", "I've assessed..." hoặc "This is..."
+8. Đây là câu hỏi giáo dục, KHÔNG PHẢI chẩn đoán cá nhân
+9. Luôn nhấn mạnh: "Thông tin chỉ mang tính tham khảo, không thay thế bác sĩ"
+10. KHÔNG kê đơn, KHÔNG khuyến nghị liều thuốc cụ thể
+
+QUAN TRỌNG VỀ ĐỘ DÀI:
+- Tối đa 250-350 từ (khoảng 1-2 đoạn văn ngắn)
+- Tập trung vào: định nghĩa ngắn gọn, nguyên tắc điều trị chính, phòng ngừa
+- KHÔNG lặp lại thông tin, KHÔNG giải thích quá chi tiết
+- Ưu tiên thông tin thực tế, dễ hiểu
+
+Hãy tạo một phản hồi markdown NGẮN GỌN, cô đọng, bao gồm:
+- Định nghĩa ngắn gọn về bệnh/triệu chứng (2-3 câu)
+- Nguyên tắc điều trị chính từ guidelines (3-4 điểm ngắn gọn)
+- Hướng dẫn phòng ngừa và chăm sóc (2-3 điểm)
+- Disclaimer ngắn gọn
+
+Ví dụ format markdown NGẮN GỌN:
 ## 📚 Về bệnh [tên bệnh]
 
-[Giải thích định nghĩa, nguyên nhân, triệu chứng dựa trên guidelines]
+[Định nghĩa ngắn gọn 2-3 câu từ guidelines]
 
 ## 💊 Nguyên tắc điều trị
 
-[Giải thích nguyên tắc điều trị từ guidelines, KHÔNG kê đơn cụ thể]
+- [Điểm 1 - ngắn gọn]
+- [Điểm 2 - ngắn gọn]
+- [Điểm 3 - ngắn gọn]
 
-## 💡 Hướng dẫn phòng ngừa và chăm sóc
+## 💡 Phòng ngừa và chăm sóc
 
-[Thông tin CỤ THỂ từ guidelines về phòng ngừa và chăm sóc]
+- [Điểm 1 - ngắn gọn]
+- [Điểm 2 - ngắn gọn]
 
----
-
-**Lưu ý quan trọng:** Thông tin này chỉ mang tính tham khảo giáo dục, không thay thế bác sĩ. Nếu bạn đang có triệu chứng, hãy đến gặp bác sĩ để được khám và chẩn đoán chính xác.`;
+**Lưu ý:** Thông tin chỉ mang tính tham khảo giáo dục, không thay thế bác sĩ.`;
 
       // Log prompt and input data before sending to LLM
       logger.info('='.repeat(80));
@@ -534,42 +541,42 @@ ${formattedGuidelines}
 
 YÊU CẦU VỀ PHONG CÁCH VIẾT:
 1. VIẾT HOÀN TOÀN BẰNG TIẾNG VIỆT - không được dùng tiếng Anh trong response
-2. Viết TỰ NHIÊN, DỄ HIỂU như đang trò chuyện với bệnh nhân
-3. CÓ THỂ biện luận, so sánh, giải thích "tại sao", "như thế nào" một cách tự do
-4. Sử dụng markdown để format (tiêu đề, danh sách, nhấn mạnh) cho dễ đọc
-5. PHẢI sử dụng thông tin từ "Hướng dẫn y tế từ Bộ Y Tế" ở trên - KHÔNG được tự ý tạo thông tin
-6. Luôn nhấn mạnh: "Thông tin chỉ mang tính tham khảo, cần bác sĩ khám để chẩn đoán chính xác"
-${cvResult.top_conditions.length === 0 ? '7. Phân tích hình ảnh không đủ tin cậy, chỉ dựa vào mô tả triệu chứng và guidelines.' : ''}
-
-Hãy tạo một phản hồi markdown TỰ NHIÊN, có thể bao gồm:
-- Giải thích về tình trạng dựa trên triệu chứng và hình ảnh (nếu có)
-- So sánh các khả năng nếu có nhiều suspected conditions
-- Giải thích "tại sao" đưa ra kết luận này (explainability)
-- Hướng dẫn cụ thể về chăm sóc tại nhà dựa trên guidelines
-- Lời khuyên về hành động tiếp theo
-- Dấu hiệu cảnh báo cần đi khám ngay
-- Disclaimer về tính tham khảo
-
-Ví dụ format markdown (KHÔNG bắt buộc phải theo đúng format này, chỉ là gợi ý):
-## 📋 Tóm tắt tình trạng
+2. Viết NGẮN GỌN, CÔ ĐỌNG - tối đa 300-400 từ, tập trung vào thông tin quan trọng nhất
+3. Viết TỰ NHIÊN, DỄ HIỂU như đang trò chuyện với bệnh nhân
+4. CÓ THỂ biện luận, giải thích "tại sao" nhưng NGẮN GỌN, không lan man
+5. Sử dụng markdown để format (tiêu đề, danh sách) cho dễ đọc
+6. PHẢI sử dụng thông tin từ "Hướng dẫn y tế từ Bộ Y Tế" ở trên - KHÔNG được tự ý tạo thông tin
+7. Luôn nhấn mạnh: "Thông tin chỉ mang tính tham khảo, cần bác sĩ khám để chẩn đoán chính xác"
+${cvResult.top_conditions.length === 0 ? '8. Phân tích hình ảnh không đủ tin cậy, chỉ dựa vào mô tả triệu chứng và guidelines.' : ''}
 
-Dựa trên hình ảnh và mô tả triệu chứng của bạn...
+QUAN TRỌNG VỀ ĐỘ DÀI:
+- Tối đa 300-400 từ (khoảng 1-2 đoạn văn ngắn)
+- Tập trung vào: tình trạng có thể là gì, hướng dẫn chăm sóc ngắn gọn, khi nào cần đi khám
+- KHÔNG lặp lại thông tin, KHÔNG giải thích quá chi tiết
+- Ưu tiên thông tin thực tế, hành động cụ thể
 
-## 🔍 Phân tích
+Hãy tạo một phản hồi markdown NGẮN GỌN, cô đọng, bao gồm:
+- Tóm tắt ngắn về tình trạng có thể là gì (1-2 câu)
+- Hướng dẫn chăm sóc tại nhà ngắn gọn từ guidelines (3-4 điểm chính)
+- Khi nào cần đi khám ngay (1-2 câu)
+- Disclaimer ngắn gọn
 
-[Giải thích, biện luận, so sánh tự do dựa trên guidelines]
+Ví dụ format markdown NGẮN GỌN:
+## 📋 Tình trạng
 
-## 💡 Hướng dẫn chăm sóc tại nhà
+Dựa trên triệu chứng và hình ảnh, có khả năng bạn đang gặp [tên bệnh]. [1-2 câu giải thích ngắn gọn].
 
-[Các lời khuyên CỤ THỂ từ guidelines về phương pháp điều trị tại chỗ, lưu ý về thuốc, cách chăm sóc]
+## 💡 Chăm sóc tại nhà
 
-## ⚠️ Khi nào cần đi khám ngay
+- [Điểm 1 từ guidelines - ngắn gọn]
+- [Điểm 2 từ guidelines - ngắn gọn]
+- [Điểm 3 từ guidelines - ngắn gọn]
 
-[Dấu hiệu cảnh báo + disclaimer]
+## ⚠️ Khi nào cần đi khám
 
----
+[1-2 câu về dấu hiệu cảnh báo]
 
-**Lưu ý quan trọng:** Thông tin này chỉ mang tính tham khảo, cần bác sĩ khám để chẩn đoán chính xác.`;
+**Lưu ý:** Thông tin chỉ mang tính tham khảo, cần bác sĩ khám để chẩn đoán chính xác.`;
 
     // Log prompt and input data before sending to LLM
     logger.info('='.repeat(80));