Upload 2 files

alz_companion/agent.py

@@ -0,0 +1,403 @@
+from __future__ import annotations
+import os
+import json
+import base64
+import time
+import tempfile
+import re # <-- ADD THIS LINE
+
+from typing import List, Dict, Any, Optional
+
+# OpenAI for LLM (optional)
+try:
+    from openai import OpenAI
+except Exception:  # pragma: no cover
+    OpenAI = None  # type: ignore
+
+# LangChain & RAG
+from langchain.schema import Document
+from langchain_community.vectorstores import FAISS
+from langchain_community.embeddings import HuggingFaceEmbeddings
+
+# TTS
+try:
+    from gtts import gTTS
+except Exception:  # pragma: no cover
+    gTTS = None  # type: ignore
+
+
+from .prompts import (
+    SYSTEM_TEMPLATE, ANSWER_TEMPLATE_CALM, ANSWER_TEMPLATE_ADQ,
+    SAFETY_GUARDRAILS, RISK_FOOTER, render_emotion_guidelines, CLASSIFICATION_PROMPT,
+    # Add the new templates to the import list
+    ROUTER_PROMPT, 
+    ANSWER_TEMPLATE_FACTUAL, 
+    ANSWER_TEMPLATE_GENERAL_KNOWLEDGE,
+    ANSWER_TEMPLATE_GENERAL,
+    QUERY_EXPANSION_PROMPT 
+)
+
+# -----------------------------
+# Multimodal Processing Functions
+# -----------------------------
+
+def _openai_client() -> Optional[OpenAI]:
+    api_key = os.getenv("OPENAI_API_KEY", "").strip()
+    return OpenAI(api_key=api_key) if api_key and OpenAI else None
+
+# In agent.py
+
+def describe_image(image_path: str) -> str:
+    """Uses a vision model to describe an image for context."""
+    client = _openai_client()
+    if not client:
+        return "(Image description failed: OpenAI API key not configured.)"
+    
+    try:
+        # --- FIX START ---
+        # Determine the MIME type based on the file extension
+        extension = os.path.splitext(image_path)[1].lower()
+        if extension == ".png":
+            mime_type = "image/png"
+        elif extension in [".jpg", ".jpeg"]:
+            mime_type = "image/jpeg"
+        elif extension == ".gif":
+            mime_type = "image/gif"
+        elif extension == ".webp":
+            mime_type = "image/webp"
+        else:
+            # Default to JPEG, but this handles the most common cases
+            mime_type = "image/jpeg"
+        # --- FIX END ---
+
+        with open(image_path, "rb") as image_file:
+            base64_image = base64.b64encode(image_file.read()).decode('utf-8')
+
+        response = client.chat.completions.create(
+            model="gpt-4o",
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": "Describe this image in a concise, factual way for a memory journal. Focus on people, places, and key objects. For example: 'A photo of John and Mary smiling on a bench at the park.'"},
+                        {
+                            "type": "image_url", 
+                            # Use the dynamically determined MIME type
+                            "image_url": {"url": f"data:{mime_type};base64,{base64_image}"}
+                        }
+                    ],
+                }
+            ],
+            max_tokens=100,
+        )
+        return response.choices[0].message.content or "No description available."
+    except Exception as e:
+        return f"[Image description error: {e}]"
+
+# -----------------------------
+# NLU Classification Function
+# -----------------------------
+# Since the LLM's response will now contain both a <thinking> block and a JSON block, 
+# we need to update the detect_tags_from_query function to correctly parse it.
+
+# In agent.py
+
+def detect_tags_from_query(query: str, behavior_options: list, emotion_options: list, topic_options: list, context_options: list) -> Dict[str, Any]:
+    """Uses a Chain-of-Thought prompt to classify the user's query."""
+    behavior_str = ", ".join(f'"{opt}"' for opt in behavior_options if opt != "None")
+    emotion_str = ", ".join(f'"{opt}"' for opt in emotion_options if opt != "None")
+    topic_str = ", ".join(f'"{opt}"' for opt in topic_options if opt != "None")
+    context_str = ", ".join(f'"{opt}"' for opt in context_options if opt != "None")
+
+    prompt = CLASSIFICATION_PROMPT.format(
+        behavior_options=behavior_str, 
+        emotion_options=emotion_str, 
+        topic_options=topic_str,
+        context_options=context_str,
+        query=query
+    )
+    
+    messages = [{"role": "system", "content": "You are a helpful NLU classification assistant. Follow the instructions precisely."}, {"role": "user", "content": prompt}]
+    response_str = call_llm(messages, temperature=0.1)
+    
+    print(f"\n--- NLU Full Response ---\n{response_str}\n-----------------------\n")
+    
+    result_dict = {
+        "detected_behaviors": [], "detected_emotion": "None",
+        "detected_topic": "None", "detected_contexts": []
+    }
+    
+    try:
+        # --- ROBUST PARSING LOGIC ---
+        # Find the first '{' and the last '}' to isolate the JSON object
+        start_brace = response_str.find('{')
+        end_brace = response_str.rfind('}')
+        
+        if start_brace != -1 and end_brace != -1 and end_brace > start_brace:
+            json_str = response_str[start_brace : end_brace + 1]
+            result = json.loads(json_str)
+            
+            # Safely process the results from the LLM
+            result_dict["detected_behaviors"] = [b for b in result.get("detected_behaviors", []) if b in behavior_options]
+            result_dict["detected_emotion"] = result.get("detected_emotion") if result.get("detected_emotion") in emotion_options else "None"
+            result_dict["detected_topic"] = result.get("detected_topic") if result.get("detected_topic") in topic_options else "None"
+            result_dict["detected_contexts"] = [c for c in result.get("detected_contexts", []) if c in context_options]
+        # --- END OF ROBUST LOGIC ---
+        
+        return result_dict
+    except (json.JSONDecodeError, AttributeError) as e:
+        print(f"ERROR parsing CoT JSON: {e}")
+        return result_dict
+
+
+# -----------------------------
+# Embeddings & VectorStore
+# -----------------------------
+
+def _default_embeddings():
+    """Lightweight, widely available model."""
+    model_name = os.getenv("EMBEDDINGS_MODEL", "sentence-transformers/all-MiniLM-L6-v2")
+    return HuggingFaceEmbeddings(model_name=model_name)
+
+def build_or_load_vectorstore(docs: List[Document], index_path: str, is_personal: bool = False) -> FAISS:
+    os.makedirs(os.path.dirname(index_path), exist_ok=True)
+    if os.path.isdir(index_path) and os.path.exists(os.path.join(index_path, "index.faiss")):
+        try:
+            return FAISS.load_local(index_path, _default_embeddings(), allow_dangerous_deserialization=True)
+        except Exception:
+            pass
+    
+    if is_personal and not docs:
+        docs = [Document(page_content="(This is the start of the personal memory journal.)", metadata={"source": "placeholder"})]
+        
+    vs = FAISS.from_documents(docs, _default_embeddings())
+    vs.save_local(index_path)
+    return vs
+
+def texts_from_jsonl(path: str) -> List[Document]:
+    out: List[Document] = []
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            for i, line in enumerate(f):
+                line = line.strip()
+                if not line: continue
+                obj = json.loads(line)
+                txt = obj.get("text") or ""
+                if not isinstance(txt, str) or not txt.strip(): continue
+                md = {"source": os.path.basename(path), "chunk": i}
+                for k in ("behaviors", "emotion"):
+                    if k in obj: md[k] = obj[k]
+                out.append(Document(page_content=txt, metadata=md))
+    except Exception:
+        return []
+    return out
+
+def bootstrap_vectorstore(sample_paths: List[str] | None = None, index_path: str = "data/faiss_index") -> FAISS:
+    docs: List[Document] = []
+    for p in (sample_paths or []):
+        try:
+            if p.lower().endswith(".jsonl"):
+                docs.extend(texts_from_jsonl(p))
+            else:
+                with open(p, "r", encoding="utf-8", errors="ignore") as fh:
+                    docs.append(Document(page_content=fh.read(), metadata={"source": os.path.basename(p)}))
+        except Exception:
+            continue
+    if not docs:
+        docs = [Document(page_content="(empty index)", metadata={"source": "placeholder"})]
+    return build_or_load_vectorstore(docs, index_path=index_path)
+
+# -----------------------------
+# LLM Call
+# -----------------------------
+# updated the detect_tags_from_query function to call call_llm with a new stop argument, 
+# but I failed to update the call_llm function itself to accept that argument.
+# Now fix call_llm function:
+def call_llm(messages: List[Dict[str, str]], temperature: float = 0.6, stop: Optional[List[str]] = None) -> str:
+    """Call OpenAI Chat Completions if available; else return a fallback."""
+    client = _openai_client()
+    model = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
+    if not client:
+        return "(Offline Mode: OpenAI API key not configured.)"
+    try:
+        # Prepare arguments for the API call to handle the optional 'stop' parameter
+        api_args = {
+            "model": model,
+            "messages": messages,
+            "temperature": float(temperature if temperature is not None else 0.6)
+        }
+        if stop:
+            api_args["stop"] = stop
+
+        resp = client.chat.completions.create(**api_args)
+        return (resp.choices[0].message.content or "").strip()
+    except Exception as e:
+        return f"[LLM API Error: {e}]"
+
+
+# -----------------------------
+# Prompting & RAG Chain
+# -----------------------------
+
+def _format_sources(docs: List[Document]) -> List[str]:
+    return list(set(d.metadata.get("source", "unknown") for d in docs))
+
+# In agent.py, replace the existing make_rag_chain function with this new one to handle general & specific conversations .
+# The logic for the "factual_question" path needs to be updated to perform the expansion query
+
+def make_rag_chain(
+    vs_general: FAISS,
+    vs_personal: FAISS,
+    *,
+    role: str = "patient",
+    temperature: float = 0.6,
+    language: str = "English",
+    patient_name: str = "the patient",
+    caregiver_name: str = "the caregiver",
+    tone: str = "warm",
+):
+    """Returns a callable that performs the complete, intelligent RAG process."""
+
+    def _format_docs(docs: List[Document], default_msg: str) -> str:
+        if not docs: return default_msg
+        unique_docs = {doc.page_content: doc for doc in docs}.values()
+        return "\n".join([f"- {d.page_content.strip()}" for d in unique_docs])
+
+    def _answer_fn(query: str, chat_history: List[Dict[str, str]], scenario_tag: Optional[str] = None, emotion_tag: Optional[str] = None) -> Dict[str, Any]:
+
+        router_messages = [{"role": "user", "content": ROUTER_PROMPT.format(query=query)}]
+        query_type = call_llm(router_messages, temperature=0.0).strip().lower()
+        print(f"Query classified as: {query_type}")
+
+        system_message = SYSTEM_TEMPLATE.format(tone=tone, language=language, patient_name=patient_name or "the patient", caregiver_name=caregiver_name or "the caregiver", guardrails=SAFETY_GUARDRAILS)
+        messages = [{"role": "system", "content": system_message}]
+        messages.extend(chat_history)
+
+        # --- NEW 'general_knowledge_question' PATH ---
+        if "general_knowledge_question" in query_type:
+            user_prompt = ANSWER_TEMPLATE_GENERAL_KNOWLEDGE.format(question=query, language=language)
+            messages.append({"role": "user", "content": user_prompt})
+            answer = call_llm(messages, temperature=temperature)
+            return {"answer": answer, "sources": ["General Knowledge"]}
+        # --- END NEW PATH ---
+
+        elif "factual_question" in query_type:
+            # ... (This entire section for query expansion and factual search remains the same)
+            print(f"Performing query expansion for: '{query}'")
+            expansion_prompt = QUERY_EXPANSION_PROMPT.format(question=query)
+            expansion_response = call_llm([{"role": "user", "content": expansion_prompt}], temperature=0.1)
+
+            try:
+                clean_response = expansion_response.strip().replace("```json", "").replace("```", "")
+                expanded_queries = json.loads(clean_response)
+                search_queries = [query] + expanded_queries
+            except json.JSONDecodeError:
+                search_queries = [query]
+
+            print(f"Searching with queries: {search_queries}")
+            retriever_personal = vs_personal.as_retriever(search_kwargs={"k": 2})
+            retriever_general = vs_general.as_retriever(search_kwargs={"k": 2})
+
+            all_docs = []
+            for q in search_queries:
+                all_docs.extend(retriever_personal.invoke(q))
+                all_docs.extend(retriever_general.invoke(q))
+
+            context = _format_docs(all_docs, "(No relevant information found in the memory journal.)")
+
+            user_prompt = ANSWER_TEMPLATE_FACTUAL.format(context=context, question=query, language=language)
+            messages.append({"role": "user", "content": user_prompt})
+            answer = call_llm(messages, temperature=temperature)
+            return {"answer": answer, "sources": _format_sources(all_docs)}
+
+        elif "general_conversation" in query_type:
+            user_prompt = ANSWER_TEMPLATE_GENERAL.format(question=query, language=language)
+            messages.append({"role": "user", "content": user_prompt})
+            answer = call_llm(messages, temperature=temperature)
+            return {"answer": answer, "sources": []}
+
+        else: # Default to the original caregiving logic
+            # ... (This entire section for caregiving scenarios remains the same)
+            search_filter = {}
+            if scenario_tag and scenario_tag != "None":
+                search_filter["behaviors"] = scenario_tag.lower()
+            if emotion_tag and emotion_tag != "None":
+                search_filter["emotion"] = emotion_tag.lower()
+
+            if search_filter:
+                personal_docs = vs_personal.similarity_search(query, k=3, filter=search_filter)
+                general_docs = vs_general.similarity_search(query, k=3, filter=search_filter)
+            else:
+                retriever_personal = vs_personal.as_retriever(search_kwargs={"k": 3})
+                retriever_general = vs_general.as_retriever(search_kwargs={"k": 3})
+                personal_docs = retriever_personal.invoke(query)
+                general_docs = retriever_general.invoke(query)
+
+            personal_context = _format_docs(personal_docs, "(No relevant personal memories found.)")
+            general_context = _format_docs(general_docs, "(No general guidance found.)")
+
+            first_emotion = None
+            all_docs_care = personal_docs + general_docs
+            for doc in all_docs_care:
+                if "emotion" in doc.metadata and doc.metadata["emotion"]:
+                    emotion_data = doc.metadata["emotion"]
+                    if isinstance(emotion_data, list): first_emotion = emotion_data[0]
+                    else: first_emotion = emotion_data
+                    if first_emotion: break
+
+            emotions_context = render_emotion_guidelines(first_emotion or emotion_tag)
+            is_tagged_scenario = (scenario_tag and scenario_tag != "None") or (emotion_tag and emotion_tag != "None") or (first_emotion is not None)
+            template = ANSWER_TEMPLATE_ADQ if is_tagged_scenario else ANSWER_TEMPLATE_CALM
+
+            if template == ANSWER_TEMPLATE_ADQ:
+                user_prompt = template.format(general_context=general_context, personal_context=personal_context, question=query, scenario_tag=scenario_tag, emotions_context=emotions_context, role=role, language=language)
+            else:
+                combined_context = f"General Guidance:\n{general_context}\n\nPersonal Memories:\n{personal_context}"
+                user_prompt = template.format(context=combined_context, question=query, language=language)
+
+            messages.append({"role": "user", "content": user_prompt})
+            answer = call_llm(messages, temperature=temperature)
+
+            high_risk_scenarios = ["exit_seeking", "wandering", "elopement"]
+            if scenario_tag and scenario_tag.lower() in high_risk_scenarios:
+                answer += f"\n\n---\n{RISK_FOOTER}"
+
+            return {"answer": answer, "sources": _format_sources(all_docs_care)}
+
+    return _answer_fn
+
+
+def answer_query(chain, question: str, **kwargs) -> Dict[str, Any]:
+    if not callable(chain): return {"answer": "[Error: RAG chain is not callable]", "sources": []}
+    chat_history, scenario_tag, emotion_tag = kwargs.get("chat_history", []), kwargs.get("scenario_tag"), kwargs.get("emotion_tag")
+    try:
+        return chain(question, chat_history=chat_history, scenario_tag=scenario_tag, emotion_tag=emotion_tag)
+    except Exception as e:
+        print(f"ERROR in answer_query: {e}")
+        return {"answer": f"[Error executing chain: {e}]", "sources": []}
+
+# -----------------------------
+# TTS & Transcription
+# -----------------------------
+def synthesize_tts(text: str, lang: str = "en"):
+    if not text or gTTS is None: return None
+    try:
+        fd, path = tempfile.mkstemp(suffix=".mp3")
+        os.close(fd)
+        tts = gTTS(text=text, lang=(lang or "en"))
+        tts.save(path)
+        return path
+    except Exception:
+        return None
+
+def transcribe_audio(filepath: str, lang: str = "en"):
+    client = _openai_client()
+    if not client:
+        return "[Transcription failed: API key not configured]"
+    api_args = {"model": "whisper-1"}
+    if lang and lang != "auto":
+        api_args["language"] = lang
+    with open(filepath, "rb") as audio_file:
+        transcription = client.audio.transcriptions.create(file=audio_file, **api_args)
+    return transcription.text
+

alz_companion/prompts.py

@@ -0,0 +1,266 @@
+"""
+Prompts for the Alzheimer’s AI Companion.
+"""
+
+# ------------------------ Behaviour‑level tags ------------------------
+BEHAVIOUR_TAGS = {
+    # Tags from "The Father"
+    "repetitive_questioning": ["validation", "gentle_redirection", "offer_distraction"],
+    "confusion": ["reassurance", "time_place_orientation", "photo_anchors"],
+    "wandering": ["walk_along_support", "simple_landmarks", "visual_cues", "safe_wandering_space"],
+    "agitation": ["de-escalating_tone", "validate_feelings", "reduce_stimulation", "simple_choices"],
+    "false_accusations": ["reassure_no_blame", "avoid_arguing", "redirect_activity"],
+    "address_memory_loss": ["encourage_ID_bracelet_or_GPS", "place_contact_info_in_wallet", "inform_trusted_neighbors", "avoid_quizzing_on_address"],
+    "hallucinations_delusions": ["avoid_arguing_or_correcting", "validate_the_underlying_emotion", "offer_reassurance_of_safety", "gently_redirect_to_real_activity", "check_for_physical_triggers"],
+
+    # Tags from "Still Alice" (and others for future use)
+    "exit_seeking": ["validation", "calm_presence", "safe_wandering_space", "environmental_cues"],
+    "aphasia": ["patience", "simple_language", "nonverbal_cues", "validation"],
+    "withdrawal": ["gentle_invitation", "calm_presence", "offer_familiar_comforts", "no_pressure"],
+    "affection": ["reciprocate_warmth", "positive_reinforcement", "simple_shared_activity"],
+    "sleep_disturbance": ["establish_calm_bedtime_routine", "limit_daytime_naps", "check_for_discomfort_or_pain"],
+    "anxiety": ["calm_reassurance", "simple_breathing_exercise", "reduce_environmental_stimuli"],
+    "depression_sadness": ["validate_feelings_of_sadness", "encourage_simple_pleasant_activity", "ensure_social_connection"],
+    "orientation_check": ["gentle_orientation_cues", "use_familiar_landmarks", "avoid_quizzing"],
+
+    # Tags from "Away from Her"
+    "misidentification": ["gently_correct_with_context", "use_photos_as_anchors", "respond_to_underlying_emotion", "avoid_insistent_correction"],
+
+    # Other useful tags
+    "sundowning_restlessness": ["predictable_routine", "soft_lighting", "low_stimulation", "familiar_music"],
+    "object_misplacement": ["nonconfrontational_search", "fixed_storage_spots"],
+
+    # --- New Tags from Test Fixtures ---
+    "validation": [],
+    "gentle_reorientation": [],
+    "de-escalation": [],
+    "distraction": [],
+    "spaced_cueing": [],
+    "reassurance": [],
+    "psychoeducation": [],
+    "goal_breakdown": [],
+    "routine_structuring": [],
+    "reminiscence_prompting": [],
+    "reframing": [],
+    "distress_tolerance": [],
+    "caregiver_communication_template": [],
+    "personalised_music_activation": [],
+    "memory_probe": [],
+    "safety_brief": [],
+    "follow_up_prompt": []
+}
+
+# ------------------------ Emotion styles & helpers ------------------------
+EMOTION_STYLES = {
+    "confusion": {"tone": "calm, orienting, concrete", "playbook": ["Offer a simple time/place orientation cue (who/where/when).", "Reference one familiar anchor (photo/object/person).", "Use short sentences and one step at a time."]},
+    "fear": {"tone": "reassuring, safety-forward, gentle", "playbook": ["Acknowledge fear without contradiction.", "Provide a clear safety cue (e.g., 'You’re safe here with me').", "Reduce novelty and stimulation; suggest one safe action."]},
+    "anger": {"tone": "de-escalating, validating, low-arousal", "playbook": ["Validate the feeling; avoid arguing/correcting.", "Keep voice low and sentences short.", "Offer a simple choice to restore control (e.g., 'tea or water?')."]},
+    "sadness": {"tone": "warm, empathetic, gentle reminiscence", "playbook": ["Acknowledge loss/longing.", "Invite one comforting memory or familiar song.", "Keep pace slow; avoid tasking."]},
+    "warmth": {"tone": "affirming, appreciative", "playbook": ["Reflect gratitude and positive connection.", "Reinforce what’s going well.", "Keep it light; don’t overload with new info."]},
+    "joy": {"tone": "supportive, celebratory (but not overstimulating)", "playbook": ["Share the joy briefly; match energy gently.", "Offer a simple, pleasant follow-up activity.", "Avoid adding complex tasks."]},
+    "calm": {"tone": "matter-of-fact, concise, steady", "playbook": ["Keep instructions simple.", "Maintain steady pace.", "No extra soothing needed."]},
+}
+
+def render_emotion_guidelines(emotion: str | None) -> str:
+    e = (emotion or "").strip().lower()
+    if e not in EMOTION_STYLES:
+        return "Emotion: (auto)\nDesired tone: calm, clear.\nWhen replying, reassure if distress is apparent; prioritise validation and simple choices."
+    style = EMOTION_STYLES[e]
+    bullet = "\n".join([f"- {x}" for x in style["playbook"]])
+    return f"Emotion: {e}\nDesired tone: {style['tone']}\nWhen replying, follow:\n{bullet}"
+
+# ------------------------ NLU Classification ------------------------
+# Sometimes, especially with complex instructions, the AI can fail to generate the JSON correctly, 
+# which causes the code that reads the response to fail and return "None"
+# SOLUTION: Improve with a hybrid approach with "Few-Shot" Prompting and step-by-step Chain of Thought
+
+CLASSIFICATION_PROMPT = """You are an expert NLU engine. Your task is to analyze the user's query to deeply understand their underlying intent and classify it correctly.
+
+--- INSTRUCTIONS ---
+First, in a <thinking> block, you must reason step-by-step about the user's query by following these points:
+- **Literal Meaning:** What is the user literally asking or stating?
+- **Underlying Situation:** What is the deeper emotional state or situation being described? (e.g., caregiver burnout, patient confusion, a request for practical help).
+- **User's Primary Goal:** Is the user's main goal **Practical Planning** (seeking a plan, strategy, or how-to advice) or **Emotional Support** (seeking comfort, validation, or reassurance)? This is the most important step.
+- **Tag Selection:** Based on the primary goal, explain which tags from the provided lists are the most appropriate and why. If the goal is practical, prioritize practical tags. If the goal is emotional, prioritize emotional support tags.
+
+# - **User's Goal:** What is their true goal? (e.g., Are they seeking factual information, emotional reassurance, or a practical action plan?).
+# - **Tag Selection:** Based on the goal and situation, explain which tags from the provided lists are the most appropriate and why.
+
+Second, after your reasoning, provide a single, valid JSON object with the final classification.
+
+--- PROVIDED TAGS ---
+Behaviors: {behavior_options}
+Emotions: {emotion_options}
+Topics: {topic_options}
+Contexts: {context_options}
+
+--- EXAMPLES ---
+
+User Query: "She looked right through me today, like I wasn't even there."
+<thinking>
+1.  **Literal Meaning:** The user's loved one did not seem to recognize them.
+2.  **Underlying Situation:** The user is expressing emotional pain and a feeling of invisibility due to the disease's progression.
+3.  **User's Goal:** They are seeking comfort and a strategy to cope with this painful experience.
+4.  **Tag Selection:** The goal is emotional support, so `behaviors` should be `validation` and `reminiscence_prompting`. The `emotion` is `sadness`. The `topic` is `treatment_option:reassurance`.
+</thinking>
+{{
+    "detected_behaviors": ["validation", "reminiscence_prompting"],
+    "detected_emotion": "sadness",
+    "detected_topic": "treatment_option:reassurance",
+    "detected_contexts": ["relationship_spouse", "setting_care_home"]
+}}
+
+User Query: "He’s withdrawn today."
+<thinking>
+1.  **Literal Meaning:** The patient is not engaging.
+2.  **Underlying Situation:** The user is observing the patient's apathy and wants to help.
+3.  **User's Goal:** They are implicitly asking for a practical action plan to engage the patient.
+4.  **Tag Selection:** The problem is `withdrawal`, but the goal implies a solution. A known strategy is music, so the `behavior` should include the proactive `personalised_music_activation`. The `topic` is `treatment_option:music_therapy`. The user's tone is `calm`.
+</thinking>
+{{
+    "detected_behaviors": ["withdrawal", "personalised_music_activation"],
+    "detected_emotion": "calm",
+    "detected_topic": "treatment_option:music_therapy",
+    "detected_contexts": ["setting_care_home"]
+}}
+---
+
+User Query: "{query}"
+
+<thinking>
+"""
+
+
+# ------------------------ Guardrails ------------------------
+SAFETY_GUARDRAILS = """Never provide medical diagnoses or dosing. If a situation implies imminent risk (e.g., wandering/elopement, severe agitation, choking, falls), signpost immediate support from onsite staff or emergency services. Use respectful, person‑centred language. Keep guidance concrete and stepwise."""
+
+# ------------------------ System & Answer Templates ------------------------
+SYSTEM_TEMPLATE = """You are an Alzheimer’s caregiving companion. Address the patient as {patient_name} and the caregiver as {caregiver_name}. Ground every suggestion in retrieved evidence when possible. If unsure, say so plainly.
+{guardrails}
+--- IMPORTANT RULE ---
+You MUST write your entire response in {language} ONLY. This is a strict instruction. Do not use any other language, even if the user or the retrieved context uses a different language. Your final output must be in {language}."""
+
+ANSWER_TEMPLATE_CALM = """Context:
+{context}
+
+---
+Question from user: {question}
+
+---
+Instructions:
+Based on the context, write a gentle and supportive response in a single, natural-sounding paragraph.
+Your response should:
+1. Start by briefly and calmly acknowledging the user's situation or feeling.
+2. Weave 2-3 practical, compassionate suggestions from the context into your paragraph. Do not use a numbered or bulleted list.
+3. Conclude with a short, reassuring phrase.
+4. You MUST use the retrieved context to directly address the user's specific **Question**.
+Your response in {language}:"""
+
+# For scenarios tagged with a specific behavior (e.g., agitation, confusion)
+ANSWER_TEMPLATE_ADQ = """--- General Guidance from Knowledge Base ---
+{general_context}
+
+--- Relevant Personal Memories ---
+{personal_context}
+
+---
+Care scenario: {scenario_tag}
+Response Guidelines:
+{emotions_context}
+Question from user: {question}
+
+---
+Instructions:
+Based on ALL the information above, write a **concise, warm, and validating** response for the {role} in a single, natural-sounding paragraph. **Keep the total response to 2-4 sentences.**
+If possible, weave details from the 'Relevant Personal Memories' into your suggestions to make the response feel more personal and familiar.
+Pay close attention to the Response Guidelines to tailor your tone.
+Your response should follow this pattern:
+1. Start by validating the user's feeling or concern with a unique, empathetic opening. DO NOT USE THE SAME OPENING PHRASE REPEATEDLY. Choose from different styles of openers, such as:
+   - Acknowledging the difficulty: "That sounds like a very challenging situation..."
+   - Expressing understanding: "I can see why that would be worrying..."
+   - Stating a shared goal: "Let's walk through how we can handle that..."
+   - Directly validating the feeling: "It's completely understandable to feel frustrated when..."
+2. Gently offer **1-2 of the most important practical steps**, combining general guidance with personal memories where appropriate. Do not use a list.
+3. If the scenario involves risk (like exit_seeking), subtly include a safety cue.
+4. End with a compassionate, de-escalation phrase.
+Your response in {language}:"""
+
+RISK_FOOTER = """If safety is a concern right now, please seek immediate assistance from onsite staff or local emergency services."""
+
+# ------------------------ Router & Specialized Templates ------------------------
+
+# --- NEW: Template for expanding user queries for better retrieval ---
+QUERY_EXPANSION_PROMPT = """You are a helpful AI assistant. Your task is to rephrase a user's question into 3 different, semantically similar questions to improve document retrieval.
+Provide the rephrased questions as a JSON list of strings.
+
+User Question: "{question}"
+
+JSON List:
+"""
+
+# Template for routing/classifying the user's intent
+ROUTER_PROMPT = """You are an expert NLU router. Your task is to classify the user's query into one of four categories:
+1.  `caregiving_scenario`: The user is describing a situation, asking for advice, or expressing a concern related to Alzheimer's or caregiving.
+2.  `factual_question`: The user is asking a direct question about a personal memory, person, or event that would be stored in the memory journal.
+3.  `general_knowledge_question`: The user is asking a general knowledge question about the world, facts, or topics not related to personal memories or caregiving (e.g., 'What is the capital of France?', 'Who directed the movie Inception?').
+4.  `general_conversation`: The user is making a general conversational remark, like a greeting, a thank you, or a simple statement that does not require a knowledge base lookup.
+
+User Query: "{query}"
+
+Respond with ONLY a single category name from the list above.
+Category: """
+
+# Template for answering direct factual questions
+ANSWER_TEMPLATE_FACTUAL = """Context:
+{context}
+
+---
+Question from user: {question}
+
+---
+Instructions:
+Based on the provided context, directly and concisely answer the user's question.
+- If the context contains the answer, state it clearly and naturally. Keep your response to a maximum of 3 sentences.
+- If the context does not contain the answer, respond in a warm and friendly tone that you couldn't find a memory of that topic and gently ask if the user would like to talk more about it or add it as a new memory.
+- Do not offer advice or suggestions unless they are part of the retrieved context.
+- ABSOLUTELY DO NOT invent, create, or hallucinate any stories, characters, or details. Your knowledge is limited to the provided context ONLY.
+
+Your response MUST be in {language}:"""
+
+
+# --- NEW: Template for answering general knowledge questions ---
+# Template for answering general knowledge questions
+ANSWER_TEMPLATE_GENERAL_KNOWLEDGE = """You are a factual answering engine.
+Your task is to directly answer the user's general knowledge question based on your training data.
+
+Instructions:
+- Be factual and concise. Go straight to the answer.
+- If the answer requires a list of examples, provide a maximum of 3 items. Do not use numbering.
+- Do NOT include apologies or disclaimers about your knowledge cutoff date.
+# - Do NOT recommend external websites or other services.
+# - Do NOT ask conversational follow-up questions.
+
+User's Question: "{question}"
+
+Your factual response in {language}:"""
+
+
+# Template for general, non-RAG conversation
+ANSWER_TEMPLATE_GENERAL = """You are a warm and friendly AI companion. The user has just said: "{question}".
+Respond in a brief, natural, and conversational way. Do not try to provide caregiving advice unless the user asks for it.
+Your response MUST be in {language}:"""
+
+
+# ------------------------ Convenience exports ------------------------
+__all__ = [
+    "SYSTEM_TEMPLATE", "ANSWER_TEMPLATE_CALM", "ANSWER_TEMPLATE_ADQ",
+    "SAFETY_GUARDRAILS", "RISK_FOOTER", "BEHAVIOUR_TAGS", "EMOTION_STYLES",
+    "render_emotion_guidelines", "CLASSIFICATION_PROMPT",
+
+    # --- New additions ---
+    "QUERY_EXPANSION_PROMPT"
+    "ROUTER_PROMPT",
+    "ANSWER_TEMPLATE_FACTUAL",
+    "ANSWER_TEMPLATE_GENERAL_KNOWLEDGE",
+    "ANSWER_TEMPLATE_GENERAL"
+]