Ghost Citadel
Menu
PlaygroundPlay

Prepare your first run.

Coming soon

Start with a small export you can inspect. Check the mapping, run the Engine and examine the result on your machine. The commands below apply once you have the matching Engine and Reader bundle.

Inspect the sample Discuss an Observatory pilot
Needs
Python 3.12 or later
Installs
The Engine and the ReaderOne pip command
Writes
out/observatory.sqliteBeside your configuration
Opens at
127.0.0.1:8765On your machine only
What a first run needs and leaves

01 / The sample

Your first run, step by step.

Earlier setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649. Use the matching bundle; the current measure snapshot is documented separately.

Start in the Ghost_Observatory source folder in the unpacked bundle. Contact us about availability or a pilot. Step 2 prepares a separate folder for your first result.

  1. Install the packages.

    From the unpacked package, install the Engine and the Reader with one command.

    $ python -m pip install ./engine ./reader

  2. Build the sample result.

    Save orders.csv and observatory.yaml from the three-row order example in a new folder. Open a terminal in that folder and run the command below.

    $ observatory run observatory.yaml --out out/observatory.sqlite

  3. Check the file.

    Continue only if the Engine run exited successfully with code 0. A failed run can leave a previous result untouched; resolve that failure before checking or opening the file.

    The Reader opens the file the way the app does, prints what it found and exits with 0 when it accepts the file. No server starts.

    $ observatory-reader out/observatory.sqlite --check

  4. Open the Reader.

    The Reader’s charts require a Chromium-based browser, version 143 or later, with working WebGPU. Engine runs and the command-line --check do not require WebGPU.

    The Reader listens on your machine at http://127.0.0.1:8765 and opens your browser.

    $ observatory-reader out/observatory.sqlite --open-browser

02 / Requirements

Check these requirements first.

The Engine and Reader run together on one machine. Install the dependencies below before your first run.

Python
3.12 or later.
Reader browser
Chromium 143 or later, with working WebGPU for charts.
Libraries
pip fetches them during installation. The core Engine and Reader then run locally. An optional hosted AI endpoint has its own network connection.
Extras
./engine[gui] adds the desktop launcher, observatory gui. ./engine[excel] adds Excel files as sources.
Paths
A relative --out is resolved against the folder where you run the command. The configuration’s own output directory is relative to the configuration file.
Account
None. The programs ask for no sign-up and no licence key, and no database server has to run.

03 / Your export

Run your first real export.

Put your export in a folder and create observatory.yaml beside it. Map the work object, activity, time and person to their source columns, declare the event order, and run.

The configuration, line by line

Run each step separately. Continue only after it exits successfully with code 0. If validation or the Engine fails, stop and fix the reported problem; an older result file may still exist.

$ observatory validate --config observatory.yaml
$ observatory run observatory.yaml --out out/observatory.sqlite
$ observatory-reader out/observatory.sqlite --check
$ observatory-reader out/observatory.sqlite --open-browser

04 / The Reader

Reader launch options.

The Reader is a local web app. It opens one result file, read-only, and listens on your machine unless you say otherwise.

Every launch option

observatory-reader PATH --open-browser serves the file at http://127.0.0.1:8765. A public deployment also needs --public-origin, authentication and a trusted HTTPS reverse proxy. --check opens the file the way the app does and exits with 0 or 2.

Security in full

05 / If a run stops

When a run stops.

When a required source has no row the contract can admit, the run stops. It names the reason, writes no file and exits with 2.

What to check, and the warnings 
$ observatory run observatory.yaml --out out/observatory.sqlite
error: Run blocked (required_source_has_no_admissible_evidence);
  refusing to create artifact …/out/observatory.sqlite
$ echo $?
2

06 / Next

Fit Observatory to your environment.

We configure deployments for your infrastructure, access controls and operating requirements. Bring us your requirements and we will define the setup.

Read the documentation Talk to us about deployment See the security model

Prepare inputs and check the first result.

Once you have the bundle, validate the configuration before running it. The Reader options and command exit codes describe how to open a result and handle a failed run.