open-pharma-plugins 2.2.0__py3-none-any.whl

open_pharma_plugins_hcp_intelligence/tools/search_hcp_web.py

@@ -0,0 +1,199 @@
+"""search_hcp_web — web search tailored for HCP profiling."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SearchHcpWebArgs(BaseModel):
+    name: str = Field(description="Full name of the healthcare professional")
+    specialty: str | None = Field(default=None, description="Medical specialty (e.g. 'Cardiology')")
+    country: str | None = Field(default=None, description="Country of practice")
+    institution: str | None = Field(default=None, description="Known institution or affiliation")
+    query_focus: str | None = Field(
+        default=None,
+        description=(
+            "Optional focus to append to the search query, e.g. "
+            "'biography', 'society membership', 'education qualifications', "
+            "'advisory board committee'"
+        ),
+    )
+    max_results: int = Field(
+        default=10,
+        ge=1,
+        le=20,
+        description="Maximum web results to return",
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "search_hcp_web",
+    "description": (
+        "Search the web for information about a specific Healthcare Professional. "
+        "Constructs a targeted query from the HCP's name, specialty, country, and "
+        "institution to find institutional profiles, society memberships, conference "
+        "appearances, and biographical information. Returns URLs, titles, and snippets. "
+        "Use query_focus to steer toward specific profile sections (e.g. 'education', "
+        "'advisory board')."
+    ),
+    "args": SearchHcpWebArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+    from datetime import datetime, timezone
+
+    query_parts = [f'"{arguments["name"]}"']
+    if arguments.get("specialty"):
+        query_parts.append(arguments["specialty"])
+    if arguments.get("country"):
+        query_parts.append(arguments["country"])
+    if arguments.get("institution"):
+        query_parts.append(arguments["institution"])
+    if arguments.get("query_focus"):
+        query_parts.append(arguments["query_focus"])
+    else:
+        query_parts.append("doctor OR physician OR professor OR consultant")
+
+    query = " ".join(query_parts)
+    max_results = arguments.get("max_results", 10)
+
+    results = _web_search(query, max_results)
+
+    output = {
+        "query": query,
+        "results": results,
+        "search_backend": _backend_name(),
+        "searched_at": datetime.now(timezone.utc).isoformat(),
+    }
+    return [{"type": "text", "text": json.dumps(output, indent=2)}]
+
+
+def _backend_name() -> str:
+    from shared.env import get_env
+
+    backend = get_env("OPEN_PHARMA_SEARCH_BACKEND", "auto").strip().lower()
+    if backend != "auto":
+        return backend
+    if get_env("SERPER_API_KEY", ""):
+        return "serper"
+    if get_env("TAVILY_API_KEY", ""):
+        return "tavily"
+    if get_env("EXA_API_KEY", ""):
+        return "exa"
+    return "none"
+
+
+def _web_search(query: str, max_results: int) -> list[dict]:
+    backend = _backend_name()
+    if backend == "serper":
+        return _serper_search(query, max_results)
+    if backend == "tavily":
+        return _tavily_search(query, max_results)
+    if backend == "exa":
+        return _exa_search(query, max_results)
+    raise RuntimeError("No web search backend configured. Set SERPER_API_KEY, TAVILY_API_KEY, or EXA_API_KEY.")
+
+
+def _serper_search(query: str, max_results: int) -> list[dict]:
+    import json
+    import urllib.request
+
+    from shared.env import get_env
+
+    body = json.dumps({"q": query, "num": max_results}).encode()
+    req = urllib.request.Request(
+        "https://google.serper.dev/search",
+        data=body,
+        headers={
+            "X-API-KEY": get_env("SERPER_API_KEY", ""),
+            "Content-Type": "application/json",
+        },
+    )
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        data = json.loads(resp.read())
+
+    return [
+        {
+            "url": r.get("link", ""),
+            "title": r.get("title", ""),
+            "snippet": r.get("snippet", ""),
+            "published_date": r.get("date"),
+            "domain": r.get("link", "").split("/")[2] if "/" in r.get("link", "") else None,
+        }
+        for r in data.get("organic", [])
+    ]
+
+
+def _tavily_search(query: str, max_results: int) -> list[dict]:
+    import json
+    import urllib.request
+
+    from shared.env import get_env
+
+    body = json.dumps(
+        {
+            "api_key": get_env("TAVILY_API_KEY", ""),
+            "query": query,
+            "max_results": max_results,
+            "search_depth": "advanced",
+        }
+    ).encode()
+    req = urllib.request.Request(
+        "https://api.tavily.com/search",
+        data=body,
+        headers={"Content-Type": "application/json"},
+    )
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        data = json.loads(resp.read())
+
+    return [
+        {
+            "url": r.get("url", ""),
+            "title": r.get("title", ""),
+            "snippet": r.get("content", ""),
+            "published_date": r.get("published_date"),
+            "domain": r.get("url", "").split("/")[2] if "/" in r.get("url", "") else None,
+        }
+        for r in data.get("results", [])
+    ]
+
+
+def _exa_search(query: str, max_results: int) -> list[dict]:
+    import json
+    import urllib.request
+
+    from shared.env import get_env
+
+    body = json.dumps(
+        {
+            "query": query,
+            "numResults": max_results,
+            "useAutoprompt": True,
+            "contents": {"text": {"maxCharacters": 500}},
+        }
+    ).encode()
+    req = urllib.request.Request(
+        "https://api.exa.ai/search",
+        data=body,
+        headers={
+            "x-api-key": get_env("EXA_API_KEY", ""),
+            "Content-Type": "application/json",
+        },
+    )
+    with urllib.request.urlopen(req, timeout=15) as resp:
+        data = json.loads(resp.read())
+
+    return [
+        {
+            "url": r.get("url", ""),
+            "title": r.get("title", ""),
+            "snippet": r.get("text", ""),
+            "published_date": r.get("publishedDate"),
+            "domain": r.get("url", "").split("/")[2] if "/" in r.get("url", "") else None,
+        }
+        for r in data.get("results", [])
+    ]

open_pharma_plugins_hcp_intelligence/tools/search_orcid.py

@@ -0,0 +1,214 @@
+"""search_orcid — query the ORCID public API for researcher profiles."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SearchOrcidArgs(BaseModel):
+    name: str = Field(
+        description="Full name of the researcher (e.g. 'Yvonne Lim')",
+    )
+    affiliation: str | None = Field(
+        default=None,
+        description="Known institution to help disambiguate (e.g. 'KK Women's and Children's Hospital')",
+    )
+    orcid_id: str | None = Field(
+        default=None,
+        description="If the ORCID ID is already known (e.g. '0000-0002-1234-5678'), fetch directly instead of searching",
+    )
+    max_results: int = Field(
+        default=5,
+        ge=1,
+        le=10,
+        description="Maximum candidate profiles to return when searching by name",
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "search_orcid",
+    "description": (
+        "Search the ORCID registry for a researcher's profile. ORCID provides "
+        "author-curated, globally unique researcher identifiers with verified "
+        "affiliations, education history, publication counts, and funding. Call "
+        "early in the HCP profiling workflow — it disambiguates common names and "
+        "fills education/affiliation gaps cheaply. Pass an orcid_id to fetch a "
+        "known profile directly, or search by name and optional affiliation."
+    ),
+    "args": SearchOrcidArgs,
+}
+
+
+_BASE = "https://pub.orcid.org/v3.0"
+_HEADERS = {"Accept": "application/json"}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+    from datetime import datetime, timezone
+
+    orcid_id = arguments.get("orcid_id")
+    if orcid_id:
+        profile = _fetch_profile(orcid_id)
+        output = {
+            "query": orcid_id,
+            "total_found": 1 if profile else 0,
+            "profiles": [profile] if profile else [],
+            "source": "orcid",
+            "searched_at": datetime.now(timezone.utc).isoformat(),
+        }
+        return [{"type": "text", "text": json.dumps(output, indent=2)}]
+
+    name = arguments["name"]
+    affiliation = arguments.get("affiliation")
+    max_results = arguments.get("max_results", 5)
+
+    query = _build_query(name, affiliation)
+    orcid_ids = _search_ids(query, max_results)
+
+    profiles = []
+    for oid in orcid_ids:
+        p = _fetch_profile(oid)
+        if p:
+            profiles.append(p)
+
+    output = {
+        "query": query,
+        "total_found": len(orcid_ids),
+        "profiles": profiles,
+        "source": "orcid",
+        "searched_at": datetime.now(timezone.utc).isoformat(),
+    }
+    return [{"type": "text", "text": json.dumps(output, indent=2)}]
+
+
+def _build_query(name: str, affiliation: str | None) -> str:
+    parts = name.strip().split()
+    if len(parts) >= 2:
+        family = parts[-1]
+        given = " ".join(parts[:-1])
+        q = f"family-name:{family} AND given-names:{given}"
+    else:
+        q = f"family-name:{name}"
+
+    if affiliation:
+        q += f" AND affiliation-org-name:{affiliation}"
+    return q
+
+
+def _search_ids(query: str, max_results: int) -> list[str]:
+    import json
+    import urllib.parse
+    import urllib.request
+
+    url = f"{_BASE}/search/?q={urllib.parse.quote(query)}&rows={max_results}"
+    req = urllib.request.Request(url, headers=_HEADERS)
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            data = json.loads(resp.read())
+    except Exception:
+        return []
+
+    results = data.get("result", []) or []
+    ids = []
+    for r in results:
+        oid = r.get("orcid-identifier", {}).get("path")
+        if oid:
+            ids.append(oid)
+    return ids
+
+
+def _fetch_profile(orcid_id: str) -> dict | None:
+    import json
+    import urllib.request
+
+    url = f"{_BASE}/{orcid_id}"
+    req = urllib.request.Request(url, headers=_HEADERS)
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            data = json.loads(resp.read())
+    except Exception:
+        return None
+
+    return _extract_profile(orcid_id, data)
+
+
+def _extract_profile(orcid_id: str, data: dict) -> dict:
+    person = data.get("person", {}) or {}
+    activities = data.get("activities-summary", {}) or {}
+
+    name_obj = person.get("name", {}) or {}
+    given = (name_obj.get("given-names", {}) or {}).get("value", "")
+    family = (name_obj.get("family-name", {}) or {}).get("value", "")
+
+    bio_obj = person.get("biography", {}) or {}
+    biography = bio_obj.get("content", "") or ""
+    if len(biography) > 500:
+        biography = biography[:497] + "..."
+
+    education = _extract_affiliations(activities.get("educations", {}) or {}, "education-summary")
+    employment = _extract_affiliations(activities.get("employments", {}) or {}, "employment-summary")
+
+    work_groups = (activities.get("works", {}) or {}).get("group", []) or []
+    funding_groups = (activities.get("fundings", {}) or {}).get("group", []) or []
+    review_groups = (activities.get("peer-reviews", {}) or {}).get("group", []) or []
+
+    return {
+        "orcid_id": orcid_id,
+        "given_names": given,
+        "family_name": family,
+        "biography": biography or None,
+        "education": education,
+        "employment": employment,
+        "publication_count": len(work_groups),
+        "funding_count": len(funding_groups),
+        "peer_review_count": len(review_groups),
+        "profile_url": f"https://orcid.org/{orcid_id}",
+    }
+
+
+def _extract_affiliations(section: dict, summary_key: str) -> list[dict]:
+    groups = section.get("affiliation-group", []) or []
+    results = []
+    for group in groups:
+        summaries = group.get("summaries", []) or []
+        for entry in summaries:
+            summary = entry.get(summary_key, {}) or {}
+            org = (summary.get("organization", {}) or {}).get("name", "")
+            role = (summary.get("role-title") or "") if summary_key == "employment-summary" else ""
+            degree = (summary.get("role-title") or "") if summary_key == "education-summary" else ""
+            dept = summary.get("department-name") or ""
+
+            start = summary.get("start-date") or {}
+            end = summary.get("end-date") or {}
+            start_year = _year_from(start)
+            end_year = _year_from(end)
+
+            entry_dict: dict[str, Any] = {"institution": org}
+            if summary_key == "education-summary":
+                entry_dict["degree"] = degree
+            else:
+                entry_dict["role"] = role
+            entry_dict["department"] = dept or None
+            entry_dict["start_year"] = start_year
+            entry_dict["end_year"] = end_year
+            results.append(entry_dict)
+    return results
+
+
+def _year_from(date_obj: dict | None) -> int | None:
+    if not date_obj:
+        return None
+    year = date_obj.get("year", {})
+    if isinstance(year, dict):
+        val = year.get("value")
+    else:
+        val = year
+    if val:
+        try:
+            return int(val)
+        except (ValueError, TypeError):
+            pass
+    return None

open_pharma_plugins_hcp_intelligence/tools/search_publications.py

@@ -0,0 +1,207 @@
+"""search_publications — query PubMed via NCBI E-utilities."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SearchPublicationsArgs(BaseModel):
+    author_name: str = Field(description="Full name of the author (e.g. 'Yvonne Lim')")
+    affiliation: str | None = Field(
+        default=None,
+        description="Institution or affiliation to narrow results (e.g. 'KK Women's and Children's Hospital')",
+    )
+    keywords: str | None = Field(
+        default=None,
+        description="Additional search terms: specialty, disease area, or MeSH terms",
+    )
+    year_from: int | None = Field(default=None, description="Earliest publication year (e.g. 2019)")
+    year_to: int | None = Field(default=None, description="Latest publication year (e.g. 2026)")
+    max_results: int = Field(
+        default=20,
+        ge=1,
+        le=100,
+        description="Maximum publications to return",
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "search_publications",
+    "description": (
+        "Search PubMed for publications by a specific author. Returns structured "
+        "records with PMID, title, authors, journal, year, abstract, MeSH terms, and "
+        "DOI. Use to identify an HCP's research output, publication themes, and "
+        "co-author network. Supports filtering by affiliation, keywords, and year range."
+    ),
+    "args": SearchPublicationsArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+    import urllib.parse
+    import urllib.request
+    from datetime import datetime, timezone
+
+    from shared.env import get_env
+
+    api_key = get_env("NCBI_API_KEY", "")
+    base = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
+
+    author = arguments["author_name"]
+    parts = [f"{author}[Author]"]
+    if arguments.get("affiliation"):
+        parts.append(f"{arguments['affiliation']}[Affiliation]")
+    if arguments.get("keywords"):
+        parts.append(arguments["keywords"])
+    query = " AND ".join(parts)
+
+    if arguments.get("year_from") or arguments.get("year_to"):
+        mindate = str(arguments.get("year_from", 1900))
+        maxdate = str(arguments.get("year_to", 2099))
+        query += f" AND {mindate}:{maxdate}[dp]"
+
+    max_results = arguments.get("max_results", 20)
+
+    search_params = {
+        "db": "pubmed",
+        "term": query,
+        "retmax": str(max_results),
+        "retmode": "json",
+        "sort": "date",
+    }
+    if api_key:
+        search_params["api_key"] = api_key
+
+    search_url = f"{base}/esearch.fcgi?{urllib.parse.urlencode(search_params)}"
+    with urllib.request.urlopen(search_url, timeout=30) as resp:
+        search_data = json.loads(resp.read())
+
+    result = search_data.get("esearchresult", {})
+    total_count = int(result.get("count", 0))
+    id_list = result.get("idlist", [])
+
+    publications = []
+    if id_list:
+        fetch_params = {
+            "db": "pubmed",
+            "id": ",".join(id_list),
+            "retmode": "xml",
+            "rettype": "abstract",
+        }
+        if api_key:
+            fetch_params["api_key"] = api_key
+
+        fetch_url = f"{base}/efetch.fcgi?{urllib.parse.urlencode(fetch_params)}"
+        with urllib.request.urlopen(fetch_url, timeout=60) as resp:
+            xml_data = resp.read()
+
+        publications = _parse_pubmed_xml(xml_data)
+
+    output = {
+        "query": query,
+        "total_count": total_count,
+        "publications": publications,
+        "source": "pubmed",
+        "searched_at": datetime.now(timezone.utc).isoformat(),
+    }
+    return [{"type": "text", "text": json.dumps(output, indent=2)}]
+
+
+def _parse_pubmed_xml(xml_bytes: bytes) -> list[dict]:
+    """Parse PubMed efetch XML into structured publication records."""
+    import xml.etree.ElementTree as ET
+
+    root = ET.fromstring(xml_bytes)
+    pubs = []
+
+    for article in root.findall(".//PubmedArticle"):
+        medline = article.find("MedlineCitation")
+        if medline is None:
+            continue
+
+        pmid_el = medline.find("PMID")
+        pmid = pmid_el.text if pmid_el is not None else None
+
+        art = medline.find("Article")
+        if art is None:
+            continue
+
+        title_el = art.find("ArticleTitle")
+        title = "".join(title_el.itertext()) if title_el is not None else ""
+
+        journal_el = art.find("Journal/Title")
+        journal = journal_el.text if journal_el is not None else ""
+
+        year = None
+        for date_path in [
+            "Journal/JournalIssue/PubDate/Year",
+            "ArticleDate/Year",
+        ]:
+            y_el = art.find(date_path)
+            if y_el is not None and y_el.text:
+                year = int(y_el.text)
+                break
+        if year is None:
+            medline_date = art.find("Journal/JournalIssue/PubDate/MedlineDate")
+            if medline_date is not None and medline_date.text:
+                import re
+
+                m = re.search(r"(\d{4})", medline_date.text)
+                if m:
+                    year = int(m.group(1))
+
+        authors = []
+        for au in art.findall("AuthorList/Author"):
+            last = au.find("LastName")
+            fore = au.find("ForeName")
+            if last is not None:
+                name = last.text or ""
+                if fore is not None and fore.text:
+                    name += f" {fore.text}"
+                authors.append(name)
+
+        abstract_parts = []
+        for abs_text in art.findall("Abstract/AbstractText"):
+            label = abs_text.get("Label", "")
+            text = "".join(abs_text.itertext())
+            if label:
+                abstract_parts.append(f"{label}: {text}")
+            else:
+                abstract_parts.append(text)
+        abstract = "\n".join(abstract_parts) if abstract_parts else None
+
+        doi = None
+        for eid in art.findall("ELocationID"):
+            if eid.get("EIdType") == "doi":
+                doi = eid.text
+                break
+
+        mesh_terms = []
+        for mh in medline.findall("MeshHeadingList/MeshHeading/DescriptorName"):
+            if mh.text:
+                mesh_terms.append(mh.text)
+
+        pub_types = []
+        for pt in art.findall("PublicationTypeList/PublicationType"):
+            if pt.text:
+                pub_types.append(pt.text)
+
+        pubs.append(
+            {
+                "pmid": pmid,
+                "title": title,
+                "authors": authors,
+                "journal": journal,
+                "year": year,
+                "doi": doi,
+                "abstract": abstract[:2000] if abstract and len(abstract) > 2000 else abstract,
+                "mesh_terms": mesh_terms,
+                "publication_types": pub_types,
+                "source_url": f"https://pubmed.ncbi.nlm.nih.gov/{pmid}/" if pmid else "",
+            }
+        )
+
+    return pubs