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

open_pharma_plugins_hcp_intelligence/tools/search_congresses.py

@@ -0,0 +1,134 @@
+"""search_congresses — web search for conference speaking roles and KOL signals."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+_CONGRESS_MAP: dict[str, list[str]] = {
+    "oncology": ["ASCO", "ESMO", "AACR", "ASH"],
+    "hematology": ["ASH", "EHA", "ASCO"],
+    "cardiology": ["AHA", "ESC", "ACC", "HRS"],
+    "endocrinology": ["ADA", "EASD", "ENDO"],
+    "diabetes": ["ADA", "EASD", "ENDO"],
+    "neurology": ["AAN", "EAN", "AES"],
+    "respiratory": ["ATS", "ERS", "CHEST"],
+    "pulmonology": ["ATS", "ERS", "CHEST"],
+    "immunology": ["ACR", "EULAR", "AAI"],
+    "rheumatology": ["ACR", "EULAR", "AAI"],
+    "infectious disease": ["IDWeek", "ECCMID", "CROI"],
+    "paediatrics": ["AAP", "ESPID", "EPA"],
+    "pediatrics": ["AAP", "ESPID", "EPA"],
+    "gastroenterology": ["DDW", "UEG", "AASLD"],
+    "hepatology": ["AASLD", "EASL", "DDW"],
+    "nephrology": ["ASN", "ERA", "WCN"],
+    "dermatology": ["AAD", "EADV", "SID"],
+    "ophthalmology": ["AAO", "ARVO", "EURETINA"],
+    "urology": ["AUA", "EAU"],
+    "psychiatry": ["APA", "EPA", "WPA"],
+    "surgery": ["ACS", "EAES", "SAGES"],
+}
+
+
+def _resolve_congresses(
+    specialty: str | None,
+    therapeutic_area: str | None,
+    explicit: list[str] | None,
+) -> list[str]:
+    if explicit:
+        return explicit
+
+    for key_source in (therapeutic_area, specialty):
+        if not key_source:
+            continue
+        needle = key_source.strip().lower()
+        for key, congresses in _CONGRESS_MAP.items():
+            if key in needle or needle in key:
+                return congresses
+
+    if specialty:
+        return [specialty.strip()]
+    return ["medical congress"]
+
+
+class SearchCongressesArgs(BaseModel):
+    name: str = Field(description="Full name of the healthcare professional")
+    specialty: str | None = Field(
+        default=None,
+        description="Medical specialty (used to select relevant congresses if congress_names is not provided)",
+    )
+    therapeutic_area: str | None = Field(
+        default=None,
+        description=("Therapeutic area to narrow congress search (e.g. 'oncology', 'cardiology', 'diabetes')"),
+    )
+    country: str | None = Field(default=None, description="Country of practice")
+    congress_names: list[str] | None = Field(
+        default=None,
+        description=(
+            "Specific congress names to search (e.g. ['ASCO', 'ESMO']). "
+            "If not provided, the tool selects congresses based on specialty "
+            "or therapeutic_area."
+        ),
+    )
+    max_results: int = Field(
+        default=15,
+        ge=1,
+        le=30,
+        description="Maximum web results to return",
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "search_congresses",
+    "description": (
+        "Search for an HCP's conference speaking roles, poster presentations, "
+        "and advisory board visibility at major medical congresses. Results "
+        "signal KOL status: invited keynote, symposium speaker, oral "
+        "presentation, poster presenter, session chair, or moderator. "
+        "Provide specialty or therapeutic_area to auto-select relevant "
+        "congresses, or pass explicit congress_names."
+    ),
+    "args": SearchCongressesArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+    from datetime import datetime, timezone
+
+    from .search_hcp_web import _backend_name, _web_search
+
+    congresses = _resolve_congresses(
+        arguments.get("specialty"),
+        arguments.get("therapeutic_area"),
+        arguments.get("congress_names"),
+    )
+
+    congress_clause = " OR ".join(congresses)
+    role_clause = (
+        "speaker OR lecture OR presentation OR poster OR symposium "
+        "OR chair OR moderator OR plenary OR keynote OR abstract"
+    )
+
+    query_parts = [
+        f'"{arguments["name"]}"',
+        f"({congress_clause})",
+        f"({role_clause})",
+    ]
+    if arguments.get("country"):
+        query_parts.append(arguments["country"])
+
+    query = " ".join(query_parts)
+    max_results = arguments.get("max_results", 15)
+
+    results = _web_search(query, max_results)
+
+    output = {
+        "query": query,
+        "results": results,
+        "congresses_searched": congresses,
+        "search_backend": _backend_name(),
+        "searched_at": datetime.now(timezone.utc).isoformat(),
+    }
+    return [{"type": "text", "text": json.dumps(output, indent=2)}]

open_pharma_plugins_hcp_intelligence/tools/search_grants.py

@@ -0,0 +1,181 @@
+"""search_grants — query NIH RePORTER for research grant funding, with web fallback."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SearchGrantsArgs(BaseModel):
+    pi_name: str = Field(description="Full name of the principal investigator (e.g. 'Yvonne Lim')")
+    institution: str | None = Field(
+        default=None,
+        description="Institution or organization name to narrow results",
+    )
+    keywords: str | None = Field(
+        default=None,
+        description="Research topic keywords (e.g. 'immunotherapy melanoma')",
+    )
+    country: str | None = Field(
+        default=None,
+        description="Country of the PI (used for web fallback when NIH RePORTER returns no results)",
+    )
+    active_only: bool = Field(
+        default=False,
+        description="If true, only return currently active grants",
+    )
+    max_results: int = Field(
+        default=20,
+        ge=1,
+        le=50,
+        description="Maximum grants to return",
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "search_grants",
+    "description": (
+        "Search for research grant funding awarded to a principal investigator. "
+        "Queries NIH RePORTER (covers NIH, NSF, and other US federal agencies) and "
+        "falls back to web search for non-US funding bodies. Returns grant number, "
+        "title, PI, institution, award amount, dates, activity status, and agency. "
+        "Active funding signals an active researcher; amounts indicate research "
+        "program scale; co-PIs reveal collaboration networks."
+    ),
+    "args": SearchGrantsArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+    from datetime import datetime, timezone
+
+    pi_name = arguments["pi_name"]
+    institution = arguments.get("institution")
+    keywords = arguments.get("keywords")
+    country = arguments.get("country")
+    active_only = arguments.get("active_only", False)
+    max_results = arguments.get("max_results", 20)
+
+    grants, total_count, source = _search_nih_reporter(pi_name, institution, keywords, active_only, max_results)
+
+    web_fallback_results = None
+    if total_count == 0 and country and country.lower() not in ("us", "usa", "united states"):
+        web_fallback_results = _web_fallback(pi_name, institution, country)
+        source = "web_fallback"
+
+    query_desc = f"PI: {pi_name}"
+    if institution:
+        query_desc += f", institution: {institution}"
+    if keywords:
+        query_desc += f", keywords: {keywords}"
+    if active_only:
+        query_desc += " (active only)"
+
+    output: dict[str, Any] = {
+        "query": query_desc,
+        "total_count": total_count,
+        "grants": grants,
+        "source": source,
+        "searched_at": datetime.now(timezone.utc).isoformat(),
+    }
+    if web_fallback_results is not None:
+        output["web_fallback_results"] = web_fallback_results
+
+    return [{"type": "text", "text": json.dumps(output, indent=2)}]
+
+
+def _search_nih_reporter(
+    pi_name: str,
+    institution: str | None,
+    keywords: str | None,
+    active_only: bool,
+    max_results: int,
+) -> tuple[list[dict], int, str]:
+    import json
+    import urllib.request
+
+    criteria: dict[str, Any] = {
+        "pi_names": [{"any_name": pi_name}],
+    }
+    if institution:
+        criteria["org_names"] = [institution]
+    if active_only:
+        criteria["is_active"] = True
+    if keywords:
+        criteria["advanced_text_search"] = {
+            "operator": "and",
+            "search_field": "terms",
+            "search_text": keywords,
+        }
+
+    body = json.dumps(
+        {
+            "criteria": criteria,
+            "offset": 0,
+            "limit": max_results,
+            "sort_field": "project_start_date",
+            "sort_order": "desc",
+        }
+    ).encode()
+
+    req = urllib.request.Request(
+        "https://api.reporter.nih.gov/v2/projects/search",
+        data=body,
+        headers={"Content-Type": "application/json", "Accept": "application/json"},
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            data = json.loads(resp.read())
+    except Exception:
+        return [], 0, "nih_reporter"
+
+    total_count = data.get("meta", {}).get("total", 0)
+    results = data.get("results", [])
+
+    grants = []
+    for r in results:
+        pis = r.get("principal_investigators", [])
+        pi_full_name = pis[0].get("full_name", "") if pis else ""
+
+        org = r.get("organization", {})
+        org_name = org.get("org_name", "")
+
+        abstract = r.get("abstract_text") or ""
+        if len(abstract) > 500:
+            abstract = abstract[:497] + "..."
+
+        app_id = r.get("appl_id", "")
+
+        grants.append(
+            {
+                "project_number": r.get("project_num", ""),
+                "title": r.get("project_title", ""),
+                "abstract": abstract,
+                "pi_name": pi_full_name,
+                "institution": org_name,
+                "award_amount": r.get("award_amount"),
+                "start_date": r.get("project_start_date"),
+                "end_date": r.get("project_end_date"),
+                "agency_code": r.get("agency_code", ""),
+                "is_active": r.get("is_active", False),
+                "source_url": f"https://reporter.nih.gov/project-details/{app_id}" if app_id else "",
+            }
+        )
+
+    return grants, total_count, "nih_reporter"
+
+
+def _web_fallback(pi_name: str, institution: str | None, country: str | None) -> list[dict]:
+    from .search_hcp_web import _web_search
+
+    parts = [f'"{pi_name}"', "(research grant OR funding OR funded by)"]
+    if institution:
+        parts.append(institution)
+    if country:
+        parts.append(country)
+    query = " ".join(parts)
+
+    return _web_search(query, 10)

open_pharma_plugins_hcp_intelligence/tools/search_guidelines.py

@@ -0,0 +1,238 @@
+"""search_guidelines — guideline authorship (PubMed) + regulatory advisory roles (web)."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class SearchGuidelinesArgs(BaseModel):
+    name: str = Field(description="Full name of the HCP (e.g. 'Yvonne Lim')")
+    specialty: str | None = Field(
+        default=None,
+        description="Medical specialty to narrow guideline search (e.g. 'Paediatric Medicine')",
+    )
+    scope: Literal["guidelines", "regulatory", "both"] = Field(
+        default="both",
+        description=(
+            "What to search: 'guidelines' for PubMed guideline/consensus publications, "
+            "'regulatory' for FDA/EMA/WHO advisory committee rosters, or 'both'."
+        ),
+    )
+    therapeutic_area: str | None = Field(
+        default=None,
+        description="Therapeutic area or disease to narrow the guideline search (e.g. 'diabetes')",
+    )
+    max_results: int = Field(
+        default=20,
+        ge=1,
+        le=50,
+        description="Maximum results to return per scope (guidelines and regulatory each up to this limit)",
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "search_guidelines",
+    "description": (
+        "Search for an HCP's clinical guideline authorship and regulatory advisory "
+        "committee roles. Guideline authorship (via PubMed) and regulatory influence "
+        "(FDA/EMA/WHO advisory membership, via web search) are top-tier KOL signals. "
+        "Use scope to search guidelines only, regulatory only, or both."
+    ),
+    "args": SearchGuidelinesArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+    from datetime import datetime, timezone
+
+    scope = arguments.get("scope", "both")
+
+    guideline_publications: list[dict] = []
+    total_guidelines_found = 0
+    guideline_query = ""
+
+    regulatory_results: list[dict] = []
+    total_regulatory_results = 0
+    regulatory_query = ""
+
+    if scope in ("guidelines", "both"):
+        guideline_query, total_guidelines_found, guideline_publications = _search_guideline_publications(arguments)
+
+    if scope in ("regulatory", "both"):
+        regulatory_query, regulatory_results = _search_regulatory_roles(arguments)
+        total_regulatory_results = len(regulatory_results)
+
+    query = guideline_query or regulatory_query
+    if guideline_query and regulatory_query:
+        query = f"guidelines: {guideline_query} | regulatory: {regulatory_query}"
+
+    output = {
+        "query": query,
+        "guideline_publications": guideline_publications,
+        "regulatory_results": regulatory_results,
+        "total_guidelines_found": total_guidelines_found,
+        "total_regulatory_results": total_regulatory_results,
+        "scope": scope,
+        "searched_at": datetime.now(timezone.utc).isoformat(),
+    }
+    return [{"type": "text", "text": json.dumps(output, indent=2)}]
+
+
+def _search_guideline_publications(
+    arguments: dict[str, Any],
+) -> tuple[str, int, list[dict]]:
+    """Query PubMed for guideline/consensus publications authored by the HCP."""
+    import json
+    import urllib.parse
+    import urllib.request
+
+    from shared.env import get_env
+
+    api_key = get_env("NCBI_API_KEY", "")
+    base = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
+
+    name = arguments["name"]
+    pub_type_filter = (
+        "(Practice Guideline[pt] OR Guideline[pt] "
+        "OR Consensus Development Conference[pt] "
+        "OR Consensus Development Conference, NIH[pt])"
+    )
+    parts = [f"{name}[Author]", pub_type_filter]
+
+    if arguments.get("therapeutic_area"):
+        parts.append(arguments["therapeutic_area"])
+    if arguments.get("specialty"):
+        parts.append(arguments["specialty"])
+
+    query = " AND ".join(parts)
+    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: list[dict] = []
+    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_guideline_xml(xml_data)
+
+    return query, total_count, publications
+
+
+def _parse_guideline_xml(xml_bytes: bytes) -> list[dict]:
+    """Parse PubMed efetch XML into guideline publication records."""
+    import re
+    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:
+                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:
+                n = last.text or ""
+                if fore is not None and fore.text:
+                    n += f" {fore.text}"
+                authors.append(n)
+
+        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,
+                "publication_types": pub_types,
+                "source_url": f"https://pubmed.ncbi.nlm.nih.gov/{pmid}/" if pmid else "",
+            }
+        )
+
+    return pubs
+
+
+def _search_regulatory_roles(arguments: dict[str, Any]) -> tuple[str, list[dict]]:
+    """Web-search for FDA/EMA/WHO advisory committee membership."""
+    from .search_hcp_web import _web_search
+
+    name = arguments["name"]
+    max_results = arguments.get("max_results", 20)
+
+    query = (
+        f'"{name}" '
+        "(FDA advisory committee OR EMA CHMP OR EMA SAWP OR EMA PDCO "
+        "OR WHO expert advisory OR advisory board roster "
+        "OR guideline committee member)"
+    )
+
+    results = _web_search(query, max_results)
+    return query, results

open_pharma_plugins_hcp_intelligence/tools/search_hco_web.py

@@ -0,0 +1,73 @@
+"""search_hco_web — web search tailored for HCO profiling."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SearchHcoWebArgs(BaseModel):
+    name: str = Field(description="Name of the healthcare organization")
+    country: str | None = Field(default=None, description="Country")
+    organization_type: str | None = Field(
+        default=None,
+        description="Type: hospital, clinic, research institute, medical school, etc.",
+    )
+    query_focus: str | None = Field(
+        default=None,
+        description=(
+            "Optional focus to append to the search query, e.g. "
+            "'departments centres of excellence', 'bed capacity annual report', "
+            "'accreditation ranking', 'history founded'"
+        ),
+    )
+    max_results: int = Field(
+        default=10,
+        ge=1,
+        le=20,
+        description="Maximum web results to return",
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "search_hco_web",
+    "description": (
+        "Search the web for information about a Healthcare Organization (hospital, "
+        "clinic, research centre, medical school). Constructs a targeted query to find "
+        "the organization's official site, Wikipedia entry, accreditation status, "
+        "departments, bed capacity, and institutional history. Use query_focus to "
+        "steer toward specific profile sections."
+    ),
+    "args": SearchHcoWebArgs,
+}
+
+
+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("country"):
+        query_parts.append(arguments["country"])
+    if arguments.get("organization_type"):
+        query_parts.append(arguments["organization_type"])
+    if arguments.get("query_focus"):
+        query_parts.append(arguments["query_focus"])
+    else:
+        query_parts.append("hospital OR medical centre OR healthcare")
+
+    query = " ".join(query_parts)
+    max_results = arguments.get("max_results", 10)
+
+    from .search_hcp_web import _backend_name, _web_search
+
+    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)}]