Upload 5 files

src/api/agent.py

@@ -1,52 +1,62 @@
-"""Authenticated agent endpoint; Cloudflare is the only intended caller."""
-
+"""Authenticated agent endpoint; Cloudflare is the only intended caller."""
+
 import html
-import time
-import uuid
-
-from fastapi import APIRouter, Request
-
-from src.agentcore.models import AgentRequest, AgentResponse
-from src.agentcore.orchestrator import _agent_query_inner, _log_agent_query
-from src.agentcore.utils import _get_runtime_config, _normalize_whitespace, _safe_metrics_increment, _sanitize_llm_response
+import re
+import time
+import uuid
+
+from fastapi import APIRouter, HTTPException, Request
+
+from src.agentcore.models import AgentRequest, AgentResponse
+from src.agentcore.orchestrator import _agent_query_inner, _log_agent_query
+from src.agentcore.utils import _get_runtime_config, _normalize_whitespace, _safe_metrics_increment, _sanitize_llm_response
 from src.services.html_sanitizer import sanitize_answer_html
-
-router = APIRouter()
-
-
-@router.post("", response_model=AgentResponse)
+from src.config import get_settings
+
+router = APIRouter()
+
+
+@router.post("", response_model=AgentResponse)
 async def agent_query(request: Request, req: AgentRequest):
     start_time = time.time()
-    request_id = request.headers.get("x-request-id", "")[:80] or str(uuid.uuid4())
+    settings = get_settings()
+    if (len(req.question) > settings.max_question_chars or
+            len(req.history) > settings.max_history_messages or
+            any(len(message.content) > settings.max_message_chars for message in req.history)):
+        raise HTTPException(status_code=422, detail="Question or history exceeds the configured text limit.")
+    supplied_id = request.headers.get("x-request-id", "")
+    request_id = supplied_id if re.fullmatch(r"[A-Za-z0-9_-]{8,80}", supplied_id) else str(uuid.uuid4())
     question = _normalize_whitespace(req.question)
-    history = list(req.history)
-    if history and history[-1].role == "user" and _normalize_whitespace(history[-1].content) == question:
-        history.pop()
-    is_canary = request.headers.get("x-libbee-canary") == "1"
-    if not is_canary:
-        _safe_metrics_increment("agent_requests")
-    response = await _agent_query_inner(question, history, req.model, req.client_state, start_time)
-    response.request_id = request_id
-    response.answer = _sanitize_llm_response(response.answer)
-    runtime_config = _get_runtime_config()
-    announcement = str(runtime_config.get("announcement", "")).strip()
-    if announcement and response.intent not in {"social_greeting", "social"}:
-        response.answer += '<div class="libbee-announcement" role="note"><strong>Announcement:</strong> ' + html.escape(announcement) + "</div>"
-    response.answer = sanitize_answer_html(response.answer)
-    if not is_canary:
-        _log_agent_query(question, response, start_time)
-    return response
-
-
-@router.get("/test")
-async def test():
-    return {"status": "ok"}
-
-
-@router.get("/rag-status")
-async def rag_status():
-    try:
-        from app import get_rag_service
-        return get_rag_service().get_stats()
-    except Exception:
-        return {"ready": False}
+    if not question:
+        raise HTTPException(status_code=422, detail="Question must contain text.")
+    history = list(req.history)
+    if history and history[-1].role == "user" and _normalize_whitespace(history[-1].content) == question:
+        history.pop()
+    is_canary = request.headers.get("x-libbee-canary") == "1"
+    if not is_canary:
+        _safe_metrics_increment("agent_requests")
+    response = await _agent_query_inner(question, history, req.model, req.client_state, start_time)
+    response.request_id = request_id
+    response.answer = _sanitize_llm_response(response.answer)
+    runtime_config = _get_runtime_config()
+    announcement = str(runtime_config.get("announcement", "")).strip()
+    if announcement and response.intent not in {"social_greeting", "social"}:
+        response.answer += '<div class="libbee-announcement" role="note"><strong>Announcement:</strong> ' + html.escape(announcement) + "</div>"
+    response.answer = sanitize_answer_html(response.answer)
+    if not is_canary:
+        _log_agent_query(question, response, start_time)
+    return response
+
+
+@router.get("/test")
+async def test():
+    return {"status": "ok"}
+
+
+@router.get("/rag-status")
+async def rag_status():
+    try:
+        from app import get_rag_service
+        return get_rag_service().get_stats()
+    except Exception:
+        return {"ready": False}

src/api/feedback.py

@@ -12,9 +12,12 @@ router = APIRouter()
 
 class FeedbackRequest(BaseModel):
     model_config = ConfigDict(extra="forbid")
-    request_id: str = Field(pattern=r"^[A-Za-z0-9-]{8,80}$")
+    request_id: str = Field(pattern=r"^[A-Za-z0-9_-]{8,80}$")
     feedback: str
     comment: str = Field(default="", max_length=500)
+    # The existing LibGuides client sends this field to its Worker. Accept it
+    # if forwarded, but do not store it in the local feedback fallback.
+    session_id: str | None = Field(default=None, pattern=r"^[A-Za-z0-9_-]{8,80}$")
 
     @field_validator("feedback")
     @classmethod
@@ -26,12 +29,14 @@ class FeedbackRequest(BaseModel):
 
 @router.post("")
 async def save_feedback(req: FeedbackRequest):
-    settings = get_settings()
+    settings = get_settings()
+    comment = re.sub(r"[\w.+-]+@[\w-]+\.[\w.-]+", "[email]", req.comment)
+    comment = re.sub(r"\b\d{6,}\b", "[number]", comment)
     payload = {
         "timestamp": time.time(),
         "request_id": req.request_id,
         "feedback": req.feedback,
-        "comment": re.sub(r"[\w.+-]+@[\w-]+\.[\w.-]+", "[email]", req.comment)[:500],
+        "comment": comment[:500],
     }
     settings.feedback_path.parent.mkdir(parents=True, exist_ok=True)
     with settings.feedback_path.open("a", encoding="utf-8") as handle:

src/api/search.py

@@ -1,259 +1,271 @@
-"""
-src/api/search.py — PRIMO + PubMed search endpoint for LibBee v3.4.
-
-Search approach: send the full boolean query as a single q=any,contains,<boolean>
-parameter — exactly how the PRIMO web UI works. This preserves phrase quotes,
-parentheses, AND/OR operators, and gives results identical to the web UI.
-
-Earlier versions split the boolean into multiple q= params (one per AND group),
-but PRIMO does not reliably handle OR within a single q= value in multi-param mode.
-The correct approach is a single q= with the full boolean, URL-encoded.
-"""
-import re
+"""PRIMO and PubMed search, with explicit filters and bounded upstream waits."""
+import asyncio
 import logging
-from datetime import datetime
+import re
 from typing import Optional
+from urllib.parse import quote
 
 from fastapi import APIRouter
-from pydantic import BaseModel, ConfigDict, Field
-from urllib.parse import quote
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 logger = logging.getLogger(__name__)
 router = APIRouter()
+PRIMO_REQUEST_TIMEOUT = 5.0
+PUBMED_REQUEST_TIMEOUT = 8.0
 
 
-# ── Models ─────────────────────────────────────────────────────────────────────
-
 class SearchRequest(BaseModel):
-    model_config = ConfigDict(extra="forbid")
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
     query: str = Field(min_length=1, max_length=1000)
     boolean_query: Optional[str] = Field(default=None, max_length=1500)
     source: str = Field(default="primo", pattern=r"^(primo|pubmed)$")
     limit: int = Field(default=5, ge=1, le=20)
     peer_reviewed: bool = False
     open_access: bool = False
-    year_from: Optional[str] = Field(default=None, pattern=r"^\d{4}$")
-    year_to: Optional[str] = Field(default=None, pattern=r"^\d{4}$")
+    year_from: Optional[str] = Field(default=None, pattern=r"^[0-9]{4}$")
+    year_to: Optional[str] = Field(default=None, pattern=r"^[0-9]{4}$")
     resource_type: str = Field(default="articles", pattern=r"^(articles|books|both)$")
 
+    @model_validator(mode="after")
+    def validate_search(self):
+        self.boolean_query = self.boolean_query or None
+        for year in (self.year_from, self.year_to):
+            if year == "0000":
+                raise ValueError("Publication years must be between 0001 and 9999")
+        if self.year_from and self.year_to and self.year_from > self.year_to:
+            raise ValueError("year_from must not be later than year_to")
+        # Primo reserves semicolons for additional field clauses, even when
+        # percent-encoded; accepting one here changes the meaning of a query.
+        if self.source == "primo" and ";" in (self.boolean_query or self.query):
+            raise ValueError("PRIMO search terms cannot contain semicolons")
+        return self
 
-# ── PRIMO query builder ────────────────────────────────────────────────────────
 
 def _boolean_to_primo_params(boolean_query: str) -> str:
-    """
-    Convert a boolean query into a single PRIMO q= parameter.
-
-    Sends the full boolean as: q=any,contains,<url-encoded boolean>
-    This matches exactly how the PRIMO web UI constructs advanced search URLs.
-
-    Examples:
-        '("machine learning" OR "deep learning") AND ("healthcare")'
-        → 'q=any,contains,%28%22machine+learning%22+OR+%22deep+learning%22%29...'
+    """Preserve exact phrases and all Boolean operators in one Primo q value."""
+    return f"q=any,contains,{quote(boolean_query.strip(), safe='')}"
 
-        '"climate change"'
-        → 'q=any,contains,%22climate+change%22'
 
-        'petroleum engineering'
-        → 'q=any,contains,petroleum+engineering'
-    """
-    if not boolean_query or not boolean_query.strip():
-        return "q=any,contains,library"
+def _year_bounds(req: SearchRequest) -> tuple[str, str]:
+    """Represent an omitted bound without silently excluding older/future works."""
+    return req.year_from or "0001", req.year_to or "9999"
 
-    # Send the full boolean as a single q= parameter — PRIMO parses it correctly
-    return f"q=any,contains,{quote(boolean_query.strip())}"
-
-
-# ── PRIMO helpers ──────────────────────────────────────────────────────────────
 
 def _build_primo_search_link(title: str, record_id: Optional[str] = None) -> Optional[str]:
-    base = 'https://khalifa.primo.exlibrisgroup.com/discovery'
+    base = "https://khalifa.primo.exlibrisgroup.com/discovery"
     if record_id:
-        return f"{base}/fulldisplay?docid={quote(str(record_id))}&vid=971KUOSTAR_INST:KU"
-    clean_title = (title or '').strip()
+        return f"{base}/fulldisplay?docid={quote(str(record_id), safe='')}&vid=971KUOSTAR_INST:KU"
+    clean_title = (title or "").strip()
     if not clean_title:
         return None
     return (
-        f"{base}/search?query=any,contains,{quote(clean_title)}"
+        f"{base}/search?query=any,contains,{quote(clean_title, safe='')}"
         "&tab=Everything&search_scope=MyInst_and_CI&vid=971KUOSTAR_INST:KU&lang=en"
     )
 
 
+def _first(value, default=""):
+    """PNX values are normally arrays; tolerate scalar/missing metadata."""
+    if isinstance(value, list):
+        value = value[0] if value else default
+    return value if isinstance(value, str) else default
+
+
+def _result_link(raw_link: str, fallback: Optional[str]) -> Optional[str]:
+    # PNX link fields can contain $$U<url>$$D<label>, rather than a bare URL.
+    match = re.match(r"(?:\$\$U)?(https?://[^\s]+?)(?:\$\$|$)", raw_link)
+    return match.group(1) if match else fallback
+
+
 async def search_primo(req: SearchRequest, api_key: str) -> dict:
-    """
-    Search the PRIMO API.
-    Prefers req.boolean_query (LLM-built) over req.query for structured results.
-    Converts boolean to multi-q-param format for accurate PRIMO results.
-    """
+    """Search Primo using the full preferred query and documented facet syntax."""
     import httpx
 
     if not api_key:
-        return {"error": "PRIMO_API_KEY not configured", "results": [], "total": 0}
-
-    raw_query = (req.boolean_query or req.query or "").strip()
-    has_bool = bool(re.search(r'\b(AND|OR)\b', raw_query)) and '(' in raw_query
+        return {"error": "PRIMO_API_KEY not configured", "results": [], "total": 0, "source": "PRIMO"}
 
-    if has_bool:
-        query_params = _boolean_to_primo_params(raw_query)
-    else:
-        clean = re.sub(r'["\']', '', raw_query).strip()
-        query_params = f"q=any,contains,{quote(clean)}"
-
-    facets = ""
+    query_params = _boolean_to_primo_params(req.boolean_query or req.query)
+    facets = []
     if req.peer_reviewed:
-        facets += "&qInclude=facet_tlevel,exact,peer_reviewed"
+        facets.append("facet_tlevel,exact,peer_reviewed")
     if req.open_access:
-        facets += "&qInclude=facet_tlevel,exact,open_access"
+        facets.append("facet_tlevel,exact,open_access")
     if req.year_from or req.year_to:
-        yf = req.year_from or "1900"
-        yt = req.year_to or str(datetime.now().year)
-        facets += f"&multiFacets=facet_searchcreationdate,include,{yf}%7C,%7C{yt}"
-    if req.resource_type == "books":
-        facets += "&qInclude=facet_rtype,exact,books"
-    elif req.resource_type == "articles":
-        facets += "&qInclude=facet_rtype,exact,articles"
-
-    vid = "971KUOSTAR_INST:KU"
+        year_from, year_to = _year_bounds(req)
+        facets.append(f"facet_searchcreationdate,exact,[{year_from} TO {year_to}]")
+    if req.resource_type != "both":
+        facets.append(f"facet_rtype,exact,{req.resource_type}")
+
+    # qInclude accepts one value, joining ANDed facets with |,|. Repeated
+    # qInclude keys are not its documented API contract.
+    facet_params = f"&qInclude={quote('|,|'.join(facets), safe='')}" if facets else ""
     qs = (
-        f"?vid={vid}&tab=Everything&scope=MyInst_and_CI"
-        f"&{query_params}"
-        f"&lang=en&sort=rank&limit={req.limit}&offset=0&mode=advanced"
-        f"&apikey={api_key}{facets}"
+        "?vid=971KUOSTAR_INST:KU&tab=Everything&scope=MyInst_and_CI"
+        f"&{query_params}&lang=en&sort=rank&limit={req.limit}&offset=0"
+        f"{facet_params}"
     )
 
-    base = "https://api-eu.hosted.exlibrisgroup.com/primo/v1/search"
-
-    async with httpx.AsyncClient(timeout=15) as client:
-        for region in ["api-eu", "api-na", "api-ap"]:
-            url = base.replace("api-eu", region) + qs
+    async with httpx.AsyncClient(timeout=PRIMO_REQUEST_TIMEOUT) as client:
+        for region in ("api-eu", "api-na", "api-ap"):
+            url = f"https://{region}.hosted.exlibrisgroup.com/primo/v1/search{qs}"
             try:
-                r = await client.get(url, headers={"Accept": "application/json"})
-                if r.status_code == 200:
-                    data = r.json()
-                    total = data.get("info", {}).get("total", 0)
-                    results = []
-                    for doc in data.get("docs", []):
-                        pnx = doc.get("pnx", {})
-                        d = pnx.get("display", {})
-                        a = pnx.get("addata", {})
-                        s = pnx.get("search", {})
-                        c = pnx.get("control", {})
-                        l = pnx.get("links", {})
-                        record_id = (c.get("recordid") or [None])[0]
-                        title = (d.get("title") or ["Untitled"])[0]
-                        primo_url = _build_primo_search_link(title, record_id)
-                        doi = (a.get("doi") or [None])[0]
-                        raw_link = (l.get("openurl") or l.get("linktorsrc") or [None])[0]
-                        results.append({
-                            "record_id": record_id,
-                            "title": title,
-                            "creator": "; ".join(
-                                d.get("creator") or d.get("contributor") or []
-                            ) or "Unknown",
-                            "date": (
-                                s.get("creationdate") or a.get("risdate") or a.get("date") or [""]
-                            )[0],
-                            "type": (d.get("type") or [""])[0],
-                            "source": (d.get("source") or a.get("jtitle") or [""])[0],
-                            "description": ((d.get("description") or [""])[0] or "")[:400],
-                            "doi": doi,
-                            "primo_url": primo_url,
-                            "link": raw_link or primo_url,
-                            "open_access": (d.get("oa") or [""])[0] == "free_for_read",
-                            "_source": "PRIMO",
-                        })
-                    return {"total": total, "results": results, "source": "PRIMO"}
-            except Exception as e:
-                logger.warning("PRIMO region %s failed: %s", region, e)
-                continue
+                # httpx read timeouts reset per chunk. wait_for additionally
+                # bounds the complete request, including a slowly streamed body.
+                response = await asyncio.wait_for(
+                    client.get(url, headers={"Accept": "application/json", "Authorization": f"apikey {api_key}"}),
+                    timeout=PRIMO_REQUEST_TIMEOUT,
+                )
+                if response.status_code != 200:
+                    logger.warning("PRIMO region %s returned HTTP %s", region, response.status_code)
+                    if response.status_code == 429:
+                        return {"error": "PRIMO request limit reached; try again later", "results": [], "total": 0, "source": "PRIMO"}
+                    if response.status_code == 400:
+                        return {"error": "PRIMO could not process this search; check the search terms", "results": [], "total": 0, "source": "PRIMO"}
+                    continue
+                data = response.json()
+                if not isinstance(data, dict) or not isinstance(data.get("docs"), list):
+                    raise ValueError("Invalid PRIMO response")
+                results = []
+                for doc in data.get("docs", []):
+                    if not isinstance(doc, dict):
+                        continue
+                    pnx = doc.get("pnx") or {}
+                    if not isinstance(pnx, dict):
+                        continue
+                    display = pnx.get("display") or {}
+                    addata = pnx.get("addata") or {}
+                    search = pnx.get("search") or {}
+                    control = pnx.get("control") or {}
+                    links = pnx.get("links") or {}
+                    record_id = _first(control.get("recordid"), None)
+                    title = _first(display.get("title"), "Untitled")
+                    primo_url = _build_primo_search_link(title, record_id)
+                    creators = display.get("creator") or display.get("contributor") or []
+                    if isinstance(creators, str):
+                        creators = [creators]
+                    raw_link = _first(links.get("openurl") or links.get("linktorsrc"))
+                    results.append({
+                        "record_id": record_id,
+                        "title": title,
+                        "creator": "; ".join(str(creator) for creator in creators) or "Unknown",
+                        "date": _first(search.get("creationdate") or addata.get("risdate") or addata.get("date")),
+                        "type": _first(display.get("type")),
+                        "source": _first(display.get("source") or addata.get("jtitle")),
+                        "description": _first(display.get("description"))[:400],
+                        "doi": _first(addata.get("doi"), None),
+                        "primo_url": primo_url,
+                        "link": _result_link(raw_link, primo_url),
+                        "open_access": _first(display.get("oa")) == "free_for_read",
+                        "_source": "PRIMO",
+                    })
+                return {"total": (data.get("info") or {}).get("total", 0), "results": results, "source": "PRIMO"}
+            except (httpx.HTTPError, TimeoutError, ValueError, TypeError, AttributeError) as exc:
+                # Exception strings from HTTP clients can include the full URL,
+                # including the API key. Never put them in logs or responses.
+                logger.warning("PRIMO region %s failed (%s)", region, type(exc).__name__)
 
     return {"error": "PRIMO API unavailable", "results": [], "total": 0, "source": "PRIMO"}
 
 
-# ── PubMed search ──────────────────────────────────────────────────────────────
+def _pubmed_query(req: SearchRequest) -> str:
+    query = req.boolean_query or req.query
+    if req.year_from or req.year_to:
+        year_from, year_to = _year_bounds(req)
+        query = f"({query}) AND ({year_from}:{year_to}[dp])"
+    if req.open_access:
+        query = f"({query}) AND free full text[sb]"
+    if req.resource_type == "books":
+        query = f'({query}) AND "pubmed books"[sb]'
+    elif req.resource_type == "articles":
+        query = f'({query}) NOT "pubmed books"[sb]'
+    return query
+
 
 async def search_pubmed(req: SearchRequest) -> dict:
-    """Search PubMed via E-utilities."""
+    """Search PubMed; free availability does not establish an open-access licence."""
     import httpx
 
     base = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
-    query = (req.query or "").strip()
+    warnings = []
+    if req.peer_reviewed:
+        warnings.append("PubMed has no general peer-reviewed-only filter; peer review must be checked for each record.")
+    if req.open_access:
+        warnings.append("The PubMed access filter finds free full text; it does not verify an open-access licence.")
+    common = {"source": "PubMed", "warnings": warnings}
 
-    if req.year_from or req.year_to:
-        yf = req.year_from or "1900"
-        yt = req.year_to or str(datetime.now().year)
-        query = f"({query}) AND ({yf}:{yt}[dp])"
+    def failed(message):
+        return {**common, "error": message, "results": [], "total": 0}
 
     try:
-        async with httpx.AsyncClient(timeout=15) as client:
-            r = await client.get(
+        async with httpx.AsyncClient(timeout=PUBMED_REQUEST_TIMEOUT) as client:
+            response = await asyncio.wait_for(client.get(
                 f"{base}/esearch.fcgi",
-                params={
-                    "db": "pubmed", "term": query,
-                    "retmax": req.limit, "retmode": "json", "sort": "relevance"
-                }
-            )
-            if r.status_code != 200:
-                return {"error": "PubMed search failed", "results": [], "source": "PubMed"}
-
-            esearch = r.json().get("esearchresult", {})
-            ids = esearch.get("idlist", [])
-            # PubMed Automatic Term Mapping: how the free-text query was
-            # expanded to MeSH terms - surfaced to teach search strategy.
+                params={"db": "pubmed", "term": _pubmed_query(req), "retmax": req.limit,
+                        "retmode": "json", "sort": "relevance"},
+            ), timeout=PUBMED_REQUEST_TIMEOUT)
+            if response.status_code != 200:
+                return failed("PubMed search failed")
+            payload = response.json()
+            esearch = payload.get("esearchresult", {})
+            if payload.get("error") or esearch.get("ERROR") or esearch.get("errorlist"):
+                return failed("PubMed could not process this search; check the search terms")
+            ids = esearch.get("idlist")
+            if not isinstance(ids, list):
+                return failed("PubMed returned an unreadable search response; try again")
             query_translation = esearch.get("querytranslation", "")
             count = int(esearch.get("count", 0))
             if not ids:
-                return {"total": 0, "results": [], "source": "PubMed", "query_translation": query_translation}
+                return {**common, "total": count, "results": [], "query_translation": query_translation}
 
-            r2 = await client.get(
+            summary = await asyncio.wait_for(client.get(
                 f"{base}/esummary.fcgi",
-                params={"db": "pubmed", "id": ",".join(ids), "retmode": "json"}
-            )
-            if r2.status_code != 200:
-                return {"error": "PubMed fetch failed", "results": [], "source": "PubMed"}
-
-            data = r2.json().get("result", {})
+                params={"db": "pubmed", "id": ",".join(ids), "retmode": "json"},
+            ), timeout=PUBMED_REQUEST_TIMEOUT)
+            if summary.status_code != 200:
+                return failed("PubMed fetch failed")
+            summary_payload = summary.json()
+            if summary_payload.get("error"):
+                return failed("PubMed fetch failed")
+            data = summary_payload.get("result", {})
             results = []
             for pid in ids:
-                rec = data.get(pid, {})
-                if not isinstance(rec, dict):
+                record = data.get(pid)
+                if not isinstance(record, dict) or record.get("error"):
                     continue
-                authors_list = rec.get("authors", [])
-                authors = ", ".join(a.get("name", "") for a in authors_list[:3])
+                authors_list = record.get("authors") or []
+                authors = ", ".join(author.get("name", "") for author in authors_list[:3])
                 if len(authors_list) > 3:
                     authors += " et al."
-                eloc = rec.get("elocationid", "")
-                doi = eloc.replace("doi: ", "") if "doi:" in eloc else None
+                doi = next((article.get("value") for article in record.get("articleids", [])
+                            if article.get("idtype") == "doi"), None)
+                if not doi:
+                    match = re.search(r"\bdoi:\s*(\S+)", record.get("elocationid", ""), re.IGNORECASE)
+                    doi = match.group(1) if match else None
                 results.append({
-                    "title": rec.get("title", ""),
+                    "title": record.get("title", ""),
                     "creator": authors,
-                    "date": rec.get("pubdate", ""),
-                    "source": rec.get("fulljournalname", rec.get("source", "")),
+                    "date": record.get("pubdate", ""),
+                    "source": record.get("fulljournalname", record.get("source", "")),
                     "doi": doi,
                     "pmid": pid,
                     "link": f"https://pubmed.ncbi.nlm.nih.gov/{pid}/",
-                    "type": "Journal Article",
+                    "type": "; ".join(record.get("pubtype") or []) or "PubMed record",
+                    "free_full_text": True if req.open_access else None,
                     "_source": "PubMed",
                 })
-            return {"total": count, "results": results, "source": "PubMed", "query_translation": query_translation}
+            if ids and not results:
+                return failed("PubMed returned no readable record details; try again")
+            return {**common, "total": count, "results": results, "query_translation": query_translation}
+    except (httpx.HTTPError, TimeoutError, ValueError, TypeError, AttributeError) as exc:
+        logger.warning("PubMed search failed (%s)", type(exc).__name__)
+        return failed("PubMed is temporarily unavailable; try again")
 
-    except Exception as e:
-        return {"error": f"PubMed: {str(e)}", "results": [], "source": "PubMed"}
-
-
-# ── FastAPI endpoint ───────────────────────────────────────────────────────────
 
 @router.post("")
 async def search_endpoint(req: SearchRequest):
-    """
-    Search PRIMO or PubMed.
-    Accepts boolean_query (preferred, LLM-built) or falls back to query.
-    """
+    """Search PRIMO or PubMed, preferring boolean_query when supplied."""
     from src.config import get_settings
-    settings = get_settings()
 
-    source = (req.source or "primo").lower()
-
-    if source == "pubmed":
+    if req.source == "pubmed":
         return await search_pubmed(req)
-
-    return await search_primo(req, settings.primo_api_key)
+    return await search_primo(req, get_settings().primo_api_key)