Open-source core of eSK — a digital twin of the Slovak economic and financial system: a consistency-gated, AI-queryable model built entirely from official public registers.
eSK is an independent research project. It is not affiliated with, endorsed by, or operated by any state body.
This repository is the method, not the data: the register connectors, the data-quality gates, the entity/person resolution logic, the canonical schema, and the provenance-gated query layer. The resolved database, the derived signals and all person-level data stay private — see GOVERNANCE.md for the boundary and the legal basis for it.
- Connectors for the Slovak public registers — RPO (legal entities), CRZ (contracts), registeruz (financial statements), RPVS (beneficial ownership). Raw payloads are persisted before parsing, so every parse is replayable 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/ …); inferred identity carries a confidence that is never 1.0. - Entity resolution anchored on the RPO id (an IČO is an identifier, not a key), IČO-normalised, with the unresolved mass reported as a first-class coverage metric rather than hidden.
- Query layer.
query/esk_api.pyexposes read-only tools that return a GraphAnswer — nodes + edges + the signal + provenance + the evidence (contracts with their CRZ links).query/mcp_server.pyis a thin MCP shim over it;query/crew.pymaps 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.
- 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, including errors.
- Data minimisation. Person payloads carry a name and a public-role flag; dates of birth are never emitted.
pip install -r requirements.txt
python -m pytest tests/ -q # fixtures-only, fully offlineThe test suite runs without network and without a database — 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.
| 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) |
Respect each register's own terms when you run the connectors. This project re-uses public data for research and transparency; it mirrors no third party's proprietary dataset.
Early. Entity-level. The macro/estimator layer and the payment (faktúry) layer are not here yet. Interfaces will change.
See GOVERNANCE.md. Issues and pull requests are welcome — especially connector fixes, register quirks, and gate/coverage improvements.