Chances — Scientific randomness

Scientific randomness from a declared protocol, with verifiable arrays and execution receipts.

Chances unifies distributions, resampling, allocation, and point designs through one seeded protocol. Declare the scientific decision, inspect it before drawing, and retain the result with the evidence needed to verify and repeat it.

What Chances Is Not

Chances owns generation, validation, archival integrity, and conditional exact replay. Researchers own the choice of distribution, resampling unit, experimental design, and interpretation. Chances does not infer those decisions or certify scientific suitability. It is not a cryptographic random generator or a physical entropy service. Core execution requires a seed, uses local generators, and leaves Python and NumPy global random state unchanged.

Capabilities

The catalog covers 19 operations and 132 distribution families.

Use the operation catalog to select a family, its parameters, and its preconditions.

First successful computation

This README describes the 2.0 API in this repository. Historical 0.1 releases on PyPI use a different interface. Start from the current source checkout:

git clone https://github.com/autonomio/chances.git
cd chances
python -m pip install .

Use Python 3.10 or later. Installation supplies NumPy and SciPy; no optional runtime extras are required. Choose a new output directory for the example; existing destinations are rejected.

from pathlib import Path
import numpy as np
import chances

spec = {
    "version": 1,
    "operation": "normal",
    "parameters": {"size": 100, "loc": 0.0, "scale": 1.0},
    "randomness": {"seed": 42, "stream": "experiment/replicate-1"},
}
profile = chances.inspect(spec)
first = chances.generate(spec)
second = chances.generate(spec)
assert profile["output"]["shape"] == [100]
assert first.data.shape == (100,)
assert np.array_equal(first.data, second.data)
assert first.receipt == second.receipt

bundle = Path("first-batch")
first.write(bundle)
checked = chances.verify(bundle)
repeated = chances.replay(bundle)
assert np.array_equal(first.data, checked.data)
assert np.array_equal(first.data, repeated.data)
assert first.receipt == checked.receipt == repeated.receipt
assert {path.name for path in bundle.iterdir()} == {
    "data.npy", "recipe.json", "receipt.json"
}
print(first.data.shape)
print(bundle.resolve())

Expected result: (100,) and the absolute path of the retained first-batch directory. The array and receipt match across generation, verification, and replay in this environment. The example keeps those files for inspection.

inspect validates and describes without drawing randomness. generate returns data, a NumPy array, and receipt, JSON evidence. A stream name identifies one computation; declare different names for distinct replicates. See the specification contract for defaults and stream semantics.

Retain the evidence

The same bundle can be inspected from a shell or an agent through JSON commands:

python -m chances inspect first-batch/recipe.json
python -m chances verify first-batch
python -m chances replay first-batch

The reproducible batch guide covers the full archival workflow; the command-line reference defines arguments, JSON output, and structured failures.

Risk Boundary

Exact replay requires the recorded compatibility envelope. It does not promise equality across package versions, platforms, or changed chunk sizes. Unsigned receipts establish integrity relative to retained evidence; they do not establish authorship, independent samples, or the suitability of a statistical model. The receipt reference defines these boundaries and recovery from changed or incompatible evidence.

Choose the next task

Installed agents start at Path(chances.__file__).parent / "AGENTS.md"; the installed manual and catalogs live beside it under docs/. Structured ChancesError fields support recovery without substituting a method.

Contributing

Start with CONTRIBUTING.md and developer setup and validation. Propose work through Autonomio Chances issues.

Support

Use SUPPORT.md for bug reports, feature requests, and usage questions. Include a minimal protocol, Chances and Python versions, operating system, and the structured error. Use a small shareable fixture when a report needs source data.

Vulnerabilities

Report suspected vulnerabilities privately through GitHub Security Advisories. Use SECURITY.md for supported versions, response policy, and artifact verification. Do not report vulnerabilities through public issues.

Citations

Use CITATION.cff for software citation metadata. A reproducible research citation should identify Chances, its version, and the retained protocol and receipt. No DOI is supplied.

License

MIT License.