Both packages are published on PyPI as version 0.1.0 (released 2026-10-01); see [release status and verification](/sdk/docs/project). 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](/sdk/resources/downloads/comuvia-offline-examples.zip). 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:

```powershell
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](https://pypi.org/project/comuvia/0.1.0/#files) into a `wheels/` subdirectory, check its hash, and install it without consulting an index:

```powershell
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`):

```text
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.

<details><summary>Alternative: run against an existing checkout, without installing</summary>

Set `sdkRoot` to a checkout of [github.com/comuvia/comuvia-sdk](https://github.com/comuvia/comuvia-sdk) at tag `v0.1.0`, then run the example with that checkout's core on the import path:

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

This alternative applies to `example.py`. The full tutorials invoke the installed CLI and should use the wheel environment.
</details>

## 2. Run the complete example

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

```powershell
./.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:

```json
{
  "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

<div class="diagram" role="img" aria-label="Question and forecast plus source snapshot and outcome produce an evaluation, which is appended as the fifth record, then independently reproduced."><div class="flow-node"><strong>4 input records</strong><span>Question · declared forecast · source snapshot · outcome</span></div><div class="flow-arrow">↓ validate + verify retained source bytes</div><div class="flow-node"><strong>Single-writer store</strong><span>Append inputs → evaluate → append evaluation</span></div><div class="flow-arrow">↓ reopen as reader</div><div class="flow-node"><strong>Two distinct checks</strong><span>Store identity: OK · Evaluation reproduction: match</span></div></div>

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

```python
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](/sdk/resources/downloads/example.py), then explore [corrections and evaluation](/sdk/docs/evaluation) or [offline ForeGlass replay](https://foreglass.ai/developers/reader/).

## If it fails

| Symptom | First check |
|---|---|
| `ModuleNotFoundError: comuvia` | Use the same virtual-environment Python for installation and execution. |
| Missing fixture file | Extract the complete bundle; keep the `fixtures/synthetic` layout. |
| Output directory already exists | Choose a new `--output` path; retain the old run for comparison. |
| `RefusalError` | Inspect `.issues` and `.codes`; do not strip fields until validation passes. |
| Expected loss differs | Confirm unchanged fixture bytes and SDK 0.1.0; retain the failed run. |