The Engine reads and calculates.
It needs Python 3.12 or later. Polars does the analytical work, Python orchestrates it and SQLite stores the result. A YAML contract tells the Engine what each column of an export means.
Powerful by design.
Coming soon
The Engine reads your exports and writes one SQLite file. Read it with the Reader, Power BI or your own code. Your analysis runs on your machine; access to the result does not depend on a Ghost Citadel cloud account.
- Your exportsCSV, Excel, JSON, Parquet, XES and more
- The EnginePython and Polars, one YAML contract per export
- observatory.sqliteOne file, every table and column declared
- Read by
- The Reader
- Power BI
- Your own code
01 / Parts
One Engine. One result file.
Architecture and dependencies reference · Engine 18.6.0rc590 / Reader 8.11.0rc649. Use the matching bundle’s declared requirements. The measure reference identifies its own snapshot.
The Engine calculates, the SQLite file holds the results and the Reader presents them. The same file also connects your analysis to Power BI and your own code.
The file keeps the result.
Every file has the same tables and columns. An analysis that could not run leaves its rows out and its measures empty, with a warning that says why.
The Reader shows the file.
A local web app opens the file read-only. It selects published rows and never recomputes a measure the Engine published.
Everything else reads the file.
BI tools can query the published result tables. Scripts and language models use the Python API or plain SQL.
02 / Built from
Libraries and runtime.
The Engine vendors no third-party code. Every library is installed from its own distribution, under its own licence, within a declared version range. The time-zone data is the one exact pin.
- Engine
- Python 3.12 or later, Polars, PyYAML, ijson, defusedxml and tzdata
- Reader
- Python standard-library HTTP server, with Three.js r186 in the browser
- Result file
- SQLite
- Charts
- WebGPU through Three.js. No fallback renderer.
- Optional
- pywebview for the desktop launcher, openpyxl for Excel files
03 / Local computing
Serious analysis belongs on ordinary hardware.
A full Engine-and-Reader installation runs on a MacBook Neo or a Raspberry Pi 5. Both run the complete software locally and use the same result format.
See the installation steps- MacBook Neo
- Everyday Apple-silicon laptop: the complete Engine and Reader, running locally.
- Raspberry Pi 5
- Small ARM machine: the same Engine and Reader, on a board that fits in your hand.
- Benchmark record
- The workload, settings, machine specifications and run logs are pending publication.
- Reported timings
- Ghost Citadel’s development timings for one run of 1 million complex rows: about 1 minute on a workstation, 2 minutes on a MacBook Neo and 7 minutes on a Raspberry Pi 5.
04 / Rules
Calculation rules.
Our earlier design guidance sets out six rules for calculation and publication, including one owner per fact and keeping unknown values distinct from zero. The linked reference has no established release version and does not demonstrate enforcement in a current build.
Read the six rules05 / Release gate
The release checks.
The earlier release-gate reference describes independent recalculation of published figures and blocking release when results disagree. It has no established release version; the reference alone is not evidence that a current build has passed those checks.
What the gate checksThe historical checklist covers rebuilt samples, declared contracts, independent recalculation, adapter fixtures with and without pseudonymisation, and Reader views. Its scope and results need to be established for each release.
Follow one number through the file06 / Security and runtime
Local files and controlled access.
The Engine and Reader run on a machine you control. The core serves its own assets and sends no process data to Ghost Citadel. If you configure a hosted AI endpoint, requests to that endpoint are a separate connection under your control.
Earlier security and runtime referenceThe linked historical reference describes local-file restrictions, read-only results, listening-address controls and exit codes. It does not identify a release for those controls. Pseudonymisation is optional: enable ANONYMIZE: true and supply a key. It covers mapped personal identifiers; review free text separately.
07 / Your own AI
Connect AI on your terms.
Programs and language models read the same published rows a person reads, through the Python API or plain SQL on the result file. Which model you use, where it runs and what it may see are your decisions.
The Python API and the access it grantsSome regions limit how AI may be used on people at work, such as the EU AI Act (Regulation (EU) 2024/1689). A deployment can be modified by region, and that is consulting work.
AI integrations and regional deployments08 / Next
Inspect the result file.
The documentation lists every command, setting and warning. The sample result is a plain SQLite file, and it opens in any SQLite tool today.
Read the documentation Download the sample Ask about your environmentInspect the calculation and storage contract.
Read how results are produced, how a query selects its analysis scope and how the release checks independently verify calculations.