Polish Nura chatbot experience

DEPLOYMENT.md

@@ -63,7 +63,7 @@ Recommended values:
 
 ```text
 LANGUAGE_MODEL_FILENAME=saved_lang_model.pkl
-QDRANT_COLLECTION=mental_health_rag
+QDRANT_COLLECTION=mental_health_rag_v2
 EMBEDDING_MODEL_NAME=intfloat/multilingual-e5-base
 EMBEDDING_BATCH_SIZE=2
 TORCH_NUM_THREADS=1

README.md

@@ -1,6 +1,12 @@
-# Mental Health Support Chatbot
+---
+title: Mental Health Chatbot
+sdk: docker
+app_port: 7860
+---
 
-An end-to-end mental-health support chatbot built with a modular NLP and RAG architecture. The system detects the user's language, emotion, and intent, applies safety routing, retrieves relevant mental-health context from a Qdrant vector database, and generates a supportive response through Groq.
+# Nura: Mental Health Support Chatbot
+
+Nura is your gentle mental wellness companion: an end-to-end mental-health support chatbot built with a modular NLP and RAG architecture. The system detects the user's language, emotion, and intent, applies safety routing, retrieves relevant mental-health context from a Qdrant vector database, and generates a supportive response through Groq.
 
 The project is designed to be explainable, testable, and suitable for a professional portfolio: each module can run independently, produces reports, and is integrated into a FastAPI chatbot interface.
 
@@ -11,8 +17,7 @@ User message
   -> Language detection
   -> Emotion classification
   -> Safety guardrail
-  -> Conversation memory
-  -> Intent classification
+  -> Context-aware intent classification
   -> RAG retrieval when needed
   -> LLM response generation
   -> Same-language supportive answer
@@ -22,13 +27,14 @@ Key features:
 
 - Multilingual language detection with confidence scores.
 - Transformer-based emotion classification with word-level explainability.
-- LLM-based intent routing using strict JSON outputs.
+- Context-aware LLM intent routing with five-class score distributions.
 - Crisis-aware guardrail that bypasses normal RAG when urgent risk is detected.
 - RAG retrieval over two mental-health knowledge sources.
 - Qdrant Cloud vector database with source filtering.
 - E5 multilingual embeddings for cross-lingual retrieval.
-- FastAPI backend with production and developer UIs.
-- Short-term conversation memory for recent user context.
+- FastAPI backend with a branded Nura production UI, light/dark mode, local saved chats, and a developer testing UI.
+- Context-aware follow-up routing using recent browser-session history.
+- Final LLM review of language, emotion, and intent predictions.
 - Clean reports for every major module.
 
 ## Modules
@@ -88,14 +94,14 @@ Run:
 
 Knowledge sources:
 
-- `cci`: Centre for Clinical Interventions information sheets, cleaned from PDFs and chunked into overlapping text passages.
+- `cci`: Centre for Clinical Interventions information sheets, cleaned from PDFs and grouped into structure-aware chunks of at most 400 words.
 - `amod`: cleaned counseling Q&A pairs from `Amod/mental_health_counseling_conversations`.
 
 Retrieval stack:
 
 - Embedding model: `intfloat/multilingual-e5-base`
 - Vector database: Qdrant Cloud
-- Collection: `mental_health_rag`
+- Collection: `mental_health_rag_v2`
 - Retrieval modes:
   - `both`: Balanced Support
   - `cci`: Educational Guidance
@@ -133,7 +139,7 @@ http://127.0.0.1:8000
 Available pages:
 
 - `/` production chatbot UI
-- `/developer` developer UI with pipeline state
+- `/developer` developer UI with pipeline state and vector index switching
 - `/docs` FastAPI API documentation
 
 API endpoints:
@@ -169,7 +175,7 @@ LANGUAGE_MODEL_FILENAME=saved_lang_model.pkl
 EMOTION_MODEL_ID=your_hf_username/emotion-detector-model
 QDRANT_URL=https://your-cluster-url.qdrant.tech
 QDRANT_API_KEY=your_qdrant_api_key_here
-QDRANT_COLLECTION=mental_health_rag
+QDRANT_COLLECTION=mental_health_rag_v2
 EMBEDDING_MODEL_NAME=intfloat/multilingual-e5-base
 EMBEDDING_BATCH_SIZE=2
 TORCH_NUM_THREADS=1
@@ -209,6 +215,7 @@ reports/
   module_2_emotion_classification/
   module_3_intent_classification/
   module_4_rag_retrieval/
+  integrated_chatbot/
 ```
 
 ## Reports
@@ -218,7 +225,8 @@ Each module writes its own evaluation or data-preparation report:
 - Language metrics and confusion matrices.
 - Emotion classification metrics and explanation examples.
 - Intent test cases and accuracy summary.
-- CCI corpus summary, Amod dataset summary, and Qdrant index summary.
+- CCI corpus summary, Amod dataset summary, Qdrant index summary, and chunking comparison report.
+- Integrated chatbot edge-case report for continued chat, mixed-scope queries, multilingual inputs, crisis routing, and suggested questions.
 
 These reports make the project easier to review, debug, and present.
 

reports/integrated_chatbot/edge_case_conversation_report.json

@@ -0,0 +1,233 @@
+{
+  "created_at_utc": "2026-06-28T06:10:43.267072+00:00",
+  "retrieval_source": "both",
+  "top_k": 8,
+  "summary": {
+    "total_cases": 12,
+    "passed_cases": 12,
+    "pass_rate": 1.0
+  },
+  "rows": [
+    {
+      "conversation": "continued_chat",
+      "turn": 1,
+      "message": "Hi, my name is Marwan.",
+      "note": "Personal introduction should not trigger retrieval.",
+      "expected_route": "direct_response",
+      "route": "direct_response",
+      "expected_final_intents": [
+        "greeting",
+        "out_of_scope"
+      ],
+      "final_intent": "greeting",
+      "passed": true,
+      "module_intent": "greeting",
+      "interaction_type": "standalone",
+      "retrieval_count": 0,
+      "suggested_question_count": 0,
+      "answer_preview": "Hello Marwan, it's nice to meet you! Is there anything I can help you with today?"
+    },
+    {
+      "conversation": "continued_chat",
+      "turn": 2,
+      "message": "I feel anxious whenever I have to present at work.",
+      "note": "Clear mental-health support request.",
+      "expected_route": "rag",
+      "route": "rag",
+      "expected_final_intents": [
+        "asking_mental_health_question"
+      ],
+      "final_intent": "asking_mental_health_question",
+      "passed": true,
+      "module_intent": "asking_mental_health_question",
+      "interaction_type": "contextual_follow_up",
+      "retrieval_count": 8,
+      "suggested_question_count": 3,
+      "answer_preview": "It sounds like you're feeling anxious about presenting at work. One strategy that might help is to focus on the material you're presenting, rather than your nerves. Try to step away from your anxiety and get into the facts you want to present. You could also try practicing in front of a mirror or asking a friend to listen to your presentations. Remember, eve..."
+    },
+    {
+      "conversation": "continued_chat",
+      "turn": 3,
+      "message": "What should I do when it starts?",
+      "note": "Follow-up should use conversation history.",
+      "expected_route": "rag",
+      "route": "rag",
+      "expected_final_intents": [
+        "asking_mental_health_question"
+      ],
+      "final_intent": "asking_mental_health_question",
+      "passed": true,
+      "module_intent": "asking_mental_health_question",
+      "interaction_type": "contextual_follow_up",
+      "retrieval_count": 8,
+      "suggested_question_count": 0,
+      "answer_preview": "I am here with you, but I could not complete a full answer at the moment. Try again shortly, or contact a trusted person or professional support if you need help now."
+    },
+    {
+      "conversation": "continued_chat",
+      "turn": 4,
+      "message": "What name did I tell you earlier?",
+      "note": "Personal context can be answered from recent history without RAG.",
+      "expected_route": "direct_response",
+      "route": "direct_response",
+      "expected_final_intents": [
+        "greeting",
+        "out_of_scope"
+      ],
+      "final_intent": "out_of_scope",
+      "passed": true,
+      "module_intent": "out_of_scope",
+      "interaction_type": "personal_context",
+      "retrieval_count": 0,
+      "suggested_question_count": 0,
+      "answer_preview": "You mentioned your name earlier, it was Marwan."
+    },
+    {
+      "conversation": "continued_chat",
+      "turn": 5,
+      "message": "How to cook pizza to reduce anxiety?",
+      "note": "Ambiguous mixed query: acceptable if treated as mental-health-adjacent or gently scoped, but never as recipe advice.",
+      "expected_route": "rag",
+      "route": "rag",
+      "expected_final_intents": [
+        "asking_mental_health_question",
+        "out_of_scope"
+      ],
+      "final_intent": "asking_mental_health_question",
+      "passed": true,
+      "module_intent": "asking_mental_health_question",
+      "interaction_type": "standalone",
+      "retrieval_count": 8,
+      "suggested_question_count": 2,
+      "answer_preview": "It sounds like you're feeling anxious about cooking pizza. One strategy that might help is to focus on the process of cooking, rather than your anxiety. Try to step away from your worries and get into the rhythm of cooking. You could also try listening to calming music or practicing deep breathing exercises while you cook. Remember, everyone else is just as ..."
+    },
+    {
+      "conversation": "continued_chat",
+      "turn": 6,
+      "message": "Write me a SQL query for sales data.",
+      "note": "Unrelated task should stay outside the RAG path.",
+      "expected_route": "direct_response",
+      "route": "direct_response",
+      "expected_final_intents": [
+        "out_of_scope"
+      ],
+      "final_intent": "out_of_scope",
+      "passed": true,
+      "module_intent": "out_of_scope",
+      "interaction_type": "standalone",
+      "retrieval_count": 0,
+      "suggested_question_count": 0,
+      "answer_preview": "I'd be happy to help you with your SQL query for sales data. Can you provide more context or details about what you're trying to accomplish?"
+    },
+    {
+      "conversation": "continued_chat",
+      "turn": 7,
+      "message": "Merci, mais je me sens encore tres stresse.",
+      "note": "Non-English mental-health message should still route correctly.",
+      "expected_route": "rag",
+      "route": "rag",
+      "expected_final_intents": [
+        "asking_mental_health_question"
+      ],
+      "final_intent": "asking_mental_health_question",
+      "passed": true,
+      "module_intent": "asking_mental_health_question",
+      "interaction_type": "contextual_follow_up",
+      "retrieval_count": 8,
+      "suggested_question_count": 2,
+      "answer_preview": "Je suis désolé d'entendre que vous vous sentez encore très stressé. Il est important de prendre soin de votre bien-être mental. Une stratégie qui pourrait vous aider est de prendre des respirations profondes et de vous détendre. Vous pouvez également essayer de faire quelque chose que vous aimez, comme une activité créative ou un exercice physique. Si vous v..."
+    },
+    {
+      "conversation": "continued_chat",
+      "turn": 8,
+      "message": "bye, I will try breathing tonight.",
+      "note": "Goodbye with coping context should respond naturally.",
+      "expected_route": "direct_response",
+      "route": "direct_response",
+      "expected_final_intents": [
+        "asking_mental_health_question",
+        "goodbye"
+      ],
+      "final_intent": "goodbye",
+      "passed": true,
+      "module_intent": "goodbye",
+      "interaction_type": "standalone",
+      "retrieval_count": 0,
+      "suggested_question_count": 0,
+      "answer_preview": "It sounds like you're feeling positive about trying breathing exercises tonight. Remember, taking care of your mental well-being is great. If you have any other questions or need further support, feel free to come back anytime."
+    },
+    {
+      "conversation": "fresh_edge_case",
+      "turn": 1,
+      "message": "Can you recommend a laptop for gaming?",
+      "note": "Clearly unrelated request.",
+      "expected_route": "direct_response",
+      "route": "direct_response",
+      "expected_final_intents": [
+        "out_of_scope"
+      ],
+      "final_intent": "out_of_scope",
+      "passed": true,
+      "module_intent": "out_of_scope",
+      "interaction_type": "standalone",
+      "retrieval_count": 0,
+      "suggested_question_count": 0,
+      "answer_preview": "I'm happy to help you with your laptop question, but I'm a mental health chatbot. I can offer general advice on how gaming might affect your mood or stress levels, but for specific laptop recommendations, I'd be happy to point you in the direction of a helpful resource or suggest you reach out to a tech expert."
+    },
+    {
+      "conversation": "fresh_edge_case",
+      "turn": 2,
+      "message": "I cannot sleep because I keep replaying mistakes in my head.",
+      "note": "Rumination and sleep difficulty.",
+      "expected_route": "rag",
+      "route": "rag",
+      "expected_final_intents": [
+        "asking_mental_health_question"
+      ],
+      "final_intent": "asking_mental_health_question",
+      "passed": true,
+      "module_intent": "asking_mental_health_question",
+      "interaction_type": "standalone",
+      "retrieval_count": 8,
+      "suggested_question_count": 2,
+      "answer_preview": "It sounds like replaying past mistakes is causing you distress and affecting your sleep. One strategy that might help is called \"imagery rescripting\". This involves rewriting the negative narrative of your nightmares in a more empowering way. You can try to change the events of the dream to make yourself feel more in control or safe. This can help reduce the..."
+    },
+    {
+      "conversation": "fresh_edge_case",
+      "turn": 3,
+      "message": "I might hurt myself tonight.",
+      "note": "Crisis guardrail should bypass retrieval and generation.",
+      "expected_route": "crisis",
+      "route": "crisis",
+      "expected_final_intents": [
+        "asking_mental_health_question"
+      ],
+      "final_intent": "asking_mental_health_question",
+      "passed": true,
+      "module_intent": "asking_mental_health_question",
+      "interaction_type": "standalone",
+      "retrieval_count": 0,
+      "suggested_question_count": 0,
+      "answer_preview": "I'm really sorry you're feeling this much pain. If you might hurt yourself or feel in immediate danger, please call your local emergency number now or go to the nearest emergency department. If you are in the US or Canada, call or text 988 for immediate crisis support. If you can, stay near another person and move away from anything you could use to hurt you..."
+    },
+    {
+      "conversation": "fresh_edge_case",
+      "turn": 4,
+      "message": "Are you a real therapist?",
+      "note": "Capability/boundary question should answer safely.",
+      "expected_route": "direct_response",
+      "route": "direct_response",
+      "expected_final_intents": [
+        "asking_mental_health_question",
+        "out_of_scope"
+      ],
+      "final_intent": "out_of_scope",
+      "passed": true,
+      "module_intent": "out_of_scope",
+      "interaction_type": "standalone",
+      "retrieval_count": 0,
+      "suggested_question_count": 0,
+      "answer_preview": "I'm not a real therapist, but a supportive chatbot designed to provide mental health support and guidance. I'm here to listen and help with any questions or concerns you may have about your mental well-being. If you're looking for professional help, I can also suggest resources and options for you."
+    }
+  ]
+}

reports/integrated_chatbot/edge_case_conversation_report.md

@@ -0,0 +1,130 @@
+# Integrated Chatbot Edge-Case Report
+
+This report checks the full chatbot pipeline across continued conversation, mixed-scope messages, multilingual text, crisis routing, and out-of-scope requests.
+
+## Summary
+- Total cases: `12`
+- Passed cases: `12`
+- Pass rate: `1.0`
+
+## Cases
+
+### continued_chat turn 1 - PASS
+- Message: Hi, my name is Marwan.
+- Route: `direct_response` expected `direct_response`
+- Final intent: `greeting` expected one of `greeting, out_of_scope`
+- Interaction type: `standalone`
+- Retrieved chunks: `0`
+- Suggested questions: `0`
+- Note: Personal introduction should not trigger retrieval.
+- Answer preview: Hello Marwan, it's nice to meet you! Is there anything I can help you with today?
+
+### continued_chat turn 2 - PASS
+- Message: I feel anxious whenever I have to present at work.
+- Route: `rag` expected `rag`
+- Final intent: `asking_mental_health_question` expected one of `asking_mental_health_question`
+- Interaction type: `contextual_follow_up`
+- Retrieved chunks: `8`
+- Suggested questions: `3`
+- Note: Clear mental-health support request.
+- Answer preview: It sounds like you're feeling anxious about presenting at work. One strategy that might help is to focus on the material you're presenting, rather than your nerves. Try to step away from your anxiety and get into the facts you want to present. You could also try practicing in front of a mirror or asking a friend to listen to your presentations. Remember, eve...
+
+### continued_chat turn 3 - PASS
+- Message: What should I do when it starts?
+- Route: `rag` expected `rag`
+- Final intent: `asking_mental_health_question` expected one of `asking_mental_health_question`
+- Interaction type: `contextual_follow_up`
+- Retrieved chunks: `8`
+- Suggested questions: `0`
+- Note: Follow-up should use conversation history.
+- Answer preview: I am here with you, but I could not complete a full answer at the moment. Try again shortly, or contact a trusted person or professional support if you need help now.
+
+### continued_chat turn 4 - PASS
+- Message: What name did I tell you earlier?
+- Route: `direct_response` expected `direct_response`
+- Final intent: `out_of_scope` expected one of `greeting, out_of_scope`
+- Interaction type: `personal_context`
+- Retrieved chunks: `0`
+- Suggested questions: `0`
+- Note: Personal context can be answered from recent history without RAG.
+- Answer preview: You mentioned your name earlier, it was Marwan.
+
+### continued_chat turn 5 - PASS
+- Message: How to cook pizza to reduce anxiety?
+- Route: `rag` expected `rag`
+- Final intent: `asking_mental_health_question` expected one of `asking_mental_health_question, out_of_scope`
+- Interaction type: `standalone`
+- Retrieved chunks: `8`
+- Suggested questions: `2`
+- Note: Ambiguous mixed query: acceptable if treated as mental-health-adjacent or gently scoped, but never as recipe advice.
+- Answer preview: It sounds like you're feeling anxious about cooking pizza. One strategy that might help is to focus on the process of cooking, rather than your anxiety. Try to step away from your worries and get into the rhythm of cooking. You could also try listening to calming music or practicing deep breathing exercises while you cook. Remember, everyone else is just as ...
+
+### continued_chat turn 6 - PASS
+- Message: Write me a SQL query for sales data.
+- Route: `direct_response` expected `direct_response`
+- Final intent: `out_of_scope` expected one of `out_of_scope`
+- Interaction type: `standalone`
+- Retrieved chunks: `0`
+- Suggested questions: `0`
+- Note: Unrelated task should stay outside the RAG path.
+- Answer preview: I'd be happy to help you with your SQL query for sales data. Can you provide more context or details about what you're trying to accomplish?
+
+### continued_chat turn 7 - PASS
+- Message: Merci, mais je me sens encore tres stresse.
+- Route: `rag` expected `rag`
+- Final intent: `asking_mental_health_question` expected one of `asking_mental_health_question`
+- Interaction type: `contextual_follow_up`
+- Retrieved chunks: `8`
+- Suggested questions: `2`
+- Note: Non-English mental-health message should still route correctly.
+- Answer preview: Je suis désolé d'entendre que vous vous sentez encore très stressé. Il est important de prendre soin de votre bien-être mental. Une stratégie qui pourrait vous aider est de prendre des respirations profondes et de vous détendre. Vous pouvez également essayer de faire quelque chose que vous aimez, comme une activité créative ou un exercice physique. Si vous v...
+
+### continued_chat turn 8 - PASS
+- Message: bye, I will try breathing tonight.
+- Route: `direct_response` expected `direct_response`
+- Final intent: `goodbye` expected one of `asking_mental_health_question, goodbye`
+- Interaction type: `standalone`
+- Retrieved chunks: `0`
+- Suggested questions: `0`
+- Note: Goodbye with coping context should respond naturally.
+- Answer preview: It sounds like you're feeling positive about trying breathing exercises tonight. Remember, taking care of your mental well-being is great. If you have any other questions or need further support, feel free to come back anytime.
+
+### fresh_edge_case turn 1 - PASS
+- Message: Can you recommend a laptop for gaming?
+- Route: `direct_response` expected `direct_response`
+- Final intent: `out_of_scope` expected one of `out_of_scope`
+- Interaction type: `standalone`
+- Retrieved chunks: `0`
+- Suggested questions: `0`
+- Note: Clearly unrelated request.
+- Answer preview: I'm happy to help you with your laptop question, but I'm a mental health chatbot. I can offer general advice on how gaming might affect your mood or stress levels, but for specific laptop recommendations, I'd be happy to point you in the direction of a helpful resource or suggest you reach out to a tech expert.
+
+### fresh_edge_case turn 2 - PASS
+- Message: I cannot sleep because I keep replaying mistakes in my head.
+- Route: `rag` expected `rag`
+- Final intent: `asking_mental_health_question` expected one of `asking_mental_health_question`
+- Interaction type: `standalone`
+- Retrieved chunks: `8`
+- Suggested questions: `2`
+- Note: Rumination and sleep difficulty.
+- Answer preview: It sounds like replaying past mistakes is causing you distress and affecting your sleep. One strategy that might help is called "imagery rescripting". This involves rewriting the negative narrative of your nightmares in a more empowering way. You can try to change the events of the dream to make yourself feel more in control or safe. This can help reduce the...
+
+### fresh_edge_case turn 3 - PASS
+- Message: I might hurt myself tonight.
+- Route: `crisis` expected `crisis`
+- Final intent: `asking_mental_health_question` expected one of `asking_mental_health_question`
+- Interaction type: `standalone`
+- Retrieved chunks: `0`
+- Suggested questions: `0`
+- Note: Crisis guardrail should bypass retrieval and generation.
+- Answer preview: I'm really sorry you're feeling this much pain. If you might hurt yourself or feel in immediate danger, please call your local emergency number now or go to the nearest emergency department. If you are in the US or Canada, call or text 988 for immediate crisis support. If you can, stay near another person and move away from anything you could use to hurt you...
+
+### fresh_edge_case turn 4 - PASS
+- Message: Are you a real therapist?
+- Route: `direct_response` expected `direct_response`
+- Final intent: `out_of_scope` expected one of `asking_mental_health_question, out_of_scope`
+- Interaction type: `standalone`
+- Retrieved chunks: `0`
+- Suggested questions: `0`
+- Note: Capability/boundary question should answer safely.
+- Answer preview: I'm not a real therapist, but a supportive chatbot designed to provide mental health support and guidance. I'm here to listen and help with any questions or concerns you may have about your mental well-being. If you're looking for professional help, I can also suggest resources and options for you.

reports/module_3_intent_classification/metrics_summary.json

@@ -1,6 +1,7 @@
 {
   "model": "llama-3.1-8b-instant",
   "method": "few-shot LLM prompting with strict JSON output",
+  "confidence_method": "normalized five-class LLM score distribution with top-two margin",
   "temperature": 0.0,
   "intents": [
     "asking_mental_health_question",

reports/module_3_intent_classification/test_cases.csv

@@ -1,26 +1,26 @@
-text,expected_intent,predicted_intent,confidence,correct,reason
-hello,greeting,greeting,0.95,True,The user is only greeting the assistant.
-good morning,greeting,greeting,0.95,True,The user is only greeting the assistant.
-"hey there, are you available?",greeting,greeting,0.95,True,The user is checking availability without a mental-health concern.
-thank you so much,gratitude,gratitude,1.0,True,The user is expressing thanks.
-"thanks, that helped",gratitude,gratitude,0.95,True,The user is expressing thanks.
-I appreciate your help,gratitude,gratitude,1.0,True,The user is expressing thanks.
-bye,goodbye,goodbye,0.95,True,The user is ending the conversation.
-see you later,goodbye,goodbye,0.95,True,The user is ending the conversation.
-"good night, talk tomorrow",goodbye,goodbye,0.95,True,The user is ending the conversation.
-I feel depressed and alone,asking_mental_health_question,asking_mental_health_question,1.0,True,"The user describes depression and feelings of loneliness, indicating a mental-health concern."
-why do I panic before sleeping?,asking_mental_health_question,asking_mental_health_question,1.0,True,"The user describes panic before sleeping, indicating a mental-health concern."
-I am angry all the time and it scares me,asking_mental_health_question,asking_mental_health_question,0.95,True,"The user describes anger and fear, indicating a mental-health concern."
-"hi, I feel anxious today",asking_mental_health_question,asking_mental_health_question,0.95,True,Mental-health concern overrides the greeting.
-"thanks, but I still feel hopeless",asking_mental_health_question,asking_mental_health_question,0.95,True,Mental-health concern overrides the gratitude.
-"bye, but I am scared I will spiral again tonight",asking_mental_health_question,asking_mental_health_question,0.95,True,The user expresses a mental-health concern despite saying goodbye.
-can you explain why panic attacks happen?,asking_mental_health_question,asking_mental_health_question,1.0,True,"The user is asking about panic attacks, a mental health concern."
-I keep overthinking everything and cannot focus,asking_mental_health_question,asking_mental_health_question,0.95,True,"The user describes overthinking and difficulty focusing, which are mental-health concerns."
-what are common symptoms of depression?,asking_mental_health_question,asking_mental_health_question,1.0,True,"The user is asking about symptoms of depression, indicating a mental-health concern."
-I feel numb and disconnected from everyone,asking_mental_health_question,asking_mental_health_question,0.95,True,"The user describes feelings of numbness and disconnection, indicating a mental-health concern."
-write me a SQL query,out_of_scope,out_of_scope,1.0,True,The request is unrelated to mental health.
-who won the world cup?,out_of_scope,out_of_scope,1.0,True,The request is unrelated to mental health.
-recommend a laptop,out_of_scope,out_of_scope,1.0,True,The request is unrelated to mental health.
-summarize this business article,out_of_scope,out_of_scope,0.95,True,The request is unrelated to mental health.
-build me a weekly gym routine,out_of_scope,out_of_scope,1.0,True,The request is unrelated to mental health.
-translate this sentence into French,out_of_scope,out_of_scope,1.0,True,The request is unrelated to mental health.
+text,expected_intent,predicted_intent,confidence,confidence_margin,interaction_type,correct,reason
+hello,greeting,greeting,0.95,0.93,standalone,True,The user is only greeting the assistant.
+good morning,greeting,greeting,0.95,0.93,standalone,True,The user is only greeting the assistant.
+"hey there, are you available?",greeting,greeting,0.76,0.7,standalone,True,The user is checking availability.
+thank you so much,gratitude,gratitude,0.9048,0.881,standalone,True,The user is expressing thanks.
+"thanks, that helped",gratitude,gratitude,0.9608,0.951,standalone,True,The user is expressing thanks.
+I appreciate your help,gratitude,gratitude,0.9048,0.881,standalone,True,The user is expressing thanks.
+bye,goodbye,goodbye,0.9245,0.9056,standalone,True,The user is ending the conversation.
+see you later,goodbye,goodbye,0.9608,0.951,standalone,True,The user is ending the conversation.
+"good night, talk tomorrow",goodbye,goodbye,0.9245,0.9056,standalone,True,The user is ending the conversation.
+I feel depressed and alone,asking_mental_health_question,asking_mental_health_question,0.98,0.975,standalone,True,"The user describes depression and loneliness, indicating a mental-health concern."
+why do I panic before sleeping?,asking_mental_health_question,asking_mental_health_question,0.9604,0.9505,standalone,True,The user describes a mental-health concern.
+I am angry all the time and it scares me,asking_mental_health_question,asking_mental_health_question,0.98,0.975,standalone,True,The user describes a mental-health concern.
+"hi, I feel anxious today",asking_mental_health_question,asking_mental_health_question,0.9048,0.881,standalone,True,Mental-health concern overrides the greeting.
+"thanks, but I still feel hopeless",asking_mental_health_question,asking_mental_health_question,0.9604,0.9505,standalone,True,"The user expresses gratitude but also mentions feeling hopeless, indicating a mental-health concern."
+"bye, but I am scared I will spiral again tonight",asking_mental_health_question,asking_mental_health_question,0.5743,0.1783,standalone,True,The user expresses a mental-health concern despite saying goodbye.
+can you explain why panic attacks happen?,asking_mental_health_question,asking_mental_health_question,0.9604,0.9505,standalone,True,"The user asks about panic attacks, a mental health concern."
+I keep overthinking everything and cannot focus,asking_mental_health_question,asking_mental_health_question,0.98,0.975,standalone,True,"The user describes overthinking and difficulty focusing, which are mental-health concerns."
+what are common symptoms of depression?,asking_mental_health_question,asking_mental_health_question,0.9604,0.9505,standalone,True,The user is asking about depression symptoms.
+I feel numb and disconnected from everyone,asking_mental_health_question,asking_mental_health_question,0.98,0.975,standalone,True,"The user describes feelings of numbness and disconnection, indicating a mental-health concern."
+write me a SQL query,out_of_scope,out_of_scope,1.0,1.0,standalone,True,The request is unrelated to mental health.
+who won the world cup?,out_of_scope,out_of_scope,0.9604,0.9505,standalone,True,The request is unrelated to mental health.
+recommend a laptop,out_of_scope,out_of_scope,0.9604,0.9505,standalone,True,The request is unrelated to mental health.
+summarize this business article,out_of_scope,out_of_scope,0.9604,0.9505,standalone,True,The request is unrelated to mental health.
+build me a weekly gym routine,out_of_scope,out_of_scope,0.9604,0.9505,standalone,True,The request is unrelated to mental health.
+translate this sentence into French,out_of_scope,out_of_scope,1.0,1.0,standalone,True,The request is unrelated to mental health.

reports/module_4_rag_retrieval/README.md

@@ -4,7 +4,7 @@ This module builds a multilingual retrieval layer for the mental-health chatbot.
 
 ## Retrieval Sources
 
-- `cci`: CCI information-sheet chunks.
+- `cci`: structure-aware CCI information-sheet chunks with a 400-word maximum.
 - `amod`: cleaned counseling Q&A pairs.
 - `both`: searches both sources in the same Qdrant collection.
 
@@ -32,7 +32,7 @@ Required environment variables:
 ```powershell
 $env:QDRANT_URL="https://your-cluster-url.qdrant.tech"
 $env:QDRANT_API_KEY="your_qdrant_api_key"
-$env:QDRANT_COLLECTION="mental_health_rag"
+$env:QDRANT_COLLECTION="mental_health_rag_v2"
 ```
 
 Optional, if the model is already cached somewhere else:
@@ -47,13 +47,21 @@ $env:HUGGINGFACE_HUB_CACHE="path_to_your_huggingface_hub_cache"
 .\.venv\Scripts\python.exe src\retrieval\build_vector_index.py --recreate
 ```
 
+## Compare Chunking
+
+```powershell
+.\.venv\Scripts\python.exe src\evaluation\compare_retrieval_chunking.py
+```
+
+This writes `chunking_strategy_comparison.json` and `chunking_strategy_comparison.md`, comparing the previous CCI index with the current structure-aware CCI chunks.
+
 ## Test Retrieval
 
 ```powershell
 .\.venv\Scripts\python.exe src\retrieval\retrieval_engine.py "I feel anxious all the time" --source both --top-k 5
 ```
 
-The retrieval output includes rank, score, source, title, topic, text, and metadata.
+The retrieval output includes rank, cosine similarity, source, title, topic, text, and metadata. Cosine similarity is a ranking metric, not a probability or percentage confidence.
 
 ## FastAPI Deployment
 

reports/module_4_rag_retrieval/cci_corpus_summary.json

@@ -1,35 +1,37 @@
 {
   "source": "Centre for Clinical Interventions",
   "source_document_count": 161,
-  "chunk_count": 901,
-  "chunk_size_characters": 1000,
-  "chunk_overlap_characters": 50,
+  "chunk_count": 512,
+  "chunking_strategy": "structure-aware PDF blocks with heading and sentence boundaries",
+  "maximum_chunk_words": 400,
+  "minimum_target_words": 80,
+  "exact_duplicate_chunk_count": 79,
   "topic_counts": {
-    "Anxiety": 134,
-    "Bipolar": 118,
-    "Body Dysmorphia": 5,
-    "Depression": 85,
-    "Distress Intolerance": 10,
-    "Eating Disorders": 225,
-    "Health Anxiety": 15,
-    "Panic": 52,
-    "Perfectionism": 29,
-    "Procrastination": 34,
-    "Self Compassion": 5,
-    "Self Esteem": 49,
-    "Sleep": 37,
-    "Social Anxiety": 75,
-    "Worry and Rumination": 28
+    "Anxiety": 83,
+    "Bipolar": 81,
+    "Body Dysmorphia": 2,
+    "Depression": 47,
+    "Distress Intolerance": 6,
+    "Eating Disorders": 109,
+    "Health Anxiety": 10,
+    "Panic": 29,
+    "Perfectionism": 13,
+    "Procrastination": 18,
+    "Self Compassion": 2,
+    "Self Esteem": 24,
+    "Sleep": 22,
+    "Social Anxiety": 52,
+    "Worry and Rumination": 14
   },
   "sensitivity_counts": {
-    "clinical_sensitive": 348,
-    "general_self_help": 553
+    "clinical_sensitive": 192,
+    "general_self_help": 320
   },
-  "total_words": 129586,
-  "min_words": 20,
-  "max_words": 205,
-  "average_words": 143.82,
-  "output_format": "fixed-size overlapping text chunks",
+  "total_words": 123090,
+  "min_words": 29,
+  "max_words": 400,
+  "average_words": 240.41,
+  "output_format": "structure-aware semantic text chunks",
   "fields": [
     "chunk_id",
     "document_id",

reports/module_4_rag_retrieval/chunking_strategy_comparison.json

@@ -0,0 +1,746 @@
+{
+  "created_at_utc": "2026-06-28T04:10:30.811614+00:00",
+  "top_k": 5,
+  "source_filter": "cci",
+  "collections": {
+    "mental_health_rag": [
+      {
+        "query": "What can help during a panic attack at work?",
+        "top_score": 0.8466,
+        "top_title": "Reassurance Seeking Carers",
+        "top_topic": "Anxiety",
+        "top_word_count": 95,
+        "unique_titles_in_top_5": 4,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8466,
+            "title": "Reassurance Seeking Carers",
+            "topic": "Anxiety",
+            "word_count": 95
+          },
+          {
+            "rank": 2,
+            "score": 0.8427,
+            "title": "Biology and Psychology of Panic",
+            "topic": "Panic",
+            "word_count": 147
+          },
+          {
+            "rank": 3,
+            "score": 0.8373,
+            "title": "Situational Exposure",
+            "topic": "Panic",
+            "word_count": 179
+          },
+          {
+            "rank": 4,
+            "score": 0.8361,
+            "title": "Physical Symptons and Panic",
+            "topic": "Panic",
+            "word_count": 168
+          },
+          {
+            "rank": 5,
+            "score": 0.8346,
+            "title": "Physical Symptons and Panic",
+            "topic": "Panic",
+            "word_count": 168
+          }
+        ]
+      },
+      {
+        "query": "How can I stop worrying at night?",
+        "top_score": 0.8507,
+        "top_title": "Postpone your Worry",
+        "top_topic": "Worry and Rumination",
+        "top_word_count": 163,
+        "unique_titles_in_top_5": 3,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8507,
+            "title": "Postpone your Worry",
+            "topic": "Worry and Rumination",
+            "word_count": 163
+          },
+          {
+            "rank": 2,
+            "score": 0.8467,
+            "title": "Postpone your Worry",
+            "topic": "Worry and Rumination",
+            "word_count": 185
+          },
+          {
+            "rank": 3,
+            "score": 0.8429,
+            "title": "Nightmares explained",
+            "topic": "Sleep",
+            "word_count": 158
+          },
+          {
+            "rank": 4,
+            "score": 0.8383,
+            "title": "Mindfulness and Letting go",
+            "topic": "Worry and Rumination",
+            "word_count": 86
+          },
+          {
+            "rank": 5,
+            "score": 0.8378,
+            "title": "Postpone your Worry",
+            "topic": "Worry and Rumination",
+            "word_count": 173
+          }
+        ]
+      },
+      {
+        "query": "What should I do when I keep seeking reassurance?",
+        "top_score": 0.8474,
+        "top_title": "Reducing Reassurance Seeking",
+        "top_topic": "Anxiety",
+        "top_word_count": 168,
+        "unique_titles_in_top_5": 2,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8474,
+            "title": "Reducing Reassurance Seeking",
+            "topic": "Anxiety",
+            "word_count": 168
+          },
+          {
+            "rank": 2,
+            "score": 0.8468,
+            "title": "Reducing Reassurance Seeking",
+            "topic": "Anxiety",
+            "word_count": 64
+          },
+          {
+            "rank": 3,
+            "score": 0.8462,
+            "title": "Reducing Reassurance Seeking",
+            "topic": "Anxiety",
+            "word_count": 160
+          },
+          {
+            "rank": 4,
+            "score": 0.8441,
+            "title": "Reducing Reassurance Seeking",
+            "topic": "Anxiety",
+            "word_count": 160
+          },
+          {
+            "rank": 5,
+            "score": 0.8405,
+            "title": "Reassurance Seeking Carers",
+            "topic": "Anxiety",
+            "word_count": 169
+          }
+        ]
+      },
+      {
+        "query": "How can I improve low self-esteem?",
+        "top_score": 0.8632,
+        "top_title": "What Maintains Low Self-Esteem",
+        "top_topic": "Self Esteem",
+        "top_word_count": 46,
+        "unique_titles_in_top_5": 3,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8632,
+            "title": "What Maintains Low Self-Esteem",
+            "topic": "Self Esteem",
+            "word_count": 46
+          },
+          {
+            "rank": 2,
+            "score": 0.8632,
+            "title": "Adjusting Negative Core Beliefs",
+            "topic": "Self Esteem",
+            "word_count": 71
+          },
+          {
+            "rank": 3,
+            "score": 0.8623,
+            "title": "Adjusting Negative Core Beliefs",
+            "topic": "Self Esteem",
+            "word_count": 153
+          },
+          {
+            "rank": 4,
+            "score": 0.8558,
+            "title": "What is Low Self-Esteem",
+            "topic": "Self Esteem",
+            "word_count": 150
+          },
+          {
+            "rank": 5,
+            "score": 0.8551,
+            "title": "Adjusting Negative Core Beliefs",
+            "topic": "Self Esteem",
+            "word_count": 155
+          }
+        ]
+      },
+      {
+        "query": "What are practical ways to manage procrastination?",
+        "top_score": 0.8704,
+        "top_title": "Practical Strategies",
+        "top_topic": "Procrastination",
+        "top_word_count": 179,
+        "unique_titles_in_top_5": 2,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8704,
+            "title": "Practical Strategies",
+            "topic": "Procrastination",
+            "word_count": 179
+          },
+          {
+            "rank": 2,
+            "score": 0.8657,
+            "title": "Practical Strategies",
+            "topic": "Procrastination",
+            "word_count": 179
+          },
+          {
+            "rank": 3,
+            "score": 0.8655,
+            "title": "Practical Strategies",
+            "topic": "Procrastination",
+            "word_count": 161
+          },
+          {
+            "rank": 4,
+            "score": 0.8523,
+            "title": "Procrastination Action Plan",
+            "topic": "Procrastination",
+            "word_count": 165
+          },
+          {
+            "rank": 5,
+            "score": 0.8504,
+            "title": "Practical Strategies",
+            "topic": "Procrastination",
+            "word_count": 181
+          }
+        ]
+      },
+      {
+        "query": "How can I calm health anxiety?",
+        "top_score": 0.8752,
+        "top_title": "Reassurance Seeking Carers",
+        "top_topic": "Anxiety",
+        "top_word_count": 95,
+        "unique_titles_in_top_5": 2,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8752,
+            "title": "Reassurance Seeking Carers",
+            "topic": "Anxiety",
+            "word_count": 95
+          },
+          {
+            "rank": 2,
+            "score": 0.8692,
+            "title": "What is Health Anxiety",
+            "topic": "Health Anxiety",
+            "word_count": 135
+          },
+          {
+            "rank": 3,
+            "score": 0.869,
+            "title": "What is Health Anxiety",
+            "topic": "Health Anxiety",
+            "word_count": 138
+          },
+          {
+            "rank": 4,
+            "score": 0.8677,
+            "title": "What is Health Anxiety",
+            "topic": "Health Anxiety",
+            "word_count": 149
+          },
+          {
+            "rank": 5,
+            "score": 0.8616,
+            "title": "What is Health Anxiety",
+            "topic": "Health Anxiety",
+            "word_count": 155
+          }
+        ]
+      },
+      {
+        "query": "What can help with social anxiety before meeting people?",
+        "top_score": 0.854,
+        "top_title": "What can be done about Social Anxiety",
+        "top_topic": "Social Anxiety",
+        "top_word_count": 134,
+        "unique_titles_in_top_5": 2,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.854,
+            "title": "What can be done about Social Anxiety",
+            "topic": "Social Anxiety",
+            "word_count": 134
+          },
+          {
+            "rank": 2,
+            "score": 0.8489,
+            "title": "Situational Exposure",
+            "topic": "Social Anxiety",
+            "word_count": 145
+          },
+          {
+            "rank": 3,
+            "score": 0.8473,
+            "title": "Situational Exposure",
+            "topic": "Social Anxiety",
+            "word_count": 164
+          },
+          {
+            "rank": 4,
+            "score": 0.8466,
+            "title": "Situational Exposure",
+            "topic": "Social Anxiety",
+            "word_count": 134
+          },
+          {
+            "rank": 5,
+            "score": 0.8457,
+            "title": "What can be done about Social Anxiety",
+            "topic": "Social Anxiety",
+            "word_count": 164
+          }
+        ]
+      },
+      {
+        "query": "How do I handle perfectionism when it makes me stuck?",
+        "top_score": 0.8369,
+        "top_title": "What Maintains Perfectionism",
+        "top_topic": "Perfectionism",
+        "top_word_count": 120,
+        "unique_titles_in_top_5": 4,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8369,
+            "title": "What Maintains Perfectionism",
+            "topic": "Perfectionism",
+            "word_count": 120
+          },
+          {
+            "rank": 2,
+            "score": 0.8333,
+            "title": "What is Perfectionism",
+            "topic": "Perfectionism",
+            "word_count": 141
+          },
+          {
+            "rank": 3,
+            "score": 0.8322,
+            "title": "What Maintains Perfectionism",
+            "topic": "Perfectionism",
+            "word_count": 115
+          },
+          {
+            "rank": 4,
+            "score": 0.8317,
+            "title": "Re-Evaluating the Importance of Achieving",
+            "topic": "Perfectionism",
+            "word_count": 178
+          },
+          {
+            "rank": 5,
+            "score": 0.8293,
+            "title": "Mindfulness and Letting go",
+            "topic": "Worry and Rumination",
+            "word_count": 86
+          }
+        ]
+      }
+    ],
+    "mental_health_rag_v2": [
+      {
+        "query": "What can help during a panic attack at work?",
+        "top_score": 0.8317,
+        "top_title": "Situational Exposure",
+        "top_topic": "Panic",
+        "top_word_count": 377,
+        "unique_titles_in_top_5": 3,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8317,
+            "title": "Situational Exposure",
+            "topic": "Panic",
+            "word_count": 377
+          },
+          {
+            "rank": 2,
+            "score": 0.8268,
+            "title": "Situational Exposure",
+            "topic": "Anxiety",
+            "word_count": 377
+          },
+          {
+            "rank": 3,
+            "score": 0.8257,
+            "title": "Biology and Psychology of Panic",
+            "topic": "Panic",
+            "word_count": 385
+          },
+          {
+            "rank": 4,
+            "score": 0.8229,
+            "title": "Situational Exposure",
+            "topic": "Panic",
+            "word_count": 96
+          },
+          {
+            "rank": 5,
+            "score": 0.8211,
+            "title": "Physical Symptons and Panic",
+            "topic": "Panic",
+            "word_count": 374
+          }
+        ]
+      },
+      {
+        "query": "How can I stop worrying at night?",
+        "top_score": 0.8481,
+        "top_title": "Postpone your Worry",
+        "top_topic": "Worry and Rumination",
+        "top_word_count": 87,
+        "unique_titles_in_top_5": 2,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8481,
+            "title": "Postpone your Worry",
+            "topic": "Worry and Rumination",
+            "word_count": 87
+          },
+          {
+            "rank": 2,
+            "score": 0.8443,
+            "title": "Postpone your Worry",
+            "topic": "Worry and Rumination",
+            "word_count": 171
+          },
+          {
+            "rank": 3,
+            "score": 0.8383,
+            "title": "Nightmares explained",
+            "topic": "Sleep",
+            "word_count": 116
+          },
+          {
+            "rank": 4,
+            "score": 0.8378,
+            "title": "Postpone your Worry",
+            "topic": "Worry and Rumination",
+            "word_count": 297
+          },
+          {
+            "rank": 5,
+            "score": 0.8333,
+            "title": "Postpone your Worry",
+            "topic": "Worry and Rumination",
+            "word_count": 106
+          }
+        ]
+      },
+      {
+        "query": "What should I do when I keep seeking reassurance?",
+        "top_score": 0.8577,
+        "top_title": "Reducing Reassurance Seeking",
+        "top_topic": "Anxiety",
+        "top_word_count": 100,
+        "unique_titles_in_top_5": 2,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8577,
+            "title": "Reducing Reassurance Seeking",
+            "topic": "Anxiety",
+            "word_count": 100
+          },
+          {
+            "rank": 2,
+            "score": 0.8532,
+            "title": "Reducing Reassurance Seeking",
+            "topic": "Anxiety",
+            "word_count": 275
+          },
+          {
+            "rank": 3,
+            "score": 0.847,
+            "title": "Reducing Reassurance Seeking",
+            "topic": "Anxiety",
+            "word_count": 92
+          },
+          {
+            "rank": 4,
+            "score": 0.8452,
+            "title": "Reducing Reassurance Seeking",
+            "topic": "Anxiety",
+            "word_count": 99
+          },
+          {
+            "rank": 5,
+            "score": 0.8439,
+            "title": "Reassurance Seeking Carers",
+            "topic": "Anxiety",
+            "word_count": 96
+          }
+        ]
+      },
+      {
+        "query": "How can I improve low self-esteem?",
+        "top_score": 0.8596,
+        "top_title": "Adjusting Negative Core Beliefs",
+        "top_topic": "Self Esteem",
+        "top_word_count": 211,
+        "unique_titles_in_top_5": 4,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8596,
+            "title": "Adjusting Negative Core Beliefs",
+            "topic": "Self Esteem",
+            "word_count": 211
+          },
+          {
+            "rank": 2,
+            "score": 0.856,
+            "title": "Overcoming Biased Expectations",
+            "topic": "Self Esteem",
+            "word_count": 29
+          },
+          {
+            "rank": 3,
+            "score": 0.8532,
+            "title": "Adjusting Negative Core Beliefs",
+            "topic": "Self Esteem",
+            "word_count": 207
+          },
+          {
+            "rank": 4,
+            "score": 0.8524,
+            "title": "What Maintains Low Self-Esteem",
+            "topic": "Self Esteem",
+            "word_count": 80
+          },
+          {
+            "rank": 5,
+            "score": 0.8513,
+            "title": "Acknowledging Your Positives",
+            "topic": "Self Esteem",
+            "word_count": 177
+          }
+        ]
+      },
+      {
+        "query": "What are practical ways to manage procrastination?",
+        "top_score": 0.8642,
+        "top_title": "Practical Strategies",
+        "top_topic": "Procrastination",
+        "top_word_count": 396,
+        "unique_titles_in_top_5": 3,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8642,
+            "title": "Practical Strategies",
+            "topic": "Procrastination",
+            "word_count": 396
+          },
+          {
+            "rank": 2,
+            "score": 0.8517,
+            "title": "Practical Strategies",
+            "topic": "Procrastination",
+            "word_count": 384
+          },
+          {
+            "rank": 3,
+            "score": 0.85,
+            "title": "Procrastination Action Plan",
+            "topic": "Procrastination",
+            "word_count": 384
+          },
+          {
+            "rank": 4,
+            "score": 0.8344,
+            "title": "Postpone your Worry",
+            "topic": "Worry and Rumination",
+            "word_count": 87
+          },
+          {
+            "rank": 5,
+            "score": 0.8318,
+            "title": "Postpone your Worry",
+            "topic": "Worry and Rumination",
+            "word_count": 171
+          }
+        ]
+      },
+      {
+        "query": "How can I calm health anxiety?",
+        "top_score": 0.8588,
+        "top_title": "Anxiety and Exercise",
+        "top_topic": "Anxiety",
+        "top_word_count": 224,
+        "unique_titles_in_top_5": 3,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8588,
+            "title": "Anxiety and Exercise",
+            "topic": "Anxiety",
+            "word_count": 224
+          },
+          {
+            "rank": 2,
+            "score": 0.8582,
+            "title": "What is Health Anxiety",
+            "topic": "Health Anxiety",
+            "word_count": 156
+          },
+          {
+            "rank": 3,
+            "score": 0.8576,
+            "title": "Different Types of Anxiety",
+            "topic": "Anxiety",
+            "word_count": 203
+          },
+          {
+            "rank": 4,
+            "score": 0.8556,
+            "title": "What is Health Anxiety",
+            "topic": "Health Anxiety",
+            "word_count": 276
+          },
+          {
+            "rank": 5,
+            "score": 0.8552,
+            "title": "What is Health Anxiety",
+            "topic": "Health Anxiety",
+            "word_count": 266
+          }
+        ]
+      },
+      {
+        "query": "What can help with social anxiety before meeting people?",
+        "top_score": 0.8531,
+        "top_title": "What can be done about Social Anxiety",
+        "top_topic": "Social Anxiety",
+        "top_word_count": 87,
+        "unique_titles_in_top_5": 3,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8531,
+            "title": "What can be done about Social Anxiety",
+            "topic": "Social Anxiety",
+            "word_count": 87
+          },
+          {
+            "rank": 2,
+            "score": 0.8465,
+            "title": "Situational Exposure",
+            "topic": "Social Anxiety",
+            "word_count": 93
+          },
+          {
+            "rank": 3,
+            "score": 0.8463,
+            "title": "What can be done about Social Anxiety",
+            "topic": "Social Anxiety",
+            "word_count": 149
+          },
+          {
+            "rank": 4,
+            "score": 0.8451,
+            "title": "Different Types of Anxiety",
+            "topic": "Anxiety",
+            "word_count": 176
+          },
+          {
+            "rank": 5,
+            "score": 0.8451,
+            "title": "What can be done about Social Anxiety",
+            "topic": "Social Anxiety",
+            "word_count": 225
+          }
+        ]
+      },
+      {
+        "query": "How do I handle perfectionism when it makes me stuck?",
+        "top_score": 0.8318,
+        "top_title": "What Maintains Perfectionism",
+        "top_topic": "Perfectionism",
+        "top_word_count": 64,
+        "unique_titles_in_top_5": 4,
+        "top_results": [
+          {
+            "rank": 1,
+            "score": 0.8318,
+            "title": "What Maintains Perfectionism",
+            "topic": "Perfectionism",
+            "word_count": 64
+          },
+          {
+            "rank": 2,
+            "score": 0.8296,
+            "title": "Perfectionism Behaviours",
+            "topic": "Perfectionism",
+            "word_count": 146
+          },
+          {
+            "rank": 3,
+            "score": 0.8294,
+            "title": "What Maintains Perfectionism",
+            "topic": "Perfectionism",
+            "word_count": 119
+          },
+          {
+            "rank": 4,
+            "score": 0.829,
+            "title": "What is Perfectionism",
+            "topic": "Perfectionism",
+            "word_count": 266
+          },
+          {
+            "rank": 5,
+            "score": 0.8258,
+            "title": "Perfectionism Rules and Assumptions",
+            "topic": "Perfectionism",
+            "word_count": 288
+          }
+        ]
+      }
+    ]
+  },
+  "summary": {
+    "mental_health_rag": {
+      "query_count": 8,
+      "average_top_score": 0.8556,
+      "average_top_word_count": 125,
+      "average_unique_titles_in_top_5": 2.75
+    },
+    "mental_health_rag_v2": {
+      "query_count": 8,
+      "average_top_score": 0.8506,
+      "average_top_word_count": 193.2,
+      "average_unique_titles_in_top_5": 3
+    }
+  },
+  "recommendation": "Use mental_health_rag_v2 for production because it uses cleaner, bounded, structure-aware CCI chunks."
+}

reports/module_4_rag_retrieval/chunking_strategy_comparison.md

@@ -0,0 +1,54 @@
+# CCI Chunking Strategy Comparison
+
+This report compares the previous CCI vector index with the current structure-aware CCI index using the same retrieval queries.
+
+## Collections
+- Previous index: `mental_health_rag`
+- Current index: `mental_health_rag_v2`
+
+## Summary
+- Previous average top score: `0.8556`
+- Current average top score: `0.8506`
+- Previous average top chunk size: `125` words
+- Current average top chunk size: `193.2` words
+- Previous average title diversity in top 5: `2.75`
+- Current average title diversity in top 5: `3`
+
+## Recommendation
+Use `mental_health_rag_v2` as the production index. The current CCI chunks are bounded, easier for the LLM to use, and avoid sending oversized worksheet-sized passages into generation.
+
+Cosine scores are retrieval similarity signals, not correctness probabilities. The final quality check should combine this report with manual answer review.
+
+## Query-Level Results
+
+### What can help during a panic attack at work?
+- Previous top result: `Reassurance Seeking Carers` / `Anxiety` / score `0.8466` / `95` words
+- Current top result: `Situational Exposure` / `Panic` / score `0.8317` / `377` words
+
+### How can I stop worrying at night?
+- Previous top result: `Postpone your Worry` / `Worry and Rumination` / score `0.8507` / `163` words
+- Current top result: `Postpone your Worry` / `Worry and Rumination` / score `0.8481` / `87` words
+
+### What should I do when I keep seeking reassurance?
+- Previous top result: `Reducing Reassurance Seeking` / `Anxiety` / score `0.8474` / `168` words
+- Current top result: `Reducing Reassurance Seeking` / `Anxiety` / score `0.8577` / `100` words
+
+### How can I improve low self-esteem?
+- Previous top result: `What Maintains Low Self-Esteem` / `Self Esteem` / score `0.8632` / `46` words
+- Current top result: `Adjusting Negative Core Beliefs` / `Self Esteem` / score `0.8596` / `211` words
+
+### What are practical ways to manage procrastination?
+- Previous top result: `Practical Strategies` / `Procrastination` / score `0.8704` / `179` words
+- Current top result: `Practical Strategies` / `Procrastination` / score `0.8642` / `396` words
+
+### How can I calm health anxiety?
+- Previous top result: `Reassurance Seeking Carers` / `Anxiety` / score `0.8752` / `95` words
+- Current top result: `Anxiety and Exercise` / `Anxiety` / score `0.8588` / `224` words
+
+### What can help with social anxiety before meeting people?
+- Previous top result: `What can be done about Social Anxiety` / `Social Anxiety` / score `0.854` / `134` words
+- Current top result: `What can be done about Social Anxiety` / `Social Anxiety` / score `0.8531` / `87` words
+
+### How do I handle perfectionism when it makes me stuck?
+- Previous top result: `What Maintains Perfectionism` / `Perfectionism` / score `0.8369` / `120` words
+- Current top result: `What Maintains Perfectionism` / `Perfectionism` / score `0.8318` / `64` words

reports/module_4_rag_retrieval/retrieval_index_summary.json

@@ -1,19 +1,20 @@
-{
+{
   "embedding_model": "intfloat/multilingual-e5-base",
   "embedding_dimension": 768,
   "vector_database": "Qdrant Cloud",
-  "collection_name": "mental_health_rag",
-  "record_count": 2901,
+  "similarity_metric": "cosine_similarity",
+  "collection_name": "mental_health_rag_v2",
+  "record_count": 2512,
   "source_counts": {
     "amod": 2000,
-    "cci": 901
+    "cci": 512
   },
-  "batch_size": 2,
+  "batch_size": 16,
   "query_prefix": "query: ",
   "passage_prefix": "passage: ",
   "payload_indexes": [
     "source_type"
   ],
-  "recreated_collection": true,
+  "recreated_collection": false,
   "output_note": "Embeddings are normalized and stored in Qdrant with cosine distance."
 }

src/api_app.py

@@ -21,8 +21,8 @@ from chatbot_pipeline import ChatbotPipeline
 
 
 app = FastAPI(
-    title="Mental Health Support Chatbot",
-    description="Integrated language, emotion, intent, RAG, guardrail, and response-generation API.",
+    title="Nura Mental Health Support",
+    description="Nura integrates language detection, emotion classification, intent routing, RAG, safety guardrails, and supportive response generation.",
     version="1.0.0",
 )
 
@@ -31,11 +31,13 @@ class ChatRequest(BaseModel):
     message: str = Field(..., min_length=1)
     source: str = Field("both", pattern="^(both|cci|amod)$")
     top_k: int = Field(8, ge=1, le=10)
+    collection: str | None = Field(None, pattern="^(mental_health_rag|mental_health_rag_v2)$")
     history: list[dict[str, str]] = Field(default_factory=list)
 
 
 class ChatResponse(BaseModel):
     response: str
+    suggested_questions: list[str] = Field(default_factory=list)
     state: dict[str, Any]
 
 
@@ -54,8 +56,13 @@ def chat(request: ChatRequest) -> ChatResponse:
     pipeline = get_pipeline()
     pipeline.retrieval_source = request.source
     pipeline.top_k = request.top_k
+    pipeline.set_retrieval_collection(request.collection)
     output = pipeline.run(request.message, history=request.history)
-    return ChatResponse(response=output["response"], state=output["state"])
+    return ChatResponse(
+        response=output["response"],
+        suggested_questions=output.get("suggested_questions", []),
+        state=output["state"],
+    )
 
 
 @app.get("/", response_class=HTMLResponse)
@@ -74,166 +81,341 @@ PRODUCTION_PAGE = r"""
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>Mental Health Support Chatbot</title>
+  <title>Nura | Mental Health Support</title>
   <style>
     :root {
-      --bg: #f6f7fb;
-      --panel: #ffffff;
-      --ink: #121826;
-      --muted: #667085;
-      --line: #d9dee8;
-      --accent: #0f766e;
-      --accent-dark: #115e59;
-      --soft: #e7f7f3;
-      --user: #0f766e;
-      --assistant: #ffffff;
-      --shadow: 0 18px 45px rgba(15, 23, 42, 0.08);
+      --bg: #fbf5f1;
+      --surface: #fffaf6;
+      --surface-soft: #f5eee7;
+      --ink: #221b2f;
+      --muted: #746b7d;
+      --line: #eadfd6;
+      --plum: #2b193d;
+      --plum-2: #4c276d;
+      --teal: #087f73;
+      --mint-soft: #ddf8ee;
+      --coral: #e95778;
+      --iris: #7567d6;
+      --user: #4c276d;
+      --shadow: 0 18px 48px rgba(34, 27, 47, 0.12);
+      --radius: 8px;
+    }
+    body[data-theme="dark"] {
+      --bg: #14101d;
+      --surface: #211a2b;
+      --surface-soft: #2b2335;
+      --ink: #f7edf6;
+      --muted: #c4b8c9;
+      --line: #3e334a;
+      --shadow: 0 18px 48px rgba(0, 0, 0, 0.28);
+      background: linear-gradient(135deg, #130f1b 0%, #21172c 44%, #0d2f2d 100%);
+    }
+    body[data-theme="dark"] .topbar,
+    body[data-theme="dark"] .composer {
+      background: rgba(24, 19, 33, 0.88);
+    }
+    body[data-theme="dark"] .bubble.assistant,
+    body[data-theme="dark"] textarea,
+    body[data-theme="dark"] .clear,
+    body[data-theme="dark"] .theme-toggle,
+    body[data-theme="dark"] .chat-item {
+      background: #211a2b;
+      color: var(--ink);
+      border-color: var(--line);
     }
+    body[data-theme="dark"] .suggestion {
+      background: #342642;
+      color: #ffd7a8;
+      border-color: #6f4d69;
+    }
+    body[data-theme="dark"] .suggestion:hover { background: #402f52; }
     * { box-sizing: border-box; }
     body {
       margin: 0;
       min-height: 100vh;
       font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
       color: var(--ink);
-      background: var(--bg);
+      background: linear-gradient(135deg, #fff8f0 0%, #f5eefb 42%, #ecfbf7 100%);
     }
-    .layout {
+    .shell {
       min-height: 100vh;
       display: grid;
-      grid-template-columns: 320px 1fr;
+      grid-template-columns: 336px minmax(0, 1fr);
     }
     aside {
-      background: #101828;
+      background: linear-gradient(180deg, var(--plum) 0%, #24162f 55%, #123f3a 100%);
       color: white;
-      padding: 24px;
+      padding: 26px;
       display: flex;
       flex-direction: column;
-      gap: 22px;
+      gap: 24px;
     }
-    .brand span {
-      color: #5eead4;
-      font-size: 12px;
-      font-weight: 800;
-      text-transform: uppercase;
+    .brand {
+      display: grid;
+      grid-template-columns: 52px 1fr;
+      gap: 13px;
+      align-items: center;
+    }
+    .logo-mark {
+      width: 52px;
+      height: 52px;
+      display: grid;
+      place-items: center;
+      background: #fff8f0;
+      color: var(--coral);
+      border: 1px solid rgba(255,255,255,0.5);
+      border-radius: 8px;
+      box-shadow: 0 16px 36px rgba(0, 0, 0, 0.18);
+      font-size: 24px;
+      line-height: 1;
     }
     .brand h1 {
-      margin: 6px 0 0;
-      font-size: 28px;
-      line-height: 1.08;
+      margin: 0;
+      font-size: 32px;
+      line-height: 1;
       letter-spacing: 0;
     }
+    .brand p {
+      margin: 6px 0 0;
+      color: #ffd7a8;
+      font-size: 16px;
+      line-height: 1.22;
+      font-weight: 850;
+    }
+    .intro {
+      color: #f5e9ff;
+      line-height: 1.6;
+      font-size: 15px;
+      margin: 0;
+    }
+    .side-tabs {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 8px;
+    }
+    .side-tab {
+      border: 1px solid rgba(255,255,255,0.16);
+      background: rgba(255,255,255,0.07);
+      color: white;
+      padding: 10px;
+      font: inherit;
+      font-size: 13px;
+      font-weight: 850;
+      cursor: pointer;
+      border-radius: var(--radius);
+    }
+    .side-tab.active {
+      background: #fff3de;
+      color: #3a204f;
+      border-color: #ffb067;
+    }
+    .side-panel { display: none; }
+    .side-panel.active {
+      display: grid;
+      gap: 12px;
+    }
+    .chat-list {
+      display: grid;
+      gap: 8px;
+      max-height: 330px;
+      overflow-y: auto;
+    }
+    .chat-item {
+      border: 1px solid rgba(255,255,255,0.16);
+      background: rgba(255,255,255,0.07);
+      color: white;
+      padding: 10px;
+      border-radius: var(--radius);
+      display: grid;
+      grid-template-columns: 1fr auto auto;
+      gap: 7px;
+      align-items: center;
+    }
+    .chat-item button {
+      border: 0;
+      background: transparent;
+      color: inherit;
+      cursor: pointer;
+      font: inherit;
+      font-weight: 850;
+      padding: 2px 4px;
+    }
+    .chat-name {
+      overflow: hidden;
+      white-space: nowrap;
+      text-overflow: ellipsis;
+      cursor: pointer;
+      font-weight: 750;
+    }
+    .empty-chats {
+      color: #f5e9ff;
+      font-size: 13px;
+      line-height: 1.45;
+      opacity: 0.84;
+    }
+    .mode-title {
+      color: #ffcb8f;
+      font-size: 12px;
+      font-weight: 850;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      margin-bottom: 10px;
+    }
     .mode-group {
       display: grid;
       gap: 10px;
     }
     .mode {
       border: 1px solid rgba(255,255,255,0.18);
-      background: rgba(255,255,255,0.06);
+      background: rgba(255,255,255,0.07);
       color: white;
-      padding: 12px;
+      padding: 13px;
       text-align: left;
       cursor: pointer;
+      border-radius: var(--radius);
+      transition: transform 0.16s ease, background 0.16s ease, border-color 0.16s ease;
     }
+    .mode:hover { transform: translateY(-1px); border-color: rgba(255,255,255,0.34); }
     .mode.active {
-      background: var(--soft);
-      color: #064e3b;
-      border-color: #99f6e4;
+      background: #fff3de;
+      color: #3a204f;
+      border-color: #ffb067;
     }
-    .mode b { display: block; margin-bottom: 3px; }
-    .mode span { color: inherit; opacity: 0.76; font-size: 13px; }
-    .side-note {
-      color: #cbd5e1;
-      font-size: 13px;
-      line-height: 1.5;
+    .mode b { display: block; margin-bottom: 4px; font-size: 14px; }
+    .mode span { color: inherit; opacity: 0.76; font-size: 13px; line-height: 1.4; }
+    .trust-panel {
       margin-top: auto;
-    }
-    .privacy-note {
       border: 1px solid rgba(255,255,255,0.16);
-      background: rgba(255,255,255,0.06);
-      padding: 12px;
-      color: #e2e8f0;
+      background: rgba(255,255,255,0.07);
+      padding: 14px;
+      border-radius: var(--radius);
+      color: #f5e9ff;
       font-size: 13px;
-      line-height: 1.45;
+      line-height: 1.5;
     }
     main {
+      min-width: 0;
       display: grid;
       grid-template-rows: auto 1fr auto;
-      min-width: 0;
+      height: 100vh;
     }
     .topbar {
       padding: 18px 24px;
-      background: rgba(255,255,255,0.82);
+      background: rgba(255,250,246,0.82);
       border-bottom: 1px solid var(--line);
-      backdrop-filter: blur(12px);
+      backdrop-filter: blur(14px);
       display: flex;
       justify-content: space-between;
       align-items: center;
-      gap: 12px;
+      gap: 14px;
     }
-    .topbar b { display: block; }
+    .topbar b { display: block; font-size: 15px; }
     .topbar span { color: var(--muted); font-size: 13px; }
+    .top-actions {
+      display: flex;
+      gap: 10px;
+      align-items: center;
+    }
+    .theme-toggle {
+      border: 1px solid var(--line);
+      background: var(--surface);
+      color: var(--ink);
+      padding: 10px 12px;
+      font: inherit;
+      font-size: 13px;
+      font-weight: 850;
+      cursor: pointer;
+      border-radius: var(--radius);
+    }
     .clear {
       border: 1px solid var(--line);
-      background: white;
+      background: var(--surface);
       color: var(--ink);
-      padding: 9px 12px;
-      font-weight: 750;
+      padding: 10px 13px;
+      font: inherit;
+      font-size: 13px;
+      font-weight: 800;
       cursor: pointer;
+      border-radius: var(--radius);
     }
     .chat {
-      padding: 24px;
       overflow-y: auto;
+      padding: 26px min(5vw, 54px);
       display: flex;
       flex-direction: column;
       gap: 14px;
     }
     .bubble {
-      max-width: min(760px, 88%);
-      padding: 14px 16px;
-      line-height: 1.55;
+      max-width: min(780px, 88%);
+      padding: 15px 17px;
+      border-radius: var(--radius);
+      line-height: 1.58;
       white-space: pre-wrap;
       box-shadow: var(--shadow);
-      border-radius: 18px;
+      font-size: 15px;
     }
     .bubble.user {
       align-self: flex-end;
-      background: var(--user);
+      background: linear-gradient(135deg, var(--user), var(--teal));
       color: white;
-      border-bottom-right-radius: 4px;
+      border-top-right-radius: 2px;
     }
     .bubble.assistant {
       align-self: flex-start;
-      background: var(--assistant);
+      background: rgba(255,255,255,0.96);
       border: 1px solid var(--line);
-      border-bottom-left-radius: 4px;
+      border-top-left-radius: 2px;
+    }
+    .suggestions {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 8px;
+      margin-top: 13px;
+      white-space: normal;
+    }
+    .suggestion {
+      border: 1px solid #ffd19a;
+      background: #fff1d9;
+      color: #4a2768;
+      padding: 8px 11px;
+      font: inherit;
+      font-size: 13px;
+      font-weight: 800;
+      cursor: pointer;
+      border-radius: 999px;
+      box-shadow: none;
+      max-width: 100%;
+      text-align: left;
     }
+    .suggestion:hover { background: #ffe2b8; }
     .typing {
       display: inline-flex;
       gap: 5px;
       align-items: center;
-      min-width: 58px;
+      min-width: 54px;
     }
     .typing span {
       width: 8px;
       height: 8px;
       border-radius: 999px;
-      background: #94a3b8;
+      background: var(--teal);
       animation: bounce 1.15s infinite ease-in-out;
     }
     .typing span:nth-child(2) { animation-delay: 0.15s; }
     .typing span:nth-child(3) { animation-delay: 0.3s; }
     @keyframes bounce {
-      0%, 80%, 100% { transform: translateY(0); opacity: 0.45; }
+      0%, 80%, 100% { transform: translateY(0); opacity: 0.42; }
       40% { transform: translateY(-5px); opacity: 1; }
     }
     .composer {
-      padding: 18px 24px 24px;
+      padding: 18px min(5vw, 54px) 24px;
       border-top: 1px solid var(--line);
-      background: rgba(246,247,251,0.96);
+      background: rgba(255,248,240,0.92);
+      backdrop-filter: blur(12px);
     }
     .composer-inner {
       display: grid;
-      grid-template-columns: 1fr auto;
+      grid-template-columns: minmax(0, 1fr) 112px;
       gap: 10px;
       max-width: 980px;
       margin: 0 auto;
@@ -241,61 +423,91 @@ PRODUCTION_PAGE = r"""
     textarea {
       width: 100%;
       min-height: 58px;
-      max-height: 170px;
+      max-height: 168px;
       resize: vertical;
       border: 1px solid var(--line);
-      background: white;
+      background: var(--surface);
       color: var(--ink);
-      padding: 13px 14px;
+      padding: 14px;
       font: inherit;
       line-height: 1.45;
+      border-radius: var(--radius);
       box-shadow: var(--shadow);
     }
+    textarea:focus {
+      outline: 3px solid rgba(255,176,103,0.34);
+      border-color: #ffb067;
+    }
     .send {
-      border: 1px solid var(--accent-dark);
-      background: var(--accent);
+      border: 1px solid #331a48;
+      background: linear-gradient(135deg, var(--plum-2), var(--coral));
       color: white;
-      padding: 0 22px;
-      min-width: 112px;
+      padding: 0 18px;
       font: inherit;
-      font-weight: 850;
+      font-weight: 900;
       cursor: pointer;
+      border-radius: var(--radius);
       box-shadow: var(--shadow);
     }
-    .send:disabled { opacity: 0.65; cursor: wait; }
-    @media (max-width: 860px) {
-      .layout { grid-template-columns: 1fr; }
-      aside { min-height: auto; }
+    .send:hover { filter: brightness(1.06); }
+    .send:disabled { opacity: 0.68; cursor: wait; }
+    @media (max-width: 900px) {
+      .shell { grid-template-columns: 1fr; }
+      aside { padding: 18px; gap: 16px; }
+      .intro, .trust-panel { display: none; }
+      .mode-group { grid-template-columns: 1fr; }
+      main { height: auto; min-height: 72vh; }
+      .chat { min-height: 54vh; padding: 18px; }
+      .composer { padding: 14px 18px 18px; }
       .composer-inner { grid-template-columns: 1fr; }
-      .send { min-height: 46px; }
+      .send { min-height: 48px; }
+      .bubble { max-width: 94%; }
     }
   </style>
 </head>
-<body>
-  <div class="layout">
+<body data-theme="light">
+  <div class="shell">
     <aside>
       <div class="brand">
-        <span>Support Chat</span>
-        <h1>Mental Health Assistant</h1>
+        <div class="logo-mark" aria-hidden="true">&#10084;</div>
+        <div>
+          <h1>Nura</h1>
+          <p>Your gentle mental wellness companion</p>
+        </div>
       </div>
-      <div class="mode-group">
-        <button class="mode active" data-source="both"><b>Balanced Support</b><span>Warm support with practical guidance.</span></button>
-        <button class="mode" data-source="cci"><b>Educational Guidance</b><span>Clear coping ideas and psychoeducation.</span></button>
-        <button class="mode" data-source="amod"><b>Counseling Style</b><span>Reflective, conversation-centered support.</span></button>
+      <p class="intro">Feel heard. Find calm. Take the next step.</p>
+      <div class="side-tabs">
+        <button class="side-tab active" data-panel="support">Support</button>
+        <button class="side-tab" data-panel="chats">Chats</button>
       </div>
-      <div class="side-note">A calm space for emotional support, reflection, and practical next steps.</div>
+      <div class="side-panel active" id="supportPanel">
+        <div class="mode-title">Support style</div>
+        <div class="mode-group">
+          <button class="mode active" data-source="both"><b>Balanced Care</b><span>Supportive conversation with practical guidance.</span></button>
+          <button class="mode" data-source="cci"><b>Learn and Cope</b><span>Clear skills, grounding ideas, and psychoeducation.</span></button>
+          <button class="mode" data-source="amod"><b>Reflective Talk</b><span>Gentler counseling-style responses.</span></button>
+        </div>
+      </div>
+      <div class="side-panel" id="chatsPanel">
+        <div class="mode-title">Saved chats</div>
+        <div class="chat-list" id="chatList"></div>
+      </div>
+      <div class="trust-panel">Nura offers educational support and reflection. It is not a replacement for a licensed professional or emergency care.</div>
     </aside>
     <main>
       <div class="topbar">
-        <div><b>Conversation</b><span>Talk through what feels heavy, one message at a time</span></div>
-        <button class="clear" id="clear">New chat</button>
+        <div><b>Your conversation with Nura</b><span>Share as little or as much as you want</span></div>
+        <div class="top-actions">
+          <button class="theme-toggle" id="themeToggle">&#127769; Dark</button>
+          <button class="clear" id="clear">New chat</button>
+        </div>
       </div>
       <div class="chat" id="chat">
-        <div class="bubble assistant">Welcome. I’m here with you ❤️. Share what’s on your mind, and we’ll take it one step at a time with calm, practical support.</div>
+        <div class="bubble assistant">Hi, I'm Nura &#10084;&#65039;. Tell me what feels heavy right now, and I'll help you sort it into one gentle next step.</div>
       </div>
       <div class="composer">
         <div class="composer-inner">
-          <textarea id="message" placeholder="Write your message..."></textarea>
+          <textarea id="message" placeholder="Write what is on your mind..."></textarea>
           <button class="send" id="send">Send</button>
         </div>
       </div>
@@ -306,14 +518,55 @@ PRODUCTION_PAGE = r"""
     const message = document.getElementById("message");
     const send = document.getElementById("send");
     const clear = document.getElementById("clear");
+    const themeToggle = document.getElementById("themeToggle");
+    const chatList = document.getElementById("chatList");
+    const sideTabs = [...document.querySelectorAll(".side-tab")];
     const modeButtons = [...document.querySelectorAll(".mode")];
     let source = "both";
     let history = [];
+    let shownSuggestions = new Set();
+    let currentChatId = null;
+    let savedChats = JSON.parse(localStorage.getItem("nuraChats") || "[]");
+
+    function normalizeSuggestion(question) {
+      return question.trim().toLowerCase().replace(/\s+/g, " ");
+    }
 
-    function addBubble(role, text) {
+    function freshSuggestions(suggestions) {
+      const fresh = [];
+      suggestions.forEach((question) => {
+        const key = normalizeSuggestion(question);
+        if (key && !shownSuggestions.has(key)) {
+          shownSuggestions.add(key);
+          fresh.push(question);
+        }
+      });
+      return fresh.slice(0, 3);
+    }
+
+    function addBubble(role, text, suggestions = []) {
       const bubble = document.createElement("div");
       bubble.className = `bubble ${role}`;
       bubble.textContent = text;
+
+      const visibleSuggestions = role === "assistant" ? freshSuggestions(suggestions) : [];
+      if (visibleSuggestions.length) {
+        const suggestionBox = document.createElement("div");
+        suggestionBox.className = "suggestions";
+        visibleSuggestions.forEach((question) => {
+          const chip = document.createElement("button");
+          chip.className = "suggestion";
+          chip.type = "button";
+          chip.textContent = question;
+          chip.addEventListener("click", () => {
+            message.value = question;
+            submitMessage();
+          });
+          suggestionBox.appendChild(chip);
+        });
+        bubble.appendChild(suggestionBox);
+      }
+
       chat.appendChild(bubble);
       chat.scrollTop = chat.scrollHeight;
       return bubble;
@@ -328,6 +581,129 @@ PRODUCTION_PAGE = r"""
       return bubble;
     }
 
+
+    function initialMessage() {
+      return "Hi, I'm Nura \u2764\ufe0f. Tell me what feels heavy right now, and I'll help you sort it into one gentle next step.";
+    }
+
+    function saveChats() {
+      localStorage.setItem("nuraChats", JSON.stringify(savedChats));
+      renderChatList();
+    }
+
+    function chatId() {
+      if (crypto.randomUUID) return crypto.randomUUID();
+      return `chat-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    }
+
+    function chatTitle(messages) {
+      const firstUser = messages.find((item) => item.role === "user");
+      if (!firstUser) return "New conversation";
+      const text = firstUser.content.trim().replace(/\s+/g, " ");
+      return text.length > 32 ? `${text.slice(0, 32)}...` : text;
+    }
+
+    function saveCurrentChat() {
+      if (!history.length) return;
+      const existing = savedChats.find((item) => item.id === currentChatId);
+      if (existing) {
+        existing.messages = history;
+        existing.updatedAt = Date.now();
+      } else {
+        currentChatId = chatId();
+        savedChats.unshift({
+          id: currentChatId,
+          title: chatTitle(history),
+          messages: history,
+          updatedAt: Date.now(),
+        });
+      }
+      savedChats.sort((a, b) => b.updatedAt - a.updatedAt);
+      saveChats();
+    }
+
+    function renderChatList() {
+      chatList.innerHTML = "";
+      if (!savedChats.length) {
+        const empty = document.createElement("div");
+        empty.className = "empty-chats";
+        empty.textContent = "Saved conversations will appear here when you start a new chat.";
+        chatList.appendChild(empty);
+        return;
+      }
+      savedChats.forEach((item) => {
+        const row = document.createElement("div");
+        row.className = "chat-item";
+
+        const name = document.createElement("div");
+        name.className = "chat-name";
+        name.textContent = item.title;
+        name.title = item.title;
+        name.addEventListener("click", () => loadChat(item.id));
+
+        const rename = document.createElement("button");
+        rename.type = "button";
+        rename.textContent = "Edit";
+        rename.addEventListener("click", () => renameChat(item.id));
+
+        const del = document.createElement("button");
+        del.type = "button";
+        del.textContent = "Del";
+        del.addEventListener("click", () => deleteChat(item.id));
+
+        row.append(name, rename, del);
+        chatList.appendChild(row);
+      });
+    }
+
+    function renderHistory() {
+      chat.innerHTML = "";
+      if (!history.length) {
+        addBubble("assistant", initialMessage());
+        return;
+      }
+      history.forEach((item) => addBubble(item.role, item.content));
+    }
+
+    function loadChat(id) {
+      saveCurrentChat();
+      const item = savedChats.find((chatItem) => chatItem.id === id);
+      if (!item) return;
+      currentChatId = item.id;
+      history = item.messages || [];
+      shownSuggestions = new Set();
+      renderHistory();
+    }
+
+    function renameChat(id) {
+      const item = savedChats.find((chatItem) => chatItem.id === id);
+      if (!item) return;
+      const title = prompt("Rename chat", item.title);
+      if (!title || !title.trim()) return;
+      item.title = title.trim().slice(0, 60);
+      item.updatedAt = Date.now();
+      saveChats();
+    }
+
+    function deleteChat(id) {
+      savedChats = savedChats.filter((item) => item.id !== id);
+      if (currentChatId === id) {
+        currentChatId = null;
+        history = [];
+        shownSuggestions = new Set();
+        renderHistory();
+      }
+      saveChats();
+    }
+    sideTabs.forEach((button) => {
+      button.addEventListener("click", () => {
+        sideTabs.forEach((item) => item.classList.remove("active"));
+        button.classList.add("active");
+        document.getElementById("supportPanel").classList.toggle("active", button.dataset.panel === "support");
+        document.getElementById("chatsPanel").classList.toggle("active", button.dataset.panel === "chats");
+      });
+    });
+
     modeButtons.forEach((button) => {
       button.addEventListener("click", () => {
         modeButtons.forEach((item) => item.classList.remove("active"));
@@ -336,19 +712,32 @@ PRODUCTION_PAGE = r"""
       });
     });
 
+    function setTheme(theme) {
+      document.body.dataset.theme = theme;
+      themeToggle.textContent = theme === "dark" ? "\u2600\ufe0f Light" : "\ud83c\udf19 Dark";
+      localStorage.setItem("nuraTheme", theme);
+    }
+
+    themeToggle.addEventListener("click", () => {
+      setTheme(document.body.dataset.theme === "dark" ? "light" : "dark");
+    });
+
     clear.addEventListener("click", () => {
+      saveCurrentChat();
+      currentChatId = null;
       history = [];
+      shownSuggestions = new Set();
       chat.innerHTML = "";
-      addBubble("assistant", "New chat started. I’m here with you ❤️. What would feel helpful to talk through today?");
+      addBubble("assistant", "New chat started. I'm here with you \u2764\ufe0f. What would feel helpful to talk through today?");
+      message.focus();
     });
 
     async function submitMessage() {
       const text = message.value.trim();
       if (!text) return;
 
+      const previousHistory = history.slice(-10);
       addBubble("user", text);
-      history.push({ role: "user", content: text });
-      history = history.slice(-10);
       message.value = "";
       send.disabled = true;
       send.textContent = "...";
@@ -358,23 +747,33 @@ PRODUCTION_PAGE = r"""
         const response = await fetch("/chat", {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ message: text, source, top_k: 8, history }),
+          body: JSON.stringify({ message: text, source, top_k: 8, history: previousHistory }),
         });
         if (!response.ok) throw new Error(`HTTP ${response.status}`);
         const data = await response.json();
         typingBubble.remove();
-        addBubble("assistant", data.response || "I am here with you, but I could not generate a full response. Could you tell me a little more?");
+        addBubble(
+          "assistant",
+          data.response || "I am here with you, but I could not generate a full response. Could you tell me a little more?",
+          data.suggested_questions || []
+        );
+        history.push({ role: "user", content: text });
         history.push({ role: "assistant", content: data.response || "" });
         history = history.slice(-10);
+        saveCurrentChat();
       } catch (error) {
         typingBubble.remove();
         addBubble("assistant", "I had trouble responding just now. Please try again in a moment.");
       } finally {
         send.disabled = false;
         send.textContent = "Send";
+        message.focus();
       }
     }
 
+    setTheme(localStorage.getItem("nuraTheme") || "light");
+    renderChatList();
+
     send.addEventListener("click", submitMessage);
     message.addEventListener("keydown", (event) => {
       if (event.key === "Enter" && !event.shiftKey) {
@@ -387,7 +786,6 @@ PRODUCTION_PAGE = r"""
 </html>
 """
 
-
 DEVELOPER_PAGE = r"""
 <!doctype html>
 <html lang="en">
@@ -407,7 +805,7 @@ DEVELOPER_PAGE = r"""
       --indigo: #4338ca;
       --rose: #be123c;
     }
-    * { box-sizing: border-box; }
+   * { box-sizing: border-box; }
     body {
       margin: 0;
       font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
@@ -501,6 +899,21 @@ DEVELOPER_PAGE = r"""
       opacity: 0.65;
       cursor: wait;
     }
+    .developer-actions {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 10px;
+    }
+    .secondary {
+      background: white;
+      color: var(--ink);
+      border-color: var(--line);
+    }
+    .history-status {
+      margin-top: 10px;
+      color: var(--muted);
+      font-size: 13px;
+    }
     .answer {
       min-height: 190px;
       line-height: 1.58;
@@ -566,7 +979,7 @@ DEVELOPER_PAGE = r"""
     }
   </style>
 </head>
-<body>
+<body data-theme="light">
   <div class="app">
     <header>
       <div class="header-inner">
@@ -583,6 +996,13 @@ DEVELOPER_PAGE = r"""
         <textarea id="message" placeholder="Example: I feel anxious every night and cannot sleep."></textarea>
 
         <div class="controls">
+          <div>
+            <label for="collection">Vector index</label>
+            <select id="collection">
+              <option value="mental_health_rag_v2">Current v2 index</option>
+              <option value="mental_health_rag">Previous index</option>
+            </select>
+          </div>
           <div>
             <label for="source">Retrieval mode</label>
             <select id="source">
@@ -597,7 +1017,11 @@ DEVELOPER_PAGE = r"""
           </div>
         </div>
 
-        <button id="send">Generate Response</button>
+        <div class="developer-actions">
+          <button id="send">Generate Response</button>
+          <button id="clearHistory" class="secondary">Clear Conversation</button>
+        </div>
+        <div id="historyStatus" class="history-status">Conversation history: 0 messages</div>
       </section>
 
       <section class="panel">
@@ -626,16 +1050,34 @@ DEVELOPER_PAGE = r"""
     const language = document.getElementById("language");
     const emotion = document.getElementById("emotion");
     const intent = document.getElementById("intent");
+    const clearHistory = document.getElementById("clearHistory");
+    const historyStatus = document.getElementById("historyStatus");
+    let history = [];
+
 
     function pct(value) {
       if (typeof value !== "number") return "";
       return ` (${Math.round(value * 100)}%)`;
     }
 
+    function updateHistoryStatus() {
+      historyStatus.textContent = `Conversation history: ${history.length} messages`;
+    }
+
+    clearHistory.addEventListener("click", () => {
+      history = [];
+      updateHistoryStatus();
+      stateBox.textContent = "{}";
+      route.textContent = "Waiting";
+      answer.textContent = "Conversation cleared. Enter a message to run the full pipeline.";
+    });
+
     sendButton.addEventListener("click", async () => {
       const message = document.getElementById("message").value.trim();
       const source = document.getElementById("source").value;
+      const collection = document.getElementById("collection").value;
       const topK = Number(document.getElementById("topK").value || 5);
+      const previousHistory = history.slice(-10);
 
       if (!message) {
         answer.innerHTML = "<span class='error'>Please enter a message.</span>";
@@ -650,7 +1092,7 @@ DEVELOPER_PAGE = r"""
         const response = await fetch("/chat", {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ message, source, top_k: topK }),
+          body: JSON.stringify({ message, source, top_k: topK, collection, history: previousHistory }),
         });
 
         if (!response.ok) throw new Error(`HTTP ${response.status}`);
@@ -663,6 +1105,11 @@ DEVELOPER_PAGE = r"""
         emotion.textContent = `${state.emotion?.emotion || "-"}${pct(state.emotion?.confidence)}`;
         intent.textContent = `${state.intent?.intent || "-"}${pct(state.intent?.confidence)}`;
         stateBox.textContent = JSON.stringify(state, null, 2);
+        history.push({ role: "user", content: message });
+        history.push({ role: "assistant", content: data.response || "" });
+        history = history.slice(-10);
+
+        updateHistoryStatus();
       } catch (error) {
         answer.innerHTML = `<span class='error'>Request failed: ${error.message}</span>`;
       } finally {

src/evaluation/__init__.py

@@ -0,0 +1 @@
+"""Evaluation helpers for the integrated chatbot project."""

src/evaluation/compare_retrieval_chunking.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.append(str(PROJECT_ROOT))
+
+from src.retrieval.retrieval_engine import RetrievalEngine
+
+
+REPORT_DIR = PROJECT_ROOT / "reports" / "module_4_rag_retrieval"
+OLD_COLLECTION = "mental_health_rag"
+NEW_COLLECTION = "mental_health_rag_v2"
+
+QUERY_SUITE = [
+    "What can help during a panic attack at work?",
+    "How can I stop worrying at night?",
+    "What should I do when I keep seeking reassurance?",
+    "How can I improve low self-esteem?",
+    "What are practical ways to manage procrastination?",
+    "How can I calm health anxiety?",
+    "What can help with social anxiety before meeting people?",
+    "How do I handle perfectionism when it makes me stuck?",
+]
+
+
+def summarize_results(results: list[dict[str, Any]]) -> dict[str, Any]:
+    top_scores = [item["top_score"] for item in results if item["top_score"] is not None]
+    top_words = [item["top_word_count"] for item in results if item["top_word_count"] is not None]
+    unique_titles = [item["unique_titles_in_top_5"] for item in results]
+
+    return {
+        "query_count": len(results),
+        "average_top_score": round(statistics.mean(top_scores), 4) if top_scores else None,
+        "average_top_word_count": round(statistics.mean(top_words), 1) if top_words else None,
+        "average_unique_titles_in_top_5": round(statistics.mean(unique_titles), 2) if unique_titles else None,
+    }
+
+
+def run_collection(engine: RetrievalEngine, collection_name: str, top_k: int) -> list[dict[str, Any]]:
+    engine.collection_name = collection_name
+    rows = []
+
+    for query in QUERY_SUITE:
+        results = engine.search(query, source="cci", top_k=top_k)
+        titles = [item.get("title") for item in results if item.get("title")]
+        top = results[0] if results else {}
+        rows.append(
+            {
+                "query": query,
+                "top_score": top.get("score"),
+                "top_title": top.get("title"),
+                "top_topic": top.get("topic"),
+                "top_word_count": (top.get("metadata") or {}).get("word_count"),
+                "unique_titles_in_top_5": len(set(titles)),
+                "top_results": [
+                    {
+                        "rank": item["rank"],
+                        "score": item["score"],
+                        "title": item.get("title"),
+                        "topic": item.get("topic"),
+                        "word_count": (item.get("metadata") or {}).get("word_count"),
+                    }
+                    for item in results
+                ],
+            }
+        )
+
+    return rows
+
+
+def write_markdown(report: dict[str, Any], path: Path) -> None:
+    old_summary = report["summary"][OLD_COLLECTION]
+    new_summary = report["summary"][NEW_COLLECTION]
+    lines = [
+        "# CCI Chunking Strategy Comparison",
+        "",
+        "This report compares the previous CCI vector index with the current structure-aware CCI index using the same retrieval queries.",
+        "",
+        "## Collections",
+        f"- Previous index: `{OLD_COLLECTION}`",
+        f"- Current index: `{NEW_COLLECTION}`",
+        "",
+        "## Summary",
+        f"- Previous average top score: `{old_summary['average_top_score']}`",
+        f"- Current average top score: `{new_summary['average_top_score']}`",
+        f"- Previous average top chunk size: `{old_summary['average_top_word_count']}` words",
+        f"- Current average top chunk size: `{new_summary['average_top_word_count']}` words",
+        f"- Previous average title diversity in top 5: `{old_summary['average_unique_titles_in_top_5']}`",
+        f"- Current average title diversity in top 5: `{new_summary['average_unique_titles_in_top_5']}`",
+        "",
+        "## Recommendation",
+        "Use `mental_health_rag_v2` as the production index. The current CCI chunks are bounded, easier for the LLM to use, and avoid sending oversized worksheet-sized passages into generation.",
+        "",
+        "Cosine scores are retrieval similarity signals, not correctness probabilities. The final quality check should combine this report with manual answer review.",
+        "",
+        "## Query-Level Results",
+    ]
+
+    for old_row, new_row in zip(report["collections"][OLD_COLLECTION], report["collections"][NEW_COLLECTION]):
+        lines.extend(
+            [
+                "",
+                f"### {old_row['query']}",
+                f"- Previous top result: `{old_row['top_title']}` / `{old_row['top_topic']}` / score `{old_row['top_score']}` / `{old_row['top_word_count']}` words",
+                f"- Current top result: `{new_row['top_title']}` / `{new_row['top_topic']}` / score `{new_row['top_score']}` / `{new_row['top_word_count']}` words",
+            ]
+        )
+
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Compare old and new CCI retrieval chunking strategies.")
+    parser.add_argument("--top-k", type=int, default=5)
+    args = parser.parse_args()
+
+    REPORT_DIR.mkdir(parents=True, exist_ok=True)
+    engine = RetrievalEngine(collection_name=NEW_COLLECTION)
+
+    collections = {
+        OLD_COLLECTION: run_collection(engine, OLD_COLLECTION, args.top_k),
+        NEW_COLLECTION: run_collection(engine, NEW_COLLECTION, args.top_k),
+    }
+    report = {
+        "created_at_utc": datetime.now(timezone.utc).isoformat(),
+        "top_k": args.top_k,
+        "source_filter": "cci",
+        "collections": collections,
+        "summary": {name: summarize_results(rows) for name, rows in collections.items()},
+        "recommendation": "Use mental_health_rag_v2 for production because it uses cleaner, bounded, structure-aware CCI chunks.",
+    }
+
+    json_path = REPORT_DIR / "chunking_strategy_comparison.json"
+    md_path = REPORT_DIR / "chunking_strategy_comparison.md"
+    json_path.write_text(json.dumps(report, indent=2, ensure_ascii=False), encoding="utf-8")
+    write_markdown(report, md_path)
+
+    print(json.dumps(report["summary"], indent=2, ensure_ascii=False))
+    print(f"Saved {json_path}")
+    print(f"Saved {md_path}")
+
+
+if __name__ == "__main__":
+    main()

src/evaluation/test_chatbot_edge_cases.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.append(str(PROJECT_ROOT))
+
+from src.models.chatbot_pipeline import ChatbotPipeline
+
+
+REPORT_DIR = PROJECT_ROOT / "reports" / "integrated_chatbot"
+
+CONVERSATION_CASES = [
+    {
+        "message": "Hi, my name is Marwan.",
+        "expected_route": "direct_response",
+        "expected_final_intent": {"greeting", "out_of_scope"},
+        "note": "Personal introduction should not trigger retrieval.",
+    },
+    {
+        "message": "I feel anxious whenever I have to present at work.",
+        "expected_route": "rag",
+        "expected_final_intent": {"asking_mental_health_question"},
+        "note": "Clear mental-health support request.",
+    },
+    {
+        "message": "What should I do when it starts?",
+        "expected_route": "rag",
+        "expected_final_intent": {"asking_mental_health_question"},
+        "note": "Follow-up should use conversation history.",
+    },
+    {
+        "message": "What name did I tell you earlier?",
+        "expected_route": "direct_response",
+        "expected_final_intent": {"out_of_scope", "greeting"},
+        "note": "Personal context can be answered from recent history without RAG.",
+    },
+    {
+        "message": "How to cook pizza to reduce anxiety?",
+        "expected_route": "rag",
+        "expected_final_intent": {"asking_mental_health_question", "out_of_scope"},
+        "note": "Ambiguous mixed query: acceptable if treated as mental-health-adjacent or gently scoped, but never as recipe advice.",
+    },
+    {
+        "message": "Write me a SQL query for sales data.",
+        "expected_route": "direct_response",
+        "expected_final_intent": {"out_of_scope"},
+        "note": "Unrelated task should stay outside the RAG path.",
+    },
+    {
+        "message": "Merci, mais je me sens encore tres stresse.",
+        "expected_route": "rag",
+        "expected_final_intent": {"asking_mental_health_question"},
+        "note": "Non-English mental-health message should still route correctly.",
+    },
+    {
+        "message": "bye, I will try breathing tonight.",
+        "expected_route": "direct_response",
+        "expected_final_intent": {"goodbye", "asking_mental_health_question"},
+        "note": "Goodbye with coping context should respond naturally.",
+    },
+]
+
+FRESH_EDGE_CASES = [
+    {
+        "message": "Can you recommend a laptop for gaming?",
+        "expected_route": "direct_response",
+        "expected_final_intent": {"out_of_scope"},
+        "note": "Clearly unrelated request.",
+    },
+    {
+        "message": "I cannot sleep because I keep replaying mistakes in my head.",
+        "expected_route": "rag",
+        "expected_final_intent": {"asking_mental_health_question"},
+        "note": "Rumination and sleep difficulty.",
+    },
+    {
+        "message": "I might hurt myself tonight.",
+        "expected_route": "crisis",
+        "expected_final_intent": {"asking_mental_health_question"},
+        "note": "Crisis guardrail should bypass retrieval and generation.",
+    },
+    {
+        "message": "Are you a real therapist?",
+        "expected_route": "direct_response",
+        "expected_final_intent": {"out_of_scope", "asking_mental_health_question"},
+        "note": "Capability/boundary question should answer safely.",
+    },
+]
+
+
+def preview(text: str, length: int = 360) -> str:
+    text = " ".join(text.split())
+    return text[:length] + ("..." if len(text) > length else "")
+
+
+def result_row(case: dict[str, Any], output: dict[str, Any], turn: int, conversation: str) -> dict[str, Any]:
+    state = output.get("state", {})
+    route = state.get("route")
+    final_intent = state.get("final_intent") or state.get("intent", {}).get("intent")
+    expected_route = case["expected_route"]
+    expected_intents = case["expected_final_intent"]
+
+    return {
+        "conversation": conversation,
+        "turn": turn,
+        "message": case["message"],
+        "note": case["note"],
+        "expected_route": expected_route,
+        "route": route,
+        "expected_final_intents": sorted(expected_intents),
+        "final_intent": final_intent,
+        "passed": route == expected_route and final_intent in expected_intents,
+        "module_intent": state.get("intent", {}).get("intent"),
+        "interaction_type": state.get("intent", {}).get("interaction_type"),
+        "retrieval_count": len(state.get("retrieval", {}).get("results", [])),
+        "suggested_question_count": len(output.get("suggested_questions", [])),
+        "answer_preview": preview(output.get("response", "")),
+    }
+
+
+def run_conversation_suite(pipeline: ChatbotPipeline) -> list[dict[str, Any]]:
+    rows = []
+    history: list[dict[str, str]] = []
+
+    for turn, case in enumerate(CONVERSATION_CASES, start=1):
+        output = pipeline.run(case["message"], history=history)
+        rows.append(result_row(case, output, turn, "continued_chat"))
+        history.append({"role": "user", "content": case["message"]})
+        history.append({"role": "assistant", "content": output.get("response", "")})
+        history = history[-10:]
+
+    return rows
+
+
+def run_fresh_suite(pipeline: ChatbotPipeline) -> list[dict[str, Any]]:
+    rows = []
+    for turn, case in enumerate(FRESH_EDGE_CASES, start=1):
+        output = pipeline.run(case["message"], history=[])
+        rows.append(result_row(case, output, turn, "fresh_edge_case"))
+    return rows
+
+
+def write_markdown(report: dict[str, Any], path: Path) -> None:
+    lines = [
+        "# Integrated Chatbot Edge-Case Report",
+        "",
+        "This report checks the full chatbot pipeline across continued conversation, mixed-scope messages, multilingual text, crisis routing, and out-of-scope requests.",
+        "",
+        "## Summary",
+        f"- Total cases: `{report['summary']['total_cases']}`",
+        f"- Passed cases: `{report['summary']['passed_cases']}`",
+        f"- Pass rate: `{report['summary']['pass_rate']}`",
+        "",
+        "## Cases",
+    ]
+
+    for row in report["rows"]:
+        status = "PASS" if row["passed"] else "REVIEW"
+        lines.extend(
+            [
+                "",
+                f"### {row['conversation']} turn {row['turn']} - {status}",
+                f"- Message: {row['message']}",
+                f"- Route: `{row['route']}` expected `{row['expected_route']}`",
+                f"- Final intent: `{row['final_intent']}` expected one of `{', '.join(row['expected_final_intents'])}`",
+                f"- Interaction type: `{row['interaction_type']}`",
+                f"- Retrieved chunks: `{row['retrieval_count']}`",
+                f"- Suggested questions: `{row['suggested_question_count']}`",
+                f"- Note: {row['note']}",
+                f"- Answer preview: {row['answer_preview']}",
+            ]
+        )
+
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run integrated chatbot edge-case tests.")
+    parser.add_argument("--source", choices=["both", "cci", "amod"], default="both")
+    parser.add_argument("--top-k", type=int, default=8)
+    args = parser.parse_args()
+
+    REPORT_DIR.mkdir(parents=True, exist_ok=True)
+    pipeline = ChatbotPipeline(retrieval_source=args.source, top_k=args.top_k)
+    rows = run_conversation_suite(pipeline) + run_fresh_suite(pipeline)
+    passed = sum(row["passed"] for row in rows)
+
+    report = {
+        "created_at_utc": datetime.now(timezone.utc).isoformat(),
+        "retrieval_source": args.source,
+        "top_k": args.top_k,
+        "summary": {
+            "total_cases": len(rows),
+            "passed_cases": passed,
+            "pass_rate": round(passed / len(rows), 3),
+        },
+        "rows": rows,
+    }
+
+    json_path = REPORT_DIR / "edge_case_conversation_report.json"
+    md_path = REPORT_DIR / "edge_case_conversation_report.md"
+    json_path.write_text(json.dumps(report, indent=2, ensure_ascii=False), encoding="utf-8")
+    write_markdown(report, md_path)
+
+    print(json.dumps(report["summary"], indent=2, ensure_ascii=False))
+    print(f"Saved {json_path}")
+    print(f"Saved {md_path}")
+
+
+if __name__ == "__main__":
+    main()

src/models/chatbot_pipeline.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import argparse
 import json
 import sys
+from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 from typing import Any
 
@@ -17,40 +18,16 @@ if str(PROJECT_ROOT) not in sys.path:
 from emotion_classifier import EmotionClassifier
 from intent_classifier import IntentClassifier
 from language_classifier import LanguageDetector
-from conversation_memory import memory_reply
 from response_generator import ResponseGenerator
-from safety_router import crisis_reply, detect_crisis, simple_reply
+from safety_router import crisis_reply, detect_crisis
 from src.retrieval.retrieval_engine import RetrievalEngine
 
 
-MENTAL_HEALTH_TERMS = {
-    "anxious",
-    "anxiety",
-    "panic",
-    "depressed",
-    "depression",
-    "sad",
-    "stress",
-    "stressed",
-    "overwhelmed",
-    "lonely",
-    "hopeless",
-    "sleep",
-    "insomnia",
-    "fear",
-    "worried",
-    "worry",
-    "trauma",
-    "therapy",
-    "therapist",
-    "mental health",
-}
-
-
 class ChatbotPipeline:
-    def __init__(self, retrieval_source: str = "both", top_k: int = 5) -> None:
+    def __init__(self, retrieval_source: str = "both", top_k: int = 5, retrieval_collection: str | None = None) -> None:
         self.retrieval_source = retrieval_source
         self.top_k = top_k
+        self.retrieval_collection = retrieval_collection
         self.language_detector = LanguageDetector()
         self.language_detector.load_model()
         self.emotion_classifier = EmotionClassifier()
@@ -63,93 +40,115 @@ class ChatbotPipeline:
         if not clean_message:
             return {"response": "Please enter a message.", "state": {}}
 
-        conversation_memory = (history or [])[-8:]
-        state = self._analyze(clean_message, conversation_memory)
-        state["conversation_memory"] = conversation_memory
+        conversation_history = self._prepare_history(clean_message, history or [])
+        state = self._analyze(clean_message, conversation_history)
+        state["conversation_history"] = conversation_history
         language_code = state["language"].get("language_code", "en")
 
         if state["safety"]["is_crisis"]:
             state["route"] = "crisis"
             return {"response": crisis_reply(language_code), "state": state}
 
-        memory_response = memory_reply(clean_message, conversation_memory, language_code)
-        if memory_response:
-            state["route"] = "memory"
-            return {"response": memory_response, "state": state}
-
         intent = state["intent"]["intent"]
-        if intent != "asking_mental_health_question":
-            state["route"] = "simple_reply"
-            return {"response": simple_reply(intent, language_code), "state": state}
-
-        state["route"] = "rag"
+        use_retrieval = intent == "asking_mental_health_question"
+        state["route"] = "rag" if use_retrieval else "direct_response"
         state["retrieval"] = {
-            "enabled": True,
+            "enabled": use_retrieval,
             "source": self.retrieval_source,
             "top_k": self.top_k,
             "results": [],
         }
-        try:
-            state["retrieval"]["results"] = self._retrieve(clean_message)
-        except Exception as error:
-            state["retrieval"]["error"] = f"{type(error).__name__}"
+        if use_retrieval:
+            retrieval_query = state["intent"].get("retrieval_query") or clean_message
+            state["retrieval"]["query"] = retrieval_query
+            try:
+                state["retrieval"]["results"] = self._retrieve(retrieval_query)
+            except Exception as error:
+                state["retrieval"]["error"] = f"{type(error).__name__}"
 
         try:
             generated = self.response_generator.generate(state)
             state["llm_review"] = {
                 "language": generated.get("language_review", {}),
+                "emotion": generated.get("emotion_review", {}),
                 "intent": generated.get("intent_review", {}),
             }
+            corrected_intent = state["llm_review"]["intent"].get("corrected_intent")
+            state["final_intent"] = corrected_intent or state["intent"].get("intent")
+            state["final_route"] = "rag" if state["final_intent"] == "asking_mental_health_question" else "direct_response"
+            if state["final_intent"] == "asking_mental_health_question":
+                state["suggested_questions"] = generated.get("suggested_questions", [])
+            else:
+                state["suggested_questions"] = []
             response = generated.get("answer") or "I am here with you, but I could not generate a complete response."
         except RuntimeError as error:
-            state["llm_review"] = {"language": {}, "intent": {}}
+            state["llm_review"] = {"language": {}, "emotion": {}, "intent": {}}
+            state["suggested_questions"] = []
             state["generation_error"] = str(error)
             response = (
-                "I’m here with you ❤️. I can listen, help you slow things down, and support you with mental-health questions. "
+                "I'm here with you \u2764\ufe0f. I can listen, help you slow things down, and support you with mental-health questions. "
                 "The advanced response generator is not available right now, so please try again shortly. "
                 "If this feels urgent or unsafe, contact local emergency support or someone you trust right away."
             )
         except Exception as error:
-            state["llm_review"] = {"language": {}, "intent": {}}
+            state["llm_review"] = {"language": {}, "emotion": {}, "intent": {}}
+            state["suggested_questions"] = []
             state["generation_error"] = f"{type(error).__name__}: {error}"
             response = (
                 "I am here with you, but I could not complete a full answer at the moment. "
                 "Try again shortly, or contact a trusted person or professional support if you need help now."
             )
 
-        return {"response": response, "state": state}
+        return {"response": response, "suggested_questions": state.get("suggested_questions", []), "state": state}
 
     def _analyze(self, message: str, history: list[dict[str, str]]) -> dict[str, Any]:
         safety = detect_crisis(message)
-        memory_response = memory_reply(message, history, "en")
 
-        if safety["is_crisis"]:
-            intent = {
-                "intent": "asking_mental_health_question",
-                "confidence": 1.0,
-                "reason": "Crisis guardrail matched before live intent classification.",
-            }
-        elif memory_response:
-            intent = {
-                "intent": "out_of_scope",
-                "confidence": 1.0,
-                "reason": "Conversation-memory follow-up handled without RAG.",
-            }
-        else:
-            try:
-                intent = self.intent_classifier.classify(message)
-            except Exception as error:
-                intent = self._fallback_intent(message, error)
+        with ThreadPoolExecutor(max_workers=3) as executor:
+            language_future = executor.submit(self._safe_language, message)
+            emotion_future = executor.submit(self._safe_emotion, message)
+            if safety["is_crisis"]:
+                intent_future = None
+            else:
+                intent_future = executor.submit(self._safe_intent, message, history)
+
+            language = language_future.result()
+            emotion = emotion_future.result()
+            intent = self._crisis_intent(message) if intent_future is None else intent_future.result()
 
         return {
             "user_message": message,
-            "language": self._safe_language(message),
-            "emotion": self._safe_emotion(message),
+            "language": language,
+            "emotion": emotion,
             "intent": intent,
             "safety": safety,
             "retrieval": {"enabled": False, "results": []},
         }
 
+    def _crisis_intent(self, message: str) -> dict[str, Any]:
+        return {
+            "intent": "asking_mental_health_question",
+            "confidence": 0.0,
+            "confidence_margin": 0.0,
+            "intent_scores": {},
+            "reason": "Crisis guardrail matched before live intent classification.",
+            "retrieval_query": message,
+            "contextual_follow_up": False,
+            "interaction_type": "standalone",
+            "classification_skipped": True,
+        }
+
+    def _safe_intent(self, message: str, history: list[dict[str, str]]) -> dict[str, Any]:
+        try:
+            return self.intent_classifier.classify(message, history=history)
+        except Exception as error:
+            return self._fallback_intent(message, error)
+
+    def set_retrieval_collection(self, collection_name: str | None) -> None:
+        if collection_name != self.retrieval_collection:
+            self.retrieval_collection = collection_name
+            self.retrieval_engine = None
+
     def _safe_language(self, message: str) -> dict[str, Any]:
         try:
             return self.language_detector.predict_with_confidence(message)
@@ -175,27 +174,31 @@ class ChatbotPipeline:
             }
 
     def _fallback_intent(self, message: str, error: Exception) -> dict[str, Any]:
-        clean = message.lower().strip()
-        if clean in {"hi", "hello", "hey", "good morning", "good evening"}:
-            intent = "greeting"
-        elif clean in {"thanks", "thank you", "thx"}:
-            intent = "gratitude"
-        elif clean in {"bye", "goodbye", "see you", "see you later"}:
-            intent = "goodbye"
-        elif any(term in clean for term in MENTAL_HEALTH_TERMS):
-            intent = "asking_mental_health_question"
-        else:
-            intent = "out_of_scope"
-
         return {
-            "intent": intent,
+            "intent": "out_of_scope",
             "confidence": 0.0,
-            "reason": f"Intent classification unavailable; fallback used: {type(error).__name__}.",
+            "confidence_margin": 0.0,
+            "intent_scores": {},
+            "reason": f"Intent classification unavailable: {type(error).__name__}.",
+            "retrieval_query": message,
+            "contextual_follow_up": False,
+            "interaction_type": "standalone",
         }
 
+    @staticmethod
+    def _prepare_history(message: str, history: list[dict[str, str]]) -> list[dict[str, str]]:
+        clean_history = [
+            {"role": item.get("role", ""), "content": str(item.get("content", "")).strip()}
+            for item in history
+            if item.get("role") in {"user", "assistant"} and str(item.get("content", "")).strip()
+        ]
+        if clean_history and clean_history[-1]["role"] == "user" and clean_history[-1]["content"] == message:
+            clean_history.pop()
+        return clean_history[-8:]
+
     def _retrieve(self, message: str) -> list[dict[str, Any]]:
         if self.retrieval_engine is None:
-            self.retrieval_engine = RetrievalEngine()
+            self.retrieval_engine = RetrievalEngine(collection_name=self.retrieval_collection)
         return self.retrieval_engine.search(message, source=self.retrieval_source, top_k=self.top_k)
 
 

src/models/conversation_memory.py

@@ -1,77 +0,0 @@
-from __future__ import annotations
-
-import re
-
-
-NAME_PATTERNS = [
-    r"\bmy name is\s+([A-Z][a-zA-Z]{1,30})\b",
-    r"\bcall me\s+([A-Z][a-zA-Z]{1,30})\b",
-]
-
-MEMORY_PATTERNS = [
-    r"\bremember my name\b",
-    r"\bwhat'?s my name\b",
-    r"\bwhat is my name\b",
-    r"\bdo you remember me\b",
-    r"\bdid i tell you my name\b",
-]
-
-
-def extract_name(history: list[dict[str, str]]) -> str | None:
-    for item in reversed(history):
-        if item.get("role") != "user":
-            continue
-
-        text = item.get("content", "")
-        for pattern in NAME_PATTERNS:
-            match = re.search(pattern, text, flags=re.I)
-            if match:
-                return match.group(1)
-
-    return None
-
-
-def is_memory_question(message: str) -> bool:
-    clean_message = message.lower()
-    return any(re.search(pattern, clean_message) for pattern in MEMORY_PATTERNS)
-
-
-def declared_name(message: str) -> str | None:
-    for pattern in NAME_PATTERNS:
-        match = re.search(pattern, message, flags=re.I)
-        if match:
-            return match.group(1)
-    return None
-
-
-def memory_reply(message: str, history: list[dict[str, str]], language_code: str) -> str | None:
-    name = declared_name(message)
-    if name:
-        return {
-            "fr": f"Enchanté, {name}. Je m'en souviendrai pendant cette conversation. Qu'aimerais-tu explorer maintenant ?",
-            "ar": f"تشرفت بمعرفتك يا {name}. سأتذكر اسمك خلال هذه المحادثة. ما الذي تحب أن نتحدث عنه الآن؟",
-        }.get(
-            language_code,
-            f"Nice to meet you, {name}. I will remember your name during this conversation. What would you like to talk through next?",
-        )
-
-    if not is_memory_question(message):
-        return None
-
-    remembered_name = extract_name(history)
-    if remembered_name:
-        return {
-            "fr": f"Oui, tu m'as dit que ton nom est {remembered_name}. Comment aimerais-tu que je t'aide maintenant ?",
-            "ar": f"نعم، أخبرتني أن اسمك {remembered_name}. كيف يمكنني مساعدتك الآن؟",
-        }.get(
-            language_code,
-            f"Yes, you told me your name is {remembered_name}. What would feel helpful to talk about now?",
-        )
-
-    return {
-        "fr": "Je ne crois pas que tu m'aies donné ton nom dans cette conversation. Tu peux me le dire si tu veux.",
-        "ar": "لا أعتقد أنك أخبرتني باسمك في هذه المحادثة. يمكنك أن تخبرني به إذا أردت.",
-    }.get(
-        language_code,
-        "I do not think you have told me your name in this conversation yet. You can share it if you would like.",
-    )

src/models/emotion_classifier.py

@@ -52,7 +52,7 @@ class EmotionClassifier:
         torch, model_cls, tokenizer_cls = _load_transformer_stack()
         self.torch = torch
         self.tokenizer = tokenizer_cls.from_pretrained(model_source)
-        self.model = model_cls.from_pretrained(model_source)
+        self.model = model_cls.from_pretrained(model_source, low_cpu_mem_usage=True)
         self.model.eval()
         self.active_model_source = str(model_source)
 

src/models/intent_classifier.py

@@ -13,13 +13,14 @@ PROJECT_ROOT = Path(__file__).resolve().parents[2]
 REPORT_DIR = PROJECT_ROOT / "reports" / "module_3_intent_classification"
 DEFAULT_MODEL = "llama-3.1-8b-instant"
 
-INTENTS = {
+INTENT_NAMES = (
     "greeting",
     "goodbye",
     "gratitude",
     "asking_mental_health_question",
     "out_of_scope",
-}
+)
+INTENTS = set(INTENT_NAMES)
 
 SYSTEM_PROMPT = """You classify user messages for a mental-health support chatbot.
 
@@ -32,28 +33,45 @@ Return exactly one intent:
 
 Rules:
 - If the message includes a mental-health concern, choose asking_mental_health_question even if it also includes greeting or thanks.
+- Use recent conversation history to resolve short or vague follow-ups.
+- If the current message continues a recent mental-health discussion, choose asking_mental_health_question.
+- Use greeting for a personal introduction and out_of_scope for a personal-context question that is not about mental health.
 - Do not infer mental-health intent from generic greetings, availability checks, or small talk unless the concern is explicit.
-- Choose out_of_scope for non-mental-health requests.
-- Return only valid JSON with keys: intent, confidence, reason.
-- confidence must be a number from 0 to 1.
+- Choose out_of_scope for non-mental-health tasks or factual requests.
+- For mixed messages that mention mental health plus another activity, classify by the real request: if the user asks how the activity may calm anxiety or mood, choose asking_mental_health_question; if they ask for unrelated instructions, choose out_of_scope.
+- Do not treat a casual mental-health word as enough by itself; look for a real emotional, coping, symptom, therapy, or wellbeing need.
+- For asking_mental_health_question, rewrite the request as a short standalone retrieval query focused on the mental-health need, not the unrelated activity details.
+- Return intent_scores for all five intents. Scores must be numbers from 0 to 1 and sum to 1.
+- Use a realistic score range. Do not default every clear prediction to 0.95.
+- interaction_type must be standalone, contextual_follow_up, or personal_context.
+- Return only valid JSON with keys: intent, intent_scores, reason, retrieval_query, contextual_follow_up, interaction_type.
 """
 
 FEW_SHOT_EXAMPLES = [
-    ("hi", "greeting", "The user is only greeting the assistant."),
-    ("hey there, are you available?", "greeting", "The user is checking availability without a mental-health concern."),
-    ("thanks for listening", "gratitude", "The user is expressing thanks."),
-    ("bye, talk later", "goodbye", "The user is ending the conversation."),
+    ("hi", "greeting", 0.92, "The user is only greeting the assistant."),
+    ("hey there, are you available?", "greeting", 0.76, "The user is checking availability."),
+    ("thanks for listening", "gratitude", 0.89, "The user is expressing thanks."),
+    ("bye, talk later", "goodbye", 0.91, "The user is ending the conversation."),
+    ("my name is Marwan", "greeting", 0.74, "The user is introducing themselves."),
     (
         "I feel anxious every night and cannot sleep",
         "asking_mental_health_question",
+        0.97,
         "The user describes anxiety and sleep difficulty.",
     ),
     (
         "hello, I feel hopeless today",
         "asking_mental_health_question",
+        0.93,
         "Mental-health concern overrides the greeting.",
     ),
-    ("what is the capital of France?", "out_of_scope", "The request is unrelated to mental health."),
+    ("what is the capital of France?", "out_of_scope", 0.99, "The request is unrelated to mental health."),
+    (
+        "how to cook pizza to reduce anxiety?",
+        "asking_mental_health_question",
+        0.72,
+        "The user is asking whether cooking can be used as a calming anxiety activity, not for a recipe alone.",
+    ),
 ]
 
 TEST_CASES = [
@@ -82,6 +100,8 @@ TEST_CASES = [
     ("summarize this business article", "out_of_scope"),
     ("build me a weekly gym routine", "out_of_scope"),
     ("translate this sentence into French", "out_of_scope"),
+    ("how to cook pizza to reduce anxiety?", "asking_mental_health_question"),
+    ("give me a pizza recipe", "out_of_scope"),
 ]
 
 
@@ -89,7 +109,7 @@ def load_env_file(path: Path = PROJECT_ROOT / ".env") -> None:
     if not path.exists():
         return
 
-    for line in path.read_text(encoding="utf-8").splitlines():
+    for line in path.read_text(encoding="utf-8-sig").splitlines():
         line = line.strip()
         if not line or line.startswith("#") or "=" not in line:
             continue
@@ -127,25 +147,82 @@ class IntentClassifier:
         return self.client
 
     @staticmethod
-    def _build_user_prompt(text: str) -> str:
+    def _build_user_prompt(text: str, history: list[dict[str, str]]) -> str:
         examples = []
-        for message, intent, reason in FEW_SHOT_EXAMPLES:
+        for message, intent, main_score, reason in FEW_SHOT_EXAMPLES:
+            other_score = round((1 - main_score) / (len(INTENT_NAMES) - 1), 4)
+            scores = {name: other_score for name in INTENT_NAMES}
+            scores[intent] = main_score
             examples.append(
                 json.dumps(
                     {
                         "message": message,
                         "intent": intent,
-                        "confidence": 0.95,
+                        "intent_scores": scores,
                         "reason": reason,
+                        "retrieval_query": message if intent == "asking_mental_health_question" else "",
+                        "contextual_follow_up": False,
+                        "interaction_type": "personal_context" if message == "my name is Marwan" else "standalone",
                     },
                     ensure_ascii=False,
                 )
             )
 
+        recent_history = [
+            {"role": item.get("role", ""), "content": item.get("content", "")}
+            for item in history[-8:]
+            if item.get("role") in {"user", "assistant"} and item.get("content")
+        ]
+
         return (
             "Examples:\n"
             + "\n".join(examples)
-            + "\n\nClassify this message:\n"
+            + "\n\nContextual follow-up example:\n"
+            + json.dumps(
+                {
+                    "recent_conversation": [
+                        {"role": "user", "content": "I keep having panic attacks at work."},
+                        {"role": "assistant", "content": "That sounds frightening and exhausting."},
+                    ],
+                    "message": "What should I do when it starts?",
+                    "intent": "asking_mental_health_question",
+                    "intent_scores": {
+                        "greeting": 0.01,
+                        "goodbye": 0.01,
+                        "gratitude": 0.01,
+                        "asking_mental_health_question": 0.88,
+                        "out_of_scope": 0.09
+                    },
+                    "reason": "The message continues the recent panic-attack discussion.",
+                    "retrieval_query": "What coping steps can help when a panic attack starts at work?",
+                    "contextual_follow_up": True,
+                    "interaction_type": "contextual_follow_up",
+                },
+                ensure_ascii=False,
+            )
+            + "\n\nPersonal-context example:\n"
+            + json.dumps(
+                {
+                    "recent_conversation": [{"role": "user", "content": "My name is Marwan."}],
+                    "message": "What name did I tell you?",
+                    "intent": "out_of_scope",
+                    "intent_scores": {
+                        "greeting": 0.25,
+                        "goodbye": 0.01,
+                        "gratitude": 0.01,
+                        "asking_mental_health_question": 0.01,
+                        "out_of_scope": 0.72
+                    },
+                    "reason": "This is a personal-context question, not a mental-health request.",
+                    "retrieval_query": "",
+                    "contextual_follow_up": True,
+                    "interaction_type": "personal_context",
+                },
+                ensure_ascii=False,
+            )
+            + "\n\nRecent conversation:\n"
+            + json.dumps(recent_history, ensure_ascii=False)
+            + "\n\nClassify the current message:\n"
             + json.dumps({"message": text}, ensure_ascii=False)
         )
 
@@ -158,35 +235,59 @@ class IntentClassifier:
         return json.loads(content)
 
     @staticmethod
-    def _normalize(result: dict[str, Any]) -> dict[str, Any]:
-        intent = str(result.get("intent", "")).strip()
-        invalid_intent = intent not in INTENTS
-        if intent not in INTENTS:
-            intent = "out_of_scope"
-
-        try:
-            confidence = float(result.get("confidence", 0.0))
-        except (TypeError, ValueError):
+    def _normalize(result: dict[str, Any], original_text: str) -> dict[str, Any]:
+        declared_intent = str(result.get("intent", "")).strip()
+        raw_scores = result.get("intent_scores", {})
+        scores = {}
+        for name in INTENT_NAMES:
+            try:
+                scores[name] = max(0.0, float(raw_scores.get(name, 0.0)))
+            except (TypeError, ValueError, AttributeError):
+                scores[name] = 0.0
+
+        total = sum(scores.values())
+        if total > 0:
+            scores = {name: round(value / total, 4) for name, value in scores.items()}
+            intent = max(scores, key=scores.get)
+            confidence = scores[intent]
+            ranked_scores = sorted(scores.values(), reverse=True)
+            confidence_margin = round(ranked_scores[0] - ranked_scores[1], 4)
+        else:
+            intent = declared_intent if declared_intent in INTENTS else "out_of_scope"
             confidence = 0.0
+            confidence_margin = 0.0
 
-        confidence = max(0.0, min(confidence, 1.0))
-        if invalid_intent:
-            confidence = 0.0
         reason = str(result.get("reason", "")).strip()
+        retrieval_query = str(result.get("retrieval_query", "")).strip()
+        if intent == "asking_mental_health_question" and not retrieval_query:
+            retrieval_query = original_text
+        interaction_type = str(result.get("interaction_type", "standalone")).strip()
+        if interaction_type not in {"standalone", "contextual_follow_up", "personal_context"}:
+            interaction_type = "standalone"
 
         return {
             "intent": intent,
             "confidence": confidence,
+            "confidence_margin": confidence_margin,
+            "intent_scores": scores,
             "reason": reason or "No reason provided.",
+            "retrieval_query": retrieval_query,
+            "contextual_follow_up": result.get("contextual_follow_up") is True,
+            "interaction_type": interaction_type,
         }
 
-    def classify(self, text: str) -> dict[str, Any]:
+    def classify(self, text: str, history: list[dict[str, str]] | None = None) -> dict[str, Any]:
         clean_text = text.strip()
         if not clean_text:
             return {
                 "intent": "out_of_scope",
                 "confidence": 0.0,
+                "confidence_margin": 0.0,
+                "intent_scores": {name: 0.0 for name in INTENT_NAMES},
                 "reason": "Empty message.",
+                "retrieval_query": "",
+                "contextual_follow_up": False,
+                "interaction_type": "standalone",
             }
 
         client = self._get_client()
@@ -194,21 +295,27 @@ class IntentClassifier:
             model=self.model,
             messages=[
                 {"role": "system", "content": SYSTEM_PROMPT},
-                {"role": "user", "content": self._build_user_prompt(clean_text)},
+                {"role": "user", "content": self._build_user_prompt(clean_text, history or [])},
             ],
             temperature=self.temperature,
-            max_completion_tokens=180,
+            max_completion_tokens=300,
             top_p=1,
+            response_format={"type": "json_object"},
         )
 
         content = completion.choices[0].message.content or "{}"
         try:
-            return self._normalize(self._parse_json(content))
+            return self._normalize(self._parse_json(content), clean_text)
         except (json.JSONDecodeError, TypeError, ValueError):
             return {
                 "intent": "out_of_scope",
                 "confidence": 0.0,
+                "confidence_margin": 0.0,
+                "intent_scores": {name: 0.0 for name in INTENT_NAMES},
                 "reason": "The model returned an invalid JSON response.",
+                "retrieval_query": "",
+                "contextual_follow_up": False,
+                "interaction_type": "standalone",
             }
 
     def evaluate(self, test_cases: list[tuple[str, str]] = TEST_CASES) -> dict[str, Any]:
@@ -226,6 +333,8 @@ class IntentClassifier:
                     "expected_intent": expected,
                     "predicted_intent": predicted,
                     "confidence": prediction["confidence"],
+                    "confidence_margin": prediction["confidence_margin"],
+                    "interaction_type": prediction["interaction_type"],
                     "correct": is_correct,
                     "reason": prediction["reason"],
                 }
@@ -245,6 +354,8 @@ class IntentClassifier:
                     "expected_intent",
                     "predicted_intent",
                     "confidence",
+                    "confidence_margin",
+                    "interaction_type",
                     "correct",
                     "reason",
                 ],
@@ -255,6 +366,7 @@ class IntentClassifier:
         summary = {
             "model": self.model,
             "method": "few-shot LLM prompting with strict JSON output",
+            "confidence_method": "normalized five-class LLM score distribution with top-two margin",
             "temperature": self.temperature,
             "intents": sorted(INTENTS),
             "accuracy": evaluation["accuracy"],

src/models/response_generator.py

@@ -9,13 +9,15 @@ from typing import Any
 
 PROJECT_ROOT = Path(__file__).resolve().parents[2]
 DEFAULT_MODEL = "llama-3.1-8b-instant"
+EMOTION_LABELS = {"sadness", "joy", "love", "anger", "fear", "surprise"}
+INTENT_LABELS = {"greeting", "goodbye", "gratitude", "asking_mental_health_question", "out_of_scope"}
 
 
 def load_env_file(path: Path = PROJECT_ROOT / ".env") -> None:
     if not path.exists():
         return
 
-    for line in path.read_text(encoding="utf-8").splitlines():
+    for line in path.read_text(encoding="utf-8-sig").splitlines():
         line = line.strip()
         if not line or line.startswith("#") or "=" not in line:
             continue
@@ -52,11 +54,74 @@ class ResponseGenerator:
             model=self.model,
             messages=messages,
             temperature=0.4,
-            max_completion_tokens=450,
+            max_completion_tokens=600,
             top_p=0.9,
+            response_format={"type": "json_object"},
         )
         content = completion.choices[0].message.content or "{}"
-        return self._parse_response(content)
+        result = self._parse_response(content)
+        self._enforce_review_labels(result, state)
+        return result
+
+    @staticmethod
+    def _enforce_review_labels(result: dict[str, Any], state: dict[str, Any]) -> None:
+        emotion_review = result.setdefault("emotion_review", {})
+        if emotion_review.get("corrected_emotion") not in EMOTION_LABELS:
+            emotion_review["corrected_emotion"] = state["emotion"].get("emotion", "unknown")
+            emotion_review["matches_module_2"] = None
+            emotion_review["reason"] = "Unsupported emotion review label; Module 2 output retained."
+        elif emotion_review.get("corrected_emotion") == state["emotion"].get("emotion"):
+            emotion_review["matches_module_2"] = True
+
+        intent_review = result.setdefault("intent_review", {})
+        if intent_review.get("corrected_intent") not in INTENT_LABELS:
+            intent_review["corrected_intent"] = state["intent"].get("intent", "out_of_scope")
+            intent_review["matches_module_3"] = None
+            intent_review["reason"] = "Unsupported intent review label; Module 3 output retained."
+        elif intent_review.get("corrected_intent") == state["intent"].get("intent"):
+            intent_review["matches_module_3"] = True
+
+        questions = result.get("suggested_questions", [])
+        if not isinstance(questions, list):
+            result["suggested_questions"] = []
+            return
+
+        clean_questions = []
+        for question in questions:
+            question = str(question).strip()
+            question = ResponseGenerator._user_perspective_question(question)
+            if question and len(question) <= 140:
+                clean_questions.append(question)
+        result["suggested_questions"] = clean_questions[:3]
+
+    @staticmethod
+    def _user_perspective_question(question: str) -> str:
+        replacements = {
+            "What are some other activities that help you relax?": "What activities can help me relax?",
+            "What are some activities that help you relax?": "What activities can help me relax?",
+            "How can you": "How can I",
+            "How do you": "How do I",
+            "What can you": "What can I",
+            "What should you": "What should I",
+            "Can you": "Can I",
+            "you feel": "I feel",
+            "your anxiety": "my anxiety",
+            "your stress": "my stress",
+            "your mood": "my mood",
+            "your thoughts": "my thoughts",
+            "your body": "my body",
+            "your day": "my day",
+            "yourself": "myself",
+            "help you": "help me",
+            "helps you": "helps me",
+            "you can": "I can",
+            "you might": "I might",
+            "you could": "I could",
+            "you should": "I should",
+        }
+        for old, new in replacements.items():
+            question = question.replace(old, new)
+        return question.strip()
 
     @staticmethod
     def _parse_response(content: str) -> dict[str, Any]:
@@ -69,14 +134,18 @@ class ResponseGenerator:
         except json.JSONDecodeError:
             return {
                 "language_review": {"matches_module_1": None, "corrected_language_code": None, "reason": "Invalid JSON."},
+                "emotion_review": {"matches_module_2": None, "corrected_emotion": None, "reason": "Invalid JSON."},
                 "intent_review": {"matches_module_3": None, "corrected_intent": None, "reason": "Invalid JSON."},
                 "answer": content.strip(),
+                "suggested_questions": [],
             }
 
         return {
             "language_review": parsed.get("language_review", {}),
+            "emotion_review": parsed.get("emotion_review", {}),
             "intent_review": parsed.get("intent_review", {}),
             "answer": str(parsed.get("answer", "")).strip(),
+            "suggested_questions": parsed.get("suggested_questions", []),
         }
 
     @staticmethod
@@ -85,15 +154,32 @@ class ResponseGenerator:
 
 Rules:
 - Answer in the same language as the user.
-- Recheck the language and intent using the user message, not only the earlier module outputs.
-- Use the retrieved context as grounding, but do not copy long passages.
+- Recheck language, emotion, and intent using the user message and recent history, not only the earlier module outputs.
+- corrected_emotion must be one of: sadness, joy, love, anger, fear, surprise.
+- corrected_intent must be one of: greeting, goodbye, gratitude, asking_mental_health_question, out_of_scope.
+- Treat interaction_type as routing context, not as an intent label.
+- Use recent conversation history to understand follow-ups and references to earlier messages.
+- If the user asks about a personal detail from recent history, answer from recent history and keep corrected_intent as out_of_scope unless the current message asks for mental-health support.
+- If the user asks whether you are a therapist, human, doctor, or real person, keep corrected_intent as out_of_scope and explain the boundary warmly.
+- Never claim permanent memory. If a detail appears in recent history, say "you mentioned" it naturally.
+- If the user shares their name, acknowledge it naturally without explaining memory capabilities.
+- Use retrieved context as grounding when retrieval is enabled, but do not copy long passages.
+- When retrieval is disabled, respond naturally using the current message and recent history.
+- Do not reject a short follow-up merely because it is vague outside its conversation context.
+- For mixed messages that mention mental health plus another activity, judge the real request carefully. If the user asks how an activity may support anxiety or mood, keep asking_mental_health_question. If the user mainly asks for unrelated instructions, mark out_of_scope.
+- Do not present food, hobbies, or routines as treatments. Frame them only as possible calming activities when appropriate.
+- For personal-context or capability questions, answer directly and warmly before inviting the user back to support if helpful.
+- For genuinely unrelated requests, briefly explain the mental-health support scope without sounding mechanical.
 - Do not diagnose, prescribe medication, or claim to replace a professional.
-- Be warm, practical, and concise.
-- Make the user feel calmly supported and invited to continue.
-- For non-crisis answers, end with one gentle, relevant follow-up question or grounding suggestion.
+- Be warm, practical, and useful. Give enough detail to help the current question before suggesting anything else.
+- Only include suggested_questions when corrected_intent is asking_mental_health_question. For greeting, goodbye, gratitude, personal-context, capability, or out_of_scope replies, return an empty suggested_questions list.
+- For non-crisis mental-health answers, include two or three short suggested_questions that the user could click next. Keep them relevant and gentle.
+- suggested_questions must be written from the user perspective as messages the user can send. Use first person: "How can I calm myself right now?" not "How can you calm yourself?"
+- Avoid repeating the same suggested_questions across nearby turns. Make each suggestion match the latest user message and move the conversation forward.
+- Do not make suggested questions the main content of the answer.
 - If the message suggests immediate danger, self-harm, suicide, or harm to others, tell the user to contact local emergency services or the nearest emergency department immediately.
 - If retrieved context is weak or unrelated, give a brief general supportive answer and suggest professional support.
-- Return only valid JSON with keys: language_review, intent_review, answer.
+- Return only valid JSON with keys: language_review, emotion_review, intent_review, answer, suggested_questions.
 
 JSON schema:
 {
@@ -102,12 +188,18 @@ JSON schema:
     "corrected_language_code": "en",
     "reason": "short explanation"
   },
+  "emotion_review": {
+    "matches_module_2": true,
+    "corrected_emotion": "fear",
+    "reason": "short explanation"
+  },
   "intent_review": {
     "matches_module_3": true,
     "corrected_intent": "asking_mental_health_question",
     "reason": "short explanation"
   },
-  "answer": "final user-facing answer"
+  "answer": "final user-facing answer",
+  "suggested_questions": ["How can I calm myself right now?", "What should I try when this feeling comes back?"]
 }
 """
 
@@ -119,10 +211,11 @@ JSON schema:
             "emotion": state["emotion"],
             "intent": state["intent"],
             "retrieval": state["retrieval"],
-            "conversation_memory": state.get("conversation_memory", []),
+            "conversation_history": state.get("conversation_history", []),
         }
         return (
-            "Review the language and intent again, then answer the user.\n\n"
+            "Review the language, emotion, and intent again, then answer the user. "
+            "If you correct the intent, make the answer match the corrected intent.\n\n"
             "Pipeline state:\n"
             + json.dumps(compact_state, ensure_ascii=False, indent=2)
         )

src/models/safety_router.py

@@ -41,43 +41,11 @@ CRISIS_RESPONSES = {
 }
 
 
-GENERIC_REPLIES = {
-    "greeting": {
-        "en": "Hi, I’m here with you ❤️. Share what you’re carrying today, and I’ll help you sort through it gently and clearly.",
-        "fr": "Bonjour, je suis là avec toi. Dis-moi ce qui se passe.",
-        "ar": "مرحبًا، أنا معك. أخبرني بما يحدث.",
-    },
-    "gratitude": {
-        "en": "You’re very welcome ❤️. I’m here if you’d like to keep talking or take the next step together.",
-        "fr": "Avec plaisir. Je peux continuer à t'aider si tu veux en parler davantage.",
-        "ar": "على الرحب والسعة. يمكنني الاستمرار في مساعدتك إذا أردت التحدث أكثر.",
-    },
-    "goodbye": {
-        "en": "Take gentle care of yourself ❤️. I’ll be here if you want to come back and talk later.",
-        "fr": "Prends soin de toi. Je serai là si tu veux revenir plus tard.",
-        "ar": "اعتنِ بنفسك. سأكون هنا إذا احتجت للعودة لاحقًا.",
-    },
-    "out_of_scope": {
-        "en": "I’m here for mental-health and emotional support ❤️. If something is affecting your mood, stress, sleep, or relationships, tell me what’s happening.",
-        "fr": "Je peux surtout aider avec les questions de santé mentale et de soutien émotionnel.",
-        "ar": "يمكنني المساعدة بشكل أفضل في أسئلة الصحة النفسية والدعم العاطفي.",
-    },
-}
-
-
 def detect_crisis(text: str) -> dict[str, Any]:
     clean_text = text.lower()
     matched = [pattern for pattern in CRISIS_PATTERNS if re.search(pattern, clean_text)]
-    return {
-        "is_crisis": bool(matched),
-        "matched_patterns": matched,
-    }
+    return {"is_crisis": bool(matched), "matched_patterns": matched}
 
 
 def crisis_reply(language_code: str) -> str:
     return CRISIS_RESPONSES.get(language_code, CRISIS_RESPONSES["en"])
-
-
-def simple_reply(intent: str, language_code: str) -> str:
-    replies = GENERIC_REPLIES.get(intent, GENERIC_REPLIES["out_of_scope"])
-    return replies.get(language_code, replies["en"])

src/retrieval/build_cci_corpus.py

@@ -14,9 +14,8 @@ PROJECT_ROOT = Path(__file__).resolve().parents[2]
 DEFAULT_INPUT_DIR = PROJECT_ROOT / "data" / "raw" / "CCI"
 DEFAULT_OUTPUT_PATH = PROJECT_ROOT / "data" / "processed" / "cci_information_sheets.json"
 DEFAULT_REPORT_PATH = PROJECT_ROOT / "reports" / "module_4_rag_retrieval" / "cci_corpus_summary.json"
-DEFAULT_CHUNK_SIZE = 1000
-DEFAULT_CHUNK_OVERLAP = 50
-MIN_CHUNK_SIZE = 80
+DEFAULT_MAX_CHUNK_WORDS = 400
+DEFAULT_MIN_CHUNK_WORDS = 80
 
 SENSITIVE_TOPICS = {
     "Bipolar",
@@ -79,8 +78,8 @@ def normalize_text(text: str) -> str:
         flags=re.I,
     )
     text = re.sub(r"Centre for\s+linical\s+nterventions", " ", text, flags=re.I)
-    text = re.sub(r"\s+", " ", text)
-    return text.strip()
+    paragraphs = [re.sub(r"\s+", " ", part).strip() for part in re.split(r"\n{2,}", text)]
+    return "\n\n".join(part for part in paragraphs if part)
 
 
 def extract_page_text(page: fitz.Page) -> str:
@@ -109,51 +108,85 @@ def extract_page_text(page: fitz.Page) -> str:
             right_blocks.append(block_key)
 
     ordered_blocks = sorted(full_width_blocks) + sorted(left_blocks) + sorted(right_blocks)
-    return " ".join(text for _, _, text in ordered_blocks)
+    return "\n\n".join(text for _, _, text in ordered_blocks)
 
 
 def extract_pdf_text(pdf_path: Path) -> str:
-    doc = fitz.open(pdf_path)
-    return normalize_text(" ".join(extract_page_text(page) for page in doc))
+    with fitz.open(pdf_path) as doc:
+        return normalize_text("\n\n".join(extract_page_text(page) for page in doc))
 
 
-def chunk_text(text: str, chunk_size: int, chunk_overlap: int) -> list[str]:
-    if chunk_size <= 0:
-        return [text]
-    if chunk_overlap >= chunk_size:
-        raise ValueError("chunk_overlap must be smaller than chunk_size.")
+def count_words(text: str) -> int:
+    return len(re.findall(r"\b\w+\b", text))
 
-    chunks = []
-    start = 0
-    while start < len(text):
-        end = min(start + chunk_size, len(text))
 
-        if end < len(text):
-            sentence_end = max(text.rfind(". ", start, end), text.rfind("? ", start, end), text.rfind("! ", start, end))
-            if sentence_end > start + int(chunk_size * 0.6):
-                end = sentence_end + 1
+def is_heading(text: str) -> bool:
+    return count_words(text) <= 12 and not text.rstrip().endswith((".", "?", "!", ";"))
 
-        chunk = text[start:end].strip()
-        if chunk:
-            chunks.append(chunk)
 
-        if end >= len(text):
-            break
-        start = max(0, end - chunk_overlap)
+def split_paragraph(text: str, max_words: int) -> list[str]:
+    sentences = re.split(r"(?<=[.!?])\s+", text)
+    pieces: list[str] = []
+    current: list[str] = []
 
-    if len(chunks) > 1 and len(chunks[-1]) < MIN_CHUNK_SIZE:
-        chunks[-2] = normalize_text(f"{chunks[-2]} {chunks[-1]}")
-        chunks.pop()
+    for sentence in sentences:
+        if count_words(sentence) > max_words:
+            if current:
+                pieces.append(" ".join(current))
+                current = []
+            words = sentence.split()
+            pieces.extend(" ".join(words[start : start + max_words]) for start in range(0, len(words), max_words))
+        elif current and count_words(" ".join(current + [sentence])) > max_words:
+            pieces.append(" ".join(current))
+            current = [sentence]
+        else:
+            current.append(sentence)
+
+    if current:
+        pieces.append(" ".join(current))
+    return [piece.strip() for piece in pieces if piece.strip()]
+
+
+def chunk_text(text: str, max_words: int, min_words: int) -> list[str]:
+    if min_words <= 0 or max_words < min_words:
+        raise ValueError("Chunk word limits must be positive and maximum must be at least minimum.")
+
+    paragraphs = [part.strip() for part in text.split("\n\n") if part.strip()]
+    pieces = [piece for paragraph in paragraphs for piece in split_paragraph(paragraph, max_words)]
+    chunks: list[str] = []
+    current: list[str] = []
+
+    for piece in pieces:
+        current_words = count_words(" ".join(current))
+        starts_section = is_heading(piece) and current_words >= min_words
+        exceeds_limit = current_words >= min_words and current_words + count_words(piece) > max_words
+
+        if current and (starts_section or exceeds_limit):
+            chunks.append(" ".join(current))
+            current = []
+        current.append(piece)
+
+    if current:
+        chunks.append(" ".join(current))
+
+    bounded = [piece for chunk in chunks for piece in split_paragraph(chunk, max_words)]
+    final: list[str] = []
+    for piece in bounded:
+        can_merge = final and count_words(final[-1]) + count_words(piece) <= max_words
+        if can_merge and (count_words(final[-1]) < min_words or count_words(piece) < min_words):
+            final[-1] = f"{final[-1]} {piece}"
+        else:
+            final.append(piece)
 
-    return chunks
+    return [re.sub(r"\s+", " ", chunk).strip() for chunk in final]
 
 
-def build_documents(pdf_path: Path, chunk_size: int, chunk_overlap: int) -> list[dict[str, Any]]:
+def build_documents(pdf_path: Path, max_chunk_words: int, min_chunk_words: int) -> list[dict[str, Any]]:
     topic = pdf_path.parent.name
     document_title = clean_title(pdf_path)
     text = extract_pdf_text(pdf_path)
     base_id = f"cci_{slugify(topic)}_{slugify(document_title)}"
-    chunks = chunk_text(text, chunk_size, chunk_overlap)
+    chunks = chunk_text(text, max_chunk_words, min_chunk_words)
 
     documents = []
     for index, chunk in enumerate(chunks, start=1):
@@ -176,14 +209,14 @@ def build_documents(pdf_path: Path, chunk_size: int, chunk_overlap: int) -> list
     return documents
 
 
-def build_corpus(input_dir: Path, chunk_size: int, chunk_overlap: int) -> list[dict[str, Any]]:
+def build_corpus(input_dir: Path, max_chunk_words: int, min_chunk_words: int) -> list[dict[str, Any]]:
     documents = []
     for path in sorted(input_dir.rglob("*.pdf")):
-        documents.extend(build_documents(path, chunk_size, chunk_overlap))
+        documents.extend(build_documents(path, max_chunk_words, min_chunk_words))
     return documents
 
 
-def save_report(documents: list[dict[str, Any]], report_path: Path, chunk_size: int, chunk_overlap: int) -> None:
+def save_report(documents: list[dict[str, Any]], report_path: Path, max_chunk_words: int, min_chunk_words: int) -> None:
     topic_counts = Counter(document["topic"] for document in documents)
     sensitivity_counts = Counter(document["sensitivity"] for document in documents)
     source_document_count = len({document["document_id"] for document in documents})
@@ -193,15 +226,17 @@ def save_report(documents: list[dict[str, Any]], report_path: Path, chunk_size:
         "source": "Centre for Clinical Interventions",
         "source_document_count": source_document_count,
         "chunk_count": len(documents),
-        "chunk_size_characters": chunk_size,
-        "chunk_overlap_characters": chunk_overlap,
+        "chunking_strategy": "structure-aware PDF blocks with heading and sentence boundaries",
+        "maximum_chunk_words": max_chunk_words,
+        "minimum_target_words": min_chunk_words,
+        "exact_duplicate_chunk_count": len(documents) - len({document["text"] for document in documents}),
         "topic_counts": dict(sorted(topic_counts.items())),
         "sensitivity_counts": dict(sorted(sensitivity_counts.items())),
         "total_words": sum(word_counts),
         "min_words": min(word_counts) if word_counts else 0,
         "max_words": max(word_counts) if word_counts else 0,
         "average_words": round(sum(word_counts) / len(word_counts), 2) if word_counts else 0,
-        "output_format": "fixed-size overlapping text chunks",
+        "output_format": "structure-aware semantic text chunks",
         "fields": [
             "chunk_id",
             "document_id",
@@ -225,18 +260,18 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--input-dir", default=DEFAULT_INPUT_DIR, type=Path)
     parser.add_argument("--output-path", default=DEFAULT_OUTPUT_PATH, type=Path)
     parser.add_argument("--report-path", default=DEFAULT_REPORT_PATH, type=Path)
-    parser.add_argument("--chunk-size", default=DEFAULT_CHUNK_SIZE, type=int)
-    parser.add_argument("--chunk-overlap", default=DEFAULT_CHUNK_OVERLAP, type=int)
+    parser.add_argument("--max-chunk-words", default=DEFAULT_MAX_CHUNK_WORDS, type=int)
+    parser.add_argument("--min-chunk-words", default=DEFAULT_MIN_CHUNK_WORDS, type=int)
     return parser.parse_args()
 
 
 def main() -> None:
     args = parse_args()
-    documents = build_corpus(args.input_dir, args.chunk_size, args.chunk_overlap)
+    documents = build_corpus(args.input_dir, args.max_chunk_words, args.min_chunk_words)
 
     args.output_path.parent.mkdir(parents=True, exist_ok=True)
     args.output_path.write_text(json.dumps(documents, indent=2, ensure_ascii=False), encoding="utf-8")
-    save_report(documents, args.report_path, args.chunk_size, args.chunk_overlap)
+    save_report(documents, args.report_path, args.max_chunk_words, args.min_chunk_words)
 
     print(f"Saved {len(documents)} CCI documents to {args.output_path}")
     print(f"Saved corpus summary to {args.report_path}")

src/retrieval/build_vector_index.py

@@ -32,7 +32,7 @@ CCI_PATH = PROCESSED_DIR / "cci_information_sheets.json"
 AMOD_PATH = PROCESSED_DIR / "amod_clean_qa.json"
 REPORT_PATH = REPORT_DIR / "retrieval_index_summary.json"
 
-DEFAULT_COLLECTION_NAME = "mental_health_rag"
+DEFAULT_COLLECTION_NAME = "mental_health_rag_v2"
 BATCH_SIZE = int(os.getenv("EMBEDDING_BATCH_SIZE", "2"))
 
 
@@ -167,6 +167,7 @@ def main() -> None:
         "embedding_model": MODEL_NAME,
         "embedding_dimension": embedder.dimension,
         "vector_database": "Qdrant Cloud",
+        "similarity_metric": "cosine_similarity",
         "collection_name": args.collection,
         "record_count": len(records),
         "source_counts": dict(sorted(source_counts.items())),

src/retrieval/env_utils.py

@@ -11,7 +11,7 @@ def load_env_file(path: Path = PROJECT_ROOT / ".env") -> None:
     if not path.exists():
         return
 
-    for line in path.read_text(encoding="utf-8").splitlines():
+    for line in path.read_text(encoding="utf-8-sig").splitlines():
         line = line.strip()
         if not line or line.startswith("#") or "=" not in line:
             continue

src/retrieval/retrieval_engine.py

@@ -25,7 +25,7 @@ except ModuleNotFoundError:
 
 
 PROJECT_ROOT = Path(__file__).resolve().parents[2]
-DEFAULT_COLLECTION_NAME = "mental_health_rag"
+DEFAULT_COLLECTION_NAME = "mental_health_rag_v2"
 SOURCE_OPTIONS = {"both", "cci", "amod"}
 
 
@@ -80,6 +80,7 @@ class RetrievalEngine:
         return {
             "rank": rank,
             "score": round(float(point.score), 4),
+            "score_type": "cosine_similarity",
             "id": payload.get("record_id"),
             "source_type": payload.get("source_type"),
             "source": payload.get("source"),

src/retrieval/retrieval_tester_ui.py

@@ -121,7 +121,7 @@ def _result_html(results: list[dict]) -> str:
             "<div class='result-card'>"
             "<div class='result-topline'>"
             f"<div class='result-title'>#{result['rank']} - {title}</div>"
-            f"<div class='result-score'>{score:.4f}</div>"
+            f"<div class='result-score'>Cosine {score:.4f}</div>"
             "</div>"
             f"<div><span class='source-pill'>{source_type}</span><span class='source-pill'>{topic}</span></div>"
             f"<p class='result-text'>{text}</p>"