poisson-prove 0.1.0__tar.gz

poisson_prove-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing / tooling caches
+.pytest_cache/
+.hypothesis/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Run stores. The default store root is ./prove-runs.
+prove-runs/
+
+# A contributor's own working log, never committed
+devlog.md
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

poisson_prove-0.1.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to Poisson Prove are written here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[semantic versioning](https://semver.org/).
+
+## 0.1.0 — 2026-10-29
+
+The first public release. Prove tells you whether a change to an AI agent really changed how often
+it fails. It replays the same cases before and after the change, on the same seeds, compares the
+two runs condition by condition, and gives a verdict with stated error bounds and detection
+limits. Python 3.11 to 3.14, on macOS and Linux.
+
+### Verbs
+
+- `poisson-prove init` writes `prove.toml`, a sweep spec to edit; `init --example` writes the
+  keyless example; `init --agent` writes a skill and a prompt for your own coding agent, which sets
+  Prove up in your repository for you to review. Prove itself makes no model call.
+- `poisson-prove sweep` prints the plan, its cost and the smallest change one condition alone would
+  be flagged for, refuses a design too small for the change you accept and names the replicates
+  that would do, then runs the sweep on this machine, on Modal or on Burla. A stopped sweep resumes
+  where it stopped, and `--pair-with` gives a sweep an earlier run's seeds.
+- `poisson-prove diff` compares two stored runs condition by condition, per outcome, and names the
+  method it used.
+- `poisson-prove report` writes `report.md`, `heatmap.svg` and `receipt.html` for two runs, or one,
+  and saves the comparison.
+- `poisson-prove paired` checks that a declaration's arms replayed the same requests, then writes
+  its files.
+- `poisson-prove check` gates on a comparison: passed exits 0, failed exits 4.
+- `poisson-prove serve` serves a read-only page comparing two runs on a loopback port, and saves
+  the comparison.
+- `poisson-prove inspect` prints the episodes behind an outcome, with a snippet to reproduce one.
+- `poisson-prove runs` lists the runs in the store, by name and id.
+- `poisson-prove ui` builds the dashboard: static pages over the store, opened from disk.
+- `poisson-prove` with no verb, on a terminal, opens the terminal app over the store.
+
+### Concepts
+
+- The verdict is one word for the whole comparison: `safer`, `worse`, `trade` (some conditions
+  safer and at least one worse), `no significant change` (no change counted, and every condition
+  could have caught one of the size you accepted) or `too small to tell` (no change counted, and at
+  least one condition could not have).
+- A condition's flag is held to a false discovery rate (Benjamini-Hochberg); the verdict counts
+  only the changes that also hold at the family-wise level (Holm).
+- Every condition that did not move says how large a change it would have caught 4 times in 5,
+  computed for the test the comparison used, or that it could not have caught one at all.
+- Runs paired at sweep time share their seeds and are compared with the paired test (McNemar) by
+  default; every output names the method it used.
+- Every episode is stored in Parquet with its seed, outcome, time and trace. Runs go by readable
+  names, and `latest` and `previous` stand for the two newest.
+- Runs and saved comparisons are written in a documented artifact format, which the dashboard and
+  the terminal app read.
+- The layered report: one omnibus test over every condition, the fault lines that group them, and
+  the conditions under each.
+- Fault injection through a `[chaos]` table, and capture of an agent's trace through OpenTelemetry.
+- A Modal or Burla worker runs the rollout's BLAS on one thread unless its environment sets a
+  thread count; `threadpoolctl` is a core requirement for this.
+- The Python API (`poisson_prove`) gives the same comparisons the command line prints.
+- The packaged example needs no key: a mock agent and a patched version of it, swept on the same
+  seeds, whose comparison reads `trade`.
+
+### Install
+
+- `pip install poisson-prove`. The extras are `[modal]` (Modal 1.0.0 or later), `[burla]`
+  (exactly Burla 1.8.2; the backend is experimental), `[agent]` (OpenTelemetry capture and the
+  OpenAI client), and `[all]`.
+- Prove sends nothing anywhere beyond the backend you choose: no telemetry, no analytics, no update
+  check. `serve` binds to 127.0.0.1 only.
+
+### Renamed
+
+- This is the first public release. Earlier private builds were called proofload; stores they
+  wrote are read unchanged.

poisson_prove-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing
+
+Thank you for helping. This page says how to set up a checkout, run the tests, and send a change.
+[Architecture](https://github.com/poisson-labs/prove/blob/main/docs/architecture.md) says where a
+change belongs.
+
+## Set up
+
+Prove needs Python 3.11 or later. Install the checkout with every extra and the development tools,
+in a virtual environment of its own:
+
+<!-- docs-check: skip: installs a checkout for development, run from its root -->
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[all,dev]"
+```
+
+## Running the tests
+
+Two suites. Run the code suite before every pull request, and the math suite (the statistics,
+marked `math`) when you change statistics code:
+
+<!-- docs-check: skip: runs the test suites of a checkout -->
+```bash
+python -m pytest tests -n 10 -m "not math and not calibration and not backend and not slow"
+python -m pytest tests -n 10 -m math
+```
+
+`-n` runs the tests in parallel (`pytest-xdist`); pick a number near your machine's cores. The code
+suite takes a few minutes. Tests marked `calibration` are the slow statistical checks of the error
+rates; tests marked `backend` call a real Modal or Burla account and never run unless you opt in.
+
+Tests marked `slow` take longer and some reach the package index: a browser check of the
+dashboard's pages, every docs page run again from the built wheel in a fresh environment, and the
+code suite with every requirement installed at its stated floor on Python 3.11. At the floors,
+numpy and SciPy each start a BLAS thread pool in every process, so set `OPENBLAS_NUM_THREADS=1`
+for this run or the parallel workers swamp the machine. The browser check needs Playwright's
+engines:
+
+<!-- docs-check: skip: runs the slow tests of a checkout -->
+```bash
+python -m playwright install chromium firefox webkit
+OPENBLAS_NUM_THREADS=1 python -m pytest tests -n 6 -m "slow and not backend"
+```
+
+## CI
+
+Every pull request and every push to main runs the code lane: ruff, the format check on `src`,
+mypy and the code suite, on Python 3.11 for a pull request and on 3.11 and 3.14 for main. A pull request that changes the statistics, a test
+of the math suite, or the version a statistics library resolves to also runs the math suite, and the
+job summary says why. Every night, and before a release, CI runs everything else: the code suite on
+every supported Python, the math suite, the slow tests, the floors run and the code suite in a Linux
+container. Tests marked `backend` never run in CI. Each job's summary gives the tests it ran, its
+time against the lane's budget, and the code lane's tests over 10 seconds.
+
+## The docs are tested
+
+Every command block in the README and under `docs/` runs, from a folder of its own, and must do
+what its page shows: each block carries a mark in an HTML comment on the line before it
+(`run`, `skip: REASON`, or `file NAME`), and a block with no mark fails. A page's shown output is
+checked by its verdict word and its line labels, never by its counts, which change from one sweep
+to the next. The docs check under `tests/` defines the marks in its docstring. When you change a
+command's output or its help, run the docs tests and update the pages they name.
+
+## Snapshots
+
+A few tests compare a page of the dashboard whole against a snapshot under `tests/snapshots/`,
+and a screen of the terminal app whole (its rows and each cell's colour role) against one under
+`tests/__snapshots__/`. They are the one place output is pinned whole; everywhere else a test pins
+facts. When a change to a page or a screen is meant, rewrite the snapshots with the one command
+that does so and review the diff in the pull request:
+
+<!-- docs-check: skip: rewrites the snapshots of a checkout -->
+```bash
+python -m pytest tests -k snapshot --update-snapshots
+```
+
+## Rules the code keeps
+
+- The core imports no network library and no optional package: `modal`, `burla`, `openai` and the
+  OpenTelemetry SDK live behind their extras, and a bare install runs every verb locally.
+- Prove makes no network call of its own: no telemetry, no update check. `serve` binds 127.0.0.1
+  only.
+- A test pins a fact, never prose. A test is changed only by a commit that says why, never to make
+  a change pass.
+- Frozen tests are read-only. A test written before the code it checks is not edited, skipped or
+  marked to fail so that a change passes; if one looks wrong, say so in the pull request.
+- Every requirement has a floor that the slow floors test installs and runs; raise one only with
+  the reason in the commit.
+
+## Sending a change
+
+Commits are signed and their messages follow Conventional Commits (`feat:`, `fix:`, `docs:`,
+`test:`, `chore:`), each saying in plain words what changed and why. One pull request per change,
+with the tests that pin it, the docs it moves, and the suites green.

poisson_prove-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taylor Kolasinski / Poisson Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

poisson_prove-0.1.0/NOTICE

@@ -0,0 +1,38 @@
+Poisson Prove
+Copyright (c) 2026 Taylor Kolasinski / Poisson Labs
+
+This product includes data from a third party, listed below. Poisson Prove itself is
+distributed under the MIT licence; see LICENSE.
+
+--------------------------------------------------------------------------------
+AgentChaos
+https://github.com/floritange/AgentChaos
+Distributed on PyPI as the agentchaos-sdk distribution, version 0.1.0
+Licence: MIT
+
+src/poisson_prove/chaos_catalog.py carries a copy of AgentChaos's fault vocabulary: the
+fault names, their target paths and their literal replacement strings, read from
+agentchaos/fault_config.py of the 0.1.0 wheel. No AgentChaos code is included and
+AgentChaos is not a dependency of Prove at any tier; the mutation semantics behind the
+copied names are Prove's own.
+
+MIT License
+
+Copyright (c) 2025 AgentChaos contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify,
+merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be included in all copies
+or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
+OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

poisson_prove-0.1.0/PKG-INFO

@@ -0,0 +1,316 @@
+Metadata-Version: 2.5
+Name: poisson-prove
+Version: 0.1.0
+Summary: Did your change to the agent really change how often it fails? Replays the same cases before and after, and says per condition, with stated error bounds and detection limits.
+Project-URL: Homepage, https://poissonlabs.ai/tools/prove
+Project-URL: Source, https://github.com/poisson-labs/prove
+Project-URL: Documentation, https://github.com/poisson-labs/prove/tree/main/docs
+Project-URL: Changelog, https://github.com/poisson-labs/prove/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/poisson-labs/prove/issues
+Author-email: Poisson Labs <work@poissonlabs.ai>
+Maintainer-email: Poisson Labs <work@poissonlabs.ai>
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agents,evaluation,llm,reliability,statistics,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pyarrow>=17.0.0
+Requires-Dist: rich>=14.2.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: textual>=6.4.0
+Requires-Dist: threadpoolctl>=3.0.0
+Provides-Extra: agent
+Requires-Dist: openai<3,>=2.20; extra == 'agent'
+Requires-Dist: opentelemetry-sdk>=1.41.0; extra == 'agent'
+Provides-Extra: all
+Requires-Dist: burla==1.8.2; extra == 'all'
+Requires-Dist: modal>=1.0.0; extra == 'all'
+Requires-Dist: openai<3,>=2.20; extra == 'all'
+Requires-Dist: opentelemetry-sdk>=1.41.0; extra == 'all'
+Provides-Extra: burla
+Requires-Dist: burla==1.8.2; extra == 'burla'
+Provides-Extra: dev
+Requires-Dist: cloudpickle>=3.1.1; extra == 'dev'
+Requires-Dist: hatchling>=1.27.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.70.0; extra == 'dev'
+Requires-Dist: jsonschema>=4.18.0; extra == 'dev'
+Requires-Dist: lifelines>=0.27.8; extra == 'dev'
+Requires-Dist: markdown-it-py>=2.2.0; extra == 'dev'
+Requires-Dist: mypy>=2.2.0; extra == 'dev'
+Requires-Dist: opentelemetry-exporter-otlp-proto-common>=1.41.0; extra == 'dev'
+Requires-Dist: packaging>=25.0; extra == 'dev'
+Requires-Dist: playwright>=1.40.0; extra == 'dev'
+Requires-Dist: pyte>=0.8.1; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.5.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0.1; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: statsmodels>=0.14.0; extra == 'dev'
+Provides-Extra: modal
+Requires-Dist: modal>=1.0.0; extra == 'modal'
+Description-Content-Type: text/markdown
+
+# Poisson Prove
+
+Did your change to the agent really change how often it fails?
+
+Prove replays the same cases before and after a change, on the same seeds, and tells you per condition
+whether failures went up, went down, or did not move by more than it could have detected, with stated
+error bounds and detection limits. Every verdict comes with the smallest change that condition could
+have shown.
+
+<!-- docs-check: run -->
+
+    python3 -m venv .venv && source .venv/bin/activate
+    pip install poisson-prove
+    poisson-prove init --example
+    poisson-prove sweep --yes
+    poisson-prove sweep --yes --target poisson_prove.examples.mock_agent:rollout_patched --pair-with latest
+    poisson-prove diff
+
+- No key and no account for the example; your own agent runs on your machine by default.
+- Prove sends nothing anywhere: no telemetry, no update check; `serve` binds to 127.0.0.1 only.
+- Python 3.11 to 3.14 on macOS and Linux. MIT licensed.
+
+For your own agent you write one function that runs one case and says how it ended: see
+[Your own agent](https://github.com/poisson-labs/prove/blob/main/docs/your-own-agent.md).
+`uv tool install poisson-prove` or `pipx install poisson-prove` installs the command alone: enough
+for the example, not for importing your agent.
+
+## What the first run showed
+
+The example sweeps a small mock agent over three tasks and three tool failure rates, 194 episodes
+in each of the nine conditions, then sweeps a patched version of it (it retries a failed tool call
+once) on the same seeds. `diff` compares the two runs:
+
+<!-- docs-check: run -->
+```console
+$ poisson-prove diff
+trade  timeout: … safer, … worse · violated: … safer, … worse (paired test on shared seeds); …
+  method  paired test on shared seeds (McNemar), the default for runs paired at sweep time
+  before  mock-agent 2026-10-26 a
+  after  mock-agent 2026-10-26 b
+…
+  next: poisson-prove report --x task_id --y tool_fail_rate
+```
+
+Read the first line word by word. `trade` is the verdict: some conditions got safer and at least
+one got worse. Then, per outcome, how many conditions were flagged as falling (safer) and rising
+(worse); the clause after the test names the changes that also hold at the stricter level the word
+is decided at, where they differ from the flags.
+`violated` (the agent took a forbidden fallback) falls in most conditions and rises in none;
+`timeout` (the agent ran out of its 20 tool calls) falls in some and rises in the hardest one. The
+patch trades one failure for another: retrying keeps the agent off the forbidden path, and where
+tools fail most the retries use up its budget. "Paired test on shared seeds" says the two runs drew
+the same random numbers, so each episode is compared with its twin. The counts move a little from
+one pair of sweeps to the next, since each pair draws fresh seeds; the verdict did not, in our runs.
+
+The lines under it name the method and the two runs; the full output goes on, with every
+condition's change, an interval on it and the smallest change it could have detected. The `next:`
+line is the command to run next, whole.
+
+## Let your coding agent set it up
+
+<!-- docs-check: run -->
+```console
+$ poisson-prove init --agent
+ok  wrote the setup for your coding agent (4 files)
+…
+  prompt  Use the poisson-prove-setup skill in this repository: set Poisson Prove up for me to review, then stop.
+  next: give your coding agent the prompt above, then review what it wrote
+```
+
+This writes a skill your coding agent (Claude Code, Codex, Cursor) follows. Give it the prompt: it
+reads your code, writes `prove_rollout.py` and `prove.toml`, checks them with
+`poisson-prove sweep --dry-run`, and stops for you to review. Prove makes no model call and reads no
+key. When the files look right, run `poisson-prove sweep` yourself. The whole procedure is in
+[Set Prove up with your coding agent](https://github.com/poisson-labs/prove/blob/main/docs/setup-with-your-agent.md).
+
+## The terminal app and the dashboard
+
+On a terminal, `poisson-prove` with no verb opens the terminal app: your runs, your comparisons and
+their verdicts, a sweep from the folder's `prove.toml`, all by keys. `poisson-prove ui` builds a
+dashboard of the same views as pages you open from disk:
+
+<!-- docs-check: run -->
+```console
+$ poisson-prove ui
+ok  dashboard at file:///…/prove-runs/.poisson/ui/index.html
+```
+
+See [The terminal app](https://github.com/poisson-labs/prove/blob/main/docs/terminal-app.md) and
+[The dashboard](https://github.com/poisson-labs/prove/blob/main/docs/dashboard.md).
+
+## Your own agent
+
+A rollout is a function `(cfg, seed) -> Episode`: it runs one case of your agent under the
+condition `cfg` names, with randomness seeded from `seed`, and says how the case ended. This one
+wraps a support bot:
+
+<!-- docs-check: file my_rollout.py -->
+```python
+from poisson_prove import Episode
+from support_bot import TICKETS, handle  # your agent and its cases
+
+
+def rollout(cfg, seed):
+    ticket = TICKETS[cfg["ticket"]]
+    reply = handle(ticket, temperature=cfg["temperature"], seed=seed)
+    if reply.timed_out:
+        outcome = "timeout"
+    elif reply.resolved:
+        outcome = "resolved"
+    else:
+        outcome = "unresolved"
+    return Episode(outcome=outcome, t=reply.steps, horizon=20, meta={"case_id": cfg["ticket"]})
+```
+
+The sweep spec names it with `target`, lists the conditions as axes (each case its own axis value,
+so a condition runs one case) and says which outcomes count against the agent:
+
+<!-- docs-check: file support.toml -->
+```toml
+target = "my_rollout:rollout"
+target_id = "support-bot"
+t_unit = "steps"
+replicates = 200
+
+[axes.ticket]
+type = "categorical"
+values = ["refund", "password", "shipping"]
+
+[axes.temperature]
+type = "continuous"
+values = [0.0, 0.7]
+
+[declare]
+outcomes = ["resolved", "unresolved", "timeout"]
+failures = ["unresolved", "timeout"]
+successes = ["resolved"]
+```
+
+An agent traced with OpenTelemetry can have its spans stored with each episode by adding a
+`[capture]` table (it needs `pip install "poisson-prove[agent]"` and the instrumentor you name):
+
+<!-- docs-check: run -->
+```toml
+[capture]
+instrument = ["openai"]
+content = false
+max_observation_bytes = 16384
+```
+
+[Your own agent](https://github.com/poisson-labs/prove/blob/main/docs/your-own-agent.md) runs this
+example end to end and says what each piece does.
+
+## Recipes
+
+- [First look](https://github.com/poisson-labs/prove/blob/main/docs/recipes/first-look.md): the example, and how to read every block of `diff`.
+- [A prompt change](https://github.com/poisson-labs/prove/blob/main/docs/recipes/a-prompt-change.md): before and after a change to your prompt, paired, with a gate.
+- [A model change, with its cost](https://github.com/poisson-labs/prove/blob/main/docs/recipes/a-model-change-with-cost.md): a cheaper model as an axis, and what it saves.
+- [In CI](https://github.com/poisson-labs/prove/blob/main/docs/recipes/in-ci.md): `check` as a step that fails the build.
+- [When it says too small to tell](https://github.com/poisson-labs/prove/blob/main/docs/recipes/when-it-says-too-small-to-tell.md): what to change so it can tell.
+- [Paired replay](https://github.com/poisson-labs/prove/blob/main/docs/recipes/paired-replay.md): does the same request, sent twice, get the same decision?
+
+## Commands
+
+- `init`: write `prove.toml`, the keyless example, or the setup for your coding agent ([page](https://github.com/poisson-labs/prove/blob/main/docs/commands/init.md)).
+- `sweep`: show the plan, then run every condition of the spec ([page](https://github.com/poisson-labs/prove/blob/main/docs/commands/sweep.md)).
+- `diff`: compare two runs condition by condition ([page](https://github.com/poisson-labs/prove/blob/main/docs/commands/diff.md)).
+- `check`: the same comparison as a gate that exits 4 when it fails ([page](https://github.com/poisson-labs/prove/blob/main/docs/commands/check.md)).
+- `report`: write a report folder with a heatmap and a receipt ([page](https://github.com/poisson-labs/prove/blob/main/docs/commands/report.md)).
+- `paired`: check that two arms replayed the same requests, then analyse them ([page](https://github.com/poisson-labs/prove/blob/main/docs/commands/paired.md)).
+- `serve`: one comparison as a page on a loopback port ([page](https://github.com/poisson-labs/prove/blob/main/docs/commands/serve.md)).
+- `inspect`: the episodes behind an outcome, with code to reproduce one ([page](https://github.com/poisson-labs/prove/blob/main/docs/commands/inspect.md)).
+- `runs`: the runs in the store ([page](https://github.com/poisson-labs/prove/blob/main/docs/commands/runs.md)).
+- `ui`: build the dashboard ([page](https://github.com/poisson-labs/prove/blob/main/docs/commands/ui.md)).
+
+## What the numbers claim, and what they do not
+
+Each condition's change is tested on its own, and the flags are held to a false discovery rate
+(Benjamini-Hochberg, q 0.05 by default); the verdict word counts only the changes that also hold
+at the family-wise level (Holm). Every condition that did not move says how large a change it would
+have caught 4 times in 5. `no significant change` means no change counted and every condition could
+have caught one of the size you accepted; `too small to tell` means at least one could not. Before
+a sweep runs, the plan refuses a design too small to detect the change you accept.
+
+What Prove does not claim: that the change caused anything (it compares two runs), anything about
+conditions you did not sweep, or that an outcome label means what you meant by it. It is not a
+benchmark, an agent framework or an observability tool, and it never edits your code. [What the statistics claim](https://github.com/poisson-labs/prove/blob/main/docs/concepts/what-the-statistics-claim.md)
+says it in full, and [Defining outcomes](https://github.com/poisson-labs/prove/blob/main/docs/defining-outcomes.md)
+says how to choose labels that measure your agent and not your provider. The serve page and the
+traces have pages of their own:
+[Reading a serve page](https://github.com/poisson-labs/prove/blob/main/docs/reading-a-serve-page.md) and
+[What capture stores](https://github.com/poisson-labs/prove/blob/main/docs/what-capture-stores.md).
+
+## Where Prove sits beside Trace and Tasks
+
+Tasks makes the cases; Prove says whether a change moved the failure rate, and by how much it
+could have; Trace says where in a run it failed, and whether that moved. Prove installs alone and
+calls neither; Trace reads Prove's store. See
+[Prove with Trace and Tasks](https://github.com/poisson-labs/prove/blob/main/docs/with-trace-and-tasks.md).
+
+## Backends
+
+Sweeps run on your machine by default. `--backend modal` runs them in parallel Modal containers on
+your own account (`pip install "poisson-prove[modal]"`), with a cost estimate in the plan.
+`--backend burla` runs them on your own Burla cluster (`pip install "poisson-prove[burla]"`); it is
+experimental. Your rollout's code and conditions go to the account you choose, and the rows come
+back to the same local store. See [Backends](https://github.com/poisson-labs/prove/blob/main/docs/backends.md).
+
+Prove never phones home. No telemetry, no analytics, no update checks. `poisson-prove serve` binds a
+loopback listener on request and makes no outbound connection: it holds one page built from data
+already on the machine, and dies with the process.
+
+## Python
+
+The comparisons, the store and the statistics are importable; `compare.diff` returns the result
+`diff` prints:
+
+<!-- docs-check: run -->
+```python
+from poisson_prove import compare
+
+for run in compare.runs("prove-runs"):
+    print(run.run_name, run.run_id)
+```
+
+See [Python API](https://github.com/poisson-labs/prove/blob/main/docs/python.md).
+
+## Development
+
+[CONTRIBUTING.md](https://github.com/poisson-labs/prove/blob/main/CONTRIBUTING.md) says how to
+install a checkout, run the two test suites and send a change.
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/poisson-labs/prove/blob/main/LICENSE) and
+[NOTICE](https://github.com/poisson-labs/prove/blob/main/NOTICE) for what Prove includes from others.
+
+## Citation
+
+<!-- docs-check: skip: a citation to copy, not a command -->
+```bibtex
+@software{poisson_prove,
+  title  = {Poisson Prove},
+  author = {{Poisson Labs}},
+  year   = {2026},
+  url    = {https://github.com/poisson-labs/prove}
+}
+```