Upload 12 files

src/agentcore/__init__.py

@@ -1 +1 @@
-"""LibBee agent core: constraint-driven intent-routing pipeline, split by pipeline stage."""
+"""LibBee agent core: constraint-driven intent-routing pipeline, split by pipeline stage."""

src/agentcore/classify.py

@@ -1,130 +1,130 @@
-"""Stage 2-3 of the pipeline: rule-based pre-classifier and the GPT-4o-mini intent classifier."""
-import asyncio
-import html
-import json
-import logging
-import os
-import re
-import time
-import uuid
-from datetime import datetime
-from typing import Any, Dict, List, Literal, Optional, Tuple
-from urllib.parse import quote
-
-import httpx
-from pydantic import BaseModel, ConfigDict, Field
-
-from src.config import get_settings, LIBBEE_VERSION
-
-from src.agentcore.models import ChatMessage
-from src.agentcore.constants import (
-    CURRENT_INFO_RE,
-    GREETING_FOLLOWUP_RE,
-    HISTORY_WINDOW,
-    HOURS_RE,
-    KU_CAMPUS_RE,
-    LIBRARY_CUE_RE,
-    MEDICAL_KEYWORDS,
-    MEDICAL_SEARCH_RE,
-    RESEARCH_CUE_RE,
-    SOCIAL_RE,
-    SUMMARY_RE,
-    _CLASSIFIER_SYSTEM,
-)
-from src.agentcore.utils import _get_llm
-
-logger = logging.getLogger(__name__)
-
-def _is_summary_request(question: str) -> bool:
-    return bool(SUMMARY_RE.search(question or ""))
-
-
-def _is_greeting_menu_followup(question: str, history: List[ChatMessage]) -> bool:
-    if not GREETING_FOLLOWUP_RE.match((question or "").strip()):
-        return False
-    for m in reversed(history):
-        if m.role == "assistant":
-            last = m.content.lower()
-            return "i'm libbee" in last or "are you looking for one of these" in last
-    return False
-
-
-def _looks_library_hours_question(question: str) -> bool:
-    q = (question or "").strip().lower()
-    return bool(HOURS_RE.search(q)) and any(
-        kw in q for kw in (
-            "library", "campus", "habshan", "san", "hours", "open", "close",
-            "schedule", "till", "until", "today", "tomorrow", "friday",
-            "saturday", "sunday", "week", "ramadan",
-        )
-    )
-
-
-def _looks_campus_question(question: str) -> bool:
-    return bool(KU_CAMPUS_RE.search(question or ""))
-
-
-def _looks_medical_search(question: str) -> bool:
-    q = (question or "").lower()
-    if not any(kw in q for kw in MEDICAL_KEYWORDS):
-        return False
-    return bool(MEDICAL_SEARCH_RE.search(q) or RESEARCH_CUE_RE.search(q) or SUMMARY_RE.search(q))
-
-
-def _looks_research_question(question: str) -> bool:
-    q = question or ""
-    return bool(RESEARCH_CUE_RE.search(q) or SUMMARY_RE.search(q))
-
-
-def _rule_based_classify(question: str) -> Dict[str, str]:
-    q = (question or "").lower()
-    if SOCIAL_RE.match((question or "").strip()):
-        return {
-            "intent": "social",
-            "casual_answer": (
-                "Hello! I'm LibBee, the KU Library AI Assistant. "
-                "I'm here to help you with articles, books, databases, and library services. "
-                "What would you like to find today?"
-            ),
-        }
-    if _looks_medical_search(question):
-        return {"intent": "search_medical"}
-    if _looks_research_question(question):
-        return {"intent": "search_academic"}
-    if LIBRARY_CUE_RE.search(q):
-        return {"intent": "library_info"}
-    if CURRENT_INFO_RE.search(q):
-        return {"intent": "general_recent"}
-    return {"intent": "general"}
-
-
-async def _llm_classify(question: str, history: List[ChatMessage], model: str) -> Dict[str, str]:
-    settings = get_settings()
-    if not settings.openai_api_key and not settings.anthropic_api_key:
-        return _rule_based_classify(question)
-    try:
-        ctx_parts = [
-            f"{m.role}: {m.content[:100]}"
-            for m in history[-HISTORY_WINDOW:]
-            if m.role in ("user", "assistant")
-        ]
-        ctx = " | ".join(ctx_parts) if ctx_parts else "none"
-        classify_model = "gpt" if settings.openai_api_key else model
-        llm = _get_llm(classify_model, temperature=0, max_tokens=120)
-        response = await llm.ainvoke([
-            {"role": "system", "content": _CLASSIFIER_SYSTEM},
-            {"role": "user", "content": f"Message: {question[:400]}\nContext: {ctx}\nJSON:"},
-        ])
-        raw = response.content.strip()
-        if raw.startswith("```"):
-            raw = raw.split("\n", 1)[1].rsplit("```", 1)[0].strip()
-        result = json.loads(raw)
-        intent = result.get("intent", "general")
-        if intent not in {"social", "library_info", "search_academic", "search_medical", "general_recent", "general", "sensitive"}:
-            intent = "general"
-        return {"intent": intent, "casual_answer": result.get("casual_answer", "")}
-    except Exception as e:
-        logger.warning(f"LLM classifier error: {e} — falling back to rule-based")
-        return _rule_based_classify(question)
-
-
+"""Stage 2-3 of the pipeline: rule-based pre-classifier and the GPT-4o-mini intent classifier."""
+import asyncio
+import html
+import json
+import logging
+import os
+import re
+import time
+import uuid
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from src.config import get_settings, LIBBEE_VERSION
+
+from src.agentcore.models import ChatMessage
+from src.agentcore.constants import (
+    CURRENT_INFO_RE,
+    GREETING_FOLLOWUP_RE,
+    HISTORY_WINDOW,
+    HOURS_RE,
+    KU_CAMPUS_RE,
+    LIBRARY_CUE_RE,
+    MEDICAL_KEYWORDS,
+    MEDICAL_SEARCH_RE,
+    RESEARCH_CUE_RE,
+    SOCIAL_RE,
+    SUMMARY_RE,
+    _CLASSIFIER_SYSTEM,
+)
+from src.agentcore.utils import _get_llm
+
+logger = logging.getLogger(__name__)
+
+def _is_summary_request(question: str) -> bool:
+    return bool(SUMMARY_RE.search(question or ""))
+
+
+def _is_greeting_menu_followup(question: str, history: List[ChatMessage]) -> bool:
+    if not GREETING_FOLLOWUP_RE.match((question or "").strip()):
+        return False
+    for m in reversed(history):
+        if m.role == "assistant":
+            last = m.content.lower()
+            return "i'm libbee" in last or "are you looking for one of these" in last
+    return False
+
+
+def _looks_library_hours_question(question: str) -> bool:
+    q = (question or "").strip().lower()
+    return bool(HOURS_RE.search(q)) and any(
+        kw in q for kw in (
+            "library", "campus", "habshan", "san", "hours", "open", "close",
+            "schedule", "till", "until", "today", "tomorrow", "friday",
+            "saturday", "sunday", "week", "ramadan",
+        )
+    )
+
+
+def _looks_campus_question(question: str) -> bool:
+    return bool(KU_CAMPUS_RE.search(question or ""))
+
+
+def _looks_medical_search(question: str) -> bool:
+    q = (question or "").lower()
+    if not any(kw in q for kw in MEDICAL_KEYWORDS):
+        return False
+    return bool(MEDICAL_SEARCH_RE.search(q) or RESEARCH_CUE_RE.search(q) or SUMMARY_RE.search(q))
+
+
+def _looks_research_question(question: str) -> bool:
+    q = question or ""
+    return bool(RESEARCH_CUE_RE.search(q) or SUMMARY_RE.search(q))
+
+
+def _rule_based_classify(question: str) -> Dict[str, str]:
+    q = (question or "").lower()
+    if SOCIAL_RE.match((question or "").strip()):
+        return {
+            "intent": "social",
+            "casual_answer": (
+                "Hello! I'm LibBee, the KU Library AI Assistant. "
+                "I'm here to help you with articles, books, databases, and library services. "
+                "What would you like to find today?"
+            ),
+        }
+    if _looks_medical_search(question):
+        return {"intent": "search_medical"}
+    if _looks_research_question(question):
+        return {"intent": "search_academic"}
+    if LIBRARY_CUE_RE.search(q):
+        return {"intent": "library_info"}
+    if CURRENT_INFO_RE.search(q):
+        return {"intent": "general_recent"}
+    return {"intent": "general"}
+
+
+async def _llm_classify(question: str, history: List[ChatMessage], model: str) -> Dict[str, str]:
+    settings = get_settings()
+    if not settings.openai_api_key and not settings.anthropic_api_key:
+        return _rule_based_classify(question)
+    try:
+        ctx_parts = [
+            f"{m.role}: {m.content[:100]}"
+            for m in history[-HISTORY_WINDOW:]
+            if m.role in ("user", "assistant")
+        ]
+        ctx = " | ".join(ctx_parts) if ctx_parts else "none"
+        classify_model = "gpt" if settings.openai_api_key else model
+        llm = _get_llm(classify_model, temperature=0, max_tokens=120)
+        response = await llm.ainvoke([
+            {"role": "system", "content": _CLASSIFIER_SYSTEM},
+            {"role": "user", "content": f"Message: {question[:400]}\nContext: {ctx}\nJSON:"},
+        ])
+        raw = response.content.strip()
+        if raw.startswith("```"):
+            raw = raw.split("\n", 1)[1].rsplit("```", 1)[0].strip()
+        result = json.loads(raw)
+        intent = result.get("intent", "general")
+        if intent not in {"social", "library_info", "search_academic", "search_medical", "general_recent", "general", "sensitive"}:
+            intent = "general"
+        return {"intent": intent, "casual_answer": result.get("casual_answer", "")}
+    except Exception as e:
+        logger.warning(f"LLM classifier error: {e} — falling back to rule-based")
+        return _rule_based_classify(question)
+
+

src/agentcore/intents_general.py

@@ -1,160 +1,160 @@
-"""general / social intents: web-search answers, general LLM answers, casual persona replies."""
-import asyncio
-import html
-import json
-import logging
-import os
-import re
-import time
-import uuid
-from datetime import datetime
-from typing import Any, Dict, List, Literal, Optional, Tuple
-from urllib.parse import quote
-
-import httpx
-from pydantic import BaseModel, ConfigDict, Field
-
-from src.config import get_settings, LIBBEE_VERSION
-
-from src.agentcore.models import ChatMessage
-from src.agentcore.constants import KU_MAIN_URL, _GUARDRAIL, _URL_INSTRUCTION
-from src.agentcore.utils import _build_history_messages, _get_llm, _get_runtime_config
-
-logger = logging.getLogger(__name__)
-
-async def _libbee_casual_response(question: str, history: List[ChatMessage], model: str, hint: str = "") -> str:
-    """LLM #1 — casual social response. v3.8.1: appends _GUARDRAIL + _URL_INSTRUCTION."""
-    if hint and len(hint.strip()) > 20:
-        return hint.strip()
-    settings = get_settings()
-    if not settings.openai_api_key and not settings.anthropic_api_key:
-        return "I'm <strong>LibBee</strong>, the Khalifa University Library AI Assistant — always happy to help!"
-    try:
-        llm = _get_llm(model, temperature=0.6, max_tokens=160)
-        msgs = [{"role": "system", "content": (
-            "You are LibBee, the Khalifa University Library AI Assistant. "
-            "Respond warmly and naturally in 1-3 sentences as a friendly librarian. "
-            "No markdown, no bullet points. "
-            + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
-        )}]
-        _cfg = _get_runtime_config()
-        _ci = _cfg.get("custom_instructions", "").strip()
-        if _ci:
-            msgs[0]["content"] += " " + _ci
-        msgs.extend(_build_history_messages(history))
-        msgs.append({"role": "user", "content": question})
-        response = await llm.ainvoke(msgs)
-        return response.content.strip()
-    except Exception:
-        return "I'm <strong>LibBee</strong>, the Khalifa University Library AI Assistant — always happy to help!"
-
-
-async def _llm_general_answer(question: str, history: List[ChatMessage], model: str) -> str:
-    """LLM #3 — general factual answer. v3.8.1: appends _GUARDRAIL + _URL_INSTRUCTION."""
-    settings = get_settings()
-    if not settings.openai_api_key and not settings.anthropic_api_key:
-        return (
-            "I'm <strong>LibBee</strong>, the KU Library AI Assistant. "
-            f'For general university information, visit <a href="{KU_MAIN_URL}" target="_blank">ku.ac.ae</a>.'
-        )
-    system = (
-        "You are LibBee, the Khalifa University Library AI Assistant (Abu Dhabi, UAE). "
-        "Answer factually and concisely in 3-5 sentences. Use HTML <br> for line breaks. "
-        "KU means Khalifa University. If the topic is academic, briefly offer to help find library resources. "
-        "When referencing KU Library services, include these verified links where relevant: "
-        "Library homepage: https://library.ku.ac.ae | "
-        "Ask a Librarian: https://library.ku.ac.ae/AskUs | "
-        "Library hours: https://library.ku.ac.ae/hours | "
-        "ILL requests: https://library.ku.ac.ae/ill/ | "
-        "Study rooms: https://library.ku.ac.ae/rooms/ | "
-        "E-resources: https://library.ku.ac.ae/eresources | "
-        "Khazna repository: https://khazna.ku.ac.ae | "
-        "PRIMO discovery: https://khalifa.primo.exlibrisgroup.com/discovery/search?vid=971KUOSTAR_INST:KU. "
-        "Only use these exact URLs — never invent others. "
-        + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
-    )
-    _cfg = _get_runtime_config()
-    _ci = _cfg.get("custom_instructions", "").strip()
-    if _ci:
-        system += " " + _ci
-    try:
-        llm = _get_llm(model, temperature=0.3, max_tokens=360)
-        msgs = [{"role": "system", "content": system}]
-        msgs.extend(_build_history_messages(history))
-        msgs.append({"role": "user", "content": question})
-        response = await llm.ainvoke(msgs)
-        return response.content.strip()
-    except Exception as e:
-        logger.error(f"_llm_general_answer error: {e}")
-        return f'Having trouble right now. Visit <a href="{KU_MAIN_URL}" target="_blank">ku.ac.ae</a>.'
-
-
-async def _web_search_answer(question: str, history: List[ChatMessage], model: str) -> str:
-    """LLM #4 — web search answer. v3.8.1: appends _GUARDRAIL + _URL_INSTRUCTION."""
-    settings = get_settings()
-    _WEB_SYSTEM = (
-        "You are LibBee, the Khalifa University Library AI Assistant (Abu Dhabi, UAE). "
-        "Answer using current web search. Be concise and factual. Use HTML <br> for line breaks. "
-        + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
-    )
-    if model == "claude" and settings.anthropic_api_key:
-        try:
-            import anthropic
-            client = anthropic.Anthropic(api_key=settings.anthropic_api_key)
-            response = client.messages.create(
-                model="claude-haiku-4-5-20251001",
-                max_tokens=520,
-                system=_WEB_SYSTEM,
-                tools=[{"type": "web_search_20250305", "name": "web_search"}],
-                messages=[{"role": "user", "content": question}],
-            )
-            text = "".join(block.text for block in response.content if hasattr(block, "text"))
-            if text.strip():
-                return text.strip()
-        except Exception as e:
-            logger.warning(f"Claude web search failed: {e}")
-    if settings.openai_api_key:
-        try:
-            from openai import OpenAI
-            client = OpenAI(api_key=settings.openai_api_key)
-            response = client.responses.create(
-                model="gpt-4o-mini",
-                tools=[{"type": "web_search_preview"}],
-                instructions=_WEB_SYSTEM,
-                input=question,
-            )
-            text = ""
-            for item in response.output:
-                if hasattr(item, "content"):
-                    for block in item.content:
-                        if hasattr(block, "text"):
-                            text += block.text
-            if text.strip():
-                return text.strip()
-        except Exception as e:
-            logger.warning(f"GPT web search failed: {e}")
-    return await _llm_general_answer(question, history, model)
-
-
-def _general_follow_up(question: str) -> Tuple[str, List[dict]]:
-    return (
-        "Would you like a brief explanation, current web information, or KU Library resources on this topic?",
-        [
-            {"label": "Shorter explanation", "question": f"Give me a shorter explanation of {question}"},
-            {"label": "Current web information", "question": f"Show current web information on {question}"},
-            {"label": "Find KU Library resources", "question": f"Find KU Library resources on {question}"},
-        ],
-    )
-
-
-def _social_follow_up() -> Tuple[str, List[dict]]:
-    return (
-        "What would you like help with next?",
-        [
-            {"label": "Find articles on a topic", "question": "Find articles on a topic"},
-            {"label": "Check a library service", "question": "Check a library service"},
-            {"label": "Contact a librarian", "question": "Contact a librarian"},
-        ],
-    )
-
-
+"""general / social intents: web-search answers, general LLM answers, casual persona replies."""
+import asyncio
+import html
+import json
+import logging
+import os
+import re
+import time
+import uuid
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from src.config import get_settings, LIBBEE_VERSION
+
+from src.agentcore.models import ChatMessage
+from src.agentcore.constants import KU_MAIN_URL, _GUARDRAIL, _URL_INSTRUCTION
+from src.agentcore.utils import _build_history_messages, _get_llm, _get_runtime_config
+
+logger = logging.getLogger(__name__)
+
+async def _libbee_casual_response(question: str, history: List[ChatMessage], model: str, hint: str = "") -> str:
+    """LLM #1 — casual social response. v3.8.1: appends _GUARDRAIL + _URL_INSTRUCTION."""
+    if hint and len(hint.strip()) > 20:
+        return hint.strip()
+    settings = get_settings()
+    if not settings.openai_api_key and not settings.anthropic_api_key:
+        return "I'm <strong>LibBee</strong>, the Khalifa University Library AI Assistant — always happy to help!"
+    try:
+        llm = _get_llm(model, temperature=0.6, max_tokens=160)
+        msgs = [{"role": "system", "content": (
+            "You are LibBee, the Khalifa University Library AI Assistant. "
+            "Respond warmly and naturally in 1-3 sentences as a friendly librarian. "
+            "No markdown, no bullet points. "
+            + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
+        )}]
+        _cfg = _get_runtime_config()
+        _ci = _cfg.get("custom_instructions", "").strip()
+        if _ci:
+            msgs[0]["content"] += " " + _ci
+        msgs.extend(_build_history_messages(history))
+        msgs.append({"role": "user", "content": question})
+        response = await llm.ainvoke(msgs)
+        return response.content.strip()
+    except Exception:
+        return "I'm <strong>LibBee</strong>, the Khalifa University Library AI Assistant — always happy to help!"
+
+
+async def _llm_general_answer(question: str, history: List[ChatMessage], model: str) -> str:
+    """LLM #3 — general factual answer. v3.8.1: appends _GUARDRAIL + _URL_INSTRUCTION."""
+    settings = get_settings()
+    if not settings.openai_api_key and not settings.anthropic_api_key:
+        return (
+            "I'm <strong>LibBee</strong>, the KU Library AI Assistant. "
+            f'For general university information, visit <a href="{KU_MAIN_URL}" target="_blank">ku.ac.ae</a>.'
+        )
+    system = (
+        "You are LibBee, the Khalifa University Library AI Assistant (Abu Dhabi, UAE). "
+        "Answer factually and concisely in 3-5 sentences. Use HTML <br> for line breaks. "
+        "KU means Khalifa University. If the topic is academic, briefly offer to help find library resources. "
+        "When referencing KU Library services, include these verified links where relevant: "
+        "Library homepage: https://library.ku.ac.ae | "
+        "Ask a Librarian: https://library.ku.ac.ae/AskUs | "
+        "Library hours: https://library.ku.ac.ae/hours | "
+        "ILL requests: https://library.ku.ac.ae/ill/ | "
+        "Study rooms: https://library.ku.ac.ae/rooms/ | "
+        "E-resources: https://library.ku.ac.ae/eresources | "
+        "Khazna repository: https://khazna.ku.ac.ae | "
+        "PRIMO discovery: https://khalifa.primo.exlibrisgroup.com/discovery/search?vid=971KUOSTAR_INST:KU. "
+        "Only use these exact URLs — never invent others. "
+        + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
+    )
+    _cfg = _get_runtime_config()
+    _ci = _cfg.get("custom_instructions", "").strip()
+    if _ci:
+        system += " " + _ci
+    try:
+        llm = _get_llm(model, temperature=0.3, max_tokens=360)
+        msgs = [{"role": "system", "content": system}]
+        msgs.extend(_build_history_messages(history))
+        msgs.append({"role": "user", "content": question})
+        response = await llm.ainvoke(msgs)
+        return response.content.strip()
+    except Exception as e:
+        logger.error(f"_llm_general_answer error: {e}")
+        return f'Having trouble right now. Visit <a href="{KU_MAIN_URL}" target="_blank">ku.ac.ae</a>.'
+
+
+async def _web_search_answer(question: str, history: List[ChatMessage], model: str) -> str:
+    """LLM #4 — web search answer. v3.8.1: appends _GUARDRAIL + _URL_INSTRUCTION."""
+    settings = get_settings()
+    _WEB_SYSTEM = (
+        "You are LibBee, the Khalifa University Library AI Assistant (Abu Dhabi, UAE). "
+        "Answer using current web search. Be concise and factual. Use HTML <br> for line breaks. "
+        + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
+    )
+    if model == "claude" and settings.anthropic_api_key:
+        try:
+            import anthropic
+            client = anthropic.AsyncAnthropic(api_key=settings.anthropic_api_key)
+            response = await client.messages.create(
+                model="claude-haiku-4-5-20251001",
+                max_tokens=520,
+                system=_WEB_SYSTEM,
+                tools=[{"type": "web_search_20250305", "name": "web_search"}],
+                messages=[{"role": "user", "content": question}],
+            )
+            text = "".join(block.text for block in response.content if hasattr(block, "text"))
+            if text.strip():
+                return text.strip()
+        except Exception as e:
+            logger.warning(f"Claude web search failed: {e}")
+    if settings.openai_api_key:
+        try:
+            from openai import AsyncOpenAI
+            client = AsyncOpenAI(api_key=settings.openai_api_key)
+            response = await client.responses.create(
+                model="gpt-4o-mini",
+                tools=[{"type": "web_search_preview"}],
+                instructions=_WEB_SYSTEM,
+                input=question,
+            )
+            text = ""
+            for item in response.output:
+                if hasattr(item, "content"):
+                    for block in item.content:
+                        if hasattr(block, "text"):
+                            text += block.text
+            if text.strip():
+                return text.strip()
+        except Exception as e:
+            logger.warning(f"GPT web search failed: {e}")
+    return await _llm_general_answer(question, history, model)
+
+
+def _general_follow_up(question: str) -> Tuple[str, List[dict]]:
+    return (
+        "Would you like a brief explanation, current web information, or KU Library resources on this topic?",
+        [
+            {"label": "Shorter explanation", "question": f"Give me a shorter explanation of {question}"},
+            {"label": "Current web information", "question": f"Show current web information on {question}"},
+            {"label": "Find KU Library resources", "question": f"Find KU Library resources on {question}"},
+        ],
+    )
+
+
+def _social_follow_up() -> Tuple[str, List[dict]]:
+    return (
+        "What would you like help with next?",
+        [
+            {"label": "Find articles on a topic", "question": "Find articles on a topic"},
+            {"label": "Check a library service", "question": "Check a library service"},
+            {"label": "Contact a librarian", "question": "Contact a librarian"},
+        ],
+    )
+
+

src/agentcore/intents_library.py

@@ -1,280 +1,280 @@
-"""library_info intent handlers: campus, RAG answers, database recommendations, full-text chain, theses."""
-import asyncio
-import html
-import json
-import logging
-import os
-import re
-import time
-import uuid
-from datetime import datetime
-from typing import Any, Dict, List, Literal, Optional, Tuple
-from urllib.parse import quote
-
-import httpx
-from pydantic import BaseModel, ConfigDict, Field
-
-from src.config import get_settings, LIBBEE_VERSION
-from src.services.staff_service import (
-    STAFF_DIRECTORY,
-    match_staff_name,
-    match_staff_role,
-    should_attempt_staff_lookup,
-    staff_name_answer,
-    staff_role_answer,
-)
-
-from src.agentcore.models import ChatMessage
-from src.agentcore.constants import (
-    ASK_LIBRARIAN_URL,
-    DATABASE_RECOMMEND_RE,
-    _DB_GENERAL,
-    _DB_SUBJECTS,
-    _GUARDRAIL,
-    _URL_INSTRUCTION,
-)
-from src.agentcore.utils import (
-    _build_history_messages,
-    _escape,
-    _get_llm,
-    _get_runtime_config,
-    _normalize_whitespace,
-    _strip_resource_noise,
-)
-from src.agentcore.classify import _looks_library_hours_question
-
-logger = logging.getLogger(__name__)
-
-def _campus_answer() -> str:
-    return (
-        "Khalifa University Library has <strong>two branches</strong>:<br><br>"
-        "<strong>1. Main Campus Library</strong><br>"
-        "Location: E Building, Main Campus, Abu Dhabi<br>"
-        'Reference desk: <a href="tel:+97123124604">+971 2 312 4604</a><br><br>'
-        "<strong>2. Habshan Library (SAN Campus)</strong><br>"
-        "Location: Building 5, Ground Floor &amp; First Floor, Sas Al Nakhl (SAN) Campus, Abu Dhabi<br>"
-        'Service desk: <a href="tel:+97123123160">+971 2 312 3160</a><br><br>'
-        "Both branches offer study spaces, computer workstations, printing, scanning, "
-        "and access to physical collections.<br><br>"
-        f'For general library enquiries: <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a> '
-        'or email <a href="mailto:libse@ku.ac.ae">libse@ku.ac.ae</a>.'
-    )
-
-
-def _greeting_menu_clarify_answer() -> str:
-    return (
-        "Sure — what would you like help with?<br><br>"
-        "You can choose one of these or type your question directly:<br>"
-        "• Find articles and books<br>"
-        "• Get full text for an article<br>"
-        "• Submit an Interlibrary Loan (ILL) request<br>"
-        "• Contact a librarian<br>"
-        "• Check library hours"
-    )
-
-
-async def _rag_answer(question: str, rag_results: List[dict], history: List[ChatMessage], model: str) -> str:
-    """LLM #2 — RAG answer from KB chunks. v3.8.1: appends _GUARDRAIL + _URL_INSTRUCTION."""
-    settings = get_settings()
-    if not settings.openai_api_key and not settings.anthropic_api_key:
-        return rag_results[0]["content"] if rag_results else ""
-    context = "\n\n---\n\n".join(r["content"] for r in rag_results)
-    system = (
-        "You are LibBee, the Khalifa University Library AI Assistant. "
-        "Answer the user's question using ONLY the context provided below. "
-        "Be concise, friendly, and use HTML <br> for line breaks where needed. "
-        "IMPORTANT — LINKS: When the context contains a URL (starting with https:// or http://), "
-        "include it as a clickable HTML link using <a href=\"URL\" target=\"_blank\">link text</a>. "
-        "For example, if context mentions 'library.ku.ac.ae/ill/' include it as a link. "
-        "NEVER invent or guess URLs that do not appear in the context. "
-        "Only link to URLs that are explicitly present in the context below. "
-        f"If the context does not contain enough information, say so and suggest Ask a Librarian at "
-        f'<a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a> or '
-        f'<a href="mailto:libse@ku.ac.ae">libse@ku.ac.ae</a>.\n\n'
-        f"CONTEXT:\n{context}\n\n"
-        + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
-    )
-    _cfg = _get_runtime_config()
-    _ci = _cfg.get("custom_instructions", "").strip()
-    if _ci:
-        system += "\n\nAdditional instructions: " + _ci
-    try:
-        llm = _get_llm(model, temperature=0.2, max_tokens=380)
-        msgs = [{"role": "system", "content": system}]
-        msgs.extend(_build_history_messages(history))
-        msgs.append({"role": "user", "content": question})
-        response = await llm.ainvoke(msgs)
-        return response.content.strip()
-    except Exception as e:
-        logger.error(f"_rag_answer error: {e}")
-        return (
-            "I'm having trouble generating an answer right now. "
-            f'Please try <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a>.'
-        )
-
-
-def _is_database_recommendation_question(question: str) -> bool:
-    return bool(DATABASE_RECOMMEND_RE.search(question or ""))
-
-
-def _match_db_subject(q: str) -> Optional[str]:
-    checks = [
-        (["quantum computing", "quantum algorithm", "quantum cryptography", "quantum information"], "quantum_computing"),
-        (["robotics", "autonomous system", "intelligent system"], "robotics"),
-        (["artificial intelligence", "machine learning", "deep learning", "nlp", "natural language processing", "neural network", "cybersecurity", "computer science", "software engineering", "algorithm", "data structure"], "computer_science"),
-        (["computer engineering", "embedded system", "computer architecture", "networking", "digital system"], "computer_science"),
-        (["aerospace", "aerodynamic", "propulsion", "aircraft", "aviation", "flight system"], "aerospace"),
-        (["biomedical engineering", "medical device", "biomechanic", "bioinstrument", "tissue engineering", "biomedical imaging"], "biomedical"),
-        (["chemical engineering", "process engineering", "reaction engineering", "separation", "catalysis"], "chemical_engineering"),
-        (["chemistry", "organic chemistry", "analytical chemistry", "inorganic", "chemical", "chemical properties"], "chemistry"),
-        (["civil engineering", "structural engineering", "geotechnical", "transportation engineering", "water resources", "construction"], "civil_engineering"),
-        (["electrical engineering", "circuit", "power system", "signal processing", "control system", "communication system", "electronics"], "electrical_engineering"),
-        (["energy engineering", "renewable energy", "sustainable energy", "clean energy", "energy transition", "solar", "wind power"], "energy"),
-        (["engineering management", "engineering systems", "systems engineering", "operations management", "innovation management"], "engineering_management"),
-        (["mechanical engineering", "thermofluid", "thermodynamics", "fluid mechanics", "manufacturing", "mechatronics"], "mechanical_engineering"),
-        (["nuclear engineering", "reactor", "radiation", "nuclear material", "nuclear safety"], "nuclear"),
-        (["petroleum engineering", "oil and gas", "drilling", "reservoir", "subsurface", "petroleum"], "petroleum"),
-        (["earth science", "geology", "geophysics", "geochemistry", "planetary science", "geoscience"], "earth_science"),
-        (["environment", "sustainability", "climate change", "sustainable development", "conservation", "environmental policy", "ecology"], "environment"),
-        (["materials science", "nanotechnology", "nanomaterial", "biomaterial", "advanced material", "functional material"], "materials"),
-        (["cell biology", "molecular biology", "genetics", "genomics", "biotechnology", "bioinformatics", "microbiology", "virology"], "biology"),
-        (["medicine", "medical", "health science", "clinical", "nursing", "pharmacy", "biomedical literature", "pharmacology", "clinical trial", "systematic review", "evidence-based", "patient care"], "medical"),
-        (["business", "management", "finance", "economics", "accounting", "entrepreneurship", "marketing", "strategy", "leadership", "international relations", "political science", "social science", "humanities", "law", "education", "psychology", "sociology"], "business"),
-        (["physics", "optics", "photonics", "quantum physics", "condensed matter", "theoretical physics", "astrophysics"], "physics"),
-        (["mathematics", "statistics", "data science", "calculus", "algebra", "optimization", "probability", "mathematical model"], "mathematics"),
-        (["impact factor", "journal metrics", "citescore", "jcr", "quartile", "research impact", "scival", "bibliometric"], "metrics"),
-        (["dissertation", "thesis", "doctoral", "master thesis", "repository", "phd thesis"], "theses"),
-    ]
-    for keywords, key in checks:
-        if any(kw in q for kw in keywords):
-            return key
-    return None
-
-
-def _extract_db_topic(question: str) -> str:
-    q = _normalize_whitespace(question or "")
-    patterns = [
-        r"^(best|good|recommended?)\s+databases?\s+for\s+",
-        r"^which\s+databases?\s+(for|should i use for|is best for|are best for)\s+",
-        r"^databases?\s+for\s+",
-        r"^where should i (search|start)\s+(for\s+)?",
-        r"^what (database|databases)\s+(for|should i use for)\s+",
-    ]
-    lower = q.lower()
-    for pat in patterns:
-        m = re.match(pat, lower)
-        if m:
-            q = q[m.end():]
-            break
-    q = re.sub(r"\s+(please|thanks|thank you)\.?$", "", q, flags=re.IGNORECASE)
-    q = _strip_resource_noise(q)
-    return _normalize_whitespace(q).strip(".?") or "this subject"
-
-
-def _database_recommendation_answer(question: str) -> str:
-    q = (question or "").lower()
-    subject = _extract_db_topic(question)
-    topic = _escape(subject)
-    subject_key = _match_db_subject(q)
-    dbs = _DB_SUBJECTS.get(subject_key, _DB_GENERAL) if subject_key else _DB_GENERAL
-    dbs = list(dbs)[:5]
-    answer = f"<strong>Recommended databases for {topic}</strong><br><br>"
-    answer += "Here are the strongest KU-subscribed starting points:<br>"
-    for name, url, why in dbs:
-        answer += f'<br>• <a href="{url}" target="_blank"><strong>{_escape(name)}</strong></a> — {_escape(why)}'
-    if not subject_key:
-        answer += (
-            "<br><br>💡 For subject-specific databases, ask me: "
-            "<em>\"best databases for [your subject]\"</em> — e.g. physics, chemistry, medicine, civil engineering."
-        )
-    answer += (
-        f'<br><br>Browse all 50+ KU databases: '
-        f'<a href="https://library.ku.ac.ae/eresources" target="_blank">library.ku.ac.ae/eresources</a>'
-    )
-    answer += "<br><br>Want me to run a direct search on any of these for a specific topic?"
-    return answer
-
-
-def _fulltext_chain_answer(question: str) -> str:
-    return (
-        "<strong>📄 How to get full text for an article</strong><br><br>"
-        "Follow this chain in order — each step is faster than the next:<br><br>"
-        "<strong>Step 1 — Search KU PRIMO</strong><br>"
-        "Find the article in <a href=\"https://khalifa.primo.exlibrisgroup.com/discovery/search"
-        "?vid=971KUOSTAR_INST:KU\" target=\"_blank\">KU Library Discovery</a>. "
-        "If KU subscribes, you'll see a <em>Full Text Available</em> or <em>Online Access</em> link. "
-        "Click it — it passes through the IDM proxy automatically when on campus or logged in.<br><br>"
-        "<strong>Step 2 — Try LibKey Nomad (browser extension)</strong><br>"
-        "<a href=\"https://libkey.io/libraries/3025/\" target=\"_blank\">LibKey Nomad</a> is a free browser "
-        "extension that detects articles you're viewing and fetches KU's full text automatically. "
-        "Install it once and it works on every publisher site.<br><br>"
-        "<strong>Step 3 — Try the publisher or open access</strong><br>"
-        "Visit the DOI link directly. Many authors post their accepted manuscript on "
-        "<a href=\"https://arxiv.org\" target=\"_blank\">arXiv</a>, "
-        "<a href=\"https://www.researchgate.net\" target=\"_blank\">ResearchGate</a>, or their institutional page. "
-        "<a href=\"https://openalex.org\" target=\"_blank\">OpenAlex</a> also links to many legal open-access PDFs.<br><br>"
-        "<strong>Step 4 — Submit an Interlibrary Loan (ILL) request</strong><br>"
-        "If none of the above work, KU Library can borrow the article from another library — usually within 1–5 working days. "
-        "Submit here: <a href=\"https://library.ku.ac.ae/ill/\" target=\"_blank\">library.ku.ac.ae/ill/</a><br>"
-        "Contact: <strong>Suaad Al Jneibi</strong> · "
-        "<a href=\"mailto:suaad.aljneibi@ku.ac.ae\">suaad.aljneibi@ku.ac.ae</a> · +971 2 312 4278"
-    )
-
-
-def _theses_answer() -> str:
-    return (
-        "<strong>📘 Finding KU theses, dissertations, and institutional research</strong><br><br>"
-        "<strong>Khalifa University Khazna Repository</strong><br>"
-        "Khazna is KU's institutional repository — it holds KU theses, dissertations, "
-        "faculty publications, conference papers, and open-access research outputs.<br>"
-        '🔗 <a href="https://khazna.ku.ac.ae" target="_blank">khazna.ku.ac.ae</a><br><br>'
-        "<strong>ProQuest Dissertations &amp; Theses Global</strong><br>"
-        "KU subscribes to ProQuest D&T Global — the world's largest database of "
-        "theses and dissertations from universities worldwide.<br>"
-        '🔗 <a href="https://khalifa.idm.oclc.org/login?url=https://www.proquest.com/pqdtglobal" target="_blank">'
-        "Access via KU Library</a><br><br>"
-        "<strong>Other sources</strong><br>"
-        '• <a href="https://ethos.bl.uk" target="_blank">EThOS</a> — UK theses (British Library)<br>'
-        '• <a href="https://www.dart-europe.org" target="_blank">DART-Europe</a> — European theses<br>'
-        '• <a href="https://ndltd.org" target="_blank">NDLTD</a> — Global networked digital library of theses<br><br>'
-        "For help with Khazna deposits or ORCID integration, contact: "
-        "<strong>Nikesh Narayanan</strong> · "
-        "<a href=\"mailto:nikesh.narayanan@ku.ac.ae\">nikesh.narayanan@ku.ac.ae</a>"
-    )
-
-
-def _library_follow_up(question: str) -> Tuple[str, List[dict]]:
-    q = (question or "").lower()
-    if _looks_library_hours_question(question):
-        return (
-            "Would you like the library contact details too?",
-            [
-                {"label": "Show library contact details", "question": "Show the library contact details"},
-                {"label": "Open the live library hours page", "question": "Open the live library hours page"},
-            ],
-        )
-    if "study room" in q or "room" in q:
-        return (
-            "Would you like the study-room booking link?",
-            [
-                {"label": "Study-room booking link", "question": "Show the study-room booking link"},
-                {"label": "Library services for both campuses", "question": "Show library services for both campuses"},
-            ],
-        )
-    if any(token in q for token in ["database", "databases", "search", "articles", "research"]):
-        return (
-            "Would you like me to recommend the best KU databases for this topic?",
-            [
-                {"label": "Recommend best KU databases", "question": "Recommend the best KU databases for this topic"},
-                {"label": "How to access databases off campus", "question": "How do I access databases off campus?"},
-            ],
-        )
-    return (
-        "Would you like a related library service or staff contact?",
-        [
-            {"label": "Best staff contact", "question": "Show the best staff contact for this"},
-            {"label": "KU library page for this topic", "question": "Open the KU library page for this topic"},
-        ],
-    )
-
-
+"""library_info intent handlers: campus, RAG answers, database recommendations, full-text chain, theses."""
+import asyncio
+import html
+import json
+import logging
+import os
+import re
+import time
+import uuid
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from src.config import get_settings, LIBBEE_VERSION
+from src.services.staff_service import (
+    STAFF_DIRECTORY,
+    match_staff_name,
+    match_staff_role,
+    should_attempt_staff_lookup,
+    staff_name_answer,
+    staff_role_answer,
+)
+
+from src.agentcore.models import ChatMessage
+from src.agentcore.constants import (
+    ASK_LIBRARIAN_URL,
+    DATABASE_RECOMMEND_RE,
+    _DB_GENERAL,
+    _DB_SUBJECTS,
+    _GUARDRAIL,
+    _URL_INSTRUCTION,
+)
+from src.agentcore.utils import (
+    _build_history_messages,
+    _escape,
+    _get_llm,
+    _get_runtime_config,
+    _normalize_whitespace,
+    _strip_resource_noise,
+)
+from src.agentcore.classify import _looks_library_hours_question
+
+logger = logging.getLogger(__name__)
+
+def _campus_answer() -> str:
+    return (
+        "Khalifa University Library has <strong>two branches</strong>:<br><br>"
+        "<strong>1. Main Campus Library</strong><br>"
+        "Location: E Building, Main Campus, Abu Dhabi<br>"
+        'Reference desk: <a href="tel:+97123124604">+971 2 312 4604</a><br><br>'
+        "<strong>2. Habshan Library (SAN Campus)</strong><br>"
+        "Location: Building 5, Ground Floor &amp; First Floor, Sas Al Nakhl (SAN) Campus, Abu Dhabi<br>"
+        'Service desk: <a href="tel:+97123123160">+971 2 312 3160</a><br><br>'
+        "Both branches offer study spaces, computer workstations, printing, scanning, "
+        "and access to physical collections.<br><br>"
+        f'For general library enquiries: <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a> '
+        'or email <a href="mailto:libse@ku.ac.ae">libse@ku.ac.ae</a>.'
+    )
+
+
+def _greeting_menu_clarify_answer() -> str:
+    return (
+        "Sure — what would you like help with?<br><br>"
+        "You can choose one of these or type your question directly:<br>"
+        "• Find articles and books<br>"
+        "• Get full text for an article<br>"
+        "• Submit an Interlibrary Loan (ILL) request<br>"
+        "• Contact a librarian<br>"
+        "• Check library hours"
+    )
+
+
+async def _rag_answer(question: str, rag_results: List[dict], history: List[ChatMessage], model: str) -> str:
+    """LLM #2 — RAG answer from KB chunks. v3.8.1: appends _GUARDRAIL + _URL_INSTRUCTION."""
+    settings = get_settings()
+    if not settings.openai_api_key and not settings.anthropic_api_key:
+        return rag_results[0]["content"] if rag_results else ""
+    context = "\n\n---\n\n".join(r["content"] for r in rag_results)
+    system = (
+        "You are LibBee, the Khalifa University Library AI Assistant. "
+        "Answer the user's question using ONLY the context provided below. "
+        "Be concise, friendly, and use HTML <br> for line breaks where needed. "
+        "IMPORTANT — LINKS: When the context contains a URL (starting with https:// or http://), "
+        "include it as a clickable HTML link using <a href=\"URL\" target=\"_blank\">link text</a>. "
+        "For example, if context mentions 'library.ku.ac.ae/ill/' include it as a link. "
+        "NEVER invent or guess URLs that do not appear in the context. "
+        "Only link to URLs that are explicitly present in the context below. "
+        f"If the context does not contain enough information, say so and suggest Ask a Librarian at "
+        f'<a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a> or '
+        f'<a href="mailto:libse@ku.ac.ae">libse@ku.ac.ae</a>.\n\n'
+        f"CONTEXT:\n{context}\n\n"
+        + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
+    )
+    _cfg = _get_runtime_config()
+    _ci = _cfg.get("custom_instructions", "").strip()
+    if _ci:
+        system += "\n\nAdditional instructions: " + _ci
+    try:
+        llm = _get_llm(model, temperature=0.2, max_tokens=380)
+        msgs = [{"role": "system", "content": system}]
+        msgs.extend(_build_history_messages(history))
+        msgs.append({"role": "user", "content": question})
+        response = await llm.ainvoke(msgs)
+        return response.content.strip()
+    except Exception as e:
+        logger.error(f"_rag_answer error: {e}")
+        return (
+            "I'm having trouble generating an answer right now. "
+            f'Please try <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a>.'
+        )
+
+
+def _is_database_recommendation_question(question: str) -> bool:
+    return bool(DATABASE_RECOMMEND_RE.search(question or ""))
+
+
+def _match_db_subject(q: str) -> Optional[str]:
+    checks = [
+        (["quantum computing", "quantum algorithm", "quantum cryptography", "quantum information"], "quantum_computing"),
+        (["robotics", "autonomous system", "intelligent system"], "robotics"),
+        (["artificial intelligence", "machine learning", "deep learning", "nlp", "natural language processing", "neural network", "cybersecurity", "computer science", "software engineering", "algorithm", "data structure"], "computer_science"),
+        (["computer engineering", "embedded system", "computer architecture", "networking", "digital system"], "computer_science"),
+        (["aerospace", "aerodynamic", "propulsion", "aircraft", "aviation", "flight system"], "aerospace"),
+        (["biomedical engineering", "medical device", "biomechanic", "bioinstrument", "tissue engineering", "biomedical imaging"], "biomedical"),
+        (["chemical engineering", "process engineering", "reaction engineering", "separation", "catalysis"], "chemical_engineering"),
+        (["chemistry", "organic chemistry", "analytical chemistry", "inorganic", "chemical", "chemical properties"], "chemistry"),
+        (["civil engineering", "structural engineering", "geotechnical", "transportation engineering", "water resources", "construction"], "civil_engineering"),
+        (["electrical engineering", "circuit", "power system", "signal processing", "control system", "communication system", "electronics"], "electrical_engineering"),
+        (["energy engineering", "renewable energy", "sustainable energy", "clean energy", "energy transition", "solar", "wind power"], "energy"),
+        (["engineering management", "engineering systems", "systems engineering", "operations management", "innovation management"], "engineering_management"),
+        (["mechanical engineering", "thermofluid", "thermodynamics", "fluid mechanics", "manufacturing", "mechatronics"], "mechanical_engineering"),
+        (["nuclear engineering", "reactor", "radiation", "nuclear material", "nuclear safety"], "nuclear"),
+        (["petroleum engineering", "oil and gas", "drilling", "reservoir", "subsurface", "petroleum"], "petroleum"),
+        (["earth science", "geology", "geophysics", "geochemistry", "planetary science", "geoscience"], "earth_science"),
+        (["environment", "sustainability", "climate change", "sustainable development", "conservation", "environmental policy", "ecology"], "environment"),
+        (["materials science", "nanotechnology", "nanomaterial", "biomaterial", "advanced material", "functional material"], "materials"),
+        (["cell biology", "molecular biology", "genetics", "genomics", "biotechnology", "bioinformatics", "microbiology", "virology"], "biology"),
+        (["medicine", "medical", "health science", "clinical", "nursing", "pharmacy", "biomedical literature", "pharmacology", "clinical trial", "systematic review", "evidence-based", "patient care"], "medical"),
+        (["business", "management", "finance", "economics", "accounting", "entrepreneurship", "marketing", "strategy", "leadership", "international relations", "political science", "social science", "humanities", "law", "education", "psychology", "sociology"], "business"),
+        (["physics", "optics", "photonics", "quantum physics", "condensed matter", "theoretical physics", "astrophysics"], "physics"),
+        (["mathematics", "statistics", "data science", "calculus", "algebra", "optimization", "probability", "mathematical model"], "mathematics"),
+        (["impact factor", "journal metrics", "citescore", "jcr", "quartile", "research impact", "scival", "bibliometric"], "metrics"),
+        (["dissertation", "thesis", "doctoral", "master thesis", "repository", "phd thesis"], "theses"),
+    ]
+    for keywords, key in checks:
+        if any(kw in q for kw in keywords):
+            return key
+    return None
+
+
+def _extract_db_topic(question: str) -> str:
+    q = _normalize_whitespace(question or "")
+    patterns = [
+        r"^(best|good|recommended?)\s+databases?\s+for\s+",
+        r"^which\s+databases?\s+(for|should i use for|is best for|are best for)\s+",
+        r"^databases?\s+for\s+",
+        r"^where should i (search|start)\s+(for\s+)?",
+        r"^what (database|databases)\s+(for|should i use for)\s+",
+    ]
+    lower = q.lower()
+    for pat in patterns:
+        m = re.match(pat, lower)
+        if m:
+            q = q[m.end():]
+            break
+    q = re.sub(r"\s+(please|thanks|thank you)\.?$", "", q, flags=re.IGNORECASE)
+    q = _strip_resource_noise(q)
+    return _normalize_whitespace(q).strip(".?") or "this subject"
+
+
+def _database_recommendation_answer(question: str) -> str:
+    q = (question or "").lower()
+    subject = _extract_db_topic(question)
+    topic = _escape(subject)
+    subject_key = _match_db_subject(q)
+    dbs = _DB_SUBJECTS.get(subject_key, _DB_GENERAL) if subject_key else _DB_GENERAL
+    dbs = list(dbs)[:5]
+    answer = f"<strong>Recommended databases for {topic}</strong><br><br>"
+    answer += "Here are the strongest KU-subscribed starting points:<br>"
+    for name, url, why in dbs:
+        answer += f'<br>• <a href="{url}" target="_blank"><strong>{_escape(name)}</strong></a> — {_escape(why)}'
+    if not subject_key:
+        answer += (
+            "<br><br>💡 For subject-specific databases, ask me: "
+            "<em>\"best databases for [your subject]\"</em> — e.g. physics, chemistry, medicine, civil engineering."
+        )
+    answer += (
+        f'<br><br>Browse all 50+ KU databases: '
+        f'<a href="https://library.ku.ac.ae/eresources" target="_blank">library.ku.ac.ae/eresources</a>'
+    )
+    answer += "<br><br>Want me to run a direct search on any of these for a specific topic?"
+    return answer
+
+
+def _fulltext_chain_answer(question: str) -> str:
+    return (
+        "<strong>📄 How to get full text for an article</strong><br><br>"
+        "Follow this chain in order — each step is faster than the next:<br><br>"
+        "<strong>Step 1 — Search KU PRIMO</strong><br>"
+        "Find the article in <a href=\"https://khalifa.primo.exlibrisgroup.com/discovery/search"
+        "?vid=971KUOSTAR_INST:KU\" target=\"_blank\">KU Library Discovery</a>. "
+        "If KU subscribes, you'll see a <em>Full Text Available</em> or <em>Online Access</em> link. "
+        "Click it — it passes through the IDM proxy automatically when on campus or logged in.<br><br>"
+        "<strong>Step 2 — Try LibKey Nomad (browser extension)</strong><br>"
+        "<a href=\"https://libkey.io/libraries/3025/\" target=\"_blank\">LibKey Nomad</a> is a free browser "
+        "extension that detects articles you're viewing and fetches KU's full text automatically. "
+        "Install it once and it works on every publisher site.<br><br>"
+        "<strong>Step 3 — Try the publisher or open access</strong><br>"
+        "Visit the DOI link directly. Many authors post their accepted manuscript on "
+        "<a href=\"https://arxiv.org\" target=\"_blank\">arXiv</a>, "
+        "<a href=\"https://www.researchgate.net\" target=\"_blank\">ResearchGate</a>, or their institutional page. "
+        "<a href=\"https://openalex.org\" target=\"_blank\">OpenAlex</a> also links to many legal open-access PDFs.<br><br>"
+        "<strong>Step 4 — Submit an Interlibrary Loan (ILL) request</strong><br>"
+        "If none of the above work, KU Library can borrow the article from another library — usually within 1–5 working days. "
+        "Submit here: <a href=\"https://library.ku.ac.ae/ill/\" target=\"_blank\">library.ku.ac.ae/ill/</a><br>"
+        "Contact: <strong>Suaad Al Jneibi</strong> · "
+        "<a href=\"mailto:suaad.aljneibi@ku.ac.ae\">suaad.aljneibi@ku.ac.ae</a> · +971 2 312 4278"
+    )
+
+
+def _theses_answer() -> str:
+    return (
+        "<strong>📘 Finding KU theses, dissertations, and institutional research</strong><br><br>"
+        "<strong>Khalifa University Khazna Repository</strong><br>"
+        "Khazna is KU's institutional repository — it holds KU theses, dissertations, "
+        "faculty publications, conference papers, and open-access research outputs.<br>"
+        '🔗 <a href="https://khazna.ku.ac.ae" target="_blank">khazna.ku.ac.ae</a><br><br>'
+        "<strong>ProQuest Dissertations &amp; Theses Global</strong><br>"
+        "KU subscribes to ProQuest D&T Global — the world's largest database of "
+        "theses and dissertations from universities worldwide.<br>"
+        '🔗 <a href="https://khalifa.idm.oclc.org/login?url=https://www.proquest.com/pqdtglobal" target="_blank">'
+        "Access via KU Library</a><br><br>"
+        "<strong>Other sources</strong><br>"
+        '• <a href="https://ethos.bl.uk" target="_blank">EThOS</a> — UK theses (British Library)<br>'
+        '• <a href="https://www.dart-europe.org" target="_blank">DART-Europe</a> — European theses<br>'
+        '• <a href="https://ndltd.org" target="_blank">NDLTD</a> — Global networked digital library of theses<br><br>'
+        "For help with Khazna deposits or ORCID integration, contact: "
+        "<strong>Nikesh Narayanan</strong> · "
+        "<a href=\"mailto:nikesh.narayanan@ku.ac.ae\">nikesh.narayanan@ku.ac.ae</a>"
+    )
+
+
+def _library_follow_up(question: str) -> Tuple[str, List[dict]]:
+    q = (question or "").lower()
+    if _looks_library_hours_question(question):
+        return (
+            "Would you like the library contact details too?",
+            [
+                {"label": "Show library contact details", "question": "Show the library contact details"},
+                {"label": "Open the live library hours page", "question": "Open the live library hours page"},
+            ],
+        )
+    if "study room" in q or "room" in q:
+        return (
+            "Would you like the study-room booking link?",
+            [
+                {"label": "Study-room booking link", "question": "Show the study-room booking link"},
+                {"label": "Library services for both campuses", "question": "Show library services for both campuses"},
+            ],
+        )
+    if any(token in q for token in ["database", "databases", "search", "articles", "research"]):
+        return (
+            "Would you like me to recommend the best KU databases for this topic?",
+            [
+                {"label": "Recommend best KU databases", "question": "Recommend the best KU databases for this topic"},
+                {"label": "How to access databases off campus", "question": "How do I access databases off campus?"},
+            ],
+        )
+    return (
+        "Would you like a related library service or staff contact?",
+        [
+            {"label": "Best staff contact", "question": "Show the best staff contact for this"},
+            {"label": "KU library page for this topic", "question": "Open the KU library page for this topic"},
+        ],
+    )
+
+

src/agentcore/intents_search.py

@@ -1,891 +1,901 @@
-"""search_academic / search_medical machinery: topic extraction, boolean building, URLs, research snapshot, follow-up state."""
-import asyncio
-import html
-import json
-import logging
-import os
-import re
-import time
-import uuid
-from datetime import datetime
-from typing import Any, Dict, List, Literal, Optional, Tuple
-from urllib.parse import quote
-
-import httpx
-from pydantic import BaseModel, ConfigDict, Field
-
-from src.config import get_settings, LIBBEE_VERSION
-
-from src.agentcore.models import ClientStatePayload, SearchContextPayload
-from src.agentcore.scholarly import fetch_evidence_panel
-from src.agentcore.constants import (
-    ALT_TERMS_RE,
-    CURRENT_YEAR,
-    REFINEMENT_STOP_WORDS,
-    REVIEW_ONLY_RE,
-    _BOOLEAN_SYSTEM,
-    _BUILD_SEARCH_PLAN_SYSTEM,
-    _GUARDRAIL,
-    _URL_INSTRUCTION,
-)
-from src.agentcore.utils import (
-    _clean_database_keywords,
-    _escape,
-    _get_llm,
-    _light_strip_retrieval_boilerplate,
-    _normalize_whitespace,
-    _primo_clean_url,
-    _sanitize_boolean_for_primo,
-    _shared_build_primo_boolean_query,
-    _strip_resource_noise,
-    _title_case_topic,
-)
-from src.agentcore.rendering import _ai_tools_footer, _search_trace_block, _tool_urls
-
-logger = logging.getLogger(__name__)
-
-def _extract_topic_regex(question: str) -> str:
-    q = _normalize_whitespace(question)
-    prefixes = [
-        "can u give me a deep analysis of ", "can you give me a deep analysis of ",
-        "give me a deep analysis of ", "deep analysis of ",
-        "give me a summary of ", "give me a summary on ", "give me a summary about ",
-        "give me an overview of ", "give me an overview on ",
-        "give me a brief overview of ", "give me a brief summary of ",
-        "summarize the latest studies in ", "summarize latest studies in ",
-        "summarize the latest research on ", "summarize latest research on ",
-        "summarize recent studies in ", "summarize recent research on ",
-        "latest studies in ", "latest research on ", "recent studies in ", "recent research on ",
-        "summarize ", "summarise ", "summary of ", "summary on ", "summary about ",
-        "overview of ", "overview on ", "brief overview of ", "brief summary of ",
-        "analysis of ", "analyze ", "analyse ", "explain ", "tell me about ",
-        "what is ", "what are ", "describe ", "review of ", "literature review on ",
-        "recent advances in ", "recent developments in ", "state of the art in ",
-        "state of research on ", "research overview of ", "research summary of ",
-        "find peer reviewed articles on ", "find peer reviewed papers on ",
-        "find articles on ", "find papers on ", "find books on ", "find articles about ",
-        "find papers about ", "search for articles on ", "search for papers on ",
-        "i need peer reviewed articles on ", "i need articles on ", "i need papers on ",
-        "i need books on ", "give me articles on ", "show me articles on ",
-        "get me articles on ", "look for articles on ", "articles on ", "papers on ",
-        "books on ", "research on ", "literature on ", "find ", "search for ",
-        "i need ", "give me ", "show me ", "get me ",
+"""search_academic / search_medical machinery: topic extraction, boolean building, URLs, research snapshot, follow-up state."""
+import asyncio
+import html
+import json
+import logging
+import os
+import re
+import time
+import uuid
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from src.config import get_settings, LIBBEE_VERSION
+
+from src.agentcore.models import ClientStatePayload, SearchContextPayload
+from src.agentcore.scholarly import fetch_evidence_panel
+from src.agentcore.constants import (
+    ALT_TERMS_RE,
+    CURRENT_YEAR,
+    REFINEMENT_STOP_WORDS,
+    REVIEW_ONLY_RE,
+    _BOOLEAN_SYSTEM,
+    _BUILD_SEARCH_PLAN_SYSTEM,
+    _GUARDRAIL,
+    _URL_INSTRUCTION,
+)
+from src.agentcore.utils import (
+    _clean_database_keywords,
+    _escape,
+    _get_llm,
+    _light_strip_retrieval_boilerplate,
+    _normalize_whitespace,
+    _primo_clean_url,
+    _sanitize_boolean_for_primo,
+    _shared_build_primo_boolean_query,
+    _strip_resource_noise,
+    _title_case_topic,
+)
+from src.agentcore.rendering import _ai_tools_footer, _search_trace_block, _tool_urls
+
+logger = logging.getLogger(__name__)
+
+def _extract_topic_regex(question: str) -> str:
+    q = _normalize_whitespace(question)
+    prefixes = [
+        "can u give me a deep analysis of ", "can you give me a deep analysis of ",
+        "give me a deep analysis of ", "deep analysis of ",
+        "give me a summary of ", "give me a summary on ", "give me a summary about ",
+        "give me an overview of ", "give me an overview on ",
+        "give me a brief overview of ", "give me a brief summary of ",
+        "summarize the latest studies in ", "summarize latest studies in ",
+        "summarize the latest research on ", "summarize latest research on ",
+        "summarize recent studies in ", "summarize recent research on ",
+        "latest studies in ", "latest research on ", "recent studies in ", "recent research on ",
+        "summarize ", "summarise ", "summary of ", "summary on ", "summary about ",
+        "overview of ", "overview on ", "brief overview of ", "brief summary of ",
+        "analysis of ", "analyze ", "analyse ", "explain ", "tell me about ",
+        "what is ", "what are ", "describe ", "review of ", "literature review on ",
+        "recent advances in ", "recent developments in ", "state of the art in ",
+        "state of research on ", "research overview of ", "research summary of ",
+        "find peer reviewed articles on ", "find peer reviewed papers on ",
+        "find articles on ", "find papers on ", "find books on ", "find articles about ",
+        "find papers about ", "search for articles on ", "search for papers on ",
+        "i need peer reviewed articles on ", "i need articles on ", "i need papers on ",
+        "i need books on ", "give me articles on ", "show me articles on ",
+        "get me articles on ", "look for articles on ", "articles on ", "papers on ",
+        "books on ", "research on ", "literature on ", "find ", "search for ",
+        "i need ", "give me ", "show me ", "get me ",
+    ]
+    lower = q.lower()
+    for prefix in prefixes:
+        if lower.startswith(prefix):
+            q = q[len(prefix):]
+            break
+    q = re.sub(r"\s+(please|thanks|thank you)\.?$", "", q, flags=re.IGNORECASE)
+    q = re.sub(r"\b(peer[- ]reviewed|open access|last \d+ years?|past \d+ years?)\b", "", q, flags=re.IGNORECASE)
+    q = _strip_resource_noise(q)
+    return _normalize_whitespace(q).strip(".?")
+
+
+async def _extract_topic(question: str, model: str) -> str:
+    settings = get_settings()
+    if not settings.openai_api_key and not settings.anthropic_api_key:
+        return _extract_topic_regex(question)
+    try:
+        llm = _get_llm(model, temperature=0, max_tokens=32)
+        response = await llm.ainvoke([
+            {"role": "system", "content": (
+                "Extract only the core research topic from the user's question. "
+                "Return 2-7 keywords ONLY — no punctuation, no sentence, no explanation. "
+                "CRITICAL: do NOT include words like articles, papers, books, journals, "
+                "peer-reviewed, open-access, studies, or research in your output. "
+                "Those are filters, not topic words. Return ONLY the subject matter.\n"
+                "Examples:\n"
+                "'find articles on indian politics' → indian politics\n"
+                "'peer reviewed papers on climate change 2020' → climate change\n"
+                "'books on structural engineering UAE' → structural engineering UAE\n"
+                "'give me a summary of quantum physics advances' → quantum physics advances\n"
+                "'i need peer reviewed research on machine learning healthcare' → machine learning healthcare"
+            )},
+            {"role": "user", "content": question},
+        ])
+        topic = response.content.strip().strip('"').strip("'").strip(".")
+        topic = _strip_resource_noise(topic)
+        topic = _normalize_whitespace(topic).strip(".?")
+        if topic and len(topic) > 2:
+            return topic
+    except Exception as e:
+        logger.warning(f"Topic extraction failed: {e}")
+    return _extract_topic_regex(question)
+
+
+async def _llm_build_boolean_query(topic: str, model: str) -> str:
+    settings = get_settings()
+    if not settings.openai_api_key and not settings.anthropic_api_key:
+        return _shared_build_primo_boolean_query(topic)
+    try:
+        llm = _get_llm(model, temperature=0, max_tokens=120)
+        response = await llm.ainvoke([
+            {"role": "system", "content": _BOOLEAN_SYSTEM},
+            {"role": "user", "content": f"Input: {topic.strip()}"},
+        ])
+        result = response.content.strip()
+        if not result or len(result) > 500:
+            raise ValueError("Bad LLM boolean output")
+        result = re.sub(r"^```[a-z]*\n?", "", result).rstrip("`").strip()
+        if '"' not in result and ' AND ' not in result and ' OR ' not in result:
+            result = f'"{result}"'
+        logger.info(f"LLM boolean: {result!r} ← topic: {topic!r}")
+        return result
+    except Exception as e:
+        logger.warning(f"LLM boolean query failed: {e} — using regex fallback")
+        return _shared_build_primo_boolean_query(topic)
+
+
+def _derive_resource_type(question: str, existing: Optional[str] = None) -> str:
+    q = (question or "").lower()
+    if any(token in q for token in ["book", "books", "ebook", "ebooks"]):
+        return "books"
+    if any(token in q for token in ["article", "articles", "paper", "papers", "study", "studies", "journal", "journals"]):
+        return "articles"
+    return existing or "articles"
+
+
+def _parse_year_filters(question: str) -> Tuple[Optional[str], Optional[str]]:
+    q = (question or "").lower()
+    match = re.search(r"\b(last|past)\s+(\d{1,2})\s+years?\b", q)
+    if match:
+        years = int(match.group(2))
+        return str(CURRENT_YEAR - years + 1), str(CURRENT_YEAR)
+    between = re.search(r"\b(?:from|between)\s+(20\d{2}|19\d{2})\s+(?:to|and|-)\s+(20\d{2}|19\d{2})\b", q)
+    if between:
+        return between.group(1), between.group(2)
+    years = re.findall(r"\b(19\d{2}|20\d{2})\b", q)
+    if len(years) >= 2:
+        return min(years), max(years)
+    if len(years) == 1 and any(word in q for word in ["since", "from", "after"]):
+        return years[0], str(CURRENT_YEAR)
+    return None, None
+
+
+def _compose_ai_tool_query(question: str, context: SearchContextPayload, is_follow_up: bool) -> str:
+    topic = context.display_topic or context.topic
+    topic = _title_case_topic(topic)
+    scope = context.resource_type
+    filters = []
+    if context.peer_reviewed:
+        filters.append("peer-reviewed")
+    if context.open_access:
+        filters.append("open-access")
+    if context.year_from and context.year_to:
+        filters.append(f"published between {context.year_from} and {context.year_to}")
+    elif context.year_from:
+        filters.append(f"published from {context.year_from} onward")
+    if is_follow_up:
+        if scope == "books":
+            base = f"Find books on {topic}"
+        elif scope == "both":
+            base = f"Find articles and books on {topic}"
+        else:
+            base = f"Find research articles on {topic}"
+    else:
+        base = _normalize_whitespace(question).strip(".?")
+        if len(base.split()) < 4:
+            base = f"Find research on {topic}"
+    if filters:
+        return f"{base} with {', '.join(filters)}."
+    return base.rstrip(".") + "."
+
+
+def _context_to_dict(context: SearchContextPayload) -> dict:
+    return context.model_dump()
+
+
+async def _validate_topic(topic: str, model: str) -> Tuple[bool, str]:
+    settings = get_settings()
+    if not settings.openai_api_key and not settings.anthropic_api_key:
+        return True, topic
+    try:
+        llm = _get_llm(model, temperature=0, max_tokens=40)
+        response = await llm.ainvoke([
+            {"role": "system", "content": (
+                "You are a topic validator for an academic library search system. "
+                "Given a word or phrase, decide if it is a recognisable research topic, "
+                "subject area, acronym, proper noun, or concept — even if misspelled.\n\n"
+                "Rules:\n"
+                "- If recognisable or a fixable typo: return JSON {\"valid\": true, \"corrected\": \"<corrected spelling>\"}\n"
+                "- If gibberish, random characters, or completely unrecognisable: return JSON {\"valid\": false, \"corrected\": \"\"}\n"
+                "- Acronyms like NLP, ML, AI, CRISPR, IoT are always valid.\n"
+                "- Proper nouns (country names, people, organisations) are always valid.\n"
+                "- Misspellings like 'machne lernig' → corrected: 'machine learning' → valid: true\n"
+                "- Random strings like 'sdfmdnoc', 'xyzabc123', 'qwerty' → valid: false\n"
+                "Return ONLY valid JSON. No explanation."
+            )},
+            {"role": "user", "content": f"Topic: {topic}"},
+        ])
+        raw = response.content.strip()
+        if raw.startswith("```"):
+            raw = raw.split("\n", 1)[1].rsplit("```", 1)[0].strip()
+        s, e = raw.find("{"), raw.rfind("}")
+        if s != -1 and e > s:
+            result = json.loads(raw[s:e + 1])
+            is_valid = bool(result.get("valid", True))
+            corrected = str(result.get("corrected") or topic).strip()
+            return is_valid, corrected
+        return True, topic
+    except Exception as exc:
+        logger.warning(f"_validate_topic failed: {exc} — failing open")
+        return True, topic
+
+
+async def _build_search_plan(question: str, model: str) -> dict:
+    settings = get_settings()
+    raw_query = _normalize_whitespace(question or "")
+    light_query = _light_strip_retrieval_boilerplate(raw_query) or raw_query
+    _stripped = light_query.strip()
+    _is_pure_number  = bool(re.fullmatch(r"[\d\s\.\,\-\/]+", _stripped))
+    _is_too_short    = len(_stripped) < 2
+    _is_single_char  = bool(re.fullmatch(r"[a-zA-Z0-9]", _stripped))
+    _content_words   = [w for w in _stripped.split() if len(w) > 1 and not re.fullmatch(r"[\d\.\,\-]+", w)]
+    _no_content      = len(_content_words) == 0 and len(_stripped) > 0
+    if _is_pure_number or _is_too_short or _is_single_char or _no_content:
+        _display = _stripped or raw_query
+        return {
+            "corrected": raw_query, "natural": light_query, "boolean": "",
+            "database_query": "", "year_from": "", "year_to": "",
+            "peer_reviewed": False, "open_access": False,
+            "clarification_needed": True,
+            "clarification_message": (
+                f"I want to make sure I search for the right thing. "
+                f"Could you clarify what <strong>{_escape(_display)}</strong> refers to? "
+                f"For example, is it a course code, a specific topic name, a year, "
+                f"or something else? The more detail you provide, "
+                f"the better I can build your search."
+            ),
+        }
+    if settings.openai_api_key or settings.anthropic_api_key:
+        _valid, _corrected_topic = await _validate_topic(_stripped, model)
+        if not _valid:
+            return {
+                "corrected": raw_query, "natural": light_query, "boolean": "",
+                "database_query": "", "year_from": "", "year_to": "",
+                "peer_reviewed": False, "open_access": False,
+                "clarification_needed": True,
+                "clarification_message": (
+                    f"I couldn't recognise <strong>{_escape(_stripped)}</strong> as a research topic. "
+                    f"Could you check the spelling, or describe what you're looking for in more detail? "
+                    f"For example: <em>\"find research on machine learning\"</em> or "
+                    f"<em>\"articles on renewable energy in UAE\"</em>."
+                ),
+            }
+        if _corrected_topic and _corrected_topic.lower() != _stripped.lower():
+            logger.info(f"_validate_topic corrected: {_stripped!r} → {_corrected_topic!r}")
+            light_query = _corrected_topic
+    if settings.openai_api_key or settings.anthropic_api_key:
+        try:
+            llm = _get_llm(model, temperature=0, max_tokens=300)
+            response = await llm.ainvoke([
+                {"role": "system", "content": _BUILD_SEARCH_PLAN_SYSTEM},
+                {"role": "user", "content": f'Query: "{light_query}"'},
+            ])
+            raw = response.content.strip()
+            if raw.startswith("```"):
+                raw = raw.split("\n", 1)[1].rsplit("```", 1)[0].strip()
+            s, e = raw.find("{"), raw.rfind("}")
+            if s != -1 and e > s:
+                result = json.loads(raw[s:e + 1])
+            else:
+                raise ValueError("No JSON found in response")
+            corrected = (result.get("corrected") or raw_query).strip() or raw_query
+            natural   = (result.get("natural") or corrected).strip() or corrected
+            boolean   = (result.get("boolean") or "").strip()
+            has_ops   = bool(re.search(r"\b(AND|OR)\b", boolean)) if boolean else False
+            has_parens = "(" in boolean if boolean else False
+            if not has_ops or not has_parens:
+                boolean = _shared_build_primo_boolean_query(corrected)
+            boolean = _sanitize_boolean_for_primo(boolean)
+            year_from = str(result.get("year_from") or "").strip()
+            year_to   = str(result.get("year_to")   or "").strip()
+            if not year_from and not year_to:
+                yf, yt = _parse_year_filters(raw_query)
+                year_from = yf or ""
+                year_to   = yt or ""
+            return {
+                "corrected":      corrected,
+                "natural":        natural,
+                "boolean":        boolean,
+                "database_query": _clean_database_keywords(boolean),
+                "year_from":      year_from,
+                "year_to":        year_to,
+                "peer_reviewed":  bool(result.get("peer_reviewed", False)),
+                "open_access":    bool(result.get("open_access", False)),
+            }
+        except Exception as e:
+            logger.warning(f"_build_search_plan LLM failed: {e} — using regex fallback")
+    boolean = _shared_build_primo_boolean_query(light_query)
+    yf, yt = _parse_year_filters(raw_query)
+    pr = bool(re.search(r"\bpeer[- ]reviewed\b", raw_query, re.IGNORECASE))
+    oa = bool(re.search(r"\bopen[- ]access\b", raw_query, re.IGNORECASE))
+    return {
+        "corrected":      raw_query,
+        "natural":        light_query,
+        "boolean":        boolean,
+        "database_query": _clean_database_keywords(boolean),
+        "year_from":      yf or "",
+        "year_to":        yt or "",
+        "peer_reviewed":  pr,
+        "open_access":    oa,
+    }
+
+
+async def _prepare_queries(question: str, context: SearchContextPayload, model: str, is_follow_up: bool) -> SearchContextPayload:
+    topic = _strip_resource_noise(context.display_topic or context.topic) or context.topic
+    q = question if not is_follow_up else f"Find {context.resource_type} on {topic}"
+    plan = await _build_search_plan(q, model)
+    if plan.get("clarification_needed"):
+        context.clarification_needed = True
+        context.clarification_message = plan.get("clarification_message", "")
+        return context
+    context.ai_tool_query        = plan["natural"]
+    context.primo_boolean_query  = plan["boolean"]
+    if not context.year_from and plan.get("year_from"):
+        context.year_from = plan["year_from"]
+    if not context.year_to and plan.get("year_to"):
+        context.year_to = plan["year_to"]
+    if not context.peer_reviewed and plan.get("peer_reviewed"):
+        context.peer_reviewed = True
+    if not context.open_access and plan.get("open_access"):
+        context.open_access = True
+    return context
+
+
+async def _topic_intro(topic: str, model: str) -> str:
+    """LLM #5 — 3-sentence topic intro. v3.8.1: appends _GUARDRAIL + _URL_INSTRUCTION."""
+    settings = get_settings()
+    if not settings.openai_api_key and not settings.anthropic_api_key:
+        return ""
+    try:
+        llm = _get_llm(model, temperature=0.2, max_tokens=180)
+        response = await llm.ainvoke([
+            {"role": "system", "content": (
+                "You are LibBee, the Khalifa University Library AI Assistant. "
+                "Write exactly 3 clear, factual sentences introducing the given research topic "
+                "for a university student or researcher. "
+                "Cover: what the topic is, why it matters, and one key area of current research interest. "
+                "Use HTML <br> for line breaks only if needed. No markdown, no bullet points, no headings. "
+                "Be concise and informative. "
+                + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
+            )},
+            {"role": "user", "content": f"Research topic: {topic}"},
+        ])
+        intro = response.content.strip()
+        return intro if intro else ""
+    except Exception as e:
+        logger.warning(f"_topic_intro failed: {e}")
+        return ""
+
+
+
+def _extractive_snapshot_from_papers(topic: str, papers: List[dict]) -> str:
+    if not papers:
+        return ""
+    statements: List[str] = []
+    for paper in papers[:4]:
+        sentences = re.split(r"(?<=[.!?])\s+", paper.get("abstract", ""))
+        lead = sentences[0].strip() if sentences else ""
+        if not lead:
+            continue
+        citation = (
+            f'<a href="{paper["link"]}" target="_blank" '
+            f'style="color:#1e40af;font-weight:600;text-decoration:none">'
+            f'[{_escape(paper["citation_key"])}]</a>'
+        )
+        statements.append(f"{_escape(lead)} {citation}")
+    if not statements:
+        return f"Recent literature on <strong>{_escape(topic)}</strong> is available in the cited papers below."
+    intro = f"Recent literature on <strong>{_escape(topic)}</strong>:<br><br>"
+    return intro + "<br><br>".join(statements[:4])
+
+
+def _database_guidance_for_topic(context: SearchContextPayload) -> str:
+    topic = _escape(context.display_topic or context.topic)
+    urls = _tool_urls(context)
+    ai_tools = (
+        f'<a href="{urls["leapspace"]}" target="_blank" style="color:#9a3412;font-weight:700;text-decoration:none">LeapSpace</a> · '
+        f'<a href="{urls["scopus_ai"]}" target="_blank" style="color:#1e40af;font-weight:700;text-decoration:none">Scopus AI</a> · '
+        f'<a href="{urls["ebsco_ai"]}" target="_blank" style="color:#9d174d;font-weight:700;text-decoration:none">EBSCO AI</a> · '
+        f'<a href="{urls["primo_ai"]}" target="_blank" style="color:#5b21b6;font-weight:700;text-decoration:none">PRIMO AI Assistant</a> · '
+        f'<a href="{urls["consensus"]}" target="_blank" style="color:#86198f;font-weight:700;text-decoration:none">Consensus</a>'
+    )
+    more_results = f'<a href="{urls["primo_discovery"]}" target="_blank" style="color:#5b21b6;font-weight:700;text-decoration:none">PRIMO Library Discovery</a>'
+    if context.intent == "search_medical" and urls.get("pubmed"):
+        more_results += f' · <a href="{urls["pubmed"]}" target="_blank" style="color:#065f46;font-weight:700;text-decoration:none">PubMed</a>'
+        return (
+            f"For deeper work on <strong>{topic}</strong>, continue with these AI research tools: {ai_tools}. "
+            f"For more results, use {more_results}. Medical topics are strongest in PubMed, Embase, and CINAHL."
+        )
+    return (
+        f"For deeper work on <strong>{topic}</strong>, continue with these AI research tools: {ai_tools}. "
+        f"For more results, use {more_results}."
+    )
+
+
+async def _search_strategy_answer(question: str, model: str) -> Tuple[str, dict]:
+    plan = await _build_search_plan(question, model)
+    topic = _escape(_light_strip_retrieval_boilerplate(question) or question)
+    boolean = _escape(plan.get("boolean", ""))
+    natural = _escape(plan.get("natural", ""))
+    explanation = (
+        f"<strong>🔍 Search strategy for: {topic}</strong><br><br>"
+        f"<strong>1. Identify your key concepts</strong><br>"
+        f"Break the topic into 2–3 core concepts. For your question, I identified these concepts "
+        f"and suggested synonyms for each using OR, then joined concepts with AND:<br><br>"
+        f'<code style="display:block;padding:8px 12px;background:#1a1a2e;color:#C8A951;'
+        f'border-radius:8px;font-size:.82rem;word-break:break-all">{boolean}</code><br>'
+        f"<strong>Why AND and OR?</strong> AND narrows — both concepts must appear. "
+        f"OR broadens — any synonym counts. Quoting phrases like "
+        f"<code>\"machine learning\"</code> keeps them together as an exact phrase.<br><br>"
+        f"<strong>2. Apply filters</strong><br>"
+        f"Use database facets to limit by: peer-reviewed, date range, document type (article / review / book), "
+        f"language, or open access. In PRIMO, these appear in the left sidebar after you search.<br><br>"
+        f"<strong>3. Natural language query for AI tools</strong><br>"
+        f"For AI-powered tools (LeapSpace, Scopus AI, Consensus), use a conversational query:<br>"
+        f'<em style="color:var(--color-text-secondary)">{natural}</em><br><br>'
+        f"<strong>4. Iterate</strong><br>"
+        f"Too many results → add more AND terms or apply filters. "
+        f"Too few → remove an AND group or use broader synonyms. "
+        f"You can ask me to refine: <em>\"narrow to peer-reviewed only\"</em>, "
+        f"<em>\"limit to last 5 years\"</em>, or <em>\"suggest alternative keywords\"</em>."
+    )
+    return explanation, plan
+
+
+async def _alternative_terms_answer(question: str, context: Optional[SearchContextPayload], model: str) -> str:
+    topic = (context.display_topic or context.topic) if context else question
+    settings = get_settings()
+    if not settings.openai_api_key and not settings.anthropic_api_key:
+        return (
+            f"<strong>Alternative search terms for: {_escape(topic)}</strong><br><br>"
+            "Try combining these broader, narrower, and related terms:<br>"
+            "• Use broader terms if too few results<br>"
+            "• Use narrower/specific terms if too many results<br>"
+            "• Try acronyms and full forms (e.g. AI / Artificial Intelligence)<br>"
+            "• Include British and American spellings (e.g. organisation/organization)"
+        )
+    try:
+        llm = _get_llm(model, temperature=0.4, max_tokens=300)
+        response = await llm.ainvoke([
+            {"role": "system", "content": (
+                "You are an academic librarian. Given a research topic, generate a structured list of alternative "
+                "search terms. Group them as: Broader terms, Narrower/specific terms, Related concepts, Acronyms/abbreviations. "
+                "Format as HTML using <strong> for group labels and <br> for line breaks. "
+                "Keep it concise — 3-4 terms per group maximum. No bullet points, use • instead."
+            )},
+            {"role": "user", "content": f"Research topic: {topic}"},
+        ])
+        terms = response.content.strip()
+        return (
+            f"<strong>💡 Alternative search terms for: {_escape(topic)}</strong><br><br>"
+            f"{terms}<br><br>"
+            f"<strong>Tip:</strong> In PRIMO or databases, use OR between synonyms within a concept group, "
+            f"and AND between different concept groups. Ask me to run a new search with any of these."
+        )
+    except Exception as e:
+        logger.warning(f"_alternative_terms_answer failed: {e}")
+        return f"<strong>Alternative terms for {_escape(topic)}</strong><br><br>Try synonyms, acronyms, broader/narrower terms, and related concepts in your search."
+
+
+def _citation_chain_answer() -> str:
+    return (
+        "<strong>🔗 How to trace citations forward and backward from a paper</strong><br><br>"
+        "<strong>Backward citation (who does this paper cite?)</strong><br>"
+        "Read the paper's reference list — every source it cites is a potential lead. "
+        "This gives you foundational and seminal works on the topic.<br><br>"
+        "<strong>Forward citation (who has cited this paper since publication?)</strong><br>"
+        "Use these tools — paste in the DOI or title:<br>"
+        '• <a href="https://www-scopus-com.khalifa.idm.oclc.org/pages/ai" target="_blank"><strong>Scopus</strong></a> '
+        '— search the article, then click "Cited by N documents"<br>'
+        '• <a href="https://www.webofscience.com" target="_blank"><strong>Web of Science</strong></a> '
+        '— search the article, click "Times Cited"<br>'
+        '• <a href="https://www.semanticscholar.org" target="_blank"><strong>Semantic Scholar</strong></a> '
+        '— free, excellent for CS and engineering, shows "Citations" tab<br>'
+        '• <a href="https://openalex.org" target="_blank"><strong>OpenAlex</strong></a> '
+        '— fully open, API-accessible citation graph<br><br>'
+        "<strong>Lateral search (similar papers)</strong><br>"
+        "In PRIMO, use <em>\"Find Similar\"</em>. In Semantic Scholar, use <em>\"Recommended Papers\"</em>. "
+        "In Scopus, use <em>\"Related Documents\"</em>.<br><br>"
+        "<strong>Tip:</strong> Start with one highly cited foundational paper, trace forward to find the newest "
+        "work, and backward to understand the theoretical roots."
+    )
+
+
+def _predatory_eval_answer() -> str:
+    return (
+        "<strong>✅ How to tell if an article or journal is peer-reviewed, scholarly, or predatory</strong><br><br>"
+        "<strong>Is it peer-reviewed?</strong><br>"
+        "• Check the journal's website for a peer-review statement or editorial process description<br>"
+        "• In PRIMO, tick the <em>Peer-reviewed</em> filter in the left sidebar<br>"
+        "• Check if the journal is indexed in "
+        '<a href="https://www-scopus-com.khalifa.idm.oclc.org" target="_blank">Scopus</a> or '
+        '<a href="https://www.webofscience.com" target="_blank">Web of Science</a> — '
+        "indexed = generally peer-reviewed<br><br>"
+        "<strong>Is it a legitimate journal?</strong><br>"
+        "• <a href=\"https://doaj.org\" target=\"_blank\"><strong>DOAJ</strong></a> "
+        "— Directory of Open Access Journals (vetted, legitimate OA)<br>"
+        "• <a href=\"https://mjl.clarivate.com\" target=\"_blank\"><strong>Web of Science Master Journal List</strong></a><br>"
+        "• <a href=\"https://www.scopus.com/sources\" target=\"_blank\"><strong>Scopus Source List</strong></a><br>"
+        "• Think · Check · Submit: <a href=\"https://thinkchecksubmit.org\" target=\"_blank\">thinkchecksubmit.org</a> "
+        "— a checklist to assess any journal<br><br>"
+        "<strong>Warning signs of predatory journals</strong><br>"
+        "• Unsolicited email invitation to submit<br>"
+        "• No clear peer-review process or very fast acceptance (days)<br>"
+        "• High article processing charges (APCs) with no clear metrics<br>"
+        "• Not indexed in Scopus or Web of Science<br>"
+        "• Generic or misleading journal name ('International Journal of...')<br><br>"
+        "<strong>Need help checking a specific journal?</strong> Ask our E-Resources Librarian: "
+        "<strong>Rani Anand</strong> · <a href=\"mailto:rani.anand@ku.ac.ae\">rani.anand@ku.ac.ae</a>"
+    )
+
+
+def _highly_cited_note(topic_escaped: str) -> str:
+    return (
+        f"<br><br><strong>📊 Finding highly cited papers on {topic_escaped}</strong><br>"
+        "PRIMO doesn't sort by citation count, but these tools do:<br>"
+        '• <a href="https://www-scopus-com.khalifa.idm.oclc.org" target="_blank"><strong>Scopus</strong></a> '
+        '— search your topic → Sort by <em>Cited by (highest)</em><br>'
+        '• <a href="https://www.webofscience.com" target="_blank"><strong>Web of Science</strong></a> '
+        '— search → Sort by <em>Times Cited</em><br>'
+        '• <a href="https://www.semanticscholar.org" target="_blank"><strong>Semantic Scholar</strong></a> '
+        '— free, sort by <em>Citation Count</em><br>'
+        '• <a href="https://scholar.google.com" target="_blank"><strong>Google Scholar</strong></a> '
+        '— sort by <em>Cited by</em> (broader but includes grey literature)'
+    )
+
+
+async def _research_snapshot(context: SearchContextPayload, model: str) -> Tuple[str, List[dict], List[dict]]:
+    """Research snapshot = prepared platform links + a live open-evidence panel.
+
+    The evidence panel queries OpenAlex first (Semantic Scholar as fallback),
+    then enriches results with legal open-access links via Unpaywall and fills
+    metadata gaps via Crossref. Every external call is best-effort: if the open
+    indexes are unreachable the handler degrades to the prepared-links block
+    (the entire pre-3.8 behaviour), so the user always gets an answer.
+    """
+    topic = context.topic
+    primo_url = _primo_clean_url(context)
+    answer = _search_trace_block(f"Research on {topic}", context)
+    answer += (
+        f"<strong>📚 Research starting points: {_escape(topic)}</strong><br><br>"
+        "Your query has been prepared and pre-loaded across multiple platforms. "
+        "Click any platform below to search instantly, or use the boolean search tip "
+        "to search directly in any KU database."
+        f'<br><br><a href="{primo_url}" target="_blank" style="color:#003366;font-weight:700">'
+        f'Search PRIMO for: {_escape(topic)} →</a>'
+    )
+
+    # Shared open-evidence panel (see scholarly.fetch_evidence_panel)
+    papers, panel_html = await fetch_evidence_panel(topic, context=context)
+    answer += panel_html
+
+    answer += _ai_tools_footer(context)
+    sources = [
+        {"title": paper.get("title", ""), "url": paper.get("link", ""),
+         "doi": paper.get("doi", ""), "provider": paper.get("_source", "")}
+        for paper in papers
     ]
-    lower = q.lower()
-    for prefix in prefixes:
-        if lower.startswith(prefix):
-            q = q[len(prefix):]
-            break
-    q = re.sub(r"\s+(please|thanks|thank you)\.?$", "", q, flags=re.IGNORECASE)
-    q = re.sub(r"\b(peer[- ]reviewed|open access|last \d+ years?|past \d+ years?)\b", "", q, flags=re.IGNORECASE)
-    q = _strip_resource_noise(q)
-    return _normalize_whitespace(q).strip(".?")
-
-
-async def _extract_topic(question: str, model: str) -> str:
-    settings = get_settings()
-    if not settings.openai_api_key and not settings.anthropic_api_key:
-        return _extract_topic_regex(question)
-    try:
-        llm = _get_llm(model, temperature=0, max_tokens=32)
-        response = await llm.ainvoke([
-            {"role": "system", "content": (
-                "Extract only the core research topic from the user's question. "
-                "Return 2-7 keywords ONLY — no punctuation, no sentence, no explanation. "
-                "CRITICAL: do NOT include words like articles, papers, books, journals, "
-                "peer-reviewed, open-access, studies, or research in your output. "
-                "Those are filters, not topic words. Return ONLY the subject matter.\n"
-                "Examples:\n"
-                "'find articles on indian politics' → indian politics\n"
-                "'peer reviewed papers on climate change 2020' → climate change\n"
-                "'books on structural engineering UAE' → structural engineering UAE\n"
-                "'give me a summary of quantum physics advances' → quantum physics advances\n"
-                "'i need peer reviewed research on machine learning healthcare' → machine learning healthcare"
-            )},
-            {"role": "user", "content": question},
-        ])
-        topic = response.content.strip().strip('"').strip("'").strip(".")
-        topic = _strip_resource_noise(topic)
-        topic = _normalize_whitespace(topic).strip(".?")
-        if topic and len(topic) > 2:
-            return topic
-    except Exception as e:
-        logger.warning(f"Topic extraction failed: {e}")
-    return _extract_topic_regex(question)
-
-
-async def _llm_build_boolean_query(topic: str, model: str) -> str:
-    settings = get_settings()
-    if not settings.openai_api_key and not settings.anthropic_api_key:
-        return _shared_build_primo_boolean_query(topic)
-    try:
-        llm = _get_llm(model, temperature=0, max_tokens=120)
-        response = await llm.ainvoke([
-            {"role": "system", "content": _BOOLEAN_SYSTEM},
-            {"role": "user", "content": f"Input: {topic.strip()}"},
-        ])
-        result = response.content.strip()
-        if not result or len(result) > 500:
-            raise ValueError("Bad LLM boolean output")
-        result = re.sub(r"^```[a-z]*\n?", "", result).rstrip("`").strip()
-        if '"' not in result and ' AND ' not in result and ' OR ' not in result:
-            result = f'"{result}"'
-        logger.info(f"LLM boolean: {result!r} ← topic: {topic!r}")
-        return result
-    except Exception as e:
-        logger.warning(f"LLM boolean query failed: {e} — using regex fallback")
-        return _shared_build_primo_boolean_query(topic)
-
-
-def _derive_resource_type(question: str, existing: Optional[str] = None) -> str:
-    q = (question or "").lower()
-    if any(token in q for token in ["book", "books", "ebook", "ebooks"]):
-        return "books"
-    if any(token in q for token in ["article", "articles", "paper", "papers", "study", "studies", "journal", "journals"]):
-        return "articles"
-    return existing or "articles"
-
-
-def _parse_year_filters(question: str) -> Tuple[Optional[str], Optional[str]]:
-    q = (question or "").lower()
-    match = re.search(r"\b(last|past)\s+(\d{1,2})\s+years?\b", q)
-    if match:
-        years = int(match.group(2))
-        return str(CURRENT_YEAR - years + 1), str(CURRENT_YEAR)
-    between = re.search(r"\b(?:from|between)\s+(20\d{2}|19\d{2})\s+(?:to|and|-)\s+(20\d{2}|19\d{2})\b", q)
-    if between:
-        return between.group(1), between.group(2)
-    years = re.findall(r"\b(19\d{2}|20\d{2})\b", q)
-    if len(years) >= 2:
-        return min(years), max(years)
-    if len(years) == 1 and any(word in q for word in ["since", "from", "after"]):
-        return years[0], str(CURRENT_YEAR)
-    return None, None
-
-
-def _compose_ai_tool_query(question: str, context: SearchContextPayload, is_follow_up: bool) -> str:
-    topic = context.display_topic or context.topic
-    topic = _title_case_topic(topic)
-    scope = context.resource_type
-    filters = []
-    if context.peer_reviewed:
-        filters.append("peer-reviewed")
-    if context.open_access:
-        filters.append("open-access")
-    if context.year_from and context.year_to:
-        filters.append(f"published between {context.year_from} and {context.year_to}")
-    elif context.year_from:
-        filters.append(f"published from {context.year_from} onward")
-    if is_follow_up:
-        if scope == "books":
-            base = f"Find books on {topic}"
-        elif scope == "both":
-            base = f"Find articles and books on {topic}"
-        else:
-            base = f"Find research articles on {topic}"
+    return answer, papers, sources
+
+
+def _filters_summary(context: SearchContextPayload) -> str:
+    filters: List[str] = []
+    if context.peer_reviewed:
+        filters.append("peer reviewed only")
+    if context.open_access:
+        filters.append("open access")
+    if context.year_from and context.year_to:
+        filters.append(f"{context.year_from}–{context.year_to}")
+    elif context.year_from:
+        filters.append(f"from {context.year_from}")
+    if context.resource_type == "books":
+        filters.append("books")
+    elif context.resource_type == "articles":
+        filters.append("articles")
+    elif context.resource_type == "both":
+        filters.append("articles and books")
+    return ", ".join(filters)
+
+
+def _question_has_new_topic(question: str, base_topic: str) -> bool:
+    q = (question or "").lower()
+    cleaned = re.sub(
+        r"\b(peer[- ]reviewed|open access|last \d+ years?|past \d+ years?|books? instead|articles? instead|"
+        r"summari[sz]e( this topic)?|overview|brief|use pubmed|search pubmed|search primo|best databases?|deep research tools?)\b",
+        " ", q,
+    )
+    tokens = [t for t in re.findall(r"[a-z0-9]+", cleaned) if t not in REFINEMENT_STOP_WORDS and len(t) > 2]
+    if len(tokens) < 3:
+        return False
+    base_tokens = {t for t in re.findall(r"[a-z0-9]+", (base_topic or "").lower()) if t not in REFINEMENT_STOP_WORDS}
+    overlap = sum(1 for t in tokens if t in base_tokens)
+    return overlap <= max(1, min(2, len(base_tokens)))
+
+
+def _parse_refinement_action(question: str) -> Optional[str]:
+    q = (question or "").lower().strip()
+    if re.search(r"\b(peer[- ]reviewed|peer reviewed only|peer reviewd|peer review only)\b", q):
+        return "peer_reviewed_only"
+    if re.search(r"\b(open access|oa only|only open access)\b", q):
+        return "open_access_only"
+    if re.search(r"\b(last|past)\s+5\s+years?\b", q):
+        return "last_5_years"
+    if re.search(r"\b(last|past)\s+10\s+years?\b|\bpast decade\b", q):
+        return "last_10_years"
+    m = re.search(r"\b(last|past)\s+(\d{1,2})\s+years?\b", q)
+    if m:
+        return f"last_{m.group(2)}_years"
+    if re.search(r"\bbooks? instead\b|\bbooks? only\b|\bfind books?\b|\bshow books?\b", q):
+        return "books_only"
+    if re.search(r"\barticles? instead\b|\barticles? only\b|\bpapers? only\b", q):
+        return "articles_only"
+    if re.search(r"\b(?:both|articles and books|books and articles)\b", q):
+        return "both_resources"
+    if REVIEW_ONLY_RE.search(q):
+        return "review_articles_only"
+    if ALT_TERMS_RE.search(q):
+        return "alt_terms"
+    if re.search(r"\b(summar(y|ize|ise)|overview|brief|what does the literature say|research snapshot)\b", q):
+        _STOP = {
+            'a','an','the','of','on','in','for','to','with','by','from','at','is','are',
+            'was','were','be','been','have','has','had','do','does','did','will','would',
+            'could','should','may','its','this','that','these','those','about','me','my',
+            'give','show','tell','please','can','you','i','need','want','get','find',
+            'research','summary','overview','summarize','summarise','brief','literature',
+        }
+        content_words = [t for t in re.findall(r'[a-z0-9]+', q)
+                         if t not in _STOP and (len(t) > 2 or t in {'ai','ml','nlp','cv','rl','dl','uae','ku','iot'})]
+        if content_words:
+            return None
+        return "summarize_topic"
+    if re.search(r"\bpubmed\b", q):
+        return "search_pubmed"
+    if re.search(r"\bprimo\b", q):
+        return "search_primo"
+    if re.search(r"\b(best database|best databases|which database|which databases)\b", q):
+        return "best_databases"
+    if re.search(r"\b(deep research|deep dive|full literature review|exhaustive)\b", q):
+        return "deep_research_tools"
+    return None
+
+
+def _resolve_base_context(client_state: Optional[ClientStatePayload]) -> Optional[SearchContextPayload]:
+    if not client_state or not client_state.recent_search_contexts:
+        return None
+    contexts = list(client_state.recent_search_contexts)
+    if client_state.follow_up_context_id:
+        for ctx in contexts:
+            if ctx.context_id == client_state.follow_up_context_id:
+                return ctx
+    if client_state.active_search_context_id:
+        for ctx in contexts:
+            if ctx.context_id == client_state.active_search_context_id:
+                return ctx
+    contexts.sort(key=lambda c: c.created_at, reverse=True)
+    return contexts[0]
+
+
+def _detect_follow_up(
+    question: str, client_state: Optional[ClientStatePayload]
+) -> Tuple[bool, Optional[str], Optional[SearchContextPayload]]:
+    base_context = _resolve_base_context(client_state)
+    if not base_context:
+        return False, None, None
+    explicit_action = (client_state.follow_up_action if client_state else None) or None
+    if explicit_action:
+        return True, explicit_action, base_context
+    action = _parse_refinement_action(question)
+    if not action:
+        return False, None, None
+    if _question_has_new_topic(question, base_context.topic):
+        return False, None, None
+    return True, action, base_context
+
+
+def _clone_context(base_context: SearchContextPayload) -> SearchContextPayload:
+    return SearchContextPayload.model_validate(base_context.model_dump())
+
+
+def _apply_follow_up_action(base_context: SearchContextPayload, action: Optional[str]) -> SearchContextPayload:
+    context = _clone_context(base_context)
+    context.context_id = str(uuid.uuid4())
+    context.created_at = time.time()
+    if action == "peer_reviewed_only":
+        context.peer_reviewed = True
+    elif action == "open_access_only":
+        context.open_access = True
+    elif action == "last_5_years":
+        context.year_from = str(CURRENT_YEAR - 4)
+        context.year_to = str(CURRENT_YEAR)
+    elif action == "last_10_years":
+        context.year_from = str(CURRENT_YEAR - 9)
+        context.year_to = str(CURRENT_YEAR)
+    elif action == "last_3_years":
+        context.year_from = str(CURRENT_YEAR - 2)
+        context.year_to = str(CURRENT_YEAR)
+    elif action == "last_2_years":
+        context.year_from = str(CURRENT_YEAR - 1)
+        context.year_to = str(CURRENT_YEAR)
+    elif action and action.startswith("last_") and action.endswith("_years"):
+        try:
+            n = int(action.split("_")[1])
+            context.year_from = str(CURRENT_YEAR - n + 1)
+            context.year_to = str(CURRENT_YEAR)
+        except (IndexError, ValueError):
+            pass
+    elif action == "books_only":
+        context.resource_type = "books"
+    elif action == "articles_only":
+        context.resource_type = "articles"
+    elif action == "both_resources":
+        context.resource_type = "both"
+    elif action == "review_articles_only":
+        context.resource_type = "articles"
+        context.peer_reviewed = True
+    elif action == "search_pubmed":
+        context.source = "pubmed"
+        context.intent = "search_medical"
+        context.resource_type = "articles"
+    elif action == "search_primo":
+        context.source = "primo"
+    return context
+
+
+async def _generate_topic_follow_ups(topic: str, model: str) -> List[dict]:
+    settings = get_settings()
+    if not settings.openai_api_key and not settings.anthropic_api_key:
+        return []
+    try:
+        llm = _get_llm(model, temperature=0.5, max_tokens=200)
+        response = await llm.ainvoke([
+            {"role": "system", "content": (
+                "You are a research librarian helping a user explore a topic more deeply. "
+                "Given a research topic, generate exactly 3 short follow-up questions that explore "
+                "DIFFERENT ASPECTS of the topic — such as subtopics, methodological angles, "
+                "applications, comparisons, or related fields. "
+                "Do NOT suggest filter actions like peer-reviewed, date ranges, or format changes. "
+                "Return ONLY a JSON array of 3 strings, each under 12 words. "
+                "No explanation, no preamble, no markdown.\n"
+                "Example for 'quantum computing':\n"
+                '[\"What are the main hardware approaches in quantum computing?\", '
+                '"How does quantum error correction work?\", '
+                '"Applications of quantum computing in cryptography\"]'
+            )},
+            {"role": "user", "content": f"Topic: {topic}"},
+        ])
+        raw = response.content.strip()
+        if raw.startswith("```"):
+            raw = raw.split("\n", 1)[1].rsplit("```", 1)[0].strip()
+        questions = json.loads(raw)
+        if not isinstance(questions, list):
+            return []
+        return [
+            {"label": q.strip("?") + "?", "question": q.strip("?") + "?"}
+            for q in questions[:3]
+            if isinstance(q, str) and q.strip()
+        ]
+    except Exception as e:
+        logger.warning(f"Topic follow-up generation failed: {e}")
+        return []
+
+
+async def _search_follow_up(
+    context: SearchContextPayload, model: str, summary_mode: bool = False
+) -> Tuple[str, List[dict]]:
+    topic = context.display_topic or context.topic
+    suggestions: List[dict] = []
+    topic_follow_ups = await _generate_topic_follow_ups(topic, model)
+    suggestions.extend(topic_follow_ups)
+
+    filter_suggestions: List[dict] = []
+    if summary_mode:
+        filter_suggestions.append({
+            "label": f"Show KU-accessible articles on {topic}",
+            "question": f"Find KU-accessible articles on {topic}",
+            "action": "articles_only",
+            "context_id": context.context_id,
+        })
+        if context.intent == "search_medical" and context.source != "pubmed":
+            filter_suggestions.append({
+                "label": "Search PubMed instead",
+                "question": f"Search PubMed for {topic}",
+                "action": "search_pubmed",
+                "context_id": context.context_id,
+            })
+        filter_suggestions.append({
+            "label": "Research snapshot",
+            "question": f"Give me a brief research snapshot on {topic}",
+            "action": "summarize_topic",
+            "context_id": context.context_id,
+        })
+
+    suggestions.extend(filter_suggestions[:2])
+    question_text = (
+        f"Here are some related angles you might want to explore on <strong>{_escape(topic)}</strong>. "
+        "Or I can refine the search with filters — just ask."
+    )
+    return question_text, suggestions[:5]
+
+
+def _search_answer_intro(context: SearchContextPayload, is_follow_up: bool) -> str:
+    topic = _escape(context.display_topic or context.topic)
+    resource = {"books": "books", "articles": "articles", "both": "articles and books"}.get(context.resource_type, "articles")
+    location = "PubMed" if context.source == "pubmed" else "KU Library catalogue"
+    if is_follow_up:
+        action = f"I updated your prepared search on <strong>{topic}</strong> for the <strong>{location}</strong> and <strong>{resource}</strong>."
     else:
-        base = _normalize_whitespace(question).strip(".?")
-        if len(base.split()) < 4:
-            base = f"Find research on {topic}"
-    if filters:
-        return f"{base} with {', '.join(filters)}."
-    return base.rstrip(".") + "."
-
-
-def _context_to_dict(context: SearchContextPayload) -> dict:
-    return context.model_dump()
-
-
-async def _validate_topic(topic: str, model: str) -> Tuple[bool, str]:
-    settings = get_settings()
-    if not settings.openai_api_key and not settings.anthropic_api_key:
-        return True, topic
-    try:
-        llm = _get_llm(model, temperature=0, max_tokens=40)
-        response = await llm.ainvoke([
-            {"role": "system", "content": (
-                "You are a topic validator for an academic library search system. "
-                "Given a word or phrase, decide if it is a recognisable research topic, "
-                "subject area, acronym, proper noun, or concept — even if misspelled.\n\n"
-                "Rules:\n"
-                "- If recognisable or a fixable typo: return JSON {\"valid\": true, \"corrected\": \"<corrected spelling>\"}\n"
-                "- If gibberish, random characters, or completely unrecognisable: return JSON {\"valid\": false, \"corrected\": \"\"}\n"
-                "- Acronyms like NLP, ML, AI, CRISPR, IoT are always valid.\n"
-                "- Proper nouns (country names, people, organisations) are always valid.\n"
-                "- Misspellings like 'machne lernig' → corrected: 'machine learning' → valid: true\n"
-                "- Random strings like 'sdfmdnoc', 'xyzabc123', 'qwerty' → valid: false\n"
-                "Return ONLY valid JSON. No explanation."
-            )},
-            {"role": "user", "content": f"Topic: {topic}"},
-        ])
-        raw = response.content.strip()
-        if raw.startswith("```"):
-            raw = raw.split("\n", 1)[1].rsplit("```", 1)[0].strip()
-        s, e = raw.find("{"), raw.rfind("}")
-        if s != -1 and e > s:
-            result = json.loads(raw[s:e + 1])
-            is_valid = bool(result.get("valid", True))
-            corrected = str(result.get("corrected") or topic).strip()
-            return is_valid, corrected
-        return True, topic
-    except Exception as exc:
-        logger.warning(f"_validate_topic failed: {exc} — failing open")
-        return True, topic
-
-
-async def _build_search_plan(question: str, model: str) -> dict:
-    settings = get_settings()
-    raw_query = _normalize_whitespace(question or "")
-    light_query = _light_strip_retrieval_boilerplate(raw_query) or raw_query
-    _stripped = light_query.strip()
-    _is_pure_number  = bool(re.fullmatch(r"[\d\s\.\,\-\/]+", _stripped))
-    _is_too_short    = len(_stripped) < 2
-    _is_single_char  = bool(re.fullmatch(r"[a-zA-Z0-9]", _stripped))
-    _content_words   = [w for w in _stripped.split() if len(w) > 1 and not re.fullmatch(r"[\d\.\,\-]+", w)]
-    _no_content      = len(_content_words) == 0 and len(_stripped) > 0
-    if _is_pure_number or _is_too_short or _is_single_char or _no_content:
-        _display = _stripped or raw_query
-        return {
-            "corrected": raw_query, "natural": light_query, "boolean": "",
-            "database_query": "", "year_from": "", "year_to": "",
-            "peer_reviewed": False, "open_access": False,
-            "clarification_needed": True,
-            "clarification_message": (
-                f"I want to make sure I search for the right thing. "
-                f"Could you clarify what <strong>{_escape(_display)}</strong> refers to? "
-                f"For example, is it a course code, a specific topic name, a year, "
-                f"or something else? The more detail you provide, "
-                f"the better I can build your search."
-            ),
-        }
-    if settings.openai_api_key or settings.anthropic_api_key:
-        _valid, _corrected_topic = await _validate_topic(_stripped, model)
-        if not _valid:
-            return {
-                "corrected": raw_query, "natural": light_query, "boolean": "",
-                "database_query": "", "year_from": "", "year_to": "",
-                "peer_reviewed": False, "open_access": False,
-                "clarification_needed": True,
-                "clarification_message": (
-                    f"I couldn't recognise <strong>{_escape(_stripped)}</strong> as a research topic. "
-                    f"Could you check the spelling, or describe what you're looking for in more detail? "
-                    f"For example: <em>\"find research on machine learning\"</em> or "
-                    f"<em>\"articles on renewable energy in UAE\"</em>."
-                ),
-            }
-        if _corrected_topic and _corrected_topic.lower() != _stripped.lower():
-            logger.info(f"_validate_topic corrected: {_stripped!r} → {_corrected_topic!r}")
-            light_query = _corrected_topic
-    if settings.openai_api_key or settings.anthropic_api_key:
-        try:
-            llm = _get_llm(model, temperature=0, max_tokens=300)
-            response = await llm.ainvoke([
-                {"role": "system", "content": _BUILD_SEARCH_PLAN_SYSTEM},
-                {"role": "user", "content": f'Query: "{light_query}"'},
-            ])
-            raw = response.content.strip()
-            if raw.startswith("```"):
-                raw = raw.split("\n", 1)[1].rsplit("```", 1)[0].strip()
-            s, e = raw.find("{"), raw.rfind("}")
-            if s != -1 and e > s:
-                result = json.loads(raw[s:e + 1])
-            else:
-                raise ValueError("No JSON found in response")
-            corrected = (result.get("corrected") or raw_query).strip() or raw_query
-            natural   = (result.get("natural") or corrected).strip() or corrected
-            boolean   = (result.get("boolean") or "").strip()
-            has_ops   = bool(re.search(r"\b(AND|OR)\b", boolean)) if boolean else False
-            has_parens = "(" in boolean if boolean else False
-            if not has_ops or not has_parens:
-                boolean = _shared_build_primo_boolean_query(corrected)
-            boolean = _sanitize_boolean_for_primo(boolean)
-            year_from = str(result.get("year_from") or "").strip()
-            year_to   = str(result.get("year_to")   or "").strip()
-            if not year_from and not year_to:
-                yf, yt = _parse_year_filters(raw_query)
-                year_from = yf or ""
-                year_to   = yt or ""
-            return {
-                "corrected":      corrected,
-                "natural":        natural,
-                "boolean":        boolean,
-                "database_query": _clean_database_keywords(boolean),
-                "year_from":      year_from,
-                "year_to":        year_to,
-                "peer_reviewed":  bool(result.get("peer_reviewed", False)),
-                "open_access":    bool(result.get("open_access", False)),
-            }
-        except Exception as e:
-            logger.warning(f"_build_search_plan LLM failed: {e} — using regex fallback")
-    boolean = _shared_build_primo_boolean_query(light_query)
-    yf, yt = _parse_year_filters(raw_query)
-    pr = bool(re.search(r"\bpeer[- ]reviewed\b", raw_query, re.IGNORECASE))
-    oa = bool(re.search(r"\bopen[- ]access\b", raw_query, re.IGNORECASE))
-    return {
-        "corrected":      raw_query,
-        "natural":        light_query,
-        "boolean":        boolean,
-        "database_query": _clean_database_keywords(boolean),
-        "year_from":      yf or "",
-        "year_to":        yt or "",
-        "peer_reviewed":  pr,
-        "open_access":    oa,
-    }
-
-
-async def _prepare_queries(question: str, context: SearchContextPayload, model: str, is_follow_up: bool) -> SearchContextPayload:
-    topic = _strip_resource_noise(context.display_topic or context.topic) or context.topic
-    q = question if not is_follow_up else f"Find {context.resource_type} on {topic}"
-    plan = await _build_search_plan(q, model)
-    if plan.get("clarification_needed"):
-        context.clarification_needed = True
-        context.clarification_message = plan.get("clarification_message", "")
-        return context
-    context.ai_tool_query        = plan["natural"]
-    context.primo_boolean_query  = plan["boolean"]
-    if not context.year_from and plan.get("year_from"):
-        context.year_from = plan["year_from"]
-    if not context.year_to and plan.get("year_to"):
-        context.year_to = plan["year_to"]
-    if not context.peer_reviewed and plan.get("peer_reviewed"):
-        context.peer_reviewed = True
-    if not context.open_access and plan.get("open_access"):
-        context.open_access = True
-    return context
-
-
-async def _topic_intro(topic: str, model: str) -> str:
-    """LLM #5 — 3-sentence topic intro. v3.8.1: appends _GUARDRAIL + _URL_INSTRUCTION."""
-    settings = get_settings()
-    if not settings.openai_api_key and not settings.anthropic_api_key:
-        return ""
-    try:
-        llm = _get_llm(model, temperature=0.2, max_tokens=180)
-        response = await llm.ainvoke([
-            {"role": "system", "content": (
-                "You are LibBee, the Khalifa University Library AI Assistant. "
-                "Write exactly 3 clear, factual sentences introducing the given research topic "
-                "for a university student or researcher. "
-                "Cover: what the topic is, why it matters, and one key area of current research interest. "
-                "Use HTML <br> for line breaks only if needed. No markdown, no bullet points, no headings. "
-                "Be concise and informative. "
-                + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
-            )},
-            {"role": "user", "content": f"Research topic: {topic}"},
-        ])
-        intro = response.content.strip()
-        return intro if intro else ""
-    except Exception as e:
-        logger.warning(f"_topic_intro failed: {e}")
-        return ""
-
-
-
-def _extractive_snapshot_from_papers(topic: str, papers: List[dict]) -> str:
-    if not papers:
-        return ""
-    statements: List[str] = []
-    for paper in papers[:4]:
-        sentences = re.split(r"(?<=[.!?])\s+", paper.get("abstract", ""))
-        lead = sentences[0].strip() if sentences else ""
-        if not lead:
-            continue
-        citation = (
-            f'<a href="{paper["link"]}" target="_blank" '
-            f'style="color:#1e40af;font-weight:600;text-decoration:none">'
-            f'[{_escape(paper["citation_key"])}]</a>'
-        )
-        statements.append(f"{_escape(lead)} {citation}")
-    if not statements:
-        return f"Recent literature on <strong>{_escape(topic)}</strong> is available in the cited papers below."
-    intro = f"Recent literature on <strong>{_escape(topic)}</strong>:<br><br>"
-    return intro + "<br><br>".join(statements[:4])
-
-
-def _database_guidance_for_topic(context: SearchContextPayload) -> str:
-    topic = _escape(context.display_topic or context.topic)
-    urls = _tool_urls(context)
-    ai_tools = (
-        f'<a href="{urls["leapspace"]}" target="_blank" style="color:#9a3412;font-weight:700;text-decoration:none">LeapSpace</a> · '
-        f'<a href="{urls["scopus_ai"]}" target="_blank" style="color:#1e40af;font-weight:700;text-decoration:none">Scopus AI</a> · '
-        f'<a href="{urls["ebsco_ai"]}" target="_blank" style="color:#9d174d;font-weight:700;text-decoration:none">EBSCO AI</a> · '
-        f'<a href="{urls["primo_ai"]}" target="_blank" style="color:#5b21b6;font-weight:700;text-decoration:none">PRIMO AI Assistant</a> · '
-        f'<a href="{urls["consensus"]}" target="_blank" style="color:#86198f;font-weight:700;text-decoration:none">Consensus</a>'
-    )
-    more_results = f'<a href="{urls["primo_discovery"]}" target="_blank" style="color:#5b21b6;font-weight:700;text-decoration:none">PRIMO Library Discovery</a>'
-    if context.intent == "search_medical" and urls.get("pubmed"):
-        more_results += f' · <a href="{urls["pubmed"]}" target="_blank" style="color:#065f46;font-weight:700;text-decoration:none">PubMed</a>'
-        return (
-            f"For deeper work on <strong>{topic}</strong>, continue with these AI research tools: {ai_tools}. "
-            f"For more results, use {more_results}. Medical topics are strongest in PubMed, Embase, and CINAHL."
-        )
-    return (
-        f"For deeper work on <strong>{topic}</strong>, continue with these AI research tools: {ai_tools}. "
-        f"For more results, use {more_results}."
-    )
-
-
-async def _search_strategy_answer(question: str, model: str) -> Tuple[str, dict]:
-    plan = await _build_search_plan(question, model)
-    topic = _escape(_light_strip_retrieval_boilerplate(question) or question)
-    boolean = _escape(plan.get("boolean", ""))
-    natural = _escape(plan.get("natural", ""))
-    explanation = (
-        f"<strong>🔍 Search strategy for: {topic}</strong><br><br>"
-        f"<strong>1. Identify your key concepts</strong><br>"
-        f"Break the topic into 2–3 core concepts. For your question, I identified these concepts "
-        f"and suggested synonyms for each using OR, then joined concepts with AND:<br><br>"
-        f'<code style="display:block;padding:8px 12px;background:#1a1a2e;color:#C8A951;'
-        f'border-radius:8px;font-size:.82rem;word-break:break-all">{boolean}</code><br>'
-        f"<strong>Why AND and OR?</strong> AND narrows — both concepts must appear. "
-        f"OR broadens — any synonym counts. Quoting phrases like "
-        f"<code>\"machine learning\"</code> keeps them together as an exact phrase.<br><br>"
-        f"<strong>2. Apply filters</strong><br>"
-        f"Use database facets to limit by: peer-reviewed, date range, document type (article / review / book), "
-        f"language, or open access. In PRIMO, these appear in the left sidebar after you search.<br><br>"
-        f"<strong>3. Natural language query for AI tools</strong><br>"
-        f"For AI-powered tools (LeapSpace, Scopus AI, Consensus), use a conversational query:<br>"
-        f'<em style="color:var(--color-text-secondary)">{natural}</em><br><br>'
-        f"<strong>4. Iterate</strong><br>"
-        f"Too many results → add more AND terms or apply filters. "
-        f"Too few → remove an AND group or use broader synonyms. "
-        f"You can ask me to refine: <em>\"narrow to peer-reviewed only\"</em>, "
-        f"<em>\"limit to last 5 years\"</em>, or <em>\"suggest alternative keywords\"</em>."
-    )
-    return explanation, plan
-
-
-async def _alternative_terms_answer(question: str, context: Optional[SearchContextPayload], model: str) -> str:
-    topic = (context.display_topic or context.topic) if context else question
-    settings = get_settings()
-    if not settings.openai_api_key and not settings.anthropic_api_key:
-        return (
-            f"<strong>Alternative search terms for: {_escape(topic)}</strong><br><br>"
-            "Try combining these broader, narrower, and related terms:<br>"
-            "• Use broader terms if too few results<br>"
-            "• Use narrower/specific terms if too many results<br>"
-            "• Try acronyms and full forms (e.g. AI / Artificial Intelligence)<br>"
-            "• Include British and American spellings (e.g. organisation/organization)"
-        )
-    try:
-        llm = _get_llm(model, temperature=0.4, max_tokens=300)
-        response = await llm.ainvoke([
-            {"role": "system", "content": (
-                "You are an academic librarian. Given a research topic, generate a structured list of alternative "
-                "search terms. Group them as: Broader terms, Narrower/specific terms, Related concepts, Acronyms/abbreviations. "
-                "Format as HTML using <strong> for group labels and <br> for line breaks. "
-                "Keep it concise — 3-4 terms per group maximum. No bullet points, use • instead."
-            )},
-            {"role": "user", "content": f"Research topic: {topic}"},
-        ])
-        terms = response.content.strip()
-        return (
-            f"<strong>💡 Alternative search terms for: {_escape(topic)}</strong><br><br>"
-            f"{terms}<br><br>"
-            f"<strong>Tip:</strong> In PRIMO or databases, use OR between synonyms within a concept group, "
-            f"and AND between different concept groups. Ask me to run a new search with any of these."
-        )
-    except Exception as e:
-        logger.warning(f"_alternative_terms_answer failed: {e}")
-        return f"<strong>Alternative terms for {_escape(topic)}</strong><br><br>Try synonyms, acronyms, broader/narrower terms, and related concepts in your search."
-
-
-def _citation_chain_answer() -> str:
-    return (
-        "<strong>🔗 How to trace citations forward and backward from a paper</strong><br><br>"
-        "<strong>Backward citation (who does this paper cite?)</strong><br>"
-        "Read the paper's reference list — every source it cites is a potential lead. "
-        "This gives you foundational and seminal works on the topic.<br><br>"
-        "<strong>Forward citation (who has cited this paper since publication?)</strong><br>"
-        "Use these tools — paste in the DOI or title:<br>"
-        '• <a href="https://www-scopus-com.khalifa.idm.oclc.org/pages/ai" target="_blank"><strong>Scopus</strong></a> '
-        '— search the article, then click "Cited by N documents"<br>'
-        '• <a href="https://www.webofscience.com" target="_blank"><strong>Web of Science</strong></a> '
-        '— search the article, click "Times Cited"<br>'
-        '• <a href="https://www.semanticscholar.org" target="_blank"><strong>Semantic Scholar</strong></a> '
-        '— free, excellent for CS and engineering, shows "Citations" tab<br>'
-        '• <a href="https://openalex.org" target="_blank"><strong>OpenAlex</strong></a> '
-        '— fully open, API-accessible citation graph<br><br>'
-        "<strong>Lateral search (similar papers)</strong><br>"
-        "In PRIMO, use <em>\"Find Similar\"</em>. In Semantic Scholar, use <em>\"Recommended Papers\"</em>. "
-        "In Scopus, use <em>\"Related Documents\"</em>.<br><br>"
-        "<strong>Tip:</strong> Start with one highly cited foundational paper, trace forward to find the newest "
-        "work, and backward to understand the theoretical roots."
-    )
-
-
-def _predatory_eval_answer() -> str:
-    return (
-        "<strong>✅ How to tell if an article or journal is peer-reviewed, scholarly, or predatory</strong><br><br>"
-        "<strong>Is it peer-reviewed?</strong><br>"
-        "• Check the journal's website for a peer-review statement or editorial process description<br>"
-        "• In PRIMO, tick the <em>Peer-reviewed</em> filter in the left sidebar<br>"
-        "• Check if the journal is indexed in "
-        '<a href="https://www-scopus-com.khalifa.idm.oclc.org" target="_blank">Scopus</a> or '
-        '<a href="https://www.webofscience.com" target="_blank">Web of Science</a> — '
-        "indexed = generally peer-reviewed<br><br>"
-        "<strong>Is it a legitimate journal?</strong><br>"
-        "• <a href=\"https://doaj.org\" target=\"_blank\"><strong>DOAJ</strong></a> "
-        "— Directory of Open Access Journals (vetted, legitimate OA)<br>"
-        "• <a href=\"https://mjl.clarivate.com\" target=\"_blank\"><strong>Web of Science Master Journal List</strong></a><br>"
-        "• <a href=\"https://www.scopus.com/sources\" target=\"_blank\"><strong>Scopus Source List</strong></a><br>"
-        "• Think · Check · Submit: <a href=\"https://thinkchecksubmit.org\" target=\"_blank\">thinkchecksubmit.org</a> "
-        "— a checklist to assess any journal<br><br>"
-        "<strong>Warning signs of predatory journals</strong><br>"
-        "• Unsolicited email invitation to submit<br>"
-        "• No clear peer-review process or very fast acceptance (days)<br>"
-        "• High article processing charges (APCs) with no clear metrics<br>"
-        "• Not indexed in Scopus or Web of Science<br>"
-        "• Generic or misleading journal name ('International Journal of...')<br><br>"
-        "<strong>Need help checking a specific journal?</strong> Ask our E-Resources Librarian: "
-        "<strong>Rani Anand</strong> · <a href=\"mailto:rani.anand@ku.ac.ae\">rani.anand@ku.ac.ae</a>"
-    )
-
-
-def _highly_cited_note(topic_escaped: str) -> str:
-    return (
-        f"<br><br><strong>📊 Finding highly cited papers on {topic_escaped}</strong><br>"
-        "PRIMO doesn't sort by citation count, but these tools do:<br>"
-        '• <a href="https://www-scopus-com.khalifa.idm.oclc.org" target="_blank"><strong>Scopus</strong></a> '
-        '— search your topic → Sort by <em>Cited by (highest)</em><br>'
-        '• <a href="https://www.webofscience.com" target="_blank"><strong>Web of Science</strong></a> '
-        '— search → Sort by <em>Times Cited</em><br>'
-        '• <a href="https://www.semanticscholar.org" target="_blank"><strong>Semantic Scholar</strong></a> '
-        '— free, sort by <em>Citation Count</em><br>'
-        '• <a href="https://scholar.google.com" target="_blank"><strong>Google Scholar</strong></a> '
-        '— sort by <em>Cited by</em> (broader but includes grey literature)'
-    )
-
-
-async def _research_snapshot(context: SearchContextPayload, model: str) -> Tuple[str, List[dict], List[dict]]:
-    """Research snapshot = prepared platform links + a live open-evidence panel.
-
-    The evidence panel queries OpenAlex first (Semantic Scholar as fallback),
-    then enriches results with legal open-access links via Unpaywall and fills
-    metadata gaps via Crossref. Every external call is best-effort: if the open
-    indexes are unreachable the handler degrades to the prepared-links block
-    (the entire pre-3.8 behaviour), so the user always gets an answer.
-    """
-    topic = context.topic
-    primo_url = _primo_clean_url(context)
-    answer = _search_trace_block(f"Research on {topic}", context)
-    answer += (
-        f"<strong>📚 Research starting points: {_escape(topic)}</strong><br><br>"
-        "Your query has been prepared and pre-loaded across multiple platforms. "
-        "Click any platform below to search instantly, or use the boolean search tip "
-        "to search directly in any KU database."
-        f'<br><br><a href="{primo_url}" target="_blank" style="color:#003366;font-weight:700">'
-        f'Search PRIMO for: {_escape(topic)} →</a>'
-    )
-
-    # Shared open-evidence panel (see scholarly.fetch_evidence_panel)
-    papers, panel_html = await fetch_evidence_panel(topic)
-    answer += panel_html
-
-    answer += _ai_tools_footer(context)
-    return answer, papers, []
-
-
-def _filters_summary(context: SearchContextPayload) -> str:
-    filters: List[str] = []
-    if context.peer_reviewed:
-        filters.append("peer reviewed only")
-    if context.open_access:
-        filters.append("open access")
-    if context.year_from and context.year_to:
-        filters.append(f"{context.year_from}–{context.year_to}")
-    elif context.year_from:
-        filters.append(f"from {context.year_from}")
-    if context.resource_type == "books":
-        filters.append("books")
-    elif context.resource_type == "articles":
-        filters.append("articles")
-    elif context.resource_type == "both":
-        filters.append("articles and books")
-    return ", ".join(filters)
-
-
-def _question_has_new_topic(question: str, base_topic: str) -> bool:
-    q = (question or "").lower()
-    cleaned = re.sub(
-        r"\b(peer[- ]reviewed|open access|last \d+ years?|past \d+ years?|books? instead|articles? instead|"
-        r"summari[sz]e( this topic)?|overview|brief|use pubmed|search pubmed|search primo|best databases?|deep research tools?)\b",
-        " ", q,
-    )
-    tokens = [t for t in re.findall(r"[a-z0-9]+", cleaned) if t not in REFINEMENT_STOP_WORDS and len(t) > 2]
-    if len(tokens) < 3:
-        return False
-    base_tokens = {t for t in re.findall(r"[a-z0-9]+", (base_topic or "").lower()) if t not in REFINEMENT_STOP_WORDS}
-    overlap = sum(1 for t in tokens if t in base_tokens)
-    return overlap <= max(1, min(2, len(base_tokens)))
-
-
-def _parse_refinement_action(question: str) -> Optional[str]:
-    q = (question or "").lower().strip()
-    if re.search(r"\b(peer[- ]reviewed|peer reviewed only|peer reviewd|peer review only)\b", q):
-        return "peer_reviewed_only"
-    if re.search(r"\b(open access|oa only|only open access)\b", q):
-        return "open_access_only"
-    if re.search(r"\b(last|past)\s+5\s+years?\b", q):
-        return "last_5_years"
-    if re.search(r"\b(last|past)\s+10\s+years?\b|\bpast decade\b", q):
-        return "last_10_years"
-    m = re.search(r"\b(last|past)\s+(\d{1,2})\s+years?\b", q)
-    if m:
-        return f"last_{m.group(2)}_years"
-    if re.search(r"\bbooks? instead\b|\bbooks? only\b|\bfind books?\b|\bshow books?\b", q):
-        return "books_only"
-    if re.search(r"\barticles? instead\b|\barticles? only\b|\bpapers? only\b", q):
-        return "articles_only"
-    if re.search(r"\b(?:both|articles and books|books and articles)\b", q):
-        return "both_resources"
-    if REVIEW_ONLY_RE.search(q):
-        return "review_articles_only"
-    if ALT_TERMS_RE.search(q):
-        return "alt_terms"
-    if re.search(r"\b(summar(y|ize|ise)|overview|brief|what does the literature say|research snapshot)\b", q):
-        _STOP = {
-            'a','an','the','of','on','in','for','to','with','by','from','at','is','are',
-            'was','were','be','been','have','has','had','do','does','did','will','would',
-            'could','should','may','its','this','that','these','those','about','me','my',
-            'give','show','tell','please','can','you','i','need','want','get','find',
-            'research','summary','overview','summarize','summarise','brief','literature',
-        }
-        content_words = [t for t in re.findall(r'[a-z0-9]+', q)
-                         if t not in _STOP and (len(t) > 2 or t in {'ai','ml','nlp','cv','rl','dl','uae','ku','iot'})]
-        if content_words:
-            return None
-        return "summarize_topic"
-    if re.search(r"\bpubmed\b", q):
-        return "search_pubmed"
-    if re.search(r"\bprimo\b", q):
-        return "search_primo"
-    if re.search(r"\b(best database|best databases|which database|which databases)\b", q):
-        return "best_databases"
-    if re.search(r"\b(deep research|deep dive|full literature review|exhaustive)\b", q):
-        return "deep_research_tools"
-    return None
-
-
-def _resolve_base_context(client_state: Optional[ClientStatePayload]) -> Optional[SearchContextPayload]:
-    if not client_state or not client_state.recent_search_contexts:
-        return None
-    contexts = list(client_state.recent_search_contexts)
-    if client_state.follow_up_context_id:
-        for ctx in contexts:
-            if ctx.context_id == client_state.follow_up_context_id:
-                return ctx
-    if client_state.active_search_context_id:
-        for ctx in contexts:
-            if ctx.context_id == client_state.active_search_context_id:
-                return ctx
-    contexts.sort(key=lambda c: c.created_at, reverse=True)
-    return contexts[0]
-
-
-def _detect_follow_up(
-    question: str, client_state: Optional[ClientStatePayload]
-) -> Tuple[bool, Optional[str], Optional[SearchContextPayload]]:
-    base_context = _resolve_base_context(client_state)
-    if not base_context:
-        return False, None, None
-    explicit_action = (client_state.follow_up_action if client_state else None) or None
-    if explicit_action:
-        return True, explicit_action, base_context
-    action = _parse_refinement_action(question)
-    if not action:
-        return False, None, None
-    if _question_has_new_topic(question, base_context.topic):
-        return False, None, None
-    return True, action, base_context
-
-
-def _clone_context(base_context: SearchContextPayload) -> SearchContextPayload:
-    return SearchContextPayload.model_validate(base_context.model_dump())
-
-
-def _apply_follow_up_action(base_context: SearchContextPayload, action: Optional[str]) -> SearchContextPayload:
-    context = _clone_context(base_context)
-    context.context_id = str(uuid.uuid4())
-    context.created_at = time.time()
-    if action == "peer_reviewed_only":
-        context.peer_reviewed = True
-    elif action == "open_access_only":
-        context.open_access = True
-    elif action == "last_5_years":
-        context.year_from = str(CURRENT_YEAR - 4)
-        context.year_to = str(CURRENT_YEAR)
-    elif action == "last_10_years":
-        context.year_from = str(CURRENT_YEAR - 9)
-        context.year_to = str(CURRENT_YEAR)
-    elif action == "last_3_years":
-        context.year_from = str(CURRENT_YEAR - 2)
-        context.year_to = str(CURRENT_YEAR)
-    elif action == "last_2_years":
-        context.year_from = str(CURRENT_YEAR - 1)
-        context.year_to = str(CURRENT_YEAR)
-    elif action and action.startswith("last_") and action.endswith("_years"):
-        try:
-            n = int(action.split("_")[1])
-            context.year_from = str(CURRENT_YEAR - n + 1)
-            context.year_to = str(CURRENT_YEAR)
-        except (IndexError, ValueError):
-            pass
-    elif action == "books_only":
-        context.resource_type = "books"
-    elif action == "articles_only":
-        context.resource_type = "articles"
-    elif action == "both_resources":
-        context.resource_type = "both"
-    elif action == "review_articles_only":
-        context.resource_type = "articles"
-        context.peer_reviewed = True
-    elif action == "search_pubmed":
-        context.source = "pubmed"
-        context.intent = "search_medical"
-        context.resource_type = "articles"
-    elif action == "search_primo":
-        context.source = "primo"
-    return context
-
-
-async def _generate_topic_follow_ups(topic: str, model: str) -> List[dict]:
-    settings = get_settings()
-    if not settings.openai_api_key and not settings.anthropic_api_key:
-        return []
-    try:
-        llm = _get_llm(model, temperature=0.5, max_tokens=200)
-        response = await llm.ainvoke([
-            {"role": "system", "content": (
-                "You are a research librarian helping a user explore a topic more deeply. "
-                "Given a research topic, generate exactly 3 short follow-up questions that explore "
-                "DIFFERENT ASPECTS of the topic — such as subtopics, methodological angles, "
-                "applications, comparisons, or related fields. "
-                "Do NOT suggest filter actions like peer-reviewed, date ranges, or format changes. "
-                "Return ONLY a JSON array of 3 strings, each under 12 words. "
-                "No explanation, no preamble, no markdown.\n"
-                "Example for 'quantum computing':\n"
-                '[\"What are the main hardware approaches in quantum computing?\", '
-                '"How does quantum error correction work?\", '
-                '"Applications of quantum computing in cryptography\"]'
-            )},
-            {"role": "user", "content": f"Topic: {topic}"},
-        ])
-        raw = response.content.strip()
-        if raw.startswith("```"):
-            raw = raw.split("\n", 1)[1].rsplit("```", 1)[0].strip()
-        questions = json.loads(raw)
-        if not isinstance(questions, list):
-            return []
-        return [
-            {"label": q.strip("?") + "?", "question": q.strip("?") + "?"}
-            for q in questions[:3]
-            if isinstance(q, str) and q.strip()
-        ]
-    except Exception as e:
-        logger.warning(f"Topic follow-up generation failed: {e}")
-        return []
-
-
-async def _search_follow_up(
-    context: SearchContextPayload, model: str, summary_mode: bool = False
-) -> Tuple[str, List[dict]]:
-    topic = context.display_topic or context.topic
-    suggestions: List[dict] = []
-    topic_follow_ups = await _generate_topic_follow_ups(topic, model)
-    suggestions.extend(topic_follow_ups)
-
-    filter_suggestions: List[dict] = []
-    if summary_mode:
-        filter_suggestions.append({
-            "label": f"Show KU-accessible articles on {topic}",
-            "question": f"Find KU-accessible articles on {topic}",
-            "action": "articles_only",
-            "context_id": context.context_id,
-        })
-        if context.intent == "search_medical" and context.source != "pubmed":
-            filter_suggestions.append({
-                "label": "Search PubMed instead",
-                "question": f"Search PubMed for {topic}",
-                "action": "search_pubmed",
-                "context_id": context.context_id,
-            })
-        filter_suggestions.append({
-            "label": "Research snapshot",
-            "question": f"Give me a brief research snapshot on {topic}",
-            "action": "summarize_topic",
-            "context_id": context.context_id,
-        })
-
-    suggestions.extend(filter_suggestions[:2])
-    question_text = (
-        f"Here are some related angles you might want to explore on <strong>{_escape(topic)}</strong>. "
-        "Or I can refine the search with filters — just ask."
-    )
-    return question_text, suggestions[:5]
-
-
-def _search_answer_intro(context: SearchContextPayload, is_follow_up: bool) -> str:
-    topic = _escape(context.display_topic or context.topic)
-    resource = {"books": "books", "articles": "articles", "both": "articles and books"}.get(context.resource_type, "articles")
-    location = "PubMed" if context.source == "pubmed" else "KU Library catalogue"
-    if is_follow_up:
-        action = f"I updated your previous search on <strong>{topic}</strong> in the <strong>{location}</strong> and looked for <strong>{resource}</strong>."
-    else:
-        action = f"I searched for <strong>{resource}</strong> on <strong>{topic}</strong>."
-    return action
-
-
-async def _run_search_mode(
-    question: str, context: SearchContextPayload, model: str, is_follow_up: bool
-) -> Tuple[str, List[dict], List[dict], str]:
-    """
-    Search mode — builds PRIMO link + 3-sentence topic intro + AI tools footer.
-    No external academic API calls (v3.8).
-    Includes clarification gate for ambiguous/gibberish queries.
-    """
-    context = await _prepare_queries(question, context, model, is_follow_up)
-
-    # Clarification gate
-    if context.clarification_needed and context.clarification_message:
-        return context.clarification_message, [], [], ""
-
-    source_url = _primo_clean_url(context)
-    topic = _escape(context.display_topic or context.topic)
-
-    # 3-sentence topic intro AND the open-evidence panel, fetched concurrently:
-    # the panel's network time hides inside the intro's LLM latency instead of
-    # adding to it. Both degrade independently if they fail.
-    intro, (papers, panel_html) = await asyncio.gather(
-        _topic_intro(context.display_topic or context.topic, model),
-        fetch_evidence_panel(context.display_topic or context.topic),
-    )
-
-    answer = _search_trace_block(question, context)
-    if intro:
-        answer += f'<div style="margin-bottom:12px;color:#374151;font-size:.88rem;line-height:1.7">{intro}</div>'
-    answer += _search_answer_intro(context, is_follow_up)
-    answer += (
-        f'<br><br>'
-        f'<a href="{source_url}" target="_blank" '
-        f'style="display:inline-block;padding:9px 18px;background:#003366;color:#fff;'
-        f'border-radius:8px;font-weight:700;text-decoration:none;font-size:.88rem">'
-        f'🔍 Search PRIMO Library Discovery for: {topic} →</a>'
-        f'<br><div style="margin-top:6px;font-size:.78rem;color:#6b7280">'
-        f'💡 Inside PRIMO you can filter by <strong>Articles</strong>, <strong>Books</strong>, '
-        f'<strong>Peer Reviewed</strong>, date range, and more.</div>'
-    )
-    answer += panel_html
-    answer += _ai_tools_footer(context)
-
-    return answer, papers, [], source_url
-
-
-def _sort_and_trim_contexts(contexts: List[SearchContextPayload]) -> List[SearchContextPayload]:
-    dedup: Dict[str, SearchContextPayload] = {}
-    for ctx in contexts:
-        dedup[ctx.context_id] = ctx
-    ordered = sorted(dedup.values(), key=lambda c: c.created_at, reverse=True)
-    return ordered[:5]
-
-
+        action = f"I prepared a search for <strong>{resource}</strong> on <strong>{topic}</strong>."
+    return action
+
+
+async def _run_search_mode(
+    question: str, context: SearchContextPayload, model: str, is_follow_up: bool
+) -> Tuple[str, List[dict], List[dict], str]:
+    """
+    Search mode — builds PRIMO link + 3-sentence topic intro + AI tools footer.
+    No external academic API calls (v3.8).
+    Includes clarification gate for ambiguous/gibberish queries.
+    """
+    context = await _prepare_queries(question, context, model, is_follow_up)
+
+    # Clarification gate
+    if context.clarification_needed and context.clarification_message:
+        return context.clarification_message, [], [], ""
+
+    source_url = _primo_clean_url(context)
+    topic = _escape(context.display_topic or context.topic)
+
+    # 3-sentence topic intro AND the open-evidence panel, fetched concurrently:
+    # the panel's network time hides inside the intro's LLM latency instead of
+    # adding to it. Both degrade independently if they fail.
+    intro, (papers, panel_html) = await asyncio.gather(
+        _topic_intro(context.display_topic or context.topic, model),
+        fetch_evidence_panel(context.display_topic or context.topic, context=context),
+    )
+
+    answer = _search_trace_block(question, context)
+    if intro:
+        answer += f'<div style="margin-bottom:12px;color:#374151;font-size:.88rem;line-height:1.7">{intro}</div>'
+    answer += _search_answer_intro(context, is_follow_up)
+    answer += (
+        f'<br><br>'
+        f'<a href="{source_url}" target="_blank" '
+        f'style="display:inline-block;padding:9px 18px;background:#003366;color:#fff;'
+        f'border-radius:8px;font-weight:700;text-decoration:none;font-size:.88rem">'
+        f'🔍 Search PRIMO Library Discovery for: {topic} →</a>'
+        f'<br><div style="margin-top:6px;font-size:.78rem;color:#6b7280">'
+        f'💡 Inside PRIMO you can filter by <strong>Articles</strong>, <strong>Books</strong>, '
+        f'<strong>Peer Reviewed</strong>, date range, and more.</div>'
+    )
+    answer += panel_html
+    answer += _ai_tools_footer(context)
+
+    sources = [
+        {"title": paper.get("title", ""), "url": paper.get("link", ""),
+         "doi": paper.get("doi", ""), "provider": paper.get("_source", "")}
+        for paper in papers
+    ]
+    return answer, papers, sources, source_url
+
+
+def _sort_and_trim_contexts(contexts: List[SearchContextPayload]) -> List[SearchContextPayload]:
+    dedup: Dict[str, SearchContextPayload] = {}
+    for ctx in contexts:
+        dedup[ctx.context_id] = ctx
+    ordered = sorted(dedup.values(), key=lambda c: c.created_at, reverse=True)
+    return ordered[:5]
+
+

src/agentcore/libcal.py

@@ -1,333 +1,333 @@
-"""LibCal client + formatting: live opening hours and events via the Cloudflare Worker proxy."""
-import asyncio
-import html
-import json
-import logging
-import os
-import re
-import time
-import uuid
-from datetime import datetime
-from typing import Any, Dict, List, Literal, Optional, Tuple
-from urllib.parse import quote
-
-import httpx
-from pydantic import BaseModel, ConfigDict, Field
-
-from src.config import get_settings, LIBBEE_VERSION
-
-from src.agentcore.constants import LIBRARY_HOURS_URL
-from src.agentcore.utils import _escape
-
-logger = logging.getLogger(__name__)
-
-_libcal_hours_cache: Dict[str, Any] = {}
-
-
-_LIBCAL_HOURS_TTL = 60 * 60
-
-
-async def _libcal_fetch_hours() -> Optional[dict]:
-    now = time.time()
-    cached_at = _libcal_hours_cache.get("cached_at", 0)
-    if _libcal_hours_cache.get("data") and now - cached_at < _LIBCAL_HOURS_TTL:
-        return _libcal_hours_cache["data"]
-    settings = get_settings()
-    worker_url = getattr(settings, "cloudflare_worker_url", "").strip()
-    if not worker_url:
-        logger.warning("LibCal: CLOUDFLARE_WORKER_URL not set — cannot fetch hours")
-        return None
-    from datetime import timezone, timedelta
-    uae_now   = datetime.now(timezone(timedelta(hours=4)))
-    date_from = uae_now.strftime("%Y-%m-%d")
-    date_to   = (uae_now + timedelta(days=6)).strftime("%Y-%m-%d")
-    try:
-        async with httpx.AsyncClient(timeout=10) as client:
-            r = await client.get(
-                f"{worker_url.rstrip('/')}/hours",
-                params={"from": date_from, "to": date_to},
-            )
-            r.raise_for_status()
-            data = r.json()
-            if data.get("error"):
-                logger.warning("LibCal worker error: %s", data["error"])
-                return None
-            _libcal_hours_cache["data"]      = data
-            _libcal_hours_cache["cached_at"] = now
-            logger.info("LibCal: hours refreshed via worker")
-            return data
-    except Exception as exc:
-        logger.warning("LibCal hours fetch failed: %s", exc)
-        return None
-
-
-def _parse_libcal_time(raw: str) -> str:
-    if not raw:
-        return raw
-    raw = raw.strip().replace("\u2013", "-").replace("–", "-")
-    raw = re.sub(r"\s+", "", raw)
-    raw = re.sub(r"(?i)(am|pm)$", lambda m: " " + m.group(1).upper(), raw)
-    return raw
-
-
-def _format_libcal_day(day_data: dict) -> str:
-    if not day_data or not isinstance(day_data, dict):
-        return "See hours page"
-    status = str(day_data.get("status") or "").lower().strip()
-    note   = str(day_data.get("note") or "").strip()
-    if status in ("closed", "0", "false"):
-        return f"Closed{f' — {note}' if note else ''}"
-    if status == "24hours":
-        return "Open 24 hours"
-    hours_list = day_data.get("hours") or []
-    if hours_list and isinstance(hours_list, list):
-        first = hours_list[0]
-        f = first.get("from") or first.get("opens") or ""
-        t = first.get("to")   or first.get("closes") or ""
-        if f and t:
-            return f"{_parse_libcal_time(f)} – {_parse_libcal_time(t)}"
-    opens  = day_data.get("opens")  or day_data.get("open")  or ""
-    closes = day_data.get("closes") or day_data.get("close") or ""
-    if opens and closes:
-        return f"{_parse_libcal_time(opens)} – {_parse_libcal_time(closes)}"
-    times = day_data.get("times") or []
-    if times and isinstance(times, list):
-        first = times[0]
-        f = first.get("from") or first.get("opens") or ""
-        t = first.get("to")   or first.get("closes") or ""
-        if f and t:
-            return f"{_parse_libcal_time(f)} – {_parse_libcal_time(t)}"
-    if status in ("open",):
-        return "Open — see hours page for times"
-    return "See hours page"
-
-
-async def _hours_answer() -> str:
-    from datetime import timezone, timedelta
-    uae_now  = datetime.now(timezone(timedelta(hours=4)))
-    today_str = uae_now.strftime("%Y-%m-%d")
-    day_names = ["Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"]
-    today_name = day_names[uae_now.weekday()]
-    hours_data = await _libcal_fetch_hours()
-    if not hours_data:
-        return (
-            "Here are the <strong>Khalifa University Library</strong> hours:<br><br>"
-            "⚠️ Live hours are currently unavailable. Please check the official schedule:<br>"
-            f'<a href="{LIBRARY_HOURS_URL}" target="_blank" '
-            f'style="font-weight:700;color:#003366">{LIBRARY_HOURS_URL}</a><br><br>'
-            "<strong>📍 Contacts:</strong><br>"
-            'Main Campus Library · E Building · <a href="tel:+97123124604">+971 2 312 4604</a><br>'
-            'Habshan Library · SAN Campus · <a href="tel:+97123123160">+971 2 312 3160</a>'
-        )
-    location_labels = {
-        "main_campus": "Main Campus Library",
-        "habshan":     "Habshan Library (SAN Campus)",
-    }
-    def _today_line(loc_name: str, loc_data: dict) -> str:
-        dates = loc_data.get("dates", {})
-        today_entry = dates.get(today_str, {})
-        if not today_entry:
-            return f"<em>See <a href='{LIBRARY_HOURS_URL}' target='_blank'>live hours</a> for today</em>"
-        hours_str = _format_libcal_day(today_entry)
-        is_closed = hours_str.lower().startswith("closed")
-        colour = "#dc2626" if is_closed else "#16a34a"
-        return (
-            f"📅 <strong>Today ({today_name}):</strong> "
-            f"<span style='color:{colour};font-weight:700'>{hours_str}</span>"
-        )
-    def _week_table(loc_data: dict) -> str:
-        dates = loc_data.get("dates", {})
-        if not dates:
-            return ""
-        rows = ""
-        for date_key in sorted(dates.keys())[:7]:
-            try:
-                from datetime import date as _date
-                d = _date.fromisoformat(date_key)
-                day_label = d.strftime("%a %d %b")
-                is_today  = date_key == today_str
-            except ValueError:
-                day_label = date_key
-                is_today  = False
-            hours_str = _format_libcal_day(dates[date_key])
-            is_closed = hours_str.lower().startswith("closed")
-            colour    = "#dc2626" if is_closed else "#16a34a"
-            weight    = "700" if is_today else "400"
-            bg        = "#fffbeb" if is_today else "transparent"
-            rows += (
-                f"<tr style='background:{bg}'>"
-                f"<td style='padding:3px 12px 3px 0;color:#374151;font-weight:{weight}'>{day_label}</td>"
-                f"<td style='padding:3px 0;font-weight:600;color:{colour}'>{hours_str}</td>"
-                f"</tr>"
-            )
-        if not rows:
-            return ""
-        return (
-            "<table style='font-size:.84rem;border-collapse:collapse;width:100%;max-width:380px'>"
-            + rows + "</table>"
-        )
-    answer = "Here are the <strong>Khalifa University Library</strong> live hours:<br><br>"
-    for key, label in location_labels.items():
-        loc = hours_data.get(key)
-        if not loc:
-            continue
-        answer += f"<strong>📍 {label}</strong><br>"
-        answer += _today_line(label, loc) + "<br>"
-        week_tbl = _week_table(loc)
-        if week_tbl:
-            answer += week_tbl + "<br><br>"
-        else:
-            answer += "<br>"
-    answer += (
-        "⚠️ <strong>Hours may change during Ramadan, public holidays, and exam periods.</strong><br>"
-        f'Always confirm at: <a href="{LIBRARY_HOURS_URL}" target="_blank" '
-        f'style="font-weight:700;color:#003366">{LIBRARY_HOURS_URL}</a><br><br>'
-        '<span style="font-size:.82rem;color:#6b7280">'
-        'Main Campus Library · E Building · <a href="tel:+97123124604">+971 2 312 4604</a><br>'
-        'Habshan Library · Building 5, SAN Campus · <a href="tel:+97123123160">+971 2 312 3160</a>'
-        '</span>'
-    )
-    return answer
-
-
-_libcal_events_cache: Dict[str, Any] = {}
-
-
-_LIBCAL_EVENTS_TTL = 30 * 60
-
-
-async def _libcal_fetch_events(days: int = 30, limit: int = 10) -> Optional[list]:
-    now = time.time()
-    cache_key = f"{days}_{limit}"
-    cached = _libcal_events_cache.get(cache_key, {})
-    if cached.get("data") and now - cached.get("cached_at", 0) < _LIBCAL_EVENTS_TTL:
-        return cached["data"]
-    settings = get_settings()
-    worker_url = getattr(settings, "cloudflare_worker_url", "").strip()
-    if not worker_url:
-        logger.warning("LibCal events: CLOUDFLARE_WORKER_URL not set")
-        return None
-    try:
-        async with httpx.AsyncClient(timeout=10) as client:
-            r = await client.get(
-                f"{worker_url.rstrip('/')}/events",
-                params={"days": days, "limit": limit},
-            )
-            r.raise_for_status()
-            data = r.json()
-            if data.get("error"):
-                logger.warning("LibCal events worker error: %s", data["error"])
-                return None
-            events_raw = data.get("events", [])
-            def _safe_str(val) -> str:
-                if val is None:
-                    return ""
-                if isinstance(val, str):
-                    return val
-                if isinstance(val, dict):
-                    return str(val.get("name") or val.get("title") or "")
-                if isinstance(val, list):
-                    return ", ".join(_safe_str(v) for v in val if v)
-                return str(val)
-            events = []
-            for e in events_raw:
-                cats = e.get("category") or e.get("categories") or []
-                if isinstance(cats, list):
-                    cat_str = ", ".join(_safe_str(c) for c in cats)
-                else:
-                    cat_str = _safe_str(cats)
-                events.append({
-                    "id":           e.get("id", ""),
-                    "title":        _safe_str(e.get("title") or "Untitled Event"),
-                    "start":        _safe_str(e.get("start") or ""),
-                    "end":          _safe_str(e.get("end") or ""),
-                    "allDay":       bool(e.get("allday") or e.get("allDay")),
-                    "location":     _safe_str(e.get("location") or ""),
-                    "description":  _safe_str(e.get("description") or e.get("summary") or "")[:300],
-                    "url":          _safe_str(e.get("url") or ""),
-                    "registration": bool(e.get("registration") or e.get("seats")),
-                    "campus":       _safe_str(e.get("campus") or ""),
-                    "category":     cat_str,
-                })
-            _libcal_events_cache[cache_key] = {"data": events, "cached_at": now}
-            logger.info("LibCal: %d events fetched", len(events))
-            return events
-    except Exception as exc:
-        logger.warning("LibCal events fetch failed: %s", exc)
-        return None
-
-
-def _format_event_datetime(start: str, end: str, all_day: bool) -> str:
-    if not start:
-        return ""
-    try:
-        from datetime import datetime as _dt
-        s = _dt.fromisoformat(start.replace("Z", "+00:00"))
-        date_str = s.strftime("%a %d %b")
-        if all_day:
-            return date_str
-        time_str = s.strftime("%I:%M %p").lstrip("0")
-        if end:
-            e = _dt.fromisoformat(end.replace("Z", "+00:00"))
-            end_str = e.strftime("%I:%M %p").lstrip("0")
-            return f"{date_str} · {time_str} – {end_str}"
-        return f"{date_str} · {time_str}"
-    except Exception:
-        return start[:16].replace("T", " ")
-
-
-async def _events_answer(days: int = 30) -> str:
-    EVENTS_URL = "https://kustar.libcal.com/calendar/events"
-    events = await _libcal_fetch_events(days=days, limit=15)
-    if not events:
-        return (
-            "<strong>📅 Khalifa University Library Events</strong><br><br>"
-            "Live event data is currently unavailable. Browse all upcoming events here:<br>"
-            f'<a href="{EVENTS_URL}" target="_blank" '
-            f'style="font-weight:700;color:#003366">{EVENTS_URL}</a>'
-        )
-    if not events:
-        return (
-            "<strong>📅 Khalifa University Library Events</strong><br><br>"
-            f"No upcoming events found in the next {days} days.<br><br>"
-            f'Browse the full calendar: <a href="{EVENTS_URL}" target="_blank"'
-            f' style="font-weight:700;color:#003366">{EVENTS_URL}</a>'
-        )
-    answer = f"<strong>📅 Upcoming Library Events, Workshops & Training</strong> (next {days} days)<br><br>"
-    for ev in events[:10]:
-        title    = _escape(str(ev.get("title") or "Untitled Event"))
-        when     = _format_event_datetime(
-            str(ev.get("start") or ""), str(ev.get("end") or ""), bool(ev.get("allDay"))
-        )
-        location = _escape(str(ev.get("location") or ""))
-        desc     = _escape(str(ev.get("description") or ""))
-        url      = str(ev.get("url") or EVENTS_URL)
-        reg      = bool(ev.get("registration"))
-        answer += (
-            f'<div style="margin-bottom:12px;padding:10px 12px;border-left:3px solid #003366;'
-            f'background:#f8fafc;border-radius:0 8px 8px 0">'
-            f'<div style="font-weight:700;font-size:.88rem;color:#003366">'
-            f'<a href="{url}" target="_blank" style="color:#003366;text-decoration:none">{title}</a></div>'
-        )
-        if when:
-            answer += f'<div style="font-size:.80rem;color:#374151;margin-top:2px">🕐 {when}</div>'
-        if location:
-            answer += f'<div style="font-size:.80rem;color:#374151">📍 {location}</div>'
-        if desc:
-            answer += f'<div style="font-size:.78rem;color:#6b7280;margin-top:4px">{desc[:180]}{"…" if len(desc) > 180 else ""}</div>'
-        if reg:
-            answer += (
-                f'<div style="margin-top:5px">'
-                f'<a href="{url}" target="_blank" '
-                f'style="font-size:.76rem;font-weight:700;color:#003366;'
-                f'padding:3px 10px;border:1px solid #003366;border-radius:6px;text-decoration:none">'
-                f'Register →</a></div>'
-            )
-        answer += '</div>'
-    answer += (
-        f'<br><a href="{EVENTS_URL}" target="_blank" '
-        f'style="font-weight:700;color:#003366">View full library events calendar →</a>'
-    )
-    return answer
-
-
+"""LibCal client + formatting: live opening hours and events via the Cloudflare Worker proxy."""
+import asyncio
+import html
+import json
+import logging
+import os
+import re
+import time
+import uuid
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from src.config import get_settings, LIBBEE_VERSION
+
+from src.agentcore.constants import LIBRARY_HOURS_URL
+from src.agentcore.utils import _escape
+
+logger = logging.getLogger(__name__)
+
+_libcal_hours_cache: Dict[str, Any] = {}
+
+
+_LIBCAL_HOURS_TTL = 60 * 60
+
+
+async def _libcal_fetch_hours() -> Optional[dict]:
+    now = time.time()
+    cached_at = _libcal_hours_cache.get("cached_at", 0)
+    if _libcal_hours_cache.get("data") and now - cached_at < _LIBCAL_HOURS_TTL:
+        return _libcal_hours_cache["data"]
+    settings = get_settings()
+    worker_url = getattr(settings, "cloudflare_worker_url", "").strip()
+    if not worker_url:
+        logger.warning("LibCal: CLOUDFLARE_WORKER_URL not set — cannot fetch hours")
+        return None
+    from datetime import timezone, timedelta
+    uae_now   = datetime.now(timezone(timedelta(hours=4)))
+    date_from = uae_now.strftime("%Y-%m-%d")
+    date_to   = (uae_now + timedelta(days=6)).strftime("%Y-%m-%d")
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            r = await client.get(
+                f"{worker_url.rstrip('/')}/hours",
+                params={"from": date_from, "to": date_to},
+            )
+            r.raise_for_status()
+            data = r.json()
+            if data.get("error"):
+                logger.warning("LibCal worker error: %s", data["error"])
+                return None
+            _libcal_hours_cache["data"]      = data
+            _libcal_hours_cache["cached_at"] = now
+            logger.info("LibCal: hours refreshed via worker")
+            return data
+    except Exception as exc:
+        logger.warning("LibCal hours fetch failed: %s", exc)
+        return None
+
+
+def _parse_libcal_time(raw: str) -> str:
+    if not raw:
+        return raw
+    raw = raw.strip().replace("\u2013", "-").replace("–", "-")
+    raw = re.sub(r"\s+", "", raw)
+    raw = re.sub(r"(?i)(am|pm)$", lambda m: " " + m.group(1).upper(), raw)
+    return raw
+
+
+def _format_libcal_day(day_data: dict) -> str:
+    if not day_data or not isinstance(day_data, dict):
+        return "See hours page"
+    status = str(day_data.get("status") or "").lower().strip()
+    note   = str(day_data.get("note") or "").strip()
+    if status in ("closed", "0", "false"):
+        return f"Closed{f' — {note}' if note else ''}"
+    if status == "24hours":
+        return "Open 24 hours"
+    hours_list = day_data.get("hours") or []
+    if hours_list and isinstance(hours_list, list):
+        first = hours_list[0]
+        f = first.get("from") or first.get("opens") or ""
+        t = first.get("to")   or first.get("closes") or ""
+        if f and t:
+            return f"{_parse_libcal_time(f)} – {_parse_libcal_time(t)}"
+    opens  = day_data.get("opens")  or day_data.get("open")  or ""
+    closes = day_data.get("closes") or day_data.get("close") or ""
+    if opens and closes:
+        return f"{_parse_libcal_time(opens)} – {_parse_libcal_time(closes)}"
+    times = day_data.get("times") or []
+    if times and isinstance(times, list):
+        first = times[0]
+        f = first.get("from") or first.get("opens") or ""
+        t = first.get("to")   or first.get("closes") or ""
+        if f and t:
+            return f"{_parse_libcal_time(f)} – {_parse_libcal_time(t)}"
+    if status in ("open",):
+        return "Open — see hours page for times"
+    return "See hours page"
+
+
+async def _hours_answer() -> str:
+    from datetime import timezone, timedelta
+    uae_now  = datetime.now(timezone(timedelta(hours=4)))
+    today_str = uae_now.strftime("%Y-%m-%d")
+    day_names = ["Monday","Tuesday","Wednesday","Thursday","Friday","Saturday","Sunday"]
+    today_name = day_names[uae_now.weekday()]
+    hours_data = await _libcal_fetch_hours()
+    if not hours_data:
+        return (
+            "Here are the <strong>Khalifa University Library</strong> hours:<br><br>"
+            "⚠️ Live hours are currently unavailable. Please check the official schedule:<br>"
+            f'<a href="{LIBRARY_HOURS_URL}" target="_blank" '
+            f'style="font-weight:700;color:#003366">{LIBRARY_HOURS_URL}</a><br><br>'
+            "<strong>📍 Contacts:</strong><br>"
+            'Main Campus Library · E Building · <a href="tel:+97123124604">+971 2 312 4604</a><br>'
+            'Habshan Library · SAN Campus · <a href="tel:+97123123160">+971 2 312 3160</a>'
+        )
+    location_labels = {
+        "main_campus": "Main Campus Library",
+        "habshan":     "Habshan Library (SAN Campus)",
+    }
+    def _today_line(loc_name: str, loc_data: dict) -> str:
+        dates = loc_data.get("dates", {})
+        today_entry = dates.get(today_str, {})
+        if not today_entry:
+            return f"<em>See <a href='{LIBRARY_HOURS_URL}' target='_blank'>live hours</a> for today</em>"
+        hours_str = _format_libcal_day(today_entry)
+        is_closed = hours_str.lower().startswith("closed")
+        colour = "#dc2626" if is_closed else "#16a34a"
+        return (
+            f"📅 <strong>Today ({today_name}):</strong> "
+            f"<span style='color:{colour};font-weight:700'>{hours_str}</span>"
+        )
+    def _week_table(loc_data: dict) -> str:
+        dates = loc_data.get("dates", {})
+        if not dates:
+            return ""
+        rows = ""
+        for date_key in sorted(dates.keys())[:7]:
+            try:
+                from datetime import date as _date
+                d = _date.fromisoformat(date_key)
+                day_label = d.strftime("%a %d %b")
+                is_today  = date_key == today_str
+            except ValueError:
+                day_label = date_key
+                is_today  = False
+            hours_str = _format_libcal_day(dates[date_key])
+            is_closed = hours_str.lower().startswith("closed")
+            colour    = "#dc2626" if is_closed else "#16a34a"
+            weight    = "700" if is_today else "400"
+            bg        = "#fffbeb" if is_today else "transparent"
+            rows += (
+                f"<tr style='background:{bg}'>"
+                f"<td style='padding:3px 12px 3px 0;color:#374151;font-weight:{weight}'>{day_label}</td>"
+                f"<td style='padding:3px 0;font-weight:600;color:{colour}'>{hours_str}</td>"
+                f"</tr>"
+            )
+        if not rows:
+            return ""
+        return (
+            "<table style='font-size:.84rem;border-collapse:collapse;width:100%;max-width:380px'>"
+            + rows + "</table>"
+        )
+    answer = "Here are the <strong>Khalifa University Library</strong> live hours:<br><br>"
+    for key, label in location_labels.items():
+        loc = hours_data.get(key)
+        if not loc:
+            continue
+        answer += f"<strong>📍 {label}</strong><br>"
+        answer += _today_line(label, loc) + "<br>"
+        week_tbl = _week_table(loc)
+        if week_tbl:
+            answer += week_tbl + "<br><br>"
+        else:
+            answer += "<br>"
+    answer += (
+        "⚠️ <strong>Hours may change during Ramadan, public holidays, and exam periods.</strong><br>"
+        f'Always confirm at: <a href="{LIBRARY_HOURS_URL}" target="_blank" '
+        f'style="font-weight:700;color:#003366">{LIBRARY_HOURS_URL}</a><br><br>'
+        '<span style="font-size:.82rem;color:#6b7280">'
+        'Main Campus Library · E Building · <a href="tel:+97123124604">+971 2 312 4604</a><br>'
+        'Habshan Library · Building 5, SAN Campus · <a href="tel:+97123123160">+971 2 312 3160</a>'
+        '</span>'
+    )
+    return answer
+
+
+_libcal_events_cache: Dict[str, Any] = {}
+
+
+_LIBCAL_EVENTS_TTL = 30 * 60
+
+
+async def _libcal_fetch_events(days: int = 30, limit: int = 10) -> Optional[list]:
+    now = time.time()
+    cache_key = f"{days}_{limit}"
+    cached = _libcal_events_cache.get(cache_key, {})
+    if cached.get("data") and now - cached.get("cached_at", 0) < _LIBCAL_EVENTS_TTL:
+        return cached["data"]
+    settings = get_settings()
+    worker_url = getattr(settings, "cloudflare_worker_url", "").strip()
+    if not worker_url:
+        logger.warning("LibCal events: CLOUDFLARE_WORKER_URL not set")
+        return None
+    try:
+        async with httpx.AsyncClient(timeout=10) as client:
+            r = await client.get(
+                f"{worker_url.rstrip('/')}/events",
+                params={"days": days, "limit": limit},
+            )
+            r.raise_for_status()
+            data = r.json()
+            if data.get("error"):
+                logger.warning("LibCal events worker error: %s", data["error"])
+                return None
+            events_raw = data.get("events", [])
+            def _safe_str(val) -> str:
+                if val is None:
+                    return ""
+                if isinstance(val, str):
+                    return val
+                if isinstance(val, dict):
+                    return str(val.get("name") or val.get("title") or "")
+                if isinstance(val, list):
+                    return ", ".join(_safe_str(v) for v in val if v)
+                return str(val)
+            events = []
+            for e in events_raw:
+                cats = e.get("category") or e.get("categories") or []
+                if isinstance(cats, list):
+                    cat_str = ", ".join(_safe_str(c) for c in cats)
+                else:
+                    cat_str = _safe_str(cats)
+                events.append({
+                    "id":           e.get("id", ""),
+                    "title":        _safe_str(e.get("title") or "Untitled Event"),
+                    "start":        _safe_str(e.get("start") or ""),
+                    "end":          _safe_str(e.get("end") or ""),
+                    "allDay":       bool(e.get("allday") or e.get("allDay")),
+                    "location":     _safe_str(e.get("location") or ""),
+                    "description":  _safe_str(e.get("description") or e.get("summary") or "")[:300],
+                    "url":          _safe_str(e.get("url") or ""),
+                    "registration": bool(e.get("registration") or e.get("seats")),
+                    "campus":       _safe_str(e.get("campus") or ""),
+                    "category":     cat_str,
+                })
+            _libcal_events_cache[cache_key] = {"data": events, "cached_at": now}
+            logger.info("LibCal: %d events fetched", len(events))
+            return events
+    except Exception as exc:
+        logger.warning("LibCal events fetch failed: %s", exc)
+        return None
+
+
+def _format_event_datetime(start: str, end: str, all_day: bool) -> str:
+    if not start:
+        return ""
+    try:
+        from datetime import datetime as _dt
+        s = _dt.fromisoformat(start.replace("Z", "+00:00"))
+        date_str = s.strftime("%a %d %b")
+        if all_day:
+            return date_str
+        time_str = s.strftime("%I:%M %p").lstrip("0")
+        if end:
+            e = _dt.fromisoformat(end.replace("Z", "+00:00"))
+            end_str = e.strftime("%I:%M %p").lstrip("0")
+            return f"{date_str} · {time_str} – {end_str}"
+        return f"{date_str} · {time_str}"
+    except Exception:
+        return start[:16].replace("T", " ")
+
+
+async def _events_answer(days: int = 30) -> str:
+    EVENTS_URL = "https://kustar.libcal.com/calendar/events"
+    events = await _libcal_fetch_events(days=days, limit=15)
+    if not events:
+        return (
+            "<strong>📅 Khalifa University Library Events</strong><br><br>"
+            "Live event data is currently unavailable. Browse all upcoming events here:<br>"
+            f'<a href="{EVENTS_URL}" target="_blank" '
+            f'style="font-weight:700;color:#003366">{EVENTS_URL}</a>'
+        )
+    if not events:
+        return (
+            "<strong>📅 Khalifa University Library Events</strong><br><br>"
+            f"No upcoming events found in the next {days} days.<br><br>"
+            f'Browse the full calendar: <a href="{EVENTS_URL}" target="_blank"'
+            f' style="font-weight:700;color:#003366">{EVENTS_URL}</a>'
+        )
+    answer = f"<strong>📅 Upcoming Library Events, Workshops & Training</strong> (next {days} days)<br><br>"
+    for ev in events[:10]:
+        title    = _escape(str(ev.get("title") or "Untitled Event"))
+        when     = _format_event_datetime(
+            str(ev.get("start") or ""), str(ev.get("end") or ""), bool(ev.get("allDay"))
+        )
+        location = _escape(str(ev.get("location") or ""))
+        desc     = _escape(str(ev.get("description") or ""))
+        url      = str(ev.get("url") or EVENTS_URL)
+        reg      = bool(ev.get("registration"))
+        answer += (
+            f'<div style="margin-bottom:12px;padding:10px 12px;border-left:3px solid #003366;'
+            f'background:#f8fafc;border-radius:0 8px 8px 0">'
+            f'<div style="font-weight:700;font-size:.88rem;color:#003366">'
+            f'<a href="{url}" target="_blank" style="color:#003366;text-decoration:none">{title}</a></div>'
+        )
+        if when:
+            answer += f'<div style="font-size:.80rem;color:#374151;margin-top:2px">🕐 {when}</div>'
+        if location:
+            answer += f'<div style="font-size:.80rem;color:#374151">📍 {location}</div>'
+        if desc:
+            answer += f'<div style="font-size:.78rem;color:#6b7280;margin-top:4px">{desc[:180]}{"…" if len(desc) > 180 else ""}</div>'
+        if reg:
+            answer += (
+                f'<div style="margin-top:5px">'
+                f'<a href="{url}" target="_blank" '
+                f'style="font-size:.76rem;font-weight:700;color:#003366;'
+                f'padding:3px 10px;border:1px solid #003366;border-radius:6px;text-decoration:none">'
+                f'Register →</a></div>'
+            )
+        answer += '</div>'
+    answer += (
+        f'<br><a href="{EVENTS_URL}" target="_blank" '
+        f'style="font-weight:700;color:#003366">View full library events calendar →</a>'
+    )
+    return answer
+
+

src/agentcore/models.py

@@ -1,71 +1,69 @@
-"""Pydantic request/response models shared across the pipeline (Stage 0: I/O contracts)."""
-import asyncio
-import html
-import json
-import logging
-import os
-import re
-import time
-import uuid
-from datetime import datetime
-from typing import Any, Dict, List, Literal, Optional, Tuple
-from urllib.parse import quote
+"""Strict request and response contracts for the LibBee agent."""
 
-import httpx
-from pydantic import BaseModel, ConfigDict, Field
+import time
+from typing import Literal, Optional
 
-from src.config import get_settings, LIBBEE_VERSION
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
-logger = logging.getLogger(__name__)
 
 class ChatMessage(BaseModel):
-    role: str
-    content: str
+    model_config = ConfigDict(extra="forbid")
+    role: Literal["user", "assistant"]
+    content: str = Field(min_length=1, max_length=4000)
 
 
 class SearchContextPayload(BaseModel):
-    context_id: str
-    topic: str
-    display_topic: Optional[str] = None
-    intent: str = "search_academic"
-    source: str = "primo"
-    resource_type: str = "articles"   # "articles" | "books" | "both"
+    model_config = ConfigDict(extra="ignore")
+    context_id: str = Field(min_length=1, max_length=80)
+    topic: str = Field(min_length=1, max_length=500)
+    display_topic: Optional[str] = Field(default=None, max_length=500)
+    intent: Literal["search_academic", "search_medical"] = "search_academic"
+    source: Literal["primo", "pubmed"] = "primo"
+    resource_type: Literal["articles", "books", "both"] = "articles"
     peer_reviewed: bool = False
     open_access: bool = False
-    year_from: Optional[str] = None
-    year_to: Optional[str] = None
-    ai_tool_query: Optional[str] = None
-    primo_boolean_query: Optional[str] = None
+    year_from: Optional[str] = Field(default=None, pattern=r"^\d{4}$")
+    year_to: Optional[str] = Field(default=None, pattern=r"^\d{4}$")
+    ai_tool_query: Optional[str] = Field(default=None, max_length=1000)
+    primo_boolean_query: Optional[str] = Field(default=None, max_length=1500)
     created_at: float = Field(default_factory=time.time)
-    # v3.8 — ambiguity gate
     clarification_needed: bool = False
-    clarification_message: Optional[str] = None
+    clarification_message: Optional[str] = Field(default=None, max_length=500)
+
+    @field_validator("year_to")
+    @classmethod
+    def years_in_order(cls, value: Optional[str], info):
+        start = info.data.get("year_from")
+        if value and start and int(value) < int(start):
+            raise ValueError("year_to must not be earlier than year_from")
+        return value
 
 
 class ClientStatePayload(BaseModel):
-    session_id: Optional[str] = None
-    active_search_context_id: Optional[str] = None
-    recent_search_contexts: List[SearchContextPayload] = Field(default_factory=list)
-    follow_up_action: Optional[str] = None
-    follow_up_context_id: Optional[str] = None
+    model_config = ConfigDict(extra="ignore")
+    session_id: Optional[str] = Field(default=None, pattern=r"^[A-Za-z0-9_-]{8,80}$")
+    active_search_context_id: Optional[str] = Field(default=None, max_length=80)
+    recent_search_contexts: list[SearchContextPayload] = Field(default_factory=list, max_length=5)
+    follow_up_action: Optional[str] = Field(default=None, max_length=80)
+    follow_up_context_id: Optional[str] = Field(default=None, max_length=80)
 
 
 class AgentRequest(BaseModel):
-    question: str
-    # FIX: validated literal — malformed model values caught at Pydantic layer
+    model_config = ConfigDict(extra="forbid")
+    question: str = Field(min_length=1, max_length=2000)
     model: Literal["gpt", "claude"] = "gpt"
-    history: List[ChatMessage] = Field(default_factory=list)
+    history: list[ChatMessage] = Field(default_factory=list, max_length=12)
     client_state: Optional[ClientStatePayload] = None
 
 
 class AgentResponse(BaseModel):
     model_config = ConfigDict(extra="ignore")
-
+    request_id: str = ""
     answer: str
     intent: str = "general"
-    tools_used: List[str] = Field(default_factory=list)
-    search_results: List[dict] = Field(default_factory=list)
-    sources: List[dict] = Field(default_factory=list)
+    tools_used: list[str] = Field(default_factory=list)
+    search_results: list[dict] = Field(default_factory=list)
+    sources: list[dict] = Field(default_factory=list)
     model_used: str = "gpt"
     response_time: float = 0
     corrected_query: Optional[str] = None
@@ -74,12 +72,10 @@ class AgentResponse(BaseModel):
     ask_librarian: Optional[bool] = None
     is_follow_up: bool = False
     follow_up_question: Optional[str] = None
-    follow_up_suggestions: List[dict] = Field(default_factory=list)
+    follow_up_suggestions: list[dict] = Field(default_factory=list)
     search_context: Optional[dict] = None
     ai_tool_query: Optional[str] = None
     primo_boolean_query: Optional[str] = None
     primo_search_url: Optional[str] = None
     primo_ai_url: Optional[str] = None
     pubmed_search_url: Optional[str] = None
-
-

src/agentcore/orchestrator.py

@@ -1,1049 +1,971 @@
-"""Stage 4 orchestration: the seven-intent routing pipeline (_agent_query_inner) and D1 logging."""
-import asyncio
-import html
-import json
-import logging
-import os
-import re
-import time
-import uuid
-from collections import deque
-from datetime import datetime
-from typing import Any, Dict, List, Literal, Optional, Tuple
-from urllib.parse import quote
-
-import httpx
-from pydantic import BaseModel, ConfigDict, Field
-
-from src.config import get_settings, LIBBEE_VERSION
-from src.services.staff_service import (
-    STAFF_DIRECTORY,
-    match_staff_name,
-    match_staff_role,
-    should_attempt_staff_lookup,
-    staff_name_answer,
-    staff_role_answer,
-)
-
-from src.agentcore.models import AgentResponse, SearchContextPayload
-from src.agentcore.constants import (
-    ALT_TERMS_RE,
-    ASK_LIBRARIAN_URL,
-    BOOLEAN_STRATEGY_RE,
-    CITATION_CHAIN_RE,
-    DUAL_RESOURCE_RE,
-    EVENTS_RE,
-    FULLTEXT_REQUEST_RE,
-    HIGHLY_CITED_RE,
-    LIBRARY_HOURS_URL,
-    PARTIAL_TITLE_RE,
-    PREDATORY_RE,
-    PURE_GREETING_RE,
-    THESES_RE,
-    _INJECTION_RE,
-)
-from src.agentcore.utils import (
-    _escape,
-    _get_runtime_config,
-    _light_strip_retrieval_boilerplate,
-    _normalize_whitespace,
-    _primo_clean_url,
-    _safe_metrics_bucket,
-    _safe_metrics_increment,
-    _title_case_topic,
-)
-from src.agentcore.classify import (
-    _is_greeting_menu_followup,
-    _is_summary_request,
-    _llm_classify,
-    _looks_campus_question,
-    _looks_library_hours_question,
-)
-from src.agentcore.libcal import _events_answer, _hours_answer
-from src.agentcore.rendering import (
-    _ai_tools_footer,
-    _contact_footer_for_query,
-    _search_trace_block,
-    _source_badge,
-    _thought_block,
-    _tool_urls,
-)
-from src.agentcore.intents_library import (
-    _campus_answer,
-    _database_recommendation_answer,
-    _fulltext_chain_answer,
-    _greeting_menu_clarify_answer,
-    _is_database_recommendation_question,
-    _library_follow_up,
-    _rag_answer,
-    _theses_answer,
-)
-from src.agentcore.intents_search import (
-    _alternative_terms_answer,
-    _apply_follow_up_action,
-    _citation_chain_answer,
-    _context_to_dict,
-    _derive_resource_type,
-    _detect_follow_up,
-    _extract_topic,
-    _highly_cited_note,
-    _parse_year_filters,
-    _predatory_eval_answer,
-    _prepare_queries,
-    _research_snapshot,
-    _run_search_mode,
-    _search_follow_up,
-    _search_strategy_answer,
-)
-from src.agentcore.intents_general import (
-    _general_follow_up,
-    _libbee_casual_response,
-    _social_follow_up,
-    _web_search_answer,
-)
-
-logger = logging.getLogger(__name__)
-
-_EMAIL_RE = re.compile(r"[\w.+-]+@[\w-]+\.[\w.-]+")
-_LONG_DIGITS_RE = re.compile(r"\d{6,}")
-_TAG_RE = re.compile(r"<[^>]+>")
-
-
-# Strong references to in-flight analytics POSTs.
-#
-# asyncio keeps only WEAK references to tasks: a task created with
-# create_task() and then dropped can be garbage-collected before it finishes,
-# silently cancelling the request. That is invisible when the network is fast
-# and drops writes unpredictably when the handshake is slow. Holding a
-# reference until the task completes is the documented fix.
-_ANALYTICS_TASKS = set()
-
-
-def _spawn_background(coro) -> bool:
-    """Run coro in the background, keeping a strong reference. True if scheduled."""
-    try:
-        loop = asyncio.get_running_loop()
-    except RuntimeError:
-        try:
-            loop = asyncio.get_event_loop()
-        except Exception:
-            return False
-    if not loop.is_running():
-        return False
-    task = loop.create_task(coro)
-    _ANALYTICS_TASKS.add(task)
-    task.add_done_callback(_ANALYTICS_TASKS.discard)
-    return True
-
-
-def _redact_for_analytics(text: str, max_len: int = 200) -> str:
-    """Privacy pass before anything reaches the analytics store: e-mail
-    addresses and long digit runs (IDs, phone numbers) are masked and the
-    text is truncated. Raw personal identifiers must never be persisted."""
-    text = _EMAIL_RE.sub("[email]", text or "")
-    text = _LONG_DIGITS_RE.sub("[number]", text)
-    return text[:max_len]
-
-
-def _answer_excerpt(answer_html: str, max_len: int = 800) -> str:
-    """Plain-text excerpt of the rendered answer for offline relevance grading
-    by the daily KB-gap agent. HTML is stripped and the same redaction applied."""
-    text = _TAG_RE.sub(" ", answer_html or "")
-    text = re.sub(r"\s+", " ", text).strip()
-    return _redact_for_analytics(text, max_len)
-
-
-# ── Analytics retry buffer ───────────────────────────────────────────────────
-# Transient failures reaching the Worker (rate limiting, connection resets)
-# previously meant the row was lost for good. Failed payloads are parked here
-# and re-attempted on subsequent queries, so a blocked window costs a delay
-# rather than data. Bounded so a long outage cannot grow memory without limit.
-
-_PENDING_LOGS: "deque" = deque(maxlen=200)
-_PENDING_DROPPED = {"count": 0}
-
-# Rolling record of the last few analytics-write attempts, so the outcome can be
-# inspected through /admin/log-status without access to container logs.
-_LOG_ATTEMPTS: "deque" = deque(maxlen=15)
-
-
-def _record_attempt(outcome: str, detail: str = "") -> None:
-    _LOG_ATTEMPTS.append({
-        "at": datetime.utcnow().strftime("%Y-%m-%d %H:%M:%S"),
-        "outcome": outcome,
-        "detail": detail[:200],
-    })
-
-
-def analytics_log_status() -> dict:
-    """Snapshot of the analytics write path for the admin dashboard."""
-    return {
-        "pending_buffered": len(_PENDING_LOGS),
-        "buffer_capacity": _PENDING_LOGS.maxlen,
-        "recent_attempts": list(_LOG_ATTEMPTS)[::-1],
-    }
-
-
-async def _send_with_retry(worker_url: str, token: str, payload: dict,
-                           attempts: int = 2, backoff: float = 2.0):
-    """_send_log_payload with one retry after a short backoff. Connectivity to
-    workers.dev from this host drops for short windows; a single immediate
-    retry recovers a meaningful fraction of those without involving the buffer."""
-    last_exc = None
-    for i in range(attempts):
-        try:
-            return await _send_log_payload(worker_url, token, payload)
-        except Exception as exc:
-            last_exc = exc
-            if i + 1 < attempts:
-                await asyncio.sleep(backoff)
-    raise last_exc
-
-
-async def _send_log_payload(worker_url: str, token: str, payload: dict):
-    """POST one analytics payload.
+"""Stage 4 orchestration: the seven-intent routing pipeline (_agent_query_inner) and D1 logging."""
+import asyncio
+import html
+import json
+import logging
+import os
+import re
+import time
+import uuid
+from collections import deque
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from src.config import get_settings, LIBBEE_VERSION
+from src.services.staff_service import (
+    STAFF_DIRECTORY,
+    match_staff_name,
+    match_staff_role,
+    should_attempt_staff_lookup,
+    staff_name_answer,
+    staff_role_answer,
+)
+
+from src.agentcore.models import AgentResponse, SearchContextPayload
+from src.agentcore.constants import (
+    ALT_TERMS_RE,
+    ASK_LIBRARIAN_URL,
+    BOOLEAN_STRATEGY_RE,
+    CITATION_CHAIN_RE,
+    DUAL_RESOURCE_RE,
+    EVENTS_RE,
+    FULLTEXT_REQUEST_RE,
+    HIGHLY_CITED_RE,
+    LIBRARY_HOURS_URL,
+    PARTIAL_TITLE_RE,
+    PREDATORY_RE,
+    PURE_GREETING_RE,
+    THESES_RE,
+    _INJECTION_RE,
+)
+from src.agentcore.utils import (
+    _escape,
+    _get_runtime_config,
+    _light_strip_retrieval_boilerplate,
+    _normalize_whitespace,
+    _primo_clean_url,
+    _safe_metrics_bucket,
+    _safe_metrics_increment,
+    _title_case_topic,
+)
+from src.agentcore.classify import (
+    _is_greeting_menu_followup,
+    _is_summary_request,
+    _llm_classify,
+    _looks_campus_question,
+    _looks_library_hours_question,
+)
+from src.agentcore.libcal import _events_answer, _hours_answer
+from src.agentcore.rendering import (
+    _ai_tools_footer,
+    _contact_footer_for_query,
+    _search_trace_block,
+    _source_badge,
+    _thought_block,
+    _tool_urls,
+)
+from src.agentcore.intents_library import (
+    _campus_answer,
+    _database_recommendation_answer,
+    _fulltext_chain_answer,
+    _greeting_menu_clarify_answer,
+    _is_database_recommendation_question,
+    _library_follow_up,
+    _rag_answer,
+    _theses_answer,
+)
+from src.agentcore.intents_search import (
+    _alternative_terms_answer,
+    _apply_follow_up_action,
+    _citation_chain_answer,
+    _context_to_dict,
+    _derive_resource_type,
+    _detect_follow_up,
+    _extract_topic,
+    _highly_cited_note,
+    _parse_year_filters,
+    _predatory_eval_answer,
+    _prepare_queries,
+    _research_snapshot,
+    _run_search_mode,
+    _search_follow_up,
+    _search_strategy_answer,
+)
+from src.agentcore.intents_general import (
+    _general_follow_up,
+    _libbee_casual_response,
+    _social_follow_up,
+    _web_search_answer,
+)
+
+logger = logging.getLogger(__name__)
+
+_EMAIL_RE = re.compile(r"[\w.+-]+@[\w-]+\.[\w.-]+")
+_LONG_DIGITS_RE = re.compile(r"\d{6,}")
+_TAG_RE = re.compile(r"<[^>]+>")
+
+
+# Strong references to in-flight analytics POSTs.
+#
+# asyncio keeps only WEAK references to tasks: a task created with
+# create_task() and then dropped can be garbage-collected before it finishes,
+# silently cancelling the request. That is invisible when the network is fast
+# and drops writes unpredictably when the handshake is slow. Holding a
+# reference until the task completes is the documented fix.
+_ANALYTICS_TASKS = set()
+
+
+def _spawn_background(coro) -> bool:
+    """Run coro in the background, keeping a strong reference. True if scheduled."""
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        try:
+            loop = asyncio.get_event_loop()
+        except Exception:
+            return False
+    if not loop.is_running():
+        return False
+    task = loop.create_task(coro)
+    _ANALYTICS_TASKS.add(task)
+    task.add_done_callback(_ANALYTICS_TASKS.discard)
+    return True
+
+
+def _redact_for_analytics(text: str, max_len: int = 200) -> str:
+    """Privacy pass before anything reaches the analytics store: e-mail
+    addresses and long digit runs (IDs, phone numbers) are masked and the
+    text is truncated. Raw personal identifiers must never be persisted."""
+    text = _EMAIL_RE.sub("[email]", text or "")
+    text = _LONG_DIGITS_RE.sub("[number]", text)
+    return text[:max_len]
+
+
+def _answer_excerpt(answer_html: str, max_len: int = 800) -> str:
+    """Plain-text excerpt of the rendered answer for offline relevance grading
+    by the daily KB-gap agent. HTML is stripped and the same redaction applied."""
+    text = _TAG_RE.sub(" ", answer_html or "")
+    text = re.sub(r"\s+", " ", text).strip()
+    return _redact_for_analytics(text, max_len)
+
+
+# ── Analytics retry buffer ───────────────────────────────────────────────────
+# Transient failures reaching the Worker (rate limiting, connection resets)
+# previously meant the row was lost for good. Failed payloads are parked here
+# and re-attempted on subsequent queries, so a blocked window costs a delay
+# rather than data. Bounded so a long outage cannot grow memory without limit.
+
+_PENDING_LOGS: "deque" = deque(maxlen=200)
+_PENDING_DROPPED = {"count": 0}
+
+# Rolling record of the last few analytics-write attempts, so the outcome can be
+# inspected through /admin/log-status without access to container logs.
+_LOG_ATTEMPTS: "deque" = deque(maxlen=15)
+
+
+def _record_attempt(outcome: str, detail: str = "") -> None:
+    _LOG_ATTEMPTS.append({
+        "at": datetime.utcnow().strftime("%Y-%m-%d %H:%M:%S"),
+        "outcome": outcome,
+        "detail": detail[:200],
+    })
+
+
+def analytics_log_status() -> dict:
+    """Snapshot of the analytics write path for the admin dashboard."""
+    return {
+        "pending_buffered": len(_PENDING_LOGS),
+        "buffer_capacity": _PENDING_LOGS.maxlen,
+        "recent_attempts": list(_LOG_ATTEMPTS)[::-1],
+    }
+
+
+async def _send_with_retry(worker_url: str, token: str, payload: dict,
+                           attempts: int = 2, backoff: float = 2.0):
+    """_send_log_payload with one retry after a short backoff. Connectivity to
+    workers.dev from this host drops for short windows; a single immediate
+    retry recovers a meaningful fraction of those without involving the buffer."""
+    last_exc = None
+    for i in range(attempts):
+        try:
+            return await _send_log_payload(worker_url, token, payload)
+        except Exception as exc:
+            last_exc = exc
+            if i + 1 < attempts:
+                await asyncio.sleep(backoff)
+    raise last_exc
+
+
+async def _send_log_payload(worker_url: str, token: str, payload: dict):
+    """POST one analytics payload.
+
+    Returns (status_code, report) where report is the Worker's own JSON verdict.
+    This matters because the Worker answers HTTP 200 even when the D1 INSERT
+    itself failed, reporting the problem in a 'warning' field - so a status code
+    alone cannot distinguish a stored row from a dropped one.
+    """
+    from src.services.http_client import make_client as _mk
+    headers = {"Authorization": f"Bearer {token}"} if token else {}
+    async with _mk(timeout=10) as client:
+        resp = await client.post(worker_url.rstrip("/") + "/log",
+                                 json=payload, headers=headers)
+    report = {}
+    try:
+        body = resp.json()
+        if isinstance(body, dict):
+            report = {k: body.get(k) for k in ("status", "logged", "schema", "warning")
+                      if body.get(k) is not None}
+    except Exception:
+        report = {"raw": resp.text[:120]}
+    return resp.status_code, report
+
+
+_FLUSHER_STARTED = {"on": False}
+
+
+def _ensure_periodic_flusher(worker_url: str, token: str) -> None:
+    """Start (once) a background loop that retries buffered rows every 90s, so
+    parked writes land as soon as connectivity returns instead of waiting for
+    the next user query. The task holds a strong reference via _spawn_background.
+    Lost on container restart - like the buffer itself - which the keep-alive
+    pings are there to make rare."""
+    if _FLUSHER_STARTED["on"]:
+        return
+
+    async def _loop():
+        while True:
+            await asyncio.sleep(90)
+            if _PENDING_LOGS:
+                try:
+                    n = await _flush_pending(worker_url, token, max_items=10)
+                    if n:
+                        _record_attempt("flushed", f"{n} buffered row(s) delivered")
+                except Exception:
+                    pass
+
+    if _spawn_background(_loop()):
+        _FLUSHER_STARTED["on"] = True
+        logger.info("Analytics flusher started (90s interval)")
+
+
+async def _flush_pending(worker_url: str, token: str, max_items: int = 5):
+    """Re-attempt parked payloads oldest-first; stop at the first failure so a
+    still-blocked Worker is not hammered."""
+    sent = 0
+    while _PENDING_LOGS and sent < max_items:
+        payload = _PENDING_LOGS[0]
+        try:
+            status, report = await _send_log_payload(worker_url, token, payload)
+        except Exception:
+            return sent
+        if status >= 400 or report.get("logged") is False:
+            return sent
+        _PENDING_LOGS.popleft()
+        sent += 1
+    if sent:
+        logger.info(f"D1 logging: flushed {sent} buffered row(s); "
+                    f"{len(_PENDING_LOGS)} still pending")
+    return sent
+
+
+def _log_agent_query(question: str, response: AgentResponse, start_time: float) -> None:
+    """Keep only local operational counters.
 
-    Returns (status_code, report) where report is the Worker's own JSON verdict.
-    This matters because the Worker answers HTTP 200 even when the D1 INSERT
-    itself failed, reporting the problem in a 'warning' field - so a status code
-    alone cannot distinguish a stored row from a dropped one.
+    Persistent analytics is written by the Cloudflare gateway after it receives
+    the origin response. This prevents duplicate rows and removes the old public
+    /log dependency.
     """
-    from src.services.http_client import make_client as _mk
-    headers = {"Authorization": f"Bearer {token}"} if token else {}
-    async with _mk(timeout=10) as client:
-        resp = await client.post(worker_url.rstrip("/") + "/log",
-                                 json=payload, headers=headers)
-    report = {}
-    try:
-        body = resp.json()
-        if isinstance(body, dict):
-            report = {k: body.get(k) for k in ("status", "logged", "schema", "warning")
-                      if body.get(k) is not None}
-    except Exception:
-        report = {"raw": resp.text[:120]}
-    return resp.status_code, report
-
-
-_FLUSHER_STARTED = {"on": False}
-
-
-def _ensure_periodic_flusher(worker_url: str, token: str) -> None:
-    """Start (once) a background loop that retries buffered rows every 90s, so
-    parked writes land as soon as connectivity returns instead of waiting for
-    the next user query. The task holds a strong reference via _spawn_background.
-    Lost on container restart - like the buffer itself - which the keep-alive
-    pings are there to make rare."""
-    if _FLUSHER_STARTED["on"]:
-        return
-
-    async def _loop():
-        while True:
-            await asyncio.sleep(90)
-            if _PENDING_LOGS:
-                try:
-                    n = await _flush_pending(worker_url, token, max_items=10)
-                    if n:
-                        _record_attempt("flushed", f"{n} buffered row(s) delivered")
-                except Exception:
-                    pass
-
-    if _spawn_background(_loop()):
-        _FLUSHER_STARTED["on"] = True
-        logger.info("Analytics flusher started (90s interval)")
-
-
-async def _flush_pending(worker_url: str, token: str, max_items: int = 5):
-    """Re-attempt parked payloads oldest-first; stop at the first failure so a
-    still-blocked Worker is not hammered."""
-    sent = 0
-    while _PENDING_LOGS and sent < max_items:
-        payload = _PENDING_LOGS[0]
-        try:
-            status, report = await _send_log_payload(worker_url, token, payload)
-        except Exception:
-            return sent
-        if status >= 400 or report.get("logged") is False:
-            return sent
-        _PENDING_LOGS.popleft()
-        sent += 1
-    if sent:
-        logger.info(f"D1 logging: flushed {sent} buffered row(s); "
-                    f"{len(_PENDING_LOGS)} still pending")
-    return sent
-
-
-def _log_agent_query(question: str, response: AgentResponse, start_time: float) -> None:
     elapsed = time.time() - start_time
-    intent = response.intent or ""
-    tool = ", ".join(response.tools_used or [])[:60]
-    model_used = response.model_used or ""
-    result_count = len(response.search_results or [])
-    try:
-        from app import get_metrics_service
-        get_metrics_service().log_query(
-            question=_redact_for_analytics(question),
-            intent=intent,
-            tool=tool,
-            model=model_used,
-            response_time=elapsed,
-            result_count=result_count,
-        )
+    intent = response.intent or ""
+    tool = ", ".join(response.tools_used or [])[:60]
+    model_used = response.model_used or ""
+    result_count = len(response.search_results or [])
+    try:
+        from app import get_metrics_service
+        get_metrics_service().log_query(
+            question=_redact_for_analytics(question),
+            intent=intent,
+            tool=tool,
+            model=model_used,
+            response_time=elapsed,
+            result_count=result_count,
+        )
     except Exception:
         pass
-    try:
-        settings = get_settings()
-        worker_url = getattr(settings, "cloudflare_worker_url", "") or ""
-        if worker_url:
-            if getattr(settings, "analytics_client_side", False):
-                # The browser posts this record to the Worker directly; skipping
-                # here avoids duplicate rows.
-                _record_attempt("client_side", "logged by browser")
-                return
-
-            _payload = {
-                "question": _redact_for_analytics(question),
-                "tool": f"{intent}:{tool}"[:80],
-                "model": model_used,
-                "response_time": round(elapsed, 3),
-                "result_count": result_count,
-                # consumed by the daily KB-gap / relevance agent
-                "answer_excerpt": _answer_excerpt(response.answer),
-                "source_ids": [
-                    str(src.get("source") or src.get("id") or "")[:60]
-                    for src in (response.sources or [])[:8]
-                ],
-            }
-            _token = getattr(settings, "cloudflare_worker_token", "") or ""
-
-            async def _post_to_worker():
-                # Drain anything parked by earlier failures first, then send this row.
-                try:
-                    await _flush_pending(worker_url, _token)
-                except Exception:
-                    pass
-                try:
-                    status, report = await _send_with_retry(worker_url, _token, _payload)
-                except Exception as _exc:
-                    _PENDING_LOGS.append(_payload)
-                    _record_attempt("unreachable", f"{type(_exc).__name__}: {_exc}")
-                    logger.warning(
-                        f"D1 logging unreachable ({type(_exc).__name__}: {_exc}); buffered "
-                        f"({len(_PENDING_LOGS)} pending)"
-                    )
-                    return
-                if status == 401:
-                    _record_attempt("rejected_401", "token mismatch")
-                    logger.error(
-                        "D1 logging rejected (401). CLOUDFLARE_WORKER_TOKEN does "
-                        "not match the Worker's ANALYTICS_TOKEN secret."
-                    )
-                elif status in (403, 429):
-                    _PENDING_LOGS.append(_payload)
-                    _record_attempt("throttled", f"HTTP {status}")
-                    logger.warning(
-                        f"D1 logging throttled or blocked (HTTP {status}); buffered "
-                        f"({len(_PENDING_LOGS)} pending). Repeated 403/429 from "
-                        f"workers.dev usually means Cloudflare is rate-limiting this "
-                        f"host; a custom domain on the Worker avoids it."
-                    )
-                elif status >= 400:
-                    _PENDING_LOGS.append(_payload)
-                    _record_attempt("http_error", f"HTTP {status}")
-                    logger.warning(f"D1 logging failed: HTTP {status}; buffered")
-                elif report.get("logged") is False:
-                    # Worker answered 200 but told us the row was not stored.
-                    _PENDING_LOGS.append(_payload)
-                    _record_attempt("worker_rejected",
-                                    f"HTTP {status} {report.get('warning') or report}")
-                    logger.warning(
-                        f"D1 insert failed Worker-side: {report.get('warning') or report}"
-                    )
-                elif report.get("warning"):
-                    # Stored, but via the legacy fallback schema - surface it.
-                    _record_attempt("ok_with_warning",
-                                    f"HTTP {status} schema={report.get('schema')} "
-                                    f"{report.get('warning')}")
-                    logger.warning(f"D1 logged with warning: {report.get('warning')}")
-                else:
-                    _record_attempt("ok", f"HTTP {status} schema={report.get('schema')}")
-                    logger.debug("D1 logged OK")
-
-            if not _spawn_background(_post_to_worker()):
-                logger.warning("D1 logging skipped: no running event loop")
-            else:
-                _ensure_periodic_flusher(worker_url, _token)
-    except Exception:
-        pass
-
-
-async def _agent_query_inner(
-    question: str,
-    history,
-    model: str,
-    client_state,
-    start_time: float,
-) -> AgentResponse:
-
-    # ── Prompt injection detection ────────────────────────────────────────────
-    if question and _INJECTION_RE.search(question):
-        _safe_metrics_bucket("intents", "injection_blocked")
-        return AgentResponse(
-            answer=(
-                "I'm sorry, but I can't process that request. "
-                "I'm LibBee, the KU Library AI Assistant — here to help with "
-                "library services, research, and academic resources. "
-                f'How can I help you today? <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a>'
-            ),
-            intent="blocked",
-            tools_used=["injection_guard"],
-            model_used=model,
-            response_time=time.time() - start_time,
-        )
-
-    if not question:
-        follow_up_question, follow_up_suggestions = _social_follow_up()
-        return AgentResponse(
-            answer="Please type a question and I'll do my best to help!" + _source_badge("libbee"),
-            intent="social",
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if PURE_GREETING_RE.match(question):
-        follow_up_question, follow_up_suggestions = _social_follow_up()
-        return AgentResponse(
-            answer=(
-                _get_runtime_config().get("welcome_message", "").strip()
-                or (
-                    "Hi! I'm <strong>LibBee</strong>, the Khalifa University Library AI Assistant.<br><br>"
-                    "I can help you find articles and books, search databases, access full text, "
-                    "request Interlibrary Loan (ILL), and answer questions about library services and staff."
-                )
-                + _source_badge("libbee")
-            ),
-            intent="social_greeting",
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    staff_match = match_staff_name(question) if should_attempt_staff_lookup(question) else None
-    if staff_match:
-        _safe_metrics_bucket("intents", "staff_lookup")
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        return AgentResponse(
-            answer=_thought_block("staff_lookup", "staff_name_match", question) + staff_name_answer(staff_match) + _source_badge("ku_library", "https://library.ku.ac.ae/"),
-            intent="library_info",
-            tools_used=["staff_name_match"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    staff_role_match = match_staff_role(question) if should_attempt_staff_lookup(question) else None
-    if staff_role_match:
-        _safe_metrics_bucket("intents", "staff_lookup")
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        return AgentResponse(
-            answer=_thought_block("staff_lookup", "staff_role_match", question) + staff_role_answer(staff_role_match, question) + _source_badge("ku_library", "https://library.ku.ac.ae/"),
-            intent="library_info",
-            tools_used=["staff_role_match"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if _is_greeting_menu_followup(question, history):
-        follow_up_question, follow_up_suggestions = _social_follow_up()
-        return AgentResponse(
-            answer=_thought_block("social_greeting", "greeting_menu", question) + _greeting_menu_clarify_answer() + _source_badge("libbee"),
-            intent="social_greeting",
-            is_follow_up=True,
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if _looks_library_hours_question(question):
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        hours_html = await _hours_answer()
-        return AgentResponse(
-            answer=_thought_block("hours", "libcal_live", question) + hours_html + _source_badge("ku_library", LIBRARY_HOURS_URL),
-            intent="library_info",
-            tools_used=["libcal_live_hours"],
-            ask_librarian=False,
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if EVENTS_RE.search(question):
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        events_html = await _events_answer()
-        return AgentResponse(
-            answer=_thought_block("library_info", "libcal_events", question,
-                                  "I fetched upcoming events from the KU LibCal events calendar.")
-                   + events_html + _source_badge("ku_library", "https://kustar.libcal.com/calendar/events"),
-            intent="library_info",
-            tools_used=["libcal_live_events"],
-            ask_librarian=False,
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if _looks_campus_question(question):
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        return AgentResponse(
-            answer=_thought_block("campus", "campus_hardcoded", question) + _campus_answer() + _source_badge("ku_library", "https://library.ku.ac.ae/"),
-            intent="library_info",
-            tools_used=["campus_hardcoded"],
-            ask_librarian=False,
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if _is_database_recommendation_question(question):
-        answer = _database_recommendation_answer(question)
-        answer += _contact_footer_for_query(question, None)
-        answer += _source_badge("ku_library", "https://library.ku.ac.ae/eresources")
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        return AgentResponse(
-            answer=_thought_block("database_rec", "database_recommendation", question) + answer,
-            intent="library_info",
-            tools_used=["database_recommendation"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    is_follow_up, follow_up_action, base_context = _detect_follow_up(question, client_state)
-
-    # ── Catalogue availability ────────────────────────────────────────────────
-    _CATALOGUE_RE = re.compile(
-        r"\b("
-        r"available in (the )?(ku|khalifa) library"
-        r"|in (the )?(ku|khalifa) library"
-        r"|does (the )?(ku|khalifa) library have"
-        r"|does (the )?library (have|carry|stock|hold)"
-        r"|(ku|khalifa) library (has|have|carry|holds?|stocks?)"
-        r"|ku library (books?|copies|titles?)"
-        r")\b",
-        re.IGNORECASE,
+
+
+async def _agent_query_inner(
+    question: str,
+    history,
+    model: str,
+    client_state,
+    start_time: float,
+) -> AgentResponse:
+
+    # ── Prompt injection detection ────────────────────────────────────────────
+    if question and _INJECTION_RE.search(question):
+        _safe_metrics_bucket("intents", "injection_blocked")
+        return AgentResponse(
+            answer=(
+                "I'm sorry, but I can't process that request. "
+                "I'm LibBee, the KU Library AI Assistant — here to help with "
+                "library services, research, and academic resources. "
+                f'How can I help you today? <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a>'
+            ),
+            intent="blocked",
+            tools_used=["injection_guard"],
+            model_used=model,
+            response_time=time.time() - start_time,
+        )
+
+    if not question:
+        follow_up_question, follow_up_suggestions = _social_follow_up()
+        return AgentResponse(
+            answer="Please type a question and I'll do my best to help!" + _source_badge("libbee"),
+            intent="social",
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if PURE_GREETING_RE.match(question):
+        follow_up_question, follow_up_suggestions = _social_follow_up()
+        return AgentResponse(
+            answer=(
+                _get_runtime_config().get("welcome_message", "").strip()
+                or (
+                    "Hi! I'm <strong>LibBee</strong>, the Khalifa University Library AI Assistant.<br><br>"
+                    "I can help you find articles and books, search databases, access full text, "
+                    "request Interlibrary Loan (ILL), and answer questions about library services and staff."
+                )
+                + _source_badge("libbee")
+            ),
+            intent="social_greeting",
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    staff_match = match_staff_name(question) if should_attempt_staff_lookup(question) else None
+    if staff_match:
+        _safe_metrics_bucket("intents", "staff_lookup")
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=_thought_block("staff_lookup", "staff_name_match", question) + staff_name_answer(staff_match) + _source_badge("ku_library", "https://library.ku.ac.ae/"),
+            intent="library_info",
+            tools_used=["staff_name_match"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    staff_role_match = match_staff_role(question) if should_attempt_staff_lookup(question) else None
+    if staff_role_match:
+        _safe_metrics_bucket("intents", "staff_lookup")
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=_thought_block("staff_lookup", "staff_role_match", question) + staff_role_answer(staff_role_match, question) + _source_badge("ku_library", "https://library.ku.ac.ae/"),
+            intent="library_info",
+            tools_used=["staff_role_match"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if _is_greeting_menu_followup(question, history):
+        follow_up_question, follow_up_suggestions = _social_follow_up()
+        return AgentResponse(
+            answer=_thought_block("social_greeting", "greeting_menu", question) + _greeting_menu_clarify_answer() + _source_badge("libbee"),
+            intent="social_greeting",
+            is_follow_up=True,
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if _looks_library_hours_question(question):
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        hours_html = await _hours_answer()
+        return AgentResponse(
+            answer=_thought_block("hours", "libcal_live", question) + hours_html + _source_badge("ku_library", LIBRARY_HOURS_URL),
+            intent="library_info",
+            tools_used=["libcal_live_hours"],
+            ask_librarian=False,
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if EVENTS_RE.search(question):
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        events_html = await _events_answer()
+        return AgentResponse(
+            answer=_thought_block("library_info", "libcal_events", question,
+                                  "I fetched upcoming events from the KU LibCal events calendar.")
+                   + events_html + _source_badge("ku_library", "https://kustar.libcal.com/calendar/events"),
+            intent="library_info",
+            tools_used=["libcal_live_events"],
+            ask_librarian=False,
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if _looks_campus_question(question):
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=_thought_block("campus", "campus_hardcoded", question) + _campus_answer() + _source_badge("ku_library", "https://library.ku.ac.ae/"),
+            intent="library_info",
+            tools_used=["campus_hardcoded"],
+            ask_librarian=False,
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if _is_database_recommendation_question(question):
+        answer = _database_recommendation_answer(question)
+        answer += _contact_footer_for_query(question, None)
+        answer += _source_badge("ku_library", "https://library.ku.ac.ae/eresources")
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=_thought_block("database_rec", "database_recommendation", question) + answer,
+            intent="library_info",
+            tools_used=["database_recommendation"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    is_follow_up, follow_up_action, base_context = _detect_follow_up(question, client_state)
+
+    # ── Catalogue availability ────────────────────────────────────────────────
+    _CATALOGUE_RE = re.compile(
+        r"\b("
+        r"available in (the )?(ku|khalifa) library"
+        r"|in (the )?(ku|khalifa) library"
+        r"|does (the )?(ku|khalifa) library have"
+        r"|does (the )?library (have|carry|stock|hold)"
+        r"|(ku|khalifa) library (has|have|carry|holds?|stocks?)"
+        r"|ku library (books?|copies|titles?)"
+        r")\b",
+        re.IGNORECASE,
+    )
+    _BOOK_RE = re.compile(r"\b(book|books|ebook|ebooks|textbook|textbooks|copy|copies|title|titles)\b", re.IGNORECASE)
+
+    if _CATALOGUE_RE.search(question) and _BOOK_RE.search(question):
+        from urllib.parse import quote as _quote
+        _topic_raw = re.sub(
+            r"\b(can you (help me )?find|find|search|look for|show me|help me find"
+            r"|books? (available|in|on)|available in.{0,30}library|in the ku library"
+            r"|on|about|regarding|related to|ku library|khalifa university library"
+            r"|machine learning|please|thanks)\b",
+            " ", question, flags=re.IGNORECASE,
+        )
+        _topic = _normalize_whitespace(_topic_raw).strip(" ,.")
+        _primo_books_url = (
+            "https://khalifa.primo.exlibrisgroup.com/discovery/search"
+            f"?query=any,contains,{_quote(_topic or question)},AND"
+            "&tab=Everything&search_scope=MyInst_and_CI"
+            "&vid=971KUOSTAR_INST:KU&lang=en&mode=advanced"
+            "&qInclude=facet_rtype,exact,books"
+        )
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+
+        rag_results = []
+        try:
+            from app import get_rag_service
+            rag_results = await get_rag_service().hybrid_search(question, top_k=3)
+        except Exception:
+            pass
+
+        if rag_results:
+            rag_answer = await _rag_answer(question, rag_results, [], model)
+        else:
+            rag_answer = ""
+
+        catalogue_answer = (
+            f"To find books available in the KU Library on <strong>{_escape(_topic or 'this topic')}</strong>, "
+            f"search the KU Library catalogue directly:<br><br>"
+            f'<a href="{_primo_books_url}" target="_blank" style="display:inline-block;padding:9px 16px;'
+            f'background:#003366;color:#fff;border-radius:8px;font-weight:700;text-decoration:none;font-size:.88rem">'
+            f"📚 Search KU Library catalogue for books →</a><br><br>"
+            f"The catalogue shows real-time availability — whether a copy is on the shelf, checked out, or available as an e-book."
+        )
+        if rag_answer:
+            catalogue_answer += f"<br><br>{rag_answer}"
+
+        return AgentResponse(
+            answer=_thought_block("library_info", "catalogue_books", question) + catalogue_answer + _source_badge("primo", _primo_books_url),
+            intent="library_info",
+            tools_used=["catalogue_books_redirect"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if is_follow_up and base_context:
+        _safe_metrics_increment("follow_up_hits")
+        context = _apply_follow_up_action(base_context, follow_up_action)
+
+        if follow_up_action == "alt_terms":
+            alt_answer = await _alternative_terms_answer(question, base_context, model)
+            follow_up_question, follow_up_suggestions = await _search_follow_up(base_context, model)
+            return AgentResponse(
+                answer=_thought_block("library_info", "alt_terms", question) + alt_answer + _source_badge("libbee"),
+                intent="library_info",
+                tools_used=["alt_terms"],
+                model_used=model,
+                response_time=time.time() - start_time,
+                follow_up_question=follow_up_question,
+                follow_up_suggestions=follow_up_suggestions,
+                search_context=_context_to_dict(base_context),
+                is_follow_up=True,
+            )
+
+        if follow_up_action in {"summarize_topic", "deep_research_tools", "best_databases"}:
+            context = await _prepare_queries(question, context, model, True)
+            if follow_up_action == "summarize_topic":
+                answer, search_results, sources = await _research_snapshot(context, model)
+            else:
+                answer = (
+                    f"{_search_trace_block(question, context)}"
+                    f"<strong>Research guide for {_escape(context.display_topic or context.topic)}</strong><br><br>"
+                    f"Here are the best AI tools and resources for a deep dive on this topic."
+                    + _source_badge("libbee")
+                    + _ai_tools_footer(context)
+                )
+                search_results = []
+                sources = []
+            follow_up_question, follow_up_suggestions = await _search_follow_up(context, model, summary_mode=True)
+            _safe_metrics_increment("search_handoffs")
+            return AgentResponse(
+                answer=answer,
+                intent=context.intent,
+                tools_used=["follow_up_resolution", follow_up_action],
+                search_results=search_results,
+                sources=sources,
+                model_used=model,
+                response_time=time.time() - start_time,
+                corrected_query=context.topic,
+                natural_query=context.ai_tool_query,
+                database_query=context.primo_boolean_query,
+                ai_tool_query=context.ai_tool_query,
+                primo_boolean_query=context.primo_boolean_query,
+                primo_search_url=_primo_clean_url(context),
+                primo_ai_url=_tool_urls(context).get("primo_ai"),
+                pubmed_search_url=_tool_urls(context).get("pubmed"),
+                follow_up_question=follow_up_question,
+                follow_up_suggestions=follow_up_suggestions,
+                search_context=_context_to_dict(context),
+                is_follow_up=True,
+            )
+
+        answer, search_results, sources, source_url = await _run_search_mode(question, context, model, True)
+        follow_up_question, follow_up_suggestions = await _search_follow_up(context, model)
+        return AgentResponse(
+            answer=answer,
+            intent=context.intent,
+            tools_used=["follow_up_resolution", follow_up_action or "contextual_refinement"],
+            search_results=search_results,
+            sources=sources,
+            model_used=model,
+            response_time=time.time() - start_time,
+            corrected_query=context.topic,
+            natural_query=context.ai_tool_query,
+            database_query=context.primo_boolean_query,
+            ai_tool_query=context.ai_tool_query,
+            primo_boolean_query=context.primo_boolean_query,
+            primo_search_url=source_url,
+            primo_ai_url=_tool_urls(context).get("primo_ai"),
+            pubmed_search_url=_tool_urls(context).get("pubmed"),
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+            search_context=_context_to_dict(context),
+            is_follow_up=True,
+        )
+
+    # ── Pre-classifier specialist handlers ───────────────────────────────────
+
+    if FULLTEXT_REQUEST_RE.search(question):
+        ft_answer = _fulltext_chain_answer(question)
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=_thought_block("library_info", "fulltext_chain", question,
+                                  "Identified a full-text access request. Returning the KU full-text access chain.") + ft_answer + _source_badge("ku_library", "https://library.ku.ac.ae/ill/"),
+            intent="library_info",
+            tools_used=["fulltext_chain"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if THESES_RE.search(question):
+        th_answer = _theses_answer()
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=_thought_block("library_info", "theses_guide", question,
+                                  "Identified a theses/repository question.") + th_answer + _source_badge("ku_library", "https://khazna.ku.ac.ae"),
+            intent="library_info",
+            tools_used=["theses_guide"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if PREDATORY_RE.search(question):
+        pr_answer = _predatory_eval_answer()
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=_thought_block("library_info", "predatory_eval", question,
+                                  "Identified a question about evaluating journals/peer review.") + pr_answer + _source_badge("ku_library", "https://library.ku.ac.ae/eresources"),
+            intent="library_info",
+            tools_used=["predatory_eval"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if CITATION_CHAIN_RE.search(question):
+        cc_answer = _citation_chain_answer()
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=_thought_block("library_info", "citation_chain", question,
+                                  "Identified a citation tracing / forward-backward search question.") + cc_answer + _source_badge("ku_library", "https://library.ku.ac.ae/eresources"),
+            intent="library_info",
+            tools_used=["citation_chain"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if BOOLEAN_STRATEGY_RE.search(question):
+        strategy_answer, _plan = await _search_strategy_answer(question, model)
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=_thought_block("library_info", "search_strategy", question,
+                                  "Identified a search strategy / boolean building request.") + strategy_answer + _source_badge("libbee"),
+            intent="library_info",
+            tools_used=["search_strategy_explain"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            database_query=_plan.get("boolean"),
+            natural_query=_plan.get("natural"),
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if ALT_TERMS_RE.search(question):
+        alt_answer = await _alternative_terms_answer(question, None, model)
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=_thought_block("library_info", "alt_terms", question) + alt_answer + _source_badge("libbee"),
+            intent="library_info",
+            tools_used=["alt_terms"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    cls_result = await _llm_classify(question, history, model)
+    intent = cls_result.get("intent", "general")
+    _safe_metrics_bucket("intents", intent)
+    casual_hint = cls_result.get("casual_answer", "")
+
+    if intent == "social":
+        answer = (
+            casual_hint
+            if casual_hint and len(casual_hint.strip()) > 20
+            else await _libbee_casual_response(question, history, model, casual_hint)
+        )
+        follow_up_question, follow_up_suggestions = _social_follow_up()
+        return AgentResponse(
+            answer=_thought_block("social", "libbee_casual", question) + answer + _source_badge("libbee"),
+            intent="social_greeting",
+            tools_used=["libbee_casual"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if intent == "sensitive":
+        _safe_metrics_bucket("intents", "sensitive_blocked")
+        follow_up_question, follow_up_suggestions = _social_follow_up()
+        return AgentResponse(
+            answer=(
+                "That's not something I'm able to comment on. "
+                "As the KU Library AI Assistant, I'm here to support your academic "
+                "and research needs — finding articles, accessing databases, "
+                "library services, and research tools.<br><br>"
+                "Is there something I can help you with today? "
+                f'<a href="{ASK_LIBRARIAN_URL}" target="_blank">💬 Ask a Librarian</a>'
+            ),
+            intent="sensitive_blocked",
+            tools_used=["sensitive_intent_guard"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if intent == "library_info":
+        rag_results = []
+        try:
+            from app import get_rag_service
+            rag_results = await get_rag_service().hybrid_search(question, top_k=4)
+        except Exception as e:
+            logger.error(f"RAG search failed: {e}")
+
+        if not rag_results:
+            answer = (
+                "I couldn't find specific information on that in my knowledge base.<br><br>"
+                "Please contact our librarians directly:<br>"
+                '📧 <a href="mailto:libse@ku.ac.ae">libse@ku.ac.ae</a><br>'
+                f'🔗 <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a>'
+            )
+            answer += _source_badge("ku_library", ASK_LIBRARIAN_URL)
+            sources = []
+            tools_used = ["rag_no_results"]
+            thought = _thought_block("library_info", "rag_no_results", question,
+                                     "No matching content was found — I am directing you to Ask a Librarian.")
+        else:
+            answer = await _rag_answer(question, rag_results, history, model)
+            answer += _source_badge("rag", "https://library.ku.ac.ae/")
+            sources = [
+                {"title": r.get("title", "Library KB"), "url": r.get("source", "")}
+                for r in rag_results if r.get("source")
+            ]
+            tools_used = ["rag_hybrid_search"]
+            thought = _thought_block("rag_search", "rag_hybrid_search", question,
+                                     f"Hybrid FAISS + BM25 search returned {len(rag_results)} relevant chunk(s) from the KB.")
+
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=thought + answer,
+            intent="library_info",
+            tools_used=tools_used,
+            sources=sources,
+            ask_librarian=not bool(rag_results),
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    if intent in ("search_academic", "search_medical"):
+        if PARTIAL_TITLE_RE.search(question):
+            from urllib.parse import quote as _qt
+            _title_frag = (re.search(r'"([^"]{4,80})"', question) or
+                           re.search(r'"([^"]{4,80})"', question))
+            _title_q = _title_frag.group(1) if _title_frag else _light_strip_retrieval_boilerplate(question)
+            _title_url = (
+                "https://khalifa.primo.exlibrisgroup.com/discovery/search"
+                f"?query=title,contains,{_qt(_title_q)},AND"
+                "&tab=Everything&search_scope=MyInst_and_CI"
+                "&vid=971KUOSTAR_INST:KU&lang=en&mode=advanced"
+            )
+            follow_up_question, follow_up_suggestions = _library_follow_up(question)
+            return AgentResponse(
+                answer=(
+                    _thought_block("library_info", "title_search", question,
+                                   "Identified a partial title search — routing to PRIMO title search.") +
+                    f"<strong>📖 Title search in KU Library</strong><br><br>"
+                    f"I'll search the KU Library catalogue by title for: <em>{_escape(_title_q)}</em><br><br>"
+                    f'<a href="{_title_url}" target="_blank" '
+                    f'style="display:inline-block;padding:9px 16px;background:#003366;color:#fff;'
+                    f'border-radius:8px;font-weight:700;text-decoration:none;font-size:.88rem">'
+                    f"🔍 Search by title in PRIMO →</a><br><br>"
+                    "If you only remember part of the title, use PRIMO's advanced search and choose "
+                    "<em>Title</em> from the field dropdown — it supports partial matches.<br>"
+                    "You can also try "
+                    '<a href="https://scholar.google.com" target="_blank">Google Scholar</a> '
+                    "with the partial title in quotes." +
+                    _source_badge("primo", _title_url)
+                ),
+                intent="library_info",
+                tools_used=["title_search"],
+                model_used=model,
+                response_time=time.time() - start_time,
+                follow_up_question=follow_up_question,
+                follow_up_suggestions=follow_up_suggestions,
+            )
+
+        topic = await _extract_topic(question, model)
+        topic = _title_case_topic(topic)
+        year_from, year_to = _parse_year_filters(question)
+
+        if DUAL_RESOURCE_RE.search(question):
+            import asyncio as _aio
+            _ctx_articles = SearchContextPayload(
+                context_id=str(uuid.uuid4()), topic=topic, display_topic=topic,
+                intent=intent, source="primo", resource_type="articles",
+                peer_reviewed=bool(re.search(r"\bpeer[- ]reviewed\b", question, re.IGNORECASE)),
+                open_access=bool(re.search(r"\bopen access\b", question, re.IGNORECASE)),
+                year_from=year_from, year_to=year_to,
+            )
+            _ctx_books = SearchContextPayload(
+                context_id=str(uuid.uuid4()), topic=topic, display_topic=topic,
+                intent=intent, source="primo", resource_type="books",
+                peer_reviewed=False, open_access=False,
+                year_from=year_from, year_to=year_to,
+            )
+            _ctx_articles, _ctx_books = await _aio.gather(
+                _prepare_queries(question, _ctx_articles, model, False),
+                _prepare_queries(question, _ctx_books, model, False),
+            )
+            _src_url_a = _primo_clean_url(_ctx_articles)
+            _src_url_b = _primo_clean_url(_ctx_books)
+
+            _dual_answer = _search_trace_block(question, _ctx_articles)
+            _dual_answer += (
+                f"<strong>📄 Articles on {_escape(topic)}</strong><br>"
+                f'<a href="{_src_url_a}" target="_blank" style="color:#003366;font-weight:700">'
+                f'Search PRIMO for articles →</a>'
+            )
+            _dual_answer += _source_badge("primo", _src_url_a)
+            _dual_answer += f"<br><br><strong>📚 Books on {_escape(topic)}</strong><br>"
+            _dual_answer += (
+                f'<a href="{_src_url_b}" target="_blank" style="color:#003366;font-weight:700">'
+                f'Search PRIMO for books →</a>'
+            )
+            _dual_answer += _source_badge("primo", _src_url_b)
+            _dual_answer += _ai_tools_footer(_ctx_articles)
+
+            follow_up_question, follow_up_suggestions = await _search_follow_up(_ctx_articles, model)
+            return AgentResponse(
+                answer=_dual_answer,
+                intent=intent,
+                tools_used=["primo_browser_link"],
+                search_results=[],
+                sources=[],
+                model_used=model,
+                response_time=time.time() - start_time,
+                corrected_query=topic,
+                natural_query=_ctx_articles.ai_tool_query,
+                primo_boolean_query=_ctx_articles.primo_boolean_query,
+                primo_search_url=_src_url_a,
+                follow_up_question=follow_up_question,
+                follow_up_suggestions=follow_up_suggestions,
+                search_context=_context_to_dict(_ctx_articles),
+            )
+
+        context = SearchContextPayload(
+            context_id=str(uuid.uuid4()),
+            topic=topic,
+            display_topic=topic,
+            intent=intent,
+            source="primo",
+            resource_type=_derive_resource_type(question),
+            peer_reviewed=bool(re.search(r"\bpeer[- ]reviewed\b", question, re.IGNORECASE)),
+            open_access=bool(re.search(r"\bopen access\b", question, re.IGNORECASE)),
+            year_from=year_from,
+            year_to=year_to,
+        )
+
+        context = await _prepare_queries(question, context, model, False)
+        summary_mode = _is_summary_request(question)
+        deep_research_mode = bool(re.search(
+            r"\b(deep research|deep dive|systematic review|full literature review|exhaustive)\b",
+            question, re.IGNORECASE,
+        ))
+        is_highly_cited = bool(HIGHLY_CITED_RE.search(question))
+
+        if summary_mode or deep_research_mode:
+            answer, search_results, sources = await _research_snapshot(context, model)
+            if deep_research_mode and "Research guide" not in answer and "AI tools" not in answer:
+                answer += f"<br><br>{_ai_tools_footer(context)}"
+            if is_highly_cited:
+                answer += _highly_cited_note(_escape(topic))
+            follow_up_question, follow_up_suggestions = await _search_follow_up(context, model, summary_mode=True)
+            _safe_metrics_increment("search_handoffs")
+            return AgentResponse(
+                answer=answer,
+                intent=intent,
+                tools_used=["research_snapshot"],
+                search_results=search_results,
+                sources=sources,
+                model_used=model,
+                response_time=time.time() - start_time,
+                corrected_query=context.topic,
+                natural_query=context.ai_tool_query,
+                database_query=context.primo_boolean_query,
+                ai_tool_query=context.ai_tool_query,
+                primo_boolean_query=context.primo_boolean_query,
+                primo_search_url=_primo_clean_url(context),
+                primo_ai_url=_tool_urls(context).get("primo_ai"),
+                pubmed_search_url=_tool_urls(context).get("pubmed"),
+                follow_up_question=follow_up_question,
+                follow_up_suggestions=follow_up_suggestions,
+                search_context=_context_to_dict(context),
+            )
+
+        answer, search_results, sources, source_url = await _run_search_mode(question, context, model, False)
+        if is_highly_cited:
+            answer += _highly_cited_note(_escape(topic))
+        follow_up_question, follow_up_suggestions = await _search_follow_up(context, model)
+        return AgentResponse(
+            answer=answer,
+            intent=intent,
+            tools_used=["primo_inline" if context.source == "primo" else "pubmed_inline"],
+            search_results=search_results,
+            sources=sources,
+            model_used=model,
+            response_time=time.time() - start_time,
+            corrected_query=context.topic,
+            natural_query=context.ai_tool_query,
+            database_query=context.primo_boolean_query,
+            ai_tool_query=context.ai_tool_query,
+            primo_boolean_query=context.primo_boolean_query,
+            primo_search_url=source_url,
+            primo_ai_url=_tool_urls(context).get("primo_ai"),
+            pubmed_search_url=_tool_urls(context).get("pubmed"),
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+            search_context=_context_to_dict(context),
+        )
+
+    if intent == "general_recent":
+        answer = await _web_search_answer(question, history, model) + _source_badge("web_live")
+        follow_up_question, follow_up_suggestions = _general_follow_up(question)
+        return AgentResponse(
+            answer=_thought_block("general_recent", "web_search", question) + answer,
+            intent="general_recent",
+            tools_used=["web_search"],
+            model_used=model,
+            response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+        )
+
+    # general fallback
+    answer = await _web_search_answer(question, history, model) + _source_badge("web")
+    follow_up_question, follow_up_suggestions = _general_follow_up(question)
+    return AgentResponse(
+        answer=_thought_block("general", "web_search", question) + answer,
+        intent="general",
+        tools_used=["web_search"],
+        model_used=model,
+        response_time=time.time() - start_time,
+        follow_up_question=follow_up_question,
+        follow_up_suggestions=follow_up_suggestions,
     )
-    _BOOK_RE = re.compile(r"\b(book|books|ebook|ebooks|textbook|textbooks|copy|copies|title|titles)\b", re.IGNORECASE)
-
-    if _CATALOGUE_RE.search(question) and _BOOK_RE.search(question):
-        from urllib.parse import quote as _quote
-        _topic_raw = re.sub(
-            r"\b(can you (help me )?find|find|search|look for|show me|help me find"
-            r"|books? (available|in|on)|available in.{0,30}library|in the ku library"
-            r"|on|about|regarding|related to|ku library|khalifa university library"
-            r"|machine learning|please|thanks)\b",
-            " ", question, flags=re.IGNORECASE,
-        )
-        _topic = _normalize_whitespace(_topic_raw).strip(" ,.")
-        _primo_books_url = (
-            "https://khalifa.primo.exlibrisgroup.com/discovery/search"
-            f"?query=any,contains,{_quote(_topic or question)},AND"
-            "&tab=Everything&search_scope=MyInst_and_CI"
-            "&vid=971KUOSTAR_INST:KU&lang=en&mode=advanced"
-            "&qInclude=facet_rtype,exact,books"
-        )
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-
-        rag_results = []
-        try:
-            from app import get_rag_service
-            rag_results = await get_rag_service().hybrid_search(question, top_k=3)
-        except Exception:
-            pass
-
-        if rag_results:
-            rag_answer = await _rag_answer(question, rag_results, [], model)
-        else:
-            rag_answer = ""
-
-        catalogue_answer = (
-            f"To find books available in the KU Library on <strong>{_escape(_topic or 'this topic')}</strong>, "
-            f"search the KU Library catalogue directly:<br><br>"
-            f'<a href="{_primo_books_url}" target="_blank" style="display:inline-block;padding:9px 16px;'
-            f'background:#003366;color:#fff;border-radius:8px;font-weight:700;text-decoration:none;font-size:.88rem">'
-            f"📚 Search KU Library catalogue for books →</a><br><br>"
-            f"The catalogue shows real-time availability — whether a copy is on the shelf, checked out, or available as an e-book."
-        )
-        if rag_answer:
-            catalogue_answer += f"<br><br>{rag_answer}"
-
-        return AgentResponse(
-            answer=_thought_block("library_info", "catalogue_books", question) + catalogue_answer + _source_badge("primo", _primo_books_url),
-            intent="library_info",
-            tools_used=["catalogue_books_redirect"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if is_follow_up and base_context:
-        _safe_metrics_increment("follow_up_hits")
-        context = _apply_follow_up_action(base_context, follow_up_action)
-
-        if follow_up_action == "alt_terms":
-            alt_answer = await _alternative_terms_answer(question, base_context, model)
-            follow_up_question, follow_up_suggestions = await _search_follow_up(base_context, model)
-            return AgentResponse(
-                answer=_thought_block("library_info", "alt_terms", question) + alt_answer + _source_badge("libbee"),
-                intent="library_info",
-                tools_used=["alt_terms"],
-                model_used=model,
-                response_time=time.time() - start_time,
-                follow_up_question=follow_up_question,
-                follow_up_suggestions=follow_up_suggestions,
-                search_context=_context_to_dict(base_context),
-                is_follow_up=True,
-            )
-
-        if follow_up_action in {"summarize_topic", "deep_research_tools", "best_databases"}:
-            context = await _prepare_queries(question, context, model, True)
-            if follow_up_action == "summarize_topic":
-                answer, search_results, sources = await _research_snapshot(context, model)
-            else:
-                answer = (
-                    f"{_search_trace_block(question, context)}"
-                    f"<strong>Research guide for {_escape(context.display_topic or context.topic)}</strong><br><br>"
-                    f"Here are the best AI tools and resources for a deep dive on this topic."
-                    + _source_badge("libbee")
-                    + _ai_tools_footer(context)
-                )
-                search_results = []
-                sources = []
-            follow_up_question, follow_up_suggestions = await _search_follow_up(context, model, summary_mode=True)
-            _safe_metrics_increment("search_handoffs")
-            return AgentResponse(
-                answer=answer,
-                intent=context.intent,
-                tools_used=["follow_up_resolution", follow_up_action],
-                search_results=search_results,
-                sources=sources,
-                model_used=model,
-                response_time=time.time() - start_time,
-                corrected_query=context.topic,
-                natural_query=context.ai_tool_query,
-                database_query=context.primo_boolean_query,
-                ai_tool_query=context.ai_tool_query,
-                primo_boolean_query=context.primo_boolean_query,
-                primo_search_url=_primo_clean_url(context),
-                primo_ai_url=_tool_urls(context).get("primo_ai"),
-                pubmed_search_url=_tool_urls(context).get("pubmed"),
-                follow_up_question=follow_up_question,
-                follow_up_suggestions=follow_up_suggestions,
-                search_context=_context_to_dict(context),
-                is_follow_up=True,
-            )
-
-        answer, search_results, sources, source_url = await _run_search_mode(question, context, model, True)
-        follow_up_question, follow_up_suggestions = await _search_follow_up(context, model)
-        return AgentResponse(
-            answer=answer,
-            intent=context.intent,
-            tools_used=["follow_up_resolution", follow_up_action or "contextual_refinement"],
-            search_results=search_results,
-            sources=sources,
-            model_used=model,
-            response_time=time.time() - start_time,
-            corrected_query=context.topic,
-            natural_query=context.ai_tool_query,
-            database_query=context.primo_boolean_query,
-            ai_tool_query=context.ai_tool_query,
-            primo_boolean_query=context.primo_boolean_query,
-            primo_search_url=source_url,
-            primo_ai_url=_tool_urls(context).get("primo_ai"),
-            pubmed_search_url=_tool_urls(context).get("pubmed"),
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-            search_context=_context_to_dict(context),
-            is_follow_up=True,
-        )
-
-    # ── Pre-classifier specialist handlers ───────────────────────────────────
-
-    if FULLTEXT_REQUEST_RE.search(question):
-        ft_answer = _fulltext_chain_answer(question)
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        return AgentResponse(
-            answer=_thought_block("library_info", "fulltext_chain", question,
-                                  "Identified a full-text access request. Returning the KU full-text access chain.") + ft_answer + _source_badge("ku_library", "https://library.ku.ac.ae/ill/"),
-            intent="library_info",
-            tools_used=["fulltext_chain"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if THESES_RE.search(question):
-        th_answer = _theses_answer()
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        return AgentResponse(
-            answer=_thought_block("library_info", "theses_guide", question,
-                                  "Identified a theses/repository question.") + th_answer + _source_badge("ku_library", "https://khazna.ku.ac.ae"),
-            intent="library_info",
-            tools_used=["theses_guide"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if PREDATORY_RE.search(question):
-        pr_answer = _predatory_eval_answer()
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        return AgentResponse(
-            answer=_thought_block("library_info", "predatory_eval", question,
-                                  "Identified a question about evaluating journals/peer review.") + pr_answer + _source_badge("ku_library", "https://library.ku.ac.ae/eresources"),
-            intent="library_info",
-            tools_used=["predatory_eval"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if CITATION_CHAIN_RE.search(question):
-        cc_answer = _citation_chain_answer()
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        return AgentResponse(
-            answer=_thought_block("library_info", "citation_chain", question,
-                                  "Identified a citation tracing / forward-backward search question.") + cc_answer + _source_badge("ku_library", "https://library.ku.ac.ae/eresources"),
-            intent="library_info",
-            tools_used=["citation_chain"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if BOOLEAN_STRATEGY_RE.search(question):
-        strategy_answer, _plan = await _search_strategy_answer(question, model)
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        return AgentResponse(
-            answer=_thought_block("library_info", "search_strategy", question,
-                                  "Identified a search strategy / boolean building request.") + strategy_answer + _source_badge("libbee"),
-            intent="library_info",
-            tools_used=["search_strategy_explain"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            database_query=_plan.get("boolean"),
-            natural_query=_plan.get("natural"),
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if ALT_TERMS_RE.search(question):
-        alt_answer = await _alternative_terms_answer(question, None, model)
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        return AgentResponse(
-            answer=_thought_block("library_info", "alt_terms", question) + alt_answer + _source_badge("libbee"),
-            intent="library_info",
-            tools_used=["alt_terms"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    cls_result = await _llm_classify(question, history, model)
-    intent = cls_result.get("intent", "general")
-    _safe_metrics_bucket("intents", intent)
-    casual_hint = cls_result.get("casual_answer", "")
-
-    if intent == "social":
-        answer = (
-            casual_hint
-            if casual_hint and len(casual_hint.strip()) > 20
-            else await _libbee_casual_response(question, history, model, casual_hint)
-        )
-        follow_up_question, follow_up_suggestions = _social_follow_up()
-        return AgentResponse(
-            answer=_thought_block("social", "libbee_casual", question) + answer + _source_badge("libbee"),
-            intent="social_greeting",
-            tools_used=["libbee_casual"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if intent == "sensitive":
-        _safe_metrics_bucket("intents", "sensitive_blocked")
-        follow_up_question, follow_up_suggestions = _social_follow_up()
-        return AgentResponse(
-            answer=(
-                "That's not something I'm able to comment on. "
-                "As the KU Library AI Assistant, I'm here to support your academic "
-                "and research needs — finding articles, accessing databases, "
-                "library services, and research tools.<br><br>"
-                "Is there something I can help you with today? "
-                f'<a href="{ASK_LIBRARIAN_URL}" target="_blank">💬 Ask a Librarian</a>'
-            ),
-            intent="sensitive_blocked",
-            tools_used=["sensitive_intent_guard"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if intent == "library_info":
-        rag_results = []
-        try:
-            from app import get_rag_service
-            rag_results = await get_rag_service().hybrid_search(question, top_k=4)
-        except Exception as e:
-            logger.error(f"RAG search failed: {e}")
-
-        if not rag_results:
-            answer = (
-                "I couldn't find specific information on that in my knowledge base.<br><br>"
-                "Please contact our librarians directly:<br>"
-                '📧 <a href="mailto:libse@ku.ac.ae">libse@ku.ac.ae</a><br>'
-                f'🔗 <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a>'
-            )
-            answer += _source_badge("ku_library", ASK_LIBRARIAN_URL)
-            sources = []
-            tools_used = ["rag_no_results"]
-            thought = _thought_block("library_info", "rag_no_results", question,
-                                     "No matching content was found — I am directing you to Ask a Librarian.")
-        else:
-            answer = await _rag_answer(question, rag_results, history, model)
-            answer += _source_badge("rag", "https://library.ku.ac.ae/")
-            sources = [
-                {"title": r.get("title", "Library KB"), "url": r.get("source", "")}
-                for r in rag_results if r.get("source")
-            ]
-            tools_used = ["rag_hybrid_search"]
-            thought = _thought_block("rag_search", "rag_hybrid_search", question,
-                                     f"Hybrid FAISS + BM25 search returned {len(rag_results)} relevant chunk(s) from the KB.")
-
-        follow_up_question, follow_up_suggestions = _library_follow_up(question)
-        return AgentResponse(
-            answer=thought + answer,
-            intent="library_info",
-            tools_used=tools_used,
-            sources=sources,
-            ask_librarian=not bool(rag_results),
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    if intent in ("search_academic", "search_medical"):
-        if PARTIAL_TITLE_RE.search(question):
-            from urllib.parse import quote as _qt
-            _title_frag = (re.search(r'"([^"]{4,80})"', question) or
-                           re.search(r'"([^"]{4,80})"', question))
-            _title_q = _title_frag.group(1) if _title_frag else _light_strip_retrieval_boilerplate(question)
-            _title_url = (
-                "https://khalifa.primo.exlibrisgroup.com/discovery/search"
-                f"?query=title,contains,{_qt(_title_q)},AND"
-                "&tab=Everything&search_scope=MyInst_and_CI"
-                "&vid=971KUOSTAR_INST:KU&lang=en&mode=advanced"
-            )
-            follow_up_question, follow_up_suggestions = _library_follow_up(question)
-            return AgentResponse(
-                answer=(
-                    _thought_block("library_info", "title_search", question,
-                                   "Identified a partial title search — routing to PRIMO title search.") +
-                    f"<strong>📖 Title search in KU Library</strong><br><br>"
-                    f"I'll search the KU Library catalogue by title for: <em>{_escape(_title_q)}</em><br><br>"
-                    f'<a href="{_title_url}" target="_blank" '
-                    f'style="display:inline-block;padding:9px 16px;background:#003366;color:#fff;'
-                    f'border-radius:8px;font-weight:700;text-decoration:none;font-size:.88rem">'
-                    f"🔍 Search by title in PRIMO →</a><br><br>"
-                    "If you only remember part of the title, use PRIMO's advanced search and choose "
-                    "<em>Title</em> from the field dropdown — it supports partial matches.<br>"
-                    "You can also try "
-                    '<a href="https://scholar.google.com" target="_blank">Google Scholar</a> '
-                    "with the partial title in quotes." +
-                    _source_badge("primo", _title_url)
-                ),
-                intent="library_info",
-                tools_used=["title_search"],
-                model_used=model,
-                response_time=time.time() - start_time,
-                follow_up_question=follow_up_question,
-                follow_up_suggestions=follow_up_suggestions,
-            )
-
-        topic = await _extract_topic(question, model)
-        topic = _title_case_topic(topic)
-        year_from, year_to = _parse_year_filters(question)
-
-        if DUAL_RESOURCE_RE.search(question):
-            import asyncio as _aio
-            _ctx_articles = SearchContextPayload(
-                context_id=str(uuid.uuid4()), topic=topic, display_topic=topic,
-                intent=intent, source="primo", resource_type="articles",
-                peer_reviewed=bool(re.search(r"\bpeer[- ]reviewed\b", question, re.IGNORECASE)),
-                open_access=bool(re.search(r"\bopen access\b", question, re.IGNORECASE)),
-                year_from=year_from, year_to=year_to,
-            )
-            _ctx_books = SearchContextPayload(
-                context_id=str(uuid.uuid4()), topic=topic, display_topic=topic,
-                intent=intent, source="primo", resource_type="books",
-                peer_reviewed=False, open_access=False,
-                year_from=year_from, year_to=year_to,
-            )
-            _ctx_articles, _ctx_books = await _aio.gather(
-                _prepare_queries(question, _ctx_articles, model, False),
-                _prepare_queries(question, _ctx_books, model, False),
-            )
-            _src_url_a = _primo_clean_url(_ctx_articles)
-            _src_url_b = _primo_clean_url(_ctx_books)
-
-            _dual_answer = _search_trace_block(question, _ctx_articles)
-            _dual_answer += (
-                f"<strong>📄 Articles on {_escape(topic)}</strong><br>"
-                f'<a href="{_src_url_a}" target="_blank" style="color:#003366;font-weight:700">'
-                f'Search PRIMO for articles →</a>'
-            )
-            _dual_answer += _source_badge("primo", _src_url_a)
-            _dual_answer += f"<br><br><strong>📚 Books on {_escape(topic)}</strong><br>"
-            _dual_answer += (
-                f'<a href="{_src_url_b}" target="_blank" style="color:#003366;font-weight:700">'
-                f'Search PRIMO for books →</a>'
-            )
-            _dual_answer += _source_badge("primo", _src_url_b)
-            _dual_answer += _ai_tools_footer(_ctx_articles)
-
-            follow_up_question, follow_up_suggestions = await _search_follow_up(_ctx_articles, model)
-            return AgentResponse(
-                answer=_dual_answer,
-                intent=intent,
-                tools_used=["primo_browser_link"],
-                search_results=[],
-                sources=[],
-                model_used=model,
-                response_time=time.time() - start_time,
-                corrected_query=topic,
-                natural_query=_ctx_articles.ai_tool_query,
-                primo_boolean_query=_ctx_articles.primo_boolean_query,
-                primo_search_url=_src_url_a,
-                follow_up_question=follow_up_question,
-                follow_up_suggestions=follow_up_suggestions,
-                search_context=_context_to_dict(_ctx_articles),
-            )
-
-        context = SearchContextPayload(
-            context_id=str(uuid.uuid4()),
-            topic=topic,
-            display_topic=topic,
-            intent=intent,
-            source="primo",
-            resource_type=_derive_resource_type(question),
-            peer_reviewed=bool(re.search(r"\bpeer[- ]reviewed\b", question, re.IGNORECASE)),
-            open_access=bool(re.search(r"\bopen access\b", question, re.IGNORECASE)),
-            year_from=year_from,
-            year_to=year_to,
-        )
-
-        context = await _prepare_queries(question, context, model, False)
-        summary_mode = _is_summary_request(question)
-        deep_research_mode = bool(re.search(
-            r"\b(deep research|deep dive|systematic review|full literature review|exhaustive)\b",
-            question, re.IGNORECASE,
-        ))
-        is_highly_cited = bool(HIGHLY_CITED_RE.search(question))
-
-        if summary_mode or deep_research_mode:
-            answer, search_results, sources = await _research_snapshot(context, model)
-            if deep_research_mode and "Research guide" not in answer and "AI tools" not in answer:
-                answer += f"<br><br>{_ai_tools_footer(context)}"
-            if is_highly_cited:
-                answer += _highly_cited_note(_escape(topic))
-            follow_up_question, follow_up_suggestions = await _search_follow_up(context, model, summary_mode=True)
-            _safe_metrics_increment("search_handoffs")
-            return AgentResponse(
-                answer=answer,
-                intent=intent,
-                tools_used=["research_snapshot"],
-                search_results=search_results,
-                sources=sources,
-                model_used=model,
-                response_time=time.time() - start_time,
-                corrected_query=context.topic,
-                natural_query=context.ai_tool_query,
-                database_query=context.primo_boolean_query,
-                ai_tool_query=context.ai_tool_query,
-                primo_boolean_query=context.primo_boolean_query,
-                primo_search_url=_primo_clean_url(context),
-                primo_ai_url=_tool_urls(context).get("primo_ai"),
-                pubmed_search_url=_tool_urls(context).get("pubmed"),
-                follow_up_question=follow_up_question,
-                follow_up_suggestions=follow_up_suggestions,
-                search_context=_context_to_dict(context),
-            )
-
-        answer, search_results, sources, source_url = await _run_search_mode(question, context, model, False)
-        if is_highly_cited:
-            answer += _highly_cited_note(_escape(topic))
-        follow_up_question, follow_up_suggestions = await _search_follow_up(context, model)
-        return AgentResponse(
-            answer=answer,
-            intent=intent,
-            tools_used=["primo_inline" if context.source == "primo" else "pubmed_inline"],
-            search_results=search_results,
-            sources=sources,
-            model_used=model,
-            response_time=time.time() - start_time,
-            corrected_query=context.topic,
-            natural_query=context.ai_tool_query,
-            database_query=context.primo_boolean_query,
-            ai_tool_query=context.ai_tool_query,
-            primo_boolean_query=context.primo_boolean_query,
-            primo_search_url=source_url,
-            primo_ai_url=_tool_urls(context).get("primo_ai"),
-            pubmed_search_url=_tool_urls(context).get("pubmed"),
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-            search_context=_context_to_dict(context),
-        )
-
-    if intent == "general_recent":
-        answer = await _web_search_answer(question, history, model) + _source_badge("web_live")
-        follow_up_question, follow_up_suggestions = _general_follow_up(question)
-        return AgentResponse(
-            answer=_thought_block("general_recent", "web_search", question) + answer,
-            intent="general_recent",
-            tools_used=["web_search"],
-            model_used=model,
-            response_time=time.time() - start_time,
-            follow_up_question=follow_up_question,
-            follow_up_suggestions=follow_up_suggestions,
-        )
-
-    # general fallback
-    answer = await _web_search_answer(question, history, model) + _source_badge("web")
-    follow_up_question, follow_up_suggestions = _general_follow_up(question)
-    return AgentResponse(
-        answer=_thought_block("general", "web_search", question) + answer,
-        intent="general",
-        tools_used=["web_search"],
-        model_used=model,
-        response_time=time.time() - start_time,
-        follow_up_question=follow_up_question,
-        follow_up_suggestions=follow_up_suggestions,
-    )

src/agentcore/rendering.py

@@ -1,590 +1,590 @@
-"""HTML fragment renderers: source badges, reasoning trace blocks, AI-tools footer, contacts."""
-import asyncio
-import html
-import json
-import logging
-import os
-import re
-import time
-import uuid
-from datetime import datetime
-from typing import Any, Dict, List, Literal, Optional, Tuple
-from urllib.parse import quote
-
-import httpx
-from pydantic import BaseModel, ConfigDict, Field
-
-from src.config import get_settings, LIBBEE_VERSION
-from src.services.staff_service import (
-    STAFF_DIRECTORY,
-    match_staff_name,
-    match_staff_role,
-    should_attempt_staff_lookup,
-    staff_name_answer,
-    staff_role_answer,
-)
-
-from src.agentcore.models import SearchContextPayload
-from src.agentcore.constants import ASK_LIBRARIAN_URL, PRIMO_AI_URL
-from src.agentcore.utils import (
-    _escape,
-    _find_staff_by_token,
-    _primo_clean_url,
-    _shared_build_pubmed_url,
-)
-
-logger = logging.getLogger(__name__)
-
-def _source_badge(source: str, url: str = "") -> str:
-    styles = {
-        "rag": ("📖", "KU Library Knowledge Base", "#fef3c7", "#92400e"),
-        "primo": ("📚", "KU Library PRIMO", "#eff6ff", "#1e40af"),
-        "semantic": ("🎓", "Semantic Scholar", "#f0fdf4", "#166534"),
-        "consensus_badge": ("🧬", "Consensus", "#fdf4ff", "#86198f"),
-        "semantic_badge": ("🎓", "Semantic Scholar", "#f0fdf4", "#166534"),
-        "pubmed": ("🏥", "PubMed", "#d1fae5", "#065f46"),
-        "web": ("🌐", "Web Search", "#f5f3ff", "#4c1d95"),
-        "web_live": ("🌐", "Web Search · Live", "#fdf4ff", "#86198f"),
-        "libbee": ("🐝", "LibBee", "#fef9c3", "#713f12"),
-        "ku_library": ("📋", "KU Library", "#eff6ff", "#1e40af"),
-        "llm": ("🤖", "AI Knowledge Base", "#f3f4f6", "#374151"),
-    }
-    icon, label, bg, fg = styles.get(source, ("ℹ️", source, "#f3f4f6", "#374151"))
-    inner = f"{icon} Source: {label}"
-    if url:
-        inner = f'<a href="{url}" target="_blank" style="color:{fg};text-decoration:none">{inner}</a>'
-    return (
-        f'<div style="margin-top:10px;display:inline-flex;align-items:center;gap:5px;'
-        f'padding:4px 10px;background:{bg};color:{fg};border-radius:20px;'
-        f'font-size:.72rem;font-weight:600;border:1px solid {fg}33">{inner}</div>'
-    )
-
-
-def _tool_urls(context: SearchContextPayload) -> Dict[str, str]:
-    ai_query = quote(context.ai_tool_query or context.display_topic or context.topic)
-    primo_ai_query = quote(context.ai_tool_query or context.display_topic or context.topic)
-    urls: Dict[str, str] = {
-        "leapspace": f"https://www.sciencedirect.com/leapspace?query={ai_query}",
-        "scopus_ai": f"https://www-scopus-com.khalifa.idm.oclc.org/pages/ai?query={ai_query}",
-        "ebsco_ai": (
-            f"https://research-ebsco-com.khalifa.idm.oclc.org/c/yst6t2/search/results"
-            f"?q={ai_query}"
-            f"&autocorrect=y"
-            f"&expanders=concept"
-            f"&limiters=None"
-            f"&searchMode=enhanced"
-            f"&searchSegment=all-results"
-        ),
-        "primo_ai": f"{PRIMO_AI_URL}{primo_ai_query}",
-        "consensus": f"https://consensus.app/results/?q={ai_query}",
-        "primo_discovery": _primo_clean_url(context),
-    }
-    if context.intent == "search_medical":
-        urls["pubmed"] = _shared_build_pubmed_url(
-            context.topic, context.year_from, context.year_to, context.peer_reviewed
-        )
-    return urls
-
-
-def _contact_footer_for_query(question: str, context: Optional[SearchContextPayload]) -> str:
-    q = (question or "").lower()
-    specialist: Optional[dict] = None
-    if any(t in q for t in ["interlibrary", "ill request", "ill form", "borrow from another",
-                              "request article", "request a book", "not available at ku",
-                              "not in ku library", "inter library", "inter-library"]):
-        footer = (
-            "<br><br><strong>Library contact points</strong><br>"
-            f'General help: <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a> · '
-            '<a href="mailto:libse@ku.ac.ae">libse@ku.ac.ae</a><br>'
-            'ILL requests: <a href="mailto:ill@ku.ac.ae">ill@ku.ac.ae</a> · '
-            '<strong>Suaad Al Jneibi</strong> · '
-            '<a href="mailto:suaad.aljneibi@ku.ac.ae">suaad.aljneibi@ku.ac.ae</a> · '
-            '<a href="tel:+97123124278">+971 2 312 4278</a>'
-        )
-        return footer
-    elif any(t in q for t in [
-        "apc", "article processing charge", "article processing fee",
-        "open access fee", "oa fee", "oa fund", "oa publishing",
-        "publish open access", "open access publish", "how to publish open access",
-        "open access journal", "open access mandate", "open access policy",
-        "waiver", "gold open access", "diamond open access", "hybrid journal",
-        "creative commons", "cc by", "cc licence", "openaccess", "open access",
-    ]):
-        # Open Access & APC → Walter Brian Hall (OA lead at KU Library)
-        specialist = _find_staff_by_token("walter")
-    elif any(t in q for t in [
-        "research support", "research service", "research consultation",
-        "research librarian", "research help", "research advice",
-        "scholarly communication", "bibliometric", "research impact",
-        "citation analysis", "h-index", "journal ranking", "impact factor",
-        "orcid", "khazna", "repository", "scival", "scopus profile",
-        "author profile", "research data", "data management",
-        "libguide", "research guide", "ai tool", "ai for research",
-        "publication advice", "journal selection", "where to publish",
-    ]):
-        # Research services → Nikesh Narayanan (Research & Access Services Librarian)
-        specialist = _find_staff_by_token("nikesh")
-    elif any(t in q for t in ["database access", "proxy", "eresource",
-                               "e-resource", "remote access", "access problem", "off campus"]):
-        specialist = _find_staff_by_token("rani")
-    elif any(t in q for t in ["website", "system", "technical", "login issue", "page not loading"]):
-        specialist = _find_staff_by_token("walter")
-    elif context and context.intent == "search_medical":
-        # Medical/clinical research questions only → Jason Fetty (Medical Librarian)
-        specialist = _find_staff_by_token("jason")
-    elif context and context.intent == "search_academic":
-        specialist = _find_staff_by_token("nikesh")
-    footer = (
-        "<br><br><strong>Library contact points</strong><br>"
-        f'General help: <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a> · '
-        '<a href="mailto:libse@ku.ac.ae">libse@ku.ac.ae</a>'
-    )
-    if specialist:
-        footer += (
-            f'<br>Relevant contact: <strong>{_escape(specialist.get("full_name", ""))}</strong> — '
-            f'{_escape(specialist.get("role", ""))}<br>'
-            f'<a href="mailto:{_escape(specialist.get("email", ""))}">{_escape(specialist.get("email", ""))}</a>'
-        )
-        phone = specialist.get("phone") or specialist.get("work_phone")
-        if phone:
-            footer += f' · <a href="tel:{_escape(str(phone).replace(" ", ""))}">{_escape(phone)}</a>'
-    return footer
-
-
-def _thought_block(intent: str, tool: str, question: str, extra: str = "") -> str:
-    labels = {
-        "library_info":    ("📋", "Library information lookup", "I searched the KU Library knowledge base for relevant content."),
-        "general":         ("🌐", "General knowledge / web search", "I answered using a web search for current information."),
-        "general_recent":  ("🔴", "Live web search", "I ran a live web search for the most up-to-date information."),
-        "social_greeting": ("🐝", "Conversational response", "I responded directly as LibBee, the KU Library AI Assistant."),
-        "social":          ("🐝", "Conversational response", "I responded directly as LibBee, the KU Library AI Assistant."),
-        "staff_lookup":    ("👤", "Staff directory lookup", "I matched your request to the KU Library staff directory."),
-        "hours":           ("⏰", "Library hours lookup", "I fetched live library hours from the KU LibCal API."),
-        "libcal_live":     ("⏰", "Live library hours", "I fetched real-time hours from the KU LibCal API."),
-        "campus":          ("📍", "Campus information lookup", "I retrieved KU Library campus information from the knowledge base."),
-        "database_rec":    ("🗄️", "Database recommendation", "I matched your subject to the KU Library e-resources database."),
-        "rag_search":      ("📖", "Knowledge base search", "I ran a hybrid semantic + keyword search across the KU Library knowledge base."),
-    }
-    icon, label, reasoning = labels.get(intent, ("🤖", "AI response", "I processed your question and generated a response."))
-    if extra:
-        reasoning += " " + extra
-    return (
-        f'<details style="margin:0 0 12px 0;border:1px solid #e5e7eb;border-radius:10px;'
-        f'background:#fafafa;overflow:hidden">'
-        f'<summary style="padding:8px 12px;cursor:pointer;font-size:.75rem;font-weight:700;'
-        f'color:#6b7280;list-style:none;display:flex;align-items:center;gap:5px">'
-        f'<span>{icon}</span> My approach — click to see</summary>'
-        f'<div style="padding:4px 12px 10px 12px;font-size:.79rem;line-height:1.7;border-top:1px solid #e5e7eb">'
-        f'<strong>Question:</strong> {_escape(question)}<br>'
-        f'<strong>Classified as:</strong> {label}<br>'
-        f'<strong>How I answered:</strong> {reasoning}'
-        f'</div></details>'
-    )
-
-
-def _search_trace_block(question: str, context: SearchContextPayload) -> str:
-    topic = _escape(context.display_topic or context.topic)
-    primo_boolean = _escape(context.primo_boolean_query or "")
-    source_label = "PubMed" if context.source == "pubmed" else "KU PRIMO Library Discovery"
-    intent_label = {
-        "search_academic": "academic literature search",
-        "search_medical": "medical / clinical literature search",
-    }.get(context.intent, "library search")
-    filters_parts = []
-    if context.peer_reviewed:
-        filters_parts.append("peer reviewed only")
-    if context.open_access:
-        filters_parts.append("open access")
-    if context.year_from and context.year_to:
-        filters_parts.append(f"{context.year_from}–{context.year_to}")
-    elif context.year_from:
-        filters_parts.append(f"from {context.year_from}")
-    rtype = {"articles": "articles", "books": "books", "both": "articles and books"}.get(
-        context.resource_type, "articles"
-    )
-    filters_parts.append(rtype)
-    filters_str = ", ".join(filters_parts)
-    reasoning = (
-        f"I classified this as a <strong>{intent_label}</strong>, "
-        f"extracted the topic <strong>{topic}</strong>, "
-        f"built an LLM-optimised boolean query with quoted phrases and OR synonyms, "
-        f"then searched <strong>{source_label}</strong> for <strong>{filters_str}</strong>."
-    )
-    if context.intent == "search_medical" and context.source != "pubmed":
-        reasoning += " For medical topics, PubMed and Embase are also recommended."
-    block = (
-        f'<details style="margin:0 0 14px 0;border:1px solid #dbe4ff;border-radius:12px;background:#f8fbff;overflow:hidden">'
-        f'<summary style="padding:10px 14px;cursor:pointer;font-size:.8rem;font-weight:700;color:#1e40af;list-style:none;display:flex;align-items:center;gap:6px">'
-        f'<span style="font-size:.9rem">🔍</span> How I searched — click to expand'
-        f'</summary>'
-        f'<div style="padding:4px 14px 12px 14px;font-size:.82rem;line-height:1.7;border-top:1px solid #dbe4ff">'
-        f'<strong>Your question:</strong> {_escape(question)}<br>'
-        f'<strong>Interpreted topic:</strong> {topic}<br>'
-    )
-    if primo_boolean:
-        block += (
-            f'<strong>Boolean query sent to {source_label}:</strong><br>'
-            f'<code style="display:block;margin:4px 0;padding:6px 10px;background:#1a1a2e;color:#C8A951;'
-            f'border-radius:7px;font-size:.78rem;word-break:break-all">{primo_boolean}</code>'
-        )
-    block += f'<strong>Reasoning:</strong> {reasoning}<br>'
-    block += '<span style="color:#5b21b6;font-size:.78rem">✨ AI research tools for deeper exploration are listed at the end of this answer.</span>'
-    block += '</div></details>'
-    return block
-
-
-def _ai_tools_footer(context):
-    from urllib.parse import quote as _q
-
-    ai_q      = _q(context.ai_tool_query or context.display_topic or context.topic)
-    bool_q    = context.primo_boolean_query or ""
-    primo_url = _primo_clean_url(context)
-    primo_ai  = PRIMO_AI_URL + ai_q
-    is_med    = context.intent == "search_medical"
-    pubmed_url = _shared_build_pubmed_url(
-        context.topic, context.year_from, context.year_to, context.peer_reviewed
-    ) if is_med else ""
-
-    KU = "https://khalifa.idm.oclc.org/login?url="
-
-    platforms = [
-        ("PRIMO AI Assistant", primo_ai, "primo"),
-        ("LeapSpace", "https://www.sciencedirect.com/leapspace?query=" + ai_q, "leapspace"),
-        ("Scopus AI", "https://www-scopus-com.khalifa.idm.oclc.org/pages/ai?query=" + ai_q, "scopus"),
-        ("EBSCO Research AI",
-         "https://research-ebsco-com.khalifa.idm.oclc.org/c/yst6t2/search/results?q=" + ai_q
-         + "&autocorrect=y&expanders=concept&limiters=None&searchMode=enhanced&searchSegment=all-results", "ebsco"),
-        ("Consensus", "https://consensus.app/results/?q=" + ai_q, "consensus"),
-        ("Semantic Scholar", "https://www.semanticscholar.org/search?q=" + ai_q + "&sort=relevance", "semanticscholar"),
-        ("Perplexity", "https://www.perplexity.ai/search?q=" + ai_q, "perplexity"),
-    ]
-    if is_med and pubmed_url:
-        platforms.append(("PubMed", pubmed_url, "pubmed"))
-
-    _SVGS = {
-        "bee": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" width="16" height="16" style="flex-shrink:0">'
-            '<ellipse cx="5.5" cy="9" rx="5" ry="2.5" fill="#a8d4f0" opacity=".85"/>'
-            '<ellipse cx="14.5" cy="9" rx="5" ry="2.5" fill="#a8d4f0" opacity=".85"/>'
-            '<ellipse cx="10" cy="13" rx="5" ry="6" fill="#1a3a6b"/>'
-            '<ellipse cx="10" cy="15" rx="3" ry="1.5" fill="#243f7a"/>'
-            '<circle cx="10" cy="8" r="5" fill="#1a3a6b"/>'
-            '<rect x="6" y="6.5" width="8" height="3.5" rx="1.5" fill="#001a40"/>'
-            '<ellipse cx="8.2" cy="8.2" rx="1.5" ry="1.2" fill="#00ccee" opacity=".9"/>'
-            '<ellipse cx="11.8" cy="8.2" rx="1.5" ry="1.2" fill="#00ccee" opacity=".9"/>'
-            '<path d="M8 10 Q10 11.5 12 10" fill="none" stroke="#00ccee" stroke-width=".8" stroke-linecap="round"/>'
-            '<line x1="8.5" y1="3.5" x2="6.5" y2="1.5" stroke="#1a3a6b" stroke-width="1.2" stroke-linecap="round"/>'
-            '<circle cx="6.5" cy="1.5" r="1.2" fill="#00ccee" opacity=".8"/>'
-            '<line x1="11.5" y1="3.5" x2="13.5" y2="1.5" stroke="#1a3a6b" stroke-width="1.2" stroke-linecap="round"/>'
-            '<ellipse cx="13.5" cy="1.2" rx="1.5" ry="1.8" fill="#e8e8e8" stroke="#aaa" stroke-width=".5"/>'
-            '<text x="10" y="17.5" font-family="Arial,sans-serif" font-size="3" font-weight="bold" fill="#C8A951" text-anchor="middle">LB</text>'
-            '</svg>'
-        ),
-        "book": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="2" y="2" width="9" height="12" rx="1" fill="#2563eb"/>'
-            '<rect x="3" y="2" width="1.5" height="12" fill="#1d4ed8"/>'
-            '<rect x="4" y="4" width="5" height="1" rx=".5" fill="#bfdbfe"/>'
-            '<rect x="4" y="6" width="5" height="1" rx=".5" fill="#bfdbfe"/>'
-            '<rect x="4" y="8" width="3" height="1" rx=".5" fill="#bfdbfe"/>'
-            '<rect x="11" y="3" width="3" height="10" rx="1" fill="#1e40af"/>'
-            '</svg>'
-        ),
-        "microscope": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="7" y="1" width="2" height="5" rx="1" fill="#6b7280"/>'
-            '<ellipse cx="8" cy="1.5" rx="2.5" ry="1.5" fill="#9ca3af"/>'
-            '<rect x="6.5" y="5" width="3" height="5" rx=".5" fill="#374151"/>'
-            '<rect x="5" y="9.5" width="6" height="1.5" rx=".5" fill="#374151"/>'
-            '<rect x="3" y="13" width="10" height="1.5" rx=".5" fill="#374151"/>'
-            '<line x1="8" y1="11" x2="8" y2="13" stroke="#374151" stroke-width="1.5"/>'
-            '<circle cx="8" cy="6" r="1.5" fill="#60a5fa" opacity=".8"/>'
-            '</svg>'
-        ),
-        "circuit": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#1e293b"/>'
-            '<circle cx="4" cy="4" r="1.5" fill="#22d3ee"/>'
-            '<circle cx="12" cy="4" r="1.5" fill="#22d3ee"/>'
-            '<circle cx="4" cy="12" r="1.5" fill="#22d3ee"/>'
-            '<circle cx="12" cy="12" r="1.5" fill="#22d3ee"/>'
-            '<circle cx="8" cy="8" r="2" fill="#06b6d4"/>'
-            '<line x1="4" y1="4" x2="8" y2="8" stroke="#22d3ee" stroke-width=".8"/>'
-            '<line x1="12" y1="4" x2="8" y2="8" stroke="#22d3ee" stroke-width=".8"/>'
-            '<line x1="4" y1="12" x2="8" y2="8" stroke="#22d3ee" stroke-width=".8"/>'
-            '<line x1="12" y1="12" x2="8" y2="8" stroke="#22d3ee" stroke-width=".8"/>'
-            '</svg>'
-        ),
-        "leaf": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<path d="M8 14 C8 14 2 10 2 5 C2 2 5 1 8 1 C11 1 14 2 14 5 C14 10 8 14 8 14Z" fill="#16a34a"/>'
-            '<line x1="8" y1="1" x2="8" y2="14" stroke="#bbf7d0" stroke-width=".8"/>'
-            '<line x1="8" y1="5" x2="5" y2="7" stroke="#bbf7d0" stroke-width=".6"/>'
-            '<line x1="8" y1="7" x2="5" y2="9" stroke="#bbf7d0" stroke-width=".6"/>'
-            '<line x1="8" y1="5" x2="11" y2="7" stroke="#bbf7d0" stroke-width=".6"/>'
-            '<line x1="8" y1="7" x2="11" y2="9" stroke="#bbf7d0" stroke-width=".6"/>'
-            '</svg>'
-        ),
-        "gear": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<path d="M6.5 1h3l.5 1.5a5 5 0 011.2.7l1.5-.5 1.5 2.6-1.2 1a5 5 0 010 1.4l1.2 1-1.5 2.6-1.5-.5a5 5 0 01-1.2.7L9.5 15h-3l-.5-1.5a5 5 0 01-1.2-.7l-1.5.5L1.8 10.8l1.2-1a5 5 0 010-1.4l-1.2-1L3.3 4.8l1.5.5A5 5 0 016 4.5L6.5 1z" fill="#64748b"/>'
-            '<circle cx="8" cy="8" r="2.5" fill="#f1f5f9"/>'
-            '<circle cx="8" cy="8" r="1.2" fill="#64748b"/>'
-            '</svg>'
-        ),
-        "chart": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="1" y="1" width="14" height="14" rx="1.5" fill="#f0fdf4"/>'
-            '<rect x="3" y="9" width="2" height="5" rx=".5" fill="#16a34a"/>'
-            '<rect x="7" y="6" width="2" height="8" rx=".5" fill="#15803d"/>'
-            '<rect x="11" y="3" width="2" height="11" rx=".5" fill="#166534"/>'
-            '<line x1="1" y1="13.5" x2="15" y2="13.5" stroke="#166534" stroke-width=".8"/>'
-            '</svg>'
-        ),
-        "atom": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<ellipse cx="8" cy="8" rx="7" ry="3" fill="none" stroke="#7c3aed" stroke-width=".9"/>'
-            '<ellipse cx="8" cy="8" rx="7" ry="3" fill="none" stroke="#7c3aed" stroke-width=".9" transform="rotate(60 8 8)"/>'
-            '<ellipse cx="8" cy="8" rx="7" ry="3" fill="none" stroke="#7c3aed" stroke-width=".9" transform="rotate(120 8 8)"/>'
-            '<circle cx="8" cy="8" r="1.8" fill="#7c3aed"/>'
-            '</svg>'
-        ),
-        "medical": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#dc2626"/>'
-            '<rect x="6.5" y="3" width="3" height="10" rx="1" fill="white"/>'
-            '<rect x="3" y="6.5" width="10" height="3" rx="1" fill="white"/>'
-            '</svg>'
-        ),
-        "wrench": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<path d="M13 2a3 3 0 00-3 3c0 .4.1.8.2 1.1L2.6 13.7a1 1 0 001.4 1.4L11.7 7.8c.3.1.7.2 1.1.2a3 3 0 000-6z" fill="#d97706"/>'
-            '<circle cx="12" cy="4" r="1.2" fill="#fef3c7"/>'
-            '</svg>'
-        ),
-        "primo": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#003366"/>'
-            '<rect x="3" y="4" width="10" height="1.5" rx=".5" fill="#C8A951"/>'
-            '<rect x="3" y="7" width="7" height="1.5" rx=".5" fill="white" opacity=".9"/>'
-            '<rect x="3" y="10" width="9" height="1.5" rx=".5" fill="white" opacity=".7"/>'
-            '<circle cx="12" cy="11" r="2.5" fill="#C8A951"/>'
-            '<line x1="11" y1="11" x2="13" y2="11" stroke="#003366" stroke-width=".8"/>'
-            '<line x1="12" y1="10" x2="12" y2="12" stroke="#003366" stroke-width=".8"/>'
-            '</svg>'
-        ),
-        "scopus": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#e8650a"/>'
-            '<text x="8" y="11.5" font-family="Arial,sans-serif" font-size="8" font-weight="bold" fill="white" text-anchor="middle">Sc</text>'
-            '</svg>'
-        ),
-        "ebsco": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#00427a"/>'
-            '<text x="8" y="11.5" font-family="Arial,sans-serif" font-size="7" font-weight="bold" fill="white" text-anchor="middle">EBS</text>'
-            '</svg>'
-        ),
-        "consensus": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="1" y="1" width="14" height="14" rx="7" fill="#6c47ff"/>'
-            '<circle cx="6" cy="7" r="1.2" fill="white"/>'
-            '<circle cx="10" cy="7" r="1.2" fill="white"/>'
-            '<path d="M5 10 Q8 12.5 11 10" fill="none" stroke="white" stroke-width="1.2" stroke-linecap="round"/>'
-            '</svg>'
-        ),
-        "leapspace": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#ff6b00"/>'
-            '<path d="M4 12 L4 7 L8 4 L12 7 L12 12 Z" fill="white" opacity=".9"/>'
-            '<rect x="6.5" y="9" width="3" height="3" fill="#ff6b00"/>'
-            '</svg>'
-        ),
-        "perplexity": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#1a1a2e"/>'
-            '<circle cx="8" cy="6.5" r="3" fill="none" stroke="#20b2aa" stroke-width="1.2"/>'
-            '<line x1="8" y1="9.5" x2="8" y2="13" stroke="#20b2aa" stroke-width="1.2" stroke-linecap="round"/>'
-            '<circle cx="8" cy="13" r=".8" fill="#20b2aa"/>'
-            '</svg>'
-        ),
-        "semanticscholar": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#1857b6"/>'
-            '<path d="M4 11 Q8 4 12 11" fill="none" stroke="white" stroke-width="1.5" stroke-linecap="round"/>'
-            '<circle cx="8" cy="7" r="1.8" fill="#4fc3f7"/>'
-            '</svg>'
-        ),
-        "pubmed": (
-            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
-            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#336699"/>'
-            '<text x="8" y="11" font-family="Arial,sans-serif" font-size="6.5" font-weight="bold" fill="white" text-anchor="middle">PubMed</text>'
-            '</svg>'
-        ),
-    }
-    _DB_MASCOT = {
-        "PubMed@KU": "microscope", "Embase": "medical", "CINAHL Ultimate": "medical",
-        "Cochrane Library": "microscope", "UpToDate": "medical",
-        "IEEE Xplore": "circuit", "ACM Digital Library": "circuit",
-        "ScienceDirect": "microscope", "Scopus": "microscope",
-        "Web of Science": "microscope", "SpringerLink": "book",
-        "ACS Publications": "atom", "APS Journals": "atom", "Knovel": "wrench",
-        "Business Source Complete": "chart", "Emerald Insight": "chart",
-        "Taylor & Francis": "book", "EBSCO": "book",
-    }
-    _BEE = _SVGS["bee"]
-
-    def _btn(label, url, mascot_key="bee"):
-        icon = _SVGS.get(mascot_key, _SVGS["bee"])
-        style = (
-            'display:inline-flex;align-items:center;gap:7px;'
-            'padding:8px 14px;border-radius:10px;text-decoration:none;'
-            'font-size:.8rem;font-weight:600;color:#1a1a2e;'
-            'background:#fff;border:1.5px solid #d1d5db;'
-            'transition:box-shadow .2s;width:100%;box-sizing:border-box'
-        )
-        return '<a href="' + url + '" target="_blank" style="' + style + '">' + icon + label + '</a>'
-
-    btn_rows = ""
-    for k in range(0, len(platforms), 2):
-        pair = platforms[k:k+2]
-        cells = ""
-        for lbl, url, mascot_key in pair:
-            cells += '<td style="width:50%;padding:3px 4px 3px 0">' + _btn(lbl, url, mascot_key) + '</td>'
-        if len(pair) == 1:
-            cells += '<td style="width:50%"></td>'
-        btn_rows += "<tr>" + cells + "</tr>"
-
-    platforms_html = (
-        '<div style="margin-top:18px;padding:14px 16px;border:1px solid #c4b5fd;'
-        'border-radius:12px;background:linear-gradient(135deg,#f5f3ff,#fdf4ff)">'
-        '<div style="font-size:.8rem;font-weight:800;color:#5b21b6;margin-bottom:4px">'
-        '🤖 Search your query across AI platforms</div>'
-        '<div style="font-size:.73rem;color:#6b7280;margin-bottom:10px">'
-        'Your query is pre-loaded. Click any platform to search instantly.</div>'
-        '<table style="width:100%;border-collapse:collapse">' + btn_rows + '</table>'
-        '</div>'
-    )
-
-    if bool_q:
-        and_count = bool_q.upper().count(" AND ")
-        if and_count >= 1:
-            bool_label = "Use this in PRIMO Advanced Search or any database for precise results:"
-        else:
-            bool_label = "Try adding synonyms with OR to find more relevant results:"
-        bool_html = (
-            '<div style="margin-top:12px;padding:12px 14px;border:1px solid #fde68a;'
-            'border-radius:10px;background:#fffbeb">'
-            '<div style="font-size:.78rem;font-weight:700;color:#92400e;margin-bottom:6px">'
-            '\U0001f4a1 Boolean search tip</div>'
-            '<div style="font-size:.74rem;color:#6b7280;margin-bottom:6px">' + bool_label + '</div>'
-            '<code style="display:block;padding:8px 10px;background:#1a1a2e;color:#C8A951;'
-            'border-radius:7px;font-size:.76rem;word-break:break-all;white-space:pre-wrap">'
-            + _escape(bool_q) +
-            '</code>'
-            '<div style="font-size:.71rem;color:#92400e;margin-top:6px">'
-            'Paste into the Advanced Search box of any database below.</div>'
-            '</div>'
-        )
-    else:
-        bool_html = ""
-
-    all_lower = ((context.ai_tool_query or "") + " " + (context.topic or "")).lower()
-
-    def _db_row(name, url, desc, favicon=None):
-        icon = _SVGS.get(_DB_MASCOT.get(name, "bee"), _SVGS["bee"])
-        return (
-            '<div style="display:flex;align-items:center;gap:8px;'
-            'padding:7px 0;border-bottom:1px solid #f3f4f6">'
-            + icon +
-            '<div><a href="' + url + '" target="_blank" '
-            'style="font-size:.8rem;font-weight:700;color:#003366;text-decoration:none">'
-            + name + '</a>'
-            '<span style="font-size:.73rem;color:#6b7280"> — ' + desc + '</span></div>'
-            '</div>'
-        )
-
-    if any(k in all_lower for k in ["medicine","medical","clinical","nursing","pharmacy","health","pubmed","embase","cinahl","cochrane","uptodate"]):
-        db_subject = "Medicine & Health Sciences"
-        dbs = [
-            ("PubMed@KU","http://www.ncbi.nlm.nih.gov/pubmed/?otool=iaekustlib","Core biomedical literature"),
-            ("Embase",KU+"https://www.embase.com","Biomedical, drugs, devices, clinical medicine"),
-            ("CINAHL Ultimate",KU+"https://search.ebscohost.com/login.aspx?authtype=ip,uid&profile=ehost&defaultdb=cul","Nursing and allied health"),
-            ("Cochrane Library",KU+"https://www.cochranelibrary.com","Systematic reviews and evidence-based medicine"),
-            ("UpToDate",KU+"https://www.uptodate.com","Point-of-care clinical decision support"),
-        ]
-    elif any(k in all_lower for k in ["machine learning","deep learning","artificial intelligence","neural network","computer science","software","algorithm","cybersecurity","robotics","nlp"]):
-        db_subject = "Computer Science & AI"
-        dbs = [
-            ("IEEE Xplore",KU+"https://ieeexplore.ieee.org","Core CS, AI, electronics and systems"),
-            ("ACM Digital Library",KU+"https://dl.acm.org","Computer science journals, proceedings and books"),
-            ("ScienceDirect",KU+"https://www.sciencedirect.com","Full text across CS and applied computing"),
-            ("Scopus",KU+"https://www.scopus.com","Discovery and citation tracking"),
-            ("Web of Science",KU+"https://www.webofscience.com","Citation index"),
-        ]
-    elif any(k in all_lower for k in ["climate","global warming","environment","sustainability","ecology","carbon","emission","renewable","sea level","maldives","island"]):
-        db_subject = "Environment & Climate"
-        dbs = [
-            ("ScienceDirect",KU+"https://www.sciencedirect.com","Full text across science, environment and engineering"),
-            ("Scopus",KU+"https://www.scopus.com","Broad discovery and citation tracking"),
-            ("Web of Science",KU+"https://www.webofscience.com","High-impact journal coverage and citation index"),
-            ("SpringerLink",KU+"https://link.springer.com","Springer journals and books"),
-        ]
-    elif any(k in all_lower for k in ["engineering","mechanical","civil","electrical","aerospace","structural","petroleum","chemical","materials"]):
-        db_subject = "Engineering"
-        dbs = [
-            ("IEEE Xplore",KU+"https://ieeexplore.ieee.org","Electrical, electronics and systems engineering"),
-            ("ScienceDirect",KU+"https://www.sciencedirect.com","Full text across engineering disciplines"),
-            ("Knovel",KU+"https://app.knovel.com","Engineering handbooks and reference data"),
-            ("Scopus",KU+"https://www.scopus.com","Discovery and citation tracking"),
-            ("Web of Science",KU+"https://www.webofscience.com","Citation index"),
-        ]
-    elif any(k in all_lower for k in ["business","management","finance","economics","leadership","marketing","strategy","entrepreneurship"]):
-        db_subject = "Business & Management"
-        dbs = [
-            ("Business Source Complete",KU+"https://search.ebscohost.com","Core business and management literature"),
-            ("Emerald Insight",KU+"https://www.emerald.com/insight","Management, strategy and leadership"),
-            ("Scopus",KU+"https://www.scopus.com","Broad discovery and citation tracking"),
-            ("ScienceDirect",KU+"https://www.sciencedirect.com","Business and social sciences full text"),
-        ]
-    elif any(k in all_lower for k in ["physics","chemistry","quantum","nuclear","materials science","nanotechnology","optics"]):
-        db_subject = "Physics, Chemistry & Materials"
-        dbs = [
-            ("ScienceDirect",KU+"https://www.sciencedirect.com","Full text across physical sciences"),
-            ("ACS Publications",KU+"https://pubs.acs.org","Core chemistry and chemical engineering"),
-            ("APS Journals",KU+"https://journals.aps.org","American Physical Society core physics journals"),
-            ("Scopus",KU+"https://www.scopus.com","Discovery and citation tracking"),
-            ("Web of Science",KU+"https://www.webofscience.com","Citation index"),
-        ]
-    else:
-        db_subject = "General"
-        dbs = [
-            ("EBSCO",KU+"https://search.ebscohost.com","Multidisciplinary full text"),
-            ("ScienceDirect",KU+"https://www.sciencedirect.com","Science, engineering and medicine"),
-            ("SpringerLink",KU+"https://link.springer.com","Journals and books across all disciplines"),
-            ("Taylor & Francis",KU+"https://www.tandfonline.com","Humanities, social sciences and STEM"),
-            ("Emerald Insight",KU+"https://www.emerald.com/insight","Management and social sciences"),
-            ("Scopus",KU+"https://www.scopus.com","Citation discovery, all disciplines"),
-            ("Web of Science",KU+"https://www.webofscience.com","Citation index, all disciplines"),
-        ]
-
-    dbs_html_rows = ""
-    for name, url, desc in dbs:
-        dbs_html_rows += _db_row(name, url, desc)
-
-    db_section = (
-        '<div style="margin-top:12px;padding:12px 14px;border:1px solid #d1d5db;'
-        'border-radius:10px;background:#f9fafb">'
-        '<div style="font-size:.78rem;font-weight:700;color:#003366;margin-bottom:8px">'
-        '\U0001f4c2 Recommended KU databases \u2014 ' + db_subject + '</div>'
-        + dbs_html_rows +
-        '<div style="padding-top:8px;font-size:.74rem">'
-        '<a href="https://library.ku.ac.ae/eresources" target="_blank" '
-        'style="color:#003366;font-weight:700">'
-        '\U0001f5c4\ufe0f Browse all 50+ KU databases \u2192</a></div>'
-        '</div>'
-    )
-
-    return platforms_html + bool_html + db_section
-
-
+"""HTML fragment renderers: source badges, reasoning trace blocks, AI-tools footer, contacts."""
+import asyncio
+import html
+import json
+import logging
+import os
+import re
+import time
+import uuid
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from src.config import get_settings, LIBBEE_VERSION
+from src.services.staff_service import (
+    STAFF_DIRECTORY,
+    match_staff_name,
+    match_staff_role,
+    should_attempt_staff_lookup,
+    staff_name_answer,
+    staff_role_answer,
+)
+
+from src.agentcore.models import SearchContextPayload
+from src.agentcore.constants import ASK_LIBRARIAN_URL, PRIMO_AI_URL
+from src.agentcore.utils import (
+    _escape,
+    _find_staff_by_token,
+    _primo_clean_url,
+    _shared_build_pubmed_url,
+)
+
+logger = logging.getLogger(__name__)
+
+def _source_badge(source: str, url: str = "") -> str:
+    styles = {
+        "rag": ("📖", "KU Library Knowledge Base", "#fef3c7", "#92400e"),
+        "primo": ("📚", "KU Library PRIMO", "#eff6ff", "#1e40af"),
+        "semantic": ("🎓", "Semantic Scholar", "#f0fdf4", "#166534"),
+        "consensus_badge": ("🧬", "Consensus", "#fdf4ff", "#86198f"),
+        "semantic_badge": ("🎓", "Semantic Scholar", "#f0fdf4", "#166534"),
+        "pubmed": ("🏥", "PubMed", "#d1fae5", "#065f46"),
+        "web": ("🌐", "Web Search", "#f5f3ff", "#4c1d95"),
+        "web_live": ("🌐", "Web Search · Live", "#fdf4ff", "#86198f"),
+        "libbee": ("🐝", "LibBee", "#fef9c3", "#713f12"),
+        "ku_library": ("📋", "KU Library", "#eff6ff", "#1e40af"),
+        "llm": ("🤖", "AI Knowledge Base", "#f3f4f6", "#374151"),
+    }
+    icon, label, bg, fg = styles.get(source, ("ℹ️", source, "#f3f4f6", "#374151"))
+    inner = f"{icon} Source: {label}"
+    if url:
+        inner = f'<a href="{url}" target="_blank" style="color:{fg};text-decoration:none">{inner}</a>'
+    return (
+        f'<div style="margin-top:10px;display:inline-flex;align-items:center;gap:5px;'
+        f'padding:4px 10px;background:{bg};color:{fg};border-radius:20px;'
+        f'font-size:.72rem;font-weight:600;border:1px solid {fg}33">{inner}</div>'
+    )
+
+
+def _tool_urls(context: SearchContextPayload) -> Dict[str, str]:
+    ai_query = quote(context.ai_tool_query or context.display_topic or context.topic)
+    primo_ai_query = quote(context.ai_tool_query or context.display_topic or context.topic)
+    urls: Dict[str, str] = {
+        "leapspace": f"https://www.sciencedirect.com/leapspace?query={ai_query}",
+        "scopus_ai": f"https://www-scopus-com.khalifa.idm.oclc.org/pages/ai?query={ai_query}",
+        "ebsco_ai": (
+            f"https://research-ebsco-com.khalifa.idm.oclc.org/c/yst6t2/search/results"
+            f"?q={ai_query}"
+            f"&autocorrect=y"
+            f"&expanders=concept"
+            f"&limiters=None"
+            f"&searchMode=enhanced"
+            f"&searchSegment=all-results"
+        ),
+        "primo_ai": f"{PRIMO_AI_URL}{primo_ai_query}",
+        "consensus": f"https://consensus.app/results/?q={ai_query}",
+        "primo_discovery": _primo_clean_url(context),
+    }
+    if context.intent == "search_medical":
+        urls["pubmed"] = _shared_build_pubmed_url(
+            context.topic, context.year_from, context.year_to, context.peer_reviewed
+        )
+    return urls
+
+
+def _contact_footer_for_query(question: str, context: Optional[SearchContextPayload]) -> str:
+    q = (question or "").lower()
+    specialist: Optional[dict] = None
+    if any(t in q for t in ["interlibrary", "ill request", "ill form", "borrow from another",
+                              "request article", "request a book", "not available at ku",
+                              "not in ku library", "inter library", "inter-library"]):
+        footer = (
+            "<br><br><strong>Library contact points</strong><br>"
+            f'General help: <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a> · '
+            '<a href="mailto:libse@ku.ac.ae">libse@ku.ac.ae</a><br>'
+            'ILL requests: <a href="mailto:ill@ku.ac.ae">ill@ku.ac.ae</a> · '
+            '<strong>Suaad Al Jneibi</strong> · '
+            '<a href="mailto:suaad.aljneibi@ku.ac.ae">suaad.aljneibi@ku.ac.ae</a> · '
+            '<a href="tel:+97123124278">+971 2 312 4278</a>'
+        )
+        return footer
+    elif any(t in q for t in [
+        "apc", "article processing charge", "article processing fee",
+        "open access fee", "oa fee", "oa fund", "oa publishing",
+        "publish open access", "open access publish", "how to publish open access",
+        "open access journal", "open access mandate", "open access policy",
+        "waiver", "gold open access", "diamond open access", "hybrid journal",
+        "creative commons", "cc by", "cc licence", "openaccess", "open access",
+    ]):
+        # Open Access & APC → Walter Brian Hall (OA lead at KU Library)
+        specialist = _find_staff_by_token("walter")
+    elif any(t in q for t in [
+        "research support", "research service", "research consultation",
+        "research librarian", "research help", "research advice",
+        "scholarly communication", "bibliometric", "research impact",
+        "citation analysis", "h-index", "journal ranking", "impact factor",
+        "orcid", "khazna", "repository", "scival", "scopus profile",
+        "author profile", "research data", "data management",
+        "libguide", "research guide", "ai tool", "ai for research",
+        "publication advice", "journal selection", "where to publish",
+    ]):
+        # Research services → Nikesh Narayanan (Research & Access Services Librarian)
+        specialist = _find_staff_by_token("nikesh")
+    elif any(t in q for t in ["database access", "proxy", "eresource",
+                               "e-resource", "remote access", "access problem", "off campus"]):
+        specialist = _find_staff_by_token("rani")
+    elif any(t in q for t in ["website", "system", "technical", "login issue", "page not loading"]):
+        specialist = _find_staff_by_token("walter")
+    elif context and context.intent == "search_medical":
+        # Medical/clinical research questions only → Jason Fetty (Medical Librarian)
+        specialist = _find_staff_by_token("jason")
+    elif context and context.intent == "search_academic":
+        specialist = _find_staff_by_token("nikesh")
+    footer = (
+        "<br><br><strong>Library contact points</strong><br>"
+        f'General help: <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a> · '
+        '<a href="mailto:libse@ku.ac.ae">libse@ku.ac.ae</a>'
+    )
+    if specialist:
+        footer += (
+            f'<br>Relevant contact: <strong>{_escape(specialist.get("full_name", ""))}</strong> — '
+            f'{_escape(specialist.get("role", ""))}<br>'
+            f'<a href="mailto:{_escape(specialist.get("email", ""))}">{_escape(specialist.get("email", ""))}</a>'
+        )
+        phone = specialist.get("phone") or specialist.get("work_phone")
+        if phone:
+            footer += f' · <a href="tel:{_escape(str(phone).replace(" ", ""))}">{_escape(phone)}</a>'
+    return footer
+
+
+def _thought_block(intent: str, tool: str, question: str, extra: str = "") -> str:
+    labels = {
+        "library_info":    ("📋", "Library information lookup", "I searched the KU Library knowledge base for relevant content."),
+        "general":         ("🌐", "General knowledge / web search", "I answered using a web search for current information."),
+        "general_recent":  ("🔴", "Live web search", "I ran a live web search for the most up-to-date information."),
+        "social_greeting": ("🐝", "Conversational response", "I responded directly as LibBee, the KU Library AI Assistant."),
+        "social":          ("🐝", "Conversational response", "I responded directly as LibBee, the KU Library AI Assistant."),
+        "staff_lookup":    ("👤", "Staff directory lookup", "I matched your request to the KU Library staff directory."),
+        "hours":           ("⏰", "Library hours lookup", "I fetched live library hours from the KU LibCal API."),
+        "libcal_live":     ("⏰", "Live library hours", "I fetched real-time hours from the KU LibCal API."),
+        "campus":          ("📍", "Campus information lookup", "I retrieved KU Library campus information from the knowledge base."),
+        "database_rec":    ("🗄️", "Database recommendation", "I matched your subject to the KU Library e-resources database."),
+        "rag_search":      ("📖", "Knowledge base search", "I ran a hybrid semantic + keyword search across the KU Library knowledge base."),
+    }
+    icon, label, reasoning = labels.get(intent, ("🤖", "AI response", "I processed your question and generated a response."))
+    if extra:
+        reasoning += " " + extra
+    return (
+        f'<details style="margin:0 0 12px 0;border:1px solid #e5e7eb;border-radius:10px;'
+        f'background:#fafafa;overflow:hidden">'
+        f'<summary style="padding:8px 12px;cursor:pointer;font-size:.75rem;font-weight:700;'
+        f'color:#6b7280;list-style:none;display:flex;align-items:center;gap:5px">'
+        f'<span>{icon}</span> My approach — click to see</summary>'
+        f'<div style="padding:4px 12px 10px 12px;font-size:.79rem;line-height:1.7;border-top:1px solid #e5e7eb">'
+        f'<strong>Question:</strong> {_escape(question)}<br>'
+        f'<strong>Classified as:</strong> {label}<br>'
+        f'<strong>How I answered:</strong> {reasoning}'
+        f'</div></details>'
+    )
+
+
+def _search_trace_block(question: str, context: SearchContextPayload) -> str:
+    topic = _escape(context.display_topic or context.topic)
+    primo_boolean = _escape(context.primo_boolean_query or "")
+    source_label = "PubMed" if context.source == "pubmed" else "KU PRIMO Library Discovery"
+    intent_label = {
+        "search_academic": "academic literature search",
+        "search_medical": "medical / clinical literature search",
+    }.get(context.intent, "library search")
+    filters_parts = []
+    if context.peer_reviewed:
+        filters_parts.append("peer reviewed only")
+    if context.open_access:
+        filters_parts.append("open access")
+    if context.year_from and context.year_to:
+        filters_parts.append(f"{context.year_from}–{context.year_to}")
+    elif context.year_from:
+        filters_parts.append(f"from {context.year_from}")
+    rtype = {"articles": "articles", "books": "books", "both": "articles and books"}.get(
+        context.resource_type, "articles"
+    )
+    filters_parts.append(rtype)
+    filters_str = ", ".join(filters_parts)
+    reasoning = (
+        f"I classified this as a <strong>{intent_label}</strong>, "
+        f"extracted the topic <strong>{topic}</strong>, "
+        f"built an LLM-optimised boolean query with quoted phrases and OR synonyms, "
+        f"then searched <strong>{source_label}</strong> for <strong>{filters_str}</strong>."
+    )
+    if context.intent == "search_medical" and context.source != "pubmed":
+        reasoning += " For medical topics, PubMed and Embase are also recommended."
+    block = (
+        f'<details style="margin:0 0 14px 0;border:1px solid #dbe4ff;border-radius:12px;background:#f8fbff;overflow:hidden">'
+        f'<summary style="padding:10px 14px;cursor:pointer;font-size:.8rem;font-weight:700;color:#1e40af;list-style:none;display:flex;align-items:center;gap:6px">'
+        f'<span style="font-size:.9rem">🔍</span> How I searched — click to expand'
+        f'</summary>'
+        f'<div style="padding:4px 14px 12px 14px;font-size:.82rem;line-height:1.7;border-top:1px solid #dbe4ff">'
+        f'<strong>Your question:</strong> {_escape(question)}<br>'
+        f'<strong>Interpreted topic:</strong> {topic}<br>'
+    )
+    if primo_boolean:
+        block += (
+            f'<strong>Boolean query sent to {source_label}:</strong><br>'
+            f'<code style="display:block;margin:4px 0;padding:6px 10px;background:#1a1a2e;color:#C8A951;'
+            f'border-radius:7px;font-size:.78rem;word-break:break-all">{primo_boolean}</code>'
+        )
+    block += f'<strong>Reasoning:</strong> {reasoning}<br>'
+    block += '<span style="color:#5b21b6;font-size:.78rem">✨ AI research tools for deeper exploration are listed at the end of this answer.</span>'
+    block += '</div></details>'
+    return block
+
+
+def _ai_tools_footer(context):
+    from urllib.parse import quote as _q
+
+    ai_q      = _q(context.ai_tool_query or context.display_topic or context.topic)
+    bool_q    = context.primo_boolean_query or ""
+    primo_url = _primo_clean_url(context)
+    primo_ai  = PRIMO_AI_URL + ai_q
+    is_med    = context.intent == "search_medical"
+    pubmed_url = _shared_build_pubmed_url(
+        context.topic, context.year_from, context.year_to, context.peer_reviewed
+    ) if is_med else ""
+
+    KU = "https://khalifa.idm.oclc.org/login?url="
+
+    platforms = [
+        ("PRIMO AI Assistant", primo_ai, "primo"),
+        ("LeapSpace", "https://www.sciencedirect.com/leapspace?query=" + ai_q, "leapspace"),
+        ("Scopus AI", "https://www-scopus-com.khalifa.idm.oclc.org/pages/ai?query=" + ai_q, "scopus"),
+        ("EBSCO Research AI",
+         "https://research-ebsco-com.khalifa.idm.oclc.org/c/yst6t2/search/results?q=" + ai_q
+         + "&autocorrect=y&expanders=concept&limiters=None&searchMode=enhanced&searchSegment=all-results", "ebsco"),
+        ("Consensus", "https://consensus.app/results/?q=" + ai_q, "consensus"),
+        ("Semantic Scholar", "https://www.semanticscholar.org/search?q=" + ai_q + "&sort=relevance", "semanticscholar"),
+        ("Perplexity", "https://www.perplexity.ai/search?q=" + ai_q, "perplexity"),
+    ]
+    if is_med and pubmed_url:
+        platforms.append(("PubMed", pubmed_url, "pubmed"))
+
+    _SVGS = {
+        "bee": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" width="16" height="16" style="flex-shrink:0">'
+            '<ellipse cx="5.5" cy="9" rx="5" ry="2.5" fill="#a8d4f0" opacity=".85"/>'
+            '<ellipse cx="14.5" cy="9" rx="5" ry="2.5" fill="#a8d4f0" opacity=".85"/>'
+            '<ellipse cx="10" cy="13" rx="5" ry="6" fill="#1a3a6b"/>'
+            '<ellipse cx="10" cy="15" rx="3" ry="1.5" fill="#243f7a"/>'
+            '<circle cx="10" cy="8" r="5" fill="#1a3a6b"/>'
+            '<rect x="6" y="6.5" width="8" height="3.5" rx="1.5" fill="#001a40"/>'
+            '<ellipse cx="8.2" cy="8.2" rx="1.5" ry="1.2" fill="#00ccee" opacity=".9"/>'
+            '<ellipse cx="11.8" cy="8.2" rx="1.5" ry="1.2" fill="#00ccee" opacity=".9"/>'
+            '<path d="M8 10 Q10 11.5 12 10" fill="none" stroke="#00ccee" stroke-width=".8" stroke-linecap="round"/>'
+            '<line x1="8.5" y1="3.5" x2="6.5" y2="1.5" stroke="#1a3a6b" stroke-width="1.2" stroke-linecap="round"/>'
+            '<circle cx="6.5" cy="1.5" r="1.2" fill="#00ccee" opacity=".8"/>'
+            '<line x1="11.5" y1="3.5" x2="13.5" y2="1.5" stroke="#1a3a6b" stroke-width="1.2" stroke-linecap="round"/>'
+            '<ellipse cx="13.5" cy="1.2" rx="1.5" ry="1.8" fill="#e8e8e8" stroke="#aaa" stroke-width=".5"/>'
+            '<text x="10" y="17.5" font-family="Arial,sans-serif" font-size="3" font-weight="bold" fill="#C8A951" text-anchor="middle">LB</text>'
+            '</svg>'
+        ),
+        "book": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="2" y="2" width="9" height="12" rx="1" fill="#2563eb"/>'
+            '<rect x="3" y="2" width="1.5" height="12" fill="#1d4ed8"/>'
+            '<rect x="4" y="4" width="5" height="1" rx=".5" fill="#bfdbfe"/>'
+            '<rect x="4" y="6" width="5" height="1" rx=".5" fill="#bfdbfe"/>'
+            '<rect x="4" y="8" width="3" height="1" rx=".5" fill="#bfdbfe"/>'
+            '<rect x="11" y="3" width="3" height="10" rx="1" fill="#1e40af"/>'
+            '</svg>'
+        ),
+        "microscope": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="7" y="1" width="2" height="5" rx="1" fill="#6b7280"/>'
+            '<ellipse cx="8" cy="1.5" rx="2.5" ry="1.5" fill="#9ca3af"/>'
+            '<rect x="6.5" y="5" width="3" height="5" rx=".5" fill="#374151"/>'
+            '<rect x="5" y="9.5" width="6" height="1.5" rx=".5" fill="#374151"/>'
+            '<rect x="3" y="13" width="10" height="1.5" rx=".5" fill="#374151"/>'
+            '<line x1="8" y1="11" x2="8" y2="13" stroke="#374151" stroke-width="1.5"/>'
+            '<circle cx="8" cy="6" r="1.5" fill="#60a5fa" opacity=".8"/>'
+            '</svg>'
+        ),
+        "circuit": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#1e293b"/>'
+            '<circle cx="4" cy="4" r="1.5" fill="#22d3ee"/>'
+            '<circle cx="12" cy="4" r="1.5" fill="#22d3ee"/>'
+            '<circle cx="4" cy="12" r="1.5" fill="#22d3ee"/>'
+            '<circle cx="12" cy="12" r="1.5" fill="#22d3ee"/>'
+            '<circle cx="8" cy="8" r="2" fill="#06b6d4"/>'
+            '<line x1="4" y1="4" x2="8" y2="8" stroke="#22d3ee" stroke-width=".8"/>'
+            '<line x1="12" y1="4" x2="8" y2="8" stroke="#22d3ee" stroke-width=".8"/>'
+            '<line x1="4" y1="12" x2="8" y2="8" stroke="#22d3ee" stroke-width=".8"/>'
+            '<line x1="12" y1="12" x2="8" y2="8" stroke="#22d3ee" stroke-width=".8"/>'
+            '</svg>'
+        ),
+        "leaf": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<path d="M8 14 C8 14 2 10 2 5 C2 2 5 1 8 1 C11 1 14 2 14 5 C14 10 8 14 8 14Z" fill="#16a34a"/>'
+            '<line x1="8" y1="1" x2="8" y2="14" stroke="#bbf7d0" stroke-width=".8"/>'
+            '<line x1="8" y1="5" x2="5" y2="7" stroke="#bbf7d0" stroke-width=".6"/>'
+            '<line x1="8" y1="7" x2="5" y2="9" stroke="#bbf7d0" stroke-width=".6"/>'
+            '<line x1="8" y1="5" x2="11" y2="7" stroke="#bbf7d0" stroke-width=".6"/>'
+            '<line x1="8" y1="7" x2="11" y2="9" stroke="#bbf7d0" stroke-width=".6"/>'
+            '</svg>'
+        ),
+        "gear": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<path d="M6.5 1h3l.5 1.5a5 5 0 011.2.7l1.5-.5 1.5 2.6-1.2 1a5 5 0 010 1.4l1.2 1-1.5 2.6-1.5-.5a5 5 0 01-1.2.7L9.5 15h-3l-.5-1.5a5 5 0 01-1.2-.7l-1.5.5L1.8 10.8l1.2-1a5 5 0 010-1.4l-1.2-1L3.3 4.8l1.5.5A5 5 0 016 4.5L6.5 1z" fill="#64748b"/>'
+            '<circle cx="8" cy="8" r="2.5" fill="#f1f5f9"/>'
+            '<circle cx="8" cy="8" r="1.2" fill="#64748b"/>'
+            '</svg>'
+        ),
+        "chart": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="1" y="1" width="14" height="14" rx="1.5" fill="#f0fdf4"/>'
+            '<rect x="3" y="9" width="2" height="5" rx=".5" fill="#16a34a"/>'
+            '<rect x="7" y="6" width="2" height="8" rx=".5" fill="#15803d"/>'
+            '<rect x="11" y="3" width="2" height="11" rx=".5" fill="#166534"/>'
+            '<line x1="1" y1="13.5" x2="15" y2="13.5" stroke="#166534" stroke-width=".8"/>'
+            '</svg>'
+        ),
+        "atom": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<ellipse cx="8" cy="8" rx="7" ry="3" fill="none" stroke="#7c3aed" stroke-width=".9"/>'
+            '<ellipse cx="8" cy="8" rx="7" ry="3" fill="none" stroke="#7c3aed" stroke-width=".9" transform="rotate(60 8 8)"/>'
+            '<ellipse cx="8" cy="8" rx="7" ry="3" fill="none" stroke="#7c3aed" stroke-width=".9" transform="rotate(120 8 8)"/>'
+            '<circle cx="8" cy="8" r="1.8" fill="#7c3aed"/>'
+            '</svg>'
+        ),
+        "medical": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#dc2626"/>'
+            '<rect x="6.5" y="3" width="3" height="10" rx="1" fill="white"/>'
+            '<rect x="3" y="6.5" width="10" height="3" rx="1" fill="white"/>'
+            '</svg>'
+        ),
+        "wrench": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<path d="M13 2a3 3 0 00-3 3c0 .4.1.8.2 1.1L2.6 13.7a1 1 0 001.4 1.4L11.7 7.8c.3.1.7.2 1.1.2a3 3 0 000-6z" fill="#d97706"/>'
+            '<circle cx="12" cy="4" r="1.2" fill="#fef3c7"/>'
+            '</svg>'
+        ),
+        "primo": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#003366"/>'
+            '<rect x="3" y="4" width="10" height="1.5" rx=".5" fill="#C8A951"/>'
+            '<rect x="3" y="7" width="7" height="1.5" rx=".5" fill="white" opacity=".9"/>'
+            '<rect x="3" y="10" width="9" height="1.5" rx=".5" fill="white" opacity=".7"/>'
+            '<circle cx="12" cy="11" r="2.5" fill="#C8A951"/>'
+            '<line x1="11" y1="11" x2="13" y2="11" stroke="#003366" stroke-width=".8"/>'
+            '<line x1="12" y1="10" x2="12" y2="12" stroke="#003366" stroke-width=".8"/>'
+            '</svg>'
+        ),
+        "scopus": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#e8650a"/>'
+            '<text x="8" y="11.5" font-family="Arial,sans-serif" font-size="8" font-weight="bold" fill="white" text-anchor="middle">Sc</text>'
+            '</svg>'
+        ),
+        "ebsco": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#00427a"/>'
+            '<text x="8" y="11.5" font-family="Arial,sans-serif" font-size="7" font-weight="bold" fill="white" text-anchor="middle">EBS</text>'
+            '</svg>'
+        ),
+        "consensus": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="1" y="1" width="14" height="14" rx="7" fill="#6c47ff"/>'
+            '<circle cx="6" cy="7" r="1.2" fill="white"/>'
+            '<circle cx="10" cy="7" r="1.2" fill="white"/>'
+            '<path d="M5 10 Q8 12.5 11 10" fill="none" stroke="white" stroke-width="1.2" stroke-linecap="round"/>'
+            '</svg>'
+        ),
+        "leapspace": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#ff6b00"/>'
+            '<path d="M4 12 L4 7 L8 4 L12 7 L12 12 Z" fill="white" opacity=".9"/>'
+            '<rect x="6.5" y="9" width="3" height="3" fill="#ff6b00"/>'
+            '</svg>'
+        ),
+        "perplexity": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#1a1a2e"/>'
+            '<circle cx="8" cy="6.5" r="3" fill="none" stroke="#20b2aa" stroke-width="1.2"/>'
+            '<line x1="8" y1="9.5" x2="8" y2="13" stroke="#20b2aa" stroke-width="1.2" stroke-linecap="round"/>'
+            '<circle cx="8" cy="13" r=".8" fill="#20b2aa"/>'
+            '</svg>'
+        ),
+        "semanticscholar": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#1857b6"/>'
+            '<path d="M4 11 Q8 4 12 11" fill="none" stroke="white" stroke-width="1.5" stroke-linecap="round"/>'
+            '<circle cx="8" cy="7" r="1.8" fill="#4fc3f7"/>'
+            '</svg>'
+        ),
+        "pubmed": (
+            '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" style="flex-shrink:0">'
+            '<rect x="1" y="1" width="14" height="14" rx="2" fill="#336699"/>'
+            '<text x="8" y="11" font-family="Arial,sans-serif" font-size="6.5" font-weight="bold" fill="white" text-anchor="middle">PubMed</text>'
+            '</svg>'
+        ),
+    }
+    _DB_MASCOT = {
+        "PubMed@KU": "microscope", "Embase": "medical", "CINAHL Ultimate": "medical",
+        "Cochrane Library": "microscope", "UpToDate": "medical",
+        "IEEE Xplore": "circuit", "ACM Digital Library": "circuit",
+        "ScienceDirect": "microscope", "Scopus": "microscope",
+        "Web of Science": "microscope", "SpringerLink": "book",
+        "ACS Publications": "atom", "APS Journals": "atom", "Knovel": "wrench",
+        "Business Source Complete": "chart", "Emerald Insight": "chart",
+        "Taylor & Francis": "book", "EBSCO": "book",
+    }
+    _BEE = _SVGS["bee"]
+
+    def _btn(label, url, mascot_key="bee"):
+        icon = _SVGS.get(mascot_key, _SVGS["bee"])
+        style = (
+            'display:inline-flex;align-items:center;gap:7px;'
+            'padding:8px 14px;border-radius:10px;text-decoration:none;'
+            'font-size:.8rem;font-weight:600;color:#1a1a2e;'
+            'background:#fff;border:1.5px solid #d1d5db;'
+            'transition:box-shadow .2s;width:100%;box-sizing:border-box'
+        )
+        return '<a href="' + url + '" target="_blank" style="' + style + '">' + icon + label + '</a>'
+
+    btn_rows = ""
+    for k in range(0, len(platforms), 2):
+        pair = platforms[k:k+2]
+        cells = ""
+        for lbl, url, mascot_key in pair:
+            cells += '<td style="width:50%;padding:3px 4px 3px 0">' + _btn(lbl, url, mascot_key) + '</td>'
+        if len(pair) == 1:
+            cells += '<td style="width:50%"></td>'
+        btn_rows += "<tr>" + cells + "</tr>"
+
+    platforms_html = (
+        '<div style="margin-top:18px;padding:14px 16px;border:1px solid #c4b5fd;'
+        'border-radius:12px;background:linear-gradient(135deg,#f5f3ff,#fdf4ff)">'
+        '<div style="font-size:.8rem;font-weight:800;color:#5b21b6;margin-bottom:4px">'
+        '🤖 Search your query across AI platforms</div>'
+        '<div style="font-size:.73rem;color:#6b7280;margin-bottom:10px">'
+        'Your query is pre-loaded. Click any platform to search instantly.</div>'
+        '<table style="width:100%;border-collapse:collapse">' + btn_rows + '</table>'
+        '</div>'
+    )
+
+    if bool_q:
+        and_count = bool_q.upper().count(" AND ")
+        if and_count >= 1:
+            bool_label = "Use this in PRIMO Advanced Search or any database for precise results:"
+        else:
+            bool_label = "Try adding synonyms with OR to find more relevant results:"
+        bool_html = (
+            '<div style="margin-top:12px;padding:12px 14px;border:1px solid #fde68a;'
+            'border-radius:10px;background:#fffbeb">'
+            '<div style="font-size:.78rem;font-weight:700;color:#92400e;margin-bottom:6px">'
+            '\U0001f4a1 Boolean search tip</div>'
+            '<div style="font-size:.74rem;color:#6b7280;margin-bottom:6px">' + bool_label + '</div>'
+            '<code style="display:block;padding:8px 10px;background:#1a1a2e;color:#C8A951;'
+            'border-radius:7px;font-size:.76rem;word-break:break-all;white-space:pre-wrap">'
+            + _escape(bool_q) +
+            '</code>'
+            '<div style="font-size:.71rem;color:#92400e;margin-top:6px">'
+            'Paste into the Advanced Search box of any database below.</div>'
+            '</div>'
+        )
+    else:
+        bool_html = ""
+
+    all_lower = ((context.ai_tool_query or "") + " " + (context.topic or "")).lower()
+
+    def _db_row(name, url, desc, favicon=None):
+        icon = _SVGS.get(_DB_MASCOT.get(name, "bee"), _SVGS["bee"])
+        return (
+            '<div style="display:flex;align-items:center;gap:8px;'
+            'padding:7px 0;border-bottom:1px solid #f3f4f6">'
+            + icon +
+            '<div><a href="' + url + '" target="_blank" '
+            'style="font-size:.8rem;font-weight:700;color:#003366;text-decoration:none">'
+            + name + '</a>'
+            '<span style="font-size:.73rem;color:#6b7280"> — ' + desc + '</span></div>'
+            '</div>'
+        )
+
+    if any(k in all_lower for k in ["medicine","medical","clinical","nursing","pharmacy","health","pubmed","embase","cinahl","cochrane","uptodate"]):
+        db_subject = "Medicine & Health Sciences"
+        dbs = [
+            ("PubMed@KU","http://www.ncbi.nlm.nih.gov/pubmed/?otool=iaekustlib","Core biomedical literature"),
+            ("Embase",KU+"https://www.embase.com","Biomedical, drugs, devices, clinical medicine"),
+            ("CINAHL Ultimate",KU+"https://search.ebscohost.com/login.aspx?authtype=ip,uid&profile=ehost&defaultdb=cul","Nursing and allied health"),
+            ("Cochrane Library",KU+"https://www.cochranelibrary.com","Systematic reviews and evidence-based medicine"),
+            ("UpToDate",KU+"https://www.uptodate.com","Point-of-care clinical decision support"),
+        ]
+    elif any(k in all_lower for k in ["machine learning","deep learning","artificial intelligence","neural network","computer science","software","algorithm","cybersecurity","robotics","nlp"]):
+        db_subject = "Computer Science & AI"
+        dbs = [
+            ("IEEE Xplore",KU+"https://ieeexplore.ieee.org","Core CS, AI, electronics and systems"),
+            ("ACM Digital Library",KU+"https://dl.acm.org","Computer science journals, proceedings and books"),
+            ("ScienceDirect",KU+"https://www.sciencedirect.com","Full text across CS and applied computing"),
+            ("Scopus",KU+"https://www.scopus.com","Discovery and citation tracking"),
+            ("Web of Science",KU+"https://www.webofscience.com","Citation index"),
+        ]
+    elif any(k in all_lower for k in ["climate","global warming","environment","sustainability","ecology","carbon","emission","renewable","sea level","maldives","island"]):
+        db_subject = "Environment & Climate"
+        dbs = [
+            ("ScienceDirect",KU+"https://www.sciencedirect.com","Full text across science, environment and engineering"),
+            ("Scopus",KU+"https://www.scopus.com","Broad discovery and citation tracking"),
+            ("Web of Science",KU+"https://www.webofscience.com","High-impact journal coverage and citation index"),
+            ("SpringerLink",KU+"https://link.springer.com","Springer journals and books"),
+        ]
+    elif any(k in all_lower for k in ["engineering","mechanical","civil","electrical","aerospace","structural","petroleum","chemical","materials"]):
+        db_subject = "Engineering"
+        dbs = [
+            ("IEEE Xplore",KU+"https://ieeexplore.ieee.org","Electrical, electronics and systems engineering"),
+            ("ScienceDirect",KU+"https://www.sciencedirect.com","Full text across engineering disciplines"),
+            ("Knovel",KU+"https://app.knovel.com","Engineering handbooks and reference data"),
+            ("Scopus",KU+"https://www.scopus.com","Discovery and citation tracking"),
+            ("Web of Science",KU+"https://www.webofscience.com","Citation index"),
+        ]
+    elif any(k in all_lower for k in ["business","management","finance","economics","leadership","marketing","strategy","entrepreneurship"]):
+        db_subject = "Business & Management"
+        dbs = [
+            ("Business Source Complete",KU+"https://search.ebscohost.com","Core business and management literature"),
+            ("Emerald Insight",KU+"https://www.emerald.com/insight","Management, strategy and leadership"),
+            ("Scopus",KU+"https://www.scopus.com","Broad discovery and citation tracking"),
+            ("ScienceDirect",KU+"https://www.sciencedirect.com","Business and social sciences full text"),
+        ]
+    elif any(k in all_lower for k in ["physics","chemistry","quantum","nuclear","materials science","nanotechnology","optics"]):
+        db_subject = "Physics, Chemistry & Materials"
+        dbs = [
+            ("ScienceDirect",KU+"https://www.sciencedirect.com","Full text across physical sciences"),
+            ("ACS Publications",KU+"https://pubs.acs.org","Core chemistry and chemical engineering"),
+            ("APS Journals",KU+"https://journals.aps.org","American Physical Society core physics journals"),
+            ("Scopus",KU+"https://www.scopus.com","Discovery and citation tracking"),
+            ("Web of Science",KU+"https://www.webofscience.com","Citation index"),
+        ]
+    else:
+        db_subject = "General"
+        dbs = [
+            ("EBSCO",KU+"https://search.ebscohost.com","Multidisciplinary full text"),
+            ("ScienceDirect",KU+"https://www.sciencedirect.com","Science, engineering and medicine"),
+            ("SpringerLink",KU+"https://link.springer.com","Journals and books across all disciplines"),
+            ("Taylor & Francis",KU+"https://www.tandfonline.com","Humanities, social sciences and STEM"),
+            ("Emerald Insight",KU+"https://www.emerald.com/insight","Management and social sciences"),
+            ("Scopus",KU+"https://www.scopus.com","Citation discovery, all disciplines"),
+            ("Web of Science",KU+"https://www.webofscience.com","Citation index, all disciplines"),
+        ]
+
+    dbs_html_rows = ""
+    for name, url, desc in dbs:
+        dbs_html_rows += _db_row(name, url, desc)
+
+    db_section = (
+        '<div style="margin-top:12px;padding:12px 14px;border:1px solid #d1d5db;'
+        'border-radius:10px;background:#f9fafb">'
+        '<div style="font-size:.78rem;font-weight:700;color:#003366;margin-bottom:8px">'
+        '\U0001f4c2 Recommended KU databases \u2014 ' + db_subject + '</div>'
+        + dbs_html_rows +
+        '<div style="padding-top:8px;font-size:.74rem">'
+        '<a href="https://library.ku.ac.ae/eresources" target="_blank" '
+        'style="color:#003366;font-weight:700">'
+        '\U0001f5c4\ufe0f Browse all 50+ KU databases \u2192</a></div>'
+        '</div>'
+    )
+
+    return platforms_html + bool_html + db_section
+
+

src/agentcore/scholarly.py

@@ -1,298 +1,323 @@
-"""Open scholarly-index clients: Semantic Scholar, OpenAlex, Crossref and Unpaywall (OA links)."""
-import asyncio
-import html
-import json
-import logging
-import os
-import re
-import time
-import uuid
-from datetime import datetime
-from typing import Any, Dict, List, Literal, Optional, Tuple
-from urllib.parse import quote
-
-import httpx
-from pydantic import BaseModel, ConfigDict, Field
-
-from src.config import get_settings, LIBBEE_VERSION
-
-from src.agentcore.utils import _escape, _strip_resource_noise
-
-logger = logging.getLogger(__name__)
-
-async def _semantic_scholar_search(topic: str, limit: int = 8) -> List[dict]:
-    clean_topic = _strip_resource_noise(topic)
-    if not clean_topic:
-        clean_topic = topic
-    try:
-        params = {
-            "query": clean_topic,
-            "limit": limit,
-            "fields": "title,authors,year,venue,abstract,externalIds,openAccessPdf",
-        }
-        async with httpx.AsyncClient(timeout=15) as client:
-            r = await client.get("https://api.semanticscholar.org/graph/v1/paper/search", params=params)
-            if r.status_code != 200:
-                logger.warning(f"Semantic Scholar {r.status_code} for '{clean_topic}'")
-                return []
-            data = r.json()
-            results = []
-            for paper in data.get("data", []):
-                abstract = paper.get("abstract") or ""
-                if not abstract or len(abstract) < 50:
-                    continue
-                author_list = paper.get("authors") or []
-                first_author_last = author_list[0].get("name", "Unknown").split()[-1] if author_list else "Unknown"
-                year = paper.get("year") or "n.d."
-                paper_id = paper.get("paperId", "")
-                doi = (paper.get("externalIds") or {}).get("DOI", "")
-                pdf_url = (paper.get("openAccessPdf") or {}).get("url", "")
-                link = (
-                    pdf_url
-                    or (f"https://doi.org/{doi}" if doi else "")
-                    or (f"https://www.semanticscholar.org/paper/{paper_id}" if paper_id else "#")
-                )
-                results.append({
-                    "title": paper.get("title", "Untitled"),
-                    "authors": (
-                        ", ".join(a.get("name", "") for a in author_list[:3])
-                        + (" et al." if len(author_list) > 3 else "")
-                    ),
-                    "first_author": first_author_last,
-                    "year": year,
-                    "citation_key": f"{first_author_last}, {year}",
+"""Open scholarly-index clients: Semantic Scholar, OpenAlex, Crossref and Unpaywall (OA links)."""
+import asyncio
+import html
+import json
+import logging
+import os
+import re
+import time
+import uuid
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from src.config import get_settings, LIBBEE_VERSION
+
+from src.agentcore.utils import _escape, _get_runtime_config, _strip_resource_noise
+
+logger = logging.getLogger(__name__)
+
+async def _semantic_scholar_search(topic: str, limit: int = 8) -> List[dict]:
+    clean_topic = _strip_resource_noise(topic)
+    if not clean_topic:
+        clean_topic = topic
+    try:
+        params = {
+            "query": clean_topic,
+            "limit": limit,
+            "fields": "title,authors,year,venue,abstract,externalIds,openAccessPdf,citationCount",
+        }
+        async with httpx.AsyncClient(timeout=15) as client:
+            r = await client.get("https://api.semanticscholar.org/graph/v1/paper/search", params=params)
+            if r.status_code != 200:
+                logger.warning(f"Semantic Scholar {r.status_code} for '{clean_topic}'")
+                return []
+            data = r.json()
+            results = []
+            for paper in data.get("data", []):
+                abstract = paper.get("abstract") or ""
+                if not abstract or len(abstract) < 50:
+                    continue
+                author_list = paper.get("authors") or []
+                first_author_last = author_list[0].get("name", "Unknown").split()[-1] if author_list else "Unknown"
+                year = paper.get("year") or "n.d."
+                paper_id = paper.get("paperId", "")
+                doi = (paper.get("externalIds") or {}).get("DOI", "")
+                pdf_url = (paper.get("openAccessPdf") or {}).get("url", "")
+                link = (
+                    pdf_url
+                    or (f"https://doi.org/{doi}" if doi else "")
+                    or (f"https://www.semanticscholar.org/paper/{paper_id}" if paper_id else "#")
+                )
+                results.append({
+                    "title": paper.get("title", "Untitled"),
+                    "authors": (
+                        ", ".join(a.get("name", "") for a in author_list[:3])
+                        + (" et al." if len(author_list) > 3 else "")
+                    ),
+                    "first_author": first_author_last,
+                    "year": year,
+                    "citation_key": f"{first_author_last}, {year}",
                     "venue": paper.get("venue", ""),
                     "abstract": abstract[:700],
+                    "doi": doi,
+                    "oa_pdf_url": pdf_url,
+                    "cited_by_count": paper.get("citationCount") or 0,
                     "link": link,
-                    "_source": "Semantic Scholar",
-                })
-            return results
-    except Exception as e:
-        logger.error(f"Semantic Scholar search failed: {e}")
-        return []
-
-
-async def _openalex_search(topic: str, limit: int = 8) -> List[dict]:
-    try:
-        from urllib.parse import quote as _oa_quote
-        clean = re.sub(r'\b(AND|OR|NOT)\b|[()"\'\\]', ' ', topic, flags=re.IGNORECASE)
-        clean = re.sub(r'\s+', ' ', clean).strip()[:200]
-        encoded = _oa_quote(clean, safe='')
-        select = "id,title,authorships,publication_year,primary_location,abstract_inverted_index,doi,cited_by_count,open_access"
-        url = (
-            f"https://api.openalex.org/works"
-            f"?search={encoded}"
-            f"&filter=has_abstract:true,type:article,is_paratext:false"
-            f"&sort=relevance_score:desc"
-            f"&per_page={limit}"
-            f"&select={select}"
-            f"&mailto={quote(get_settings().contact_email, safe='')}"
-        )
-        _contact = get_settings().contact_email
-        headers = {"User-Agent": f"LibBee/{LIBBEE_VERSION} (mailto:{_contact})"}
-        async with httpx.AsyncClient(timeout=10) as client:
-            r = await client.get(url, headers=headers)
-            if r.status_code != 200:
-                logger.warning(f"OpenAlex search failed: {r.status_code}")
-                return []
-            works = r.json().get("results", [])
-            results = []
-            for work in works:
-                title = work.get("title") or "Untitled"
-                inv = work.get("abstract_inverted_index") or {}
-                abstract = ""
-                if inv:
-                    word_positions = []
-                    for word, positions in inv.items():
-                        for pos in positions:
-                            word_positions.append((pos, word))
-                    word_positions.sort(key=lambda x: x[0])
-                    abstract = " ".join(w for _, w in word_positions)[:700]
-                if not abstract:
-                    continue
-                authorships = work.get("authorships") or []
-                author_names = [
-                    a.get("author", {}).get("display_name", "")
-                    for a in authorships[:4]
-                    if a.get("author", {}).get("display_name")
-                ]
-                authors_str = ", ".join(author_names[:3])
-                if len(author_names) > 3:
-                    authors_str += " et al."
-                first_last = author_names[0].split()[-1] if author_names else "Unknown"
-                year = str(work.get("publication_year") or "n.d.")
-                doi = (work.get("doi") or "").replace("https://doi.org/", "")
-                oa_url = (work.get("open_access") or {}).get("oa_url") or ""
-                link = (
-                    oa_url if oa_url
-                    else (f"https://doi.org/{doi}" if doi else "")
-                    or work.get("id", "https://openalex.org")
-                )
-                venue = (
-                    ((work.get("primary_location") or {}).get("source") or {})
-                    .get("display_name") or ""
-                )
-                results.append({
-                    "title": title,
-                    "authors": authors_str or "Unknown",
-                    "first_author": first_last,
-                    "year": year,
-                    "citation_key": f"{first_last}, {year}",
+                    "_source": "Semantic Scholar",
+                })
+            return results
+    except Exception as e:
+        logger.error(f"Semantic Scholar search failed: {e}")
+        return []
+
+
+async def _openalex_search(topic: str, limit: int = 8) -> List[dict]:
+    try:
+        from urllib.parse import quote as _oa_quote
+        clean = re.sub(r'\b(AND|OR|NOT)\b|[()"\'\\]', ' ', topic, flags=re.IGNORECASE)
+        clean = re.sub(r'\s+', ' ', clean).strip()[:200]
+        encoded = _oa_quote(clean, safe='')
+        select = "id,title,authorships,publication_year,primary_location,abstract_inverted_index,doi,cited_by_count,open_access"
+        url = (
+            f"https://api.openalex.org/works"
+            f"?search={encoded}"
+            f"&filter=has_abstract:true,type:article,is_paratext:false"
+            f"&sort=relevance_score:desc"
+            f"&per_page={limit}"
+            f"&select={select}"
+            f"&mailto={quote(get_settings().contact_email, safe='')}"
+        )
+        _contact = get_settings().contact_email
+        headers = {"User-Agent": f"LibBee/{LIBBEE_VERSION} (mailto:{_contact})"}
+        async with httpx.AsyncClient(timeout=10) as client:
+            r = await client.get(url, headers=headers)
+            if r.status_code != 200:
+                logger.warning(f"OpenAlex search failed: {r.status_code}")
+                return []
+            works = r.json().get("results", [])
+            results = []
+            for work in works:
+                title = work.get("title") or "Untitled"
+                inv = work.get("abstract_inverted_index") or {}
+                abstract = ""
+                if inv:
+                    word_positions = []
+                    for word, positions in inv.items():
+                        for pos in positions:
+                            word_positions.append((pos, word))
+                    word_positions.sort(key=lambda x: x[0])
+                    abstract = " ".join(w for _, w in word_positions)[:700]
+                if not abstract:
+                    continue
+                authorships = work.get("authorships") or []
+                author_names = [
+                    a.get("author", {}).get("display_name", "")
+                    for a in authorships[:4]
+                    if a.get("author", {}).get("display_name")
+                ]
+                authors_str = ", ".join(author_names[:3])
+                if len(author_names) > 3:
+                    authors_str += " et al."
+                first_last = author_names[0].split()[-1] if author_names else "Unknown"
+                year = str(work.get("publication_year") or "n.d.")
+                doi = (work.get("doi") or "").replace("https://doi.org/", "")
+                oa_url = (work.get("open_access") or {}).get("oa_url") or ""
+                link = (
+                    oa_url if oa_url
+                    else (f"https://doi.org/{doi}" if doi else "")
+                    or work.get("id", "https://openalex.org")
+                )
+                venue = (
+                    ((work.get("primary_location") or {}).get("source") or {})
+                    .get("display_name") or ""
+                )
+                results.append({
+                    "title": title,
+                    "authors": authors_str or "Unknown",
+                    "first_author": first_last,
+                    "year": year,
+                    "citation_key": f"{first_last}, {year}",
                     "venue": venue,
                     "abstract": abstract,
+                    "doi": doi,
+                    "oa_pdf_url": oa_url,
+                    "cited_by_count": int(work.get("cited_by_count") or 0),
                     "link": link,
-                    "_source": "OpenAlex",
-                })
-            logger.info(f"OpenAlex: {len(results)} papers for '{clean[:50]}'")
-            return results
-    except Exception as e:
-        logger.warning(f"OpenAlex search failed: {e}")
-        return []
-
-
-
-
-# ── Unpaywall + Crossref enrichment ──────────────────────────────────────────
-# Unpaywall (https://unpaywall.org/products/api) resolves a DOI to its best
-# legal open-access location. Crossref fills publication-year / venue gaps.
-# Both are free, keyless "polite pool" APIs identified by contact e-mail.
-# Every call is best-effort: failures never break the response.
-
-_UNPAYWALL_TTL = 24 * 60 * 60
-_unpaywall_cache: Dict[str, Any] = {}
-
-
-async def _unpaywall_oa_url(doi: str) -> str:
-    """Return the best legal OA PDF/landing URL for a DOI, or '' if none/unknown."""
-    doi = (doi or "").strip().lower().removeprefix("https://doi.org/")
-    if not doi:
-        return ""
-    now = time.time()
-    hit = _unpaywall_cache.get(doi)
-    if hit and now - hit[0] < _UNPAYWALL_TTL:
-        return hit[1]
-    url = ""
-    try:
-        email = get_settings().contact_email
-        async with httpx.AsyncClient(timeout=4) as client:
-            r = await client.get(
-                f"https://api.unpaywall.org/v2/{quote(doi, safe='')}",
-                params={"email": email},
-            )
-            if r.status_code == 200:
-                loc = (r.json() or {}).get("best_oa_location") or {}
-                url = loc.get("url_for_pdf") or loc.get("url") or ""
-    except Exception as exc:
-        logger.debug(f"Unpaywall lookup failed for {doi}: {exc}")
-    _unpaywall_cache[doi] = (now, url)
-    return url
-
-
-async def _crossref_fill(doi: str) -> dict:
-    """Return {'year': int|None, 'venue': str} from Crossref for a DOI (best effort)."""
-    doi = (doi or "").strip().lower().removeprefix("https://doi.org/")
-    if not doi:
-        return {}
+                    "_source": "OpenAlex",
+                })
+            logger.info(f"OpenAlex: {len(results)} papers for '{clean[:50]}'")
+            return results
+    except Exception as e:
+        logger.warning(f"OpenAlex search failed: {e}")
+        return []
+
+
+
+
+# ── Unpaywall + Crossref enrichment ──────────────────────────────────────────
+# Unpaywall (https://unpaywall.org/products/api) resolves a DOI to its best
+# legal open-access location. Crossref fills publication-year / venue gaps.
+# Both are free, keyless "polite pool" APIs identified by contact e-mail.
+# Every call is best-effort: failures never break the response.
+
+_UNPAYWALL_TTL = 24 * 60 * 60
+_unpaywall_cache: Dict[str, Any] = {}
+
+
+async def _unpaywall_oa_url(doi: str) -> str:
+    """Return the best legal OA PDF/landing URL for a DOI, or '' if none/unknown."""
+    doi = (doi or "").strip().lower().removeprefix("https://doi.org/")
+    if not doi:
+        return ""
+    now = time.time()
+    hit = _unpaywall_cache.get(doi)
+    if hit and now - hit[0] < _UNPAYWALL_TTL:
+        return hit[1]
+    url = ""
+    try:
+        email = get_settings().contact_email
+        async with httpx.AsyncClient(timeout=4) as client:
+            r = await client.get(
+                f"https://api.unpaywall.org/v2/{quote(doi, safe='')}",
+                params={"email": email},
+            )
+            if r.status_code == 200:
+                loc = (r.json() or {}).get("best_oa_location") or {}
+                url = loc.get("url_for_pdf") or loc.get("url") or ""
+    except Exception as exc:
+        logger.debug(f"Unpaywall lookup failed for {doi}: {exc}")
+    _unpaywall_cache[doi] = (now, url)
+    return url
+
+
+async def _crossref_fill(doi: str) -> dict:
+    """Return {'year': int|None, 'venue': str} from Crossref for a DOI (best effort)."""
+    doi = (doi or "").strip().lower().removeprefix("https://doi.org/")
+    if not doi:
+        return {}
+    try:
+        _contact = get_settings().contact_email
+        headers = {"User-Agent": f"LibBee/{LIBBEE_VERSION} (mailto:{_contact})"}
+        async with httpx.AsyncClient(timeout=4) as client:
+            r = await client.get(f"https://api.crossref.org/works/{quote(doi, safe='')}",
+                                 headers=headers)
+            if r.status_code != 200:
+                return {}
+            msg = (r.json() or {}).get("message") or {}
+            year = None
+            issued = ((msg.get("issued") or {}).get("date-parts") or [[None]])[0]
+            if issued and issued[0]:
+                year = issued[0]
+            venue = (msg.get("container-title") or [""])[0]
+            return {"year": year, "venue": venue}
+    except Exception as exc:
+        logger.debug(f"Crossref lookup failed for {doi}: {exc}")
+        return {}
+
+
+async def enrich_papers_with_oa(papers: List[dict], max_lookups: int = 5) -> List[dict]:
+    """Concurrently attach 'oa_pdf_url' (Unpaywall) and fill missing year/venue
+    (Crossref) for papers that carry a DOI. Mutates and returns the list."""
+    targets = [p for p in papers if p.get("doi") and not p.get("oa_pdf_url")][:max_lookups]
+    if not targets:
+        return papers
+    oa_results = await asyncio.gather(
+        *(_unpaywall_oa_url(p["doi"]) for p in targets), return_exceptions=True
+    )
+    for p, oa in zip(targets, oa_results):
+        if isinstance(oa, str) and oa:
+            p["oa_pdf_url"] = oa
+    missing_meta = [p for p in targets if not p.get("year") or p.get("year") == "n.d."]
+    if missing_meta:
+        cf = await asyncio.gather(
+            *(_crossref_fill(p["doi"]) for p in missing_meta), return_exceptions=True
+        )
+        for p, meta in zip(missing_meta, cf):
+            if isinstance(meta, dict):
+                if meta.get("year") and (not p.get("year") or p.get("year") == "n.d."):
+                    p["year"] = meta["year"]
+                if meta.get("venue") and not p.get("venue"):
+                    p["venue"] = meta["venue"]
+    return papers
+
+
+# ── Shared evidence panel ────────────────────────────────────────────────────
+# Used by BOTH search handlers (_run_search_mode and _research_snapshot) so the
+# panel appears on ordinary searches, not only on "deep research" phrasing.
+# Returns (papers, html). Never raises: on any failure returns ([], "") and the
+# caller renders exactly its pre-3.8 output.
+
+async def fetch_evidence_panel(topic: str, limit: int = 6, max_lookups: int = 5, context=None):
     try:
-        _contact = get_settings().contact_email
-        headers = {"User-Agent": f"LibBee/{LIBBEE_VERSION} (mailto:{_contact})"}
-        async with httpx.AsyncClient(timeout=4) as client:
-            r = await client.get(f"https://api.crossref.org/works/{quote(doi, safe='')}",
-                                 headers=headers)
-            if r.status_code != 200:
-                return {}
-            msg = (r.json() or {}).get("message") or {}
-            year = None
-            issued = ((msg.get("issued") or {}).get("date-parts") or [[None]])[0]
-            if issued and issued[0]:
-                year = issued[0]
-            venue = (msg.get("container-title") or [""])[0]
-            return {"year": year, "venue": venue}
-    except Exception as exc:
-        logger.debug(f"Crossref lookup failed for {doi}: {exc}")
-        return {}
-
-
-async def enrich_papers_with_oa(papers: List[dict], max_lookups: int = 5) -> List[dict]:
-    """Concurrently attach 'oa_pdf_url' (Unpaywall) and fill missing year/venue
-    (Crossref) for papers that carry a DOI. Mutates and returns the list."""
-    targets = [p for p in papers if p.get("doi") and not p.get("oa_pdf_url")][:max_lookups]
-    if not targets:
-        return papers
-    oa_results = await asyncio.gather(
-        *(_unpaywall_oa_url(p["doi"]) for p in targets), return_exceptions=True
-    )
-    for p, oa in zip(targets, oa_results):
-        if isinstance(oa, str) and oa:
-            p["oa_pdf_url"] = oa
-    missing_meta = [p for p in targets if not p.get("year") or p.get("year") == "n.d."]
-    if missing_meta:
-        cf = await asyncio.gather(
-            *(_crossref_fill(p["doi"]) for p in missing_meta), return_exceptions=True
+        configured_limit = int(_get_runtime_config().get("max_results", get_settings().max_results))
+    except (TypeError, ValueError):
+        configured_limit = get_settings().max_results
+    limit = max(1, min(limit, configured_limit, 20))
+    if context is not None and getattr(context, "peer_reviewed", False):
+        return [], (
+            '<div class="evidence-note" role="note"><strong>Peer-reviewed filter:</strong> '
+            'Open-index evidence is not displayed because those records do not provide a '
+            'reliable peer-review guarantee. Use the prepared PRIMO search, where the '
+            'Peer Reviewed filter is applied.</div>'
         )
-        for p, meta in zip(missing_meta, cf):
-            if isinstance(meta, dict):
-                if meta.get("year") and (not p.get("year") or p.get("year") == "n.d."):
-                    p["year"] = meta["year"]
-                if meta.get("venue") and not p.get("venue"):
-                    p["venue"] = meta["venue"]
-    return papers
-
-
-# ── Shared evidence panel ────────────────────────────────────────────────────
-# Used by BOTH search handlers (_run_search_mode and _research_snapshot) so the
-# panel appears on ordinary searches, not only on "deep research" phrasing.
-# Returns (papers, html). Never raises: on any failure returns ([], "") and the
-# caller renders exactly its pre-3.8 output.
-
-async def fetch_evidence_panel(topic: str, limit: int = 6, max_lookups: int = 5):
     papers: List[dict] = []
-    try:
-        papers = await _openalex_search(topic, limit=limit)
-        if not papers:
-            papers = await _semantic_scholar_search(topic, limit=limit)
+    try:
+        papers = await _openalex_search(topic, limit=limit)
+        if not papers:
+            papers = await _semantic_scholar_search(topic, limit=limit)
         if papers:
             papers = await enrich_papers_with_oa(papers, max_lookups=max_lookups)
-    except Exception as exc:
-        logger.warning(f"Evidence panel failed for '{topic}': {exc}")
-        return [], ""
-    if not papers:
-        return [], ""
-
-    rows = ""
-    for paper in papers[:5]:
-        _t = _escape(str(paper.get("title") or "Untitled"))
-        _y = _escape(str(paper.get("year") or "n.d."))
-        _v = _escape(str(paper.get("venue") or ""))
-        _c = paper.get("cited_by_count")
-        _link = paper.get("link") or (f"https://doi.org/{paper['doi']}" if paper.get("doi") else "")
-        _oa = paper.get("oa_pdf_url") or ""
-        _bits = [b for b in (_y, _v) if b]
-        if isinstance(_c, int) and _c > 0:
-            _bits.append(f"{_c:,} citations")
-        _meta = " \u00b7 ".join(_bits)
-        _title_html = (
-            f'<a href="{_escape(_link)}" target="_blank" style="color:#003366;font-weight:600">{_t}</a>'
-            if _link else f'<span style="font-weight:600">{_t}</span>'
-        )
-        _oa_html = (
-            f' \u00b7 <a href="{_escape(_oa)}" target="_blank" '
-            f'style="color:#047857;font-weight:700">\U0001f513 OA full text</a>'
-            if _oa else ""
-        )
-        rows += (
-            f'<div style="margin:7px 0;padding-left:2px;font-size:.84rem;line-height:1.55">'
-            f'{_title_html}<br>'
-            f'<span style="color:#6b7280;font-size:.78rem">{_meta}{_oa_html}</span></div>'
-        )
+            if context is not None:
+                year_from = int(context.year_from) if getattr(context, "year_from", None) else None
+                year_to = int(context.year_to) if getattr(context, "year_to", None) else None
+                if year_from:
+                    papers = [paper for paper in papers if str(paper.get("year", "")).isdigit() and int(paper["year"]) >= year_from]
+                if year_to:
+                    papers = [paper for paper in papers if str(paper.get("year", "")).isdigit() and int(paper["year"]) <= year_to]
+                if getattr(context, "open_access", False):
+                    papers = [paper for paper in papers if paper.get("oa_pdf_url")]
+    except Exception as exc:
+        logger.warning(f"Evidence panel failed for '{topic}': {exc}")
+        return [], ""
+    if not papers:
+        return [], ""
+
+    rows = ""
+    for paper in papers[:5]:
+        _t = _escape(str(paper.get("title") or "Untitled"))
+        _y = _escape(str(paper.get("year") or "n.d."))
+        _v = _escape(str(paper.get("venue") or ""))
+        _c = paper.get("cited_by_count")
+        _link = paper.get("link") or (f"https://doi.org/{paper['doi']}" if paper.get("doi") else "")
+        _oa = paper.get("oa_pdf_url") or ""
+        _bits = [b for b in (_y, _v) if b]
+        if isinstance(_c, int) and _c > 0:
+            _bits.append(f"{_c:,} citations")
+        _meta = " \u00b7 ".join(_bits)
+        _title_html = (
+            f'<a href="{_escape(_link)}" target="_blank" style="color:#003366;font-weight:600">{_t}</a>'
+            if _link else f'<span style="font-weight:600">{_t}</span>'
+        )
+        _oa_html = (
+            f' \u00b7 <a href="{_escape(_oa)}" target="_blank" '
+            f'style="color:#047857;font-weight:700">\U0001f513 OA full text</a>'
+            if _oa else ""
+        )
+        rows += (
+            f'<div style="margin:7px 0;padding-left:2px;font-size:.84rem;line-height:1.55">'
+            f'{_title_html}<br>'
+            f'<span style="color:#6b7280;font-size:.78rem">{_meta}{_oa_html}</span></div>'
+        )
     html = (
-        '<div style="margin-top:16px;padding:12px 14px;border:1px solid #d1fae5;'
-        'border-radius:10px;background:#f0fdf9">'
-        '<div style="font-weight:700;color:#065f46;font-size:.86rem;margin-bottom:4px">'
-        '\U0001f50e Open scholarly evidence</div>'
-        '<div style="font-size:.76rem;color:#047857;margin-bottom:8px">'
-        'Top open-index results (OpenAlex / Semantic Scholar) with legal open-access '
-        'links via Unpaywall and metadata via Crossref where available.</div>'
-        f'{rows}</div>'
-    )
-    return papers, html
+        '<div class="evidence-panel">'
+        '<div class="evidence-title">\U0001f50e Open scholarly evidence</div>'
+        '<div class="evidence-description">'
+        'Top open-index results (OpenAlex / Semantic Scholar) with legal open-access '
+        'links via Unpaywall and metadata via Crossref where available.</div>'
+        f'{rows}</div>'
+    )
+    return papers, html

src/agentcore/utils.py

@@ -1,288 +1,288 @@
-"""Small shared helpers: HTML escaping, metrics, history windowing, LLM factory, sanitizers."""
-import asyncio
-import html
-import json
-import logging
-import os
-import re
-import time
-import uuid
-from datetime import datetime
-from typing import Any, Dict, List, Literal, Optional, Tuple
-from urllib.parse import quote
-
-import httpx
-from pydantic import BaseModel, ConfigDict, Field
-
-from src.config import get_settings, LIBBEE_VERSION
-from src.services.staff_service import (
-    STAFF_DIRECTORY,
-    match_staff_name,
-    match_staff_role,
-    should_attempt_staff_lookup,
-    staff_name_answer,
-    staff_role_answer,
-)
-
-from src.agentcore.models import ChatMessage, SearchContextPayload
-from src.agentcore.constants import (
-    CURRENT_YEAR,
-    HISTORY_WINDOW,
-    _LEGACY_SYSTEM_PATTERNS,
-    _RESOURCE_TYPE_NOISE,
-)
-
-logger = logging.getLogger(__name__)
-
-def _get_runtime_config() -> dict:
-    try:
-        from src.services.runtime_store import JsonRuntimeStore
-        settings = get_settings()
-        store = JsonRuntimeStore(settings.config_path, default={
-            "max_results": 5,
-            "maintenance_mode": False,
-            "welcome_message": "",
-            "custom_instructions": "",
-            "announcement": "",
-            "maintenance_message": "",
-        })
-        return store.load()
-    except Exception:
-        return {}
-
-
-def _escape(text: str) -> str:
-    return html.escape(text or "")
-
-
-def _normalize_whitespace(text: str) -> str:
-    return re.sub(r"\s+", " ", (text or "").strip())
-
-
-def _title_case_topic(topic: str) -> str:
-    return _normalize_whitespace(topic).strip().strip(".?")
-
-
-def _strip_resource_noise(text: str) -> str:
-    cleaned = _RESOURCE_TYPE_NOISE.sub(" ", text or "")
-    cleaned = re.sub(r"\s+(AND|OR)\s+(AND|OR)\s+", " AND ", cleaned, flags=re.IGNORECASE)
-    cleaned = re.sub(r"^\s*(AND|OR)\s+", "", cleaned, flags=re.IGNORECASE)
-    cleaned = re.sub(r"\s+(AND|OR)\s*$", "", cleaned, flags=re.IGNORECASE)
-    return _normalize_whitespace(cleaned)
-
-
-def _safe_metrics_increment(key: str) -> None:
-    try:
-        from app import get_metrics_service
-        get_metrics_service().incr(key)
-    except Exception:
-        return
-
-
-def _safe_metrics_bucket(bucket: str, key: str) -> None:
-    try:
-        from app import get_metrics_service
-        get_metrics_service().incr_bucket(bucket, key)
-    except Exception:
-        return
-
-
-def _build_history_messages(history: List[ChatMessage]) -> List[dict]:
-    msgs = []
-    for m in history[-HISTORY_WINDOW:]:
-        if m.role in ("user", "assistant") and m.content:
-            msgs.append({"role": m.role, "content": m.content[:300]})
-    return msgs
-
-
-def _get_llm(model: str, temperature: float, max_tokens: int):
-    settings = get_settings()
-    if model == "claude" and settings.anthropic_api_key:
-        from langchain_anthropic import ChatAnthropic
-        return ChatAnthropic(
-            model="claude-haiku-4-5-20251001",
-            temperature=temperature,
-            max_tokens=max_tokens,
-            anthropic_api_key=settings.anthropic_api_key,
-        )
-    from langchain_openai import ChatOpenAI
-    return ChatOpenAI(
-        model="gpt-4o-mini",
-        temperature=temperature,
-        max_tokens=max_tokens,
-        openai_api_key=settings.openai_api_key,
-    )
-
-
-def _shared_build_primo_boolean_query(topic: str) -> str:
-    clean = _strip_resource_noise(topic)
-    if not clean:
-        clean = topic
-    clean = _normalize_whitespace(clean)
-    words = clean.split()
-    if len(words) <= 4:
-        return f'"{clean}"'
-    _BOOL_STOP = re.compile(
-        r"\b(of|on|in|the|a|an|and|or|for|to|with|by|from|at|is|are|was|were|"
-        r"be|been|have|has|had|do|does|did|will|would|could|should|may|its|"
-        r"this|that|these|those|about|impact|role|effect|use|analysis|review|"
-        r"what|how|why|when|where|which|between|within|across|among|using|"
-        r"based|related|towards|toward|during|after|before|over|under)\b",
-        re.IGNORECASE,
-    )
-    parts = _BOOL_STOP.split(clean)
-    concepts = [_normalize_whitespace(p) for p in parts if _normalize_whitespace(p) and len(_normalize_whitespace(p)) > 2]
-    if not concepts:
-        return f'"{clean}"'
-    if len(concepts) == 1:
-        return f'"{concepts[0]}"'
-    quoted = [f'"{c}"' if ' ' in c else c for c in concepts[:4]]
-    return " AND ".join(quoted)
-
-
-def _make_primo_boolean_query(context: SearchContextPayload) -> str:
-    topic = _title_case_topic(context.display_topic or context.topic)
-    topic = _strip_resource_noise(topic) or (context.topic or "library search")
-    return _shared_build_primo_boolean_query(topic)
-
-
-def _shared_build_primo_discovery_url(
-    boolean_query: str,
-    resource_type: str = "articles",
-    peer_reviewed: bool = False,
-    open_access: bool = False,
-    year_from: Optional[str] = None,
-    year_to: Optional[str] = None,
-) -> str:
-    base = (
-        "https://khalifa.primo.exlibrisgroup.com/discovery/search"
-        f"?vid=971KUOSTAR_INST:KU&tab=Everything&scope=MyInst_and_CI"
-        f"&query=any,contains,{quote(boolean_query)}"
-        f"&lang=en&search_scope=MyInst_and_CI&sortby=rank&mode=advanced"
-    )
-    facets = []
-    if resource_type == "articles":
-        facets.append("facet_rtype,include,articles")
-    elif resource_type == "books":
-        facets.append("facet_rtype,include,books")
-    if peer_reviewed:
-        facets.append("facet_tlevel,include,peer_reviewed")
-    if open_access:
-        facets.append("facet_tlevel,include,online_resources")
-    if year_from or year_to:
-        yf = year_from or "0001"
-        yt = year_to or "9999"
-        facets.append(f"facet_searchcreationdate,include,{yf}|,|{yt}")
-    for facet in facets:
-        base += f"&multiFacets={quote(facet)}"
-    return base
-
-
-def _shared_build_pubmed_url(
-    topic: str,
-    year_from: Optional[str] = None,
-    year_to: Optional[str] = None,
-    peer_reviewed: bool = False,
-) -> str:
-    clean = _strip_resource_noise(topic)
-    term = clean or topic
-    if peer_reviewed:
-        term = f"({term}) AND Journal Article[pt]"
-    url = f"https://pubmed.ncbi.nlm.nih.gov/?term={quote(term)}"
-    if year_from or year_to:
-        yf = year_from or "1900"
-        yt = year_to or str(CURRENT_YEAR)
-        url += f"&filter=datesearch.y_{yf}-{yt}"
-    return url
-
-
-def _primo_clean_url(context: SearchContextPayload) -> str:
-    boolean_query = context.primo_boolean_query or _make_primo_boolean_query(context)
-    return _shared_build_primo_discovery_url(
-        boolean_query,
-        resource_type=context.resource_type,
-        peer_reviewed=context.peer_reviewed,
-        open_access=context.open_access,
-        year_from=context.year_from,
-        year_to=context.year_to,
-    )
-
-
-async def _grammar_refine_query(text: str, model: str) -> str:
-    settings = get_settings()
-    if not settings.openai_api_key and not settings.anthropic_api_key:
-        return _normalize_whitespace(text)
-    try:
-        llm = _get_llm(model, temperature=0, max_tokens=60)
-        response = await llm.ainvoke([
-            {"role": "system", "content": "Rewrite the user's search question in clear grammatical English. Keep the meaning exactly the same. Return one sentence only."},
-            {"role": "user", "content": text},
-        ])
-        refined = _normalize_whitespace(response.content)
-        return refined or _normalize_whitespace(text)
-    except Exception:
-        return _normalize_whitespace(text)
-
-
-def _light_strip_retrieval_boilerplate(text: str) -> str:
-    cleaned = re.sub(r"^\s*(please\s+)?(?:can you|could you|would you)\s+", "", (text or "").strip(), flags=re.IGNORECASE)
-    cleaned = re.sub(r"^\s*(please\s+)?help me\s+", "", cleaned, flags=re.IGNORECASE)
-    cleaned = re.sub(r"^\s*please\s+", "", cleaned, flags=re.IGNORECASE)
-    cleaned = re.sub(r"\s+(please|thanks|thank you|asap)$", "", cleaned, flags=re.IGNORECASE)
-    cleaned = re.sub(
-        r"^\s*(find|search for|search|look for|get me|show me|give me|fetch|retrieve|"
-        r"research on|articles on|papers on|literature on|studies on|"
-        r"tell me about|i need|i want|can you find|help me find|"
-        r"i am looking for|i'm looking for|i need articles on|"
-        r"i want articles on|i need papers on|i want papers on)\s+",
-        "", cleaned, flags=re.IGNORECASE
-    )
-    cleaned = re.sub(
-        r"^\s*(research|articles?|papers?|books?|literature|studies|study|"
-        r"journals?|publications?|resources?)\s+(on|about|for|regarding|into)\s+",
-        "", cleaned, flags=re.IGNORECASE
-    )
-    cleaned = re.sub(
-        r"^\s*(on|about|for|regarding|concerning|into|around|of|in|the)\s+",
-        "", cleaned, flags=re.IGNORECASE
-    )
-    return re.sub(r"\s+", " ", cleaned).strip()
-
-
-def _sanitize_llm_response(text: str) -> str:
-    if not text:
-        return text
-    for pattern, replacement in _LEGACY_SYSTEM_PATTERNS:
-        text = pattern.sub(replacement, text)
-    return text
-
-
-def _sanitize_boolean_for_primo(boolean: str) -> str:
-    if not boolean:
-        return boolean
-    boolean = re.sub(r"'([^']+)'", r'"\1"', boolean)
-    boolean = re.sub(
-        r"\(\s*(?:(?:19|20)\d{2}\s*(?:OR\s*(?:19|20)\d{2}\s*)*)\)",
-        "", boolean, flags=re.IGNORECASE,
-    )
-    boolean = re.sub(r"^\s*(AND|OR)\s*", "", boolean, flags=re.IGNORECASE)
-    boolean = re.sub(r"\s*(AND|OR)\s*$", "", boolean, flags=re.IGNORECASE)
-    boolean = re.sub(r"\b(AND|OR)\s+(AND|OR)\b", r"\1", boolean, flags=re.IGNORECASE)
-    return re.sub(r"\s+", " ", boolean).strip()
-
-
-def _clean_database_keywords(boolean_query: str) -> str:
-    return re.sub(r"\s+", " ",
-                  re.sub(r"\b(AND|OR|NOT)\b|[()\"]", " ",
-                         boolean_query, flags=re.IGNORECASE)).strip()
-
-
-def _find_staff_by_token(token: str) -> Optional[dict]:
-    token = (token or "").lower()
-    for staff in STAFF_DIRECTORY:
-        hay = (staff.get("full_name", "") + " " + staff.get("role", "")).lower()
-        if token in hay:
-            return staff
-    return None
-
-
+"""Small shared helpers: HTML escaping, metrics, history windowing, LLM factory, sanitizers."""
+import asyncio
+import html
+import json
+import logging
+import os
+import re
+import time
+import uuid
+from datetime import datetime
+from typing import Any, Dict, List, Literal, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from src.config import get_settings, LIBBEE_VERSION
+from src.services.staff_service import (
+    STAFF_DIRECTORY,
+    match_staff_name,
+    match_staff_role,
+    should_attempt_staff_lookup,
+    staff_name_answer,
+    staff_role_answer,
+)
+
+from src.agentcore.models import ChatMessage, SearchContextPayload
+from src.agentcore.constants import (
+    CURRENT_YEAR,
+    HISTORY_WINDOW,
+    _LEGACY_SYSTEM_PATTERNS,
+    _RESOURCE_TYPE_NOISE,
+)
+
+logger = logging.getLogger(__name__)
+
+def _get_runtime_config() -> dict:
+    try:
+        from src.services.runtime_store import JsonRuntimeStore
+        settings = get_settings()
+        store = JsonRuntimeStore(settings.config_path, default={
+            "max_results": 5,
+            "maintenance_mode": False,
+            "welcome_message": "",
+            "custom_instructions": "",
+            "announcement": "",
+            "maintenance_message": "",
+        })
+        return store.load()
+    except Exception:
+        return {}
+
+
+def _escape(text: str) -> str:
+    return html.escape(text or "")
+
+
+def _normalize_whitespace(text: str) -> str:
+    return re.sub(r"\s+", " ", (text or "").strip())
+
+
+def _title_case_topic(topic: str) -> str:
+    return _normalize_whitespace(topic).strip().strip(".?")
+
+
+def _strip_resource_noise(text: str) -> str:
+    cleaned = _RESOURCE_TYPE_NOISE.sub(" ", text or "")
+    cleaned = re.sub(r"\s+(AND|OR)\s+(AND|OR)\s+", " AND ", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"^\s*(AND|OR)\s+", "", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"\s+(AND|OR)\s*$", "", cleaned, flags=re.IGNORECASE)
+    return _normalize_whitespace(cleaned)
+
+
+def _safe_metrics_increment(key: str) -> None:
+    try:
+        from app import get_metrics_service
+        get_metrics_service().incr(key)
+    except Exception:
+        return
+
+
+def _safe_metrics_bucket(bucket: str, key: str) -> None:
+    try:
+        from app import get_metrics_service
+        get_metrics_service().incr_bucket(bucket, key)
+    except Exception:
+        return
+
+
+def _build_history_messages(history: List[ChatMessage]) -> List[dict]:
+    msgs = []
+    for m in history[-HISTORY_WINDOW:]:
+        if m.role in ("user", "assistant") and m.content:
+            msgs.append({"role": m.role, "content": m.content[:300]})
+    return msgs
+
+
+def _get_llm(model: str, temperature: float, max_tokens: int):
+    settings = get_settings()
+    if model == "claude" and settings.anthropic_api_key:
+        from langchain_anthropic import ChatAnthropic
+        return ChatAnthropic(
+            model="claude-haiku-4-5-20251001",
+            temperature=temperature,
+            max_tokens=max_tokens,
+            anthropic_api_key=settings.anthropic_api_key,
+        )
+    from langchain_openai import ChatOpenAI
+    return ChatOpenAI(
+        model="gpt-4o-mini",
+        temperature=temperature,
+        max_tokens=max_tokens,
+        openai_api_key=settings.openai_api_key,
+    )
+
+
+def _shared_build_primo_boolean_query(topic: str) -> str:
+    clean = _strip_resource_noise(topic)
+    if not clean:
+        clean = topic
+    clean = _normalize_whitespace(clean)
+    words = clean.split()
+    if len(words) <= 4:
+        return f'"{clean}"'
+    _BOOL_STOP = re.compile(
+        r"\b(of|on|in|the|a|an|and|or|for|to|with|by|from|at|is|are|was|were|"
+        r"be|been|have|has|had|do|does|did|will|would|could|should|may|its|"
+        r"this|that|these|those|about|impact|role|effect|use|analysis|review|"
+        r"what|how|why|when|where|which|between|within|across|among|using|"
+        r"based|related|towards|toward|during|after|before|over|under)\b",
+        re.IGNORECASE,
+    )
+    parts = _BOOL_STOP.split(clean)
+    concepts = [_normalize_whitespace(p) for p in parts if _normalize_whitespace(p) and len(_normalize_whitespace(p)) > 2]
+    if not concepts:
+        return f'"{clean}"'
+    if len(concepts) == 1:
+        return f'"{concepts[0]}"'
+    quoted = [f'"{c}"' if ' ' in c else c for c in concepts[:4]]
+    return " AND ".join(quoted)
+
+
+def _make_primo_boolean_query(context: SearchContextPayload) -> str:
+    topic = _title_case_topic(context.display_topic or context.topic)
+    topic = _strip_resource_noise(topic) or (context.topic or "library search")
+    return _shared_build_primo_boolean_query(topic)
+
+
+def _shared_build_primo_discovery_url(
+    boolean_query: str,
+    resource_type: str = "articles",
+    peer_reviewed: bool = False,
+    open_access: bool = False,
+    year_from: Optional[str] = None,
+    year_to: Optional[str] = None,
+) -> str:
+    base = (
+        "https://khalifa.primo.exlibrisgroup.com/discovery/search"
+        f"?vid=971KUOSTAR_INST:KU&tab=Everything&scope=MyInst_and_CI"
+        f"&query=any,contains,{quote(boolean_query)}"
+        f"&lang=en&search_scope=MyInst_and_CI&sortby=rank&mode=advanced"
+    )
+    facets = []
+    if resource_type == "articles":
+        facets.append("facet_rtype,include,articles")
+    elif resource_type == "books":
+        facets.append("facet_rtype,include,books")
+    if peer_reviewed:
+        facets.append("facet_tlevel,include,peer_reviewed")
+    if open_access:
+        facets.append("facet_tlevel,include,online_resources")
+    if year_from or year_to:
+        yf = year_from or "0001"
+        yt = year_to or "9999"
+        facets.append(f"facet_searchcreationdate,include,{yf}|,|{yt}")
+    for facet in facets:
+        base += f"&multiFacets={quote(facet)}"
+    return base
+
+
+def _shared_build_pubmed_url(
+    topic: str,
+    year_from: Optional[str] = None,
+    year_to: Optional[str] = None,
+    peer_reviewed: bool = False,
+) -> str:
+    clean = _strip_resource_noise(topic)
+    term = clean or topic
+    if peer_reviewed:
+        term = f"({term}) AND Journal Article[pt]"
+    url = f"https://pubmed.ncbi.nlm.nih.gov/?term={quote(term)}"
+    if year_from or year_to:
+        yf = year_from or "1900"
+        yt = year_to or str(CURRENT_YEAR)
+        url += f"&filter=datesearch.y_{yf}-{yt}"
+    return url
+
+
+def _primo_clean_url(context: SearchContextPayload) -> str:
+    boolean_query = context.primo_boolean_query or _make_primo_boolean_query(context)
+    return _shared_build_primo_discovery_url(
+        boolean_query,
+        resource_type=context.resource_type,
+        peer_reviewed=context.peer_reviewed,
+        open_access=context.open_access,
+        year_from=context.year_from,
+        year_to=context.year_to,
+    )
+
+
+async def _grammar_refine_query(text: str, model: str) -> str:
+    settings = get_settings()
+    if not settings.openai_api_key and not settings.anthropic_api_key:
+        return _normalize_whitespace(text)
+    try:
+        llm = _get_llm(model, temperature=0, max_tokens=60)
+        response = await llm.ainvoke([
+            {"role": "system", "content": "Rewrite the user's search question in clear grammatical English. Keep the meaning exactly the same. Return one sentence only."},
+            {"role": "user", "content": text},
+        ])
+        refined = _normalize_whitespace(response.content)
+        return refined or _normalize_whitespace(text)
+    except Exception:
+        return _normalize_whitespace(text)
+
+
+def _light_strip_retrieval_boilerplate(text: str) -> str:
+    cleaned = re.sub(r"^\s*(please\s+)?(?:can you|could you|would you)\s+", "", (text or "").strip(), flags=re.IGNORECASE)
+    cleaned = re.sub(r"^\s*(please\s+)?help me\s+", "", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"^\s*please\s+", "", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"\s+(please|thanks|thank you|asap)$", "", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(
+        r"^\s*(find|search for|search|look for|get me|show me|give me|fetch|retrieve|"
+        r"research on|articles on|papers on|literature on|studies on|"
+        r"tell me about|i need|i want|can you find|help me find|"
+        r"i am looking for|i'm looking for|i need articles on|"
+        r"i want articles on|i need papers on|i want papers on)\s+",
+        "", cleaned, flags=re.IGNORECASE
+    )
+    cleaned = re.sub(
+        r"^\s*(research|articles?|papers?|books?|literature|studies|study|"
+        r"journals?|publications?|resources?)\s+(on|about|for|regarding|into)\s+",
+        "", cleaned, flags=re.IGNORECASE
+    )
+    cleaned = re.sub(
+        r"^\s*(on|about|for|regarding|concerning|into|around|of|in|the)\s+",
+        "", cleaned, flags=re.IGNORECASE
+    )
+    return re.sub(r"\s+", " ", cleaned).strip()
+
+
+def _sanitize_llm_response(text: str) -> str:
+    if not text:
+        return text
+    for pattern, replacement in _LEGACY_SYSTEM_PATTERNS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+def _sanitize_boolean_for_primo(boolean: str) -> str:
+    if not boolean:
+        return boolean
+    boolean = re.sub(r"'([^']+)'", r'"\1"', boolean)
+    boolean = re.sub(
+        r"\(\s*(?:(?:19|20)\d{2}\s*(?:OR\s*(?:19|20)\d{2}\s*)*)\)",
+        "", boolean, flags=re.IGNORECASE,
+    )
+    boolean = re.sub(r"^\s*(AND|OR)\s*", "", boolean, flags=re.IGNORECASE)
+    boolean = re.sub(r"\s*(AND|OR)\s*$", "", boolean, flags=re.IGNORECASE)
+    boolean = re.sub(r"\b(AND|OR)\s+(AND|OR)\b", r"\1", boolean, flags=re.IGNORECASE)
+    return re.sub(r"\s+", " ", boolean).strip()
+
+
+def _clean_database_keywords(boolean_query: str) -> str:
+    return re.sub(r"\s+", " ",
+                  re.sub(r"\b(AND|OR|NOT)\b|[()\"]", " ",
+                         boolean_query, flags=re.IGNORECASE)).strip()
+
+
+def _find_staff_by_token(token: str) -> Optional[dict]:
+    token = (token or "").lower()
+    for staff in STAFF_DIRECTORY:
+        hay = (staff.get("full_name", "") + " " + staff.get("role", "")).lower()
+        if token in hay:
+            return staff
+    return None
+
+