Upload 2 files

alz_companion/agent.py

@@ -0,0 +1,338 @@
+
+from __future__ import annotations
+import os
+import json
+import base64
+import time
+import tempfile
+import re
+
+from typing import List, Dict, Any, Optional
+
+try:
+    from openai import OpenAI
+except Exception:
+    OpenAI = None
+
+from langchain.schema import Document
+from langchain_community.vectorstores import FAISS
+from langchain_community.embeddings import HuggingFaceEmbeddings
+
+try:
+    from gtts import gTTS
+except Exception:
+    gTTS = None
+
+from .prompts import (
+    SYSTEM_TEMPLATE, ANSWER_TEMPLATE_CALM, ANSWER_TEMPLATE_ADQ,
+    SAFETY_GUARDRAILS, RISK_FOOTER, render_emotion_guidelines,
+    NLU_ROUTER_PROMPT, SPECIALIST_CLASSIFIER_PROMPT,
+    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
+
+def describe_image(image_path: str) -> str:
+    client = _openai_client()
+    if not client:
+        return "(Image description failed: OpenAI API key not configured.)"
+    try:
+        extension = os.path.splitext(image_path)[1].lower()
+        mime_type = f"image/{'jpeg' if extension in ['.jpg', '.jpeg'] else extension.strip('.')}"
+        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 concisely for a memory journal. Focus on people, places, and key objects. Example: 'A photo of John and Mary smiling on a bench at the park.'"},
+                        {"type": "image_url", "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 (Dynamic Version)
+# -----------------------------
+
+def detect_tags_from_query(
+    query: str,
+    nlu_vectorstore: FAISS,
+    behavior_options: list,
+    emotion_options: list,
+    topic_options: list,
+    context_options: list,
+    settings: dict = None
+) -> Dict[str, Any]:
+    """Uses a dynamic two-step NLU process: Route -> Retrieve Examples -> Classify."""
+
+    # --- STEP 1: Route the query to determine the primary goal ---
+    router_prompt = NLU_ROUTER_PROMPT.format(query=query)
+    primary_goal_raw = call_llm([{"role": "user", "content": router_prompt}], temperature=0.0).strip().lower()
+
+    # --- FIX START: Use separate variables for the filter (lowercase) and the prompt (Title Case) ---
+    goal_for_filter = "practical_planning" if "practical" in primary_goal_raw else "emotional_support"
+    goal_for_prompt = "Practical Planning" if "practical" in primary_goal_raw else "Emotional Support"
+    # --- FIX END ---
+
+    if settings and settings.get("debug_mode"):
+        print(f"\n--- NLU Router ---\nGoal: {goal_for_prompt} (Filter: '{goal_for_filter}')\n------------------\n")
+
+    # --- STEP 2: Retrieve relevant examples from the NLU vector store ---
+    retriever = nlu_vectorstore.as_retriever(
+        search_kwargs={"k": 2, "filter": {"primary_goal": goal_for_filter}} # <-- Use the correct lowercase filter
+    )
+    retrieved_docs = retriever.invoke(query)
+
+    # Format the retrieved examples for the prompt
+    selected_examples = "\n".join(
+        f"User Query: \"{doc.page_content}\"\n{json.dumps(doc.metadata['classification'], indent=4)}"
+        for doc in retrieved_docs
+    )
+    if not selected_examples:
+        selected_examples = "(No relevant examples found)"
+        if settings and settings.get("debug_mode"):
+             print("WARNING: NLU retriever found no examples for this query.")
+
+
+    # --- STEP 3: Use the Specialist Classifier with retrieved examples ---
+    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 = SPECIALIST_CLASSIFIER_PROMPT.format(
+        primary_goal=goal_for_prompt, # Use Title Case for the prompt text
+        examples=selected_examples,
+        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."}, {"role": "user", "content": prompt}]
+    response_str = call_llm(messages, temperature=0.1)
+
+    if settings and settings.get("debug_mode"):
+        print(f"\n--- NLU Specialist Full Response ---\n{response_str}\n----------------------------------\n")
+
+    # --- STEP 4: Parse the final result ---
+    result_dict = {"detected_behaviors": [], "detected_emotion": "None", "detected_topic": "None", "detected_contexts": []}
+    try:
+        start_brace = response_str.find('{')
+        end_brace = response_str.rfind('}')
+        if start_brace != -1 and end_brace > start_brace:
+            json_str = response_str[start_brace : end_brace + 1]
+            result = json.loads(json_str)
+            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", "None")
+            result_dict["detected_topic"] = result.get("detected_topic", "None")
+            result_dict["detected_contexts"] = [c for c in result.get("detected_contexts", []) if c in context_options]
+        return result_dict
+    except (json.JSONDecodeError, AttributeError) as e:
+        print(f"ERROR parsing NLU Specialist JSON: {e}")
+        return result_dict
+
+# -----------------------------
+# Embeddings & VectorStore
+# -----------------------------
+
+def _default_embeddings():
+    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):
+                obj = json.loads(line.strip())
+                txt = obj.get("text") or ""
+                if not txt.strip(): continue
+                md = {"source": os.path.basename(path), "chunk": i}
+                for k in ("behaviors", "emotion", "topic_tags", "context_tags"):
+                    if k in obj and obj[k]: 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
+# -----------------------------
+def call_llm(messages: List[Dict[str, str]], temperature: float = 0.6, stop: Optional[List[str]] = None) -> str:
+    client = _openai_client()
+    model = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
+    if not client:
+        return "(Offline Mode: OpenAI API key not configured.)"
+    try:
+        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 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",
+):
+    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, topic_tag: Optional[str] = None, context_tags: Optional[List[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}, *chat_history]
+
+        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})
+            return {"answer": call_llm(messages, temperature=temperature), "sources": ["General Knowledge"]}
+
+        elif "factual_question" in query_type:
+            expansion_prompt = QUERY_EXPANSION_PROMPT.format(question=query)
+            expansion_response = call_llm([{"role": "user", "content": expansion_prompt}], temperature=0.1)
+            try:
+                expanded_queries = json.loads(expansion_response.strip().replace("```json", "").replace("```", ""))
+                search_queries = [query] + expanded_queries
+            except json.JSONDecodeError:
+                search_queries = [query]
+
+            all_docs = []
+            for q in search_queries:
+                all_docs.extend(vs_personal.similarity_search(q, k=2))
+                all_docs.extend(vs_general.similarity_search(q, k=2))
+            context = _format_docs(all_docs, "(No relevant information found.)")
+            user_prompt = ANSWER_TEMPLATE_FACTUAL.format(context=context, question=query, language=language)
+            messages.append({"role": "user", "content": user_prompt})
+            return {"answer": call_llm(messages, temperature=temperature), "sources": list(set(d.metadata.get("source", "unknown") for d in 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})
+            return {"answer": call_llm(messages, temperature=temperature), "sources": []}
+
+        else: # Default to caregiving logic
+            search_filter = {}
+            if scenario_tag: search_filter["behaviors"] = scenario_tag.lower()
+            if emotion_tag: search_filter["emotion"] = emotion_tag.lower()
+            if topic_tag: search_filter["topic_tags"] = topic_tag.lower()
+            if context_tags: search_filter["context_tags"] = {"in": [tag.lower() for tag in context_tags]}
+
+            personal_docs = vs_personal.similarity_search(query, k=3)
+            general_docs = vs_general.similarity_search(query, k=3)
+            if search_filter:
+                personal_docs.extend(vs_personal.similarity_search(query, k=3, filter=search_filter))
+                general_docs.extend(vs_general.similarity_search(query, k=3, filter=search_filter))
+
+            all_docs_care = list({doc.page_content: doc for doc in personal_docs + general_docs}.values())
+            personal_context = _format_docs([d for d in all_docs_care if d in personal_docs], "(No relevant personal memories found.)")
+            general_context = _format_docs([d for d in all_docs_care if d in general_docs], "(No general guidance found.)")
+
+            first_emotion = next((d.metadata.get("emotion") for d in all_docs_care if d.metadata.get("emotion")), None)
+            emotions_context = render_emotion_guidelines(first_emotion or emotion_tag)
+
+            template = ANSWER_TEMPLATE_ADQ if any([scenario_tag, emotion_tag, first_emotion]) 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)
+
+            if scenario_tag and scenario_tag.lower() in ["exit_seeking", "wandering"]:
+                answer += f"\n\n---\n{RISK_FOOTER}"
+
+            return {"answer": answer, "sources": list(set(d.metadata.get("source", "unknown") for d in 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": []}
+    try:
+        return chain(question, **kwargs)
+    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:
+        with tempfile.NamedTemporaryFile(suffix=".mp3", delete=False) as fp:
+            tts = gTTS(text=text, lang=(lang or "en"))
+            tts.save(fp.name)
+            return fp.name
+    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,231 @@
+"""
+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 (Dynamic Pipeline) ------------------------
+
+# --- STEP 1: Router for Primary Goal ---
+NLU_ROUTER_PROMPT = """You are an expert NLU router. Your task is to classify the user's primary goal into one of two categories:
+1.  `practical_planning`: The user is seeking a plan, strategy, "how-to" advice, or a solution to a problem.
+2.  `emotional_support`: The user is expressing feelings, seeking comfort, validation, or reassurance.
+
+User Query: "{query}"
+
+Respond with ONLY a single category name from the list above.
+Category: """
+
+# --- STEP 2: Specialist Classifier (Examples are now injected dynamically) ---
+SPECIALIST_CLASSIFIER_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. You will be given a few examples that are highly relevant to the user's query.
+
+--- 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?
+- **User's Primary Goal:** You have been told the user's goal is `{primary_goal}`. Briefly confirm if the query aligns with this goal.
+- **Tag Selection:** Based on the primary goal and the provided examples, 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}
+
+--- RELEVANT EXAMPLES ---
+{examples}
+---
+
+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 ------------------------
+
+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.
+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: """
+
+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.
+- 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}:"""
+
+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.
+- Do NOT include apologies or disclaimers about your knowledge cutoff date.
+User's Question: "{question}"
+
+Your factual response in {language}:"""
+
+
+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", 
+    "NLU_ROUTER_PROMPT", "SPECIALIST_CLASSIFIER_PROMPT",
+    "QUERY_EXPANSION_PROMPT",
+    "ROUTER_PROMPT",
+    "ANSWER_TEMPLATE_FACTUAL",
+    "ANSWER_TEMPLATE_GENERAL_KNOWLEDGE",
+    "ANSWER_TEMPLATE_GENERAL"
+]