cbtone

Hawkish/dovish tone signals from public central-bank communication, with the evaluation machinery to test whether those signals carry information about later policy decisions and market reactions.

📄 Read the paper on the web · ⬇️ Download the PDF · 📚 Documentation · 🤗 Model · 🤗 Dataset

Status: 0.1.2. The pre-registered study is complete; every testable hypothesis was refuted (see Results). One-page summary: docs/EXEC_SUMMARY.md.

Why this exists

Text-based tone indices for central banks are widely used, but three practical problems recur:

1. Coverage. Most public tooling targets the Fed and the ECB in English. Statements from other banks, in other languages, are rarely available in one comparable format.
2. Contamination. A large language model may have seen both a statement and what happened next. A score that looks predictive may reflect memory rather than reading. cbtone pairs every LLM result with a masked-text variant and a post-training-cutoff split.
3. Weak evaluation. Tone scores are often reported without a pre-registered test, a baseline or a check against simple alternatives.

cbtone fetches documents politely from central-bank websites, turns them into one schema, scores them with four scorer families (dictionary, finance-tuned transformer, local LLM, fine-tuned small model), and provides event-study and ordinal-regression tools. The research questions, metrics and decision thresholds are fixed before scoring, in docs/RESEARCH_QUESTIONS.md (tag prereg-v1).

Quickstart

pip install cbtone

cbtone fetch fed ecb mas        # polite, cached download into data/raw/<bank>/
cbtone score --scorer llm       # local LLM via Ollama; resumable, cached by content hash
cbtone events                   # event timestamps plus signed FX and 2-year-yield moves

Notes on what the three commands assume:

• Between fetch and score, build the corpus snapshot from the cache with cbtone snapshot (no network). score and events read data/corpus by default (--corpus changes it).
• --scorer llm needs a running Ollama with the model pulled (default qwen3:4b; --model changes it). Other scorers: dict, fomc-roberta, ft.
• events leaves market moves empty unless cbtone markets has produced data/raw/markets/daily.parquet first.
• MAS blocks automated access to its own site, so cbtone fetch mas reads Internet Archive copies of the statements (DECISIONS D11) and never requests mas.gov.sg. Hand-saved files in data/raw/mas/manual/ take precedence (docs/sources/NEEDED.md).

Try the scorer without any download, on the tiny committed corpus (Fed and RBA only, no network):

cbtone score --scorer dict fed rba --corpus tests/fixtures/corpus_mini --out /tmp/quick.parquet

Install

pip install cbtone                      # core: fetch, snapshot, dictionary scorer, events, analysis
pip install "cbtone[transformers]"      # FOMC-RoBERTa and other Hugging Face scorers (torch)
pip install "cbtone[api]"               # reserved for an optional hosted-API scorer (not needed to reproduce)
pip install "cbtone[finetune]"          # fine-tune a small model (transformers, torch, peft)
pip install "cbtone[docs]"              # build the documentation site (mkdocs-material)

An optional [thai] extra adds Thai word segmentation. Python 3.11 or newer. For development use uv sync (see CONTRIBUTING.md).

Supported banks and languages

Counts are from corpus snapshot 2026-10-14+ed5a49c2… (2,935 documents; docs/PROGRESS.md). Per-bank details: docs/sources/.

Where text cannot be redistributed, the repository holds URLs and SHA-256 hashes plus the fetch code, and you rebuild the text locally. See docs/sources/LICENSES.md. Known gaps are listed in docs/PROGRESS.md and docs/ANOMALIES.md.

Results

Pre-registered at tag prereg-v1; local LLM qwen3:4b (Ollama); seven headline banks; numbers from results/summary.json (regenerate with make reproduce).

Gain in next-decision log-loss over persistence by bank and scorer (RQ1). Positive values favour the text model; hollow markers are banks below the pre-registered power minimum.

The full paper is available as a PDF and online, with numbered citations and every figure; all figures (SVG, PNG and a CSV table view each) are in results/figures/.

Anomalies (for example BI's AUROC of 1.000 on 20 cases) are explained in docs/ANOMALIES.md; deviations from the pre-registration in docs/DECISIONS.md.

Disclaimer

cbtone is an independent open-source project. It is built only from public documents published by central banks. It represents no institution's view, including that of any organisation the author works for, and it is not investment advice. The text of the project describes measurable properties of documents and statistical results; it does not comment on any bank's policy choices. The Bank of Thailand adapter is opt-in and excluded from the headline results. Full statement: DISCLAIMER.md.

Documentation

Site sources are in docs/site/ (build with make docs). Design decisions are recorded in docs/DECISIONS.md, data anomalies in docs/ANOMALIES.md, and the pre-registered questions in docs/RESEARCH_QUESTIONS.md.

Citation

Please cite the paper; if you use the cbtone library, also cite the software.

@misc{chongmankhong2026reading,
  author = {Chongmankhong, Thanatchon},
  title  = {Reading the Room: Do Local-{LLM} Tone Scores of Central-Bank Communication Carry Policy Signal? Pre-registered Evidence from Seven Central Banks in Three Languages},
  year   = {2026},
  note   = {Preprint},
  url    = {https://thanatchon36.github.io/cbtone/paper/}
}

@software{chongmankhong_cbtone,
  author  = {Chongmankhong, Thanatchon},
  title   = {cbtone},
  year    = {2026},
  version = {0.1.2},
  url     = {https://github.com/thanatchon36/cbtone},
  doi     = {10.5281/zenodo.23371641}
}

GitHub also reads CITATION.cff.

Licences

• Code: Apache-2.0 (LICENSE).
• Corpus text: under each source's own terms, not under Apache-2.0. See docs/sources/LICENSES.md.
• Third-party models and data: some evaluation anchors and models (for example FOMC-RoBERTa and the FOMC communication dataset) are CC-BY-NC-4.0 and are used for evaluation only; they are not redistributed. Check the same file before commercial use.