Upload 7 files

README.md

@@ -29,6 +29,8 @@ Turns a natural-language question into keyword searches on **Khazna** (KU's Else
 
 **Concept expansion:** for topic, thesis, expert, project and collaboration searches, one Pure thesaurus concept from `/concepts/search` that shares a word with the query is added as an extra search variant. Set `USE_CONCEPTS=false` to switch it off.
 
+**Name disambiguation:** for a named researcher, `/persons/search` returns up to 50 people, kept only if every typed name word equals one of their name words (first, middle or last; prefix matches only when nothing matches exactly). One match, or one exact full-name match, goes straight to that profile. Two or more return `intent: "author_clarify"` with up to `MAX_NAME_CANDIDATES` (default 12) cards marked `choose: true`. The frontend then resends the original question with `person_uuid`, which bypasses the name search entirely.
+
 Expert finding combines three signals: Pure's profile search, the KU authors of the top-ranked publications for the topic, and the supervisors of matching student theses. Profile search alone misses active researchers with sparse profiles. The publications also become the "matching outputs" evidence on each profile card.
 
 ## Pipeline
@@ -114,7 +116,7 @@ Not used, so they can be removed from the key: `/users/*`, `/roles/*`, `/changes
 | GET | `/` | redirects to `FRONTEND_URL` (https://library.ku.ac.ae/khaznabot) |
 | GET | `/test` | the Space's own test chat (widget) |
 | GET | `/widget.js` | embeddable widget |
-| POST | `/agent` | `{question, history, model: "gpt"\|"claude", scope, top_k}` → answer, `request_id` (also an `X-Request-ID` header), `search_results` (each has `kind`: publication / thesis / person / organisation / project / equipment / collaborator / dataset), `person`, `trace`, `plan`, `follow_up_suggestions` |
+| POST | `/agent` | `{question, history, model: "gpt"\|"claude", scope, top_k, person_uuid?}` → answer, `request_id` (also an `X-Request-ID` header), `search_results` (each has `kind`: publication / thesis / person / organisation / project / equipment / collaborator / dataset), `person`, `trace`, `plan`, `follow_up_suggestions` |
 | POST | `/feedback` | `{request_id, feedback: "up"\|"down", session_id}` (LibGuides block) or `{question, rating}` (widget) |
 | GET | `/config` | public frontend config: announcement, maintenance mode |
 | GET | `/health` | backend status |

app.py

@@ -143,7 +143,8 @@ class AgentRequest(BaseModel):
     model: str = "gpt"            # "gpt" | "claude"  (same convention as LibBee)
     history: list[ChatMessage] = []
     top_k: int | None = None
-    scope: str = "all"            # all | publications | persons | organisations | datasets
+    scope: str = "all"            # all | publications | theses | persons | organisations | projects | equipment | collaborations
+    person_uuid: str | None = None  # set when the user picks one researcher from a disambiguation list
 
 
 class FeedbackRequest(BaseModel):
@@ -165,7 +166,7 @@ def _public_result(o: dict, n: int) -> dict:
     kind = o.get("kind", "publication")
     if kind == "person":
         keep = ("kind", "uuid", "name", "job_titles", "organisations", "keywords", "orcid", "portal_url", "evidence", "matching_outputs",
-                "supervised", "supervised_theses")
+                "supervised", "supervised_theses", "choose")
     elif kind == "organisation":
         keep = ("kind", "uuid", "name", "type", "parents", "portal_url")
     elif kind == "collaborator":
@@ -199,6 +200,13 @@ def _reply(t0: float, **kw) -> dict:
 _SESSION_RE = re.compile(r"^[A-Za-z0-9_-]{8,80}$")
 
 
+def _portal_url(path: str, term: str, search_by: str | None = None) -> str:
+    """Plain Khazna portal search link, e.g. https://khazna.ku.ac.ae/en/persons/?search=kumar.
+    The portal's default people search already lists everyone whose name matches, so no
+    searchBy mode is added (search_by is accepted but intentionally unused)."""
+    return f"{PURE_PORTAL_URL}/en/{path}/?search={quote_plus(term)}"
+
+
 def _followups(plan, retrieval: dict | None) -> list[dict]:
     """Next-step suggestions the frontend renders as chips: {label, question, scope}."""
     kw = (plan.keyword_queries[0] if plan.keyword_queries else "").strip()
@@ -326,8 +334,9 @@ async def agent(req: AgentRequest, request: Request, response: Response):
         log_query(q, plan.intent, [], 0, model, time.time() - t0, **logx)
         return _reply(t0, **base, answer=ans)
 
+    person_uuid = req.person_uuid if req.person_uuid and re.fullmatch(r"[A-Za-z0-9-]{1,64}", req.person_uuid) else None
     try:
-        retrieval = await pipeline.retrieve(pure, plan)
+        retrieval = await pipeline.retrieve(pure, plan, person_uuid=person_uuid)
     except PureError as e:
         log_query(q, plan.intent, plan.keyword_queries, 0, model, time.time() - t0, str(e), **logx)
         if e.status == 403 and plan.intent == "dataset_search":
@@ -339,6 +348,22 @@ async def agent(req: AgentRequest, request: Request, response: Response):
         return _reply(t0, **base, answer=msg, error=str(e))
 
     results = retrieval["results"]
+    if retrieval.get("clarify"):
+        c = retrieval["clarify"]
+        more = (f" I'm showing the first {c['shown']}; add a first name, surname or department to narrow it down."
+                if c["count"] > c["shown"] else "")
+        answer = (f"I found **{c['count']} KU researchers** whose name matches “{c['name']}”. Which one do you mean?\n"
+                  f"Choose **Explore this researcher** on the right person below, or add their full name or department to your question.{more}")
+        log_query(q, "author_clarify", [c["name"]], len(results), model, time.time() - t0, **logx)
+        return _reply(
+            t0, **{**base, "intent": "author_clarify"},
+            answer=answer, clarify=True, original_question=q,
+            search_results=[_public_result(o, i) for i, o in enumerate(results, 1)],
+            total_found=c["count"], after_filters=len(results),
+            trace=[{k: v for k, v in t.items() if k != "error"} for t in retrieval["trace"]],
+            portal_search_url=_portal_url("persons", c["name"], "PartOfNameOrTitle"),
+            follow_up_suggestions=[],
+        )
     if not results:
         filt = bool(plan.year_from or plan.year_to or plan.output_types or plan.open_access_only)
         answer = ("I couldn't find Khazna records matching that" + (" with the filters you asked for" if filt else "")
@@ -365,7 +390,9 @@ async def agent(req: AgentRequest, request: Request, response: Response):
         person=_public_result(person, 0) if person else None,
         database_query=" | ".join(t.get("query", "") for t in retrieval["trace"] if t.get("query")),
         trace=[{k: v for k, v in t.items() if k != "error"} for t in retrieval["trace"]],
-        portal_search_url=f"{PURE_PORTAL_URL}/en/{portal_path}/?search={quote_plus(search_term)}",
+        portal_search_url=_portal_url(portal_path, search_term,
+                                      "PartOfNameOrTitle" if plan.intent == "author_search" and plan.author_name
+                                      else "RelatedConcepts" if plan.intent == "expert_search" else None),
         follow_up_suggestions=_followups(plan, retrieval) if results else [],
     )
 

pipeline.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import unicodedata
 from datetime import datetime
 import math
 import os
@@ -86,7 +87,8 @@ Rules:
 - Research projects, grants, funded research => project_search. Instruments, equipment, facilities, labs with a device => equipment_search.
 - "Who does KU collaborate with", partner universities/institutions, international collaboration => collab_search.
 - Follow-ups ("only 2024 ones", "more by her", "what about desalination?") must be resolved using the conversation history.
-- For author_search put the name in author_name; put any topic words in keyword_queries (may be empty).
+- For author_search put the name in author_name exactly as the user wrote it (one word like "Kumar" is fine); put any topic words in keyword_queries (may be empty).
+- A message that is only a person's name (e.g. "Kumar", "KUMAR Padmanabhan", "Dr. Fatima") is author_search.
 - Today's year is {year}.
 
 Examples:
@@ -103,6 +105,8 @@ Examples:
 "Who at KU works on robotics for agriculture?" => expert_search, ["agricultural robotics","robotics agriculture"], broad_query="robotics"
 "Find a supervisor for battery research" => expert_search, ["lithium-ion batteries","battery materials"], broad_query="batteries"
 "Show me Jane Smith's profile" => author_search, author_name="Jane Smith", keyword_queries=[]
+"Kumar" => author_search, author_name="Kumar", keyword_queries=[]
+"Publications by Kumar Padmanabhan on machine learning" => author_search, author_name="Kumar Padmanabhan", keyword_queries=["machine learning"]
 "Which KU research centres work on 6G?" => org_search, ["6G"], broad_query="wireless"
 "Department of Mechanical Engineering" => org_search, ["Mechanical Engineering"]
 "Datasets on air quality in the UAE" => dataset_search, ["air quality UAE","air pollution"], broad_query="air quality"
@@ -128,7 +132,11 @@ def _heuristic_plan(question: str, year: int) -> QueryPlan:
     yrs = [int(y) for y in re.findall(r"\b(19[89]\d|20[0-4]\d)\b", question)]
     recent = bool(re.search(r"\b(recent|latest|new)\b", question, re.I))
     intent = "topic_search"
-    named = re.search(r"\b(?i:profile|publications|papers|work|research)\b[^?!]*?\b(?i:of|by)\s+((?:Dr\.?\s+|Prof\.?\s+)?[A-Z][\w'.-]+(?:\s+[A-Z][\w'.-]+){1,3})", question)
+    if (re.fullmatch(r"\s*(?:(?:Dr|Prof)\.?\s+)?[A-Z][A-Za-z'.-]+(?:\s+[A-Z][A-Za-z'.-]+){0,3}\s*", question)
+            and question.strip().lower().strip("!.") not in {"hi", "hello", "hey", "thanks", "thank you", "ok", "okay", "help"}):
+        return QueryPlan(intent="author_search", standalone_question=question,
+                         author_name=re.sub(r"^\s*(Dr|Prof)\.?\s+", "", question).strip(), keyword_queries=[])
+    named = re.search(r"\b(?i:profile|publications|papers|work|research)\b[^?!]*?\b(?i:of|by)\s+((?:Dr\.?\s+|Prof\.?\s+)?[A-Z][\w'.-]+(?:\s+[A-Z][\w'.-]+){0,3})\s*[?.!]?\s*$", question)
     if named:
         name = re.sub(r"^(Dr|Prof)\.?\s+", "", named.group(1))
         return QueryPlan(intent="author_search", standalone_question=question, author_name=name, keyword_queries=[])
@@ -293,17 +301,76 @@ def rank(variant_hits: list[list[dict]], plan: QueryPlan) -> list[dict]:
 RETRIEVE_SIZE = int(os.environ.get("PURE_RETRIEVE_SIZE", "25"))
 
 
-async def _retrieve_outputs(pure: PureClient, plan: QueryPlan, search=None) -> dict:
+_TITLES = {"dr", "prof", "professor", "mr", "mrs", "ms", "miss", "eng", "engr"}
+MAX_CANDIDATES = int(os.environ.get("MAX_NAME_CANDIDATES", "12"))
+
+
+def _name_tokens(s: str) -> list[str]:
+    s = unicodedata.normalize("NFKD", s or "").encode("ascii", "ignore").decode().lower()
+    return [t for t in re.split(r"[^a-z]+", s) if len(t) > 1 and t not in _TITLES]
+
+
+def match_people(query: str, people: list[dict]) -> tuple[list[dict], list[dict]]:
+    """Return (matches, exact_full_name_matches) for a typed name.
+
+    A person matches when EVERY word the user typed equals one of their name words,
+    in any position (first, middle or last). Only if nobody matches exactly do we
+    accept prefix matches ('Kumar' → 'Kumaran'). Matches are ordered surname-first.
+    """
+    q = _name_tokens(query)
+    if not q:
+        return [], []
+    exact, prefix = [], []
+    for p in people:
+        tokens = _name_tokens(p.get("name", ""))
+        if all(t in tokens for t in q):
+            exact.append(p)
+        elif all(any(n.startswith(t) for n in tokens) for t in q):
+            prefix.append(p)
+    matches = exact or prefix
+    full = [p for p in matches if set(_name_tokens(p.get("name", ""))) == set(q)]
+
+    def order(p):
+        last = set(_name_tokens(p.get("last_name", "")))
+        return (0 if set(q) & last else 1, p.get("name", ""))
+    return sorted(matches, key=order), full
+
+
+async def _resolve_person(pure: PureClient, plan: QueryPlan, person_uuid: str | None, trace: list[dict]):
+    """→ (person, candidates). candidates is non-empty only when the name is ambiguous."""
+    if person_uuid:
+        person = await pure.get_person(person_uuid)
+        trace.append({"endpoint": f"persons/{person_uuid}", "hits": 1 if person else 0})
+        return person, []
+    people = await pure.search_persons(plan.author_name, size=50)
+    trace.append({"endpoint": "persons/search", "query": plan.author_name, "hits": len(people)})
+    matches, full = match_people(plan.author_name, people)
+    if not matches and len(people) == 1:
+        matches = people
+    if len(full) == 1:
+        return full[0], []
+    if len(matches) == 1:
+        return matches[0], []
+    if len(matches) >= 2:
+        return None, matches
+    return None, []
+
+
+async def _retrieve_outputs(pure: PureClient, plan: QueryPlan, search=None, person_uuid: str | None = None) -> dict:
     search = search or pure.search_research_outputs
     trace: list[dict] = []
     person = None
     total = 0
 
-    if plan.intent == "author_search" and plan.author_name:
-        people = await pure.search_persons(plan.author_name, size=5)
-        trace.append({"endpoint": "persons/search", "query": plan.author_name, "hits": len(people)})
-        if people:
-            person = people[0]
+    if plan.intent == "author_search" and (plan.author_name or person_uuid):
+        person, candidates = await _resolve_person(pure, plan, person_uuid, trace)
+        if candidates:  # ambiguous name: ask the user to choose instead of guessing
+            shown = candidates[:MAX_CANDIDATES]
+            await pure.fill_org_names(shown)
+            return {"results": [{**c, "choose": True} for c in shown], "unfiltered": len(candidates),
+                    "total": len(candidates), "person": None, "trace": trace,
+                    "clarify": {"name": plan.author_name, "count": len(candidates), "shown": len(shown)}}
+        if person:
             await pure.fill_org_names([person])
             outs = await pure.person_research_outputs(person, size=100)
             trace.append({"endpoint": f"persons/{person['uuid']}/research-outputs", "hits": len(outs)})
@@ -314,7 +381,8 @@ async def _retrieve_outputs(pure: PureClient, plan: QueryPlan, search=None) -> d
             variant_hits = [outs]
             total = len(outs)
         else:  # no person record: treat the name as a free-text query
-            plan.keyword_queries = [f"{plan.author_name} {q}".strip() for q in (plan.keyword_queries or [""])]
+            plan.keyword_queries = [f"{plan.author_name or ''} {q}".strip() for q in (plan.keyword_queries or [""])]
+            plan.keyword_queries = [q for q in plan.keyword_queries if q] or [plan.standalone_question]
             plan.intent = "topic_search"
 
     if plan.intent != "author_search" or person is None:
@@ -513,7 +581,10 @@ async def _retrieve_datasets(pure: PureClient, plan: QueryPlan) -> dict:
     return r
 
 
-async def retrieve(pure: PureClient, plan: QueryPlan) -> dict:
+async def retrieve(pure: PureClient, plan: QueryPlan, person_uuid: str | None = None) -> dict:
+    if person_uuid:  # the user picked a specific researcher from a list
+        plan.intent = "author_search"
+        return await _retrieve_outputs(pure, plan, person_uuid=person_uuid)
     concept = None
     if plan.intent in ("topic_search", "thesis_search", "expert_search", "project_search", "collab_search", "count"):
         concept = await _expand_with_concepts(pure, plan)

pure_client.py

@@ -209,9 +209,12 @@ def normalize_person(item: dict, portal_url: str) -> dict:
         if org.get("uuid"):
             orgs.append({"uuid": org["uuid"], "name": _loc(org.get("name"))})
     # NB: email / phone are intentionally never copied out of the record.
+    nm = item.get("name") if isinstance(item.get("name"), dict) else {}
     return {
         "kind": "person",
         "uuid": uuid,
+        "first_name": (nm.get("firstName") or "").strip(),
+        "last_name": (nm.get("lastName") or "").strip(),
         "name": _person_name(item.get("name")),
         "title": _person_name(item.get("name")),
         "job_titles": list(dict.fromkeys(titles))[:3],