Upload 2 files

agent.py

@@ -0,0 +1,1958 @@
+"""
+agent.py — LibBee v3 (fixed)
+
+Fixes applied:
+1. _extract_topic() — explicitly strips resource-type words (articles/books/papers)
+   from LLM output and regex fallback. Topic is ALWAYS clean keywords only.
+
+2. _make_primo_discovery_query() — removed all resource-type words from boolean.
+   Boolean is now: "keyword1 keyword2 keyword3" only.
+   Resource type handled exclusively via SearchRequest.resource_type → PRIMO facet.
+
+3. _search_primo_catalog() — now passes resource_type=context.resource_type so
+   the rtype FACET is correctly sent to PRIMO.
+
+4. _search_pubmed_articles() — year_from/year_to now wired through SearchRequest,
+   fixed in search.py to use mindate/maxdate params (not keywords).
+
+5. _search_follow_up() — now calls LLM to generate 3 topic-specific intellectual
+   follow-up questions (related subtopics, methodological angles, applications).
+   Generic filter options remain as a secondary set after the topic-specific ones.
+
+6. _primo_url_from_boolean() — now uses clean topic (not polluted boolean) for the
+   displayed PRIMO URL, matching exactly what the API actually searches.
+
+7. _generate_cited_summary() / Semantic Scholar — improved: relevance filter on
+   abstracts, better fallback, clearer citation replacement.
+"""
+import html
+import json
+import logging
+import re
+import time
+import uuid
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+from fastapi import APIRouter, Request
+from pydantic import BaseModel, ConfigDict, Field
+
+from src.config import get_settings
+from src.services.staff_service import (
+    STAFF_DIRECTORY,
+    match_staff_name,
+    match_staff_role,
+    should_attempt_staff_lookup,
+    staff_name_answer,
+    staff_role_answer,
+)
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+# ── Pydantic Models ───────────────────────────────────────────────────────────
+
+class ChatMessage(BaseModel):
+    role: str
+    content: str
+
+
+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"
+    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
+    created_at: float = Field(default_factory=time.time)
+
+
+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
+
+
+class AgentRequest(BaseModel):
+    question: str
+    model: str = "gpt"
+    history: List[ChatMessage] = Field(default_factory=list)
+    client_state: Optional[ClientStatePayload] = None
+
+
+class AgentResponse(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    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)
+    model_used: str = "gpt"
+    response_time: float = 0
+    corrected_query: Optional[str] = None
+    natural_query: Optional[str] = None
+    database_query: Optional[str] = None
+    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)
+    search_context: Optional[dict] = None
+    ai_tool_query: Optional[str] = None
+    primo_boolean_query: Optional[str] = None
+    primo_search_url: Optional[str] = None
+
+
+# ── Constants ─────────────────────────────────────────────────────────────────
+
+LIBRARY_HOURS_URL = "https://library.ku.ac.ae/hours"
+KU_MAIN_URL = "https://www.ku.ac.ae/"
+ASK_LIBRARIAN_URL = "https://library.ku.ac.ae/AskUs"
+PRIMO_BASE_URL = "https://khalifa.primo.exlibrisgroup.com/discovery/search?vid=971KUOSTAR_INST:KU"
+PRIMO_AI_URL = "https://khalifa.primo.exlibrisgroup.com/discovery/researchAssistant?vid=971KUOSTAR_INST:KU&query="
+HISTORY_WINDOW = 6
+CURRENT_YEAR = datetime.utcnow().year
+
+# Words that must never appear in a PRIMO/PubMed keyword query — they are filter signals
+_RESOURCE_TYPE_NOISE = re.compile(
+    r"\b(articles?|papers?|books?|ebooks?|journals?|publications?|monographs?"
+    r"|peer[- ]reviewed|open[- ]access|studies|study|research)\b",
+    re.IGNORECASE,
+)
+
+SOCIAL_RE = re.compile(
+    r"^(hi|hello|hey|good morning|good afternoon|good evening|how are you|hows it going"
+    r"|how are you doing|who are you|what are you|tell me about yourself|what can you do"
+    r"|what do you do|how can you help|what help can you provide|are you a bot|are you a robot"
+    r"|are you ai|are you an ai|thank you|thanks|thx|bye|goodbye|see you|lol|haha"
+    r"|you are silly|are you silly|are you dumb|stupid bot|dumb bot|idiot bot"
+    r"|joke|tell me a joke)$",
+    re.IGNORECASE,
+)
+PURE_GREETING_RE = re.compile(
+    r"^(hi|hello|hey|good morning|good afternoon|good evening)[!.\s]*$",
+    re.IGNORECASE,
+)
+GREETING_FOLLOWUP_RE = re.compile(
+    r"^(yes|yes please|yes check|sure|okay|ok|yeah|yep|please do|go ahead)$",
+    re.IGNORECASE,
+)
+HOURS_RE = re.compile(
+    r"\b(library hours?|opening hours?|closing hours?|open hours?|open today|open tomorrow"
+    r"|open now|open on|open this|closed today|closed tomorrow|closed on|closed this"
+    r"|when.*open|when.*close|when.*does.*library|what time.*open|what time.*close"
+    r"|what time.*library|opening time|closing time|is.*library.*open|is.*campus.*library"
+    r"|is.*habshan.*open|is.*san.*open|is.*library.*closed|will.*library.*open"
+    r"|will.*it.*open|does.*library.*open|library.*open.*today|library.*close.*today"
+    r"|habshan.*open|san.*open|main campus.*open|ramadan hours?|weekend hours?"
+    r"|friday hours?|saturday hours?|sunday hours?|library.*schedule|schedule.*library"
+    r"|what.*hours|till.*when|until.*when|what day.*open|which day.*open"
+    r"|what day.*closed|which day.*closed)\b",
+    re.IGNORECASE,
+)
+KU_CAMPUS_RE = re.compile(
+    r"\b(where is the library|where is.*library|library.*location|location.*library"
+    r"|which building|what building|which floor|main campus library|san campus library"
+    r"|habshan library|sas al nakhl library|library.*address|address.*library"
+    r"|how to get to.*library|how.*reach.*library|how.*find.*library"
+    r"|library.*campus(es)?|campus(es)?.*library|how many.*librar|how many.*branch"
+    r"|library.*branch(es)?|branch(es)?.*library|which campus.*library"
+    r"|library.*which campus|library.*map|map.*library|how many libraries"
+    r"|what libraries|which libraries|(ku|khalifa).*(has|have|got).*(librar|branch)"
+    r"|(librar|branch).*(ku|khalifa).*(has|have)"
+    r"|(all|both|two|2).*(libraries|library|branches)"
+    r"|tell me about.*(campus|libraries|branches)|describe.*(campus|libraries)"
+    r"|(what|where).*(campus|campuses).*(librar))\b",
+    re.IGNORECASE,
+)
+RESEARCH_CUE_RE = re.compile(
+    r"\b(find|search|look for|show me|get me|give me|locate|recommend|suggest"
+    r"|articles?|papers?|books?|journals?|studies|literature|research|systematic review"
+    r"|evidence|sources|database|databases|peer reviewed|open access|advances?"
+    r"|approach(es)?|method(s|ology)?|technique[s]?|application[s]?|framework[s]?"
+    r"|model[s]?|algorithm[s]?|publication[s]?|recent work|current state|state of the art)\b",
+    re.IGNORECASE,
+)
+LIBRARY_CUE_RE = re.compile(
+    r"\b(library|librarian|borrow|loan|renew|fine|study room|room booking|reserve a room"
+    r"|account|my library|interlibrary|ill|khazna|orcid|open access|apc|refworks"
+    r"|libkey|hours|location|contact|visitor|alumni|database access|off campus|remote access)\b",
+    re.IGNORECASE,
+)
+MEDICAL_SEARCH_RE = re.compile(
+    r"\b(pubmed|embase|cinahl|clinicalkey|cochrane|uptodate|medline|systematic review"
+    r"|clinical trial|biomedical literature|medical literature)\b",
+    re.IGNORECASE,
+)
+CURRENT_INFO_RE = re.compile(
+    r"\b(current|currently|latest|today|recent|recently|now|this week|this month"
+    r"|news|update|updated|prime minister|ceo|minister|king|ruler|who won)\b",
+    re.IGNORECASE,
+)
+SUMMARY_RE = re.compile(
+    r"\b(summar(y|ize|ise|izing|ising)|overview|explain|what is|what are|describe"
+    r"|tell me about|give me a summary|give me an overview|give me a brief"
+    r"|brief (summary|overview|explanation|description)"
+    r"|research (overview|summary|landscape|state)"
+    r"|state of (the art|research|the field)"
+    r"|recent (advances?|developments?|progress|trends?)"
+    r"|current (state|trends?|advances?|research)"
+    r"|deep analysis|analysis of|review of|literature review|deep research|deep dive"
+    r"|what do we know about|how does|how do)\b",
+    re.IGNORECASE,
+)
+
+BEST_DATABASES_RE = re.compile(
+    r"\b(best databases?|which databases?|which database|best database|recommended databases?)\b",
+    re.IGNORECASE,
+)
+
+MEDICAL_KEYWORDS = [
+    "medicine", "medical", "health", "clinical", "nursing", "pharmacy", "biomedical",
+    "anatomy", "physiology", "epidemiology", "oncology", "cardiology", "neuroscience",
+    "genomics", "pathology", "surgery", "mental health", "nutrition", "public health",
+    "disease", "therapy", "treatment", "diagnosis", "patient", "drug", "pharmaceutical",
+    "hospital", "cancer", "diabetes", "heart", "brain", "cell biology", "immunology",
+    "biochemistry", "microbiology", "virology", "pediatric", "psychiatric", "dental",
+    "ophthalmology", "radiology", "anesthesia", "emergency medicine", "geriatric",
+    "crispr", "gene therapy", "gene editing", "genomic medicine", "precision medicine",
+]
+
+REFINEMENT_STOP_WORDS = {
+    "make", "it", "them", "those", "these", "the", "a", "an", "for", "to", "only", "show",
+    "find", "give", "me", "please", "and", "with", "within", "limit", "narrow", "search",
+    "results", "on", "about", "of", "this", "that", "topic", "same", "using", "from",
+    "peer", "reviewed", "review", "open", "access", "books", "book", "articles", "article",
+    "papers", "paper", "years", "year", "last", "past", "recent", "instead", "summary",
+    "overview", "brief", "pubmed", "primo", "database", "databases", "best", "deep", "research",
+    "tools", "tool", "guide", "ku", "library",
+}
+
+_CLASSIFIER_SYSTEM = """You are the routing brain of LibBee, the Khalifa University Library AI Assistant (Abu Dhabi, UAE).
+Your only job: read the user message and return a single JSON object routing it to the right handler.
+
+INTENTS — pick exactly one:
+  "social"         — casual chat, greetings, emotions, compliments, complaints, vague help requests
+  "library_info"   — questions about KU Library services, hours, rooms, borrowing, fines, ILL, staff, databases, ORCID, RefWorks, open access, APC, account, printing, remote access, LibKey, acquisitions, Khazna, thesis submission, library policies, alumni access
+  "search_academic"— user wants to FIND/GET articles/papers/books on a topic, OR wants a summary/overview/analysis/explanation of an academic/research topic
+  "search_medical" — same as search_academic but topic is medical/clinical/nursing/pharmacy/health sciences
+  "general_recent" — questions about TRULY live/real-time data: breaking news, live sports scores, today's weather, current stock prices
+  "general"        — ALL other factual questions: university info, people, history, science definitions, technology explanations
+
+RULES:
+  1. When in doubt between library_info and social, choose library_info if ANY library keyword is present.
+  2. "I don't know how to search for articles" = library_info.
+  3. "I am fed up with searching" alone = social.
+  4. "I need help finding articles on diabetes" = search_medical.
+  5. KU = Khalifa University. Do NOT confuse with Kuwait University.
+  6. ANY summary, overview, analysis, deep dive, review, or explanation of an academic/research topic = search_academic or search_medical.
+  7. Questions about people, university leadership, history, science definitions = general.
+  8. Only use general_recent for truly live data changing by the minute.
+
+For "social" intent ONLY: include "casual_answer" — a warm 1-3 sentence LibBee response (no markdown, no bullets).
+For all other intents: omit "casual_answer".
+
+Respond ONLY with valid JSON. No preamble, no markdown fences.
+"""
+
+
+# ── Utilities ─────────────────────────────────────────────────────────────────
+
+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:
+    """
+    Remove resource-type and filter words that are PRIMO/PubMed facets, not q= keywords.
+    Belt-and-braces: called on every topic before it touches an external search API.
+    """
+    cleaned = _RESOURCE_TYPE_NOISE.sub(" ", text or "")
+    # Clean up dangling boolean operators
+    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 _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"),
+        "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 _safe_metrics_increment(key: str) -> None:
+    try:
+        from app import metrics_service
+        metrics_service.incr(key)
+    except Exception:
+        return
+
+
+def _safe_metrics_bucket(bucket: str, key: str) -> None:
+    try:
+        from app import metrics_service
+        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 _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"}
+
+
+def _hours_answer() -> str:
+    return (
+        "Here are the current <strong>Khalifa University Library</strong> hours:<br><br>"
+        "<strong>Habshan Library (SAN Campus):</strong><br>"
+        "Sunday – Wednesday: 8:00 AM – 7:00 PM<br>"
+        "Thursday: 8:00 AM – 4:00 PM<br>"
+        "Friday: Closed<br>"
+        "Saturday: 12:00 PM – 8:00 PM<br><br>"
+        "⚠️ Hours may change during exam periods, public holidays, and Ramadan. "
+        "Always check the official Library Hours page for the latest times:<br>"
+        f'<a href="{LIBRARY_HOURS_URL}" target="_blank">{LIBRARY_HOURS_URL}</a>'
+    )
+
+
+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"
+    )
+
+
+# ── LLM Helpers ───────────────────────────────────────────────────────────────
+
+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-3-haiku-20240307",
+            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,
+    )
+
+
+async def _llm_classify(question: str, history: List[ChatMessage], model: str) -> Dict[str, str]:
+    settings = get_settings()
+    if not settings.openai_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"
+        llm = _get_llm(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"}:
+            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)
+
+
+async def _libbee_casual_response(question: str, history: List[ChatMessage], model: str, hint: str = "") -> str:
+    if hint and len(hint.strip()) > 20:
+        return hint.strip()
+    settings = get_settings()
+    if not settings.openai_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."
+        )}]
+        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 _rag_answer(question: str, rag_results: List[dict], history: List[ChatMessage], model: str) -> str:
+    settings = get_settings()
+    if not settings.openai_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. "
+        f"If the context does not contain enough information, say so and suggest Ask a Librarian at {ASK_LIBRARIAN_URL}. "
+        "Never invent facts or URLs.\n\n"
+        f"CONTEXT:\n{context}"
+    )
+    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>.'
+        )
+
+
+async def _llm_general_answer(question: str, history: List[ChatMessage], model: str) -> str:
+    settings = get_settings()
+    if not settings.openai_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."
+    )
+    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:
+    settings = get_settings()
+    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-3-haiku-20240307",
+                max_tokens=520,
+                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."
+                ),
+                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=(
+                    "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."
+                ),
+                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)
+
+
+# ── Topic Extraction ──────────────────────────────────────────────────────────
+
+def _extract_topic_regex(question: str) -> str:
+    """Fast regex-based topic extraction — strips boilerplate prefixes and filter words."""
+    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
+    # Strip trailing noise
+    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)
+    # FIX: strip resource-type words that leaked through prefix stripping
+    q = _strip_resource_noise(q)
+    return _normalize_whitespace(q).strip(".?")
+
+
+async def _extract_topic(question: str, model: str) -> str:
+    """
+    LLM-based topic extraction.
+    CRITICAL: instructs LLM to never return resource-type words (articles/books/papers).
+    Falls back to regex if LLM unavailable or returns empty.
+    """
+    settings = get_settings()
+    if not settings.openai_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(".")
+        # Belt-and-braces: strip any noise the LLM snuck in anyway
+        topic = _strip_resource_noise(topic)
+        topic = _normalize_whitespace(topic).strip(".?")
+        if topic and len(topic) > 2:
+            logger.info(f"LLM topic: '{topic}' ← '{question[:60]}'")
+            return topic
+    except Exception as e:
+        logger.warning(f"Topic extraction failed: {e}")
+    return _extract_topic_regex(question)
+
+
+# ── Query Building ────────────────────────────────────────────────────────────
+
+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 _make_primo_boolean_query(context: SearchContextPayload) -> str:
+    """
+    FIX: Build a clean boolean for display purposes ONLY.
+    Contains ONLY topic keywords — NO resource-type words.
+    Resource type is expressed as a PRIMO facet in search_primo(), never here.
+    """
+    topic = _title_case_topic(context.display_topic or context.topic)
+    # Strip any remaining noise one final time
+    topic = _strip_resource_noise(topic)
+    if not topic:
+        topic = context.topic or "library search"
+    return f'"{_normalize_whitespace(topic)}"'
+
+
+def _primo_clean_url(context: SearchContextPayload) -> str:
+    """
+    Build the PRIMO discovery URL using the clean topic — matching exactly what the API searches.
+    """
+    clean_topic = _strip_resource_noise(context.topic)
+    if not clean_topic:
+        clean_topic = context.topic
+    return f"{PRIMO_BASE_URL}&query=any,contains,{quote(clean_topic)}&lang=en&mode=advanced&offset=0"
+
+
+def _topic_keywords(text: str) -> List[str]:
+    cleaned = _normalize_whitespace(re.sub(r"[^a-zA-Z0-9\s-]", " ", text or ""))
+    stop = {
+        "of", "on", "in", "the", "a", "an", "and", "or", "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", "impact",
+        "role", "effect", "use", "study", "analysis", "review", "what", "how", "why", "when", "where",
+        "which", "recent", "latest", "current", "summary", "summarize", "overview", "brief",
+        # FIX: resource-type words must never appear as keywords
+        "research", "studies", "articles", "article", "papers", "paper", "books", "book",
+        "journals", "journal", "publications", "publication",
+    }
+    tokens: List[str] = []
+    for word in cleaned.split():
+        word = word.strip("-").lower()
+        if not word or word in stop or len(word) < 3:
+            continue
+        if word not in tokens:
+            tokens.append(word)
+    return tokens[:6]
+
+
+def _compose_ai_tool_query(question: str, context: SearchContextPayload, is_follow_up: bool) -> str:
+    """Build the clean natural language query for AI tools (LeapSpace, Scopus AI, Consensus)."""
+    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(".") + "."
+
+
+async def _grammar_refine_query(text: str, model: str) -> str:
+    settings = get_settings()
+    if not settings.openai_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 _context_to_dict(context: SearchContextPayload) -> dict:
+    return context.model_dump()
+
+
+async def _prepare_queries(question: str, context: SearchContextPayload, model: str, is_follow_up: bool) -> SearchContextPayload:
+    """Populate ai_tool_query and primo_boolean_query on the context."""
+    natural = _compose_ai_tool_query(question, context, is_follow_up)
+    natural = await _grammar_refine_query(natural, model)
+    context.ai_tool_query = natural
+    # FIX: boolean is now clean topic only — resource type goes to PRIMO as a facet
+    context.primo_boolean_query = _make_primo_boolean_query(context)
+    return context
+
+
+# ── Semantic Scholar + Summary ────────────────────────────────────────────────
+
+async def _semantic_scholar_search(topic: str, limit: int = 8) -> List[dict]:
+    """Search Semantic Scholar. Returns only papers that have abstracts."""
+    # FIX: strip resource noise from topic before hitting external API
+    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}",
+                    "venue": paper.get("venue", ""),
+                    "abstract": abstract[:700],
+                    "link": link,
+                    "_source": "Semantic Scholar",
+                })
+            logger.info(f"Semantic Scholar: {len(results)} papers with abstracts for '{clean_topic}'")
+            return results
+    except Exception as e:
+        logger.error(f"Semantic Scholar search failed: {e}")
+        return []
+
+
+async def _generate_cited_summary(topic: str, papers: List[dict], model: str) -> str:
+    """
+    Generate a research summary with clickable in-text citations [Author, Year].
+    Each [N] in the LLM output is replaced with a hyperlink to the actual paper.
+    """
+    settings = get_settings()
+    if not settings.openai_api_key or not papers:
+        return ""
+
+    context_text = ""
+    for i, paper in enumerate(papers, 1):
+        context_text += (
+            f"[{i}] {paper['citation_key']}: {paper['title']}\n"
+            f"Abstract: {paper['abstract']}\n\n"
+        )
+
+    system = (
+        "You are a research librarian writing a concise academic literature snapshot. "
+        "Using ONLY the numbered references provided, write a 4-6 sentence summary on the given topic. "
+        "Use in-text citations as [1], [2], [3] etc. referring to the numbered references. "
+        "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."
+    )
+
+    try:
+        llm = _get_llm(model, temperature=0.2, max_tokens=560)
+        response = await llm.ainvoke([
+            {"role": "system", "content": system},
+            {"role": "user", "content": f"Topic: {topic}\n\nReferences:\n{context_text}\nWrite the summary."},
+        ])
+        summary = response.content.strip()
+
+        # Replace [N] with clickable citation links — work backwards to avoid [1] matching inside [10]
+        for i in range(len(papers), 0, -1):
+            paper = papers[i - 1]
+            title_escaped = _escape(paper["title"])
+            cite_html = (
+                f'<a href="{paper["link"]}" target="_blank" '
+                f'title="{title_escaped}" '
+                f'style="color:#1e40af;font-weight:600;text-decoration:none">'
+                f'[{paper["citation_key"]}]</a>'
+            )
+            summary = summary.replace(f"[{i}]", cite_html)
+        return summary
+    except Exception as e:
+        logger.error(f"Summary generation failed: {e}")
+        return ""
+
+
+def _extractive_snapshot_from_papers(topic: str, papers: List[dict]) -> str:
+    """Fallback: extract lead sentences from abstracts when LLM summary fails."""
+    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])
+
+
+# ── PRIMO / PubMed Search Wrappers ────────────────────────────────────────────
+
+from src.api.search import SearchRequest, search_primo, search_pubmed
+
+
+async def _search_primo_catalog(context: SearchContextPayload, limit: int = 5) -> Tuple[dict, str]:
+    """
+    FIX: now passes resource_type so the rtype FACET is correctly sent to PRIMO.
+    Topic is stripped of noise before hitting the API.
+    """
+    settings = get_settings()
+    # FIX: strip resource noise from topic — belt-and-braces
+    clean_topic = _strip_resource_noise(context.topic)
+    if not clean_topic:
+        clean_topic = context.topic
+
+    result = await search_primo(
+        SearchRequest(
+            query=clean_topic,
+            source="primo",
+            limit=limit,
+            peer_reviewed=context.peer_reviewed,
+            open_access=context.open_access,
+            year_from=context.year_from,
+            year_to=context.year_to,
+            resource_type=context.resource_type,  # FIX: was missing — resource type now goes as facet
+        ),
+        settings.primo_api_key,
+    )
+    source_url = _primo_clean_url(context)
+    return result, source_url
+
+
+async def _search_pubmed_articles(context: SearchContextPayload, limit: int = 5) -> Tuple[dict, str]:
+    """
+    FIX: year_from/year_to now correctly wired through SearchRequest → mindate/maxdate in search.py.
+    """
+    clean_topic = _strip_resource_noise(context.topic)
+    if not clean_topic:
+        clean_topic = context.topic
+
+    result = await search_pubmed(
+        SearchRequest(
+            query=clean_topic,
+            source="pubmed",
+            limit=limit,
+            peer_reviewed=context.peer_reviewed,
+            year_from=context.year_from,   # FIX: now actually used in search.py
+            year_to=context.year_to,       # FIX: now actually used in search.py
+        )
+    )
+    pubmed_url = f"https://pubmed.ncbi.nlm.nih.gov/?term={quote(clean_topic)}"
+    if context.year_from and context.year_to:
+        pubmed_url += f"&filter=datesearch.y_custom&dates.from={context.year_from}&dates.to={context.year_to}"
+    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)
+    clean_topic = _strip_resource_noise(context.topic)
+    return {
+        "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}",
+        "consensus": f"https://consensus.app/results/?q={ai_query}",
+        "primo_discovery": _primo_clean_url(context),
+    }
+
+
+def _ai_source_links_html(context: SearchContextPayload) -> str:
+    urls = _tool_urls(context)
+    return (
+        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["consensus"]}" target="_blank" style="color:#86198f;font-weight:700;text-decoration:none">Consensus</a> · '
+        f'<a href="{urls["primo_discovery"]}" target="_blank" style="color:#5b21b6;font-weight:700;text-decoration:none">PRIMO Library Discovery</a>'
+    )
+
+
+def _database_guidance_for_topic(context: SearchContextPayload) -> str:
+    topic = _escape(context.display_topic or context.topic)
+    links = _ai_source_links_html(context)
+    if context.intent == "search_medical":
+        return (
+            f"For a stronger evidence trail on <strong>{topic}</strong>, start with <strong>PubMed</strong> or <strong>Embase</strong> for the core medical literature, "
+            f"then continue with {links}."
+        )
+    return (
+        f"For deeper work on <strong>{topic}</strong>, continue with {links}. "
+        "Use Scopus AI for broader scholarly mapping, LeapSpace for guided evidence exploration, "
+        "Consensus for quick paper-grounded answers, and PRIMO Library Discovery for KU-accessible material."
+    )
+
+
+def _looks_database_recommendation_question(question: str) -> bool:
+    q = (question or "").lower()
+    return bool(BEST_DATABASES_RE.search(q)) and any(kw in q for kw in [
+        "database", "databases", "subject", "engineering", "medicine", "medical", "ai", "computer",
+        "physics", "chemistry", "chemical", "civil", "mechanical", "electrical", "business",
+        "biomedical", "nursing", "systematic review", "health"
+    ])
+
+
+def _database_recommendation_payload(question: str) -> Dict[str, Any]:
+    q = (question or "").lower()
+    general = {
+        "title": "General / multidisciplinary research",
+        "intro": "These are the best starting databases for broad academic searching at KU.",
+        "items": [
+            {"name": "PRIMO Library Discovery", "url": "https://khalifa.primo.exlibrisgroup.com/discovery/search?vid=971KUOSTAR_INST:KU", "why": "Best first stop for KU-accessible books, articles, journals, and holdings."},
+            {"name": "Scopus", "url": "https://khalifa.idm.oclc.org/login?url=https://www.scopus.com", "why": "Broad multidisciplinary database for scholarly discovery and citation tracking."},
+            {"name": "Web of Science", "url": "https://khalifa.idm.oclc.org/login?url=https://www.webofscience.com", "why": "Strong citation database for high-level literature mapping and journal evaluation."},
+            {"name": "ScienceDirect", "url": "https://khalifa.idm.oclc.org/login?url=https://www.sciencedirect.com", "why": "Large full-text platform across science, engineering, and medicine."},
+        ],
+    }
+    subjects = [
+        (["systematic review", "medicine", "medical", "health", "nursing", "clinical", "biomedical", "pharmacy"], {
+            "title": "Medical and health sciences",
+            "intro": "For medical evidence and subject searching, start with these databases.",
+            "items": [
+                {"name": "PubMed@KU", "url": "http://www.ncbi.nlm.nih.gov/pubmed/?otool=iaekustlib", "why": "Core biomedical literature with KU full-text linking."},
+                {"name": "Embase", "url": "https://khalifa.idm.oclc.org/login?url=https://www.embase.com", "why": "Excellent for biomedical, drugs, devices, and evidence searching."},
+                {"name": "CINAHL Ultimate", "url": "https://khalifa.idm.oclc.org/login?url=https://search.ebscohost.com/login.aspx?authtype=ip,uid&profile=ehost&defaultdb=cul", "why": "Best for nursing and allied health literature."},
+                {"name": "Cochrane Library", "url": "https://khalifa.idm.oclc.org/login?url=https://www.cochranelibrary.com", "why": "Key source for systematic reviews and evidence-based medicine."},
+                {"name": "UpToDate", "url": "https://khalifa.idm.oclc.org/login?url=https://www.uptodate.com", "why": "Clinical point-of-care resource for evidence summaries."},
+            ],
+        }),
+        (["computer science", "machine learning", "artificial intelligence", " ai", "cyber", "software", "algorithm", "computer", "data science"], {
+            "title": "Computer science and AI",
+            "intro": "For computing, AI, software, and algorithms, these are the best starting points.",
+            "items": [
+                {"name": "ACM Digital Library", "url": "https://khalifa.idm.oclc.org/login?url=https://dl.acm.org", "why": "Core computer science literature."},
+                {"name": "IEEE Xplore", "url": "https://khalifa.idm.oclc.org/login?url=https://ieeexplore.ieee.org", "why": "Strong for AI, computing systems, networks, and engineering."},
+                {"name": "arXiv", "url": "https://arxiv.org", "why": "Useful for fast-moving preprints in AI and computer science."},
+                {"name": "Scopus", "url": "https://khalifa.idm.oclc.org/login?url=https://www.scopus.com", "why": "Good for citation tracking and broader discovery."},
+            ],
+        }),
+        (["electrical", "electronics", "signals", "power systems", "communications"], {
+            "title": "Electrical engineering",
+            "intro": "For electrical engineering topics, start here.",
+            "items": [
+                {"name": "IEEE Xplore", "url": "https://khalifa.idm.oclc.org/login?url=https://ieeexplore.ieee.org", "why": "Core database for electrical engineering literature and standards."},
+                {"name": "INSPEC", "url": "https://khalifa.idm.oclc.org/login?url=https://www.theiet.org/publishing/inspec", "why": "Strong indexing for EE, electronics, communications, and computing."},
+                {"name": "ScienceDirect", "url": "https://khalifa.idm.oclc.org/login?url=https://www.sciencedirect.com", "why": "Good full-text coverage across electrical engineering and controls."},
+            ],
+        }),
+        (["mechanical", "thermo", "fluids", "manufacturing"], {
+            "title": "Mechanical engineering",
+            "intro": "For mechanical engineering, these are the strongest starts.",
+            "items": [
+                {"name": "ASME Digital Library", "url": "https://khalifa.idm.oclc.org/login?url=https://asmedigitalcollection.asme.org", "why": "Core mechanical engineering journals and conference papers."},
+                {"name": "Knovel", "url": "https://khalifa.idm.oclc.org/login?url=https://app.knovel.com", "why": "Engineering reference books and technical data."},
+                {"name": "ScienceDirect", "url": "https://khalifa.idm.oclc.org/login?url=https://www.sciencedirect.com", "why": "Strong full-text support for applied engineering topics."},
+            ],
+        }),
+        (["civil", "geotechnical", "transportation", "construction", "structures"], {
+            "title": "Civil engineering",
+            "intro": "For civil engineering and infrastructure topics, start here.",
+            "items": [
+                {"name": "ASCE Library", "url": "https://khalifa.idm.oclc.org/login?url=https://ascelibrary.org", "why": "Core civil engineering journals and conference papers."},
+                {"name": "ASTM Compass", "url": "https://khalifa.idm.oclc.org/login?url=https://compass.astm.org", "why": "Important standards and testing information for materials and engineering."},
+                {"name": "ScienceDirect", "url": "https://khalifa.idm.oclc.org/login?url=https://www.sciencedirect.com", "why": "Useful full-text coverage across civil engineering subjects."},
+            ],
+        }),
+        (["aerospace", "aerodynamics", "propulsion", "aircraft"], {
+            "title": "Aerospace engineering",
+            "intro": "For aerospace topics, these are the best databases to begin with.",
+            "items": [
+                {"name": "AIAA Aerospace Research Central", "url": "https://khalifa.idm.oclc.org/login?url=https://arc.aiaa.org/", "why": "Core aerospace journals and conference literature."},
+                {"name": "ASME Digital Library", "url": "https://khalifa.idm.oclc.org/login?url=https://asmedigitalcollection.asme.org", "why": "Useful for thermal, mechanical, and fluid systems relevant to aerospace."},
+                {"name": "ScienceDirect", "url": "https://khalifa.idm.oclc.org/login?url=https://www.sciencedirect.com", "why": "Good full-text support for aerospace materials and systems."},
+            ],
+        }),
+        (["chemical engineering", "catalysis", "separations", "chemistry", "chemical"], {
+            "title": "Chemistry and chemical engineering",
+            "intro": "For chemistry and chemical engineering, these are the strongest starting points.",
+            "items": [
+                {"name": "ACS Publications", "url": "https://khalifa.idm.oclc.org/login?url=https://pubs.acs.org", "why": "Core chemistry journals."},
+                {"name": "SciFindern", "url": "https://khalifa.idm.oclc.org/login?url=https://scifinder-n.cas.org", "why": "Best for substances, reactions, and chemistry references."},
+                {"name": "Reaxys", "url": "https://khalifa.idm.oclc.org/login?url=https://www.reaxys.com", "why": "Useful for chemistry reactions and property searching."},
+                {"name": "ScienceDirect", "url": "https://khalifa.idm.oclc.org/login?url=https://www.sciencedirect.com", "why": "Strong full-text source for chemical engineering journals."},
+            ],
+        }),
+        (["physics", "quantum", "optics", "plasma"], {
+            "title": "Physics",
+            "intro": "For physics topics, start with these databases and platforms.",
+            "items": [
+                {"name": "APS Journals", "url": "https://khalifa.idm.oclc.org/login?url=https://journals.aps.org", "why": "Core American Physical Society journals."},
+                {"name": "AIP", "url": "https://khalifa.idm.oclc.org/login?url=https://aip.scitation.org", "why": "Major physics and applied physics content."},
+                {"name": "arXiv", "url": "https://arxiv.org", "why": "Open preprints in physics and related areas."},
+            ],
+        }),
+        (["business", "management", "marketing", "economics", "finance"], {
+            "title": "Business and management",
+            "intro": "For business-related topics, start with these databases.",
+            "items": [
+                {"name": "Business Source Complete", "url": "https://khalifa.idm.oclc.org/login?url=https://search.ebscohost.com/login.aspx?authtype=ip,uid&profile=ehost&defaultdb=bsh", "why": "Comprehensive business database."},
+                {"name": "Emerald Insight", "url": "https://khalifa.idm.oclc.org/login?url=https://www.emerald.com/insight", "why": "Strong for management, marketing, and business journals."},
+                {"name": "ProQuest Databases", "url": "https://khalifa.idm.oclc.org/login?url=https://search.proquest.com", "why": "Broad business and dissertation coverage."},
+            ],
+        }),
+    ]
+    for keywords, payload in subjects:
+        if any(k in q for k in keywords):
+            return payload
+    return general
+
+
+def _database_recommendation_answer(question: str) -> str:
+    payload = _database_recommendation_payload(question)
+    answer = f"<strong>Best databases for { _escape(payload['title']) }</strong><br><br>{_escape(payload['intro'])}<br>"
+    for item in payload['items']:
+        answer += (
+            f'<br>• <a href="{item["url"]}" target="_blank" style="color:#003366;font-weight:600">{_escape(item["name"])}</a><br>'
+            f'<span style="font-size:.9rem;color:#4b5563">{_escape(item["why"])}</span>'
+        )
+    answer += (
+        f'<br><br>You can also start in <a href="{PRIMO_BASE_URL}" target="_blank">PRIMO Library Discovery</a> '
+        'and then narrow by resource type, date, and peer-reviewed content.'
+    )
+    answer += _source_badge("ku_library", "https://library.ku.ac.ae/eresources")
+    return answer
+
+
+# ── Research Snapshot ─────────────────────────────────────────────────────────
+
+async def _research_snapshot(context: SearchContextPayload, model: str) -> Tuple[str, List[dict], List[dict]]:
+    """
+    Full research snapshot:
+    1. Semantic Scholar → cited summary with hyperlinked [Author, Year] citations
+    2. PRIMO → KU-accessible results appended below
+    """
+    topic = context.topic
+    papers = await _semantic_scholar_search(topic, limit=8)
+    references: List[dict] = []
+    primo_result, primo_url = await _search_primo_catalog(context, limit=6)
+    search_results = primo_result.get("results", []) or []
+
+    if papers:
+        summary = await _generate_cited_summary(topic, papers, model)
+        if not summary:
+            _safe_metrics_increment("summary_fallbacks")
+            summary = _extractive_snapshot_from_papers(topic, papers)
+
+        answer = f"<strong>📖 Research Snapshot: {_escape(topic)}</strong><br><br>{summary}"
+        if search_results:
+            answer += (
+                "<br><br><strong>KU Library starting points:</strong> "
+                "I also pulled KU-accessible results below so you can move directly from the snapshot to subscribed material."
+            )
+        answer += f"<br><br><strong>AI sources:</strong> {_database_guidance_for_topic(context)}"
+        answer += "<br><br><strong>Selected references:</strong><br>"
+        for i, paper in enumerate(papers[:6], 1):
+            answer += (
+                f'<br><strong>[{i}]</strong> '
+                f'<a href="{paper["link"]}" target="_blank" style="color:#003366;font-weight:600">{_escape(paper["title"])}</a><br>'
+                f'<span style="font-size:.8rem;color:#6b7280">'
+                f'{_escape(paper["authors"])} · {paper["year"]} · {_escape(paper["venue"] or "")}'
+                f'</span>'
+            )
+        answer += _source_badge("semantic", "https://www.semanticscholar.org/")
+        if search_results:
+            answer += _source_badge("primo", primo_url)
+        references = [{"title": p["title"], "url": p["link"]} for p in papers[:6]]
+        return answer, search_results, references
+
+    if search_results:
+        answer = (
+            f"<strong>📚 KU Library starting points on {_escape(topic)}</strong><br><br>"
+            "I couldn't build a Semantic Scholar snapshot right now, but here are KU-accessible library results you can open immediately. "
+            f"<br><br><strong>AI sources:</strong> {_database_guidance_for_topic(context)}"
+        )
+    else:
+        answer = (
+            f"I couldn't retrieve a research snapshot for <strong>{_escape(topic)}</strong> right now.<br><br>"
+            f"<strong>AI sources:</strong> {_database_guidance_for_topic(context)}"
+        )
+    answer += _source_badge("primo", primo_url)
+    return answer, search_results, []
+
+
+# ── Follow-up System ──────────────────────────────────────────────────────────
+
+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"
+    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 re.search(r"\b(summar(y|ize|ise)|overview|brief|what does the literature say|research snapshot)\b", q):
+        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 == "books_only":
+        context.resource_type = "books"
+    elif action == "articles_only":
+        context.resource_type = "articles"
+    elif action == "both_resources":
+        context.resource_type = "both"
+    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]:
+    """
+    FIX: Generate 3 topic-specific intellectual follow-up questions using LLM.
+    These are ASPECT-based (related subtopics, methodological angles, applications)
+    not generic filter suggestions like "peer reviewed only".
+    """
+    settings = get_settings()
+    if not settings.openai_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("?") + " — find articles", "action": "new_search"}
+            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]]:
+    """
+    FIX: Now generates topic-specific intellectual follow-ups (LLM-based)
+    PLUS a smaller set of generic filter options as secondary suggestions.
+    Total suggestions: 3 topic-specific + up to 2 filter options = max 5.
+    """
+    topic = context.display_topic or context.topic
+    suggestions: List[dict] = []
+
+    # ── Topic-specific intellectual follow-ups (LLM-generated) ───────────────
+    topic_follow_ups = await _generate_topic_follow_ups(topic, model)
+    suggestions.extend(topic_follow_ups)
+
+    # ── Generic filter options (secondary) ────────────────────────────────────
+    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,
+        })
+        filter_suggestions.append({
+            "label": f"Limit {topic} to the last 5 years",
+            "question": f"Limit {topic} to the last 5 years",
+            "action": "last_5_years",
+            "context_id": context.context_id,
+        })
+    else:
+        if not context.peer_reviewed and context.source == "primo":
+            filter_suggestions.append({
+                "label": f"Peer reviewed only",
+                "question": f"Make the {topic} search peer reviewed only",
+                "action": "peer_reviewed_only",
+                "context_id": context.context_id,
+            })
+        if not (context.year_from and context.year_to == str(CURRENT_YEAR)):
+            filter_suggestions.append({
+                "label": "Last 5 years",
+                "question": f"Limit {topic} to the last 5 years",
+                "action": "last_5_years",
+                "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,
+        })
+
+    # Add up to 2 filter suggestions after topic-specific ones
+    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 _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"},
+        ],
+    )
+
+
+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"},
+        ],
+    )
+
+
+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:
+        return f"I updated your previous search on <strong>{topic}</strong> in the <strong>{location}</strong> and looked for <strong>{resource}</strong>."
+    return f"I searched the <strong>{location}</strong> for <strong>{resource}</strong> on <strong>{topic}</strong>."
+
+
+async def _run_search_mode(
+    question: str, context: SearchContextPayload, model: str, is_follow_up: bool
+) -> Tuple[str, List[dict], List[dict], str]:
+    context = await _prepare_queries(question, context, model, is_follow_up)
+    filters = _filters_summary(context)
+
+    if context.source == "pubmed":
+        result, source_url = await _search_pubmed_articles(context, limit=6)
+        source_name = "pubmed"
+    else:
+        result, source_url = await _search_primo_catalog(context, limit=6)
+        source_name = "primo"
+
+    search_results = result.get("results", []) or []
+    total = result.get("total", len(search_results))
+
+    answer = _search_answer_intro(context, is_follow_up)
+    if filters:
+        answer += f"<br><br><strong>Current filters:</strong> {_escape(filters)}."
+    if search_results:
+        answer += f"<br><br>I found <strong>{total}</strong> result(s). The top items are shown below."
+    else:
+        answer += (
+            "<br><br>I couldn't retrieve matching results right now. "
+            "You can still try the direct library links and AI research tools below."
+        )
+    if context.intent == "search_medical" and context.source != "pubmed":
+        answer += "<br><br>For the strongest medical evidence trail, I also recommend checking <strong>PubMed</strong> or <strong>Embase</strong>."
+
+    answer += _source_badge(source_name, source_url)
+    sources = []
+    for item in search_results[:6]:
+        link = item.get("primo_url") or item.get("link")
+        if link:
+            sources.append({"title": item.get("title", "Result"), "url": link})
+    return answer, search_results, 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]
+
+
+# ── Main Endpoint ──────────────────────────────────────────────────────────────
+
+@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")
+
+    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=(
+                "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=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=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=_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)
+        return AgentResponse(
+            answer=_hours_answer() + _source_badge("ku_library", LIBRARY_HOURS_URL),
+            intent="library_info",
+            tools_used=["hours_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 _looks_campus_question(question):
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=_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 _looks_database_recommendation_question(question):
+        follow_up_question = "Would you like me to search one of these databases for you next?"
+        follow_up_suggestions = [
+            {"label": "Search PRIMO on this topic", "question": question.replace("best databases", "find articles").replace("which database should I use for", "find articles on")},
+            {"label": "Show off-campus access help", "question": "How do I access databases off campus?"},
+        ]
+        return AgentResponse(
+            answer=_database_recommendation_answer(question),
+            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)
+
+    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 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)
+            elif follow_up_action == "best_databases":
+                answer = _database_recommendation_answer(context.display_topic or context.topic)
+                search_results = []
+                sources = []
+            else:
+                answer = (
+                    f"<strong>Research guide for {_escape(context.display_topic or context.topic)}</strong><br><br>"
+                    f"{_database_guidance_for_topic(context)}"
+                    + _source_badge("libbee")
+                )
+                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),
+                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,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
+            search_context=_context_to_dict(context),
+            is_follow_up=True,
+        )
+
+    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=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 == "library_info":
+        try:
+            from app import rag_service
+            rag_results = await rag_service.hybrid_search(question, top_k=4)
+        except Exception as e:
+            logger.error(f"RAG search failed: {e}")
+            rag_results = []
+
+        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"]
+        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"]
+
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
+        return AgentResponse(
+            answer=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"):
+        topic = await _extract_topic(question, model)
+        topic = _title_case_topic(topic)
+        year_from, year_to = _parse_year_filters(question)
+        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,
+        ))
+
+        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:
+                answer += f"<br><br><strong>Research guide:</strong> {_database_guidance_for_topic(context)}"
+            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),
+                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)
+        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,
+            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=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,
+        )
+
+    answer = await _web_search_answer(question, history, model) + _source_badge("web")
+    follow_up_question, follow_up_suggestions = _general_follow_up(question)
+    return AgentResponse(
+        answer=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,
+    )
+
+
+# ── Utility Endpoints ──────────────────────────────────────────────────────────
+
+@router.get("/test")
+async def test():
+    return {
+        "status": "ok",
+        "message": "Agent endpoint is working!",
+        "staff_loaded": len(STAFF_DIRECTORY),
+    }
+
+
+@router.get("/rag-status")
+async def rag_status():
+    try:
+        from app import rag_service
+        return rag_service.get_stats()
+    except Exception as e:
+        return {"error": str(e), "ready": False}

search.py

@@ -0,0 +1,374 @@
+"""
+search.py — LibBee v3
+Key fixes:
+- PRIMO: resource type (articles/books) sent as rtype FACET, not q= keyword
+- PRIMO: year filter sent as facet_searchcreationdate FACET, not keyword
+- PubMed: year filter wired to mindate/maxdate params (was silently ignored before)
+- PubMed: peer_reviewed mapped to free full text filter
+- query sent to both APIs is clean topic keywords only — no rtype noise
+"""
+import logging
+from typing import Optional
+from urllib.parse import quote
+
+import httpx
+from fastapi import APIRouter
+from pydantic import BaseModel, field_validator
+
+from src.config import get_settings
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+class SearchRequest(BaseModel):
+    query: str
+    source: str = "primo"
+    limit: int = 5
+    peer_reviewed: bool = False
+    open_access: bool = False
+    year_from: Optional[str] = None
+    year_to: Optional[str] = None
+    # resource_type controls rtype FACET — NOT injected into q= keyword query
+    resource_type: str = "articles"  # "articles" | "books" | "both"
+
+    @field_validator("query")
+    @classmethod
+    def query_not_empty(cls, v: str) -> str:
+        v = v.strip()
+        if not v:
+            raise ValueError("query must not be empty")
+        if len(v) > 500:
+            raise ValueError("query must be under 500 characters")
+        return v
+
+    @field_validator("limit")
+    @classmethod
+    def limit_in_range(cls, v: int) -> int:
+        if not 1 <= v <= 20:
+            raise ValueError("limit must be between 1 and 20")
+        return v
+
+    @field_validator("source")
+    @classmethod
+    def valid_source(cls, v: str) -> str:
+        allowed = {"primo", "pubmed", "scholar"}
+        if v not in allowed:
+            raise ValueError(f"source must be one of: {allowed}")
+        return v
+
+    @field_validator("resource_type")
+    @classmethod
+    def valid_resource_type(cls, v: str) -> str:
+        allowed = {"articles", "books", "both"}
+        if v not in allowed:
+            return "articles"
+        return v
+
+
+def _safe_metrics_increment(key: str) -> None:
+    try:
+        from app import metrics_service
+        metrics_service.incr(key)
+    except Exception:
+        return
+
+
+def _safe_metrics_bucket(bucket: str, key: str) -> None:
+    try:
+        from app import metrics_service
+        metrics_service.incr_bucket(bucket, key)
+    except Exception:
+        return
+
+
+@router.post("")
+async def search_endpoint(req: SearchRequest):
+    _safe_metrics_increment("search_requests")
+    _safe_metrics_bucket("search_sources", req.source)
+    settings = get_settings()
+    if req.source == "primo":
+        return await search_primo(req, settings.primo_api_key)
+    if req.source == "pubmed":
+        return await search_pubmed(req)
+    return await search_scholar(req)
+
+
+def _build_exact_primo_url(doc: dict, query_encoded: str) -> str:
+    pnx = doc.get("pnx", {}) or {}
+    control = pnx.get("control", {}) or {}
+    search = pnx.get("search", {}) or {}
+    recordid = ""
+    for candidate in [
+        control.get("recordid"),
+        control.get("sourcerecordid"),
+        search.get("recordid"),
+        search.get("addsrcrecordid"),
+    ]:
+        if isinstance(candidate, list) and candidate:
+            recordid = str(candidate[0]).strip()
+            if recordid:
+                break
+        elif isinstance(candidate, str) and candidate.strip():
+            recordid = candidate.strip()
+            break
+    if recordid:
+        return (
+            "https://khalifa.primo.exlibrisgroup.com/discovery/fulldisplay"
+            f"?docid={quote(recordid)}&context=L&vid=971KUOSTAR_INST:KU&lang=en"
+            f"&search_scope=MyInst_and_CI&tab=Everything&query=any,contains,{query_encoded}&offset=0"
+        )
+    return (
+        f"https://khalifa.primo.exlibrisgroup.com/discovery/search"
+        f"?query=any,contains,{query_encoded}&vid=971KUOSTAR_INST:KU"
+    )
+
+
+# ── PRIMO ──────────────────────────────────────────────────────────────────────
+
+async def search_primo(req: SearchRequest, api_key: str):
+    """
+    Send clean topic keywords to q=any,contains.
+    Resource type, peer review, open access, and year are all FACETS — never keywords.
+
+    PRIMO facet reference:
+        facet_rtype,include,articles   → journal articles
+        facet_rtype,include,books      → books / ebooks
+        facet_tlevel,include,peer_reviewed
+        facet_tlevel,include,online_resources  (open access proxy)
+        facet_searchcreationdate,include,YYYY|,|YYYY
+    """
+    if not api_key:
+        logger.warning("PRIMO_API_KEY not configured")
+        _safe_metrics_bucket("errors", "primo_missing_api_key")
+        return {"error": "PRIMO_API_KEY not configured", "results": [], "source": "PRIMO"}
+
+    # ── The query sent to PRIMO must be ONLY topic keywords ─────���────────────
+    # Strip any residual resource-type words that may have slipped through
+    # topic extraction (belt-and-braces defence).
+    clean_query = _strip_resource_noise(req.query)
+    if not clean_query:
+        clean_query = req.query  # fallback if stripping removes everything
+
+    query_encoded = quote(clean_query)
+
+    url = (
+        f"https://api-eu.hosted.exlibrisgroup.com/primo/v1/search"
+        f"?vid=971KUOSTAR_INST:KU&tab=Everything&scope=MyInst_and_CI"
+        f"&q=any,contains,{query_encoded}&lang=en&sort=rank&limit={req.limit}"
+        f"&offset=0&mode=advanced&apikey={api_key}"
+    )
+
+    # ── Build facets — resource type, quality, year ───────────────────────────
+    facets = []
+
+    # Resource type → rtype facet (NOT a keyword)
+    if req.resource_type == "articles":
+        facets.append("facet_rtype,include,articles")
+    elif req.resource_type == "books":
+        facets.append("facet_rtype,include,books")
+    # "both" → no rtype facet (search everything)
+
+    if req.peer_reviewed:
+        facets.append("facet_tlevel,include,peer_reviewed")
+
+    if req.open_access:
+        facets.append("facet_tlevel,include,online_resources")
+
+    if req.year_from or req.year_to:
+        yf = req.year_from or "0001"
+        yt = req.year_to or "9999"
+        facets.append(f"facet_searchcreationdate,include,{yf}|,|{yt}")
+
+    for facet in facets:
+        url += f"&multiFacets={quote(facet)}"
+
+    logger.info(
+        "PRIMO query=%r resource_type=%s peer_reviewed=%s year=%s-%s",
+        clean_query, req.resource_type, req.peer_reviewed, req.year_from, req.year_to,
+    )
+
+    try:
+        async with httpx.AsyncClient(timeout=20) as client:
+            r = await client.get(url, headers={"Accept": "application/json"})
+            logger.info("PRIMO status=%s", r.status_code)
+            if r.status_code != 200:
+                _safe_metrics_bucket("errors", f"primo_{r.status_code}")
+                return {"error": f"PRIMO API error: {r.status_code}", "results": [], "source": "PRIMO"}
+
+            data = r.json()
+            docs = data.get("docs", [])
+            results = []
+            for doc in docs[: req.limit]:
+                pnx = doc.get("pnx", {})
+                d = pnx.get("display", {})
+                results.append({
+                    "title": (d.get("title") or ["Untitled"])[0],
+                    "creator": "; ".join(d.get("creator") or d.get("contributor") or []) or "Unknown",
+                    "date": (d.get("date") or [""])[0],
+                    "type": (d.get("type") or [""])[0],
+                    "source": (d.get("source") or [""])[0],
+                    "primo_url": _build_exact_primo_url(doc, query_encoded),
+                    "_source": "PRIMO",
+                })
+            return {
+                "total": data.get("info", {}).get("total", 0),
+                "results": results,
+                "source": "PRIMO",
+            }
+
+    except httpx.TimeoutException:
+        _safe_metrics_bucket("errors", "primo_timeout")
+        return {"error": "PRIMO API timed out — please try again", "results": [], "source": "PRIMO"}
+    except Exception as exc:
+        logger.error("PRIMO search error: %s", exc, exc_info=True)
+        _safe_metrics_bucket("errors", "primo_exception")
+        return {"error": str(exc), "results": [], "source": "PRIMO"}
+
+
+def _strip_resource_noise(query: str) -> str:
+    """
+    Remove resource-type and filter words that should be facets, not q= keywords.
+    Called as a belt-and-braces guard before sending to PRIMO/PubMed.
+    """
+    noise = re.compile(
+        r"\b(articles?|papers?|books?|ebooks?|journals?|publications?|monographs?"
+        r"|peer[- ]reviewed|open[- ]access|studies|study|research)\b",
+        re.IGNORECASE,
+    )
+    cleaned = noise.sub(" ", query)
+    # Collapse leftover AND/OR operators with no operands
+    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 re.sub(r"\s+", " ", cleaned).strip()
+
+
+import re  # noqa: E402 (needed for _strip_resource_noise above)
+
+
+# ── PubMed ─────────────────────────────────────────────────────────────────────
+
+async def search_pubmed(req: SearchRequest):
+    """
+    Year filters use mindate/maxdate params — NOT injected into the search term.
+    Peer-reviewed filter uses [pt] (publication type) in the term.
+    """
+    # Build clean term — topic keywords only
+    clean_query = _strip_resource_noise(req.query)
+    if not clean_query:
+        clean_query = req.query
+
+    # Add peer-reviewed as a PubMed publication-type filter (appended to term)
+    term = clean_query
+    if req.peer_reviewed:
+        term = f"({term}) AND Journal Article[pt]"
+
+    query_encoded = quote(term)
+
+    # Date params (separate from search term — correct PubMed approach)
+    date_params = ""
+    if req.year_from or req.year_to:
+        yf = req.year_from or "1900"
+        yt = req.year_to or "3000"
+        date_params = f"&mindate={yf}&maxdate={yt}&datetype=pdat"
+
+    logger.info(
+        "PubMed term=%r peer_reviewed=%s year=%s-%s",
+        term, req.peer_reviewed, req.year_from, req.year_to,
+    )
+
+    try:
+        async with httpx.AsyncClient(timeout=15) as client:
+            search_url = (
+                f"https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi"
+                f"?db=pubmed&term={query_encoded}&retmax={req.limit}&retmode=json{date_params}"
+            )
+            r = await client.get(search_url)
+            if r.status_code != 200:
+                _safe_metrics_bucket("errors", "pubmed_search_failed")
+                return {"error": "PubMed search failed", "results": [], "source": "PubMed"}
+
+            ids = r.json().get("esearchresult", {}).get("idlist", [])
+            if not ids:
+                return {"total": 0, "results": [], "source": "PubMed"}
+
+            fetch_url = (
+                f"https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi"
+                f"?db=pubmed&id={','.join(ids)}&retmode=json"
+            )
+            r2 = await client.get(fetch_url)
+            if r2.status_code != 200:
+                _safe_metrics_bucket("errors", "pubmed_fetch_failed")
+                return {"error": "PubMed fetch failed", "results": [], "source": "PubMed"}
+
+            data = r2.json().get("result", {})
+            results = []
+            for pid in ids:
+                rec = data.get(pid, {})
+                if not isinstance(rec, dict):
+                    continue
+                author_list = rec.get("authors", [])
+                authors = ", ".join(a.get("name", "") for a in author_list[:3])
+                if len(author_list) > 3:
+                    authors += " et al."
+                results.append({
+                    "title": rec.get("title", ""),
+                    "creator": authors,
+                    "date": rec.get("pubdate", ""),
+                    "source": rec.get("fulljournalname", rec.get("source", "")),
+                    "pmid": pid,
+                    "link": f"https://pubmed.ncbi.nlm.nih.gov/{pid}/",
+                    "type": "Journal Article",
+                    "_source": "PubMed",
+                })
+            return {"total": len(ids), "results": results, "source": "PubMed"}
+
+    except Exception as exc:
+        logger.error("PubMed search error: %s", exc)
+        _safe_metrics_bucket("errors", "pubmed_exception")
+        return {"error": str(exc), "results": [], "source": "PubMed"}
+
+
+# ── Semantic Scholar ───────────────────────────────────────────────────────────
+
+async def search_scholar(req: SearchRequest):
+    try:
+        params = {
+            "query": req.query,
+            "limit": req.limit,
+            "fields": "title,authors,year,venue,externalIds,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:
+                _safe_metrics_bucket("errors", f"semantic_{r.status_code}")
+                return {"error": f"Semantic Scholar API: {r.status_code}", "results": [], "source": "Semantic Scholar"}
+
+            data = r.json()
+            results = []
+            for paper in data.get("data", []):
+                author_list = paper.get("authors") or []
+                authors = ", ".join(a.get("name", "") for a in author_list[:3])
+                if len(author_list) > 3:
+                    authors += " et al."
+                paper_id = paper.get("paperId")
+                results.append({
+                    "title": paper.get("title", ""),
+                    "creator": authors,
+                    "date": str(paper.get("year", "")),
+                    "source": paper.get("venue", ""),
+                    "citations": paper.get("citationCount", 0),
+                    "link": f"https://www.semanticscholar.org/paper/{paper_id}" if paper_id else "",
+                    "type": "Article",
+                    "_source": "Semantic Scholar",
+                })
+            return {"total": data.get("total", 0), "results": results, "source": "Semantic Scholar"}
+
+    except Exception as exc:
+        logger.error("Semantic Scholar search error: %s", exc)
+        _safe_metrics_bucket("errors", "semantic_exception")
+        return {"error": str(exc), "results": [], "source": "Semantic Scholar"}