eSK core

Open-source core of eSK, a digital twin of Slovak public money, reconciled from the official public registers. A consistency-gated, AI-queryable model. The method, not the data.

eSK is an independent research project. It is not affiliated with, endorsed by, or operated by any state body.

This repository holds that method: the register connectors, the data-quality gates, the entity and person resolution logic, the canonical schema, the reconciliation engine that balances money-flows through the gate, and the provenance-gated query layer. The resolved database, the derived signals, and all person-level data stay private. See GOVERNANCE.md for where that line sits and the legal basis for it.

What's in here

• Connectors for the Slovak public registers: RPO (legal entities, also via the Ekosystém RPO V2 bulk change-feed), CRZ (contracts), registeruz (financial statements), RPVS (beneficial ownership), Finančná správa (VAT-status and tax-debtor open data), ITMS2014+ (EU-fund projects and accounting documents), and Eurostat (sectoral macro accounts). Raw payloads are persisted before parsing, so every parse replays offline and nothing depends on a live API to be verified.
• Gates. An amount gate flags implausible contract values before any value-weighted figure is computed. A provenance tag rides every row (observed, derived, and so on), and inferred identity carries a confidence that is never 1.0.
• Entity resolution anchored on the RPO id, since an IČO is an identifier and not a key. It is IČO-normalised, and the unresolved mass is reported as a first-class coverage metric rather than hidden.
• Query layer. query/esk_api.py exposes read-only tools that return a GraphAnswer: nodes, edges, the signal, provenance, and the evidence (contracts with their CRZ links). query/mcp_server.py is a thin MCP shim over it. query/crew.py maps a plain-language question, Slovak or English, onto one gated tool and reports it without a model, or with one that only phrases the payload.
• Reconciliation engine (M0 to M2.1). M0 builds the from-whom-to-whom matrix of realised § 5b payments, payer body to payee firm, and attaches both margins: budget outturn on the source side, filed turnover on the sink side. It runs the matrix through the gate, so every euro has a source and a sink and any breached margin is flagged rather than silently adjusted. M2.0 rolls the counterparty side up to ESA2010 institutional sectors, and M2.1 reconciles the year's observed § 5b total against the macro figure for government purchases.
• The § 5b payment layer. Published-invoice payments are the realised leg, kept apart from the contract commitment leg and never conflated with it. A VAT as-of annotation time-aligns each payment to the supplier's VAT status on the payment date.
• EU-fund channel (E0). The same gate applied to the EU-fund stream: a gated recipient-to-supplier matrix, a named exclusion pile, and a per-year sink-side identity that holds EU receipts against filed turnover.
• Macro bond. The micro totals meet Eurostat sectoral accounts, so the register-level picture is checked against the national accounts rather than trusted on its own.

Principles, enforced in code

• Gate first. Nothing untrusted leaves. Value-weighted figures filter to amount-gated rows, and the payload reports how many were excluded.
• Provenance on every figure. No number without its source.
• Ordinal, not a share. State-contract "intensity" ranks exposure on signed contract values. A contract is a commitment, not a payment.
• The model draws no conclusions. Signals are review items with evidence, for a human to examine. The disclaimer rides every payload, errors included.
• Data minimisation. Person payloads carry a name and a public-role flag. Dates of birth are never emitted.

Quickstart

pip install -r requirements.txt
python -m pytest tests/ -q          # fixtures-only, fully offline

The test suite runs without a network and without a database. The fixtures are real register payloads with synthetic natural persons (see GOVERNANCE.md). To build your own database you point the connectors at the registers yourself; this repository ships no data.

Data sources and attribution

Register	What	Note
RPO	legal entities, ESA2010 sector	CC-BY-4.0, ŠÚ SR. Attribution required on reuse
CRZ	public contracts (daily diff dumps)	contracts are public by law
registeruz	financial statements	public register
RPVS	beneficial owners	public register (Act 315/2016)
Finančná správa	VAT-status lists, tax-debtor audit	Finančná správa SR open data
ITMS2014+	EU-fund projects, accounting documents	public EU-fund register (anonymous API)
Eurostat	sectoral / national accounts	Eurostat open data

Respect each register's own terms when you run the connectors. This project re-uses public data for research and transparency, and it mirrors no third party's proprietary dataset.

Status

Early, and interfaces will change. Entity-level resolution, the § 5b payment layer, the reconciliation engine (M0 to M2.1), and the EU-fund channel (E0) are in, with the macro totals bonded to Eurostat. The residual estimator (M1) and the wider macro layer are still landing.

Contributing & contact

See GOVERNANCE.md. Issues and pull requests are welcome, especially connector fixes, register quirks, and gate or coverage improvements.