agentdata 0.3.26__py3-none-any.whl

agentdata/healthcare/gb_mhra.py

@@ -0,0 +1,137 @@
+"""gb_mhra — UK MHRA medicines & medical-device safety-alert face provider
+(www.gov.uk search/content API; keyless — the same host and contract family as the
+gb_cma case chain).
+
+healthcare domain (0.3.16; admitted 2026-10-30, probed). Shape verified 2026-10-30:
+GET /api/search.json?filter_format=medical_safety_alert&q=&count=&start=
+  → {results:[{title,link:'/drug-device-alerts/<slug>',_id≡base_path,public_timestamp,
+     organisations:[…],document_type:'medical_safety_alert',…}], total, start, aggregates}
+  — filter_format=medical_safety_alert is this face's semantics (a fixed param, not a
+    user param); q/count/start go through with upstream verbatim names. q= is a company-
+    name penetration channel into the alert corpus (measured: Abbott → 160 alerts across
+    2019-2026). **Pit nailed: rows returned under a q= query drop the link field — the
+    base_path then lives only in _id (link and _id are both the base_path on this API);
+    the row mapper reads link first, falling back to _id.** total=1,462 measured
+    2026-10-30.
+GET /api/content/drug-device-alerts/{slug}
+  → {content_id(UUID stable key), title, description, first_published_at, public_updated_at,
+     updated_at, withdrawn_notice, details:{body(HTML), change_history:[{note,public_timestamp}],
+     attachments:[…], metadata:{alert_type, issued_date, medical_specialism:[…]}},
+     links:{organisations(MHRA),…}}
+  — **Pit nailed: the content API has no .json variant — /api/content<base_path>.json
+    returns the gov.uk 404 HTML page (a silent near-miss, not an error body); the op path
+    carries no suffix and a pasted slug with a trailing .json is stripped.**
+  — alert_type (e.g. medicines-recall-notification / device-field-safety-notice) and
+    issued_date from details.metadata are the MHRA-golden fields.
+Param-minimalism pitfall (same host as gb_cma): unprobed param combinations → 422 — this
+face accepts only q/count/start, do not widen it.
+TTL: search 24h (the alert stream lands at daily-to-weekly cadence) / alert 7 days
+(alert pages change slowly; change_history records the evolution); polite rate 1 rps
+(gov.uk publishes no search-API quota — conservative, same as gb_cma).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "gb_mhra",
+    "baseUrl": "https://www.gov.uk",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "alerts": {"path": "/api/search.json"},               # params: q, count, start (filter_format is fixed for this face)
+        "alert": {"path": "/api/content/drug-device-alerts/{slug}"},  # slug = the tail of the alert-page base_path (link or _id of the search row)
+    },
+    "ttl": {"alerts": 24 * 3600, "alert": 7 * 86400},
+}
+
+
+def alerts_from_upstream(data, size):
+    """Upstream search response → alert rows (pure function, offline-testable)."""
+    rows = [{
+        "slug": ((r.get("link") or r.get("_id") or "").removeprefix("/drug-device-alerts/") or None),
+        # ^ join key into the detail face; under q= the rows drop link — the base_path then
+        #   lives only in _id (both ≡ base_path on this API; do not pass _id off as content_id)
+        "title": r.get("title"),                      # alert name = "Class 2 Medicines Recall: <firm>, <product>" / "MDA/2020/019 …" forms
+        "public_timestamp": r.get("public_timestamp"),
+        "organisations": [o.get("title") for o in (r.get("organisations") or []) if o.get("title")],
+        "url": ("https://www.gov.uk" + p) if (p := (r.get("link") or r.get("_id"))) else None,
+    } for r in ((data or {}).get("results") or [])]
+    return {
+        "rows": rows, "count": len(rows), "limit_applied": size,
+        "total": data.get("total") if isinstance(data, dict) and isinstance(data.get("total"), int) else None,
+    }
+
+
+def alerts_raw(q=None, *, count=20, start=0, cache=None, no_cache=False):
+    """Flat-panel low-level face: q/count/start go through with verbatim names
+    (filter_format=medical_safety_alert fixed).
+
+    → {rows[], count, limit_applied, total, params, _meta}. A missing q = full-register
+    enumeration (1,462 live alerts counted 2026-10-30); count politeness wall 1-100
+    (same host contract as gb_cma — upstream walls unprobed, keep the family cap);
+    start = offset paging."""
+    from ..transport import call_provider
+
+    term = str(q or "").strip() or None
+    size = int(count) if count is not None else 20  # explicit None check — 0 being swallowed by `or` was a same-type bug caught by a test
+    if not 1 <= size <= 100:
+        raise SdkError("usage_error", provider="gb_mhra",
+                       detail=f"count must be 1-100 (politeness cap; the gov.uk search API publishes no quota — same family cap as gb_cma), got \"{count}\"")
+    off = int(start) if start is not None else 0
+    if off < 0:
+        raise SdkError("usage_error", provider="gb_mhra", detail=f"start must be an offset ≥0, got \"{start}\"")
+    params = {"filter_format": "medical_safety_alert", "count": size, "start": off}
+    if term:
+        params["q"] = term
+    r = call_provider(provider, "alerts", params, cache=cache, no_cache=no_cache)
+    return {**alerts_from_upstream(r["data"], size), "params": params, "_meta": r}
+
+
+def _clean_slug(slug):
+    s = str(slug or "").strip()
+    # Tolerance: a pasted full base_path (/drug-device-alerts/<slug> or https://www.gov.uk/drug-device-alerts/<slug>)
+    # gets its prefix stripped; a trailing .json (the 404 trap shape) is stripped too
+    for pre in ("https://www.gov.uk/drug-device-alerts/", "http://www.gov.uk/drug-device-alerts/", "/drug-device-alerts/"):
+        if s.startswith(pre):
+            s = s[len(pre):]
+    s = s.strip("/")
+    if s.endswith(".json"):
+        s = s[: -len(".json")]
+    if not s or "/" in s:
+        raise SdkError("usage_error", provider="gb_mhra",
+                       detail=f"slug must be the alert-page tail segment (e.g. class-2-medicines-recall-xeal-pharma-clopidogrel-oral-liquids-all-strengths-el-26-a-slash-43, "
+                              f"echoed verbatim from the search row's slug field): {slug}")
+    return s
+
+
+def alert_raw(slug, *, cache=None, no_cache=False):
+    """→ the full single-alert dossier (content API, no .json suffix — with it gov.uk
+    serves the 404 HTML page; content_id = the UUID stable key).
+    alert_type/issued_date = the MHRA metadata fields; attachments = the notice PDF family."""
+    from ..transport import call_provider
+
+    s = _clean_slug(slug)
+    r = call_provider(provider, "alert", {"slug": s}, cache=cache, no_cache=no_cache)
+    x = r["data"] or {}
+    det = x.get("details") or {}
+    md = det.get("metadata") or {}
+    return {
+        "slug": s,
+        "content_id": x.get("content_id"),
+        "title": x.get("title"),
+        "description": x.get("description") or None,
+        "document_type": x.get("document_type"),
+        "alert_type": md.get("alert_type"),           # e.g. medicines-recall-notification / device-field-safety-notice (MHRA metadata)
+        "issued_date": md.get("issued_date"),         # e.g. 2026-10-26 (MHRA metadata)
+        "first_published_at": x.get("first_published_at"),
+        "public_updated_at": x.get("public_updated_at"),
+        "updated_at": x.get("updated_at"),
+        "withdrawn": bool(x.get("withdrawn_notice")),
+        "change_history": det.get("change_history") or [],      # [{note, public_timestamp}] newest→oldest (last = First published)
+        "attachments": [{"title": a.get("title"), "url": a.get("url"),
+                         "content_type": a.get("content_type"), "content_id": a.get("content_id")}
+                        for a in (det.get("attachments") or [])],
+        "body_html": det.get("body") or "",                     # the alert-page body HTML (recall/action instructions)
+        "organisations": [o.get("title") for o in ((x.get("links") or {}).get("organisations") or [])
+                          if o.get("title")],
+        "url": f"https://www.gov.uk/drug-device-alerts/{s}",
+        "_meta": r,
+    }

agentdata/healthcare/gudid.py

@@ -0,0 +1,84 @@
+"""gudid — AccessGUDID v3 (device DI → master record; keyless; TTL 7 days).
+
+Migrated v2→v3 (2026-10-22): v2 carries an upstream 2021-07 deprecation notice (claiming removal after 2022-12-31, never executed and still 200);
+v3 has the same shape and was probed — a field-by-field diff on the same DI only adds keys (gmdnTerms.gmdn gains gmdnCode/implantable/gmdnCodeStatus),
+the 404 shape is the same, the WAF behaviour is the same; v3 also accepts the udi=/record_key= params (recorded, unused).
+
+Channel note: upstream has an AWS WAF human gate, and on 2026-10-16 it was measured to hold **by client stack and by egress IP** — the local Node undici
+always got 202 with an empty HTML body (the system curl always passed locally); after switching the egress proxy, curl/urllib also all got 202 + the x-amzn-waf-action challenge page.
+The Python default is transport='urllib'; whether it is blocked must be verified on a real machine (live-transport verification, off by default); if blocked, check the egress IP / change network first
+(the transport already raises an actionable error for a 2xx non-JSON response), and only pin 'curl' once the local egress confirms urllib is blocked. Data fallback: openFDA UDI, the same origin.
+Note: the v1 endpoint is deprecated and 404s — do not step on it.
+"""
+
+provider = {
+    "id": "gudid",
+    "baseUrl": "https://accessgudid.nlm.nih.gov",
+    "rate": {"rps": 2, "burst": 4},
+    "ops": {
+        "lookup": {"path": "/api/v3/devices/lookup.json", "notFound": [404], "ttl": 7 * 86400,
+                   "transport": "urllib"},
+    },
+}
+
+
+def _pick(o, *keys):
+    for k in keys:
+        if o and o.get(k) is not None:
+            return o[k]
+    return None
+
+
+def card_from_upstream(data):
+    """Pure mapper (testable offline) — v2/v3 have the same shape; only the top-level productCodes bare array is the strong shape (five fields),
+    gudid.device.productCodes.fdaProductCode is the weak shape (code+name only) — do not read them mixed.
+    The v2 response was verified field by field against a real 200 response for the DI
+    10198459305313 (2026-10-20), and v3 was verified on 2026-10-22 to use the same names; the old names are kept as a fallback."""
+    dev = ((data or {}).get("gudid") or {}).get("device") or {}
+    pcs = (data or {}).get("productCodes") or []
+    return {
+        "brand_name": _pick(dev, "brandName", "brand_name"),
+        "company_name": _pick(dev, "companyName", "company_name"),
+        "device_description": _pick(dev, "deviceDescription", "device_description"),
+        "model": _pick(dev, "versionModelNumber", "version_or_model_number"),
+        "mr_safety": _pick(dev, "MRISafetyStatus", "mriSafetyInformation", "mri_safety"),
+        "record_status": _pick(dev, "deviceRecordStatus", "recordStatus", "record_status"),
+        "public_version": _pick(dev, "publicVersionNumber", "public_version_number"),
+        "product_codes": [
+            {
+                "code": c.get("productCode"),
+                "name": c.get("deviceName"),
+                "device_class": c.get("deviceClass"),
+                "regulation_number": c.get("regulationNumber"),
+                "medical_specialty": c.get("medicalSpecialty"),
+            }
+            for c in pcs
+        ],
+    }
+
+
+def lookup_di(di: str, cache=None, no_cache: bool = False) -> dict:
+    from ..transport import call_provider
+
+    r = call_provider(provider, "lookup", {"di": str(di).strip()}, cache=cache, no_cache=no_cache)
+    return {"di": str(di).strip(), **card_from_upstream(r["data"]), "_meta": r}
+
+
+def lookup_device(di=None, udi=None, record_key=None, *, cache=None, no_cache: bool = False) -> dict:
+    """0.2.0 mirror face: one v3 endpoint with three input params (di/udi/record_key — exactly one of the three required) — the udi=/record_key=
+    two-param shapes recorded by the audit are unlocked this way (on 2026-10-23 the missing-param 400 was judged by probing: this is the only positive v3 endpoint)."""
+    from ..errors import SdkError
+    from ..transport import call_provider
+
+    given = {k: str(v).strip() for k, v in (("di", di), ("udi", udi), ("record_key", record_key)) if v}
+    if len(given) != 1:
+        raise SdkError("usage_error", provider="gudid",
+                       detail=f"exactly one of di/udi/record_key is required (the single-record lookup endpoint; got {sorted(given) or 'none'})")
+    k, v = next(iter(given.items()))
+    try:
+        r = call_provider(provider, "lookup", {k: v}, cache=cache, no_cache=no_cache)
+    except SdkError as e:
+        if e.code == "upstream_unavailable":  # WAF/TLS fingerprint gate or gateway timeout — add the same-origin fallback pointer into the envelope (0.2.8)
+            e.detail = (f"{e.detail}; same-origin fallback: openFDA /device/udi.json (another public face of the DI master record, not covered by this SDK, callable directly)")
+        raise
+    return {"by": k, k: v, **card_from_upstream(r["data"]), "_meta": r}

agentdata/healthcare/mesh.py

@@ -0,0 +1,89 @@
+"""mesh — MeSH controlled-vocabulary provider (id.nlm.nih.gov RDF lookup API; keyless; NLM/UMLS family 20/s — 0.2.8 sped up to 10 rps into the nlm group bucket).
+
+Wave 3 of the healthcare domain: resolve kind=mesh_term
+— drug/disease name → the MeSH descriptor master record, the control-term anchor for literature search and corpus normalization. Shapes measured 2026-10-23 (the param names are very easy to get wrong):
+GET /mesh/lookup/descriptor?label=<q>&match=contains&limit=N
+  → [{resource:"http://id.nlm.nih.gov/mesh/D001241", label:"Aspirin"}, …]
+**the search param is label** (passing term/descriptor just gets a 400 {"label":["must not be empty"]});
+the match closed set is contains|exact|startswith (an illegal value such as word gets a 400 listing the closed set).
+GET /mesh/lookup/details?descriptor=D001241
+  → {descriptor, qualifiers[], seealso[], terms:[{resource,label,preferred}]}
+  — terms is the synonym-entry pool of that descriptor (the preferred:true slot is the authoritative name); qualifiers are the qualifier sub-anchors.
+Every term resolution is a fixed two hops (search + details of the preferred record); on a miss "zero hits is a legal answer" — it is not treated as an error.
+TTL: MeSH releases yearly → 30 days; polite tier 1 rps (NLM's keyless guidance says ≤3).
+"""
+import re
+
+from ..errors import SdkError
+
+provider = {
+    "id": "mesh",
+    "baseUrl": "https://id.nlm.nih.gov",
+    # NLM/UMLS family 20/s (tier B, MeSH lookup is not listed separately); 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": {
+        "lookup": {"path": "/mesh/lookup/descriptor"},   # params: label, match, limit
+        "details": {"path": "/mesh/lookup/details"},     # params: descriptor
+    },
+    "ttl": {"lookup": 30 * 86400, "details": 30 * 86400},
+}
+
+_UI = re.compile(r"([A-Z]\d{6})$")
+
+
+def _ui_of(resource):
+    m = _UI.search(str(resource or ""))
+    return m.group(1) if m else None
+
+
+def descriptors_from_upstream(data, size):
+    """Upstream payload → descriptor candidates (pure function, testable offline; upstream echoes no total — lookup returns a truncated list)."""
+    items = data if isinstance(data, list) else []
+    return {
+        "candidates": [{"mesh_ui": _ui_of(d.get("resource")),
+                        "descriptor_uri": d.get("resource"),
+                        "label": d.get("label")} for d in items],
+        "limit_applied": size,
+    }
+
+
+def terms_from_upstream(details):
+    """details payload → the synonym pool (pure function, testable offline): the preferred entry comes first."""
+    terms = [{"mesh_ui": _ui_of(t.get("resource")), "label": t.get("label"), "preferred": t.get("preferred") is True}
+             for t in ((details or {}).get("terms") or [])]
+    preferred = next((t["label"] for t in terms if t["preferred"]), None) or (terms[0]["label"] if terms else None)
+    return {
+        "terms": terms,
+        "preferred_term": preferred,
+        "synonyms": [t["label"] for t in terms if not t["preferred"]],
+    }
+
+
+def search_descriptors(q, *, match="contains", limit=10, cache=None, no_cache=False):
+    """→ {candidates[], limit_applied, _meta}; descriptor candidates (the match closed set is contains|exact|startswith)."""
+    from ..transport import call_provider
+
+    label = str(q or "").strip()
+    if not label:
+        raise SdkError("usage_error", provider="mesh", detail="search_descriptors needs value (a drug/disease name, etc.)")
+    if match not in ("contains", "exact", "startswith"):
+        raise SdkError("usage_error", provider="mesh", detail=f"match must be contains|exact|startswith, got '{match}'")
+    size = min(max(1, int(limit or 10)), 50)
+    r = call_provider(provider, "lookup", {"label": label, "match": match, "limit": size}, cache=cache, no_cache=no_cache)
+    return {**descriptors_from_upstream(r["data"], size), "_meta": r}
+
+
+def descriptor_details(ui, *, cache=None, no_cache=False):
+    """→ {terms[], preferred_term, synonyms[], descriptor, qualifiers[], seealso[], _meta}; the descriptor master record."""
+    from ..transport import call_provider
+
+    descriptor = str(ui or "").strip()
+    if not re.fullmatch(r"[A-Z]\d{6}", descriptor):
+        raise SdkError("usage_error", provider="mesh", detail=f"not a MeSH UI shape (a letter + 6 digits): {ui}")
+    r = call_provider(provider, "details", {"descriptor": descriptor}, cache=cache, no_cache=no_cache)
+    d = r["data"][0] if isinstance(r["data"], list) and r["data"] else r["data"]  # guard against array wrapping
+    return {**terms_from_upstream(d),
+            "descriptor": descriptor,
+            "qualifiers": [_ui_of(q) for q in ((d or {}).get("qualifiers") or [])],
+            "seealso": [_ui_of(s) for s in ((d or {}).get("seealso") or [])],
+            "_meta": r}

agentdata/healthcare/rasff.py

@@ -0,0 +1,164 @@
+"""rasff — EU RASFF Window food-safety alert search face provider
+(webgate.ec.europa.eu/rasff-window/; keyless).
+
+healthcare domain (0.3.19; admitted 2026-11-02, probed). Shapes verified by first-hand live probing
+2026-11-02 (the probe corpus lives in tmp/probe-ca-eu-faces/):
+GET /rasff-window/screen/search
+  → the SPA shell — its GET mints the JSESSIONID session cookie (the two-step handshake).
+POST /rasff-window/backend/public/notification/search/consolidated/en/
+  → body {"parameters": {...}}; the response envelope is {notifications[], totalPages, totalElements}.
+  **Pit nailed: the path must end with the language segment AND a trailing slash — dropping either
+  one returns 404 (not an empty set).**
+  **Pit nailed (Origin/Referer are mandatory): the POST carries Origin + Referer to the window
+  screen plus the session cookie — the probe's requests without them do not return the search
+  envelope.**
+  Verified filter shapes (all three confirmed by the totalElements oracle, 2026-11-02):
+    subject               → free text on the alert subject (aflatoxin → 2,919 hits)
+    notificationReference → the reference number, exact (2026.9701 → 1 hit)
+    ecValidDateFrom/To    → the window dates, format "dd-MM-yyyy 00:00:00" (01-09-2026 → 70 hits).
+      The format is the upstream's own (the SPA's formatDate helper: en-GB dd/MM/yyyy → dd-MM-yyyy
+      + " 00:00:00"); ISO input is rejected with 400.
+    pageNumber (1-based) + itemsPerPage (the browser default 25).
+  **Known limitation (documented, not guessed around): the enum-shaped filters — notifyingCountry /
+  originCountry / productCategory / notificationClassification / riskDecision / notificationType /
+  notificationStatus / notificationBasis / actionTaken / analyticalFinding — are NOT exposed here.
+  Their parameter names come from the SPA's search component, but every object shape probed
+  ({id,description} / {id} / plain string / full object) was rejected with the same generic
+  [ERR-1003] body, so the shapes stay unproven and guessing them would burn requests for a silent
+  near-miss. This face therefore ships the three proven filters + paging only.**
+  Row shape: notif_id, ecValidationDate ("30-10-2026 18:59:15"), reference ("2026.9701"),
+  notifyingCountry{organizationName, isoCode}, subject, productCategory{id,description},
+  productType{id,description}, notificationClassification{id,description}, riskDecision{id,description},
+  published (bool), originCountries[{organizationName, isoCode}].
+  Corpus: 33,256 notifications across 11,086 pages (measured 2026-11-02).
+TTL 24h (the window is refreshed on the EU's own cadence); polite rate 1 rps (the portal publishes
+no quota for this backend — conservative).
+"""
+import re
+
+from ..errors import SdkError
+
+provider = {
+    "id": "rasff",
+    "baseUrl": "https://webgate.ec.europa.eu",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "screen": {"path": "/rasff-window/screen/search", "accept": "text"},  # the session bootstrap
+        "search": {"path": "/rasff-window/backend/public/notification/search/consolidated/en/",
+                   "method": "POST", "idempotent": True},  # params: parameters{...}
+    },
+    "ttl": {"search": 24 * 3600},
+}
+
+_SESSION_TTL = 15 * 60  # the JSESSIONID pairing is reused inside its session window
+
+_ORIGIN = "https://webgate.ec.europa.eu"
+_REFERER = "https://webgate.ec.europa.eu/rasff-window/screen/search"
+_DATE = re.compile(r"^(\d{2})-(\d{2})-(\d{4})(?:\s+00:00:00)?$")
+
+
+def _fmt_date(v, field):
+    """'01-09-2026' (or the full 'dd-MM-yyyy 00:00:00' form) → the upstream date string.
+
+    The upstream format is fixed by the SPA's own formatDate helper (en-GB dd/MM/yyyy →
+    'dd-MM-yyyy 00:00:00'); ISO input is rejected upstream with 400, so it is converted here
+    rather than passed through."""
+    s = str(v or "").strip()
+    if not s:
+        return None
+    m = _DATE.match(s)
+    if not m:
+        raise SdkError("usage_error", provider="rasff",
+                       detail=f"{field} must be dd-MM-yyyy (the upstream date format, e.g. 01-09-2026 — ISO input is rejected upstream with 400), got \"{v}\"")
+    return f"{m.group(1)}-{m.group(2)}-{m.group(3)} 00:00:00"
+
+
+def notifications_from_upstream(data):
+    """Upstream envelope → notification rows (pure function, offline-testable)."""
+    rows = []
+    for n in ((data or {}).get("notifications") or []):
+        rows.append({
+            "notif_id": n.get("notifId"),
+            "reference": n.get("reference"),
+            "ec_validation_date": n.get("ecValidationDate"),
+            "subject": n.get("subject"),
+            "notifying_country": (n.get("notifyingCountry") or {}).get("organizationName"),
+            "notifying_country_iso": (n.get("notifyingCountry") or {}).get("isoCode"),
+            "origin_countries": [{"name": (c or {}).get("organizationName"), "iso": (c or {}).get("isoCode")}
+                                 for c in (n.get("originCountries") or [])],
+            "product_category": (n.get("productCategory") or {}).get("description"),
+            "product_type": (n.get("productType") or {}).get("description"),
+            "classification": (n.get("notificationClassification") or {}).get("description"),
+            "risk_decision": (n.get("riskDecision") or {}).get("description"),
+            "published": n.get("published"),
+        })
+    return {"rows": rows, "count": len(rows),
+            "total_elements": (data or {}).get("totalElements"),
+            "total_pages": (data or {}).get("totalPages")}
+
+
+def _session(cache, no_cache=False):
+    """-> the session cookie header (the JSESSIONID minted by the window shell GET); cached 15 minutes."""
+    if not no_cache and cache is not None:
+        hit = cache.get("rasff", "window_session", _SESSION_TTL)
+        if hit:
+            return hit["payload"]["cookie"]
+    from ..transport import call_provider
+    r = call_provider(provider, "screen", {}, cache=cache, no_cache=True)
+    cookies = r.get("set_cookie") or []
+    if not cookies:
+        raise SdkError("upstream_unavailable", provider="rasff",
+                       detail="the window shell did not mint a session cookie (the handshake shape may have changed)")
+    cookie = "; ".join(c.split(";", 1)[0].strip() for c in cookies)
+    if cache is not None:
+        cache.set("rasff", "window_session", {"cookie": cookie}, _SESSION_TTL)
+    return cookie
+
+
+def search_raw(subject=None, *, notification_reference=None, ec_valid_date_from=None,
+               ec_valid_date_to=None, page_number=1, items_per_page=25, cache=None, no_cache=False):
+    """Flat-panel low-level face: the RASFF notification search (the consolidated English window).
+
+    The three filters are the proven ones (subject / notificationReference / ecValidDateFrom-To);
+    paging is pageNumber (1-based) + itemsPerPage (the browser default 25, politeness cap 200).
+    → {rows[], count, total_elements, total_pages, params, _meta} — params = the upstream body
+    actually sent (the "parameters" object), replayable."""
+    from ..transport import call_provider
+
+    idx = int(page_number) if page_number is not None else 1
+    if idx < 1:
+        raise SdkError("usage_error", provider="rasff", detail=f"page_number must be >=1 (1-based, as the SPA sends it), got \"{page_number}\"")
+    size = int(items_per_page) if items_per_page is not None else 25
+    if not 1 <= size <= 200:
+        raise SdkError("usage_error", provider="rasff",
+                       detail=f"items_per_page must be 1-200 (the browser default is 25; politeness cap — the portal publishes no quota), got \"{items_per_page}\"")
+    params = {"pageNumber": idx, "itemsPerPage": size}
+    subj = str(subject or "").strip()
+    if subj:
+        params["subject"] = subj
+    ref = str(notification_reference or "").strip()
+    if ref:
+        params["notificationReference"] = ref
+    dfrom = _fmt_date(ec_valid_date_from, "ec_valid_date_from")
+    if dfrom:
+        params["ecValidDateFrom"] = dfrom
+    dto = _fmt_date(ec_valid_date_to, "ec_valid_date_to")
+    if dto:
+        params["ecValidDateTo"] = dto
+
+    cookie = _session(cache, no_cache)
+    hdrs = {"Origin": _ORIGIN, "Referer": _REFERER, "Cookie": cookie,
+            "Accept": "application/json, text/plain, */*"}
+    try:
+        r = call_provider(provider, "search", {"parameters": params}, cache=cache, no_cache=no_cache,
+                          extra_headers=hdrs)
+    except SdkError as e:
+        # a dead session cookie (the window re-mints it) → re-collect a FRESH pairing once and resend
+        # (the re-collection is itself uncached, so it runs under no_cache too)
+        if e.status not in (400, 403):
+            raise
+        cookie = _session(None)
+        r = call_provider(provider, "search", {"parameters": params}, cache=cache, no_cache=no_cache,
+                          extra_headers={"Origin": _ORIGIN, "Referer": _REFERER, "Cookie": cookie,
+                                         "Accept": "application/json, text/plain, */*"})
+    return {**notifications_from_upstream(r["data"]), "params": params, "_meta": r}

agentdata/healthcare/rxnav.py

@@ -0,0 +1,67 @@
+"""rxnav — NLM RxNav (drug name → RxCUI normalization + ATC property; keyless; official 20/s per IP — 0.2.8 sped up to 10 rps into the nlm group bucket).
+
+TTL: drug name → RxCUI and the properties are permanent (concepts are immutable, the monthly release is a fallback replay).
+Note: the interaction API is retired (on 2026-10-16 both list/interaction endpoints were measured 404 Not found, including the ONCHigh source) —
+drug interactions are **not in the capability set**; the honest negative result is recorded.
+"""
+
+provider = {
+    "id": "rxnav",
+    "baseUrl": "https://rxnav.nlm.nih.gov/REST",
+    # Official 20/s (RxNav ToS tier A); 10/4 per source (the window's upper bound 14<=20), and over-subscription inside the family is absorbed by the nlm group bucket (10+10=20) as a fallback
+    "rate": {"rps": 10, "burst": 4, "group": "nlm"},
+    "ops": {
+        "rxcuiByName": {"path": "/rxcui.json"},
+        "rxcuiProps": {"path": "/rxcui/{rxcui}/properties.json"},
+        "rxcuiAtc": {"path": "/rxcui/{rxcui}/property.json"},
+    },
+    "ttl": {"rxcuiByName": None, "rxcuiProps": None, "rxcuiAtc": None},
+}
+
+
+def card_from_props(p: dict = None) -> dict:
+    """Probed and confirmed (2026-10-22): synonym is often an empty string rather than null (Lipitor 153165 synonym:"") — an empty string becomes None;
+    tty is the concept-level key (BN=brand name / IN=ingredient name), suppress is the quality flag (N=normal) — tty is the gate on ATC semantics (see get_atc)."""
+    p = p or {}
+    return {
+        "normalized_name": p.get("name"),
+        "synonym": p.get("synonym") or None,
+        "tty": p.get("tty"),
+        "suppress": p.get("suppress"),
+    }
+
+
+def atc_from_upstream(data: dict = None) -> list:
+    """Probed and confirmed: ATC only attaches to ingredient-level (IN) concepts — querying ATC for Lipitor 153165(BN) returns {} with the whole propConceptGroup missing,
+    while atorvastatin 83367(IN) gives C10AA05; a brand-name hit must be lowered to the ingredient level and queried again (the client layer hints at this in reason)."""
+    data = data or {}
+    concepts = ((data.get("propConceptGroup") or {}).get("propConcept")) or []
+    return [c.get("propValue") for c in concepts if c.get("propName") == "ATC" and c.get("propValue")]
+
+
+def get_atc(rxcui: str, cache=None, no_cache: bool = False) -> dict:
+    """RxCUI → the list of ATC codes (a cross-jurisdiction drug name key, the two-key model «RxCUI(US)+ATC(global)»).
+    A concept with no ATC (typically a brand-name level BN concept) returns an empty list — an honest empty set, not an error."""
+    from ..transport import call_provider
+
+    r = call_provider(provider, "rxcuiAtc", {"rxcui": str(rxcui), "propName": "ATC"},
+                      cache=cache, no_cache=no_cache)
+    return {"atc": atc_from_upstream(r.get("data")), "_meta": r}
+
+
+def resolve_drug_name(name: str, cache=None, no_cache: bool = False) -> dict:
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    ids = call_provider(provider, "rxcuiByName", {"name": name}, cache=cache, no_cache=no_cache)
+    rxcuis = ((ids["data"] or {}).get("idGroup") or {}).get("rxnormId") or []
+    if not rxcuis:
+        raise SdkError("upstream_not_found", provider="rxnav", detail=f"RxNav has no RxCUI for this drug name: {name}")
+    rxcui = rxcuis[0]
+    props = call_provider(provider, "rxcuiProps", {"rxcui": rxcui}, cache=cache, no_cache=no_cache)
+    return {
+        "rxcui": rxcui,
+        **card_from_props((props["data"] or {}).get("properties")),
+        **({"all_matches": rxcuis} if len(rxcuis) > 1 else {}),
+        "_meta": {"lookup": ids, "props": props},
+    }