Upload 5 files

src/api/__init__.py

@@ -1,3 +1,4 @@
+from . import admin
 from . import agent
+from . import feedback
 from . import search
-from . import admin

src/api/admin.py

@@ -1,121 +1,50 @@
-import logging
+from fastapi import APIRouter, HTTPException, Request, Response
+from pydantic import BaseModel
 import secrets
 import time
-from typing import Annotated
-
-from fastapi import APIRouter, Cookie, Depends, HTTPException, Request, Response
-from pydantic import BaseModel
-
-from src.config import get_settings
 
-logger = logging.getLogger(__name__)
 router = APIRouter()
 
-# In-memory session store — single instance on HF Spaces free tier
-# Resets on every container restart (expected behaviour)
-_admin_sessions: dict[str, float] = {}  # token → expiry timestamp
-
-
-# ── Auth Dependency ────────────────────────────────────────────────────────────
-
-def _cleanup_sessions():
-    """Evict expired tokens to prevent unbounded growth."""
-    now = time.time()
-    expired = [t for t, exp in _admin_sessions.items() if exp < now]
-    for t in expired:
-        del _admin_sessions[t]
-
-
-def require_admin(admin_session: Annotated[str | None, Cookie()] = None):
-    """FastAPI dependency — raises 401 if session is missing or expired."""
-    _cleanup_sessions()
-    if not admin_session or admin_session not in _admin_sessions:
-        raise HTTPException(status_code=401, detail="Not authenticated")
-    if _admin_sessions[admin_session] < time.time():
-        del _admin_sessions[admin_session]
-        raise HTTPException(status_code=401, detail="Session expired")
-
-
-# ── Request Models ─────────────────────────────────────────────────────────────
-
 class LoginRequest(BaseModel):
     password: str
 
-
 class ConfigUpdate(BaseModel):
     key: str
     value: str
 
-
-# ── Endpoints ──────────────────────────────────────────────────────────────────
+# Simple session storage (in-memory for HF single instance)
+admin_sessions = {}
 
 @router.post("/auth")
 async def admin_auth(req: LoginRequest):
+    from src.config import get_settings
     settings = get_settings()
-
-    if not settings.admin_password:
-        raise HTTPException(status_code=503, detail="Admin password not configured")
-
+    
     if req.password != settings.admin_password:
         raise HTTPException(status_code=401, detail="Invalid password")
-
+    
     token = secrets.token_hex(32)
-    _admin_sessions[token] = time.time() + 86400  # 24 hours
-
-    resp = Response(content='{"status": "ok"}', media_type="application/json")
-    resp.set_cookie(
-        key="admin_session",
-        value=token,
-        httponly=True,
-        secure=True,        # HTTPS only — HF Spaces always serves HTTPS
-        samesite="strict",
-        max_age=86400,
-    )
-    return resp
-
-
-@router.post("/logout")
-async def admin_logout(admin_session: Annotated[str | None, Cookie()] = None):
-    if admin_session and admin_session in _admin_sessions:
-        del _admin_sessions[admin_session]
-    resp = Response(content='{"status": "ok"}', media_type="application/json")
-    resp.delete_cookie("admin_session")
+    admin_sessions[token] = time.time() + 86400  # 24 hours
+    
+    resp = Response(content='{"status": "ok"}')
+    resp.set_cookie(key="admin_session", value=token, httponly=True, max_age=86400)
     return resp
 
-
-@router.get("/config", dependencies=[Depends(require_admin)])
+@router.get("/config")
 async def get_config():
+    from src.config import get_settings
     settings = get_settings()
     return {
         "max_results": settings.max_results,
-        "maintenance_mode": settings.maintenance_mode,
-        "environment": settings.environment,
+        "maintenance_mode": settings.maintenance_mode
     }
 
-
-@router.post("/config", dependencies=[Depends(require_admin)])
-async def update_config(req: ConfigUpdate):
-    # Runtime-only config update — does not persist across restarts.
-    # To persist, write to a file under /data (paid HF tier) or use an external store.
-    allowed_keys = {"maintenance_mode", "max_results"}
-    if req.key not in allowed_keys:
-        raise HTTPException(status_code=400, detail=f"Key '{req.key}' is not configurable at runtime")
-    # TODO: update a shared runtime config object here
-    logger.info(f"Admin config update: {req.key} = {req.value}")
-    return {"status": "ok", "updated": req.key, "note": "runtime only — resets on restart"}
-
-
-@router.get("/rag-status", dependencies=[Depends(require_admin)])
-async def rag_status():
-    """Admin view of RAG initialization state."""
-    try:
-        from app import rag_service
-        return rag_service.get_stats()
-    except Exception as e:
-        return {"error": str(e), "ready": False}
-
-
-@router.get("/sessions", dependencies=[Depends(require_admin)])
-async def session_info():
-    _cleanup_sessions()
-    return {"active_sessions": len(_admin_sessions)}
+@router.post("/config")
+async def update_config(req: ConfigUpdate, request: Request):
+    # Verify session
+    token = request.cookies.get("admin_session")
+    if not token or token not in admin_sessions:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+    
+    # In real implementation, update DB or env
+    return {"status": "ok", "updated": req.key}

src/api/agent.py

@@ -1,35 +1,64 @@
+import html
+import json
 import logging
-import time
 import re
-import json
-from typing import List, Optional, Dict, Tuple
+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
+from pydantic import BaseModel, ConfigDict, Field
 
 from src.config import get_settings
 from src.services.staff_service import (
-    match_staff_name, match_staff_role,
-    staff_name_answer, staff_role_answer,
     STAFF_DIRECTORY,
+    match_staff_name,
+    match_staff_role,
+    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"
+    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] = []
+    history: List[ChatMessage] = Field(default_factory=list)
+    client_state: Optional[ClientStatePayload] = None
 
 
 class AgentResponse(BaseModel):
@@ -37,9 +66,9 @@ class AgentResponse(BaseModel):
 
     answer: str
     intent: str = "general"
-    tools_used: List[str] = []
-    search_results: List[dict] = []
-    sources: List[dict] = []
+    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
@@ -47,13 +76,21 @@ class AgentResponse(BaseModel):
     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
 
 SOCIAL_RE = re.compile(
     r"^(hi|hello|hey|good morning|good afternoon|good evening|how are you|hows it going"
@@ -132,10 +169,11 @@ SUMMARY_RE = re.compile(
     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"
+    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,
 )
+
 MEDICAL_KEYWORDS = [
     "medicine", "medical", "health", "clinical", "nursing", "pharmacy", "biomedical",
     "anatomy", "physiology", "epidemiology", "oncology", "cardiology", "neuroscience",
@@ -147,172 +185,103 @@ MEDICAL_KEYWORDS = [
     "crispr", "gene therapy", "gene editing", "genomic medicine", "precision medicine",
 ]
 
-# ── Classifier Prompt ─────────────────────────────────────────────────────────
+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
+  \"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.
+  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".
+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.
+"""
+
+
+def _escape(text: str) -> str:
+    return html.escape(text or "")
 
-Examples:
-{"intent":"social","casual_answer":"Of course! I'm LibBee, the KU Library AI Assistant. What can I find for you?"}
-{"intent":"library_info"}
-{"intent":"search_academic"}
-{"intent":"search_medical"}
-{"intent":"general_recent"}
-{"intent":"general"}"""
 
+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(".?")
 
-# ── Source Badge ──────────────────────────────────────────────────────────────
 
 def _source_badge(source: str, url: str = "") -> str:
-    """
-    Returns a small HTML pill badge showing where the answer came from.
-    Appended to the end of every bot response.
-    """
     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"),
+        "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}'
+    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">'
-        f'{inner}</div>'
+        f'font-size:.72rem;font-weight:600;border:1px solid {fg}33">{inner}</div>'
     )
 
 
-# ── Helper Functions ───────────────────────────────────────────────────────────
-
-def _is_summary_request(question: str) -> bool:
-    return bool(SUMMARY_RE.search(question))
-
-
-def _extract_topic_regex(question: str) -> str:
-    """Regex-based topic extraction — fast fallback."""
-    q = question.strip()
-    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 ", "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 articles on ", "find papers on ", "find books on ",
-        "find articles about ", "find papers about ",
-        "search for articles on ", "search for papers on ",
-        "i need articles on ", "i need papers on ", "i need books on ",
-        "give me articles on ", "show me articles on ",
-        "get me articles on ", "look for articles on ",
-        "articles on ", "papers on ", "books on ",
-        "research on ", "literature on ",
-        "find ", "search for ", "i need ", "give me ",
-        "show me ", "get me ",
-    ]
-    lower = q.lower()
-    for prefix in prefixes:
-        if lower.startswith(prefix):
-            q = q[len(prefix):]
-            break
-    q = re.sub(r'\s+(please|thanks|thank you)\.?$', '', q, flags=re.IGNORECASE)
-    return q.strip()
-
-
-async def _extract_topic(question: str, model: str) -> str:
-    """
-    LLM-based topic extraction for messy natural language queries.
-    Falls back to regex if LLM unavailable.
-    Always returns clean 2-5 keyword search terms.
-    """
-    settings = get_settings()
-    if not settings.openai_api_key:
-        return _extract_topic_regex(question)
+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
 
-    try:
-        llm = _get_llm(model, temperature=0, max_tokens=30)
-        response = await llm.ainvoke([
-            {"role": "system", "content": (
-                "Extract only the core research topic from the user's question. "
-                "Return 2-5 keywords ONLY. No sentences, no punctuation, no explanation.\n"
-                "Examples:\n"
-                "'can u give me a deep analysis of quantum physics advancement in recent years' "
-                "→ quantum physics advances\n"
-                "'summarize recent research on machine learning in healthcare' "
-                "→ machine learning healthcare\n"
-                "'find articles on the impact of climate change on biodiversity' "
-                "→ climate change biodiversity\n"
-                "'give me an overview of CRISPR gene editing' "
-                "→ CRISPR gene editing\n"
-                "'i need books on structural engineering UAE' "
-                "→ structural engineering UAE"
-            )},
-            {"role": "user", "content": question},
-        ])
-        topic = response.content.strip().strip('"').strip("'").strip(".")
-        if topic and len(topic) > 2:
-            logger.info(f"LLM topic: '{topic}' ← '{question[:60]}'")
-            return topic
-    except Exception as e:
-        logger.warning(f"LLM topic extraction failed: {e}")
 
-    return _extract_topic_regex(question)
+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.strip()):
+    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 <strong>libbee</strong>" in last or "are you looking for one of these" in last
+            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.strip().lower()
+    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",
@@ -323,23 +292,24 @@ def _looks_library_hours_question(question: str) -> bool:
 
 
 def _looks_campus_question(question: str) -> bool:
-    return bool(KU_CAMPUS_RE.search(question))
+    return bool(KU_CAMPUS_RE.search(question or ""))
 
 
 def _looks_medical_search(question: str) -> bool:
-    q = question.lower()
+    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))
+    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:
-    return bool(RESEARCH_CUE_RE.search(question.lower()))
+    q = question or ""
+    return bool(RESEARCH_CUE_RE.search(q) or SUMMARY_RE.search(q))
 
 
-def _rule_based_classify(question: str) -> Dict:
-    q = question.lower()
-    if SOCIAL_RE.match(question.strip()):
+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": (
@@ -350,7 +320,7 @@ def _rule_based_classify(question: str) -> Dict:
         }
     if _looks_medical_search(question):
         return {"intent": "search_medical"}
-    if _looks_research_question(question) or _is_summary_request(question):
+    if _looks_research_question(question):
         return {"intent": "search_academic"}
     if LIBRARY_CUE_RE.search(q):
         return {"intent": "library_info"}
@@ -384,7 +354,7 @@ def _campus_answer() -> str:
         '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>"
-        'For general library enquiries: <a href="https://library.ku.ac.ae/AskUs" target="_blank">Ask a Librarian</a> '
+        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>.'
     )
 
@@ -401,8 +371,6 @@ def _greeting_menu_clarify_answer() -> str:
     )
 
 
-# ── LLM Helpers ───────────────────────────────────────────────────────────────
-
 def _get_llm(model: str, temperature: float, max_tokens: int):
     settings = get_settings()
     if model == "claude" and settings.anthropic_api_key:
@@ -422,15 +390,7 @@ def _get_llm(model: str, temperature: float, max_tokens: int):
     )
 
 
-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
-
-
-async def _llm_classify(question: str, history: List[ChatMessage], model: str) -> Dict:
+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)
@@ -442,40 +402,32 @@ async def _llm_classify(question: str, history: List[ChatMessage], model: str) -
             if m.role in ("user", "assistant")
         ]
         ctx = " | ".join(ctx_parts) if ctx_parts else "none"
-        user_msg = f"Message: {question[:400]}\nContext: {ctx}\nJSON:"
-
-        llm = _get_llm(model, temperature=0, max_tokens=150)
+        llm = _get_llm(model, temperature=0, max_tokens=120)
         response = await llm.ainvoke([
             {"role": "system", "content": _CLASSIFIER_SYSTEM},
-            {"role": "user", "content": user_msg},
+            {"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()) > 25:
+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=200)
+        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. "
@@ -489,9 +441,7 @@ async def _libbee_casual_response(
         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:
+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 ""
@@ -501,13 +451,12 @@ async def _rag_answer(
         "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. "
-        "If the context does not contain enough information, say so and suggest "
-        "Ask a Librarian at https://library.ku.ac.ae/AskUs. "
+        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=400)
+        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})
@@ -516,35 +465,52 @@ async def _rag_answer(
     except Exception as e:
         logger.error(f"_rag_answer error: {e}")
         return (
-            "I'm having trouble generating an answer. Please try "
-            '<a href="https://library.ku.ac.ae/AskUs" target="_blank">Ask a Librarian</a>.'
+            "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 _web_search_answer(
-    question: str, history: List[ChatMessage], model: str
-) -> str:
-    """Web search — Claude tool or GPT Responses API. Falls back to LLM knowledge."""
+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=600,
+                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. KU = Khalifa University."
+                    "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")
-            )
+            text = "".join(block.text for block in response.content if hasattr(block, "text"))
             if text.strip():
                 return text.strip()
         except Exception as e:
@@ -559,8 +525,7 @@ async def _web_search_answer(
                 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. KU = Khalifa University."
+                    "Answer using current web search. Be concise and factual. Use HTML <br> for line breaks."
                 ),
                 input=question,
             )
@@ -578,88 +543,314 @@ async def _web_search_answer(
     return await _llm_general_answer(question, history, model)
 
 
-async def _llm_general_answer(
-    question: str, history: List[ChatMessage], model: str
-) -> str:
+def _extract_topic_regex(question: str) -> str:
+    q = _normalize_whitespace(question)
+    prefixes = [
+        "can u give me a deep analysis of ", "can you give me a deep analysis of ",
+        "give me a deep analysis of ", "deep analysis of ",
+        "give me a summary of ", "give me a summary on ", "give me a summary about ",
+        "give me an overview of ", "give me an overview on ",
+        "give me a brief overview of ", "give me a brief summary of ",
+        "summarize ", "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 articles on ", "find papers on ", "find books on ", "find articles about ",
+        "find papers about ", "search for articles on ", "search for papers on ",
+        "i need articles on ", "i need papers on ", "i need books on ",
+        "give me articles on ", "show me articles on ", "get me articles on ",
+        "look for articles on ", "articles on ", "papers on ", "books on ",
+        "research on ", "literature on ", "find ", "search for ", "i need ",
+        "give me ", "show me ", "get me ",
+    ]
+    lower = q.lower()
+    for prefix in prefixes:
+        if lower.startswith(prefix):
+            q = q[len(prefix):]
+            break
+    q = re.sub(r"\s+(please|thanks|thank you)\.?$", "", q, flags=re.IGNORECASE)
+    q = re.sub(r"\b(peer[- ]reviewed|open access|last \d+ years?|past \d+ years?)\b", "", q, flags=re.IGNORECASE)
+    return _normalize_whitespace(q).strip(".?")
+
+
+async def _extract_topic(question: str, 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 questions 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 = Khalifa University. If topic is academic, briefly offer to find library resources."
-    )
+        return _extract_topic_regex(question)
     try:
-        llm = _get_llm(model, temperature=0.3, max_tokens=400)
-        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()
+        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 sentence, no punctuation, no explanation."
+            )},
+            {"role": "user", "content": question},
+        ])
+        topic = response.content.strip().strip('"').strip("'").strip(".")
+        return topic if topic else _extract_topic_regex(question)
     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>.'
+        logger.warning(f"Topic extraction failed: {e}")
+        return _extract_topic_regex(question)
 
 
-# ── PRIMO Search ──────────────────────────────────────────────────────────────
+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(topic: str) -> str:
+    text = _normalize_whitespace(topic)
+    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",
+    }
+    words = re.sub(r"[^\w\s-]", " ", text).split()
+    concepts: List[str] = []
+    phrase: List[str] = []
+    for word in words:
+        cleaned = word.strip("-")
+        if cleaned and cleaned.lower() not in stop and len(cleaned) > 2:
+            phrase.append(cleaned)
+        else:
+            if phrase:
+                concepts.append(" ".join(phrase))
+                phrase = []
+    if phrase:
+        concepts.append(" ".join(phrase))
+    concepts = concepts[:4]
+    if len(concepts) >= 2:
+        return " AND ".join(f'\"{c}\"' for c in concepts)
+    if len(concepts) == 1:
+        return f'\"{concepts[0]}\"'
+    return f'\"{text}\"'
+
+
+def _primo_url_from_boolean(boolean_query: str) -> str:
+    safe = re.sub(r"\s+", " ", boolean_query or "").strip()
+    return f"{PRIMO_BASE_URL}&query=any,contains,{quote(safe)}&lang=en&mode=advanced&offset=0"
+
+
+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
+
+
+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 _compose_ai_tool_query(question: str, context: SearchContextPayload, is_follow_up: bool) -> str:
+    topic = context.display_topic or context.topic
+    topic = _title_case_topic(topic)
+    scope = context.resource_type
+    filters = []
+    if context.peer_reviewed:
+        filters.append("peer-reviewed")
+    if context.open_access:
+        filters.append("open-access")
+    if context.year_from and context.year_to:
+        filters.append(f"published between {context.year_from} and {context.year_to}")
+    elif context.year_from:
+        filters.append(f"published from {context.year_from} onward")
+
+    if is_follow_up:
+        if scope == "books":
+            base = f"Find books on {topic}"
+        elif scope == "both":
+            base = f"Find articles and books on {topic}"
+        else:
+            base = f"Find research articles on {topic}"
+    else:
+        base = _normalize_whitespace(question).strip(".?")
+        if len(base.split()) < 4:
+            base = f"Find research on {topic}"
 
-async def _primo_inline_search(topic: str, limit: int = 5) -> List[dict]:
-    """Search PRIMO — API key as URL param (Ex Libris requirement)."""
-    settings = get_settings()
-    if not settings.primo_api_key:
-        logger.warning("PRIMO_API_KEY not set")
-        return []
+    if filters:
+        return f"{base} with {', '.join(filters)}."
+    return base.rstrip(".") + "."
 
-    query_encoded = quote(topic)
-    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"
-        f"&limit={limit}&offset=0&mode=advanced"
-        f"&apikey={settings.primo_api_key}"
-    )
 
+async def _grammar_refine_query(text: str, model: str) -> str:
+    settings = get_settings()
+    if not settings.openai_api_key:
+        return _normalize_whitespace(text)
     try:
-        async with httpx.AsyncClient(timeout=15) as client:
-            r = await client.get(url, headers={"Accept": "application/json"})
-            if r.status_code != 200:
-                logger.warning(f"PRIMO {r.status_code} for '{topic}'")
-                return []
-            data = r.json()
-            results = []
-            for doc in data.get("docs", [])[: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": (
-                        f"https://khalifa.primo.exlibrisgroup.com/discovery/search"
-                        f"?query=any,contains,{query_encoded}&vid=971KUOSTAR_INST:KU"
-                    ),
-                    "_source": "PRIMO",
-                })
-            logger.info(f"PRIMO: {len(results)} results for '{topic}'")
-            return results
-    except Exception as e:
-        logger.error(f"PRIMO search failed: {e}")
-        return []
+        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:
+    natural = _compose_ai_tool_query(question, context, is_follow_up)
+    natural = await _grammar_refine_query(natural, model)
+    context.ai_tool_query = natural
+    context.primo_boolean_query = _make_primo_boolean(context.topic)
+    return context
 
-# ── Semantic Scholar Search ───────────────────────────────────────────────────
 
 async def _semantic_scholar_search(topic: str, limit: int = 8) -> List[dict]:
-    """
-    Search Semantic Scholar for papers WITH abstracts.
-    Used for summary generation — abstracts enable real in-text citations.
-    Free API, no key required.
-    """
     try:
         params = {
             "query": topic,
@@ -667,279 +858,381 @@ async def _semantic_scholar_search(topic: str, limit: int = 8) -> List[dict]:
             "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,
-            )
+            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 '{topic}'")
                 return []
-
             data = r.json()
             results = []
             for paper in data.get("data", []):
                 abstract = paper.get("abstract") or ""
                 if not abstract:
-                    continue  # skip papers without abstracts
-
+                    continue
                 author_list = paper.get("authors") or []
-                first_author_last = (
-                    author_list[0].get("name", "Unknown").split()[-1]
-                    if author_list else "Unknown"
-                )
+                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 "#")
-                )
-
+                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 "")
-                    ),
+                    "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[:600],
+                    "abstract": abstract[:700],
                     "link": link,
                     "_source": "Semantic Scholar",
                 })
-
-            logger.info(f"Semantic Scholar: {len(results)} papers with abstracts for '{topic}'")
             return results
-
     except Exception as e:
         logger.error(f"Semantic Scholar search failed: {e}")
         return []
 
 
-# ── Cited Summary Generation ──────────────────────────────────────────────────
-
-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 citation links to the actual paper.
-    Grounded only in the abstracts provided — no hallucination.
-    """
+async def _generate_cited_summary(topic: str, papers: List[dict], model: str) -> str:
     settings = get_settings()
     if not settings.openai_api_key or not papers:
         return ""
 
-    # Build numbered reference context for LLM
     context = ""
-    for i, p in enumerate(papers, 1):
-        context += (
-            f"[{i}] {p['citation_key']}: {p['title']}\n"
-            f"Abstract: {p['abstract']}\n\n"
-        )
+    for i, paper in enumerate(papers, 1):
+        context += f"[{i}] {paper['citation_key']}: {paper['title']}\nAbstract: {paper['abstract']}\n\n"
 
     system = (
-        "You are a research librarian writing an academic literature summary. "
-        "Using ONLY the numbered references provided, write a 4-6 sentence "
-        "research 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 throughout the summary. "
-        "Use HTML <br><br> to separate paragraphs. No bullet points, no markdown headers. "
-        "Only state what is explicitly supported by the abstracts. "
-        "Do NOT invent content beyond what the abstracts say."
-    )
-
-    user_msg = (
-        f"Topic: {topic}\n\n"
-        f"References:\n{context}\n"
-        f"Write a cited research summary on '{topic}'."
+        "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. Cite at least 4 references. "
+        "Use HTML <br><br> for paragraph breaks. Do not invent facts."
     )
 
     try:
-        llm = _get_llm(model, temperature=0.2, max_tokens=600)
+        llm = _get_llm(model, temperature=0.2, max_tokens=560)
         response = await llm.ainvoke([
             {"role": "system", "content": system},
-            {"role": "user", "content": user_msg},
+            {"role": "user", "content": f"Topic: {topic}\n\nReferences:\n{context}\nWrite the summary."},
         ])
-        summary_text = response.content.strip()
-
-        # Replace [N] with clickable citation links
-        for i, p in enumerate(papers, 1):
-            link = p.get("link", "#")
-            title_escaped = p["title"].replace('"', "&quot;")
+        summary = response.content.strip()
+        for i, paper in enumerate(papers, 1):
+            title_escaped = _escape(paper["title"])
             cite_html = (
-                f'<a href="{link}" target="_blank" '
-                f'title="{title_escaped}" '
-                f'style="color:#1e40af;font-weight:600;text-decoration:none">'
-                f'[{p["citation_key"]}]</a>'
+                f'<a href="{paper["link"]}" target="_blank" title="{title_escaped}" '
+                f'style="color:#1e40af;font-weight:600;text-decoration:none">[{paper["citation_key"]}]</a>'
             )
-            summary_text = summary_text.replace(f"[{i}]", cite_html)
-
-        return summary_text
-
+            summary = summary.replace(f"[{i}]", cite_html)
+        return summary
     except Exception as e:
         logger.error(f"Summary generation failed: {e}")
         return ""
 
 
-# ── Research Summary (Semantic Scholar → cited summary) ───────────────────────
+from src.api.search import SearchRequest, search_primo, search_pubmed
 
-async def _research_summary(
-    topic: str, history: List[ChatMessage], model: str
-) -> Tuple[str, List[dict]]:
-    """
-    1. Search Semantic Scholar for papers with abstracts
-    2. Generate LLM summary with clickable in-text citations
-    3. Show numbered reference list with links
-    Falls back to PRIMO list if Semantic Scholar returns nothing.
-    Returns (answer_html, search_results_for_frontend).
-    """
-    # Try Semantic Scholar first (has abstracts)
-    papers = await _semantic_scholar_search(topic, limit=8)
 
-    if papers:
-        summary = await _generate_cited_summary(topic, papers, model)
+async def _search_primo_catalog(context: SearchContextPayload, limit: int = 5) -> Tuple[dict, str]:
+    settings = get_settings()
+    query = context.topic
+    result = await search_primo(
+        SearchRequest(
+            query=query,
+            source="primo",
+            limit=limit,
+            peer_reviewed=context.peer_reviewed,
+            open_access=context.open_access,
+            year_from=context.year_from,
+            year_to=context.year_to,
+        ),
+        settings.primo_api_key,
+    )
+    source_url = _primo_url_from_boolean(context.primo_boolean_query or _make_primo_boolean(context.topic))
+    return result, source_url
+
+
+async def _search_pubmed_articles(context: SearchContextPayload, limit: int = 5) -> Tuple[dict, str]:
+    query = context.topic
+    result = await search_pubmed(
+        SearchRequest(
+            query=query,
+            source="pubmed",
+            limit=limit,
+            year_from=context.year_from,
+            year_to=context.year_to,
+        )
+    )
+    pubmed_url = f"https://pubmed.ncbi.nlm.nih.gov/?term={quote(query)}"
+    return result, pubmed_url
 
-        if not summary:
-            summary = f"Here are key academic resources on <strong>{topic}</strong>:"
 
-        answer = (
-            f"<strong>📖 Research Summary: {topic}</strong><br><br>"
-            f"{summary}<br><br>"
-            f"<strong>📚 References ({len(papers)} papers):</strong><br>"
+def _database_guidance_for_topic(context: SearchContextPayload) -> str:
+    topic = _escape(context.display_topic or context.topic)
+    if context.intent == "search_medical":
+        return (
+            f"For a fuller research workflow on <strong>{topic}</strong>, start with <strong>PubMed</strong> for biomedical coverage, "
+            "then use <strong>EBSCO Research AI</strong> or <strong>Scopus AI</strong> to expand the evidence map. "
+            "For KU-accessible full text, continue in <strong>PRIMO AI</strong>."
         )
+    return (
+        f"For deeper work on <strong>{topic}</strong>, use <strong>Scopus AI</strong> for broad scholarly mapping, "
+        "<strong>EBSCO Research AI</strong> for AI-assisted database discovery, and <strong>PRIMO AI</strong> for KU-accessible resources. "
+        "If you want a more agentic literature exploration workflow, continue in <strong>LeapSpace</strong> or another deep-research tool from the library guide."
+    )
 
-        for i, p in enumerate(papers, 1):
-            safe_title = p["title"].replace("<", "&lt;").replace(">", "&gt;")
+
+async def _research_snapshot(context: SearchContextPayload, model: str) -> Tuple[str, List[dict], List[dict]]:
+    topic = context.topic
+    papers = await _semantic_scholar_search(topic, limit=8)
+    references: List[dict] = []
+
+    if papers:
+        summary = await _generate_cited_summary(topic, papers, model)
+        if not summary:
+            summary = f"Here is a concise research snapshot on <strong>{_escape(topic)}</strong>."
+        answer = f"<strong>📖 Research Snapshot: {_escape(topic)}</strong><br><br>{summary}"
+        answer += f"<br><br><strong>Research guide:</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="{p["link"]}" target="_blank" '
-                f'style="color:#003366;font-weight:600">{safe_title}</a><br>'
-                f'<span style="font-size:.8rem;color:#6b7280">'
-                f'{p["authors"]} · {p["year"]} · {p["venue"]}'
-                f'</span>'
+                f'<br><strong>[{i}]</strong> <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">{_escape(paper["authors"])} · {paper["year"]} · {_escape(paper["venue"])}</span>'
             )
+        answer += _source_badge("semantic", "https://www.semanticscholar.org/")
+        references = [{"title": p["title"], "url": p["link"]} for p in papers[:6]]
+        return answer, [], references
 
+    result, source_url = await _search_primo_catalog(context, limit=6)
+    search_results = result.get("results", []) or []
+    if search_results:
+        answer = (
+            f"<strong>📚 KU Library starting points on {_escape(topic)}</strong><br><br>"
+            "I couldn't build a cited abstract summary right now, so I've pulled KU Library results you can open immediately. "
+            f"<br><br><strong>Research guide:</strong> {_database_guidance_for_topic(context)}"
+        )
+    else:
+        answer = (
+            f"I couldn't retrieve results for <strong>{_escape(topic)}</strong> right now.<br><br>"
+            f"<strong>Research guide:</strong> {_database_guidance_for_topic(context)}"
+        )
+    answer += _source_badge("primo", source_url)
+    return answer, search_results, []
+
+
+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>💡 Want me to:<br>"
-            "• Also search the <strong>KU Library catalogue</strong> (PRIMO) for physical access?<br>"
-            "• Narrow to <strong>peer reviewed</strong> or a specific <strong>year range</strong>?<br>"
-            "Just tell me!"
+            "<br><br>I couldn't retrieve matching results right now. "
+            "You can still try the direct library links and AI research tools below."
         )
-        answer += _source_badge("semantic", "https://www.semanticscholar.org/")
 
-        # Return empty list — references already in answer HTML, avoid double render
-        return answer, []
+    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
 
-    # Fallback: PRIMO list (no abstracts, no cited summary)
-    logger.info(f"Semantic Scholar returned nothing for '{topic}' — falling back to PRIMO")
-    primo_results = await _primo_inline_search(topic, limit=8)
 
-    if not primo_results:
-        primo_url = (
-            f"https://khalifa.primo.exlibrisgroup.com/discovery/search"
-            f"?query=any,contains,{quote(topic)}&vid=971KUOSTAR_INST:KU"
+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, or should I show you how to check the live hours page for updates?",
+            [
+                {"label": "Show the library contact details", "question": "Show the library contact details"},
+                {"label": "Open the live library hours page", "question": "Open the live library hours page"},
+            ],
         )
-        answer = (
-            f"I couldn't find academic resources on <em>{topic}</em> right now.<br><br>"
-            f'Try searching directly in <a href="{primo_url}" target="_blank">PRIMO</a>.'
+    if "study room" in q or "room" in q:
+        return (
+            "Would you like the study-room booking link, or the general library services for both campuses?",
+            [
+                {"label": "Show the study-room booking link", "question": "Show the study-room booking link"},
+                {"label": "Show library services for both campuses", "question": "Show library services for both campuses"},
+            ],
         )
-        answer += _source_badge("primo", primo_url)
-        return answer, []
-
-    answer = f"<strong>📚 Resources on <em>{topic}</em> from KU Library catalogue:</strong><br>"
-    for i, r in enumerate(primo_results, 1):
-        safe = r["title"].replace("<", "&lt;").replace(">", "&gt;")
-        answer += (
-            f'<br><strong>{i}.</strong> '
-            f'<a href="{r["primo_url"]}" target="_blank" '
-            f'style="color:#003366;font-weight:600">{safe}</a><br>'
-            f'<span style="font-size:.8rem;color:#6b7280">'
-            f'{r["creator"]} · {r["date"]}'
-            f'</span>'
+    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, or show how to access them off campus?",
+            [
+                {"label": "Recommend the best KU databases for this topic", "question": "Recommend the best KU databases for this topic"},
+                {"label": "How do I access databases off campus?", "question": "How do I access databases off campus?"},
+            ],
         )
-    answer += (
-        "<br><br>💡 Want a deeper summary? "
-        "Ask me to <strong>summarize</strong> this topic and I'll use academic abstracts."
+    return (
+        "Would you like a related library service, a staff contact, or the direct KU page for this topic?",
+        [
+            {"label": "Show the best staff contact", "question": "Show the best staff contact for this"},
+            {"label": "Open the KU library page for this topic", "question": "Open the KU library page for this topic"},
+        ],
     )
-    answer += _source_badge("primo", "https://khalifa.primo.exlibrisgroup.com/")
 
-    # Return results for frontend card rendering
-    return answer, primo_results
 
+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": "Give me a shorter explanation", "question": f"Give me a shorter explanation of {question}"},
+            {"label": "Show current web information", "question": f"Show current web information on {question}"},
+            {"label": "Find KU Library resources on this topic", "question": f"Find KU Library resources on {question}"},
+        ],
+    )
+
+
+def _search_follow_up(context: SearchContextPayload, summary_mode: bool = False) -> Tuple[str, List[dict]]:
+    topic = context.display_topic or context.topic
+    suggestions: List[dict] = []
+    question: str
+
+    if summary_mode:
+        question = f"Would you like me to search KU-accessible sources on {topic}, narrow the snapshot, or point you to the best deep-research tool?"
+        suggestions.append({"label": f"Search KU-accessible articles on {topic}", "question": f"Find articles on {topic}", "action": "articles_only", "context_id": context.context_id})
+        suggestions.append({"label": f"Narrow {topic} to the last 5 years", "question": f"Limit {topic} to the last 5 years", "action": "last_5_years", "context_id": context.context_id})
+        suggestions.append({"label": f"Which deep-research tool is best for {topic}?", "question": f"Which deep-research tool is best for {topic}?", "action": "deep_research_tools", "context_id": context.context_id})
+        return question, suggestions
+
+    question = f"Would you like me to refine the {topic} search, switch source, or turn it into a short research snapshot?"
+    if not context.peer_reviewed and context.source == "primo":
+        suggestions.append({"label": f"Make the {topic} search 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)):
+        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})
+    if context.resource_type != "books":
+        suggestions.append({"label": f"Show books on {topic}", "question": f"Show books on {topic}", "action": "books_only", "context_id": context.context_id})
+    if context.intent == "search_medical" and context.source != "pubmed":
+        suggestions.append({"label": f"Search PubMed for {topic}", "question": f"Search PubMed for {topic}", "action": "search_pubmed", "context_id": context.context_id})
+    suggestions.append({"label": f"Give me a brief research snapshot on {topic}", "question": f"Give me a brief research snapshot on {topic}", "action": "summarize_topic", "context_id": context.context_id})
+    return question, suggestions[:4]
+
+
+def _social_follow_up() -> Tuple[str, List[dict]]:
+    return (
+        "What would you like help with next — finding articles, checking a library service, or contacting a librarian?",
+        [
+            {"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 _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 = req.question.strip()
+    question = _normalize_whitespace(req.question)
     history = req.history
     model = req.model
+    client_state = req.client_state
 
     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!",
+            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,
         )
 
-    # ── LAYER 0: Instant rule-based handlers ─────────────────────────────
-
-    # 1. Pure greeting
     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.<br><br>"
-                "Are you looking for one of these? You can also type your question directly."
+                "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,
         )
 
-    # 2. Staff name match
     staff_match = match_staff_name(question)
     if staff_match:
+        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,
         )
 
-    # 3. Staff role match
     staff_role_match = match_staff_role(question)
     if staff_role_match:
+        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,
         )
 
-    # 4. Greeting menu followup
     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,
         )
 
-    # 5. Library hours
     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",
@@ -947,10 +1240,12 @@ async def agent_query(request: Request, req: AgentRequest):
             ask_librarian=False,
             model_used=model,
             response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
         )
 
-    # 6. Campus/location
     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",
@@ -958,28 +1253,88 @@ async def agent_query(request: Request, req: AgentRequest):
             ask_librarian=False,
             model_used=model,
             response_time=time.time() - start_time,
+            follow_up_question=follow_up_question,
+            follow_up_suggestions=follow_up_suggestions,
         )
 
-    # ── LAYER 1: LLM Classification ────────────────────────────────────────
+    is_follow_up, follow_up_action, base_context = _detect_follow_up(question, client_state)
+
+    if is_follow_up and base_context:
+        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)
+            answer = (
+                f"<strong>Research guide for {_escape(context.display_topic or context.topic)}</strong><br><br>"
+                f"{_database_guidance_for_topic(context)}"
+            )
+            if follow_up_action == "summarize_topic":
+                snapshot_answer, search_results, sources = await _research_snapshot(context, model)
+                answer = snapshot_answer
+            else:
+                answer += _source_badge("libbee")
+                search_results = []
+                sources = []
+            follow_up_question, follow_up_suggestions = _search_follow_up(context, summary_mode=True)
+            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_url_from_boolean(context.primo_boolean_query or _make_primo_boolean(context.topic)),
+                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 = _search_follow_up(context)
+        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")
     casual_hint = cls_result.get("casual_answer", "")
 
-    # ── LAYER 2: Intent Handlers ───────────────��───────────────────────────
-
     if intent == "social":
-        answer = casual_hint if (casual_hint and len(casual_hint.strip()) > 25) else \
-                 await _libbee_casual_response(question, history, model, casual_hint)
+        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,
         )
 
-    elif intent == "library_info":
+    if intent == "library_info":
         try:
             from app import rag_service
             rag_results = await rag_service.hybrid_search(question, top_k=4)
@@ -992,20 +1347,18 @@ async def agent_query(request: Request, req: AgentRequest):
                 "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>'
-                '🔗 <a href="https://library.ku.ac.ae/AskUs" target="_blank">Ask a Librarian</a>'
+                f'🔗 <a href="{ASK_LIBRARIAN_URL}" target="_blank">Ask a Librarian</a>'
             )
-            answer += _source_badge("ku_library", "https://library.ku.ac.ae/AskUs")
-            tools_used = ["rag_no_results"]
+            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"]
-            sources = [
-                {"title": r["title"], "url": r["source"]}
-                for r in rag_results if r.get("source")
-            ]
 
+        follow_up_question, follow_up_suggestions = _library_follow_up(question)
         return AgentResponse(
             answer=answer,
             intent="library_info",
@@ -1014,86 +1367,101 @@ async def agent_query(request: Request, req: AgentRequest):
             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,
         )
 
-    elif intent in ("search_academic", "search_medical"):
-        # Step 1: extract clean topic using LLM
+    if intent in ("search_academic", "search_medical"):
         topic = await _extract_topic(question, model)
-        is_summary = _is_summary_request(question)
-        is_medical = intent == "search_medical"
-
-        if is_summary:
-            # SUMMARY MODE → Semantic Scholar + cited summary
-            answer, search_results = await _research_summary(topic, history, model)
-            tools_used = ["semantic_scholar_summary"]
-        else:
-            # FIND MODE → PRIMO inline results
-            search_results = await _primo_inline_search(topic, limit=5)
+        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,
+        )
 
-            if search_results:
-                answer = f"<strong>📚 Resources on <em>{topic}</em> from the KU Library catalogue:</strong>"
-            else:
-                primo_url = (
-                    f"https://khalifa.primo.exlibrisgroup.com/discovery/search"
-                    f"?query=any,contains,{quote(topic)}&vid=971KUOSTAR_INST:KU"
-                )
-                answer = (
-                    f"I didn't find results for <em>{topic}</em> in the KU catalogue right now. "
-                    f'Try searching directly in <a href="{primo_url}" target="_blank">PRIMO</a>.'
-                )
-
-            pubmed_offer = (
-                "<br>• 🏥 <strong>Search PubMed</strong> for medical/clinical literature?"
-                if is_medical else ""
-            )
-            answer += (
-                "<br><br>💡 <strong>Want me to refine this?</strong><br>"
-                "• Narrow to <strong>peer reviewed</strong> only?<br>"
-                "• Limit to a specific <strong>year range</strong>?<br>"
-                "• Find <strong>books</strong> instead?"
-                "• Ask for a <strong>summary</strong> of this topic with cited papers?"
-                + pubmed_offer +
-                "<br><br>Just tell me what you need!"
+        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 = _search_follow_up(context, summary_mode=True)
+            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_url_from_boolean(context.primo_boolean_query or _make_primo_boolean(context.topic)),
+                follow_up_question=follow_up_question,
+                follow_up_suggestions=follow_up_suggestions,
+                search_context=_context_to_dict(context),
             )
-            answer += _source_badge("primo", "https://khalifa.primo.exlibrisgroup.com/")
-            tools_used = ["primo_inline"]
 
+        answer, search_results, sources, source_url = await _run_search_mode(question, context, model, False)
+        follow_up_question, follow_up_suggestions = _search_follow_up(context)
         return AgentResponse(
             answer=answer,
             intent=intent,
-            tools_used=tools_used,
+            tools_used=["primo_inline" if context.source == "primo" else "pubmed_inline"],
             search_results=search_results,
-            corrected_query=topic,
-            natural_query=topic,
-            database_query=topic,
+            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),
         )
 
-    elif intent == "general_recent":
-        answer = await _web_search_answer(question, history, model)
-        answer += _source_badge("web_live")
+    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,
         )
 
-    else:  # general
-        answer = await _web_search_answer(question, history, model)
-        answer += _source_badge("web")
-        return AgentResponse(
-            answer=answer,
-            intent="general",
-            tools_used=["web_search"],
-            model_used=model,
-            response_time=time.time() - start_time,
-        )
-
+    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():

src/api/feedback.py

@@ -0,0 +1,31 @@
+import time
+from typing import List
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+router = APIRouter()
+
+
+class FeedbackRequest(BaseModel):
+    question: str
+    feedback: str
+    answer_excerpt: str = ""
+
+
+_FEEDBACK_LOG: List[dict] = []
+
+
+@router.post("")
+async def store_feedback(req: FeedbackRequest):
+    _FEEDBACK_LOG.append(
+        {
+            "question": req.question[:500],
+            "feedback": req.feedback[:20],
+            "answer_excerpt": req.answer_excerpt[:1000],
+            "timestamp": time.time(),
+        }
+    )
+    if len(_FEEDBACK_LOG) > 1000:
+        del _FEEDBACK_LOG[:-1000]
+    return {"status": "ok"}