Quickstart

Both packages are published on PyPI as version 0.1.0 (released 2026-10-01); see release status and verification. The downloadable example bundle contains scripts and fixtures only: install the package from PyPI as shown below.

Goal: retain a fictional binary forecast, compute its Brier loss and reproduce it from pinned records. Everything in the example is synthetic; the future dates are part of the fixture.

Before you start

• Python 3.11, 3.12 or 3.13. These CPython versions have measured Windows and Linux x86-64 coverage.
• pip with access to PyPI, or a verified downloaded comuvia 0.1.0 wheel for an offline install.
• Download and extract the offline example bundle. It contains runnable scripts, synthetic fixtures and a license; it contains no SDK wheels or credentials.

The bundle's fixtures/synthetic directory is required. Fixtures are not resources installed by the wheel.

1. Install the package

Extract the example bundle into a new directory, open PowerShell in that extracted directory, and stay there for installation and execution. These commands create an isolated environment and install the published core from PyPI:

python -m venv .venv
./.venv/Scripts/python.exe -m pip install "comuvia==0.1.0"

To verify before installing, download comuvia-0.1.0-py3-none-any.whl from PyPI into a wheels/ subdirectory, check its hash, and install it without consulting an index:

Get-FileHash ./wheels/comuvia-0.1.0-py3-none-any.whl -Algorithm SHA256
./.venv/Scripts/python.exe -m pip install --no-index --no-deps ./wheels/comuvia-0.1.0-py3-none-any.whl

Expected SHA-256 of the published core wheel (also listed in the repository's release/0.1.0/SHA256SUMS):

a1feeb61a8f1636322efe2ea2f5b4213d9333642d8600ec1ddebadd187b6586a

Stop if the hash differs; do not install a file whose digest is not the approved one. On macOS/Linux, the environment's Python executable is .venv/bin/python; macOS itself is not part of the measured compatibility matrix.

$sdkRoot = './comuvia-sdk'
$env:PYTHONPATH = "$sdkRoot/packages/comuvia/src"
python -B ./example.py --fixtures ./fixtures/synthetic --output ./quickstart-output

2. Run the complete example

From the extracted bundle directory, with the environment created above:

./.venv/Scripts/python.exe ./example.py --fixtures ./fixtures/synthetic --output ./quickstart-output

Use a fresh output directory for each run. The script refuses to overwrite an existing run. It writes only the selected output directory and makes no network requests.

The fixture asks whether Port Calder's first published January 2027 container throughput is below 400,000 TEU. The fictional forecaster declares p = 0.70. The retained synthetic bulletin reports 386,500 TEU, giving outcome = 1.

Expected key results:

{
  "data_origin": "synthetic",
  "records_stored": 5,
  "loss": 0.09000000000000002,
  "display_loss": "0.09",
  "store_identity_ok": true,
  "reproduction": "match"
}

The displayed loss is (0.70 − 1)² = 0.09; the longer raw value reflects floating-point arithmetic. One synthetic score demonstrates the workflow, not predictive skill.

3. Understand what ran

This excerpt is the scoring step from the complete script. It assumes writer is an open writable store containing the validated input records:

import comuvia

report = comuvia.evaluate(writer.records())
(result,) = report.results
assert result.status == "scored"

(evaluation,) = comuvia.evaluation_records(
    report, writer.records(),
    evaluated_at="2027-02-17T00:00:00Z",
    recorded_by="evaluator:offline-quickstart",
    recorded_at="2027-02-17T00:00:00Z",
)
writer.append(evaluation)
assert comuvia.reproduce(evaluation, writer.records()).result == "match"

Read the complete example.py, then explore corrections and evaluation or offline ForeGlass replay.

If it fails