agentdata 0.3.26__py3-none-any.whl

agentdata/procurement/br_pncp.py

@@ -0,0 +1,126 @@
+"""br_pncp — Brazil national procurement portal contract face provider (pncp.gov.br /api/consulta;
+operated by Serpro, keyless).
+
+procurement domain (0.3.0 founding; admitted 2026-10-29, probed). Shape measured 2026-10-29:
+GET /api/consulta/v1/contratos?dataInicial=20260901&dataFinal=20260930&pagina=1[&cnpjOrgao=…]
+  → {data:[…500 rows…], totalRegistros, totalPaginas, numeroPagina, paginasRestantes, empty}
+  — the SpringDoc spec is public (/v3/api-docs): dataInicial/dataFinal/pagina are required,
+  cnpjOrgao is an optional buyer filter; tamanhoPagina is a trap, do not invent it (the default
+  500 is fine — the spec has the parameter but a self-made value 400s).
+Row-level golden fields (2026-09 single-month window: 175,533 contracts over 352 pages, measured):
+  orgaoEntidade.cnpj×razaoSocial (buyer) × niFornecedor+nomeRazaoSocialFornecedor (supplier)
+  × the four amount columns valorInicial/Parcela/Global/Acumulado × dataAssinatura/Vigencia family
+  × numeroControlePNCP as the stable key × objetoContrato full text × esfera (federal/state/municipal)
+  × the subcontracting field family.
+PII red line (precedent: fda_crl): on tipoPessoa=PF rows the niFornecedor (CPF) and the
+supplier's personal name are not returned — set to None + fornecedorMascarado:true stated
+explicitly; tipoPessoa=PJ (incl. MEI) is returned as upstream has it (CNPJ = public business
+registry key).
+Date format: compact YYYYMMDD (the dashed YYYY-MM-DD form is accepted and normalized to
+compact before sending — both forms measured 200 on 2026-10-29).
+TTL: contract-window history months are stable, recent windows change slowly — 7 days; polite
+tier 1 rps (Serpro publishes no quota, so take the conservative value).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "br_pncp",
+    "baseUrl": "https://pncp.gov.br",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "contracts": {"path": "/api/consulta/v1/contratos"},  # params: dataInicial/dataFinal/pagina (cnpjOrgao optional)
+    },
+    "ttl": {"contracts": 7 * 86400},
+}
+
+
+def _mask_supplier(row, tipo_pessoa, ni_key, nome_key):
+    """PII red line: mask the document number and the personal name on PF (individual) rows;
+    PJ rows are returned as-is. Sets None + an explicit flag (never silent)."""
+    masked = str(tipo_pessoa or "").strip().upper() == "PF"
+    if masked:
+        row[ni_key] = None
+        row[nome_key] = None
+    row["fornecedorMascarado"] = masked
+    return row
+
+
+def contracts_from_upstream(data):
+    """Upstream contratos response → contract rows (pure function, offline-testable; PII masking
+    happens at this layer)."""
+    rows = []
+    for r in (data or {}).get("data") or []:
+        org = r.get("orgaoEntidade") or {}
+        unidade = r.get("unidadeOrgao") or {}
+        row = {
+            "numeroControlePNCP": r.get("numeroControlePNCP"),          # stable key (the portal's contract identifier)
+            "anoContrato": r.get("anoContrato"),
+            "categoria": (r.get("categoriaProcesso") or {}).get("nome"),
+            "tipoContrato": (r.get("tipoContrato") or {}).get("nome"),
+            "orgaoEntidade": {"cnpj": org.get("cnpj"), "razaoSocial": org.get("razaoSocial"),
+                              "esfera": org.get("esferaId"), "poder": org.get("poderId")},
+            "unidadeOrgao": {"uf": unidade.get("ufSigla"), "municipio": unidade.get("municipioNome")},
+            "tipoPessoa": r.get("tipoPessoa"),                          # PJ/PF (PF = supplier is an individual)
+            "niFornecedor": r.get("niFornecedor"),                      # supplier CNPJ/CPF (masked for PF)
+            "nomeRazaoSocialFornecedor": r.get("nomeRazaoSocialFornecedor"),  # supplier name (masked for PF)
+            "valorInicial": r.get("valorInicial"),
+            "valorParcela": r.get("valorParcela"),
+            "valorGlobal": r.get("valorGlobal"),
+            "valorAcumulado": r.get("valorAcumulado"),
+            "dataAssinatura": r.get("dataAssinatura"),
+            "dataVigenciaInicio": r.get("dataVigenciaInicio"),
+            "dataVigenciaFim": r.get("dataVigenciaFim"),
+            "dataPublicacaoPncp": r.get("dataPublicacaoPncp"),
+            "numeroRetificacao": r.get("numeroRetificacao"),
+            "objetoContrato": r.get("objetoContrato"),                  # full text of the contract subject
+        }
+        _mask_supplier(row, r.get("tipoPessoa"), "niFornecedor", "nomeRazaoSocialFornecedor")
+        sub_tipo = r.get("tipoPessoaSubContratada")
+        if sub_tipo or r.get("niFornecedorSubContratado") or r.get("nomeFornecedorSubContratado"):
+            row["subContratado"] = _mask_supplier(
+                {"tipoPessoa": sub_tipo, "niFornecedor": r.get("niFornecedorSubContratado"),
+                 "nomeFornecedor": r.get("nomeFornecedorSubContratado")},
+                sub_tipo, "niFornecedor", "nomeFornecedor")
+        rows.append(row)
+    return {
+        "rows": rows, "count": len(rows),
+        "total": data.get("totalRegistros") if isinstance(data, dict) else None,
+        "total_paginas": data.get("totalPaginas") if isinstance(data, dict) else None,
+        "paginas_restantes": data.get("paginasRestantes") if isinstance(data, dict) else None,
+    }
+
+
+def _norm_date(v, field):
+    s = str(v or "").strip()
+    if len(s) == 10 and s[4] == "-" and s[7] == "-":
+        s = s.replace("-", "")           # YYYY-MM-DD → compact (both forms measured 200, compact is what gets sent)
+    if len(s) != 8 or not s.isdigit():
+        raise SdkError("usage_error", provider="br_pncp",
+                       detail=f"{field} must be YYYYMMDD or YYYY-MM-DD (contract publication-window endpoint), got '{v}'")
+    return s
+
+
+def contracts_raw(data_inicial, data_final, *, pagina=1, cnpj_orgao=None, cache=None, no_cache=False):
+    """→ {rows[], count, total, total_paginas, paginas_restantes, params, _meta}.
+
+    data_inicial/data_final = the publication window (required, upstream names verbatim);
+    pagina pages from 1 (500 rows per page = the upstream default); cnpj_orgao = buyer CNPJ
+    14-digit filter (optional)."""
+    from ..transport import call_provider
+
+    di, df = _norm_date(data_inicial, "data_inicial"), _norm_date(data_final, "data_final")
+    if di > df:
+        raise SdkError("usage_error", provider="br_pncp",
+                       detail=f"data_inicial ({di}) must not be later than data_final ({df})")
+    pg = int(pagina) if pagina is not None else 1
+    if pg < 1:
+        raise SdkError("usage_error", provider="br_pncp", detail=f"pagina must be a page number ≥1, got '{pagina}'")
+    params = {"dataInicial": di, "dataFinal": df, "pagina": pg}
+    orgao = str(cnpj_orgao or "").strip().replace("/", "").replace(".", "").replace("-", "") or None
+    if orgao:
+        if len(orgao) != 14 or not orgao.isdigit():
+            raise SdkError("usage_error", provider="br_pncp",
+                           detail=f"cnpj_orgao must be the buyer's 14-digit CNPJ, got '{cnpj_orgao}'")
+        params["cnpjOrgao"] = orgao
+    r = call_provider(provider, "contracts", params, cache=cache, no_cache=no_cache)
+    return {**contracts_from_upstream(r["data"]), "params": params, "_meta": r}

agentdata/procurement/cli.py

@@ -0,0 +1,155 @@
+"""procurement cli — domain command-face registration (seventh package, stood up in 0.3.0, born flat — no verb layer).
+
+register(v, g): registers flat commands onto the domain subparser (g = root _leaf_globals factory); FLAT = flat dispatch
+table, merged by the root cli for main to use (same shape as the 0.2.6 per-domain split). Face order = lexicographic by
+face name (sorting source of truth = the English identifier).
+"""
+import argparse
+
+def register(v, g):
+    # procurement 0.3.0 founding pair (pncp_contracts/co_secop_contracts) + 0.3.6 World Bank + New York State batch
+    # (wb_proc/ny_open_data; upstream param names mirrored) — all folded in lexicographically by 0.3.10; 0.3.12 collection
+    # round adds the UNGM/NY OGS batch (ungm/ny_open_data) under the same law; 0.3.13 ISO country-prefix machine batch
+    # renames pncp_contracts -> br_pncp_contracts and secop_contracts -> co_secop_contracts (provider ids follow the module names)
+
+    f1 = v.add_parser("br_pncp_contracts", parents=[g()],
+                      help="Brazil public-procurement contracts (PNCP, keyless)",
+                      description="Brazil national procurement contracts (Portal Nacional de Contratações Públicas, "
+                                  "keyless): publication-window search over /api/consulta/v1/contratos — every row is "
+                                  "buyer CNPJ × supplier CNPJ with the four valor columns; join straight onto the RFB "
+                                  "register. data_inicial/data_final (YYYYMMDD or YYYY-MM-DD) and pagina are upstream "
+                                  "verbatim (500 rows/page); cnpj_orgao narrows to one buyer. PF (individual) supplier "
+                                  "rows carry their identifier and name masked per the PII rule")
+    f1.add_argument("--data-inicial", required=True, help="Publication-window start (upstream param: dataInicial; YYYYMMDD or YYYY-MM-DD)")
+    f1.add_argument("--data-final", required=True, help="Publication-window end (upstream param: dataFinal)")
+    f1.add_argument("--pagina", type=int, default=1, help="Page number (upstream param: pagina, 1-based; 500 rows/page)")
+    f1.add_argument("--cnpj-orgao", default=None, help="Buyer CNPJ 14-digit filter (upstream param: cnpjOrgao)")
+
+    f2 = v.add_parser("co_secop_contracts", parents=[g()],
+                      help="Colombia SECOP II electronic contracts (keyless)",
+                      description="Colombia SECOP II electronic contracts (datos.gov.co Socrata dataset jbjy-vk9h, "
+                                  "keyless): 5.6M+ contracts — buyer NIT × supplier NIT/CC with the valor family; join "
+                                  "straight onto the RUES register. where is the raw SoQL $where channel (verbatim "
+                                  "pass-through); limit/offset/order mirror $limit/$offset/$order. No total echo — page "
+                                  "with offset. Personal-document (Cédula etc.) supplier rows carry their identifier "
+                                  "and name masked per the PII rule")
+    f2.add_argument("--where", default=None, help="Raw SoQL filter (upstream param: $where; e.g. \"upper(nombre_entidad) like '%%MINISTERIO%%'\")")  # %% escaping: argparse help goes through % interpolation
+    f2.add_argument("--limit", type=int, default=20, help="Rows (upstream param: $limit; 1-500 politeness cap)")
+    f2.add_argument("--offset", type=int, default=0, help="Row offset (upstream param: $offset; Socrata has no total echo)")
+    f2.add_argument("--order", default=None, help="Sort (upstream param: $order; column [ASC|DESC] — no NULLS syntax)")
+
+    f3 = v.add_parser("ny_abo_contracts", parents=[g()],
+                      help="New York State authority contracts (ABO, keyless)",
+                      description="New York State authority contracts (data.ny.gov Socrata dataset ehig-g5x3, "
+                                  "keyless): 275k+ rows from the Authorities Budget Office universe — buyer "
+                                  "authority_name × vendor_name + full address (no UEI/DUNS; name+address walk), "
+                                  "four value columns plus MWBE / NYS-business preference flags. where is the raw SoQL "
+                                  "$where channel; limit/offset/order mirror $limit/$offset/$order. No total echo — "
+                                  "page with offset")
+    f3.add_argument("--where", default=None, help="Raw SoQL filter (upstream param: $where; e.g. \"upper(vendor_name) like '%%DELTA%%'\")")
+    f3.add_argument("--limit", type=int, default=20, help="Rows (upstream param: $limit; 1-500 politeness cap)")
+    f3.add_argument("--offset", type=int, default=0, help="Row offset (upstream param: $offset; Socrata has no total echo)")
+    f3.add_argument("--order", default=None, help="Sort (upstream param: $order; column [ASC|DESC] — no NULLS syntax)")
+
+    f4 = v.add_parser("ny_mta_procurements", parents=[g()],
+                      help="New York MTA procurements (keyless)",
+                      description="New York MTA procurements (data.ny.gov Socrata dataset twsw-2mqa, keyless): "
+                                  "107k+ rows — buyer is always the MTA; vendor_name + value family + "
+                                  "vendor_is_nys_or_fbe preference flag. where is the raw SoQL $where channel; "
+                                  "limit/offset/order mirror $limit/$offset/$order. No total echo — page with offset")
+    f4.add_argument("--where", default=None, help="Raw SoQL filter (upstream param: $where; e.g. \"upper(vendor_name) like '%%SKANSKA%%'\")")
+    f4.add_argument("--limit", type=int, default=20, help="Rows (upstream param: $limit; 1-500 politeness cap)")
+    f4.add_argument("--offset", type=int, default=0, help="Row offset (upstream param: $offset; Socrata has no total echo)")
+    f4.add_argument("--order", default=None, help="Sort (upstream param: $order; column [ASC|DESC] — no NULLS syntax)")
+
+    f5 = v.add_parser("ny_ogs_payments", parents=[g()],
+                      help="New York OGS design & construction payments (keyless)",
+                      description="New York State Office of General Services design & construction payments "
+                                  "(data.ny.gov Socrata dataset rb9h-9fit, keyless): 69k+ payment rows — "
+                                  "buyer is always OGS; each row is contractnumber × vendor × paymentamount "
+                                  "with fiscalyear/quarter/county (no address columns — name walk). Completes "
+                                  "the New York trio (ABO authorities / MTA transport / OGS construction) "
+                                  "buyer universe. where is the raw SoQL $where channel; limit/offset/order "
+                                  "mirror $limit/$offset/$order. No total echo — page with offset")
+    f5.add_argument("--where", default=None, help="Raw SoQL filter (upstream param: $where; e.g. \"upper(vendor) like '%%HIGHLAND%%'\")")
+    f5.add_argument("--limit", type=int, default=20, help="Rows (upstream param: $limit; 1-500 politeness cap)")
+    f5.add_argument("--offset", type=int, default=0, help="Row offset (upstream param: $offset; Socrata has no total echo)")
+    f5.add_argument("--order", default=None, help="Sort (upstream param: $order; column [ASC|DESC] — no NULLS syntax)")
+
+    f6 = v.add_parser("ungm_contract_awards", parents=[g()],
+                      help="UN Global Marketplace contract-award search (keyless)",
+                      description="United Nations Global Marketplace contract awards (www.ungm.org public "
+                                  "search, keyless): ~50k awards across the UN-agency buyer universe "
+                                  "(UNDP/UNFPA/ILO/UNOPS...) × global vendors — each row is award id + "
+                                  "title/vendor/award date/agency/reference/supplier country. supplier/title/"
+                                  "reference/award_from/award_to/countries/agencies/unspscs are upstream "
+                                  "verbatim; page_index (1-based) and page_size (1-100, site default 15) "
+                                  "page through; newest first by default (sort_field=AwardDate, "
+                                  "sort_ascending=false). The ASP.NET anti-forgery session pairing is "
+                                  "handled internally (15-minute reuse, auto re-bootstrap on expiry)")
+    f6.add_argument("--supplier", default=None, help="Vendor name filter (upstream param: Supplier; e.g. DELTA)")
+    f6.add_argument("--title", default=None, help="Title text filter (upstream param: Title)")
+    f6.add_argument("--reference", default=None, help="Reference filter (upstream param: Reference; e.g. rfx_11130_ROAP)")
+    f6.add_argument("--award-from", default=None, help="Award date window start (upstream param: AwardFrom; site picker format dd-MMM-yyyy)")
+    f6.add_argument("--award-to", default=None, help="Award date window end (upstream param: AwardTo)")
+    f6.add_argument("--countries", nargs="+", default=None, help="Project-country filter list (upstream param: Countries[])")
+    f6.add_argument("--agencies", nargs="+", default=None, help="UN-agency filter list (upstream param: Agencies[]; e.g. UNDP ILO)")
+    f6.add_argument("--unspscs", nargs="+", default=None, help="UNSPSC code filter list (upstream param: UNSPSCs[])")
+    f6.add_argument("--page-index", type=int, default=1, help="Page number (upstream param: PageIndex, 1-based)")
+    f6.add_argument("--page-size", type=int, default=15, help="Page size (upstream param: PageSize; 1-100 politeness cap, site default 15)")
+    f6.add_argument("--sort-field", default="AwardDate", help="Sort field (upstream param: SortField; default AwardDate — never empty: null makes the upstream 500)")
+    f6.add_argument("--sort-ascending", action="store_true", help="Sort ascending (upstream param: SortAscending; default false = newest first)")
+
+    f7 = v.add_parser("wb_procnotices", parents=[g()],
+                      help="World Bank procurement notices (keyless)",
+                      description="World Bank procurement notice stream (search.worldbank.org /api/v2/procnotices, "
+                                  "keyless): 313k+ notices across the MDB buyer universe (IBRD/IDA projects in 100+ "
+                                  "countries). notice_type/rows/os are upstream verbatim (default: Contract Award); "
+                                  "supplier keys are extracted from the embedded award section into "
+                                  "awarded_firms[]{name, supp_id} — firm name + WB supplier id, joinable onto the WB "
+                                  "debarred list. notice_text itself is not returned (embedded contact details stay "
+                                  "out of the face)")
+    f7.add_argument("--notice-type", default="Contract Award", help="Notice type (upstream param: notice_type; e.g. Contract Award, General Procurement Notice)")
+    f7.add_argument("--rows", type=int, default=10, help="Page size (upstream param: rows; 1-100 politeness cap)")
+    f7.add_argument("--os", type=int, default=0, help="Offset (upstream param: os)")
+
+
+FLAT = {
+    # procurement flat panel (upstream param names verbatim + our defaults; lambdas only shuttle names across namespaces).
+    # 0.3.6 additions: the World Bank notice stream + the NY Socrata twin faces; 0.3.12 collection additions: the UNGM award
+    # search + the NY OGS third face; 0.3.13 renames pncp_contracts -> br_pncp_contracts, secop_contracts -> co_secop_contracts
+    # — all folded in lexicographically
+    "br_pncp_contracts": lambda a: {"data_inicial": a.data_inicial, "data_final": a.data_final,
+                                 "pagina": a.pagina, "cnpj_orgao": a.cnpj_orgao},
+    "co_secop_contracts": lambda a: {"where": a.where, "limit": a.limit,
+                                  "offset": a.offset, "order": a.order},
+    "ny_abo_contracts": lambda a: {"where": a.where, "limit": a.limit,
+                                   "offset": a.offset, "order": a.order},
+    "ny_mta_procurements": lambda a: {"where": a.where, "limit": a.limit,
+                                      "offset": a.offset, "order": a.order},
+    "ny_ogs_payments": lambda a: {"where": a.where, "limit": a.limit,
+                                  "offset": a.offset, "order": a.order},
+    "ungm_contract_awards": lambda a: {"supplier": a.supplier, "title": a.title,
+                                       "reference": a.reference, "award_from": a.award_from,
+                                       "award_to": a.award_to, "countries": a.countries,
+                                       "agencies": a.agencies, "unspscs": a.unspscs,
+                                       "page_index": a.page_index, "page_size": a.page_size,
+                                       "sort_field": a.sort_field, "sort_ascending": a.sort_ascending},
+    "wb_procnotices": lambda a: {"notice_type": a.notice_type, "rows": a.rows, "os": a.os},
+}
+
+
+# 0.3.10 jurisdiction chapter: face -> jurisdiction (default = the issuing authority's jurisdiction; institutions
+# covering global phenomena = GLOBAL; vocabulary ISO-3166 alpha-2 + EU + GLOBAL) — merged by the root cli.py
+# into _JURISDICTION, the success envelope carries a jurisdiction chapter;
+# 0.3.12 collection: +ungm_contract_awards=GLOBAL (a global UN institution), +ny_ogs_payments=US;
+# 0.3.13 renames pncp_contracts -> br_pncp_contracts, secop_contracts -> co_secop_contracts (jurisdictions unchanged)
+COUNTRY = {
+    "br_pncp_contracts": "BR",
+    "co_secop_contracts": "CO",
+    "ny_abo_contracts": "US",
+    "ny_mta_procurements": "US",
+    "ny_ogs_payments": "US",
+    "ungm_contract_awards": "GLOBAL",
+    "wb_procnotices": "GLOBAL",
+}

agentdata/procurement/co_secop.py

@@ -0,0 +1,88 @@
+"""co_secop — Colombia SECOP II electronic contract face provider (datos.gov.co Socrata dataset
+jbjy-vk9h; keyless).
+
+procurement domain (0.3.0 founding; admitted 2026-10-29, probed). Shape measured 2026-10-29:
+GET /resource/jbjy-vk9h.json?$limit=2&$order=ultima_actualizacion DESC
+  → [rows…88 columns…] (Socrata returns an array directly, no total echo — paging goes through
+  $offset; the corpus-wide count is probed separately via $select=count)
+  — the Colombian procurement corpus holds **5,665,176 electronic contracts** (count measured
+  2026-10-29).
+Row-level golden fields: nit_entidad (buyer NIT) × documento_proveedor+proveedor_adjudicado
+(supplier NIT/CC) × the amount family valor_del_contrato/facturado/pagado/pendiente_de_pago
+× departamento/ciudad/sector × id_contrato as the stable key × the date family
+fecha_de_firma/inicio/fin × es_pyme — joins straight onto the RUES register by NIT.
+PII red line (precedent: fda_crl): on rows whose tipodocproveedor is a personal-document type
+(Cédula de Ciudadanía/Extranjería, Pasaporte, NUIP, Tarjeta de Identidad) the
+documento_proveedor and the supplier's personal name are not returned — set to None +
+proveedorMascarado:true stated explicitly; NIT (company tax id) rows are returned as-is.
+Socrata $-parameter channel, verbatim names: $where raw SoQL (same shape as dgcomp's raw DSL
+precedent — passed through, no local wall) / $limit/$offset/$order; the $order value domain is
+column[ ASC|DESC] (measured 2026-10-29: the "… DESC NULL LAST" form 400s — SoQL does not
+accept the NULLS syntax).
+TTL: contract rows change slowly with ultima_actualizacion — 24h; polite tier 1 rps (anonymous
+Socrata throttling, take the conservative value).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "co_secop",
+    "baseUrl": "https://datos.gov.co",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "contracts": {"path": "/resource/jbjy-vk9h.json"},  # Socrata $limit/$offset/$where/$order
+    },
+    "ttl": {"contracts": 24 * 3600},
+}
+
+# personal-document types (masked); NIT = company tax id, returned as-is
+_PERSONAL_DOC = {"cédula de ciudadanía", "cédula de extranjería", "pasaporte",
+                 "nuip", "tarjeta de identidad", "cedula de ciudadania", "cedula de extranjeria"}
+
+# row narrowing (88 columns → bilateral + amount + status skeleton; upstream column names verbatim)
+_FIELDS = ("nombre_entidad", "nit_entidad", "departamento", "ciudad", "orden", "sector", "rama",
+           "proceso_de_compra", "id_contrato", "estado_contrato", "tipo_de_contrato",
+           "modalidad_de_contratacion", "fecha_de_firma", "fecha_de_inicio_del_contrato",
+           "fecha_de_fin_del_contrato", "tipodocproveedor", "documento_proveedor",
+           "proveedor_adjudicado", "es_pyme", "valor_del_contrato", "valor_facturado",
+           "valor_pagado", "valor_pendiente_de_pago")
+
+
+def contracts_from_upstream(data):
+    """Upstream SODA row array → contract rows (pure function, offline-testable; PII masking
+    happens at this layer)."""
+    rows = []
+    for r in data or []:
+        row = {k: r.get(k) for k in _FIELDS}
+        masked = str(r.get("tipodocproveedor") or "").strip().lower() in _PERSONAL_DOC
+        if masked:
+            row["documento_proveedor"] = None
+            row["proveedor_adjudicado"] = None
+        row["proveedorMascarado"] = masked
+        rows.append(row)
+    return {"rows": rows, "count": len(rows)}
+
+
+def contracts_raw(where=None, *, limit=20, offset=0, order=None, cache=None, no_cache=False):
+    """→ {rows[], count, limit_applied, params, _meta} (Socrata sends no total echo — paging
+    goes through offset).
+
+    where = $where raw SoQL (e.g. "upper(proveedor_adjudicado) like '%ECOPETROL%'"); limit/$limit
+    politeness cap 1-500; offset/$offset ≥0; order/$order = column[ ASC|DESC]."""
+    from ..transport import call_provider
+
+    size = int(limit) if limit is not None else 20  # explicit None check — an `or default` swallows 0, the same trap as 0.2.10
+    if not 1 <= size <= 500:
+        raise SdkError("usage_error", provider="co_secop",
+                       detail=f"limit must be 1-500 (politeness cap), got '{limit}'")
+    off = int(offset) if offset is not None else 0
+    if off < 0:
+        raise SdkError("usage_error", provider="co_secop", detail=f"offset must be ≥0, got '{offset}'")
+    params = {"$limit": size, "$offset": off}
+    w = str(where or "").strip() or None
+    if w:
+        params["$where"] = w
+    o = str(order or "").strip() or None
+    if o:
+        params["$order"] = o
+    r = call_provider(provider, "contracts", params, cache=cache, no_cache=no_cache)
+    return {**contracts_from_upstream(r["data"]), "limit_applied": size, "params": params, "_meta": r}

agentdata/procurement/faces.py

@@ -0,0 +1,239 @@
+"""procurement faces — flat face-method mixin (0.3.0 seventh package, born flat).
+
+Mixes into the root _Domain (assembled via MRO, see client.py); discipline: no __init__,
+depend only on root internals (_flat_env/_c/_request…), method names globally unique across
+domains (a collision would shadow another domain's face).
+"""
+from . import ny_open_data, br_pncp, co_secop, ungm, wb_proc
+from ..errors import SdkError
+
+
+class ProcurementFaces:
+    def _pr_only(self, tool: str):
+        if self.name != "procurement":
+            raise SdkError("usage_error", detail=f"{tool} is a procurement-domain capability (not available on the {self.name} domain)")
+
+    def br_pncp_contracts(self, data_inicial, data_final, *, pagina=1, cnpj_orgao=None,
+                       execution=None, no_cache=None):
+        """procurement br_pncp_contracts: Brazil national procurement contract window
+        (PNCP /api/consulta/v1/contratos; data_inicial/data_final/pagina mirrored verbatim,
+        cnpj_orgao optional buyer filter — pinned by the SpringDoc spec).
+        Rows = buyer CNPJ × supplier CNPJ bilateral + the four amount columns; PF supplier rows
+        are masked per the PII red line."""
+        self._pr_only("br_pncp_contracts")
+        r = br_pncp.contracts_raw(data_inicial, data_final, pagina=pagina, cnpj_orgao=cnpj_orgao,
+                               cache=self._c._cache, no_cache=no_cache if no_cache is not None else self._c.no_cache)
+        res = {k: v for k, v in r.items() if k != "_meta"}
+        rows = res["rows"]
+        n_masked = sum(1 for x in rows if x.get("fornecedorMascarado"))
+        org = rows[0]["orgaoEntidade"] if rows else {}
+        w = f"{r['params']['dataInicial']}–{r['params']['dataFinal']}"
+        if rows:
+            reason = (f"PNCP contract window {w}: {res['total']:,} contracts in the window over "
+                      f"{res['total_paginas']} pages (500 rows/page), page {pagina} returned {len(rows)} rows "
+                      f"(sample buyer {org.get('razaoSocial') or '—'}) — buyer × supplier CNPJ joins straight onto the RFB register"
+                      + (f"; {n_masked} PF (individual) supplier rows masked per the PII red line" if n_masked else ""))
+        else:
+            reason = f"PNCP contract window {w}: page {pagina} returned 0 rows — an empty window or an out-of-range page is a legitimate answer (total={res['total']})"
+        ev = [{"quote": f"{x['numeroControlePNCP']} — {x['orgaoEntidade'].get('razaoSocial') or '—'} × "
+                        f"{x.get('nomeRazaoSocialFornecedor') or '(PF masked)'} — "
+                        f"{x.get('valorGlobal')} BRL",
+               "url": "https://pncp.gov.br/api/consulta/v1/contratos"}
+              for x in rows[:3] if x.get("numeroControlePNCP")]
+        return self._flat_env(tool="br_pncp_contracts",
+                              input={"data_inicial": data_inicial, "data_final": data_final,
+                                     "pagina": pagina, "cnpj_orgao": cnpj_orgao},
+                              reason=reason, result=res, evidence=ev, provider_id="br_pncp",
+                              metas=[r["_meta"]],
+                              query={"source": "raw", "upstream": r["params"]})
+
+    def co_secop_contracts(self, where=None, *, limit=20, offset=0, order=None,
+                        execution=None, no_cache=None):
+        """procurement co_secop_contracts: Colombia SECOP II electronic contracts (datos.gov.co
+        Socrata jbjy-vk9h; where→$where raw SoQL verbatim channel, limit/offset/order mirrored
+        by the same names). 5.66M contracts corpus-wide; rows = buyer NIT × supplier NIT
+        bilateral + the amount family; personal-document supplier rows are masked per the PII
+        red line."""
+        self._pr_only("co_secop_contracts")
+        r = co_secop.contracts_raw(where, limit=limit, offset=offset, order=order,
+                                cache=self._c._cache, no_cache=no_cache if no_cache is not None else self._c.no_cache)
+        res = {k: v for k, v in r.items() if k != "_meta"}
+        rows = res["rows"]
+        n_masked = sum(1 for x in rows if x.get("proveedorMascarado"))
+        if rows:
+            reason = (f"SECOP II electronic contracts: {len(rows)} rows returned (from offset={offset}; "
+                      f"Socrata sends no total echo) — buyer NIT × supplier NIT joins straight onto "
+                      f"the RUES register (sample {rows[0].get('nombre_entidad') or '—'})"
+                      + (f"; {n_masked} personal-document (CC etc.) supplier rows masked per the PII red line" if n_masked else ""))
+        else:
+            reason = "SECOP II: 0 rows — either the where filter has no match or offset is past the end; both are legitimate answers (not errors)"
+        ev = [{"quote": f"{x.get('id_contrato')} — {x.get('nombre_entidad') or '—'} × "
+                        f"{x.get('proveedor_adjudicado') or '(personal masked)'} — "
+                        f"{x.get('valor_del_contrato')} COP",
+               "url": "https://datos.gov.co/resource/jbjy-vk9h.json"}
+              for x in rows[:3] if x.get("id_contrato")]
+        return self._flat_env(tool="co_secop_contracts",
+                              input={"where": where, "limit": limit, "offset": offset, "order": order},
+                              reason=reason, result=res, evidence=ev, provider_id="co_secop",
+                              metas=[r["_meta"]],
+                              query={"source": "raw", "upstream": r["params"]})
+
+    def wb_procnotices(self, notice_type="Contract Award", *, rows=10, os=0,
+                       execution=None, no_cache=None):
+        """procurement wb_procnotices: World Bank procurement notice stream (search.worldbank.org /api/v2/procnotices;
+        notice_type/rows/os mirrored verbatim, default = award notices). 313k notices in full — the MDB buyer universe
+        (IBRD/IDA development projects in 100+ countries); supplier keys are extracted from the embedded notice_text
+        section (awarded_firms[]{name, supp_id} — firm name + WB supplier id), notice_text itself is not returned
+        (embedded contact addresses/phones stay out of the face)."""
+        self._pr_only("wb_procnotices")
+        r = wb_proc.procnotices_raw(notice_type, rows=rows, os_=os,
+                                    cache=self._c._cache, no_cache=no_cache if no_cache is not None else self._c.no_cache)
+        res = {k: v for k, v in r.items() if k != "_meta"}
+        prows = res["rows"]
+        n_firms = sum(len(x["awarded_firms"]) for x in prows)
+        if prows:
+            total_str = f"{res['total']:,}" if res["total"] is not None else "not echoed upstream"
+            reason = (f"World Bank procurement notices ({r['params']['notice_type']}): {total_str} notices in full, "
+                      f"offset {os} returned {len(prows)} rows — this page extracted {n_firms} awarded suppliers "
+                      f"(firm name + WB supplier id supp_id, cross-checkable against the WB debarred list on the same key)")
+        else:
+            reason = (f"World Bank procurement notices ({r['params']['notice_type']}): 0 rows — "
+                      f"an out-of-range os or a notice_type with no such value is a legitimate answer (total={res['total']})")
+        ev = [{"quote": f"{x['id']} — {x['project_ctry_name']} — {x['project_id']} — "
+                        f"{' / '.join(f['name'] + ' (' + f['supp_id'] + ')' for f in x['awarded_firms']) or '(no award section in notice)'}",
+               "url": "https://search.worldbank.org/api/v2/procnotices"}
+              for x in prows[:3] if x.get("id")]
+        return self._flat_env(tool="wb_procnotices",
+                              input={"notice_type": notice_type, "rows": rows, "os": os},
+                              reason=reason, result=res, evidence=ev, provider_id="wb_proc",
+                              metas=[r["_meta"]],
+                              query={"source": "raw", "upstream": r["params"]})
+
+    def ny_abo_contracts(self, where=None, *, limit=20, offset=0, order=None,
+                         execution=None, no_cache=None):
+        """procurement ny_abo_contracts: New York State authority contracts (data.ny.gov Socrata ehig-g5x3;
+        where→$where raw SoQL verbatim channel, limit/offset/order mirrored by the same names). 276k rows corpus-wide —
+        authority_name buyer authority × vendor_name + full-address supplier (no UEI/DUNS, name walk),
+        four value columns + the MWBE/NYS procurement-preference flag family."""
+        self._pr_only("ny_abo_contracts")
+        r = ny_open_data.abo_contracts_raw(where, limit=limit, offset=offset, order=order,
+                                           cache=self._c._cache, no_cache=no_cache if no_cache is not None else self._c.no_cache)
+        res = {k: v for k, v in r.items() if k != "_meta"}
+        rows = res["rows"]
+        if rows:
+            reason = (f"NY State authority contracts (ABO): returned {len(rows)} rows (from offset={offset}; Socrata sends no total echo)"
+                      f" — buyer authority_name × supplier vendor_name + full address (name+address walk)"
+                      f" (sample {rows[0].get('authority_name') or '—'} × {rows[0].get('vendor_name') or '—'})")
+        else:
+            reason = "NY ABO: 0 rows — either the where filter has no match or offset is past the end; both are legitimate answers (not errors)"
+        ev = [{"quote": f"{x.get('authority_name') or '—'} × {x.get('vendor_name') or '—'} — "
+                        f"{x.get('contract_amount') or '—'} USD (awarded {x.get('award_date') or '—'})",
+               "url": "https://data.ny.gov/resource/ehig-g5x3.json"}
+              for x in rows[:3] if x.get("vendor_name")]
+        return self._flat_env(tool="ny_abo_contracts",
+                              input={"where": where, "limit": limit, "offset": offset, "order": order},
+                              reason=reason, result=res, evidence=ev, provider_id="ny_open_data",
+                              metas=[r["_meta"]],
+                              query={"source": "raw", "upstream": r["params"]})
+
+    def ny_mta_procurements(self, where=None, *, limit=20, offset=0, order=None,
+                            execution=None, no_cache=None):
+        """procurement ny_mta_procurements: New York MTA procurements (data.ny.gov Socrata twsw-2mqa;
+        where→$where raw SoQL verbatim channel, limit/offset/order mirrored by the same names). 107k rows corpus-wide —
+        buyer is always the MTA, vendor_name supplier + value family + vendor_is_nys_or_fbe preference flag."""
+        self._pr_only("ny_mta_procurements")
+        r = ny_open_data.mta_procurements_raw(where, limit=limit, offset=offset, order=order,
+                                              cache=self._c._cache, no_cache=no_cache if no_cache is not None else self._c.no_cache)
+        res = {k: v for k, v in r.items() if k != "_meta"}
+        rows = res["rows"]
+        if rows:
+            reason = (f"NY MTA procurements: returned {len(rows)} rows (from offset={offset}; Socrata sends no total echo)"
+                      f" — supplier vendor_name + full address (buyer is always the MTA)"
+                      f" (sample {rows[0].get('vendor_name') or '—'} — {rows[0].get('contract_amount') or '—'} USD)")
+        else:
+            reason = "NY MTA: 0 rows — either the where filter has no match or offset is past the end; both are legitimate answers (not errors)"
+        ev = [{"quote": f"MTA × {x.get('vendor_name') or '—'} — {x.get('contract_amount') or '—'} USD"
+                        f" (awarded {x.get('award_date') or '—'}, {x.get('status') or '—'})",
+               "url": "https://data.ny.gov/resource/twsw-2mqa.json"}
+              for x in rows[:3] if x.get("vendor_name")]
+        return self._flat_env(tool="ny_mta_procurements",
+                              input={"where": where, "limit": limit, "offset": offset, "order": order},
+                              reason=reason, result=res, evidence=ev, provider_id="ny_open_data",
+                              metas=[r["_meta"]],
+                              query={"source": "raw", "upstream": r["params"]})
+
+    def ungm_contract_awards(self, supplier=None, *, title=None, reference=None,
+                             award_from=None, award_to=None, countries=None, agencies=None,
+                             unspscs=None, page_index=1, page_size=15, sort_field="AwardDate",
+                             sort_ascending=False, execution=None, no_cache=None):
+        """procurement ungm_contract_awards: UN Global Marketplace contract-award search
+        (www.ungm.org/Public/ContractAward PublicSearch; Supplier/Title/Reference/AwardFrom/
+        AwardTo/Countries/Agencies/UNSPSCs under their upstream names, page_index/page_size
+        paging). Full corpus ~50k awards — the UN-agency buyer universe (UNDP/UNFPA/ILO/
+        UNOPS…) × global suppliers (vendor name + supplier country); rows = id (the award
+        key) + six slots. The anti-forgery pairing session is reused for 15 minutes and
+        re-collected on a 400; the browser-UA gate is built into the provider layer."""
+        self._pr_only("ungm_contract_awards")
+        r = ungm.awards_raw(supplier, title=title, reference=reference, award_from=award_from,
+                            award_to=award_to, countries=countries, agencies=agencies,
+                            unspscs=unspscs, page_index=page_index, page_size=page_size,
+                            sort_field=sort_field, sort_ascending=sort_ascending,
+                            cache=self._c._cache,
+                            no_cache=no_cache if no_cache is not None else self._c.no_cache)
+        res = {k: v for k, v in r.items() if k != "_meta"}
+        rows = res["rows"]
+        n_vendor = sum(1 for x in rows if x.get("vendor"))
+        if rows:
+            reason = (f"UNGM award search: {res['total']:,} total hits, page {page_index} returned {len(rows)} rows"
+                      f" ({n_vendor} rows carry a vendor name) — UN-agency buyers × global suppliers"
+                      + (f", supplier=\"{supplier}\"" if supplier else "")
+                      + f" (sample {rows[0].get('agency') or '—'} × {rows[0].get('vendor') or '—'}, "
+                        f"awarded {rows[0].get('award_date') or '—'})")
+        else:
+            reason = (f"UNGM award search: 0 rows — no filter match or a past-the-end page number, "
+                      f"both legitimate answers (total={res['total']})")
+        ev = [{"quote": f"{x['id']} — {x.get('agency') or '—'} × {x.get('vendor') or '—'} — "
+                        f"{x.get('supplier_country') or '—'} ({x.get('award_date') or '—'})",
+               "url": f"https://www.ungm.org/Public/ContractAward/{x['id']}"}
+              for x in rows[:3] if x.get("id")]
+        return self._flat_env(tool="ungm_contract_awards",
+                              input={"supplier": supplier, "title": title, "reference": reference,
+                                     "award_from": award_from, "award_to": award_to,
+                                     "countries": countries, "agencies": agencies,
+                                     "unspscs": unspscs, "page_index": page_index,
+                                     "page_size": page_size, "sort_field": sort_field,
+                                     "sort_ascending": sort_ascending},
+                              reason=reason, result=res, evidence=ev, provider_id="ungm",
+                              metas=[r["_meta"]],
+                              query={"source": "raw", "upstream": r["params"]})
+
+    def ny_ogs_payments(self, where=None, *, limit=20, offset=0, order=None,
+                        execution=None, no_cache=None):
+        """procurement ny_ogs_payments: New York State OGS D&C payments (data.ny.gov Socrata
+        rb9h-9fit; where→$where the bare-SoQL upstream-name channel, limit/offset/order
+        mirrored under the same names). Full corpus ~69k rows — the buyer is always OGS,
+        rows = contractnumber×vendor×paymentamount + fiscalyear/quarter/county (no address
+        column; a name walk with a single key); pairs with the ABO/MTA faces to complete
+        the New York State three-buyer universe."""
+        self._pr_only("ny_ogs_payments")
+        r = ny_open_data.ogs_dc_payments_raw(where, limit=limit, offset=offset, order=order,
+                                             cache=self._c._cache,
+                                             no_cache=no_cache if no_cache is not None else self._c.no_cache)
+        res = {k: v for k, v in r.items() if k != "_meta"}
+        rows = res["rows"]
+        if rows:
+            reason = (f"NY OGS D&C payments: returned {len(rows)} rows (from offset={offset}; Socrata sends no total echo)"
+                      f" — the buyer is always OGS, contractnumber×vendor×paymentamount three pillars"
+                      f" (sample {rows[0].get('vendor') or '—'} — {rows[0].get('paymentamount') or '—'} USD, "
+                      f"{rows[0].get('fiscalyear') or '—'} Q{rows[0].get('quarter') or '—'})")
+        else:
+            reason = "NY OGS: 0 rows — the where filter has no match or offset is past the end, both legitimate answers (not errors)"
+        ev = [{"quote": f"OGS × {x.get('vendor') or '—'} — {x.get('paymentamount') or '—'} USD"
+                        f" ({x.get('contractnumber') or '—'}, {x.get('fiscalyear') or '—'} Q{x.get('quarter') or '—'})",
+               "url": "https://data.ny.gov/resource/rb9h-9fit.json"}
+              for x in rows[:3] if x.get("vendor")]
+        return self._flat_env(tool="ny_ogs_payments",
+                              input={"where": where, "limit": limit, "offset": offset, "order": order},
+                              reason=reason, result=res, evidence=ev, provider_id="ny_open_data",
+                              metas=[r["_meta"]],
+                              query={"source": "raw", "upstream": r["params"]})