agentdata 0.3.26__py3-none-any.whl

agentdata/legal/lda.py

@@ -0,0 +1,147 @@
+"""lda — US LDA lobbying-disclosure API v1 provider (company name → lobbying filing face; keyless).
+
+The official OpenAPI (lda.gov/api/openapi/v1/) is anonymously usable but rate-limited harder: the ToS anonymous
+tier is 15/min (API key 120/min) — the 0.2.5 fix runs at 14/60 rps with burst 1 (the earlier 0.5 rps = 30/min
+exceeded the limit by 2×; compliance fixed; recorded as an exception in docs/domains/rate-limits.md).
+Channel note (real-machine Python test 2026-10-20): lda.gov fronts with Akamai gating on the **client stack** —
+Node undici always gets 403 and needs the curl subprocess channel; **Python urllib connects directly with 200**
+(machine-local probe: filings count=70,545), so the default urllib path is used
+(gating is stack-dependent — verify per stack on the real machine, do not copy the transport declaration from the Node side).
+DRF requires the trailing slash (without it, 301). Amount pitfall: income/expenses only carry values on
+quarterly reports (Q1-Q4); registration filings (RR/RA) are always null.
+page_size is hard-clamped to 25: verified 2026-10-26, page_size 26/50/100/500 all silently return only 25 rows
+(an earlier note claiming "no published ceiling, 100 = polite cap" was a mis-record — the old verb face's
+limit_applied=100 never actually got more than 25 rows); paging goes through the page param (true offset paging,
+page=2 has a different first row and next/previous are echoed back, verified 2026-10-26).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "lda",
+    "baseUrl": "https://lda.gov/api/v1",
+    "rate": {"rps": 14 / 60, "burst": 1},  # anonymous tier 15/min, hugging the line (quota semantics): the upper bound in any 60s window is 1+14=15≤15 (burst counts against the budget)
+    "ops": {
+        "filings": {"path": "/filings/"},                       # DRF trailing slash; params: registrant_name|client_name|filing_year + page_size/ordering
+        "filing": {"path": "/filings/{filing_uuid}/", "notFound": [404]},
+        "registrant": {"path": "/registrants/{id}/", "notFound": [404]},  # id=house_registrant_id (official key)
+        "client": {"path": "/clients/{id}/", "notFound": [404]},          # id=client_id
+    },
+    "ttl": {"filings": 7 * 86400, "filing": 7 * 86400, "registrant": 30 * 86400, "client": 30 * 86400},
+}
+
+
+def search_filings(client_name=None, registrant_name=None, filing_year=None, *,
+                   limit=20, cache=None, no_cache=False):
+    """→ {total, rows[], _meta}; the client=lobbied company / registrant=lobbying firm two-name face.
+    Amounts are fetched per filing_type (only quarterly reports carry them) — do not judge liveness by
+    "has an amount or not"."""
+    from ..transport import call_provider
+    from datetime import date
+
+    filters = {}
+    if registrant_name:
+        filters["registrant_name"] = str(registrant_name).strip()
+    if client_name:
+        filters["client_name"] = str(client_name).strip()
+    if filing_year is not None:
+        y = int(filing_year)
+        if y < 1999 or y > date.today().year + 1:
+            raise SdkError("usage_error", provider="lda", detail=f"filing_year must be a year from 1999 on, got \"{filing_year}\"")
+        filters["filing_year"] = y
+    if not filters:
+        raise SdkError("usage_error", provider="lda",
+                       detail="search_filings requires registrant_name / client_name / filing_year — at least one of the three")
+    size = min(max(1, int(limit or 20)), 100)  # the verb face keeps the inherited behaviour (upstream hard-clamps to 25, see the module header — overturned 2026-10-26)
+    r = call_provider(provider, "filings", {
+        **filters,
+        "page_size": size,
+        "ordering": "-dt_posted",
+    }, cache=cache, no_cache=no_cache)
+    return {**_rows_from(r["data"]), "total": (r["data"] or {}).get("count"),
+            "limit_applied": size, "_meta": r}
+
+
+def _rows_from(data):
+    """Upstream response → {"rows": [...]} (pure function, offline-testable; shared by both faces)."""
+    return {"rows": [{
+        "filing_uuid": f.get("filing_uuid"),
+        "filing_type": f.get("filing_type"),           # RR registration / Q1-Q4 quarterly report (amounts only on quarterly reports)
+        "filing_type_display": f.get("filing_type_display"),  # upstream human-readable type (reconciled and added in the 2026-10-21 audit)
+        "filing_year": f.get("filing_year"),
+        "period": f.get("filing_period_display") or f.get("filing_period"),
+        "dt_posted": f.get("dt_posted"),
+        "income": f.get("income"),                     # lobbying income (quarterly reports)
+        "expenses": f.get("expenses"),                 # lobbying expenses (quarterly reports)
+        "termination_date": f.get("termination_date"),  # termination filing date (Q Termination reports)
+        "registrant": ({"house_registrant_id": f["registrant"].get("house_registrant_id"),
+                        "name": f["registrant"].get("name"), "state": f["registrant"].get("state")}
+                       if f.get("registrant") else None),
+        "client": ({"client_id": f["client"].get("client_id"), "name": f["client"].get("name"),
+                    "state": f["client"].get("state"), "country": f["client"].get("country")}
+                   if f.get("client") else None),
+        "issues": [a.get("general_issue_code_display") or a.get("general_issue_code")
+                   for a in f.get("lobbying_activities") or []
+                   if a.get("general_issue_code_display") or a.get("general_issue_code")],
+        "document_url": f.get("filing_document_url"),  # direct link to the filing PDF/print view
+    } for f in (data or {}).get("results") or []]}
+
+
+def search_raw(client_name=None, registrant_name=None, filing_year=None, *,
+               limit=20, page=None, ordering="-dt_posted", cache=None, no_cache=False):
+    """Flat-panel low-level face: client_name/registrant_name/filing_year/page_size/ordering/page all go through
+    with verbatim names.
+
+    → {total, rows[], limit_applied, params, _meta}. limit wall 1-25: verified 2026-10-26,
+    page_size 26/50/100/500 all silently return only 25 rows (upstream hard clamp); page through page (true offset paging).
+    client_name (the lobbied company) and registrant_name (the lobbying firm) can be combined (upstream ANDs them)."""
+    from ..transport import call_provider
+    from datetime import date
+
+    params = {}
+    if registrant_name:
+        params["registrant_name"] = str(registrant_name).strip()
+    if client_name:
+        params["client_name"] = str(client_name).strip()
+    if filing_year is not None:
+        y = int(filing_year)
+        if y < 1999 or y > date.today().year + 1:
+            raise SdkError("usage_error", provider="lda", detail=f"filing_year must be a year from 1999 on, got \"{filing_year}\"")
+        params["filing_year"] = y
+    if not params:
+        raise SdkError("usage_error", provider="lda",
+                       detail="search_raw requires client_name / registrant_name / filing_year — at least one of the three"
+                              " (local safety wall: enumerating the full 70,545+ row corpus belongs to the batch line)")
+    lim = int(limit or 20)
+    if not 1 <= lim <= 25:
+        raise SdkError("usage_error", provider="lda",
+                       detail=f"limit must be 1-25 (upstream page_size hard clamp: verified 2026-10-26, "
+                              f"26/50/100/500 silently return only 25 rows), page through page — got \"{limit}\"")
+    params.update({"page_size": lim, "ordering": str(ordering or "-dt_posted")})
+    if page is not None:
+        params["page"] = max(1, int(page))
+    r = call_provider(provider, "filings", params, cache=cache, no_cache=no_cache)
+    return {**_rows_from(r["data"]), "total": (r["data"] or {}).get("count"),
+            "limit_applied": lim, "params": params, "_meta": r}
+
+
+def lookup_registrant(registrant_id, *, cache=None, no_cache=False):
+    """→ the lobbying firm's master record (house_registrant_id official key, normalized)."""
+    from ..transport import call_provider
+
+    try:
+        n = int(registrant_id)
+    except (TypeError, ValueError):
+        n = 0
+    if n <= 0:
+        raise SdkError("usage_error", provider="lda",
+                       detail=f"registrant id must be a positive integer (house_registrant_id), got \"{registrant_id}\"")
+    r = call_provider(provider, "registrant", {"id": n}, cache=cache, no_cache=no_cache)
+    d = r["data"] or {}
+    address = ", ".join(x for x in (d.get("address_1"), d.get("city"), d.get("state"), d.get("country")) if x)
+    return {
+        "house_registrant_id": d.get("house_registrant_id") or n,
+        "name": d.get("name"),
+        "description": d.get("description"),
+        "address": address or None,
+        "_meta": r,
+    }

agentdata/legal/sipri.py

@@ -0,0 +1,178 @@
+"""sipri — SIPRI arms-transfer database provider (country-level arms-trade face; keyless anonymous /api/p).
+
+Shape verified 2026-10-20: POST JSON body {filters:[…], logic:"AND", type:"delivered"|"orders", status:"0",
+pageNo, pageSize, sorts:{}}; **country filters need a numeric EntityId in listData** (putting a country name in
+value1 → 500 NumberFormatException); the EntityId table = GET /countries/getAllCountriesTrimmed (385 countries,
+quasi-static); the response is a **bare array** (no wrapper key); sorts must be a map ({}), not an array; pageSize is
+capped at 100; a wrong prefix /api/v1 = 401.
+Note: trades is a country-level face (buyer/seller = country names), not a company-level one — the company-level
+universe lives in the Top-100 XLSX (batch line).
+TTL: trades 30 days (the historical database changes slowly) / countries 30 days (quasi-static table); polite rate 0.5 rps.
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "sipri",
+    "baseUrl": "https://atbackend.sipri.org/api/p",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "trades": {"path": "/trades/search", "method": "POST", "idempotent": True},  # params: the whole body (filters/logic/type/status/pageNo/pageSize/sorts)
+        "countries": {"path": "/countries/getAllCountriesTrimmed"},                  # params: none (the full 385-country EntityId table)
+    },
+    "ttl": {"trades": 30 * 86400, "countries": 30 * 86400},
+}
+
+
+def _mk_filter(field, entity_id):
+    return {"field": field, "oldField": "", "condition": "contains", "value1": "", "value2": "",
+            "logic": "AND", "listData": [entity_id]}
+
+
+def trades_body(supplier_id=None, recipient_id=None, *, type="delivered", page=1, limit=20):
+    """→ the POST body (pure function so the body is offline-testable); a country name in value1 → upstream 500,
+    it needs a numeric EntityId in listData."""
+    if type not in ("delivered", "orders"):
+        raise SdkError("usage_error", provider="sipri", detail=f"type must be delivered|orders, got \"{type}\"")
+    filters = []
+    if supplier_id:
+        filters.append(_mk_filter("Supplier", supplier_id))
+    if recipient_id:
+        filters.append(_mk_filter("Recipient", recipient_id))
+    if not filters:
+        raise SdkError("usage_error", provider="sipri",
+                       detail="search_trades requires supplier / recipient — at least one of the two")
+    return {
+        "filters": filters, "logic": "AND", "type": type, "status": "0",
+        "pageNo": max(1, int(page or 1)), "pageSize": min(max(1, int(limit or 20)), 100), "sorts": {},
+    }
+
+
+def _resolve_country(name, cache=None, no_cache=False):
+    """Country name → EntityId (exact match, case-insensitive; the table is cached for 30 days).
+    On a miss it offers near matches."""
+    from ..transport import call_provider
+
+    r = call_provider(provider, "countries", {}, cache=cache, no_cache=no_cache)
+    lst = r["data"] if isinstance(r["data"], list) else []
+    low = str(name).lower()
+    hit = next((c for c in lst if str(c.get("Name") or "").lower() == low), None)
+    if not hit:
+        near = [c.get("Name") for c in lst if low in str(c.get("Name") or "").lower()][:5]
+        hint = f" (near: {' / '.join(near)})" if near else " (use the full English name, e.g. United States / Angola)"
+        raise SdkError("usage_error", provider="sipri", detail=f"country name is not in the SIPRI table: \"{name}\"{hint}")
+    return {"entity_id": hit["EntityId"], "name": hit["Name"], "code": hit.get("CountryCode"), "_meta": r}
+
+
+def search_trades(supplier=None, recipient=None, *, type=None, page=1, limit=20,
+                  cache=None, no_cache=False):
+    """→ {rows[], _meta, _metas}; arms-transfer rows (country × model × quantity).
+    Each country-name → EntityId resolution costs one cached call (30-day table); the trades call passes through,
+    and metas keeps the from_cache flags accurate for the whole chain."""
+    from ..transport import call_provider
+
+    if not supplier and not recipient:
+        raise SdkError("usage_error", provider="sipri",
+                       detail="search_trades requires supplier / recipient — at least one of the two")
+    size = min(max(1, int(limit or 20)), 100)  # upstream pageSize caps at 100; truncation must stay visible (limit_applied)
+    metas = []
+    supplier_id = recipient_id = None
+    if supplier:
+        s = _resolve_country(supplier, cache, no_cache)
+        supplier_id, _ = s["entity_id"], metas.append(s["_meta"])
+    if recipient:
+        s = _resolve_country(recipient, cache, no_cache)
+        recipient_id, _ = s["entity_id"], metas.append(s["_meta"])
+    r = call_provider(provider, "trades",
+                      trades_body(supplier_id, recipient_id, type=type or "delivered",
+                                  page=page, limit=limit),
+                      cache=cache, no_cache=no_cache)
+    data = r["data"]
+    trades = data if isinstance(data, list) else (data or {}).get("trades") or []
+    rows = [{
+        "trade_id": t.get("tradeId") or t.get("id"),
+        "supplier": t.get("seller"),               # exporting country (country name)
+        "recipient": t.get("buyer"),               # importing country (country name)
+        "order_year": t.get("orderYr"),
+        "order_year_est": t.get("orderYrEst"),     # estimated flag (data-quality flag)
+        "delivery_year": t.get("deliveryYr"),
+        "units": t.get("units"),
+        "units_est": t.get("unitsEst"),
+        "designation": t.get("desg"),              # model (An-26 etc.)
+        "description": t.get("desc"),              # equipment description (transport aircraft)
+        "category": t.get("category"),             # major category (Aircraft etc.)
+        "sub_category": t.get("subCategory"),
+    } for t in trades]
+    return {"rows": rows, "limit_applied": size, "_meta": r, "_metas": metas + [r]}
+
+
+def search_raw(filters=None, *, supplier=None, recipient=None, type="delivered",
+               page=1, limit=20, cache=None, no_cache=False):
+    """Flat-panel low-level face: filters (the raw POST body, verbatim-name channel: [{field, listData:[EntityId], …}])
+    XOR supplier/recipient (sugar: country name → EntityId resolved against the 30-day cached table first).
+
+    → {rows[], limit_applied, resolved_countries, params, _meta, _metas} — params is the exact POST body sent.
+    A country name in value1 → upstream 500 NumberFormatException (verified 2026-10-20): the sugar channel
+    guarantees that what lands in listData is a numeric EntityId; pageSize wall 1-100 (upstream cap,
+    verified 2026-10-20)."""
+    from ..transport import call_provider
+
+    if filters is not None and (str(supplier or "").strip() or str(recipient or "").strip()):
+        raise SdkError("usage_error", provider="sipri",
+                       detail="filters (verbatim-name channel: numeric EntityId in listData) and supplier/recipient "
+                              "(sugar: country names resolved to EntityId first) are mutually exclusive — give only one")
+    lim = int(limit or 20)
+    if not 1 <= lim <= 100:
+        raise SdkError("usage_error", provider="sipri",
+                       detail=f"limit must be 1-100 (upstream pageSize caps at 100, verified 2026-10-20), got \"{limit}\"")
+    if type not in ("delivered", "orders"):
+        raise SdkError("usage_error", provider="sipri", detail=f"type must be delivered|orders, got \"{type}\"")
+    metas, resolved = [], {}
+    if filters is not None:
+        if not isinstance(filters, list) or not filters:
+            raise SdkError("usage_error", provider="sipri",
+                           detail="filters must be a non-empty list ([{field:'Supplier'|'Recipient', listData:[EntityId], …}])")
+        for f in filters:
+            if not isinstance(f, dict) or f.get("field") not in ("Supplier", "Recipient") \
+                    or not (isinstance(f.get("listData"), list) and f["listData"]):
+                raise SdkError("usage_error", provider="sipri",
+                               detail="filters elements look like {\"field\": \"Supplier\", \"listData\": [<numeric EntityId>]} — "
+                                      "a country name in value1 causes a 500 (verified 2026-10-20)")
+            for eid in f["listData"]:
+                if not str(eid).isdigit():
+                    raise SdkError("usage_error", provider="sipri",
+                                   detail=f"listData must hold numeric EntityIds (resolve country names first via the supplier/recipient sugar), got \"{eid}\"")
+        body = {"filters": filters, "logic": "AND", "type": type, "status": "0",
+                "pageNo": max(1, int(page or 1)), "pageSize": lim, "sorts": {}}
+    else:
+        if not supplier and not recipient:
+            raise SdkError("usage_error", provider="sipri",
+                           detail="search_raw requires supplier / recipient (country names) or filters (the raw EntityId table) — at least one of the two")
+        sid = rid = None
+        if supplier:
+            s = _resolve_country(supplier, cache, no_cache)
+            sid, resolved["supplier"] = s["entity_id"], {"entity_id": s["entity_id"], "name": s["name"]}
+            metas.append(s["_meta"])
+        if recipient:
+            s = _resolve_country(recipient, cache, no_cache)
+            rid, resolved["recipient"] = s["entity_id"], {"entity_id": s["entity_id"], "name": s["name"]}
+            metas.append(s["_meta"])
+        body = trades_body(sid, rid, type=type, page=page, limit=lim)
+    r = call_provider(provider, "trades", body, cache=cache, no_cache=no_cache)
+    data = r["data"]
+    trades = data if isinstance(data, list) else (data or {}).get("trades") or []
+    rows = [{
+        "trade_id": t.get("tradeId") or t.get("id"),
+        "supplier": t.get("seller"),               # exporting country (country name)
+        "recipient": t.get("buyer"),               # importing country (country name)
+        "order_year": t.get("orderYr"),
+        "order_year_est": t.get("orderYrEst"),     # estimated flag (data-quality flag)
+        "delivery_year": t.get("deliveryYr"),
+        "units": t.get("units"),
+        "units_est": t.get("unitsEst"),
+        "designation": t.get("desg"),              # model (An-26 etc.)
+        "description": t.get("desc"),              # equipment description (transport aircraft)
+        "category": t.get("category"),             # major category (Aircraft etc.)
+        "sub_category": t.get("subCategory"),
+    } for t in trades]
+    return {"rows": rows, "limit_applied": lim, "resolved_countries": resolved or None,
+            "params": body, "_meta": r, "_metas": metas + [r]}

agentdata/legal/ukec.py

@@ -0,0 +1,148 @@
+"""ukec — UK Electoral Commission political funding provider (donations + loans two faces; keyless).
+
+search.electoralcommission.org.uk/api/search/. Shape verified 2026-10-20: donations carry the full param set
+sort/order/et/date/rptPd/prePoll + from/to; loans need the triplicate params loanStatus×2 + register×3 +
+isIrishSource×2 — missing params → Total=-1 (fake success); the response is a .NET-family shape —
+rows live in **Result (singular)**, the amount key is Value, dates are `/Date(epoch)/`.
+Channel note (real-machine Python test 2026-10-20): Node undici hits a connection-level timeout and needs the
+curl channel; **Python urllib connects directly with 200** (machine-local probe: donations 200), so the default
+urllib path is used — gating is client-stack dependent, verify each stack on the real machine.
+urllib cannot assemble repeated query keys → the full param set is baked into op.path (the dynamic keys
+query/start/rows/from/to are appended by core).
+rows is hard-clamped to 50: verified 2026-10-26, rows=51→50 and 200→50 (an earlier note saying "100 = polite cap"
+never actually got 50+ rows — the old verb face's limit_applied=100 only ever got 50 upstream).
+TTL 24h (quarterly cadence, rows change slowly); polite rate 0.5 rps.
+"""
+import re
+from datetime import date
+
+from ..errors import SdkError
+
+provider = {
+    "id": "ukec",
+    "baseUrl": "https://search.electoralcommission.org.uk/api/search",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "donations": {"path": "/donations?sort=AcceptedDate&order=desc&et=pp&date=Accepted&rptPd=&prePoll=false"},
+        "loans": {"path": "/loans?sort=StartDate&order=desc&loanStatus=outstanding&loanStatus=ended&register=gb&register=ni&register=none&isIrishSourceYes=true&isIrishSourceNo=true"},
+    },
+    "ttl": {"donations": 24 * 3600, "loans": 24 * 3600},
+}
+
+REGISTER_START = "2001-02-16"  # PPERA 2000 in force (register origin) — the default for the full-history window
+
+
+def date_window(_from=None, to=None):
+    """Complete the ends into a full range (guards against the -1 fake success caused by donations' from/to
+    defaults; the edgar-fts end-completion has the same semantics)."""
+    f = str(_from or REGISTER_START)
+    t = str(to or date.today().isoformat())
+    return {"params": {"from": f, "to": t}, "date_range": {"from": f, "to": t}}
+
+
+def _dotnet_date(v):
+    """/Date(1762214400000)/ → ISO date; non-.NET date values pass through unchanged."""
+    m = re.search(r"/Date\((\d+)\)/", str(v or ""))
+    if m:
+        return date.fromtimestamp(int(m.group(1)) // 1000).isoformat()
+    return v
+
+
+def _pick(row, *keys):
+    for k in keys:
+        if row.get(k) is not None:
+            return row[k]
+    return None
+
+
+def _to_rows(data):
+    """Row normalization: .NET PascalCase keys (Result, singular, array); the donations and loans faces share
+    the same shape (same Value key).
+    Loan rows have no LenderName key — the counterparty is in LoanParticipantName (probed in the 2026-10-21 audit,
+    fixing the bug where the lender name on the loans face was always null); the loan type key is LoanType,
+    not TypeDescription."""
+    return [{
+        "donor_or_lender": _pick(d, "DonorName", "LenderName", "LoanParticipantName"),
+        "recipient": _pick(d, "RegulatedEntityName", "RecipientName"),
+        "recipient_registration": _pick(d, "CompanyRegistrationNumber"),
+        "value_gbp": _pick(d, "Value", "AcceptedValue"),
+        "date": _dotnet_date(_pick(d, "AcceptedDate", "StartDate")),
+        "type_description": _pick(d, "DonationType", "TypeDescription", "LoanType"),
+        "donation_action": _pick(d, "DonationAction"),
+        "ec_ref": _pick(d, "ECRef"),
+    } for d in ((data or {}).get("Result") or (data or {}).get("Results") or [])[:100]]
+
+
+def search_donations(query, *, _from=None, to=None, limit=20, cache=None, no_cache=False):
+    """→ {total, rows[], date_range, _meta}; query = donor/regulated-entity name, contains-match."""
+    from ..transport import call_provider
+
+    q = str(query or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="ukec", detail="donations requires query (donor / regulated-entity name)")
+    win = date_window(_from, to)
+    size = min(max(1, int(limit or 20)), 100)  # the verb face keeps the inherited behaviour (upstream hard-clamps to 50, see the module header — overturned 2026-10-26)
+    r = call_provider(provider, "donations", {
+        "query": q, "start": 0, "rows": size, **win["params"],
+    }, cache=cache, no_cache=no_cache)
+    return {"total": (r["data"] or {}).get("Total"), "rows": _to_rows(r["data"]),
+            "limit_applied": size, "date_range": win["date_range"], "_meta": r}
+
+
+def search_loans(query, *, limit=20, cache=None, no_cache=False):
+    """→ {total, rows[], _meta}; the loans face (the regulatory params are baked into the path)."""
+    from ..transport import call_provider
+
+    q = str(query or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="ukec", detail="loans requires query (lender / borrower name)")
+    size = min(max(1, int(limit or 20)), 100)  # the verb face keeps the inherited behaviour (upstream hard-clamps to 50, see the module header — overturned 2026-10-26)
+    r = call_provider(provider, "loans", {
+        "query": q, "start": 0, "rows": size,
+    }, cache=cache, no_cache=no_cache)
+    return {"total": (r["data"] or {}).get("Total"), "rows": _to_rows(r["data"]), "limit_applied": size, "_meta": r}
+
+
+def _wall_rows_limit(limit):
+    lim = int(limit or 20)
+    if not 1 <= lim <= 50:
+        raise SdkError("usage_error", provider="ukec",
+                       detail=f"limit must be 1-50 (upstream rows hard clamp: verified 2026-10-26, 51→50 and 200→50), got \"{limit}\"")
+    return lim
+
+
+def donations_raw(query, *, _from=None, to=None, limit=20, start=0, cache=None, no_cache=False):
+    """Flat-panel low-level face: query/from/to/start/rows go through with upstream verbatim names (donations face).
+
+    → {total, rows[], limit_applied, date_range, params, _meta}. When the window is missing we complete the ends
+    (a missing from/to → upstream Total=-1 fake success — we fill from the 2001-02-16 register origin to today);
+    limit wall 1-50 (upstream rows hard clamp of 50, verified 2026-10-26)."""
+    from ..transport import call_provider
+
+    q = str(query or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="ukec", detail="donations requires query (donor / regulated-entity name)")
+    lim = _wall_rows_limit(limit)
+    win = date_window(_from, to)
+    params = {"query": q, "start": max(0, int(start or 0)), "rows": lim, **win["params"]}
+    r = call_provider(provider, "donations", params, cache=cache, no_cache=no_cache)
+    return {"total": (r["data"] or {}).get("Total"), "rows": _to_rows(r["data"]),
+            "limit_applied": lim, "date_range": win["date_range"], "params": params, "_meta": r}
+
+
+def loans_raw(query, *, limit=20, start=0, cache=None, no_cache=False):
+    """Flat-panel low-level face: query/start/rows go through with upstream verbatim names (loans face; the
+    regulatory triplicate is baked into op.path).
+
+    → {total, rows[], limit_applied, params, _meta}; the limit wall is the same as for donations
+    (upstream hard clamp 50)."""
+    from ..transport import call_provider
+
+    q = str(query or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="ukec", detail="loans requires query (lender / borrower name)")
+    lim = _wall_rows_limit(limit)
+    params = {"query": q, "start": max(0, int(start or 0)), "rows": lim}
+    r = call_provider(provider, "loans", params, cache=cache, no_cache=no_cache)
+    return {"total": (r["data"] or {}).get("Total"), "rows": _to_rows(r["data"]),
+            "limit_applied": lim, "params": params, "_meta": r}

agentdata/legal/wb.py

@@ -0,0 +1,92 @@
+"""wb — World Bank debarred-firms roster provider (apigwext SAP gateway; keyless via the page-embedded public apikey).
+
+legal debarment-roster face (0.3.21; admitted 2026-11-02, probed tmp/probe-debar-0321). Shape measured 2026-11-02:
+GET /dvsvc/v1.0/json/APPLICATION/ADOBE_EXPRNCE_MGR/FIRM/SANCTIONED_FIRM + header apikey
+  → {"response": {"ZPROCSUPP": [1,546 rows × 45 SAP fields]}} — a single-shot full dump, no paging, 1.77MB
+  (the page self-reports a 3-hour refresh; the row count drifts as the live register is regenerated).
+Golden fields: SUPP_ID (the WB supplier key) × SUPP_NAME × SUPP_TYPE_CODE (F firm 1,268 / I individual 269 /
+U 8 / C 1) × LAND1+COUNTRY_NAME × address quartet × SUPP_ELIG_STAT (DEBARRED 890 / X-DEBARRED 656) ×
+DEBAR_FROM_DATE~DEBAR_TO_DATE (**2999-12-31 = indefinite**, measured) × DEBAR_REASON (procurement-guidelines
+clause citation, "Procurement Guidelines, 1.14(a)(ii)") × INELIGIBLY_STATUS ("Ongoing"). China leads the
+roster at 392 firms (LAND1=CN, measured 2026-11-02); DNB/REGISTER identifier fields exist in the schema but
+measure empty — name walk is the join channel (name × country narrows well).
+The gateway apikey is a **browser-public constant embedded in the debarred-firms page inline script** (every
+browser visitor sends the same key; not a registration credential — the same class as dgcomp's CS_PROD_ODSE_PROD
+public config key); pinned live 2026-11-02: plain agentdata UA + this key = 200, no UA override needed.
+Screening = **local full-register scan** (upstream has no query surface) — pull the whole dump once, cache 24h,
+then contains-match scans run with zero network (same contract as csl_screening_list).
+TTL: 24h (upstream refreshes every 3h; a day-old screening register is fine); polite tier 0.2 rps
+(single-endpoint face, one pull per day suffices).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "wb",
+    "baseUrl": "https://apigwext.worldbank.org",
+    "rate": {"rps": 0.2, "burst": 1},
+    "ops": {
+        "sanctioned_firms": {  # single-shot full dump (no paging, no query surface)
+            "path": "/dvsvc/v1.0/json/APPLICATION/ADOBE_EXPRNCE_MGR/FIRM/SANCTIONED_FIRM",
+            "timeoutMs": 120000,  # 1.77MB JSON
+        },
+    },
+    "ttl": {"sanctioned_firms": 24 * 3600},
+}
+
+# browser-public apikey embedded in the debarred-firms page inline script (pinned 2026-11-02;
+# the same constant every browser visitor sends — not a .env credential, see module docstring)
+_PUBLIC_APIKEY = {"apikey": "z9duUaFUiEUYSHs97CU38fcZO7ipOPvm"}
+
+# row narrowing: of the 45 SAP fields, the twelve golden ones (identity × jurisdiction × window × reason)
+_FIELDS = ("SUPP_ID", "SUPP_NAME", "SUPP_TYPE_CODE", "LAND1", "COUNTRY_NAME", "SUPP_CITY", "SUPP_ADDR",
+           "SUPP_ELIG_STAT", "DEBAR_FROM_DATE", "DEBAR_TO_DATE", "DEBAR_REASON", "INELIGIBLY_STATUS")
+
+
+def rows_from_upstream(data):
+    """Upstream ZPROCSUPP array → debarred-firm rows (pure function, offline-testable; SAP field names verbatim,
+    narrowed to the golden twelve — the DNB/REGISTER identifier fields measure empty and are dropped)."""
+    payload = (data or {}).get("response") or {}
+    rows = [{k: r.get(k) for k in _FIELDS} for r in (payload.get("ZPROCSUPP") or [])]
+    return rows
+
+
+def filter_rows(rows, name=None, country=None, type=None):
+    """Local register scan (pure function for offline regression). name: contains-match (case-insensitive)
+    over SUPP_NAME; country: contains over COUNTRY_NAME **or** the LAND1 code ("China" and "CN" both hit);
+    type: exact over SUPP_TYPE_CODE (F/I/U/C, case-insensitive)."""
+    needle = str(name or "").strip().lower() or None
+    cn_needle = str(country or "").strip().lower() or None
+    ty_needle = str(type or "").strip().upper() or None
+    hits = []
+    for r in rows:
+        if cn_needle and cn_needle not in str(r.get("COUNTRY_NAME") or "").lower() \
+                and cn_needle != str(r.get("LAND1") or "").lower():
+            continue
+        if ty_needle and str(r.get("SUPP_TYPE_CODE") or "").strip().upper() != ty_needle:
+            continue
+        if needle and needle not in str(r.get("SUPP_NAME") or "").lower():
+            continue
+        hits.append(r)
+    return hits
+
+
+def debarred_firms_raw(name=None, *, country=None, type=None, limit=20, cache=None, no_cache=False):
+    """Full-register scan (pulls the whole dump, caches 24h, then scans locally)
+    → {rows, total_matched, scanned_rows, limit_applied, params, _meta}.
+
+    name = contains-match over SUPP_NAME; country = contains over country name or the LAND1 code;
+    type = F/I/U/C exact. No filter → enumerate from the register head (the local payload wall keeps
+    truncation visible: total_matched echoes the exact hit count)."""
+    from ..transport import call_provider
+
+    size = int(limit) if limit is not None else 20  # explicit None check — an `or default` swallows 0, the 0.2.10 trap
+    if not 1 <= size <= 100:
+        raise SdkError("usage_error", provider="wb",
+                       detail=f"limit must be 1-100 (local payload wall), got '{limit}'")
+    r = call_provider(provider, "sanctioned_firms", {}, cache=cache, no_cache=no_cache,
+                      extra_headers=_PUBLIC_APIKEY)
+    rows = rows_from_upstream(r["data"])
+    hits = filter_rows(rows, name=name, country=country, type=type)
+    return {"rows": hits[:size], "total_matched": len(hits), "scanned_rows": len(rows),
+            "limit_applied": size,
+            "params": {"name": name, "country": country, "type": type}, "_meta": r}

agentdata/procurement/__init__.py

@@ -0,0 +1,5 @@
+"""procurement domain package — flat provider adapters (one file per source) + faces/cli (0.3.0, seventh package).
+
+PNCP/SECOP passed the admission gate, ruled 2026-10-29.
+"""
+from . import br_pncp, co_secop  # noqa: F401