Update src/api/agent.py

src/api/agent.py

@@ -1,33 +1,10 @@
 """
-agent.py — LibBee v3.6
-
-╔══════════════════════════════════════════════════════════════════╗
-║  TABLE OF CONTENTS                                              ║
-╠══════════════════════════════════════════════════════════════════╣
-║  §1   Imports                                                   ║
-║  §2   Pydantic Models                                           ║
-║  §3   Constants & Compiled Regexes                              ║
-║  §4   LibCal Hours & Events Service  ← v3.5/v3.6               ║
-║  §5   Runtime Config & Utility Helpers                          ║
-║  §6   Intent Classification (rule-based + LLM)                  ║
-║  §7   LLM Wrappers                                              ║
-║  §8   Topic Extraction                                          ║
-║  §9   Query Builders (PRIMO boolean, PubMed URL)                ║
-║  §10  Search Preparation & Planning                             ║
-║  §11  Search Runners (OpenAlex, Semantic Scholar, PRIMO, PubMed)║
-║  §12  Response Builders (badges, thought blocks, SVG mascots)   ║
-║  §13  Hardcoded Answers (campus, fulltext, DB recs, theses...)  ║
-║  §14  Follow-up System                                          ║
-║  §15  Main Routing (_agent_query_inner)                         ║
-║  §16  FastAPI Endpoint & Utility Routes                         ║
-╚══════════════════════════════════════════════════════════════════╝
-
-Changes over v3.5:
-- §4 LibCal Events: EVENTS_RE + _libcal_fetch_events() +
-  _events_answer() — live upcoming events from KU LibCal calendar
-  via Cloudflare Worker /events proxy. 30-min cache.
-- Routing: EVENTS_RE check added in _agent_query_inner.
-- worker.js: /events endpoint added (v3.6).
+agent.py — LibBee v3.8.1
+
+Changes over v3.6 (two targeted changes only):
+- §3 _URL_INSTRUCTION constant added after _GUARDRAIL.
+- §7 All 6 LLM system prompts now append _URL_INSTRUCTION alongside _GUARDRAIL.
+All other logic is verbatim from v3.6.
 """
 # ── §1 Imports ────────────────────────────────────────────────────────────────
 
@@ -241,9 +218,40 @@ _GUARDRAIL = (
     "Never produce content that could embarrass Khalifa University or its library."
 )
 
+# ── URL accuracy instruction — NEW v3.8.1 — appended to ALL LLM system prompts
+# Prevents the LLM from hallucinating or guessing URLs in any response.
+# All 6 LLM system prompts append this constant alongside _GUARDRAIL.
+_URL_INSTRUCTION = (
+    "IMPORTANT — URLS AND LINKS: "
+    "You must ONLY include URLs that are explicitly present in the context or "
+    "knowledge base provided to you, OR that appear in this fixed verified list of "
+    "KU Library URLs: "
+    "https://library.ku.ac.ae | "
+    "https://library.ku.ac.ae/hours | "
+    "https://library.ku.ac.ae/AskUs | "
+    "https://library.ku.ac.ae/ill/ | "
+    "https://library.ku.ac.ae/rooms/ | "
+    "https://library.ku.ac.ae/eresources | "
+    "https://library.ku.ac.ae/orcid | "
+    "https://library.ku.ac.ae/oa/ | "
+    "https://library.ku.ac.ae/alumni/ | "
+    "https://library.ku.ac.ae/med/ | "
+    "https://library.ku.ac.ae/requesttitle/ | "
+    "https://library.ku.ac.ae/google | "
+    "https://khazna.ku.ac.ae | "
+    "https://khalifa.primo.exlibrisgroup.com/discovery/search?vid=971KUOSTAR_INST:KU | "
+    "https://khalifa.primo.exlibrisgroup.com/discovery/account?vid=971KUOSTAR_INST:KU&section=overview | "
+    "https://kustar.libcal.com/calendar/events | "
+    "https://ku-library.github.io/researchbee/. "
+    "NEVER invent, guess, or construct URLs that are not in the above list or "
+    "explicitly present in the provided context. "
+    "When a relevant verified URL exists for your answer, ALWAYS include it as a "
+    'clickable HTML link: <a href="URL" target="_blank">descriptive link text</a>. '
+    "If you are unsure whether a URL is correct, omit it entirely and direct the "
+    "user to Ask a Librarian at https://library.ku.ac.ae/AskUs instead."
+)
+
 # ── Sensitive institutional topic gate ───────────────────────────────────────
-# Catches requests for negative opinions/criticism about KU, UAE, or religion
-# before any LLM or web search is invoked.
 _SENSITIVE_TOPIC_RE = re.compile(
     r"\b("
     r"(bad|worst|negative[s]?|problem[s]?|issue[s]?|weakness|weaknesses|"
@@ -295,11 +303,9 @@ SUMMARY_RE = re.compile(
 )
 DATABASE_RECOMMEND_RE = re.compile(
     r"("
-    # explicit recommendation phrasing
     r"\b(best database|best databases|which database|which databases"
     r"|database for|databases for"
     r"|where should i search|where should i start)\b"
-    # subscription / access phrasing
     r"|databases?\s+(does|did|do)\s+.{0,40}subscri"
     r"|\bsubscribed\s+databases?\b"
     r"|\blibrary\s+subscri"
@@ -312,7 +318,6 @@ DATABASE_RECOMMEND_RE = re.compile(
     r"|\be.?resources?\s+(available|subscri)\b"
     r"|\baccess\s+to\s+databases?\b"
     r"|\blist\s+of\s+databases?\b"
-    # comparison phrasing  ← NEW
     r"|\b(compare|comparison|difference|differences)\s+(between\s+)?(\w+\s+)?(and\s+)?\w*\s*database"
     r"|\bdifference\s+between.{0,60}database"
     r"|\bscopus\s+(vs|versus|or)\s+(web of science|wos|google scholar)\b"
@@ -321,8 +326,6 @@ DATABASE_RECOMMEND_RE = re.compile(
     re.IGNORECASE,
 )
 
-# ── New pattern detection regexes ────────────────────────────────────────────
-
 HIGHLY_CITED_RE = re.compile(
     r"\b(highly cited|most cited|top cited|citation count|most influential"
     r"|most referenced|high impact papers?|most downloaded)\b",
@@ -342,7 +345,6 @@ BOOLEAN_STRATEGY_RE = re.compile(
 
 FULLTEXT_REQUEST_RE = re.compile(
     r"\b("
-    # PDF / access problem — only fires when there's an explicit access failure
     r"(can.t|cannot|couldn.t|don.t have|doesn.t have|no).{0,30}(access|pdf|full.?text)"
     r"|(pdf|full.?text).{0,20}(not available|unavailable|can.t find|not found|missing)"
     r"|found.{0,30}citation.{0,20}(but|not).{0,20}(pdf|full.?text)"
@@ -413,8 +415,6 @@ ALT_TERMS_RE = re.compile(
     re.IGNORECASE,
 )
 
-# ─────────────────────────────────────────────────────────────────────────────
-
 MEDICAL_KEYWORDS = [
     "medicine", "medical", "health", "clinical", "nursing", "pharmacy", "biomedical",
     "anatomy", "physiology", "epidemiology", "oncology", "cardiology", "neuroscience",
@@ -507,53 +507,25 @@ Respond ONLY with valid JSON. No preamble, no markdown fences.
 
 
 # ── §4 LibCal Hours Service ────────────────────────────────────────────────────
-# Live library hours from the KU LibCal API (kustar.libcal.com).
-# Credentials read from env vars — never hardcoded in source.
-#
-# Location IDs confirmed from page source:
-#   Main Campus Library → 6386
-#   Habshan Library     → 25028
-#
-# Token TTL: 55 min (LibCal tokens expire at 60 min)
-# Hours TTL: 60 min  (hours don't change intra-day)
-# Fallback:  library.ku.ac.ae/hours link if API is unreachable.
-
-# LibCal hours are fetched via the Cloudflare Worker (/hours endpoint).
-# The Worker holds the LibCal credentials and is not blocked by LibCal's
-# host allowlist. Direct calls from HF Spaces return 403.
-#
-# Worker secrets required:  LIBCAL_CLIENT_ID, LIBCAL_CLIENT_SECRET
-# Worker endpoint:          {CLOUDFLARE_WORKER_URL}/hours
-# Location IDs (reference): Main Campus=6386, Habshan=25028
-
-# In-process hours cache — avoids hitting the worker on every hours query
-_libcal_hours_cache: Dict[str, Any] = {}   # {"data": dict, "cached_at": float}
-_LIBCAL_HOURS_TTL = 60 * 60               # 60 minutes
+
+_libcal_hours_cache: Dict[str, Any] = {}
+_LIBCAL_HOURS_TTL = 60 * 60
 
 
 async def _libcal_fetch_hours() -> Optional[dict]:
-    """
-    Fetch today + next 6 days of hours via Cloudflare Worker proxy.
-    The Worker calls LibCal on our behalf (not blocked by LibCal allowlist).
-    Returns dict: {"main_campus": {...}, "habshan": {...}} or None on failure.
-    Caches result for _LIBCAL_HOURS_TTL seconds.
-    """
     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(
@@ -575,38 +547,23 @@ async def _libcal_fetch_hours() -> Optional[dict]:
 
 
 def _parse_libcal_time(raw: str) -> str:
-    """Normalise LibCal time strings: '8:00am' → '8:00 AM', '7:30am' → '7:30 AM'."""
     if not raw:
         return raw
     raw = raw.strip().replace("\u2013", "-").replace("–", "-")
     raw = re.sub(r"\s+", "", raw)
-    # Insert space before AM/PM
     raw = re.sub(r"(?i)(am|pm)$", lambda m: " " + m.group(1).upper(), raw)
     return raw
 
 
 def _format_libcal_day(day_data: dict) -> str:
-    """
-    Return a human-readable hours string for one day entry from LibCal API v1.1.
-
-    LibCal returns several possible structures:
-      Structure A: {"status": "open",   "hours": [{"from": "8:00am", "to": "5:00pm"}]}
-      Structure B: {"status": "open",   "opens": "8:00am", "closes": "5:00pm"}
-      Structure C: {"status": "closed", "note": "Eid Al Adha"}
-      Structure D: {"status": "24hours"}
-    """
     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"
-
-    # Structure A — hours array (LibCal API v1.1 standard)
     hours_list = day_data.get("hours") or []
     if hours_list and isinstance(hours_list, list):
         first = hours_list[0]
@@ -614,14 +571,10 @@ def _format_libcal_day(day_data: dict) -> str:
         t = first.get("to")   or first.get("closes") or ""
         if f and t:
             return f"{_parse_libcal_time(f)} – {_parse_libcal_time(t)}"
-
-    # Structure B — opens/closes at top level
     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)}"
-
-    # Structure C — times list (some LibCal versions)
     times = day_data.get("times") or []
     if times and isinstance(times, list):
         first = times[0]
@@ -629,28 +582,18 @@ def _format_libcal_day(day_data: dict) -> str:
         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:
-    """
-    Return live library hours from LibCal API.
-    Shows today's status prominently, then a 7-day table for each branch.
-    Falls back to a link to library.ku.ac.ae/hours if API is unavailable.
-    """
     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()
-
-    # ── Fallback: link to live hours page ─────────────────────────────────────
     if not hours_data:
         return (
             "Here are the <strong>Khalifa University Library</strong> hours:<br><br>"
@@ -661,18 +604,14 @@ async def _hours_answer() -> str:
             '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>'
         )
-
-    # ── Build per-location sections ────────────────────────────────────────────
     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:
-            # Some responses use "weeks" structure — fall back to link
             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")
@@ -681,7 +620,6 @@ async def _hours_answer() -> str:
             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:
@@ -713,9 +651,7 @@ async def _hours_answer() -> str:
             "<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:
@@ -727,7 +663,6 @@ async def _hours_answer() -> str:
             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" '
@@ -744,11 +679,9 @@ async def _hours_answer() -> str:
 
 EVENTS_RE = re.compile(
     r"\b("
-    # Direct event/workshop/seminar/training queries
     r"library events?|library workshops?|library seminars?|library training"
     r"|library sessions?|library talks?|library webinars?|library programmes?"
     r"|library classes?|library courses?|library instruction"
-    # "upcoming/any/what" + event type
     r"|upcoming (events?|workshops?|seminars?|training|sessions?|talks?|webinars?)"
     r"|any (events?|workshops?|seminars?|training|sessions?|talks?)"
     r"|what (events?|workshops?|seminars?|training|sessions?|talks?)"
@@ -756,14 +689,11 @@ EVENTS_RE = re.compile(
     r"|workshops? (at|in|by|from) (the )?library"
     r"|seminars? (at|in|by|from) (the )?library"
     r"|training (at|in|by|from) (the )?library"
-    # "what's on" / calendar queries
     r"|what'?s? on (at |in )?(the )?library"
     r"|library calendar|library programme|library schedule"
     r"|library events? calendar|events? calendar"
-    # "is there a" patterns
     r"|is there (a |an )?(workshop|seminar|training|session|event|talk|webinar)"
     r"|are there (any )?(workshops?|seminars?|training|sessions?|events?|talks?)"
-    # database/research training specifically
     r"|database training|research skills (workshop|session|training|class)"
     r"|citation (workshop|training|session)|refworks (workshop|training|session)"
     r"|endnote (workshop|training)|zotero (workshop|training)"
@@ -773,26 +703,20 @@ EVENTS_RE = re.compile(
 )
 
 _libcal_events_cache: Dict[str, Any] = {}
-_LIBCAL_EVENTS_TTL = 30 * 60  # 30 minutes — events change more often than hours
+_LIBCAL_EVENTS_TTL = 30 * 60
 
 
 async def _libcal_fetch_events(days: int = 30, limit: int = 10) -> Optional[list]:
-    """
-    Fetch upcoming library events via Cloudflare Worker /events proxy.
-    Caches for 30 minutes.
-    """
     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(
@@ -805,9 +729,7 @@ async def _libcal_fetch_events(days: int = 30, limit: int = 10) -> Optional[list
                 logger.warning("LibCal events worker error: %s", data["error"])
                 return None
             events_raw = data.get("events", [])
-
             def _safe_str(val) -> str:
-                """Flatten LibCal fields that may be str, dict, list, or None."""
                 if val is None:
                     return ""
                 if isinstance(val, str):
@@ -817,16 +739,13 @@ async def _libcal_fetch_events(days: int = 30, limit: int = 10) -> Optional[list
                 if isinstance(val, list):
                     return ", ".join(_safe_str(v) for v in val if v)
                 return str(val)
-
             events = []
             for e in events_raw:
-                # Flatten category — can be list of dicts or list of strings
                 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"),
@@ -849,12 +768,10 @@ async def _libcal_fetch_events(days: int = 30, limit: int = 10) -> Optional[list
 
 
 def _format_event_datetime(start: str, end: str, all_day: bool) -> str:
-    """Format LibCal event start/end into a readable string."""
     if not start:
         return ""
     try:
         from datetime import datetime as _dt
-        # LibCal returns ISO8601: "2026-04-20T14:00:00+04:00" or "2026-04-20"
         s = _dt.fromisoformat(start.replace("Z", "+00:00"))
         date_str = s.strftime("%a %d %b")
         if all_day:
@@ -866,18 +783,12 @@ def _format_event_datetime(start: str, end: str, all_day: bool) -> str:
             return f"{date_str} · {time_str} – {end_str}"
         return f"{date_str} · {time_str}"
     except Exception:
-        # Fallback: return raw start string cleaned up
         return start[:16].replace("T", " ")
 
 
 async def _events_answer(days: int = 30) -> str:
-    """
-    Return upcoming library events from LibCal.
-    Falls back to library events calendar link if unavailable.
-    """
     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>"
@@ -885,7 +796,6 @@ async def _events_answer(days: int = 30) -> str:
             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>"
@@ -893,9 +803,7 @@ async def _events_answer(days: int = 30) -> str:
             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(
@@ -905,7 +813,6 @@ async def _events_answer(days: int = 30) -> str:
         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">'
@@ -927,7 +834,6 @@ async def _events_answer(days: int = 30) -> str:
                 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>'
@@ -936,15 +842,9 @@ async def _events_answer(days: int = 30) -> str:
 
 
 
-
-# ── Runtime config helper ────────────────────────────────────────────────────
+# ── §5 Runtime Config & Utility Helpers ──────────────────────────────────────
 
 def _get_runtime_config() -> dict:
-    """
-    Load the admin runtime config (welcome_message, custom_instructions,
-    announcement, max_results, maintenance_mode) from the JsonRuntimeStore.
-    Returns defaults silently if the file does not exist yet.
-    """
     try:
         from src.services.runtime_store import JsonRuntimeStore
         settings = get_settings()
@@ -1006,7 +906,6 @@ def _source_badge(source: str, url: str = "") -> str:
     )
 
 
-# FIX: use get_metrics_service() accessor to avoid circular import fragility
 def _safe_metrics_increment(key: str) -> None:
     try:
         from app import get_metrics_service
@@ -1096,9 +995,6 @@ def _rule_based_classify(question: str) -> Dict[str, str]:
     return {"intent": "general"}
 
 
-# _hours_answer() is now async and defined in §4 LibCal Hours Service above.
-
-
 def _campus_answer() -> str:
     return (
         "Khalifa University Library has <strong>two branches</strong>:<br><br>"
@@ -1127,13 +1023,13 @@ def _greeting_menu_clarify_answer() -> str:
     )
 
 
-# ── §7 LLM Wrappers ───────────────────────────────────────────────────────────
 
-# ── LLM Helpers ───────────────────────────────────────────────────────────────
+# ── §7 LLM Wrappers ───────────────────────────────────────────────────────────
+# v3.8.1 change: ALL 6 LLM system prompts append both _GUARDRAIL and
+# _URL_INSTRUCTION to prevent hallucinated URLs in any response.
 
 def _get_llm(model: str, temperature: float, max_tokens: int):
     settings = get_settings()
-    # FIX: updated model string — claude-3-haiku-20240307 is deprecated
     if model == "claude" and settings.anthropic_api_key:
         from langchain_anthropic import ChatAnthropic
         return ChatAnthropic(
@@ -1162,9 +1058,6 @@ async def _llm_classify(question: str, history: List[ChatMessage], model: str) -
             if m.role in ("user", "assistant")
         ]
         ctx = " | ".join(ctx_parts) if ctx_parts else "none"
-        # Always use GPT-4o-mini for classification — cheap, fast, consistent
-        # regardless of which model the user has toggled for answers.
-        # This ensures identical routing whether the user is on GPT or Claude.
         classify_model = "gpt" if settings.openai_api_key else model
         llm = _get_llm(classify_model, temperature=0, max_tokens=120)
         response = await llm.ainvoke([
@@ -1185,6 +1078,7 @@ async def _llm_classify(question: str, history: List[ChatMessage], model: str) -
 
 
 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()
@@ -1195,7 +1089,8 @@ async def _libbee_casual_response(question: str, history: List[ChatMessage], mod
         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
+            "No markdown, no bullet points. "
+            + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
         )}]
         _cfg = _get_runtime_config()
         _ci = _cfg.get("custom_instructions", "").strip()
@@ -1210,6 +1105,7 @@ async def _libbee_casual_response(question: str, history: List[ChatMessage], mod
 
 
 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 ""
@@ -1227,7 +1123,7 @@ async def _rag_answer(question: str, rag_results: List[dict], history: List[Chat
         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
+        + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
     )
     _cfg = _get_runtime_config()
     _ci = _cfg.get("custom_instructions", "").strip()
@@ -1249,6 +1145,7 @@ async def _rag_answer(question: str, rag_results: List[dict], history: List[Chat
 
 
 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 (
@@ -1269,7 +1166,7 @@ async def _llm_general_answer(question: str, history: List[ChatMessage], model:
         "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
+        + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
     )
     _cfg = _get_runtime_config()
     _ci = _cfg.get("custom_instructions", "").strip()
@@ -1288,11 +1185,12 @@ async def _llm_general_answer(question: str, history: List[ChatMessage], model:
 
 
 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
+        + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
     )
     if model == "claude" and settings.anthropic_api_key:
         try:
@@ -1310,7 +1208,6 @@ async def _web_search_answer(question: str, history: List[ChatMessage], model: s
                 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
@@ -1331,13 +1228,11 @@ async def _web_search_answer(question: str, history: List[ChatMessage], model: s
                 return text.strip()
         except Exception as e:
             logger.warning(f"GPT web search failed: {e}")
-
     return await _llm_general_answer(question, history, model)
 
 
-# ── §8 Topic Extraction ───────────────────────────────────────────────────────
 
-# ── Topic Extraction ──────────────────────────────────────────────────────────
+# ── §8 Topic Extraction ───────────────────────────────────────────────────────
 
 def _extract_topic_regex(question: str) -> str:
     q = _normalize_whitespace(question)
@@ -1409,31 +1304,16 @@ async def _extract_topic(question: str, model: str) -> str:
     return _extract_topic_regex(question)
 
 
-# ── §9 Query Builders (PRIMO boolean, PubMed URL) ─────────────────────────────
-
-# ── PRIMO / PubMed URL + Query Builders ───────────────────────────────────────
-# FIX: these were previously imported from search.py as
-# build_primo_boolean_query / build_primo_discovery_url / build_pubmed_url
-# but those exports do not exist in search.py.
-# They are now self-contained here.
+# ── §9 Query Builders ──���──────────────────────────────────────────────────────
 
 def _shared_build_primo_boolean_query(topic: str) -> str:
-    """
-    Regex fallback for boolean query construction — used only when LLM is unavailable.
-    Keeps multi-word phrases quoted, strips stop words, ANDs remaining concepts.
-    Does NOT split known compound terms.
-    """
     clean = _strip_resource_noise(topic)
     if not clean:
         clean = topic
     clean = _normalize_whitespace(clean)
-
-    # Treat the whole cleaned topic as a single phrase if ≤ 4 words
     words = clean.split()
     if len(words) <= 4:
         return f'"{clean}"'
-
-    # For longer topics: split on stop words, quote resulting multi-word chunks
     _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|"
@@ -1442,14 +1322,12 @@ def _shared_build_primo_boolean_query(topic: str) -> str:
         r"based|related|towards|toward|during|after|before|over|under)\b",
         re.IGNORECASE,
     )
-    # Split on stop words, keep non-stop chunks
     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]}"'
-    # Quote multi-word concepts, leave single words bare
     quoted = [f'"{c}"' if ' ' in c else c for c in concepts[:4]]
     return " AND ".join(quoted)
 
@@ -1491,13 +1369,6 @@ Output: ("renewable energy" OR "clean energy" OR "sustainable energy") AND ("pol
 
 
 async def _llm_build_boolean_query(topic: str, model: str) -> str:
-    """
-    Use LLM to generate a high-quality PRIMO boolean query with:
-    - Quoted multi-word phrases
-    - OR synonyms within concept groups
-    - AND between distinct concepts
-    Falls back to regex version if LLM fails.
-    """
     settings = get_settings()
     if not settings.openai_api_key and not settings.anthropic_api_key:
         return _shared_build_primo_boolean_query(topic)
@@ -1508,14 +1379,10 @@ async def _llm_build_boolean_query(topic: str, model: str) -> str:
             {"role": "user", "content": f"Input: {topic.strip()}"},
         ])
         result = response.content.strip()
-        # Sanity checks — must contain quotes and AND/OR or be a short phrase
         if not result or len(result) > 500:
             raise ValueError("Bad LLM boolean output")
-        # Strip any markdown the LLM snuck in
         result = re.sub(r"^```[a-z]*\n?", "", result).rstrip("`").strip()
-        # Must have at least one quote or look like a valid query
         if '"' not in result and ' AND ' not in result and ' OR ' not in result:
-            # Wrap bare output as a phrase
             result = f'"{result}"'
         logger.info(f"LLM boolean: {result!r} ← topic: {topic!r}")
         return result
@@ -1525,7 +1392,6 @@ async def _llm_build_boolean_query(topic: str, model: str) -> str:
 
 
 def _make_primo_boolean_query(context: SearchContextPayload) -> str:
-    """Sync wrapper — returns regex boolean. Async LLM version called from _prepare_queries."""
     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)
@@ -1539,7 +1405,6 @@ def _shared_build_primo_discovery_url(
     year_from: Optional[str] = None,
     year_to: Optional[str] = None,
 ) -> str:
-    """Build a full PRIMO discovery URL with facets."""
     base = (
         "https://khalifa.primo.exlibrisgroup.com/discovery/search"
         f"?vid=971KUOSTAR_INST:KU&tab=Everything&scope=MyInst_and_CI"
@@ -1570,7 +1435,6 @@ def _shared_build_pubmed_url(
     year_to: Optional[str] = None,
     peer_reviewed: bool = False,
 ) -> str:
-    """Build a PubMed search URL."""
     clean = _strip_resource_noise(topic)
     term = clean or topic
     if peer_reviewed:
@@ -1583,9 +1447,8 @@ def _shared_build_pubmed_url(
     return url
 
 
-# ── §10 Search Preparation & Planning ────────────────────────────────────────
 
-# ── Query Building ────────────────────────────────────────────────────────────
+# ── §10 Search Preparation & Planning ────────────────────────────────────────
 
 def _derive_resource_type(question: str, existing: Optional[str] = None) -> str:
     q = (question or "").lower()
@@ -1613,12 +1476,6 @@ def _parse_year_filters(question: str) -> Tuple[Optional[str], Optional[str]]:
     return None, None
 
 
-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 _primo_clean_url(context: SearchContextPayload) -> str:
     boolean_query = context.primo_boolean_query or _make_primo_boolean_query(context)
     return _shared_build_primo_discovery_url(
@@ -1644,7 +1501,6 @@ def _compose_ai_tool_query(question: str, context: SearchContextPayload, is_foll
         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}"
@@ -1656,7 +1512,6 @@ def _compose_ai_tool_query(question: str, context: SearchContextPayload, is_foll
         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(".") + "."
@@ -1679,12 +1534,10 @@ async def _grammar_refine_query(text: str, model: str) -> str:
 
 
 def _light_strip_retrieval_boilerplate(text: str) -> str:
-    """Strip common retrieval command prefixes before building a search plan."""
     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)
-    # Pass 1: strip search intent verbs
     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|"
@@ -1693,14 +1546,11 @@ def _light_strip_retrieval_boilerplate(text: str) -> str:
         r"i want articles on|i need papers on|i want papers on)\s+",
         "", cleaned, flags=re.IGNORECASE
     )
-    # Pass 2: strip residual noun boilerplate left after pass 1
-    # e.g. "find research on 33" → pass1 → "research on 33" → pass2 → "33"
     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
     )
-    # Pass 3: strip dangling prepositions
     cleaned = re.sub(
         r"^\s*(on|about|for|regarding|concerning|into|around|of|in|the)\s+",
         "", cleaned, flags=re.IGNORECASE
@@ -1709,7 +1559,6 @@ def _light_strip_retrieval_boilerplate(text: str) -> str:
 
 
 _LEGACY_SYSTEM_PATTERNS = [
-    # Summon — KU's old discovery system, replaced by PRIMO
     (
         re.compile(
             r'(you can use )?summon[™™]?\s*(to find [^.]+\.)?\s*'
@@ -1719,21 +1568,13 @@ _LEGACY_SYSTEM_PATTERNS = [
         ),
         "PRIMO Library Discovery (https://khalifa.primo.exlibrisgroup.com/discovery/search?vid=971KUOSTAR_INST:KU)",
     ),
-    # Any bare Summon reference
     (re.compile(r'\bSummon[™™]?\b', re.IGNORECASE), "PRIMO Library Discovery"),
-    # EDS / EBSCO Discovery Service (not the same as EBSCO databases)
     (re.compile(r'\bEBSCO Discovery Service\b', re.IGNORECASE), "PRIMO Library Discovery"),
-    # Encore (old III discovery)
     (re.compile(r'\bEncore\b(?!\s+(?:learning|education))', re.IGNORECASE), "PRIMO Library Discovery"),
 ]
 
 
 def _sanitize_llm_response(text: str) -> str:
-    """
-    Strip legacy discovery system references from LLM output.
-    KU migrated from Summon → PRIMO. Old KB chunks may still mention Summon
-    and the LLM may echo them. This runs as a final pass on all agent answers.
-    """
     if not text:
         return text
     for pattern, replacement in _LEGACY_SYSTEM_PATTERNS:
@@ -1742,26 +1583,20 @@ def _sanitize_llm_response(text: str) -> str:
 
 
 def _sanitize_boolean_for_primo(boolean: str) -> str:
-    """Clean LLM-generated boolean so it works in PRIMO advanced search URLs."""
     if not boolean:
         return boolean
-    # Single quotes → double quotes around terms
     boolean = re.sub(r"'([^']+)'", r'"\1"', boolean)
-    # Remove pure-year groups like (2025 OR 2026) — years belong in date facets
     boolean = re.sub(
         r"\(\s*(?:(?:19|20)\d{2}\s*(?:OR\s*(?:19|20)\d{2}\s*)*)\)",
         "", boolean, flags=re.IGNORECASE,
     )
-    # Remove dangling AND/OR
     boolean = re.sub(r"^\s*(AND|OR)\s*", "", boolean, flags=re.IGNORECASE)
     boolean = re.sub(r"\s*(AND|OR)\s*$", "", boolean, flags=re.IGNORECASE)
-    # Collapse double AND/OR
     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:
-    """Strip boolean operators/punctuation to get plain keyword string."""
     return re.sub(r"\s+", " ",
                   re.sub(r"\b(AND|OR|NOT)\b|[()\"]", " ",
                          boolean_query, flags=re.IGNORECASE)).strip()
@@ -1784,7 +1619,7 @@ The user typed a research request. Create THREE forms preserving the full intent
 
 3. boolean: write a PRIMO/PubMed Boolean query with AND/OR/parentheses.
 
-Also detect: year_from, year_to (e.g. "last 24 months" → year_from={{CURRENT_YEAR-2}}),
+Also detect: year_from, year_to (e.g. "last 24 months" → year_from={{{CURRENT_YEAR}-2}}),
 peer_reviewed, open_access.
 
 STEP 1 — TOPIC EXTRACTION:
@@ -1849,12 +1684,6 @@ Return ONLY valid JSON:
 
 
 async def _validate_topic(topic: str, model: str) -> Tuple[bool, str]:
-    """
-    Stage 2 topic validator — runs after the regex ambiguity gate.
-    Catches gibberish/unrecognisable words that passed the gate.
-    Returns (True, corrected_topic) or (False, "").
-    Fails open on any exception so it never blocks a legitimate search.
-    """
     settings = get_settings()
     if not settings.openai_api_key and not settings.anthropic_api_key:
         return True, topic
@@ -1892,25 +1721,15 @@ async def _validate_topic(topic: str, model: str) -> Tuple[bool, str]:
 
 
 async def _build_search_plan(question: str, model: str) -> dict:
-    """
-    LLM-driven search plan.
-    Includes:
-    - Ambiguity gate (numbers, single chars, no content words)
-    - Stage 2 LLM topic validator (gibberish detection + typo correction)
-    Falls back to regex boolean if LLM fails.
-    """
     settings = get_settings()
     raw_query = _normalize_whitespace(question or "")
     light_query = _light_strip_retrieval_boilerplate(raw_query) or raw_query
-
-    # ── Stage 1: Regex ambiguity gate ────────────────────────────────────────
     _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 {
@@ -1926,7 +1745,6 @@ async def _build_search_plan(question: str, model: str) -> dict:
                 f"the better I can build your search."
             ),
         }
-    # ── Stage 2: LLM topic validator ─────────────────────────────────────────
     if settings.openai_api_key or settings.anthropic_api_key:
         _valid, _corrected_topic = await _validate_topic(_stripped, model)
         if not _valid:
@@ -1945,8 +1763,6 @@ async def _build_search_plan(question: str, model: str) -> dict:
         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)
@@ -1957,34 +1773,25 @@ async def _build_search_plan(question: str, model: str) -> dict:
             raw = response.content.strip()
             if raw.startswith("```"):
                 raw = raw.split("\n", 1)[1].rsplit("```", 1)[0].strip()
-            # Extract JSON object
             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()
-
-            # Validate boolean — must have operators and structure
             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 LLM didn't detect year filters, fall back to regex
             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,
@@ -1997,8 +1804,6 @@ async def _build_search_plan(question: str, model: str) -> dict:
             }
         except Exception as e:
             logger.warning(f"_build_search_plan LLM failed: {e} — using regex fallback")
-
-    # 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))
@@ -2016,21 +1821,15 @@ async def _build_search_plan(question: str, model: str) -> dict:
 
 
 async def _prepare_queries(question: str, context: SearchContextPayload, model: str, is_follow_up: bool) -> SearchContextPayload:
-    """Build all query forms using _build_search_plan."""
     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)
-
-    # Clarification gate
     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"):
@@ -2039,18 +1838,14 @@ async def _prepare_queries(question: str, context: SearchContextPayload, model:
         context.peer_reviewed = True
     if not context.open_access and plan.get("open_access"):
         context.open_access = True
-
     return context
 
 
-# ── §11 Search Runners ────────────────────────────────────────────────────────
 
+# ── §11 Search Runners ────────────────────────────────────────────────────────
 
 async def _topic_intro(topic: str, model: str) -> str:
-    """
-    3-sentence topic intro — lightweight LLM call (~180 tokens, no external APIs).
-    Prepended to all academic/medical search responses (v3.8).
-    """
+    """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 ""
@@ -2063,7 +1858,8 @@ async def _topic_intro(topic: str, model: str) -> str:
                 "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."
+                "Be concise and informative. "
+                + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
             )},
             {"role": "user", "content": f"Research topic: {topic}"},
         ])
@@ -2074,8 +1870,6 @@ async def _topic_intro(topic: str, model: str) -> str:
         return ""
 
 
-# ── Semantic Scholar + Summary ────────────────────────────────────────────────
-
 async def _semantic_scholar_search(topic: str, limit: int = 8) -> List[dict]:
     clean_topic = _strip_resource_noise(topic)
     if not clean_topic:
@@ -2129,13 +1923,8 @@ async def _semantic_scholar_search(topic: str, limit: int = 8) -> List[dict]:
 
 
 async def _openalex_search(topic: str, limit: int = 8) -> List[dict]:
-    """
-    Search OpenAlex using ?search= — same relevance engine as the browser link.
-    Passes the full corrected natural language query, strips only boolean operators.
-    """
     try:
         from urllib.parse import quote as _oa_quote
-        # Strip boolean operators only — keep all keywords including proper nouns
         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='')
@@ -2155,12 +1944,9 @@ async def _openalex_search(topic: str, limit: int = 8) -> List[dict]:
                 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"
-
-                # Reconstruct abstract from inverted index
                 inv = work.get("abstract_inverted_index") or {}
                 abstract = ""
                 if inv:
@@ -2170,10 +1956,8 @@ async def _openalex_search(topic: str, limit: int = 8) -> List[dict]:
                             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", "")
@@ -2184,7 +1968,6 @@ async def _openalex_search(topic: str, limit: int = 8) -> List[dict]:
                 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 ""
@@ -2197,7 +1980,6 @@ async def _openalex_search(topic: str, limit: int = 8) -> List[dict]:
                     ((work.get("primary_location") or {}).get("source") or {})
                     .get("display_name") or ""
                 )
-
                 results.append({
                     "title": title,
                     "authors": authors_str or "Unknown",
@@ -2209,16 +1991,15 @@ async def _openalex_search(topic: str, limit: int = 8) -> List[dict]:
                     "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 []
 
 
 async def _generate_cited_summary(topic: str, papers: List[dict], model: str) -> str:
+    """LLM #6 — cited literature summary. v3.8.1: appends _GUARDRAIL + _URL_INSTRUCTION."""
     settings = get_settings()
     if not settings.openai_api_key and not settings.anthropic_api_key:
         return ""
@@ -2237,7 +2018,8 @@ async def _generate_cited_summary(topic: str, papers: List[dict], model: str) ->
         "Cite at least 4 different references. "
         "Use HTML <br><br> for paragraph breaks. Do not use bullet points or markdown. "
         "Only state what is explicitly supported by the abstracts. "
-        "Do NOT invent content."
+        "Do NOT invent content. "
+        + _GUARDRAIL + "\n\n" + _URL_INSTRUCTION
     )
     try:
         llm = _get_llm(model, temperature=0.2, max_tokens=560)
@@ -2283,14 +2065,12 @@ def _extractive_snapshot_from_papers(topic: str, papers: List[dict]) -> str:
     return intro + "<br><br>".join(statements[:4])
 
 
-# ── §12 Response Builders ─────────────────────────────────────────────────────
 
-# ── PRIMO / PubMed Search Wrappers ────────────────────────────────────────────
+# ── §12 Response Builders ─────────────────────────────────────────────────────
 
 async def _search_primo_catalog(context: SearchContextPayload, limit: int = 5) -> Tuple[dict, str]:
     from src.api.search import SearchRequest, search_primo
     settings = get_settings()
-    # Use the LLM-built boolean query if available, else fall back to plain topic
     boolean = context.primo_boolean_query
     if not boolean:
         clean_topic = _strip_resource_noise(context.topic)
@@ -2334,8 +2114,6 @@ async def _search_pubmed_articles(context: SearchContextPayload, limit: int = 5)
     return result, pubmed_url
 
 
-# ── AI Tools / Database Guidance ─────────────────────────────────────────────
-
 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)
@@ -2397,12 +2175,9 @@ def _find_staff_by_token(token: str) -> Optional[dict]:
 def _contact_footer_for_query(question: str, context: Optional[SearchContextPayload]) -> str:
     q = (question or "").lower()
     specialist: Optional[dict] = None
-
-    # ILL — always Suaad Al Jneibi, not Jason
     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"]):
-        # Use hardcoded ILL contact since Suaad may not be in staff directory
         footer = (
             "<br><br><strong>Library contact points</strong><br>"
             f'General help: <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a> · '
@@ -2422,7 +2197,6 @@ def _contact_footer_for_query(question: str, context: Optional[SearchContextPayl
         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> · '
@@ -2441,9 +2215,6 @@ def _contact_footer_for_query(question: str, context: Optional[SearchContextPayl
 
 
 def _thought_block(intent: str, tool: str, question: str, extra: str = "") -> str:
-    """
-    Lightweight collapsible reasoning block shown at the top of every non-search response.
-    """
     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."),
@@ -2460,7 +2231,6 @@ def _thought_block(intent: str, tool: str, question: str, extra: str = "") -> st
     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">'
@@ -2476,19 +2246,13 @@ def _thought_block(intent: str, tool: str, question: str, extra: str = "") -> st
 
 
 def _search_trace_block(question: str, context: SearchContextPayload) -> str:
-    """
-    Richer collapsible reasoning block for search responses.
-    Shows topic, boolean query, and reasoning. Also hints that AI tools are at the end.
-    """
     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")
@@ -2503,7 +2267,6 @@ def _search_trace_block(question: str, context: SearchContextPayload) -> str:
     )
     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>, "
@@ -2512,7 +2275,6 @@ def _search_trace_block(question: str, context: SearchContextPayload) -> str:
     )
     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">'
@@ -2534,6 +2296,7 @@ def _search_trace_block(question: str, context: SearchContextPayload) -> str:
     return block
 
 
+
 def _ai_tools_footer(context):
     from urllib.parse import quote as _q
 
@@ -2562,7 +2325,6 @@ def _ai_tools_footer(context):
     if is_med and pubmed_url:
         platforms.append(("PubMed", pubmed_url, "pubmed"))
 
-    # Inline SVG mascots — unique per database type, no network requests
     _SVGS = {
         "bee": (
             '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" width="16" height="16" style="flex-shrink:0">'
@@ -2664,7 +2426,6 @@ def _ai_tools_footer(context):
             '<circle cx="12" cy="4" r="1.2" fill="#fef3c7"/>'
             '</svg>'
         ),
-        # Platform mascots — publisher-style
         "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"/>'
@@ -2725,7 +2486,6 @@ def _ai_tools_footer(context):
             '</svg>'
         ),
     }
-    # Per-database mascot map
     _DB_MASCOT = {
         "PubMed@KU": "microscope", "Embase": "medical", "CINAHL Ultimate": "medical",
         "Cochrane Library": "microscope", "UpToDate": "medical",
@@ -2736,8 +2496,7 @@ def _ai_tools_footer(context):
         "Business Source Complete": "chart", "Emerald Insight": "chart",
         "Taylor & Francis": "book", "EBSCO": "book",
     }
-    _BEE = _SVGS["bee"]  # default for platform buttons
-
+    _BEE = _SVGS["bee"]
 
     def _btn(label, url, mascot_key="bee"):
         icon = _SVGS.get(mascot_key, _SVGS["bee"])
@@ -2898,11 +2657,6 @@ def _is_database_recommendation_question(question: str) -> bool:
 
 
 def _safe_db_url(url: str) -> str:
-    """
-    Encode the inner URL in IDM proxy links so the frontend fmt() auto-linkify
-    regex cannot match a bare https:// inside an href attribute and break the HTML.
-    e.g. href="...?url=https://foo.com" → href="...?url=https%3A%2F%2Ffoo.com"
-    """
     from urllib.parse import quote as _quote
     if "?url=" in url:
         base, inner = url.split("?url=", 1)
@@ -2910,8 +2664,9 @@ def _safe_db_url(url: str) -> str:
     return url
 
 
-# ── Subject → database mapping sourced from KU KB ────────────────────────────
-# All IDM proxy URLs are encoded via _safe_db_url to prevent HTML breakage.
+
+# ── Subject → database mapping ────────────────────────────────────────────────
+
 _DB_SUBJECTS: Dict[str, List[Tuple[str, str, str]]] = {
     "physics": [
         ("APS Journals", _safe_db_url("https://khalifa.idm.oclc.org/login?url=https://journals.aps.org"), "American Physical Society — core physics journals."),
@@ -3087,7 +2842,6 @@ _DB_SUBJECTS: Dict[str, List[Tuple[str, str, str]]] = {
     ],
 }
 
-# General / fallback databases (used when no subject match found)
 _DB_GENERAL: List[Tuple[str, str, str]] = [
     ("PRIMO (KU Library Discovery)", "https://khalifa.primo.exlibrisgroup.com/discovery/search?vid=971KUOSTAR_INST:KU", "Best starting point — search all KU books, articles, and journals."),
     ("Scopus", _safe_db_url("https://khalifa.idm.oclc.org/login?url=https://www.scopus.com"), "Largest abstract and citation database — all disciplines."),
@@ -3101,7 +2855,6 @@ _DB_GENERAL: List[Tuple[str, str, str]] = [
 
 
 def _match_db_subject(q: str) -> Optional[str]:
-    """Map lowercased question to a _DB_SUBJECTS key using keyword matching."""
     checks = [
         (["quantum computing", "quantum algorithm", "quantum cryptography", "quantum information"], "quantum_computing"),
         (["robotics", "autonomous system", "intelligent system"], "robotics"),
@@ -3136,13 +2889,7 @@ def _match_db_subject(q: str) -> Optional[str]:
 
 
 def _extract_db_topic(question: str) -> str:
-    """
-    Extract the subject from a database-recommendation question.
-    e.g. "best databases for physics" → "physics"
-         "which database should I use for machine learning" → "machine learning"
-    """
     q = _normalize_whitespace(question or "")
-    # Strip leading boilerplate phrases
     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+",
@@ -3156,7 +2903,6 @@ def _extract_db_topic(question: str) -> str:
         if m:
             q = q[m.end():]
             break
-    # Strip trailing noise
     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"
@@ -3166,26 +2912,18 @@ def _database_recommendation_answer(question: str) -> str:
     q = (question or "").lower()
     subject = _extract_db_topic(question)
     topic = _escape(subject)
-
-    # Match to a specific subject list; fall back to general KU databases
     subject_key = _match_db_subject(q)
     dbs = _DB_SUBJECTS.get(subject_key, _DB_GENERAL) if subject_key else _DB_GENERAL
-
-    # Cap at 5 results for readability
     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:
-        # Generic topic — add a note that subject-specific guides exist
         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>'
@@ -3194,12 +2932,10 @@ def _database_recommendation_answer(question: str) -> str:
     return answer
 
 
-# ── §13 Hardcoded Answers ─────────────────────────────────────────────────────
 
-# ── Full-text access chain ────────────────────────────────────────────────────
+# ── §13 Hardcoded Answers ─────────────────────────────────────────────────────
 
 def _fulltext_chain_answer(question: str) -> str:
-    """Step-by-step guide for getting full text when PDF is unavailable."""
     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>"
@@ -3225,18 +2961,11 @@ def _fulltext_chain_answer(question: str) -> str:
     )
 
 
-# ── Search strategy / Boolean explanation ─────────────────────────────────────
-
 async def _search_strategy_answer(question: str, model: str) -> Tuple[str, dict]:
-    """
-    Build a search plan AND explain it step by step.
-    Returns (explanation_html, plan_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>"
@@ -3262,10 +2991,7 @@ async def _search_strategy_answer(question: str, model: str) -> Tuple[str, dict]
     return explanation, plan
 
 
-# ── Alternative search terms ──────────────────────────────────────────────────
-
 async def _alternative_terms_answer(question: str, context: Optional[SearchContextPayload], model: str) -> str:
-    """Generate alternative keywords/synonyms for the current topic without re-running the search."""
     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:
@@ -3300,8 +3026,6 @@ async def _alternative_terms_answer(question: str, context: Optional[SearchConte
         return f"<strong>Alternative terms for {_escape(topic)}</strong><br><br>Try synonyms, acronyms, broader/narrower terms, and related concepts in your search."
 
 
-# ── Citation chaining guide ───────────────────────────────────────────────────
-
 def _citation_chain_answer() -> str:
     return (
         "<strong>🔗 How to trace citations forward and backward from a paper</strong><br><br>"
@@ -3326,8 +3050,6 @@ def _citation_chain_answer() -> str:
     )
 
 
-# ── Predatory / peer-review evaluation guide ─────────────────────────────────
-
 def _predatory_eval_answer() -> str:
     return (
         "<strong>✅ How to tell if an article or journal is peer-reviewed, scholarly, or predatory</strong><br><br>"
@@ -3356,8 +3078,6 @@ def _predatory_eval_answer() -> str:
     )
 
 
-# ── Theses / dissertations guide ─────────────────────────────────────────────
-
 def _theses_answer() -> str:
     return (
         "<strong>📘 Finding KU theses, dissertations, and institutional research</strong><br><br>"
@@ -3380,10 +3100,7 @@ def _theses_answer() -> str:
     )
 
 
-# ── Highly-cited papers guide ─────────────────────────────────────────────────
-
 def _highly_cited_note(topic_escaped: str) -> str:
-    """Append to a standard search answer when highly-cited filter is detected."""
     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>"
@@ -3398,13 +3115,7 @@ def _highly_cited_note(topic_escaped: str) -> str:
     )
 
 
-# ── Research Snapshot ─────────────────────────────────────────────────────────
-
 async def _research_snapshot(context: SearchContextPayload, model: str) -> Tuple[str, List[dict], List[dict]]:
-    """
-    Research snapshot — no API calls.
-    Shows PRIMO browser link + AI tools footer only.
-    """
     topic = context.topic
     primo_url = _primo_clean_url(context)
     answer = _search_trace_block(f"Research on {topic}", context)
@@ -3419,9 +3130,9 @@ async def _research_snapshot(context: SearchContextPayload, model: str) -> Tuple
     answer += _ai_tools_footer(context)
     return answer, [], []
 
-# ── §14 Follow-up System ──────────────────────────────────────────────────────
 
-# ── Follow-up System ──────────────────────────────────────────────────────────
+
+# ── §14 Follow-up System ──────────────────────────────────────────────────────
 
 def _filters_summary(context: SearchContextPayload) -> str:
     filters: List[str] = []
@@ -3467,7 +3178,6 @@ def _parse_refinement_action(question: str) -> Optional[str]:
         return "last_5_years"
     if re.search(r"\b(last|past)\s+10\s+years?\b|\bpast decade\b", q):
         return "last_10_years"
-    # "last 3 years", "last 2 years" etc.
     m = re.search(r"\b(last|past)\s+(\d{1,2})\s+years?\b", q)
     if m:
         return f"last_{m.group(2)}_years"
@@ -3477,17 +3187,10 @@ def _parse_refinement_action(question: str) -> Optional[str]:
         return "articles_only"
     if re.search(r"\b(?:both|articles and books|books and articles)\b", q):
         return "both_resources"
-    # Review articles only — NEW
     if REVIEW_ONLY_RE.search(q):
         return "review_articles_only"
-    # Alternative search terms — NEW
     if ALT_TERMS_RE.search(q):
         return "alt_terms"
-    # summarize_topic: ONLY match short/topicless follow-ups like "summarize this",
-    # "give me an overview", "what does the literature say" — NOT questions that
-    # include an explicit new topic like "summarize quantum physics".
-    # A question with 4+ non-stop content words almost certainly has its own topic
-    # and should be handled as a fresh query, not a follow-up.
     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',
@@ -3498,7 +3201,6 @@ def _parse_refinement_action(question: str) -> Optional[str]:
         }
         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'})]
-        # Any explicit topic word → treat as a fresh query, not a follow-up
         if content_words:
             return None
         return "summarize_topic"
@@ -3571,7 +3273,6 @@ def _apply_follow_up_action(base_context: SearchContextPayload, action: Optional
         context.year_from = str(CURRENT_YEAR - 1)
         context.year_to = str(CURRENT_YEAR)
     elif action and action.startswith("last_") and action.endswith("_years"):
-        # Generic "last N years" — parse N
         try:
             n = int(action.split("_")[1])
             context.year_from = str(CURRENT_YEAR - n + 1)
@@ -3585,11 +3286,8 @@ def _apply_follow_up_action(base_context: SearchContextPayload, action: Optional
     elif action == "both_resources":
         context.resource_type = "both"
     elif action == "review_articles_only":
-        # Map to PRIMO facet for review articles — stored as resource_type hint
         context.resource_type = "articles"
-        context.peer_reviewed = True  # reviews are implicitly peer-reviewed
-        # Store the review filter flag in the context notes field if available
-        # The PRIMO query will add facet_rtype=reviews
+        context.peer_reviewed = True
     elif action == "search_pubmed":
         context.source = "pubmed"
         context.intent = "search_medical"
@@ -3781,6 +3479,7 @@ async def _run_search_mode(
 
     return answer, [], [], source_url
 
+
 def _sort_and_trim_contexts(contexts: List[SearchContextPayload]) -> List[SearchContextPayload]:
     dedup: Dict[str, SearchContextPayload] = {}
     for ctx in contexts:
@@ -3789,18 +3488,15 @@ def _sort_and_trim_contexts(contexts: List[SearchContextPayload]) -> List[Search
     return ordered[:5]
 
 
-# ── §15 Main Routing ──────────────────────────────────────────────────────────
 
-# ── Main Endpoint ──────────────────────────────────────────────────────────────
+# ── §15 Main Routing ──────────────────────────────────────────────────────────
 
 def _log_agent_query(question: str, response: AgentResponse, start_time: float) -> None:
-    """Fire-and-forget query logging to MetricsService AND Cloudflare D1 via Worker."""
     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 [])
-    # Log to local MetricsService (in-memory counters)
     try:
         from app import get_metrics_service
         get_metrics_service().log_query(
@@ -3813,7 +3509,6 @@ def _log_agent_query(question: str, response: AgentResponse, start_time: float)
         )
     except Exception:
         pass
-    # Log to Cloudflare D1 via Worker (persistent across deploys)
     try:
         settings = get_settings()
         worker_url = getattr(settings, "cloudflare_worker_url", "") or ""
@@ -3844,34 +3539,6 @@ def _log_agent_query(question: str, response: AgentResponse, start_time: float)
         pass
 
 
-
-# ── §16 FastAPI Endpoint & Utility Routes ─────────────────────────────────────
-
-@router.post("", response_model=AgentResponse)
-async def agent_query(request: Request, req: AgentRequest):
-    start_time = time.time()
-    question = _normalize_whitespace(req.question)
-    history = req.history
-    model = req.model
-    client_state = req.client_state
-    _safe_metrics_increment("agent_requests")
-    response = await _agent_query_inner(question, history, model, client_state, start_time)
-    # Strip legacy discovery system references (Summon etc.) from all responses
-    response.answer = _sanitize_llm_response(response.answer)
-    _log_agent_query(question, response, start_time)
-    # Append announcement banner if set in admin config
-    _rcfg = _get_runtime_config()
-    _ann = _rcfg.get("announcement", "").strip()
-    if _ann and response.intent not in ("social_greeting", "social"):
-        _ann_html = (
-            '<div style="margin-top:14px;padding:10px 14px;border-radius:10px;'
-            'background:#fffbeb;border:1px solid #fde68a;font-size:.82rem;color:#92400e">'
-            f'📢 {_ann}</div>'
-        )
-        response.answer = response.answer + _ann_html
-    return response
-
-
 async def _agent_query_inner(
     question: str,
     history,
@@ -3896,12 +3563,6 @@ async def _agent_query_inner(
             response_time=time.time() - start_time,
         )
 
-    # ── Sensitive institutional topic gate ───────────────────────────────────
-    # Handled by LLM classifier (intent == "sensitive") further below.
-    # The regex gate (_SENSITIVE_TOPIC_RE) has been removed in favour of the
-    # LLM classifier which understands context and intent more accurately.
-    # ─────────────────────────────────────────────────────────────────────────
-
     if not question:
         follow_up_question, follow_up_suggestions = _social_follow_up()
         return AgentResponse(
@@ -4032,9 +3693,7 @@ async def _agent_query_inner(
 
     is_follow_up, follow_up_action, base_context = _detect_follow_up(question, client_state)
 
-    # ── Catalogue availability: "books available in the KU library on X" ─────────
-    # Catches questions asking what the library *holds*, not topic searches.
-    # Must fire BEFORE the LLM classifier which would route these to search_academic.
+    # ── Catalogue availability ────────────────────────────────────────────────
     _CATALOGUE_RE = re.compile(
         r"\b("
         r"available in (the )?(ku|khalifa) library"
@@ -4049,8 +3708,6 @@ async def _agent_query_inner(
     _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):
-        # Route as library_info → RAG will handle or fall back to Ask a Librarian
-        # Also build a PRIMO books URL so the user can search directly
         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"
@@ -4069,7 +3726,6 @@ async def _agent_query_inner(
         )
         follow_up_question, follow_up_suggestions = _library_follow_up(question)
 
-        # Try RAG first for any policy/service context
         rag_results = []
         try:
             from app import get_rag_service
@@ -4107,74 +3763,6 @@ async def _agent_query_inner(
         _safe_metrics_increment("follow_up_hits")
         context = _apply_follow_up_action(base_context, follow_up_action)
 
-        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:
-                # deep_research_tools / best_databases follow-up
-                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,
-        )
-
-    if is_follow_up and base_context:
-        _safe_metrics_increment("follow_up_hits")
-        context = _apply_follow_up_action(base_context, follow_up_action)
-
-        # ── Follow-up: alternative search terms (no new search) ───────────────
         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)
@@ -4195,7 +3783,6 @@ async def _agent_query_inner(
             if follow_up_action == "summarize_topic":
                 answer, search_results, sources = await _research_snapshot(context, model)
             else:
-                # deep_research_tools / best_databases follow-up
                 answer = (
                     f"{_search_trace_block(question, context)}"
                     f"<strong>Research guide for {_escape(context.display_topic or context.topic)}</strong><br><br>"
@@ -4254,10 +3841,7 @@ async def _agent_query_inner(
         )
 
     # ── Pre-classifier specialist handlers ───────────────────────────────────
-    # These fire BEFORE the LLM classifier for patterns the classifier handles
-    # poorly (too often routes to search_academic for library-service questions).
 
-    # Full-text / ILL chain
     if FULLTEXT_REQUEST_RE.search(question):
         ft_answer = _fulltext_chain_answer(question)
         follow_up_question, follow_up_suggestions = _library_follow_up(question)
@@ -4272,7 +3856,6 @@ async def _agent_query_inner(
             follow_up_suggestions=follow_up_suggestions,
         )
 
-    # Theses / dissertations / Khazna
     if THESES_RE.search(question):
         th_answer = _theses_answer()
         follow_up_question, follow_up_suggestions = _library_follow_up(question)
@@ -4287,7 +3870,6 @@ async def _agent_query_inner(
             follow_up_suggestions=follow_up_suggestions,
         )
 
-    # Predatory / peer-review evaluation
     if PREDATORY_RE.search(question):
         pr_answer = _predatory_eval_answer()
         follow_up_question, follow_up_suggestions = _library_follow_up(question)
@@ -4302,7 +3884,6 @@ async def _agent_query_inner(
             follow_up_suggestions=follow_up_suggestions,
         )
 
-    # Citation chaining
     if CITATION_CHAIN_RE.search(question):
         cc_answer = _citation_chain_answer()
         follow_up_question, follow_up_suggestions = _library_follow_up(question)
@@ -4317,7 +3898,6 @@ async def _agent_query_inner(
             follow_up_suggestions=follow_up_suggestions,
         )
 
-    # Search strategy / boolean explanation
     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)
@@ -4334,7 +3914,6 @@ async def _agent_query_inner(
             follow_up_suggestions=follow_up_suggestions,
         )
 
-    # Alternative search terms (standalone, not follow-up)
     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)
@@ -4348,7 +3927,6 @@ async def _agent_query_inner(
             follow_up_suggestions=follow_up_suggestions,
         )
 
-    # FIX: _llm_classify always falls back to rule-based on any exception
     cls_result = await _llm_classify(question, history, model)
     intent = cls_result.get("intent", "general")
     _safe_metrics_bucket("intents", intent)
@@ -4436,10 +4014,8 @@ async def _agent_query_inner(
         )
 
     if intent in ("search_academic", "search_medical"):
-        # ── Partial title search — route to PRIMO title query ─────────────────
         if PARTIAL_TITLE_RE.search(question):
             from urllib.parse import quote as _qt
-            # Extract quoted fragment or the whole question as title search
             _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)
@@ -4479,10 +4055,8 @@ async def _agent_query_inner(
         topic = _title_case_topic(topic)
         year_from, year_to = _parse_year_filters(question)
 
-        # ── Dual resource type: articles AND books in one question ─────────────
         if DUAL_RESOURCE_RE.search(question):
             import asyncio as _aio
-            # Build two contexts: articles and books
             _ctx_articles = SearchContextPayload(
                 context_id=str(uuid.uuid4()), topic=topic, display_topic=topic,
                 intent=intent, source="primo", resource_type="articles",
@@ -4500,8 +4074,6 @@ async def _agent_query_inner(
                 _prepare_queries(question, _ctx_articles, model, False),
                 _prepare_queries(question, _ctx_books, model, False),
             )
-            # No API — just build PRIMO links for articles and books
-            _ctx_articles = await _prepare_queries(question, _ctx_articles, model, False)
             _src_url_a = _primo_clean_url(_ctx_articles)
             _src_url_b = _primo_clean_url(_ctx_books)
 
@@ -4589,7 +4161,6 @@ async def _agent_query_inner(
             )
 
         answer, search_results, sources, source_url = await _run_search_mode(question, context, model, False)
-        # Append highly-cited guidance if requested
         if is_highly_cited:
             answer += _highly_cited_note(_escape(topic))
         follow_up_question, follow_up_suggestions = await _search_follow_up(context, model)
@@ -4641,7 +4212,30 @@ async def _agent_query_inner(
     )
 
 
-# ── Utility Endpoints ──────────────────────────────────────────────────────────
+# ── §16 FastAPI Endpoint & Utility Routes ─────────────────────────────────────
+
+@router.post("", response_model=AgentResponse)
+async def agent_query(request: Request, req: AgentRequest):
+    start_time = time.time()
+    question = _normalize_whitespace(req.question)
+    history = req.history
+    model = req.model
+    client_state = req.client_state
+    _safe_metrics_increment("agent_requests")
+    response = await _agent_query_inner(question, history, model, client_state, start_time)
+    response.answer = _sanitize_llm_response(response.answer)
+    _log_agent_query(question, response, start_time)
+    _rcfg = _get_runtime_config()
+    _ann = _rcfg.get("announcement", "").strip()
+    if _ann and response.intent not in ("social_greeting", "social"):
+        _ann_html = (
+            '<div style="margin-top:14px;padding:10px 14px;border-radius:10px;'
+            'background:#fffbeb;border:1px solid #fde68a;font-size:.82rem;color:#92400e">'
+            f'📢 {_ann}</div>'
+        )
+        response.answer = response.answer + _ann_html
+    return response
+
 
 @router.get("/test")
 async def test():
@@ -4654,7 +4248,6 @@ async def test():
 
 @router.get("/rag-status")
 async def rag_status():
-    # FIX: use get_rag_service() accessor
     try:
         from app import get_rag_service
         return get_rag_service().get_stats()