agentdata 0.3.26__py3-none-any.whl

agentdata/healthcare/safety_gate.py

@@ -0,0 +1,175 @@
+"""safety_gate — EU Safety Gate (the ex-RAPEX rapid alert system for dangerous non-food products)
+weekly-report XML face provider (ec.europa.eu/safety-gate-alerts/api/download/; 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 /safety-gate-alerts/api/download/weeklyReport/list/xml/en
+  → the whole weekly-report index in ONE XML document (1,122 reports measured 2026-11-02;
+    Report-2005-1 → Report-2026-43). Each <weeklyReport> entry: reference (Report-YYYY-WW),
+    publicationDate (dd/mm/yyyy), year/month/day/week, and URL — the URL path embeds the numeric
+    reportId (…/detail/xml/10000329), which is the join key into the detail face.
+GET /safety-gate-alerts/api/download/weeklyReport/detail/xml/<reportId>?language=en&search=WEB_REPORT|:|<reportId>,
+  → the single weekly report as XML: a <Safety-Gate> root (report_language/report_date/report_year/
+    report_week) wrapping N <notifications> entries (67 measured for report 10000329 = 2026-W43).
+    Alert fields: caseNumber (SR/03023/26), reference (the alert-detail URL → the numeric alert id),
+    category, product, brand, name, type_numberOfModel, batchNumber, barcode, riskType, danger
+    (the risk narrative), measures (the concatenated operator/measure/effective-date blocks),
+    URLrecall, description, notifyingCountry, countryOfOrigin, type (Consumer…), level
+    (Serious risk…), onlineTrader, companyRecallCode, productionDates.
+    language is a query param but search is the SPA's own echo parameter — both are FIXED for this
+    face (constructed from the report id; the en channel is the one probed).
+The list/detail pair is the same shape family as gb_tna_caselaw (an XML face among JSON APIs).
+Local row slicing (limit/skip) and the year post-filter slice the single cached full documents.
+TTL: list 24h (new reports land weekly) / detail 7 days (a published weekly report is immutable);
+polite rate 1 rps (the download family publishes no quota).
+"""
+import re
+import xml.etree.ElementTree as ET
+
+from ..errors import SdkError
+
+provider = {
+    "id": "safety_gate",
+    "baseUrl": "https://ec.europa.eu",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "weekly_list": {"path": "/safety-gate-alerts/api/download/weeklyReport/list/xml/en", "accept": "text"},
+        # the detail query string is baked into the path byte-exact as probed (the ukec shape: urlencode
+        # would re-encode the SPA's echo parameter WEB_REPORT|:|<id>, — a silent near-miss risk not worth taking)
+        "weekly_detail": {"path": "/safety-gate-alerts/api/download/weeklyReport/detail/xml/{report_id}"
+                                   "?language=en&search=WEB_REPORT%7C:%7C{report_id},",
+                          "accept": "text"},
+    },
+    "ttl": {"weekly_list": 24 * 3600, "weekly_detail": 7 * 86400},
+}
+
+_REPORT_ID = re.compile(r"/detail/xml/(\d+)")   # the list face's download URL → the report id
+_ALERT_ID = re.compile(r"alertDetail/(\d+)")    # the detail rows' reference URL → the alert id (a different path shape)
+
+
+def _txt(el):
+    return (el.text or "").strip() or None if el is not None else None
+
+
+def alerts_from_upstream(xml_text):
+    """The list XML → weekly-report index rows (pure function, offline-testable).
+
+    The reportId lives only inside the URL element — it is carved out here as the join key."""
+    root = ET.fromstring(xml_text)
+    rows = []
+    for wr in root.iter("weeklyReport"):
+        url = _txt(wr.find("URL")) or ""
+        rid = _REPORT_ID.search(url)
+        rows.append({
+            "report_id": rid.group(1) if rid else None,   # the join key into the detail face
+            "reference": _txt(wr.find("reference")),       # Report-YYYY-WW
+            "publication_date": _txt(wr.find("publicationDate")),
+            "year": _txt(wr.find("year")),
+            "week": _txt(wr.find("week")),
+            "url": url or None,
+        })
+    return {"rows": rows, "count": len(rows)}
+
+
+def report_from_upstream(xml_text, report_id):
+    """The detail XML → {report header, rows[]} (pure function, offline-testable)."""
+    root = ET.fromstring(xml_text)
+    rows = []
+    for n in root.iter("notifications"):
+        ref_url = _txt(n.find("reference")) or ""
+        aid = _ALERT_ID.search(ref_url)
+        rows.append({
+            "order": _txt(n.find("order")),
+            "case_number": _txt(n.find("caseNumber")),
+            "alert_id": aid.group(1) if aid else None,     # the numeric id from the alert-detail URL
+            "alert_url": ref_url or None,
+            "category": _txt(n.find("category")),
+            "product": _txt(n.find("product")),
+            "brand": _txt(n.find("brand")),
+            "name": _txt(n.find("name")),
+            "type_number_of_model": _txt(n.find("type_numberOfModel")),
+            "batch_number": _txt(n.find("batchNumber")),
+            "barcode": _txt(n.find("barcode")),
+            "risk_type": _txt(n.find("riskType")),         # e.g. "Electric shock, Fire"
+            "danger": _txt(n.find("danger")),               # the risk narrative
+            "measures": _txt(n.find("measures")),           # operator/measure/effective-date blocks
+            "url_recall": _txt(n.find("URLrecall")),
+            "description": _txt(n.find("description")),
+            "notifying_country": _txt(n.find("notifyingCountry")),
+            "country_of_origin": _txt(n.find("countryOfOrigin")),
+            "type": _txt(n.find("type")),                   # e.g. Consumer
+            "level": _txt(n.find("level")),                 # e.g. Serious risk
+            "online_trader": _txt(n.find("onlineTrader")),
+            "company_recall_code": _txt(n.find("companyRecallCode")),
+            "production_dates": _txt(n.find("productionDates")),
+        })
+    return {
+        "report_id": str(report_id),
+        # the detail XML carries no Report-YYYY-WW reference field — the caller stitches it from the
+        # list face; the report_year/report_week pair below is the upstream's own framing
+        "report_date": _txt(root.find("report_date")),
+        "report_year": _txt(root.find("report_year")),
+        "report_week": _txt(root.find("report_week")),
+        "report_language": _txt(root.find("report_language")),
+        "rows": rows, "count": len(rows),
+    }
+
+
+def _slice(rows, limit, skip):
+    off = int(skip) if skip is not None else 0
+    if off < 0:
+        raise SdkError("usage_error", provider="safety_gate", 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="safety_gate", detail=f"limit must be >=1 (local post-slice, no upstream cap), got \"{limit}\"")
+    return rows[off:off + size]
+
+
+def weekly_list_raw(*, year=None, limit=200, skip=0, cache=None, no_cache=False):
+    """Flat-panel low-level face: the weekly-report index (1,122 reports 2005→now, one cached XML).
+
+    year = an optional local post-filter on the report year (the upstream index has no filter —
+    it always serves the whole index); limit/skip is a local post-slice.
+    → {rows[], count, total, params, _meta} — total = the whole index size (post-year-filter)."""
+    from ..transport import call_provider
+
+    params = {}
+    if year is not None:
+        y = str(year).strip()
+        if not y.isdigit():
+            raise SdkError("usage_error", provider="safety_gate", detail=f"year must be a 4-digit year (a local post-filter on the report index), got \"{year}\"")
+        params["year"] = y
+    r = call_provider(provider, "weekly_list", {}, cache=cache, no_cache=no_cache)
+    out = alerts_from_upstream(r["data"])
+    rows = [x for x in out["rows"] if (not params.get("year") or x["year"] == params["year"])]
+    rows = _slice(rows, limit, skip)
+    return {"rows": rows, "count": len(rows), "total": len(out["rows"]) if not params.get("year")
+            else sum(1 for x in out["rows"] if x["year"] == params["year"]),
+            "params": params or None, "_meta": r}
+
+
+def _clean_report_id(report_id):
+    """Numeric reportId; a pasted detail URL gets its id carved out (the join key echoed by the list rows)."""
+    s = str(report_id or "").strip()
+    m = _REPORT_ID.search(s)
+    if m:
+        s = m.group(1)
+    if not s.isdigit():
+        raise SdkError("usage_error", provider="safety_gate",
+                       detail=f"report_id must be the numeric report id (e.g. 10000329 — the report_id field echoed by safety_gate_alerts; a pasted detail URL also works), got \"{report_id}\"")
+    return s
+
+
+def weekly_detail_raw(report_id, *, limit=200, skip=0, cache=None, no_cache=False):
+    """Flat-panel low-level face: one weekly report's alerts (the detail XML — 67 alerts for 2026-W43).
+
+    → {report header…, rows[], count, params, _meta} — the alert rows carry caseNumber/risk/level/
+    notifyingCountry/countryOfOrigin/onlineTrader (the company-relevant edges) verbatim."""
+    from ..transport import call_provider
+
+    rid = _clean_report_id(report_id)
+    params = {"report_id": rid}
+    r = call_provider(provider, "weekly_detail", params, cache=cache, no_cache=no_cache)
+    out = report_from_upstream(r["data"] or "", rid)
+    rows = _slice(out["rows"], limit, skip)
+    return {**out, "rows": rows, "count": len(rows), "params": params, "_meta": r}

agentdata/healthcare/shortages.py

@@ -0,0 +1,107 @@
+"""shortages — FDA Drug Shortages provider (openFDA drug/shortages.json; keyless).
+
+Wave 5 of the healthcare domain: related
+kind=drug_shortages — manufacturer/drug name → drug shortage records, the supply-risk event stream: the last piece of the pipeline × safety × supply triad.
+Row shapes measured 2026-10-23:
+GET /drug/shortages.json?search=<q>&limit=N&skip=M&sort=update_date:desc
+  search segments (three, AND-combinable, measured q1=179/q2=82/q3=AND 18):
+    manufacturer → openfda.manufacturer_name.exact:"Fresenius Kabi USA, LLC" (exact phrase; bare tokens scatter)
+    drug name → generic_name:"bupivacaine" (phrase search, multi-word ingredient names match whole)
+    status → status:Current (the enum Current/Resolved/To Be Discontinued — measured on a 100-row Fresenius sample as 83/1/16)
+  **zero hits = 404 {"error":{"code":"NOT_FOUND","message":"No matches found!"}}** — a legal answer, not an error
+  (the openFDA convention); the op declares notFound:[404], and upstream_not_found turns into an empty set at this layer.
+Row fields: generic_name/company_name/availability/status/update_type/update_date/initial_posting_date/
+  package_ndc/presentation/dosage_form/shortage_reason/therapeutic_category/contact_info
+  + the openfda enrichment block (manufacturer_name/application_number/product_ndc/rxcui/substance_name)
+  — company_name = the manufacturer registered on the shortage record (may differ from openfda.manufacturer_name: that is the normalization layer, both columns are kept).
+update_date can be sorted desc (measured: 10/15/2026 comes back first); the date form is MM/DD/YYYY.
+TTL: a daily cadence (meta.last_updated measured 2026-10-22) → 24h; the keyless quota is 240/min → polite tier 2 rps.
+"""
+from datetime import datetime, timezone
+
+from ..errors import SdkError
+
+provider = {
+    "id": "shortages",
+    "baseUrl": "https://api.fda.gov",
+    "rate": {"rps": 2, "burst": 5, "group": "fda"},
+    "ops": {
+        "search": {"path": "/drug/shortages.json", "notFound": [404]},  # params: search, limit, skip, sort
+    },
+    "ttl": {"search": 24 * 3600},
+}
+
+
+def rows_from_upstream(results):
+    """Upstream rows → shortage record rows (pure function, testable offline): both company columns are kept (the registered manufacturer + the openFDA normalized manufacturer)."""
+    rows = results if isinstance(results, list) else []
+    out = []
+    for r in rows:
+        of = r.get("openfda") or {}
+        out.append({
+            "generic_name": r.get("generic_name"),
+            "company_name": r.get("company_name"),          # the manufacturer registered on the shortage record (company edge, primary column)
+            "manufacturers": of.get("manufacturer_name"),   # the openFDA normalized manufacturer (company edge, comparison column)
+            "availability": r.get("availability"),
+            "status": r.get("status"),
+            "update_type": r.get("update_type"),
+            "update_date": r.get("update_date"),
+            "first_posted": r.get("initial_posting_date"),
+            "package_ndc": r.get("package_ndc"),
+            "presentation": r.get("presentation"),
+            "dosage_form": r.get("dosage_form"),
+            "shortage_reason": r.get("shortage_reason"),
+            "therapeutic_category": r.get("therapeutic_category"),
+            "applications": of.get("application_number"),
+            "product_ndcs": of.get("product_ndc"),
+            "rxcuis": of.get("rxcui"),
+            "substances": of.get("substance_name"),
+            "contact": r.get("contact_info"),
+        })
+    return out
+
+
+def search_raw(search, *, limit=20, skip=0, sort="update_date:desc", cache=None, no_cache=False):
+    """0.2.0 mirror face: the search expression is passed through verbatim (openFDA query syntax) + the upstream param names limit/skip/sort.
+
+    Hard limit (protocol, confirmed by probing on 2026-10-23): limit 1-1000 — 1001 → 400 BAD_REQUEST
+    «Limit cannot exceed 1000 results for search requests. Use the skip or search_after param»;
+    deeper paging goes through skip — search_after is not accepted (probed 2026-10-28): with sort → 400 «search_after has 1 value(s)
+    but sort has 2» (a semicolon double value → an ES parse error; the default sort → 200 but the rows are identical to the baseline = silently ignored); and the whole
+    database holds only ~1604 rows, so limit 1000 + skip reaches the bottom in two pages — the deep-paging gap does not exist, skip is complete.
+    search is required (local safety gate: under the keyless 240/min quota a bare full-table query is served by the bulk harvest line, not by this single-lookup face).
+    A free sort string passes through (measured update_date:desc works; the default is ours, not the upstream one).
+    → {rows[], total, count, skip, limit_applied, has_more, search, sort, _meta}; zero hits = an empty set that is not cached (same as above).
+    """
+    from ..transport import call_provider
+
+    q = str(search or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="shortages",
+                       detail="search requires an expression (e.g. generic_name:'bupivacaine' — the phrase segment needs double quotes; a bare full-table query is served by the bulk line)")
+    size = int(limit or 20)
+    if not 1 <= size <= 1000:
+        raise SdkError("usage_error", provider="shortages",
+                       detail=f"limit must be 1-1000 (upstream 400: Limit cannot exceed 1000 results for search "
+                              f"requests — measured 2026-10-23; to page deeper use skip, the whole database of ~1604 rows is reached in two pages), 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/legal/__init__.py

@@ -0,0 +1,4 @@
+"""legal domain package — provider adapters laid flat (one source per file) + faces/cli (0.2.6 per-domain split).
+"""
+from . import (afdb, ca_sema, csl, courtlistener, co_sic, dgcomp, ecfr,  # noqa: F401
+               federalregister, idb, lda, sipri, gb_tna_caselaw, ukec, gb_cma, wb)

agentdata/legal/afdb.py

@@ -0,0 +1,93 @@
+"""afdb — African Development Bank debarred-entities roster provider (afdb.org json-feed; keyless).
+
+legal debarment-roster face (0.3.21; admitted 2026-11-02, probed tmp/probe-debar-0321). Shape measured 2026-11-02:
+GET /en/debarred-entities-json-feed → a bare JSON array, 1,440 rows × 7 columns (Type FIRM 1,196 / INDIVIDUAL 244,
+Name, Nationality, From, To, Basis, Notes) — a single-shot full dump (the -csv-export sibling serves byte-identical
+content; the -xml-export sibling returns a 2.4KB stub). To = empty means ongoing (169 rows); Notes ∈ {ONGOING,
+INDEFINITE, empty}.
+**Basis is the cross-debarment edge, self-evidenced**: "CROSS DEBARMENT : WBG" 653 / "CROSS-DEBARMENT: ADB" 377 /
+"CROSS-DEBARMENT: IDB" 161+2 / "CROSS DEBARMENT : EBRD" 127 / "DEBARMENT:AFDB" 120 — note the upstream spacing is
+**inconsistent** ("CROSS DEBARMENT : WBG" with spaces vs "CROSS-DEBARMENT: ADB" hyphenated): the basis filter is a
+contains-match precisely so "WBG"/"ADB"/"IDB"/"EBRD" hit regardless of punctuation.
+**Cloudflare UA-fingerprint gate** (pinned 2026-11-02): the default agentdata UA passes then 403s flakily on repeat;
+a bare "Mozilla/5.0" UA is refused outright; the **full browser document suite passes consistently** — per-request
+header override (ext 8), same family as UNGM (0.3.12).
+Screening = local full-register scan (upstream has no query surface), cache 24h.
+TTL: 24h; polite tier 0.2 rps (single-endpoint face; also keeps the Cloudflare gate calm).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "afdb",
+    "baseUrl": "https://www.afdb.org",
+    "rate": {"rps": 0.2, "burst": 1},
+    "ops": {
+        "debarred": {"path": "/en/debarred-entities-json-feed", "timeoutMs": 90000},
+    },
+    "ttl": {"debarred": 24 * 3600},
+}
+
+# Cloudflare UA-fingerprint gate (pinned 2026-11-02, tmp/probe-debar-0321 p3): default agentdata UA → flaky
+# 403 on repeat; bare Mozilla/5.0 → 403; this full document suite → 200 twice in a row — ext-8 override
+_CF_BROWSER_HEADERS = {
+    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+                  "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.7",
+    "Accept-Language": "en-US,en;q=0.9",
+    "Referer": "https://www.afdb.org/en/projects-operations/debarment-and-sanctions-procedures",
+    "Upgrade-Insecure-Requests": "1",
+    "Sec-Fetch-Dest": "document",
+    "Sec-Fetch-Mode": "navigate",
+    "Sec-Fetch-Site": "none",
+    "Sec-Fetch-User": "?1",
+    "sec-ch-ua": '"Chromium";v="131", "Not_A Brand";v="24"',
+    "sec-ch-ua-mobile": "?0",
+    "sec-ch-ua-platform": '"Windows"',
+}
+
+
+def rows_from_upstream(data):
+    """Upstream JSON array → debarred-entity rows (pure function; the seven upstream columns verbatim —
+    the register is already narrow, and To="" / Notes carry the ongoing/indefinite semantics)."""
+    return [{k: r.get(k) for k in ("Type", "Name", "Nationality", "From", "To", "Basis", "Notes")}
+            for r in (data or [])]
+
+
+def filter_rows(rows, name=None, type=None, basis=None):
+    """Local register scan (pure function). name: contains (case-insensitive) over Name; type: exact over
+    Type (FIRM/INDIVIDUAL); basis: **contains** over Basis — upstream spacing is inconsistent
+    ("CROSS DEBARMENT : WBG" vs "CROSS-DEBARMENT: ADB"), so filter on the bank token (WBG/ADB/IDB/EBRD)."""
+    needle = str(name or "").strip().lower() or None
+    ty_needle = str(type or "").strip().upper() or None
+    bs_needle = str(basis or "").strip().lower() or None
+    hits = []
+    for r in rows:
+        if ty_needle and str(r.get("Type") or "").strip().upper() != ty_needle:
+            continue
+        if bs_needle and bs_needle not in str(r.get("Basis") or "").lower():
+            continue
+        if needle and needle not in str(r.get("Name") or "").lower():
+            continue
+        hits.append(r)
+    return hits
+
+
+def debarred_entities_raw(name=None, *, type=None, basis=None, limit=20, cache=None, no_cache=False):
+    """Full-register scan (pulls the whole feed, caches 24h, then scans locally)
+    → {rows, total_matched, scanned_rows, limit_applied, params, _meta}.
+
+    name = contains over Name; type = FIRM/INDIVIDUAL exact; basis = contains over Basis (bank token:
+    WBG/ADB/IDB/EBRD — punctuation upstream is inconsistent). No filter → enumerate from the register head."""
+    from ..transport import call_provider
+
+    size = int(limit) if limit is not None else 20
+    if not 1 <= size <= 100:
+        raise SdkError("usage_error", provider="afdb",
+                       detail=f"limit must be 1-100 (local payload wall), got '{limit}'")
+    r = call_provider(provider, "debarred", {}, cache=cache, no_cache=no_cache,
+                      extra_headers=_CF_BROWSER_HEADERS)
+    rows = rows_from_upstream(r["data"])
+    hits = filter_rows(rows, name=name, type=type, basis=basis)
+    return {"rows": hits[:size], "total_matched": len(hits), "scanned_rows": len(rows),
+            "limit_applied": size,
+            "params": {"name": name, "type": type, "basis": basis}, "_meta": r}

agentdata/legal/ca_sema.py

@@ -0,0 +1,143 @@
+"""ca_sema — Canada SEMA sanctions listings provider (Global Affairs Canada sema-lmes.xml; keyless).
+
+legal sanctions-roster face (0.3.21; admitted 2026-11-02, probed tmp/probe-debar-0321). Shape measured 2026-11-02:
+GET /world-monde/assets/office_docs/international_relations-relations_internationales/sanctions/sema-lmes.xml
+  → <data-set><record>… — the Consolidated Canadian Autonomous Sanctions List under the Special Economic
+Measures Act, **5,708 live records** (persons 3,526 with GivenName / entities 2,181 via EntityOrShip — of which
+**731 ships carrying an IMO number**; the census-era 11,328 counted cumulative history). Tags are **bilingual
+paired names** (Country-Pays, LastName-NomDeFamille, GivenName-Prenom, Aliases-Alias, DateOfBirthOrShipBuildDate-…,
+EntityOrShip-EntiteOuNavire, TitleOrShipType-…, ShipIMONumber-…, Schedule-Annexe, Item-NumeroDarticle,
+DateOfListing-…); values are bilingual too ("Syria / Syrie", ship types "General Cargo/Multi Purpose | Cargo
+classique/navire polyvalent" — the **| separates the language halves**). Aliases are semicolon-delimited where
+multiple (222 records). Schedule references the SEMA schedule ("1, Part 1" 1,945 / "1, Part 2" 1,062 / "Part 1"
+742 / "1.1" 731…; 329 records carry none). Listing dates run 2008→2026 (2026 already at 518).
+**Accept content-negotiation gate** (pinned 2026-11-02): the asset answers 406 to Accept: application/json —
+the op overrides Accept to text/xml (ext 8); the plain agentdata UA passes.
+Screening = local full-register scan (upstream has no query surface), cache 24h.
+TTL: 24h; polite tier 0.2 rps (single-file face, 2.9MB).
+"""
+import xml.etree.ElementTree as ET
+
+from ..errors import SdkError
+
+provider = {
+    "id": "ca_sema",
+    "baseUrl": "https://www.international.gc.ca",
+    "rate": {"rps": 0.2, "burst": 1},
+    "ops": {
+        "listings": {
+            "path": "/world-monde/assets/office_docs/international_relations-relations_internationales/sanctions/sema-lmes.xml",
+            "accept": "text",  # XML surface — the raw text comes back and this module parses it
+            "timeoutMs": 120000,  # 2.9MB XML
+        },
+    },
+    "ttl": {"listings": 24 * 3600},
+}
+
+# Accept content-negotiation gate (pinned 2026-11-02): application/json → 406 Not Acceptable;
+# text/xml (and */*) → 206/200 — ext-8 override over the transport's default JSON Accept
+_XML_ACCEPT = {"Accept": "text/xml, */*"}
+
+# bilingual paired tag names (upstream verbatim — the EN/FR halves live in one element name)
+_T = {
+    "country": "Country-Pays",
+    "last_name": "LastName-NomDeFamille",
+    "given_name": "GivenName-Prenom",
+    "aliases": "Aliases-Alias",
+    "dob_or_ship_build": "DateOfBirthOrShipBuildDate-DateDeNaissanceOuDateDeConstructionDuNavire",
+    "entity_or_ship": "EntityOrShip-EntiteOuNavire",
+    "title_or_ship_type": "TitleOrShipType-TitreOuTypeDeNavire",
+    "ship_imo": "ShipIMONumber-NumeroOMIDuNavire",
+    "schedule": "Schedule-Annexe",
+    "item": "Item-NumeroDarticle",
+    "date_of_listing": "DateOfListing-DateDinscription",
+}
+
+
+def _txt(rec, key):
+    el = rec.find(_T[key])
+    return (el.text or "").strip() if el is not None and el.text else None
+
+
+def rows_from_xml(text):
+    """XML raw text → sanction-listing rows (pure function, offline-testable). Each record becomes
+    {kind, name, matched faces…}: kind = ship (IMO present) / entity (EntityOrShip) / person (GivenName×LastName);
+    name = the assembled display form ("Khazalbek Bakhtibekovich Atabekov" for persons, the EntityOrShip value
+    otherwise); aliases = semicolon-split; every other field verbatim bilingual."""
+    if not text:
+        return []
+    root = ET.fromstring(text)
+    rows = []
+    for rec in root.findall("record"):
+        imo = _txt(rec, "ship_imo")
+        entity = _txt(rec, "entity_or_ship")
+        given, last = _txt(rec, "given_name"), _txt(rec, "last_name")
+        if imo:
+            kind = "ship"
+        elif entity:
+            kind = "entity"
+        else:
+            kind = "person"
+        if kind == "person":
+            name = " ".join(x for x in (given, last) if x) or None
+        else:
+            name = entity
+        aliases = []
+        for el in rec.findall(_T["aliases"]):
+            aliases.extend(a.strip() for a in (el.text or "").split(";") if a.strip())
+        rows.append({
+            "kind": kind,
+            "name": name,
+            "aliases": aliases,
+            "country": _txt(rec, "country"),            # bilingual verbatim ("Syria / Syrie")
+            "dob_or_ship_build": _txt(rec, "dob_or_ship_build"),
+            "title_or_ship_type": _txt(rec, "title_or_ship_type"),  # person title OR ship type (bilingual)
+            "ship_imo": imo,                             # the join key onto shipping rosters (THETIS-MRV family)
+            "schedule": _txt(rec, "schedule"),
+            "item": _txt(rec, "item"),
+            "date_of_listing": _txt(rec, "date_of_listing"),
+        })
+    return rows
+
+
+def filter_rows(rows, name=None, country=None):
+    """Local register scan (pure function). name: contains (case-insensitive) over name **and** aliases
+    (matched_on echoes the hit face); country: contains over the bilingual country cell ("Syria" and "Syrie"
+    both hit the "Syria / Syrie" row)."""
+    needle = str(name or "").strip().lower() or None
+    cn_needle = str(country or "").strip().lower() or None
+    hits = []
+    for r in rows:
+        if cn_needle and cn_needle not in str(r.get("country") or "").lower():
+            continue
+        if not needle:
+            hits.append({**r, "matched_on": None})
+            continue
+        if needle in str(r.get("name") or "").lower():
+            hits.append({**r, "matched_on": "name"})
+            continue
+        alias = next((a for a in r.get("aliases") or [] if needle in a.lower()), None)
+        if alias:
+            hits.append({**r, "matched_on": "alias"})
+    return hits
+
+
+def sanctions_raw(name=None, *, country=None, limit=20, cache=None, no_cache=False):
+    """Full-register scan (pulls the whole XML, caches 24h, then scans locally)
+    → {rows, total_matched, scanned_rows, limit_applied, params, _meta}.
+
+    name = contains over name + aliases; country = contains over the bilingual country cell.
+    No filter → enumerate from the register head."""
+    from ..transport import call_provider
+
+    size = int(limit) if limit is not None else 20
+    if not 1 <= size <= 100:
+        raise SdkError("usage_error", provider="ca_sema",
+                       detail=f"limit must be 1-100 (local payload wall), got '{limit}'")
+    r = call_provider(provider, "listings", {}, cache=cache, no_cache=no_cache,
+                      extra_headers=_XML_ACCEPT)
+    rows = rows_from_xml(r["data"])
+    hits = filter_rows(rows, name=name, country=country)
+    return {"rows": hits[:size], "total_matched": len(hits), "scanned_rows": len(rows),
+            "limit_applied": size,
+            "params": {"name": name, "country": country}, "_meta": r}