agentdata 0.3.26__py3-none-any.whl

agentdata/healthcare/ca_mdall.py

@@ -0,0 +1,155 @@
+"""ca_mdall — Health Canada Medical Devices Active Licence Listing (MDALL) face provider
+(health-products.canada.ca; keyless — the same host as ca_dpd).
+
+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 /api/medical-devices/company/?lang=en&type=json
+  → the MDALL company register in ONE shot (no pagination surface — 7,682 rows measured 2026-11-02;
+    rows carry company_id (the MDALL join key) + company_name + company_status A/I + postal address
+    + country_cd/region_cd — a rare two-country register: US manufacturers dominate the volume).
+GET /mdall-limh/information?licenceId=111577&type=active&lang=eng
+  → the single-licence dossier as a server-rendered HTML page (the LIMH = Licence Listing search
+    application the site itself uses). **Pit nailed: the search POST (prepareSearch → option=4) is a
+    PRG dance needing a CSRF pairing, but the information GET it redirects to works stateless and
+    session-free — the point-lookup face skips the dance entirely.** A browser-looking referer/cookie
+    is NOT required (a bare GET returns 200). The page shape:
+    h2 Manufacturer → name span + em/span address lines + "Company ID:" span;
+    "Licence No.:" h3 → licence span; Type / Device class / Device first issue date / Licence name
+    label→span pairs; a "Device details" table whose td[headers*=idname] cells are the device
+    identifiers (one row per identifier, grouped under th[namedev*] device names).
+    A 200 page WITHOUT the "Licence No.:" block = no such licence at that type (active vs archived
+    are separate indexes — an archived licence under type=active returns the empty page, not the record).
+Param-minimalism pitfall (same host family as ca_dpd): unprobed params are silently ignored or dump
+full registers — **the /api/medical-devices/device/ endpoint has NO working server-side filter (a
+licence_no filter is ignored → the full 22.8MB device register), which is why the device face here
+is the limh point lookup, not a device listing** — do not widen.
+Local row slicing (limit/skip) is a post-slice over the single cached full shot.
+TTL: companies 7 days (a slowly-changing register) / licence 7 days (issued licences change slowly);
+polite rate 1 rps (the host publishes no quota; shared host with ca_dpd — the host bucket coordinates).
+"""
+import re
+
+from ..errors import SdkError
+
+provider = {
+    "id": "ca_mdall",
+    "baseUrl": "https://health-products.canada.ca",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "companies": {"path": "/api/medical-devices/company/"},  # params: lang/type fixed for this face
+        "licence": {"path": "/mdall-limh/information", "accept": "text"},  # params: licenceId/type/lang (HTML dossier)
+    },
+    "ttl": {"companies": 7 * 86400, "licence": 7 * 86400},
+}
+
+# —— HTML dossier anchors (server-rendered WET page; regex parse — the same style as the ungm row family) ——
+_TAGWS = re.compile(r"<[^>]+>|\s+")
+_MFG = re.compile(r"<h2>Manufacturer</h2>\s*<span\s*>(.*?)</span>", re.S)
+_EM_ADDR = re.compile(r"<em>\s*<span[^>]*>(.*?)</span>\s*</em>", re.S)
+_COMPANY_ID = re.compile(r'Company ID:</span></strong>\s*<span\s*>(.*?)</span>', re.S)
+_LABELLED = re.compile(r'<span\s*>(Licence No\.:|Type:|Device class:|Device first issue date:|Licence name:)</span>\s*(?:</strong>)?\s*<span\s*>(.*?)</span>', re.S)
+# the Licence No. pair sits in its own h3 (no </strong> after it) — a second pattern for that shape:
+_LICNO_H3 = re.compile(r'<h3><span\s*>Licence No\.:</span>\s*<span\s*>(.*?)</span>\s*</h3>', re.S)
+_DEVICE_NAME = re.compile(r'<th id="namedev(\d+)"[^>]*>(.*?)</th>', re.S)
+_DEVICE_ID = re.compile(r'<td headers="datedev(\d+) namedev\d+ idname">(.*?)</td>', re.S)
+_NO_RESULT = re.compile(r'Licence No\.:')  # absence of this marker = the empty page
+
+
+def _txt(x):
+    from html import unescape
+    return _TAGWS.sub(" ", unescape(x or "")).strip() or None
+
+
+def licence_from_upstream(html, licence_id):
+    """LIMH information page HTML → the licence dossier (pure function, offline-testable).
+
+    The labelled pairs come in two shapes (Licence No. lives in an h3; the rest after a </strong>) —
+    both shapes are collected; device identifiers are flattened with their group device name."""
+    if not _NO_RESULT.search(html or ""):
+        return None  # the 200 empty page = no such licence at this type
+    fields = dict(_LABELLED.findall(html))
+    lic = _LICNO_H3.search(html)
+    if lic:
+        fields["Licence No.:"] = lic.group(1)
+    names = {int(i): _txt(x) for i, x in _DEVICE_NAME.findall(html)}
+    # each identifier row names its device group via the headers attribute (datedevN namedevN idname) — the group index is the join
+    identifiers = [{"device_name": names.get(int(g)), "device_identifier": _txt(x)}
+                   for g, x in _DEVICE_ID.findall(html)]
+    return {
+        "licence_id": str(licence_id),
+        "licence_no": _txt(fields.get("Licence No.:")),
+        "licence_name": _txt(fields.get("Licence name:")),
+        "licence_type": _txt(fields.get("Type:")),               # e.g. Device Family
+        "device_class": _txt(fields.get("Device class:")),
+        "first_issue_date": _txt(fields.get("Device first issue date:")),
+        "manufacturer": None if not _MFG.search(html) else {
+            "name": _txt(_MFG.search(html).group(1)),
+            "address": [_txt(x) for x in _EM_ADDR.findall(html) if _txt(x)],
+            "company_id": _txt(_COMPANY_ID.search(html).group(1)) if _COMPANY_ID.search(html) else None,
+        },
+        "device_identifiers": identifiers,
+        "device_names": [n for n in names.values() if n],
+    }
+
+
+def companies_from_upstream(data):
+    """Upstream company array → company rows (pure function, offline-testable)."""
+    rows = [{
+        "company_id": r.get("company_id"),              # the MDALL join key
+        "company_name": r.get("company_name"),
+        "company_status": r.get("company_status"),      # A = active / I = inactive
+        "address": {k: r.get(k) for k in ("addr_line_1", "addr_line_2", "addr_line_3",
+                                          "city", "region_cd", "postal_code", "country_cd")},
+    } for r in (data or []) if isinstance(r, dict)]
+    return {"rows": rows, "count": len(rows)}
+
+
+def companies_raw(*, limit=200, skip=0, cache=None, no_cache=False):
+    """Flat-panel low-level face: the MDALL company register, one full shot (7,682 rows measured
+    2026-11-02) cached whole; limit/skip is a local post-slice.
+
+    → {rows[], count, total, params, _meta} — total = the whole register size (not the page)."""
+    from ..transport import call_provider
+
+    off = int(skip) if skip is not None else 0
+    if off < 0:
+        raise SdkError("usage_error", provider="ca_mdall", detail=f"skip must be >=0, got \"{skip}\"")
+    size = int(limit) if limit is not None else 200
+    if size < 1:
+        raise SdkError("usage_error", provider="ca_mdall", detail=f"limit must be >=1 (local post-slice, no upstream cap), got \"{limit}\"")
+    params = {"lang": "en", "type": "json"}
+    r = call_provider(provider, "companies", params, cache=cache, no_cache=no_cache)
+    out = companies_from_upstream(r["data"])
+    return {"rows": out["rows"][off:off + size], "count": min(size, max(0, out["count"] - off)),
+            "total": out["count"], "params": params, "_meta": r}
+
+
+def licence_raw(licence_id, *, licence_type="active", lang="eng", cache=None, no_cache=False):
+    """Flat-panel low-level face: the MDALL single-licence dossier (LIMH information page, stateless GET).
+
+    licence_id = the numeric MDALL licence number (e.g. 111577); licence_type = active|archived
+    (separate upstream indexes — an archived licence must be asked for with type=archived);
+    lang = eng|fra. A 200 page without the licence block = not_found (no such licence at that type).
+    → {licence dossier…, params, _meta}."""
+    from ..transport import call_provider
+
+    v = str(licence_id or "").strip()
+    if not v.isdigit():
+        raise SdkError("usage_error", provider="ca_mdall",
+                       detail=f"licence_id must be the numeric MDALL licence number (e.g. 111577, echoed from the LIMH listing), got \"{licence_id}\"")
+    t = str(licence_type or "active").strip()
+    if t not in ("active", "archived"):
+        raise SdkError("usage_error", provider="ca_mdall",
+                       detail=f"licence_type must be active|archived (two separate upstream indexes — an inactive licence lives under archived), got \"{licence_type}\"")
+    lg = str(lang or "eng").strip()
+    if lg not in ("eng", "fra"):
+        raise SdkError("usage_error", provider="ca_mdall", detail=f"lang must be eng|fra, got \"{lang}\"")
+    params = {"licenceId": v, "type": t, "lang": lg}
+    r = call_provider(provider, "licence", params, cache=cache, no_cache=no_cache)
+    dossier = licence_from_upstream(r["data"] or "", v)
+    if dossier is None:
+        raise SdkError("upstream_not_found", provider="ca_mdall",
+                       detail=f"no MDALL licence {v} under type={t} (the page returns 200 empty — try licence_type=archived)")
+    # the index param echoes under its upstream name "type"; the dossier's own licence_type is the
+    # page's "Type:" field (Device Family …) — the two live side by side, no clobbering
+    return {**dossier, "type": t, "params": params, "_meta": r}

agentdata/healthcare/cli.py

@@ -0,0 +1,375 @@
+"""healthcare cli — domain command face registration (split per domain in 0.2.6, moved in from the root cli.py; purely flat since the 0.3.0 verb-layer + sugar removal).
+
+register(v, g): registers flat commands on the domain subparser (g = the root _leaf_globals factory,
+passed in as a parameter to avoid a cli ↔ domain-cli cycle); FLAT = the flat dispatch table, merged by the root cli for main to use.
+"""
+import argparse
+
+def register(v, g):
+    # —— Flat panel commands (healthcare main face: source-qualified names + upstream params under original names + our defaults; the only face family since 0.3.0) ——
+    f1 = v.add_parser("au_tga_artg", parents=[g()],
+                       help="AU ARTG registered products (TGA eBS; --query raw words)",
+                       description="Australian Register of Therapeutic Goods: product×sponsor rows (97,988 entries; sponsor = Australian marketing accountability entity)")
+    f1.add_argument("--query", default=None, help="Free-text words, AND across all fields (upstream param: Query; quoted phrase narrows onto the sponsor)")
+    f1.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: Count; cap 100, default 20)")
+    f1.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: Start; default 0)")
+
+    f2 = v.add_parser("au_tga_manufacturers", parents=[g()],
+                       help="AU medical-device manufacturer licences (TGA MIS, single-shot full register)",
+                       description="Australian manufacturer licence register (444 licences, one full shot + state filter); licence × manufacturer edge")
+    f2.add_argument("--state", default=None, help="State filter, e.g. QLD / NSW / VIC (local post-filter on SiteState)")
+    f2.add_argument("--limit", type=int, default=100, help="Rows to return (upstream param: count; cap 500, default 100)")
+
+    # —— 0.3.19 CA + EU product-safety faces (born flat: upstream param original names + closed-set validation; probed 2026-11-02) ——
+
+    f3 = v.add_parser("ca_dpd_companies", parents=[g()],
+                      help="CA DPD company register (one full shot; local limit/skip slice)",
+                      description="Health Canada Drug Product Database companies: 5,253 DIN owners with company_code join key + postal address (no upstream paging — one cached full register)")
+    f3.add_argument("--limit", type=int, default=200, help="Rows to return (local post-slice over the single cached full shot)")
+    f3.add_argument("--skip", type=int, default=0, help="Rows to skip (local post-slice)")
+
+    f4 = v.add_parser("ca_dpd_drug_products", parents=[g()],
+                      help="CA DPD drug products by market status (status closed set)",
+                      description="Drug Product Database products: DIN + brand + company rows, filtered by the Read Me status closed set — status is required (an unknown value is silently ignored upstream and dumps the whole 15MB register)")
+    f4.add_argument("--status", type=int, required=True, help="Market status, closed set 1=Approved 2=Marketed 3=Cancelled Pre-Market 4=Cancelled Post-Market 6=Dormant (validated: any other value silently dumps the full 15MB register)")
+    f4.add_argument("--limit", type=int, default=200, help="Rows to return (local post-slice)")
+    f4.add_argument("--skip", type=int, default=0, help="Rows to skip (local post-slice)")
+
+    f5 = v.add_parser("ca_mdall_companies", parents=[g()],
+                      help="CA MDALL medical-device company register (one full shot; local limit/skip slice)",
+                      description="Medical Devices Active Licence Listing companies: 7,682 device makers/importers (a two-country register — US rows carry country_cd US) with company_id join key + active/inactive status")
+    f5.add_argument("--limit", type=int, default=200, help="Rows to return (local post-slice over the single cached full shot)")
+    f5.add_argument("--skip", type=int, default=0, help="Rows to skip (local post-slice)")
+
+    f6 = v.add_parser("ca_mdall_licence", parents=[g()],
+                      help="CA MDALL single-licence dossier (LIMH information page)",
+                      description="The licence dossier: manufacturer block + Company ID + device class + the device-identifier family — active|archived are separate upstream indexes (ask for inactive licences with --licence-type archived)")
+    f6.add_argument("--licence-id", dest="licence_id", required=True, help="Numeric MDALL licence number (upstream param: licenceId; e.g. 111577)")
+    f6.add_argument("--licence-type", dest="licence_type", default="active", choices=["active", "archived"], help="Licence index (upstream param: type; default active)")
+    f6.add_argument("--lang", default="eng", choices=["eng", "fra"], help="Language (upstream param: lang; default eng)")
+
+    f7 = v.add_parser("ctgov_studies", parents=[g()],
+                      help="Clinical-trial search (CT.gov v2; --query.term upstream syntax)",
+                      description="Clinical trials: raw syntax via --query.term, structured --query.cond/--filter.advanced combine with either; bare call = first page of all studies (legal upstream)")
+    f7.add_argument("--query.term", dest="query_term", default=None, help="Raw query expression (upstream param: query.term; AREA[…] syntax, e.g. 'AREA[LeadSponsorName](\"Pfizer\")')")
+    f7.add_argument("--query.titles", dest="query_titles", default=None, help="Title-field search (upstream param: query.titles; combinable; aspirin 2983→967)")
+    f7.add_argument("--query.intr", dest="query_intr", default=None, help="Intervention-field search (upstream param: query.intr; combinable; insulin 21109→8229)")
+    f7.add_argument("--query.cond", dest="query_cond", default=None, help="Condition search (upstream param: query.cond; combinable)")
+    f7.add_argument("--filter.advanced", dest="filter_advanced", default=None, help="Advanced filter, AREA[…] syntax (upstream param: filter.advanced; combinable)")
+    f7.add_argument("--agg-filters", dest="agg_filters", default=None, help="Facet filter (upstream param: aggFilters; numeric enum values, e.g. phase:3 — PHASE3 → 0 hits)")
+    f7.add_argument("--fields", default=None, help="Row slimming, comma-separated (upstream param: fields; e.g. NCTId,BriefTitle)")
+    f7.add_argument("--page-size", dest="page_size", type=int, default=20, help="Rows per page (upstream param: pageSize; default 20, no enforced cap)")
+    f7.add_argument("--page-token", dest="page_token", default=None, help="Pagination token (upstream param: pageToken; feed next_page_token)")
+    f7.add_argument("--sort", default=None, help="Sort (upstream param: sort; e.g. EnrollmentCount:desc)")
+    f7.add_argument("--count-total", dest="count_total", action=argparse.BooleanOptionalAction, default=True,
+                    help="Request totalCount (upstream param: countTotal; default on)")
+
+    f8 = v.add_parser("dailymed_spls", parents=[g()],
+                      help="Drug labeling SPL metadata (DailyMed spls.json)",
+                      description="SPL labeling metadata: setid + title + source URL (full-text XML via the URL); manufacturer/setid filters and page/pagesize/sort pass through upstream verbatim")
+    f8.add_argument("--search", default=None, help="Drug name (upstream param: drug_name; raw channel)")
+    f8.add_argument("--manufacturer", default=None, help="Labeler filter (upstream param: manufacturer; e.g. Pfizer)")
+    f8.add_argument("--setid", default=None, help="Exact SPL setid filter (upstream param: setid)")
+    f8.add_argument("--page", type=int, default=None, help="Page number (upstream param: page)")
+    f8.add_argument("--pagesize", type=int, default=None, help="Rows per page (upstream param: pagesize; silent clamp at 100 — echoed as elements_per_page)")
+    f8.add_argument("--sort", default=None, help="Sort (upstream param: sort; e.g. published_date)")
+
+    f9 = v.add_parser("epmc_search", parents=[g()],
+                      help="Literature evidence (Europe PMC; --search upstream syntax)",
+                      description="Literature search incl. full PubMed: raw query syntax via --search (AFF: for affiliations); cursor pagination via next_cursor_mark")
+    f9.add_argument("--search", default=None, help="Raw query expression (upstream param: query; e.g. 'AFF:\"Novartis\" AND \"psoriasis\"')")
+    f9.add_argument("--result-type", dest="result_type", default="lite", choices=["lite", "core", "full", "idlist"],
+                    help="Row depth (upstream param: resultType; default lite)")
+    f9.add_argument("--page-size", dest="page_size", type=int, default=25, help="Rows per page (upstream param: pageSize; 1-1000, default 25)")
+    f9.add_argument("--cursor-mark", dest="cursor_mark", default="*", help="Pagination cursor (upstream param: cursorMark; * = first page)")
+    f9.add_argument("--sort", default=None, help="Sort (upstream param: sort; e.g. 'CITED desc')")
+
+    f10 = v.add_parser("eudamed_devices_udi_di_data", parents=[g()],
+                      help="EU device master record (EUDAMED primaryDi exact + upstream pagination)",
+                      description="EU device record: manufacturer SRN + EU authorised-rep SRN edges (cold ~50s — primaryDi is unindexed upstream)")
+    f10.add_argument("--primary-di", dest="primary_di", required=True, help="EU UDI-DI (upstream param: primaryDi)")
+    f10.add_argument("--page", type=int, default=0, help="Page number (upstream param: page; default 0)")
+    f10.add_argument("--page-size", dest="page_size", type=int, default=5, help="Rows per page (upstream param: pageSize; default 5)")
+    f10.add_argument("--iso2-code", dest="iso2_code", default="en", help="Language (upstream param: iso2Code; default en)")
+
+    f11 = v.add_parser("fda_crl_letters", parents=[g()],
+                       help="FDA Complete Response Letters (openFDA transparency/crl; upstream-verbatim params)",
+                       description="Complete Response Letters: company × negative-approval events (approval_status = application outcome "
+                   "after the letter). company_rep (person name, PII) and text (OCR noise) are dropped at the row-shaping layer. "
+                   "Zero hits = valid answer (404 NOT_FOUND)")
+    f11.add_argument("--search", default=None, help="Raw query expression (upstream param: search; e.g. 'company_name:\"Firm Name\"' — required)")
+    f11.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: limit; 1-1000 hard wall, default 20)")
+    f11.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: skip; default 0)")
+    f11.add_argument("--sort", default="letter_date:desc", help="Sort (upstream param: sort; our default letter_date:desc)")
+
+    # —— Wave 10b openFDA family, seven faces (2026-10-29; born flat: upstream param original names only, zero sugar, zero deprecation debt) ——
+
+    f12 = v.add_parser("fda_device_510k", parents=[g()],
+                       help="FDA device 510(k) clearances (openFDA device/510k; upstream-verbatim params)",
+                       description="Premarket notification clearances (176,466 rows): k_number × applicant with decision "
+                                   "code/date. contact (person name, PII) and the openfda blob (100+ registration numbers "
+                                   "per row) are dropped at the row-shaping layer. Zero hits = valid answer")
+    f12.add_argument("--search", default=None, help="Raw query expression (upstream param: search; e.g. 'applicant:\"Medtronic\"' — required)")
+    f12.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: limit; 1-1000 hard wall, default 20)")
+    f12.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: skip; default 0)")
+    f12.add_argument("--sort", default=None, help="Sort (upstream param: sort; our default decision_date:desc)")
+
+    f13 = v.add_parser("fda_device_classification", parents=[g()],
+                       help="FDA device product-code classification (openFDA device/classification; upstream-verbatim params)",
+                       description="Product-code taxonomy (device_name × product_code × device_class with 21 CFR regulation "
+                                   "number); no date field, so no default sort. product_code joins the 510(k)/PMA/recall "
+                                   "faces. Zero hits = valid answer")
+    f13.add_argument("--search", default=None, help="Raw query expression (upstream param: search; e.g. 'device_name:\"syringe\"' — required)")
+    f13.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: limit; 1-1000 hard wall, default 20)")
+    f13.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: skip; default 0)")
+    f13.add_argument("--sort", default=None, help="Sort (upstream param: sort; no default — this face has no date field)")
+
+    f14 = v.add_parser("fda_device_pma", parents=[g()],
+                       help="FDA device PMA approvals (openFDA device/pma; upstream-verbatim params)",
+                       description="Premarket approvals + supplements (12,896 rows): pma_number × applicant with decision "
+                                   "code/date. ao_statement (long text) and street-level address are dropped. "
+                                   "Zero hits = valid answer")
+    f14.add_argument("--search", default=None, help="Raw query expression (upstream param: search; e.g. 'applicant:\"Medtronic\"' — required)")
+    f14.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: limit; 1-1000 hard wall, default 20)")
+    f14.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: skip; default 0)")
+    f14.add_argument("--sort", default=None, help="Sort (upstream param: sort; our default decision_date:desc)")
+
+    f15 = v.add_parser("fda_device_recalls", parents=[g()],
+                       help="FDA device recalls (openFDA device/recall RES system; upstream-verbatim params)",
+                       description="Device recalls from the RES system (incl. Ongoing full lifecycle; a different system from the bulk-loaded "
+                   "device/enforcement press releases). Rows carry firm_fei_number + k_numbers hub keys. "
+                   "Firm matching uses the phrase form (probed 2026-10-28)")
+    f15.add_argument("--search", default=None, help="Raw query expression (upstream param: search; e.g. 'recalling_firm:\"Firm Name\"' phrase — .exact unprobed; required)")
+    f15.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: limit; 1-1000 hard wall, default 20)")
+    f15.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: skip; default 0)")
+    f15.add_argument("--sort", default=None, help="Sort (upstream param: sort; our default event_date_posted:desc)")
+
+    f16 = v.add_parser("fda_device_registrations", parents=[g()],
+                       help="FDA device establishment registrations (openFDA device/registrationlisting; upstream-verbatim params)",
+                       description="Establishment registration & listing (336,946 rows, quarterly): registration_number/fei_number "
+                                   "× firm_name. All searchable fields live in the registration.* namespace (top-level "
+                                   "firm_name/fei_number don't match — probed 2026-10-29). us_agent and "
+                                   "official_correspondent (person contacts, PII) are dropped. Zero hits = valid answer")
+    f16.add_argument("--search", default=None, help="Raw query expression (upstream param: search; e.g. 'registration.name:\"Firm Name\"' — required)")
+    f16.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: limit; 1-1000 hard wall, default 20)")
+    f16.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: skip; default 0)")
+    f16.add_argument("--sort", default=None, help="Sort (upstream param: sort; our default registration.reg_expiry_date_year:desc)")
+
+    f17 = v.add_parser("fda_drug_approvals", parents=[g()],
+                       help="FDA drug application/approval records (openFDA drug/drugsfda; upstream-verbatim params)",
+                       description="Drugs@FDA application dossiers (29,420 applications): application_number × sponsor_name "
+                                   "with products[] and submissions[] timelines. Company search uses sponsor_name "
+                                   "(applicant_name is a docs illusion — probed 2026-10-29). Zero hits = valid answer")
+    f17.add_argument("--search", default=None, help="Raw query expression (upstream param: search; e.g. 'sponsor_name:\"TEVA\"' — keyword field is case-sensitive, match stored form; required)")
+    f17.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: limit; 1-1000 hard wall, default 20)")
+    f17.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: skip; default 0)")
+    f17.add_argument("--sort", default=None, help="Sort (upstream param: sort; our default submissions.submission_status_date:desc)")
+
+    f18 = v.add_parser("fda_drug_catalog", parents=[g()],
+                       help="FDA NDC directory (openFDA drug/ndc; upstream-verbatim params)",
+                       description="NDC product catalog (daily refresh): product_ndc × labeler_name with marketing dates and "
+                                   "category — NSDE content lives here (the separate /drug/nsde.json endpoint is dead, "
+                                   "probed 2026-10-29). Zero hits = valid answer")
+    f18.add_argument("--search", default=None, help="Raw query expression (upstream param: search; e.g. 'labeler_name:\"pfizer\"' — required)")
+    f18.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: limit; 1-1000 hard wall, default 20)")
+    f18.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: skip; default 0)")
+    f18.add_argument("--sort", default=None, help="Sort (upstream param: sort; our default marketing_start_date:desc)")
+
+    f19 = v.add_parser("fda_drug_recalls", parents=[g()],
+                       help="FDA drug recalls (openFDA drug/enforcement; upstream-verbatim params)",
+                       description="Drug recall/enforcement records 2012+ (press-release source — drug has no separate recall endpoint): "
+                                   "recall_number × recalling_firm with class/status/reason. Zero hits = valid answer (404 NOT_FOUND)")
+    f19.add_argument("--search", default=None, help="Raw query expression (upstream param: search; e.g. 'recalling_firm.exact:\"Firm Name\"' — required)")
+    f19.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: limit; 1-1000 hard wall, default 20)")
+    f19.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: skip; default 0)")
+    f19.add_argument("--sort", default=None, help="Sort (upstream param: sort; our default report_date:desc)")
+
+    f20 = v.add_parser("fda_drug_shortages", parents=[g()],
+                      help="FDA drug shortages (openFDA; --search upstream syntax)",
+                      description="Drug-shortage records: supply-risk event stream (status/availability/reason); limit 1-1000 is an upstream hard wall, deeper via --skip")
+    f20.add_argument("--search", default=None, help="Raw query expression (upstream param: search; e.g. 'generic_name:\"bupivacaine\"' or 'openfda.manufacturer_name.exact:\"Fresenius Kabi USA, LLC\"')")
+    f20.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: limit; 1-1000 hard wall, default 20)")
+    f20.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: skip; default 0)")
+    f20.add_argument("--sort", default="update_date:desc", help="Sort (upstream param: sort; our default update_date:desc)")
+
+    f21 = v.add_parser("fda_food_recalls", parents=[g()],
+                       help="FDA food recalls (openFDA food/enforcement; upstream-verbatim params)",
+                       description="Food recall/enforcement records 2012+: recall_number × recalling_firm with class/status/reason. "
+                                   "Zero hits = valid answer (404 NOT_FOUND)")
+    f21.add_argument("--search", default=None, help="Raw query expression (upstream param: search; e.g. 'recalling_firm.exact:\"Firm Name\"' — required)")
+    f21.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: limit; 1-1000 hard wall, default 20)")
+    f21.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: skip; default 0)")
+    f21.add_argument("--sort", default=None, help="Sort (upstream param: sort; our default report_date:desc)")
+
+    f22 = v.add_parser("fda_orangebook", parents=[g()],
+                       help="FDA Orange Book approved drugs (openFDA drug/orangebook; upstream-verbatim params)",
+                       description="Orange Book approved-drug products (48,865 rows): approval_date × application holder with "
+                                   "RLD/reference-standard flags. Company keys sit inside products[] (application_name / "
+                                   "application_full_name — top-level applicant fields don't exist, probed 2026-10-29). "
+                                   "Zero hits = valid answer")
+    f22.add_argument("--search", default=None, help="Raw query expression (upstream param: search; e.g. 'products.application_full_name:\"Teva\"' — required)")
+    f22.add_argument("--limit", type=int, default=20, help="Rows to return (upstream param: limit; 1-1000 hard wall, default 20)")
+    f22.add_argument("--skip", type=int, default=0, help="Rows to skip (upstream param: skip; default 0)")
+    f22.add_argument("--sort", default=None, help="Sort (upstream param: sort; our default approval_date:desc)")
+
+    # —— 0.3.16 UK MHRA safety-alert twin faces (gov.uk search/content API, same contract family as the gb_cma case chain; stood up from live probing 2026-10-30) ——
+
+    f23 = v.add_parser("gb_mhra_alert", parents=[g()],
+                       help="UK MHRA single-alert dossier (gov.uk content API)",
+                       description="UK MHRA single safety-alert dossier (keyless): content_id is the stable UUID key; "
+                                   "alert_type/issued_date are the MHRA metadata fields (medicines-recall-notification, "
+                                   "device-field-safety-notice …); attachments = the notice PDF family. The content API "
+                                   "has no .json variant — a trailing .json serves the 404 page (a pasted slug with it "
+                                   "gets it stripped); a pasted full base_path (/drug-device-alerts/<slug> or absolute "
+                                   "URL) is accepted — the prefix is stripped")
+    f23.add_argument("--slug", required=True, help="Alert slug (from gb_mhra_alerts rows; bare tail segment, e.g. class-2-medicines-recall-xeal-pharma-clopidogrel-oral-liquids-all-strengths-el-26-a-slash-43)")
+
+    f24 = v.add_parser("gb_mhra_alerts", parents=[g()],
+                       help="UK MHRA medicines & device safety alerts (drug alerts, device alerts, FSN weeklies)",
+                       description="UK MHRA safety-alert search (gov.uk search API, keyless): q verbatim over alert "
+                                   "titles/bodies — a company-name penetration channel (Abbott → 160 alerts across "
+                                   "2019-2026, probed 2026-10-30); count politeness cap 100; start = offset "
+                                   "pagination; omit --q to enumerate the full live register (~1,462 alerts). "
+                                   "Single-alert detail: gb_mhra_alert with the slug from each row (under a q= query "
+                                   "the rows drop link — the row mapper then reads the _id base_path)")
+    f24.add_argument("--q", default=None, help="Query term (upstream param: q; company/product names penetrate — e.g. Abbott, recall class)")
+    f24.add_argument("--count", type=int, default=20, help="Rows (upstream param: count; 1-100 politeness cap)")
+    f24.add_argument("--start", type=int, default=0, help="Offset (upstream param: start)")
+
+    f25 = v.add_parser("gudid_devices", parents=[g()],
+                      help="US device master record (AccessGUDID v3, one of di/udi/record_key)",
+                      description="US device record: brand/company/product codes (exactly one of --di / --udi / --record-key)")
+    f25.add_argument("--di", default=None, help="Device Identifier (upstream param: di)")
+    f25.add_argument("--udi", default=None, help="Full UDI (upstream param: udi)")
+    f25.add_argument("--record-key", dest="record_key", default=None, help="Record key (upstream param: record_key)")
+
+    f26 = v.add_parser("mesh_descriptor", parents=[g()],
+                      help="Term→MeSH descriptor + synonym pool (NLM lookup API)",
+                      description="Drug/disease term → MeSH descriptor candidates + top hit's synonym pool (controlled-vocabulary anchor)")
+    f26.add_argument("--label", required=True, help="Term to look up (upstream param: label — passing term/descriptor gets 400)")
+    f26.add_argument("--match", default="contains", choices=["contains", "exact", "startswith"],
+                    help="Match mode (upstream param: match; default contains)")
+    f26.add_argument("--limit", type=int, default=10, help="Candidates cap (upstream param: limit; default 10, cap 50)")
+
+    f27 = v.add_parser("rasff_notifications", parents=[g()],
+                       help="EU RASFF food-safety alert search (window backend)",
+                       description="The consolidated English RASFF window: subject/reference/date-window filters (the proven ones — enum-shaped country filters stay unprobed upstream) + paging; 33k-notification corpus, notifying country × product × risk rows")
+    f27.add_argument("--subject", default=None, help="Free text on the alert subject (upstream param: subject; e.g. aflatoxin)")
+    f27.add_argument("--notification-reference", dest="notification_reference", default=None, help="Reference number, exact (upstream param: notificationReference; e.g. 2026.9701)")
+    f27.add_argument("--ec-valid-date-from", dest="ec_valid_date_from", default=None, help="Window start (upstream param: ecValidDateFrom; format dd-MM-yyyy, e.g. 01-09-2026 — ISO input is rejected upstream)")
+    f27.add_argument("--ec-valid-date-to", dest="ec_valid_date_to", default=None, help="Window end (upstream param: ecValidDateTo; format dd-MM-yyyy)")
+    f27.add_argument("--page-number", dest="page_number", type=int, default=1, help="Page number, 1-based (upstream param: pageNumber)")
+    f27.add_argument("--items-per-page", dest="items_per_page", type=int, default=25, help="Rows per page (upstream param: itemsPerPage; browser default 25, politeness cap 200)")
+
+    f28 = v.add_parser("rxnav_rxcui_atc", parents=[g()],
+                      help="RxCUI→ATC class (RxNav property.json?propName=ATC)",
+                      description="RxCUI → ATC classification (numeric RxCUI only; resolve names first via rxnav_rxcui_by_name)")
+    f28.add_argument("--rxcui", required=True, help="Numeric RxCUI (upstream param: rxcui)")
+
+    f29 = v.add_parser("rxnav_rxcui_by_name", parents=[g()],
+                      help="Drug name→RxCUI card (RxNav rxcuiByName)",
+                      description="Identity normalization: drug/brand name → RxCUI (single-record face, no pagination)")
+    f29.add_argument("--name", required=True, help="Drug or brand name (upstream param: name)")
+
+    f30 = v.add_parser("safety_gate_alerts", parents=[g()],
+                       help="EU Safety Gate weekly-report index (one XML, 2005→now)",
+                       description="The ex-RAPEX rapid-alert system's weekly-report index: 1,122 reports with report_id join keys; year is a local post-filter (the upstream always serves the whole index)")
+    f30.add_argument("--year", default=None, help="Report year, a local post-filter (not an upstream param; e.g. 2026)")
+    f30.add_argument("--limit", type=int, default=200, help="Rows to return (local post-slice over the single cached index)")
+    f30.add_argument("--skip", type=int, default=0, help="Rows to skip (local post-slice)")
+
+    f31 = v.add_parser("safety_gate_report", parents=[g()],
+                       help="EU Safety Gate one weekly report's alerts (detail XML)",
+                       description="A single weekly report's alert rows: case number / product / risk type / level / notifying country / country of origin / online trader — the company-relevant edges of the non-food product-safety regime")
+    f31.add_argument("--report-id", dest="report_id", required=True, help="Numeric report id (the report_id field echoed by safety_gate_alerts; e.g. 10000329 — a pasted detail URL also works)")
+    f31.add_argument("--limit", type=int, default=200, help="Rows to return (local post-slice)")
+    f31.add_argument("--skip", type=int, default=0, help="Rows to skip (local post-slice)")
+
+    # —— Wave 10 openFDA family, four faces (2026-10-28; born flat: upstream param original names only, zero sugar, zero deprecation debt) ——
+
+FLAT = {
+    "au_tga_artg": lambda a: {"query": a.query, "limit": a.limit, "skip": a.skip},
+    "au_tga_manufacturers": lambda a: {"state": a.state, "limit": a.limit},
+    # 0.3.19 CA + EU product-safety faces (born flat: upstream params verbatim + closed-set validation; local post-slices marked)
+    "ca_dpd_companies": lambda a: {"limit": a.limit, "skip": a.skip},
+    "ca_dpd_drug_products": lambda a: {"status": a.status, "limit": a.limit, "skip": a.skip},
+    "ca_mdall_companies": lambda a: {"limit": a.limit, "skip": a.skip},
+    "ca_mdall_licence": lambda a: {"licence_id": a.licence_id, "licence_type": a.licence_type,
+                                   "lang": a.lang},
+    "ctgov_studies": lambda a: {"query_term": a.query_term, "query_titles": a.query_titles,
+                               "query_intr": a.query_intr, "query_cond": a.query_cond,
+                               "filter_advanced": a.filter_advanced, "agg_filters": a.agg_filters,
+                               "fields": a.fields,
+                               "page_size": a.page_size, "page_token": a.page_token,
+                               "sort": a.sort, "count_total": a.count_total},
+    "dailymed_spls": lambda a: {"search": a.search, "manufacturer": a.manufacturer,
+                                 "setid": a.setid, "page": a.page, "pagesize": a.pagesize, "sort": a.sort},
+    "epmc_search": lambda a: {"search": a.search, "result_type": a.result_type,
+                                "page_size": a.page_size, "cursor_mark": a.cursor_mark, "sort": a.sort},
+    "eudamed_devices_udi_di_data": lambda a: {"primary_di": a.primary_di, "page": a.page,
+                                 "page_size": a.page_size, "iso2_code": a.iso2_code},
+    "fda_crl_letters": lambda a: {"search": a.search, "limit": a.limit, "skip": a.skip, "sort": a.sort},
+    # Wave 10b openFDA family, seven faces (born flat: upstream param names passed through, no sugar keys)
+    "fda_device_510k": lambda a: {"search": a.search, "limit": a.limit, "skip": a.skip, "sort": a.sort},
+    "fda_device_classification": lambda a: {"search": a.search, "limit": a.limit, "skip": a.skip, "sort": a.sort},
+    "fda_device_pma": lambda a: {"search": a.search, "limit": a.limit, "skip": a.skip, "sort": a.sort},
+    "fda_device_recalls": lambda a: {"search": a.search, "limit": a.limit, "skip": a.skip, "sort": a.sort},
+    "fda_device_registrations": lambda a: {"search": a.search, "limit": a.limit, "skip": a.skip, "sort": a.sort},
+    "fda_drug_approvals": lambda a: {"search": a.search, "limit": a.limit, "skip": a.skip, "sort": a.sort},
+    "fda_drug_catalog": lambda a: {"search": a.search, "limit": a.limit, "skip": a.skip, "sort": a.sort},
+    "fda_drug_recalls": lambda a: {"search": a.search, "limit": a.limit, "skip": a.skip, "sort": a.sort},
+    "fda_drug_shortages": lambda a: {"search": a.search,
+                                     "limit": a.limit, "skip": a.skip, "sort": a.sort},
+    "fda_food_recalls": lambda a: {"search": a.search, "limit": a.limit, "skip": a.skip, "sort": a.sort},
+    "fda_orangebook": lambda a: {"search": a.search, "limit": a.limit, "skip": a.skip, "sort": a.sort},
+    # 0.3.16 UK MHRA safety-alert twin faces (gov.uk search/content API; upstream param names verbatim + our polite tier)
+    "gb_mhra_alert": lambda a: {"slug": a.slug},
+    "gb_mhra_alerts": lambda a: {"q": a.q, "count": a.count, "start": a.start},
+    "gudid_devices": lambda a: {"di": a.di, "udi": a.udi, "record_key": a.record_key},
+    "mesh_descriptor": lambda a: {"label": a.label, "match": a.match, "limit": a.limit},
+    "rasff_notifications": lambda a: {"subject": a.subject, "notification_reference": a.notification_reference,
+                                      "ec_valid_date_from": a.ec_valid_date_from, "ec_valid_date_to": a.ec_valid_date_to,
+                                      "page_number": a.page_number, "items_per_page": a.items_per_page},
+    "rxnav_rxcui_atc": lambda a: {"rxcui": a.rxcui},
+    "rxnav_rxcui_by_name": lambda a: {"name": a.name},
+    "safety_gate_alerts": lambda a: {"year": a.year, "limit": a.limit, "skip": a.skip},
+    "safety_gate_report": lambda a: {"report_id": a.report_id, "limit": a.limit, "skip": a.skip},
+    # Wave 10 openFDA family, four faces (born flat: upstream param names passed through, no sugar keys)
+}
+
+
+# 0.3.10 jurisdiction chapter: face → jurisdiction (default = the issuing authority's jurisdiction; bodies
+# covering global phenomena = GLOBAL; vocabulary = ISO-3166 alpha-2 + EU + GLOBAL) — merged into _JURISDICTION by the root cli.py; success envelopes carry the jurisdiction chapter
+COUNTRY = {
+    "au_tga_artg": "AU",
+    "au_tga_manufacturers": "AU",
+    "ca_dpd_companies": "CA",
+    "ca_dpd_drug_products": "CA",
+    "ca_mdall_companies": "CA",
+    "ca_mdall_licence": "CA",
+    "ctgov_studies": "US",
+    "dailymed_spls": "US",
+    "epmc_search": "GLOBAL",
+    "eudamed_devices_udi_di_data": "EU",
+    "fda_crl_letters": "US",
+    "fda_device_510k": "US",
+    "fda_device_classification": "US",
+    "fda_device_pma": "US",
+    "fda_device_recalls": "US",
+    "fda_device_registrations": "US",
+    "fda_drug_approvals": "US",
+    "fda_drug_catalog": "US",
+    "fda_drug_recalls": "US",
+    "fda_drug_shortages": "US",
+    "fda_food_recalls": "US",
+    "fda_orangebook": "US",
+    "gb_mhra_alert": "GB",
+    "gb_mhra_alerts": "GB",
+    "gudid_devices": "US",
+    "mesh_descriptor": "GLOBAL",
+    "rasff_notifications": "EU",
+    "rxnav_rxcui_atc": "US",
+    "rxnav_rxcui_by_name": "US",
+    "safety_gate_alerts": "EU",
+    "safety_gate_report": "EU",
+}