Update src/api/agent.py

src/api/agent.py

@@ -1225,23 +1225,126 @@ def _contact_footer_for_query(question: str, context: Optional[SearchContextPayl
 
 
 def _search_trace_block(question: str, context: SearchContextPayload) -> str:
+    """
+    'How I searched' reasoning panel — shown at the top of every search response.
+    Collapsible <details> so it doesn't dominate the answer.
+    """
     topic = _escape(context.display_topic or context.topic)
-    question_html = _escape(question)
     primo_boolean = _escape(context.primo_boolean_query or "")
-    found_via = "I identified the main topic, built a PRIMO search query, and looked for KU-accessible results."
-    if context.intent == "search_medical":
-        found_via += " Because this is a medical topic, PubMed is also recommended for broader evidence searching."
+    source_label = "PubMed" if context.source == "pubmed" else "KU PRIMO Library Discovery"
+
+    # Build reasoning sentence
+    intent_label = {
+        "search_academic": "academic literature search",
+        "search_medical": "medical / clinical literature search",
+    }.get(context.intent, "library search")
+
+    filters_parts = []
+    if context.peer_reviewed:
+        filters_parts.append("peer reviewed only")
+    if context.open_access:
+        filters_parts.append("open access")
+    if context.year_from and context.year_to:
+        filters_parts.append(f"{context.year_from}–{context.year_to}")
+    elif context.year_from:
+        filters_parts.append(f"from {context.year_from}")
+    rtype = {"articles": "articles", "books": "books", "both": "articles and books"}.get(
+        context.resource_type, "articles"
+    )
+    filters_parts.append(rtype)
+    filters_str = ", ".join(filters_parts)
+
+    reasoning = (
+        f"I identified this as a <strong>{intent_label}</strong>. "
+        f"I extracted the topic <strong>{topic}</strong>, "
+        f"built an LLM-optimised boolean query with quoted phrases and synonyms, "
+        f"then searched <strong>{source_label}</strong> for <strong>{filters_str}</strong>."
+    )
+    if context.intent == "search_medical" and context.source != "pubmed":
+        reasoning += " For medical topics, PubMed and Embase are also recommended."
+
     block = (
-        f'<div style="margin:10px 0 14px 0;padding:12px 14px;border:1px solid #dbe4ff;border-radius:12px;background:#f8fbff">'
-        f"<strong>Your question:</strong> {question_html}<br>"
-        f"<strong>Interpreted topic:</strong> {topic}<br>"
+        f'<details style="margin:0 0 14px 0;border:1px solid #dbe4ff;border-radius:12px;background:#f8fbff;overflow:hidden">'
+        f'<summary style="padding:10px 14px;cursor:pointer;font-size:.8rem;font-weight:700;color:#1e40af;list-style:none;display:flex;align-items:center;gap:6px">'
+        f'<span style="font-size:.9rem">🔍</span> How I searched — click to expand'
+        f'</summary>'
+        f'<div style="padding:4px 14px 12px 14px;font-size:.82rem;line-height:1.7;border-top:1px solid #dbe4ff">'
+        f'<strong>Your question:</strong> {_escape(question)}<br>'
+        f'<strong>Interpreted topic:</strong> {topic}<br>'
     )
     if primo_boolean:
-        block += f"<strong>PRIMO query used:</strong> <code>{primo_boolean}</code><br>"
-    block += f"<strong>How I found this:</strong> {found_via}</div>"
+        block += (
+            f'<strong>Boolean query sent to {source_label}:</strong><br>'
+            f'<code style="display:block;margin:4px 0;padding:6px 10px;background:#1a1a2e;color:#C8A951;'
+            f'border-radius:7px;font-size:.78rem;word-break:break-all">{primo_boolean}</code>'
+        )
+    block += f'<strong>Reasoning:</strong> {reasoning}'
+    block += '</div></details>'
     return block
 
 
+def _ai_tools_footer(context: SearchContextPayload) -> str:
+    """
+    AI tools recommendation panel — always rendered at the very end of the answer.
+    Structured as KU-subscribed tools first, then freemium, then more results.
+    """
+    urls = _tool_urls(context)
+    topic_enc = _escape(context.ai_tool_query or context.display_topic or context.topic)
+    is_medical = context.intent == "search_medical"
+
+    ku_tools = [
+        ("🔬 LeapSpace", urls["leapspace"], "leapspace", "#9a3412"),
+        ("🔭 Scopus AI", urls["scopus_ai"], "scopus", "#1e40af"),
+        ("📰 EBSCO AI", urls["ebsco_ai"], "ebscoai", "#9d174d"),
+        ("⭐ PRIMO AI Assistant", urls["primo_ai"], "primoai", "#5b21b6"),
+    ]
+    free_tools = [
+        ("🧬 Consensus", urls["consensus"], "consensus", "#86198f"),
+        ("🌐 OpenAlex", f"https://openalex.org/works?page=1&sort=relevance_score:desc&search={topic_enc}", "openalex", "#0c4a6e"),
+        ("🔎 Perplexity", f"https://www.perplexity.ai/search?q={topic_enc}", "perplexity", "#4c1d95"),
+    ]
+    more = [("📚 PRIMO Library Discovery", urls["primo_discovery"], "primoai", "#003366")]
+    if is_medical and urls.get("pubmed"):
+        more.append(("🏥 PubMed", urls["pubmed"], "pubmed_badge", "#065f46"))
+
+    def chip(label, url, cls, color):
+        return (
+            f'<a href="{url}" target="_blank" '
+            f'style="display:inline-flex;align-items:center;padding:5px 11px;margin:3px;'
+            f'border-radius:20px;font-size:.72rem;font-weight:700;text-decoration:none;'
+            f'border:1.5px solid {color}33;color:{color};background:{color}11;'
+            f'transition:all .2s;white-space:nowrap">{label}</a>'
+        )
+
+    html = (
+        '<div style="margin-top:18px;padding:12px 14px;border:1px solid #c4b5fd;'
+        'border-radius:12px;background:linear-gradient(135deg,#f5f3ff,#fdf4ff)">'
+        '<div style="font-size:.75rem;font-weight:800;color:#5b21b6;margin-bottom:8px">'
+        '✨ For deeper research — AI tools</div>'
+        '<div style="font-size:.67rem;font-weight:700;color:#6b7280;text-transform:uppercase;'
+        'letter-spacing:.5px;margin-bottom:4px">🔐 KU subscribed</div>'
+        '<div style="line-height:2">'
+    )
+    for label, url, cls, color in ku_tools:
+        html += chip(label, url, cls, color)
+    html += (
+        '</div><div style="font-size:.67rem;font-weight:700;color:#6b7280;text-transform:uppercase;'
+        'letter-spacing:.5px;margin:8px 0 4px">🆓 Freemium tools</div>'
+        '<div style="line-height:2">'
+    )
+    for label, url, cls, color in free_tools:
+        html += chip(label, url, cls, color)
+    html += (
+        '</div><div style="font-size:.67rem;font-weight:700;color:#6b7280;text-transform:uppercase;'
+        'letter-spacing:.5px;margin:8px 0 4px">📚 More results</div>'
+        '<div style="line-height:2">'
+    )
+    for label, url, cls, color in more:
+        html += chip(label, url, cls, color)
+    html += '</div></div>'
+    return html
+
+
 def _is_database_recommendation_question(question: str) -> bool:
     return bool(DATABASE_RECOMMEND_RE.search(question or ""))
 
@@ -1548,35 +1651,42 @@ def _database_recommendation_answer(question: str) -> str:
 async def _research_snapshot(context: SearchContextPayload, model: str) -> Tuple[str, List[dict], List[dict]]:
     """
     Research snapshot:
-    - Runs Semantic Scholar + PRIMO in parallel for speed.
-    - If Semantic Scholar returns papers: generate cited summary, show refs, then AI tools at bottom.
-    - If Semantic Scholar returns nothing: silently fall back to PRIMO results + AI tools.
-      Never mention Semantic Scholar failure to the user.
-    - AI tools panel always appears at the end.
+    - Reasoning block at the top (collapsible).
+    - Cited summary in the middle.
+    - PRIMO results below that.
+    - AI tools recommendation panel always at the very end.
+    - Silent fallback if Semantic Scholar returns nothing.
     """
     import asyncio as _asyncio
     topic = context.topic
     references: List[dict] = []
 
-    # Parallel fetch — don't wait for Semantic Scholar before starting PRIMO
+    # Parallel fetch
     papers, (primo_result, primo_url) = await _asyncio.gather(
         _semantic_scholar_search(topic, limit=8),
         _search_primo_catalog(context, limit=6),
     )
     search_results = primo_result.get("results", []) or []
 
+    # ── Top: reasoning block ──────────────────────────────────────────────────
+    q_display = context.ai_tool_query or f"Research on {topic}"
+    answer = _search_trace_block(q_display, context)
+
     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}"
+        # ── Middle: cited summary ─────────────────────────────────────────────
+        answer += f"<strong>📖 Research Snapshot: {_escape(topic)}</strong><br><br>{summary}"
+
         if search_results:
             answer += (
                 "<br><br><strong>KU Library results:</strong> "
-                "KU-accessible items are shown below — open them directly or use the AI tools for a deeper search."
+                "KU-accessible items are shown below."
             )
+
         answer += "<br><br><strong>Selected references:</strong><br>"
         for i, paper in enumerate(papers[:6], 1):
             answer += (
@@ -1586,29 +1696,29 @@ async def _research_snapshot(context: SearchContextPayload, model: str) -> Tuple
                 f'{_escape(paper["authors"])} · {paper["year"]} · {_escape(paper["venue"] or "")}'
                 f"</span>"
             )
-        # AI tools always at the bottom
-        answer += f"<br><br>{_database_guidance_for_topic(context)}"
         answer += _source_badge("semantic", "https://www.semanticscholar.org/")
         if search_results:
             answer += _source_badge("primo", primo_url)
+
+        # ── Bottom: AI tools ──────────────────────────���───────────────────────
+        answer += _ai_tools_footer(context)
         references = [{"title": p["title"], "url": p["link"]} for p in papers[:6]]
         return answer, search_results, references
 
-    # Semantic Scholar returned nothing — silent fallback, no error message
+    # Semantic Scholar returned nothing — silent fallback
     if search_results:
-        answer = (
+        answer += (
             f"<strong>📚 Research starting points: {_escape(topic)}</strong><br><br>"
-            "Here are KU-accessible results you can open immediately. "
-            "For a deeper literature synthesis, use the AI research tools below."
-            f"<br><br>{_database_guidance_for_topic(context)}"
+            "Here are KU-accessible results you can open immediately."
         )
     else:
-        answer = (
+        answer += (
             f"<strong>📚 Research starting points: {_escape(topic)}</strong><br><br>"
-            "I didn't find direct results right now — try the AI research tools below for a deep search on this topic."
-            f"<br><br>{_database_guidance_for_topic(context)}"
+            "I didn't find direct results right now — try the AI research tools below."
         )
     answer += _source_badge("primo", primo_url)
+    # ── Bottom: AI tools ──────────────────────────────────────────────────────
+    answer += _ai_tools_footer(context)
     return answer, search_results, []
 
 
@@ -1910,7 +2020,6 @@ 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)
@@ -1922,20 +2031,29 @@ async def _run_search_mode(
     search_results = result.get("results", []) or []
     total = result.get("total", len(search_results))
 
-    answer = _search_answer_intro(context, is_follow_up)
+    # ── Top: reasoning / how-I-searched block ────────────────────────────────
+    answer = _search_trace_block(question, context)
+
+    # ── Middle: answer sentence + result count ────────────────────────────────
+    answer += _search_answer_intro(context, is_follow_up)
+
+    filters = _filters_summary(context)
     if filters:
-        answer += f"<br><br><strong>Current filters:</strong> {_escape(filters)}."
+        answer += f"<br><br><strong>Active filters:</strong> {_escape(filters)}."
+
     if search_results:
-        answer += f"<br><br>I found <strong>{total}</strong> result(s). The top items are shown below."
+        answer += f"<br><br>Found <strong>{total:,}</strong> result(s) — top {len(search_results)} 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."
-        )
+        answer += "<br><br>No matching results found right now — try broadening your terms or use the AI 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 += "<br><br>For the strongest medical evidence trail, also check <strong>PubMed</strong> or <strong>Embase</strong>."
 
     answer += _source_badge(source_name, source_url)
+
+    # ── Bottom: AI tools recommendation panel ─────────────────────────────────
+    answer += _ai_tools_footer(context)
+
     sources = []
     for item in search_results[:6]:
         link = item.get("primo_url") or item.get("link")