bedrok 0.2.0__py3-none-any.whl

bedrok/__init__.py

@@ -0,0 +1,22 @@
+"""Bedrok — a local store of public macroeconomic and market data, for analysis
+from inside an AI assistant.
+
+The package is layered, and the direction of dependency is one way:
+
+    surfaces -> ops -> engines -> ingest -> core
+
+  core/      configuration, the store, and shared vocabulary
+  ingest/    source adapters and the sync drivers
+  engines/   the analysis maths — percentiles, rates
+  ops/       the audit reports and the connectivity check
+  surfaces/  things that render the store for a human or an assistant
+
+`config` and `store` are re-exported here because they are the documented
+embedding entry point — a sandbox session does `from bedrok import config;
+config.set_profile(...)`, and that recipe is written down in
+docs/engineering/notes.md. Those two names do not move. Everything else should
+be imported from its real home so the layer it belongs to stays visible.
+"""
+from bedrok.core import config, store  # noqa: F401
+
+__all__ = ["config", "store"]

bedrok/__main__.py

@@ -0,0 +1,75 @@
+"""Bedrok CLI — one entry point over the store and the engines.
+
+  bedrok [--profile PATH] <command> [command args...]
+
+Commands:
+  smoke        connectivity check, one call per data source
+  backfill     full deep historical pull (idempotent)  [--only ids --stage S]
+  refresh      incremental sync of the local store
+  validate     coverage + trust audit (staleness, licence)
+  query        read-only SQL over the store           "SELECT ..." [--csv]
+  tieout       compare re-pointed series with the store [--only ids]
+  doctor       store + freshness report               (offline; run this first)
+  schema       the store's table/column layout
+  pctile       percentile of a series' latest value    SERIES_ID [--value V --since D]
+  rates        EUR-investor rates/inflation toolkit   [--csv]
+  serve        MCP server over stdio, for Claude and other assistants
+  docs         regenerate docs/SOURCES.md and docs/LICENSES.md  [--check]
+
+The profile (user config + data) resolves from --profile, $BEDROK_PROFILE, or
+./profile. See docs/SETUP.md.
+"""
+from __future__ import annotations
+
+import sys
+
+_COMMANDS = {
+    "smoke": "bedrok.ops.smoke",
+    "backfill": "bedrok.ingest.backfill",
+    "refresh": "bedrok.ingest.refresh",
+    "validate": "bedrok.ops.validate",
+    "query": "bedrok.core.query",
+    "tieout": "bedrok.ops.tieout",
+    "doctor": "bedrok.ops.doctor",
+    "schema": "bedrok.core.schema",
+    "pctile": "bedrok.engines.pctile",
+    "rates": "bedrok.engines.rates_infl",
+    "serve": "bedrok.surfaces.mcp_server",
+    "docs": "bedrok.ops.docs",
+}
+
+
+def main() -> int:
+    argv = sys.argv[1:]
+
+    profile = None
+    if "--profile" in argv:
+        i = argv.index("--profile")
+        try:
+            profile = argv[i + 1]
+        except IndexError:
+            print("--profile requires a path", file=sys.stderr)
+            return 2
+        argv = argv[:i] + argv[i + 2:]
+
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print(__doc__)
+        return 0
+    cmd, rest = argv[0], argv[1:]
+    if cmd not in _COMMANDS:
+        print(f"unknown command {cmd!r}\n", file=sys.stderr)
+        print(__doc__)
+        return 2
+
+    from bedrok.core import config
+    if profile:
+        config.set_profile(profile)
+
+    import importlib
+    mod = importlib.import_module(_COMMANDS[cmd])
+    sys.argv = [f"bedrok {cmd}"] + rest
+    return mod.main()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bedrok/core/__init__.py

@@ -0,0 +1,5 @@
+"""Foundations: configuration, the store, and vocabulary shared by everything.
+
+Nothing here imports from ingest, engines, ops or surfaces. If something in this
+package needs one of those, it is in the wrong package.
+"""

bedrok/core/aliases.py

@@ -0,0 +1,25 @@
+"""One id per concept: the ids that point at another.
+
+The bulk families name a series by family and geography (`hicp_yoy_es`); the
+seed names the most-asked ones by geography first (`es_hicp_yoy`), the
+convention every instruction teaches. Where both exist they are the same
+number from the same dataset, so the family id becomes an alias: it still
+answers, with `alias_of` naming the canonical id, but it is neither stored nor
+listed (session 11, after the feedback session found the duplicates).
+
+Pure data, in core: nothing here imports a layer above.
+"""
+from __future__ import annotations
+
+ALIASES: dict[str, str] = {
+    "hicp_yoy_ea": "ea_hicp_yoy",
+    "hicp_yoy_es": "es_hicp_yoy",
+    "hicp_yoy_de": "de_hicp_yoy",
+    "hicp_yoy_fr": "fr_hicp_yoy",
+    "gdp_qoq_ea20": "ea_gdp_qoq",
+    "gdp_qoq_es": "es_gdp_qoq",
+}
+
+
+def canonical(series_id: str) -> str:
+    return ALIASES.get(series_id, series_id)

bedrok/core/charting.py

@@ -0,0 +1,176 @@
+"""The chart recipe: what every Bedrok chart says, whoever draws it.
+
+Bedrok does not draw. The assistant in the host does, with whatever chart tool
+that host has, so two charts drawn in two places used to look like two
+products. What Bedrok can fix is the content: the same title rules, the same
+subtitle carrying the units, the same axes, colours, labels, source line and
+footnotes, every time. The prose version is bedrok/seeds/charting.md
+(bedrok://charting); this module is the arithmetic of it.
+
+The house decisions (2026-10-11): two vertical scales when units differ; units
+in the subtitle and on the vertical axis, never in the title; a chart by
+default, a table only when asked; short answers.
+
+Pure data, in core: nothing here imports a layer above.
+"""
+from __future__ import annotations
+
+import math
+from datetime import date
+
+# Okabe–Ito, without its yellow (unreadable on white): seven hues that stay
+# distinct for the common forms of colour blindness. Assigned in the order the
+# series were asked for, so a series keeps its colour across charts.
+PALETTE = ["#0072B2", "#E69F00", "#009E73", "#D55E00", "#56B4E9", "#CC79A7", "#7F7F7F"]
+
+# The house style, repeated on every recipe so a host that never read
+# bedrok://charting still draws it the same way.
+LAYOUT = {
+    "container": "a card with a border",
+    "title": "top, bold; never carries units",
+    "subtitle": "under the title; carries the units and how the data is measured",
+    "legend": "below the chart; clicking a series hides or shows it",
+    "source": "one line under the legend",
+    "footnotes": "under the source line, smaller",
+    "toggle": "a switch between the chart and a table of the same numbers",
+    "y_axis": "labelled with the units; left scale solid lines, right scale dashed",
+    "x_axis": "the labels given, every `tick_every`-th one shown",
+    "gaps": "leave empty: never draw a line across a null",
+    "type": "lines; bars only when every series has a single period",
+}
+
+_HOW_WORDS = {
+    ("weekly", "last"): "weekly closes", ("weekly", "mean"): "weekly averages",
+    ("weekly", "sum"): "weekly totals", ("weekly", "first"): "first value of each week",
+    ("monthly", "mean"): "monthly averages", ("monthly", "last"): "month-end values",
+    ("monthly", "sum"): "monthly totals", ("monthly", "first"): "first value of each month",
+    ("quarterly", "mean"): "quarterly averages", ("quarterly", "last"): "quarter-end values",
+    ("quarterly", "sum"): "quarterly totals", ("quarterly", "first"): "first value of each quarter",
+    ("annual", "mean"): "annual averages", ("annual", "last"): "year-end values",
+    ("annual", "sum"): "annual totals", ("annual", "first"): "first value of each year",
+}
+_MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+MAX_TICKS = 10
+
+
+def colour(i: int) -> str:
+    return PALETTE[i % len(PALETTE)]
+
+
+def title_suggestion(names: list[str]) -> str:
+    """One series: its name. Two: both. More: the first and a count. The
+    assistant may always replace it; it never carries units."""
+    if not names:
+        return ""
+    if len(names) == 1:
+        return names[0]
+    if len(names) == 2:
+        return f"{names[0]} and {names[1]}"
+    return f"{names[0]} and {len(names) - 1} others"
+
+
+def axes(series: list[tuple[str, str]]) -> dict:
+    """[(id, units)] → which series go on the left scale and which on the right.
+
+    One unit: one scale. Two: the first-listed series' units on the left, the
+    other on the right. Three or more cannot be read on two scales: the first
+    two groups are placed and `problem` says what to do instead."""
+    groups: list[str] = []
+    for _, u in series:
+        if u not in groups:
+            groups.append(u)
+    left = [i for i, u in series if u == groups[0]] if groups else []
+    right = [i for i, u in series if len(groups) > 1 and u == groups[1]]
+    out = {"left": {"units": groups[0] if groups else None, "series": left},
+           "right": {"units": groups[1], "series": right} if len(groups) > 1 else None,
+           "problem": None}
+    if len(groups) > 2:
+        dropped = [i for i, u in series if u in groups[2:]]
+        out["problem"] = (f"{len(groups)} different units cannot share two scales; "
+                          f"{', '.join(dropped)} are not placed. Draw two charts, or ask "
+                          "for transform='index_to' so every series is an index.")
+    return out
+
+
+def _span_label(d: date, frequency: str) -> str:
+    if frequency == "quarterly":
+        return f"Q{(d.month - 1) // 3 + 1} {d.year}"
+    if frequency == "annual":
+        return str(d.year)
+    return f"{_MONTHS[d.month - 1]} {d.year}"
+
+
+def subtitle(placed: dict, frequency: str, how: str | None, first: date | None,
+             last: date | None) -> str:
+    """Units first (per scale when there are two), then how the data is
+    measured, then the span: "Percent; weekly closes; Oct 2023 to Oct 2026"."""
+    def cap(u: str | None) -> str:
+        return (u[:1].upper() + u[1:]) if u else ""
+    if placed.get("right"):
+        units = f"Left: {placed['left']['units']}. Right: {placed['right']['units']}"
+    else:
+        units = cap(placed["left"]["units"])
+    parts = [units]
+    parts.append(_HOW_WORDS.get((frequency, how or ""), frequency))
+    if first and last:
+        parts.append(f"{_span_label(first, frequency)} to {_span_label(last, frequency)}")
+    return "; ".join(p for p in parts if p)
+
+
+def x_labels(dates: list[date], frequency: str) -> dict:
+    """Labels by frequency, and how many to skip so about ten show."""
+    def one(d: date) -> str:
+        if frequency == "weekly":
+            return f"{d.day} {_MONTHS[d.month - 1]} {d.year}"
+        if frequency == "monthly":
+            return f"{_MONTHS[d.month - 1]} {str(d.year)[2:]}"
+        if frequency == "quarterly":
+            return f"Q{(d.month - 1) // 3 + 1} {str(d.year)[2:]}"
+        return str(d.year)
+    n = len(dates)
+    return {"labels": [one(d) for d in dates],
+            "tick_every": max(1, math.ceil(n / MAX_TICKS))}
+
+
+def source_line(publishers: list[tuple[str, bool, bool]]) -> str:
+    """[(publisher name, personal use?, fetched live?)] → one line, each
+    publisher once, in order, with its condition when it has one."""
+    seen, parts = set(), []
+    for name, personal, live in publishers:
+        if name in seen:
+            continue
+        seen.add(name)
+        cond = [c for c, on in (("personal use only", personal), ("fetched live, not stored", live)) if on]
+        parts.append(name + (f" ({', '.join(cond)})" if cond else ""))
+    return "Source: " + "; ".join(parts) + "." if parts else ""
+
+
+def footnotes(entries: list[dict], table: dict, frequency: str) -> list[str]:
+    """Everything the chart cannot say by itself, one short line each: the
+    loud warnings for the period shown, periods not over or missing a part,
+    a cut, and series drawn as steps."""
+    notes: list[str] = []
+    names = {e["series_id"]: e.get("name", e["series_id"]) for e in entries}
+    for e in entries:
+        for w in e.get("warnings") or []:
+            period = w.get("period_start") or ""
+            if w.get("period_end"):
+                period += f" to {w['period_end']}"
+            # The whole effect: warning texts are kept short in the seed, and a
+            # cut at the first ". " breaks on abbreviations ("incl.").
+            line = f"{names[e['series_id']]}, {period}: {(w.get('effect_on_data') or '').strip()}"
+            if line not in notes:
+                notes.append(line)
+    for sid, stepped in (table.get("stepped") or {}).items():
+        if stepped:
+            notes.append(f"{names.get(sid, sid)} is published less often than {frequency}; "
+                         "it is drawn as a step, each value held until the next.")
+    for sid, partial in (table.get("partial_last") or {}).items():
+        if partial:
+            notes.append(f"{names.get(sid, sid)}: the latest period is not over yet.")
+    for sid, short in (table.get("incomplete") or {}).items():
+        notes.append(f"{names.get(sid, sid)}: {', '.join(short)} hold only part of their period "
+                     "(a month or quarter not published).")
+    if table.get("cut"):
+        notes.append(table["cut"])
+    return notes

bedrok/core/config.py

@@ -0,0 +1,228 @@
+"""Bedrok configuration: profile resolution, profile.toml parsing, DB connection.
+
+A *profile* (the Bedrok home folder) holds everything user-specific:
+
+    <home>/
+    ├── profile.toml          # the config parsed here (all keys optional)
+    ├── data/market.duckdb    # the store — one file; $BEDROK_DB overrides the path
+    └── .env                  # API keys, all optional (chmod 600); which source
+                              # reads which: bedrok/seeds/sources.csv
+
+The catalog and the source list are not in the profile: they ship inside the
+package, in bedrok/seeds/ (SEEDS_DIR), so an installed wheel has them too.
+
+Resolution order for the home folder: explicit `set_profile()` (CLI --profile)
+→ $BEDROK_PROFILE (what the Claude Desktop bundle's folder field sets) →
+legacy $FDP_ROOT → ./profile under the current directory → the per-user data
+folder (~/Library/Application Support/bedrok on macOS, ~/.local/share/bedrok
+on Linux). There is always a home, so a fresh install needs no setup: the
+first `bedrok serve` creates the folder and the store. The DB path may be
+overridden independently via $BEDROK_DB (legacy $FDP_DB).
+
+An environment value that is an unfilled placeholder — `${user_config.x}`,
+which a Claude Desktop bundle may pass for a blank optional field — counts as
+unset, here and for API keys (core/sources.py).
+"""
+from __future__ import annotations
+
+import importlib.resources
+import os
+from pathlib import Path
+
+try:
+    import tomllib  # stdlib from 3.11
+except ModuleNotFoundError:  # 3.10 sandboxes (Cowork's system python) need the backport
+    import tomli as tomllib
+
+import duckdb
+
+try:
+    from dotenv import load_dotenv
+except ImportError:  # read-only runs don't need python-dotenv
+    def load_dotenv(*_a, **_k):
+        return False
+
+
+# ---- defaults (a missing/empty profile.toml gets exactly these) -------------
+# Sections a profile.toml carries that are not listed here pass through _merge
+# untouched and are simply never read — a [market] block from the days of the
+# pack, or the portfolio-era [broker]/[sleeves]/[strategy], load without error.
+_DEFAULTS = {
+    "owner": {"name": "Investor"},
+    "base": {"currency": "EUR", "symbol": "€"},
+    "macro": {"hicp_europe": True},
+}
+
+
+def _merge(base: dict, over: dict) -> dict:
+    out = dict(base)
+    for k, v in over.items():
+        out[k] = _merge(base[k], v) if isinstance(v, dict) and isinstance(base.get(k), dict) else v
+    return out
+
+
+# The seeds ship inside the package and are found through the package itself,
+# never by counting ".parent" off a file: that once repointed every seed path
+# when config.py moved into core/, and an installed wheel has no repo root at all.
+SEEDS_DIR = Path(str(importlib.resources.files("bedrok") / "seeds"))
+
+
+def unset(value: str | None) -> bool:
+    """True for a missing, blank, or unfilled-placeholder (`${...}`) value."""
+    v = (value or "").strip()
+    return not v or (v.startswith("${") and v.endswith("}"))
+
+
+def default_home() -> Path:
+    """The per-user data folder a fresh install uses."""
+    import platformdirs
+    return Path(platformdirs.user_data_dir("bedrok", appauthor=False))
+
+
+def _resolve_default_dir() -> Path:
+    for env in ("BEDROK_PROFILE", "FDP_ROOT"):
+        if not unset(os.getenv(env)):
+            return Path(os.getenv(env).strip()).expanduser()
+    cwd_profile = Path.cwd() / "profile"
+    if cwd_profile.is_dir():
+        return cwd_profile
+    return default_home()
+
+
+# ---- module state (recomputed by set_profile) -------------------------------
+PROFILE_DIR: Path | None = None
+PROFILE: dict = dict(_DEFAULTS)
+ROOT: Path | None = None
+DATA_DIR: Path | None = None
+DB_PATH: Path | None = None
+BASE_CCY = "EUR"
+BASE_SYMBOL = "€"
+
+
+
+def fx_pairs() -> list[tuple[str, str, str]]:
+    """(pair, source, code) list for sync_fx, derived from the base currency.
+
+    ECB reference rates are EUR-based; non-EUR bases get 'derived' cross pairs
+    computed from them at sync time (best-effort — EUR is the fully-tested path).
+    """
+    # The engines look up f"{BASE_CCY}{ccy}", so the store carries the three
+    # fetchable pairs plus their reciprocals; EUR, GBP and USD bases all resolve.
+    fetchable = [
+        ("EURUSD", "ecb", "EXR/D.USD.EUR.SP00.A"),
+        ("EURGBP", "ecb", "EXR/D.GBP.EUR.SP00.A"),
+        ("GBPUSD", "fedboard", "H10:RXI$US_N.B.UK"),  # FRED's DEXUSUK is this H.10 series
+    ]
+    derived = [
+        ("USDEUR", "derived", "1/EURUSD"),
+        ("GBPEUR", "derived", "1/EURGBP"),
+        ("USDGBP", "derived", "1/GBPUSD"),
+    ]
+    if BASE_CCY in ("EUR", "USD", "GBP"):
+        return fetchable + derived
+    raise SystemExit(
+        f"base currency {BASE_CCY!r} not supported yet "
+        "(EUR/USD/GBP ship as a full cross set; others need new pairs)")
+
+
+def set_profile(path: str | Path | None = None) -> None:
+    """Load (or reload) the profile and recompute all module paths/settings."""
+    global PROFILE_DIR, PROFILE, ROOT, DATA_DIR, DB_PATH
+    global BASE_CCY, BASE_SYMBOL
+
+    PROFILE_DIR = Path(path) if path else _resolve_default_dir()
+    toml_data = {}
+    if PROFILE_DIR and (PROFILE_DIR / "profile.toml").exists():
+        toml_data = tomllib.loads((PROFILE_DIR / "profile.toml").read_text())
+    PROFILE = _merge(_DEFAULTS, toml_data)
+
+    ROOT = PROFILE_DIR
+    DATA_DIR = PROFILE_DIR / "data" if PROFILE_DIR else None
+    db_env = next((os.getenv(e) for e in ("BEDROK_DB", "FDP_DB") if not unset(os.getenv(e))), None)
+    DB_PATH = Path(db_env) if db_env else (DATA_DIR / "market.duckdb" if DATA_DIR else None)
+
+    BASE_CCY = PROFILE["base"]["currency"].upper()
+    BASE_SYMBOL = PROFILE["base"]["symbol"]
+
+    # A Claude Desktop bundle sets every key it declares, blank or as the
+    # unfilled `${user_config.x}`, and load_dotenv never overrides a variable
+    # that exists — so a blank field would hide the same key in the home
+    # folder's .env. Clear blank and placeholder keys first, then load .env.
+    for name in [k for k, v in os.environ.items() if k.endswith("_API_KEY") and unset(v)]:
+        del os.environ[name]
+    if PROFILE_DIR:
+        load_dotenv(PROFILE_DIR / ".env")
+    # Keys stay in the environment: core/sources.py reads the one a source
+    # names (`key_env`) at the moment it is needed.
+
+
+def require_profile() -> Path:
+    if PROFILE_DIR is None:
+        raise SystemExit(
+            "No Bedrok home folder resolved. Pass --profile PATH or set "
+            "$BEDROK_PROFILE. See docs/INSTALL.md.")
+    return PROFILE_DIR
+
+
+def require_key(name: str) -> str:
+    val = os.getenv(name)
+    if not val:
+        raise RuntimeError(
+            f"{name} missing. Add it to "
+            f"{PROFILE_DIR / '.env' if PROFILE_DIR else 'your profile .env'}.")
+    return val
+
+
+def sandbox_copy_recipe() -> str:
+    """The copy-store workaround, spelled out with this profile's real path."""
+    db = Path(DB_PATH) if DB_PATH else Path("profile/data/market.duckdb")
+    return (
+        "  Writes are impossible against a read-only mount. To work anyway:\n"
+        "    mkdir -p /tmp/bedrok/data\n"
+        f"    cp '{db}'* /tmp/bedrok/data/\n"
+        f"    export BEDROK_DB=/tmp/bedrok/data/{db.name}\n"
+        "  then re-run. NOTE: everything written to /tmp DIES WITH THE SESSION —\n"
+        "  replay the refresh Mac-side afterwards."
+    )
+
+
+def _open(path: Path, read_only: bool) -> duckdb.DuckDBPyConnection:
+    """duckdb.connect, with the read-only-mount WAL failure made actionable.
+
+    DuckDB removes the `.wal` when it opens a database. The Cowork mount permits
+    write and truncate but NOT unlink, so any `.wal` left behind by an earlier
+    command makes every subsequent open fail — the first write of a session
+    works and the second does not, which reads as an intermittent fault rather
+    than a permission model. `store.close_checkpointed` stops us leaving one;
+    this turns somebody else's leftover into instructions instead of a traceback.
+    """
+    try:
+        return duckdb.connect(str(path), read_only=read_only)
+    except duckdb.IOException as e:
+        msg = str(e)
+        if "Could not remove file" not in msg or ".wal" not in msg:
+            raise
+        raise SystemExit(
+            f"Cannot open {path}: a stale write-ahead log is in the way and this "
+            f"filesystem does not allow deleting it.\n"
+            f"  {msg.strip()}\n\n"
+            f"  This mount allows writing and truncating but not unlinking, so\n"
+            f"  emptying the file works where removing it does not:\n"
+            f"    : > '{path}.wal'\n"
+            f"  then re-run. If that is also refused, copy the store instead:\n"
+            f"{sandbox_copy_recipe()}") from e
+
+
+def connect(read_only: bool = False) -> duckdb.DuckDBPyConnection:
+    """Open the profile's one store at DB_PATH."""
+    require_profile()
+    if DB_PATH is None:
+        raise SystemExit("no store path resolved (profile has no data/ dir?)")
+    DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    if read_only and not DB_PATH.exists():
+        raise SystemExit(f"no store at {DB_PATH} — run `bedrok backfill` to build it.")
+    return _open(DB_PATH, read_only)
+
+
+# Initialise from environment/cwd at import; the CLI re-calls set_profile(--profile).
+set_profile()

bedrok/core/geography.py

@@ -0,0 +1,97 @@
+"""Places: which geography a series is about, and which words name one.
+
+One table, used by search (a place in the question filters the catalog rather
+than being scored like any other word), by the warnings search, and by the
+test that every name leads with its geography.
+
+Series ids carry their geography in one of two places: first, by convention
+(`es_hicp_yoy`, `us_10y`), or last, for the families the bulk stages build
+(`hicp_core_es`, `gdp_qoq_ea20`, `oecd_cli_deu`). Commodity and positioning
+series have no geography of their own: "us" in `wb_banana_us` is where the
+banana price is quoted, not a country to search by.
+
+Pure data, in core: nothing here imports a layer above.
+"""
+from __future__ import annotations
+
+import re
+
+# id code → how names begin (the names test) and a readable label.
+CODES = {
+    "us": "US", "ea": "Euro area", "eu": "EU", "uk": "UK", "jp": "Japan",
+    "cn": "China", "ca": "Canada", "au": "Australia", "ch": "Switzerland",
+    "de": "Germany", "fr": "France", "it": "Italy", "es": "Spain",
+    "nl": "Netherlands", "be": "Belgium", "at": "Austria", "pt": "Portugal",
+    "ie": "Ireland", "el": "Greece", "fi": "Finland", "se": "Sweden",
+    "no": "Norway", "dk": "Denmark",
+}
+
+# Words a person types for a place → its code. Two-letter country codes that
+# are also common words (it, no, de, es, at, be, ie) are deliberately absent:
+# "it" in a question is a pronoun before it is Italy.
+NAMES = {
+    "us": "us", "usa": "us", "america": "us", "american": "us", "united states": "us",
+    "uk": "uk", "britain": "uk", "british": "uk", "united kingdom": "uk", "england": "uk",
+    "euro area": "ea", "eurozone": "ea", "euro-area": "ea", "ea": "ea",
+    "eu": "eu", "european union": "eu",
+    "japan": "jp", "japanese": "jp", "china": "cn", "chinese": "cn",
+    "canada": "ca", "canadian": "ca", "australia": "au", "australian": "au",
+    "switzerland": "ch", "swiss": "ch", "germany": "de", "german": "de",
+    "france": "fr", "french": "fr", "italy": "it", "italian": "it",
+    "spain": "es", "spanish": "es", "netherlands": "nl", "dutch": "nl",
+    "belgium": "be", "belgian": "be", "austria": "at", "austrian": "at",
+    "portugal": "pt", "portuguese": "pt", "ireland": "ie", "irish": "ie",
+    "greece": "el", "greek": "el", "finland": "fi", "finnish": "fi",
+    "sweden": "se", "swedish": "se", "norway": "no", "norwegian": "no",
+    "denmark": "dk", "danish": "dk",
+}
+
+# Where an id suffix spells a place differently: OECD's ISO-3 codes and
+# Eurostat's euro-area and EU aggregates.
+_SUFFIX = {"usa": "us", "deu": "de", "fra": "fr", "ita": "it", "esp": "es", "gbr": "uk",
+           "jpn": "jp", "chn": "cn", "ea20": "ea", "ea21": "ea", "eu27": "eu", "cn": "cn"}
+
+# ISO 3166 alpha-2 where it differs from the id code (the warnings carry ISO).
+ISO2 = {**{c: c.upper() for c in CODES}, "uk": "GB", "el": "GR", "ea": "", "eu": ""}
+
+# Sources whose series are not about a country.
+_PLACELESS_SOURCES = {"worldbank", "cftc"}
+
+
+def of_series(series_id: str, source: str | None = None) -> str | None:
+    """The geography code a series is about, or None."""
+    if source in _PLACELESS_SOURCES:
+        return None
+    sid = series_id.lower()
+    first = sid.split("_", 1)[0]
+    if first in CODES:
+        return first
+    sid = re.sub(r"_eu27_2020$", "_eu27", sid)
+    last = sid.rsplit("_", 1)[-1]
+    if last in _SUFFIX:
+        return _SUFFIX[last]
+    return last if last in CODES and "_" in sid else None
+
+
+def in_text(text: str) -> tuple[set[str], list[str]]:
+    """(codes of the places named, the other words), two-word names first."""
+    words = re.findall(r"[a-z0-9-]+", text.lower())
+    codes, rest, i = set(), [], 0
+    while i < len(words):
+        pair = " ".join(words[i:i + 2])
+        if i + 1 < len(words) and pair in NAMES:
+            codes.add(NAMES[pair])
+            i += 2
+            continue
+        if words[i] in NAMES:
+            codes.add(NAMES[words[i]])
+        else:
+            rest.append(words[i])
+        i += 1
+    return codes, rest
+
+
+def words_for_iso2(iso2: str) -> set[str]:
+    """Every single word in NAMES that names the country with this ISO code."""
+    codes = {c for c, iso in ISO2.items() if iso and iso == (iso2 or "").upper()}
+    return {w for w, c in NAMES.items() if c in codes and " " not in w}