Upload 73 files

.env

@@ -0,0 +1,9 @@
+# .env file
+GEMINI_API_KEY="AIzaSyAn1HDv1_zU4TQbwwUtBIOo7tu5iKVBWho"
+GOOGLE_API_KEY="AIzaSyAn1HDv1_zU4TQbwwUtBIOo7tu5iKVBWho"
+OPENAI_API_KEY="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"
+
+COHERE_API_KEY="D6PBHYizSmWFqzHoMWafV65yJelDh6X3Xg0ghIue"
+
+# Production
+# COHERE_API_KEY="VFaacPxkjW0L4HaijiBXuKYWqgYj8XkAo3o5uMWu"

.gitattributes

@@ -1,35 +1,4 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+# Auto detect text files and perform LF normalization
+* text=auto
+knowledge_base/chroma/c8c2137c-264c-4fe5-a301-20b02985da11/data_level0.bin filter=lfs diff=lfs merge=lfs -text
+knowledge_base/chroma/chroma.sqlite3 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,2 @@
+.env
+secrets.toml

.streamlit/secrets.toml

@@ -0,0 +1,23 @@
+# Streamlit Secrets Configuration
+# Copy your API keys here for production
+# For local development, you can still use .env file
+
+[api_keys]
+GEMINI_API_KEY = "AIzaSyAn1HDv1_zU4TQbwwUtBIOo7tu5iKVBWho"
+OPENAI_API_KEY = "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"  
+COHERE_API_KEY = "D6PBHYizSmWFqzHoMWafV65yJelDh6X3Xg0ghIue"
+
+# Production
+# COHERE_API_KEY="VFaacPxkjW0L4HaijiBXuKYWqgYj8XkAo3o5uMWu"
+
+# Database and storage paths
+[paths]
+KNOWLEDGE_BASE_PATH = "./knowledge_base"
+DOCUMENTS_FOLDER = "./viettelpay_docs"
+
+# Model configurations
+[models]
+EMBEDDING_MODEL = "dangvantuan/vietnamese-document-embedding"
+LLM_PROVIDER = "gemini"
+GEMINI_MODEL = "gemini-2.0-flash"
+OPENAI_MODEL = "gpt-4o-mini" 

knowledge_base/chroma/c8c2137c-264c-4fe5-a301-20b02985da11/data_level0.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:23add52afbe7588391f32d3deffb581b2663d2e2ad8851aba7de25e6b3f66761
+size 32120000

knowledge_base/chroma/chroma.sqlite3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b962ed5c081a92e80ccb83ef40c1dfb530542ca161a4cefe9fc6ccebebf23e75
+size 1937408

requirements.txt

@@ -1,3 +1,32 @@
-altair
+# requirements.txt
 pandas
-streamlit
+python-docx
+langchain-chroma==0.2.4
+chromadb==1.0.12
+langchain_cohere==0.4.4
+langchain==0.3.25
+langgraph
+langchain_community==0.3.24
+google-generativeai
+openai
+sentence-transformers==4.1.0
+pydantic
+python-dotenv
+PyYAML
+tqdm
+loguru
+scikit-learn==1.6.1
+protobuf<3.21
+grpcio-status==1.48.2
+torch
+transformers==4.52.4
+rank_bm25==0.2.2
+markitdown[docx]
+underthesea
+pyvi
+langchain-huggingface==0.2.0
+streamlit
+langmem
+dotenv
+numpy==1.26.4
+python-docx

src/agent/nodes.py

@@ -0,0 +1,463 @@
+"""
+LangGraph Agent State and Processing Nodes
+"""
+
+from typing import Dict, List, Optional, TypedDict, Annotated
+from langchain.schema import Document
+from langchain_core.messages import AnyMessage
+from langgraph.graph.message import add_messages
+import json
+import re
+
+from src.agent.prompts import (
+    INTENT_CLASSIFICATION_PROMPT,
+    QUERY_ENHANCEMENT_PROMPT,
+    RESPONSE_GENERATION_PROMPT,
+    get_system_prompt_by_intent,
+)
+
+
+class ViettelPayState(TypedDict):
+    """State for ViettelPay agent workflow with message history support"""
+
+    # Message history for multi-turn conversation
+    messages: Annotated[List[AnyMessage], add_messages]
+
+    # Processing
+    intent: Optional[str]
+    confidence: Optional[float]
+
+    # Query enhancement
+    enhanced_query: Optional[str]
+
+    # Knowledge retrieval
+    retrieved_docs: Optional[List[Document]]
+
+    # Conversation context (cached to avoid repeated computation)
+    conversation_context: Optional[str]
+
+    # Response type metadata
+    response_type: Optional[str]  # "script" or "generated"
+
+    # Metadata
+    error: Optional[str]
+    processing_info: Optional[Dict]
+
+
+def get_conversation_context(messages: List[AnyMessage], max_messages: int = 3) -> str:
+    """
+    Extract conversation context from message history
+
+    Args:
+        messages: List of conversation messages
+        max_messages: Maximum number of recent messages to include
+
+    Returns:
+        Formatted conversation context string
+    """
+    if len(messages) <= 1:
+        return ""
+
+    context = "\n\nLịch sử cuộc hội thoại:\n"
+    # Get recent messages (excluding the current/last message for intent classification)
+    recent_messages = messages[
+        -(max_messages + 1) : -1
+    ]  # Exclude the very last message
+
+    for msg in recent_messages:
+        # Handle different message types more robustly
+        if hasattr(msg, "type"):
+            if msg.type == "human":
+                role = "Người dùng"
+            elif msg.type == "ai":
+                role = "Trợ lý"
+            else:
+                role = f"Unknown-{msg.type}"
+        elif hasattr(msg, "role"):
+            if msg.role in ["user", "human"]:
+                role = "Người dùng"
+            elif msg.role in ["assistant", "ai"]:
+                role = "Trợ lý"
+            else:
+                role = f"Unknown-{msg.role}"
+        else:
+            role = "Unknown"
+
+        # Limit message length to avoid token overflow
+        # content = msg.content[:1000] + "..." if len(msg.content) > 1000 else msg.content
+        content = msg.content
+        context += f"{role}: {content}\n"
+    # print(context)
+    return context
+
+
+def classify_intent_node(state: ViettelPayState, llm_client) -> ViettelPayState:
+    """Node for intent classification using LLM with conversation context"""
+
+    # Get the latest user message
+    messages = state["messages"]
+    if not messages:
+        return {
+            **state,
+            "intent": "unclear",
+            "confidence": 0.0,
+            "error": "No messages found",
+        }
+
+    # Find the last human/user message
+    user_message = None
+    for msg in reversed(messages):
+        if hasattr(msg, "type") and msg.type == "human":
+            user_message = msg.content
+            break
+        elif hasattr(msg, "role") and msg.role == "user":
+            user_message = msg.content
+            break
+
+    if not user_message:
+        return {
+            **state,
+            "intent": "unclear",
+            "confidence": 0.0,
+            "error": "No user message found",
+        }
+
+    try:
+        # Get conversation context for better intent classification
+        conversation_context = get_conversation_context(messages)
+
+        # Intent classification prompt with context using the prompts file
+        classification_prompt = INTENT_CLASSIFICATION_PROMPT.format(
+            conversation_context=conversation_context, user_message=user_message
+        )
+
+        # Get classification using the pre-initialized LLM client
+        response = llm_client.generate(classification_prompt, temperature=0.1)
+
+        # print(f"🔍 Raw LLM response: {response}")
+
+        # Parse JSON response
+        try:
+            # Try to extract JSON from response (in case there's extra text)
+            response_clean = response.strip()
+
+            # Look for JSON object in the response
+            json_match = re.search(r"\{.*\}", response_clean, re.DOTALL)
+            if json_match:
+                json_str = json_match.group()
+                result = json.loads(json_str)
+            else:
+                # Try parsing the whole response
+                result = json.loads(response_clean)
+
+            intent = result.get("intent", "unclear")
+            confidence = result.get("confidence", 0.5)
+            explanation = result.get("explanation", "")
+
+            # print(
+            #     f"✅ JSON parsed successfully: intent={intent}, confidence={confidence}"
+            # )
+
+        except (json.JSONDecodeError, AttributeError) as e:
+            print(f"❌ JSON parsing failed: {e}")
+            print(f"   Raw response: {response}")
+
+            # Fallback: try to extract intent from text
+            response_lower = response.lower()
+            if any(
+                word in response_lower for word in ["lỗi", "error", "606", "mã lỗi"]
+            ):
+                intent = "error_help"
+                confidence = 0.7
+            elif any(word in response_lower for word in ["xin chào", "hello", "chào"]):
+                intent = "greeting"
+                confidence = 0.8
+            elif any(word in response_lower for word in ["hủy", "cancel", "thủ tục"]):
+                intent = "procedure_guide"
+                confidence = 0.7
+            elif any(
+                word in response_lower for word in ["nạp", "cước", "dịch vụ", "faq"]
+            ):
+                intent = "faq"
+                confidence = 0.7
+            else:
+                intent = "unclear"
+                confidence = 0.3
+
+            print(f"🔄 Fallback classification: {intent} (confidence: {confidence})")
+            explanation = "Fallback classification due to JSON parse error"
+
+        # print(f"🎯 Intent classified: {intent} (confidence: {confidence})")
+
+        return {
+            **state,
+            "intent": intent,
+            "confidence": confidence,
+            "conversation_context": conversation_context,  # Save context for reuse
+            "processing_info": {
+                "classification_raw": response,
+                "explanation": explanation,
+                "context_used": bool(conversation_context.strip()),
+            },
+        }
+
+    except Exception as e:
+        print(f"❌ Intent classification error: {e}")
+        return {**state, "intent": "unclear", "confidence": 0.0, "error": str(e)}
+
+
+def query_enhancement_node(state: ViettelPayState, llm_client) -> ViettelPayState:
+    """Node for enhancing search query using conversation context"""
+
+    # Get the latest user message
+    messages = state["messages"]
+    if not messages:
+        return {**state, "enhanced_query": "", "error": "No messages found"}
+
+    # Find the last human/user message
+    user_message = None
+    for msg in reversed(messages):
+        if hasattr(msg, "type") and msg.type == "human":
+            user_message = msg.content
+            break
+        elif hasattr(msg, "role") and msg.role == "user":
+            user_message = msg.content
+            break
+
+    if not user_message:
+        return {**state, "enhanced_query": "", "error": "No user message found"}
+
+    try:
+        # Use saved conversation context if available, otherwise get it
+        conversation_context = state.get("conversation_context")
+        if conversation_context is None:
+            conversation_context = get_conversation_context(messages)
+
+        # If no context, use original message
+        if not conversation_context.strip():
+            print(f"🔍 No context available, using original query: {user_message}")
+            return {**state, "enhanced_query": user_message}
+
+        # Query enhancement prompt using the prompts file
+        enhancement_prompt = QUERY_ENHANCEMENT_PROMPT.format(
+            conversation_context=conversation_context, user_message=user_message
+        )
+
+        # Get enhanced query
+        enhanced_query = llm_client.generate(enhancement_prompt, temperature=0.1)
+        enhanced_query = enhanced_query.strip()
+
+        print(f"🔍 Original query: {user_message}")
+        print(f"🚀 Enhanced query: {enhanced_query}")
+
+        return {**state, "enhanced_query": enhanced_query}
+
+    except Exception as e:
+        print(f"❌ Query enhancement error: {e}")
+        # Fallback to original message
+        return {**state, "enhanced_query": user_message, "error": str(e)}
+
+
+def knowledge_retrieval_node(
+    state: ViettelPayState, knowledge_retriever
+) -> ViettelPayState:
+    """Node for knowledge retrieval using pre-initialized ViettelKnowledgeBase"""
+
+    # Use enhanced query if available, otherwise fall back to extracting from messages
+    enhanced_query = state.get("enhanced_query", "")
+
+    if not enhanced_query:
+        # Fallback: extract from messages
+        messages = state["messages"]
+        if not messages:
+            return {**state, "retrieved_docs": [], "error": "No messages found"}
+
+        # Find the last human/user message
+        for msg in reversed(messages):
+            if hasattr(msg, "type") and msg.type == "human":
+                enhanced_query = msg.content
+                break
+            elif hasattr(msg, "role") and msg.role == "user":
+                enhanced_query = msg.content
+                break
+
+    if not enhanced_query:
+        return {**state, "retrieved_docs": [], "error": "No query available"}
+
+    try:
+        if not knowledge_retriever:
+            raise ValueError("Knowledge retriever not available")
+
+        # Retrieve relevant documents using enhanced query and pre-initialized ViettelKnowledgeBase
+        retrieved_docs = knowledge_retriever.search(enhanced_query, top_k=10)
+
+        print(
+            f"📚 Retrieved {len(retrieved_docs)} documents for enhanced query: {enhanced_query}"
+        )
+
+        return {**state, "retrieved_docs": retrieved_docs}
+
+    except Exception as e:
+        print(f"❌ Knowledge retrieval error: {e}")
+        return {**state, "retrieved_docs": [], "error": str(e)}
+
+
+def script_response_node(state: ViettelPayState) -> ViettelPayState:
+    """Node for script-based responses"""
+
+    from src.agent.scripts import ConversationScripts
+    from langchain_core.messages import AIMessage
+
+    intent = state.get("intent", "")
+
+    try:
+        # Load scripts
+        scripts = ConversationScripts("./viettelpay_docs/processed/kich_ban.csv")
+
+        # Map intents to script types
+        intent_to_script = {
+            "greeting": "greeting",
+            "out_of_scope": "out_of_scope",
+            "human_request": "human_request_attempt_1",  # Could be enhanced later
+            "unclear": "ask_for_clarity",
+        }
+
+        script_type = intent_to_script.get(intent)
+
+        if script_type and scripts.has_script(script_type):
+            response_text = scripts.get_script(script_type)
+            print(f"📋 Using script response: {script_type}")
+
+            # Add AI message to the conversation
+            ai_message = AIMessage(content=response_text)
+
+            return {**state, "messages": [ai_message], "response_type": "script"}
+
+        else:
+            # Fallback script
+            fallback_response = (
+                "Xin lỗi, em chưa hiểu rõ yêu cầu của anh/chị. Vui lòng thử lại."
+            )
+            ai_message = AIMessage(content=fallback_response)
+
+            print(f"📋 Using fallback script for intent: {intent}")
+
+            return {**state, "messages": [ai_message], "response_type": "script"}
+
+    except Exception as e:
+        print(f"❌ Script response error: {e}")
+        fallback_response = "Xin lỗi, em gặp lỗi kỹ thuật. Vui lòng thử lại sau."
+        ai_message = AIMessage(content=fallback_response)
+
+        return {
+            **state,
+            "messages": [ai_message],
+            "response_type": "error",
+            "error": str(e),
+        }
+
+
+def generate_response_node(state: ViettelPayState, llm_client) -> ViettelPayState:
+    """Node for LLM-based response generation with conversation context"""
+
+    from langchain_core.messages import AIMessage
+
+    # Get the latest user message and conversation history
+    messages = state["messages"]
+    if not messages:
+        ai_message = AIMessage(content="Xin lỗi, em không thể xử lý yêu cầu này.")
+        return {**state, "messages": [ai_message], "response_type": "error"}
+
+    # Find the last human/user message
+    user_message = None
+    for msg in reversed(messages):
+        if hasattr(msg, "type") and msg.type == "human":
+            user_message = msg.content
+            break
+        elif hasattr(msg, "role") and msg.role == "user":
+            user_message = msg.content
+            break
+
+    if not user_message:
+        ai_message = AIMessage(content="Xin lỗi, em không thể xử lý yêu cầu này.")
+        return {**state, "messages": [ai_message], "response_type": "error"}
+
+    intent = state.get("intent", "")
+    retrieved_docs = state.get("retrieved_docs", [])
+    enhanced_query = state.get("enhanced_query", "")
+
+    try:
+        # Build context from retrieved documents using original content
+        context = ""
+        if retrieved_docs:
+            context = "\n\n".join(
+                [
+                    f"[{doc.metadata.get('doc_type', 'unknown')}] {doc.metadata.get('original_content', doc.page_content)}"
+                    for doc in retrieved_docs
+                ]
+            )
+
+        # Use saved conversation context if available, otherwise get it
+        conversation_context = state.get("conversation_context")
+        if conversation_context is None:
+            conversation_context = get_conversation_context(messages, max_messages=6)
+
+        # Get system prompt based on intent using the prompts file
+        system_prompt = get_system_prompt_by_intent(intent)
+
+        # Build full prompt with both knowledge context and conversation context using the prompts file
+        generation_prompt = RESPONSE_GENERATION_PROMPT.format(
+            system_prompt=system_prompt,
+            context=context,
+            conversation_context=conversation_context,
+            user_message=user_message,
+            enhanced_query=enhanced_query,
+        )
+
+        # Generate response using the pre-initialized LLM client
+        response_text = llm_client.generate(generation_prompt, temperature=0.1)
+
+        print(f"🤖 Generated response for intent: {intent}")
+
+        # Add AI message to the conversation
+        ai_message = AIMessage(content=response_text)
+
+        return {**state, "messages": [ai_message], "response_type": "generated"}
+
+    except Exception as e:
+        print(f"❌ Response generation error: {e}")
+        error_response = "Xin lỗi, em gặp lỗi khi xử lý yêu cầu. Vui lòng thử lại sau."
+        ai_message = AIMessage(content=error_response)
+
+        return {
+            **state,
+            "messages": [ai_message],
+            "response_type": "error",
+            "error": str(e),
+        }
+
+
+# Routing function for conditional edges
+def route_after_intent_classification(state: ViettelPayState) -> str:
+    """Route to appropriate node after intent classification"""
+
+    intent = state.get("intent", "unclear")
+
+    # Script-based intents (no knowledge retrieval needed)
+    script_intents = {"greeting", "out_of_scope", "human_request", "unclear"}
+
+    if intent in script_intents:
+        return "script_response"
+    else:
+        # Knowledge-based intents need query enhancement first
+        return "query_enhancement"
+
+
+def route_after_query_enhancement(state: ViettelPayState) -> str:
+    """Route after query enhancement (always to knowledge retrieval)"""
+    return "knowledge_retrieval"
+
+
+def route_after_knowledge_retrieval(state: ViettelPayState) -> str:
+    """Route after knowledge retrieval (always to generation)"""
+    return "generate_response"

src/agent/prompts.py

@@ -0,0 +1,125 @@
+"""
+Prompt templates for ViettelPay AI Agent
+All prompts using Vietnamese language for ViettelPay Pro customer support
+"""
+
+# Intent Classification Prompt (JSON format for better parsing)
+INTENT_CLASSIFICATION_PROMPT = """
+Bạn là hệ thống phân loại ý định cho ViettelPay Pro. ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+Phân tích tin nhắn của người dùng và trả về ý định chính.
+
+Các loại ý định:
+* **`greeting`**: Chỉ là lời chào hỏi thuần túy, không có câu hỏi hoặc yêu cầu cụ thể nào khác. Nếu tin nhắn có cả lời chào VÀ câu hỏi thì phân loại theo các ý định khác, không phải greeting.
+    * *Ví dụ:* "chào em", "hello shop", "xin chào ạ"
+    * *Không phải greeting:* "xin chào, cho hỏi về lỗi 606" → đây là error_help
+* **`faq`**: Các câu hỏi đáp chung, tìm hiểu về dịch vụ, tính năng, v.v.
+    * *Ví dụ:* "App có bán thẻ game không?", "ViettelPay Pro nạp tiền được cho mạng nao?"
+* **`error_help`**: Báo cáo sự cố, hỏi về mã lỗi cụ thể.
+    * *Ví dụ:* "Giao dịch báo lỗi 606", "tại sao tôi không thanh toán được?", "lỗi này là gì?"
+* **`procedure_guide`**: Hỏi về các bước cụ thể để thực hiện một tác vụ.
+    * *Ví dụ:* "làm thế nào để hủy giao dịch?", "chỉ tôi cách lấy lại mã thẻ cào", "hướng dẫn nạp cước"
+* **`human_request`**: Yêu cầu được nói chuyện trực tiếp với nhân viên hỗ trợ.
+    * *Ví dụ:* "cho tôi gặp người thật", "nối máy cho tổng đài", "em k hiểu, cho gặp ai đó"
+* **`out_of_scope`**: Câu hỏi ngoài phạm vi ViettelPay (thời tiết, chính trị, v.v.), không liên quan gì đến các dịch vụ tài chính, viễn thông của Viettel.
+    * *Ví dụ:* "dự báo thời tiết hôm nay?", "giá xăng bao nhiêu?", "cách nấu phở"
+* **`unclear`**: Câu hỏi không rõ ràng, thiếu thông tin cụ thể, cần người dùng bổ sung thêm chi tiết để có thể hỗ trợ hiệu quả.
+    * *Ví dụ:* "lỗi", "giúp với", "gd", "???", "ko hiểu", "bị lỗi giờ sao đây", "không thực hiện được", "sao vậy", "tại sao thế"
+
+**Bối cảnh cuộc trò chuyện:**
+<conversation_context>
+{conversation_context}
+</conversation_context>
+
+**Tin nhắn mới của người dùng:**
+<user_message>
+{user_message}
+</user_message>
+
+Hãy phân tích dựa trên cả ngữ cảnh cuộc hội thoại và tin nhắn mới nhất của người dùng.
+
+QUAN TRỌNG: Chỉ trả về JSON thuần túy, không có text khác. Format chính xác:
+{{"intent": "tên_ý_định", "confidence": 0.9, "explanation": "lý do ngắn gọn"}}
+"""
+
+# Query Enhancement Prompt for contextual search improvement
+QUERY_ENHANCEMENT_PROMPT = """
+**Nhiệm vụ:** Bạn là một trợ lý chuyên gia của ViettelPay Pro. 
+ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+Nhiệm vụ của bạn là đọc cuộc trò chuyện và tin nhắn mới nhất của người dùng để tạo ra một truy vấn tìm kiếm (search query) duy nhất, tối ưu cho cơ sở dữ liệu nội bộ.
+
+**Bối cảnh cuộc trò chuyện:**
+<conversation_context>
+{conversation_context}
+</conversation_context>
+
+**Tin nhắn mới của người dùng:**
+<user_message>
+{user_message}
+</user_message
+
+**Quy tắc tạo truy vấn:**
+1.  **Kết hợp Ngữ cảnh:** Phân tích toàn bộ cuộc trò chuyện để tạo ra một truy vấn đầy đủ ý nghĩa, nắm bắt được mục tiêu thực sự của người dùng.
+2.  **Làm rõ & Cụ thể:** Thay thế các đại từ (ví dụ: "nó", "cái đó") bằng các chủ thể hoặc thuật ngữ cụ thể đã được đề cập (ví dụ: "liên kết ngân hàng", "rút tiền tại ATM", "mã lỗi 101").
+3.  **Tích hợp Thuật ngữ:** Tích hợp một cách **tự nhiên** các từ khóa và thuật ngữ chuyên ngành của ViettelPay Pro (ví dụ: "giao dịch", "nạp cước", "chiết khấu", "OTP", "hoa hồng").
+4.  **Duy trì Tính tự nhiên (QUAN TRỌNG):** Truy vấn phải là một câu hỏi hoặc một cụm từ hoàn chỉnh, tự nhiên bằng tiếng Việt. **Tránh tạo ra danh sách từ khóa rời rạc.**
+    * **Tốt:** "cách tính hoa hồng khi nạp thẻ điện thoại cho khách"
+    * **Không tốt:** "hoa hồng nạp thẻ điện thoại"
+5.  **Giữ lại Ý định Gốc:** Truy vấn phải phản ánh chính xác câu hỏi của người dùng, không thêm thông tin hoặc suy diễn.
+6. Thêm vài câu sử dụng từ đồng nghĩa và cách diễn đạt khác nhau trong tiếng Việt để tăng khả năng tìm kiếm
+
+**ĐẦU RA:** CHỈ trả về một chuỗi truy vấn tìm kiếm đã được cải thiện. Không thêm lời giải thích.
+"""
+
+# System Prompt for Error Help responses
+ERROR_HELP_SYSTEM_PROMPT = """Bạn là chuyên gia hỗ trợ kỹ thuật ViettelPay Pro. ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+Thể hiện sự cảm thông với khó khăn của người dùng.
+Cung cấp giải pháp cụ thể, từng bước.
+Nếu cần hỗ trợ thêm, hướng dẫn liên hệ tổng đài.
+Nếu có lịch sử cuộc hội thoại, hãy tham khảo để đưa ra câu trả lời phù hợp và có tính liên kết."""
+
+# System Prompt for Procedure Guide responses
+PROCEDURE_GUIDE_SYSTEM_PROMPT = """Bạn là hướng dẫn viên ViettelPay Pro. ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+Cung cấp hướng dẫn từng bước rõ ràng.
+Bao gồm link video nếu có trong thông tin.
+Sử dụng format có số thứ tự cho các bước.
+Nếu có lịch sử cuộc hội thoại, hãy tham khảo để đưa ra câu trả lời phù hợp và có tính liên kết."""
+
+# Default System Prompt for general responses
+DEFAULT_SYSTEM_PROMPT = """Bạn là trợ lý ảo ViettelPay Pro. ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+Trả lời câu hỏi dựa trên thông tin được cung cấp.
+Giọng điệu thân thiện, chuyên nghiệp.
+Sử dụng "Anh/chị" khi xưng hô.
+Nếu có lịch sử cuộc hội thoại, hãy tham khảo để đưa ra câu trả lời phù hợp và có tính liên kết."""
+
+# Response Generation Template with context and knowledge base integration
+RESPONSE_GENERATION_PROMPT = """<system_prompt>
+{system_prompt}
+</system_prompt>
+
+**Thông tin tham khảo từ cơ sở tri thức:**
+<knowledge_base_context>
+{context}
+</knowledge_base_context>
+
+**Bối cảnh cuộc trò chuyện:**
+<conversation_context>
+{conversation_context}
+</conversation_context>
+
+**Tin nhắn mới của người dùng:**
+<user_message>
+{user_message}
+</user_message>
+
+Hãy trả lời câu hỏi dựa trên thông tin tham khảo và lịch sử cuộc hội thoại (nếu có). Nếu không có thông tin phù hợp, hãy nói rằng bạn cần thêm thông tin.
+"""
+
+
+def get_system_prompt_by_intent(intent: str) -> str:
+    """Get appropriate system prompt based on intent classification"""
+    if intent == "error_help":
+        return ERROR_HELP_SYSTEM_PROMPT
+    elif intent == "procedure_guide":
+        return PROCEDURE_GUIDE_SYSTEM_PROMPT
+    else:  # faq, etc.
+        return DEFAULT_SYSTEM_PROMPT

src/agent/scripts.py

@@ -0,0 +1,157 @@
+"""
+Conversation Scripts Handler
+Manages predefined scripts for standard conversation scenarios
+"""
+
+import os
+import pandas as pd
+from typing import Dict, Optional
+
+
+class ConversationScripts:
+    """Handler for conversation scripts and standard responses"""
+
+    def __init__(self, scripts_file: Optional[str] = None):
+        self.scripts = {}
+        self.scripts_file = scripts_file
+
+        # Default built-in scripts (fallback)
+        self._load_default_scripts()
+
+        # Load from file if provided
+        if scripts_file and os.path.exists(scripts_file):
+            self._load_scripts_from_file(scripts_file)
+            print(f"✅ Loaded conversation scripts from {scripts_file}")
+        else:
+            print("⚠️ Using default built-in scripts")
+
+    def _load_default_scripts(self):
+        """Load default conversation scripts"""
+        self.scripts = {
+            "greeting": """Xin chào! Em là Trợ lý ảo Viettelpay Pro sẵn sàng hỗ trợ Anh/chị!
+Hiện tại, Trợ lý ảo đang trong giai đoạn thử nghiệm hỗ trợ nghiệp vụ cước viễn thông, thẻ cào và thẻ game với các nội dung sau:
+ - Hướng dẫn sử dụng
+ - Chính sách phí bán hàng
+ - Tìm hiểu quy định hủy giao dịch
+ - Hướng dẫn xử lý một số lỗi thường gặp.
+
+Anh/Chị vui lòng bấm vào từng chủ đề để xem chi tiết.
+Nếu thông tin chưa đáp ứng nhu cầu, Anh/Chị hãy đặt lại câu hỏi để em tiếp tục hỗ trợ ạ!""",
+            "out_of_scope": """Cảm ơn Anh/chị đã đặt câu hỏi!
+Trợ lý ảo Viettelpay Pro đang thử nghiệm và cập nhật kiến thức nghiệp vụ để hỗ trợ Anh/chị tốt hơn. Vì vậy, rất tiếc nhu cầu hiện tại của Anh/chị nằm ngoài khả năng hỗ trợ của Trợ lý ảo.
+
+Để được hỗ trợ chính xác và đầy đủ hơn, Anh/chị vui lòng gửi yêu cầu hỗ trợ tại đây""",
+            "human_request_attempt_1": """Anh/Chị vui lòng chia sẻ thêm nội dung cần hỗ trợ, Em rất mong được giải đáp trực tiếp để tiết kiệm thời gian của Anh/Chị ạ!""",
+            "human_request_attempt_2": """Rất tiếc! Hiện tại hệ thống chưa có Tư vấn viên hỗ trợ trực tuyến.
+Tuy nhiên, Anh/chị vẫn có thể yêu cầu hỗ trợ được trợ giúp qua các hình thức sau: 
+📌 1. Đặt câu hỏi ngay tại đây, Trợ lý ảo ViettelPay Pro luôn sẵn sàng hỗ trợ Anh/chị trong phạm vi nghiệp vụ thử nghiệm (nghiệp vụ cước viễn thông, thẻ cào, thẻ game):
+✅ Hướng dẫn sử dụng
+✅ Chính sách phí bán hàng
+✅ Tìm hiểu về quy định hủy giao dịch
+✅ Hướng dẫn xử lý một số lỗi thường gặp.
+📌 2. Tìm hiểu thông tin nghiệp vụ tại mục:
+📚 Hướng dẫn, hỗ trợ: Các video hướng dẫn nghiệp vụ
+💡Thông báo: Các tin tức nghiệp vụ và tin nâng cấp hệ thống/tin sự cố.
+📌 3. Gửi yêu cầu hỗ trợ tại đây
+ Hoặc gọi Tổng đài 1789 nhánh 5 trong trường hợp khẩn cấp""",
+            "confirmation_check": """Anh/Chị có thắc mắc thêm vấn đề nào liên quan đến nội dung em vừa cung cấp không ạ?""",
+            "closing": """Hy vọng những thông tin vừa rồi đã đáp ứng nhu cầu của Anh/chị.
+Nếu cần hỗ trợ thêm, Anh/Chị hãy đặt câu hỏi để em tiếp tục hỗ trợ ạ!
+🌟 Chúc Anh/chị một ngày thật vui và thành công!""",
+            "ask_for_clarity": """Em chưa hiểu rõ yêu cầu của Anh/chị. Anh/chị có thể chia sẻ cụ thể hơn được không ạ?""",
+            "empathy_error": """Em hiểu Anh/chị đang gặp khó khăn với lỗi này. Để hỗ trợ Anh/chị tốt nhất, em sẽ tìm hiểu và đưa ra hướng giải quyết cụ thể.""",
+        }
+
+    def _load_scripts_from_file(self, file_path: str):
+        """Load scripts from CSV file (kich_ban.csv format)"""
+        try:
+            df = pd.read_csv(file_path)
+
+            # Map CSV scenarios to script keys
+            scenario_mapping = {
+                "Chào hỏi": "greeting",
+                "Trao đổi thông tin chính": "out_of_scope",  # First occurrence
+                "Trước khi kết thúc phiên": "confirmation_check",
+                "Kết thúc": "closing",
+            }
+
+            for _, row in df.iterrows():
+                scenario_type = row.get("Loại kịch bản", "")
+                situation = row.get("Tình huống", "")
+                script = row.get("Kịch bản chốt", "")
+
+                # Handle specific mappings
+                if scenario_type == "Chào hỏi":
+                    self.scripts["greeting"] = script
+                elif scenario_type == "Trao đổi thông tin chính":
+                    if "ngoài nghiệp vụ" in situation:
+                        self.scripts["out_of_scope"] = script
+                    elif "gặp tư vấn viên" in situation:
+                        if "Lần 1" in script:
+                            self.scripts["human_request_attempt_1"] = (
+                                script.split("Lần 1:")[1].split("Lần 2:")[0].strip()
+                            )
+                        if "Lần 2" in script:
+                            self.scripts["human_request_attempt_2"] = script.split(
+                                "Lần 2:"
+                            )[1].strip()
+                    elif "không đủ ý" in situation:
+                        self.scripts["ask_for_clarity"] = (
+                            "Em chưa hiểu rõ yêu cầu của Anh/chị. Anh/chị có thể chia sẻ cụ thể hơn được không ạ?"
+                        )
+                    elif "lỗi" in situation:
+                        self.scripts["empathy_error"] = (
+                            "Em hiểu Anh/chị đang gặp khó khăn với lỗi này."
+                        )
+                elif scenario_type == "Trước khi kết thúc phiên":
+                    self.scripts["confirmation_check"] = script
+                elif scenario_type == "Kết thúc":
+                    self.scripts["closing"] = script
+
+        except Exception as e:
+            print(f"⚠️ Error loading scripts from file: {e}")
+            print("Using default scripts instead")
+
+    def get_script(self, script_type: str) -> Optional[str]:
+        """Get script by type"""
+        return self.scripts.get(script_type)
+
+    def has_script(self, script_type: str) -> bool:
+        """Check if script exists"""
+        return script_type in self.scripts
+
+    def get_all_script_types(self) -> list:
+        """Get all available script types"""
+        return list(self.scripts.keys())
+
+    def add_script(self, script_type: str, script_content: str):
+        """Add or update a script"""
+        self.scripts[script_type] = script_content
+
+    def get_stats(self) -> dict:
+        """Get statistics about loaded scripts"""
+        return {
+            "total_scripts": len(self.scripts),
+            "script_types": list(self.scripts.keys()),
+            "source": "file" if self.scripts_file else "default",
+        }
+
+
+# Usage example
+if __name__ == "__main__":
+    # Test with default scripts
+    scripts = ConversationScripts()
+    print("📊 Scripts Stats:", scripts.get_stats())
+
+    # Test specific scripts
+    greeting = scripts.get_script("greeting")
+    print(f"\n👋 Greeting Script:\n{greeting}")
+
+    # Test loading from file (if available)
+    try:
+        scripts_with_file = ConversationScripts(
+            "./viettelpay_docs/processed/kich_ban.csv"
+        )
+        print(f"\n📊 File-based Scripts Stats: {scripts_with_file.get_stats()}")
+    except Exception as e:
+        print(f"File loading test failed: {e}")

src/agent/viettelpay_agent.py

@@ -0,0 +1,416 @@
+"""
+ViettelPay AI Agent using LangGraph
+Multi-turn conversation support with short-term memory using InMemorySaver
+"""
+
+import os
+from typing import Dict, Optional
+from functools import partial
+from langgraph.graph import StateGraph, END
+from langgraph.checkpoint.memory import InMemorySaver
+from langchain_core.messages import HumanMessage
+
+from src.agent.nodes import (
+    ViettelPayState,
+    classify_intent_node,
+    query_enhancement_node,
+    knowledge_retrieval_node,
+    script_response_node,
+    generate_response_node,
+    route_after_intent_classification,
+    route_after_query_enhancement,
+    route_after_knowledge_retrieval,
+)
+
+# Import configuration utility
+from src.utils.config import get_knowledge_base_path, get_llm_provider
+
+
+class ViettelPayAgent:
+    """Main ViettelPay AI Agent using LangGraph workflow with multi-turn conversation support"""
+
+    def __init__(
+        self,
+        knowledge_base_path: str = None,
+        scripts_file: Optional[str] = None,
+        llm_provider: str = None,
+    ):
+        knowledge_base_path = knowledge_base_path or get_knowledge_base_path()
+        scripts_file = scripts_file or "./viettelpay_docs/processed/kich_ban.csv"
+        llm_provider = llm_provider or get_llm_provider()
+
+        self.knowledge_base_path = knowledge_base_path
+        self.scripts_file = scripts_file
+        self.llm_provider = llm_provider
+
+        # Initialize LLM client once during agent creation
+        print(f"🧠 Initializing LLM client ({self.llm_provider})...")
+        from src.llm.llm_client import LLMClientFactory
+
+        self.llm_client = LLMClientFactory.create_client(self.llm_provider)
+        print(f"✅ LLM client initialized and ready")
+
+        # Initialize knowledge retriever once during agent creation
+        print(f"📚 Initializing knowledge retriever...")
+        try:
+            from src.knowledge_base.viettel_knowledge_base import ViettelKnowledgeBase
+
+            self.knowledge_base = ViettelKnowledgeBase()
+            ensemble_retriever = self.knowledge_base.load_knowledge_base(
+                knowledge_base_path
+            )
+            if not ensemble_retriever:
+                raise ValueError(
+                    f"Knowledge base not found at {knowledge_base_path}. Run build_database_script.py first."
+                )
+            print(f"✅ Knowledge retriever initialized and ready")
+        except Exception as e:
+            print(f"⚠️ Knowledge retriever initialization failed: {e}")
+            self.knowledge_base = None
+
+        # Initialize checkpointer for short-term memory
+        self.checkpointer = InMemorySaver()
+
+        # Build workflow with pre-initialized components
+        self.workflow = self._build_workflow()
+        self.app = self.workflow.compile(checkpointer=self.checkpointer)
+
+        print("✅ ViettelPay Agent initialized with multi-turn conversation support")
+
+    def _build_workflow(self) -> StateGraph:
+        """Build LangGraph workflow with pre-initialized components"""
+
+        # Create workflow graph
+        workflow = StateGraph(ViettelPayState)
+
+        # Create node functions with pre-bound components using functools.partial
+        # This eliminates the need to initialize components in each node call
+        classify_intent_with_llm = partial(
+            classify_intent_node, llm_client=self.llm_client
+        )
+        query_enhancement_with_llm = partial(
+            query_enhancement_node, llm_client=self.llm_client
+        )
+        knowledge_retrieval_with_retriever = partial(
+            knowledge_retrieval_node, knowledge_retriever=self.knowledge_base
+        )
+        generate_response_with_llm = partial(
+            generate_response_node, llm_client=self.llm_client
+        )
+
+        # Add nodes (some with pre-bound components, some without)
+        workflow.add_node("classify_intent", classify_intent_with_llm)
+        workflow.add_node("query_enhancement", query_enhancement_with_llm)
+        workflow.add_node("knowledge_retrieval", knowledge_retrieval_with_retriever)
+        workflow.add_node(
+            "script_response", script_response_node
+        )  # No pre-bound components needed
+        workflow.add_node("generate_response", generate_response_with_llm)
+
+        # Set entry point
+        workflow.set_entry_point("classify_intent")
+
+        # Add conditional routing after intent classification
+        workflow.add_conditional_edges(
+            "classify_intent",
+            route_after_intent_classification,
+            {
+                "script_response": "script_response",
+                "query_enhancement": "query_enhancement",
+            },
+        )
+
+        # Script responses go directly to end
+        workflow.add_edge("script_response", END)
+
+        # Query enhancement goes to knowledge retrieval
+        workflow.add_edge("query_enhancement", "knowledge_retrieval")
+
+        # Knowledge retrieval goes to response generation
+        workflow.add_edge("knowledge_retrieval", "generate_response")
+        workflow.add_edge("generate_response", END)
+
+        print("🔄 LangGraph workflow built successfully with optimized component usage")
+        return workflow
+
+    def process_message(self, user_message: str, thread_id: str = "default") -> Dict:
+        """Process a user message in a multi-turn conversation"""
+
+        print(f"\n💬 Processing message: '{user_message}' (thread: {thread_id})")
+        print("=" * 50)
+
+        # Create configuration with thread_id for conversation memory
+        config = {"configurable": {"thread_id": thread_id}}
+
+        try:
+            # Create human message
+            human_message = HumanMessage(content=user_message)
+
+            # Initialize state with the new message
+            # Note: conversation_context is set to None so it gets recomputed with fresh message history
+            initial_state = {
+                "messages": [human_message],
+                "intent": None,
+                "confidence": None,
+                "enhanced_query": None,
+                "retrieved_docs": None,
+                "conversation_context": None,  # Reset to ensure fresh context computation
+                "response_type": None,
+                "error": None,
+                "processing_info": None,
+            }
+
+            # Run workflow with memory
+            result = self.app.invoke(initial_state, config)
+
+            # Extract response from the last AI message
+            messages = result.get("messages", [])
+            if messages:
+                # Get the last AI message
+                last_message = messages[-1]
+                if hasattr(last_message, "content"):
+                    response = last_message.content
+                else:
+                    response = str(last_message)
+            else:
+                response = "Xin lỗi, em không thể xử lý yêu cầu này."
+
+            response_type = result.get("response_type", "unknown")
+            intent = result.get("intent", "unknown")
+            confidence = result.get("confidence", 0.0)
+            enhanced_query = result.get("enhanced_query", "")
+            error = result.get("error")
+
+            # Build response info
+            response_info = {
+                "response": response,
+                "intent": intent,
+                "confidence": confidence,
+                "response_type": response_type,
+                "enhanced_query": enhanced_query,
+                "success": error is None,
+                "error": error,
+                "thread_id": thread_id,
+                "message_count": len(messages),
+            }
+
+            print(f"✅ Response generated successfully")
+            print(f"   Intent: {intent} (confidence: {confidence})")
+            print(f"   Type: {response_type}")
+            if enhanced_query and enhanced_query != user_message:
+                print(f"   Enhanced query: {enhanced_query}")
+            print(f"   Thread: {thread_id}")
+
+            return response_info
+
+        except Exception as e:
+            print(f"❌ Workflow error: {e}")
+
+            return {
+                "response": "Xin lỗi, em gặp lỗi kỹ thuật. Vui lòng thử lại sau.",
+                "intent": "error",
+                "confidence": 0.0,
+                "response_type": "error",
+                "enhanced_query": "",
+                "success": False,
+                "error": str(e),
+                "thread_id": thread_id,
+                "message_count": 0,
+            }
+
+    def chat(self, user_message: str, thread_id: str = "default") -> str:
+        """Simple chat interface - returns just the response text"""
+        result = self.process_message(user_message, thread_id)
+        return result["response"]
+
+    def get_conversation_history(self, thread_id: str = "default") -> list:
+        """Get conversation history for a specific thread"""
+        try:
+            config = {"configurable": {"thread_id": thread_id}}
+
+            # Get the current state to access message history
+            current_state = self.app.get_state(config)
+
+            if current_state and current_state.values.get("messages"):
+                messages = current_state.values["messages"]
+                history = []
+
+                for msg in messages:
+                    if hasattr(msg, "type") and hasattr(msg, "content"):
+                        role = "user" if msg.type == "human" else "assistant"
+                        history.append({"role": role, "content": msg.content})
+                    elif hasattr(msg, "role") and hasattr(msg, "content"):
+                        history.append({"role": msg.role, "content": msg.content})
+
+                return history
+            else:
+                return []
+
+        except Exception as e:
+            print(f"❌ Error getting conversation history: {e}")
+            return []
+
+    def clear_conversation(self, thread_id: str = "default") -> bool:
+        """Clear conversation history for a specific thread"""
+        try:
+            # Note: InMemorySaver doesn't have a direct clear method
+            # The conversation will be cleared when the app is restarted
+            # For persistent memory, you'd need to implement a clear method
+            print(f"📝 Conversation clearing requested for thread: {thread_id}")
+            print("   Note: InMemorySaver conversations clear on app restart")
+            return True
+        except Exception as e:
+            print(f"❌ Error clearing conversation: {e}")
+            return False
+
+    def get_workflow_info(self) -> Dict:
+        """Get information about the workflow structure"""
+        return {
+            "nodes": [
+                "classify_intent",
+                "query_enhancement",
+                "knowledge_retrieval",
+                "script_response",
+                "generate_response",
+            ],
+            "entry_point": "classify_intent",
+            "knowledge_base_path": self.knowledge_base_path,
+            "scripts_file": self.scripts_file,
+            "llm_provider": self.llm_provider,
+            "memory_type": "InMemorySaver",
+            "multi_turn": True,
+            "query_enhancement": True,
+            "optimizations": {
+                "llm_client": "Single initialization with functools.partial",
+                "knowledge_retriever": "Single initialization with functools.partial",
+                "conversation_context": "Cached in state to avoid repeated computation",
+            },
+        }
+
+    def health_check(self) -> Dict:
+        """Check if all components are working"""
+
+        health_status = {
+            "agent": True,
+            "workflow": True,
+            "memory": True,
+            "llm": False,
+            "knowledge_base": False,
+            "scripts": False,
+            "overall": False,
+        }
+
+        try:
+            # Test LLM client (already initialized)
+            test_response = self.llm_client.generate("Hello", temperature=0.1)
+            health_status["llm"] = bool(test_response)
+            print("✅ LLM client working")
+
+        except Exception as e:
+            print(f"⚠️ LLM health check failed: {e}")
+            health_status["llm"] = False
+
+        try:
+            # Test memory/checkpointer
+            test_config = {"configurable": {"thread_id": "health_check"}}
+            test_state = {"messages": [HumanMessage(content="test")]}
+
+            # Try to invoke with memory
+            self.app.invoke(test_state, test_config)
+            health_status["memory"] = True
+            print("✅ Memory/checkpointer working")
+
+        except Exception as e:
+            print(f"⚠️ Memory health check failed: {e}")
+            health_status["memory"] = False
+
+        try:
+            # Test knowledge base (using pre-initialized retriever)
+            if self.knowledge_base:
+                # Test a simple search to verify it's working
+                test_docs = self.knowledge_base.search("test", top_k=1)
+                health_status["knowledge_base"] = True
+                print("✅ Knowledge retriever working")
+            else:
+                health_status["knowledge_base"] = False
+                print("❌ Knowledge retriever not initialized")
+
+        except Exception as e:
+            print(f"⚠️ Knowledge base health check failed: {e}")
+            health_status["knowledge_base"] = False
+
+        try:
+            # Test scripts
+            from src.agent.scripts import ConversationScripts
+
+            scripts = ConversationScripts(self.scripts_file)
+            health_status["scripts"] = len(scripts.get_all_script_types()) > 0
+
+        except Exception as e:
+            print(f"⚠️ Scripts health check failed: {e}")
+
+        # Overall health
+        health_status["overall"] = all(
+            [
+                health_status["agent"],
+                health_status["memory"],
+                health_status["llm"],
+                health_status["knowledge_base"],
+                health_status["scripts"],
+            ]
+        )
+
+        return health_status
+
+
+# Usage example and testing
+if __name__ == "__main__":
+    # Initialize agent
+    agent = ViettelPayAgent()
+
+    # Health check
+    print("\n🏥 Health Check:")
+    health = agent.health_check()
+    for component, status in health.items():
+        status_icon = "✅" if status else "❌"
+        print(f"   {component}: {status_icon}")
+
+    if not health["overall"]:
+        print("\n⚠️ Some components are not healthy. Check requirements and data files.")
+        exit(1)
+
+    print(f"\n🤖 Agent ready! Workflow info: {agent.get_workflow_info()}")
+
+    # Test multi-turn conversation with query enhancement
+    test_thread = "test_conversation"
+
+    print(
+        f"\n🧪 Testing multi-turn conversation with query enhancement (thread: {test_thread}):"
+    )
+
+    test_messages = [
+        "Xin chào!",
+        "Mã lỗi 606 là gì?",
+        "Làm sao khắc phục?",  # This should be enhanced to "làm sao khắc phục lỗi 606"
+        "Còn lỗi nào khác tương tự không?",  # This should be enhanced with error context
+        "Cảm ơn bạn!",
+    ]
+
+    for i, message in enumerate(test_messages, 1):
+        print(f"\n--- Turn {i} ---")
+        result = agent.process_message(message, test_thread)
+        print(f"User: {message}")
+        print(f"Bot: {result['response'][:150]}...")
+
+        if result.get("enhanced_query") and result["enhanced_query"] != message:
+            print(f"🚀 Query enhanced: {result['enhanced_query']}")
+
+        # Show conversation history
+        if i > 1:
+            history = agent.get_conversation_history(test_thread)
+            print(f"History length: {len(history)} messages")
+
+    print(f"\n📜 Final conversation history:")
+    history = agent.get_conversation_history(test_thread)
+    for i, msg in enumerate(history, 1):
+        print(f"  {i}. {msg['role']}: {msg['content'][:100]}...")

src/evaluation/intent_classification.py

@@ -0,0 +1,901 @@
+"""
+Simplified Intent Classification Evaluation for ViettelPay AI Agent
+Removed pattern-based generation, improved chunk mixing, and configurable conversations per chunk
+"""
+
+import json
+import os
+import sys
+import argparse
+import time
+import random
+from typing import Dict, List, Optional
+from pathlib import Path
+from collections import defaultdict, Counter
+import pandas as pd
+from tqdm import tqdm
+import re
+import numpy as np
+
+# Load environment variables from .env file
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Add the project root to Python path so we can import from src
+project_root = Path(__file__).parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+# Import existing components
+from src.evaluation.prompts import INTENT_CLASSIFICATION_CONVERSATION_GENERATION_PROMPT
+from src.knowledge_base.viettel_knowledge_base import ViettelKnowledgeBase
+from src.llm.llm_client import LLMClientFactory
+from src.agent.nodes import classify_intent_node, ViettelPayState
+from langchain_core.messages import HumanMessage
+
+
+class IntentDatasetCreator:
+    """Simplified intent classification dataset creator with two strategies"""
+
+    def __init__(
+        self, gemini_api_key: str, knowledge_base: ViettelKnowledgeBase = None
+    ):
+        """Initialize with Gemini API key and optional knowledge base"""
+        self.llm_client = LLMClientFactory.create_client(
+            "gemini", api_key=gemini_api_key, model="gemini-2.0-flash"
+        )
+        self.knowledge_base = knowledge_base
+        self.dataset = {
+            "conversations": {},
+            "generation_methods": {},
+            "intent_distribution": {},
+            "metadata": {
+                "total_conversations": 0,
+                "total_user_messages": 0,
+                "creation_timestamp": time.time(),
+            },
+        }
+
+        print("✅ IntentDatasetCreator initialized (simplified version)")
+
+    def generate_json_response(
+        self, prompt: str, max_retries: int = 3
+    ) -> Optional[Dict]:
+        """Generate response and parse as JSON with retries"""
+        for attempt in range(max_retries):
+            try:
+                response = self.llm_client.generate(prompt, temperature=0.1)
+
+                if response:
+                    response_text = response.strip()
+                    json_match = re.search(r"\{.*\}", response_text, re.DOTALL)
+                    if json_match:
+                        json_text = json_match.group()
+                        return json.loads(json_text)
+                    else:
+                        return json.loads(response_text)
+
+            except json.JSONDecodeError as e:
+                print(f"⚠️ JSON parsing error (attempt {attempt + 1}): {e}")
+                if attempt == max_retries - 1:
+                    print(f"❌ Failed to parse JSON after {max_retries} attempts")
+
+            except Exception as e:
+                print(f"⚠️ API error (attempt {attempt + 1}): {e}")
+                if attempt < max_retries - 1:
+                    time.sleep(2**attempt)
+
+        return None
+
+    def get_all_chunks(self) -> List[Dict]:
+        """Get ALL chunks from ChromaDB vectorstore"""
+        print(f"📚 Retrieving ALL chunks from ChromaDB vectorstore...")
+
+        if not self.knowledge_base:
+            raise ValueError("Knowledge base not provided.")
+
+        try:
+            if (
+                not hasattr(self.knowledge_base, "chroma_retriever")
+                or not self.knowledge_base.chroma_retriever
+            ):
+                raise ValueError("ChromaDB retriever not found in knowledge base")
+
+            vectorstore = self.knowledge_base.chroma_retriever.vectorstore
+            all_docs = vectorstore.get(include=["documents", "metadatas"])
+
+            documents = all_docs["documents"]
+            metadatas = all_docs["metadatas"]
+
+            all_chunks = []
+            seen_content_hashes = set()
+
+            for i, (content, metadata) in enumerate(zip(documents, metadatas)):
+                content_hash = hash(content[:300])
+
+                if (
+                    content_hash not in seen_content_hashes
+                    and len(content.strip()) > 100
+                ):
+                    chunk_info = {
+                        "id": f"chunk_{len(all_chunks)}",
+                        "content": content,
+                        "metadata": metadata or {},
+                    }
+                    all_chunks.append(chunk_info)
+                    seen_content_hashes.add(content_hash)
+
+            print(f"✅ Retrieved {len(all_chunks)} unique chunks from ChromaDB")
+            return all_chunks
+
+        except Exception as e:
+            print(f"❌ Error accessing ChromaDB: {e}")
+            return []
+
+    def generate_single_chunk_conversations(
+        self, chunk: Dict, num_conversations: int = 3
+    ) -> List[Dict]:
+        """Generate conversations from single chunk"""
+        content = chunk["content"]
+
+        generation_instruction = "Tạo cuộc hội thoại tập trung vào chủ đề chính của tài liệu. Bao gồm cả các intent phổ biến như greeting, unclear, human_request để tăng tính đa dạng"
+
+        prompt = INTENT_CLASSIFICATION_CONVERSATION_GENERATION_PROMPT.format(
+            num_conversations=num_conversations,
+            content=content,
+            generation_instruction=generation_instruction,
+        )
+
+        response_json = self.generate_json_response(prompt)
+
+        if response_json and "conversations" in response_json:
+            conversations = response_json["conversations"]
+            valid_conversations = []
+
+            for i, conversation in enumerate(conversations):
+                if "turns" in conversation and len(conversation["turns"]) >= 1:
+                    valid_turns = []
+                    for turn in conversation["turns"]:
+                        if "user" in turn and "intent" in turn:
+                            valid_turns.append(turn)
+
+                    if valid_turns:
+                        conv_obj = {
+                            "id": f"single_{chunk['id']}_{i}",
+                            "turns": valid_turns,
+                            "generation_method": "single_chunk",
+                            "source_chunks": [chunk["id"]],
+                            "chunk_metadata": [chunk["metadata"]],
+                        }
+                        valid_conversations.append(conv_obj)
+            return valid_conversations
+        else:
+            print(f"⚠️ No valid conversations generated for chunk {chunk['id']}")
+            return []
+
+    def generate_multi_chunk_conversations(
+        self, chunks: List[Dict], num_conversations: int = 3
+    ) -> List[Dict]:
+        """Generate conversations from multiple chunks (2-3 chunks)"""
+        # Combine content from multiple chunks
+        combined_content = ""
+        for i, chunk in enumerate(chunks):
+            combined_content += f"\n\n--- Chủ đề {i+1} ---\n" + chunk["content"]
+
+        generation_instruction = f"Tạo cuộc hội thoại tự nhiên kết hợp {len(chunks)} chủ đề khác nhau. Người dùng có thể chuyển từ chủ đề này sang chủ đề khác. Đặc biệt bao gồm các intent như greeting, unclear, human_request để cuộc hội thoại thực tế hơn"
+
+        prompt = INTENT_CLASSIFICATION_CONVERSATION_GENERATION_PROMPT.format(
+            num_conversations=num_conversations,
+            content=combined_content,
+            generation_instruction=generation_instruction,
+        )
+
+        response_json = self.generate_json_response(prompt)
+
+        if response_json and "conversations" in response_json:
+            conversations = response_json["conversations"]
+            valid_conversations = []
+
+            for i, conversation in enumerate(conversations):
+                if "turns" in conversation and len(conversation["turns"]) >= 1:
+                    valid_turns = []
+                    for turn in conversation["turns"]:
+                        if "user" in turn and "intent" in turn:
+                            valid_turns.append(turn)
+
+                    if valid_turns:
+                        conv_obj = {
+                            "id": f"multi_{'-'.join([c['id'] for c in chunks])}_{i}",
+                            "turns": valid_turns,
+                            "generation_method": "multi_chunk",
+                            "source_chunks": [c["id"] for c in chunks],
+                            "chunk_metadata": [c["metadata"] for c in chunks],
+                        }
+                        valid_conversations.append(conv_obj)
+
+            print(
+                f"✅ Generated {len(valid_conversations)} conversations for multi-chunk {[c['id'] for c in chunks]}"
+            )
+            return valid_conversations
+        else:
+            print(
+                f"⚠️ No valid conversations generated for chunks {[c['id'] for c in chunks]}"
+            )
+            return []
+
+    def create_intent_dataset(
+        self,
+        num_conversations_per_chunk: int = 3,
+        save_path: str = "evaluation_data/datasets/intent_classification/viettelpay_intent_dataset.json",
+    ) -> Dict:
+        """Create intent classification dataset using two strategies only"""
+        print(f"\n🚀 Creating intent classification dataset...")
+        print(f"   Conversations per chunk: {num_conversations_per_chunk}")
+
+        # Step 1: Get all chunks
+        all_chunks = self.get_all_chunks()
+        if not all_chunks:
+            raise ValueError("No chunks found in knowledge base!")
+
+        total_chunks = len(all_chunks)
+        print(f"✅ Using all {total_chunks} chunks and shuffle them")
+        random.shuffle(all_chunks)
+
+        # Step 2: Split chunks for two strategies (60% single, 40% multi)
+        split_point = int(total_chunks * 0.6)
+        single_chunks = all_chunks[:split_point]
+        multi_chunks = all_chunks[split_point:]
+
+        print(f"📊 Distribution plan:")
+        print(
+            f"   • Single chunk: {len(single_chunks)} chunks → ~{len(single_chunks) * num_conversations_per_chunk} conversations"
+        )
+        print(
+            f"   • Multi chunk: {len(multi_chunks)} chunks → ~{len(multi_chunks) // 2.5 * num_conversations_per_chunk} conversations"
+        )
+
+        all_conversations = []
+
+        # Step 3: Generate single-chunk conversations
+        print(f"\n💬 Generating single-chunk conversations...")
+        for chunk in tqdm(single_chunks, desc="Single-chunk conversations"):
+            conversations = self.generate_single_chunk_conversations(
+                chunk, num_conversations_per_chunk
+            )
+            all_conversations.extend(conversations)
+            time.sleep(0.1)
+
+        # Step 4: Generate multi-chunk conversations (2-3 chunks randomly)
+        print(f"\n🔀 Generating multi-chunk conversations...")
+        random.shuffle(multi_chunks)  # Randomize order
+
+        i = 0
+        while i < len(multi_chunks):
+            # Randomly choose to use 2 or 3 chunks
+            chunk_count = random.choice([2, 3])
+            chunk_group = multi_chunks[i : i + chunk_count]
+
+            # Only proceed if we have at least 2 chunks
+            if len(chunk_group) >= 2:
+                conversations = self.generate_multi_chunk_conversations(
+                    chunk_group, num_conversations_per_chunk
+                )
+                all_conversations.extend(conversations)
+                time.sleep(0.1)
+
+            i += chunk_count
+
+        # Step 5: Track generation methods and intent distribution
+        method_stats = defaultdict(int)
+        intent_counts = Counter()
+
+        for conv in all_conversations:
+            method_stats[conv["generation_method"]] += 1
+            for turn in conv["turns"]:
+                intent_counts[turn["intent"]] += 1
+
+        # Step 6: Populate dataset structure
+        self.dataset["conversations"] = {conv["id"]: conv for conv in all_conversations}
+
+        self.dataset["generation_methods"] = dict(method_stats)
+        self.dataset["intent_distribution"] = dict(intent_counts)
+
+        # Step 7: Update metadata
+        total_user_messages = sum(len(conv["turns"]) for conv in all_conversations)
+
+        self.dataset["metadata"].update(
+            {
+                "total_conversations": len(all_conversations),
+                "total_user_messages": total_user_messages,
+                "chunks_used": total_chunks,
+                "conversations_per_chunk": num_conversations_per_chunk,
+                "generation_distribution": dict(method_stats),
+                "completion_timestamp": time.time(),
+            }
+        )
+
+        # Step 8: Save dataset
+        os.makedirs(
+            os.path.dirname(save_path) if os.path.dirname(save_path) else ".",
+            exist_ok=True,
+        )
+
+        with open(save_path, "w", encoding="utf-8") as f:
+            json.dump(self.dataset, f, ensure_ascii=False, indent=2)
+
+        print(f"\n✅ Intent classification dataset created successfully!")
+        print(f"   📁 Saved to: {save_path}")
+        print(f"   📊 Statistics:")
+        print(f"      • Total conversations: {len(all_conversations)}")
+        print(f"      • Total user messages: {total_user_messages}")
+        print(f"      • Conversations per chunk: {num_conversations_per_chunk}")
+        print(f"      • Generation methods: {dict(method_stats)}")
+        print(f"      • Intent distribution: {dict(intent_counts)}")
+
+        return self.dataset
+
+
+class IntentClassificationEvaluator:
+    """Evaluator for intent classification performance with method-specific analysis"""
+
+    def __init__(self, dataset: Dict, llm_client):
+        """Initialize evaluator with dataset and LLM client"""
+        self.dataset = dataset
+        self.llm_client = llm_client
+
+        # Define expected intents
+        self.expected_intents = [
+            "greeting",
+            "faq",
+            "error_help",
+            "procedure_guide",
+            "human_request",
+            "out_of_scope",
+            "unclear",
+        ]
+
+        # Critical intents for business
+        self.critical_intents = ["error_help", "human_request"]
+
+        # Define flow mappings based on agent routing logic
+        self.script_based_intents = {
+            "greeting",
+            "out_of_scope",
+            "human_request",
+            "unclear",
+        }
+        self.knowledge_based_intents = {
+            "faq",
+            "error_help",
+            "procedure_guide",
+        }
+
+    def _get_intent_flow(self, intent: str) -> str:
+        """Classify intent into flow type based on agent routing logic"""
+        if intent in self.script_based_intents:
+            return "script_based"
+        elif intent in self.knowledge_based_intents:
+            return "knowledge_based"
+        else:
+            return "unknown"
+
+    def _make_json_serializable(self, obj):
+        """Convert numpy types to native Python types for JSON serialization"""
+        try:
+            import numpy as np
+
+            if isinstance(obj, dict):
+                return {k: self._make_json_serializable(v) for k, v in obj.items()}
+            elif isinstance(obj, list):
+                return [self._make_json_serializable(item) for item in obj]
+            elif isinstance(obj, np.integer):
+                return int(obj)
+            elif isinstance(obj, np.floating):
+                return float(obj)
+            elif isinstance(obj, np.ndarray):
+                return obj.tolist()
+            else:
+                return obj
+        except ImportError:
+            # If numpy is not available, just return the object as-is
+            if isinstance(obj, dict):
+                return {k: self._make_json_serializable(v) for k, v in obj.items()}
+            elif isinstance(obj, list):
+                return [self._make_json_serializable(item) for item in obj]
+            else:
+                return obj
+
+    def calculate_essential_metrics(
+        self, ground_truth: List[str], predictions: List[str]
+    ) -> Dict:
+        """Calculate only essential metrics: accuracy, macro, per-class"""
+        try:
+            from sklearn.metrics import accuracy_score, precision_recall_fscore_support
+
+            overall_accuracy = accuracy_score(ground_truth, predictions)
+
+            # Calculate macro metrics (equal weight per intent)
+            precision, recall, f1, support = precision_recall_fscore_support(
+                ground_truth, predictions, average="macro", zero_division=0
+            )
+
+            macro_metrics = {
+                "macro_precision": precision,
+                "macro_recall": recall,
+                "macro_f1": f1,
+            }
+
+            # Calculate per-class metrics
+            precision_per_class, recall_per_class, f1_per_class, support_per_class = (
+                precision_recall_fscore_support(
+                    ground_truth, predictions, average=None, zero_division=0
+                )
+            )
+
+            # Get unique labels
+            unique_labels = sorted(list(set(ground_truth + predictions)))
+
+            per_class_metrics = {}
+            for i, label in enumerate(unique_labels):
+                if i < len(precision_per_class):
+                    per_class_metrics[label] = {
+                        "precision": float(precision_per_class[i]),
+                        "recall": float(recall_per_class[i]),
+                        "f1": float(f1_per_class[i]),
+                        "support": int(
+                            support_per_class[i] if i < len(support_per_class) else 0
+                        ),
+                    }
+
+            # Calculate critical intent recall
+            critical_recall = {}
+            for intent in self.critical_intents:
+                if intent in per_class_metrics:
+                    critical_recall[intent] = per_class_metrics[intent]["recall"]
+
+            return {
+                "overall_accuracy": float(overall_accuracy),
+                "macro_precision": float(macro_metrics["macro_precision"]),
+                "macro_recall": float(macro_metrics["macro_recall"]),
+                "macro_f1": float(macro_metrics["macro_f1"]),
+                "per_class_metrics": per_class_metrics,
+                "critical_intent_recall": {
+                    k: float(v) for k, v in critical_recall.items()
+                },
+            }
+
+        except ImportError:
+            print("⚠️ scikit-learn not installed. Using basic accuracy only.")
+            overall_accuracy = sum(
+                1 for gt, pred in zip(ground_truth, predictions) if gt == pred
+            ) / len(predictions)
+
+            return {"overall_accuracy": float(overall_accuracy)}
+
+    def evaluate_intent_classification(self) -> Dict:
+        """Evaluate intent classification performance with method and flow breakdown"""
+        print(f"\n🎯 Running intent classification evaluation...")
+
+        conversations = self.dataset["conversations"]
+
+        # Initialize tracking
+        all_predictions = []
+        all_ground_truth = []
+        method_results = defaultdict(lambda: {"predictions": [], "ground_truth": []})
+        flow_results = defaultdict(lambda: {"predictions": [], "ground_truth": []})
+        conversation_results = {}
+
+        # Process each conversation
+        for conv_id, conv_data in tqdm(
+            conversations.items(), desc="Evaluating conversations"
+        ):
+            generation_method = conv_data.get("generation_method", "unknown")
+
+            conversation_results[conv_id] = {
+                "turns": [],
+                "accuracy": 0,
+                "generation_method": generation_method,
+            }
+
+            correct_predictions = 0
+            total_turns = len(conv_data["turns"])
+
+            # Process each turn in the conversation
+            for turn_idx, turn in enumerate(conv_data["turns"]):
+                user_message = turn["user"]
+                ground_truth_intent = turn["intent"]
+
+                try:
+                    # Create messages in the format expected by classify_intent_node
+                    messages = [HumanMessage(content=user_message)]
+
+                    # Create a mock state for the intent classification node
+                    state = ViettelPayState(messages=messages)
+
+                    # Use the classify_intent_node directly
+                    result_state = classify_intent_node(state, self.llm_client)
+                    predicted_intent = result_state.get("intent", "unclear")
+
+                    # Track results
+                    is_correct = predicted_intent == ground_truth_intent
+                    if is_correct:
+                        correct_predictions += 1
+
+                    # Add to overall tracking
+                    all_predictions.append(predicted_intent)
+                    all_ground_truth.append(ground_truth_intent)
+
+                    # Add to method-specific tracking
+                    method_results[generation_method]["predictions"].append(
+                        predicted_intent
+                    )
+                    method_results[generation_method]["ground_truth"].append(
+                        ground_truth_intent
+                    )
+
+                    # Add to flow-specific tracking
+                    ground_truth_flow = self._get_intent_flow(ground_truth_intent)
+                    predicted_flow = self._get_intent_flow(predicted_intent)
+
+                    flow_results[ground_truth_flow]["predictions"].append(
+                        predicted_intent
+                    )
+                    flow_results[ground_truth_flow]["ground_truth"].append(
+                        ground_truth_intent
+                    )
+
+                    conversation_results[conv_id]["turns"].append(
+                        {
+                            "turn": turn_idx + 1,
+                            "user_message": user_message,
+                            "ground_truth": ground_truth_intent,
+                            "predicted": predicted_intent,
+                            "correct": is_correct,
+                        }
+                    )
+
+                except Exception as e:
+                    print(f"⚠️ Error processing turn {turn_idx} in {conv_id}: {e}")
+                    # Use "unclear" as fallback prediction
+                    all_predictions.append("unclear")
+                    all_ground_truth.append(ground_truth_intent)
+                    method_results[generation_method]["predictions"].append("unclear")
+                    method_results[generation_method]["ground_truth"].append(
+                        ground_truth_intent
+                    )
+
+                    # Add to flow-specific tracking (for errors)
+                    ground_truth_flow = self._get_intent_flow(ground_truth_intent)
+                    flow_results[ground_truth_flow]["predictions"].append("unclear")
+                    flow_results[ground_truth_flow]["ground_truth"].append(
+                        ground_truth_intent
+                    )
+
+            # Calculate conversation accuracy
+            conversation_results[conv_id]["accuracy"] = float(
+                correct_predictions / total_turns if total_turns > 0 else 0
+            )
+
+        # Calculate overall metrics
+        overall_metrics = self.calculate_essential_metrics(
+            all_ground_truth, all_predictions
+        )
+
+        # Calculate method-specific metrics
+        method_metrics = {}
+        for method, method_data in method_results.items():
+            if method_data["predictions"]:  # Ensure we have data
+                method_metrics[method] = self.calculate_essential_metrics(
+                    method_data["ground_truth"], method_data["predictions"]
+                )
+                method_metrics[method]["total_messages"] = len(
+                    method_data["predictions"]
+                )
+
+        # Calculate flow-specific metrics
+        flow_metrics = {}
+        for flow, flow_data in flow_results.items():
+            if flow_data["predictions"]:  # Ensure we have data
+                flow_metrics[flow] = self.calculate_essential_metrics(
+                    flow_data["ground_truth"], flow_data["predictions"]
+                )
+                flow_metrics[flow]["total_messages"] = len(flow_data["predictions"])
+
+        results = {
+            "overall_metrics": overall_metrics,
+            "method_specific_metrics": method_metrics,
+            "flow_specific_metrics": flow_metrics,
+            "conversation_results": conversation_results,
+            "intent_distribution": {
+                "ground_truth": dict(Counter(all_ground_truth)),
+                "predicted": dict(Counter(all_predictions)),
+            },
+            "generation_methods": self.dataset.get("generation_methods", {}),
+        }
+
+        # Make sure all values are JSON serializable
+        results = self._make_json_serializable(results)
+
+        return results
+
+    def print_evaluation_results(self, results: Dict):
+        """Print comprehensive evaluation results"""
+        print(f"\n🎯 INTENT CLASSIFICATION EVALUATION RESULTS")
+        print("=" * 60)
+
+        # Overall performance
+        overall = results["overall_metrics"]
+        print(f"\n📊 Overall Performance:")
+        print(f"   Accuracy: {overall['overall_accuracy']:.3f}")
+        if "macro_precision" in overall:
+            print(f"   Macro Precision: {overall['macro_precision']:.3f}")
+            print(f"   Macro Recall: {overall['macro_recall']:.3f}")
+            print(f"   Macro F1: {overall['macro_f1']:.3f}")
+
+        # Per-class performance
+        if "per_class_metrics" in overall:
+            print(f"\n📋 Per-Class Performance:")
+            print(
+                f"{'Intent':<15} {'Precision':<10} {'Recall':<10} {'F1':<10} {'Support':<10}"
+            )
+            print("-" * 65)
+
+            per_class = overall["per_class_metrics"]
+            for intent in self.expected_intents:
+                if intent in per_class:
+                    metrics = per_class[intent]
+                    print(
+                        f"{intent:<15} {metrics['precision']:<10.3f} {metrics['recall']:<10.3f} {metrics['f1']:<10.3f} {metrics['support']:<10}"
+                    )
+
+        # Critical intents performance
+        if "critical_intent_recall" in overall:
+            print(f"\n🚨 Critical Intent Performance:")
+            for intent, recall in overall["critical_intent_recall"].items():
+                status = "✅" if recall >= 0.85 else "⚠️" if recall >= 0.75 else "❌"
+                print(f"   {status} {intent}: Recall = {recall:.3f}")
+
+        # Method-specific performance
+        print(f"\n🔄 Performance by Generation Method:")
+        method_metrics = results["method_specific_metrics"]
+        if method_metrics:
+            print(f"{'Method':<20} {'Accuracy':<10} {'Macro F1':<10} {'Messages':<10}")
+            print("-" * 55)
+
+            for method, metrics in method_metrics.items():
+                accuracy = metrics["overall_accuracy"]
+                macro_f1 = metrics.get("macro_f1", 0)
+                total_msgs = metrics["total_messages"]
+                print(
+                    f"{method:<20} {accuracy:<10.3f} {macro_f1:<10.3f} {total_msgs:<10}"
+                )
+
+        # Flow-specific performance
+        print(f"\n🔀 Performance by Agent Flow:")
+        flow_metrics = results["flow_specific_metrics"]
+        if flow_metrics:
+            print(
+                f"{'Flow Type':<20} {'Accuracy':<10} {'Macro F1':<10} {'Messages':<10}"
+            )
+            print("-" * 55)
+
+            for flow, metrics in flow_metrics.items():
+                accuracy = metrics["overall_accuracy"]
+                macro_f1 = metrics.get("macro_f1", 0)
+                total_msgs = metrics["total_messages"]
+                flow_display = f"{flow}_flow"
+                print(
+                    f"{flow_display:<20} {accuracy:<10.3f} {macro_f1:<10.3f} {total_msgs:<10}"
+                )
+
+        # Intent distribution comparison
+        print(f"\n📈 Intent Distribution:")
+        gt_dist = results["intent_distribution"]["ground_truth"]
+        pred_dist = results["intent_distribution"]["predicted"]
+
+        print(f"{'Intent':<15} {'Ground Truth':<15} {'Predicted':<15}")
+        print("-" * 50)
+
+        all_intents = set(list(gt_dist.keys()) + list(pred_dist.keys()))
+        for intent in sorted(all_intents):
+            gt_count = gt_dist.get(intent, 0)
+            pred_count = pred_dist.get(intent, 0)
+            print(f"{intent:<15} {gt_count:<15} {pred_count:<15}")
+
+        # Method insights
+        print(f"\n💡 Method-Specific Insights:")
+        if method_metrics:
+            method_accuracies = {
+                method: metrics["overall_accuracy"]
+                for method, metrics in method_metrics.items()
+            }
+            best_method = max(
+                method_accuracies.keys(), key=lambda k: method_accuracies[k]
+            )
+            worst_method = min(
+                method_accuracies.keys(), key=lambda k: method_accuracies[k]
+            )
+
+            print(
+                f"   • Best performing method: {best_method} ({method_accuracies[best_method]:.3f})"
+            )
+            print(
+                f"   • Most challenging method: {worst_method} ({method_accuracies[worst_method]:.3f})"
+            )
+            print(
+                f"   • Performance gap: {method_accuracies[best_method] - method_accuracies[worst_method]:.3f}"
+            )
+
+        # Flow insights
+        print(f"\n🔀 Flow-Specific Insights:")
+        if flow_metrics:
+            flow_accuracies = {
+                flow: metrics["overall_accuracy"]
+                for flow, metrics in flow_metrics.items()
+            }
+
+            if len(flow_accuracies) >= 2:
+                best_flow = max(
+                    flow_accuracies.keys(), key=lambda k: flow_accuracies[k]
+                )
+                worst_flow = min(
+                    flow_accuracies.keys(), key=lambda k: flow_accuracies[k]
+                )
+
+                print(
+                    f"   • Best performing flow: {best_flow} ({flow_accuracies[best_flow]:.3f})"
+                )
+                print(
+                    f"   • Most challenging flow: {worst_flow} ({flow_accuracies[worst_flow]:.3f})"
+                )
+                print(
+                    f"   • Flow performance gap: {flow_accuracies[best_flow] - flow_accuracies[worst_flow]:.3f}"
+                )
+
+                # Provide interpretation
+                if (
+                    "script_based" in flow_accuracies
+                    and "knowledge_based" in flow_accuracies
+                ):
+                    script_acc = flow_accuracies["script_based"]
+                    kb_acc = flow_accuracies["knowledge_based"]
+
+                    if script_acc > kb_acc:
+                        print(
+                            f"   • Script-based intents are easier to classify ({script_acc:.3f} vs {kb_acc:.3f})"
+                        )
+                    elif kb_acc > script_acc:
+                        print(
+                            f"   • Knowledge-based intents are easier to classify ({kb_acc:.3f} vs {script_acc:.3f})"
+                        )
+                    else:
+                        print(
+                            f"   • Both flows perform similarly ({script_acc:.3f} vs {kb_acc:.3f})"
+                        )
+            else:
+                for flow, accuracy in flow_accuracies.items():
+                    print(f"   • {flow} flow accuracy: {accuracy:.3f}")
+
+        # Success criteria check
+        print(f"\n✅ Success Criteria Check:")
+        accuracy = overall["overall_accuracy"]
+        if accuracy >= 0.80:
+            print(f"   🎉 GOOD: Overall accuracy {accuracy:.3f} >= 0.80")
+        elif accuracy >= 0.75:
+            print(f"   ⚠️ OKAY: Overall accuracy {accuracy:.3f} >= 0.75")
+        else:
+            print(f"   ❌ NEEDS WORK: Overall accuracy {accuracy:.3f} < 0.75")
+
+
+def main():
+    """Main function for simplified intent classification evaluation"""
+    parser = argparse.ArgumentParser(
+        description="Simplified ViettelPay Intent Classification Evaluation"
+    )
+    parser.add_argument(
+        "--mode",
+        choices=["create", "evaluate", "full"],
+        default="full",
+        help="Mode: create dataset, evaluate, or full pipeline",
+    )
+    parser.add_argument(
+        "--dataset-path",
+        default="evaluation_data/datasets/intent_classification/viettelpay_intent_dataset.json",
+        help="Path to intent dataset",
+    )
+    parser.add_argument(
+        "--results-path",
+        default="evaluation_data/results/intent_classification/viettelpay_intent_results.json",
+        help="Path to save evaluation results",
+    )
+    parser.add_argument(
+        "--conversations-per-chunk",
+        type=int,
+        default=3,
+        help="Number of conversations per chunk (default: 3)",
+    )
+    parser.add_argument(
+        "--knowledge-base-path",
+        default="./knowledge_base",
+        help="Path to knowledge base",
+    )
+
+    args = parser.parse_args()
+
+    # Configuration
+    GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
+
+    if not GEMINI_API_KEY:
+        print("❌ Please set GEMINI_API_KEY environment variable")
+        return
+
+    try:
+        # Initialize components based on mode
+        kb = None
+        if args.mode in ["create", "full"]:
+            # Initialize knowledge base only if creating dataset
+            print("🔧 Initializing ViettelPay knowledge base...")
+            kb = ViettelKnowledgeBase()
+            if not kb.load_knowledge_base(args.knowledge_base_path):
+                print(
+                    "❌ Failed to load knowledge base. Please run build_database_script.py first."
+                )
+                return
+
+        # Step 1: Create dataset if requested
+        if args.mode in ["create", "full"]:
+            print(f"\n🎯 Creating simplified intent classification dataset...")
+            creator = IntentDatasetCreator(GEMINI_API_KEY, kb)
+
+            dataset = creator.create_intent_dataset(
+                num_conversations_per_chunk=args.conversations_per_chunk,
+                save_path=args.dataset_path,
+            )
+
+        # Step 2: Evaluate if requested
+        if args.mode in ["evaluate", "full"]:
+            print(f"\n📊 Evaluating intent classification...")
+
+            # Load dataset if not created in this run
+            if args.mode == "evaluate":
+                if not os.path.exists(args.dataset_path):
+                    print(f"❌ Dataset not found: {args.dataset_path}")
+                    return
+
+                with open(args.dataset_path, "r", encoding="utf-8") as f:
+                    dataset = json.load(f)
+
+            # Initialize LLM client for intent classification
+            print("🤖 Initializing LLM client for intent classification...")
+            llm_client = LLMClientFactory.create_client(
+                "gemini", api_key=GEMINI_API_KEY, model="gemini-2.0-flash"
+            )
+
+            # Run evaluation
+            evaluator = IntentClassificationEvaluator(dataset, llm_client)
+            results = evaluator.evaluate_intent_classification()
+            evaluator.print_evaluation_results(results)
+
+            # Save results
+            if args.results_path:
+                with open(args.results_path, "w", encoding="utf-8") as f:
+                    json.dump(results, f, ensure_ascii=False, indent=2)
+                print(f"\n💾 Results saved to: {args.results_path}")
+
+        print(f"\n✅ Intent classification evaluation completed successfully!")
+        print(f"\n💡 Summary improvements made:")
+        print(f"   • Removed pattern-based generation for simplicity")
+        print(f"   • Added configurable conversations-per-chunk (default: 3)")
+        print(f"   • Improved chunk mixing (random 2-3 chunks)")
+        print(f"   • Enhanced prompts to include non-topic intents")
+        print(f"   • Added flow-specific analysis (script-based vs knowledge-based)")
+
+    except Exception as e:
+        print(f"❌ Error in main execution: {e}")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()

src/evaluation/multi_turn_retrieval.py

@@ -0,0 +1,815 @@
+"""
+Multi-Turn Conversation Retrieval Evaluation for ViettelPay RAG System
+Generates multi-turn conversations and evaluates retrieval performance
+"""
+
+import json
+import os
+import sys
+import argparse
+import time
+from typing import Dict, List, Tuple, Optional, Union
+from pathlib import Path
+from collections import defaultdict
+import pandas as pd
+from tqdm import tqdm
+import re
+
+# Load environment variables from .env file
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Add the project root to Python path so we can import from src
+project_root = Path(__file__).parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+# Import existing components
+from src.evaluation.prompts import MULTI_TURN_CONVERSATION_GENERATION_PROMPT
+from src.knowledge_base.viettel_knowledge_base import ViettelKnowledgeBase
+from src.evaluation.single_turn_retrieval import SingleTurnRetrievalEvaluator
+from src.llm.llm_client import LLMClientFactory, BaseLLMClient
+from src.agent.nodes import query_enhancement_node, ViettelPayState
+from langchain_core.messages import HumanMessage
+
+
+class MultiTurnDatasetCreator:
+    """Multi-turn conversation dataset creator for ViettelPay evaluation"""
+
+    def __init__(
+        self, gemini_api_key: str, knowledge_base: ViettelKnowledgeBase = None
+    ):
+        """
+        Initialize with Gemini API key and optional knowledge base
+
+        Args:
+            gemini_api_key: Google AI API key for Gemini
+            knowledge_base: Pre-initialized ViettelKnowledgeBase instance
+        """
+        self.llm_client = LLMClientFactory.create_client(
+            "gemini", api_key=gemini_api_key, model="gemini-2.0-flash"
+        )
+        self.knowledge_base = knowledge_base
+        self.dataset = {
+            "conversations": {},
+            "documents": {},
+            "metadata": {
+                "total_chunks_processed": 0,
+                "conversations_generated": 0,
+                "creation_timestamp": time.time(),
+            },
+        }
+
+        print("✅ MultiTurnDatasetCreator initialized with Gemini 2.0 Flash")
+
+    def generate_json_response(
+        self, prompt: str, max_retries: int = 3
+    ) -> Optional[Dict]:
+        """
+        Generate response and parse as JSON with retries
+
+        Args:
+            prompt: Input prompt
+            max_retries: Maximum number of retry attempts
+
+        Returns:
+            Parsed JSON response or None if failed
+        """
+        for attempt in range(max_retries):
+            try:
+                response = self.llm_client.generate(prompt, temperature=0.1)
+
+                if response:
+                    # Clean response text
+                    response_text = response.strip()
+
+                    # Extract JSON from response (handle cases with extra text)
+                    json_match = re.search(r"\{.*\}", response_text, re.DOTALL)
+                    if json_match:
+                        json_text = json_match.group()
+                        return json.loads(json_text)
+                    else:
+                        # Try parsing the whole response
+                        return json.loads(response_text)
+
+            except json.JSONDecodeError as e:
+                print(f"⚠️ JSON parsing error (attempt {attempt + 1}): {e}")
+                if attempt == max_retries - 1:
+                    print(f"❌ Failed to parse JSON after {max_retries} attempts")
+                    print(
+                        f"Raw response: {response if 'response' in locals() else 'No response'}"
+                    )
+
+            except Exception as e:
+                print(f"⚠️ API error (attempt {attempt + 1}): {e}")
+                if attempt < max_retries - 1:
+                    time.sleep(2**attempt)  # Exponential backoff
+
+        return None
+
+    def get_all_chunks(self) -> List[Dict]:
+        """
+        Get ALL chunks directly from ChromaDB vectorstore
+        Reuse the same method from single-turn evaluation
+
+        Returns:
+            List of all document chunks with content and metadata
+        """
+        print(f"📚 Retrieving ALL chunks directly from ChromaDB vectorstore...")
+
+        if not self.knowledge_base:
+            raise ValueError(
+                "Knowledge base not provided. Please initialize with a ViettelKnowledgeBase instance."
+            )
+
+        try:
+            # Access the ChromaDB vectorstore directly
+            if (
+                not hasattr(self.knowledge_base, "chroma_retriever")
+                or not self.knowledge_base.chroma_retriever
+            ):
+                raise ValueError("ChromaDB retriever not found in knowledge base")
+
+            # Get the vectorstore from the retriever
+            vectorstore = self.knowledge_base.chroma_retriever.vectorstore
+
+            # Get all documents directly from ChromaDB
+            print("   Accessing ChromaDB collection...")
+            all_docs = vectorstore.get(include=["documents", "metadatas"])
+
+            documents = all_docs["documents"]
+            metadatas = all_docs["metadatas"]
+
+            print(f"   Found {len(documents)} documents in ChromaDB")
+
+            # Convert to our expected format
+            all_chunks = []
+            seen_content_hashes = set()
+
+            for i, (content, metadata) in enumerate(zip(documents, metadatas)):
+                # Create content hash for deduplication
+                content_hash = hash(content[:300])
+
+                if (
+                    content_hash not in seen_content_hashes
+                    and len(content.strip()) > 100
+                ):
+                    chunk_info = {
+                        "id": f"chunk_{len(all_chunks)}",
+                        "content": content,
+                        "metadata": metadata or {},
+                        "source": "chromadb_direct",
+                        "content_length": len(content),
+                        "original_index": i,
+                    }
+                    all_chunks.append(chunk_info)
+                    seen_content_hashes.add(content_hash)
+
+            print(f"✅ Retrieved {len(all_chunks)} unique chunks from ChromaDB")
+
+            # Sort by content length (longer chunks first)
+            all_chunks.sort(key=lambda x: x["content_length"], reverse=True)
+
+            return all_chunks
+
+        except Exception as e:
+            print(f"❌ Error accessing ChromaDB directly: {e}")
+            return []
+
+    def generate_conversations_for_chunk(
+        self, chunk: Dict, num_conversations: int = 2
+    ) -> List[Dict]:
+        """
+        Generate multi-turn conversations for a single chunk using Gemini
+
+        Args:
+            chunk: Chunk dictionary with content and metadata
+            num_conversations: Number of conversations to generate per chunk
+
+        Returns:
+            List of conversation dictionaries
+        """
+        content = chunk["content"]
+
+        prompt = MULTI_TURN_CONVERSATION_GENERATION_PROMPT.format(
+            num_conversations=num_conversations, content=content
+        )
+
+        response_json = self.generate_json_response(prompt)
+
+        if response_json and "conversations" in response_json:
+            conversations = response_json["conversations"]
+
+            # Create conversation objects with metadata
+            conversation_objects = []
+            for i, conversation in enumerate(conversations):
+                if len(conversation.get("turns", [])) >= 2:  # At least 2 turns
+                    conversation_obj = {
+                        "id": f"conv_{chunk['id']}_{i}",
+                        "turns": conversation["turns"],
+                        "conversation_type": conversation.get("type", "general"),
+                        "source_chunk": chunk["id"],
+                        "chunk_metadata": chunk["metadata"],
+                        "generation_method": "gemini_json",
+                    }
+                    conversation_objects.append(conversation_obj)
+
+            return conversation_objects
+        else:
+            print(f"⚠️ No valid conversations generated for chunk {chunk['id']}")
+            return []
+
+    def create_multi_turn_dataset(
+        self,
+        conversations_per_chunk: int = 2,
+        save_path: str = "evaluation_data/datasets/multi_turn_retrieval/viettelpay_multiturn_conversations.json",
+    ) -> Dict:
+        """
+        Create multi-turn conversation dataset using ALL chunks
+
+        Args:
+            conversations_per_chunk: Number of conversations to generate per chunk
+            save_path: Path to save the dataset JSON file
+
+        Returns:
+            Complete dataset dictionary with conversations
+        """
+        print(f"\n🚀 Creating multi-turn conversation dataset...")
+        print(f"   Target: Process ALL chunks from knowledge base")
+        print(f"   Conversations per chunk: {conversations_per_chunk}")
+
+        # Step 1: Get all chunks
+        all_chunks = self.get_all_chunks()
+        total_chunks = len(all_chunks)
+
+        if total_chunks == 0:
+            raise ValueError("No chunks found in knowledge base!")
+
+        print(f"✅ Found {total_chunks} chunks to process")
+
+        # Step 2: Generate conversations for all chunks
+        print(f"\n💬 Generating conversations for {total_chunks} chunks...")
+        all_conversations = []
+
+        for chunk in tqdm(all_chunks, desc="Generating conversations"):
+            conversations = self.generate_conversations_for_chunk(
+                chunk, conversations_per_chunk
+            )
+            all_conversations.extend(conversations)
+            time.sleep(0.2)  # Rate limiting for Gemini API
+
+        # Step 3: Populate dataset structure
+        self.dataset["documents"] = {
+            chunk["id"]: chunk["content"] for chunk in all_chunks
+        }
+        self.dataset["conversations"] = {
+            conv["id"]: {
+                "turns": conv["turns"],
+                "conversation_type": conv["conversation_type"],
+                "source_chunk": conv["source_chunk"],
+                "chunk_metadata": conv["chunk_metadata"],
+                "generation_method": conv["generation_method"],
+            }
+            for conv in all_conversations
+        }
+
+        # Step 4: Update metadata
+        self.dataset["metadata"].update(
+            {
+                "total_chunks_processed": total_chunks,
+                "conversations_generated": len(all_conversations),
+                "conversations_per_chunk": conversations_per_chunk,
+                "completion_timestamp": time.time(),
+            }
+        )
+
+        # Step 5: Save dataset
+        os.makedirs(
+            os.path.dirname(save_path) if os.path.dirname(save_path) else ".",
+            exist_ok=True,
+        )
+
+        with open(save_path, "w", encoding="utf-8") as f:
+            json.dump(self.dataset, f, ensure_ascii=False, indent=2)
+
+        print(f"\n✅ Multi-turn conversation dataset created successfully!")
+        print(f"   📁 Saved to: {save_path}")
+        print(f"   📊 Statistics:")
+        print(f"      • Chunks processed: {total_chunks}")
+        print(f"      • Conversations generated: {len(all_conversations)}")
+        print(
+            f"      • Avg conversations per chunk: {len(all_conversations)/total_chunks:.1f}"
+        )
+
+        return self.dataset
+
+
+class ConversationEnhancer:
+    """Convert multi-turn conversations to enhanced queries using existing query enhancement"""
+
+    def __init__(self, gemini_api_key: str):
+        """Initialize with Gemini API key for query enhancement"""
+        self.llm_client = LLMClientFactory.create_client(
+            "gemini", api_key=gemini_api_key, model="gemini-2.0-flash-lite"
+        )
+        print("✅ ConversationEnhancer initialized")
+
+    def enhance_conversation(self, conversation_turns: List[Dict]) -> str:
+        """
+        Convert a multi-turn conversation to an enhanced query
+
+        Args:
+            conversation_turns: List of turn dictionaries with role and content
+
+        Returns:
+            Enhanced query string
+        """
+        try:
+            # Create messages in the format expected by query_enhancement_node
+            messages = []
+            for turn in conversation_turns:
+                if turn["role"] == "user":
+                    messages.append(HumanMessage(content=turn["content"]))
+
+            # Create a mock state for the query enhancement node
+            state = ViettelPayState(messages=messages)
+
+            # Use the existing query enhancement node
+            enhanced_state = query_enhancement_node(state, self.llm_client)
+
+            enhanced_query = enhanced_state.get("enhanced_query", "")
+
+            if not enhanced_query:
+                # Fallback: concatenate all user messages
+                user_messages = [
+                    turn["content"]
+                    for turn in conversation_turns
+                    if turn["role"] == "user"
+                ]
+                enhanced_query = " ".join(user_messages)
+
+            return enhanced_query
+
+        except Exception as e:
+            print(f"❌ Error enhancing conversation: {e}")
+            # Fallback: concatenate all user messages
+            user_messages = [
+                turn["content"] for turn in conversation_turns if turn["role"] == "user"
+            ]
+            return " ".join(user_messages)
+
+    def convert_dataset_to_single_turn_format(
+        self,
+        multi_turn_dataset: Dict,
+        save_path: str = "evaluation_data/datasets/multi_turn_retrieval/viettelpay_multiturn_enhanced.json",
+    ) -> Dict:
+        """
+        Convert multi-turn conversation dataset to single-turn format with enhanced queries
+
+        Args:
+            multi_turn_dataset: Multi-turn conversation dataset
+            save_path: Path to save the converted dataset
+
+        Returns:
+            Single-turn format dataset
+        """
+        print(f"\n🔄 Converting multi-turn conversations to enhanced queries...")
+
+        conversations = multi_turn_dataset["conversations"]
+        documents = multi_turn_dataset["documents"]
+
+        # Initialize single-turn format dataset
+        single_turn_dataset = {
+            "queries": {},
+            "documents": documents,
+            "conversation_metadata": {},
+            "metadata": {
+                "total_conversations_processed": len(conversations),
+                "enhanced_queries_generated": 0,
+                "conversion_timestamp": time.time(),
+                "original_dataset_metadata": multi_turn_dataset.get("metadata", {}),
+            },
+        }
+
+        enhanced_count = 0
+
+        # Process each conversation
+        for conv_id, conv_data in tqdm(
+            conversations.items(), desc="Enhancing conversations"
+        ):
+            try:
+                # Extract turns
+                turns = conv_data["turns"]
+
+                # Enhance conversation to single query
+                enhanced_query = self.enhance_conversation(turns)
+
+                if enhanced_query and len(enhanced_query.strip()) > 5:
+                    single_turn_dataset["queries"][conv_id] = enhanced_query
+                    single_turn_dataset["conversation_metadata"][conv_id] = {
+                        "original_conversation": turns,
+                        "conversation_type": conv_data.get(
+                            "conversation_type", "general"
+                        ),
+                        "source_chunk": conv_data["source_chunk"],
+                        "chunk_metadata": conv_data.get("chunk_metadata", {}),
+                        "generation_method": conv_data.get(
+                            "generation_method", "unknown"
+                        ),
+                    }
+                    enhanced_count += 1
+
+                time.sleep(0.1)  # Small delay for rate limiting
+
+            except Exception as e:
+                print(f"⚠️ Error processing conversation {conv_id}: {e}")
+                continue
+
+        # Update metadata
+        single_turn_dataset["metadata"]["enhanced_queries_generated"] = enhanced_count
+
+        # Save converted dataset
+        os.makedirs(
+            os.path.dirname(save_path) if os.path.dirname(save_path) else ".",
+            exist_ok=True,
+        )
+
+        with open(save_path, "w", encoding="utf-8") as f:
+            json.dump(single_turn_dataset, f, ensure_ascii=False, indent=2)
+
+        print(f"✅ Conversion completed successfully!")
+        print(f"   📁 Saved to: {save_path}")
+        print(f"   📊 Statistics:")
+        print(f"      • Conversations processed: {len(conversations)}")
+        print(f"      • Enhanced queries generated: {enhanced_count}")
+        print(f"      • Success rate: {enhanced_count/len(conversations)*100:.1f}%")
+
+        return single_turn_dataset
+
+
+class MultiTurnEvaluator:
+    """Extended evaluator for multi-turn conversation retrieval with additional analysis"""
+
+    def __init__(self, dataset: Dict, knowledge_base: ViettelKnowledgeBase):
+        """
+        Initialize evaluator with dataset and knowledge base
+
+        Args:
+            dataset: Evaluation dataset in single-turn format (from converted multi-turn)
+            knowledge_base: ViettelKnowledgeBase instance to evaluate
+        """
+        self.dataset = dataset
+        self.knowledge_base = knowledge_base
+        self.single_turn_evaluator = SingleTurnRetrievalEvaluator(
+            dataset, knowledge_base
+        )
+
+    def _get_conversation_metadata(self, query_id: str) -> Dict:
+        """
+        Get conversation metadata for a query, handling both formats
+
+        Args:
+            query_id: Query identifier
+
+        Returns:
+            Metadata dictionary
+        """
+        # First try conversation_metadata (multi-turn format)
+        conversation_metadata = self.dataset.get("conversation_metadata", {})
+        if query_id in conversation_metadata:
+            return conversation_metadata[query_id]
+
+        # Fallback to question_metadata (single-turn format)
+        question_metadata = self.dataset.get("question_metadata", {})
+        if query_id in question_metadata:
+            # Convert single-turn format to multi-turn format for consistency
+            meta = question_metadata[query_id]
+            return {
+                "conversation_type": "single_turn",
+                "source_chunk": meta.get("source_chunk"),
+                "original_conversation": [
+                    {"role": "user", "content": self.dataset["queries"][query_id]}
+                ],
+                "chunk_metadata": meta.get("chunk_metadata", {}),
+                "generation_method": meta.get("generation_method", "unknown"),
+            }
+
+        return {}
+
+    def evaluate_multi_turn_performance(
+        self, k_values: List[int] = [1, 3, 5, 10]
+    ) -> Dict:
+        """
+        Evaluate multi-turn conversation retrieval performance
+
+        Args:
+            k_values: List of k values to evaluate
+
+        Returns:
+            Dictionary with evaluation results and multi-turn specific analysis
+        """
+        print(f"\n🔍 Running multi-turn conversation evaluation...")
+
+        # Step 1: Run standard single-turn evaluation
+        base_results = self.single_turn_evaluator.evaluate(k_values)
+
+        # Step 2: Add multi-turn specific analysis
+        # Analyze by conversation type
+        results_by_type = defaultdict(
+            lambda: {"hit_rates": {k: [] for k in k_values}, "rr_scores": []}
+        )
+
+        for query_id, query_result in base_results["per_query_results"].items():
+            conv_meta = self._get_conversation_metadata(query_id)
+            conv_type = conv_meta.get("conversation_type", "unknown")
+
+            # Add to type-specific results
+            results_by_type[conv_type]["rr_scores"].append(query_result.get("rr", 0))
+            for k in k_values:
+                hit_rate = query_result.get("hit_rates", {}).get(k, 0)
+                results_by_type[conv_type]["hit_rates"][k].append(hit_rate)
+
+        # Calculate averages by conversation type
+        type_analysis = {}
+        for conv_type, type_results in results_by_type.items():
+            type_analysis[conv_type] = {
+                "hit_rates": {
+                    k: sum(hits) / len(hits) if hits else 0
+                    for k, hits in type_results["hit_rates"].items()
+                },
+                "mrr": (
+                    sum(type_results["rr_scores"]) / len(type_results["rr_scores"])
+                    if type_results["rr_scores"]
+                    else 0
+                ),
+                "total_conversations": len(type_results["rr_scores"]),
+            }
+
+        # Analyze conversation length impact
+        turn_length_analysis = self._analyze_by_conversation_length(
+            base_results, k_values
+        )
+
+        # Combine results
+        multi_turn_results = {
+            **base_results,  # Include all base results
+            "conversation_type_analysis": type_analysis,
+            "turn_length_analysis": turn_length_analysis,
+            "multi_turn_metadata": {
+                "evaluation_type": "multi_turn_conversation",
+                "conversation_types": list(type_analysis.keys()),
+                "total_conversation_types": len(type_analysis),
+            },
+        }
+
+        return multi_turn_results
+
+    def _analyze_by_conversation_length(
+        self, base_results: Dict, k_values: List[int]
+    ) -> Dict:
+        """Analyze performance by conversation turn length"""
+
+        length_analysis = defaultdict(
+            lambda: {"hit_rates": {k: [] for k in k_values}, "rr_scores": []}
+        )
+
+        for query_id, query_result in base_results["per_query_results"].items():
+            conv_meta = self._get_conversation_metadata(query_id)
+            original_conv = conv_meta.get("original_conversation", [])
+            turn_count = len(
+                [turn for turn in original_conv if turn.get("role") == "user"]
+            )
+
+            # Categorize by turn length
+            if turn_count == 1:
+                length_category = "1_turn"  # Single-turn questions
+            elif turn_count == 2:
+                length_category = "2_turns"
+            elif turn_count == 3:
+                length_category = "3_turns"
+            elif turn_count >= 4:
+                length_category = "4+_turns"
+            else:
+                length_category = "unknown_turns"
+
+            # Add to length-specific results
+            length_analysis[length_category]["rr_scores"].append(
+                query_result.get("rr", 0)
+            )
+            for k in k_values:
+                hit_rate = query_result.get("hit_rates", {}).get(k, 0)
+                length_analysis[length_category]["hit_rates"][k].append(hit_rate)
+
+        # Calculate averages by turn length
+        final_length_analysis = {}
+        for length_cat, length_results in length_analysis.items():
+            final_length_analysis[length_cat] = {
+                "hit_rates": {
+                    k: sum(hits) / len(hits) if hits else 0
+                    for k, hits in length_results["hit_rates"].items()
+                },
+                "mrr": (
+                    sum(length_results["rr_scores"]) / len(length_results["rr_scores"])
+                    if length_results["rr_scores"]
+                    else 0
+                ),
+                "total_conversations": len(length_results["rr_scores"]),
+            }
+
+        return final_length_analysis
+
+    def print_multi_turn_results(self, results: Dict):
+        """Print multi-turn evaluation results with additional analysis"""
+
+        # Print base results first
+        self.single_turn_evaluator.print_evaluation_results(results)
+
+        # Print multi-turn specific analysis
+        print(f"\n🔍 MULTI-TURN SPECIFIC ANALYSIS")
+        print("=" * 60)
+
+        # Conversation type analysis
+        type_analysis = results.get("conversation_type_analysis", {})
+        if type_analysis:
+            print(f"\n📊 Performance by Conversation Type:")
+            print(f"{'Type':<20} {'MRR':<8} {'Hit@5':<8} {'Count':<8}")
+            print("-" * 50)
+
+            for conv_type, analysis in type_analysis.items():
+                mrr = analysis["mrr"]
+                hit_at_5 = analysis["hit_rates"].get(5, 0) * 100
+                count = analysis["total_conversations"]
+                print(f"{conv_type:<20} {mrr:<8.3f} {hit_at_5:<8.1f}% {count:<8}")
+
+        # Turn length analysis
+        length_analysis = results.get("turn_length_analysis", {})
+        if length_analysis:
+            print(f"\n📊 Performance by Conversation Length:")
+            print(f"{'Length':<12} {'MRR':<8} {'Hit@5':<8} {'Count':<8}")
+            print("-" * 40)
+
+            for length_cat, analysis in length_analysis.items():
+                mrr = analysis["mrr"]
+                hit_at_5 = analysis["hit_rates"].get(5, 0) * 100
+                count = analysis["total_conversations"]
+                print(f"{length_cat:<12} {mrr:<8.3f} {hit_at_5:<8.1f}% {count:<8}")
+
+        print(f"\n💡 Multi-Turn Insights:")
+
+        # Best performing conversation type
+        if type_analysis:
+            best_type = max(type_analysis.keys(), key=lambda k: type_analysis[k]["mrr"])
+            worst_type = min(
+                type_analysis.keys(), key=lambda k: type_analysis[k]["mrr"]
+            )
+            print(
+                f"   • Best conversation type: {best_type} (MRR: {type_analysis[best_type]['mrr']:.3f})"
+            )
+            print(
+                f"   • Worst conversation type: {worst_type} (MRR: {type_analysis[worst_type]['mrr']:.3f})"
+            )
+
+        # Turn length insights
+        if length_analysis:
+            best_length = max(
+                length_analysis.keys(), key=lambda k: length_analysis[k]["mrr"]
+            )
+            print(
+                f"   • Best performing length: {best_length} (MRR: {length_analysis[best_length]['mrr']:.3f})"
+            )
+
+
+def main():
+    """Main function for multi-turn conversation evaluation"""
+    parser = argparse.ArgumentParser(
+        description="ViettelPay Multi-Turn Conversation Retrieval Evaluation"
+    )
+    parser.add_argument(
+        "--mode",
+        choices=["create", "enhance", "evaluate", "full"],
+        default="full",
+        help="Mode: create conversations, enhance to queries, evaluate, or full pipeline",
+    )
+    parser.add_argument(
+        "--conversations-dataset",
+        default="evaluation_data/datasets/multi_turn_retrieval/viettelpay_multiturn_conversations.json",
+        help="Path to multi-turn conversations dataset",
+    )
+    parser.add_argument(
+        "--enhanced-dataset",
+        default="evaluation_data/datasets/multi_turn_retrieval/viettelpay_multiturn_enhanced.json",
+        help="Path to enhanced queries dataset",
+    )
+    parser.add_argument(
+        "--results-path",
+        default="evaluation_data/results/multi_turn_retrieval/viettelpay_multiturn_results.json",
+        help="Path to save evaluation results",
+    )
+    parser.add_argument(
+        "--conversations-per-chunk",
+        type=int,
+        default=3,
+        help="Number of conversations per chunk",
+    )
+    parser.add_argument(
+        "--k-values",
+        nargs="+",
+        type=int,
+        default=[1, 3, 5, 10],
+        help="K values for evaluation",
+    )
+    parser.add_argument(
+        "--knowledge-base-path",
+        default="./knowledge_base",
+        help="Path to knowledge base",
+    )
+
+    args = parser.parse_args()
+
+    # Configuration
+    GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
+
+    if not GEMINI_API_KEY:
+        print("❌ Please set GEMINI_API_KEY environment variable")
+        return
+
+    try:
+        # Initialize knowledge base
+        print("🔧 Initializing ViettelPay knowledge base...")
+        kb = ViettelKnowledgeBase()
+        if not kb.load_knowledge_base(args.knowledge_base_path):
+            print(
+                "❌ Failed to load knowledge base. Please run build_database_script.py first."
+            )
+            return
+
+        # Step 1: Create multi-turn conversations if requested
+        if args.mode in ["create", "full"]:
+            print(f"\n🎯 Creating multi-turn conversation dataset...")
+            creator = MultiTurnDatasetCreator(GEMINI_API_KEY, kb)
+
+            conversations_dataset = creator.create_multi_turn_dataset(
+                conversations_per_chunk=args.conversations_per_chunk,
+                save_path=args.conversations_dataset,
+            )
+
+        # Step 2: Enhance conversations to queries if requested
+        if args.mode in ["enhance", "full"]:
+            print(f"\n⚡ Converting conversations to enhanced queries...")
+
+            # Load conversations if not created in this run
+            if args.mode == "enhance":
+                if not os.path.exists(args.conversations_dataset):
+                    print(
+                        f"❌ Conversations dataset not found: {args.conversations_dataset}"
+                    )
+                    return
+
+                with open(args.conversations_dataset, "r", encoding="utf-8") as f:
+                    conversations_dataset = json.load(f)
+
+            # Enhance conversations
+            enhancer = ConversationEnhancer(GEMINI_API_KEY)
+            enhanced_dataset = enhancer.convert_dataset_to_single_turn_format(
+                conversations_dataset, args.enhanced_dataset
+            )
+
+        # Step 3: Evaluate if requested
+        if args.mode in ["evaluate", "full"]:
+            print(f"\n📊 Evaluating multi-turn conversation retrieval...")
+
+            # Load enhanced dataset if not created in this run
+            if args.mode == "evaluate":
+                if not os.path.exists(args.enhanced_dataset):
+                    print(f"❌ Enhanced dataset not found: {args.enhanced_dataset}")
+                    return
+
+                with open(args.enhanced_dataset, "r", encoding="utf-8") as f:
+                    enhanced_dataset = json.load(f)
+
+            # Run evaluation
+            evaluator = MultiTurnEvaluator(enhanced_dataset, kb)
+            results = evaluator.evaluate_multi_turn_performance(k_values=args.k_values)
+            evaluator.print_multi_turn_results(results)
+
+            # Save results
+            if args.results_path:
+                with open(args.results_path, "w", encoding="utf-8") as f:
+                    json.dump(results, f, ensure_ascii=False, indent=2)
+                print(f"\n💾 Results saved to: {args.results_path}")
+
+        print(f"\n✅ Multi-turn evaluation completed successfully!")
+        print(f"\n💡 Next steps:")
+        print(f"   1. Compare multi-turn vs single-turn performance")
+        print(f"   2. Analyze conversation types that work best")
+        print(f"   3. Optimize query enhancement for multi-turn scenarios")
+
+    except Exception as e:
+        print(f"❌ Error in main execution: {e}")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()

src/evaluation/prompts.py

@@ -0,0 +1,318 @@
+"""
+Prompts for ViettelPay Synthetic Evaluation Dataset Creation
+Simplified version for MRR and Hit Rate evaluation only
+"""
+
+# Question Generation Prompt (JSON format for better parsing)
+QUESTION_GENERATION_PROMPT = """Bạn là chuyên gia tạo câu hỏi đánh giá cho hệ thống ViettelPay Pro.
+ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+Dựa trên đoạn văn bản sau từ tài liệu hướng dẫn, hãy tạo ra {num_questions} câu hỏi đa dạng:
+
+<context>
+{content}
+</context>
+
+Tạo các loại câu hỏi:
+1. Câu hỏi trực tiếp về thông tin trong đoạn văn
+2. Câu hỏi về cách thực hiện hoặc quy trình  
+3. Câu hỏi về lỗi, vấn đề hoặc troubleshooting
+4. Câu hỏi về quy định, chính sách, phí
+
+Yêu cầu cho mỗi câu hỏi:
+- Tự nhiên như khách hàng ViettelPay thật sẽ hỏi
+- Có thể trả lời được từ đoạn văn bản đã cho
+- Ngắn gọn (5-20 từ)
+- Sử dụng tiếng Việt thông dụng
+- Đa dạng về loại câu hỏi và độ phức tạp
+
+QUAN TRỌNG: Trả về kết quả dưới dạng JSON với format chính xác như sau:
+{{
+  "questions": [
+    "Câu hỏi đầu tiên?",
+    "Câu hỏi thứ hai?",
+    "Câu hỏi thứ ba?"
+  ]
+}}
+
+CHỈ trả về JSON, không có text khác."""
+
+# Multi-Turn Conversation Generation Prompt (JSON format)
+MULTI_TURN_CONVERSATION_GENERATION_PROMPT = """Bạn là một chuyên gia trong việc tạo dữ liệu huấn luyện cho chatbot hỗ trợ khách hàng của ứng dụng ViettelPay Pro.
+ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+Nhiệm vụ của bạn là tạo ra **{num_conversations}** cuộc hội thoại đa lượt, chân thực và tự nhiên giữa người dùng (Đại lý/Điểm bán) và Trợ lý AI. Toàn bộ nội dung cuộc hội thoại phải dựa **hoàn toàn** vào thông tin được cung cấp trong tài liệu dưới đây.
+
+<context>
+{content}
+</context>
+
+Hãy tạo ra các cuộc hội thoại xoay quanh những kịch bản sau:
+
+1.  **Giải quyết vấn đề (`error_resolution`):** Người dùng gặp lỗi, giao dịch thất bại, hoặc một tính năng không hoạt động như mong đợi. Họ muốn tìm hiểu nguyên nhân và cách khắc phục.
+    * *Ví dụ luồng hội thoại:* Báo lỗi -> Hỏi về nguyên nhân sâu xa -> Hỏi cách để tránh lỗi này trong tương lai.
+
+2.  **Hướng dẫn thực hiện (`procedure_guide`):** Người dùng muốn biết cách thực hiện một tác vụ cụ thể. Cuộc hội thoại nên đi sâu vào các bước, điều kiện, hoặc các chi tiết liên quan.
+    * *Ví dụ luồng hội thoại:* Hỏi cách thực hiện một dịch vụ -> Hỏi về một bước cụ thể -> Hỏi về một trường hợp đặc biệt (ví dụ: "nếu làm cho nhà mạng khác thì sao?").
+
+3.  **Tra cứu thông tin (`policy_info`):** Người dùng có câu hỏi về chính sách, phí, hạn mức, hoặc các quy định của dịch vụ.
+    * *Ví dụ luồng hội thoại:* Hỏi về một quy định chung -> Hỏi về một trường hợp áp dụng cụ thể -> Hỏi về các ngoại lệ.
+
+**YÊU CẦU QUAN TRỌNG:**
+
+* **Dòng chảy tự nhiên:** Mỗi lượt hỏi của người dùng phải là một phản ứng logic, tự nhiên sau khi nhận được câu trả lời (tưởng tượng) từ AI. Hãy hình dung AI đã đưa ra câu trả lời hữu ích nhưng chưa đầy đủ, khiến người dùng phải hỏi thêm để làm rõ.
+* **Chân thực như người dùng thật:**
+    * Sử dụng ngôn ngữ đời thường, ngắn gọn, đi thẳng vào vấn đề.
+    * Có thể dùng các từ viết tắt phổ biến (vd: "sđt", "tk", "gd", "đk").
+    * Giọng điệu có thể thể hiện sự bối rối, cần hỗ trợ gấp hoặc tò mò.
+* **Bám sát tài liệu:** **Không** được tự ý sáng tạo thông tin, chính sách, hoặc tính năng không có trong phần `<context>`.
+* Tất cả các lượt câu hỏi, đặc biệt là câu hỏi cuối cùng, phải có thể trả lời được từ thông tin trong tài liệu `<context>`.
+* **Cấu trúc:** Mỗi cuộc hội thoại phải có từ 2 đến 3 lượt hỏi từ phía người dùng.
+* **Ngôn ngữ:** Tiếng Việt.
+
+Ví dụ cuộc hội thoại:
+```
+Lượt 1: "mã lỗi 606 là gì vậy?"
+Lượt 2: "làm sao để khắc phục lỗi này?"
+```
+
+QUAN TRỌNG: Trả về kết quả dưới dạng JSON với format chính xác như sau:
+{{
+  "conversations": [
+    {{
+      "type": "error_resolution",
+      "turns": [
+        {{"role": "user", "content": "mã lỗi 606 là gì vậy?"}},
+        {{"role": "user", "content": "làm sao để khắc phục lỗi này?"}}
+      ]
+    }},
+    {{
+      "type": "procedure_inquiry", 
+      "turns": [
+        {{"role": "user", "content": "nạp cước điện thoại như thế nào?"}},
+        {{"role": "user", "content": "có thể nạp cho số Viettel không?"}},
+        {{"role": "user", "content": "có các mệnh giá nào?"}}
+      ]
+    }}
+  ]
+}}
+
+CHỈ trả về JSON, không có text khác."""
+
+
+# Quality Check Prompt for Generated Questions
+QUESTION_QUALITY_CHECK_PROMPT = """Đánh giá chất lượng của câu hỏi được tạo ra cho hệ thống ViettelPay Pro. ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+
+Câu hỏi: {question}
+Đoạn văn gốc: {context}
+
+Tiêu chí đánh giá:
+1. Clarity (Rõ ràng): Câu hỏi có dễ hiểu không?
+2. Answerability (Có thể trả lời): Có thể trả lời từ đoạn văn không?
+3. Naturalness (Tự nhiên): Có giống cách khách hàng thật hỏi không?
+4. Relevance (Liên quan): Có phù hợp với nội dung ViettelPay không?
+
+Mỗi tiêu chí từ 1-5 điểm (5 là tốt nhất).
+
+QUAN TRỌNG: Trả về kết quả dưới dạng JSON với format chính xác như sau:
+{{
+  "clarity": 5,
+  "answerability": 4, 
+  "naturalness": 5,
+  "relevance": 5,
+  "overall_score": 4.75,
+  "keep_question": true,
+  "feedback": "Câu hỏi tốt, rõ ràng và tự nhiên"
+}}
+
+CHỈ trả về JSON, không có text khác."""
+
+# Context Quality Check Prompt
+CONTEXT_QUALITY_CHECK_PROMPT = """Đánh giá chất lượng của đoạn văn bản ViettelPay Pro để tạo câu hỏi. ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+
+Đoạn văn bản:
+{content}
+
+Tiêu chí đánh giá:
+1. Clarity (Rõ ràng): Thông tin có dễ hiểu không?
+2. Completeness (Đầy đủ): Có đủ thông tin để tạo câu hỏi không?
+3. Structure (Cấu trúc): Có tổ chức tốt không?
+4. Relevance (Liên quan): Có phù hợp với ViettelPay không?
+5. Information_density (Mật độ thông tin): Có đủ thông tin hữu ích không?
+
+Mỗi tiêu chí từ 1-5 điểm (5 là tốt nhất).
+
+QUAN TRỌNG: Trả về kết quả dưới dạng JSON với format chính xác như sau:
+{{
+  "clarity": 5,
+  "completeness": 4,
+  "structure": 4,
+  "relevance": 5,
+  "information_density": 4,
+  "overall_score": 4.4,
+  "use_context": true,
+  "feedback": "Đoạn văn tốt, có thể tạo câu hỏi chất lượng"
+}}
+
+CHỈ trả về JSON, không có text khác."""
+
+# Question Evolution/Variation Prompt
+QUESTION_EVOLUTION_PROMPT = """Tạo các biến thể của câu hỏi ViettelPay Pro để tăng tính đa dạng. ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+
+Câu hỏi gốc: {original_question}
+Ngữ cảnh: {context}
+
+Tạo 3 biến thể khác nhau:
+1. Phiên bản casual/thông tục (cách nói hàng ngày)
+2. Phiên bản formal/lịch sự (cách nói trang trọng)  
+3. Phiên bản cụ thể (thêm chi tiết, tình huống cụ thể)
+
+Yêu cầu:
+- Giữ nguyên ý nghĩa cốt lõi
+- Vẫn có thể trả lời từ cùng ngữ cảnh
+- Tự nhiên với người dùng Việt Nam
+- Đa dạng về cách diễn đạt
+
+QUAN TRỌNG: Trả về kết quả dưới dạng JSON với format chính xác như sau:
+{{
+  "original_question": "{original_question}",
+  "variations": [
+    "Phiên bản casual",
+    "Phiên bản formal", 
+    "Phiên bản cụ thể"
+  ]
+}}
+
+CHỈ trả về JSON, không có text khác."""
+
+# Dataset Statistics Prompt
+DATASET_STATS_PROMPT = """Phân tích thống kê dataset đánh giá ViettelPay Pro. ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+
+Dữ liệu:
+- Tổng số câu hỏi: {total_questions}
+- Tổng số documents: {total_documents}  
+- Câu hỏi theo loại: {question_types}
+
+Tạo báo cáo thống kê và đề xuất cải thiện.
+
+QUAN TRỌNG: Trả về kết quả dưới dạng JSON với format chính xác như sau:
+{{
+  "coverage_analysis": {{
+    "error_handling": "20%",
+    "procedures": "30%", 
+    "policies": "25%",
+    "faq": "25%"
+  }},
+  "quality_metrics": {{
+    "avg_questions_per_doc": 2.1,
+    "question_diversity": "high"
+  }},
+  "recommendations": [
+    "Tăng câu hỏi về error handling",
+    "Cân bằng độ khó của câu hỏi"
+  ]
+}}
+
+CHỈ trả về JSON, không có text khác."""
+
+# Error Analysis Prompt
+ERROR_ANALYSIS_PROMPT = """Phân tích lỗi trong quá trình đánh giá retrieval ViettelPay Pro. ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+
+Kết quả đánh giá:
+{evaluation_results}
+
+Xác định:
+1. Câu hỏi có hiệu suất thấp (Hit Rate < 0.3)
+2. Loại lỗi thường gặp
+3. Nguyên nhân gốc rễ
+4. Đề xuất cải thiện
+
+QUAN TRỌNG: Trả về kết quả dưới dạng JSON với format chính xác như sau:
+{{
+  "low_performance_queries": [
+    {{"query": "câu hỏi", "hit_rate": 0.2, "issue": "từ khóa không rõ ràng"}}
+  ],
+  "common_error_types": [
+    "Thiếu từ khóa chính",
+    "Ngữ cảnh không đủ",
+    "Chunking không tối ưu"
+  ],
+  "improvement_suggestions": [
+    "Cải thiện chunking strategy",
+    "Thêm synonyms cho từ khóa"
+  ]
+}}
+
+CHỈ trả về JSON, không có text khác."""
+
+# Intent Classification Prompt
+# Updated Intent Classification Conversation Generation Prompt with chunk mixing support
+# Improved Intent Classification Conversation Generation Prompt
+INTENT_CLASSIFICATION_CONVERSATION_GENERATION_PROMPT = """Bạn là chuyên gia tạo dữ liệu đánh giá cho hệ thống phân loại ý định (intent classification) của Trợ lý AI trên ứng dụng ViettelPay Pro.
+ViettelPay Pro là ứng dụng chuyên biệt dành cho các đại lý và điểm bán của Viettel, giúp họ thực hiện các giao dịch tài chính và viễn thông cho khách hàng một cách nhanh chóng, an toàn và đơn giản.
+
+Nhiệm vụ của bạn là tạo ra **{num_conversations}** cuộc hội thoại đa lượt thực tế. Mỗi tin nhắn của người dùng phải được gán một nhãn `intent` chính xác.
+`intent` là ý định của người dùng trong câu hỏi hiện tại và liên quan đến các lượt hỏi trước đó trong cuộc hội thoại.
+
+**1. Định nghĩa các loại ý định (Bắt buộc phải tuân theo):**
+
+* **`greeting`**: Chỉ là lời chào hỏi thuần túy, không có câu hỏi hoặc yêu cầu cụ thể nào khác. Nếu tin nhắn có cả lời chào VÀ câu hỏi thì phân loại theo các ý định khác, không phải greeting.
+    * *Ví dụ:* "chào em", "hello shop", "xin chào ạ"
+    * *Không phải greeting:* "xin chào, cho hỏi về lỗi 606" → đây là error_help
+* **`faq`**: Các câu hỏi đáp chung, tìm hiểu về dịch vụ, tính năng, v.v.
+    * *Ví dụ:* "App có bán thẻ game không?", "ViettelPay Pro nạp tiền được cho mạng nao?"
+* **`error_help`**: Báo cáo sự cố, hỏi về mã lỗi cụ thể.
+    * *Ví dụ:* "Giao dịch báo lỗi 606", "tại sao tôi không thanh toán được?", "lỗi này là gì?"
+* **`procedure_guide`**: Hỏi về các bước cụ thể để thực hiện một tác vụ.
+    * *Ví dụ:* "làm thế nào để hủy giao dịch?", "chỉ tôi cách lấy lại mã thẻ cào", "hướng dẫn nạp cước"
+* **`human_request`**: Yêu cầu được nói chuyện trực tiếp với nhân viên hỗ trợ.
+    * *Ví dụ:* "cho tôi gặp người thật", "nối máy cho tổng đài", "em k hiểu, cho gặp ai đó"
+* **`out_of_scope`**: Câu hỏi ngoài phạm vi ViettelPay (thời tiết, chính trị, v.v.), không liên quan gì đến các dịch vụ tài chính, viễn thông của Viettel.
+    * *Ví dụ:* "dự báo thời tiết hôm nay?", "giá xăng bao nhiêu?", "cách nấu phở"
+* **`unclear`**: Câu hỏi không rõ ràng, thiếu thông tin cụ thể, cần người dùng bổ sung thêm chi tiết để có thể hỗ trợ hiệu quả.
+    * *Ví dụ:* "lỗi", "giúp với", "gd", "???", "ko hiểu", "bị lỗi giờ sao đây", "không thực hiện được", "sao vậy", "tại sao thế"
+
+**2. Nguồn kiến thức (Context):**
+
+Sử dụng tài liệu dưới đây để lấy các mã lỗi (vd: 606, W02), tên dịch vụ (vd: Gạch nợ cước), và các tình huống thực tế để xây dựng cuộc hội thoại.
+
+<context>
+{content}
+</context>
+
+**3. Yêu cầu về kịch bản hội thoại:**
+
+* Mỗi cuộc hội thoại có t��� 2 đến 4 lượt hỏi từ người dùng. Tùy chỉnh sao cho phù hợp với tài liệu.
+* {generation_instruction}
+* Tạo các cuộc hội thoại đa dạng, không lặp lại.
+* **QUAN TRỌNG - Intent Mixing**: Khoảng 70% tin nhắn nên liên quan đến context, nhưng 30% tin nhắn nên là các intent tự nhiên khác như:
+  - `greeting` ở đầu cuộc hội thoại
+  - `unclear` khi người dùng hỏi không rõ ràng, trợ lý cần thêm thông tin từ người dùng
+  - `human_request` khi họ muốn hỗ trợ trực tiếp
+  - `out_of_scope` khi họ hỏi không liên quan đến ViettelPay Pro
+* Ngôn ngữ phải tự nhiên như người dùng thật, có thể dùng từ viết tắt, và đi thẳng vào vấn đề.
+* Tạo các tình huống thực tế như người dùng thật sự sẽ hỏi. Không cần phải kết thúc bằng cảm ơn hay tạm biệt.
+* Các câu hỏi nên dễ để phân loại ý định, không cần phải suy nghĩ quá lâu.
+
+**4. Ví dụ cuộc hội thoại thực tế:**
+{{
+  "conversations": [
+    {{
+      "turns": [
+        {{"user": "chào em", "intent": "greeting"}},
+        {{"user": "mã lỗi 606 là gì z?", "intent": "error_help"}},
+        {{"user": "em ko hiểu, gặp ai đó dc ko?", "intent": "human_request"}}
+      ]
+    }},
+    {{
+      "turns": [
+        {{"user": "nạp cước như nào?", "intent": "procedure_guide"}},
+        {{"user": "hôm nay trời đẹp nhỉ", "intent": "out_of_scope"}},
+        {{"user": "ờ quay lại, có phí ko?", "intent": "faq"}}
+      ]
+    }}
+  ]
+}}
+
+**5. Định dạng đầu ra (Output):**
+
+QUAN TRỌNG: Trả về kết quả dưới dạng JSON với format chính xác như ví dụ trên.
+CHỈ trả về JSON, không có text khác."""

src/evaluation/single_turn_retrieval.py

@@ -0,0 +1,844 @@
+"""
+Single Turn Synthetic Retrieval Evaluation Dataset Creator for ViettelPay RAG System
+Uses Google Gemini 2.0 Flash with JSON responses for better parsing
+Simplified version with only MRR and hit rate evaluation (no qrels generation)
+"""
+
+import json
+import os
+import sys
+import argparse
+import time
+from typing import Dict, List, Tuple, Optional, Union
+from pathlib import Path
+from collections import defaultdict
+import pandas as pd
+from tqdm import tqdm
+import re
+
+# Load environment variables from .env file
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Add the project root to Python path so we can import from src
+project_root = Path(__file__).parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+# Import prompts (only the ones we need)
+from src.evaluation.prompts import (
+    QUESTION_GENERATION_PROMPT,
+    QUESTION_QUALITY_CHECK_PROMPT,
+    CONTEXT_QUALITY_CHECK_PROMPT,
+    QUESTION_EVOLUTION_PROMPT,
+)
+
+# Import your existing knowledge base and LLM client
+from src.knowledge_base.viettel_knowledge_base import ViettelKnowledgeBase
+from src.llm.llm_client import LLMClientFactory, BaseLLMClient
+
+
+class SingleTurnDatasetCreator:
+    """Single turn synthetic evaluation dataset creator with JSON responses and all chunks processing"""
+
+    def __init__(
+        self, gemini_api_key: str, knowledge_base: ViettelKnowledgeBase = None
+    ):
+        """
+        Initialize with Gemini API key and optional knowledge base
+
+        Args:
+            gemini_api_key: Google AI API key for Gemini
+            knowledge_base: Pre-initialized ViettelKnowledgeBase instance
+        """
+        self.llm_client = LLMClientFactory.create_client(
+            "gemini", api_key=gemini_api_key, model="gemini-2.0-flash"
+        )
+        self.knowledge_base = knowledge_base
+        self.dataset = {
+            "queries": {},
+            "documents": {},
+            "metadata": {
+                "total_chunks_processed": 0,
+                "questions_generated": 0,
+                "creation_timestamp": time.time(),
+            },
+        }
+
+        print("✅ SingleTurnDatasetCreator initialized with Gemini 2.0 Flash")
+
+    def generate_json_response(
+        self, prompt: str, max_retries: int = 3
+    ) -> Optional[Dict]:
+        """
+        Generate response and parse as JSON with retries
+
+        Args:
+            prompt: Input prompt
+            max_retries: Maximum number of retry attempts
+
+        Returns:
+            Parsed JSON response or None if failed
+        """
+        for attempt in range(max_retries):
+            try:
+                response = self.llm_client.generate(prompt, temperature=0.1)
+
+                if response:
+                    # Clean response text
+                    response_text = response.strip()
+
+                    # Extract JSON from response (handle cases with extra text)
+                    json_match = re.search(r"\{.*\}", response_text, re.DOTALL)
+                    if json_match:
+                        json_text = json_match.group()
+                        return json.loads(json_text)
+                    else:
+                        # Try parsing the whole response
+                        return json.loads(response_text)
+
+            except json.JSONDecodeError as e:
+                print(f"⚠️ JSON parsing error (attempt {attempt + 1}): {e}")
+                if attempt == max_retries - 1:
+                    print(f"❌ Failed to parse JSON after {max_retries} attempts")
+                    print(
+                        f"Raw response: {response if 'response' in locals() else 'No response'}"
+                    )
+
+            except Exception as e:
+                print(f"⚠️ API error (attempt {attempt + 1}): {e}")
+                if attempt < max_retries - 1:
+                    time.sleep(2**attempt)  # Exponential backoff
+
+        return None
+
+    def get_all_chunks(self) -> List[Dict]:
+        """
+        Get ALL chunks directly from ChromaDB vectorstore (no sampling)
+
+        Returns:
+            List of all document chunks with content and metadata
+        """
+        print(f"📚 Retrieving ALL chunks directly from ChromaDB vectorstore...")
+
+        if not self.knowledge_base:
+            raise ValueError(
+                "Knowledge base not provided. Please initialize with a ViettelKnowledgeBase instance."
+            )
+
+        try:
+            # Access the ChromaDB vectorstore directly
+            if (
+                not hasattr(self.knowledge_base, "chroma_retriever")
+                or not self.knowledge_base.chroma_retriever
+            ):
+                raise ValueError("ChromaDB retriever not found in knowledge base")
+
+            # Get the vectorstore from the retriever
+            vectorstore = self.knowledge_base.chroma_retriever.vectorstore
+
+            # Get all documents directly from ChromaDB
+            print("   Accessing ChromaDB collection...")
+            all_docs = vectorstore.get(include=["documents", "metadatas"])
+
+            documents = all_docs["documents"]
+            metadatas = all_docs["metadatas"]
+
+            print(f"   Found {len(documents)} documents in ChromaDB")
+            print(f"   Sample document preview:")
+            for i, doc in enumerate(documents[:3]):
+                print(f"      Doc {i+1}: {doc[:100]}...")
+
+            # Convert to our expected format
+            all_chunks = []
+            seen_content_hashes = set()
+
+            for i, (content, metadata) in enumerate(zip(documents, metadatas)):
+                # Create content hash for deduplication (just in case)
+                content_hash = hash(content[:300])
+
+                if (
+                    content_hash not in seen_content_hashes
+                    and len(content.strip()) > 50
+                ):
+                    chunk_info = {
+                        "id": f"chunk_{len(all_chunks)}",
+                        "content": content,
+                        "metadata": metadata or {},
+                        "source": "chromadb_direct",
+                        "content_length": len(content),
+                        "original_index": i,
+                    }
+                    all_chunks.append(chunk_info)
+                    seen_content_hashes.add(content_hash)
+                else:
+                    if content_hash in seen_content_hashes:
+                        print(f"   ⚠️ Skipping duplicate content at index {i}")
+                    else:
+                        print(
+                            f"   ⚠️ Skipping short content at index {i} (length: {len(content.strip())})"
+                        )
+
+            print(f"✅ Retrieved {len(all_chunks)} unique chunks from ChromaDB")
+            print(
+                f"   Filtered out {len(documents) - len(all_chunks)} duplicates/short chunks"
+            )
+
+            # Sort by content length (longer chunks first, usually more informative)
+            all_chunks.sort(key=lambda x: x["content_length"], reverse=True)
+
+            # Display statistics
+            avg_length = sum(chunk["content_length"] for chunk in all_chunks) / len(
+                all_chunks
+            )
+            min_length = min(chunk["content_length"] for chunk in all_chunks)
+            max_length = max(chunk["content_length"] for chunk in all_chunks)
+
+            print(f"   📊 Chunk Statistics:")
+            print(f"      • Average length: {avg_length:.0f} characters")
+            print(f"      • Min length: {min_length} characters")
+            print(f"      • Max length: {max_length} characters")
+
+            return all_chunks
+
+        except Exception as e:
+            print(f"❌ Error accessing ChromaDB directly: {e}")
+            print(f"   Falling back to search-based method...")
+            return self._get_all_chunks_fallback()
+
+    def _get_all_chunks_fallback(self) -> List[Dict]:
+        """
+        Fallback method using search queries if direct ChromaDB access fails
+
+        Returns:
+            List of document chunks retrieved via search
+        """
+        print(f"🔄 Using fallback search-based chunk retrieval...")
+
+        # Use comprehensive search terms to capture most content
+        comprehensive_queries = [
+            "ViettelPay",
+            "nạp",
+            "cước",
+            "giao dịch",
+            "thanh toán",
+            "lỗi",
+            "hủy",
+            "thẻ",
+            "chuyển",
+            "tiền",
+            "quy định",
+            "phí",
+            "dịch vụ",
+            "tài khoản",
+            "ngân hàng",
+            "OTP",
+            "PIN",
+            "mã",
+            "số",
+            "điện thoại",
+            "internet",
+            "truyền hình",
+            "homephone",
+            "cố định",
+            "game",
+            "Viettel",
+            "Mobifone",
+            # Add some Vietnamese words that might not be captured above
+            "ứng dụng",
+            "khách hàng",
+            "hỗ trợ",
+            "kiểm tra",
+            "xác nhận",
+            "bảo mật",
+        ]
+
+        all_chunks = []
+        seen_content_hashes = set()
+
+        for query in comprehensive_queries:
+            try:
+                # Search with large k to get as many chunks as possible
+                docs = self.knowledge_base.search(query, top_k=50)
+
+                for doc in docs:
+                    # Create content hash for deduplication
+                    content_hash = hash(doc.page_content[:300])
+
+                    if (
+                        content_hash not in seen_content_hashes
+                        and len(doc.page_content.strip()) > 50
+                    ):
+                        chunk_info = {
+                            "id": f"chunk_{len(all_chunks)}",
+                            "content": doc.page_content,
+                            "metadata": doc.metadata,
+                            "source": f"search_{query}",
+                            "content_length": len(doc.page_content),
+                        }
+                        all_chunks.append(chunk_info)
+                        seen_content_hashes.add(content_hash)
+
+            except Exception as e:
+                print(f"⚠️ Error searching for '{query}': {e}")
+                continue
+
+        print(f"✅ Fallback method retrieved {len(all_chunks)} unique chunks")
+
+        # Sort by content length
+        all_chunks.sort(key=lambda x: x["content_length"], reverse=True)
+
+        return all_chunks
+
+    def generate_questions_for_chunk(
+        self, chunk: Dict, num_questions: int = 2
+    ) -> List[Dict]:
+        """
+        Generate questions for a single chunk using Gemini with JSON response
+
+        Args:
+            chunk: Chunk dictionary with content and metadata
+            num_questions: Number of questions to generate per chunk
+
+        Returns:
+            List of question dictionaries with metadata
+        """
+        content = chunk["content"]
+
+        prompt = QUESTION_GENERATION_PROMPT.format(
+            num_questions=num_questions, content=content
+        )
+
+        response_json = self.generate_json_response(prompt)
+
+        if response_json and "questions" in response_json:
+            questions = response_json["questions"]
+
+            # Create question objects with metadata
+            question_objects = []
+            for i, question_text in enumerate(questions):
+                if len(question_text.strip()) > 5:  # Filter very short questions
+                    question_obj = {
+                        "id": f"q_{chunk['id']}_{i}",
+                        "text": question_text.strip(),
+                        "source_chunk": chunk["id"],
+                        "chunk_metadata": chunk["metadata"],
+                        "generation_method": "gemini_json",
+                    }
+                    question_objects.append(question_obj)
+
+            return question_objects
+        else:
+            print(f"⚠️ No valid questions generated for chunk {chunk['id']}")
+            return []
+
+    def check_context_quality(self, chunk: Dict) -> bool:
+        """
+        Check if a chunk is suitable for question generation
+
+        Args:
+            chunk: Chunk dictionary
+
+        Returns:
+            True if chunk should be used, False otherwise
+        """
+        content = chunk["content"]
+
+        # Basic checks first
+        if len(content.strip()) < 100:
+            return False
+
+        # Use Gemini for quality assessment
+        prompt = CONTEXT_QUALITY_CHECK_PROMPT.format(content=content[:1000])
+
+        response_json = self.generate_json_response(prompt)
+
+        if response_json:
+            return response_json.get("use_context", True)
+        else:
+            # Fallback to basic heuristics
+            return len(content.strip()) > 100 and len(content.split()) > 20
+
+    def create_complete_dataset(
+        self,
+        questions_per_chunk: int = 2,
+        save_path: str = "evaluation_data/datasets/single_turn_retrieval/viettelpay_complete_eval_dataset.json",
+        quality_check: bool = True,
+    ) -> Dict:
+        """
+        Create complete synthetic evaluation dataset using ALL chunks
+
+        Args:
+            questions_per_chunk: Number of questions to generate per chunk
+            save_path: Path to save the dataset JSON file
+            quality_check: Whether to perform quality checks on chunks
+
+        Returns:
+            Complete dataset dictionary
+        """
+        print(f"\n🚀 Creating simplified synthetic evaluation dataset...")
+        print(f"   Target: Process ALL chunks from knowledge base")
+        print(f"   Questions per chunk: {questions_per_chunk}")
+        print(f"   Quality check: {quality_check}")
+        print(f"   Evaluation method: MRR and Hit Rates only (no qrels)")
+
+        # Step 1: Get all chunks
+        all_chunks = self.get_all_chunks()
+        total_chunks = len(all_chunks)
+
+        if total_chunks == 0:
+            raise ValueError("No chunks found in knowledge base!")
+
+        print(f"✅ Found {total_chunks} chunks to process")
+
+        # Step 2: Quality filtering (optional)
+        if quality_check:
+            print(f"\n🔍 Performing quality checks on chunks...")
+            quality_chunks = []
+
+            for chunk in tqdm(all_chunks, desc="Quality checking"):
+                if self.check_context_quality(chunk):
+                    quality_chunks.append(chunk)
+                time.sleep(0.1)  # Rate limiting
+
+            print(
+                f"✅ {len(quality_chunks)}/{total_chunks} chunks passed quality check"
+            )
+            chunks_to_process = quality_chunks
+        else:
+            chunks_to_process = all_chunks
+
+        # Step 3: Generate questions for all chunks
+        print(f"\n📝 Generating questions for {len(chunks_to_process)} chunks...")
+        all_questions = []
+
+        for chunk in tqdm(chunks_to_process, desc="Generating questions"):
+            questions = self.generate_questions_for_chunk(chunk, questions_per_chunk)
+            all_questions.extend(questions)
+            time.sleep(0.2)  # Rate limiting for Gemini API
+
+        print(
+            f"✅ Generated {len(all_questions)} questions from {len(chunks_to_process)} chunks"
+        )
+
+        # Step 4: Populate dataset structure
+        self.dataset["documents"] = {
+            chunk["id"]: chunk["content"] for chunk in chunks_to_process
+        }
+        self.dataset["queries"] = {q["id"]: q["text"] for q in all_questions}
+
+        # Add question metadata
+        question_metadata = {
+            q["id"]: {
+                "source_chunk": q["source_chunk"],
+                "chunk_metadata": q["chunk_metadata"],
+                "generation_method": q["generation_method"],
+            }
+            for q in all_questions
+        }
+
+        self.dataset["question_metadata"] = question_metadata
+
+        # Step 5: Update metadata
+        self.dataset["metadata"].update(
+            {
+                "total_chunks_processed": len(chunks_to_process),
+                "total_chunks_available": total_chunks,
+                "questions_generated": len(all_questions),
+                "questions_per_chunk": questions_per_chunk,
+                "quality_check_enabled": quality_check,
+                "evaluation_method": "mrr_hit_rates_only",
+                "completion_timestamp": time.time(),
+            }
+        )
+
+        # Step 6: Save dataset
+        os.makedirs(
+            os.path.dirname(save_path) if os.path.dirname(save_path) else ".",
+            exist_ok=True,
+        )
+
+        with open(save_path, "w", encoding="utf-8") as f:
+            json.dump(self.dataset, f, ensure_ascii=False, indent=2)
+
+        print(f"\n✅ COMPLETE dataset created successfully!")
+        print(f"   📁 Saved to: {save_path}")
+        print(f"   📊 Statistics:")
+        print(f"      • Chunks processed: {len(chunks_to_process)}/{total_chunks}")
+        print(f"      • Questions generated: {len(all_questions)}")
+        print(f"      • Evaluation method: MRR and Hit Rates only")
+        print(
+            f"      • Coverage: {len(chunks_to_process)/total_chunks*100:.1f}% of knowledge base"
+        )
+
+        return self.dataset
+
+    def load_dataset(self, dataset_path: str) -> Dict:
+        """Load dataset from JSON file with metadata"""
+        with open(dataset_path, "r", encoding="utf-8") as f:
+            self.dataset = json.load(f)
+
+        metadata = self.dataset.get("metadata", {})
+
+        print(f"📖 Loaded dataset from {dataset_path}")
+        print(f"   📊 Dataset Statistics:")
+        print(f"      • Queries: {len(self.dataset['queries'])}")
+        print(f"      • Documents: {len(self.dataset['documents'])}")
+        print(f"      • Created: {time.ctime(metadata.get('creation_timestamp', 0))}")
+
+        return self.dataset
+
+
+class SingleTurnRetrievalEvaluator:
+    """Simplified retrieval evaluator with only MRR and hit rates"""
+
+    def __init__(self, dataset: Dict, knowledge_base: ViettelKnowledgeBase):
+        """
+        Initialize evaluator with dataset and knowledge base
+
+        Args:
+            dataset: Evaluation dataset with queries and documents
+            knowledge_base: ViettelKnowledgeBase instance to evaluate
+        """
+        self.dataset = dataset
+        self.knowledge_base = knowledge_base
+        self.results = {}
+
+    def _match_retrieved_documents(self, retrieved_docs) -> List[str]:
+        """
+        Enhanced document matching with multiple strategies
+
+        Args:
+            retrieved_docs: Retrieved Document objects from knowledge base
+
+        Returns:
+            List of matched document IDs
+        """
+        matched_ids = []
+
+        for doc in retrieved_docs:
+            # Strategy 1: Try to find exact content match
+            doc_id = self._find_exact_content_match(doc.page_content)
+
+            if not doc_id:
+                # Strategy 2: Try fuzzy content matching
+                doc_id = self._find_fuzzy_content_match(doc.page_content)
+
+            if doc_id:
+                matched_ids.append(doc_id)
+
+        return matched_ids
+
+    def _find_exact_content_match(self, retrieved_content: str) -> Optional[str]:
+        """Find exact content match"""
+        for doc_id, doc_content in self.dataset["documents"].items():
+            if retrieved_content.strip() == doc_content.strip():
+                return doc_id
+        return None
+
+    def _find_fuzzy_content_match(
+        self, retrieved_content: str, min_overlap: int = 50
+    ) -> Optional[str]:
+        """Find fuzzy content match with word overlap"""
+        best_match_id = None
+        best_overlap = 0
+
+        retrieved_words = set(retrieved_content.lower().split())
+
+        for doc_id, doc_content in self.dataset["documents"].items():
+            doc_words = set(doc_content.lower().split())
+            overlap = len(retrieved_words & doc_words)
+
+            if overlap > best_overlap and overlap >= min_overlap:
+                best_overlap = overlap
+                best_match_id = doc_id
+
+        return best_match_id
+
+    def _safe_average(self, values: List[float]) -> float:
+        """Calculate average safely handling empty lists"""
+        return sum(values) / len(values) if values else 0.0
+
+    def evaluate(self, k_values: List[int] = [1, 3, 5, 10]) -> Dict:
+        """
+        Simplified evaluation with only MRR and hit rates
+
+        This method checks if the source document (where the question was generated from)
+        is retrieved among the top-k results.
+
+        Args:
+            k_values: List of k values to evaluate
+
+        Returns:
+            Dictionary with MRR and hit rate results
+        """
+        print(f"\n🔍 Running simplified evaluation (MRR and Hit Rates only)...")
+        print(f"   📊 K values: {k_values}")
+        print(f"   📚 Total queries: {len(self.dataset['queries'])}")
+
+        # Initialize results
+        hit_rates = {k: [] for k in k_values}
+        rr_scores = []  # Reciprocal Rank scores for MRR calculation
+        query_results = {}
+        failed_queries = []
+
+        # Process each query
+        for query_id, query_text in tqdm(
+            self.dataset["queries"].items(), desc="Evaluating queries"
+        ):
+            try:
+                # Get source document from metadata - handle both single-turn and multi-turn formats
+                source_chunk_id = None
+
+                # Try question_metadata first (single-turn format)
+                question_meta = self.dataset.get("question_metadata", {}).get(
+                    query_id, {}
+                )
+                if question_meta:
+                    source_chunk_id = question_meta.get("source_chunk")
+
+                # If not found, try conversation_metadata (multi-turn format)
+                if not source_chunk_id:
+                    conversation_meta = self.dataset.get(
+                        "conversation_metadata", {}
+                    ).get(query_id, {})
+                    if conversation_meta:
+                        source_chunk_id = conversation_meta.get("source_chunk")
+
+                if not source_chunk_id:
+                    print(f"⚠️ No source chunk info for query {query_id}")
+                    continue
+
+                # Get retrieval results
+                retrieved_docs = self.knowledge_base.search(
+                    query_text, top_k=max(k_values)
+                )
+                retrieved_doc_ids = self._match_retrieved_documents(retrieved_docs)
+
+                # Check if source document is in top-k for each k
+                query_results[query_id] = {
+                    "query": query_text,
+                    "source_chunk": source_chunk_id,
+                    "retrieved": retrieved_doc_ids,
+                    "hit_rates": {},
+                }
+
+                # Calculate Reciprocal Rank (MRR) - once per query
+                if source_chunk_id in retrieved_doc_ids:
+                    source_rank = (
+                        retrieved_doc_ids.index(source_chunk_id) + 1
+                    )  # 1-indexed rank
+                    rr_score = 1.0 / source_rank
+                else:
+                    rr_score = 0.0
+
+                query_results[query_id]["rr"] = rr_score
+                query_results[query_id]["source_rank"] = (
+                    source_rank if rr_score > 0 else None
+                )
+                rr_scores.append(rr_score)
+
+                for k in k_values:
+                    top_k_docs = retrieved_doc_ids[:k]
+                    hit = 1 if source_chunk_id in top_k_docs else 0
+                    hit_rates[k].append(hit)
+                    query_results[query_id]["hit_rates"][k] = hit
+
+            except Exception as e:
+                print(f"❌ Error evaluating query {query_id}: {e}")
+                failed_queries.append((query_id, str(e)))
+                continue
+
+        # Calculate average metrics
+        avg_hit_rates = {}
+        avg_rr = sum(rr_scores) / len(rr_scores) if rr_scores else 0.0
+
+        for k in k_values:
+            avg_hit_rates[k] = self._safe_average(hit_rates[k])
+
+        results = {
+            "hit_rates": avg_hit_rates,
+            "mrr": avg_rr,
+            "per_query_results": query_results,
+            "failed_queries": failed_queries,
+            "summary": {
+                "total_queries": len(self.dataset["queries"]),
+                "evaluated_queries": len(query_results),
+                "failed_queries": len(failed_queries),
+                "success_rate": len(query_results) / len(self.dataset["queries"]) * 100,
+                "k_values": k_values,
+                "evaluation_type": "mrr_hit_rates_only",
+                "evaluation_timestamp": time.time(),
+            },
+        }
+
+        return results
+
+    def print_evaluation_results(self, results: Dict):
+        """Print simplified evaluation results"""
+        print(f"\n�� SIMPLIFIED EVALUATION RESULTS (MRR + Hit Rates)")
+        print("=" * 60)
+
+        print(f"\n📈 Hit Rates (Source Document Found in Top-K):")
+        print(f"{'K':<5} {'Hit Rate':<12} {'Percentage':<12}")
+        print("-" * 30)
+
+        for k in sorted(results["hit_rates"].keys()):
+            hit_rate = results["hit_rates"][k]
+            percentage = hit_rate * 100
+            print(f"{k:<5} {hit_rate:<12.4f} {percentage:<12.1f}%")
+
+        # Display MRR separately since it's not k-dependent
+        mrr = results["mrr"]
+        print(f"\n📊 Mean Reciprocal Rank (MRR): {mrr:.4f}")
+        print(f"   • MRR measures the average reciprocal rank of the source document")
+        print(f"   • Higher is better (max = 1.0 if all sources are rank 1)")
+
+        print(f"\n📊 Hit Rate Summary:")
+        for k in sorted(results["hit_rates"].keys()):
+            hit_rate = results["hit_rates"][k]
+            percentage = hit_rate * 100
+            print(
+                f"   • Top-{k}: {percentage:.1f}% of questions find their source document"
+            )
+
+        # Summary stats
+        summary = results["summary"]
+        print(f"\n📋 Evaluation Summary:")
+        print(f"   • Total queries: {summary['total_queries']}")
+        print(f"   • Successfully evaluated: {summary['evaluated_queries']}")
+        print(f"   • Failed queries: {summary['failed_queries']}")
+        print(f"   • Success rate: {summary['success_rate']:.1f}%")
+        print(f"   • Evaluation type: {summary['evaluation_type']}")
+
+        # Simple interpretation
+        avg_hit_rate_5 = results["hit_rates"].get(5, 0)
+        mrr = results["mrr"]
+        print(f"\n🎯 Quick Interpretation:")
+        if avg_hit_rate_5 > 0.8:
+            print(
+                f"   ✅ Excellent: {avg_hit_rate_5*100:.1f}% hit rate@5, MRR = {mrr:.3f}"
+            )
+        elif avg_hit_rate_5 > 0.6:
+            print(f"   👍 Good: {avg_hit_rate_5*100:.1f}% hit rate@5, MRR = {mrr:.3f}")
+        elif avg_hit_rate_5 > 0.4:
+            print(f"   ⚠️ Fair: {avg_hit_rate_5*100:.1f}% hit rate@5, MRR = {mrr:.3f}")
+        else:
+            print(f"   ❌ Poor: {avg_hit_rate_5*100:.1f}% hit rate@5, MRR = {mrr:.3f}")
+
+
+def main():
+    """Main function with argument parsing for separate operations"""
+    parser = argparse.ArgumentParser(
+        description="ViettelPay Retrieval Evaluation Dataset Creator (Simplified)"
+    )
+    parser.add_argument(
+        "--mode",
+        choices=["create", "evaluate", "both"],
+        default="both",
+        help="Mode: create dataset, evaluate only, or both",
+    )
+    parser.add_argument(
+        "--dataset-path",
+        default="evaluation_data/datasets/single_turn_retrieval/viettelpay_complete_eval.json",
+        help="Path to dataset file",
+    )
+    parser.add_argument(
+        "--results-path",
+        default="evaluation_data/results/single_turn_retrieval/viettelpay_eval_results.json",
+        help="Path to save evaluation results",
+    )
+    parser.add_argument(
+        "--questions-per-chunk",
+        type=int,
+        default=3,
+        help="Number of questions per chunk",
+    )
+    parser.add_argument(
+        "--k-values",
+        nargs="+",
+        type=int,
+        default=[1, 3, 5, 10],
+        help="K values for evaluation",
+    )
+    parser.add_argument(
+        "--quality-check",
+        action="store_true",
+        help="Enable quality checking for chunks",
+    )
+    parser.add_argument(
+        "--knowledge-base-path",
+        default="./knowledge_base",
+        help="Path to knowledge base",
+    )
+
+    args = parser.parse_args()
+
+    # Configuration
+    GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
+
+    if not GEMINI_API_KEY:
+        print("❌ Please set GEMINI_API_KEY environment variable")
+        return
+
+    try:
+        # Initialize knowledge base
+        print("🔧 Initializing ViettelPay knowledge base...")
+        kb = ViettelKnowledgeBase()
+        if not kb.load_knowledge_base(args.knowledge_base_path):
+            print(
+                "❌ Failed to load knowledge base. Please run build_database_script.py first."
+            )
+            return
+
+        # Create dataset if requested
+        if args.mode in ["create", "both"]:
+            print(f"\n🎯 Creating synthetic evaluation dataset...")
+            creator = SingleTurnDatasetCreator(GEMINI_API_KEY, kb)
+
+            dataset = creator.create_complete_dataset(
+                questions_per_chunk=args.questions_per_chunk,
+                save_path=args.dataset_path,
+                quality_check=args.quality_check,
+            )
+
+        # Evaluate if requested
+        if args.mode in ["evaluate", "both"]:
+            print(f"\n⚡ Evaluating retrieval performance...")
+
+            # Load dataset if not created in this run
+            if args.mode == "evaluate":
+                if not os.path.exists(args.dataset_path):
+                    print(f"❌ Dataset file not found: {args.dataset_path}")
+                    return
+
+                creator = SingleTurnDatasetCreator(GEMINI_API_KEY, kb)
+                dataset = creator.load_dataset(args.dataset_path)
+
+            # Run evaluation
+            evaluator = SingleTurnRetrievalEvaluator(dataset, kb)
+            results = evaluator.evaluate(k_values=args.k_values)
+            evaluator.print_evaluation_results(results)
+
+            # Save results
+            if args.results_path:
+                with open(args.results_path, "w", encoding="utf-8") as f:
+                    json.dump(results, f, ensure_ascii=False, indent=2)
+                print(f"\n💾 Results saved to: {args.results_path}")
+
+        print(f"\n✅ Operation completed successfully!")
+        print(f"\n💡 Next steps:")
+        print(f"   1. Review the MRR and hit rate results")
+        print(f"   2. Identify queries with low performance")
+        print(f"   3. Optimize your retrieval system")
+        print(f"   4. Re-run evaluation to measure progress")
+
+    except Exception as e:
+        print(f"❌ Error in main execution: {e}")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()

src/knowledge_base/viettel_knowledge_base.py

@@ -0,0 +1,521 @@
+"""
+ViettelPay Knowledge Base with Contextual Retrieval
+
+This updated version:
+- Uses ContextualWordProcessor for all document processing
+- Integrates OpenAI for contextual enhancement
+- Processes all doc/docx files from a parent folder
+- Removes CSV processor dependency
+"""
+
+import os
+import pickle
+
+# import torch
+from typing import List, Optional
+from pathlib import Path
+from openai import OpenAI
+
+from langchain.schema import Document
+from langchain.retrievers import EnsembleRetriever
+from langchain_community.retrievers import BM25Retriever
+from langchain_core.runnables import ConfigurableField
+from langchain_cohere.rerank import CohereRerank
+
+# Use newest import paths for langchain
+try:
+    from langchain_chroma import Chroma
+except ImportError:
+    from langchain_community.vectorstores import Chroma
+
+# Use the new HuggingFaceEmbeddings from langchain-huggingface
+try:
+    from langchain_huggingface import HuggingFaceEmbeddings
+except ImportError:
+    from langchain_community.embeddings import HuggingFaceEmbeddings
+
+from src.processor.contextual_word_processor import ContextualWordProcessor
+from src.processor.text_utils import VietnameseTextProcessor
+
+# Import configuration utility
+from src.utils.config import get_cohere_api_key, get_openai_api_key, get_embedding_model
+
+
+class ViettelKnowledgeBase:
+    """ViettelPay knowledge base with contextual retrieval enhancement"""
+
+    def __init__(self, embedding_model: str = None):
+        """
+        Initialize the knowledge base
+
+        Args:
+            embedding_model: Vietnamese embedding model to use
+        """
+        embedding_model = embedding_model or get_embedding_model()
+
+        # Initialize Vietnamese text processor
+        self.text_processor = VietnameseTextProcessor()
+
+        # self.device = "cuda" if torch.cuda.is_available() else "cpu"
+        self.device = "cpu"
+        print(f"[INFO] Using device: {self.device}")
+
+        # Initialize embeddings with GPU support and trust_remote_code
+        model_kwargs = {"device": self.device, "trust_remote_code": True}
+
+        self.embeddings = HuggingFaceEmbeddings(
+            model_name=embedding_model, model_kwargs=model_kwargs
+        )
+
+        # Initialize retrievers as None
+        self.chroma_retriever = None
+        self.bm25_retriever = None
+        self.ensemble_retriever = None
+
+        self.reranker = CohereRerank(
+            model="rerank-v3.5",
+            cohere_api_key=get_cohere_api_key(),
+        )
+
+    def build_knowledge_base(
+        self,
+        documents_folder: str,
+        persist_dir: str = "./knowledge_base",
+        reset: bool = True,
+        openai_api_key: Optional[str] = None,
+    ) -> None:
+        """
+        Build knowledge base from all Word documents in a folder
+
+        Args:
+            documents_folder: Path to folder containing doc/docx files
+            persist_dir: Directory to persist the knowledge base
+            reset: Whether to reset existing knowledge base
+            openai_api_key: OpenAI API key for contextual enhancement (optional)
+
+        Returns:
+            None. Use the search() method to perform searches.
+        """
+
+        print(
+            "[INFO] Building ViettelPay knowledge base with contextual enhancement..."
+        )
+
+        # Initialize OpenAI client for contextual enhancement if API key provided
+        openai_client = None
+        if openai_api_key:
+            openai_client = OpenAI(api_key=openai_api_key)
+            print(f"[INFO] OpenAI client initialized for contextual enhancement")
+        elif get_openai_api_key():
+            api_key = get_openai_api_key()
+            openai_client = OpenAI(api_key=api_key)
+            print(f"[INFO] OpenAI client initialized from configuration")
+        else:
+            print(
+                f"[WARNING] No OpenAI API key provided. Contextual enhancement disabled."
+            )
+
+        # Initialize the contextual word processor with OpenAI client
+        word_processor = ContextualWordProcessor(llm_client=openai_client)
+
+        # Find all Word documents in the folder
+        word_files = self._find_word_documents(documents_folder)
+
+        if not word_files:
+            raise ValueError(f"No Word documents found in {documents_folder}")
+
+        print(f"[INFO] Found {len(word_files)} Word documents to process")
+
+        # Process all documents
+        all_documents = self._process_all_word_files(word_files, word_processor)
+        print(f"[INFO] Total documents processed: {len(all_documents)}")
+
+        # Create directories
+        os.makedirs(persist_dir, exist_ok=True)
+        chroma_dir = os.path.join(persist_dir, "chroma")
+        bm25_path = os.path.join(persist_dir, "bm25_retriever.pkl")
+
+        # Build ChromaDB retriever (uses contextualized content)
+        print("[INFO] Building ChromaDB retriever with contextualized content...")
+        self.chroma_retriever = self._build_chroma_retriever(
+            all_documents, chroma_dir, reset
+        )
+
+        # Build BM25 retriever (uses contextualized content with Vietnamese tokenization)
+        print("[INFO] Building BM25 retriever with Vietnamese tokenization...")
+        self.bm25_retriever = self._build_bm25_retriever(
+            all_documents, bm25_path, reset
+        )
+
+        # Create ensemble retriever with configurable top-k
+        print("[INFO] Creating ensemble retriever...")
+        self.ensemble_retriever = self._build_retriever(
+            self.bm25_retriever, self.chroma_retriever
+        )
+
+        print("[SUCCESS] Contextual knowledge base built successfully!")
+        print("[INFO] Use kb.search(query, top_k) to perform searches.")
+
+    def load_knowledge_base(self, persist_dir: str = "./knowledge_base") -> bool:
+        """
+        Load existing knowledge base from disk and rebuild BM25 from ChromaDB documents
+
+        Args:
+            persist_dir: Directory where the knowledge base is stored
+
+        Returns:
+            bool: True if loaded successfully, False otherwise
+        """
+
+        print("[INFO] Loading knowledge base from disk...")
+
+        chroma_dir = os.path.join(persist_dir, "chroma")
+
+        try:
+            # Load ChromaDB
+            if os.path.exists(chroma_dir):
+                vectorstore = Chroma(
+                    persist_directory=chroma_dir, embedding_function=self.embeddings
+                )
+
+                self.chroma_retriever = vectorstore.as_retriever(search_kwargs={"k": 5})
+                print("[SUCCESS] ChromaDB loaded")
+            else:
+                print("[ERROR] ChromaDB not found")
+                return False
+
+            # Extract all documents from ChromaDB to rebuild BM25
+            print("[INFO] Extracting documents from ChromaDB to rebuild BM25...")
+            try:
+                # Get all documents and metadata from ChromaDB
+                all_docs = vectorstore.get(include=["documents", "metadatas"])
+
+                documents = all_docs["documents"]
+                metadatas = all_docs["metadatas"]
+
+                # Reconstruct Document objects
+                doc_objects = []
+                for i, (doc_content, metadata) in enumerate(zip(documents, metadatas)):
+                    # Handle case where metadata might be None
+                    if metadata is None:
+                        metadata = {}
+
+                    doc_obj = Document(page_content=doc_content, metadata=metadata)
+                    doc_objects.append(doc_obj)
+
+                print(f"[INFO] Extracted {len(doc_objects)} documents from ChromaDB")
+
+                # Rebuild BM25 retriever using existing method
+                self.bm25_retriever = self._build_bm25_retriever(
+                    documents=doc_objects,
+                    bm25_path=None,  # Not used anymore
+                    reset=False,  # Not relevant for rebuilding
+                )
+
+            except Exception as e:
+                print(f"[ERROR] Error rebuilding BM25 from ChromaDB: {e}")
+                return False
+
+            # Create ensemble retriever with configurable top-k
+            self.ensemble_retriever = self._build_retriever(
+                self.bm25_retriever, self.chroma_retriever
+            )
+
+            print("[SUCCESS] Knowledge base loaded successfully!")
+            print("[INFO] Use kb.search(query, top_k) to perform searches.")
+            return True
+
+        except Exception as e:
+            print(f"[ERROR] Error loading knowledge base: {e}")
+            return False
+
+    def search(self, query: str, top_k: int = 10) -> List[Document]:
+        """
+        Main search method using ensemble retriever with configurable top-k
+
+        Args:
+            query: Search query
+            top_k: Number of documents to return from each retriever (default: 5)
+
+        Returns:
+            List of retrieved documents
+        """
+        if not self.ensemble_retriever:
+            raise ValueError(
+                "Knowledge base not loaded. Call build_knowledge_base() or load_knowledge_base() first."
+            )
+
+        # Build config based on top_k parameter
+        config = {
+            "configurable": {
+                "bm25_k": top_k * 5,
+                "chroma_search_kwargs": {"k": top_k * 5},
+            }
+        }
+
+        results = self.ensemble_retriever.invoke(query, config=config)
+        reranked_results = self.reranker.rerank(results, query, top_n=top_k)
+
+        final_results = []
+        for rerank_item in reranked_results:
+            # Get the original document using the index
+            original_doc = results[rerank_item["index"]]
+
+            # Create a new document with the relevance score added to metadata
+            reranked_doc = Document(
+                page_content=original_doc.page_content,
+                metadata={
+                    **original_doc.metadata,
+                    "relevance_score": rerank_item["relevance_score"],
+                },
+            )
+            final_results.append(reranked_doc)
+
+        return final_results
+
+    def get_stats(self) -> dict:
+        """Get statistics about the knowledge base"""
+        stats = {}
+
+        if self.chroma_retriever:
+            try:
+                vectorstore = self.chroma_retriever.vectorstore
+                collection = vectorstore._collection
+                stats["chroma_documents"] = collection.count()
+            except:
+                stats["chroma_documents"] = "Unknown"
+
+        if self.bm25_retriever:
+            try:
+                stats["bm25_documents"] = len(self.bm25_retriever.docs)
+            except:
+                stats["bm25_documents"] = "Unknown"
+
+        stats["ensemble_available"] = self.ensemble_retriever is not None
+        stats["device"] = self.device
+        stats["vietnamese_tokenizer"] = "Vietnamese BM25 tokenizer (underthesea)"
+
+        return stats
+
+    def _find_word_documents(self, folder_path: str) -> List[str]:
+        """
+        Find all Word documents (.doc, .docx) in the given folder
+
+        Args:
+            folder_path: Path to the folder to search
+
+        Returns:
+            List of full paths to Word documents
+        """
+        word_files = []
+        folder = Path(folder_path)
+
+        if not folder.exists():
+            raise FileNotFoundError(f"Folder not found: {folder_path}")
+
+        # Search for Word documents
+        for pattern in ["*.doc", "*.docx"]:
+            word_files.extend(folder.glob(pattern))
+
+        # Convert to string paths and sort for consistent processing order
+        word_files = [str(f) for f in word_files]
+        word_files.sort()
+
+        print(f"[INFO] Found Word documents: {[Path(f).name for f in word_files]}")
+        return word_files
+
+    def _process_all_word_files(
+        self, word_files: List[str], word_processor: ContextualWordProcessor
+    ) -> List[Document]:
+        """Process all Word files into unified chunks with contextual enhancement"""
+        all_documents = []
+
+        for file_path in word_files:
+            try:
+                print(f"[INFO] Processing: {Path(file_path).name}")
+                chunks = word_processor.process_word_document(file_path)
+                all_documents.extend(chunks)
+
+                # Print processing stats for this file
+                stats = word_processor.get_document_stats(chunks)
+                print(
+                    f"[SUCCESS] Processed {Path(file_path).name}: {len(chunks)} chunks"
+                )
+                print(f"  - Contextualized: {stats.get('contextualized_docs', 0)}")
+                print(
+                    f"  - Non-contextualized: {stats.get('non_contextualized_docs', 0)}"
+                )
+
+            except Exception as e:
+                print(f"[ERROR] Error processing {Path(file_path).name}: {e}")
+
+        return all_documents
+
+    def _build_retriever(self, bm25_retriever, chroma_retriever):
+        """
+        Build ensemble retriever with configurable top-k parameters
+
+        Args:
+            bm25_retriever: BM25 retriever with configurable fields
+            chroma_retriever: Chroma retriever with configurable fields
+
+        Returns:
+            EnsembleRetriever with configurable retrievers
+        """
+        return EnsembleRetriever(
+            retrievers=[bm25_retriever, chroma_retriever],
+            weights=[0.2, 0.8],  # Slightly favor semantic search
+        )
+
+    def _build_chroma_retriever(
+        self, documents: List[Document], chroma_dir: str, reset: bool
+    ):
+        """Build ChromaDB retriever with configurable search parameters"""
+
+        if reset and os.path.exists(chroma_dir):
+            import shutil
+
+            shutil.rmtree(chroma_dir)
+            print("[INFO] Removed existing ChromaDB for rebuild")
+
+        # Create Chroma vectorstore (uses contextualized content)
+        vectorstore = Chroma.from_documents(
+            documents=documents, embedding=self.embeddings, persist_directory=chroma_dir
+        )
+
+        # Create retriever with configurable search_kwargs
+        retriever = vectorstore.as_retriever(
+            search_kwargs={"k": 5}  # default value
+        ).configurable_fields(
+            search_kwargs=ConfigurableField(
+                id="chroma_search_kwargs",
+                name="Chroma Search Kwargs",
+                description="Search kwargs for Chroma DB retriever",
+            )
+        )
+
+        print(
+            f"[SUCCESS] ChromaDB created with {len(documents)} contextualized documents"
+        )
+        return retriever
+
+    def _build_bm25_retriever(
+        self, documents: List[Document], bm25_path: str, reset: bool
+    ):
+        """Build BM25 retriever with Vietnamese tokenization and configurable k parameter"""
+
+        # Note: We no longer save BM25 to pickle file to avoid Streamlit Cloud compatibility issues
+        # BM25 will be rebuilt from ChromaDB documents when loading the knowledge base
+
+        # Create BM25 retriever with Vietnamese tokenizer as preprocess_func
+        print("[INFO] Using Vietnamese tokenizer for BM25 on contextualized content...")
+        retriever = BM25Retriever.from_documents(
+            documents=documents,
+            preprocess_func=self.text_processor.bm25_tokenizer,
+            k=5,  # default value
+        ).configurable_fields(
+            k=ConfigurableField(
+                id="bm25_k",
+                name="BM25 Top K",
+                description="Number of documents to return from BM25",
+            )
+        )
+
+        print(
+            f"[SUCCESS] BM25 retriever created with {len(documents)} contextualized documents"
+        )
+        return retriever
+
+
+def test_contextual_kb(kb: ViettelKnowledgeBase, test_queries: List[str]):
+    """Test function for the contextual knowledge base"""
+
+    print("\n[INFO] Testing Contextual Knowledge Base")
+    print("=" * 60)
+
+    for i, query in enumerate(test_queries, 1):
+        print(f"\n#{i} Query: '{query}'")
+        print("-" * 40)
+
+        try:
+            # Test ensemble search with configurable top-k
+            results = kb.search(query, top_k=3)
+
+            if results:
+                for j, doc in enumerate(results, 1):
+                    content_preview = doc.page_content[:150].replace("\n", " ")
+                    doc_type = doc.metadata.get("doc_type", "unknown")
+                    has_context = doc.metadata.get("has_context", False)
+                    context_indicator = (
+                        " [CONTEXTUAL]" if has_context else " [ORIGINAL]"
+                    )
+                    print(
+                        f"  {j}. [{doc_type}]{context_indicator} {content_preview}..."
+                    )
+            else:
+                print("  No results found")
+
+        except Exception as e:
+            print(f"  [ERROR] Error: {e}")
+
+
+# Example usage
+if __name__ == "__main__":
+    # Initialize knowledge base
+    kb = ViettelKnowledgeBase(
+        embedding_model="dangvantuan/vietnamese-document-embedding"
+    )
+
+    # Build knowledge base from a folder of Word documents
+    documents_folder = "./viettelpay_docs"  # Folder containing .doc/.docx files
+
+    try:
+        # Build knowledge base (pass OpenAI API key here for contextual enhancement)
+        kb.build_knowledge_base(
+            documents_folder,
+            "./contextual_kb",
+            reset=True,
+            openai_api_key="your-openai-api-key-here",  # or None to use env variable
+        )
+
+        # Alternative: Load existing knowledge base
+        # success = kb.load_knowledge_base("./contextual_kb")
+        # if not success:
+        #     print("[ERROR] Failed to load knowledge base")
+
+        # Test queries
+        test_queries = [
+            "lỗi 606",
+            "không nạp được tiền",
+            "hướng dẫn nạp cước",
+            "quy định hủy giao dịch",
+            "mệnh giá thẻ cào",
+        ]
+
+        # Test the knowledge base
+        test_contextual_kb(kb, test_queries)
+
+        # Example of runtime configuration for different top-k values
+        print(f"\n[INFO] Example of runtime configuration:")
+        print("=" * 50)
+
+        # Search with different top-k values
+        sample_query = "lỗi 606"
+
+        # Search with top_k=3
+        results1 = kb.search(sample_query, top_k=3)
+        print(f"Search with top_k=3: {len(results1)} total results")
+
+        # Search with top_k=8
+        results2 = kb.search(sample_query, top_k=8)
+        print(f"Search with top_k=8: {len(results2)} total results")
+
+        # Show stats
+        print(f"\n[INFO] Knowledge Base Stats: {kb.get_stats()}")
+
+    except Exception as e:
+        print(f"[ERROR] Error building knowledge base: {e}")
+        print("[INFO] Make sure you have:")
+        print("  1. Valid OpenAI API key")
+        print("  2. Word documents in the specified folder")
+        print("  3. Required dependencies installed (openai, markitdown, etc.)")

src/llm/llm_client.py

@@ -0,0 +1,181 @@
+"""
+LLM Client Abstraction Layer
+Supports multiple LLM providers without hardcoding
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+import os
+
+# Import configuration utility
+from src.utils.config import get_gemini_api_key, get_openai_api_key
+
+
+class BaseLLMClient(ABC):
+    """Abstract base class for LLM clients"""
+
+    def __init__(self, **kwargs):
+        pass
+
+    @abstractmethod
+    def generate(self, prompt: str, **kwargs) -> str:
+        """Generate response from prompt"""
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if LLM service is available"""
+        pass
+
+
+class GeminiClient(BaseLLMClient):
+    """Google Gemini client implementation"""
+
+    def __init__(self, api_key: Optional[str] = None, model: str = "gemini-2.0-flash"):
+        self.api_key = api_key or get_gemini_api_key()
+        self.model = model
+
+        if not self.api_key:
+            raise ValueError("Gemini API key not provided")
+
+        try:
+            import google.generativeai as genai
+
+            genai.configure(api_key=self.api_key)
+            self.client = genai.GenerativeModel(self.model)
+            print(f"✅ Gemini client initialized with model: {self.model}")
+        except ImportError:
+            raise ImportError("google-generativeai package not installed")
+
+    def generate(self, prompt: str, **kwargs) -> str:
+        """Generate response using Gemini"""
+        try:
+            # Set default temperature to 0.1 for consistency
+            generation_config = {
+                "temperature": kwargs.get("temperature", 0.1),
+                "top_p": kwargs.get("top_p", 0.8),
+                "top_k": kwargs.get("top_k", 40),
+                "max_output_tokens": kwargs.get("max_output_tokens", 2048),
+            }
+
+            response = self.client.generate_content(
+                prompt, generation_config=generation_config
+            )
+            return response.text
+        except Exception as e:
+            print(f"❌ Gemini generation error: {e}")
+            raise
+
+    def is_available(self) -> bool:
+        """Check Gemini availability"""
+        try:
+            test_response = self.client.generate_content("Hello")
+            return bool(test_response.text)
+        except:
+            return False
+
+
+class OpenAIClient(BaseLLMClient):
+    """OpenAI client implementation"""
+
+    def __init__(self, api_key: Optional[str] = None, model: str = "gpt-4"):
+        self.api_key = api_key or get_openai_api_key()
+        self.model = model
+
+        if not self.api_key:
+            raise ValueError("OpenAI API key not provided")
+
+        try:
+            import openai
+
+            self.client = openai.OpenAI(api_key=self.api_key)
+            print(f"✅ OpenAI client initialized with model: {self.model}")
+        except ImportError:
+            raise ImportError("openai package not installed")
+
+    def generate(self, prompt: str, **kwargs) -> str:
+        """Generate response using OpenAI"""
+        try:
+            # Set default temperature to 0.1 for consistency
+            openai_kwargs = {
+                "temperature": kwargs.get("temperature", 0.1),
+                "top_p": kwargs.get("top_p", 1.0),
+                "max_tokens": kwargs.get("max_tokens", 2048),
+            }
+            # Remove any Gemini-specific parameters
+            openai_kwargs.update(
+                {
+                    k: v
+                    for k, v in kwargs.items()
+                    if k
+                    in [
+                        "temperature",
+                        "top_p",
+                        "max_tokens",
+                        "frequency_penalty",
+                        "presence_penalty",
+                    ]
+                }
+            )
+
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[{"role": "user", "content": prompt}],
+                **openai_kwargs,
+            )
+            return response.choices[0].message.content
+        except Exception as e:
+            print(f"❌ OpenAI generation error: {e}")
+            raise
+
+    def is_available(self) -> bool:
+        """Check OpenAI availability"""
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[{"role": "user", "content": "Hello"}],
+                max_tokens=5,
+            )
+            return bool(response.choices[0].message.content)
+        except:
+            return False
+
+
+class LLMClientFactory:
+    """Factory for creating LLM clients"""
+
+    SUPPORTED_PROVIDERS = {
+        "gemini": GeminiClient,
+        "openai": OpenAIClient,
+    }
+
+    @classmethod
+    def create_client(self, provider: str = "gemini", **kwargs) -> BaseLLMClient:
+        """Create LLM client by provider name"""
+
+        if provider not in self.SUPPORTED_PROVIDERS:
+            raise ValueError(
+                f"Unsupported provider: {provider}. Supported: {list(self.SUPPORTED_PROVIDERS.keys())}"
+            )
+
+        client_class = self.SUPPORTED_PROVIDERS[provider]
+        return client_class(**kwargs)
+
+    @classmethod
+    def get_available_providers(cls) -> list:
+        """Get list of available providers"""
+        return list(cls.SUPPORTED_PROVIDERS.keys())
+
+
+# Usage example
+if __name__ == "__main__":
+    # Test Gemini client
+    try:
+        client = LLMClientFactory.create_client("gemini")
+        if client.is_available():
+            response = client.generate("Xin chào, bạn có khỏe không?")
+            print(f"Response: {response}")
+        else:
+            print("Gemini not available")
+    except Exception as e:
+        print(f"Error: {e}")