agentdata 0.3.26__py3-none-any.whl

agentdata/company/ch_zefix.py

@@ -0,0 +1,100 @@
+"""ch_zefix — Swiss Zefix commercial register (Zentraler Firmenindex) provider (same-origin REST front door; keyless).
+
+2026-10-29 probed shape: POST /firm/search.json with JSON body
+{languageKey, maxEntries, offset, name} → {list[], hasMoreResults, offset, maxEntries, maxOffset};
+name is a contains-match (nestle hits Nestler), pagination = offset+hasMoreResults (maxOffset ~540k = upstream offset wall);
+single record GET /firm/{ehraid}.json returns the full record: oldNames[] name history + hasTakenOver/wasTakenOverBy M&A edges
+(rows carry ehraid/uid/chid cross-references — closed-loop linking inside the Swiss registry system) + purpose full text.
+Three keys surfaced directly: ehraid (master id) / uid (CHE business id) / chid (register id). Officers/directors are not in the public face.
+TTL: search 7 days (current-value query) / firm 30 days (records change slowly); politeness tier 0.5 rps (no published quota).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "ch_zefix",
+    "baseUrl": "https://www.zefix.ch/ZefixREST/api/v1",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "search": {"path": "/firm/search.json", "method": "POST", "idempotent": True},  # params: name/maxEntries/offset (all in the JSON body)
+        "firm": {"path": "/firm/{ehraid}.json", "notFound": [404]},                     # params: ehraid (path template)
+    },
+    "ttl": {"search": 7 * 86400, "firm": 30 * 86400},
+}
+
+
+def search_firms(name, *, max_entries=100, offset=0, cache=None, no_cache=False):
+    """→ {firms[], has_more, max_offset, params, _meta}; name → registry candidates (contains-match, not authoritative normalization).
+    maxEntries/offset are honored and echoed upstream (probed: maxEntries=3 returned 3 rows); 1-100 is our politeness cap, not an upstream wall."""
+    from ..transport import call_provider
+
+    q = str(name or "").strip()
+    if not q:
+        raise SdkError("usage_error", provider="ch_zefix", detail="search requires name (company name, contains-match)")
+    n = min(max(1, int(max_entries or 100)), 100)
+    off = max(0, int(offset or 0))
+    r = call_provider(provider, "search",
+                      {"name": q, "maxEntries": n, "offset": off, "languageKey": "en"},
+                      cache=cache, no_cache=no_cache)
+    d = r["data"] or {}
+    rows = [{
+        "ehraid": f.get("ehraid"),
+        "uid": f.get("uid"),
+        "uid_formatted": f.get("uidFormatted"),
+        "chid": f.get("chid"),
+        "chid_formatted": f.get("chidFormatted"),
+        "name": f.get("name"),
+        "status": f.get("status"),                      # EXISTIEREND / GELOESCHT…
+        "legal_seat": f.get("legalSeat"),
+        "legal_form_id": f.get("legalFormId"),
+        "register_office_id": f.get("registerOfficeId"),
+        "shab_date": f.get("shabDate"),                 # latest gazette date
+        "delete_date": f.get("deleteDate"),             # non-null on GELOESCHT rows
+        "cantonal_excerpt_web": f.get("cantonalExcerptWeb"),  # cantonal register excerpt page (human-readable)
+    } for f in d.get("list") or []]
+    return {"firms": rows, "has_more": bool(d.get("hasMoreResults")),
+            "max_offset": d.get("maxOffset"),
+            "params": {"name": q, "maxEntries": n, "offset": off, "languageKey": "en"},
+            "_meta": r}
+
+
+def get_firm(ehraid, *, cache=None, no_cache=False):
+    """→ {firm, _meta}; full record card by ehraid (purpose/oldNames/M&A edges).
+    hasTakenOver = predecessors this firm absorbed / wasTakenOverBy = the successor that absorbed this firm —
+    rows carry ehraid/uid/chid so ch_zefix_firm/ch_zefix_firm_search can be called next for a closed loop."""
+    from ..transport import call_provider
+
+    v = str(ehraid or "").strip()
+    if not v.isdigit():
+        raise SdkError("usage_error", provider="ch_zefix",
+                       detail=f"ehraid must be numeric (master id, surfaced by search rows), got \"{ehraid}\"")
+    r = call_provider(provider, "firm", {"ehraid": v}, cache=cache, no_cache=no_cache)
+    d = r["data"] or {}
+    firm = {
+        "ehraid": d.get("ehraid"),
+        "uid": d.get("uid"),
+        "uid_formatted": d.get("uidFormatted"),
+        "chid": d.get("chid"),
+        "chid_formatted": d.get("chidFormatted"),
+        "name": d.get("name"),
+        "translation": d.get("translation"),
+        "status": d.get("status"),
+        "legal_seat": d.get("legalSeat"),
+        "legal_form_id": d.get("legalFormId"),
+        "register_office_id": d.get("registerOfficeId"),
+        "shab_date": d.get("shabDate"),
+        "delete_date": d.get("deleteDate"),
+        "cantonal_excerpt_web": d.get("cantonalExcerptWeb"),
+        "purpose": d.get("purpose"),                    # full statement of purpose
+        "address": d.get("address"),                    # registered address (upstream shape passed through)
+        "old_names": [{"name": o.get("name"), "sequence_nr": o.get("sequenceNr"),
+                       "translation": o.get("translation")} for o in d.get("oldNames") or []],
+        "has_taken_over": _edge(d.get("hasTakenOver")),      # predecessors: merged into this firm
+        "taken_over_by": _edge(d.get("wasTakenOverBy")),     # successors: absorbed this firm
+    }
+    return {"firm": firm, "_meta": r}
+
+
+def _edge(rows):
+    """M&A edge row projection: name + three keys (ehraid/uid/chid) — keys feed the next hop, the rest is dropped."""
+    return [{"name": e.get("name"), "ehraid": e.get("ehraid"),
+             "uid": e.get("uid"), "chid": e.get("chid")} for e in rows or []]

agentdata/company/cli.py

@@ -0,0 +1,243 @@
+"""company cli — domain command face registration (split per domain in 0.2.6, moved in from the root cli.py; purely flat since the 0.3.0 verb-layer + sugar removal).
+
+register(v, g): registers flat commands on the domain subparser (g = the root _leaf_globals factory,
+passed in as a parameter to avoid a cli ↔ domain-cli cycle); FLAT = the flat dispatch table, merged by the root cli for main to use.
+"""
+import argparse
+
+def register(v, g):
+    # —— Flat panel commands (company main face: source-qualified names + upstream params under original names + our defaults; the only face family since 0.3.0) ——
+    f1 = v.add_parser("ch_zefix_firm", parents=[g()],
+                       help="Swiss firm full profile by ehraid (Zefix /firm/{ehraid}.json)",
+                       description="Zefix single record: purpose full text, oldNames history, hasTakenOver/takenOverBy M&A edges with ehraid/uid/chid cross-references (precedessor/successor)")
+    f1.add_argument("--ehraid", required=True, help="Registry master id (upstream path param: ehraid; from search rows)")
+    # —— 0.3.3 European country registry realtime faces (CH Zefix / NO Brreg / FI YTJ) ——
+    f2 = v.add_parser("ch_zefix_firm_search", parents=[g()],
+                       help="Swiss commercial register name search (Zefix POST search.json)",
+                       description="Zefix firm search: name contains-match (hits historical names too); three registry keys (ehraid/uid/chid) per row; maxEntries/offset honored upstream (echoed back)")
+    f2.add_argument("--name", required=True, help="Company name (upstream param: name; contains-match, non-authoritative)")
+    f2.add_argument("--max-entries", dest="max_entries", type=int, default=100,
+                     help="Rows per page (upstream param: maxEntries; honored upstream; 1-100 our politeness cap)")
+    f2.add_argument("--offset", type=int, default=0, help="Offset (upstream param: offset; walk with --offset, cap ~540k upstream maxOffset)")
+    # —— 0.3.11 CO RUES + KR hometax dual-country batch ——
+    f_co = v.add_parser("co_rues_companies", parents=[g()],
+                       help="Colombian business registry master (RUES via datos.gov.co Socrata; --where SoQL)",
+                       description="RUES registro mercantil master, 9.4M rows: matricula registry key x NIT tax id x CIIU industry x legal form x representante_legal name edge; base filter keeps NIT-identified (tax entity) rows only — persona natural rows whose id columns are cedulas stay out of the face, and the RL cedula-number column is stripped (names kept)")
+    f_co.add_argument("--where", default=None,
+                     help="Raw SoQL filter (upstream param: $where; merged with base filter clase_identificacion='NIT' by AND)")
+    f_co.add_argument("--limit", type=int, default=20, help="Rows per page (upstream param: $limit; 1-500 our politeness cap)")
+    f_co.add_argument("--offset", type=int, default=0, help="Row offset (upstream param: $offset; >=0)")
+    f_co.add_argument("--order", default=None, help="Order clause (upstream param: $order; column [ASC|DESC], no NULLS syntax)")
+    f3 = v.add_parser("fdic_institutions", parents=[g()],
+                      help="US insured-bank master record (FDIC BankFind; --search/--filters raw channels)",
+                      description="FDIC institutions: ES search × structured filters are combinable raw channels (search 'NAME:\"…\"' / filters 'CERT:n'); no upstream limit wall (10,000 verified)")
+    f3.add_argument("--search", default=None, help="ES full-text (upstream param: search; e.g. 'NAME:\"First National\" AND ST:TX')")
+    f3.add_argument("--filters", default=None, help="Structured filter (upstream param: filters; e.g. 'CERT:628' or 'ST:TX AND CITY:Dallas')")
+    f3.add_argument("--limit", type=int, default=5, help="Rows to return (upstream param: limit; no wall verified ≤10000, default 5)")
+    f4 = v.add_parser("fi_ytj_companies", parents=[g()],
+                       help="Finnish business register records (PRH YTJ v3; --name search XOR --business-id direct)",
+                       description="YTJ v3 companies: name contains-match hits historical/branch names; businessId direct lookup; pagination params are silently ignored upstream — fixed ~63-row pages, totalResults is the real total")
+    f4.add_argument("--name", default=None, help="Company name (upstream param: name; contains-match incl. historical names)")
+    f4.add_argument("--business-id", dest="business_id", default=None,
+                     help="Business id, 0194099-3 form (upstream param: businessId; spaces ok)")
+    # —— 0.3.4 FR annuaire realtime search face (recherche-entreprises) ——
+    # —— 0.3.4 FR annuaire realtime search face (recherche-entreprises) ——
+    f5 = v.add_parser("fr_recherche_search", parents=[g()],
+                       help="French registry aggregate search (annuaire-entreprises; --q name/officer-name/SIREN)",
+                       description="etalab recherche-entreprises: one q for company name, officer name (cross-company mandate search) or SIREN direct lookup; rich rows with dirigeants (person + corporate slots), finances, tva; etat_administratif A=active/C=ceased true filter")
+    f5.add_argument("--q", required=True,
+                     help="Query: company name / officer name / SIREN (upstream param: q; name search hits historical names, officer names give cross-company mandates)")
+    f5.add_argument("--page", type=int, default=None, help="Page, 1-based (upstream param: page; walk while page<=total_pages)")
+    f5.add_argument("--per-page", dest="per_page", type=int, default=10,
+                     help="Rows per page (upstream param: per_page; hard wall 1-25 upstream-verified, default 10)")
+    f5.add_argument("--etat-administratif", dest="etat_administratif", default=None,
+                     help="Lifecycle filter (upstream param: etat_administratif; A=active, C=ceased — true filter, ceased rows carry date_fermeture)")
+    f6 = v.add_parser("gb_contracts_finder_published_notices", parents=[g()],
+                       help="UK below-threshold contracts (Contracts Finder OCDS; bare dates legal here)",
+                       description="Sub-threshold UK contracts: publishedFrom/publishedTo are bare dates (opposite of FTS); no window → our rolling 7-day default (upstream returns empty without one); --stages filters tender|award (upstream 400 self-validates); --name = client-side contains filter")
+    f6.add_argument("--name", default=None, help="Company name — client-side contains filter (no upstream name-search param exists)")
+    f6.add_argument("--stages", default=None,
+                     help="OCDS stage filter (upstream param: stages; tender|award — invalid → upstream 400 self-describing; absent = mixed feed; 0.2.9 audit)")
+    f6.add_argument("--published-from", dest="published_from", default=None,
+                     help="Window start YYYY-MM-DD, bare (upstream param: publishedFrom; default 7 days back)")
+    f6.add_argument("--published-to", dest="published_to", default=None,
+                     help="Window end YYYY-MM-DD, bare (upstream param: publishedTo; default today)")
+    f6.add_argument("--limit", type=int, default=10, help="Rows (upstream param: limit; 1-100; with --name = matches cap, fetch stays 100)")
+    f6.add_argument("--cursor", default=None, help="Pagination cursor (upstream param: cursor; pass the same window when walking)")
+    f7 = v.add_parser("gb_fts_release_packages", parents=[g()],
+                       help="UK above-threshold tenders (Find a Tender OCDS; upstream has no name-search param)",
+                       description="WTO-line UK procurement releases: stages/limit/cursor/updatedFrom/updatedTo upstream-verbatim; --name is a client-side contains filter (forces fetch of the full 100-row page, matches buyer or suppliers)")
+    f7.add_argument("--name", default=None, help="Company name — client-side contains filter (no upstream name-search param exists)")
+    f7.add_argument("--stages", default="award", help="OCDS stage (upstream param: stages; award|tender, default award)")
+    f7.add_argument("--limit", type=int, default=10, help="Rows (upstream param: limit; 1-100; with --name = matches cap, fetch stays 100)")
+    f7.add_argument("--cursor", default=None, help="Pagination cursor (upstream param: cursor; feed next_cursor)")
+    f7.add_argument("--updated-from", dest="updated_from", default=None,
+                     help="Window start YYYY-MM-DD or full ISO datetime (upstream param: updatedFrom; bare date gets T00:00:00Z)")
+    f7.add_argument("--updated-to", dest="updated_to", default=None,
+                     help="Window end (upstream param: updatedTo; bare date gets T23:59:59Z)")
+    f8 = v.add_parser("gleif_direct_parent", parents=[g()],
+                      help="LEI→direct parent (GLEIF dedicated endpoint)",
+                      description="Direct parent card; 404 = honestly no parent (not an error)")
+    f8.add_argument("--lei", required=True, help="LEI, 20 chars ISO 17442 (upstream path param: lei)")
+    f9 = v.add_parser("gleif_lei_records", parents=[g()],
+                      help="LEI→entity profile (GLEIF single-record face)",
+                      description="Legal Entity Identifier → entity card (legal name, status, jurisdiction, registration; "
+                                  "+ successor LEIs (M&A edge), expiration, legal form, BIC/MIC)")
+    f9.add_argument("--lei", required=True, help="LEI, 20 chars ISO 17442 (upstream path param: lei)")
+    f10 = v.add_parser("gleif_lei_records_search", parents=[g()],
+                      help="Company name→LEI candidates (GLEIF legalName contains; --filter-entity-jurisdiction/--filter-entity-status narrow)",
+                      description="Name → LEI candidates (non-authoritative; verify with gleif_lei_records before persisting); "
+                                  "jurisdiction/status filters and page[number] walking upstream-verbatim; rows carry registered_as (cross-registry join key)")
+    f10.add_argument("--filter-entity-legal-name", dest="filter_entity_legal_name", required=True,
+                    help="Company name (upstream param: filter[entity.legalName], bracket-transcribed)")
+    f10.add_argument("--filter-entity-jurisdiction", dest="filter_entity_jurisdiction", default=None,
+                    help="Jurisdiction filter (upstream param: filter[entity.jurisdiction]; ISO 3166 country or region code, e.g. CH or US-MO — probed US-MO→1 hit; jurisdictionCountry is whitelist-rejected upstream, not mirrored)")
+    f10.add_argument("--filter-entity-status", dest="filter_entity_status", default=None,
+                    help="Entity status filter (upstream param: filter[entity.status]; ACTIVE/INACTIVE/NULL — entity lifecycle, not registration.status ISSUED/LAPSED/RETIRED)")
+    f10.add_argument("--page-number", dest="page_number", type=int, default=None,
+                    help="Page, 1-based (upstream param: page[number]; walk while page ≤ result page.lastPage)")
+    f10.add_argument("--page-size", dest="page_size", type=int, default=10,
+                    help="Candidates cap (upstream param: page[size]; 1-200 hard wall, default 10)")
+    f11 = v.add_parser("gleif_ultimate_parent", parents=[g()],
+                       help="LEI→ultimate parent (GLEIF dedicated endpoint)",
+                       description="Ultimate parent card (top of the control chain); 404 = honestly no parent (not an error)")
+    f11.add_argument("--lei", required=True, help="LEI, 20 chars ISO 17442 (upstream path param: lei)")
+    f_kr = v.add_parser("kr_hometax_biz_status", parents=[g()],
+                       help="Korean biz registration status, single lookup (hometax 휴폐업/과세유형; --biz-no)",
+                       description="NTS hometax anonymous single-BRN status: four states all legal answers — active (일반/간이/과세특례 taxpayer), closed (ISO closure date extracted), unregistered (result=S, not an error), error; txprNm is always null upstream (no owner-name leak)")
+    f_kr.add_argument("--biz-no", dest="biz_no", required=True,
+                     help="10-digit business registration number (사업자등록번호; 3-2-5 hyphens optional, e.g. 124-81-00998)")
+    f12 = v.add_parser("no_brreg_enheter", parents=[g()],
+                       help="Norwegian registry master record (Enhetsregisteret; --navn search XOR --organisasjonsnummer single)",
+                       description="Brønnøysund Enhetsregisteret: navn search with HAL pagination (page/size, 0-based) or orgnr single record; navn is the Norwegian upstream param (?name= 400s)")
+    f12.add_argument("--navn", default=None, help="Name search (upstream param: navn — Norwegian, not 'name')")
+    f12.add_argument("--organisasjonsnummer", dest="organisasjonsnummer", default=None,
+                     help="9-digit org number (upstream path param; spaces ok)")
+    f12.add_argument("--page", type=int, default=0, help="Page, 0-based (upstream param: page; search face only)")
+    f12.add_argument("--size", type=int, default=20, help="Rows per page (upstream param: size; 1-100 our politeness cap)")
+    f13 = v.add_parser("no_brreg_roller", parents=[g()],
+                       help="Norwegian registry roles by org number (Enhetsregisteret /roller)",
+                       description="Role groups (DAGL CEO / STYR board / REVI auditor): persons carry name+birth date (no national id in the public face), corporate roles (auditors) carry org number; avregistrert=true = retired")
+    f13.add_argument("--organisasjonsnummer", dest="organisasjonsnummer", required=True,
+                     help="9-digit org number (upstream path param; spaces ok)")
+    f14 = v.add_parser("ror_organizations", parents=[g()],
+                      help="Research-org record (ROR v2; --query search XOR --ror-id single record)",
+                      description="Research Organization Registry: query → candidates (fixed 20/page, --page walks), or ror_id → authoritative single record")
+    f14.add_argument("--query", default=None, help="Org name search (upstream param: query)")
+    f14.add_argument("--ror-id", dest="ror_id", default=None, help="ROR id, 0+8 chars (upstream path: /organizations/{id}; bare or full URL)")
+    f14.add_argument("--page", type=int, default=None, help="Page number for --query (upstream param: page; fixed 20 rows/page)")
+    f14.add_argument("--all-status", dest="all_status", action="store_true", default=None,
+                    help="Include inactive/withdrawn orgs (upstream param: all_status; default upstream=false hides them — 0.2.9 audit)")
+    f15 = v.add_parser("sec_fulltext_search", parents=[g()],
+                       help="SEC filing full-text search 2001+ (EDGAR FTS)",
+                       description="EDGAR full-text search: q/forms/startdt/enddt upstream-verbatim; a single date end is auto-completed (silently ignored upstream), dateRange=custom always two-ended; total_relation gte = capped at 10k")
+    f15.add_argument("--q", required=True, help="Query term (upstream param: q; EDGAR FTS syntax)")
+    f15.add_argument("--forms", default=None, help="Form-type filter (upstream param: forms; e.g. 8-K,10-K)")
+    f15.add_argument("--startdt", default=None, help="Start date YYYY-MM-DD (upstream param: startdt; single end auto-completed to 2001-01-01)")
+    f15.add_argument("--enddt", default=None, help="End date YYYY-MM-DD (upstream param: enddt; single end auto-completed to today)")
+    f15.add_argument("--limit", type=int, default=10, help="Rows to return (client-side slice of the 100-hit page; ≤100)")
+    f16 = v.add_parser("sec_submissions", parents=[g()],
+                      help="SEC CIK→registrant card (data.sec.gov submissions)",
+                      description="Registrant identity card: legal/former names, tickers·exchanges, EIN, SIC, filing totals (accepts bare/zero-padded/CIK-prefixed input)")
+    f16.add_argument("--cik", required=True, help="CIK, 1-10 digits (upstream path param: CIK{cik10}.json)")
+    f17 = v.add_parser("ted_notices_search", parents=[g()],
+                      help="EU procurement notices (TED v3 expert search; --query expert syntax)",
+                      description="Tenders Electronic Daily: expert-syntax query via --query (e.g. 'organisation-name-buyer=Siemens* AND organisation-country-buyer=DEU' / classification-cpv=33100000); limit 1-250 is an upstream hard wall")
+    f17.add_argument("--query", required=True, help="Expert syntax (upstream param: query; trailing wildcard = prefix match; buyer facets organisation-name-buyer / organisation-country-buyer, CPV via classification-cpv)")
+    f17.add_argument("--fields", default=None, help="Comma list of eForms fields (upstream param: fields; wrong names 400 with the full 1,833-field dump)")
+    f17.add_argument("--limit", type=int, default=10, help="Notices per page (upstream param: limit; 1-250 hard wall, default 10)")
+    f17.add_argument("--page", type=int, default=1, help="Page number (upstream param: page)")
+    f18 = v.add_parser("usaspending_spending_by_award", parents=[g()],
+                      help="US federal awards by recipient (USAspending spending_by_award POST)",
+                      description="Federal contracts/grants: recipient name (array upstream, scalar auto-wrapped); award-type codes, time window (single end auto-completed), fields all upstream-verbatim")
+    f18.add_argument("--recipient-search-text", dest="recipient_search_text", required=True,
+                    help="Recipient name (upstream param: recipient_search_text; array semantics — scalar auto-wrapped)")
+    f18.add_argument("--award-type-codes", dest="award_type_codes", default=None,
+                    help="Comma list (upstream param: award_type_codes; default A,B,C,D contracts — grants 02/03 etc.)")
+    f18.add_argument("--start-date", dest="start_date", default=None,
+                    help="Window start YYYY-MM-DD (upstream param: time_period[].start_date; single end auto-completed)")
+    f18.add_argument("--end-date", dest="end_date", default=None,
+                    help="Window end YYYY-MM-DD (upstream param: time_period[].end_date; single end auto-completed)")
+    f18.add_argument("--fields", default=None, help="Comma list of columns (upstream param: fields; default 6 columns)")
+    f18.add_argument("--limit", type=int, default=10, help="Rows per page (upstream param: limit; 1-100, default 10)")
+    f18.add_argument("--page", type=int, default=1, help="Page number (upstream param: page; walk while has_more)")
+    f18.add_argument("--subawards", action=argparse.BooleanOptionalAction, default=False,
+                    help="Include subawards (upstream param: subawards; default off)")
+    f19 = v.add_parser("vies_vat", parents=[g()],
+                      help="EU VAT number check (VIES; INVALID is a valid answer)",
+                      description="Official EU VAT validation: member-state prefixed number; INVALID → ok:true with valid=false; '---' masking → null (not missing data)")
+    f19.add_argument("--vat", required=True, help="VAT with member-state prefix (upstream path: /ms/{cc}/vat/{number}; e.g. DE811907980)")
+    # —— 0.3.3 European country registry realtime faces (CH Zefix / NO Brreg / FI YTJ) ——
+
+FLAT = {
+    # company 0.2.0 flat panel (upstream params under original names + our defaults; the lambda only ferries names across namespaces)
+    "ch_zefix_firm": lambda a: {"ehraid": a.ehraid},
+    # 0.3.3 European country registry realtime faces (five)
+    "ch_zefix_firm_search": lambda a: {"name": a.name, "max_entries": a.max_entries, "offset": a.offset},
+    # 0.3.11 CO RUES + KR hometax dual-country batch
+    "co_rues_companies": lambda a: {"where": a.where, "limit": a.limit, "offset": a.offset,
+                          "order": a.order},
+    "fdic_institutions": lambda a: {"search": a.search, "filters": a.filters,
+                            "limit": a.limit},
+    "fi_ytj_companies": lambda a: {"name": a.name, "business_id": a.business_id},
+    "fr_recherche_search": lambda a: {"q": a.q, "page": a.page, "per_page": a.per_page,
+                            "etat_administratif": a.etat_administratif},
+    "gb_contracts_finder_published_notices": lambda a: {"name": a.name, "published_from": a.published_from,
+                                      "published_to": a.published_to, "stages": a.stages,
+                                      "limit": a.limit, "cursor": a.cursor},
+    "gb_fts_release_packages": lambda a: {"name": a.name, "stages": a.stages, "limit": a.limit,
+                                 "cursor": a.cursor, "updated_from": a.updated_from,
+                                 "updated_to": a.updated_to},
+    "gleif_direct_parent": lambda a: {"lei": a.lei},
+    "gleif_lei_records": lambda a: {"lei": a.lei},
+    "gleif_lei_records_search": lambda a: {"filter_entity_legal_name": a.filter_entity_legal_name,
+                                           "page_size": a.page_size,
+                                           "filter_entity_jurisdiction": a.filter_entity_jurisdiction,
+                                           "filter_entity_status": a.filter_entity_status,
+                                           "page_number": a.page_number},
+    "gleif_ultimate_parent": lambda a: {"lei": a.lei},
+    "kr_hometax_biz_status": lambda a: {"biz_no": a.biz_no},
+    "no_brreg_enheter": lambda a: {"navn": a.navn, "organisasjonsnummer": a.organisasjonsnummer,
+                          "page": a.page, "size": a.size},
+    "no_brreg_roller": lambda a: {"organisasjonsnummer": a.organisasjonsnummer},
+    "ror_organizations": lambda a: {"query": a.query, "ror_id": a.ror_id, "page": a.page,
+                                    "all_status": a.all_status},
+    "sec_fulltext_search": lambda a: {"q": a.q, "forms": a.forms, "startdt": a.startdt,
+                          "enddt": a.enddt, "limit": a.limit},
+    "sec_submissions": lambda a: {"cik": a.cik},
+    "ted_notices_search": lambda a: {"query": a.query,
+                              "fields": a.fields, "limit": a.limit, "page": a.page},
+    "usaspending_spending_by_award": lambda a: {"recipient_search_text": a.recipient_search_text,
+                                     "award_type_codes": a.award_type_codes,
+                                     "start_date": a.start_date, "end_date": a.end_date,
+                                     "fields": a.fields, "limit": a.limit, "page": a.page,
+                                     "subawards": a.subawards},
+    "vies_vat": lambda a: {"vat": a.vat},
+}
+
+
+# 0.3.10 jurisdiction chapter: face → jurisdiction (default = the issuing authority's jurisdiction; bodies
+# covering global phenomena = GLOBAL; vocabulary = ISO-3166 alpha-2 + EU + GLOBAL) — merged into _JURISDICTION by the root cli.py; success envelopes carry the jurisdiction chapter
+COUNTRY = {
+    "ch_zefix_firm": "CH",
+    "ch_zefix_firm_search": "CH",
+    "co_rues_companies": "CO",
+    "fdic_institutions": "US",
+    "fi_ytj_companies": "FI",
+    "fr_recherche_search": "FR",
+    "gb_contracts_finder_published_notices": "GB",
+    "gb_fts_release_packages": "GB",
+    "gleif_direct_parent": "GLOBAL",
+    "gleif_lei_records": "GLOBAL",
+    "gleif_lei_records_search": "GLOBAL",
+    "gleif_ultimate_parent": "GLOBAL",
+    "kr_hometax_biz_status": "KR",
+    "no_brreg_enheter": "NO",
+    "no_brreg_roller": "NO",
+    "ror_organizations": "GLOBAL",
+    "sec_fulltext_search": "US",
+    "sec_submissions": "US",
+    "ted_notices_search": "EU",
+    "usaspending_spending_by_award": "US",
+    "vies_vat": "EU",
+}

agentdata/company/co_rues.py

@@ -0,0 +1,72 @@
+"""co_rues — Colombia RUES commercial-registry master provider (datos.gov.co Socrata; keyless).
+
+company roster (admitted in 0.3.11, probe tmp/probe-co-kr/; harvest-side recipe in the co-rues-socrata volume).
+Shape verified 2026-10-30: GET /resource/c82u-588k.json?$limit= → array straight out (9,436,330-row corpus,
+36 columns — Socrata omits null fields per row: natural-person rows carry no NIT/RL columns, legal-entity
+rows surface the three-column RL family).
+Company-row key and profile: matricula (camara x matricula registry key) + numero_identificacion
+(rows with clase_identificacion='NIT' = corporate tax id NIT) + digito_verificacion check digit +
+razon_social + CIIU primary/secondary industries (cod_ciiu_act_econ_pri/sec) + tipo_sociedad/
+organizacion_juridica two-level legal form + estado_matricula/fecha_cancelacion status family +
+representante_legal (officer-name edge — names in a public registry are collectable, no_brreg roller precedent).
+
+**PII double gate (red line, pinned by the 2026-10-30 probe)**: (1) default base filter
+clase_identificacion='NIT' — on persona natural rows numero_identificacion equals the nit column
+= cedula personal id (observed 7174354); the company-domain face admits tax-entity rows only
+(the user where is AND-merged with the base filter, parentheses preserve the user expression);
+(2) row shaping strips num_identificacion_representante_legal (the RL's cedula number) —
+the name is kept, the number is not collected. Sole-proprietor bulk needs go through the harvest
+bulk line (api/views rows.csv has no Range), not this face.
+Licence CC-BY-SA (contagious — site redistribution on its own rail; the SDK query face is not restricted).
+
+Socrata $-param verbatim channel (same contract as ny_open_data/secop): $where raw SoQL passthrough /
+$limit 1-500 / $offset>=0 / $order rejects NULLS; no total echo, none faked (corpus count probed
+separately via $select=count).
+TTL: registry master changes slowly — 7 days; politeness 1 rps (conservative tier for anonymous Socrata).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "co_rues",
+    "baseUrl": "https://www.datos.gov.co",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "companies": {"path": "/resource/c82u-588k.json"},  # Socrata $limit/$offset/$where/$order
+    },
+    "ttl": {"companies": 7 * 86400},
+}
+
+# PII red-line columns: RL (legal representative) cedula number — name columns kept, number columns always stripped
+_RL_ID_COLUMNS = ("num_identificacion_representante_legal",)
+
+# Default base filter: tax-entity rows only (clase_identificacion='NIT') — on persona natural rows
+# numero_identificacion/nit = cedula personal id; the company-domain face does not admit them (PII gate one of two)
+_BASE_FILTER = "clase_identificacion='NIT'"
+
+
+def _strip_pii(row):
+    for col in _RL_ID_COLUMNS:
+        row.pop(col, None)
+    return row
+
+
+def companies_raw(where=None, *, limit=20, offset=0, order=None, cache=None, no_cache=False):
+    """→ {rows[], count, limit_applied, params, _meta} (Socrata echoes no total; RL number column stripped from rows)."""
+    from ..transport import call_provider
+
+    size = int(limit) if limit is not None else 20  # explicit None check — 0 swallowed by or is the 0.2.10-style pit
+    if not 1 <= size <= 500:
+        raise SdkError("usage_error", provider="co_rues",
+                       detail=f"limit must be 1-500 (politeness cap), got {limit!r}")
+    off = int(offset) if offset is not None else 0
+    if off < 0:
+        raise SdkError("usage_error", provider="co_rues", detail=f"offset must be >=0, got {offset!r}")
+    w = str(where or "").strip() or None
+    merged = f"({w}) and {_BASE_FILTER}" if w else _BASE_FILTER  # base filter AND-merged (parentheses preserve the user expression)
+    params = {"$limit": size, "$offset": off, "$where": merged}
+    o = str(order or "").strip() or None
+    if o:
+        params["$order"] = o
+    r = call_provider(provider, "companies", params, cache=cache, no_cache=no_cache)
+    data = [_strip_pii(x) for x in (r["data"] or [])]
+    return {"rows": data, "count": len(data), "limit_applied": size, "params": params, "_meta": r}

agentdata/company/edgar_cik.py

@@ -0,0 +1,84 @@
+"""edgar_cik — SEC EDGAR submissions (CIK → registrant identity card; keyless).
+
+data.sec.gov/submissions/CIK##########.json — same source as edgar_fts, different face: FTS handles search,
+this file handles normalization (fulltext hits resolve via ciks[0] here; ticker/LEI→CIK closes at the same door).
+Official fair-access policy caps at 10 req/s and requires a UA — we set 5 rps/burst 5 (0.2.7 realignment: the old
+5/10 worst case was 15>10 in a 1s window, an lda-type violation; quota semantics 5+5=10≤10 stay inside; as with
+edgar_fts, the UA is attached uniformly by the transport layer).
+Field-value findings confirmed by probing (2026-10-22): business state key = stateOrCountry, not state (the old
+read of state made the US state permanently null — Apple=CA was the confirmed live failure); foreign-address state
+semantics lives in foreignStateTerritory (Shell plc=DC); ein '000000000' = foreign issuer without EIN sentinel;
+person-face empty-string values (sic/category/stateOfIncorporation '') normalize to null; entityType has only the
+two values {operating, other} — natural persons (Musk) are also other, not a distinct value.
+P1-1 port (2026-10-22): full business key table (three live entities) = street1/street2/city/stateOrCountry/zipCode/
+stateOrCountryDescription/isForeignLocation/foreignStateTerritory/country/countryCode — state code and readable name
+are two parallel slots (ASML P7→Netherlands; Apple CA→CA; foreign rows fall back to the readable country name
+country=United Kingdom; the country key is kept, not always null); filings_total = recent + files[].filingCount
+(recent is always truncated at the top).
+CIK input tolerance: bare digits / leading zeros / the "CIK0000320193" prefix are all accepted (non-digits stripped,
+then padded to 10).
+"""
+import re
+
+provider = {
+    "id": "edgar-cik",
+    "baseUrl": "https://data.sec.gov",
+    "rate": {"rps": 5, "burst": 5},  # quota semantics at the line: 5+5×1s=10≤SEC 10/s (0.2.7 realignment)
+    "ops": {
+        "submissions": {"path": "/submissions/CIK{cik10}.json", "notFound": [404]},
+    },
+    "ttl": {"submissions": 7 * 86400},
+}
+
+
+def normalize_cik(value) -> str:
+    """→ 10-digit zero-padded CIK (parity with Node normalizeCik; non 1-10 digit number → usage_error)."""
+    from ..errors import SdkError
+
+    digits = re.sub(r"\D+", "", str(value if value is not None else ""))
+    if not digits or len(digits) > 10:
+        raise SdkError("usage_error", provider="edgar-cik",
+                       detail=f"CIK must be 1-10 digits (got \"{value}\")")
+    return digits.zfill(10)
+
+
+def card_from_upstream(d, cik10):
+    """Identity card pure mapping (split out for offline testing; key-name fixes and sentinel normalization live in this layer)."""
+    recent = (d.get("filings") or {}).get("recent") or {}
+    biz = (d.get("addresses") or {}).get("business")
+    return {
+        "cik": d.get("cik") or cik10,
+        "name": d.get("name"),
+        "entity_type": d.get("entityType"),
+        "tickers": d.get("tickers") or [],
+        "exchanges": d.get("exchanges") or [],
+        "ein": d.get("ein") if d.get("ein") and d.get("ein") != "000000000" else None,  # foreign sentinel→null
+        "sic": ({"code": d["sic"], "description": d.get("sicDescription") or None}
+                if d.get("sic") else None),  # person face sic='' is falsy → None
+        "filer_category": d.get("category") or None,
+        "state_of_incorporation": d.get("stateOfIncorporation") or None,  # empty string → None
+        "fiscal_year_end": d.get("fiscalYearEnd"),  # MMDD format (Apple '0926') kept upstream-verbatim
+        "former_names": [{"name": f.get("name"),
+                          "from": (f.get("from") or "")[:10], "to": (f.get("to") or "")[:10]}
+                         for f in (d.get("formerNames") or [])],
+        "business_address": ({"city": biz.get("city"),
+                              "state_or_country": biz.get("stateOrCountry") or biz.get("foreignStateTerritory"),  # code slot: CA/P7; foreign state semantics = foreignStateTerritory (Shell=DC)
+                              "state_or_country_name": biz.get("stateOrCountryDescription") or biz.get("country"),  # readable-name slot: CA/Netherlands; foreign rows fall back to the country name (United Kingdom)
+                              "country": biz.get("country")} if biz else None),  # only present for foreign addresses (2026-10-22 live check: Shell carries a real value, do not remove)
+        "recent_filings_count": len(recent.get("form") or []),
+        "filings_total": (len(recent.get("form") or [])
+                          + sum(int(f.get("filingCount") or 0)
+                                for f in ((d.get("filings") or {}).get("files") or []))),  # recent is always truncated at ~1000, history pagination lives in files[].filingCount — the two numbers must not be mixed
+        "last_filing_date": (recent.get("filingDate") or [None])[0],  # recent arrays are newest-first
+    }
+
+
+def lookup_cik(value, *, cache=None, no_cache=False):
+    """→ registrant identity card (legal/former names, tickers·exchanges, EIN, SIC industry, filer category, address)."""
+    from ..transport import call_provider
+
+    cik10 = normalize_cik(value)
+    r = call_provider(provider, "submissions", {"cik10": cik10}, cache=cache, no_cache=no_cache)
+    out = card_from_upstream(r["data"] or {}, cik10)
+    out["_meta"] = r
+    return out

agentdata/company/edgar_fts.py

@@ -0,0 +1,101 @@
+"""edgar_fts — SEC EDGAR Full-Text Search (2001+ full-text filing search; keyless).
+
+Official fair-access policy caps at 10 req/s and requires a UA — we set 5 rps/burst 5 (0.2.7 realignment: the old
+5/10 worst case was 15>10 in a 1s window, an lda-type violation; quota semantics 5+5=10≤10; the UA is attached
+uniformly by the transport layer).
+First case of the "full-text search exception": we do not build a local terabyte-scale inverted index and instead
+lean on the official compute as an external read-only FTS face.
+Live-shape check:
+hits.hits[]{_id="adsh:file", _source{adsh,ciks[],display_names[],root_forms[],file_date,form}}.
+Date-range pitfall (probed live 2026-10-20): upstream applies dateRange=custom only when startdt AND enddt are
+both given — a single end is silently ignored (tell-tale signs: total pinned at 10000 + relation:"gte" + out-of-range
+file_date with ok:true) — so if either end is given the other is filled in (missing startdt → corpus start 2001-01-01,
+missing enddt → today); date_range echoes the window actually in effect.
+"""
+import re
+
+provider = {
+    "id": "edgar-fts",
+    "baseUrl": "https://efts.sec.gov",
+    "rate": {"rps": 5, "burst": 5},  # quota semantics at the line: 5+5×1s=10≤SEC 10/s (0.2.7 realignment)
+    "ops": {
+        "search": {"path": "/LATEST/search-index"},  # params: q, forms, startdt, enddt, dateRange (assembled query)
+    },
+    "ttl": {"search": 24 * 3600},  # new filings keep landing, a search page stays valid for a day
+}
+
+_TAIL_PARENS = re.compile(r"(\s*\([^()]*\))+\s*$")
+
+
+def clean_display_name(v):
+    """Strip the parenthesized tail noise from upstream display_names[0] ('NAME  (TICKER)  (CIK ##########)' → 'NAME').
+
+    Double spaces + a CIK tail that duplicates the cik field already in the card; mid-string parentheses such as
+    'X (formerly Y) Inc.' are left untouched."""
+
+    if not isinstance(v, str):
+        return v if v is not None else None
+    cleaned = _TAIL_PARENS.sub("", v).strip()
+    return cleaned or v
+
+
+def search_fulltext(q, *, forms=None, startdt=None, enddt=None, limit=10, cache=None, no_cache=False):
+    """→ {total, total_relation, hits[], date_range, _meta}; hit.adsh directly composes the accession key shared with the SEC corpus line, doc_url points at the human-readable original.
+    total_relation:"gte" = upstream truncation (≥ ten thousand, not an exact value), "eq" = exact; date_range=None means no date window was enabled."""
+    from ..transport import call_provider
+    from ..errors import SdkError
+
+    query = str(q or "").strip()
+    if not query:
+        raise SdkError("usage_error", provider="edgar-fts", detail="fulltext requires --q")
+    params = {"q": query}
+    if forms:
+        params["forms"] = str(forms)  # form-type filter is decoupled from the date window (forms no longer triggers dateRange)
+    date_range = None
+    if startdt or enddt:  # fill the missing end: a single end is silently ignored upstream, both ends are required
+        from ..daterange import resolve as _range
+        _start, _end, date_range = _range(startdt, enddt, default_start="2001-01-01",
+                                          provider=provider["id"])
+        params["startdt"], params["enddt"] = _start, _end
+        params["dateRange"] = "custom"
+    r = call_provider(provider, "search", params, cache=cache, no_cache=no_cache)
+    hits = ((r["data"] or {}).get("hits") or {}).get("hits") or []
+    cap = min(max(1, int(limit) or 10), 100)
+    rows = []
+    for h in hits[:cap]:
+        s = h.get("_source") or {}
+        cik = (s.get("ciks") or [None])[0]
+        _id = h.get("_id") or ""
+        file = _id.split(":")[1] if ":" in _id else None
+        adsh = s.get("adsh") or (_id.split(":")[0] if _id else None)
+        rows.append({
+            "adsh": adsh,  # accession number — same key as the SEC corpus line
+            "cik": cik,
+            "company": clean_display_name((s.get("display_names") or [None])[0]),  # strip the (TICKER)(CIK) parenthesized tail
+            "form_type": s.get("form") or (s.get("root_forms") or [None])[0],
+            "file_date": s.get("file_date"),
+            "period_ending": s.get("period_ending"),
+            "doc_url": (f"https://www.sec.gov/Archives/edgar/data/{int(cik)}/{adsh.replace('-', '')}/{file}"
+                        if cik and adsh and file else None),
+        })
+    total_obj = (((r["data"] or {}).get("hits") or {}).get("total") or {})
+    total = total_obj.get("value")
+    return {"total": total if total is not None else len(rows),
+            "total_relation": total_obj.get("relation"),  # gte=truncated (≥ ten thousand), not an exact value
+            "hits": rows, "limit_applied": cap, "date_range": date_range, "_meta": r}  # cap = client-side slice size, truncation must stay visible
+
+
+def search_raw(q, *, forms=None, startdt=None, enddt=None, limit=10, cache=None, no_cache=False):
+    """→ {total, total_relation, hits[], limit_applied, date_range, params, _meta}; the four params pass through verbatim.
+    params = the actually sent query-string keys (q/forms/startdt/enddt[/dateRange=custom]) — after end completion both ends are always present (a single end is
+    silently ignored upstream, measured 2026-10-20), date_range echoes the window actually in effect; the echo is replayable."""
+    r = search_fulltext(q, forms=forms, startdt=startdt, enddt=enddt,
+                        limit=limit, cache=cache, no_cache=no_cache)
+    params = {"q": str(q).strip()}
+    if forms:
+        params["forms"] = str(forms)
+    if r["date_range"]:
+        params["startdt"] = r["date_range"]["startdt"]
+        params["enddt"] = r["date_range"]["enddt"]
+        params["dateRange"] = "custom"
+    return {**r, "params": params}