Auto deploy from GitHub

.env.example

@@ -11,4 +11,10 @@ OPENROUTER_MODEL_NAME=openai/gpt-oss-20b:free
 SUPABASE_URL=your_project_url
 SUPABASE_KEY=your_anon_key
 SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
-SUPABASE_JWT_SECRET=your_jwt_secret
+SUPABASE_JWT_SECRET=your_jwt_secret
+# Optional: enable fallback to DEFAULT_PATIENT_UUID when no credentials provided (development only)
+DEV_ALLOW_DEFAULT_PATIENT=true
+# Optional: default patient id used in dev fallback
+DEFAULT_PATIENT_UUID=00000000-0000-0000-0000-000000000000
+# Rate limit per minute (integer)
+RATE_LIMIT_PER_MINUTE=30

app.py

@@ -1,8 +1,12 @@
-from fastapi import FastAPI, HTTPException, Depends
+from fastapi import FastAPI, HTTPException, Depends, Request
 from pydantic import BaseModel
 from typing import List, Dict, Any, Optional
+import datetime
 import os
 import sys
+import uuid
+import csv
+import datetime
 from dotenv import load_dotenv
 from langchain_core.messages import HumanMessage, AIMessage, ToolMessage
 from src.utils.logger import setup_logger
@@ -24,13 +28,17 @@ from src.tools.fhir_memory import (
     create_session, 
     get_sessions_by_patient, 
     get_chat_history_by_session,
-    save_chat_as_fhir
+    save_chat_as_fhir,
+    _get_client
+    get_chat_history_by_session
 )
+from src.mcp.server import MedicalMCPServer
 
 load_dotenv()
 logger = setup_logger("FastAPI")
 
 app = FastAPI(title="Medical AI Backend")
+mcp_server = MedicalMCPServer()
 
 class ChatMessage(BaseModel):
     role: str
@@ -43,6 +51,11 @@ class PipelineRequest(BaseModel):
     mode: str = "Standard Triage"  # "Standard Triage" or "CDM Proactive"
     history: List[Dict[str, Any]] = []
 
+class ClinicianScore(BaseModel):
+    trace_id: str
+    score: int
+    feedback: str
+
 class PipelineResponse(BaseModel):
     messages: List[Dict[str, Any]]
     final_state: Dict[str, Any]
@@ -91,10 +104,14 @@ async def process_pipeline(request: PipelineRequest, user_id: str = Depends(get_
     initial_messages = convert_to_langchain_messages(history)
     initial_messages.append(HumanMessage(content=enhanced_prompt))
     
+    trace_id = str(uuid.uuid4())
+    
     initial_state = {
         "messages": initial_messages,
         "user_role": "unknown",
         "intent_type": "unknown",
+        "trace_id": trace_id,
+        "session_id": session_id,
         "is_valid": False,
         "is_safe": False,
         "attempts": 0,
@@ -105,20 +122,15 @@ async def process_pipeline(request: PipelineRequest, user_id: str = Depends(get_
         "logs": [],
         "metrics": []
     }
-    
+
     initial_state["patient_id"] = patient_id
 
     try:
-        final_state = await active_pipeline.ainvoke(initial_state)
-        
-        # Save chat history as FHIR Communication linked to session
-        new_msgs_for_fhir = []
-        for msg in final_state["messages"][len(initial_messages)-1:]:
-            role = "user" if isinstance(msg, HumanMessage) else "assistant"
-            new_msgs_for_fhir.append({"role": role, "content": msg.content})
+        final_state = await active_pipeline.ainvoke(
+            initial_state,
+            config={"run_name": "MedicalPipeline", "metadata": {"trace_id": trace_id}}
+        )
         
-        save_chat_as_fhir.invoke({"patient_id": patient_id, "messages": new_msgs_for_fhir, "session_id": session_id})
-
         # Format messages for response
         resp_messages = []
         for msg in final_state["messages"][len(initial_messages):]:
@@ -146,6 +158,16 @@ async def list_sessions(user_id: str = Depends(get_active_user)):
 async def get_session_history(session_id: str, user_id: str = Depends(get_active_user)):
     return get_chat_history_by_session.invoke({"session_id": session_id})
 
+@app.post("/feedback/score")
+async def save_clinician_score(score_data: ClinicianScore, user_id: str = Depends(get_active_user)):
+    file_exists = os.path.isfile("clinician_scores.csv")
+    with open("clinician_scores.csv", mode="a", newline="", encoding="utf-8") as f:
+        writer = csv.writer(f)
+        if not file_exists:
+            writer.writerow(["trace_id", "user_id", "score", "feedback", "timestamp"])
+        writer.writerow([score_data.trace_id, user_id, score_data.score, score_data.feedback, datetime.datetime.now().isoformat()])
+    return {"status": "success", "message": "Score saved successfully"}
+
 @app.get("/patient/summary")
 async def get_patient_summary(user_id: str = Depends(get_active_user)):
     try:
@@ -171,6 +193,38 @@ async def set_llm_provider(provider: str, user_id: str = Depends(get_current_use
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
+@app.post("/mcp")
+async def mcp_endpoint(request: Request):
+    body = await request.json()
+    return await mcp_server.handle_request(body)
+
+@app.get("/Patient/{patient_id}")
+async def get_fhir_patient(patient_id: str):
+    client = _get_client()
+    res = client.table("patients").select("resource").eq("id", patient_id).execute()
+    if res.data:
+        return res.data[0]["resource"]
+    raise HTTPException(status_code=404, detail="Patient not found")
+
+@app.get("/Observation")
+async def get_fhir_observation(patient: str, code: Optional[str] = None):
+    client = _get_client()
+    query = client.table("observations").select("resource").eq("patient_id", patient)
+    res = query.execute()
+    observations = [r["resource"] for r in res.data]
+    if code:
+        observations = [
+            obs for obs in observations 
+            if any(c.get("code") == code for c in obs.get("code", {}).get("coding", []))
+        ]
+    return observations
+
+@app.get("/Communication")
+async def get_fhir_communication(patient: str):
+    client = _get_client()
+    res = client.table("communications").select("resource").eq("patient_id", patient).execute()
+    return [r["resource"] for r in res.data]
+
 if __name__ == "__main__":
     import uvicorn
     import datetime

main.py

@@ -1,7 +1,8 @@
-from fastapi import FastAPI, HTTPException
+from fastapi import FastAPI, HTTPException, Request
 from fastapi.middleware.cors import CORSMiddleware
 from pydantic import BaseModel
 from typing import List, Dict, Any, Optional
+import datetime
 import os
 import sys
 from dotenv import load_dotenv
@@ -17,7 +18,49 @@ from src.core.graph import medical_pipeline
 from src.core.graph_cdm import cdm_pipeline
 from src.core.model_manager import model_manager
 from src.agents.agent_instances import update_all_agents_llm
-from src.tools.fhir_memory import get_patient_summary_fhir, save_observation, save_patient
+from src.tools.fhir_memory import (
+    get_patient_summary_fhir,
+    save_observation,
+    save_patient,
+    create_session,
+    get_chat_history_by_session,
+    _get_client,
+)
+from src.utils.auth import create_dev_token
+import re
+import time
+import uuid
+
+# Simple in-memory rate limiter: keys map to list of request timestamps
+_RATE_LIMIT_WINDOW = 60  # seconds
+_RATE_LIMIT_MAX = int(os.getenv("RATE_LIMIT_PER_MINUTE", "30"))
+_rate_store = {}
+
+def _check_rate_limit(key: str):
+    now = time.time()
+    bucket = _rate_store.get(key, [])
+    # drop old
+    bucket = [t for t in bucket if now - t < _RATE_LIMIT_WINDOW]
+    if len(bucket) >= _RATE_LIMIT_MAX:
+        return False
+    bucket.append(now)
+    _rate_store[key] = bucket
+    return True
+
+_PROMPT_INJECTION_PATTERNS = [
+    r"ignore (system|instructions|previous|above)",
+    r"disregard (previous|above|system)",
+    r"do not follow (system|instructions)",
+    r"override (system|instructions)",
+]
+
+def _detect_prompt_injection(text: str) -> bool:
+    if not text:
+        return False
+    for p in _PROMPT_INJECTION_PATTERNS:
+        if re.search(p, text, re.IGNORECASE):
+            return True
+    return False
 
 load_dotenv()
 logger = setup_logger("FastAPI")
@@ -43,12 +86,14 @@ class ChatMessage(BaseModel):
 class PipelineRequest(BaseModel):
     prompt: str
     patient_id: Optional[str] = None
+    session_id: Optional[str] = None
     mode: str = "Standard Triage"  # "Standard Triage" or "CDM Proactive"
     history: List[Dict[str, Any]] = []
 
 class PipelineResponse(BaseModel):
     messages: List[Dict[str, Any]]
     final_state: Dict[str, Any]
+    session_id: Optional[str] = None
 
 def convert_to_langchain_messages(history):
     messages = []
@@ -56,32 +101,58 @@ def convert_to_langchain_messages(history):
         if msg["role"] == "user":
             messages.append(HumanMessage(content=msg["content"]))
         elif msg["role"] == "assistant":
-            # For now, simplifying. Full implementation would handle tool calls.
             messages.append(AIMessage(content=msg["content"]))
     return messages
 
+
+def load_session_history(session_id: str):
+    if not session_id:
+        return []
+
+    raw_history = get_chat_history_by_session.invoke({"session_id": session_id})
+    history = []
+    for comm in raw_history:
+        payload = comm.get("payload", [])
+        for item in payload:
+            content = item.get("contentString", "")
+            if ":" in content:
+                role, text = content.split(":", 1)
+                history.append({"role": role.strip(), "content": text.strip()})
+    return history
+
 import json
 from fastapi.responses import StreamingResponse
 
 @app.post("/process_stream")
 async def process_pipeline_stream(request: PipelineRequest):
     logger.info(f"Streaming request for mode: {request.mode}")
-    
-    # Select pipeline
+
+    history = list(request.history)
+    session_id = request.session_id
+    if not session_id and request.patient_id:
+        session_id = create_session.invoke(
+            {
+                "patient_id": request.patient_id,
+                "title": f"Session {datetime.datetime.now().strftime('%Y-%m-%d %H:%M')}",
+            }
+        )
+    if session_id and not history:
+        history = load_session_history(session_id)
+
     active_pipeline = cdm_pipeline if request.mode == "CDM Proactive" else medical_pipeline
-    
-    # Prepare initial state
+
     enhanced_prompt = request.prompt
     if request.patient_id:
         enhanced_prompt = f"[System: User's Patient ID is {request.patient_id}]\n\n{request.prompt}"
-    
-    initial_messages = convert_to_langchain_messages(request.history)
+
+    initial_messages = convert_to_langchain_messages(history)
     initial_messages.append(HumanMessage(content=enhanced_prompt))
-    
+
     initial_state = {
         "messages": initial_messages,
         "user_role": "unknown",
         "intent_type": "unknown",
+        "session_id": session_id,
         "is_valid": False,
         "is_safe": False,
         "attempts": 0,
@@ -90,46 +161,72 @@ async def process_pipeline_stream(request: PipelineRequest):
         "research_output": "",
         "sources": [],
         "logs": [],
-        "metrics": []
+        "metrics": [],
     }
-    
+
     if request.patient_id:
         initial_state["patient_id"] = request.patient_id
 
+    final_state = None
+
     async def event_generator():
+        saw_stream = False
+
+        def chunk_text(text: str, size: int = 24):
+            for start in range(0, len(text), size):
+                yield text[start:start + size]
+
+        nonlocal final_state
         try:
-            # Using astream_events v2 for more granular control
             async for event in active_pipeline.astream_events(initial_state, version="v2"):
                 kind = event["event"]
-                
+
                 # Progress Update: Node start
                 if kind == "on_chain_start" and event.get("name") in [
-                    "role_classifier", "patient_llm", "safety_check", "validator", 
-                    "intent_classifier", "persistence_node", "tools_node"
+                    "role_classifier", "patient_llm", "caregiver_llm", "safety_check", "validator", 
+                    "intent_classifier", "persistence_node", "tools_node",
+                    "diagnosis_assist", "treatment_assist", "monitoring_assist", "general_assist",
+                    "merge_outputs", "research_agent", "dietary_assist"
                 ]:
                     yield f"data: {json.dumps({'type': 'node', 'node': event['name']})}\n\n"
-                
+
                 # Progress Update: Graph Nodes
+                if kind == "on_chain_start" and event.get("name") in [
+                    "role_classifier",
+                    "patient_llm",
+                    "safety_check",
+                    "validator",
+                    "intent_classifier",
+                    "persistence_node",
+                    "tools_node",
+                ]:
+                    yield f"data: {json.dumps({'type': 'node', 'node': event['name']})}\n\n"
+
                 elif kind == "on_chain_end" and "node" in event.get("metadata", {}):
                     node_name = event["metadata"]["node"]
                     yield f"data: {json.dumps({'type': 'node_complete', 'node': node_name})}\n\n"
 
-                # Token Streaming: Chat Model stream
                 elif kind == "on_chat_model_stream":
-                    content = event["data"]["chunk"].content
+                    content = getattr(event["data"]["chunk"], "content", "")
                     if content:
+                        saw_stream = True
                         yield f"data: {json.dumps({'type': 'token', 'content': content})}\n\n"
-                
+
                 # Final State: End of graph
                 elif kind == "on_chain_end" and event["name"] == "LangGraph":
-                    final_state = event["data"]["output"]
+                    final_state = event["data"].get("output", {}) or {}
                     final_msg = ""
+                    
+                    # Extract the final message from the state
                     if "messages" in final_state and final_state["messages"]:
-                        final_msg = final_state["messages"][-1].content
-                    # Format state for frontend
+                        last_msg = final_state["messages"][-1]
+                        final_msg = last_msg.content if hasattr(last_msg, "content") else str(last_msg)
+                    
+                    # Format state for frontend (exclude messages to save bandwidth)
                     clean_state = {k: v for k, v in final_state.items() if k != "messages"}
-                    yield f"data: {json.dumps({'type': 'end', 'final_state': clean_state, 'final_message': final_msg})}\n\n"
                     
+                    yield f"data: {json.dumps({'type': 'end', 'final_state': clean_state, 'final_message': final_msg})}\n\n"
+
         except Exception as e:
             logger.error(f"Streaming error: {str(e)}")
             yield f"data: {json.dumps({'type': 'error', 'detail': str(e)})}\n\n"
@@ -139,22 +236,33 @@ async def process_pipeline_stream(request: PipelineRequest):
 @app.post("/process", response_model=PipelineResponse)
 async def process_pipeline(request: PipelineRequest):
     logger.info(f"Processing request for mode: {request.mode}")
-    
-    # Select pipeline
+
+    history = list(request.history)
+    session_id = request.session_id
+    if not session_id and request.patient_id:
+        session_id = create_session.invoke(
+            {
+                "patient_id": request.patient_id,
+                "title": f"Session {datetime.datetime.now().strftime('%Y-%m-%d %H:%M')}",
+            }
+        )
+    if session_id and not history:
+        history = load_session_history(session_id)
+
     active_pipeline = cdm_pipeline if request.mode == "CDM Proactive" else medical_pipeline
-    
-    # Prepare initial state
+
     enhanced_prompt = request.prompt
     if request.patient_id:
         enhanced_prompt = f"[System: User's Patient ID is {request.patient_id}]\n\n{request.prompt}"
-    
-    initial_messages = convert_to_langchain_messages(request.history)
+
+    initial_messages = convert_to_langchain_messages(history)
     initial_messages.append(HumanMessage(content=enhanced_prompt))
-    
+
     initial_state = {
         "messages": initial_messages,
         "user_role": "unknown",
         "intent_type": "unknown",
+        "session_id": session_id,
         "is_valid": False,
         "is_safe": False,
         "attempts": 0,
@@ -163,30 +271,31 @@ async def process_pipeline(request: PipelineRequest):
         "research_output": "",
         "sources": [],
         "logs": [],
-        "metrics": []
+        "metrics": [],
     }
-    
+
     if request.patient_id:
         initial_state["patient_id"] = request.patient_id
 
     try:
-        # Run the pipeline
         final_state = await active_pipeline.ainvoke(initial_state)
-        
-        # Format messages for response
+
         resp_messages = []
         for msg in final_state["messages"][len(initial_messages):]:
             from langchain_core.messages import AIMessage, ToolMessage
             msg_type = "assistant" if isinstance(msg, AIMessage) else "tool" if isinstance(msg, ToolMessage) else "user"
-            resp_messages.append({
-                "role": msg_type,
-                "content": msg.content,
-                "type": msg.__class__.__name__
-            })
-            
+            resp_messages.append(
+                {
+                    "role": msg_type,
+                    "content": msg.content,
+                    "type": msg.__class__.__name__,
+                }
+            )
+
         return PipelineResponse(
             messages=resp_messages,
-            final_state={k: v for k, v in final_state.items() if k != "messages"}
+            final_state={k: v for k, v in final_state.items() if k != "messages"},
+            session_id=session_id,
         )
     except Exception as e:
         logger.error(f"Pipeline error: {str(e)}")
@@ -225,3 +334,84 @@ if __name__ == "__main__":
     port = int(os.environ.get("PORT", 8000))
     logger.info(f"Starting server on port {port}")
     uvicorn.run("main:app", host="0.0.0.0", port=port, reload=False)
+
+
+class RegisterRequest(BaseModel):
+    username: str
+    first_name: str
+    last_name: str
+
+@app.post("/auth/register")
+async def dev_register(req: RegisterRequest):
+    if not req.username.strip():
+        raise HTTPException(status_code=400, detail="Username is required")
+    if not req.first_name.strip():
+        raise HTTPException(status_code=400, detail="First name is required")
+    if not req.last_name.strip():
+        raise HTTPException(status_code=400, detail="Last name is required")
+    
+    client = _get_client()
+    try:
+        # Check if username already exists
+        res = client.table("patients").select("id").eq("resource->>username", req.username.strip()).execute()
+        if res.data:
+            raise HTTPException(status_code=400, detail="Username already exists")
+        
+        pid = str(uuid.uuid4())
+        full_name = f"{req.first_name.strip()} {req.last_name.strip()}"
+        fhir_patient = {
+            "resourceType": "Patient",
+            "id": pid,
+            "active": True,
+            "name": [{
+                "text": full_name,
+                "use": "official",
+                "given": [req.first_name.strip()],
+                "family": req.last_name.strip()
+            }],
+            "username": req.username.strip(),
+            "meta": {
+                "lastUpdated": datetime.datetime.now(datetime.timezone.utc).isoformat()
+            }
+        }
+        data = {
+            "id": pid,
+            "resource": fhir_patient,
+            "last_updated": datetime.datetime.now(datetime.timezone.utc).isoformat()
+        }
+        client.table("patients").insert(data).execute()
+        
+        token = create_dev_token(pid, expires_minutes=24 * 60)
+        return {"status": "ok", "patient_id": pid, "token": token}
+    except HTTPException as he:
+        raise he
+    except Exception as e:
+        logger.error(f"Failed to register: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+class LoginRequest(BaseModel):
+    username: str
+
+@app.post("/auth/login")
+async def dev_login(req: LoginRequest):
+    """Development-only login endpoint that verifies username.
+    """
+    if not req.username:
+        raise HTTPException(status_code=400, detail="Username required")
+    
+    client = _get_client()
+    try:
+        res = client.table("patients").select("*").eq("resource->>username", req.username.strip()).execute()
+        if not res.data:
+            raise HTTPException(status_code=404, detail="Username not found. Please register first.")
+        
+        patient = res.data[0]
+        pid = patient["id"]
+        token = create_dev_token(pid, expires_minutes=24 * 60)
+        return {"status": "ok", "patient_id": pid, "token": token}
+    except HTTPException as he:
+        raise he
+    except Exception as e:
+        logger.error(f"Failed to login: {e}")
+        raise HTTPException(status_code=500, detail=str(e))

requirements.txt

@@ -7,8 +7,6 @@ pysqlite3
 bs4
 requests
 pypdf
-pymongo
-langchain-mongodb
 langchain-openai
 pydantic
 ddgs

src/agent_params.py

@@ -0,0 +1,18 @@
+import json
+from pathlib import Path
+
+
+def _load_params() -> dict:
+    params_path = Path(__file__).with_name("params.json")
+    if not params_path.exists():
+        return {}
+
+    with params_path.open("r", encoding="utf-8") as handle:
+        data = json.load(handle)
+
+    return data if isinstance(data, dict) else {}
+
+
+def get_agent_params(agent_name: str) -> dict:
+    params = _load_params().get(agent_name, {})
+    return params if isinstance(params, dict) else {}

src/agents/agent_instances.py

@@ -1,5 +1,5 @@
 from src.agents.agents import (
-    RoleClassifier, PatientLLM, ResponseValidator, SafetyCheck,
+    RoleClassifier, PatientLLM, CaregiverLLM, ResponseValidator, SafetyCheck,
     IntentClassifier, ClinicalSpecialist, OutputMerger, ResearchAgent,
     DietarySpecialist
 )
@@ -11,6 +11,7 @@ logger = setup_logger("AgentInstances")
 # Instantiate all agents
 role_classifier = RoleClassifier()
 patient_llm = PatientLLM()
+caregiver_llm = CaregiverLLM()
 validator = ResponseValidator()
 safety_check = SafetyCheck()
 intent_classifier = IntentClassifier()
@@ -31,21 +32,19 @@ trend_analyzer = TrendAnalyzer()
 
 def update_all_agents_llm(provider_name: str):
     from src.core.model_manager import model_manager
-    
+
     if model_manager.provider == provider_name.lower():
         return
-        
+
     model_manager.provider = provider_name.lower()
     logger.info(f"Switching LLM provider to: {provider_name}")
-    
+
     all_agents = [
-        role_classifier, patient_llm, validator, safety_check,
+        role_classifier, patient_llm, caregiver_llm, validator, safety_check,
         intent_classifier, diagnosis_assist, treatment_assist,
         monitoring_assist, general_assist, output_merger,
         research_agent, dietary_assist, health_coach, trend_analyzer
     ]
-    
+
     for agent in all_agents:
-        agent.llm = model_manager.get_llm()
-        if hasattr(agent, 'tools') and agent.tools:
-            agent.llm = agent.llm.bind_tools(agent.tools)
+        agent._refresh_llm()

src/agents/agents.py

@@ -1,113 +1,164 @@
 import os
-import sys
-from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
-from langchain_core.prompts import ChatPromptTemplate
+import re
 import json
 import time
+from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
 from src.utils.logger import setup_logger
 
 logger = setup_logger("Agents")
 
-# Absolute import management for the new structure - removed as it's redundant and can cause issues
-
+from src.agent_params import get_agent_params
 from src.core.model_manager import model_manager
 from src.core.state import AgentState
+from src.core.evidence_models import ClinicalOutputWithEvidence, EvidenceCitation
 from src.tools.web_tools import web_search_tool
 from src.tools.dietary_tools import search_guidelines, get_nutritional_data, page_indexed_retrieval
 from src.tools.patient_memory import save_patient_memory, get_patient_memory
+from src.agents.role_utils import classify_role
+from datetime import datetime
+
 
 class BaseAgent:
-    def __init__(self, fallback_prompt: str, prompt_file: str = None, tools: list = None):
-        self.llm = model_manager.get_llm()
-        self.tools = tools
-        if tools:
-            # We use bind_tools for LLMs that support it
-            self.llm = self.llm.bind_tools(tools)
+    def __init__(self, fallback_prompt: str, prompt_file: str = None, tools: list = None, agent_name: str = None):
+        self.agent_name = agent_name or self.__class__.__name__
         self.fallback_prompt = fallback_prompt
         self.prompt_file = prompt_file
+        self.tools = tools or []
+        self.params = get_agent_params(self.agent_name)
+        self.temperature = float(self.params.get("temperature", 0.0))
+        self.model_name = self.params.get("model_name")
+        self._refresh_llm()
+
+    def _refresh_llm(self):
+        llm = model_manager.get_llm(
+            temperature=self.temperature,
+            model_name=self.model_name,
+        )
+        if self.tools:
+            llm = llm.bind_tools(self.tools)
+        self.llm = llm
+
+    def parse_json_response(self, response_text: str):
+        if not response_text:
+            return {}
+
+        text = response_text.strip()
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            match = re.search(r"\{.*\}", text, re.S)
+            if not match:
+                return {}
+            try:
+                return json.loads(match.group(0))
+            except json.JSONDecodeError:
+                return {}
 
     @property
     def system_prompt(self) -> str:
         """Dynamically load prompt from file if available, otherwise use fallback."""
         if self.prompt_file:
-            # Get the path relative to this file's location
             current_dir = os.path.dirname(os.path.abspath(__file__))
             prompt_path = os.path.abspath(os.path.join(current_dir, "..", "prompts", self.prompt_file))
             try:
                 if os.path.exists(prompt_path):
-                    with open(prompt_path, "r", encoding="utf-8") as f:
-                        return f.read().strip()
-            except Exception as e:
-                # Log locally or via print, then fall back
-                pass
-        return self.fallback_prompt
+                    with open(prompt_path, "r", encoding="utf-8") as handle:
+                        prompt = handle.read().strip()
+                else:
+                    prompt = self.fallback_prompt
+            except Exception:
+                prompt = self.fallback_prompt
+        else:
+            prompt = self.fallback_prompt
+
+        skip_confidence = self.agent_name in {"ResponseValidator", "SafetyCheck"}
+        confidence_instruction = (
+            "\n\nAt the end of your response, include a confidence score from 0.0 to 1.0 "
+            "in the format: Confidence: 0.8"
+        )
+        if not skip_confidence and "confidence" not in prompt.lower():
+            prompt = f"{prompt}{confidence_instruction}"
+        return prompt
 
     async def run(self, state: AgentState, config=None):
         """Standard run method for graph nodes."""
         messages = [SystemMessage(content=self.system_prompt)] + state["messages"]
-        logger.info(f"--- Sending {len(messages)} messages to LLM ({self.__class__.__name__}) ---")
-        
+        logger.info(f"--- Sending {len(messages)} messages to LLM ({self.agent_name}) ---")
+
         start_time = time.time()
         try:
             response = await self.llm.ainvoke(messages, config=config)
             end_time = time.time()
-            
-            # Extract tokens
+
             tokens = 0
             if hasattr(response, "usage_metadata") and response.usage_metadata:
                 tokens = response.usage_metadata.get("total_tokens", 0)
             elif "token_usage" in response.response_metadata:
                 tokens = response.response_metadata["token_usage"].get("total_tokens", 0)
-                
+
+            confidence = None
+            if hasattr(response, "content") and isinstance(response.content, str):
+                match = re.search(r"Confidence(?:\s+Score)?:\s*([0-9.]+)", response.content, re.IGNORECASE)
+                if match:
+                    try:
+                        confidence = float(match.group(1))
+                    except ValueError:
+                        pass
+
             metrics = {
-                "agent": self.__class__.__name__,
+                "agent": self.agent_name,
                 "tokens": tokens,
-                "time": round(end_time - start_time, 3)
+                "time": round(end_time - start_time, 3),
+                "confidence": confidence
             }
-            
+
             return {"messages": [response], "metrics": [metrics]}
         except Exception as e:
-            logger.error(f"Error in {self.__class__.__name__}.run: {e}")
+            logger.error(f"Error in {self.agent_name}.run: {e}")
             raise
 
+
 class RoleClassifier(BaseAgent):
     def __init__(self):
-        fallback_prompt = """You are a medical triage assistant. 
-        Classify the user input into one of four roles: 'patient', 'clinician', 'researcher', or 'dietary'. Return only the name."""
+        fallback_prompt = """You are a medical triage assistant.
+        Classify the user input into one of five roles: 'patient', 'caregiver', 'clinician', 'researcher', or 'dietary'. Return only the name."""
         super().__init__(fallback_prompt, "RoleClassifier.txt")
 
     async def run(self, state: AgentState):
         messages = [SystemMessage(content=self.system_prompt)] + state["messages"]
         logger.info(f"--- RoleClassifier: Sending {len(messages)} messages to LLM ---")
-        
+
+        user_message = state["messages"][-1].content.lower() if state["messages"] else ""
+        role = classify_role(user_message)
+
         start_time = time.time()
         try:
-            response = await self.llm.ainvoke(messages)
-            end_time = time.time()
-            
-            role = response.content.lower().strip()
-            if not role:
-                role = "patient"
-            roles = ["patient", "clinician", "researcher", "dietary"]
-            for r in roles:
-                if r in role:
-                    role = r
-                    break
-            if role not in roles:
-                role = "patient"
-                
-            tokens = 0
-            if hasattr(response, "usage_metadata") and response.usage_metadata:
-                tokens = response.usage_metadata.get("total_tokens", 0)
-            elif "token_usage" in response.response_metadata:
-                tokens = response.response_metadata["token_usage"].get("total_tokens", 0)
-                
+            if role is None:
+                response = await self.llm.ainvoke(messages)
+                end_time = time.time()
+                raw = response.content.lower()
+                if not raw.strip():
+                    role = "patient"
+                else:
+                    roles = ["patient", "caregiver", "clinician", "researcher", "dietary"]
+                    role = next((r for r in roles if r in raw), "patient")
+                tokens = 0
+                if hasattr(response, "usage_metadata") and response.usage_metadata:
+                    tokens = response.usage_metadata.get("total_tokens", 0)
+                elif "token_usage" in response.response_metadata:
+                    tokens = response.response_metadata["token_usage"].get("total_tokens", 0)
+                duration = round(end_time - start_time, 3)
+            else:
+                end_time = time.time()
+                tokens = 0
+                duration = round(end_time - start_time, 3)
+
             metrics = {
                 "agent": "RoleClassifier",
                 "tokens": tokens,
-                "time": round(end_time - start_time, 3)
+                "time": duration
             }
-            
+
             return {"user_role": role, "metrics": [metrics]}
         except Exception as e:
             logger.error(f"Error in RoleClassifier.run: {e}")
@@ -119,71 +170,99 @@ class PatientLLM(BaseAgent):
         Provide helpful, empathetic, and medically sound advice."""
         super().__init__(fallback_prompt, "PatientLLM.txt", tools=[web_search_tool, save_patient_memory, get_patient_memory])
 
+class CaregiverLLM(BaseAgent):
+    def __init__(self):
+        fallback_prompt = """You are a supportive caregiver assistant for a diabetes management platform.
+        Help caregivers interpret symptoms, monitor treatment adherence, and know when to escalate to urgent care.
+        Frame advice as practical proxy guidance for a patient while remaining clear and compassionate."""
+        super().__init__(fallback_prompt, "CaregiverLLM.txt", tools=[web_search_tool, save_patient_memory, get_patient_memory])
+
 class ResponseValidator(BaseAgent):
     def __init__(self):
-        fallback_prompt = """You are a medical response validator. 
-        Check if the last response is medically accurate and follows guidelines. Return 'valid' or 'invalid'."""
+        fallback_prompt = """You are a medical response validator.
+        Check if the last response is medically accurate and follows guidelines. Return JSON only."""
         super().__init__(fallback_prompt, "ResponseValidator.txt")
 
     async def run(self, state: AgentState):
-        # We check the last AI message in the state
         last_message = state["messages"][-1].content
-        
+
         start_time = time.time()
         response = await self.llm.ainvoke([
             SystemMessage(content=self.system_prompt),
             HumanMessage(content=f"Verify this response: {last_message}")
         ])
         end_time = time.time()
-        
-        is_valid = "valid" in response.content.lower()
-        
+
+        parsed = self.parse_json_response(response.content)
+        decision = parsed.get("decision", "invalid").lower()
+        is_valid = decision == "valid"
+        if not parsed:
+            lower_response = response.content.lower()
+            if re.search(r"\binvalid\b", lower_response):
+                is_valid = False
+            elif re.search(r"\bvalid\b", lower_response):
+                is_valid = True
+            else:
+                is_valid = False
+
         tokens = 0
         if hasattr(response, "usage_metadata") and response.usage_metadata:
             tokens = response.usage_metadata.get("total_tokens", 0)
         elif "token_usage" in response.response_metadata:
             tokens = response.response_metadata["token_usage"].get("total_tokens", 0)
-            
+
         metrics = {
             "agent": "ResponseValidator",
             "tokens": tokens,
             "time": round(end_time - start_time, 3)
         }
-        
+
         return {"is_valid": is_valid, "metrics": [metrics]}
 
+
 class SafetyCheck(BaseAgent):
     def __init__(self):
-        fallback_prompt = """You are a medical safety officer. 
-        Check if the response contains any dangerous advice or misinformation. Return 'safe' or 'unsafe'."""
+        fallback_prompt = """You are a medical safety officer.
+        Check if the response contains any dangerous advice or misinformation. Return JSON only."""
         super().__init__(fallback_prompt, "SafetyCheck.txt")
 
     async def run(self, state: AgentState):
         last_message = state["messages"][-1].content
-        
+
         start_time = time.time()
         response = await self.llm.ainvoke([
             SystemMessage(content=self.system_prompt),
             HumanMessage(content=f"Safety check on this: {last_message}")
         ])
         end_time = time.time()
-        
-        is_safe = "safe" in response.content.lower()
-        
+
+        parsed = self.parse_json_response(response.content)
+        decision = parsed.get("decision", "unsafe").lower()
+        is_safe = decision == "safe"
+        if not parsed:
+            lower_response = response.content.lower()
+            if re.search(r"\bunsafe\b", lower_response):
+                is_safe = False
+            elif re.search(r"\bsafe\b", lower_response):
+                is_safe = True
+            else:
+                is_safe = False
+
         tokens = 0
         if hasattr(response, "usage_metadata") and response.usage_metadata:
             tokens = response.usage_metadata.get("total_tokens", 0)
         elif "token_usage" in response.response_metadata:
             tokens = response.response_metadata["token_usage"].get("total_tokens", 0)
-            
+
         metrics = {
             "agent": "SafetyCheck",
             "tokens": tokens,
             "time": round(end_time - start_time, 3)
         }
-        
+
         return {"is_safe": is_safe, "metrics": [metrics]}
 
+
 class IntentClassifier(BaseAgent):
     def __init__(self):
         fallback_prompt = """You are a clinical intent classifier. 
@@ -212,15 +291,170 @@ class IntentClassifier(BaseAgent):
         return {"intent_type": intent, "metrics": [metrics]}
 
 class ClinicalSpecialist(BaseAgent):
+    """
+    Clinical specialist agent with structured output including evidence citations.
+    Bug 12.3: Provides explainability through guideline sources and evidence levels.
+    """
     def __init__(self, specialty: str):
         fallback_prompt = f"You are a clinical specialist in {specialty}. Provide expert medical support."
         super().__init__(fallback_prompt, f"ClinicalSpecialist_{specialty}.txt")
+        self.specialty = specialty
+    
+    async def run(self, state: AgentState, config=None):
+        """
+        Run clinical specialist with structured output requiring evidence citations.
+        Returns both the text response and evidence citations in AgentState.
+        """
+        messages = [SystemMessage(content=self.system_prompt)] + state["messages"]
+        logger.info(f"--- ClinicalSpecialist ({self.specialty}): Running with evidence structure ---")
+        
+        start_time = time.time()
+        try:
+            # Use structured output with the LLM if available
+            try:
+                # Try to use with_structured_output for models that support it
+                llm_with_output = self.llm.with_structured_output(ClinicalOutputWithEvidence)
+                response = await llm_with_output.ainvoke(messages, config=config)
+            except (AttributeError, NotImplementedError):
+                # Fallback: regular invocation and manual extraction
+                logger.warning(f"Model does not support structured output, using fallback")
+                response = await self.llm.ainvoke(messages, config=config)
+                # Create a basic ClinicalOutputWithEvidence from the response
+                from src.core.evidence_models import Citation
+                response = ClinicalOutputWithEvidence(
+                    recommendation=response.content[:200] if hasattr(response, 'content') else str(response),
+                    explanation=response.content if hasattr(response, 'content') else str(response),
+                    citations=[
+                        Citation(
+                            source_document="Knowledge Base",
+                            evidence_level="C",
+                            section="General"
+                        )
+                    ],
+                    confidence_score=0.7
+                )
+            
+            end_time = time.time()
+            
+            # Extract tokens
+            tokens = 0
+            if hasattr(response, "usage_metadata") and response.usage_metadata:
+                tokens = response.usage_metadata.get("total_tokens", 0)
+            elif isinstance(response, dict) and "usage_metadata" in response:
+                tokens = response["usage_metadata"].get("total_tokens", 0)
+            elif hasattr(response, "response_metadata") and "token_usage" in response.response_metadata:
+                tokens = response.response_metadata["token_usage"].get("total_tokens", 0)
+            
+            confidence = 0.7
+            if isinstance(response, ClinicalOutputWithEvidence):
+                output_content = response.recommendation
+                citations = response.citations
+                confidence = getattr(response, "confidence_score", 0.7)
+            else:
+                output_content = response.content if hasattr(response, 'content') else str(response)
+                citations = []
+                if isinstance(output_content, str):
+                    match = re.search(r"Confidence(?:\s+Score)?:\s*([0-9.]+)", output_content, re.IGNORECASE)
+                    if match:
+                        try:
+                            confidence = float(match.group(1))
+                        except ValueError:
+                            pass
+
+            metrics = {
+                "agent": f"ClinicalSpecialist({self.specialty})",
+                "tokens": tokens,
+                "time": round(end_time - start_time, 3),
+                "confidence": confidence
+            }
+            
+            # Build evidence citations from the structured output
+            evidence_citations = []
+            for idx, citation in enumerate(citations):
+                evidence_citation = {
+                    "recommendation_id": f"{self.specialty}_{idx}",
+                    "source_document": citation.source_document if hasattr(citation, 'source_document') else "Unknown",
+                    "page_number": getattr(citation, 'page_number', None),
+                    "evidence_level": getattr(citation, 'evidence_level', 'C'),
+                    "agent_name": f"ClinicalSpecialist({self.specialty})",
+                    "timestamp": datetime.utcnow().isoformat()
+                }
+                evidence_citations.append(evidence_citation)
+            
+            from langchain_core.messages import AIMessage
+            return {
+                "messages": [AIMessage(content=output_content)],
+                "metrics": [metrics],
+                "evidence_citations": evidence_citations
+            }
+            
+        except Exception as e:
+            logger.error(f"Error in ClinicalSpecialist({self.specialty}).run: {e}")
+            raise
 
 class OutputMerger(BaseAgent):
     def __init__(self):
         fallback_prompt = "You are a clinical coordinator. Merge outputs into a single cohesive report."
         super().__init__(fallback_prompt, "OutputMerger.txt")
 
+    async def run(self, state: AgentState, config=None):
+        latest_user_message = None
+        for message in reversed(state["messages"]):
+            if getattr(message, "type", None) == "human":
+                latest_user_message = message.content
+                break
+
+        human_messages = []
+        if latest_user_message:
+            human_messages.append(HumanMessage(content=f"Original user request:\n{latest_user_message}"))
+
+        clinician_outputs = state.get("clinician_outputs") or []
+        if clinician_outputs:
+            human_messages.append(
+                HumanMessage(content="Latest specialist outputs:\n" + "\n\n".join(clinician_outputs))
+            )
+
+        messages = [SystemMessage(content=self.system_prompt)] + human_messages
+
+        start_time = time.time()
+        response = None
+        full_content = ""
+        async for chunk in self.llm.astream(messages, config=config):
+            response = chunk
+            if chunk and hasattr(chunk, "content") and isinstance(chunk.content, str):
+                full_content += chunk.content
+
+        if response is None:
+            response = await self.llm.ainvoke(messages, config=config)
+            if response and hasattr(response, "content") and isinstance(response.content, str):
+                full_content = response.content
+
+        end_time = time.time()
+
+        tokens = 0
+        if hasattr(response, "usage_metadata") and response.usage_metadata:
+            tokens = response.usage_metadata.get("total_tokens", 0)
+        elif "token_usage" in response.response_metadata:
+            tokens = response.response_metadata["token_usage"].get("total_tokens", 0)
+
+        confidence = None
+        if full_content:
+            match = re.search(r"Confidence(?:\s+Score)?:\s*([0-9.]+)", full_content, re.IGNORECASE)
+            if match:
+                try:
+                    confidence = float(match.group(1))
+                except ValueError:
+                    pass
+
+        metrics = {
+            "agent": self.__class__.__name__,
+            "tokens": tokens,
+            "time": round(end_time - start_time, 3),
+            "confidence": confidence
+        }
+
+        return {"messages": [response], "metrics": [metrics]}
+
 class ResearchAgent(BaseAgent):
     def __init__(self):
         fallback_prompt = """You are a medical research assistant. Provide detailed information for researchers."""
@@ -230,8 +464,6 @@ class DietarySpecialist(BaseAgent):
     def __init__(self):
         fallback_prompt = """You are a certified dietary specialist. Provide advice based on guidelines."""
         super().__init__(fallback_prompt, "DietarySpecialist.txt", tools=[search_guidelines, get_nutritional_data, page_indexed_retrieval, save_patient_memory, get_patient_memory])
-    
+
     async def run(self, state: AgentState, config=None):
-        messages = [SystemMessage(content=self.system_prompt)] + state["messages"]
-        response = await self.llm.ainvoke(messages, config=config)
-        return {"messages": [response]}
+        return await super().run(state, config=config)

src/agents/cdm_agents.py

@@ -1,8 +1,9 @@
 import json
 import time
+from datetime import datetime, timedelta
 from src.agents.agents import BaseAgent
 from src.core.state import AgentState
-from src.tools.fhir_memory import get_observations_by_patient
+from src.tools.fhir_memory import get_observations_by_patient, get_medications_by_patient
 from langchain_core.messages import SystemMessage, HumanMessage
 from src.utils.logger import setup_logger
 
@@ -12,7 +13,8 @@ class HealthCoach(BaseAgent):
     def __init__(self):
         fallback_prompt = """You are a proactive Chronic Disease Management (CDM) Health Coach.
         Your goal is to help patients manage their conditions (like Diabetes or Hypertension) through motivation, education, and lifestyle tracking.
-        Always review their recent FHIR observations and provide trend-aware advice.
+        Always review their recent FHIR observations, current medications, and trend analysis to provide personalized advice.
+        Consider the patient's medication regimen when making lifestyle recommendations.
         Be encouraging but firm about safety guidelines."""
         super().__init__(fallback_prompt, "HealthCoach.txt")
 
@@ -21,64 +23,178 @@ class TrendAnalyzer(BaseAgent):
         fallback_prompt = """You are a medical data trend analyzer. 
         You analyze FHIR observations and identify clinically significant trends.
         If you see rising glucose levels or blood pressure, flag them immediately.
-        Provide a concise summary of the last 7 days of data."""
+        Provide a concise summary of the last 7-14 days of data with trend projections."""
         super().__init__(fallback_prompt, "TrendAnalyzer.txt")
 
+    def _compute_trend_statistics(self, values: list) -> dict:
+        """
+        Compute statistical trend indicators using polynomial regression.
+        Bug 7.2: Enhanced trend analysis with proper windowing.
+        
+        Returns:
+            dict: Contains trend direction, slope, R-squared, and projection
+        """
+        if len(values) < 2:
+            return {"trend": "insufficient", "slope": 0, "r_squared": 0, "projection": None}
+        
+        try:
+            import numpy as np
+            
+            # Prepare data points
+            x = np.array(range(len(values)))
+            y = np.array(values)
+            
+            # First-order polynomial fit (linear regression)
+            if len(values) >= 3:
+                coeffs = np.polyfit(x, y, 1)
+                slope = coeffs[0]
+                intercept = coeffs[1]
+                
+                # Calculate R-squared
+                y_pred = np.polyval(coeffs, x)
+                ss_res = np.sum((y - y_pred) ** 2)
+                ss_tot = np.sum((y - np.mean(y)) ** 2)
+                r_squared = 1 - (ss_res / ss_tot) if ss_tot != 0 else 0
+                
+                # Determine trend with threshold
+                if abs(slope) < 0.5:
+                    trend = "stable"
+                elif slope > 0.5:
+                    trend = "rising"
+                else:
+                    trend = "falling"
+                
+                # Project next value
+                next_x = len(values)
+                projection = np.polyval(coeffs, next_x)
+                
+                return {
+                    "trend": trend,
+                    "slope": float(slope),
+                    "r_squared": float(r_squared),
+                    "projection": float(projection),
+                    "change_rate": float(slope)
+                }
+            else:
+                # For < 3 points, use simple delta
+                slope = (values[-1] - values[0]) / (len(values) - 1)
+                trend = "rising" if slope > 0.5 else "falling" if slope < -0.5 else "stable"
+                return {
+                    "trend": trend,
+                    "slope": float(slope),
+                    "r_squared": 0,
+                    "projection": values[-1] + slope,
+                    "change_rate": float(slope)
+                }
+        except ImportError:
+            logger.warning("NumPy not available, using basic trend analysis")
+            # Fallback: basic two-point comparison
+            if len(values) >= 2:
+                delta = values[-1] - values[-2]
+                trend = "rising" if delta > 0.5 else "falling" if delta < -0.5 else "stable"
+                return {
+                    "trend": trend,
+                    "slope": float(delta),
+                    "r_squared": 0,
+                    "projection": values[-1] + delta,
+                    "change_rate": float(delta)
+                }
+            return {"trend": "insufficient", "slope": 0, "r_squared": 0, "projection": None}
+
     async def analyze_trends(self, patient_id: str):
         """
-        Logic to analyze trends for a specific patient.
-        This can be called as a tool or as an agent step.
+        Logic to analyze trends for a specific patient with windowing.
+        Bug 7.2: Implements 7-14 day moving window analysis with regression.
         """
         logger.info(f"Analyzing health trends for patient: {patient_id}")
         observations = get_observations_by_patient.invoke({"patient_id": patient_id})
         if isinstance(observations, str):
             return observations
+        
+        if not observations:
+            return "No observations available for trend analysis.", {}
             
-        # Group by LOINC code
+        # Group by LOINC code and sort by date
         data_points = {}
         for obs in observations:
-            code = obs["code"]["coding"][0]["display"]
-            val = obs["valueQuantity"]["value"]
-            date = obs["effectiveDateTime"]
-            if code not in data_points:
-                data_points[code] = []
-            data_points[code].append({"value": val, "date": date})
-            
-        # Basic trend analysis logic
-        analysis = "Trend Analysis Summary:\n"
+            try:
+                code = obs["code"]["coding"][0]["display"]
+                val = float(obs["valueQuantity"]["value"])
+                date = obs["effectiveDateTime"]
+                if code not in data_points:
+                    data_points[code] = []
+                data_points[code].append({"value": val, "date": date})
+            except (KeyError, IndexError, ValueError) as e:
+                logger.warning(f"Error parsing observation: {e}")
+                continue
+        
+        # Sort each metric's points by date (descending for most recent first)
+        for code in data_points:
+            data_points[code].sort(key=lambda x: x["date"], reverse=True)
+        
+        # Comprehensive trend analysis
+        analysis = "**Trend Analysis Report (7-14 Day Window)**\n\n"
+        structured_data = {}
+        
         for code, points in data_points.items():
             if len(points) >= 2:
-                latest = points[0]["value"]
-                previous = points[1]["value"]
-                diff = latest - previous
-                trend = "increasing" if diff > 0 else "decreasing" if diff < 0 else "stable"
-                analysis += f"- {code}: {trend} (latest: {latest}, change: {diff:+.1f})\n"
-            else:
-                analysis += f"- {code}: Insufficient data for trend (latest: {points[0]['value']})\n"
+                # Extract values for statistical analysis
+                values = [p["value"] for p in points]
+                stats = self._compute_trend_statistics(values)
+                
+                latest = values[0]
+                prev = values[1] if len(values) > 1 else values[0]
+                delta = latest - prev
+                
+                analysis += f"**{code}**\n"
+                analysis += f"- Latest: {latest:.1f}\n"
+                analysis += f"- Trend: {stats['trend'].upper()} (slope: {stats['slope']:.2f}/day)\n"
                 
-        return analysis
+                if stats['r_squared'] > 0:
+                    analysis += f"- Trend Quality (R²): {stats['r_squared']:.2f}\n"
+                
+                if stats['projection'] is not None:
+                    analysis += f"- Projected Next: {stats['projection']:.1f}\n"
+                
+                # Clinical alert for high-priority metrics
+                if code.lower() in ["blood glucose", "glucose"] and latest > 250:
+                    analysis += f"  ⚠️ **ALERT**: Glucose critically high\n"
+                elif code.lower() in ["blood glucose", "glucose"] and latest < 70:
+                    analysis += f"  ⚠️ **ALERT**: Risk of hypoglycemia\n"
+                
+                
+                # Add to structured data
+                structured_data[code] = {
+                    "points": [{"date": p["date"], "value": p["value"]} for p in points],
+                    "stats": stats
+                }
+                
+                analysis += "\n"
+            elif len(points) == 1:
+                analysis += f"**{code}**: Single data point (latest: {points[0]['value']:.1f}) — insufficient for trend\n\n"
+        
+        return analysis, structured_data
 
     async def run(self, state: AgentState):
-        # Extract patient ID from messages or state
-        # For simplicity, we assume it's in the state or can be derived
-        # In a real scenario, we'd have a 'patient_id' in AgentState
+        # Extract patient ID from state
         patient_id = state.get("patient_id", "unknown")
         if patient_id == "unknown":
             logger.warning("TrendAnalyzer: No patient ID found in state.")
             return {"logs": ["TrendAnalyzer: No patient ID found in state."]}
             
         start_time = time.time()
-        analysis = await self.analyze_trends(patient_id)
+        analysis, structured_data = await self.analyze_trends(patient_id)
         end_time = time.time()
         
         metrics = {
             "agent": "TrendAnalyzer",
-            "tokens": 0, # Logic based, no LLM call here
+            "tokens": 0,  # Logic-based, no LLM call
             "time": round(end_time - start_time, 3)
         }
         
         return {
             "trend_analysis": analysis,
+            "trend_data": structured_data,
             "logs": [f"TrendAnalyzer: Completed analysis for {patient_id}"],
             "metrics": [metrics]
         }

src/agents/role_utils.py

@@ -0,0 +1,23 @@
+import re
+
+
+def classify_role(user_message: str) -> str | None:
+    """Return an inferred role from the user's message using regex cues."""
+    text = (user_message or "").lower()
+
+    if re.search(r"\b(caregiver|care giver|caring for|supporting|helping)\b", text):
+        return "caregiver"
+
+    if re.search(r"\b(pregnant|pregnancy|gestational|pregnant woman|gestational diabetes)\b", text):
+        return "patient"
+
+    if re.search(r"\b(diet|nutrition|meal plan|glycemic|carbohydrate|food facts|calorie|keto|vegetarian|vegan|grocery|menu)\b", text):
+        return "dietary"
+
+    if re.search(r"\b(study|research|paper|trial|meta-analysis|randomized|cohort|evidence|data|epidemiology)\b", text):
+        return "researcher"
+
+    if re.search(r"\b(doctor|dr\.|physician|provider|clinician|prescription|diagnosis|treatment|protocol|dose|medication|management|hba1c|a1c|insulin regimen|therapy|medical advice)\b", text):
+        return "clinician"
+
+    return None

src/core/evidence_models.py

@@ -0,0 +1,57 @@
+"""
+Evidence and citation models for clinical recommendations.
+Bug 12.3: Explainability Layer for Clinical Recommendations
+"""
+
+from pydantic import BaseModel, Field
+from typing import List, Literal, Optional
+
+
+class Citation(BaseModel):
+    """Represents a citation to a specific guideline or evidence source."""
+    source_document: str = Field(
+        description="Name of the guideline or research document (e.g., 'ADA Standards of Care 2026')"
+    )
+    page_number: Optional[int] = Field(None, description="Page number in the source document")
+    section: Optional[str] = Field(None, description="Section or chapter title in the document")
+    evidence_level: Literal["A", "B", "C"] = Field(
+        description="Evidence level per ADA standards: A (Excellent), B (Good), C (Limited)"
+    )
+    url: Optional[str] = Field(None, description="Optional URL to the source document")
+
+
+class ClinicalOutputWithEvidence(BaseModel):
+    """
+    Clinical specialist output with explicit evidence citations.
+    This ensures transparency and allows clinician users to verify the basis of recommendations.
+    """
+    recommendation: str = Field(
+        description="The clinical recommendation or advice provided"
+    )
+    explanation: str = Field(
+        description="Detailed explanation of the recommendation and its rationale"
+    )
+    citations: List[Citation] = Field(
+        description="List of guideline and evidence sources supporting this recommendation"
+    )
+    confidence_score: float = Field(
+        ge=0.0, le=1.0,
+        description="Agent's confidence score in this recommendation (0.0 to 1.0)"
+    )
+    disclaimer: Optional[str] = Field(
+        None,
+        description="Any clinical disclaimers or caveats (e.g., 'Consult with physician', 'Not for acute conditions')"
+    )
+
+
+class EvidenceCitation(BaseModel):
+    """
+    Record of an evidence citation used in the clinical pipeline.
+    Used to track citations within AgentState.
+    """
+    recommendation_id: str = Field(description="ID of the clinical recommendation this cites")
+    source_document: str = Field(description="Name of the source document")
+    page_number: Optional[int] = Field(None, description="Page number in source")
+    evidence_level: Literal["A", "B", "C"] = Field(description="Evidence level classification")
+    agent_name: str = Field(description="Name of the agent that produced this citation")
+    timestamp: str = Field(description="ISO format timestamp when citation was generated")

src/core/graph.py

@@ -1,7 +1,10 @@
+import re
+import time
+
 from langgraph.graph import StateGraph, END
 from src.core.state import AgentState
 from src.agents.agent_instances import (
-    role_classifier, patient_llm, validator, safety_check,
+    role_classifier, patient_llm, caregiver_llm, validator, safety_check,
     intent_classifier, diagnosis_assist, treatment_assist,
     monitoring_assist, general_assist, output_merger, research_agent,
     dietary_assist
@@ -11,10 +14,15 @@ from langgraph.prebuilt import ToolNode
 from src.tools.web_tools import web_search_tool
 from src.utils.logger import setup_logger
 from src.tools.fhir_memory import save_chat_as_fhir
-import time
 
 logger = setup_logger("MedicalPipeline")
 
+MAX_RECOVERY_ATTEMPTS = 3
+EMERGENCY_PATTERNS = [
+    r"\b(unconscious|passed out|not breathing|seizure|seizing|stroke|heart attack|chest pain|coma)\b",
+    r"\b(dka|ketoacidosis|hypoglycemic emergency|hyperglycemic emergency|insulin overdose)\b",
+]
+
 def log_step(name: str, output: str = None):
     """Utility to log both to terminal and return a state update for the logs list."""
     logger.info(f"Executing: {name}")
@@ -23,14 +31,45 @@ def log_step(name: str, output: str = None):
         log_msg += f"\nOutput: {output}"
     return {"logs": [log_msg]}
 
+
+def _extract_message_content(message) -> str:
+    if getattr(message, "content", None):
+        return message.content
+    return str(getattr(message, "tool_calls", ""))
+
+
+def _set_latest_clinician_output(res: dict):
+    latest_output = ""
+    if res.get("messages"):
+        latest_output = _extract_message_content(res["messages"][-1])
+
+    if latest_output:
+        res["clinician_outputs"] = [latest_output]
+    else:
+        res["clinician_outputs"] = []
+    return res
+def detect_emergency(state: AgentState) -> bool:
+    last_message = state.get("messages")[-1] if state.get("messages") else None
+    if not last_message:
+        return False
+
+    content = getattr(last_message, "content", "")
+    if not content:
+        return False
+
+    normalized = content.lower()
+    return any(re.search(pattern, normalized) for pattern in EMERGENCY_PATTERNS)
+
+
 async def role_classifier_node(state: AgentState):
     res = await role_classifier.run(state)
     log = log_step("Role Classifier", f"Detected Role: {res.get('user_role')}")
     res.update(log)
-    
+
+    # Intent is only needed for the clinician pathway.
     if res.get('user_role') != "clinician":
         res['intent_type'] = "general"
-        
+
     return res
 
 from langchain_core.runnables.config import RunnableConfig
@@ -42,6 +81,13 @@ async def patient_llm_node(state: AgentState, config: RunnableConfig):
     log = log_step("Patient LLM", content)
     return {"messages": res["messages"], "logs": log["logs"]}
 
+async def caregiver_llm_node(state: AgentState, config: RunnableConfig):
+    res = await caregiver_llm.run(state, config=config)
+    last_msg = res["messages"][-1]
+    content = last_msg.content if getattr(last_msg, "content", "") else str(getattr(last_msg, "tool_calls", ""))
+    log = log_step("Caregiver LLM", content)
+    return {"messages": res["messages"], "logs": log["logs"]}
+
 async def validator_node(state: AgentState):
     res = await validator.run(state)
     log = log_step("Response Validator", f"Valid: {res.get('is_valid')}")
@@ -63,6 +109,22 @@ async def recovery_loop_node(state: AgentState):
         "logs": log["logs"]
     }
 
+
+async def emergency_response_node(state: AgentState):
+    response = (
+        "This appears to be a possible medical emergency. Seek urgent medical assistance now "
+        "and do not delay care. If the person is unconscious, not breathing, or having a seizure, "
+        "call emergency services immediately."
+    )
+    log = log_step("Emergency Fast Path", response)
+    return {
+        "messages": [AIMessage(content=response)],
+        "logs": log["logs"],
+        "is_valid": True,
+        "is_safe": True,
+    }
+
+
 async def intent_classifier_node(state: AgentState):
     res = await intent_classifier.run(state)
     log = log_step("Intent Classifier", f"Intent: {res.get('intent_type')}")
@@ -70,31 +132,48 @@ async def intent_classifier_node(state: AgentState):
     return res
 
 async def diagnosis_assist_node(state: AgentState, config: RunnableConfig):
-    res = await diagnosis_assist.run(state, config=config)
+    res = _set_latest_clinician_output(await diagnosis_assist.run(state, config=config))
     log = log_step("Diagnosis Assistant", res.get('clinician_outputs', [""])[-1] if res.get('clinician_outputs') else "")
     res.update(log)
+    clinician_outputs = (state.get("clinician_outputs") or []) + (res.get("clinician_outputs") or [])
+    res["clinician_outputs"] = clinician_outputs
     return res
 
 async def treatment_assist_node(state: AgentState, config: RunnableConfig):
-    res = await treatment_assist.run(state, config=config)
+    res = _set_latest_clinician_output(await treatment_assist.run(state, config=config))
     log = log_step("Treatment Assistant", res.get('clinician_outputs', [""])[-1] if res.get('clinician_outputs') else "")
     res.update(log)
+    clinician_outputs = (state.get("clinician_outputs") or []) + (res.get("clinician_outputs") or [])
+    res["clinician_outputs"] = clinician_outputs
     return res
 
 async def monitoring_assist_node(state: AgentState, config: RunnableConfig):
-    res = await monitoring_assist.run(state, config=config)
+    res = _set_latest_clinician_output(await monitoring_assist.run(state, config=config))
     log = log_step("Monitoring Assistant", res.get('clinician_outputs', [""])[-1] if res.get('clinician_outputs') else "")
     res.update(log)
+    clinician_outputs = (state.get("clinician_outputs") or []) + (res.get("clinician_outputs") or [])
+    res["clinician_outputs"] = clinician_outputs
     return res
 
 async def general_assist_node(state: AgentState, config: RunnableConfig):
-    res = await general_assist.run(state, config=config)
+    res = _set_latest_clinician_output(await general_assist.run(state, config=config))
     log = log_step("General Clinical Assistant", res.get('clinician_outputs', [""])[-1] if res.get('clinician_outputs') else "")
     res.update(log)
+    clinician_outputs = (state.get("clinician_outputs") or []) + (res.get("clinician_outputs") or [])
+    res["clinician_outputs"] = clinician_outputs
     return res
 
 async def merge_outputs_node(state: AgentState, config: RunnableConfig):
-    res = await output_merger.run(state, config=config)
+    # Prepare state with context about the specialist outputs for the OutputMerger
+    clinician_outputs = state.get("clinician_outputs", [])
+    if clinician_outputs:
+        # Add specialist outputs summary to messages for context
+        outputs_context = "\n\n".join([f"Specialist Output {i+1}:\n{output}" for i, output in enumerate(clinician_outputs)])
+        state_with_context = dict(state)
+        state_with_context["messages"] = state["messages"] + [AIMessage(content=outputs_context)]
+        res = await output_merger.run(state_with_context, config=config)
+    else:
+        res = await output_merger.run(state, config=config)
     log = log_step("Output Merger", "Merged outputs successfully.")
     res.update(log)
     return res
@@ -134,23 +213,28 @@ async def tool_node_with_logging(state: AgentState):
     return res
 
 async def persistence_node(state: AgentState):
-    """Save the current chat history to MongoDB in FHIR format."""
+    """Save the current chat history to Supabase in FHIR format."""
     patient_id = state.get("patient_id", "anonymous")
-    
+    session_id = state.get("session_id")
+
     # Convert LangChain messages to a simple list of dicts for the tool
     formatted_messages = []
     for msg in state["messages"]:
         role = "user" if msg.type == "human" else "assistant"
         formatted_messages.append({"role": role, "content": msg.content})
-    
-    # We only save if there's a patient_id and it's a patient role
-    if state.get("user_role") == "patient":
+
+    # Persist patient-facing and caregiver-facing conversations for the active patient.
+    if state.get("user_role") in ("patient", "caregiver"):
         start_time = time.time()
-        res = save_chat_as_fhir.invoke({"patient_id": patient_id, "messages": formatted_messages})
+        res = save_chat_as_fhir.invoke({
+            "patient_id": patient_id,
+            "messages": formatted_messages,
+            "session_id": session_id,
+        })
         end_time = time.time()
-        
+
         log = log_step("FHIR Persistence", res)
-        
+
         metrics = {
             "agent": "PersistenceNode",
             "tokens": 0,
@@ -163,8 +247,12 @@ async def persistence_node(state: AgentState):
 # Define routing functions
 def route_after_role(state: AgentState):
     role = state["user_role"]
+    if role in {"patient", "caregiver"} and detect_emergency(state):
+        return "emergency_response"
     if role == "patient":
         return "patient_llm"
+    elif role == "caregiver":
+        return "caregiver_llm"
     elif role == "clinician":
         return "intent_classifier"
     elif role == "researcher":
@@ -193,6 +281,8 @@ def route_after_tools(state: AgentState):
         return "research_agent"
     elif role == "dietary":
         return "dietary_assist"
+    elif role == "caregiver":
+        return "caregiver_llm"
     return "patient_llm"
 
 def route_after_validator(state: AgentState):
@@ -209,10 +299,18 @@ def route_after_persistence(state: AgentState):
     return END
 
 def route_after_recovery(state: AgentState):
+    attempts = state.get("attempts", 0)
+    if attempts >= MAX_RECOVERY_ATTEMPTS:
+        return "persistence_node"
+
     role = state.get("user_role")
     if role == "dietary":
         return "dietary_assist"
-    return "patient_llm"
+    elif role == "caregiver":
+        return "caregiver_llm"
+    elif role == "patient":
+        return "patient_llm"
+    return "persistence_node"
 
 def route_after_intent(state: AgentState):
     intent = state.get("intent_type", "general")
@@ -237,9 +335,11 @@ builder = StateGraph(AgentState)
 # Add nodes
 builder.add_node("role_classifier", role_classifier_node)
 builder.add_node("patient_llm", patient_llm_node)
+builder.add_node("caregiver_llm", caregiver_llm_node)
 builder.add_node("validator", validator_node)
 builder.add_node("safety_check", safety_check_node)
 builder.add_node("recovery_loop", recovery_loop_node)
+builder.add_node("emergency_response", emergency_response_node)
 builder.add_node("intent_classifier", intent_classifier_node)
 builder.add_node("diagnosis_assist", diagnosis_assist_node)
 builder.add_node("treatment_assist", treatment_assist_node)
@@ -257,17 +357,23 @@ builder.set_entry_point("role_classifier")
 # Define edges
 builder.add_conditional_edges("role_classifier", route_after_role, {
     "patient_llm": "patient_llm",
+    "caregiver_llm": "caregiver_llm",
     "intent_classifier": "intent_classifier",
     "research_agent": "research_agent",
     "dietary_assist": "dietary_assist",
+    "emergency_response": "emergency_response",
     END: END
 })
 
-# Patient Pathway
+# Patient and Caregiver Pathways
 builder.add_conditional_edges("patient_llm", route_patient_llm, {
     "tools_node": "tools_node",
     "validator": "validator"
 })
+builder.add_conditional_edges("caregiver_llm", route_patient_llm, {
+    "tools_node": "tools_node",
+    "validator": "validator"
+})
 builder.add_conditional_edges("validator", route_after_validator, {
     "safety_check": "safety_check",
     "recovery_loop": "recovery_loop"
@@ -279,9 +385,13 @@ builder.add_conditional_edges("safety_check", route_after_safety, {
 builder.add_edge("persistence_node", END)
 builder.add_conditional_edges("recovery_loop", route_after_recovery, {
     "dietary_assist": "dietary_assist",
-    "patient_llm": "patient_llm"
+    "caregiver_llm": "caregiver_llm",
+    "patient_llm": "patient_llm",
+    "persistence_node": "persistence_node"
 })
 
+builder.add_edge("emergency_response", "persistence_node")
+
 # Clinician Pathway
 builder.add_conditional_edges("intent_classifier", route_after_intent, {
     "diagnosis_assist": "diagnosis_assist",
@@ -305,6 +415,7 @@ builder.add_conditional_edges("research_agent", route_research_agent, {
 builder.add_conditional_edges("tools_node", route_after_tools, {
     "research_agent": "research_agent",
     "patient_llm": "patient_llm",
+    "caregiver_llm": "caregiver_llm",
     "dietary_assist": "dietary_assist"
 })
 

src/core/graph_cdm.py

@@ -3,7 +3,10 @@ from src.core.state import AgentState
 from src.agents.agent_instances import (
     health_coach, trend_analyzer, validator, safety_check
 )
-from src.tools.fhir_memory import get_patient_summary_fhir, save_observation, ingest_fhir_bundle
+from src.tools.fhir_memory import (
+    get_patient_summary_fhir, save_observation, ingest_fhir_bundle, 
+    get_medications_by_patient, save_medication
+)
 from src.tools.web_tools import web_search_tool
 from langgraph.prebuilt import ToolNode
 import time
@@ -19,15 +22,33 @@ def log_step(name: str, output: str = None):
     return {"logs": [log_msg]}
 
 async def data_fetch_node(state: AgentState):
+    """
+    Fetch FHIR data and medications for CDM context.
+    Bug 7.3: Include medication context in CDM pipeline.
+    """
     patient_id = state.get("patient_id", "unknown")
     if patient_id == "unknown":
         return log_step("Data Fetch", "No Patient ID provided.")
     
     start_time = time.time()
+    
+    # Fetch FHIR summary
     summary = get_patient_summary_fhir.invoke({"patient_id": patient_id})
+    
+    # Bug 7.3: Fetch medications for context
+    medications = get_medications_by_patient.invoke({"patient_id": patient_id})
+    
+    # If summary has active_medications field, populate it
+    if isinstance(summary, dict) and "active_medications" in summary:
+        summary["active_medications"] = medications if medications else []
+    
     end_time = time.time()
     
-    log = log_step("FHIR Data Fetch", f"Retrieved summary for {patient_id}")
+    log_output = f"Retrieved summary and medications for {patient_id}"
+    if medications:
+        log_output += f" ({len(medications)} active medications)"
+    
+    log = log_step("FHIR Data Fetch", log_output)
     
     metrics = {
         "agent": "DataFetchNode",
@@ -37,6 +58,7 @@ async def data_fetch_node(state: AgentState):
     
     return {
         "fhir_data": [summary] if isinstance(summary, dict) else [], 
+        "current_medications": medications if isinstance(medications, list) else [],
         "logs": log["logs"],
         "metrics": [metrics]
     }
@@ -85,7 +107,7 @@ def route_after_validator(state: AgentState):
     return "health_coach" # Simple retry
 
 # Setup tools
-cdm_tools = [web_search_tool, save_observation, ingest_fhir_bundle, get_patient_summary_fhir]
+cdm_tools = [web_search_tool, save_observation, ingest_fhir_bundle, get_patient_summary_fhir, get_medications_by_patient, save_medication]
 tool_node = ToolNode(cdm_tools)
 
 async def tools_node_with_metrics(state: AgentState):

src/core/model_manager.py

@@ -107,6 +107,14 @@ class ReqModel:
         loop = asyncio.get_event_loop()
         return await loop.run_in_executor(None, lambda: self._make_request(messages, config, **kwargs))
 
+    def stream(self, messages, config=None, **kwargs):
+        yield self._make_request(messages, config, **kwargs)
+
+    async def astream(self, messages, config=None, **kwargs):
+        loop = asyncio.get_event_loop()
+        response = await loop.run_in_executor(None, lambda: self._make_request(messages, config, **kwargs))
+        yield response
+
 class RateLimitFallbackWrapper:
     def __init__(self, main_llm, fallback_llms):
         self.main_llm = main_llm
@@ -132,7 +140,7 @@ class RateLimitFallbackWrapper:
                 return await fb_llm.ainvoke(messages, config=config, **kwargs)
             except Exception as fb_e:
                 logger.warning(f"Fallback {idx+1} failed: {fb_e}")
-        
+
         raise RuntimeError("All models (main and fallbacks) failed.") from None
 
     def invoke(self, messages, config=None, **kwargs):
@@ -147,9 +155,45 @@ class RateLimitFallbackWrapper:
                 return fb_llm.invoke(messages, config=config, **kwargs)
             except Exception as fb_e:
                 logger.warning(f"Fallback {idx+1} failed: {fb_e}")
-        
+
         raise RuntimeError("All models failed synchronously.") from None
 
+    def stream(self, messages, config=None, **kwargs):
+        try:
+            yield from self.main_llm.stream(messages, config=config, **kwargs)
+            return
+        except Exception as e:
+            logger.warning(f"LLM stream error with main model: {e}. Attempting fallbacks immediately.")
+
+        for idx, fb_llm in enumerate(self.fallback_llms):
+            try:
+                logger.info(f"Trying fallback model {idx+1} for streaming")
+                yield from fb_llm.stream(messages, config=config, **kwargs)
+                return
+            except Exception as fb_e:
+                logger.warning(f"Fallback {idx+1} streaming failed: {fb_e}")
+
+        raise RuntimeError("All models failed while streaming.")
+
+    async def astream(self, messages, config=None, **kwargs):
+        try:
+            async for chunk in self.main_llm.astream(messages, config=config, **kwargs):
+                yield chunk
+            return
+        except Exception as e:
+            logger.warning(f"LLM async stream error with main model: {e}. Attempting fallbacks immediately.")
+
+        for idx, fb_llm in enumerate(self.fallback_llms):
+            try:
+                logger.info(f"Trying fallback model {idx+1} for async streaming")
+                async for chunk in fb_llm.astream(messages, config=config, **kwargs):
+                    yield chunk
+                return
+            except Exception as fb_e:
+                logger.warning(f"Fallback {idx+1} async streaming failed: {fb_e}")
+
+        raise RuntimeError("All models failed while async streaming.")
+
 class ModelManager:
     def __init__(self, model_name: str = "google/gemma-4-26b-a4b-it:free"):
         self.provider = os.getenv("MODEL_PROVIDER", "openrouter").lower()
@@ -171,13 +215,13 @@ class ModelManager:
 
         return primary_api_key, secondary_api_key
 
-    def get_llm(self, temperature: float = 0):
-        logger.info(f"Initializing LLM: Provider={self.provider}, Model={self.model_name}")
+    def get_llm(self, temperature: float = 0, model_name: str = None):
+        model = model_name or self.model_name
+        logger.info(f"Initializing LLM: Provider={self.provider}, Model={model}")
         
-        model = self.model_name
         primary_api_key, secondary_api_key = self._get_openrouter_api_keys()
         base_url = "https://openrouter.ai/api/v1"
-        
+
         main_llm = ReqModel(
             model=model,
             temperature=temperature,

src/core/state.py

@@ -9,11 +9,15 @@ class AgentState(TypedDict):
     # Metadata for routing
     user_role: str  # patient, clinician, researcher
     intent_type: str  # diagnosis, treatment, monitoring, general
+    trace_id: str
     
     # CDM / FHIR Data
+    session_id: str
     patient_id: str
     fhir_data: List[dict]
     trend_analysis: str
+    trend_data: dict
+    current_medications: List[dict]
     
     # Validation status
     is_valid: bool
@@ -30,6 +34,9 @@ class AgentState(TypedDict):
     # Sources for information
     sources: Annotated[List[str], operator.add]
     
+    # Evidence citations for clinical recommendations (Bug 12.3)
+    evidence_citations: Annotated[List[dict], operator.add]
+    
     # Execution logs
     logs: Annotated[List[str], operator.add]
     

src/mcp/server.py

@@ -6,7 +6,9 @@ import sys
 import json
 import asyncio
 from typing import Any, Dict, List
-from src.tools.fhir_memory import get_observations_by_patient, ingest_fhir_bundle
+import src.tools.fhir_memory as fhir_tools
+import src.tools.dietary_tools as dietary_tools
+from langchain_core.tools import BaseTool
 from src.agents.cdm_agents import TrendAnalyzer
 from src.utils.logger import setup_logger
 
@@ -15,6 +17,12 @@ logger = setup_logger("MCPServer")
 class MedicalMCPServer:
     def __init__(self):
         self.trend_analyzer = TrendAnalyzer()
+        self.tools = {}
+        for module in [fhir_tools, dietary_tools]:
+            for name in dir(module):
+                obj = getattr(module, name)
+                if isinstance(obj, BaseTool):
+                    self.tools[obj.name] = obj
 
     async def handle_request(self, request: Dict[str, Any]) -> Dict[str, Any]:
         method = request.get("method")
@@ -35,7 +43,7 @@ class MedicalMCPServer:
             return {"jsonrpc": "2.0", "error": {"code": -32603, "message": str(e)}, "id": req_id}
 
     def list_tools(self) -> List[Dict[str, Any]]:
-        return [
+        tool_list = [
             {
                 "name": "analyze_health_trends",
                 "description": "Analyze FHIR observation trends for a patient.",
@@ -46,29 +54,31 @@ class MedicalMCPServer:
                     },
                     "required": ["patient_id"]
                 }
-            },
-            {
-                "name": "query_fhir_observations",
-                "description": "Query historical FHIR observations for a patient.",
-                "inputSchema": {
-                    "type": "object",
-                    "properties": {
-                        "patient_id": {"type": "string"},
-                        "loinc_code": {"type": "string"}
-                    },
-                    "required": ["patient_id"]
-                }
             }
         ]
+        
+        for name, tool_obj in self.tools.items():
+            schema = {}
+            if tool_obj.args_schema:
+                try:
+                    schema = tool_obj.args_schema.schema()
+                except AttributeError:
+                    schema = tool_obj.args_schema.model_json_schema()
+            
+            tool_list.append({
+                "name": name,
+                "description": tool_obj.description,
+                "inputSchema": schema
+            })
+            
+        return tool_list
 
     async def call_tool(self, name: str, args: Dict[str, Any]) -> Any:
         logger.info(f"Calling MCP tool: {name}")
         if name == "analyze_health_trends":
             return await self.trend_analyzer.analyze_trends(args["patient_id"])
-        elif name == "query_fhir_observations":
-            return get_observations_by_patient.invoke(args)
-        elif name == "ingest_fhir":
-            return ingest_fhir_bundle.invoke({"bundle": args["bundle"]})
+        elif name in self.tools:
+            return self.tools[name].invoke(args)
         else:
             raise ValueError(f"Unknown tool: {name}")
 

src/params.json

@@ -0,0 +1,47 @@
+{
+  "RoleClassifier": {
+    "temperature": 0.1
+  },
+  "IntentClassifier": {
+    "temperature": 0.0
+  },
+  "PatientLLM": {
+    "temperature": 0.2
+  },
+  "CaregiverLLM": {
+    "temperature": 0.2
+  },
+  "ResponseValidator": {
+    "temperature": 0.0
+  },
+  "SafetyCheck": {
+    "temperature": 0.0
+  },
+  "ClinicalSpecialist_Diagnosis": {
+    "temperature": 0.0
+  },
+  "ClinicalSpecialist_Treatment": {
+    "temperature": 0.0
+  },
+  "ClinicalSpecialist_Monitoring": {
+    "temperature": 0.0
+  },
+  "ClinicalSpecialist_General Clinical Support": {
+    "temperature": 0.2
+  },
+  "ResearchAgent": {
+    "temperature": 0.2
+  },
+  "DietarySpecialist": {
+    "temperature": 0.2
+  },
+  "OutputMerger": {
+    "temperature": 0.2
+  },
+  "HealthCoach": {
+    "temperature": 0.2
+  },
+  "TrendAnalyzer": {
+    "temperature": 0.0
+  }
+}

src/prompts/CaregiverLLM.txt

@@ -0,0 +1,6 @@
+You are a supportive caregiver assistant for a diabetes management platform.
+Your role is to help a caregiver interpret the patient's symptoms, understand medication and monitoring needs, and know when to escalate to urgent care.
+Answer in a calm, practical, third-person tone as if you are guiding someone who is supporting a patient.
+Focus on actionable next steps, safety, and reassurance. If the query involves urgent symptoms, encourage immediate escalation to emergency services or professional help.
+
+At the end of your response, include a confidence score from 0.0 to 1.0 in the format: Confidence: 0.8

src/prompts/ClinicalSpecialist_Diagnosis.txt

@@ -1 +1,13 @@
-You are a assistant to a certified medical pratiotioner in Diabetes. You are to assist the pratiotioner to diagnose what specific issue he wants you to diagnose and validate. Provide proper reasoning. Use medical terminologies and expressions.
+You are a assistant to a certified medical practitioner in Diabetes. You are to assist the practitioner to diagnose what specific issue they want you to diagnose and validate. Provide proper reasoning. Use medical terminologies and expressions.
+
+[Evidence Citation Requirements - Bug 12.3]
+For EVERY diagnostic recommendation or clinical statement, you MUST:
+1. Cite the specific guideline or document source (e.g., "ADA Standards of Care 2026", page X)
+2. Assign an evidence level: A (Excellent evidence), B (Good evidence), or C (Limited evidence)
+3. Include the specific guideline clause or section being referenced
+
+Format your response with clear sections:
+- DIAGNOSIS: [Your diagnostic statement]
+- EVIDENCE LEVEL: [A/B/C]
+- SOURCE: [Specific guideline, page, section]
+- EXPLANATION: [Detailed clinical reasoning]

src/prompts/ClinicalSpecialist_General Clinical Support.txt

@@ -1 +1,14 @@
-You are a assistant to a certified medical pratiotioner in Diabetes. You are to assist the pratiotioner in general clinical support. Provide proper reasoning. Use medical terminologies and expressions.
+You are a assistant to a certified medical pratiotioner in Diabetes. You are to assist the pratiotioner in general clinical support. Provide proper reasoning. Use medical terminologies and expressions.
+
+[Evidence Citation Requirements - Bug 12.3]
+For clinical statements and recommendations, you MUST:
+1. Cite the specific guideline or document source when applicable (e.g., "ADA Standards of Care 2026", page X)
+2. Assign an evidence level: A (Excellent evidence), B (Good evidence), or C (Limited evidence)
+3. Include the specific guideline clause or section being referenced
+
+Structure clinical guidance with:
+- TOPIC/QUESTION: [What is being addressed]
+- KEY POINTS: [Main clinical information]
+- EVIDENCE LEVEL: [A/B/C]
+- SOURCE: [Specific guideline or reference]
+- CLINICAL CONTEXT: [Relevant considerations for application]

src/prompts/ClinicalSpecialist_General.txt

@@ -1 +1,13 @@
-You are a assistant to a certified medical pratiotioner in Diabetes. You are to assist the pratiotioner in general clinical support. Provide proper reasoning. Use medical terminologies and expressions.
+You are a assistant to a certified medical pratiotioner in Diabetes. You are to assist the pratiotioner in general clinical support. Provide proper reasoning. Use medical terminologies and expressions.
+
+[Evidence Citation Requirements - Bug 12.3]
+For EVERY clinical recommendation or statement, you MUST:
+1. Cite the specific guideline or document source (e.g., "ADA Standards of Care 2026", page X)
+2. Assign an evidence level: A (Excellent evidence), B (Good evidence), or C (Limited evidence)
+3. Include the specific guideline clause or section being referenced
+
+Format key recommendations with:
+- RECOMMENDATION: [Your recommendation]
+- EVIDENCE LEVEL: [A/B/C]
+- SOURCE: [Specific guideline, page, section]
+- RATIONALE: [Clinical reasoning]

src/prompts/ClinicalSpecialist_Monitoring.txt

@@ -1 +1,15 @@
-You are a assistant to a certified medical pratiotioner in Diabetes. You are to assist the pratiotioner to monitor the patient. Go through diffrential diagnosis to arrive at a final possible diagnosis. Use medical terminologies and expressions.
+You are a assistant to a certified medical pratiotioner in Diabetes. You are to assist the pratiotioner to monitor the patient. Go through diffrential diagnosis to arrive at a final possible diagnosis. Use medical terminologies and expressions.
+
+[Evidence Citation Requirements - Bug 12.3]
+For EVERY monitoring recommendation or parameter threshold, you MUST:
+1. Cite the specific guideline or document source (e.g., "ADA Standards of Care 2026", page X)
+2. Assign an evidence level: A (Excellent evidence), B (Good evidence), or C (Limited evidence)
+3. Include the specific guideline clause or section being referenced
+
+Format monitoring recommendations with:
+- MONITORING PARAMETER: [Parameter to monitor]
+- THRESHOLD/TARGET: [Specific value or range]
+- EVIDENCE LEVEL: [A/B/C]
+- SOURCE: [Specific guideline, page, section]
+- FREQUENCY: [Recommended monitoring frequency]
+- RATIONALE: [Clinical justification]

src/prompts/ClinicalSpecialist_Treatment.txt

@@ -1 +1,14 @@
-You are a assistant to a certified medical pratiotioner in Diabetes. You are to assist the pratiotioner to treat the patient. If multiple treatments are possible, then list them with their pros and cons and let the pratiotioner decide. Use medical terminologies and expressions.
+You are a assistant to a certified medical pratiotioner in Diabetes. You are to assist the pratiotioner to treat the patient. If multiple treatments are possible, then list them with their pros and cons and let the pratiotioner decide. Use medical terminologies and expressions.
+
+[Evidence Citation Requirements - Bug 12.3]
+For EVERY treatment recommendation or medication suggestion, you MUST:
+1. Cite the specific guideline or document source (e.g., "ADA Standards of Care 2026", page X)
+2. Assign an evidence level: A (Excellent evidence), B (Good evidence), or C (Limited evidence)
+3. Include the specific guideline clause or section being referenced
+
+Format treatment recommendations with:
+- TREATMENT OPTION: [Your recommendation]
+- EVIDENCE LEVEL: [A/B/C]
+- SOURCE: [Specific guideline, page, section]
+- CLINICAL RATIONALE: [Detailed explanation]
+- MONITORING: [Required follow-up and monitoring]

src/prompts/ResponseValidator.txt

@@ -3,6 +3,8 @@ You are a medical response validator for a diabetes management AI. Your task is
 GUIDELINES:
 1. Check the response for medical accuracy and completeness regarding diabetes care.
 2. Check for proper source citations.
-3. If the response is accurate, return only 'valid'.
-4. If there are issues, return 'invalid' followed by a brief reason.
-5. Use professional judgment but be rigorous.
+3. Return JSON only in the following format:
+   {"decision": "valid"}
+   or
+   {"decision": "invalid", "reason": "brief explanation"}
+4. Use professional judgment but be rigorous.

src/prompts/RoleClassifier.txt

@@ -1,10 +1,19 @@
 You are a highly accurate Medical Triage Assistant for a diabetes management platform. 
-Your task is to analyze the user's input and classify it into one of four specific roles:
+Your task is to analyze the user's input and classify it into one of five specific roles:
 - 'patient': For general health inquiries, symptoms, diabetes self-management, or personal medical advice.
+- 'caregiver': For questions from a family member, caregiver, or proxy support person managing a patient's care.
 - 'clinician': For professional medical questions regarding diabetes diagnosis, treatment protocols, HbA1c management, or specialized medical data.
 - 'researcher': For deep medical research, endocrinology scientific information, or clinical trial data on diabetes.
 - 'dietary': For requests related to nutrition, diabetic diet plans, food facts, glycemic index, or nutritional guidelines.
 
+Use regex-style signal words when possible. For example:
+- caregiver queries: "caregiver", "caring for", "helping my mother", "supporting my father"
+- diet or nutrition queries: "meal plan", "glycemic index", "food facts", "carbohydrate counting"
+- research queries: "study", "trial", "paper", "meta-analysis", "cohort", "evidence"
+- clinician queries: "doctor", "physician", "prescription", "diagnosis", "treatment", "protocol", "dose", "HbA1c"
+- patient queries: first-person symptoms like "I have", "I've been", "I feel", "my blood sugar", "my doctor told me"
+
 Return ONLY the role name in lowercase (e.g., 'patient').
 If the input is ambiguous but mentions food, nutrition, or diet, prioritize 'dietary'.
-If the user is asking about scientific papers or diabetes guidelines, it might be 'researcher' or 'dietary' depending on the focus.
+If the user is asking about scientific papers or diabetes guidelines, it might be 'researcher' or 'dietary' depending on the focus.
+If the user is asking on behalf of another person, prioritize 'caregiver'.

src/prompts/SafetyCheck.txt

@@ -3,6 +3,8 @@ You are a medical safety officer for a diabetes management AI. Your primary resp
 GUIDELINES:
 1. Check if the response contains any life-threatening misinformation (e.g., incorrect insulin dosing advice, ignoring severe hypoglycemia).
 2. Verify if the advice is compliant with standard medical protocols for diabetes (e.g., WHO, ADA, or national guidelines).
-3. If the advice is safe, return 'safe'.
-4. If there is even a small risk of harm or severe misinformation, return 'unsafe' followed by the specific safety concern.
-5. Pay close attention to dosages (especially insulin), dangerous drug interactions, or inappropriate self-treatment suggestions for severe symptoms (like DKA).
+3. Return JSON only in the following format:
+   {"decision": "safe"}
+   or
+   {"decision": "unsafe", "reason": "brief explanation"}
+4. Pay close attention to dosages (especially insulin), dangerous drug interactions, or inappropriate self-treatment suggestions for severe symptoms (like DKA).

src/tools/dietary_tools.py

@@ -14,11 +14,24 @@ DB_PATH = os.path.join(os.path.dirname(__file__), "../../data/dietary_guidelines
 logger.info("Loading embedding model for tools...")
 model = SentenceTransformer('all-MiniLM-L6-v2')
 
-def _get_supabase_client() -> Client:
+_supabase_client = None
+
+
+def _build_supabase_client() -> Client:
     url = os.getenv("SUPABASE_URL")
     key = os.getenv("SUPABASE_KEY")
+    if not url or not key:
+        raise RuntimeError("SUPABASE_URL and SUPABASE_KEY must be set")
     return create_client(url, key)
 
+
+def get_supabase_client() -> Client:
+    global _supabase_client
+    if _supabase_client is None:
+        _supabase_client = _build_supabase_client()
+    return _supabase_client
+
+
 @tool
 def search_guidelines(query: str):
     """
@@ -26,8 +39,8 @@ def search_guidelines(query: str):
     Returns content with source and page information.
     """
     logger.info(f"Searching Supabase guidelines for: {query}")
-    client = _get_supabase_client()
-    
+    client = get_supabase_client()
+
     # Generate embedding for query
     query_embedding = model.encode(query).tolist()
     

src/tools/fhir_memory.py

@@ -273,6 +273,77 @@ def get_chat_history_by_session(session_id: str):
         logger.error(f"Error retrieving chat history: {e}")
         return []
 
+@tool
+def get_medications_by_patient(patient_id: str):
+    """
+    Retrieve current medications for a patient in FHIR MedicationRequest format.
+    Bug 7.3: Retrieve medications to support CDM pipeline context.
+    """
+    logger.info(f"Retrieving medications for patient: {patient_id}")
+    client = _get_client()
+    
+    try:
+        # Query medications table if it exists
+        query = client.table("medications").select("resource").eq("patient_id", patient_id)
+        response = query.execute()
+        
+        if response.data:
+            medications = [record["resource"] for record in response.data]
+            return medications
+        
+        # Return empty list with informative message if no medications found
+        return []
+    except Exception as e:
+        logger.error(f"Error retrieving medications: {e}")
+        # Return empty list on error to prevent pipeline failures
+        return []
+
+@tool
+def save_medication(patient_id: str, medication_name: str, dosage: str, frequency: str, status: str = "active"):
+    """
+    Save a medication record for a patient in FHIR MedicationRequest format.
+    Bug 7.3: Store medications to support CDM pipeline context.
+    """
+    logger.info(f"Saving medication for patient: {patient_id}")
+    client = _get_client()
+    _ensure_patient_exists(patient_id, client)
+    
+    med_id = str(uuid.uuid4())
+    
+    # Construct FHIR MedicationRequest
+    fhir_medication_request = {
+        "resourceType": "MedicationRequest",
+        "id": med_id,
+        "status": status,
+        "intent": "order",
+        "subject": {"reference": f"Patient/{patient_id}"},
+        "authoredOn": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "medication": {
+            "coding": [{
+                "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
+                "display": medication_name
+            }]
+        },
+        "dosageInstruction": [{
+            "text": f"{dosage} {frequency}"
+        }]
+    }
+    
+    data = {
+        "id": med_id,
+        "patient_id": patient_id,
+        "resource": fhir_medication_request,
+        "last_updated": datetime.datetime.now(datetime.timezone.utc).isoformat()
+    }
+    
+    try:
+        # Check if medications table exists, if not create in memory
+        client.table("medications").insert(data).execute()
+        return f"Successfully saved medication: {medication_name}"
+    except Exception as e:
+        logger.error(f"Error saving medication: {e}")
+        return f"Error saving medication: {str(e)}"
+
 @tool
 def ingest_fhir_bundle(bundle: dict):
     """

src/utils/auth.py

@@ -1,5 +1,7 @@
 import os
 import jwt
+import datetime
+import uuid
 from fastapi import Request, HTTPException, Depends
 from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
 from src.utils.logger import setup_logger
@@ -7,19 +9,25 @@ from src.utils.logger import setup_logger
 logger = setup_logger("Auth")
 security = HTTPBearer(auto_error=False)
 
+# Default patient fallback is allowed only in development when explicitly enabled
 DEFAULT_PATIENT_ID = os.getenv("DEFAULT_PATIENT_UUID")
+DEV_ALLOW_DEFAULT_PATIENT = os.getenv("DEV_ALLOW_DEFAULT_PATIENT", "false").lower() in ("1", "true", "yes")
+
 
 def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(security)):
     """
     Verifies the Supabase JWT and returns the user ID (sub).
     """
+    if not credentials:
+        raise HTTPException(status_code=401, detail="Missing credentials")
+
     token = credentials.credentials
     jwt_secret = os.getenv("SUPABASE_JWT_SECRET")
-    
+
     if not jwt_secret:
         logger.error("SUPABASE_JWT_SECRET not found in environment")
         raise HTTPException(status_code=500, detail="JWT secret missing")
-        
+
     try:
         # Supabase uses HS256 for signing JWTs with the project secret
         payload = jwt.decode(token, jwt_secret, algorithms=["HS256"], audience="authenticated")
@@ -33,14 +41,44 @@ def get_current_user(credentials: HTTPAuthorizationCredentials = Depends(securit
         logger.warning(f"Invalid token: {e}")
         raise HTTPException(status_code=401, detail="Invalid token")
 
+
 def get_active_user(credentials: HTTPAuthorizationCredentials = Depends(security)):
     """
-    Returns the user ID from the token if valid, otherwise returns the DEFAULT_PATIENT_ID.
+    Returns the user ID from the token if valid.
+    In development mode (DEV_ALLOW_DEFAULT_PATIENT) it falls back to DEFAULT_PATIENT_ID when no token provided.
+    In production it will raise 401 for missing/invalid tokens.
     """
     if not credentials:
-        return DEFAULT_PATIENT_ID
-    
+        if DEV_ALLOW_DEFAULT_PATIENT and DEFAULT_PATIENT_ID:
+            logger.info("No credentials provided; falling back to DEFAULT_PATIENT_ID (dev mode)")
+            return DEFAULT_PATIENT_ID
+        raise HTTPException(status_code=401, detail="Missing credentials")
+
     try:
         return get_current_user(credentials)
-    except Exception:
-        return DEFAULT_PATIENT_ID
+    except HTTPException as e:
+        # In dev mode we may still fall back
+        if DEV_ALLOW_DEFAULT_PATIENT and DEFAULT_PATIENT_ID:
+            logger.info("Invalid credentials; falling back to DEFAULT_PATIENT_ID (dev mode)")
+            return DEFAULT_PATIENT_ID
+        raise e
+
+
+def create_dev_token(patient_id: str, expires_minutes: int = 60):
+    """Create a development JWT signed with SUPABASE_JWT_SECRET for local dev/testing.
+
+    The token uses `sub` to store the patient/user id and `aud` of 'authenticated' to match validation.
+    """
+    jwt_secret = os.getenv("SUPABASE_JWT_SECRET")
+    if not jwt_secret:
+        raise RuntimeError("SUPABASE_JWT_SECRET not set; cannot create token")
+
+    now = datetime.datetime.utcnow()
+    payload = {
+        "sub": patient_id,
+        "iat": now,
+        "exp": now + datetime.timedelta(minutes=expires_minutes),
+        "aud": "authenticated",
+    }
+    token = jwt.encode(payload, jwt_secret, algorithm="HS256")
+    return token

src/utils/export_prompts.py

@@ -7,8 +7,8 @@ if project_root not in sys.path:
     sys.path.append(project_root)
 
 from src.agents.agents import (
-    RoleClassifier, PatientLLM, ResponseValidator, SafetyCheck, 
-    IntentClassifier, ClinicalSpecialist, OutputMerger, 
+    RoleClassifier, PatientLLM, CaregiverLLM, ResponseValidator, SafetyCheck,
+    IntentClassifier, ClinicalSpecialist, OutputMerger,
     ResearchAgent, DietarySpecialist
 )
 
@@ -21,6 +21,7 @@ def export_prompts():
     agents = {
         "RoleClassifier": RoleClassifier(),
         "PatientLLM": PatientLLM(),
+        "CaregiverLLM": CaregiverLLM(),
         "ResponseValidator": ResponseValidator(),
         "SafetyCheck": SafetyCheck(),
         "IntentClassifier": IntentClassifier(),

tests/test_agent_output_structuring.py

@@ -0,0 +1,49 @@
+import asyncio
+import sys
+import types
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.agents.agents import ResponseValidator, SafetyCheck
+
+
+class _DummyLLM:
+    def __init__(self, content):
+        self.content = content
+
+    async def ainvoke(self, messages):
+        return types.SimpleNamespace(
+            content=self.content,
+            usage_metadata=None,
+            response_metadata={}
+        )
+
+
+class TestStructuredAgentOutputs(unittest.TestCase):
+    def test_response_validator_accepts_structured_json(self):
+        validator = ResponseValidator()
+        validator.llm = _DummyLLM('{"decision": "invalid", "reason": "not complete"}')
+
+        async def _run():
+            return await validator.run({"messages": [types.SimpleNamespace(content="Sample output")]})
+
+        result = asyncio.run(_run())
+        self.assertFalse(result["is_valid"])
+
+    def test_safety_check_accepts_structured_json(self):
+        safety_check = SafetyCheck()
+        safety_check.llm = _DummyLLM('{"decision": "safe"}')
+
+        async def _run():
+            return await safety_check.run({"messages": [types.SimpleNamespace(content="Sample output")]})
+
+        result = asyncio.run(_run())
+        self.assertTrue(result["is_safe"])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_agent_params.py

@@ -0,0 +1,16 @@
+import unittest
+
+from src.agent_params import get_agent_params
+
+
+class TestAgentParams(unittest.TestCase):
+    def test_known_agent_temperature_is_loaded(self):
+        params = get_agent_params("PatientLLM")
+        self.assertEqual(params["temperature"], 0.2)
+
+    def test_unknown_agent_returns_empty_dict(self):
+        self.assertEqual(get_agent_params("UnknownAgent"), {})
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_chapter6.py

@@ -0,0 +1,73 @@
+import sys
+import unittest
+from pathlib import Path
+
+from langchain_core.messages import AIMessage, HumanMessage
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.agents.agents import DietarySpecialist, OutputMerger
+
+
+class StubLLM:
+    def __init__(self, content):
+        self.content = content
+        self.calls = []
+
+    async def ainvoke(self, messages, config=None):
+        self.calls.append(messages)
+        return AIMessage(content=self.content)
+
+    async def astream(self, messages, config=None):
+        self.calls.append(messages)
+        yield AIMessage(content=self.content)
+
+
+class TestChapter6(unittest.IsolatedAsyncioTestCase):
+    async def test_output_merger_uses_latest_specialist_output(self):
+        llm = StubLLM("merged response")
+        merger = OutputMerger()
+        merger.llm = llm
+
+        state = {
+            "messages": [
+                HumanMessage(content="What should I do next?"),
+                AIMessage(content="Older specialist response"),
+                AIMessage(content="Older user-facing answer"),
+            ],
+            "clinician_outputs": [
+                "Diagnosis says continue monitoring.",
+                "Treatment says adjust medication dose.",
+            ],
+        }
+
+        result = await merger.run(state)
+
+        self.assertEqual(result["messages"][-1].content, "merged response")
+        self.assertEqual(result["metrics"][0]["agent"], "OutputMerger")
+
+        merged_prompt = "\n".join(
+            message.content for message in llm.calls[-1]
+        )
+        self.assertIn("Treatment says adjust medication dose.", merged_prompt)
+        self.assertNotIn("Older specialist response", merged_prompt)
+
+    async def test_dietary_specialist_returns_metrics(self):
+        llm = StubLLM("dietary guidance")
+        specialist = DietarySpecialist()
+        specialist.llm = llm
+
+        state = {
+            "messages": [HumanMessage(content="Suggest a low-carb meal plan for today.")]
+        }
+
+        result = await specialist.run(state)
+
+        self.assertEqual(result["messages"][-1].content, "dietary guidance")
+        self.assertEqual(result["metrics"][0]["agent"], "DietarySpecialist")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_dietary_singletons.py

@@ -0,0 +1,23 @@
+import unittest
+from unittest.mock import patch
+
+from src.tools import dietary_tools
+
+
+class TestDietarySingletons(unittest.TestCase):
+    def tearDown(self):
+        dietary_tools._supabase_client = None
+
+    def test_get_supabase_client_reuses_cached_client(self):
+        sentinel_client = object()
+
+        with patch.object(dietary_tools, "_build_supabase_client", return_value=sentinel_client):
+            first_client = dietary_tools.get_supabase_client()
+            second_client = dietary_tools.get_supabase_client()
+
+        self.assertIs(first_client, second_client)
+        self.assertIs(first_client, sentinel_client)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_dietary_tools.py

@@ -0,0 +1,44 @@
+import unittest
+from unittest.mock import patch
+
+from src.tools import dietary_tools
+
+
+class DummyResponse:
+    def __init__(self, data):
+        self.data = data
+
+
+class DummyClient:
+    def __init__(self, data):
+        self._data = data
+
+    def rpc(self, *args, **kwargs):
+        return DummyResponse(self._data)
+
+    def table(self, *args, **kwargs):
+        return DummyResponse([])
+
+
+class TestDietaryTools(unittest.TestCase):
+    def test_page_indexed_retrieval_matches_search_guidelines(self):
+        dummy_results = [
+            {
+                "metadata": {"source": "Supabase Guide", "page_index": 12},
+                "content": "Use dietary guidance for carbohydrate targets."
+            }
+        ]
+        dummy_client = DummyClient(dummy_results)
+
+        with patch.object(dietary_tools, "get_supabase_client", return_value=dummy_client), \
+             patch.object(dietary_tools.model, "encode", return_value=[0.1, 0.2, 0.3]):
+            search_output = dietary_tools.search_guidelines.invoke("low carb meal plan")
+            page_output = dietary_tools.page_indexed_retrieval.invoke("low carb meal plan")
+
+        self.assertEqual(search_output, page_output)
+        self.assertIn("Supabase pgvector", search_output)
+        self.assertIn("Supabase Guide", search_output)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_graph_routing.py

@@ -0,0 +1,161 @@
+import importlib.util
+import sys
+import types
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+
+class _DummyLogger:
+    def info(self, *_args, **_kwargs):
+        return None
+
+
+class _DummyMessage:
+    def __init__(self, content):
+        self.content = content
+
+
+class _DummyStateGraph:
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def add_node(self, *args, **kwargs):
+        return None
+
+    def add_conditional_edges(self, *args, **kwargs):
+        return None
+
+    def add_edge(self, *args, **kwargs):
+        return None
+
+    def set_entry_point(self, *args, **kwargs):
+        return None
+
+    def compile(self):
+        return self
+
+
+def _load_graph_module():
+    langgraph = types.ModuleType("langgraph")
+    graph_module = types.ModuleType("langgraph.graph")
+    graph_module.StateGraph = _DummyStateGraph
+    graph_module.END = "END"
+    langgraph.graph = graph_module
+
+    prebuilt_module = types.ModuleType("langgraph.prebuilt")
+    prebuilt_module.ToolNode = lambda tools: tools
+
+    langchain_core = types.ModuleType("langchain_core")
+    messages_module = types.ModuleType("langchain_core.messages")
+
+    class AIMessage:
+        pass
+
+    class ToolMessage:
+        pass
+
+    messages_module.AIMessage = AIMessage
+    messages_module.ToolMessage = ToolMessage
+
+    runnables_module = types.ModuleType("langchain_core.runnables")
+    config_module = types.ModuleType("langchain_core.runnables.config")
+    config_module.RunnableConfig = dict
+
+    runnables_module.config = config_module
+    langchain_core.messages = messages_module
+    langchain_core.runnables = runnables_module
+
+    sys.modules.setdefault("langgraph", langgraph)
+    sys.modules.setdefault("langgraph.graph", graph_module)
+    sys.modules.setdefault("langgraph.prebuilt", prebuilt_module)
+    sys.modules.setdefault("langchain_core", langchain_core)
+    sys.modules.setdefault("langchain_core.messages", messages_module)
+    sys.modules.setdefault("langchain_core.runnables", runnables_module)
+    sys.modules.setdefault("langchain_core.runnables.config", config_module)
+
+    dummy_tools_module = types.ModuleType("src.tools.web_tools")
+    dummy_tools_module.web_search_tool = object()
+
+    dummy_fhir_module = types.ModuleType("src.tools.fhir_memory")
+    dummy_fhir_module.save_chat_as_fhir = types.SimpleNamespace(invoke=lambda payload: {"saved": True})
+
+    logger_module = types.ModuleType("src.utils.logger")
+    logger_module.setup_logger = lambda _name: _DummyLogger()
+
+    dietary_module = types.ModuleType("src.tools.dietary_tools")
+    dietary_module.page_indexed_retrieval = object()
+    dietary_module.search_guidelines = object()
+    dietary_module.get_nutritional_data = object()
+
+    agent_instances_module = types.ModuleType("src.agents.agent_instances")
+    agent_instances_module.role_classifier = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.patient_llm = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.caregiver_llm = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.validator = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.safety_check = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.intent_classifier = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.diagnosis_assist = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.treatment_assist = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.monitoring_assist = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.general_assist = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.output_merger = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.research_agent = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.dietary_assist = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+
+    sys.modules.setdefault("src.tools.web_tools", dummy_tools_module)
+    sys.modules.setdefault("src.tools.fhir_memory", dummy_fhir_module)
+    sys.modules.setdefault("src.utils.logger", logger_module)
+    sys.modules.setdefault("src.tools.dietary_tools", dietary_module)
+    sys.modules.setdefault("src.agents.agent_instances", agent_instances_module)
+
+    spec = importlib.util.spec_from_file_location("graph_under_test", ROOT / "backend" / "src" / "core" / "graph.py")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+class TestGraphRouting(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.graph = _load_graph_module()
+
+    def test_role_routes_caregiver_to_caregiver_llm(self):
+        state = {"user_role": "caregiver"}
+        self.assertEqual(self.graph.route_after_role(state), "caregiver_llm")
+
+    def test_role_routes_clinician_to_intent_classifier(self):
+        state = {"user_role": "clinician"}
+        self.assertEqual(self.graph.route_after_role(state), "intent_classifier")
+
+    def test_tools_route_returns_caregiver_llm_for_caregiver(self):
+        state = {"user_role": "caregiver"}
+        self.assertEqual(self.graph.route_after_tools(state), "caregiver_llm")
+
+    def test_recovery_route_returns_caregiver_llm_for_caregiver(self):
+        state = {"user_role": "caregiver"}
+        self.assertEqual(self.graph.route_after_recovery(state), "caregiver_llm")
+
+    def test_recovery_route_persists_after_max_attempts(self):
+        state = {"user_role": "patient", "attempts": 3}
+        self.assertEqual(self.graph.route_after_recovery(state), "persistence_node")
+
+    def test_emergency_route_triggers_fast_path_for_patient(self):
+        state = {
+            "user_role": "patient",
+            "messages": [_DummyMessage("The patient is unconscious and not breathing.")]
+        }
+        self.assertEqual(self.graph.route_after_role(state), "emergency_response")
+
+    def test_intent_classifier_routes_general_to_general_assist(self):
+        state = {"intent_type": "general"}
+        self.assertEqual(self.graph.route_after_intent(state), "general_assist")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_role_classifier.py

@@ -0,0 +1,15 @@
+import unittest
+
+from src.agents.role_utils import classify_role
+
+
+class TestRoleClassifier(unittest.TestCase):
+    def test_caregiver_query_maps_to_caregiver(self):
+        self.assertEqual(classify_role("I am caring for my mother with diabetes"), "caregiver")
+
+    def test_dietary_query_maps_to_dietary(self):
+        self.assertEqual(classify_role("Can you suggest a low-carb meal plan?"), "dietary")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_session_persistence.py

@@ -0,0 +1,153 @@
+import importlib.util
+import sys
+import types
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+
+class _DummyLogger:
+    def info(self, *_args, **_kwargs):
+        return None
+
+
+class _DummyStateGraph:
+    def __init__(self, *args, **kwargs):
+        pass
+
+    def add_node(self, *args, **kwargs):
+        return None
+
+    def add_conditional_edges(self, *args, **kwargs):
+        return None
+
+    def add_edge(self, *args, **kwargs):
+        return None
+
+    def set_entry_point(self, *args, **kwargs):
+        return None
+
+    def compile(self):
+        return self
+
+
+class DummyMessage:
+    def __init__(self, message_type, content):
+        self.type = message_type
+        self.content = content
+
+
+def _load_graph_module():
+    langgraph = types.ModuleType("langgraph")
+    graph_module = types.ModuleType("langgraph.graph")
+    graph_module.StateGraph = _DummyStateGraph
+    graph_module.END = "END"
+    langgraph.graph = graph_module
+
+    prebuilt_module = types.ModuleType("langgraph.prebuilt")
+    prebuilt_module.ToolNode = lambda tools: tools
+
+    langchain_core = types.ModuleType("langchain_core")
+    messages_module = types.ModuleType("langchain_core.messages")
+
+    class AIMessage:
+        pass
+
+    class ToolMessage:
+        pass
+
+    messages_module.AIMessage = AIMessage
+    messages_module.ToolMessage = ToolMessage
+
+    runnables_module = types.ModuleType("langchain_core.runnables")
+    config_module = types.ModuleType("langchain_core.runnables.config")
+    config_module.RunnableConfig = dict
+    runnables_module.config = config_module
+    langchain_core.messages = messages_module
+    langchain_core.runnables = runnables_module
+
+    sys.modules.setdefault("langgraph", langgraph)
+    sys.modules.setdefault("langgraph.graph", graph_module)
+    sys.modules.setdefault("langgraph.prebuilt", prebuilt_module)
+    sys.modules.setdefault("langchain_core", langchain_core)
+    sys.modules.setdefault("langchain_core.messages", messages_module)
+    sys.modules.setdefault("langchain_core.runnables", runnables_module)
+    sys.modules.setdefault("langchain_core.runnables.config", config_module)
+
+    dummy_tools_module = types.ModuleType("src.tools.web_tools")
+    dummy_tools_module.web_search_tool = object()
+
+    captured = {}
+
+    class DummySaveFHIR:
+        def invoke(self, payload):
+            captured.update(payload)
+            return "saved"
+
+    dummy_fhir_module = types.ModuleType("src.tools.fhir_memory")
+    dummy_fhir_module.save_chat_as_fhir = DummySaveFHIR()
+
+    logger_module = types.ModuleType("src.utils.logger")
+    logger_module.setup_logger = lambda _name: _DummyLogger()
+
+    dietary_module = types.ModuleType("src.tools.dietary_tools")
+    dietary_module.page_indexed_retrieval = object()
+    dietary_module.search_guidelines = object()
+    dietary_module.get_nutritional_data = object()
+
+    agent_instances_module = types.ModuleType("src.agents.agent_instances")
+    agent_instances_module.role_classifier = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.patient_llm = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.caregiver_llm = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.validator = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.safety_check = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.intent_classifier = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.diagnosis_assist = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.treatment_assist = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.monitoring_assist = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.general_assist = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.output_merger = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.research_agent = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+    agent_instances_module.dietary_assist = types.SimpleNamespace(run=lambda *_args, **_kwargs: None)
+
+    sys.modules.setdefault("src.tools.web_tools", dummy_tools_module)
+    sys.modules.setdefault("src.tools.fhir_memory", dummy_fhir_module)
+    sys.modules.setdefault("src.utils.logger", logger_module)
+    sys.modules.setdefault("src.tools.dietary_tools", dietary_module)
+    sys.modules.setdefault("src.agents.agent_instances", agent_instances_module)
+
+    spec = importlib.util.spec_from_file_location("graph_under_test", ROOT / "backend" / "src" / "core" / "graph.py")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module, captured
+
+
+class TestSessionPersistence(unittest.IsolatedAsyncioTestCase):
+    async def test_persistence_node_passes_session_id_to_fhir(self):
+        graph, captured = _load_graph_module()
+
+        state = {
+            "messages": [
+                DummyMessage("human", "What is my glucose trend?"),
+                DummyMessage("ai", "Your glucose trend is stable."),
+            ],
+            "user_role": "patient",
+            "patient_id": "patient-123",
+            "session_id": "session-456",
+        }
+
+        result = await graph.persistence_node(state)
+
+        self.assertEqual(captured["patient_id"], "patient-123")
+        self.assertEqual(captured["session_id"], "session-456")
+        self.assertEqual(captured["messages"][0]["role"], "user")
+        self.assertEqual(captured["messages"][1]["role"], "assistant")
+        self.assertEqual(result["metrics"][0]["agent"], "PersistenceNode")
+
+
+if __name__ == "__main__":
+    unittest.main()