agentdata 0.3.26__py3-none-any.whl

agentdata/legal/federalregister.py

@@ -0,0 +1,188 @@
+"""federalregister — Federal Register API provider (federalregister.gov; keyless).
+
+Federal regulations/notices full-text search over the daily release stream (rules, proposed rules, notices).
+Shape verified 2026-10-23:
+GET /api/v1/documents.json?conditions[term]=<q>&conditions[publication_date][gte|lte]=YYYY-MM-DD
+  &per_page=N&page=1&order=newest|relevance
+  → {count, total_pages, next_page_url, results:[{document_number, type:RULE|PRORULE|NOTICE|PRESDOCU,
+     title, abstract, publication_date, agencies:[{name,raw_name,url}], citation, comments_close_on, …}]}
+— omitting fields[] returns every field (a few KB per record; no problem observed at per_page 50 this round).
+GET /api/v1/documents/{document_number}.json → a single record with raw_text_url/body_html_url (full-text anchors,
+used by the corpus batch line to fetch documents).
+The date range must carry both ends to actually filter (the EDGAR FTS trap of the same kind: a single end is
+silently ignored — this provider always sends both ends).
+TTL: search 24h (daily release stream) / single record 30 days; polite rate 1 rps (official no-key guidance ≤5,
+we take the conservative value).
+"""
+import re
+from datetime import date
+
+from ..errors import SdkError
+
+provider = {
+    "id": "federalregister",
+    "baseUrl": "https://www.federalregister.gov",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "search": {"path": "/api/v1/documents.json"},     # params: conditions[term], conditions[publication_date][gte/lte], per_page, page, order
+        "document": {"path": "/api/v1/documents/{doc}.json"},  # doc = document_number (e.g. 2026-12345)
+    },
+    "ttl": {"search": 24 * 3600, "document": 30 * 86400},
+}
+
+_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+# 0.2.9 audit (2026-10-28): order has a fourth official value executive_order_number (listed in the official
+# documentation.json, verified 200 in a live probe) — the old whitelist missed it and blocked it locally by mistake.
+# The type closed set has four values (official enumeration); **an invalid type silently returns
+# 0 rows upstream** (conditions[type][]=BOGUS → 200 count=0, no 400 — a false-negative trap), so it is blocked
+# locally here (osv/sectors have the same shape).
+ORDERS = ("relevance", "newest", "oldest", "executive_order_number")
+DOC_TYPES = ("RULE", "PRORULE", "NOTICE", "PRESDOCU")
+
+
+def docs_from_upstream(data, size):
+    """Upstream response → hit rows (pure function, offline-testable)."""
+    rows = [{
+        "document_number": d.get("document_number"),     # stable key (used by the corpus batch line to fetch full text)
+        "title": d.get("title"),
+        "type": d.get("type"),                           # RULE|PRORULE|NOTICE|PRESDOCU
+        "publication_date": d.get("publication_date"),
+        "abstract": d.get("abstract") or None,           # upstream often returns an empty string — normalize to None
+        "citation": d.get("citation"),
+        "agencies": [a.get("name") or a.get("raw_name") for a in (d.get("agencies") or [])
+                     if a.get("name") or a.get("raw_name")],
+        "docket_ids": d.get("docket_ids") or [],
+        "comments_close_on": d.get("comments_close_on") or None,
+        "url": d.get("html_url"),
+    } for d in ((data or {}).get("results") or [])]
+    return {
+        "rows": rows, "count": len(rows),
+        "limit_applied": size,
+        "total": data.get("count") if isinstance(data, dict) and isinstance(data.get("count"), int) else None,
+        "total_pages": data.get("total_pages") if isinstance(data, dict) and isinstance(data.get("total_pages"), int) else None,
+    }
+
+
+def search_docs(q=None, *, startdt=None, enddt=None, order="relevance", page=1, limit=20,
+                cache=None, no_cache=False):
+    """→ {rows[], count, limit_applied, total, total_pages, _meta}; full-text search hits (q goes through
+    conditions[term] at full-text level).
+    The date range requires startdt/enddt as a pair (a single end is silently ignored upstream — reject it
+    outright rather than pass it silently)."""
+    from ..transport import call_provider
+
+    term = str(q or "").strip()
+    if not term:
+        raise SdkError("usage_error", provider="federalregister",
+                       detail="search_docs requires q (quote phrases for exact-phrase matching)")
+    if (startdt is None) != (enddt is None):
+        raise SdkError("usage_error", provider="federalregister",
+                       detail="the date range requires startdt and enddt as a pair (a single end is silently ignored upstream)")
+    for d in (startdt, enddt):
+        if d is not None and not _DATE.match(d):
+            raise SdkError("usage_error", provider="federalregister", detail=f"date must be YYYY-MM-DD: {d}")
+    if order not in ORDERS:
+        raise SdkError("usage_error", provider="federalregister", detail=f"order must be one of {'|'.join(ORDERS)}, got \"{order}\"")
+    size = min(max(1, int(limit or 20)), 50)  # upstream per_page ceiling is 1000 — our polite cap is 50 (realtime face)
+    params = {"conditions[term]": term, "per_page": size, "page": max(1, int(page or 1)), "order": order}
+    if startdt:
+        params["conditions[publication_date][gte]"] = startdt
+        params["conditions[publication_date][lte]"] = enddt
+    r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    return {**docs_from_upstream(r["data"], size), "_meta": r}
+
+
+DATA_START = "1994-01-01"  # Federal Register data start (1994+ daily release stream) — the default when one end is missing
+
+
+def search_raw(q, *, startdt=None, enddt=None, order="relevance", page=1, limit=20,
+               doc_type=None, agencies=None, cfr_title=None, cfr_part=None,
+               cache=None, no_cache=False):
+    """Flat-panel low-level face + 0.2.9 audit param additions: conditions[term]/[publication_date][gte|lte]/
+    [type][]/[agencies][]/[cfr][title|part]/per_page/page/order go through with verbatim names.
+
+    → {rows[], count, limit_applied, total, total_pages, date_range, params, _meta}.
+    Missing end is auto-completed (same semantics as the full-text face): giving either end completes the other
+    (missing startdt → 1994-01-01, missing enddt → today), after which both ends are always sent — a single end is
+    silently ignored upstream (verified 2026-10-23). limit polite cap 50 (upstream per_page ceiling 1000).
+    0.2.9 new params (reconciled against the official documentation.json and probed live 2026-10-28):
+    - order's fourth value executive_order_number (listed officially, verified 200) — the old whitelist's false block is fixed.
+    - doc_type→conditions[type][]: the closed set of four values RULE/PRORULE/NOTICE/PRESDOCU is validated locally —
+      **an invalid value silently returns 0 rows upstream** (type=BOGUS → 200 count=0, no 400 — a false-negative trap);
+      valid values really filter (asbestos+PRORULE=426 vs 2551 unfiltered, the response description says
+      "of type Proposed Rule"). Single value/param (upstream array members need repeated keys, the transport dict does
+      not support repeated keys — the multi-value OR is not exposed for now, recorded).
+    - agencies→conditions[agencies][]: agency slug (value domain from GET /api/v1/agencies; environmental-protection-agency
+      verified working, the description says "from Environmental Protection Agency").
+    - cfr_title/cfr_part→conditions[cfr][title]/[part]: code-anchored search (part may be a range form "763" or "1-50"
+      per the official wording, and the official text states that part requires the CFR title — this face rejects cp
+      without ct; title=40&part=763 verified count=33, all Rules — the TSCA section; cfr alone (no term) also works,
+      while q is required here because that is the search-face semantics, not an upstream restriction)."""
+    from ..transport import call_provider
+
+    term = str(q or "").strip()
+    if not term:
+        raise SdkError("usage_error", provider="federalregister",
+                       detail="search_raw requires q (quote phrases for exact-phrase matching)")
+    for d in (startdt, enddt):
+        if d is not None and not _DATE.match(d):
+            raise SdkError("usage_error", provider="federalregister", detail=f"date must be YYYY-MM-DD: {d}")
+    if order not in ORDERS:
+        raise SdkError("usage_error", provider="federalregister",
+                       detail=f"order must be one of {'|'.join(ORDERS)}, got \"{order}\"")
+    dt = str(doc_type or "").strip() or None
+    if dt is not None and dt not in DOC_TYPES:
+        raise SdkError("usage_error", provider="federalregister",
+                       detail=f"doc_type \"{dt}\" is not in the closed set ({'|'.join(DOC_TYPES)}; "
+                              "invalid values silently return 0 rows upstream — the false-negative guard lives here; "
+                              "official enumeration documentation.json reconciled 2026-10-28)")
+    ag = str(agencies or "").strip() or None
+    ct = str(cfr_title or "").strip() or None
+    cp = str(cfr_part or "").strip() or None
+    if cp and not ct:
+        raise SdkError("usage_error", provider="federalregister",
+                       detail="cfr_part must be used together with cfr_title (official semantics: part requires the title anchor)")
+    size = min(max(1, int(limit or 20)), 50)  # polite cap 50 (upstream ceiling 1000) — realtime single-query face
+    dr = None
+    if startdt or enddt:
+        s = startdt or DATA_START
+        e = enddt or date.today().isoformat()
+        dr = {"startdt": s, "enddt": e}
+    params = {"conditions[term]": term, "per_page": size, "page": max(1, int(page or 1)), "order": order}
+    if dr:
+        params["conditions[publication_date][gte]"] = dr["startdt"]
+        params["conditions[publication_date][lte]"] = dr["enddt"]
+    if dt:
+        params["conditions[type][]"] = dt
+    if ag:
+        params["conditions[agencies][]"] = ag
+    if ct:
+        params["conditions[cfr][title]"] = ct
+    if cp:
+        params["conditions[cfr][part]"] = cp
+    r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    return {**docs_from_upstream(r["data"], size), "date_range": dr, "params": params, "_meta": r}
+
+
+def get_document(doc, *, cache=None, no_cache=False):
+    """→ a single record with all fields (including the raw_text_url / body_html_url full-text anchors)."""
+    from ..transport import call_provider
+
+    d = str(doc or "").strip()
+    if not re.fullmatch(r"\d{2,4}-\d{1,6}", d):
+        raise SdkError("usage_error", provider="federalregister",
+                       detail=f"not in document_number form (e.g. 2026-12345): {doc}")
+    r = call_provider(provider, "document", {"doc": d}, cache=cache, no_cache=no_cache)
+    x = r["data"] or {}
+    return {
+        "document_number": x.get("document_number") or d, "title": x.get("title"), "type": x.get("type"),
+        "publication_date": x.get("publication_date"), "abstract": x.get("abstract") or None,
+        "citation": x.get("citation"),
+        "agencies": [a.get("name") or a.get("raw_name") for a in (x.get("agencies") or [])
+                     if a.get("name") or a.get("raw_name")],
+        "docket_ids": x.get("docket_ids") or [],
+        "body_html_url": x.get("body_html_url"), "raw_text_url": x.get("raw_text_url"),
+        "comments_close_on": x.get("comments_close_on") or None, "url": x.get("html_url"),
+        "_meta": r,
+    }

agentdata/legal/gb_cma.py

@@ -0,0 +1,117 @@
+"""gb_cma — UK Competition and Markets Authority case face provider (www.gov.uk content/search API; keyless).
+
+Shape verified 2026-10-29:
+GET /api/search.json?filter_format=cma_case&q=&count=&start=
+  → {results:[{title,link:'/cma-cases/<slug>',_id=content_id,public_timestamp,description,
+     organisations:[…],format:'cma_case',…}], total, start, aggregates, …}
+  — filter_format=cma_case is this face's semantics (a fixed param, not a user param); q/count/start go through
+  with upstream verbatim names.
+  count has no upstream wall (verified 2026-10-29: count=1000 → the full 1000 rows/76KB in one shot) — this face
+  uses a politeness cap of 100.
+GET /api/content/cma-cases/{slug}
+  → {content_id(UUID stable key), title, first_published_at, public_updated_at, updated_at,
+     withdrawn_notice, details:{body(HTML), change_history:[{note,public_timestamp}],
+     attachments:[{title,url,content_type,content_id,…}]}, links:{organisations,…}}
+Param-minimalism pitfall: combined params like organisations/order → 422 — this face accepts only q/count/start,
+do not widen it.
+atom incremental feed: /cma-cases.atom (the increment anchor for the corpus batch line; not used by this realtime face).
+TTL: search 24h (the case list drifts at daily cadence) / case 7 days (case cards change slowly; change_history
+records the evolution); polite rate 1 rps (gov.uk publishes no search-API quota — conservative).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "gb_cma",
+    "baseUrl": "https://www.gov.uk",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "search": {"path": "/api/search.json"},          # params: q, count, start (filter_format is fixed for this face)
+        "case": {"path": "/api/content/cma-cases/{slug}"},  # slug = the tail segment of the case-page base_path (the search row's link field)
+    },
+    "ttl": {"search": 24 * 3600, "case": 7 * 86400},
+}
+
+
+def cases_from_upstream(data, size):
+    """Upstream search response → case rows (pure function, offline-testable)."""
+    rows = [{
+        "slug": (r.get("link") or "").removeprefix("/cma-cases/") or None,  # join key into the detail face (link=/cma-cases/<slug>;
+                                                                           # the search row's _id ≡ base_path, not a UUID — do not pass it off as content_id)
+        "title": r.get("title"),                       # case name = the party pair "A / B" form
+        "public_timestamp": r.get("public_timestamp"),
+        "description": r.get("description") or None,
+        "organisations": [o.get("title") for o in (r.get("organisations") or []) if o.get("title")],
+        "url": ("https://www.gov.uk" + r["link"]) if r.get("link") else None,
+    } for r in ((data or {}).get("results") or [])]
+    return {
+        "rows": rows, "count": len(rows), "limit_applied": size,
+        "total": data.get("total") if isinstance(data, dict) and isinstance(data.get("total"), int) else None,
+    }
+
+
+def search_raw(q=None, *, count=20, start=0, cache=None, no_cache=False):
+    """Flat-panel low-level face: q/count/start go through with verbatim names (filter_format=cma_case fixed).
+
+    → {rows[], count, limit_applied, total, params, _meta}. A missing q = full-register enumeration (2,591 live
+    cases counted 2026-10-29); count politeness wall 1-100 (upstream has no wall — count=1000 was verified to
+    deliver in full); start = offset paging."""
+    from ..transport import call_provider
+
+    term = str(q or "").strip() or None
+    size = int(count) if count is not None else 20  # explicit None check — 0 being swallowed by `or` was a same-type bug caught by a test
+    if not 1 <= size <= 100:
+        raise SdkError("usage_error", provider="gb_cma",
+                       detail=f"count must be 1-100 (politeness cap; upstream has no wall — verified 2026-10-29, count=1000 delivers in full), got \"{count}\"")
+    off = int(start) if start is not None else 0
+    if off < 0:
+        raise SdkError("usage_error", provider="gb_cma", detail=f"start must be an offset ≥0, got \"{start}\"")
+    params = {"filter_format": "cma_case", "count": size, "start": off}
+    if term:
+        params["q"] = term
+    r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    return {**cases_from_upstream(r["data"], size), "params": params, "_meta": r}
+
+
+def _clean_slug(slug):
+    s = str(slug or "").strip()
+    # Tolerance: a pasted full base_path (/cma-cases/<slug> or https://www.gov.uk/cma-cases/<slug>) gets its prefix stripped
+    for pre in ("https://www.gov.uk/cma-cases/", "http://www.gov.uk/cma-cases/", "/cma-cases/"):
+        if s.startswith(pre):
+            s = s[len(pre):]
+    s = s.strip("/")
+    if not s or "/" in s:
+        raise SdkError("usage_error", provider="gb_cma",
+                       detail=f"slug must be the case-page tail segment (e.g. nexfibre-slash-substantial-merger-inquiry, "
+                              f"echoed verbatim from the search row's link field): {slug}")
+    return s
+
+
+def case_raw(slug, *, cache=None, no_cache=False):
+    """→ the full single-case dossier (content API; content_id = the UUID stable key).
+    attachments = the decision/notice PDF family."""
+    from ..transport import call_provider
+
+    s = _clean_slug(slug)
+    r = call_provider(provider, "case", {"slug": s}, cache=cache, no_cache=no_cache)
+    x = r["data"] or {}
+    det = x.get("details") or {}
+    return {
+        "slug": s,
+        "content_id": x.get("content_id"),
+        "title": x.get("title"),
+        "description": x.get("description") or None,
+        "document_type": x.get("document_type"),
+        "first_published_at": x.get("first_published_at"),
+        "public_updated_at": x.get("public_updated_at"),
+        "updated_at": x.get("updated_at"),
+        "withdrawn": bool(x.get("withdrawn_notice")),
+        "change_history": det.get("change_history") or [],      # [{note, public_timestamp}] newest→oldest (last = First published)
+        "attachments": [{"title": a.get("title"), "url": a.get("url"),
+                         "content_type": a.get("content_type"), "content_id": a.get("content_id")}
+                        for a in (det.get("attachments") or [])],
+        "body_html": det.get("body") or "",                     # the case-page body HTML (investigation/decision summary)
+        "organisations": [o.get("title") for o in ((x.get("links") or {}).get("organisations") or [])
+                          if o.get("title")],
+        "url": f"https://www.gov.uk/cma-cases/{s}",
+        "_meta": r,
+    }

agentdata/legal/gb_tna_caselaw.py

@@ -0,0 +1,245 @@
+"""gb_tna_caselaw — UK National Archives caselaw library provider (caselaw.nationalarchives.gov.uk; keyless).
+
+The legal register's judgment line P0 (roadmapped 2026-10-29; born 0.3.8, ISO-prefixed 0.3.13, Englished in the
+0.3.14 collection round). Shapes verified by first-hand live probing 2026-10-29 (tmp/probe-tna/):
+GET /atom.xml?party=&judge=&court=&tribunal=&query=&order=&page=&per_page=&minimum_availability=
+  → Atom feed (official OpenAPI: the feed header's rel=service-desc links nationalarchives/ds-find-caselaw-docs)
+  — entries carry tna:uri (the machine-stable document URI) / tna:identifier (ukncn = the neutral-citation
+    human-readable key + fclid, a dual key) / tna:contenthash (body SHA256, cross-format change detection) /
+    author=name = the court name; link rel=last = total pages.
+  per_page defaults to 50 (polite tier 1-50); order enum ±date/±updated/±transformation;
+  court/tribunal are arrays with explode=true (repeated keys); minimum_availability enum metadata/document/full-text.
+GET /{document_uri}/data.xml → Akoma Ntoso (LegalDocML):
+  meta/proprietary = court/year/number/cite/caseNumber/hash; FRBRWork = FRBRname case name + FRBRdate handed-down date;
+  header/<party as="#claimant|#defendant" refersTo="#eId"> = the official party→role edge (companies + individuals);
+  judgmentBody = the body (~32k chars per document).
+Two document-URI generations coexist (per the official contract, never parse attributes out of the URI): before
+2025-04 court/year/seq (with slashes), after that d-<uuid>; identifiers additionally carry an fclid slug form
+(tna.xxxx) — all three forms are accepted by the judgment face.
+Rate: official 1000 req/rolling 5 min (≈3.3 rps) — polite tier 0.5 rps.
+**The licence gate (first case of keyless-but-licence)**: the Open Justice Licence allows commercial reuse and
+expressly forbids bulk computational analysis (free on application) — this face is directed search /
+single-document reading (rolling-monitor compliant); do not enumerate-harvest the corpus.
+TTL: search 24h (the feed drifts at daily cadence) / judgment 7 days (judgments are slow-moving; the contenthash
+detects text changes).
+"""
+import re
+import xml.etree.ElementTree as ET
+
+from ..errors import SdkError
+
+_ATOM = "{http://www.w3.org/2005/Atom}"
+_TNA = "{https://caselaw.nationalarchives.gov.uk}"
+_AKN = "{http://docs.oasis-open.org/legaldocml/ns/akn/3.0}"
+
+_ORDERS = ("date", "-date", "updated", "-updated", "transformation", "-transformation")
+_AVAILABILITY = ("metadata", "document", "full-text")
+
+provider = {
+    "id": "gb_tna_caselaw",
+    "baseUrl": "https://caselaw.nationalarchives.gov.uk",
+    "rate": {"rps": 0.5, "burst": 1},
+    "ops": {
+        "search": {"path": "/atom.xml", "accept": "text"},   # params: query/court/tribunal/party/judge/order/page/per_page/minimum_availability
+        "judgment": {"path": "/{document_uri}/data.xml", "accept": "text",
+                     "path_safe": "/"},                       # document_uri contains slashes (ewhc/admin/2026/2298) — keep / in path params
+    },
+    "ttl": {"search": 24 * 3600, "judgment": 7 * 86400},
+}
+
+
+def _as_list(v):
+    """court/tribunal explode arrays: a str is treated as a single element (a CLI --court repeat builds a list passed straight through)."""
+    if v is None:
+        return None
+    return v if isinstance(v, (list, tuple)) else [v]
+
+
+def entries_from_atom(text):
+    """Upstream Atom feed → judgment rows + feed-level ledger (pure function, offline-testable)."""
+    try:
+        root = ET.fromstring(text)
+    except ET.ParseError as e:
+        raise SdkError("upstream_error", provider="gb_tna_caselaw",
+                       detail=f"atom feed XML parse failed: {e}")
+    if root.tag != _ATOM + "feed":
+        raise SdkError("upstream_error", provider="gb_tna_caselaw",
+                       detail=f"unexpected root element {root.tag} (expected an Atom feed)")
+
+    def _page(href):
+        m = re.search(r"[?&]page=(\d+)", href or "")
+        return int(m.group(1)) if m else None
+
+    total_pages, feed_updated, license_url = None, None, None
+    for el in root:
+        if el.tag == _ATOM + "link" and el.get("rel") == "last":
+            total_pages = _page(el.get("href"))
+        elif el.tag == _ATOM + "updated":
+            feed_updated = (el.text or "").strip() or None
+        elif el.tag == _ATOM + "rights":
+            license_url = (el.text or "").strip() or None
+
+    rows = []
+    for e in root.findall(_ATOM + "entry"):
+        neutral_citation = fcid = None
+        for ident in e.findall(_TNA + "identifier"):
+            if ident.get("type") == "ukncn":
+                neutral_citation = (ident.text or "").strip() or None
+            elif ident.get("type") == "fclid":
+                fcid = (ident.text or "").strip() or None
+        links = {((l.get("rel") or ""), (l.get("type") or "")): l.get("href") for l in e.findall(_ATOM + "link")}
+        rows.append({
+            "uri": next((t.text.strip() for t in e.findall(_TNA + "uri") if t.text), None),
+            "neutral_citation": neutral_citation,          # ukncn human-readable official key ([2026] EWHC 2298 (Admin))
+            "fcid": fcid,                                   # Find Case Law Identifier (source of the tna.xxxx slug)
+            "title": (e.findtext(_ATOM + "title") or "").strip() or None,   # case name = the party string
+            "court": (e.findtext(_ATOM + "author/" + _ATOM + "name") or "").strip() or None,
+            "published": e.findtext(_ATOM + "published"),   # handed-down date
+            "updated": e.findtext(_ATOM + "updated"),       # XML last-updated (includes markup touch-ups)
+            "contenthash": next((t.text.strip() for t in e.findall(_TNA + "contenthash") if t.text), None),
+            "html_url": links.get(("alternate", "")),
+            "data_url": links.get(("alternate", "application/akn+xml")),
+            "pdf_url": links.get(("alternate", "application/pdf")),
+        })
+    return {"rows": rows, "count": len(rows), "total_pages": total_pages,
+            "feed_updated": feed_updated, "license": license_url}
+
+
+def search_raw(query=None, *, court=None, tribunal=None, party=None, judge=None,
+               order=None, page=1, per_page=50, minimum_availability=None,
+               cache=None, no_cache=False):
+    """Flat-panel plumbing: eight params under their upstream names, straight through (GET /atom.xml).
+
+    → {rows[], count, page, per_page, total_pages, feed_updated, params, _meta}.
+    party/judge = party/judge names with whole-word matching; court/tribunal = court codes (repeatable, explode);
+    query = full-text search; total_pages comes straight from the feed header's link rel=last.
+    The licence forbids bulk — a directed-search face."""
+    from ..transport import call_provider
+
+    params = {}
+    if query is not None and str(query).strip():
+        params["query"] = str(query).strip()
+    for k, v in (("party", party), ("judge", judge)):
+        if v is not None and str(v).strip():
+            params[k] = str(v).strip()
+    for k, v in (("court", _as_list(court)), ("tribunal", _as_list(tribunal))):
+        if v:
+            params[k] = [str(x).strip() for x in v if str(x).strip()]
+            if not params[k]:
+                del params[k]
+    if order is not None:
+        if order not in _ORDERS:
+            raise SdkError("usage_error", provider="gb_tna_caselaw",
+                           detail=f"order must be one of {'/'.join(_ORDERS)}, got {order!r}")
+        params["order"] = order
+    pg = int(page) if page is not None else 1
+    if pg < 1:
+        raise SdkError("usage_error", provider="gb_tna_caselaw", detail=f"page must be >=1, got {page!r}")
+    size = int(per_page) if per_page is not None else 50
+    if not 1 <= size <= 50:
+        raise SdkError("usage_error", provider="gb_tna_caselaw",
+                       detail=f"per_page must be 1-50 (polite tier = the upstream default page size; the licence "
+                              f"forbids bulk — do not pull larger pages), got {per_page!r}")
+    params["page"], params["per_page"] = pg, size
+    if minimum_availability is not None:
+        if minimum_availability not in _AVAILABILITY:
+            raise SdkError("usage_error", provider="gb_tna_caselaw",
+                           detail=f"minimum_availability must be one of {'/'.join(_AVAILABILITY)}, got "
+                                  f"{minimum_availability!r}")
+        params["minimum_availability"] = minimum_availability
+    r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    out = entries_from_atom(r["data"])
+    return {**out, "page": pg, "per_page": size, "params": params, "_meta": r}
+
+
+_URI_CHARS = re.compile(r"^[a-z0-9][a-z0-9/.\-]*$")
+
+
+def _clean_uri(document_uri):
+    s = str(document_uri or "").strip()
+    # tolerance: a pasted full URL (…/<uri> or …/<uri>/data.xml) is shelled; all three forms accepted —
+    # the tna.xxxx slug, the modern d-uuid, and the legacy court/year/seq
+    for pre in ("https://caselaw.nationalarchives.gov.uk/", "http://caselaw.nationalarchives.gov.uk/", "/"):
+        if s.startswith(pre):
+            s = s[len(pre):]
+    if s.endswith("/data.xml"):
+        s = s[: -len("/data.xml")]
+    s = s.strip("/")
+    if not s or not _URI_CHARS.match(s):
+        raise SdkError("usage_error", provider="gb_tna_caselaw",
+                       detail=f"document_uri must be a document URI (legacy ewhc/admin/2026/2298, modern d-<uuid>, "
+                              f"or tna.<fclid>; the search rows' uri/neutral_citation slugs carry them verbatim): "
+                              f"{document_uri}")
+    return s
+
+
+def _txt(el):
+    return " ".join((el.text or "").split()) if el is not None and el.text else None
+
+
+def judgment_from_akn(text):
+    """Akoma Ntoso data.xml → a single structured judgment dossier (pure function, offline-testable)."""
+    try:
+        root = ET.fromstring(text)
+    except ET.ParseError as e:
+        raise SdkError("upstream_error", provider="gb_tna_caselaw",
+                       detail=f"judgment XML parse failed: {e}")
+    j = root.find(_AKN + "judgment")   # an Element with no children is falsy — always test `is not None`, never an `or` chain
+    if j is None:
+        j = root.find(_AKN + "doc")
+    if j is None:
+        raise SdkError("upstream_error", provider="gb_tna_caselaw",
+                       detail=f"unexpected root structure (expected an Akoma Ntoso judgment, got {root.tag})")
+    prop = {}
+    p = j.find(_AKN + "meta/" + _AKN + "proprietary")
+    if p is not None:
+        for el in p:
+            tag = el.tag.split("}")[-1]
+            if tag in ("court", "year", "number", "cite", "caseNumber", "hash"):
+                prop[tag] = (el.text or "").strip() or None
+    frbr = j.find(_AKN + "meta/" + _AKN + "identification/" + _AKN + "FRBRWork")
+    name = date = frbr_uri = None
+    if frbr is not None:
+        n = frbr.find(_AKN + "FRBRname")          # the case name lives in the value attribute, not element text (Akn attribute-bearing convention)
+        name = n.get("value") if n is not None else None
+        d = frbr.find(_AKN + "FRBRdate")
+        date = d.get("date") if d is not None else None
+        this = frbr.find(_AKN + "FRBRthis")
+        frbr_uri = this.get("value") if this is not None else None
+    # the official party→role edge: header/<party as="#claimant" refersTo="#eId">NAME</party>
+    parties = []
+    hdr = j.find(_AKN + "header")
+    if hdr is not None:
+        for pty in hdr.iter(_AKN + "party"):
+            parties.append({"name": _txt(pty),
+                            "role": ((pty.get("as") or "").lstrip("#") or None)})
+    judges = []
+    for jd in (hdr.iter(_AKN + "judge") if hdr is not None else []):
+        nm = _txt(jd)
+        if nm and nm not in judges:
+            judges.append(nm)
+    body = j.find(_AKN + "judgmentBody")
+    text_out = " ".join(body.itertext()).strip() if body is not None else None
+    return {
+        "neutral_citation": prop.get("cite"),
+        "court_code": prop.get("court"),                    # EWHC-KBD-Admin (a proprietary code)
+        "case_number": prop.get("caseNumber"),              # docket number (e.g. AC-2024-LON-003318)
+        "title": name,                                      # FRBRname = the case name (the party string)
+        "date": date,                                       # FRBRdate = handed-down date
+        "judges": judges,
+        "parties": parties,                                 # [{name, role}] the official edge for company + individual parties
+        "contenthash": prop.get("hash"),
+        "frbr_uri": frbr_uri,                               # canonical document URI (id/ form)
+        "text": text_out,                                   # judgment body (plain-text extraction)
+        "text_length": len(text_out) if text_out else 0,
+    }
+
+
+def judgment_raw(document_uri, *, cache=None, no_cache=False):
+    """→ a single judgment's full dossier (Akoma Ntoso structured: citation/court/party-role edges/judges/body)."""
+    from ..transport import call_provider
+
+    s = _clean_uri(document_uri)
+    r = call_provider(provider, "judgment", {"document_uri": s}, cache=cache, no_cache=no_cache)
+    out = judgment_from_akn(r["data"])
+    return {"uri": s, "url": f"https://caselaw.nationalarchives.gov.uk/{s}", **out, "_meta": r}

agentdata/legal/idb.py

@@ -0,0 +1,85 @@
+"""idb — Inter-American Development Bank sanctioned-firms roster provider (data.iadb.org CKAN DataStore; keyless).
+
+legal debarment-roster face (0.3.21; admitted 2026-11-02, probed tmp/probe-debar-0321). Shape measured 2026-11-02:
+GET /api/action/datastore_search?resource_id=cd0bd9ac-18c6-44bc-8592-9be468c2efd9&… → CKAN envelope
+{result: {records[], total}} — **live total 1,343 rows** (the census-era 2,603 counted cumulative history; the
+live DataStore holds the current register). Rows carry 13 columns verbatim: _id / Title (firm or individual name) /
+Entity (Firm/Individual) / Nationality / Country (a **multi-country cell exists**: " Kenya, United Republic of
+Tanzania, Zambia" — and values carry leading spaces, trimmed at the mapping layer) / From~To (**"Ongoing" or a
+datetime**; From arrives as "2009-07-10 00:00:00.000000000" nanosecond text, kept verbatim) / Prohibited Practice
+("Fraud, Extortion" — the violation family) / Source (**"IDB" or the cross-debarment marker "ADB cross debarment"
+/ "WBG cross debarment"**) / "Tipo de sancion del BID" (Spanish column = the sanction type, "Debarment") /
+IDB Sanction Source (SCOM = Sanctions Committee) / Other Name.
+Query semantics (verified live 2026-11-02): q = full-text across all fields (returns a rank); filters = JSON
+field→value **exact** match (e.g. {"To": "Ongoing"}); sort = "From desc" style; offset paging; include_total=true
+echoes the exact total. The plain agentdata UA passes (no UA gate).
+TTL: 24h; polite tier 0.5 rps (conservative pick; the CKAN publishes no quota).
+"""
+import json
+
+from ..errors import SdkError
+
+provider = {
+    "id": "idb",
+    "baseUrl": "https://data.iadb.org",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "debarred": {"path": "/api/action/datastore_search", "timeoutMs": 30000},
+    },
+    "ttl": {"debarred": 24 * 3600},
+}
+
+_RESOURCE_ID = "cd0bd9ac-18c6-44bc-8592-9be468c2efd9"  # the "Dataset of Sanctioned firms and individuals" resource
+
+
+def rows_from_upstream(data):
+    """CKAN result → sanction rows (pure function; the 13 upstream columns verbatim, string values trimmed —
+    the register ships leading spaces in Country/Prohibited Practice, measured 2026-11-02)."""
+    result = (data or {}).get("result") or {}
+    rows = []
+    for r in result.get("records") or []:
+        row = {}
+        for k, v in r.items():
+            row[k] = v.strip() if isinstance(v, str) else v
+        rows.append(row)
+    return rows, result.get("total")
+
+
+def debarred_entities_raw(q=None, *, filters=None, limit=20, offset=0, sort=None, cache=None, no_cache=False):
+    """→ {rows, total, limit_applied, offset, params, _meta} (server-side search; include_total=true always sent).
+
+    q = full-text across all fields (upstream param verbatim); filters = JSON field→value exact-match dict in
+    JSON text form (upstream param verbatim — {"To": "Ongoing"}, {"Entity": "Firm"}); limit 1-100 politeness
+    cap; offset paging; sort = "From desc" style (upstream param verbatim)."""
+    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="idb",
+                       detail=f"limit must be 1-100 (politeness cap), got '{limit}'")
+    off = int(offset) if offset is not None else 0
+    if off < 0:
+        raise SdkError("usage_error", provider="idb", detail=f"offset must be ≥0, got '{offset}'")
+    if isinstance(filters, str):  # the CLI face hands us JSON text — normalize to the dict channel
+        try:
+            filters = json.loads(filters) if filters.strip() else None
+        except ValueError:
+            raise SdkError("usage_error", provider="idb",
+                           detail="filters must be a JSON object of field→value exact matches, "
+                                  'e.g. \'{"To": "Ongoing"}\'')
+    if filters is not None and not isinstance(filters, dict):
+        raise SdkError("usage_error", provider="idb",
+                       detail="filters must be dict-shaped (field→value exact match), e.g. {\"Entity\": \"Firm\"}")
+    qq = str(q or "").strip() or None
+    ss = str(sort or "").strip() or None
+    params = {"resource_id": _RESOURCE_ID, "limit": size, "offset": off, "include_total": "true"}
+    if qq:
+        params["q"] = qq
+    if filters:
+        params["filters"] = json.dumps(filters, ensure_ascii=False)
+    if ss:
+        params["sort"] = ss
+    r = call_provider(provider, "debarred", params, cache=cache, no_cache=no_cache)
+    rows, total = rows_from_upstream(r["data"])
+    return {"rows": rows, "total": total, "limit_applied": size, "offset": off,
+            "params": params, "_meta": r}