In 30 seconds: ContinuityBreakDetector ingests public time-series data, runs deterministic statistical backtests, ranks candidate continuity breaks or regime shifts, and can optionally let ML/LLM reviewers critique the results. The core remains deterministic, auditable, and usable without Docker or ML.
ContinuityBreakDetector is not a typical anomaly detector.
It is a deterministic analysis pipeline followed by a structured AI review layer, built around a simple idea: AI as a reviewer, not a decision maker.
It ingests long-run public time series, computes statistical features, runs rolling backtests, ranks candidate continuity breaks, and filters likely artifacts. All these stages are deterministic, reproducible, and fully inspectable.
The system does not rely on AI for detection. LLMs are introduced only after the analytical pipeline, where they interpret, challenge, and contextualize the results through a set of specialized agents.
In many real-world datasets, the problem is not just noise or missing values—the signal itself changes regime. A process shifts. A sensor behaves differently. A dataset stops being "the same story."
ContinuityBreakDetector provides the structure to:
- Identify structural breaks across heterogeneous domains.
- Audit whether a break is a real-world event or a data artifact (e.g., source revisions).
- Explain the results using a committee of specialized agents.
public data -> deterministic core -> audit artifacts -> committee review -> reports
flowchart LR
OWID["Our World in Data"] --> ING["Ingestion"]
WB["World Bank"] --> ING
ING --> NORM["Normalization (Parquet)"]
NORM --> STATS["Statistics<br/>deterministic core"]
STATS --> BACKTEST["Backtesting Engine<br/>deterministic core"]
BACKTEST --> RANK["Ranking"]
RANK --> AUDIT["Audit"]
AUDIT --> ARTIFACT["Artifact Detection"]
ARTIFACT --> LLM["Optional LLM Analysis<br/>Committee of Agents"]
LLM --> PUB["Publication outputs"]
For design details, see ARCHITECTURE.md and the ML architecture notes.
The system is built around a strict two-layer architecture.
- Deterministic Layer: Produces evidence: forecast errors, ranked candidates, audit scores, artifact flags, and reproducibility metadata. It uses Python, Pandas, and Parquet for efficiency and auditability.
- Interpretative Layer: A structured set of agents (skeptic, auditor, interpreter) reads those artifacts and produces a critical review.
By isolating heavy ML dependencies (TimesFM, Chronos) in Docker workers and keeping the core logic deterministic, the system remains lightweight and easy to verify.
Run an end-to-end deterministic study from embedded fixture data in seconds. It does not require network access, heavy ML models, or LLM keys.
python -m pip install -e '.[test]'
cbd demo_studycbd --help
cbd demo_study
cbd list_forecasters
cbd backtest_advanced
cbd analyze_agents --study-path studies/backtests/<study_id>The demo writes structured artifacts to studies/demo_study/:
summary.json: High-level study statistics and top break candidates.study.md: A human-readable report summarizing the findings.data_artifact_audit.json: Detailed scoring of artifact risk for each candidate.forecast_errors.parquet: The raw evidence used for ranking.
Example of a human-readable summary generated by the demo:
[Skeptic]
Top candidate: 2012
Assessment:
- Strong statistical signal across multiple domains.
- High artifact risk due to source revision patterns.
Conclusion: Likely a data artifact rather than a real-world event.
The project is built with the standards expected in production tools:
pytest -q # Current verified result: 149 passed
ruff check . # Linting and style consistency
mypy . # Type safety verificationCoverage can be measured locally with:
pytest --cov=continuity_break_detector --cov-report=term-missingAdvanced models such as TimesFM and Chronos run in isolated Docker workers. They are optional and do not add ML dependencies to the core Python environment.
Use this quickstart for setup and commands:
Architecture and contract details:
- Ingestion: fetches public-source data and stores raw responses with metadata.
- Normalization: converts source-specific payloads into a common yearly schema.
- Statistics: computes growth, log growth, acceleration, rolling z-scores, and break scores.
- Backtesting: evaluates whether future values became difficult to predict from prior windows.
- Ranking: groups anomalies into cross-domain candidate break years using heuristic weights documented in docs/scoring.md.
- Audit: checks robustness, model agreement, source coverage, sparsity, and known explanations.
- Artifact detection: flags likely data artifacts, source dominance, extreme statistical values, and model echoes using heuristic scoring subject to tuning.
- Publication outputs: produces compact reports and optional draft material from deterministic results.
- Deterministic baseline forecasting:
naive_last_value,linear_trend,exponential_trend - Optional advanced forecasters isolated in Docker workers
- Optional local LLM interpretation through a Lemonade-compatible endpoint
- File-based, inspectable pipeline using Parquet and JSON artifacts
- CLI entrypoint:
cbd - CI with Ruff, mypy, and pytest
- 140+ tests covering normalization, statistics, backtesting, ranking, audit, artifacts, forecasting adapters, and publication helpers
- No committed raw data, generated studies, secrets, model checkpoints, or local caches
Currently supported source integrations:
- World Bank datasets
- Our World in Data
- OpenAlex
- arXiv
- Crossref
The source layer is designed for additional public-data connectors using the same ingestion and normalization pattern. Examples of compatible future integrations include OECD, Eurostat, IEA, Energy Institute / BP datasets, Maddison, UN World Population Prospects, GitHub public activity data, and Dimensions.
See:
The advanced components are optional and isolated from the deterministic core.
| Component | Role | Isolation |
|---|---|---|
| TimesFM | Neural time-series forecasting | Docker worker via timesfm-worker |
| Chronos | Probabilistic time-series forecasting | Docker worker via chronos-worker |
| Lemonade | Local LLM interpretation reports | OpenAI-compatible local HTTP endpoint |
If an optional model is unavailable, the deterministic pipeline still runs.
cbd list_forecasters
cbd backtest_advanced
cbd analyze_agents --study-path studies/backtests/<study_id>Committed examples:
Generated outputs:
data/raw/
data/processed/
studies/backtests/
studies/demo_study/
publication/paper/
Generated outputs are intentionally ignored by Git.
Long-run public datasets contain real shocks, methodology changes, sparse historical coverage, source revisions, and model failures. A raw anomaly score is not enough.
ContinuityBreakDetector shows how to structure this kind of analysis so claims remain inspectable: deterministic computation first, artifact review before interpretation, optional ML/LLM layers kept outside the core method, and reproducible artifacts at every step.
The current conclusion is cautious: the pipeline detects known real-world shocks and likely data artifacts, but does not claim causal proof or an unexplained synchronized cross-domain break.
A detailed write-up of the analysis behind this project is available here:
This article focuses on the data analysis and results, while this repository focuses on the implementation and pipeline design.
- The pipeline identifies statistical candidates, not causes.
- Artifact filtering assigns risk indicators, not definitive labels.
- Optional TimesFM and Chronos runs require Docker and may download model weights into the Hugging Face cache volume at runtime.
- Optional Lemonade reports are interpretive aids, not scientific evidence.
- Public API schemas, coverage, and rate limits can change.
- Broader claims require more data sources, source-level validation, and independent replication.
This project is licensed under the MIT License.