agentdata 0.3.26__py3-none-any.whl

agentdata/company/kr_hometax.py

@@ -0,0 +1,112 @@
+"""kr_hometax — Korea NTA hometax business-registration status (휴폐업/tax type) provider (keyless anonymous single-shot).
+
+company roster (admitted in 0.3.11, probe tmp/probe-co-kr/). Shape verified 2026-10-30:
+POST to the bare domain hometax.go.kr/wqAction.do?actionId=ATTABZAA001R08&screenId=UTEABAAA13&
+popupYn=false&realScreenId= (the actionId family lives in the query string) + a seven-field flat JSON body
+(dongCode = middle-2 digits of the 10-digit number, txprDscmNo = the 10-digit business number,
+the other four constants) →
+{resultMsg{result S/F}, trtCntn full status sentence, smpcBmanTrtCntn concise status + 폐업일자,
+smpcBmanEnglTrtCntn English version, txprNm always null when anonymous (no owner-name leak),
+trtEndCd, nrgtTxprYn}.
+
+**Harvest-recipe deltas (two SDK-layer reversals, 2026-10-30 elimination probe)**: (1) the EverSafe
+trailing token (42-char hash appended to the JSON body) is **NOT required** — a bare POST without it
+still returns 200 result=S with the correct state (the old recipe was defensive redundancy; the
+hometaxbot k4 confusion is a smokescreen); (2) a browser UA is **NOT required** — urllib's default
+UA passes (not in the FAA/JFTC header-fingerprint gate family). (3) The response is **UTF-8 JSON**
+(Content-Type self-evident; the old cp949 observation belonged to a different action — the SDK face
+decodes UTF-8 via http_json and is correct).
+
+**Four-state semantics (every result=S shape is a legal answer, not an error)**: operating =
+「부가가치세 일반과세자 입니다.」 (VAT general taxpayer) or the 간이/과세특례 variants; closed =
+「폐업자 (…, 폐업일자:YYYY-MM-DD)」 (ISO date regex-extracted); unregistered =
+「국세청에 등록되지 않은…」 (registered=False); 휴업 (suspended) same sentence family.
+Positioning = status-column enrichment over lists (the batch-100-건 actionId has drifted, unexplored).
+TTL: status changes slowly — 7 days; politeness 0.5 rps (conservative tier for a government
+real-name-grade query gate).
+"""
+import re
+
+from ..errors import SdkError
+
+provider = {
+    "id": "kr_hometax",
+    "baseUrl": "https://hometax.go.kr",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        # actionId family inline in the path query string (POST read semantics: the seven fields are not path
+        # params, they go in the JSON body; idempotent participates in retries)
+        "biz_status": {"path": "/wqAction.do?actionId=ATTABZAA001R08&screenId=UTEABAAA13"
+                               "&popupYn=false&realScreenId=",
+                       "method": "POST", "idempotent": True, "timeoutMs": 30000},
+    },
+    "ttl": {"biz_status": 7 * 86400},
+}
+
+_BIZNO_RE = re.compile(r"^\d{10}$")
+_CLOSED_DATE_RE = re.compile(r"폐업일자[:：]?\s*(\d{4}-\d{2}-\d{2})")
+_UNREGISTERED_MARK = "국세청에 등록되지 않은"
+_CLOSED_MARK = "폐업"
+
+
+def _bizno(v):
+    """'124-81-00998'/'1248100998' → 10-digit string (Korean business number 3-2-5 hyphens optional)."""
+    norm = re.sub(r"[\s-]", "", str(v or ""))
+    if not _BIZNO_RE.match(norm):
+        raise SdkError("usage_error", provider="kr_hometax",
+                       detail=f"business registration number must be 10 digits (3-2-5 hyphens optional, e.g. 124-81-00998), got {v!r}")
+    return norm
+
+
+def parse_status(data, biz_no):
+    """Upstream JSON → four-state normalization (operating/closed/unregistered/other; registered bit + closed ISO date extracted).
+
+    Every result=S shape is a legal answer (unregistered is S too, not an error — same semantics as VIES INVALID);
+    result≠S or a malformed shape → state='error', verbatim passthrough, never faked.
+    """
+    d = data or {}
+    result = ((d.get("resultMsg") or {}).get("result")) or None
+    trt = (d.get("trtCntn") or "").strip() or None
+    simple = (d.get("smpcBmanTrtCntn") or "").strip() or None
+    english = (d.get("smpcBmanEnglTrtCntn") or "").strip() or None
+    blob = " ".join(x for x in (trt, simple) if x)
+    m = _CLOSED_DATE_RE.search(blob)
+    closed_date = m.group(1) if m else None
+    if result == "S" and blob:
+        if _UNREGISTERED_MARK in blob:
+            state, registered = "unregistered", False
+        elif _CLOSED_MARK in blob or closed_date:
+            state, registered = "closed", True
+        else:
+            state, registered = "active", True
+    else:
+        state, registered = "error", None
+    return {
+        "biz_no": biz_no,
+        "result": result,
+        "state": state,                # active | closed | unregistered | error
+        "registered": registered,      # None = malformed shape, never self-answered
+        "tax_type": trt,               # full status sentence (tax type: 일반/간이/과세특례…)
+        "simple_status": simple,       # concise status + 폐업일자
+        "english_status": english,     # English status sentence
+        "closed_date": closed_date,    # 폐업일자 ISO (always present on closed rows; operating/unregistered = None)
+        "trt_end_cd": d.get("trtEndCd"),
+    }
+
+
+def biz_status_raw(biz_no, *, cache=None, no_cache=False):
+    """→ {status, _meta} (four-state normalized; txprNm stays null when anonymous and is not carried in upstream response values)."""
+    from ..transport import call_provider
+
+    norm = _bizno(biz_no)
+    params = {
+        "dongCode": norm[3:5],   # middle-2-digit segment of the 10-digit number (district code)
+        "txprDscmNo": norm,       # the 10-digit business number
+        "inqrTrgtClCd": "1",
+        "mobYn": "N",
+        "psbSearch": "Y",
+        "pubcUserNo": "",
+        "userReqInfoVO": {},
+    }
+    r = call_provider(provider, "biz_status", params, cache=cache, no_cache=no_cache)
+    return {"status": parse_status(r["data"], norm), "_meta": r}

agentdata/company/no_brreg.py

@@ -0,0 +1,124 @@
+"""no_brreg — Norwegian Enhetsregisteret (Brønnøysund registry master) provider (HAL JSON front door; keyless).
+
+2026-10-29 probed shape: the real param is **?navn=** (?name= gives 400 valideringsfeil — the parameter takes
+the Norwegian spelling); pagination ?size=&page= (0-based) → HAL page{number,size,totalElements,totalPages};
+single record GET /enheter/{orgnr} (404 = no such number); roles face GET /enheter/{orgnr}/roller →
+rollegrupper[] (DAGL CEO / STYR board / REVI auditor groups), rows = person{navn{fornavn,etternavn},
+fodselsdato, erDoed} or enhet{organisasjonsnummer} (auditors are often companies) + the avregistrert retirement flag.
+PII line: the public face exposes only birth dates, no national id numbers (fnr is not on this face) — name + birth
+date are collectible.
+TTL: enheter/enhet 7 days (current-value queries) / roller 30 days (role sequences change slowly); politeness tier 0.5 rps.
+"""
+import re
+
+from ..errors import SdkError
+
+provider = {
+    "id": "no_brreg",
+    "baseUrl": "https://data.brreg.no/enhetsregisteret/api",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "enheter": {"path": "/enheter"},                                              # params: navn/size/page (query)
+        "enhet": {"path": "/enheter/{organisasjonsnummer}", "notFound": [404]},       # params: organisasjonsnummer (path)
+        "roller": {"path": "/enheter/{organisasjonsnummer}/roller", "notFound": [404]},  # same (roles face)
+    },
+    "ttl": {"enheter": 7 * 86400, "enhet": 7 * 86400, "roller": 30 * 86400},
+}
+
+_ORGNR_RE = re.compile(r"^\d{9}$")
+
+
+def _orgnr(v):
+    norm = str(v or "").replace(" ", "").strip()
+    if not _ORGNR_RE.match(norm):
+        raise SdkError("usage_error", provider="no_brreg",
+                       detail=f"organisasjonsnummer must be 9 digits (Norwegian organization number), got \"{v}\"")
+    return norm
+
+
+def _norm_enhet(e):
+    """Full 40-key record → due-diligence core projection (industry/flags/address/headcount); historical names passed through."""
+    addr = e.get("forretningsadresse") or {}
+    return {
+        "organisasjonsnummer": e.get("organisasjonsnummer"),
+        "navn": e.get("navn"),
+        "organisasjonsform": {"kode": (e.get("organisasjonsform") or {}).get("kode"),
+                              "beskrivelse": (e.get("organisasjonsform") or {}).get("beskrivelse")},
+        "naeringskode1": {"kode": (e.get("naeringskode1") or {}).get("kode"),
+                          "beskrivelse": (e.get("naeringskode1") or {}).get("beskrivelse")},  # NACE main industry
+        "antall_ansatte": e.get("antallAnsatte"),
+        "registreringsdato_enhetsregisteret": e.get("registreringsdatoEnhetsregisteret"),
+        "stiftelsesdato": e.get("stiftelsesdato"),
+        "hjemmeside": e.get("hjemmeside"),
+        "konkurs": e.get("konkurs"),
+        "under_avvikling": e.get("underAvvikling"),
+        "under_tvangsavvikling": e.get("underTvangsavviklingEllerTvangsopplosning"),
+        "registrert_i_mva_registeret": e.get("registrertIMvaregisteret"),   # VAT register flag
+        "registrert_i_foretaksregisteret": e.get("registrertIForetaksregisteret"),
+        "overordnet_enhet": e.get("overordnetEnhet"),                        # parent org number (subsidiary edge)
+        "forretningsadresse": {"adresse": (addr.get("adresse") or [None])[0],
+                               "poststed": addr.get("poststed"), "kommune": addr.get("kommune"),
+                               "landkode": addr.get("landkode")},
+        "historiske_navn": e.get("historiskeNavn"),                          # former names passed through (upstream shape)
+    }
+
+
+def search_enheter(navn, *, page=0, size=20, cache=None, no_cache=False):
+    """→ {enheter[], page{}, params, _meta}; name search (navn verbatim channel; size/page 0-based HAL pagination)."""
+    from ..transport import call_provider
+
+    q = str(navn or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="no_brreg", detail="search requires navn (name search, the ?navn= verbatim channel)")
+    p, s = max(0, int(page or 0)), min(max(1, int(size or 20)), 100)  # 1-100 = our politeness cap
+    r = call_provider(provider, "enheter", {"navn": q, "page": p, "size": s},
+                      cache=cache, no_cache=no_cache)
+    d = r["data"] or {}
+    rows = [_norm_enhet(e) for e in (d.get("_embedded") or {}).get("enheter") or []]
+    pg = d.get("page") or {}
+    return {"enheter": rows,
+            "page": {"number": pg.get("number"), "size": pg.get("size"),
+                     "total_elements": pg.get("totalElements"), "total_pages": pg.get("totalPages")},
+            "params": {"navn": q, "page": p, "size": s}, "_meta": r}
+
+
+def get_enhet(organisasjonsnummer, *, cache=None, no_cache=False):
+    """→ {enhet, _meta}; single record by 9-digit org number (404 = no such number, honestly reported)."""
+    from ..transport import call_provider
+
+    v = _orgnr(organisasjonsnummer)
+    r = call_provider(provider, "enhet", {"organisasjonsnummer": v}, cache=cache, no_cache=no_cache)
+    return {"enhet": _norm_enhet(r["data"] or {}), "_meta": r}
+
+
+def get_roller(organisasjonsnummer, *, cache=None, no_cache=False):
+    """→ {organisasjonsnummer, rollegrupper[], _meta}; roles face (DAGL/STYR/REVI groups).
+    Person rows = name + birth date (no national id number on the public face); corporate rows (auditors, typically) =
+    org number. avregistrert=true = retired."""
+    from ..transport import call_provider
+
+    v = _orgnr(organisasjonsnummer)
+    r = call_provider(provider, "roller", {"organisasjonsnummer": v}, cache=cache, no_cache=no_cache)
+    d = r["data"] or {}
+    groups = [{
+        "type_kode": (g.get("type") or {}).get("kode"),
+        "type_beskrivelse": (g.get("type") or {}).get("beskrivelse"),
+        "sist_endret": g.get("sistEndret"),
+        "roller": [{
+            "kode": (m.get("type") or {}).get("kode"),
+            "beskrivelse": (m.get("type") or {}).get("beskrivelse"),
+            "person": _person(m.get("person")),
+            "enhet_organisasjonsnummer": ((m.get("enhet") or {}).get("organisasjonsnummer")),
+            "avregistrert": m.get("avregistrert"),
+            "rekkefolge": m.get("rekkefolge"),          # order within the group
+        } for m in g.get("roller") or []],
+    } for g in d.get("rollegrupper") or []]
+    return {"organisasjonsnummer": v, "rollegrupper": groups, "_meta": r}
+
+
+def _person(p):
+    if not p:
+        return None
+    navn = p.get("navn") or {}
+    full = " ".join(x for x in (navn.get("fornavn"), navn.get("etternavn")) if x) or None
+    return {"navn": full, "fodselsdato": p.get("fodselsdato"), "er_doed": p.get("erDoed")}

agentdata/company/ror.py

@@ -0,0 +1,105 @@
+"""ror — ROR (Research Organization Registry) provider (v2 schema; keyless).
+
+api.ror.org. 2026-10-23 probed shape:
+GET /organizations?query=<q> → {number_of_results, time_taken, items:[{id,names[],types[],status,
+established,locations[],external_ids[],relationships[],domains[],links[],admin}]};
+GET /organizations/{id} (id = the full ror.org URL, path-segment encoded) → **a bare single record** (no items
+wrapper, 200 verified).
+v2 migration notes: **the top-level name/country keys are gone** — the display name lives in names[] (the entry whose
+types includes ror_display has the value), the country in locations[0].geonames_details.country_name; external_ids is
+an array ({type,preferred,all[]}) not the v1 dict; relationships[] {label,type:parent|child|related,id(full URL)} is
+the parent/child/related edge face.
+The search face is fixed at 20 rows per page (upstream has no per_page param, only page) — one page is enough for the
+candidate face, pagination is not wired up.
+TTL: search 7 days / record 30 days (ROR ships quarterly); politeness tier 1 rps (official no-key guidance is ≤2).
+"""
+import re
+
+from ..errors import SdkError
+
+provider = {
+    "id": "ror",
+    "baseUrl": "https://api.ror.org",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "search": {"path": "/organizations"},            # params: query, page, all_status (added in 0.2.9)
+        "record": {"path": "/organizations/{id}"},       # id takes the full https://ror.org/<ui> (pre-encoded at build time)
+    },
+    "ttl": {"search": 7 * 86400, "record": 30 * 86400},
+}
+
+_ROR_UI = re.compile(r"^(?:https?://ror\.org/)?(0[a-z0-9]{8})$", re.IGNORECASE)  # ROR id: leading 0 + 8 chars
+
+
+def display_name(names):
+    """v2 display name = the names[] entry whose types includes ror_display (falls back to label / first entry)."""
+    if not isinstance(names, list) or not names:
+        return None
+    for want in ("ror_display", "label"):
+        for n in names:
+            if want in (n.get("types") or []):
+                return n.get("value")
+    return names[0].get("value")
+
+
+def orgs_from_upstream(data):
+    """Upstream payload → org candidates (pure function, offline-testable). A bare single record must first be wrapped as {items:[rec]}."""
+    items = data if isinstance(data, list) else (data or {}).get("items") or []
+    candidates = []
+    for o in items:
+        loc = ((o.get("locations") or [{}])[0].get("geonames_details") or {})
+        parent = next((r for r in (o.get("relationships") or []) if r.get("type") == "parent"), None)
+        candidates.append({
+            "ror_id": o.get("id", "").replace("https://ror.org/", "").replace("http://ror.org/", "") or None,
+            "name": display_name(o.get("names")),                      # v2: the top-level name key is gone
+            "aliases": [n.get("value") for n in (o.get("names") or [])
+                        if "ror_display" not in (n.get("types") or []) and n.get("value")],
+            "type": (o.get("types") or [None])[0],                     # company|education|healthcare|facility|government|nonprofit|archive|other
+            "country": loc.get("country_name"),                        # v2: country comes from locations (first address)
+            "country_code": loc.get("country_code"),
+            "status": o.get("status"),                                 # active|inactive|withdrawn
+            "established": o.get("established"),
+            "website": next((l.get("value") for l in (o.get("links") or []) if l.get("type") == "website"), None),
+            "domains": o.get("domains") or [],
+            "parent": ({"name": parent.get("label"),
+                        "ror_id": (parent.get("id") or "").replace("https://ror.org/", "") or None}
+                       if parent else None),                           # parent-org edge (the research-world counterpart of the GLEIF parent)
+            "external_ids": {e.get("type"): (e.get("preferred") or (e.get("all") or [None])[0])
+                             for e in (o.get("external_ids") or [])},
+        })
+    return {
+        "candidates": candidates,
+        "total": data.get("number_of_results") if isinstance(data, dict) and isinstance(data.get("number_of_results"), int) else (1 if isinstance(data, list) else None),
+    }
+
+
+def search_orgs(q, *, page=None, all_status=None, cache=None, no_cache=False):
+    """→ {candidates[], total, _meta}; org-name search candidates (query matches all fields; fixed 20 rows/page, page passes straight through).
+    all_status (added in the 0.2.9 audit): an upstream boolean, default false = **only active orgs are returned** —
+    inactive/withdrawn are hidden wholesale by default (2026-10-28 probe, AstraZeneca: default 22 rows all active vs
+    all_status=true 23 rows including 1 withdrawn); None = param not sent, upstream default applies; True/False passed
+    through explicitly. Due-diligence use cases usually want withdrawn rows included explicitly."""
+    from ..transport import call_provider
+
+    query = str(q or "").strip()
+    if not query:
+        raise SdkError("usage_error", provider="ror", detail="search_orgs requires a value (org name or ROR id)")
+    params = {"query": query}
+    if page is not None:
+        params["page"] = int(page)
+    if all_status is not None:
+        params["all_status"] = "true" if all_status else "false"
+    r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    return {**orgs_from_upstream(r["data"]), "_meta": r}
+
+
+def lookup_ror(id_, *, cache=None, no_cache=False):
+    """→ {candidates[1], total, _meta}; ROR id single-record identity card (accepts either the bare UI or the full https://ror.org/… form)."""
+    from ..transport import call_provider
+
+    m = _ROR_UI.match(str(id_ or "").strip())
+    if not m:
+        raise SdkError("usage_error", provider="ror", detail=f"not a ROR id shape (0 + 8 chars): {id_}")
+    r = call_provider(provider, "record", {"id": f"https://ror.org/{m.group(1).lower()}"}, cache=cache, no_cache=no_cache)
+    data = r["data"]
+    return {**orgs_from_upstream(data if isinstance(data, list) else {"items": [data]}), "_meta": r}

agentdata/company/ted.py

@@ -0,0 +1,117 @@
+"""ted — EU TED (Tenders Electronic Daily) v3 provider (EU procurement notices; keyless).
+
+The old face (search.api.ted.europa.eu REST/SOAP) was 429-blocked three times in 2026-10 — overturned on
+2026-10-23: api.ted.europa.eu/v3 POST expert search works from this egress (the old block only applied to the old
+face; do not extrapolate across faces).
+Contract pitfalls (self-evidenced by the 400 error body): 1. GET→405 (POST-only); 2. body {query, fields[], limit, page};
+3. fields must come from the eForms field enumeration (a wrong name 400s and dumps the full 1,833-field list — the error
+body is the documentation).
+Wildcard pitfall: values must match ^[^*?] — leading wildcards are forbidden (*Siemens* 400), a trailing wildcard is
+legal (Siemens* = prefix match).
+Return-shape pitfall: text fields are language dicts ({'deu':['…']}) — loc() flattens preferring eng; publication-date
+carries a 'Z' suffix.
+TTL: search 24h (notice feeds update daily). Politeness tier 0.5 rps (conservative given the old face's 429 record).
+"""
+import re
+
+from ..errors import SdkError
+
+provider = {
+    "id": "ted",
+    "baseUrl": "https://api.ted.europa.eu/v3",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        # POST with read semantics: expert search is idempotent read-only; all params go in the JSON body
+        "search": {"path": "/notices/search", "method": "POST", "idempotent": True, "timeoutMs": 30000},
+    },
+    "ttl": {"search": 24 * 3600},
+}
+
+_FIELDS = ["publication-number", "publication-date", "notice-title", "notice-type",
+           "organisation-name-buyer", "organisation-country-buyer", "total-value"]
+
+
+def loc(v):
+    """Language dict/array flattening: {'eng':['X'],'deu':['Y']} → prefer eng, take the first value."""
+    if isinstance(v, list):
+        return next((x for x in v if x), None)
+    if isinstance(v, dict):
+        k = "eng" if "eng" in v else next(iter(v), None)
+        return loc(v.get(k)) if k is not None else None
+    return v
+
+
+def ted_from_upstream(data, limit=10):
+    """Upstream payload → {notices[], has_more} (pure function, offline-testable); no total — inferred from a full page."""
+    ns = (data or {}).get("notices") or []
+    return {
+        "has_more": len(ns) >= limit,
+        "notices": [{
+            "publication_number": n.get("publication-number"),   # stable key (e.g. 671086-2023)
+            "publication_date": (n.get("publication-date") or "").removesuffix("Z") or None,
+            "title": loc(n.get("notice-title")),
+            "notice_type": n.get("notice-type"),                 # eForms type (cn-standard = contract notice, standard…)
+            "buyer": loc(n.get("organisation-name-buyer")),
+            "buyer_country": n.get("organisation-country-buyer"),
+            "total_value": n.get("total-value"),
+            "xml_url": (n.get("links") or {}).get("xml"),        # eForms XML original anchor (the corpus line pulls full text from it)
+        } for n in ns],
+    }
+
+
+def company_eu_tenders(name=None, *, country=None, cpv=None, limit=10, cache=None, no_cache=False):
+    """→ {notices[], has_more, query, _meta}; EU procurement notice rows (buyer prefix match).
+    Join discipline (same as fed_awards): match on name against the buyer face, parent/subsidiary groups are not merged,
+    narrow by VAT/LEI before persisting."""
+    from ..transport import call_provider
+
+    parts = []
+    q = str(name or "").strip()
+    if q:
+        if q[:1] in "*?":
+            raise SdkError("usage_error", provider="ted",
+                           detail="upstream forbids leading wildcards (^[^*?]) — use prefix matching (e.g. Siemens)")
+        parts.append(f"organisation-name-buyer={re.sub(r'[*?]', '', q)}*")  # trailing wildcard = prefix match
+    c = str(country or "").strip().upper()
+    if c:
+        if not re.fullmatch(r"[A-Z]{3}", c):
+            raise SdkError("usage_error", provider="ted", detail="country must be ISO-3 (e.g. DEU)")
+        parts.append(f"organisation-country-buyer={c}")
+    cp = str(cpv or "").strip()
+    if cp:
+        if not re.fullmatch(r"\d{8}", cp):
+            raise SdkError("usage_error", provider="ted", detail="cpv must be an 8-digit CPV code (e.g. 33100000 medical consumables)")
+        parts.append(f"classification-cpv={cp}")
+    if not parts:
+        raise SdkError("usage_error", provider="ted", detail="give at least one of name / country / cpv")
+    lim = min(max(1, int(limit) or 10), 20)
+    query = " AND ".join(parts)
+    r = call_provider(provider, "search", {"query": query, "fields": _FIELDS, "limit": lim, "page": 1},
+                      cache=cache, no_cache=no_cache)
+    return {**ted_from_upstream(r["data"], lim), "query": query, "_meta": r}
+
+
+def search_raw(query, *, fields=None, limit=10, page=1, cache=None, no_cache=False):
+    """→ {notices[], has_more, query, params, _meta}; expert search verbatim (query goes into the POST body by its upstream name).
+    limit wall 1-250: measured 2026-10-23, 251→400 SEARCH_EXCEEDS_MAX_LIMIT
+    ("Value (251) of parameter 'limit' exceeds maximum allowed value (250)"); 250 served in full.
+    fields defaults to the seven _FIELDS columns and can be overridden with a comma-separated string — a wrong name 400s and
+    dumps the full 1,833-field list (the error body is the documentation).
+    The old company_eu_tenders 20 clamp is this repo's politeness tier, not an upstream limit — the flat face follows the
+    measured wall."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    q = str(query or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="ted",
+                       detail="ted_notices_search requires query (expert syntax, e.g. organisation-name-buyer=Siemens*)")
+    lim = int(limit)
+    if not 1 <= lim <= 250:
+        raise SdkError("usage_error", provider="ted",
+                       detail="limit must be 1-250 (measured 2026-10-23: 251→400 SEARCH_EXCEEDS_MAX_LIMIT, "
+                              "upstream text \"exceeds maximum allowed value (250)\")")
+    flds = [f.strip() for f in str(fields).split(",") if f.strip()] if fields else list(_FIELDS)
+    params = {"query": q, "fields": flds, "limit": lim, "page": int(page)}
+    r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    return {**ted_from_upstream(r["data"], lim), "query": q, "params": params, "_meta": r}

agentdata/company/usaspending.py

@@ -0,0 +1,124 @@
+"""usaspending — USAspending API (US federal contracts/grants by recipient; keyless).
+
+Keyless at ~1,000 req/hr/IP plus 30 req/5s bursts — we set 0.25 rps/burst 5 (≈900/hr, comfortably inside) so no
+daily-quota ledger is needed.
+First use of POST read semantics: spending_by_award is a POST JSON body, ops declare idempotent=True to join the
+retry path. Live-shape check: the whole tree sits under the /api/v2/ prefix (/v2/ is now 404);
+autocomplete returns {count, results[{recipient_name, uei, duns}]};
+spending_by_award's recipient_search_text must be an **array** (422 measured).
+"""
+provider = {
+    "id": "usaspending",
+    "baseUrl": "https://api.usaspending.gov",
+    "rate": {"rps": 0.25, "burst": 5},
+    "ops": {
+        "recipientAutocomplete": {"path": "/api/v2/autocomplete/recipient/", "method": "POST", "idempotent": True},
+        "spendingByAward": {"path": "/api/v2/search/spending_by_award/", "method": "POST", "idempotent": True},
+    },
+    "ttl": {"recipientAutocomplete": 7 * 86400, "spendingByAward": 24 * 3600},
+}
+
+
+def find_recipient(name, *, limit=5, cache=None, no_cache=False):
+    """→ {candidates[{recipient_name,uei,duns}], _meta}; uei is often null — the authoritative UEI anchor is the SAM.gov card (watch list); this serves only as a candidate hint."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    q = str(name or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="usaspending", detail="--name is required")
+    r = call_provider(provider, "recipientAutocomplete",
+                      {"search_text": q, "limit": min(max(1, int(limit) or 5), 20)},
+                      cache=cache, no_cache=no_cache)
+    rows = [{"recipient_name": e.get("recipient_name"), "uei": e.get("uei"), "duns": e.get("duns")}
+            for e in (r["data"] or {}).get("results") or []]  # duns = legacy key, trending permanently null as of 2026
+    return {"candidates": rows, "_meta": r}
+
+
+def _awards_from_upstream(data):
+    """Upstream payload → awards rows (pure function, offline-testable; shared by company_fed_awards and awards_raw)."""
+    return [{
+        "award_id": a.get("Award ID"),
+        "recipient_name": a.get("Recipient Name"),
+        "award_amount": a.get("Award Amount"),
+        "start_date": a.get("Start Date"),
+        "end_date": a.get("End Date"),
+        "awarding_agency": a.get("Awarding Agency"),
+        "generated_internal_id": a.get("generated_internal_id"),  # official detail key (CONT_AWD_…), composes the USAspending human page
+    } for a in (data or {}).get("results") or []]
+
+
+def company_fed_awards(name, *, limit=10, startdt=None, enddt=None, cache=None, no_cache=False):
+    """→ {page_metadata, has_more, awards[], date_range, _meta}; the four contract types A/B/C/D (grant types come in a later wave).
+    page_metadata has no total (only hasNext/last_record_* pagination cursors — the endpoint gives no counts) — the old name
+    total_estimate is fully removed; the window semantics = the award period intersects the window (long-running contracts that
+    span it are included), not "started inside the window".
+    Join discipline: no blind name concatenation — the caller narrows by CIK/LEI first, then this face yields the numbers."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    q = str(name or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="usaspending", detail="related kind=fed_awards requires --name")
+    filters = {
+        "award_type_codes": ["A", "B", "C", "D"],
+        "recipient_search_text": [q],  # measured 2026-10-19: must be an array, a string gets 422
+    }
+    date_range = None
+    if startdt or enddt:  # either end given → fill the other into a complete window; date_range echoes the values actually in effect (guards against "sent but silently swallowed" look-alikes)
+        from ..daterange import resolve as _range
+        _start, _end, date_range = _range(startdt, enddt, default_start="2007-10-01",
+                                          provider=provider["id"], label="recipient award period")
+        filters["time_period"] = [{"start_date": _start, "end_date": _end}]
+    r = call_provider(provider, "spendingByAward", {
+        "filters": filters,
+        "fields": ["Award ID", "Recipient Name", "Award Amount", "Start Date", "End Date", "Awarding Agency"],
+        "limit": min(max(1, int(limit) or 10), 100),
+        "page": 1,
+        "subawards": False,
+    }, cache=cache, no_cache=no_cache)
+    rows = _awards_from_upstream(r["data"])
+    # page_metadata has no total — truncation visibility rides on has_more (hasNext)
+    pm = (r["data"] or {}).get("page_metadata")
+    return {"page_metadata": pm, "has_more": bool(pm and pm.get("hasNext")), "awards": rows,
+            "date_range": date_range, "_meta": r}
+
+
+def awards_raw(recipient_search_text, *, award_type_codes=None, start_date=None, end_date=None,
+               fields=None, limit=10, page=1, subawards=False, cache=None, no_cache=False):
+    """→ {page_metadata, has_more, awards[], date_range, params, _meta}; spending_by_award params pass through verbatim.
+    recipient_search_text must be an array upstream (a string 422s, measured 2026-10-19) — a scalar is auto-wrapped;
+    award_type_codes comma string → array (default A,B,C,D the four contract types; grants 02/03 etc. can override);
+    time_period auto-fills the missing end (upstream silently swallows single-ended windows — same EDGAR guard), date_range
+    echoes the window actually in effect; fields comma string → array (default six columns); limit 1-100 (upstream API docs);
+    subawards passes straight through upstream."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    q = str(recipient_search_text or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="usaspending",
+                       detail="usaspending_spending_by_award requires recipient_search_text (recipient name, upstream array semantics — a scalar is auto-wrapped)")
+    lim = int(limit)
+    if not 1 <= lim <= 100:
+        raise SdkError("usage_error", provider="usaspending",
+                       detail="limit must be 1-100 (upstream API docs spending_by_award page-size cap)")
+    types = ([t.strip() for t in str(award_type_codes).split(",") if t.strip()]
+             if award_type_codes else ["A", "B", "C", "D"])
+    filters = {"award_type_codes": types, "recipient_search_text": [q]}
+    date_range = None
+    if start_date or end_date:
+        from ..daterange import resolve as _range
+        _start, _end, date_range = _range(start_date, end_date, default_start="2007-10-01",
+                                          provider=provider["id"], label="recipient award period")
+        filters["time_period"] = [{"start_date": _start, "end_date": _end}]
+    flds = ([f.strip() for f in str(fields).split(",") if f.strip()]
+            if fields else ["Award ID", "Recipient Name", "Award Amount",
+                            "Start Date", "End Date", "Awarding Agency"])
+    params = {"filters": filters, "fields": flds, "limit": lim,
+              "page": int(page), "subawards": bool(subawards)}
+    r = call_provider(provider, "spendingByAward", params, cache=cache, no_cache=no_cache)
+    pm = (r["data"] or {}).get("page_metadata")
+    return {"page_metadata": pm, "has_more": bool(pm and pm.get("hasNext")),
+            "awards": _awards_from_upstream(r["data"]), "date_range": date_range,
+            "params": params, "_meta": r}

agentdata/company/vies.py

@@ -0,0 +1,66 @@
+"""vies — EU VIES provider (EU VAT number online validation; keyless).
+
+GET /ms/{cc}/vat/{number} → {isValid, userError, name, address, requestDate, requestIdentifier,
+vatNumber, originalVatNumber, viesApproximate{matchName, matchStreet…}}.
+Three-way semantics: isValid=true → valid (name/address may be masked as '---' by a member state — DE does,
+record null honestly); isValid=false + userError=INVALID → the legal answer "number invalid" (ok=True, not an
+error); userError=anything else (MS_UNAVAILABLE/TIME_OUT/*MAX_CONCURRENT_REQ…) → upstream_unavailable (the
+member-state system is offline/rate-limited).
+Input accepts the whole VAT string ('DE811907980', first two chars = member-state code, Greece is EL not GR —
+passed through as-is, not normalized).
+TTL: 7 days (the validation verdict; requestIdentifier is the official audit-trace key).
+"""
+import re
+
+from ..errors import SdkError
+
+provider = {
+    "id": "vies",
+    "baseUrl": "https://ec.europa.eu/taxation_customs/vies/rest-api",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "check": {"path": "/ms/{cc}/vat/{number}", "ttl": 7 * 86400, "timeoutMs": 30000},
+    },
+    "ttl": {"check": 7 * 86400},
+}
+
+_VAT = re.compile(r"^([A-Z]{2})([A-Z0-9+*]{2,13})$")
+
+
+def _soft(v):
+    return None if v == "---" else v
+
+
+def parse_vat(value):
+    """'DE811907980' → ('DE','811907980'); no country prefix → usage_error (VIES routes by member state)."""
+    s = re.sub(r"[\s.]", "", str(value or "")).upper()
+    m = _VAT.match(s)
+    if not m:
+        raise SdkError("usage_error", provider="vies",
+                       detail="VAT number must carry a member-state prefix (e.g. DE811907980 / EL040127129); add the country code to a bare number first")
+    return m.group(1), m.group(2)
+
+
+def check_vat(value, *, cache=None, no_cache=False):
+    """→ {valid, user_error, vat_number, name, address, request_identifier, approximate, _meta}."""
+    from ..transport import call_provider
+
+    cc, number = parse_vat(value)
+    r = call_provider(provider, "check", {"cc": cc, "number": number}, cache=cache, no_cache=no_cache)
+    d = r["data"] or {}
+    ue = d.get("userError")
+    if ue and ue not in ("VALID", "INVALID"):
+        raise SdkError("upstream_unavailable", provider="vies",
+                       detail=f"VIES member-state system returned no verdict (userError={ue}) — retry later, not a validation failure")
+    return {
+        "valid": d.get("isValid") is True,
+        "user_error": ue,
+        "country_code": cc,
+        "vat_number": f"{cc}{d.get('originalVatNumber') or d.get('vatNumber') or number}",  # display sense, prefix restored
+        "name": _soft(d.get("name")),
+        "address": _soft(d.get("address")),
+        "request_date": d.get("requestDate"),
+        "request_identifier": d.get("requestIdentifier"),   # official audit-trace key (for audit backtracking)
+        "approximate": d.get("viesApproximate"),            # approximate match scores (corroborating evidence for member-state data confidence)
+        "_meta": r,
+    }