agentdata 0.3.26__py3-none-any.whl

agentdata/healthcare/fda_crl.py

@@ -0,0 +1,86 @@
+"""fda_crl — FDA Complete Response Letters provider (openFDA transparency/crl.json; keyless).
+
+Fourth of the four Wave 10 healthcare faces. A CRL is the closing letter of a drug application review: FDA's formal
+"cannot approve" letter for an NDA/ANDA application — a **company × negative-approval event** stream (approval-risk face).
+The contract is shared with the shortages/recalls family: GET /transparency/crl.json?search=&limit=&skip=&sort=,
+zero hits = HTTP 404 NOT_FOUND is a legal answer (the empty envelope is not cached).
+Row shape measured 2026-10-28: company_name:"InnoPharma" → 3 hits;
+rows have 13 keys, and **company_rep (the letter recipient's representative) and approver_name (the issuing officer) are both person names and are not returned, nor is text (OCR full-text
+noise)** — PII red line + noise reduction (aligned with the PhilGEPS Contact Person / UK IIR personal-face precedents).
+TTL 30d (a historical letter face, near-zero increments); rate limit is the polite 2 rps shared by the same-host family.
+"""
+from datetime import datetime, timezone
+
+from ..errors import SdkError
+
+provider = {
+    "id": "fda_crl",
+    "baseUrl": "https://api.fda.gov",
+    "rate": {"rps": 2, "burst": 5, "group": "fda"},
+    "ops": {
+        "search": {"path": "/transparency/crl.json", "notFound": [404]},  # params: search, limit, skip, sort
+    },
+    "ttl": {"search": 30 * 24 * 3600},
+}
+
+
+def rows_from_upstream(results):
+    """Upstream rows → CRL rows (pure function, testable offline; key order verified against the 13 keys seen on 2026-10-28).
+
+    company_rep (the letter recipient's representative) and approver_name (the issuing officer) are both person names and are not returned — PII red line;
+    text (OCR full-text noise) is not returned — noise reduction.
+    """
+    rows = results if isinstance(results, list) else []
+    out = []
+    for r in rows:
+        out.append({
+            "company_name": r.get("company_name"),          # company edge, primary column
+            "company_address": r.get("company_address"),
+            "letter_date": r.get("letter_date"),
+            "letter_year": r.get("letter_year"),
+            "letter_type": r.get("letter_type"),
+            "application_number": r.get("application_number"),  # links to the drugsfda application line
+            "approval_status": r.get("approval_status"),    # application outcome after the CRL
+            "file_name": r.get("file_name"),                # key of the original letter PDF
+            "approver_center": r.get("approver_center"),    # issuing center (organizational side, e.g. CDER)
+            "approver_title": r.get("approver_title"),      # issuing officer's title (organizational side)
+        })
+    return out
+
+
+def search(search, *, limit=20, skip=0, sort="letter_date:desc", cache=None, no_cache=False):
+    """Born flat: the search expression is passed through verbatim (upstream param names search/limit/skip/sort, zero sugar).
+    limit 1-1000 (the openFDA search hard limit); search is required (local safety gate: a bare full-table query is served by the bulk harvest line).
+    → {rows[], total, count, skip, limit_applied, has_more, search, sort, _meta}; zero hits = an empty set that is not cached.
+    """
+    from ..transport import call_provider
+
+    q = str(search or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider=provider["id"],
+                       detail="search requires an expression (e.g. company_name:\"Firm Name\"; a bare full-table query is served by the bulk line)")
+    size = int(limit) if limit is not None else 20  # 0 is an explicitly bad value (do not let `or` swallow it into the default); the gate below rejects it
+    if not 1 <= size <= 1000:
+        raise SdkError("usage_error", provider=provider["id"],
+                       detail=f"limit must be 1-1000 (the openFDA search hard limit, same as measured for shortages), got {size}")
+    sk = max(0, int(skip or 0))
+    so = str(sort or "").strip()
+    params = {"search": q, "limit": size}
+    if sk:
+        params["skip"] = sk
+    if so:
+        params["sort"] = so
+    try:
+        r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    except SdkError as e:
+        if e.code == "upstream_not_found":
+            return {"rows": [], "total": 0, "count": 0, "skip": sk, "limit_applied": size,
+                    "has_more": False, "search": q, "sort": so or None,
+                    "_meta": {"from_cache": False,
+                              "fetched_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")}}
+        raise
+    data = r.get("data") or {}
+    rows = rows_from_upstream(data.get("results"))
+    total = (data.get("meta") or {}).get("results", {}).get("total", len(rows))
+    return {"rows": rows, "total": total, "count": len(rows), "skip": sk, "limit_applied": size,
+            "has_more": total > sk + len(rows), "search": q, "sort": so or None, "_meta": r}

agentdata/healthcare/fda_devices.py

@@ -0,0 +1,199 @@
+"""fda_devices — FDA device provider, four faces (openFDA device/510k · pma · registrationlisting · classification; keyless).
+
+Wave 10b of the healthcare domain (second batch; row shapes measured 2026-10-29).
+The family contract is shared with fda_recalls/shortages/fda_drugs: GET /<ep>.json?search=&limit=&skip=&sort=,
+zero hits = HTTP 404 {"error":{"code":"NOT_FOUND"}} is a legal answer (notFound:[404] → an empty envelope that is not cached).
+Probing anchors on 2026-10-29 (field names verified by _exists_, not inferred from the docs):
+  device/510k (176,466 clearances): company field = **applicant** (the same name as pma; the docs once said applicant_name — overturned);
+    **contact (a person-name slot, e.g. Marybeth Gamber) is not returned — the same PII red line as additional_info_contact on Wave 10 device recalls**;
+    openfda.registration_number can carry 100+ entries on one row (row inflation), so the whole slot is not returned.
+  device/pma (12,896 approvals): company field = applicant; ao_statement (long approval text) is not returned (row slimming, same precedent as CRL text);
+    street_1/2+zip are not returned (street-level address; city/state are kept).
+  device/registrationlisting (336,946 registration rows, quarterly): company fields = **registration.name + registration.owner_operator.firm_name**
+    (three keys: registration_number/fei_number/owner_operator_number; the top-level firm_name/fei_number etc. all 404 under _exists_ —
+    everything lives in the registration.* namespace; the default sort on the nested key registration.reg_expiry_date_year:desc was measured to work).
+    **registration.us_agent (US agent name+phone+email+address) and owner_operator.official_correspondent (personal contact) are not returned — PII red line**.
+  device/classification (the product-code taxonomy face): no date field → no default sort; the openfda sub-object is small (k_number/registration_number
+    /fei_number cross keys), so it is kept whole.
+Rate limit: the openFDA family shares a keyless quota (polite 2 rps per face, the family total must stay under ~4 rps).
+TTL: 510k/pma 24h, registrations 7d (quarterly), classification 30d (the taxonomy is near-static).
+"""
+from datetime import datetime, timezone
+
+from ..errors import SdkError
+
+provider = {
+    "id": "fda_devices",
+    "baseUrl": "https://api.fda.gov",
+    "rate": {"rps": 2, "burst": 5, "group": "fda"},
+    "ops": {
+        "clearance_510k": {"path": "/device/510k.json", "notFound": [404]},
+        "pma": {"path": "/device/pma.json", "notFound": [404]},
+        "registrations": {"path": "/device/registrationlisting.json", "notFound": [404]},
+        "classification": {"path": "/device/classification.json", "notFound": [404]},
+    },
+    "ttl": {"clearance_510k": 24 * 3600, "pma": 24 * 3600,
+            "registrations": 7 * 24 * 3600, "classification": 30 * 24 * 3600},
+}
+
+# Default sort per face (our default, not the upstream one; classification has no date field → None)
+_DEFAULT_SORT = {"clearance_510k": "decision_date:desc",
+                 "pma": "decision_date:desc",
+                 "registrations": "registration.reg_expiry_date_year:desc"}
+
+
+def _k510_rows(results):
+    """device/510k rows → premarket notification clearance rows (pure function, testable offline). Key order verified against the 2026-10-29 probe of k510.ex2.json.
+
+    contact (the applicant's contact, often a person name) and openfda (a registration_number list with 100+ entries per row) are not returned.
+    """
+    out = []
+    for r in results if isinstance(results, list) else []:
+        out.append({
+            "k_number": r.get("k_number"),                            # hub key (links to the recall k_numbers)
+            "applicant": r.get("applicant"),                          # company edge, primary column (the applicant)
+            "device_name": r.get("device_name"),
+            "clearance_type": r.get("clearance_type"),
+            "decision_code": r.get("decision_code"),                  # SESE/SE/…
+            "decision_description": r.get("decision_description"),
+            "decision_date": r.get("decision_date"),                  # ISO date
+            "date_received": r.get("date_received"),
+            "expedited_review_flag": r.get("expedited_review_flag"),
+            "third_party_flag": r.get("third_party_flag"),
+            "advisory_committee": r.get("advisory_committee"),
+            "advisory_committee_description": r.get("advisory_committee_description"),
+            "product_code": r.get("product_code"),                    # links to the classification face
+            "statement_or_summary": r.get("statement_or_summary"),
+            "city": r.get("city"), "state": r.get("state"), "country_code": r.get("country_code"),
+        })
+    return out
+
+
+def _pma_rows(results):
+    """device/pma rows → premarket approval rows (pure function). The ao_statement long text and street/zip are not returned (row slimming + street-level address)."""
+    out = []
+    for r in results if isinstance(results, list) else []:
+        out.append({
+            "pma_number": r.get("pma_number"),                        # hub key
+            "supplement_number": r.get("supplement_number"),
+            "supplement_type": r.get("supplement_type"),
+            "supplement_reason": r.get("supplement_reason"),
+            "applicant": r.get("applicant"),                          # company edge, primary column
+            "trade_name": r.get("trade_name"),
+            "generic_name": r.get("generic_name"),
+            "decision_code": r.get("decision_code"),                  # APPR/…
+            "decision_date": r.get("decision_date"),                  # ISO date
+            "date_received": r.get("date_received"),
+            "expedited_review_flag": r.get("expedited_review_flag"),
+            "advisory_committee": r.get("advisory_committee"),
+            "advisory_committee_description": r.get("advisory_committee_description"),
+            "product_code": r.get("product_code"),
+            "docket_number": r.get("docket_number"),
+            "city": r.get("city"), "state": r.get("state"),
+        })
+    return out
+
+
+def _reg_rows(results):
+    """device/registrationlisting rows → facility registration rows (pure function). Key order verified against the 2026-10-29 probe of reg.f2-registration.name.json.
+
+    registration.us_agent (US agent name/phone/email/address) and owner_operator.official_correspondent (personal contact)
+    are not returned — PII red line; address_line_1/2 (street-level) are not returned, city/iso_country_code/postal_code are kept.
+    registration.* is flattened to the top level (the namespace survives only inside the search expression).
+    """
+    out = []
+    for r in results if isinstance(results, list) else []:
+        reg = r.get("registration") or {}
+        own = reg.get("owner_operator") or {}
+        out.append({
+            "registration_number": reg.get("registration_number"),    # hub key (links to 510k openfda / recalls)
+            "fei_number": reg.get("fei_number"),                      # FEI facility key (links to the recall firm_fei_number)
+            "firm_name": reg.get("name"),                             # company edge, primary column (the registered facility name)
+            "owner_operator_number": own.get("owner_operator_number"),
+            "owner_operator_name": own.get("firm_name"),              # parent / responsible-operator name
+            "status_code": reg.get("status_code"),
+            "initial_importer_flag": reg.get("initial_importer_flag"),
+            "reg_expiry_date_year": reg.get("reg_expiry_date_year"),
+            "city": reg.get("city"), "state_code": reg.get("state_code"),
+            "iso_country_code": reg.get("iso_country_code"), "postal_code": reg.get("postal_code"),
+            "establishment_types": r.get("establishment_type"),
+            "proprietary_names": r.get("proprietary_name"),
+            "k_number": r.get("k_number"), "pma_number": r.get("pma_number"),
+            "products": [{"product_code": p.get("product_code"),
+                          "created_date": p.get("created_date"),
+                          "openfda": p.get("openfda")}                 # device_name/regulation_number/device_class
+                         for p in (r.get("products") or []) if isinstance(p, dict)],
+        })
+    return out
+
+
+def _cls_rows(results):
+    """device/classification rows → product-code taxonomy rows (pure function). The openfda cross keys are small, so they are kept whole."""
+    out = []
+    for r in results if isinstance(results, list) else []:
+        out.append({
+            "product_code": r.get("product_code"),                    # hub key (links to 510k/pma/recalls)
+            "device_name": r.get("device_name"),
+            "device_class": r.get("device_class"),                    # 1/2/3
+            "definition": r.get("definition"),
+            "regulation_number": r.get("regulation_number"),
+            "medical_specialty": r.get("medical_specialty"),
+            "medical_specialty_description": r.get("medical_specialty_description"),
+            "review_panel": r.get("review_panel"),
+            "review_code": r.get("review_code"),
+            "submission_type_id": r.get("submission_type_id"),
+            "implant_flag": r.get("implant_flag"),
+            "gmp_exempt_flag": r.get("gmp_exempt_flag"),
+            "third_party_flag": r.get("third_party_flag"),
+            "life_sustain_support_flag": r.get("life_sustain_support_flag"),
+            "summary_malfunction_reporting": r.get("summary_malfunction_reporting"),
+            "unclassified_reason": r.get("unclassified_reason"),
+            "openfda": r.get("openfda"),                              # k_number/registration_number/fei_number
+        })
+    return out
+
+
+_ROWS = {"clearance_510k": _k510_rows, "pma": _pma_rows,
+         "registrations": _reg_rows, "classification": _cls_rows}
+
+
+def search(face, search, *, limit=20, skip=0, sort=None, cache=None, no_cache=False):
+    """Born flat: the search expression is passed through verbatim (upstream param names search/limit/skip/sort, zero sugar).
+    face ∈ clearance_510k|pma|registrations|classification. limit 1-1000 (the openFDA search hard limit).
+    search is required (local safety gate: under a keyless quota a bare full-table query is served by the bulk harvest line).
+    → {rows[], total, count, skip, limit_applied, has_more, search, sort, _meta}; zero hits = an empty set that is not cached.
+    """
+    from ..transport import call_provider
+
+    if face not in provider["ops"]:
+        raise SdkError("usage_error", provider=provider["id"],
+                       detail=f"face must be clearance_510k|pma|registrations|classification, got '{face}'")
+    q = str(search or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider=provider["id"],
+                       detail="search requires an expression (e.g. registration.name:\"Firm Name\" or applicant:\"Medtronic\"; a bare full-table query is served by the bulk line)")
+    size = int(limit) if limit is not None else 20  # 0 is an explicitly bad value (do not let `or` swallow it into the default); the gate below rejects it
+    if not 1 <= size <= 1000:
+        raise SdkError("usage_error", provider=provider["id"],
+                       detail=f"limit must be 1-1000 (the openFDA search hard limit, same as shortages measured on 2026-10-23), got {size}")
+    sk = max(0, int(skip or 0))
+    so = str(sort).strip() if sort is not None else _DEFAULT_SORT.get(face)
+    params = {"search": q, "limit": size}
+    if sk:
+        params["skip"] = sk
+    if so:
+        params["sort"] = so
+    try:
+        r = call_provider(provider, face, params, cache=cache, no_cache=no_cache)
+    except SdkError as e:
+        if e.code == "upstream_not_found":
+            return {"rows": [], "total": 0, "count": 0, "skip": sk, "limit_applied": size,
+                    "has_more": False, "search": q, "sort": so or None,
+                    "_meta": {"from_cache": False,
+                              "fetched_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")}}
+        raise
+    data = r.get("data") or {}
+    rows = _ROWS[face](data.get("results"))
+    total = (data.get("meta") or {}).get("results", {}).get("total", len(rows))
+    return {"rows": rows, "total": total, "count": len(rows), "skip": sk, "limit_applied": size,
+            "has_more": total > sk + len(rows), "search": q, "sort": so or None, "_meta": r}

agentdata/healthcare/fda_drugs.py

@@ -0,0 +1,156 @@
+"""fda_drugs — FDA drug provider, three faces (openFDA drug/drugsfda · drug/ndc · drug/orangebook; keyless).
+
+Wave 10b of the healthcare domain (second batch; row shapes measured 2026-10-29).
+The family contract is shared with fda_recalls/shortages: GET /<ep>.json?search=&limit=&skip=&sort=, zero hits = HTTP 404
+{"error":{"code":"NOT_FOUND"}} is a legal answer (notFound:[404] → an empty envelope that is not cached).
+Probing anchors on 2026-10-29 (field names verified by _exists_, not inferred from the docs):
+  drug/drugsfda (29,420 applications): company field = **sponsor_name** (the docs once said applicant_name — overturned by _exists_);
+    a row = application_number × products[] × submissions[]; the default sort is the nested key submissions.submission_status_date:desc (measured to sort).
+  drug/ndc (NDC catalogue, 138,153+ rows, daily refresh): company field = labeler_name (plus the openfda.manufacturer_name normalization layer);
+    marketing_start/end_date + marketing_category + listing_expiration_date are in the columns — **the NSDE endpoint is dead (Cannot GET
+    /drug/nsde.json) and its content was merged into this face** (confirmed by probing on wave10b).
+  drug/orangebook (48,865 rows, the Orange Book's first API face): company field = products[].application_name/_full_name
+    (the licence holder); the RLD/reference_standard flags sit on the row; **it replaces the dead nsde as wave10b's 7th face**.
+    applicant/applicant_holder/holder etc. all 404 under _exists_ — the company key only exists inside products[].
+Rate limit: a keyless quota shared with fda_recalls/shortages on the same host (polite 2 rps per face, the family total must stay under ~4 rps).
+TTL 24h (all three faces refresh on a daily-to-weekly cadence).
+"""
+from datetime import datetime, timezone
+
+from ..errors import SdkError
+
+provider = {
+    "id": "fda_drugs",
+    "baseUrl": "https://api.fda.gov",
+    "rate": {"rps": 2, "burst": 5, "group": "fda"},
+    "ops": {
+        "approvals": {"path": "/drug/drugsfda.json", "notFound": [404]},
+        "catalog": {"path": "/drug/ndc.json", "notFound": [404]},
+        "orange_book": {"path": "/drug/orangebook.json", "notFound": [404]},
+    },
+    "ttl": {"approvals": 24 * 3600, "catalog": 24 * 3600, "orange_book": 24 * 3600},
+}
+
+# Default sort per face (our default, not the upstream one; drugsfda by latest submission date, ndc by marketing start, the Orange Book by approval date; all measured to sort on 2026-10-29)
+_DEFAULT_SORT = {"approvals": "submissions.submission_status_date:desc",
+                 "catalog": "marketing_start_date:desc",
+                 "orange_book": "approval_date:desc"}
+
+
+def _approvals_rows(results):
+    """drug/drugsfda rows → application dossier rows (pure function, testable offline). Key order verified against the 2026-10-29 probe of drugsfda.exists.json."""
+    out = []
+    for r in results if isinstance(results, list) else []:
+        out.append({
+            "application_number": r.get("application_number"),        # NDA/ANDA/BLA number (hub key linking to the Orange Book)
+            "sponsor_name": r.get("sponsor_name"),                    # company edge, primary column (the applicant)
+            "products": [{"product_number": p.get("product_number"),
+                          "brand_name": p.get("brand_name"),
+                          "active_ingredients": p.get("active_ingredients"),
+                          "dosage_form": p.get("dosage_form"),
+                          "route": p.get("route"),
+                          "marketing_status": p.get("marketing_status"),
+                          "reference_drug": p.get("reference_drug"),
+                          "reference_standard": p.get("reference_standard")}
+                         for p in (r.get("products") or []) if isinstance(p, dict)],
+            "submissions": [{"submission_type": s.get("submission_type"),
+                             "submission_number": s.get("submission_number"),
+                             "submission_status": s.get("submission_status"),
+                             "submission_status_date": s.get("submission_status_date")}
+                            for s in (r.get("submissions") or []) if isinstance(s, dict)],
+        })
+    return out
+
+
+def _catalog_rows(results):
+    """drug/ndc rows → NDC catalogue rows (pure function). The openfda sub-object is kept whole (rxcui/spl_set_id/unii product metadata, no PII)."""
+    out = []
+    for r in results if isinstance(results, list) else []:
+        out.append({
+            "product_ndc": r.get("product_ndc"),                      # hub key (links to shortages/recall product_ndcs)
+            "brand_name": r.get("brand_name"),
+            "generic_name": r.get("generic_name"),
+            "labeler_name": r.get("labeler_name"),                    # company edge, primary column (the labeler)
+            "dosage_form": r.get("dosage_form"),
+            "route": r.get("route"),
+            "finished": r.get("finished"),
+            "marketing_category": r.get("marketing_category"),
+            "marketing_start_date": r.get("marketing_start_date"),    # YYYYMMDD (field merged in from NSDE)
+            "marketing_end_date": r.get("marketing_end_date"),
+            "listing_expiration_date": r.get("listing_expiration_date"),
+            "application_number": r.get("application_number"),
+            "product_type": r.get("product_type"),
+            "active_ingredients": r.get("active_ingredients"),
+            "package_ndcs": [p.get("package_ndc") for p in (r.get("packaging") or [])
+                             if isinstance(p, dict) and p.get("package_ndc")],
+            "openfda": r.get("openfda"),                              # manufacturer_name/rxcui/spl_set_id/unii
+        })
+    return out
+
+
+def _orange_rows(results):
+    """drug/orangebook rows → Orange Book rows (pure function). The company key lives inside products[] (the top-level applicant fields all 404 under _exists_)."""
+    out = []
+    for r in results if isinstance(results, list) else []:
+        out.append({
+            "approval_date": r.get("approval_date"),                  # YYYYMMDD
+            "product_number": r.get("product_number"),
+            "products": [{"brand_name": p.get("brand_name"),
+                          "active_ingredients": p.get("active_ingredients"),
+                          "application_name": p.get("application_name"),          # company edge, primary column (short name of the licence holder)
+                          "application_full_name": p.get("application_full_name"), # the company's full name
+                          "application_type": p.get("application_type"),           # N/ANDA
+                          "application_number": p.get("application_number"),       # hub key linking to drugsfda
+                          "reference_listed_drug": p.get("reference_listed_drug"),
+                          "reference_standard": p.get("reference_standard"),
+                          "marketing_status": p.get("marketing_status"),
+                          "dosage_form": p.get("dosage_form"),
+                          "route": p.get("route")}
+                         for p in (r.get("products") or []) if isinstance(p, dict)],
+        })
+    return out
+
+
+_ROWS = {"approvals": _approvals_rows, "catalog": _catalog_rows, "orange_book": _orange_rows}
+
+
+def search(face, search, *, limit=20, skip=0, sort=None, cache=None, no_cache=False):
+    """Born flat: the search expression is passed through verbatim (upstream param names search/limit/skip/sort, zero sugar).
+    face ∈ approvals|catalog|orange_book. limit 1-1000 (the openFDA search hard limit, same as shortages measured 1001→400).
+    search is required (local safety gate: under a keyless quota a bare full-table query is served by the bulk harvest line).
+    → {rows[], total, count, skip, limit_applied, has_more, search, sort, _meta}; zero hits = an empty set that is not cached.
+    """
+    from ..transport import call_provider
+
+    if face not in provider["ops"]:
+        raise SdkError("usage_error", provider=provider["id"],
+                       detail=f"face must be approvals|catalog|orange_book, got '{face}'")
+    q = str(search or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider=provider["id"],
+                       detail="search requires an expression (e.g. sponsor_name:\"TEVA\" — the keyword field is case-sensitive, so use the form stored in the rows; a bare full-table query is served by the bulk line)")
+    size = int(limit) if limit is not None else 20  # 0 is an explicitly bad value (do not let `or` swallow it into the default); the gate below rejects it
+    if not 1 <= size <= 1000:
+        raise SdkError("usage_error", provider=provider["id"],
+                       detail=f"limit must be 1-1000 (the openFDA search hard limit, same as shortages measured on 2026-10-23), got {size}")
+    sk = max(0, int(skip or 0))
+    so = str(sort).strip() if sort is not None else _DEFAULT_SORT[face]
+    params = {"search": q, "limit": size}
+    if sk:
+        params["skip"] = sk
+    if so:
+        params["sort"] = so
+    try:
+        r = call_provider(provider, face, params, cache=cache, no_cache=no_cache)
+    except SdkError as e:
+        if e.code == "upstream_not_found":
+            return {"rows": [], "total": 0, "count": 0, "skip": sk, "limit_applied": size,
+                    "has_more": False, "search": q, "sort": so or None,
+                    "_meta": {"from_cache": False,
+                              "fetched_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")}}
+        raise
+    data = r.get("data") or {}
+    rows = _ROWS[face](data.get("results"))
+    total = (data.get("meta") or {}).get("results", {}).get("total", len(rows))
+    return {"rows": rows, "total": total, "count": len(rows), "skip": sk, "limit_applied": size,
+            "has_more": total > sk + len(rows), "search": q, "sort": so or None, "_meta": r}

agentdata/healthcare/fda_recalls.py

@@ -0,0 +1,137 @@
+"""fda_recalls — FDA recall provider, three faces (openFDA drug/enforcement · device/recall · food/enforcement; keyless).
+
+Wave 10 of the healthcare domain (2026-10-28 decision to fill out the query faces with the openFDA family; third of the four opening faces).
+The family contract is shared with shortages: GET /<ep>.json?search=&limit=&skip=&sort=, zero hits = HTTP 404
+{"error":{"code":"NOT_FOUND"}} is a legal answer (notFound:[404] → an empty envelope that is not cached).
+Row shapes measured 2026-10-28:
+  drug/enforcement (18,010 rows, weekly): recalling_firm.exact:"SV Labs Toronto Corporation" → 2 hits;
+    status was seen as Ongoing; **the drug line has no separate recall endpoint — enforcement is the recall face** (a press-release source).
+  device/recall (59,618 rows, the RES recall system): recalling_firm:"Sedecal" as a phrase → 62 hits; recall_status
+    was seen as Terminated/Ongoing; rows carry firm_fei_number + k_numbers — **this is a different system from device/enforcement (the
+    press-release face already bulk-loaded)**: RES is the newer authority (and carries the full Ongoing lifecycle). .exact is unverified, so the wrapped form is always a phrase.
+  food/enforcement (29,485 rows): recalling_firm.exact:"TODD'S SEEDS LLC" → 6 hits; status was seen as Ongoing.
+Rate limit: a keyless quota shared with shortages on the same host (polite 2 rps per face, the family total must stay under ~4 rps).
+TTL 24h (all three faces are on a weekly cadence).
+"""
+from datetime import datetime, timezone
+
+from ..errors import SdkError
+
+provider = {
+    "id": "fda_recalls",
+    "baseUrl": "https://api.fda.gov",
+    "rate": {"rps": 2, "burst": 5, "group": "fda"},
+    "ops": {
+        "drug": {"path": "/drug/enforcement.json", "notFound": [404]},
+        "device": {"path": "/device/recall.json", "notFound": [404]},
+        "food": {"path": "/food/enforcement.json", "notFound": [404]},
+    },
+    "ttl": {"drug": 24 * 3600, "device": 24 * 3600, "food": 24 * 3600},
+}
+
+# Default sort per face (our default, not the upstream one; both enforcement faces use the same key report_date, the RES face uses the posted date)
+_DEFAULT_SORT = {"drug": "report_date:desc", "food": "report_date:desc",
+                 "device": "event_date_posted:desc"}
+
+
+def _enf_rows(results):
+    """drug/food enforcement rows → recall record rows (pure function, testable offline). Key order verified against the 2026-10-28 probe."""
+    out = []
+    for r in results if isinstance(results, list) else []:
+        of = r.get("openfda") or {}
+        out.append({
+            "recall_number": r.get("recall_number"),
+            "event_id": r.get("event_id"),                      # stable key (links to the bulk events corpus line)
+            "recalling_firm": r.get("recalling_firm"),          # company edge, primary column
+            "classification": r.get("classification"),          # Class I/II/III
+            "status": r.get("status"),                          # Ongoing/Terminated/Completed
+            "product_type": r.get("product_type"),
+            "product_description": r.get("product_description"),
+            "product_quantity": r.get("product_quantity"),
+            "reason_for_recall": r.get("reason_for_recall"),
+            "code_info": r.get("code_info"),
+            "more_code_info": r.get("more_code_info"),
+            "distribution_pattern": r.get("distribution_pattern"),
+            "voluntary_mandated": r.get("voluntary_mandated"),
+            "initial_firm_notification": r.get("initial_firm_notification"),
+            "recalled_on": r.get("recall_initiation_date"),     # YYYYMMDD
+            "reported_on": r.get("report_date"),
+            "city": r.get("city"), "state": r.get("state"), "country": r.get("country"),
+            "address": r.get("address_1"),
+            "applications": of.get("application_number"),       # links to the drugsfda product line
+            "product_ndcs": of.get("product_ndc"),
+        })
+    return out
+
+
+def _device_rows(results):
+    """device/recall (RES system) rows → recall record rows (pure function; FEI is the company-facility-product hub key).
+
+    additional_info_contact (the recalling firm's contact, often a person name) is not returned — the same PII red line as the PhilGEPS Contact Person.
+    """
+    out = []
+    for r in results if isinstance(results, list) else []:
+        out.append({
+            "res_event_number": r.get("res_event_number"),
+            "product_res_number": r.get("product_res_number"),
+            "cfres_id": r.get("cfres_id"),
+            "recalling_firm": r.get("recalling_firm"),          # company edge, primary column
+            "firm_fei_number": r.get("firm_fei_number"),        # FEI hub key (links to registrationlisting)
+            "k_numbers": r.get("k_numbers"),                    # links to the 510(k) device line
+            "product_code": r.get("product_code"),
+            "recall_status": r.get("recall_status"),            # Ongoing/Terminated/…
+            "action": r.get("action"),
+            "product_description": r.get("product_description"),
+            "reason_for_recall": r.get("reason_for_recall"),
+            "root_cause_description": r.get("root_cause_description"),
+            "code_info": r.get("code_info"),
+            "product_quantity": r.get("product_quantity"),
+            "distribution_pattern": r.get("distribution_pattern"),
+            "initiated_on": r.get("event_date_initiated"),      # ISO date
+            "posted_on": r.get("event_date_posted"),
+            "terminated_on": r.get("event_date_terminated"),
+            "address": r.get("address_1"),
+            "city": r.get("city"), "state": r.get("state"),
+        })
+    return out
+
+
+def search(face, search, *, limit=20, skip=0, sort=None, cache=None, no_cache=False):
+    """Born flat: the search expression is passed through verbatim (upstream param names search/limit/skip/sort, zero sugar).
+    face ∈ drug|device|food. limit 1-1000 (the openFDA search hard limit, same as shortages measured 1001→400).
+    search is required (local safety gate: under a keyless quota a bare full-table query is served by the bulk harvest line).
+    → {rows[], total, count, skip, limit_applied, has_more, search, sort, _meta}; zero hits = an empty set that is not cached.
+    """
+    from ..transport import call_provider
+
+    if face not in provider["ops"]:
+        raise SdkError("usage_error", provider=provider["id"], detail=f"face must be drug|device|food, got '{face}'")
+    q = str(search or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider=provider["id"],
+                       detail="search requires an expression (e.g. recalling_firm.exact:\"Firm Name\"; a bare full-table query is served by the bulk line)")
+    size = int(limit) if limit is not None else 20  # 0 is an explicitly bad value (do not let `or` swallow it into the default); the gate below rejects it
+    if not 1 <= size <= 1000:
+        raise SdkError("usage_error", provider=provider["id"],
+                       detail=f"limit must be 1-1000 (the openFDA search hard limit, same as shortages measured on 2026-10-23), got {size}")
+    sk = max(0, int(skip or 0))
+    so = str(sort).strip() if sort is not None else _DEFAULT_SORT[face]
+    params = {"search": q, "limit": size}
+    if sk:
+        params["skip"] = sk
+    if so:
+        params["sort"] = so
+    try:
+        r = call_provider(provider, face, params, cache=cache, no_cache=no_cache)
+    except SdkError as e:
+        if e.code == "upstream_not_found":
+            return {"rows": [], "total": 0, "count": 0, "skip": sk, "limit_applied": size,
+                    "has_more": False, "search": q, "sort": so or None,
+                    "_meta": {"from_cache": False,
+                              "fetched_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")}}
+        raise
+    data = r.get("data") or {}
+    rows = (_device_rows if face == "device" else _enf_rows)(data.get("results"))
+    total = (data.get("meta") or {}).get("results", {}).get("total", len(rows))
+    return {"rows": rows, "total": total, "count": len(rows), "skip": sk, "limit_applied": size,
+            "has_more": total > sk + len(rows), "search": q, "sort": so or None, "_meta": r}