agentdata 0.3.26__py3-none-any.whl

agentdata/economy/fred.py

@@ -0,0 +1,92 @@
+"""fred — US Federal Reserve Economic Data (fred.stlouisfed.org/graph/fredgraph.csv; keyless).
+
+One face: series (one FRED series over a date window).
+
+Channel decisions (verified 2026-11-02, tmp/probe-economy/):
+  * GET /fredgraph.csv?id={SERIES}[&cosd=&coed=] answers text/csv:
+    "observation_date,SERIES" then one row per observation (1947-01-01,21.480 for CPIAUCSL).
+  * SEVERAL series ids in one call answer application/zip (a ZIP with README.txt + one CSV
+    per series) — a binary payload, destroyed by the JSON-only transport (the 0.3.22
+    binary-wall ruling) -> one series per call, enforced locally.
+  * An unknown series id answers an HTML ERROR PAGE ("Error - St. Louis Fed", 29 KB) instead
+    of a 4xx -> the magic-number check is mandatory: the answer must start with
+    "observation_date", otherwise it is an upstream_not_found (an unknown series id), never
+    data. (A 2xx non-CSV answer is never passed through as if it were a series.)
+  * A missing observation is a lone "." in the CSV -> null (a gap is a fact).
+  * cosd / coed are the upstream observation-window bounds (verified: GDP 2020-01-01..2021-01-01).
+Rate: FRED publishes no public limit for the CSV endpoint -> polite tier 1 rps / burst 2.
+TTL: 12h (the cadence differs per series — daily, monthly, quarterly).
+"""
+import csv
+import io
+
+from ..errors import SdkError
+
+provider = {
+    "id": "fred",
+    "baseUrl": "https://fred.stlouisfed.org/graph",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "series": {"path": "/fredgraph.csv", "accept": "text", "notFound": [404]},
+    },
+    "ttl": {"series": 12 * 3600},
+}
+
+_MAGIC = "observation_date"
+
+
+def _norm_series(series):
+    """One series id per call (several ids answer a ZIP = binary wall)."""
+    s = str(series or "").strip().upper()
+    if not s:
+        raise SdkError("usage_error", provider="fred",
+                       detail="fred_series requires --series (a FRED series id, e.g. GDP, CPIAUCSL, "
+                              "DGS10) — several ids in one call answer a ZIP archive, which the "
+                              "JSON transport cannot carry")
+    if "," in s or ";" in s:
+        raise SdkError("usage_error", provider="fred",
+                       detail="fred_series takes ONE series id per call — the upstream answers a "
+                              "ZIP archive (binary) when several ids are requested")
+    return s
+
+
+def series_raw(series, *, start=None, end=None, cache=None, no_cache=False):
+    """-> {total, count, rows, params, _meta}; /fredgraph.csv?id={series}
+    series = the FRED series id; start / end = the upstream cosd / coed observation window;
+    the rows are long-form {date, series, value} and a missing observation is null."""
+    from ..transport import call_provider
+
+    sid = _norm_series(series)
+    params = {"id": sid}
+    s = str(start).strip() if start else None
+    e = str(end).strip() if end else None
+    if s:
+        params["cosd"] = s
+    if e:
+        params["coed"] = e
+    r = call_provider(provider, "series", params, cache=cache, no_cache=no_cache)
+    text = r["data"]
+    if not isinstance(text, str) or not text.lstrip().startswith(_MAGIC):
+        # the upstream answers an HTML error page for an unknown series id
+        raise SdkError("upstream_not_found", provider="fred",
+                       detail=f"FRED answered a non-CSV page for series '{sid}' (the upstream "
+                              "returns an HTML error page for an unknown series id)")
+    recs = list(csv.DictReader(io.StringIO(text)))
+    rows = []
+    for rec in recs:
+        date = rec.get("observation_date") or rec.get("DATE")
+        for col, val in rec.items():
+            if col in (None, "observation_date", "DATE"):
+                continue
+            v = (val or "").strip()
+            if v in (".", "", "NA", "NaN"):
+                v = None
+            else:
+                try:
+                    v = float(v)
+                except ValueError:
+                    pass
+            rows.append({"date": date, "series": col, "value": v})
+    rows.sort(key=lambda x: ((x.get("date") or ""), (x.get("series") or "")))
+    return {"total": len(rows), "count": len(rows), "rows": rows,
+            "params": {"series": sid, "start": s, "end": e}, "_meta": r}

agentdata/economy/ilo_stat.py

@@ -0,0 +1,99 @@
+"""ilo_stat — ILOSTAT bulk API via the rplumber endpoint (rplumber.ilo.org; keyless).
+
+One face: indicator (one indicator x one country x a year window).
+
+Shapes verified by first-hand live probing 2026-11-02 (tmp/probe-economy/):
+GET /data/indicator/?id=EMP_TEMP_SEX_ECO_NB_A&ref_area=USA&timefrom=2020&format=json
+  -> [ {ref_area, source, indicator, sex, classif1, time, obs_value, obs_status,
+        note_indicator, note_source}, ... ]  (612 rows for USA 2020-2025: 6 years x 3 sexes x
+      34 classif1 buckets — the economic-sector breakdown of employment)
+Traps found by probing:
+  * the format flag is the QUERY parameter `format=json` — the path suffix ".jsondata" is a
+    400 ("Unsupported format") and ".json" as a path suffix is a 404 ("wrong query");
+  * the trailing slash of /data/indicator/ is part of the route;
+  * the CLIENT STACK decides: the curl subprocess returns an EMPTY 200 (0 bytes) and a
+    schannel TLS handshake failure on this host, while the urllib channel (the SDK default)
+    answers 612 rows / 118,127 bytes every time — the mirrored twin of the AU ABS lesson
+    (curl-schannel family). This provider therefore keeps the default urllib channel and
+    must NOT be pinned to transport='curl';
+  * the upper year bound is spelled `timeto` upstream — `timeuntil` is accepted and SILENTLY
+    IGNORED, so the answer runs from `timefrom` to the newest year (verified 2026-11-02:
+    timefrom=2020&timeuntil=2022 -> 612 rows 2020-2025, the same set as no upper bound;
+    timefrom=2020&timeto=2022 -> 306 rows 2020-2022). A 200 that looks healthy and drops
+    the filter — the "silent clamp" family, caught by the row-count cross-check;
+  * the answer carries Content-Type: application/octet-stream while the body IS JSON — the
+    body is parsed, not the content type.
+Rate: the public rplumber endpoint publishes no limit -> polite tier 0.5 rps / burst 2.
+TTL: 24h (ILOSTAT refreshes monthly/quarterly per series).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "ilo_stat",
+    "baseUrl": "https://rplumber.ilo.org/data",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "indicator": {"path": "/indicator/", "notFound": [404]},
+    },
+    "ttl": {"indicator": 24 * 3600},
+}
+
+
+def indicator_raw(indicator, *, ref_area=None, time_from=None, time_until=None, sex=None,
+                  classif=None, source=None, cache=None, no_cache=False):
+    """-> {total, count, rows, params, _meta}; /data/indicator/
+    indicator = the ILOSTAT indicator code (e.g. EMP_TEMP_SEX_ECO_NB_A); ref_area = the
+    country (ISO-3, e.g. USA); time_from / time_until = the year bounds (the upstream
+    timefrom / timeto — `timeuntil` is ignored upstream, see the module docstring);
+    sex / classif / source = the upstream dimension filters.
+    Local wall: --ref-area is required — the world-wide answer of one indicator is orders of
+    magnitude bigger than the country answer."""
+    from ..transport import call_provider
+
+    ind = str(indicator or "").strip().upper()
+    if not ind:
+        raise SdkError("usage_error", provider="ilo_stat",
+                       detail="ilo_stat_indicator requires --indicator (the ILOSTAT code, "
+                              "e.g. EMP_TEMP_SEX_ECO_NB_A)")
+    area = str(ref_area or "").strip().upper()
+    if not area:
+        raise SdkError("usage_error", provider="ilo_stat",
+                       detail="ilo_stat_indicator requires --ref-area (the ISO-3 country code, "
+                              "e.g. USA) — the world-wide answer of one indicator is orders of "
+                              "magnitude bigger than the country answer")
+    params = {"id": ind, "ref_area": area, "format": "json"}
+    if time_from:
+        params["timefrom"] = str(time_from).strip()
+    if time_until:
+        params["timeto"] = str(time_until).strip()   # NOT `timeuntil` — silently ignored upstream
+    if sex:
+        params["sex"] = str(sex).strip().upper()
+    if classif:
+        params["classif1"] = str(classif).strip().upper()
+    if source:
+        params["source"] = str(source).strip()
+    r = call_provider(provider, "indicator", params, cache=cache, no_cache=no_cache)
+    data = r["data"]
+    if not isinstance(data, list):
+        raise SdkError("upstream_unavailable", provider="ilo_stat",
+                       detail=f"Unexpected ILOSTAT payload shape: {str(data)[:160]!r}")
+    rows = [{
+        "ref_area": x.get("ref_area"),
+        "indicator": x.get("indicator"),
+        "source": x.get("source"),
+        "sex": x.get("sex"),
+        "classif1": x.get("classif1"),
+        "time": x.get("time"),
+        "obs_value": x.get("obs_value"),
+        "obs_status": x.get("obs_status"),
+        "note_indicator": x.get("note_indicator"),
+        "note_source": x.get("note_source"),
+    } for x in data]
+    # Newest year first, deterministically (the upstream order is not pinned): the reason
+    # line names rows[0] as the latest observation, so the order has to be ours.
+    rows.sort(key=lambda x: (x.get("time") or ""), reverse=True)
+    return {"total": len(rows), "count": len(rows), "rows": rows,
+            "params": {"indicator": ind, "ref_area": area, "time_from": time_from,
+                       "time_until": time_until, "sex": sex, "classif1": classif,
+                       "source": source},
+            "_meta": r}

agentdata/economy/imf_sdmx.py

@@ -0,0 +1,133 @@
+"""imf_sdmx — IMF SDMX 2.1 data service (api.imf.org/external/sdmx/2.1; keyless).
+
+One face: sdmx_series — one dataflow × one country × one indicator over an optional period
+window (the trailing key dimensions — FREQUENCY and beyond — are omittable upstream; the face
+keeps the optional trailing FREQUENCY and nothing else).
+
+Channel decision (the ecb csvdata idiom, 0.3.23): the SDMX 2.1 endpoint answers the Accept
+header FIRST — with the transport default `Accept: application/json` the answer comes back as
+SDMX-XML (mangled by the JSON-only transport); asking explicitly for
+`application/vnd.sdmx.data+csv;version=1.0.0` yields the SDMX 2.1 generic CSV (DATAFLOW, one
+column per key dimension, TIME_PERIOD, OBS_VALUE, then attribute columns — verified
+2026-11-02: WEO/USA.NGDP_RPCH -> 200, 111,674 B, 52 data rows 1980-2031 at full precision).
+
+Walls and traps (research chapter 87, 2026-11-02):
+  * the country-only key (ONE key segment) is the multi-megabyte wall — the whole dataset for
+    one country. The face requires BOTH --country and --indicator, so a one-segment key is
+    never formed here.
+  * the DSD codelists come back partial/empty (the indicator dictionary is not fetchable that
+    way) — the CSV columns ARE the dimension list, and they vary per flow: WEO/GDD spell them
+    COUNTRY.INDICATOR.FREQUENCY; UNFCCC inserts INDUSTRY/GAS_TYPE before the indicator, so the
+    country.indicator key shape fits the WEO/GDD/CPI family and NOT UNFCCC (documented limit,
+    wrong-order keys upstream 404).
+  * SCALE is a display hint — OBS_VALUE already carries the true value (DataMapper's rounded
+    1-decimal numbers are the reason that surface is a background board, not a source).
+
+Rate: no published limit -> polite 0.5 rps / burst 2. TTL 24h (the WEO family refreshes on its
+own vintage cadence; 101 of the 229 dataflows are standing, the rest are monthly vintages).
+"""
+import csv
+import io
+import re
+
+from ..errors import SdkError
+
+provider = {
+    "id": "imf_sdmx",
+    "baseUrl": "https://api.imf.org/external/sdmx/2.1",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "sdmx_series": {"path": "/data/{flow}/{key}", "accept": "text", "notFound": [404]},
+    },
+    "ttl": {"sdmx_series": 24 * 3600},
+}
+
+_TOKEN_RE = re.compile(r"^[A-Z0-9_]+$")
+
+# The SDMX 2.1 generic CSV: ask for the CSV flavour explicitly (see the module docstring —
+# the JSON Accept is ignored upstream and the answer degrades to XML).
+_CSV_ACCEPT = {"Accept": "application/vnd.sdmx.data+csv;version=1.0.0"}
+
+
+def _norm_token(value, what, provider_id="imf_sdmx"):
+    """The key parts are upper-case tokens (USA, NGDP_RPCH, WEO, A)."""
+    t = str(value or "").strip().upper()
+    if not t or not _TOKEN_RE.match(t):
+        raise SdkError("usage_error", provider=provider_id,
+                       detail=f"{what} must be an upper-case code token (letters/digits/'_'), "
+                              f"got {value!r}")
+    return t
+
+
+def _dim_names(head):
+    """The key-dimension columns of the SDMX 2.1 generic CSV: everything between DATAFLOW and
+    TIME_PERIOD (they vary per flow — WEO/GDD say COUNTRY,INDICATOR,FREQUENCY; UNFCCC inserts
+    INDUSTRY/GAS_TYPE — so the boundary, not a fixed list, is the reliable rule)."""
+    names = []
+    for col in head:
+        if col in ("DATAFLOW",):
+            continue
+        if col == "TIME_PERIOD":
+            break
+        names.append(col)
+    return names
+
+
+def _parse_csv(text):
+    lines = [ln for ln in (text or "").splitlines() if ln.strip()]
+    if not lines:
+        raise SdkError("upstream_unavailable", provider="imf_sdmx",
+                       detail="The IMF SDMX CSV answer was empty")
+    head = lines[0].split(",")
+    if "TIME_PERIOD" not in head or "OBS_VALUE" not in head:
+        # not the generic CSV (an SDMX XML error page, a gateway notice)
+        raise SdkError("upstream_unavailable", provider="imf_sdmx",
+                       detail=f"The IMF SDMX answer is not the generic CSV table "
+                              f"(head {lines[0][:120]!r})")
+    dims = _dim_names(head)
+    rows = []
+    for rec in csv.DictReader(io.StringIO("\n".join(lines))):
+        try:
+            value = float(rec.get("OBS_VALUE"))
+        except (TypeError, ValueError):
+            value = None
+        out = {"flow": (rec.get("DATAFLOW") or "").split(":")[-1].split("(")[0] or None,
+               "dims": {d: rec.get(d) for d in dims if rec.get(d) not in (None, "")},
+               "period": rec.get("TIME_PERIOD"),
+               "value": value,
+               "scale": rec.get("SCALE") or None,
+               "series_name": rec.get("SERIES_NAME") or None,
+               "description": rec.get("FULL_DESCRIPTION") or None,
+               "doi": rec.get("DOI") or None}
+        rows.append(out)
+    return rows
+
+
+def sdmx_series_raw(flow, country, indicator, frequency=None, *, start=None, end=None,
+                    cache=None, no_cache=False):
+    """-> {total, count, rows, params, _meta}; /data/{flow}/{COUNTRY.INDICATOR[.FREQUENCY]}
+    flow = the dataflow id (WEO, GDD, CPI …); country + indicator are BOTH required — the
+    country-only key is the multi-megabyte wall; frequency = the optional trailing key
+    dimension; start / end = the upstream startPeriod / endPeriod bounds."""
+    from ..transport import call_provider
+
+    fl = _norm_token(flow, "--flow")
+    cc = _norm_token(country, "--country")
+    ind = _norm_token(indicator, "--indicator")
+    freq = _norm_token(frequency, "--frequency") if frequency else None
+    key = ".".join([cc, ind] + ([freq] if freq else []))
+    s = str(start).strip() if start else None
+    e = str(end).strip() if end else None
+    params = {"flow": fl, "key": key}
+    if s:
+        params["startPeriod"] = s
+    if e:
+        params["endPeriod"] = e
+    r = call_provider(provider, "sdmx_series", params, cache=cache, no_cache=no_cache,
+                      extra_headers=_CSV_ACCEPT)
+    rows = _parse_csv(r["data"])
+    rows.sort(key=lambda x: (x.get("period") or ""))
+    return {"total": len(rows), "count": len(rows), "rows": rows, "key": key,
+            "params": {"flow": fl, "country": cc, "indicator": ind, "frequency": freq,
+                       "start": s, "end": e},
+            "_meta": r}

agentdata/economy/un_comtrade.py

@@ -0,0 +1,199 @@
+"""un_comtrade — UN Comtrade public preview API (comtradeapi.un.org; keyless, no registration).
+
+One face: trade (one reporter x partner x period x commodity trade flow).
+
+Channels (verified 2026-11-02, tmp/probe-economy/):
+  * data: GET /public/v1/preview/{type}/{freq}/{cl}?reporterCode=&period=&partnerCode=&cmdCode=
+    &flowCode=&maxRecords=&includeDesc=
+    -> {"elapsedTime":"0.95 secs","count":1,"data":[{typeCode, freqCode, refPeriodId, period,
+        reporterCode, reporterISO, reporterDesc, flowCode, flowDesc, partnerCode, partnerISO,
+        partnerDesc, partner2Code/ISO/Desc, classificationCode, cmdCode, cmdDesc, customsCode,
+        mosCode, motCode, qtyUnitCode, qty, netWgt, grossWgt, cifvalue, fobvalue, primaryValue,
+        isAggregate}], "error":""}
+    The preview answer is capped at 500 records; the full subscription API is keyed (out of scope).
+  * areas: GET /files/v1/app/reference/partnerAreas.json -> 310 area rows {id, text,
+    PartnerCode, PartnerDesc, PartnerCodeIsoAlpha2, PartnerCodeIsoAlpha3, isGroup}.
+
+The area-code trap (the reference is NOT a clean ISO3 map):
+  * 16 ISO3 codes carry SEVERAL rows — the historical ones carry a "(...YYYY)" suffix in the
+    text (Germany: "Fed. Rep. of Germany (...1990)" = 280 vs the current "Germany" = 276);
+  * the USA carries THREE rows: 840 "United States of America", 842 "USA", 841 "USA and Puerto
+    Rico (...1980)" — and the live preview answers reporterCode=842 for the USA (840 is the
+    ISO 3166 numeric, 842 is the Comtrade trade code). So a naive "ISO3 -> code" dict built by
+    insertion order picks the WRONG code (841) — the resolution rule below drops the historical
+    rows and then prefers the shortest current name, which reproduces every current code
+    (USA 842, DEU 276, FRA 251, IND 699, PAK 586, VNM 704, NOR 579 …);
+  * reporterCode=USA (the ISO3 string) is a 400 "The field reporterCode is invalid" — the
+    numeric code is mandatory, hence the translation step;
+  * partner 0 = the World aggregate (partnerISO "W00").
+Rate: the preview answers with a rate-limit header in the paid API; the public preview is
+polite-tier 0.5 rps / burst 2. TTL: 12h (the preview data is refreshed hourly).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "un_comtrade",
+    "baseUrl": "https://comtradeapi.un.org",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "trade": {"path": "/public/v1/preview/{type_code}/{freq_code}/{cl_code}", "notFound": [404]},
+        "areas": {"path": "/files/v1/app/reference/partnerAreas.json", "notFound": [404]},
+    },
+    "ttl": {"trade": 12 * 3600, "areas": 7 * 86400},
+}
+
+_PREVIEW_CAP = 500     # the public preview answers at most 500 records per call
+
+
+def _norm_code(value, what):
+    """A Comtrade area code: digits pass through, an ISO3 code is translated."""
+    v = str(value or "").strip()
+    if not v:
+        return None
+    if v.isdigit():
+        return int(v)
+    return v.upper()
+
+
+def _pick_area(rows, iso3):
+    """The Comtrade code of one ISO3 area, resolved against the reference rows.
+    Rule (verified against the live preview): drop the historical rows (their text carries a
+    "(...YYYY)" suffix), then prefer the shortest current name — USA -> 842 (not 840, not 841),
+    DEU -> 276, FRA -> 251, IND -> 699, PAK -> 586."""
+    code = str(iso3 or "").strip().upper()
+    if not code:
+        return None
+    cands = [r for r in rows if (r.get("PartnerCodeIsoAlpha3") or "").strip().upper() == code]
+    if not cands:
+        return None
+    live = [r for r in cands if "(..." not in (r.get("text") or "")]
+    pool = live or cands
+    best = sorted(pool, key=lambda r: (len((r.get("text") or "").strip()), r.get("PartnerCode") or 0))[0]
+    return best.get("PartnerCode")
+
+
+def _areas(cache=None, no_cache=False):
+    """-> (rows, meta): the area reference table (310 rows)."""
+    from ..transport import call_provider
+    r = call_provider(provider, "areas", {}, cache=cache, no_cache=no_cache)
+    data = r["data"]
+    rows = data.get("results") if isinstance(data, dict) else None
+    if rows is None:
+        rows = data if isinstance(data, list) else []
+    return rows, r
+
+
+def _resolve_area(value, what, *, cache=None, no_cache=False):
+    """An area argument -> the numeric Comtrade code (the ISO3 is translated)."""
+    v = str(value or "").strip()
+    if not v:
+        raise SdkError("usage_error", provider="un_comtrade",
+                       detail=f"un_comtrade_trade requires {what}")
+    if v.isdigit():
+        return int(v)
+    up = v.upper()
+    if up in ("W00", "WORLD", "WLD"):
+        return 0
+    rows, meta = _areas(cache=cache, no_cache=no_cache)
+    code = _pick_area(rows, up)
+    if code is None:
+        raise SdkError("upstream_not_found", provider="un_comtrade",
+                       detail=f"No Comtrade area code for '{v}' (the area reference has no such "
+                              "ISO3 code — check the spelling)")
+    return int(code)
+
+
+def _row(rec):
+    return {
+        "type_code": rec.get("typeCode"),
+        "freq_code": rec.get("freqCode"),
+        "period": rec.get("period"),
+        "ref_period_id": rec.get("refPeriodId"),
+        "ref_year": rec.get("refYear"),
+        "reporter_code": rec.get("reporterCode"),
+        "reporter_iso3": rec.get("reporterISO"),
+        "reporter_name": rec.get("reporterDesc"),
+        "flow_code": rec.get("flowCode"),
+        "flow_name": rec.get("flowDesc"),
+        "partner_code": rec.get("partnerCode"),
+        "partner_iso3": rec.get("partnerISO"),
+        "partner_name": rec.get("partnerDesc"),
+        "partner2_code": rec.get("partner2Code"),
+        "partner2_iso3": rec.get("partner2ISO"),
+        "classification_code": rec.get("classificationCode"),
+        "cmd_code": rec.get("cmdCode"),
+        "cmd_name": rec.get("cmdDesc"),
+        "customs_code": rec.get("customsCode"),
+        "customs_name": rec.get("customsDesc"),
+        "mot_code": rec.get("motCode"),
+        "mot_name": rec.get("motDesc"),
+        "qty_unit_code": rec.get("qtyUnitCode"),
+        "qty_unit": rec.get("qtyUnitAbbr"),
+        "qty": rec.get("qty"),
+        "net_weight": rec.get("netWgt"),
+        "gross_weight": rec.get("grossWgt"),
+        "cif_value": rec.get("cifvalue"),
+        "fob_value": rec.get("fobvalue"),
+        "primary_value": rec.get("primaryValue"),
+        "is_aggregate": rec.get("isAggregate"),
+        "is_reported": rec.get("isReported"),
+    }
+
+
+def trade_raw(reporter, *, period=None, partner=None, cmd=None, flow=None, type_code="C",
+              freq_code="A", cl_code="HS", max_records=500, partner2=None, customs=None,
+              mot=None, cache=None, no_cache=False):
+    """-> {total, count, rows, params, _meta}; /public/v1/preview/{type}/{freq}/{cl}
+    reporter = the reporting country (ISO3 or the numeric code — the ISO3 is translated through
+    the area reference); period = the upstream period (2023 / 202301 / a comma list);
+    partner = the partner area (ISO3 or code; 0 / "W00" = the World aggregate);
+    cmd = the commodity code (a comma list; TOTAL = all goods); flow = the trade flow
+    (X export / M import / "X,M"); type_code / freq_code / cl_code = the path segments
+    (C commodities / A annual / HS classification); max_records 1-500 (the preview cap)."""
+    from ..transport import call_provider
+
+    rep = _resolve_area(reporter, "--reporter (the reporting country)", cache=cache, no_cache=no_cache)
+    per = str(period or "").strip()
+    if not per:
+        raise SdkError("usage_error", provider="un_comtrade",
+                       detail="un_comtrade_trade requires --period (e.g. 2023 or 202301)")
+    par = _resolve_area(partner if partner not in (None, "") else "W00",
+                         "--partner (the partner area; '0' = the World aggregate)",
+                         cache=cache, no_cache=no_cache)
+    mr = int(max_records or 500)
+    if not 1 <= mr <= _PREVIEW_CAP:
+        raise SdkError("usage_error", provider="un_comtrade",
+                       detail=f"maxRecords must be 1-{_PREVIEW_CAP} (the public preview cap)")
+    params = {
+        "type_code": str(type_code or "C").strip().upper(),
+        "freq_code": str(freq_code or "A").strip().upper(),
+        "cl_code": str(cl_code or "HS").strip().upper(),
+        "reporterCode": rep,
+        "period": per,
+        "partnerCode": par,
+        "cmdCode": str(cmd or "TOTAL").strip(),
+        "maxRecords": mr,
+        "includeDesc": "true",
+    }
+    if flow:
+        params["flowCode"] = str(flow).strip().upper()
+    if partner2 not in (None, ""):
+        params["partner2Code"] = _resolve_area(partner2, "--partner2", cache=cache, no_cache=no_cache)
+    if customs not in (None, ""):
+        params["customsCode"] = str(customs).strip()
+    if mot not in (None, ""):
+        params["motCode"] = str(mot).strip()
+    r = call_provider(provider, "trade", params, cache=cache, no_cache=no_cache)
+    data = r["data"]
+    if not isinstance(data, dict):
+        raise SdkError("upstream_unavailable", provider="un_comtrade",
+                       detail=f"Unexpected Comtrade payload shape: {str(data)[:160]!r}")
+    err = (data.get("error") or "").strip()
+    if err:
+        raise SdkError("upstream_unavailable", provider="un_comtrade", detail=f"Comtrade: {err}")
+    recs = data.get("data") or []
+    rows = [_row(x) for x in recs]
+    return {"total": data.get("count"), "count": len(rows), "rows": rows,
+            "elapsed": data.get("elapsedTime"),
+            "params": {k: v for k, v in params.items() if k not in ("type_code", "freq_code", "cl_code")},
+            "_meta": r}