IMF Agentic Integration Playbook

May 11, 2026 · View on GitHub

Purpose: Step-by-step integration pattern for agentic workflows that produce Riksdagsmonitor articles. IMF is the primary economic-data source; World Bank and SCB fill governance / environment / social-residue and Swedish-specific gaps respectively.

Audience: Agentic workflow authors (.github/workflows/news-*.md), agent personas (.github/agents/*.md), and skill files (.github/skills/*/SKILL.md).

1 · Provider decision matrix

Use this table to decide which provider owns which indicator class before writing a single MCP call or CLI invocation.

Class	Primary provider	Secondary	Rationale
Macro (GDP, growth)	IMF WEO	—	Freshness + T+5 projections
Inflation (annual)	IMF WEO	SCB (monthly)	Freshness + projections
Inflation (monthly)	IMF IFS CPI	SCB	High frequency
Unemployment (annual)	IMF WEO	SCB AKU	Freshness + projections; SCB for Swedish-specific
Fiscal — debt, revenue, expenditure, balance	IMF WEO + FM	—	GFSM 2014, projections
Fiscal — cyclically-adjusted, primary balance	IMF FM	—	Debt-sustainability methodology
External sector — current account, trade volumes	IMF WEO	—	Projections
Bilateral trade flows	IMF DOTS	—	Partner-country dimension
Monetary — policy rate, interbank	IMF MFS_IR / IFS	Riksbank	Standardised cross-country
Exchange rates	IMF ER	Riksbank	Historical depth
Commodity prices	IMF PCPS	—	Canonical price benchmarks
Government spending by function	IMF GFS_COFOG	—	Committee-aligned (02/07/09/10)
Population, demographics	IMF WEO	SCB	Projections
Governance (WGI: CC.EST, RL.EST, VA.EST, GE.EST, RQ.EST, PV.EST)	World Bank	—	IMF has no equivalent — `source=75`
Environment (CO2, renewables, forest)	World Bank	PCPS (prices)	IMF has no equivalent
Education (residue)	World Bank	GFS_COFOG 09	WB for participation rates
Defence spending	World Bank MS.MIL.*	GFS_COFOG 02	WB has deeper historical
Rule of law, crime	World Bank	—	IMF has no equivalent
Swedish-specific ground truth (monthly labour, regional, budget execution)	SCB	—	Primary source for national statistics

2 · Seven-step integration contract

Every agentic news workflow MUST perform these steps in order at Step 2.6 (04-analysis-pipeline.md phase).

Step 1 — Identify the policy domain & committee

From the source documents (motions, propositions, betänkanden), extract the committee codes (FiU, SkU, AU, NU, UU, SoU, SfU, FöU, MJU, UbU, KU, JuU, KrU) and policy areas.

Step 2 — Map committee → indicators via the inventory

# View the authoritative inventory (JSON is machine-readable; also human-reviewable)
cat analysis/imf/indicators-inventory.json | jq '.committeeMatrix.FiU'
# → { "provider": "IMF (primary)", "mustQuery": ["WEO:NGDP_RPCH", ...] }

Alternative programmatic lookup:

import { findImfIndicatorsForCommittee } from './scripts/imf-context.js';
const ind = findImfIndicatorsForCommittee('FiU'); // returns IMF indicator set

Step 3 — Pre-warm IMF endpoint (cold-start protection)

# One throwaway call to wake the upstream; ignore output.
tsx scripts/imf-fetch.ts weo --country SWE --indicator NGDP_RPCH --years 1 >/dev/null 2>&1 || true
sleep 1

🔴 Pre-warm gate — the throwaway call above is the manual cold-start probe. The full pre-warm gate is invoked automatically by the .github/actions/news-prewarm composite action (and therefore by every one of the 14 .github/workflows/news-*.md workflows) via scripts/check-imf-connectivity.ts:

What it probes — three IMF transports: WEO + FM via Datamapper, IFS monthly CPI via SDMX 3.0.

Authentication — every SDMX 3.0 /data/... endpoint requires the Ocp-Apim-Subscription-Key Azure APIM header (since ~2026-05). Each news workflow forwards secrets.IMF_SDMX_SUBSCRIPTION_KEY (primary, required) to the composite action via with: imf-sdmx-subscription-key:. The action then exports the key to $GITHUB_ENV so both the connectivity probe AND the agent's bash: tool (which runs awf --env-all) inherit it. IMF_SDMX_SUBSCRIPTION_KEY_SECONDARY is the rotation key — it is not consumed by code, only stored in repository secrets so operators can swap primary↔secondary without downtime when the IMF issues new credentials. See "Key rotation" below. The unauthenticated WEO + FM Datamapper transport is unaffected.

Vintage discipline — parses ImfClient.weoVintage (WEO-2026-04 at the time of writing) into a calendar age. Anything older than STALE_VINTAGE_MAX_MONTHS (6) flips the report to status: "stale-vintage" and emits an ℹ️ annotation block per .github/aw/ECONOMIC_DATA_CONTRACT.md v3.1 §"Vintage discipline".

Outputs — always writes data/imf-context.json ({status, vintage, vintageAgeMonths, stale, probes, checkedAt, warningBlock}); on connectivity failure additionally writes data/imf-unavailable.flag containing the structured payload.

Failure handling — non-blocking by default (exit 0 + flag file so the workflow continues). On connectivity failure every workflow MUST inject the ⚠️ IMF context unavailable block into executive-brief.md, comparative-international.md, and synthesis-summary.md — the exact wording is provided in report.warningBlock so the agent can paste it verbatim. When only the SDMX probe fails the report carries status: "degraded" (WEO/FM still healthy) and a lighter ℹ️ IMF auxiliary transport degraded annotation. A missing/invalid SDMX key surfaces as the deterministic reason sdmx-subscription-key-not-configured instead of the raw HTTP code so operators can distinguish "secret never set" from "IMF outage" or "key revoked".

Manual invocation — tsx scripts/check-imf-connectivity.ts [--strict] [--output-dir data]. --strict flips to fail-fast for operator debugging.

Key rotation (primary ↔ secondary)

The IMF Data SDMX API subscription product issues two keys per subscription. We mirror this in repository secrets:

IMF_SDMX_SUBSCRIPTION_KEY — primary, required, consumed by every workflow run via secrets.IMF_SDMX_SUBSCRIPTION_KEY.

IMF_SDMX_SUBSCRIPTION_KEY_SECONDARY — secondary, optional, stored only so the next rotation can be performed without an outage: a. Confirm the secondary key works (curl + Ocp-Apim-Subscription-Key). b. Promote: copy IMF_SDMX_SUBSCRIPTION_KEY_SECONDARY over IMF_SDMX_SUBSCRIPTION_KEY in repository / org secrets. c. Re-issue a new key on the IMF portal and store it as the new IMF_SDMX_SUBSCRIPTION_KEY_SECONDARY. d. Revoke the old primary on the portal.

No workflow or script reads IMF_SDMX_SUBSCRIPTION_KEY_SECONDARY directly — it exists purely as a hot spare. This matches the IMF Azure APIM "regenerate primary key" / "regenerate secondary key" semantics.

Copilot coding-agent sessions

Interactive Copilot coding-agent runners do not automatically inherit repository secrets — GitHub's secret store is write-only by design (no PAT, including the agent's own token, can read secret values via the REST API). The top-level workflow env: block in .github/workflows/copilot-setup-steps.yml is only scoped to the setup-job's own steps — it is NOT inherited by the agent's interactive bash: runtime.

The mechanism that DOES propagate to the agent runtime is writing the secret to $GITHUB_ENV from within a setup step. The dedicated "Export IMF SDMX subscription keys to agent env" step in copilot-setup-steps.yml does exactly that:
- name: Export IMF SDMX subscription keys to agent env
  env:
    IMF_SDMX_SUBSCRIPTION_KEY: ${{ secrets.IMF_SDMX_SUBSCRIPTION_KEY }}
    IMF_SDMX_SUBSCRIPTION_KEY_SECONDARY: ${{ secrets.IMF_SDMX_SUBSCRIPTION_KEY_SECONDARY }}
  run: |
    echo "IMF_SDMX_SUBSCRIPTION_KEY=${IMF_SDMX_SUBSCRIPTION_KEY}" >> "$GITHUB_ENV"
    echo "::add-mask::${IMF_SDMX_SUBSCRIPTION_KEY}"
    # …secondary key handled identically
After this wiring, tsx scripts/imf-fetch.ts sdmx ... and curl -H "Ocp-Apim-Subscription-Key: $IMF_SDMX_SUBSCRIPTION_KEY" ... both succeed in the agent shell. Sessions that were launched before this wiring existed will not see the env var retroactively — only sessions started after the wiring change inherit it. WEO + FM via the unauthenticated www.imf.org Datamapper transport works in every session regardless of whether the SDMX key is wired.

Diagnostic: the env var COPILOT_AGENT_INJECTED_SECRET_NAMES in the agent shell lists which secrets the Copilot runtime injected. If IMF_SDMX_SUBSCRIPTION_KEY is missing from that list AND missing from $GITHUB_ENV, the wiring above failed (most often because the repo secret itself is unset). Repository secrets must exist at Settings → Secrets and variables → Actions for ${{ secrets.* }} resolution to succeed.

Step 4 — Batched `compare` call for peer-set

Always prefer compare (single batched Datamapper call across countries) over parallel weo calls — one call vs five gets you 80 % off the rate-limit budget.

tsx scripts/imf-fetch.ts compare \
  --indicator GGXWDG_NGDP \
  --countries SWE,DNK,NOR,FIN,DEU \
  --persist
sleep 1

tsx scripts/imf-fetch.ts compare \
  --indicator NGDP_RPCH \
  --countries SWE,DNK,NOR,FIN,DEU \
  --persist
sleep 1

Step 5 — Historical + projection time series (Sweden only)

# 15-year window captures both the 2009/2020 historical extremes and the T+5 projection.
tsx scripts/imf-fetch.ts weo --country SWE --indicator PCPIPCH  --years 15 --persist
sleep 1
tsx scripts/imf-fetch.ts weo --country SWE --indicator LUR      --years 15 --persist
sleep 1

Step 6 — SDMX 3.0 for non-WEO coverage

For IFS monthly CPI, policy rates, GFS COFOG, DOTS bilateral trade, PCPS commodities:

tsx scripts/imf-fetch.ts sdmx \
  --path "/data/IMF.STA,CPI,5.0.0/SWE.CPI._T.IX.M?startPeriod=2024-01" \
  --indicator _T.IX --country SWE --persist
sleep 1

Step 7 — Write `economic-data.json`

Assemble the collected dataPoints[] into the v2.0 schema (see ECONOMIC_DATA_CONTRACT.md). Every projection row MUST carry projectionVintage.

{
  "version": "2.0",
  "articleType": "committee-reports",
  "date": "2026-04-24",
  "dataPoints": [
    { "countryCode": "SWE", "indicatorId": "GGXWDG_NGDP", "date": "2027", "value": 32.4, "provider": "imf", "projection": true, "projectionVintage": "WEO-2026-04" }
  ],
  "commentary": "IMF projects Sweden's general government gross debt at 32.4 % of GDP in 2027 (WEO Apr-2026, GGXWDG_NGDP)…",
  "source": { "imf": ["WEO:GGXWDG_NGDP"], "worldBank": [], "scb": [] }
}

3 · Rate-limit discipline

IMF advertises ~10 requests / 5 s. Exceed this and you get HTTP 429. Treat 429 as a test of discipline, not a normal state.

Pattern	Effect
`compare --countries A,B,C,D,E`	1 call, 5 countries (batched at Datamapper)
5 parallel `weo --country X`	5 calls, same data. Avoid.
`sleep 1` between CLI invocations	Keeps cumulative rate below limit
`--persist` + re-use within the same day	Zero calls for repeat indicators
Client retry on 429	Built-in 3× with 1s→2s→4s back-off

Rule: Per article, target ≤ 10 IMF calls total. Any workflow emitting > 15 IMF calls in a single run is mis-designed.

4 · Vintage discipline

4.1 Current vintage

WEO-2026-04   (published late April 2026, valid until WEO Oct-2026 ships)
FM-2026-04    (published late April 2026, aligned with WEO)

4.2 Cut-over checklist

When the IMF publishes a new flagship (April or October):

Update DEFAULT_WEO_VINTAGE in scripts/imf-client.ts.
Update vintageDiscipline.current in analysis/imf/indicators-inventory.json.
Update the banner in analysis/imf/README.md.
Add a row to the release calendar in analysis/imf/data-dictionary.md § Release calendar.
Ship all four changes in one PR titled chore(imf): cut over to WEO-YYYY-MM vintage.

4.3 Stale-vintage audit

A projection citation with a vintage tag older than 6 months is flagged in methodology-reflection.md as a stale-vintage warning. Example:

⚠️ Stale vintage — commentary cites (WEO Oct-2025, GGXWDG_NGDP) but current vintage is WEO-2026-04. Re-fetch and re-cite.

5 · Parallel IMF + World Bank split rules

Some article types naturally need both providers. Follow these rules to avoid overlap.

Article scenario	IMF role	WB role
FiU budget commentary	Macro + fiscal headline	—
SoU health-policy piece	COFOG 07, population	`SH.XPD.CHEX.GD.ZS`, `SH.MED.PHYS.ZS`
FöU defence	COFOG 02 (if monthly)	`MS.MIL.XPND.GD.ZS` (historical)
MJU climate-policy	PCPS oil benchmark	`EN.ATM.CO2E.PC`, `EG.FEC.RNEW.ZS`, `AG.LND.FRST.ZS`
KU constitutional	—	WGI (`CC.EST`, `RL.EST`, `VA.EST`, `GE.EST`)
JuU justice	—	`VC.IHR.PSRC.P5`, `CC.EST`
UbU education	COFOG 09	`SE.XPD.TOTL.GD.ZS`, `SE.PRM.ENRR`
Weekly / monthly review	Full macro + fiscal + external	Governance overlay + environment

Forbidden combinations:

Do NOT cite WB:NY.GDP.MKTP.KD.ZG alongside WEO:NGDP_RPCH as if they were independent confirmations. They measure the same thing; the newer IMF value supersedes.
Do NOT rely on WB for fiscal when IMF has an EDP-consistent answer.
Do NOT use WB environment proxies for IMF-style fiscal work.

6 · Fallback strategies

6.1 IMF upstream down

If all three data.imf.org, api.imf.org, www.imf.org return 5xx after the client's 3× retry:

Log the failure to analysis/data/imf/_outages/{date}.log.
Fall back to cached analysis/data/imf/{indicator}/{country}.json.
Add a stale-cache flag "sourceIsStale": true to economic-data.json.
Add to mcp-reliability-audit.md with severity HIGH.
Do NOT silently fall back to WB — that defeats the audit.

6.2 Country code unknown

scripts/imf-codes.ts → toImfAreaCode(iso3) throws on unknown codes. This is intentional (fail-loud). If the article needs a country not in ISO3_TO_IMF_AREA:

Verify the SDMX code via GET /structure/codelist/IMF,CL_AREA_{dataset},....
Add the mapping to ISO3_TO_IMF_AREA in scripts/imf-codes.ts.
Re-run the workflow.

6.3 Divergence with SCB

When IMF and SCB disagree on a Swedish figure (typical for unemployment, inflation) by more than the tolerance:

Unemployment: > 0.3 pp difference
Inflation: > 0.2 pp difference

…annotate BOTH values in commentary with the methodology difference:

"The IMF WEO Apr-2026 vintage pegs 2025 CPI inflation at 2.1 % (PCPIPCH) versus SCB's 2.3 % (KPIF, December-on-December). The gap reflects WEO's harmonised HICP-leaning basket."

# Recipe A — Nordic fiscal snapshot (FiU, SkU articles)
tsx scripts/imf-fetch.ts compare --indicator GGXWDG_NGDP --countries SWE,DNK,NOR,FIN,DEU --persist
tsx scripts/imf-fetch.ts compare --indicator GGXCNL_NGDP --countries SWE,DNK,NOR,FIN,DEU --persist
tsx scripts/imf-fetch.ts compare --indicator GGR_NGDP     --countries SWE,DNK,NOR,FIN,DEU --persist

# Recipe B — Sweden macro time series (commentary + chart)
tsx scripts/imf-fetch.ts weo --country SWE --indicator NGDP_RPCH --years 15 --persist
tsx scripts/imf-fetch.ts weo --country SWE --indicator PCPIPCH    --years 15 --persist
tsx scripts/imf-fetch.ts weo --country SWE --indicator LUR        --years 15 --persist

# Recipe C — High-frequency inflation (monthly, CPI)
tsx scripts/imf-fetch.ts sdmx \
  --path "/data/IMF.STA,CPI,5.0.0/SWE.CPI._T.IX.M?startPeriod=2023-01" \
  --indicator _T.IX --country SWE --persist

# Recipe D — Trade partner analysis (NU / UU articles, IMTS)
tsx scripts/imf-fetch.ts sdmx \
  --path "/data/IMF.STA,IMTS,1.0.0/SWE.XG_FOB_USD.RUS.M?startPeriod=2022-01" \
  --indicator XG_FOB_USD --country SWE --persist

# Recipe E — Commodity pass-through (MJU, FiU inflation drivers)
tsx scripts/imf-fetch.ts sdmx \
  --path "/data/IMF.RES,PCPS,9.0.0/G001.POILBRE.USD.M?startPeriod=2022-01" \
  --indicator POILBRE --country WORLD --persist

# Recipe F — COFOG spending decomposition (SoU, UbU, FöU, SfU)
tsx scripts/imf-fetch.ts sdmx \
  --path "/data/IMF.STA,GFS_COFOG,11.0.0/SWE.S13.G2MF.GF07_T.POGDP_PT.A?startPeriod=2018" \
  --indicator GF07_T --country SWE --persist

# Recipe G — Discovery: list all built-in indicator codes (no network call)
tsx scripts/imf-fetch.ts list-indicators

9 · Integration checklist (per workflow)

Workflow network.allowed includes data.imf.org, api.imf.org, www.imf.org.
Step 2.6 is IMF-first — WEO / FM calls precede any WB economic call.
Peer-set calls use compare not parallel weo.
Every projection citation has projectionVintage.
source.imf[] is non-empty for articles with economic context.
economic-data.json validates against analysis/schemas/economic-data.schema.json.
Footer attribution reads Data by IMF / SCB (or IMF / World Bank / SCB if WB-sourced governance / environment data is also cited).
Cached raw responses written to analysis/data/imf/{indicator}/{country}.json via --persist.
Article commentary cites 2–3 concrete numeric values with vintage tags.

10 · Anti-patterns (hard-stop)

Anti-pattern	Fix
Parallel `weo` calls for the Nordic peer set	Use `compare --countries SWE,DNK,NOR,FIN,DEU`
Projection citation without vintage tag	Add `(WEO Apr-2026, INDICATOR_CODE)`
Quoting WB `NY.GDP.MKTP.KD.ZG` as primary macro	Use `WEO:NGDP_RPCH`
Forecast phrasing ("Sweden is expected to…") without cited IMF value	Rewrite as "IMF projects Sweden's X at Y…"
Skipping Step 2.6 because "no economic angle"	Still run 1 `weo` call for context; write `skip: true` only for pure-process articles
Running IMF on `.github/copilot-mcp.json` as MCP	Never. IMF is CLI-via-`bash` only. No Python, no uvx.
Mixing WEO and FM values for the same code without disambiguation	Cite each with its vintage tag

11 · See also

analysis/imf/README.md — overview
analysis/imf/indicators-inventory.json — machine-readable catalogue
analysis/imf/data-dictionary.md — dataflow reference
analysis/imf/indicator-policy-mapping.md — committee matrix
analysis/imf/use-cases.md — canonical article examples
analysis/methodologies/imf-indicator-mapping.md — authoritative methodology
.github/aw/ECONOMIC_DATA_CONTRACT.md — validator contract
.github/prompts/02-mcp-access.md — shared prompt MCP/CLI reference
.github/prompts/04-analysis-pipeline.md — analysis phase integration
scripts/imf-client.ts, scripts/imf-fetch.ts, scripts/imf-codes.ts, scripts/imf-context.ts — code surface

IMF Agentic Integration Playbook

1 · Provider decision matrix

2 · Seven-step integration contract

Step 1 — Identify the policy domain & committee

Step 2 — Map committee → indicators via the inventory

Step 3 — Pre-warm IMF endpoint (cold-start protection)

Key rotation (primary ↔ secondary)

Copilot coding-agent sessions

Step 4 — Batched `compare` call for peer-set

Step 5 — Historical + projection time series (Sweden only)

Step 6 — SDMX 3.0 for non-WEO coverage

Step 7 — Write `economic-data.json`

3 · Rate-limit discipline

4 · Vintage discipline

4.1 Current vintage

4.2 Cut-over checklist

4.3 Stale-vintage audit

5 · Parallel IMF + World Bank split rules

6 · Fallback strategies

6.1 IMF upstream down

6.2 Country code unknown

6.3 Divergence with SCB

7 · Workflow-specific patterns

7.1 `news-committee-reports`

7.2 `news-propositions`

7.3 `news-motions`

7.4 `news-week-ahead` / `news-month-ahead`

7.5 `news-weekly-review` / `news-monthly-review`

7.6 `news-evening-analysis` / `news-realtime-monitor`

7.7 `news-translate`

8 · Canonical CLI recipes

9 · Integration checklist (per workflow)

10 · Anti-patterns (hard-stop)

11 · See also