Skip to content

Groundfact

A governed semantic layer over official statistics. Every number is traced back to its source, dataset and snapshot date. Nepal is the first instance; the architecture is country-agnostic.

The problem

The same country's statistics arrive from a dozen institutions in a dozen shapes. The World Bank publishes modelled estimates; the DHS Program publishes survey results; a census publishes an enumeration. They use different identifiers for the same country — Nepal is NPL to the World Bank, 524 to the UN, 149 to FAOSTAT and NP to DHS. They disagree, for real methodological reasons, and almost nothing surfaces where or why.

How it works

public APIs → dated snapshots → conformed warehouse → semantic layer → cited answers

Immutable dated snapshots. Every ingestion writes a timestamped Parquet file that is never modified. This is the revision mechanism: any cited answer is reproducible as-of its snapshot date because the file that produced it is still on disk, untouched.

One conformed fact table. Every observation resolves to a canonical geography and, where the indicator is curated, a canonical indicator id. Rows whose geography cannot be resolved are dropped rather than passed through with a null key — an unresolved geography is a wrong answer waiting to happen.

A semantic layer that cannot drift. The indicator YAML is upstream truth. One build step renders it into the documentation you are reading, the grounding document the language model sees, and the warehouse's own indicator dimension. CI rebuilds those artifacts and fails if they differ from what was committed, so the docs and the model's view of the world cannot fall out of step with the data.

The model never writes SQL. A question is resolved into a validated query specification whose every field is an enum or an identifier that must already exist. Deterministic code turns that into parameterised SQL. The model chooses chart shape and labels; the server binds the values. It is therefore not merely discouraged from inventing a number — it is never in a position to supply one.

Reconciliation is a feature, not an embarrassment. Where two sources report the same indicator for the same place and period, the difference is computed and surfaced. Under-five mortality in Nepal is a good example: the World Bank and the DHS Program differ by 25–37% in every survey year since 1996. Neither is wrong — one is modelled, one is measured.

What is deliberately not here

No Kubernetes, no orchestrator, no vector database, no free-form text-to-SQL, and no single-page-app framework. The whole warehouse is under 100 MB and rebuilds in seconds; a single-node design is not a limitation being apologised for, it is the correct size for the problem.

  • Feasibility study — measured source coverage and sizing, taken live rather than assumed. Several of the assumptions it tested turned out to be wrong.
  • Architecture decisions — every deviation from the original design, with the reasoning, including one where the stated rationale turned out to be partly wrong and is corrected in place.
  • Indicator reference — the curated indicators, generated from the semantic layer.

Built by Binit — TWAKKA LTD.