agentdata 0.3.26__py3-none-any.whl

agentdata/economy/unsd_sdg.py

@@ -0,0 +1,154 @@
+"""unsd_sdg — UN Statistics Division SDG Global Database (unstats.un.org/SDGAPI/v1; keyless).
+
+Two faces: indicators (the 251-indicator catalog with the per-indicator series codes nested in
+each row) and series (the observations of ONE series — 17 goals, 713 series codes).
+
+Traps (research chapter 90, 2026-11-02 — every one of these decided this face's shape):
+  * the `area` parameter on GET Series/Data is DECORATIVE — with and without it the answer is
+    byte-identical (areaCodes / geoAreaCode variants are ignored the same way), so the geo
+    filter is a LOCAL pass over the fetched page, never an upstream param.
+  * `timePeriod` DOES filter upstream (seriesCode=DC_ODA_POVLG&timePeriod=2020 -> 138 rows
+    totalElements vs 3,499 unfiltered) — the only upstream filter that works on this endpoint.
+  * POST Series/Data is a 404; the GET form is the only live channel.
+  * Indicator/Data (whole-indicator granularity) answers 3,198,008 rows for one indicator —
+    the beast. This module never forms that call: the series face is seriesCode-granularity
+    only, and the catalog face is what tells you the valid seriesCodes.
+
+Rate: no published limit -> polite 0.5 rps / burst 2. TTL: 7 days (the 251-indicator catalog)
+and 24h (series observations; the SDG database refreshes per quarterly release).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "unsd_sdg",
+    "baseUrl": "https://unstats.un.org/SDGAPI/v1/sdg",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "indicators": {"path": "/Indicator/List"},
+        "series": {"path": "/Series/Data"},
+    },
+    "ttl": {"indicators": 7 * 24 * 3600, "series": 24 * 3600},
+}
+
+
+def _norm_series(series):
+    t = str(series or "").strip().upper()
+    if not t:
+        raise SdkError("usage_error", provider="unsd_sdg",
+                       detail="--series is required (an SDG series code, e.g. SI_POV_DAY1, "
+                              "DC_ODA_POVLG — list them with unsd_sdg_indicators; the "
+                              "whole-indicator endpoint is a 3.2M-row wall and is never used)")
+    return t
+
+
+def _norm_period(p):
+    """timePeriodStart arrives as a JSON number when the period is a plain year (2020.0) and as
+    a string for split periods — normalise to the plain form the caller reads."""
+    if p is None:
+        return None
+    try:
+        f = float(p)
+        return str(int(f)) if f.is_integer() else str(f)
+    except (TypeError, ValueError):
+        return str(p)
+
+
+def _indicator_row(x):
+    series = x.get("series") or []
+    return {"goal": str(x.get("goal") or "") or None,
+            "target": str(x.get("target") or "") or None,
+            "code": x.get("code"),
+            "description": x.get("description"),
+            "tier": x.get("tier"),
+            "uri": x.get("uri"),
+            "series_count": len(series),
+            "series_codes": [s.get("code") for s in series if s.get("code")]}
+
+
+def indicators_raw(*, page=1, per_page=50, search=None, cache=None, no_cache=False):
+    """-> {total, count, rows, params, _meta}; /Indicator/List
+    The upstream answers the whole 251-row catalog in one payload (no upstream pagination) —
+    page / per_page slice it locally; search is a LOCAL keyword scan (code / description /
+    series codes), never an upstream filter."""
+    from ..transport import call_provider
+
+    pg = int(page or 1)
+    pp = int(per_page or 50)
+    if pg < 1:
+        raise SdkError("usage_error", provider="unsd_sdg", detail="page must be >= 1")
+    if not 1 <= pp <= 500:
+        raise SdkError("usage_error", provider="unsd_sdg", detail="per_page must be 1-500")
+    r = call_provider(provider, "indicators", {}, cache=cache, no_cache=no_cache)
+    data = r["data"]
+    if not isinstance(data, list):
+        raise SdkError("upstream_unavailable", provider="unsd_sdg",
+                       detail="The SDGAPI Indicator/List answer is not the catalog list")
+    rows = [_indicator_row(x) for x in data]
+    q = str(search or "").strip().lower()
+    if q:
+        rows = [x for x in rows
+                if q in (x["code"] or "").lower() or q in (x["description"] or "").lower()
+                or any(q in (c or "").lower() for c in x["series_codes"])]
+    total = len(rows)
+    rows = rows[(pg - 1) * pp: pg * pp]
+    return {"total": total, "count": len(rows), "rows": rows,
+            "params": {"page": pg, "per_page": pp, "search": q or None}, "_meta": r}
+
+
+def series_raw(series, *, geo=None, time=None, page=1, page_size=100,
+               cache=None, no_cache=False):
+    """-> {total, count, rows, params, _meta}; /Series/Data?seriesCode=..
+    One series code per call. geo = a LOCAL filter over the fetched page (the upstream `area`
+    param is decorative — byte-identical with and without it); it matches the numeric M49-style
+    geoAreaCode or the geoAreaName, case-insensitively. time = the upstream timePeriod filter
+    (the one upstream filter that works). page / page_size ride the upstream pager."""
+    from ..transport import call_provider
+
+    code = _norm_series(series)
+    pg = int(page or 1)
+    ps = int(page_size or 100)
+    if pg < 1:
+        raise SdkError("usage_error", provider="unsd_sdg", detail="page must be >= 1")
+    if not 1 <= ps <= 1000:
+        raise SdkError("usage_error", provider="unsd_sdg", detail="page_size must be 1-1000")
+    params = {"seriesCode": code, "page": pg, "pageSize": ps}
+    t = str(time).strip() if time else None
+    if t:
+        params["timePeriod"] = t
+    r = call_provider(provider, "series", params, cache=cache, no_cache=no_cache)
+    data = r["data"]
+    if not isinstance(data, dict) or not isinstance(data.get("data"), list):
+        raise SdkError("upstream_unavailable", provider="unsd_sdg",
+                       detail="The SDGAPI Series/Data answer is not the paged envelope")
+    g = str(geo).strip() if geo else None
+    gl = g.lower() if g else None
+
+    def _row(x):
+        return {"series": x.get("series") or code,
+                "series_description": x.get("seriesDescription"),
+                "goal": (x.get("goal") or [None])[0],
+                "target": (x.get("target") or [None])[0],
+                "indicator": (x.get("indicator") or [None])[0],
+                "geo_area_code": x.get("geoAreaCode"),
+                "geo_area_name": x.get("geoAreaName"),
+                "period": _norm_period(x.get("timePeriodStart")),
+                "value": x.get("value"),
+                "value_type": x.get("valueType"),
+                "attributes": x.get("attributes") or {},
+                "dimensions": x.get("dimensions") or {},
+                "source": x.get("source"),
+                "footnotes": x.get("footnotes") or []}
+
+    rows = [_row(x) for x in data["data"]]
+    total = data.get("totalElements")
+    pages = data.get("totalPages")
+    if gl:
+        rows = [x for x in rows
+                if gl == str(x["geo_area_code"] or "").lower()
+                or gl == str(x["geo_area_name"] or "").lower()]
+    rows.sort(key=lambda x: (str(x["geo_area_code"] or ""), str(x["period"] or "")))
+    return {"total": total, "count": len(rows), "rows": rows,
+            "total_pages": pages, "page": data.get("pageNumber"),
+            "geo_filtered": bool(gl), "params": {"series": code, "geo": g, "time": t,
+                                                 "page": pg, "page_size": ps},
+            "_meta": r}

agentdata/economy/wb.py

@@ -0,0 +1,208 @@
+"""wb — World Bank Open Data provider (api.worldbank.org; keyless).
+
+Three faces born flat: wdi_values (country x indicator x year window), wdi_indicators (the
+indicator catalog), countries (the ISO3/ISO2 + income-level + region reference).
+
+Shapes verified by first-hand live probing 2026-11-02 (tmp/probe-economy/):
+GET /v2/country/{country}/indicator/{indicator}?format=json&date=YYYY:YYYY&per_page=N
+  -> [meta, rows]; meta = {page, pages, per_page, total, sourceid, lastupdated}
+  -> rows = {indicator:{id,value}, country:{id,value}, countryiso3code, date, value, unit,
+             obs_status, decimal}
+  * several countries in one call via the `;` separator (CHN;JPN over 2020:2023 -> 8 rows);
+  * several indicators via `;` is REJECTED upstream ("120 Invalid value") -> one indicator per
+    call, enforced locally (the mirror of an upstream wall, not a local invention);
+  * `date` takes "YYYY" or "YYYY:YYYY" (the upstream range form); `value` is null for a missing
+    observation — null is kept as null (a gap is a fact, never fabricated);
+  * sourceid=2 is the WDI source.
+GET /v2/indicator?format=json&source=2&per_page=500
+  -> the 1,445 WDI indicators in one page (572 KB). WITHOUT source= the catalog is every World
+    Bank source at once (29,544 rows / 5,909 pages) -> source=2 is the default here.
+  -> row = {id, name, unit, source:{id,value}, sourceNote, sourceOrganization, topics[]}
+GET /v2/country?format=json&per_page=N
+  -> rows = {id (ISO3), iso2Code, name, region{}, adminregion{}, incomeLevel{}, lendingType{},
+             capitalCity, longitude, latitude} — the country reference table (income group =
+     the CLASS grouping used as a buyer screen).
+Rate: no official limit published -> polite tier 1 rps / burst 2. TTL: values 24h (quarterly
+cadence, the meta carries lastupdated), catalogs 7 days.
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "wb",
+    "baseUrl": "https://api.worldbank.org",
+    "rate": {"rps": 1, "burst": 2},
+    "ops": {
+        "wdi_values": {"path": "/v2/country/{country}/indicator/{indicator}",
+                       "notFound": [404]},          # params: date/per_page
+        "wdi_indicators": {"path": "/v2/indicator", "notFound": [404]},   # params: source/page/per_page
+        "countries": {"path": "/v2/country", "notFound": [404]},          # params: page/per_page
+    },
+    "ttl": {"wdi_values": 24 * 3600, "wdi_indicators": 7 * 86400,
+            "countries": 7 * 86400},
+}
+
+_PER_PAGE_CAP = 1000  # upstream accepts large pages; 1,000 keeps one catalog page a sane payload
+
+
+def _iso3_list(country):
+    """Country argument -> the upstream path form. Accepts a single ISO3 code or a list;
+    the upstream separator is `;` (verified: CHN;JPN in one path segment)."""
+    if isinstance(country, (list, tuple)):
+        items = [str(x).strip().upper() for x in country if str(x).strip()]
+    else:
+        items = [x.strip().upper() for x in str(country or "").split(";") if x.strip()]
+    if not items:
+        raise SdkError("usage_error", provider="wb",
+                       detail="wb_wdi_values requires --country (ISO3 code, e.g. CHN; several codes may be joined with ';')")
+    return ";".join(items)
+
+
+def _split_payload(payload):
+    """The API answers [meta, rows] — an error answer is a single [{message:[...]}] object."""
+    if isinstance(payload, list) and payload and isinstance(payload[0], dict) and "message" in payload[0]:
+        msg = payload[0]["message"]
+        raise SdkError("upstream_unavailable", provider="wb",
+                       detail=f"World Bank API error {msg[0].get('id') if msg else '?'}: "
+                              f"{msg[0].get('value') if msg else payload}")
+    if not isinstance(payload, list) or len(payload) < 2:
+        raise SdkError("upstream_unavailable", provider="wb",
+                       detail=f"Unexpected World Bank payload shape: {str(payload)[:160]!r}")
+    return payload[0] or {}, payload[1] or []
+
+
+def _value_row(r):
+    ind = r.get("indicator") or {}
+    ctry = r.get("country") or {}
+    return {
+        "indicator_code": ind.get("id"),
+        "indicator_name": ind.get("value"),
+        "country_iso3": r.get("countryiso3code") or ctry.get("id"),
+        "country_name": ctry.get("value"),
+        "year": r.get("date"),
+        "value": r.get("value"),
+        "unit": r.get("unit") or None,
+        "obs_status": r.get("obs_status") or None,
+        "decimal": r.get("decimal"),
+    }
+
+
+def wdi_values_raw(country, indicator, *, date=None, per_page=100, cache=None, no_cache=False):
+    """-> {total, count, rows, params, last_updated, _meta}; /v2/country/{c}/indicator/{i}.
+    country = ISO3 code or a list (upstream `;` separator); indicator = one WDI code (the
+    upstream rejects several codes in one path segment -> one per call); date = "YYYY" or
+    "YYYY:YYYY" (upstream range form); per_page 1-1000. A null value is a missing
+    observation and stays null."""
+    from ..transport import call_provider
+
+    ctry = _iso3_list(country)
+    ind = str(indicator or "").strip()
+    if not ind:
+        raise SdkError("usage_error", provider="wb",
+                       detail="wb_wdi_values requires --indicator (a WDI code, e.g. NY.GDP.MKTP.CD)")
+    if ";" in ind:
+        raise SdkError("usage_error", provider="wb",
+                       detail="The World Bank API rejects several indicator codes in one call "
+                              "(upstream \"120 Invalid value\") — pass one --indicator per call")
+    pp = int(per_page or 100)
+    if not 1 <= pp <= _PER_PAGE_CAP:
+        raise SdkError("usage_error", provider="wb", detail=f"per_page must be 1-{_PER_PAGE_CAP}")
+    params = {"format": "json", "per_page": pp}
+    if date:
+        params["date"] = str(date).strip()
+    r = call_provider(provider, "wdi_values", dict(params, country=ctry, indicator=ind),
+                      cache=cache, no_cache=no_cache)
+    meta, rows = _split_payload(r["data"])
+    return {"total": meta.get("total"), "count": len(rows),
+            "rows": [_value_row(x) for x in rows],
+            "pages": meta.get("pages"), "page": meta.get("page"),
+            "last_updated": meta.get("lastupdated"),
+            "params": {"country": ctry, "indicator": ind, "date": params.get("date"),
+                       "per_page": pp},
+            "_meta": r}
+
+
+def _indicator_row(x):
+    src = x.get("source") or {}
+    return {
+        "indicator_code": x.get("id"),
+        "name": x.get("name"),
+        "unit": x.get("unit") or None,
+        "source_id": src.get("id"),
+        "source_name": src.get("value"),
+        "source_note": x.get("sourceNote"),
+        "source_organization": x.get("sourceOrganization"),
+        "topics": [t.get("value") for t in (x.get("topics") or []) if isinstance(t, dict)],
+    }
+
+
+def wdi_indicators_raw(*, source=2, page=1, per_page=500, search=None,
+                       cache=None, no_cache=False):
+    """-> {total, count, rows, params, _meta}; /v2/indicator?format=json&source=..
+    source = the World Bank source id (2 = WDI, the default here; without it the catalog is
+    every source at once — 29,544 rows). search = a local keyword scan over the returned page
+    (name / sourceOrganization / sourceNote), never an upstream filter."""
+    from ..transport import call_provider
+
+    src = str(source if source is not None else 2).strip() or "2"
+    pp = int(per_page or 500)
+    if not 1 <= pp <= _PER_PAGE_CAP:
+        raise SdkError("usage_error", provider="wb", detail=f"per_page must be 1-{_PER_PAGE_CAP}")
+    pg = int(page or 1)
+    if pg < 1:
+        raise SdkError("usage_error", provider="wb", detail="page must be >= 1")
+    params = {"format": "json", "source": src, "per_page": pp, "page": pg}
+    r = call_provider(provider, "wdi_indicators", params, cache=cache, no_cache=no_cache)
+    meta, rows = _split_payload(r["data"])
+    out = [_indicator_row(x) for x in rows]
+    q = str(search or "").strip().lower()
+    if q:
+        out = [x for x in out
+               if q in (x["indicator_code"] or "").lower() or q in (x["name"] or "").lower()
+               or q in (x["source_organization"] or "").lower() or q in (x["source_note"] or "").lower()]
+    return {"total": meta.get("total"), "count": len(out), "rows": out,
+            "page": meta.get("page"), "pages": meta.get("pages"),
+            "params": {"source": src, "page": pg, "per_page": pp, "search": q or None},
+            "_meta": r}
+
+
+def _country_row(x):
+    region = x.get("region") or {}
+    income = x.get("incomeLevel") or {}
+    lending = x.get("lendingType") or {}
+    admin = x.get("adminregion") or {}
+    return {
+        "iso3": x.get("id"),
+        "iso2": x.get("iso2Code"),
+        "name": x.get("name"),
+        "region_id": region.get("id") or None,
+        "region_name": region.get("value") or None,
+        "admin_region": admin.get("value") or None,
+        "income_level_id": income.get("id") or None,
+        "income_level": income.get("value") or None,
+        "lending_type_id": lending.get("id") or None,
+        "lending_type": lending.get("value") or None,
+        "capital_city": x.get("capitalCity"),
+        "longitude": x.get("longitude"),
+        "latitude": x.get("latitude"),
+    }
+
+
+def countries_raw(*, page=1, per_page=100, cache=None, no_cache=False):
+    """-> {total, count, rows, params, _meta}; /v2/country?format=json
+    The country reference: ISO3 / ISO2 / region / income level / lending type / coordinates
+    (the buyer-screen dimension; income level = the World Bank CLASS grouping)."""
+    from ..transport import call_provider
+
+    pp = int(per_page or 100)
+    if not 1 <= pp <= _PER_PAGE_CAP:
+        raise SdkError("usage_error", provider="wb", detail=f"per_page must be 1-{_PER_PAGE_CAP}")
+    pg = int(page or 1)
+    if pg < 1:
+        raise SdkError("usage_error", provider="wb", detail="page must be >= 1")
+    params = {"format": "json", "per_page": pp, "page": pg}
+    r = call_provider(provider, "countries", params, cache=cache, no_cache=no_cache)
+    meta, rows = _split_payload(r["data"])
+    return {"total": meta.get("total"), "count": len(rows),
+            "rows": [_country_row(x) for x in rows],
+            "page": meta.get("page"), "pages": meta.get("pages"),
+            "params": {"page": pg, "per_page": pp}, "_meta": r}

agentdata/economy/who_xmart.py

@@ -0,0 +1,177 @@
+"""who_xmart — WHO xMart OData service (xmart-api-public.who.int; keyless, no registration).
+
+Three ops behind two faces:
+  * indicator_directory — IND_DIRECTORY_WIDE, the 1,561-indicator catalog; each row carries
+    IND_URI_API (the per-indicator API diameter) and IND_URI_WEB (the human page).
+  * indicator_values   — DATA_/{entity set}, the observations of one indicator.
+  * geo_reference      — REF_GEO_WIDE, the M49 <-> ISO3/ISO2 geography join.
+
+Shapes verified by first-hand live probing 2026-11-02 (tmp/probe-economy/):
+GET /DATA_/IND_DIRECTORY_WIDE?$filter=IND_NAME eq 'TB_ppm_enrol_tx_prct'
+  -> {"@odata.context":..., "@odata.count":1561, "value":[{IND_ID, IND_UUID, IND_PER_CODE,
+      IND_NAME, IND_NAME_FULL, IND_CODE_GHO, VALUE_TYPE, IND_UNIT, IND_URI_API, IND_URI_WEB,
+      IND_PUBLISH_TIME_PREV, DATA_PROVENANCE, DIM_GEO_COVERAGE, DIM_GEO_GRANULARITY, ...}]}
+GET /DATA_/RELAY_TBPPM?$filter=IND_CODE eq 'TB_ppm_enrol_tx_prct'
+  -> {"value":[{IND_CODE, DIM_TIME ("2020"), DIM_TIME_TYPE, DIM_GEO_CODE_M49 ("586"),
+      DIM_GEO_CODE_TYPE, DIM_1_CODE/DIM_MEMBER_1_CODE … DIM_9_CODE/DIM_MEMBER_9_CODE,
+      VALUE_NUMERIC, VALUE_LABEL, OBSERVATION_STATUS, DIM_PUBLISH_STATE_CODE, IND_ID}]}
+GET /DATA_/REF_GEO_WIDE?$filter=GEO_CODE_M49 eq '586' and TERM_LANG eq 'en'
+  -> {"value":[{GEO_CODE_M49 ("586"), GEO_CODE_ISO_3 ("PAK"), GEO_CODE_ISO_2 ("PK"),
+      GEO_NAME_SHORT ("Pakistan"), GEO_TYPE, GEO_CLASS, GEO_SOVEREIGN, TERM_LANG}]}
+Traps found by probing (each one cost a call):
+  * DIM_TIME is Edm.String -> the year needs QUOTES ("DIM_TIME eq '2021'"; an unquoted year
+    is a 400 type error). DIM_GEO_CODE_M49 is a string too ('586');
+  * the geography table is multilingual — one row per TERM_LANG; add "and TERM_LANG eq 'en'";
+  * the property is GEO_CODE_M49 in REF_GEO_WIDE but DIM_GEO_CODE_M49 in the value tables;
+  * the indicator -> entity-set diameter travels in IND_URI_API (the last path segment is the
+    entity set name); several entity sets may carry the same indicator name, and the
+    candidate list is NOT auto-picked (the caller chooses, OpenAlex-style discipline);
+  * a malformed $filter is a 400 — a usage error, not an upstream outage (re-mapped here).
+Rate: no published limit -> polite tier 0.5 rps / burst 2. TTL: 24h (WHO publishes daily).
+"""
+from ..errors import SdkError
+
+provider = {
+    "id": "who_xmart",
+    "baseUrl": "https://xmart-api-public.who.int/DATA_",
+    "rate": {"rps": 0.5, "burst": 2},
+    "ops": {
+        "indicator_directory": {"path": "/IND_DIRECTORY_WIDE", "notFound": [404]},
+        "indicator_values": {"path": "/{entity_set}", "notFound": [404]},
+        "geo_reference": {"path": "/REF_GEO_WIDE", "notFound": [404]},
+    },
+    "ttl": {"indicator_directory": 24 * 3600, "indicator_values": 24 * 3600,
+            "geo_reference": 7 * 86400},
+}
+
+_DIR_COLS = ("IND_ID", "IND_NAME", "IND_NAME_FULL", "IND_NAME_SHORT", "IND_UUID", "IND_PER_CODE",
+             "IND_CODE_GHO", "VALUE_TYPE", "IND_UNIT", "IND_URI_API", "IND_URI_WEB",
+             "IND_PUBLISH_TIME_PREV", "DATA_PROVENANCE", "DIM_GEO_COVERAGE",
+             "DIM_GEO_GRANULARITY", "IND_PROGRESS_DIRECTION_CODE", "SOURCE_TABLE", "TERM_LANG")
+_VAL_COLS = ("IND_ID", "IND_CODE", "DIM_TIME", "DIM_TIME_TYPE", "DIM_GEO_CODE_M49",
+             "DIM_GEO_CODE_TYPE", "DIM_1_CODE", "DIM_MEMBER_1_CODE", "DIM_2_CODE",
+             "DIM_MEMBER_2_CODE", "DIM_3_CODE", "DIM_MEMBER_3_CODE", "DIM_4_CODE",
+             "DIM_MEMBER_4_CODE", "DIM_5_CODE", "DIM_MEMBER_5_CODE", "DIM_6_CODE",
+             "DIM_MEMBER_6_CODE", "DIM_7_CODE", "DIM_MEMBER_7_CODE", "DIM_8_CODE",
+             "DIM_MEMBER_8_CODE", "DIM_9_CODE", "DIM_MEMBER_9_CODE", "VALUE_NUMERIC",
+             "VALUE_LABEL", "VALUE_NUMERIC_LOWER", "VALUE_NUMERIC_UPPER", "OBSERVATION_STATUS",
+             "DIM_PUBLISH_STATE_CODE", "VALUE_PROVENANCE")
+_GEO_COLS = ("GEO_CODE_M49", "GEO_CODE_ISO_3", "GEO_CODE_ISO_2", "GEO_NAME_SHORT",
+             "GEO_NAME_FORMAL", "GEO_TYPE", "GEO_CLASS", "GEO_SOVEREIGN", "GEO_GROUP_TYPE",
+             "GEO_CAPITAL", "TERM_LANG")
+
+
+def _odata(op, params, *, cache=None, no_cache=False):
+    """One OData call; a 400 (malformed $filter / wrong property) is a usage error, not an outage."""
+    from ..transport import call_provider
+    try:
+        r = call_provider(provider, op, params, cache=cache, no_cache=no_cache)
+    except SdkError as e:
+        if e.status == 400:
+            raise SdkError("usage_error", provider="who_xmart",
+                           detail=f"The WHO xMart service rejected the query (HTTP 400): {e.detail}")
+        raise
+    data = r["data"]
+    if not isinstance(data, dict) or "value" not in data:
+        raise SdkError("upstream_unavailable", provider="who_xmart",
+                       detail=f"Unexpected xMart payload shape: {str(data)[:160]!r}")
+    return data, r
+
+
+def _pick(row, cols):
+    return {c: row.get(c) for c in cols if c in row}
+
+
+def indicator_directory_raw(*, filter=None, top=500, skip=0, search=None,
+                             cache=None, no_cache=False):
+    """-> {total, count, rows, params, _meta}; /IND_DIRECTORY_WIDE
+    filter = the raw upstream OData $filter (advanced; the property names are the upstream's);
+    top / skip = the upstream $top / $skip paging; search = a LOCAL keyword scan over the
+    returned page (name / full name / unit / web URI) — never an upstream filter."""
+    from ..transport import call_provider  # noqa: F401  (kept for symmetry with the other ops)
+
+    f = str(filter).strip() if filter else None
+    tp = int(top or 500)
+    sk = int(skip or 0)
+    if tp < 1 or tp > 5000:
+        raise SdkError("usage_error", provider="who_xmart", detail="$top must be 1-5000")
+    if sk < 0:
+        raise SdkError("usage_error", provider="who_xmart", detail="$skip must be >= 0")
+    params = {"$top": tp, "$skip": sk, "$count": "true"}
+    if f:
+        params["$filter"] = f
+    data, r = _odata("indicator_directory", params, cache=cache, no_cache=no_cache)
+    rows = [_pick(x, _DIR_COLS) for x in data.get("value") or []]
+    q = str(search or "").strip().lower()
+    if q:
+        rows = [x for x in rows
+                if q in (x.get("IND_NAME") or "").lower()
+                or q in (x.get("IND_NAME_FULL") or "").lower()
+                or q in (x.get("IND_NAME_SHORT") or "").lower()
+                or q in (x.get("IND_UNIT") or "").lower()
+                or q in (x.get("IND_URI_WEB") or "").lower()]
+    return {"total": data.get("@odata.count"), "count": len(rows), "rows": rows,
+            "params": {"filter": f, "top": tp, "skip": sk, "search": q or None}, "_meta": r}
+
+
+def indicator_values_raw(entity_set, *, filter=None, top=500, skip=0,
+                         cache=None, no_cache=False):
+    """-> {total, count, rows, params, _meta}; /DATA_/{entity_set}
+    entity_set = the WHO entity set (e.g. RELAY_TBPPM) — the last path segment of the
+    directory's IND_URI_API; filter = the raw upstream OData $filter."""
+    es = str(entity_set or "").strip().strip("/")
+    if not es:
+        raise SdkError("usage_error", provider="who_xmart",
+                       detail="who_xmart_values needs the entity set (IND_URI_API's last path "
+                              "segment, e.g. RELAY_TBPPM) — resolve it with who_xmart_indicators")
+    tp = int(top or 500)
+    sk = int(skip or 0)
+    if tp < 1 or tp > 5000:
+        raise SdkError("usage_error", provider="who_xmart", detail="$top must be 1-5000")
+    params = {"$top": tp, "$skip": sk, "$count": "true"}
+    f = str(filter).strip() if filter else None
+    if f:
+        params["$filter"] = f
+    data, r = _odata("indicator_values", dict(params, entity_set=es), cache=cache, no_cache=no_cache)
+    rows = [_pick(x, _VAL_COLS) for x in data.get("value") or []]
+    return {"total": data.get("@odata.count"), "count": len(rows), "rows": rows,
+            "params": {"entity_set": es, "filter": f, "top": tp, "skip": sk}, "_meta": r}
+
+
+def geo_reference_raw(*, filter=None, top=100, skip=0, cache=None, no_cache=False):
+    """-> {total, count, rows, params, _meta}; /REF_GEO_WIDE
+    filter = the raw upstream OData $filter (e.g. "GEO_CODE_ISO_3 eq 'USA' and TERM_LANG eq 'en'")."""
+    f = str(filter).strip() if filter else None
+    tp = int(top or 100)
+    sk = int(skip or 0)
+    params = {"$top": tp, "$skip": sk, "$count": "true"}
+    if f:
+        params["$filter"] = f
+    data, r = _odata("geo_reference", params, cache=cache, no_cache=no_cache)
+    rows = [_pick(x, _GEO_COLS) for x in data.get("value") or []]
+    return {"total": data.get("@odata.count"), "count": len(rows), "rows": rows,
+            "params": {"filter": f, "top": tp, "skip": sk}, "_meta": r}
+
+
+def m49_for_iso3(iso3, *, cache=None, no_cache=False):
+    """ISO-3166 alpha-3 -> the M49 code used by DIM_GEO_CODE_M49.
+    -> (m49, rows, meta); the lookup is a real upstream call (the geography table is the
+    authoritative mapping) and its answer is cached for a week."""
+    code = str(iso3 or "").strip().upper()
+    if not code:
+        return None, [], None
+    f = f"GEO_CODE_ISO_3 eq '{code}' and TERM_LANG eq 'en'"
+    res = geo_reference_raw(filter=f, top=5, cache=cache, no_cache=no_cache)
+    for row in res["rows"]:
+        m49 = row.get("GEO_CODE_M49")
+        if m49:
+            return str(m49), res["rows"], res["_meta"]
+    return None, res["rows"], res["_meta"]
+
+
+def entity_sets_for_indicator(code, *, cache=None, no_cache=False):
+    """The directory rows of one indicator code -> the candidate entity sets.
+    -> (rows, meta). The candidate list is never auto-picked."""
+    f = f"IND_NAME eq '{code}'"
+    res = indicator_directory_raw(filter=f, top=50, cache=cache, no_cache=no_cache)
+    return res["rows"], res["_meta"]

agentdata/entries.py

@@ -0,0 +1,30 @@
+"""agentdata.entries — 0.2.0 per-domain executable entry points (console_scripts healthcare/company/esg/legal;
+research/security were born domains but missed registration in 0.2.2, fixed in 0.2.4).
+
+Naming ruling (2026-10-23): the agentdata prefix on the call face is redundant — each domain gets its own
+executable name (`healthcare fda_drug_shortages …`); the pip package name stays agentdata (the
+`agentdata <domain> …` compatibility alias remains). argv is spliced straight into cli.main, so parsing,
+exit codes and global flags are identical to the agentdata main entry.
+"""
+import sys
+
+from .cli import main
+
+
+def _domain_entry(domain: str):
+    def run() -> int:
+        return main([domain, *sys.argv[1:]])
+    run.__name__ = domain
+    run.__doc__ = f"agentdata {domain} — per-domain executable (args identical to `agentdata {domain} …`)"
+    return run
+
+
+healthcare = _domain_entry("healthcare")
+company = _domain_entry("company")
+economy = _domain_entry("economy")
+esg = _domain_entry("esg")
+legal = _domain_entry("legal")
+procurement = _domain_entry("procurement")  # 0.3.0: the seventh domain
+research = _domain_entry("research")   # added in 0.2.4 (formerly named grants — the alias was removed in 0.3.0; research is the only entry)
+security = _domain_entry("security")   # added in 0.2.4 (born domain missed registration in 0.2.2)
+

agentdata/errors.py

@@ -0,0 +1,38 @@
+"""agentdata.errors — the closed error set (docs/domains/api.md sections 8.3/9.4; CLI exit codes 0/1/2).
+
+- Upstream/availability family (exit 1): upstream_unavailable / upstream_rate_limited / upstream_not_found /
+  thirdparty_upstream_unavailable / thirdparty_rate_limited / capability_unavailable / rate_limited
+- Usage family (exit 2): usage_error / op_unknown / resolve_kind_unknown /
+  corpus-contract 4xx (undeclared_field / bad_value / unauthenticated / forbidden …) /
+  insufficient_credits (RFC-001 §3.6 — 网关 402 余额不足，携带升级提示)
+New entries require adversarial review (the same closed-set discipline as the Node side).
+"""
+
+
+class SdkError(Exception):
+    def __init__(self, code, provider=None, status=None, detail=None, retry_after=None):
+        super().__init__(detail or code)
+        self.code = code
+        self.provider = provider
+        self.status = status
+        self.detail = detail or code
+        self.retry_after = retry_after
+
+    # —— exit-code families (contract: upstream/availability family 1, usage family 2) ——
+    EXIT1 = {
+        "upstream_unavailable", "upstream_rate_limited", "upstream_not_found",
+        "thirdparty_upstream_unavailable", "thirdparty_rate_limited",
+        "capability_unavailable", "rate_limited",
+    }
+
+    @property
+    def exit_code(self) -> int:
+        return 1 if self.code in self.EXIT1 else 2
+
+    def to_dict(self):
+        err = {"code": self.code, "message": self.detail}
+        if self.provider:
+            err["provider"] = self.provider
+        if self.retry_after:
+            err["retry_after"] = self.retry_after
+        return {"ok": False, "error": err}

agentdata/esg/__init__.py

@@ -0,0 +1,5 @@
+"""esg domain package — flat provider adapters (one file per source) + faces/cli (0.2.6 domain reorg).
+
+One domain per package: provider adapters laid flat (one source per file) + faces/cli.
+"""
+from . import climatetrace, eiti, epa_frs, euasl, eutl, paris_mou, thetis_mrv  # noqa: F401