agentdata 0.3.26__py3-none-any.whl

agentdata/healthcare/ctgov.py

@@ -0,0 +1,101 @@
+"""ctgov — ClinicalTrials.gov API v2 (clinical-trial lookup face; keyless; polite tier 2 rps).
+
+Positioning: fresh single lookups on top of the bulk line (us/clinicaltrials full harvest) — sponsor search / status filter / single-NCT semantics.
+TTL: search 7 days (trial records change slowly; the published results page is authoritative).
+Query construction: company → AREA[LeadSponsorName]("…"); status → AREA[OverallStatus](…); a free query expression is AND-joined.
+"""
+
+provider = {
+    "id": "ctgov",
+    "baseUrl": "https://clinicaltrials.gov/api/v2",
+    "rate": {"rps": 2, "burst": 4},
+    "ops": {
+        "search": {"path": "/studies", "ttl": 7 * 86400},
+    },
+}
+
+
+def _row_from_study(s: dict) -> dict:
+    p = s.get("protocolSection") or {}
+    ident = p.get("identificationModule") or {}
+    st = s.get("statusModule") or {}
+    sponsor = ((p.get("sponsorCollaboratorsModule") or {}).get("leadSponsor") or {}).get("name")
+    phases = (p.get("designModule") or {}).get("phases") or []
+    nct = ident.get("nctId")
+    return {
+        "nct_id": nct,
+        "title": ident.get("briefTitle"),
+        "status": st.get("overallStatus"),
+        "phase": " + ".join(phases) or None,
+        "sponsor": sponsor,
+        "start_date": (st.get("startDateStruct") or {}).get("date"),
+        "url": f"https://clinicaltrials.gov/study/{nct}" if nct else None,
+    }
+
+
+def search_trials(company=None, query=None, status=None, limit=10, cache=None, no_cache: bool = False) -> dict:
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    terms = []
+    if company:
+        terms.append(f'AREA[LeadSponsorName]("{company}")')
+    if status:
+        terms.append(f"AREA[OverallStatus]({status})")
+    if query:
+        terms.append(query)
+    if not terms:
+        raise SdkError("op_unknown", provider="ctgov", detail="trials needs at least one of company / query / status")
+    r = call_provider(provider, "search",
+                      {"query.term": " AND ".join(terms),
+                       "pageSize": min(50, max(1, int(limit))), "countTotal": "true"},
+                      cache=cache, no_cache=no_cache)
+    studies = (r["data"] or {}).get("studies") or []
+    return {"total": (r["data"] or {}).get("totalCount"),
+            "rows": [_row_from_study(s) for s in studies], "_meta": r}
+
+
+def search_raw(*, query_term=None, query_titles=None, query_intr=None, query_cond=None,
+               filter_advanced=None, agg_filters=None, fields=None, page_size=20,
+               page_token=None, sort=None, count_total=True, cache=None, no_cache: bool = False) -> dict:
+    """0.2.0 mirror face: upstream param names verbatim (query.term/query.titles/query.intr/query.cond/filter.advanced/
+    aggFilters/fields/pageSize/pageToken/sort/countTotal).
+
+    No cap: the pageSize docs say <=1000 but 1001 was measured returning all 200 rows (probed 2026-10-23, the limit is not enforced) — we only guarantee >=1;
+    a bare call is legal (the upstream default = page 1 of the whole database, countTotal gives the total); a free sort string passes through (measured EnrollmentCount:desc works).
+    0.2.8 added four params (all verified by probing on 2026-10-28): query.titles = title-field search (aspirin 2983→967),
+    query.intr = intervention field (insulin 21109→8229), aggFilters = facet filter (phase:3 → 583; **the value domain is a numeric enum**,
+    spelling PHASE3 gives 0 hits, not an error), fields = row slimming (NCTId,BriefTitle → rows keep only those two keys).
+    → {total, rows[], next_page_token, page_size, params, _meta}.
+    """
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    ps = int(page_size)
+    if ps < 1:
+        raise SdkError("usage_error", provider="ctgov", detail=f"page_size must be >= 1, got {ps}")
+    params = {"pageSize": ps, "countTotal": "true" if count_total else "false"}
+    if query_term:
+        params["query.term"] = str(query_term)
+    if query_titles:
+        params["query.titles"] = str(query_titles)
+    if query_intr:
+        params["query.intr"] = str(query_intr)
+    if query_cond:
+        params["query.cond"] = str(query_cond)
+    if filter_advanced:
+        params["filter.advanced"] = str(filter_advanced)
+    if agg_filters:
+        params["aggFilters"] = str(agg_filters)
+    if fields:
+        params["fields"] = str(fields)
+    if page_token:
+        params["pageToken"] = str(page_token)
+    if sort:
+        params["sort"] = str(sort)
+    r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    studies = (r["data"] or {}).get("studies") or []
+    return {"total": (r["data"] or {}).get("totalCount"),
+            "rows": [_row_from_study(s) for s in studies],
+            "next_page_token": (r["data"] or {}).get("nextPageToken"),
+            "page_size": ps, "params": params, "_meta": r}

agentdata/healthcare/dailymed.py

@@ -0,0 +1,102 @@
+"""dailymed — NLM DailyMed v2 (SPL labeling metadata layer; keyless; NLM family 20/s — 0.2.8 sped up to 10 rps into the nlm group bucket).
+
+TTL: the spls list 7 days (setid is immutable, the list changes slowly with each release). First-version scope: setid + title + labeling URL as the verbatim-text entry point;
+the SPL XML full text is not parsed (let the agent fetch it along the URL).
+Probed and confirmed (2026-10-22): metadata.total_elements = the full count (atorvastatin 406) — the old face lost it entirely;
+the real pagesize limit is 100; published_date 'MMM dd, yyyy' is not ISO → normalized; empty pagination values in metadata are the string 'null', not JSON null.
+"""
+
+import re
+
+provider = {
+    "id": "dailymed",
+    "baseUrl": "https://dailymed.nlm.nih.gov/dailymed/services/v2",
+    # NLM family 20/s (tier B, DailyMed is not listed separately so it follows NLM policy); 0.2.8 sped up to 10/4 into the nlm group bucket (same note as rxnav)
+    "rate": {"rps": 10, "burst": 4, "group": "nlm"},
+    "ops": {
+        "spls": {"path": "/spls.json", "ttl": 7 * 86400},
+    },
+}
+
+_MONTHS = {"Jan": "01", "Feb": "02", "Mar": "03", "Apr": "04", "May": "05", "Jun": "06",
+           "Jul": "07", "Aug": "08", "Sep": "09", "Oct": "10", "Nov": "11", "Dec": "12"}
+_US_DATE = re.compile(r"^([A-Z][a-z]{2}) (\d{1,2}), (\d{4})$")
+
+
+def us_date_to_iso(v):
+    """'Oct 19, 2026' → '2026-10-19' (the same MDY-normalization family as the FDIC batch). Values in any other shape are returned unchanged."""
+    if not isinstance(v, str):
+        return None if v is None else v
+    m = _US_DATE.match(v.strip())
+    if m and m.group(1) in _MONTHS:
+        return f"{m.group(3)}-{_MONTHS[m.group(1)]}-{int(m.group(2)):02d}"
+    return v
+
+
+def row_from_upstream(x: dict) -> dict:
+    return {
+        "setid": x.get("setid"),
+        "title": x.get("title"),  # the title carries its own [labeler] bracket section — that is the upstream shape, passed through verbatim
+        "spl_version": x.get("spl_version"),
+        "published_date": us_date_to_iso(x.get("published_date")),
+        "url": f"https://dailymed.nlm.nih.gov/dailymed/drugInfo.cfm?setid={x['setid']}" if x.get("setid") else None,
+    }
+
+
+def search_label(drug: str, limit: int = 5, cache=None, no_cache: bool = False) -> dict:
+    from ..transport import call_provider
+
+    r = call_provider(provider, "spls",
+                      {"drug_name": drug, "pagesize": min(50, max(1, int(limit)))},
+                      cache=cache, no_cache=no_cache)
+    data = r["data"] or {}
+    rows = data.get("data") or []
+    total = ((data.get("metadata") or {}).get("total_elements")) or len(rows)
+    return {
+        "total": total,
+        "rows": [row_from_upstream(x) for x in rows],
+        "_meta": r,
+    }
+
+
+def spls_raw(*, drug_name=None, manufacturer=None, setid=None, page=None, pagesize=None,
+             sort=None, cache=None, no_cache: bool = False) -> dict:
+    """0.2.0 mirror face: all six spls.json params passed through under their upstream names (all verified by probing on 2026-10-23: manufacturer=Pfizer → Hospira rows,
+    setid filters exactly, page/pagesize/sort paginate and sort).
+
+    No hard cap: upstream silently clamps pagesize to 100 (101 → elements_per_page=100, no error) — the default None = omit (the upstream default is 100),
+    and the clamp is visible through the elements_per_page echo; a bare call is legal (full SPL enumeration, which upstream can express).
+    → {total, rows[], page, elements_per_page, params, _meta}; empty pagination values in metadata are the string 'null' and are normalized.
+    """
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    params = {}
+    if drug_name:
+        params["drug_name"] = str(drug_name)
+    if manufacturer:
+        params["manufacturer"] = str(manufacturer)
+    if setid:
+        params["setid"] = str(setid)
+    if page is not None:
+        params["page"] = int(page)
+    if pagesize is not None:
+        ps = int(pagesize)
+        if ps < 1:
+            raise SdkError("usage_error", provider="dailymed", detail=f"pagesize must be >= 1, got {ps}")
+        params["pagesize"] = ps
+    if sort:
+        params["sort"] = str(sort)
+    r = call_provider(provider, "spls", params, cache=cache, no_cache=no_cache)
+    data = r["data"] or {}
+    meta = data.get("metadata") or {}
+    rows = data.get("data") or []
+    total = meta.get("total_elements") or len(rows)
+    return {
+        "total": total,
+        "rows": [row_from_upstream(x) for x in rows],
+        "page": meta.get("current_page"),
+        "elements_per_page": meta.get("elements_per_page"),
+        "params": params,
+        "_meta": r,
+    }

agentdata/healthcare/epmc.py

@@ -0,0 +1,108 @@
+"""epmc — Europe PMC (literature evidence layer; keyless; polite tier 2 rps).
+
+TTL: search result pages 24h. Query construction: company→AFF:"…" (author affiliation field search; do not use AUTH=author name —
+company names via AUTH collapse the hit count — an external review on 2026-10-16 ruled 2 vs 37,108); focus appends an AND all-field term.
+The real upstream pageSize limit is 1-1000 (1001 → errCode 404 «Invalid page size»; probed and confirmed) — polite tier 50, truncation visible via hitCount.
+"""
+
+provider = {
+    "id": "epmc",
+    "baseUrl": "https://www.ebi.ac.uk/europepmc/webservices/rest",
+    "rate": {"rps": 2, "burst": 4},
+    "ops": {
+        "search": {"path": "/search", "ttl": 24 * 3600},
+    },
+}
+
+
+def row_from_upstream(x: dict) -> dict:
+    """Probed and confirmed (2026-10-22, three-source diff + self-describing core fullTextUrlList reconciliation):
+    the old url only recognised pmid → PMC-only rows (pmcid present, pmid null) and PPR preprint rows (id only) all came back null, breaking the evidence chain;
+    the official self-describing URLs: pmcid rows = articles/{pmcid} (same shape for MED/PMC), PPR = article/PPR/{id},
+    PAT has no EPMC page (it only gives SureChembl/EPO outbound links) → an honest None.
+    For new PMC-only records pubYear can be null while firstPublicationDate has a value → year fallback."""
+    year_fallback = (str(x.get("firstPublicationDate") or ""))[:4] or None
+    if x.get("pmcid"):
+        url = f"https://europepmc.org/articles/{x['pmcid']}"
+    elif x.get("pmid"):
+        url = f"https://europepmc.org/article/{x.get('source') or 'MED'}/{x['pmid']}"
+    elif x.get("source") and x.get("id") and x.get("source") != "PAT":
+        url = f"https://europepmc.org/article/{x['source']}/{x['id']}"
+    else:
+        url = None
+    return {
+        "id": x.get("id"),  # a PPR preprint row only has this key filled in (both pmid and pmcid are null) — the evidence chain never breaks
+        "pmid": x.get("pmid"),
+        "source": x.get("source"),
+        "title": x.get("title"),
+        "authors": x.get("authorString"),
+        "journal": x.get("journalTitle"),
+        "pub_year": x.get("pubYear") or year_fallback,
+        "cited_by": x.get("citedByCount", 0),
+        "url": url,
+    }
+
+
+def search_evidence(query=None, company=None, focus=None, limit=10, cache=None, no_cache=False) -> dict:
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    q = query
+    if not q and company:
+        q = f'AFF:"{company}"'
+        if focus:
+            q += f' AND "{focus}"'
+    if not q:
+        raise SdkError("op_unknown", provider="epmc", detail="evidence needs query or company (focus may be added)")
+    r = call_provider(provider, "search",
+                      {"query": q, "format": "json", "resultType": "lite",
+                       "pageSize": min(50, max(1, int(limit)))},
+                      cache=cache, no_cache=no_cache)
+    rows = ((r["data"] or {}).get("resultList") or {}).get("result") or []
+    return {
+        "hitCount": (r["data"] or {}).get("hitCount", len(rows)),
+        "rows": [row_from_upstream(x) for x in rows],
+        "_meta": r,
+    }
+
+
+def search_raw(query, *, result_type="lite", page_size=25, cursor_mark="*", sort=None,
+               fmt="json", cache=None, no_cache=False) -> dict:
+    """0.2.0 mirror face: upstream param names (query/resultType/pageSize/cursorMark/sort/format) + our defaults.
+
+    Hard limit (protocol, confirmed by probing on 2026-10-23): pageSize 1-1000 — 1001 → errCode 404 «Invalid page size»;
+    format supports only json (this stack parses JSON — a local safety gate; for the xml face the agent fetches along the evidence url itself).
+    resultType is the closed set lite|core|full|idlist; a free sort string passes through (measured "CITED desc" works, echoed back in nextPageUrl).
+    Defaults follow the upstream defaults: pageSize=25, cursorMark="*" (the first-page sentinel), sort=None (relevance).
+    → {hitCount, rows[], next_cursor_mark, page_size, query, _meta}.
+    """
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    q = str(query or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="epmc", detail="query requires a search expression (Europe PMC all-field syntax)")
+    rt = str(result_type or "lite").strip()
+    if rt not in ("lite", "core", "full", "idlist"):
+        raise SdkError("usage_error", provider="epmc",
+                       detail=f"the resultType closed set is lite|core|full|idlist, got '{rt}'")
+    if str(fmt or "json").strip() != "json":
+        raise SdkError("usage_error", provider="epmc",
+                       detail="format supports only json (this stack parses JSON; for the xml face fetch it yourself along the evidence url)")
+    ps = int(page_size)
+    if not 1 <= ps <= 1000:
+        raise SdkError("usage_error", provider="epmc",
+                       detail=f"pageSize must be 1-1000 (upstream 1001 → errCode 404 Invalid page size, measured 2026-10-23), got {ps}")
+    params = {"query": q, "format": "json", "resultType": rt,
+              "pageSize": ps, "cursorMark": str(cursor_mark or "*")}
+    if sort:
+        params["sort"] = str(sort)
+    r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    rows = ((r["data"] or {}).get("resultList") or {}).get("result") or []
+    return {
+        "hitCount": (r["data"] or {}).get("hitCount", len(rows)),
+        "rows": [row_from_upstream(x) for x in rows],
+        "next_cursor_mark": (r["data"] or {}).get("nextCursorMark"),
+        "page_size": ps, "query": q,
+        "_meta": r,
+    }

agentdata/healthcare/eudamed.py

@@ -0,0 +1,124 @@
+"""eudamed — EUDAMED public device catalogue (EU UDI-DI → master record; keyless).
+
+Endpoint = the SPA's same-origin REST (the api:{…} map is plaintext in the main bundle, not an officially documented face): GET /api/devices/udiDiData.
+Rows carry manufacturerSrn (XX-MF-…) + authorisedRepresentativeSrn (XX-AR-…) — the EU counterpart of GUDID;
+the AccessGUDID egress is intermittently gated by a TLS fingerprint gate (2026-10-16 case), so the EU face became its own edge.
+Acceptance gate observations: probed 2026-10-17 and re-checked 2026-10-20 — the endpoint / param semantics / row shape are stable.
+Channel note (measured 2026-10-20): the upstream exact DI query (primaryDi=) is unindexed — cold 50.8s / warm 11.2s,
+so the op gets a 90s timeout and 0 retries (the slow path must not burn retries); tradeName= is the fast face but it is a search, not a normalization, so it does not enter this kind.
+Pagination (all three params are sent together): page&pageSize&size + iso2Code=en; totalElements===0 = a structured not_found —
+but an empty set is never authoritative for the cache: the unindexed face occasionally returns a wholly empty page (hit here on 2026-10-20: a 0-hit page poisoned the 7-day TTL), so an empty verdict discards the cached entry and refetches once.
+"""
+
+
+def _tail(code):
+    """refdata.risk-class.class-iia → class-iia (non-string → None).
+
+    P1-2 (folded in 2026-10-22): the same batch of upstream fields comes in two shapes — riskClass/deviceStatusType/manufacturerStatus
+    are {code} objects (the real-machine shape), while issuingAgency on list pages can be an object or a bare string. Both shapes are collected here,
+    so call sites can pass the value straight through; the old implementation only accepted strings, so manufacturerStatus was always None.
+    """
+    if isinstance(code, dict):
+        code = code.get("code")
+    return code.split(".").pop() if isinstance(code, str) else None
+
+
+def _params(v):
+    return {"primaryDi": v, "page": 0, "pageSize": 5, "size": 5, "iso2Code": "en"}
+
+
+def _empty(d):
+    return not (d or {}).get("totalElements") or not (d or {}).get("content")
+
+
+provider = {
+    "id": "eudamed",
+    "baseUrl": "https://ec.europa.eu/tools/eudamed",
+    "rate": {"rps": 1, "burst": 2},
+    "concurrency": 1,  # ⑤ host concurrency pinned to 1: primaryDi is unindexed and cold ~50s, so more concurrency would only drag down the EU face
+    "ops": {
+        "lookup": {"path": "/api/devices/udiDiData", "timeout": 90.0, "retries": 0},
+    },
+    "ttl": {"lookup": 7 * 86400},
+}
+
+
+def _query(params, cache, no_cache):
+    """A single udiDiData query + the empty-page poison guard (an empty verdict discards the cached entry and refetches once; only a still-empty result counts as not_found)."""
+    from ..errors import SdkError
+    from ..transport import call_provider, cache_key_for
+
+    r = call_provider(provider, "lookup", params, cache=cache, no_cache=no_cache)
+    if _empty(r["data"]):
+        # An empty set is untrustworthy: discard the cached entry (including a stale empty one) and refetch once; only a still-empty result counts as not_found. The refetch goes through the normal read path
+        # (the entry was deleted, so it must miss) and a good result is written back — the same effect as "noCache only skips reads, not writes" on the Node side (both stacks align).
+        key = cache_key_for("lookup", params)
+        if cache is not None:
+            cache.delete("eudamed", key)
+        fresh = call_provider(provider, "lookup", params, cache=cache, no_cache=False)
+        if _empty(fresh["data"]):
+            if cache is not None:
+                cache.delete("eudamed", key)
+            raise SdkError("upstream_not_found", provider="eudamed",
+                           detail=f"no such EUDAMED record (0 hits is a structured empty set): {params.get('primaryDi') or params}")
+        r = fresh
+    return r
+
+
+def _card_from_row(row):
+    ia = row.get("issuingAgency")  # on list pages it can be an object or a string (the detail face is richer) — both shapes are accepted
+    ia_code = ia.get("code") if isinstance(ia, dict) else ia
+    return {
+        "primary_di": row.get("primaryDi"),
+        "basic_udi": row.get("basicUdi"),
+        "trade_name": row.get("tradeName"),
+        "device_name": row.get("deviceName"),
+        "device_model": row.get("deviceModel"),
+        "risk_class": _tail((row.get("riskClass") or {}).get("code")),
+        "device_status": _tail((row.get("deviceStatusType") or {}).get("code")),
+        "version_number": row.get("versionNumber"),
+        "issuing_agency": _tail(ia_code),
+        "sterile": row.get("sterile"),
+        # manufacturerStatus is a {code} object (same shape as riskClass) — _tail accepts both shapes, so passing it straight yields active (P1-2)
+        "manufacturer": {"name": row.get("manufacturerName"), "srn": row.get("manufacturerSrn"),
+                         "status": _tail(row.get("manufacturerStatus"))},
+        "authorised_representative": (
+            {"name": row.get("authorisedRepresentativeName"), "srn": row.get("authorisedRepresentativeSrn")}
+            if (row.get("authorisedRepresentativeSrn") or row.get("authorisedRepresentativeName")) else None),
+        "last_update_date": row.get("lastUpdateDate"),
+        "uuid": row.get("uuid"),
+    }
+
+
+def lookup_di_eu(di, *, cache=None, no_cache=False):
+    """→ EU device identity card (manufacturer SRN + authorised-rep SRN edge + risk class/status/version) — the old verb face (resolve kind=device_eu)."""
+    from ..errors import SdkError
+
+    v = str(di or "").strip()
+    if not v:
+        raise SdkError("usage_error", provider="eudamed", detail="resolve kind=device_eu needs a DI code")
+    r = _query(_params(v), cache, no_cache)
+    row = (r["data"].get("content") or [None])[0]
+    return {**_card_from_row(row), "_meta": r}
+
+
+def query_udi_di(primary_di=None, *, page=0, page_size=5, iso2_code="en", cache=None, no_cache=False):
+    """0.2.0 mirror face: the primaryDi exact lookup + the upstream param names page/pageSize/iso2Code (paging is unlocked this way).
+
+    size is sent together with pageSize (all three params go out together); a larger pageSize widens the rows (the unindexed face is cold ~50s, so widen with care).
+    → identity card (the first-page row) + pagination echo total_elements/page/page_size; paging past the end = an empty page → not_found (the single-record face is the detail lookup).
+    """
+    from ..errors import SdkError
+
+    v = str(primary_di or "").strip()
+    if not v:
+        raise SdkError("usage_error", provider="eudamed", detail="eudamed_device needs primary_di (the EU UDI-DI)")
+    if int(page_size) < 1:
+        raise SdkError("usage_error", provider="eudamed", detail="page_size must be >= 1")
+    params = {"primaryDi": v, "page": int(page), "pageSize": int(page_size),
+              "size": int(page_size), "iso2Code": str(iso2_code or "en")}
+    r = _query(params, cache, no_cache)
+    row = (r["data"].get("content") or [None])[0]
+    return {**_card_from_row(row),
+            "total_elements": (r["data"] or {}).get("totalElements"),
+            "page": int(page), "page_size": int(page_size), "_meta": r}