agentdata 0.3.26__py3-none-any.whl

agentdata/company/fdic_bankfind.py

@@ -0,0 +1,107 @@
+"""fdic_bankfind — FDIC BankFind Suite (US insured-bank institution master lookup; keyless).
+
+Keyless at roughly ~1,000 req/hr/IP — we set 0.25 rps/burst 5, same tier as usaspending.
+Live-shape check: **the host has moved to api.fdic.gov** (banks.data.fdic.gov 301) — new home /banks/institutions;
+response data[].data.{NAME,CERT,CITY,STALP,ACTIVE,ID} (double-layered data).
+Field-value findings confirmed by probing (2026-10-21): null fields are omitted upstream (absence = null, not
+distinguishable); operating rows carry the ENDEFYMD='12/31/9999' sentinel (a flat export stamps every live row with a
+9999 end date) → null; the end-date sense covers closure/de-insurance/M&A exits (SVB 24735=03/10/2023).
+Financials are not here (the fdic-edos corpus line already covers them); this face only answers "which bank is this,
+is it still alive" against the master current values.
+"""
+import re
+
+provider = {
+    "id": "fdic-bankfind",
+    "baseUrl": "https://api.fdic.gov",
+    "rate": {"rps": 0.25, "burst": 5},
+    "ops": {
+        "institutions": {"path": "/banks/institutions"},  # params: search / filters / fields / limit (assembled query)
+    },
+    "ttl": {"institutions": 30 * 86400},  # registry master changes slowly
+}
+
+FIELDS = "NAME,CERT,CITY,STALP,ACTIVE,REPDTE,ESTYMD,ENDEFYMD"
+
+MDY_RE = re.compile(r"^\d{2}/\d{2}/\d{4}$")
+# active sentinel: a flat export stamps every live row with a 9999 end date
+ACTIVE_SENTINEL = "12/31/9999"
+
+
+def mdy_to_iso(v):
+    """'MM/DD/YYYY'→'YYYY-MM-DD' (MDY strings are easy to misread across regions; other shapes are returned unchanged)."""
+    if isinstance(v, str):
+        s = v.strip()
+        if MDY_RE.match(s):
+            return f"{s[6:10]}-{s[0:2]}-{s[3:5]}"
+    return v if v is not None else None
+
+
+def institution_from_upstream(d):
+    """Institution card pure mapping (split out for offline testing; upstream omits null fields — absence = null, not
+    distinguishable; the ENDEFYMD sentinel '12/31/9999' = operating → null, only a real end date lands a value)."""
+    end = d.get("ENDEFYMD") if d.get("ENDEFYMD") and d.get("ENDEFYMD") != ACTIVE_SENTINEL else None
+    active = d.get("ACTIVE")
+    return {
+        "cert": d.get("CERT"),
+        "name": d.get("NAME"),
+        "city": d.get("CITY"),
+        "state": d.get("STALP"),
+        "active": True if active == 1 else False if active == 0 else None,
+        "established_date": mdy_to_iso(d.get("ESTYMD")),   # opening date
+        "end_date": mdy_to_iso(end),                       # end of the insurance relationship (null while operating)
+        "report_date": mdy_to_iso(d.get("REPDTE")),        # master current-value reporting period
+    }
+
+
+def find_bank(*, name=None, cert=None, limit=5, cache=None, no_cache=False):
+    """→ {total, institutions[{cert,name,city,state,active,established_date,end_date,report_date}], _meta}.
+    Name fuzzy (ES phrase form) or CERT exact — exactly one of the two; active semantics 1=operating, 0=closed."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    params = {"fields": FIELDS, "limit": min(max(1, int(limit) or 5), 50)}
+    if cert is not None and str(cert).strip() != "":
+        try:
+            params["filters"] = f"CERT:{int(str(cert).strip())}"  # CERT exact
+        except ValueError:
+            raise SdkError("usage_error", provider="fdic-bankfind",
+                           detail=f"CERT must be numeric: {cert}")
+    elif name:
+        q = str(name).strip()
+        if not q:
+            raise SdkError("usage_error", provider="fdic-bankfind", detail="findBank requires either --name or --cert")
+        params["search"] = f'NAME:"{q}"'  # ES phrase-form name match
+    else:
+        raise SdkError("usage_error", provider="fdic-bankfind", detail="findBank requires either --name or --cert")
+    r = call_provider(provider, "institutions", params, cache=cache, no_cache=no_cache)
+    rows = [institution_from_upstream(e.get("data") or {})
+            for e in (r["data"] or {}).get("data") or []]
+    total = (r["data"] or {}).get("meta", {}).get("total")
+    return {"total": total if total is not None else len(rows), "institutions": rows, "_meta": r}
+
+
+def institutions_raw(*, search=None, filters=None, fields=None, limit=5,
+                     cache=None, no_cache=False):
+    """→ {total, institutions[], params, _meta}; search/filters pass through with upstream names (combinable — ES full text × structured filter).
+    limit has no upstream wall: measured 2026-10-23, 1001 really returns 1001 rows and 10000 really returns 10000 rows
+    (whole database 27,835); the old find_bank 50 cap is this repo's politeness tier, not an upstream limit. fields defaults to
+    the eight FIELDS columns and can be overridden with a comma-separated string.
+    Zero hits is a legal empty set (no raise — the find_bank CERT face carries its own semantics at the client layer)."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    lim = int(limit)
+    if lim < 1:
+        raise SdkError("usage_error", provider="fdic-bankfind", detail="limit must be ≥1")
+    params = {"fields": str(fields).strip() if fields else FIELDS, "limit": lim}
+    if search:
+        params["search"] = str(search)
+    if filters:
+        params["filters"] = str(filters)
+    r = call_provider(provider, "institutions", params, cache=cache, no_cache=no_cache)
+    rows = [institution_from_upstream(e.get("data") or {})
+            for e in (r["data"] or {}).get("data") or []]
+    total = (r["data"] or {}).get("meta", {}).get("total")
+    return {"total": total if total is not None else len(rows), "institutions": rows,
+            "params": params, "_meta": r}

agentdata/company/fi_ytj.py

@@ -0,0 +1,89 @@
+"""fi_ytj — Finnish PRH YTJ business information system v3 (avoindata open API front door; keyless).
+
+2026-10-29 probed shape: GET /companies?name=|businessId= (one endpoint, two lookup shapes);
+name is a contains-match that also hits historical names and secondary names (nokia hits the branch name Fysios Nokia);
+**pagination params are ignored upstream — resultsFrom/maxResults silently have no effect (p63/p200 measured
+byte-identical), page size is always ~63 rows, and totalResults is the real total** — so large name families cannot be
+fetched in full; narrow with a more precise name or a businessId direct lookup.
+Row shape: businessId is a nested object {value, registrationDate, source}; names[] = versioned name history
+(type 1 main name / 3 branch name); mainBusinessLine/companyForms/companySituations carry fi/sv/en
+descriptions (languageCode 1=fi 2=sv 3=en).
+TTL: 7 days (registry current values); politeness tier 0.5 rps (no published quota).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "fi_ytj",
+    "baseUrl": "https://avoindata.prh.fi/opendata-ytj-api/v3",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "companies": {"path": "/companies"},   # params: name | businessId (query; pagination params are not upstream, not exposed)
+    },
+    "ttl": {"companies": 7 * 86400},
+}
+
+
+def _desc(trilingual):
+    """[{languageCode, description}] → joined en/fi string (languageCode 3=en 1=fi; sv dropped — projection to reduce noise)."""
+    by = {d.get("languageCode"): d.get("description") for d in trilingual or []}
+    parts = [by.get(c) for c in ("3", "1")]
+    return " / ".join(x for x in parts if x) or None
+
+
+def search_companies(name=None, business_id=None, *, cache=None, no_cache=False):
+    """→ {total_results, companies[], params, _meta}; name search XOR businessId direct lookup (one endpoint, two lookup shapes).
+    name also matches historical/branch names by contains; **page size is always ~63 rows (pagination params are silently
+    ignored upstream, pinned by measurement), total_results is the real total — large families must be narrowed with a more
+    precise name or a businessId**."""
+    from ..transport import call_provider
+
+    nm = str(name or "").strip() or None
+    bid = str(business_id or "").replace(" ", "").strip() or None
+    if bool(nm) == bool(bid):
+        raise SdkError("usage_error", provider="fi_ytj",
+                       detail="name (search face) and business_id (direct lookup face) are mutually exclusive — provide exactly one of the two required")
+    params = {"name": nm, "businessId": bid}
+    r = call_provider(provider, "companies", params, cache=cache, no_cache=no_cache)
+    d = r["data"] or {}
+    return {"total_results": d.get("totalResults"),
+            "companies": [_norm(c) for c in d.get("companies") or []],
+            "params": {k: v for k, v in params.items() if v}, "_meta": r}
+
+
+def _norm(c):
+    """Row projection: businessId split out of its nested object; full name history kept; trilingual fields joined en/fi; address takes the first row."""
+    bid = c.get("businessId") or {}
+    addr0 = (c.get("addresses") or [{}])[0] or {}
+    city = None
+    for po in addr0.get("postOffices") or []:
+        if po.get("languageCode") in ("1", "3"):  # fi or en city name
+            city = po.get("city")
+            if po.get("languageCode") == "3":
+                break
+    return {
+        "business_id": bid.get("value"),                # 0194099-3 shape (value split from the nested object)
+        "business_id_registration_date": bid.get("registrationDate"),
+        "latest_name": ((c.get("names") or [{}])[0]).get("name"),   # names[0] = most recent row (upstream order)
+        "names": [{"name": n.get("name"), "type": n.get("type"),          # full history (1 main name / 3 branch name)
+                   "registration_date": n.get("registrationDate"), "end_date": n.get("endDate"),
+                   "version": n.get("version")} for n in c.get("names") or []],
+        "main_business_line": {"code": (c.get("mainBusinessLine") or {}).get("type"),
+                               "description": _desc((c.get("mainBusinessLine") or {}).get("descriptions")),
+                               "codeset": (c.get("mainBusinessLine") or {}).get("typeCodeSet")},  # TOIMI4
+        "company_forms": [{"type": f.get("type"), "description": _desc(f.get("descriptions")),
+                           "start_date": f.get("startDate"), "end_date": f.get("endDate")}
+                          for f in c.get("companyForms") or []],
+        "company_situations": [{"description": _desc(s.get("descriptions")),
+                                "start_date": s.get("startDate"), "end_date": s.get("endDate")}
+                               for s in c.get("companySituations") or []],
+        "status": c.get("status"),                       # upstream numeric code (2 = registered/live is the common value)
+        "trade_register_status": c.get("tradeRegisterStatus"),
+        "registration_date": c.get("registrationDate"),
+        "end_date": c.get("endDate"),
+        "last_modified": c.get("lastModified"),
+        "address": {"street": addr0.get("street"), "building_number": addr0.get("buildingNumber"),
+                    "post_code": addr0.get("postCode"), "city": city},
+        "registered_entries": [{"type": e.get("type"), "description": _desc(e.get("descriptions")),
+                                "registration_date": e.get("registrationDate"), "end_date": e.get("endDate")}
+                               for e in c.get("registeredEntries") or []],   # commercial register entry history
+    }

agentdata/company/fr_recherche.py

@@ -0,0 +1,124 @@
+"""fr_recherche — French annuaire-entreprises official aggregate search (recherche-entreprises.api.gouv.fr; etalab/DINUM, keyless).
+
+2026-10-29 probed shape: GET /search?q=&page=&per_page=&etat_administratif=
+(the API behind the etalab annuaire-entreprises search engine — api.insee.fr needs a key, this face is the keyless
+search front door).
+q takes company name / officer name / SIREN alike (BERNARD DE SAINT AFFRIQUE → 37 companies with mandates;
+q=552032534 → total 1 exact); **per_page has an explicit wall of 1-25** (default 10; beyond it the upstream answers with a
+self-describing French erreur — the local precheck saves one request); pagination is closed-form
+page+total_pages+total_results. Rows are a rich 30-key shape: dirigeants with two slots (physique = person name +
+year-month-granularity birth date; morale = {siren,denomination} company×company director edges)
++ finances{year:{ca,resultat_net}} + tva + siren_conserve (predecessor key) + complements (est_* flag family).
+Rate limiting is real: burst-style 429s with plain-text bodies and intermittent connection resets — backing off gets
+through, politeness tier 0.5 rps. TTL: 7 days (registry current values; date_mise_a_jour measured updating at T-1).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "fr_recherche",
+    "baseUrl": "https://recherche-entreprises.api.gouv.fr",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "search": {"path": "/search"},   # params: q/page/per_page/etat_administratif (A active / C ceased)
+    },
+    "ttl": {"search": 7 * 86400},
+}
+
+
+def search(q, *, page=None, per_page=10, etat_administratif=None, cache=None, no_cache=False):
+    """→ {total_results, total_pages, page, per_page, results[], params, _meta}.
+    q takes company name / officer name / SIREN alike (officer name = cross-company mandate search, SIREN = exact direct
+    lookup); per_page upstream hard wall 1-25 (default 10, prechecked locally); etat_administratif A/C is a true filter.
+    Zero hits is a legal answer (total_results:0)."""
+    from ..transport import call_provider
+
+    q = str(q or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="fr_recherche",
+                       detail="search requires q (company name / officer name / SIREN)")
+    pp = int(per_page if per_page is not None else 10)
+    if not 1 <= pp <= 25:
+        raise SdkError("usage_error", provider="fr_recherche",
+                       detail=f"per_page upstream hard wall is 1-25 (got {pp}; default 10 — beyond the wall upstream answers with a French erreur)")
+    params = {"q": q, "per_page": pp}
+    if page is not None:
+        pg = int(page)
+        if pg < 1:
+            raise SdkError("usage_error", provider="fr_recherche",
+                           detail=f"page is 1-based (got {pg})")
+        params["page"] = pg
+    if etat_administratif is not None:
+        ea = str(etat_administratif).strip().upper()
+        if ea not in ("A", "C"):
+            raise SdkError("usage_error", provider="fr_recherche",
+                           detail=f"etat_administratif only accepts A (active) / C (ceased), got \"{etat_administratif}\"")
+        params["etat_administratif"] = ea
+    r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    d = r["data"] or {}
+    return {"total_results": d.get("total_results"),
+            "total_pages": d.get("total_pages"),
+            "page": d.get("page"), "per_page": d.get("per_page"),
+            "results": [_norm(x) for x in d.get("results") or []],
+            "params": params, "_meta": r}
+
+
+def _norm_dir(d):
+    """dirigeants two slots: physique = person name + year-month-granularity birth date (public registry sense, no national
+    id number); morale = siren+denomination (company×company director edge; the statutory auditor slot has the same shape)."""
+    return {"type_dirigeant": d.get("type_dirigeant"),
+            "nom": d.get("nom"), "prenoms": d.get("prenoms"),
+            "date_de_naissance": d.get("date_de_naissance"),   # year-month granularity ("1964-12")
+            "annee_de_naissance": d.get("annee_de_naissance"),
+            "nationalite": d.get("nationalite"),
+            "siren": d.get("siren"),                           # morale slot only
+            "denomination": d.get("denomination"),
+            "qualite": d.get("qualite")}
+
+
+def _norm_etab(e):
+    """etablissement card (shared by siege/matching_etablissements): keeps the master/geographic/activity core columns."""
+    e = e or {}
+    return {"siret": e.get("siret"), "est_siege": e.get("est_siege"),
+            "ancien_siege": e.get("ancien_siege"),
+            "etat_administratif": e.get("etat_administratif"),
+            "adresse": e.get("adresse"), "code_postal": e.get("code_postal"),
+            "libelle_commune": e.get("libelle_commune"), "departement": e.get("departement"),
+            "region": e.get("region"), "latitude": e.get("latitude"), "longitude": e.get("longitude"),
+            "nom_commercial": e.get("nom_commercial"), "liste_enseignes": e.get("liste_enseignes"),
+            "activite_principale": e.get("activite_principale"),
+            "date_creation": e.get("date_creation"),
+            "date_debut_activite": e.get("date_debut_activite"),
+            "date_fermeture": e.get("date_fermeture")}
+
+
+def _norm(r):
+    """Row projection, 30 keys: SIREN primary key + dirigeants two slots + finances yearly panel + tva + siren_conserve predecessor key."""
+    fin = r.get("finances") or {}
+    return {
+        "siren": r.get("siren"),
+        "nom_complet": r.get("nom_complet"), "nom_raison_sociale": r.get("nom_raison_sociale"),
+        "sigle": r.get("sigle"),
+        "etat_administratif": r.get("etat_administratif"),   # A active / C ceased
+        "date_creation": r.get("date_creation"), "date_fermeture": r.get("date_fermeture"),
+        "nature_juridique": r.get("nature_juridique"),       # legal form code (5599=SA)
+        "categorie_entreprise": r.get("categorie_entreprise"),          # PME/ETI/GE
+        "annee_categorie_entreprise": r.get("annee_categorie_entreprise"),
+        "tranche_effectif_salarie": r.get("tranche_effectif_salarie"),
+        "caractere_employeur": r.get("caractere_employeur"),
+        "activite_principale": r.get("activite_principale"),           # NAF code
+        "activite_principale_naf25": r.get("activite_principale_naf25"),
+        "section_activite_principale": r.get("section_activite_principale"),
+        "tva": (r.get("tva") or [None])[0],                  # "FR…" (the monthly corpus file lacks this column)
+        "dirigeants": [_norm_dir(x) for x in r.get("dirigeants") or []],
+        "finances": {y: {"ca": v.get("ca"), "resultat_net": v.get("resultat_net")}
+                     for y, v in fin.items()},               # {year:{ca,resultat_net}}
+        "siege": _norm_etab(r.get("siege")),
+        "siren_conserve": r.get("siren_conserve"),           # predecessor SIREN (surviving key after a merger)
+        "nombre_etablissements": r.get("nombre_etablissements"),
+        "nombre_etablissements_ouverts": r.get("nombre_etablissements_ouverts"),
+        "matching_etablissements": [_norm_etab(x) for x in r.get("matching_etablissements") or []],
+        "complements": r.get("complements"),                 # est_* flag family + liste_finess etc. (passed through)
+        "statut_diffusion": r.get("statut_diffusion"),       # O=public / P=partially protected (name and address redacted)
+        "date_mise_a_jour": r.get("date_mise_a_jour"),
+        "date_mise_a_jour_rne": r.get("date_mise_a_jour_rne"),
+    }

agentdata/company/fts.py

@@ -0,0 +1,121 @@
+"""fts — UK Find a Tender Service OCDS provider (UK public procurement; keyless).
+
+GET /api/1.0/ocdsReleasePackages → OCDS 1.1 release package: releases[] (stable ocid key /
+buyer.name / awards[].suppliers[{id=GB-FTS-…, name}] / tag / date) + links.next cursor pagination.
+Closed parameter set (400 enumerates them): stages, limit, cursor, updatedFrom, updatedTo — no name-search
+param exists: name filtering is a client-side contains match (same sense as the lda client_name filter),
+pagination continues via cursor.
+Date pitfall: updatedFrom/updatedTo require full ISO timestamps ('2026-10-22T00:00:00Z' — bare dates 400);
+a single end may be omitted (the server auto-fills now) — norm_win() appends the T timestamp to bare dates.
+Note: the old direct Contracts Finder face (www/api.contractsfinder.service.gov.uk) now 404s/000s — CF has
+merged into the FTS platform, and the OCP mirror is the historical backfill line; this provider only serves the live face. TTL: 24h.
+"""
+import re
+from urllib.parse import urlparse, parse_qs
+
+from ..errors import SdkError
+
+provider = {
+    "id": "fts",
+    "baseUrl": "https://www.find-tender.service.gov.uk/api/1.0",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "releases": {"path": "/ocdsReleasePackages", "ttl": 24 * 3600, "timeoutMs": 30000},
+    },
+    "ttl": {"releases": 24 * 3600},
+}
+
+_BARE_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def norm_win(v, from_=True):
+    """Bare date '2026-10-01' → '2026-10-01T00:00:00Z' (the to end gets 23:59:59); full timestamps pass through."""
+    s = str(v or "").strip()
+    if not s:
+        return None
+    if _BARE_DATE.match(s):
+        return f"{s}T{'00:00:00' if from_ else '23:59:59'}Z"
+    return s
+
+
+def fts_from_upstream(data, name="", limit=10):
+    """Upstream payload → {rows, next_cursor, has_more} (pure function + client-side name filter, offline-testable).
+    Match face: buyer.name ∨ awards[].suppliers[].name (a hit on either the buyer or supplier side keeps the row);
+    has_more = upstream has a next page (decoupled from the client-side filter — a filtered page that isn't full ≠ no more
+    matches; continue with next_cursor)."""
+    q = str(name or "").lower().strip()
+    hit = (lambda s: not q or q in str(s or "").lower())
+
+    def keep(rel):
+        if hit((rel or {}).get("buyer", {}).get("name")):
+            return True
+        return any(hit(sp.get("name")) for aw in (rel or {}).get("awards") or []
+                   for sp in (aw or {}).get("suppliers") or [])
+
+    rows = []
+    for rel in [x for x in (data or {}).get("releases") or [] if keep(x)][:limit]:
+        rows.append({
+            "ocid": rel.get("ocid"),                                  # OCDS stable key (ocds-h6vhtk-…)
+            "date": rel.get("date"),
+            "tags": rel.get("tag") or [],
+            "buyer": (rel.get("buyer") or {}).get("name"),
+            "suppliers": sorted({sp.get("name") for aw in rel.get("awards") or []
+                                 for sp in aw.get("suppliers") or [] if sp.get("name")}),
+            "supplier_ids": sorted({sp.get("id") for aw in rel.get("awards") or []
+                                    for sp in aw.get("suppliers") or [] if sp.get("id")}),  # GB-FTS-… registry key
+            "award_values": [{"date": aw.get("date"), "amount": (aw.get("value") or {}).get("amount"),
+                              "currency": (aw.get("value") or {}).get("currency")}
+                             for aw in rel.get("awards") or [] if (aw.get("value") or {}).get("amount") is not None],
+            "tender_title": (rel.get("tender") or {}).get("title"),
+        })
+    nxt = (data or {}).get("links", {}).get("next")
+    cursor = (parse_qs(urlparse(nxt).query).get("cursor") or [None])[0] if nxt else None
+    return {"rows": rows, "next_cursor": cursor, "has_more": bool(nxt)}
+
+
+def company_uk_tenders(name, *, stages="award", limit=10, cursor=None,
+                       updated_from=None, updated_to=None, cache=None, no_cache=False):
+    """→ {rows, next_cursor, has_more, matched_on, _meta}; UK procurement release rows (client-side contains match)."""
+    from ..transport import call_provider
+
+    q = str(name or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="fts",
+                       detail="name is required (the OCDS face has no name-search param — client-side contains match)")
+    lim = min(max(1, int(limit) or 10), 100)
+    # Fetch strategy: always fetch the full 100-row page (upstream cap) then filter and slice to lim — fetching the
+    # original page at lim then filtering is almost guaranteed to come up empty (measured before f5c4f6c)
+    p = {"stages": str(stages or "award"), "limit": 100}
+    if cursor:
+        p["cursor"] = str(cursor)
+    wf, wt = norm_win(updated_from, True), norm_win(updated_to, False)
+    if wf:
+        p["updatedFrom"] = wf
+    if wt:
+        p["updatedTo"] = wt
+    r = call_provider(provider, "releases", p, cache=cache, no_cache=no_cache)
+    return {**fts_from_upstream(r["data"], q, lim), "matched_on": "buyer|suppliers contains", "_meta": r}
+
+
+def releases_raw(*, stages=None, limit=10, cursor=None, updated_from=None, updated_to=None,
+                 cache=None, no_cache=False):
+    """→ {rows, next_cursor, has_more, params, _meta}; the five OCDS params pass through verbatim (no name filter — upstream has no such param).
+    limit 1-100 (upstream page cap — the name-filter line's "always fetch the full 100" is this number); updatedFrom/updatedTo
+    get the T timestamp appended to bare dates (bare 400 is empirically proven, same as norm_win). Name-contains filtering is a
+    client-layer convenience (uk_fts_tenders name)."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    lim = int(limit)
+    if not 1 <= lim <= 100:
+        raise SdkError("usage_error", provider="fts", detail="limit must be 1-100 (upstream page cap)")
+    params = {"stages": str(stages or "award"), "limit": lim}
+    if cursor:
+        params["cursor"] = str(cursor)
+    wf, wt = norm_win(updated_from, True), norm_win(updated_to, False)
+    if wf:
+        params["updatedFrom"] = wf
+    if wt:
+        params["updatedTo"] = wt
+    r = call_provider(provider, "releases", params, cache=cache, no_cache=no_cache)
+    return {**fts_from_upstream(r["data"], "", lim), "params": params, "_meta": r}

agentdata/company/gleif.py

@@ -0,0 +1,178 @@
+"""gleif — GLEIF LEI API (LEI → entity identity card normalization + reverse name search + parent-company control chain; keyless).
+
+Politeness tier 1 rps/burst 2; TTL: lookup/search 7 days, parents 30 days (ownership chains change infrequently).
+Positioning boundary: exact LEI normalization — an LEI in, an entity identity card out; reverse name search is a
+legal-name contains match (not fuzzy tolerance), and candidates are not an authoritative normalization.
+2026-10-21: parents moved to the dedicated endpoints /lei-records/{lei}/direct-parent|ultimate-parent
+(each returns the full parent card; no parent → 404) — the old include= route, when a firm self-reports "no parent",
+pointed relationships at reporting-exceptions and the exception id got laid into the result as if it were an LEI;
+the dedicated endpoints are naturally honest nulls and the N+1 follow-up lookups disappeared.
+2026-10-30 param-fidelity round (0 new faces): search gains jurisdiction/status/page_number passthrough
+(filter[entity.jurisdiction] country-or-region / filter[entity.status] ACTIVE-INACTIVE-NULL / page[number]
+walking, bounded by meta.pagination.lastPage) and candidate rows surface registered_as (the cross-registry
+join key); the lookup card surfaces bic/mic, legal_form{elf,other}, expiration{date,reason} and
+successor_entities (LEI list — the M&A successor edge).
+"""
+import re
+
+provider = {
+    "id": "gleif",
+    "baseUrl": "https://api.gleif.org/api/v1",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "lookup": {"path": "/lei-records/{lei}", "notFound": [404]},   # params: lei (path template)
+        "search": {"path": "/lei-records"},                            # params: name, limit, jurisdiction, status, page_number (query assembled as filter[entity.legalName]/page[size]/filter[entity.jurisdiction]/filter[entity.status]/page[number])
+        "direct_parent": {"path": "/lei-records/{lei}/direct-parent", "notFound": [404]},     # dedicated endpoint returns the full parent card; 404 = none
+        "ultimate_parent": {"path": "/lei-records/{lei}/ultimate-parent", "notFound": [404]}, # same (ultimate sense)
+    },
+    "ttl": {"lookup": 7 * 86400, "search": 7 * 86400, "direct_parent": 30 * 86400, "ultimate_parent": 30 * 86400},
+}
+
+LEI_RE = re.compile(r"^[A-Z0-9]{20}$")
+
+
+def lookup_lei(lei: str, cache=None, no_cache: bool = False) -> dict:
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    norm = str(lei).strip().upper()
+    if not LEI_RE.match(norm):
+        raise SdkError("usage_error", provider="gleif",
+                       detail=f"invalid LEI shape (ISO 17442: 20 alphanumeric chars): {lei}")
+    r = call_provider(provider, "lookup", {"lei": norm}, cache=cache, no_cache=no_cache)
+    a = ((r["data"] or {}).get("data") or {}).get("attributes") or {}
+    ent, reg = a.get("entity") or {}, a.get("registration") or {}
+    creation = ent.get("creationDate")
+    return {
+        "lei": a.get("lei") or norm,
+        "legal_name": (ent.get("legalName") or {}).get("name"),
+        "name_language": (ent.get("legalName") or {}).get("language"),
+        "entity_status": ent.get("status"),
+        "jurisdiction": ent.get("jurisdiction"),
+        "registration_country": (ent.get("legalAddress") or {}).get("country"),
+        "hq_country": (ent.get("headquartersAddress") or {}).get("country"),
+        "hq_city": (ent.get("headquartersAddress") or {}).get("city"),
+        "bic": a.get("bic"),   # BIC/MIC are top-level record attributes (null unless the LOU captured them)
+        "mic": a.get("mic"),
+        "entity_category": ent.get("category"),
+        "legal_form": {"id": (ent.get("legalForm") or {}).get("id"),        # GLEIF ELF code (e.g. 8888)
+                       "other": (ent.get("legalForm") or {}).get("other")},  # raw local legal-form text (e.g. CREDIT_UNION)
+        "creation_date": creation[:10] if creation else None,
+        "expiration": {"date": (ent.get("expiration") or {}).get("date"),
+                       "reason": (ent.get("expiration") or {}).get("reason")},
+        # successor LEIs (the M&A successor edge); upstream names are null in practice — resolve each via lookup_lei
+        "successor_entities": [s.get("lei") for s in (ent.get("successorEntities") or []) if (s or {}).get("lei")],
+        "registration": {
+            "status": reg.get("status"),  # ISSUED / LAPSED / RETIRED… (issuance sense)
+            "last_update": reg.get("lastUpdateDate"),  # upstream key lastUpdateDate (2026-10-21: the old read of lastUpdate was permanently null)
+            "next_renewal_date": reg.get("nextRenewalDate"),
+            "registrar_id": (ent.get("registeredAt") or {}).get("id"),
+            "registered_as": ent.get("registeredAs"),
+        },
+        "_meta": r,
+    }
+
+
+def search_lei_by_name(name, *, jurisdiction=None, status=None, page_number=None, limit=10, cache=None, no_cache=False):
+    """→ {total, page, candidates[], _meta}; name → LEI reverse search. Legal-name contains match, not fuzzy tolerance —
+    candidates are not an authoritative normalization; re-verify with lookup_lei before persisting.
+    2026-10-30 param-fidelity round: jurisdiction (filter[entity.jurisdiction] — ISO 3166-1 country or
+    ISO 3166-2 region code: CH→14 Nestlé hits, US-MO→1 hit = Nestlé Purina registeredAs=00007498; the sibling
+    filter[entity.jurisdictionCountry] is whole-filter whitelist-rejected 400, do not mirror it), status
+    (filter[entity.status] — ACTIVE/INACTIVE/NULL, entity lifecycle; LAPSED lives in registration.status, a
+    different field), page_number (page[number], 1-based — walk while page <= meta.pagination.lastPage)."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    q = str(name or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="gleif", detail="search requires --name")
+    params = {
+        "filter[entity.legalName]": q,
+        "page[size]": min(max(1, int(limit) or 10), 200),  # real upstream limit 200 (probed: 201→400, 200 served in full; the earlier 100 clamp was a misrecord)
+    }
+    if jurisdiction is not None and str(jurisdiction).strip():
+        params["filter[entity.jurisdiction]"] = str(jurisdiction).strip().upper()
+    if status is not None and str(status).strip():
+        params["filter[entity.status]"] = str(status).strip().upper()
+    if page_number is not None:
+        if int(page_number) < 1:
+            raise SdkError("usage_error", provider="gleif", detail="page_number is 1-based (upstream page[number])")
+        params["page[number]"] = int(page_number)
+    r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    rows = [{
+        "lei": (e.get("attributes") or {}).get("lei") or e.get("id"),
+        "legal_name": ((e.get("attributes") or {}).get("entity") or {}).get("legalName", {}).get("name"),
+        "entity_status": ((e.get("attributes") or {}).get("entity") or {}).get("status"),
+        "jurisdiction": ((e.get("attributes") or {}).get("entity") or {}).get("jurisdiction"),
+        "registration_country": (((e.get("attributes") or {}).get("entity") or {}).get("legalAddress") or {}).get("country"),
+        "registered_as": ((e.get("attributes") or {}).get("entity") or {}).get("registeredAs"),  # national-registry id inside the registering LOU's jurisdiction — the cross-registry join key (e.g. US-MO Nestlé Purina 00007498, FR 74530)
+    } for e in (r["data"] or {}).get("data") or []]
+    pg = (((r["data"] or {}).get("meta") or {}).get("pagination")) or {}
+    total = pg.get("total")
+    return {"total": total if total is not None else len(rows),
+            "page": ({k: pg.get(k) for k in ("currentPage", "perPage", "from", "to", "total", "lastPage")}
+                     if pg else None),  # lastPage = honest walk bound (Nestlé bare name: total 140 @ perPage 15 → lastPage 10)
+            "candidates": rows, "_meta": r}
+
+
+def _norm_lei(lei):
+    from ..errors import SdkError
+
+    norm = str(lei).strip().upper()
+    if not LEI_RE.match(norm):
+        raise SdkError("usage_error", provider="gleif",
+                       detail=f"invalid LEI shape (ISO 17442: 20 alphanumeric chars): {lei}")
+    return norm
+
+
+def _card(norm, op, cache, no_cache):
+    """Single-endpoint parent card extraction → (card|None, meta). 404 = no parent, honest null (including the self-reported
+    reporting-exception face). The dedicated endpoints /direct-parent|/ultimate-parent return the parent card directly — the old
+    include= route laid the exception id into the result as if it were an LEI."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+    from datetime import datetime, timezone
+
+    try:
+        r = call_provider(provider, op, {"lei": norm}, cache=cache, no_cache=no_cache)
+        a = (((r["data"] or {}).get("data") or {}).get("attributes")) or {}
+        lei_id = a.get("lei")
+        if not lei_id:
+            return None, r  # empty-face fallback
+        ent = a.get("entity") or {}
+        return ({"lei": lei_id,
+                 "legal_name": (ent.get("legalName") or {}).get("name"),
+                 "entity_status": ent.get("status"),
+                 "jurisdiction": ent.get("jurisdiction")}), r
+    except SdkError as e:
+        if e.code == "upstream_not_found":
+            # 404 = no such parent — honest null; notFound is not cached, the meta is minted on the spot
+            return None, {"from_cache": False,
+                          "fetched_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")}
+        raise
+
+
+def get_direct_parent(lei, *, cache=None, no_cache=False):
+    """→ {lei, parent, _meta}; /lei-records/{lei}/direct-parent single-endpoint face (0.2.0 naming split: one command, one endpoint)."""
+    norm = _norm_lei(lei)
+    card, meta = _card(norm, "direct_parent", cache, no_cache)
+    return {"lei": norm, "parent": card, "_meta": meta}
+
+
+def get_ultimate_parent(lei, *, cache=None, no_cache=False):
+    """→ {lei, parent, _meta}; /lei-records/{lei}/ultimate-parent single-endpoint face (ultimate sense)."""
+    norm = _norm_lei(lei)
+    card, meta = _card(norm, "ultimate_parent", cache, no_cache)
+    return {"lei": norm, "parent": card, "_meta": meta}
+
+
+def get_parents(lei, *, cache=None, no_cache=False):
+    """→ {lei, direct_parent, ultimate_parent, _meta, _metas}; no parent = honest null, not an error.
+    (internal merge face: used by the related kind=parent internals; the command face is already split into the
+    gleif_direct_parent / gleif_ultimate_parent two endpoints.)"""
+    d = get_direct_parent(lei, cache=cache, no_cache=no_cache)
+    u = get_ultimate_parent(lei, cache=cache, no_cache=no_cache)
+    return {"lei": d["lei"], "direct_parent": d["parent"], "ultimate_parent": u["parent"],
+            "_meta": d["_meta"],
+            "_metas": [d["_meta"], u["_meta"]]}  # full-chain metas (one per dedicated endpoint) — the client layer's enrich_source consumes them one by one