cape-aeri 0.1.0__tar.gz

cape_aeri-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CAPE Economic Research and Consulting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cape_aeri-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: cape-aeri
+Version: 0.1.0
+Summary: AERI article scoring and country-month economic-risk index library.
+Author: Shakir Adeyemi Tewogbade
+License: MIT
+Project-URL: Homepage, https://github.com/CAPE-ERC/aeri-library
+Project-URL: Issues, https://github.com/CAPE-ERC/aeri-library/issues
+Keywords: economics,news,risk-index,africa,nlp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# aeri
+
+AERI article scoring and country-month economic-risk index library, built
+from the AERI/ARS work at CAPE Economic Research and Consulting.
+
+This first release covers **Library 1** from the proposal: scoring each
+scraped news article and rolling the scores up into the country-month
+AERI (Africa Economic Risk Index). Pillar composite indices, the ARS
+composite score and early-warning alerts (Libraries 2-4) are planned as
+follow-up PRs on top of this foundation. Matching conventions, data
+layout and output schema are kept consistent with the sibling
+[`newsindex`](https://github.com/CAPE-ERC/newsindex-library) (EPU) library
+and the production AERI Pillar API, so the CAPE libraries interoperate.
+
+## Install
+
+```bash
+pip install cape-aeri  # the import name is still `aeri`: import aeri
+```
+
+For development:
+
+```bash
+pip install -e ".[test]"
+```
+
+## Quickstart
+
+```python
+import aeri
+
+dictionary = aeri.dictionary.load("data/aeri_country_keywords.json")
+articles = aeri.read_articles("path/to/Shak_Scrapped_Top_Articles")
+
+scored = aeri.score_articles(articles, dictionary)
+
+aeri_df = aeri.compute_aeri(scored)
+diag = aeri.diagnostics(scored)
+aeri_df = aeri.coverage_filter(aeri_df, diag)  # drop thin country-months
+```
+
+## Data format
+
+`read_articles()` expects the on-disk layout produced by CAPE's scraper:
+
+```
+<root>/<Country>/<Publisher>/<YYYY-MM>/articles_<Publisher>_<YYYY-MM>.csv(.gz)
+```
+
+Each CSV has columns `site`, `date`, `title`, `url`, `text`. `country` is
+not a column -- it's the top-level folder name, added by `read_articles()`
+along with `year_month`.
+
+`read_articles()` does **not** auto-canonicalize country folder names
+(matching `newsindex`'s loader). A folder like `Morocco_new` is kept
+distinct from `Morocco` rather than silently merged -- it may be a
+deliberately separate re-scrape. Apply `aeri.countries.canonicalize()`
+yourself once you've decided whether/how to merge it.
+
+## Scoring pipeline
+
+| Function | What it does |
+| --- | --- |
+| `normalize_text()` | Strip HTML; standardise case, whitespace and Unicode |
+| `is_relevant()` | Economic relevance flag `R_i`, per the article's country dictionary |
+| `severity_tier()` | Ordinal severity `S_i` from 0 to 4; the highest tier matched wins |
+| `confidence_weight()` | `W_i = clip(1 + 0.5*TitleHint + 0.2*LongText + 0.3*MultiPillar, 1, 2)` |
+| `assign_pillars()` | Flags for the 8 pillars; one article can activate several |
+| `article_score()` | `A_i = R_i * S_i * W_i` |
+| `compute_aeri()` | `AERI = 100 * sum(A_i) / N_t` for each country and month |
+| `diagnostics()` | Total/relevant articles, relevant share, average confidence, average severity among relevant articles |
+| `coverage_filter()` | Keeps country-months with at least 100 articles |
+
+`score_articles()` runs the per-article functions over an articles
+DataFrame in one pass. Relevance, severity and pillar matching run on the
+article's **title and body concatenated** (`x_i = title + " " + text`),
+and matching is **word-boundary aware** (`aeri.match`), not substring
+search -- e.g. the severity term `"war"` does not match inside `"warning"`
+or `"forward"`. `compute_aeri()` / `diagnostics()` output `Country`,
+`Period` (`YYYY-MM`), `AERI`, `TotalArticles`, `RelevantArticles`,
+`RelevantSharePct`, `AvgConfidence`, `AvgSeverityAmongRelevant` -- the
+same column names as the production `aeri_country_period.csv` /
+`aeri_diagnostics.csv` already consumed by the AERI Pillar API.
+
+The 8 pillars (`aeri.config.PILLARS`) are named to match the Pillar API's
+catalog: `InflationRisk`, `FXExternalRisk`, `DebtFiscalRisk`,
+`FinancialSectorRisk`, `GrowthRealEconomyRisk`, `CommoditySupplyRisk`,
+`PoliticalEconomyRisk`, `ClimateDisasterRisk`.
+
+## Dictionaries
+
+`data/aeri_country_keywords.json` is the real, production EPTU-schema
+keyword dictionary (54 African countries, Economic/Policy/Uncertainty
+term lists) shared with `newsindex`. `is_relevant()` defaults to the
+Economic component alone for `R_i` -- **this default is an assumption**;
+no source document specified whether Policy terms should also count
+toward relevance. Add `"policy"` via `AERIConfig.relevance_components` to
+include them:
+
+```python
+from aeri import AERIConfig
+config = AERIConfig(relevance_components=("economic", "policy"))
+```
+
+The **severity-tier and pillar keyword lists have no equivalent
+production source** -- nothing in the underlying research materials
+defines them as keyword lists, only conceptually ("mild concern" through
+"crisis-level language"). `aeri.config.DEFAULT_SEVERITY_KEYWORDS` and
+`DEFAULT_PILLAR_KEYWORDS` are a first-pass, hand-curated starting point
+that needs calibration before being treated as final. Every scoring
+function takes an `AERIConfig` to override them without forking the
+library.
+
+The `TitleHint`/`LongText`/`MultiPillar` thresholds inside
+`confidence_weight()` (title relevance; >=300 words; >=2 active pillars)
+are likewise placeholders -- the exact numeric cutoffs used in the
+original research were not found in any available source and need
+confirmation.
+
+## Roadmap
+
+- Pillar composite indices and PCA-combined pillar measure (Library 2)
+- `ars` composite score (Library 3): `ARS = 100 * (0.40*Intensity + 0.25*Breadth + 0.20*Severity + 0.15*Structure)`, risk bands at 20/40/60/80
+- `riskalert` early-warning alerts (Library 4)
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```

cape_aeri-0.1.0/README.md

@@ -0,0 +1,131 @@
+# aeri
+
+AERI article scoring and country-month economic-risk index library, built
+from the AERI/ARS work at CAPE Economic Research and Consulting.
+
+This first release covers **Library 1** from the proposal: scoring each
+scraped news article and rolling the scores up into the country-month
+AERI (Africa Economic Risk Index). Pillar composite indices, the ARS
+composite score and early-warning alerts (Libraries 2-4) are planned as
+follow-up PRs on top of this foundation. Matching conventions, data
+layout and output schema are kept consistent with the sibling
+[`newsindex`](https://github.com/CAPE-ERC/newsindex-library) (EPU) library
+and the production AERI Pillar API, so the CAPE libraries interoperate.
+
+## Install
+
+```bash
+pip install cape-aeri  # the import name is still `aeri`: import aeri
+```
+
+For development:
+
+```bash
+pip install -e ".[test]"
+```
+
+## Quickstart
+
+```python
+import aeri
+
+dictionary = aeri.dictionary.load("data/aeri_country_keywords.json")
+articles = aeri.read_articles("path/to/Shak_Scrapped_Top_Articles")
+
+scored = aeri.score_articles(articles, dictionary)
+
+aeri_df = aeri.compute_aeri(scored)
+diag = aeri.diagnostics(scored)
+aeri_df = aeri.coverage_filter(aeri_df, diag)  # drop thin country-months
+```
+
+## Data format
+
+`read_articles()` expects the on-disk layout produced by CAPE's scraper:
+
+```
+<root>/<Country>/<Publisher>/<YYYY-MM>/articles_<Publisher>_<YYYY-MM>.csv(.gz)
+```
+
+Each CSV has columns `site`, `date`, `title`, `url`, `text`. `country` is
+not a column -- it's the top-level folder name, added by `read_articles()`
+along with `year_month`.
+
+`read_articles()` does **not** auto-canonicalize country folder names
+(matching `newsindex`'s loader). A folder like `Morocco_new` is kept
+distinct from `Morocco` rather than silently merged -- it may be a
+deliberately separate re-scrape. Apply `aeri.countries.canonicalize()`
+yourself once you've decided whether/how to merge it.
+
+## Scoring pipeline
+
+| Function | What it does |
+| --- | --- |
+| `normalize_text()` | Strip HTML; standardise case, whitespace and Unicode |
+| `is_relevant()` | Economic relevance flag `R_i`, per the article's country dictionary |
+| `severity_tier()` | Ordinal severity `S_i` from 0 to 4; the highest tier matched wins |
+| `confidence_weight()` | `W_i = clip(1 + 0.5*TitleHint + 0.2*LongText + 0.3*MultiPillar, 1, 2)` |
+| `assign_pillars()` | Flags for the 8 pillars; one article can activate several |
+| `article_score()` | `A_i = R_i * S_i * W_i` |
+| `compute_aeri()` | `AERI = 100 * sum(A_i) / N_t` for each country and month |
+| `diagnostics()` | Total/relevant articles, relevant share, average confidence, average severity among relevant articles |
+| `coverage_filter()` | Keeps country-months with at least 100 articles |
+
+`score_articles()` runs the per-article functions over an articles
+DataFrame in one pass. Relevance, severity and pillar matching run on the
+article's **title and body concatenated** (`x_i = title + " " + text`),
+and matching is **word-boundary aware** (`aeri.match`), not substring
+search -- e.g. the severity term `"war"` does not match inside `"warning"`
+or `"forward"`. `compute_aeri()` / `diagnostics()` output `Country`,
+`Period` (`YYYY-MM`), `AERI`, `TotalArticles`, `RelevantArticles`,
+`RelevantSharePct`, `AvgConfidence`, `AvgSeverityAmongRelevant` -- the
+same column names as the production `aeri_country_period.csv` /
+`aeri_diagnostics.csv` already consumed by the AERI Pillar API.
+
+The 8 pillars (`aeri.config.PILLARS`) are named to match the Pillar API's
+catalog: `InflationRisk`, `FXExternalRisk`, `DebtFiscalRisk`,
+`FinancialSectorRisk`, `GrowthRealEconomyRisk`, `CommoditySupplyRisk`,
+`PoliticalEconomyRisk`, `ClimateDisasterRisk`.
+
+## Dictionaries
+
+`data/aeri_country_keywords.json` is the real, production EPTU-schema
+keyword dictionary (54 African countries, Economic/Policy/Uncertainty
+term lists) shared with `newsindex`. `is_relevant()` defaults to the
+Economic component alone for `R_i` -- **this default is an assumption**;
+no source document specified whether Policy terms should also count
+toward relevance. Add `"policy"` via `AERIConfig.relevance_components` to
+include them:
+
+```python
+from aeri import AERIConfig
+config = AERIConfig(relevance_components=("economic", "policy"))
+```
+
+The **severity-tier and pillar keyword lists have no equivalent
+production source** -- nothing in the underlying research materials
+defines them as keyword lists, only conceptually ("mild concern" through
+"crisis-level language"). `aeri.config.DEFAULT_SEVERITY_KEYWORDS` and
+`DEFAULT_PILLAR_KEYWORDS` are a first-pass, hand-curated starting point
+that needs calibration before being treated as final. Every scoring
+function takes an `AERIConfig` to override them without forking the
+library.
+
+The `TitleHint`/`LongText`/`MultiPillar` thresholds inside
+`confidence_weight()` (title relevance; >=300 words; >=2 active pillars)
+are likewise placeholders -- the exact numeric cutoffs used in the
+original research were not found in any available source and need
+confirmation.
+
+## Roadmap
+
+- Pillar composite indices and PCA-combined pillar measure (Library 2)
+- `ars` composite score (Library 3): `ARS = 100 * (0.40*Intensity + 0.25*Breadth + 0.20*Severity + 0.15*Structure)`, risk bands at 20/40/60/80
+- `riskalert` early-warning alerts (Library 4)
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+```

cape_aeri-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cape-aeri"
+version = "0.1.0"
+description = "AERI article scoring and country-month economic-risk index library."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Shakir Adeyemi Tewogbade" },
+]
+keywords = ["economics", "news", "risk-index", "africa", "nlp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "pandas>=1.5",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/CAPE-ERC/aeri-library"
+Issues = "https://github.com/CAPE-ERC/aeri-library/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

cape_aeri-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cape_aeri-0.1.0/src/aeri/__init__.py

@@ -0,0 +1,39 @@
+"""aeri: AERI article scoring and country-month economic-risk index library."""
+
+from __future__ import annotations
+
+from . import config, countries, dictionary, match
+from .articles import read_articles
+from .config import DEFAULT_CONFIG, PILLARS, AERIConfig
+from .confidence import confidence_weight
+from .index import compute_aeri, coverage_filter, diagnostics
+from .pillars import active_pillar_count, assign_pillars
+from .relevance import is_relevant
+from .scoring import article_score, score_articles
+from .severity import severity_tier
+from .text import normalize_text
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "config",
+    "countries",
+    "dictionary",
+    "match",
+    "AERIConfig",
+    "DEFAULT_CONFIG",
+    "PILLARS",
+    "normalize_text",
+    "is_relevant",
+    "severity_tier",
+    "confidence_weight",
+    "assign_pillars",
+    "active_pillar_count",
+    "article_score",
+    "score_articles",
+    "compute_aeri",
+    "diagnostics",
+    "coverage_filter",
+    "read_articles",
+    "__version__",
+]

cape_aeri-0.1.0/src/aeri/articles.py

@@ -0,0 +1,63 @@
+"""Read scraped article archives into a single table.
+
+Expects the on-disk layout produced by CAPE's scraper: ``<root>/<country>/
+<newspaper>/<year-month>/articles_<newspaper>_<year-month>.csv(.gz)``, each
+file holding the columns ``site``, ``date``, ``title``, ``url``, ``text``.
+Matches the loader in the sibling ``newsindex`` package so both libraries
+read the same archive the same way.
+
+The inferred ``country`` is the raw top-level folder name -- it is **not**
+auto-canonicalized against :mod:`aeri.countries`, because a folder like
+``"Morocco_new"`` may be a deliberately separate corpus (a re-scrape) and
+silently merging it into ``"Morocco"`` could conflate two different data
+sources. Apply :func:`aeri.countries.canonicalize` yourself once you've
+decided that's the right thing to do for your archive.
+"""
+
+from __future__ import annotations
+
+import html
+from pathlib import Path
+
+import pandas as pd
+
+_REQUIRED_COLUMNS = ("site", "date", "title", "url", "text")
+
+
+def _unescape(value: object) -> object:
+    if not isinstance(value, str):
+        return value
+    return html.unescape(value)
+
+
+def read_articles(root: str | Path, *, encoding: str = "utf-8") -> pd.DataFrame:
+    """Read every ``articles_*.csv`` / ``articles_*.csv.gz`` file under
+    ``root`` into one table, adding ``country`` (the top-level folder name)
+    and ``year_month`` (the first seven characters of ``date``) columns.
+
+    Article titles and text are HTML-unescaped (the scraper stores raw
+    HTML entities such as ``&#8217;``) before they reach `aeri.match`.
+    """
+    root = Path(root)
+    files = sorted({*root.glob("**/*.csv.gz"), *root.glob("**/*.csv")})
+    if not files:
+        raise FileNotFoundError(f"no article files found under {root}")
+
+    frames: list[pd.DataFrame] = []
+    for file in files:
+        country = file.relative_to(root).parts[0]
+        frame = pd.read_csv(file, encoding=encoding, compression="infer")
+        missing = [col for col in _REQUIRED_COLUMNS if col not in frame.columns]
+        if missing:
+            raise ValueError(f"{file}: missing column(s) {missing}")
+        frame["country"] = country
+        frame["source_file"] = str(file)
+        frames.append(frame)
+
+    combined = pd.concat(frames, ignore_index=True)
+    combined["title"] = combined["title"].map(_unescape)
+    combined["text"] = combined["text"].map(_unescape)
+    combined["year_month"] = combined["date"].astype(str).str.slice(0, 7)
+    return combined[
+        ["country", "site", "year_month", "date", "title", "url", "text", "source_file"]
+    ]

cape_aeri-0.1.0/src/aeri/confidence.py

@@ -0,0 +1,45 @@
+"""Confidence weighting for article scores."""
+
+from __future__ import annotations
+
+from .config import DEFAULT_CONFIG, AERIConfig
+from .dictionary import CountryDictionary
+from .pillars import active_pillar_count, assign_pillars
+from .relevance import is_relevant
+from .text import normalize_text, word_count
+
+
+def confidence_weight(
+    title: str,
+    text: str,
+    entry: CountryDictionary,
+    pillar_flags: dict[str, bool] | None = None,
+    config: AERIConfig = DEFAULT_CONFIG,
+) -> float:
+    """W_i = clip(1 + 0.5*TitleHint + 0.2*LongText + 0.3*MultiPillar, 1, 2).
+
+    - TitleHint: the title itself carries an economic-relevance signal
+      (per the country's dictionary).
+    - LongText: the article body is at least `long_text_word_threshold`
+      words (normalized word count). This threshold is a placeholder --
+      no source document gave the real cutoff; see README.
+    - MultiPillar: the article activates `multi_pillar_threshold` or more
+      of the 8 pillars.
+
+    `pillar_flags` can be passed in to reuse an `assign_pillars()` result
+    already computed for this article; otherwise it is derived from `text`.
+    """
+    title_hint = 1.0 if is_relevant(title, entry, config) else 0.0
+
+    normalized_text = normalize_text(text)
+    long_text = 1.0 if word_count(normalized_text) >= config.long_text_word_threshold else 0.0
+
+    if pillar_flags is None:
+        pillar_flags = assign_pillars(text, config)
+    multi_pillar = (
+        1.0 if active_pillar_count(pillar_flags) >= config.multi_pillar_threshold else 0.0
+    )
+
+    weight = 1.0 + 0.5 * title_hint + 0.2 * long_text + 0.3 * multi_pillar
+    low, high = config.confidence_bounds
+    return min(max(weight, low), high)

cape_aeri-0.1.0/src/aeri/config.py

@@ -0,0 +1,126 @@
+"""Configuration and default keyword sets for AERI scoring.
+
+The economic-relevance dictionary is real production data loaded
+separately via :mod:`aeri.dictionary` (country-specific, see
+``data/aeri_country_keywords.json``). The severity-tier and pillar
+keyword sets below have **no equivalent production source** -- no
+dictionary for them was found anywhere in the underlying research
+materials -- so these are a first-pass, hand-curated starting point that
+needs calibration against real coverage before being treated as final.
+Every scoring function accepts an `AERIConfig` so a project can supply
+its own keyword sets without forking the library.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping, Sequence
+
+#: The 8 AERI risk pillars, named to match the production AERI Pillar API
+#: catalog (`InflationRisk`, `FXExternalRisk`, ...) and the
+#: `aeri_pillars_country_period.csv` column headers it publishes.
+PILLARS: tuple[str, ...] = (
+    "InflationRisk",
+    "FXExternalRisk",
+    "DebtFiscalRisk",
+    "FinancialSectorRisk",
+    "GrowthRealEconomyRisk",
+    "CommoditySupplyRisk",
+    "PoliticalEconomyRisk",
+    "ClimateDisasterRisk",
+)
+
+DEFAULT_SEVERITY_KEYWORDS: dict[int, tuple[str, ...]] = {
+    1: (
+        "concern", "warning", "pressure", "risk", "slowdown", "softening",
+        "worry", "caution", "uncertainty",
+    ),
+    2: (
+        "falling", "decline", "drop", "shortage", "strain", "weakening",
+        "job losses", "cutbacks", "downgrade", "rising prices", "protest",
+        "strike",
+    ),
+    3: (
+        "crisis", "collapse", "plunge", "default", "devaluation", "emergency",
+        "unrest", "shutdown", "severe shortage", "mass layoffs", "coup",
+        "credit downgrade",
+    ),
+    4: (
+        "catastrophe", "famine", "hyperinflation", "economic collapse",
+        "state of emergency", "war", "coup d'etat", "humanitarian crisis",
+        "bankruptcy", "sovereign default", "civil war", "mass starvation",
+        "currency collapse",
+    ),
+}
+
+DEFAULT_PILLAR_KEYWORDS: dict[str, tuple[str, ...]] = {
+    "InflationRisk": (
+        "inflation", "deflation", "consumer price", "cost of living",
+        "price hike", "price increase", "food price", "fuel price", "cpi",
+        "disinflation", "hyperinflation", "rising prices",
+    ),
+    "FXExternalRisk": (
+        "exchange rate", "devaluation", "depreciation", "currency", "forex",
+        "foreign reserves", "balance of payments", "current account",
+        "trade deficit", "capital flight", "remittance", "export", "import",
+    ),
+    "DebtFiscalRisk": (
+        "public debt", "sovereign debt", "fiscal deficit", "budget deficit",
+        "treasury", "government spending", "austerity", "imf", "world bank",
+        "bailout", "credit rating", "default", "bond", "eurobond",
+        "tax revenue",
+    ),
+    "FinancialSectorRisk": (
+        "bank", "banking sector", "interest rate", "central bank",
+        "monetary policy", "non-performing loan", "liquidity",
+        "credit crunch", "stock exchange", "bond market", "financial sector",
+        "lending rate",
+    ),
+    "GrowthRealEconomyRisk": (
+        "gdp", "economic growth", "recession", "unemployment", "job losses",
+        "manufacturing", "industrial output", "retail sales",
+        "consumer spending", "business confidence", "economic slowdown",
+    ),
+    "CommoditySupplyRisk": (
+        "commodity price", "oil price", "gas price", "mining", "agriculture",
+        "harvest", "food supply", "supply chain", "shortage",
+        "import dependency", "wheat", "maize", "fertilizer",
+    ),
+    "PoliticalEconomyRisk": (
+        "election", "coup", "protest", "strike", "sanctions", "corruption",
+        "policy reform", "political instability", "government shutdown",
+        "regulation", "nationalization", "unrest",
+    ),
+    "ClimateDisasterRisk": (
+        "drought", "flood", "famine", "climate change", "natural disaster",
+        "cyclone", "locust", "food insecurity", "humanitarian crisis",
+        "displacement", "crop failure",
+    ),
+}
+
+
+@dataclass(frozen=True)
+class AERIConfig:
+    """Bundles the thresholds and (non-relevance) keyword sets used across
+    the pipeline. Severity and pillar keywords default to the first-pass
+    sets above; relevance is intentionally not part of this config -- it
+    comes from a country-keyed :class:`aeri.dictionary.Dictionary`.
+    """
+
+    severity_keywords: Mapping[int, Sequence[str]] = field(
+        default_factory=lambda: DEFAULT_SEVERITY_KEYWORDS
+    )
+    pillar_keywords: Mapping[str, Sequence[str]] = field(
+        default_factory=lambda: DEFAULT_PILLAR_KEYWORDS
+    )
+    long_text_word_threshold: int = 300
+    multi_pillar_threshold: int = 2
+    confidence_bounds: tuple[float, float] = (1.0, 2.0)
+    coverage_min_articles: int = 100
+    #: Which dictionary component(s) count toward R_i. Defaults to the
+    #: Economic component alone; add "policy" to also count policy terms.
+    #: Unverified against source -- see README.
+    relevance_components: tuple[str, ...] = ("economic",)
+
+
+DEFAULT_CONFIG = AERIConfig()