nullbench
Pre-register decisions. Score them against chance.
Lab / alpha — local seals under M1; not a global notary.
Product gate: without a green M1 gate, do not claim absolute「可稽核」or「永不 backfill」.
See docs/MATURITY.md.
nullbench is a null-first decision evaluation lab: freeze choices before outcomes, settle against equal-cost chance portfolios, keep an append-only ledger with semantic seals, and report descriptive percentiles plus sequential diagnostics.
It is not a lottery predictor. Negative expected-value domains are welcome as methodology stress tests.
Maturity (M0 → M4)
| Level | Meaning |
|---|---|
| M0 | Lab CLI / demo / PyPI alpha — shipping |
| M1 | Sealed ExperimentSpec + pin hashes + settle verify + claim lint + adversarial IC-01…08 — must-pass |
| M2 | PRD + Threat Model + Public API + Claim Policy frozen |
| M3 | OIDC trusted publish / SBOM / plugin allowlist |
| M4 | Remote sealed study / vault |
nullbench maturity
nullbench maturity --check-m1 # pytest -m m1
Install
pip install nullbench
# from source (needed for maturity --check-m1 tests)
pip install -e ".[dev]"
Python 3.11+.
60-second start
nullbench doctor
nullbench demo --name try1
nullbench report --study try1 --open
nullbench next --study try1
nullbench maturity --check-m1
Golden path
nullbench init my-study -d demo649
nullbench strategy add random --study my-study --tickets 5 --seed 1
nullbench freeze --study my-study --latest
nullbench settle --study my-study
nullbench report --study my-study --open
What M1 seals (local)
| Seal | Purpose |
|---|---|
experiment_hash |
Spec cannot silently change after freeze |
content_hash |
Tickets + seals bound |
history_hash / outcome_hash |
Draw history / known outcome pinned |
| Tip + semantic audit | Forged payouts fail even if chain re-linked |
| Claim lint | Report text scanned for promotional language |
Residual risk: an adversary who rewrites all seals consistently still wins until M4. Documented in docs/THREAT_MODEL.md.
Commands
| Command | Purpose |
|---|---|
maturity |
Ladder + optional M1 gate |
doctor |
Env + chain + semantic |
next / periods |
Coach / navigation |
demo / init / strategy / freeze / settle / report |
Core loop |
formal |
α-spending 26/52 (before freeze) |
ingest / coverage |
Taiwan data / OR-Tools extra |
domains -v / strategies -v |
Discovery (plugins need NULLBENCH_TRUST_PLUGINS=1) |
Docs
- MATURITY.md · INTEGRITY.md
- PRD.md · THREAT_MODEL.md · CLAIM_POLICY.md (M2 drafts)
- ARCHITECTURE.md · PRODUCT.md · CHANGELOG.md
Ethics
Pure simulation. No betting integration. Do not market predicted numbers.
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file nullbench-0.6.0.tar.gz.
File metadata
- Download URL: nullbench-0.6.0.tar.gz
- Upload date:
- Size: 60.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/7.0.0 CPython/3.11.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
76e8f485fec10ba95c23a570e1d6f5160ed32c7967243437ea06d18f843714a6
|
|
| MD5 |
450911bd26b36c721d22021841429a23
|
|
| BLAKE2b-256 |
f6fe4428c100fd8102e8364899bf00c64a3df33fa612fb8ab20d891040093879
|
File details
Details for the file nullbench-0.6.0-py3-none-any.whl.
File metadata
- Download URL: nullbench-0.6.0-py3-none-any.whl
- Upload date:
- Size: 60.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/7.0.0 CPython/3.11.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6c2151b6280e6dd9d835964105d99638f37131886a3b95e5957f74046f4c5101
|
|
| MD5 |
4c698f48acb22206e4fb86b2d3077fe8
|
|
| BLAKE2b-256 |
b33ae8c2e05b1d74f885de509bb8bddd990566f128b3eb85a2bc09b707f0fbf7
|
