euparliamentmonitor 0.8.25 → 0.8.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.8.25",
+  "version": "0.8.26",
   "type": "module",
   "description": "European Parliament Intelligence Platform - Monitor political activity with systematic transparency",
   "main": "scripts/index.js",

package/scripts/constants/committee-indicator-map.d.ts

@@ -10,12 +10,31 @@
  *
  * Used by news generation strategies to automatically select the right
  * economic indicators when enriching articles with World Bank data.
+ *
+ * ## ⚠️ For AI Agents / Agentic Workflows
+ *
+ * The 34 indicators in {@link WB_INDICATORS} are a **curated subset** mapped
+ * to EP committee mandates. The full World Bank catalog has **thousands** of
+ * indicators. For dynamic indicator discovery:
+ *
+ * 1. Use `search-indicators` MCP tool to find indicators by keyword on demand
+ * 2. Read `analysis/worldbank/indicator-catalog.md` for the full **200+ indicator**
+ *    reference organized by 10 EP policy domains
+ * 3. Use `analysis/worldbank/use-cases.md` to decide when indicators add editorial value
+ * 4. Use `analysis/worldbank/chart-integration-guide.md` for visualization templates
+ *
+ * **Never assume the indicators below are exhaustive.** Always consider whether
+ * `search-indicators` would reveal a more specific indicator for the policy topic.
  */
 import { ArticleCategory, AnalysisPerspective } from '../types/common.js';
 /**
  * Extended set of World Bank indicator IDs relevant to EU Parliament policy areas.
  * Superset of {@link PolicyRelevantIndicators} — includes domain-specific indicators
  * that map to individual committee mandates.
+ *
+ * ⚠️ **AI Agents**: This is a **curated subset of 34 indicators**. The World Bank
+ * has thousands more. Use `search-indicators` MCP tool for on-demand discovery.
+ * Full reference: `analysis/worldbank/indicator-catalog.md` (200+ indicators).
  */
 export declare const WB_INDICATORS: {
     /** GDP (current US$) */

package/scripts/constants/committee-indicator-map.js

@@ -12,6 +12,21 @@
  *
  * Used by news generation strategies to automatically select the right
  * economic indicators when enriching articles with World Bank data.
+ *
+ * ## ⚠️ For AI Agents / Agentic Workflows
+ *
+ * The 34 indicators in {@link WB_INDICATORS} are a **curated subset** mapped
+ * to EP committee mandates. The full World Bank catalog has **thousands** of
+ * indicators. For dynamic indicator discovery:
+ *
+ * 1. Use `search-indicators` MCP tool to find indicators by keyword on demand
+ * 2. Read `analysis/worldbank/indicator-catalog.md` for the full **200+ indicator**
+ *    reference organized by 10 EP policy domains
+ * 3. Use `analysis/worldbank/use-cases.md` to decide when indicators add editorial value
+ * 4. Use `analysis/worldbank/chart-integration-guide.md` for visualization templates
+ *
+ * **Never assume the indicators below are exhaustive.** Always consider whether
+ * `search-indicators` would reveal a more specific indicator for the policy topic.
  */
 import { ArticleCategory, AnalysisPerspective } from '../types/common.js';
 // ─── Priority Constants ──────────────────────────────────────────────────────
@@ -61,6 +76,10 @@ const N = {
  * Extended set of World Bank indicator IDs relevant to EU Parliament policy areas.
  * Superset of {@link PolicyRelevantIndicators} — includes domain-specific indicators
  * that map to individual committee mandates.
+ *
+ * ⚠️ **AI Agents**: This is a **curated subset of 34 indicators**. The World Bank
+ * has thousands more. Use `search-indicators` MCP tool for on-demand discovery.
+ * Full reference: `analysis/worldbank/indicator-catalog.md` (200+ indicators).
  */
 export const WB_INDICATORS = {
     // ── Macro-economic ──

package/scripts/index.d.ts

@@ -44,7 +44,7 @@ export { assessPoliticalThreats, buildActorThreatProfiles, buildConsequenceTree,
 export { stripHtmlTags, stripScriptBlocks } from './utils/html-sanitize.js';
 export { parseArticleFilename, formatSlug, calculateReadTime, escapeHTML, isSafeURL, validateArticleHTML, type ArticleValidationResult, } from './utils/file-utils.js';
 export { detectCategory } from './utils/article-category.js';
-export { EU_COUNTRY_CODES, EU_AGGREGATE_CODE, POLICY_INDICATORS, parseWorldBankCSV, formatIndicatorValue, getMostRecentValue, buildEconomicContext, getWorldBankCountryCode, isEUMemberState, buildEconomicContextHTML, } from './utils/world-bank-data.js';
+export { EU_COUNTRY_CODES, EU_AGGREGATE_CODE, COMPARISON_COUNTRIES, WB_AGGREGATE_LABELS, POLICY_INDICATORS, parseWorldBankCSV, formatIndicatorValue, getMostRecentValue, buildEconomicContext, getWorldBankCountryCode, isEUMemberState, buildEconomicContextHTML, } from './utils/world-bank-data.js';
 export { generateArticleHTML } from './templates/article-template.js';
 export { computeArticleQualityScore, buildTableOfContents, buildQualityScoreBadge, } from './templates/section-builders.js';
 export { ALL_LANGUAGES, LANGUAGE_PRESETS, LANGUAGE_FLAGS, LANGUAGE_NAMES, getLocalizedString, isSupportedLanguage, getTextDirection, } from './constants/language-core.js';

package/scripts/index.js

@@ -61,7 +61,7 @@ export { parseArticleFilename, formatSlug, calculateReadTime, escapeHTML, isSafe
 // ─── Article Category Detection ──────────────────────────────────────────────
 export { detectCategory } from './utils/article-category.js';
 // ─── World Bank Data Utilities ───────────────────────────────────────────────
-export { EU_COUNTRY_CODES, EU_AGGREGATE_CODE, POLICY_INDICATORS, parseWorldBankCSV, formatIndicatorValue, getMostRecentValue, buildEconomicContext, getWorldBankCountryCode, isEUMemberState, buildEconomicContextHTML, } from './utils/world-bank-data.js';
+export { EU_COUNTRY_CODES, EU_AGGREGATE_CODE, COMPARISON_COUNTRIES, WB_AGGREGATE_LABELS, POLICY_INDICATORS, parseWorldBankCSV, formatIndicatorValue, getMostRecentValue, buildEconomicContext, getWorldBankCountryCode, isEUMemberState, buildEconomicContextHTML, } from './utils/world-bank-data.js';
 // ─── Templates ───────────────────────────────────────────────────────────────
 export { generateArticleHTML } from './templates/article-template.js';
 export { computeArticleQualityScore, buildTableOfContents, buildQualityScoreBadge, } from './templates/section-builders.js';

package/scripts/types/world-bank.d.ts

@@ -69,17 +69,82 @@ export interface PolicyRelevantIndicators {
     gdp: string;
     /** GDP growth (annual %) — NY.GDP.MKTP.KD.ZG */
     gdpGrowth: string;
+    /** GDP per capita (current US$) — NY.GDP.PCAP.CD */
+    gdpPerCapita: string;
+    /** GNI per capita, Atlas method (current US$) — NY.GNP.PCAP.CD */
+    gniPerCapita: string;
     /** Inflation, consumer prices (annual %) — FP.CPI.TOTL.ZG */
     inflation: string;
     /** Unemployment, total (% of total labor force) — SL.UEM.TOTL.ZS */
     unemployment: string;
+    /** Exports of goods and services (% of GDP) — NE.EXP.GNFS.ZS */
+    exportsGdp: string;
+    /** Foreign direct investment, net inflows (BoP, current US$) — BN.KLT.DINV.CD */
+    fdiNet: string;
     /** Trade (% of GDP) — NE.TRD.GNFS.ZS */
     trade: string;
-    /** CO2 emissions (metric tons per capita) — EN.ATM.CO2E.PC */
-    co2Emissions: string;
+    /** Tax revenue (% of GDP) — GC.TAX.TOTL.GD.ZS */
+    taxRevenue: string;
+    /** General government final consumption expenditure (% of GDP) — NE.CON.GOVT.ZS */
+    govExpenditure: string;
+    /** Military expenditure (% of GDP) — MS.MIL.XPND.GD.ZS */
+    militaryExpenditure: string;
     /** Population, total — SP.POP.TOTL */
     population: string;
+    /** Life expectancy at birth, total (years) — SP.DYN.LE00.IN */
+    lifeExpectancy: string;
+    /** Birth rate, crude (per 1,000 people) — SP.DYN.CBRT.IN */
+    birthRate: string;
+    /** Death rate, crude (per 1,000 people) — SP.DYN.CDRT.IN */
+    deathRate: string;
+    /** Individuals using the Internet (% of population) — IT.NET.USER.ZS */
+    internetUsers: string;
+    /** Current health expenditure (% of GDP) — SH.XPD.CHEX.GD.ZS */
+    healthExpenditure: string;
+    /** Physicians (per 1,000 people) — SH.MED.PHYS.ZS */
+    physicians: string;
+    /** Hospital beds (per 1,000 people) — SH.MED.BEDS.ZS */
+    hospitalBeds: string;
+    /** Government expenditure on education, total (% of GDP) — SE.XPD.TOTL.GD.ZS */
+    educationExpenditure: string;
+    /** CO2 emissions (metric tons per capita) — EN.ATM.CO2E.PC */
+    co2Emissions: string;
+    /** Renewable energy consumption (% of total) — EG.FEC.RNEW.ZS */
+    renewableEnergy: string;
     /** Research and development expenditure (% of GDP) — GB.XPD.RSDV.GD.ZS */
     rdExpenditure: string;
+    /** High-technology exports (% of manufactured exports) — TX.VAL.TECH.MF.ZS */
+    hightechExports: string;
+}
+/**
+ * World Bank MCP tool names available for data fetching.
+ * Maps to the tool functions on the worldbank-mcp server.
+ *
+ * These type literals use **kebab-case** (e.g., `get-economic-data`) to match
+ * the underlying tool registration names in worldbank-mcp@1.0.0
+ * (`server.tool('get-economic-data', ...)`).
+ * When called via the MCP gateway prefix in this repository's workflows, use
+ * the corresponding **snake_case** form, for example
+ * `world_bank___get_economic_data(...)`.
+ *
+ * **Note:** The codebase also has a `WorldBankMCPClient.getIndicatorForCountry()`
+ * wrapper (in `src/mcp/wb-mcp-client.ts`) that calls the `get_indicator_for_country`
+ * tool — this is a legacy convenience method not listed in this type union since it
+ * is not part of the standard worldbank-mcp tool surface.
+ */
+export type WBMCPToolName = 'get-economic-data' | 'get-social-data' | 'get-health-data' | 'get-education-data' | 'get-country-info' | 'get-countries' | 'search-indicators';
+/**
+ * World Bank MCP tool indicator key mapping.
+ * Maps each tool to the indicator key literals it accepts.
+ */
+export interface WBToolIndicatorKeys {
+    /** Economic indicators accepted by `get-economic-data` */
+    'get-economic-data': 'GDP' | 'GDP_GROWTH' | 'GDP_PER_CAPITA' | 'GNI' | 'GNI_PER_CAPITA' | 'EXPORTS_GDP' | 'FDI_NET' | 'INFLATION' | 'UNEMPLOYMENT';
+    /** Social indicators accepted by `get-social-data` */
+    'get-social-data': 'POPULATION' | 'LIFE_EXPECTANCY' | 'BIRTH_RATE' | 'DEATH_RATE' | 'INTERNET_USERS';
+    /** Health indicators accepted by `get-health-data` */
+    'get-health-data': 'HEALTH_EXPENDITURE' | 'PHYSICIANS' | 'HOSPITAL_BEDS' | 'IMMUNIZATION' | 'HIV_PREVALENCE' | 'MALNUTRITION' | 'TUBERCULOSIS';
+    /** Education indicators accepted by `get-education-data` */
+    'get-education-data': 'LITERACY_RATE' | 'SCHOOL_ENROLLMENT' | 'SCHOOL_COMPLETION' | 'TEACHERS_PRIMARY' | 'EDUCATION_EXPENDITURE';
 }
 //# sourceMappingURL=world-bank.d.ts.map

package/scripts/utils/world-bank-data.d.ts

@@ -9,6 +9,22 @@
  * Functions in this module are designed to be stateless and avoid observable
  * side effects, with the exception of explicitly recording metadata such as
  * data timestamps in returned objects.
+ *
+ * ## ⚠️ For AI Agents / Agentic Workflows
+ *
+ * The constants below ({@link POLICY_INDICATORS}, {@link EU_COUNTRY_CODES},
+ * {@link COMPARISON_COUNTRIES}) are a **convenience subset** used by TypeScript
+ * code for formatting and parsing. They do **NOT** represent the full World Bank
+ * indicator inventory.
+ *
+ * **For indicator selection in articles and analysis:**
+ * 1. Read `analysis/worldbank/indicator-catalog.md` — **200+ indicators** by EP policy domain
+ * 2. Use `search-indicators` MCP tool to **discover indicators on demand** by keyword
+ * 3. Read `analysis/worldbank/eu-country-mapping.md` for country codes + comparison groups
+ * 4. Read `analysis/worldbank/chart-integration-guide.md` for Chart.js + Mermaid templates
+ *
+ * The World Bank MCP server has thousands of indicators beyond the ones listed
+ * here. Use `search-indicators` to find the best match for any policy topic.
  */
 import type { EconomicContext, PolicyRelevantIndicators, WorldBankIndicator } from '../types/world-bank.js';
 /**
@@ -18,9 +34,25 @@ import type { EconomicContext, PolicyRelevantIndicators, WorldBankIndicator } fr
 export declare const EU_COUNTRY_CODES: Readonly<Record<string, string>>;
 /** EU aggregate code in World Bank (European Union) */
 export declare const EU_AGGREGATE_CODE = "EUU";
+/**
+ * Comparison country codes for benchmarking EU performance against global peers.
+ * Organized by geopolitical relevance to EU Parliament policy analysis.
+ */
+export declare const COMPARISON_COUNTRIES: Readonly<Record<string, string>>;
+/**
+ * Aggregate/region codes useful for EU benchmarking.
+ * Keys are World Bank group codes; values are human-readable labels.
+ */
+export declare const WB_AGGREGATE_LABELS: Readonly<Record<string, string>>;
 /**
  * World Bank indicator IDs relevant to EU Parliament policy analysis.
- * These indicators map to common policy areas discussed in EP legislation.
+ *
+ * ⚠️ **AI Agents**: This is a convenience subset of 25 core indicators used by
+ * TypeScript formatting code. The World Bank has **thousands** of indicators.
+ * For article/analysis generation:
+ * - Read `analysis/worldbank/indicator-catalog.md` for the full **200+ indicator** reference
+ * - Use `search-indicators` MCP tool to discover indicators on demand by keyword
+ * - See `analysis/worldbank/use-cases.md` for when each indicator type adds value
  */
 export declare const POLICY_INDICATORS: PolicyRelevantIndicators;
 /**

package/scripts/utils/world-bank-data.js

@@ -37,19 +37,96 @@ export const EU_COUNTRY_CODES = {
 };
 /** EU aggregate code in World Bank (European Union) */
 export const EU_AGGREGATE_CODE = 'EUU';
+/**
+ * Comparison country codes for benchmarking EU performance against global peers.
+ * Organized by geopolitical relevance to EU Parliament policy analysis.
+ */
+export const COMPARISON_COUNTRIES = {
+    // ── G7 Non-EU ──
+    US: 'USA', // United States
+    GB: 'GBR', // United Kingdom (post-Brexit benchmark)
+    JP: 'JPN', // Japan
+    CA: 'CAN', // Canada
+    // ── BRICS ──
+    CN: 'CHN', // China
+    IN: 'IND', // India
+    BR: 'BRA', // Brazil
+    RU: 'RUS', // Russia
+    ZA: 'ZAF', // South Africa
+    // ── EU Candidate States ──
+    UA: 'UKR', // Ukraine
+    TR: 'TUR', // Türkiye
+    RS: 'SRB', // Serbia
+    ME: 'MNE', // Montenegro
+    AL: 'ALB', // Albania
+    MK: 'MKD', // North Macedonia
+    MD: 'MDA', // Moldova
+    BA: 'BIH', // Bosnia & Herzegovina
+    GE: 'GEO', // Georgia
+    // ── Key Trade Partners ──
+    KR: 'KOR', // South Korea
+    AU: 'AUS', // Australia
+    NO: 'NOR', // Norway (EEA)
+    CH: 'CHE', // Switzerland (EFTA)
+    IL: 'ISR', // Israel
+};
+/**
+ * Aggregate/region codes useful for EU benchmarking.
+ * Keys are World Bank group codes; values are human-readable labels.
+ */
+export const WB_AGGREGATE_LABELS = {
+    EUU: 'European Union',
+    EMU: 'Euro area',
+    OED: 'OECD members',
+    WLD: 'World',
+    ECS: 'Europe & Central Asia',
+    NAC: 'North America',
+    EAS: 'East Asia & Pacific',
+    SSF: 'Sub-Saharan Africa',
+};
 /**
  * World Bank indicator IDs relevant to EU Parliament policy analysis.
- * These indicators map to common policy areas discussed in EP legislation.
+ *
+ * ⚠️ **AI Agents**: This is a convenience subset of 25 core indicators used by
+ * TypeScript formatting code. The World Bank has **thousands** of indicators.
+ * For article/analysis generation:
+ * - Read `analysis/worldbank/indicator-catalog.md` for the full **200+ indicator** reference
+ * - Use `search-indicators` MCP tool to discover indicators on demand by keyword
+ * - See `analysis/worldbank/use-cases.md` for when each indicator type adds value
  */
 export const POLICY_INDICATORS = {
+    // Macro-economic (get-economic-data)
     gdp: 'NY.GDP.MKTP.CD',
     gdpGrowth: 'NY.GDP.MKTP.KD.ZG',
+    gdpPerCapita: 'NY.GDP.PCAP.CD',
+    gniPerCapita: 'NY.GNP.PCAP.CD',
     inflation: 'FP.CPI.TOTL.ZG',
     unemployment: 'SL.UEM.TOTL.ZS',
+    exportsGdp: 'NE.EXP.GNFS.ZS',
+    fdiNet: 'BN.KLT.DINV.CD',
+    // Trade & fiscal
     trade: 'NE.TRD.GNFS.ZS',
-    co2Emissions: 'EN.ATM.CO2E.PC',
+    taxRevenue: 'GC.TAX.TOTL.GD.ZS',
+    govExpenditure: 'NE.CON.GOVT.ZS',
+    militaryExpenditure: 'MS.MIL.XPND.GD.ZS',
+    // Social (get-social-data)
     population: 'SP.POP.TOTL',
+    lifeExpectancy: 'SP.DYN.LE00.IN',
+    birthRate: 'SP.DYN.CBRT.IN',
+    deathRate: 'SP.DYN.CDRT.IN',
+    internetUsers: 'IT.NET.USER.ZS',
+    // Health (get-health-data)
+    healthExpenditure: 'SH.XPD.CHEX.GD.ZS',
+    physicians: 'SH.MED.PHYS.ZS',
+    hospitalBeds: 'SH.MED.BEDS.ZS',
+    // Education (get-education-data)
+    educationExpenditure: 'SE.XPD.TOTL.GD.ZS',
+    // Environment & energy
+    co2Emissions: 'EN.ATM.CO2E.PC',
+    renewableEnergy: 'EG.FEC.RNEW.ZS',
+    // Research & innovation
     rdExpenditure: 'GB.XPD.RSDV.GD.ZS',
+    hightechExports: 'TX.VAL.TECH.MF.ZS',
 };
 // ─── CSV Parsing ─────────────────────────────────────────────────────────────
 /** Known CSV header aliases for each World Bank field */
@@ -194,7 +271,16 @@ export function formatIndicatorValue(value, indicatorId) {
         indicatorId === POLICY_INDICATORS.inflation ||
         indicatorId === POLICY_INDICATORS.unemployment ||
         indicatorId === POLICY_INDICATORS.trade ||
-        indicatorId === POLICY_INDICATORS.rdExpenditure) {
+        indicatorId === POLICY_INDICATORS.taxRevenue ||
+        indicatorId === POLICY_INDICATORS.govExpenditure ||
+        indicatorId === POLICY_INDICATORS.militaryExpenditure ||
+        indicatorId === POLICY_INDICATORS.exportsGdp ||
+        indicatorId === POLICY_INDICATORS.healthExpenditure ||
+        indicatorId === POLICY_INDICATORS.educationExpenditure ||
+        indicatorId === POLICY_INDICATORS.internetUsers ||
+        indicatorId === POLICY_INDICATORS.renewableEnergy ||
+        indicatorId === POLICY_INDICATORS.rdExpenditure ||
+        indicatorId === POLICY_INDICATORS.hightechExports) {
         return `${value.toFixed(1)}%`;
     }
     // CO2 emissions - metric tons per capita
@@ -232,12 +318,29 @@ export function buildEconomicContext(countryCode, countryName, indicatorData) {
     const indicatorNames = {
         [POLICY_INDICATORS.gdp]: 'GDP',
         [POLICY_INDICATORS.gdpGrowth]: 'GDP Growth',
+        [POLICY_INDICATORS.gdpPerCapita]: 'GDP per Capita',
+        [POLICY_INDICATORS.gniPerCapita]: 'GNI per Capita',
         [POLICY_INDICATORS.inflation]: 'Inflation',
         [POLICY_INDICATORS.unemployment]: 'Unemployment',
+        [POLICY_INDICATORS.exportsGdp]: 'Exports (% of GDP)',
+        [POLICY_INDICATORS.fdiNet]: 'FDI Net Inflows',
         [POLICY_INDICATORS.trade]: 'Trade (% of GDP)',
-        [POLICY_INDICATORS.co2Emissions]: 'CO₂ Emissions',
+        [POLICY_INDICATORS.taxRevenue]: 'Tax Revenue (% of GDP)',
+        [POLICY_INDICATORS.govExpenditure]: 'Gov. Expenditure (% of GDP)',
+        [POLICY_INDICATORS.militaryExpenditure]: 'Military Expenditure (% of GDP)',
         [POLICY_INDICATORS.population]: 'Population',
-        [POLICY_INDICATORS.rdExpenditure]: 'R&D Expenditure',
+        [POLICY_INDICATORS.lifeExpectancy]: 'Life Expectancy',
+        [POLICY_INDICATORS.birthRate]: 'Birth Rate',
+        [POLICY_INDICATORS.deathRate]: 'Death Rate',
+        [POLICY_INDICATORS.internetUsers]: 'Internet Users (%)',
+        [POLICY_INDICATORS.healthExpenditure]: 'Health Expenditure (% of GDP)',
+        [POLICY_INDICATORS.physicians]: 'Physicians (per 1,000)',
+        [POLICY_INDICATORS.hospitalBeds]: 'Hospital Beds (per 1,000)',
+        [POLICY_INDICATORS.educationExpenditure]: 'Education Expenditure (% of GDP)',
+        [POLICY_INDICATORS.co2Emissions]: 'CO₂ Emissions',
+        [POLICY_INDICATORS.renewableEnergy]: 'Renewable Energy (%)',
+        [POLICY_INDICATORS.rdExpenditure]: 'R&D Expenditure (% of GDP)',
+        [POLICY_INDICATORS.hightechExports]: 'High-Tech Exports (%)',
     };
     for (const [indicatorId, dataPoints] of indicatorData) {
         const recent = getMostRecentValue(dataPoints);