bedrok 0.2.0__tar.gz

bedrok-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bedrok contributors
+
+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.

bedrok-0.2.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: bedrok
+Version: 0.2.0
+Summary: Public macroeconomic data from central banks, statistics offices and international organisations, in your AI assistant: a local MCP server and store. No keys needed to start. Not financial advice.
+Author: Andreu Paddack
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KrustyKronk/bedrok
+Project-URL: Source, https://github.com/KrustyKronk/bedrok
+Project-URL: Issues, https://github.com/KrustyKronk/bedrok/issues
+Project-URL: Changelog, https://github.com/KrustyKronk/bedrok/releases
+Keywords: macroeconomics,economic data,mcp,duckdb,sdmx,central banks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: duckdb<2,>=1.5
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: requests>=2.31.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: xlrd>=2.0.1
+Requires-Dist: mcp<3,>=2
+Requires-Dist: platformdirs>=4
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# Bedrok
+
+**Public macroeconomic data, in your AI assistant.**
+
+Bedrok is a local MCP server. Ask Claude — or any assistant that speaks MCP —
+where euro-area inflation sits in its history, how far US real yields have
+risen this year, or what the BIS credit gap says about China, and it answers
+from more than 500 curated series with deep history: US rates and the Fed's
+releases, US labour and prices, the euro area country by country, the UK, the
+OECD, the BIS, the IMF, national statistics offices from Canada to Japan,
+commodities, futures positioning and FX. Each series is fetched from the
+publisher that produces it, into a store on your own machine, with its licence
+and the line to credit it with. Percentiles always come with their sample, and
+charts come with a recipe so they look the same in every assistant.
+
+## Install
+
+**Claude Desktop:** download `bedrok-<version>.mcpb` from the
+[latest release](https://github.com/KrustyKronk/bedrok/releases/latest) and
+open it.
+
+**Claude Code** (needs [uv](https://docs.astral.sh/uv/getting-started/installation/)):
+
+```bash
+claude mcp add bedrok --scope user -- uvx --python 3.12 bedrok serve
+```
+
+**Any other MCP host:** a stdio server, `uvx --python 3.12 bedrok serve`.
+
+**No keys needed to start.** Six free keys add US GDP and PCE, retail and
+housing, energy, Germany's and Japan's national statistics, and the series
+only FRED publishes. Details, keys and the data folder: [INSTALL](docs/INSTALL.md).
+
+## The shape of it
+
+- **Local, and nothing hosted.** Each install fetches its own data from the
+  publishers; nobody redistributes anything.
+- **The publisher's terms travel with the number.** Every series carries its
+  licence class and attribution; series whose terms forbid storing them (FRED's)
+  are fetched live and never written. See [SOURCES](docs/SOURCES.md),
+  [LICENSES](docs/LICENSES.md) and the reasoning in [LICENSING](docs/LICENSING.md).
+- **It says when a number is in doubt.** Documented cases where an official
+  figure should not be taken at face value — a suspended release, a
+  restatement, a break — ride along with the answer. See
+  [WARNINGS](docs/WARNINGS.md) and what no open source provides, [GAPS](docs/GAPS.md).
+- **Fetch on demand.** A series is fetched the first time it is asked for and
+  refreshed when it goes stale.
+- **Never advice.** Bedrok measures, contextualises and premise-checks. You
+  decide. See [DISCLAIMER](docs/DISCLAIMER.md).
+
+## What it is not
+
+Not financial advice and never a buy/sell signal. No equity prices — official
+rates, FX, energy and positioning are the markets layer. Not hosted: there is
+no Bedrok server anywhere but your own machine.
+
+## Contributing
+
+A new publisher is mostly a row in a CSV. [CONTRIBUTING](CONTRIBUTING.md) says
+how, and the [source request](https://github.com/KrustyKronk/bedrok/issues/new?template=source-request.yml)
+form is the place to ask for one. Developer setup is [SETUP](docs/SETUP.md).
+The project is built in sessions with an AI assistant; `CLAUDE.md` holds its
+rules and `STATE.md` where it stands.
+
+## Docs
+
+[INSTALL](docs/INSTALL.md) · [SOURCES](docs/SOURCES.md) · [LICENSES](docs/LICENSES.md) ·
+[WARNINGS](docs/WARNINGS.md) · [GAPS](docs/GAPS.md) · [CHARTING](docs/CHARTING.md) ·
+[SETUP](docs/SETUP.md) · [LICENSING](docs/LICENSING.md) ·
+[DISCLAIMER](docs/DISCLAIMER.md) · [Plan](docs/rebuild-plan.md) ·
+[Engineering notes](docs/engineering/notes.md)
+
+Python ≥3.11 · macOS and Linux · MIT licence for the code; the data keeps its
+publishers' terms. By Andreu Paddack.

bedrok-0.2.0/README.md

@@ -0,0 +1,74 @@
+# Bedrok
+
+**Public macroeconomic data, in your AI assistant.**
+
+Bedrok is a local MCP server. Ask Claude — or any assistant that speaks MCP —
+where euro-area inflation sits in its history, how far US real yields have
+risen this year, or what the BIS credit gap says about China, and it answers
+from more than 500 curated series with deep history: US rates and the Fed's
+releases, US labour and prices, the euro area country by country, the UK, the
+OECD, the BIS, the IMF, national statistics offices from Canada to Japan,
+commodities, futures positioning and FX. Each series is fetched from the
+publisher that produces it, into a store on your own machine, with its licence
+and the line to credit it with. Percentiles always come with their sample, and
+charts come with a recipe so they look the same in every assistant.
+
+## Install
+
+**Claude Desktop:** download `bedrok-<version>.mcpb` from the
+[latest release](https://github.com/KrustyKronk/bedrok/releases/latest) and
+open it.
+
+**Claude Code** (needs [uv](https://docs.astral.sh/uv/getting-started/installation/)):
+
+```bash
+claude mcp add bedrok --scope user -- uvx --python 3.12 bedrok serve
+```
+
+**Any other MCP host:** a stdio server, `uvx --python 3.12 bedrok serve`.
+
+**No keys needed to start.** Six free keys add US GDP and PCE, retail and
+housing, energy, Germany's and Japan's national statistics, and the series
+only FRED publishes. Details, keys and the data folder: [INSTALL](docs/INSTALL.md).
+
+## The shape of it
+
+- **Local, and nothing hosted.** Each install fetches its own data from the
+  publishers; nobody redistributes anything.
+- **The publisher's terms travel with the number.** Every series carries its
+  licence class and attribution; series whose terms forbid storing them (FRED's)
+  are fetched live and never written. See [SOURCES](docs/SOURCES.md),
+  [LICENSES](docs/LICENSES.md) and the reasoning in [LICENSING](docs/LICENSING.md).
+- **It says when a number is in doubt.** Documented cases where an official
+  figure should not be taken at face value — a suspended release, a
+  restatement, a break — ride along with the answer. See
+  [WARNINGS](docs/WARNINGS.md) and what no open source provides, [GAPS](docs/GAPS.md).
+- **Fetch on demand.** A series is fetched the first time it is asked for and
+  refreshed when it goes stale.
+- **Never advice.** Bedrok measures, contextualises and premise-checks. You
+  decide. See [DISCLAIMER](docs/DISCLAIMER.md).
+
+## What it is not
+
+Not financial advice and never a buy/sell signal. No equity prices — official
+rates, FX, energy and positioning are the markets layer. Not hosted: there is
+no Bedrok server anywhere but your own machine.
+
+## Contributing
+
+A new publisher is mostly a row in a CSV. [CONTRIBUTING](CONTRIBUTING.md) says
+how, and the [source request](https://github.com/KrustyKronk/bedrok/issues/new?template=source-request.yml)
+form is the place to ask for one. Developer setup is [SETUP](docs/SETUP.md).
+The project is built in sessions with an AI assistant; `CLAUDE.md` holds its
+rules and `STATE.md` where it stands.
+
+## Docs
+
+[INSTALL](docs/INSTALL.md) · [SOURCES](docs/SOURCES.md) · [LICENSES](docs/LICENSES.md) ·
+[WARNINGS](docs/WARNINGS.md) · [GAPS](docs/GAPS.md) · [CHARTING](docs/CHARTING.md) ·
+[SETUP](docs/SETUP.md) · [LICENSING](docs/LICENSING.md) ·
+[DISCLAIMER](docs/DISCLAIMER.md) · [Plan](docs/rebuild-plan.md) ·
+[Engineering notes](docs/engineering/notes.md)
+
+Python ≥3.11 · macOS and Linux · MIT licence for the code; the data keeps its
+publishers' terms. By Andreu Paddack.

bedrok-0.2.0/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-0.2.0/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-0.2.0/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-0.2.0/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-0.2.0/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