cloudposterior 0.6.0__tar.gz

cloudposterior-0.6.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC token for PyPI Trusted Publishing (no stored secrets)
+      contents: read
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Install Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build --no-sources
+
+      # Catch a wheel/sdist that's missing bundled files (remote/worker.py, the
+      # embedded dashboard HTML) before anything is uploaded -- versions on PyPI
+      # are immutable, so a broken artifact would burn the version number.
+      - name: Smoke test (wheel)
+        run: uv run --isolated --no-project --with dist/*.whl tests/smoke_test.py
+
+      - name: Smoke test (source distribution)
+        run: uv run --isolated --no-project --with dist/*.tar.gz tests/smoke_test.py
+
+      # Trusted Publishing (OIDC) + automatic PEP 740 attestations. uv build does
+      # not generate attestations, so the upload stays on the PyPA action (kept on
+      # its maintained moving tag, release/v1, per PyPA guidance).
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cloudposterior-0.6.0/.github/workflows/test.yml

@@ -0,0 +1,63 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+      - name: Lint with ruff
+        run: uvx ruff check cloudposterior/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        # Exercise both arviz majors: PyMC 5 ships arviz 0.x, PyMC 6 requires
+        # arviz 1.x (the DataTree rewrite). Modal e2e tests are not run in CI.
+        pymc: ["5", "6"]
+        exclude:
+          # PyMC 5 is legacy; don't gate the release on it under the newest
+          # Python. 3.13 is still covered by the PyMC 6 leg.
+          - python-version: "3.13"
+            pymc: "5"
+          # PyMC 6 needs arviz 1.x, whose compatible nutpie (>=0.16.10) ships no
+          # Python 3.11 wheel -- the combination is unsatisfiable. PyMC 6 is
+          # covered on 3.12 and 3.13.
+          - python-version: "3.11"
+            pymc: "6"
+
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      # Pin pymc AND arviz per leg so each major is exercised deterministically
+      # (an unpinned resolve drifts to the newest arviz for both legs).
+      - name: Run tests (PyMC ${{ matrix.pymc }})
+        run: |
+          if [ "${{ matrix.pymc }}" = "6" ]; then
+            uv run --python ${{ matrix.python-version }} \
+              --with "pymc>=6,<7" --with "arviz>=1.1,<2.0" --with "nutpie>=0.13" \
+              python -m pytest tests/ -v --cov=cloudposterior --cov-report=term-missing
+          else
+            uv run --python ${{ matrix.python-version }} \
+              --with "pymc>=5,<6" --with "arviz>=0.18,<1.0" --with "nutpie>=0.13" \
+              python -m pytest tests/ -v --cov=cloudposterior --cov-report=term-missing
+          fi

cloudposterior-0.6.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.env.local
+.venv/
+venv/
+*.nc
+.modal/
+.cloudposterior/
+
+# Local worktrees
+worktrees/
+
+# Local Claude Code settings and plans
+.claude/
+
+# marimo export session/layout artifacts
+__marimo__/

cloudposterior-0.6.0/CLAUDE.md

@@ -0,0 +1,106 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this project is
+
+cloudposterior lets you run PyMC MCMC sampling on cloud VMs (currently Modal) with one line of code. It intercepts `pm.sample()` via a context manager (`cp.cloud`) and adds cloud execution, automatic caching, live progress display, and phone notifications.
+
+## Commands
+
+```bash
+uv sync                          # install all deps (including dev group)
+uv run pytest tests/ -v          # run free local tests (default)
+uv run pytest tests/ -v --run-modal   # also run paid Modal e2e tests
+uv run pytest tests/test_cache.py -v          # run one test file
+uv run pytest tests/test_cache.py::test_name -v  # run single test
+```
+
+Tests marked `@pytest.mark.modal` (`tests/test_modal_e2e.py`) hit real Modal infrastructure and incur cloud costs. They are skipped unless `--run-modal` is passed. See `tests/conftest.py` for the marker plumbing.
+
+CI runs pytest on Python 3.11 and 3.12 (free tests only -- Modal tests are not in CI).
+
+## Example notebooks
+
+Each example in `examples/` exists in two formats that must be kept in sync:
+
+- `*.ipynb` -- the Jupyter version. This is the artifact GitHub renders (with embedded outputs), so it is what users see in the repo.
+- `*.py` -- the marimo version (`uv run marimo edit examples/<name>.py`). This is the source you edit and pair on.
+
+**Sync rule: whenever you change one format, update the other in the same change.** They are equivalent notebooks, not independent files -- an edit to a marimo `.py` cell must be mirrored into the matching `.ipynb`, and vice versa.
+
+- marimo `.py` -> `.ipynb`: `uv run marimo export ipynb examples/<name>.py -o examples/<name>.ipynb`. Add `--include-outputs` to refresh the rendered outputs, but note it re-executes the notebook (real Modal sampling, so cost + time -- only do this deliberately).
+- `.ipynb` -> marimo `.py`: `uvx marimo convert examples/<name>.ipynb -o examples/<name>.py`, then re-apply the marimo cleanups (drop trailing `;` output-suppression, make each cell's final expression the value to render). Do NOT add a PEP 723 script-metadata block -- `cloudposterior` is a local editable install and would fail to resolve from PyPI; these run in the project venv.
+- After editing either format, run `uv run marimo check examples/<name>.py` before committing.
+
+## Architecture
+
+### Request flow
+
+1. `cp.cloud(model)` context manager monkeypatches five PyMC functions to route through `api.py`: `pm.sample` (→ `_run_sample` / `_run_sample_persistent`), `pm.sample_prior_predictive` / `pm.sample_posterior_predictive` (→ `_run_predictive`), `pm.sample_smc` (→ `_run_smc`), and `pm.compute_log_likelihood` (→ `_run_idata_op`). The latter three reuse a blocking (non-streaming) remote-op template; only `pm.sample` streams per-draw progress.
+2. Model + observed data are serialized separately (cloudpickle + lz4 for the model, numpy + lz4 for data) in `serialize.py`
+3. Cache key is computed from the serialized bytes + sample kwargs (`cache.py`)
+4. If remote: `ModalBackend` (`backends/modal_backend.py`) submits a `SamplingPayload` to Modal, which runs `remote/worker.py` in a container with version-matched dependencies
+5. If local: the original `pm.sample` is called directly
+6. Progress events stream back via msgpack and are rendered by display sinks (an anywidget that animates live in both Jupyter and marimo notebooks, Rich for terminals) in `display.py`
+7. Results are cached and returned as `az.InferenceData`
+
+### Key abstractions
+
+- **`ComputeBackend` / `SamplingJob`** (`backends/__init__.py`): Abstract interface for compute providers. Only Modal is implemented; designed for future providers.
+- **`RemoteEnvironment`** (`backends/__init__.py`): Persistent execution environment with data pre-loaded (via Modal Volumes). Accepts multiple sampling jobs without re-uploading data. Provisioned via `ComputeBackend.provision()`.
+- **`CacheBackend`** (`cache.py`): Protocol with `MemoryCache` (default, session-scoped) and `DiskCache` (persistent, human-readable directory tree under `.cloudposterior/`).
+- **`ProgressEvent`** (`progress.py`): Union type of `PhaseUpdate` and `SamplingProgress` that flows through display sinks.
+- **`SamplingPayload`** (`serialize.py`): Dataclass bundling serialized model, data, version manifest, and sample kwargs for transport.
+
+### Persistent containers and volumes
+
+When `remote=True`, containers stay warm for 20 minutes. Model payloads are stored in a project-scoped Modal Volume so only sample kwargs are sent per-call:
+
+1. Model is serialized once in `__enter__()` and uploaded to a Volume at `{model_slug}/{data_slug}/payload-{hash}.bin`
+2. A `modal.Cls`-based sampler loads the payload from the mounted Volume (fast local read)
+3. Each `pm.sample()` call sends only kwargs + a path string -- no model/data bytes on the wire
+4. If the model changes between calls, the new payload is uploaded to the Volume (KB, fast)
+5. Volume is project-scoped (`cp-{project}`) -- cleaned up via `cp.cleanup_volumes(project=...)`
+
+The provisioned env is **kept warm past the `with` block** (not torn down in `__exit__`): it's held in `api._LIVE_ENVS` keyed by `(project, model_slug)` and reused by later runs of the same model, so the dashboard stays browsable and re-runs skip cold start. It's torn down by `cp.cleanup_volumes()` / `session.destroy()` / an `atexit` hook (Modal's `scaledown_window` idles the container out ~20 min regardless). Each run clears the control `Dict["stop"]` flag so a reused env doesn't inherit a stale stop.
+
+### Naming conventions (two layers)
+
+Human-readable names for browsability, machine hashes for correctness:
+
+| System | Human-readable (cosmetic) | Machine-correct (identity) |
+|--------|--------------------------|---------------------------|
+| Local disk cache | `{model_slug}/{data_slug}/{params}.nc` | `compute_cache_key()` SHA-256 |
+| Remote Volume | `{model_slug}/{data_slug}/payload-{hash}.bin` | `payload_hash()` SHA-256 prefix |
+| Notifications | `{model_slug}-{random_wordhash}` | N/A |
+
+Shared utilities in `naming.py`: `model_slug()`, `data_slug()`, `payload_hash()`, `wordhash()`
+
+### Live dashboard (`notify="dashboard"` or `notify=True` with `remote=True`)
+
+`dashboard.py` contains `DashboardSink` (writes progress to a Modal Dict) and `DASHBOARD_HTML` (self-contained page with JS polling). Two `@modal.fastapi_endpoint` functions serve the HTML and progress JSON. The dashboard URL includes the model name for readability (e.g., `radon-intercepts-a3f7b2-dev.modal.run`).
+
+When `notify=True` and `remote=True`, defaults to dashboard. When local, defaults to ntfy (start + complete notifications only).
+
+### Remote worker
+
+`remote/worker.py` runs inside Modal containers. It is never imported locally -- Modal serializes and executes it. It deserializes the model, runs sampling while streaming per-chain stats via a queue, and returns lz4-compressed NetCDF. `_sample_and_stream` branches three ways by sampler:
+
+- **`pymc`**: `pm.sample(nuts_sampler="pymc", callback=...)` -- the per-draw callback fills the progress queue. The `nuts_sampler="pymc"` is explicit so PyMC 6 doesn't auto-select nutpie (which would reject the callback).
+- **`nutpie`** (the default): runs nutpie's background sampler (`blocking=False`) with its native `progress_callback`; the generator loop polls the stop Dict and calls `handle.abort()` to stop early (keeping the partial trace), then `handle.wait()` for the final result.
+- **`numpyro`/`blackjax`**: `pm.sample(nuts_sampler=..., progressbar=False)` with **no callback** -- PyMC's external NUTS samplers run inside JAX with no per-draw hook (and PyMC 6 raises if a callback is passed). These report phase-level progress only.
+
+Besides streaming sampling, the worker has **blocking (non-streaming) entries** that load the model and return lz4 NetCDF directly: `run_prior_predictive` / `run_posterior_predictive`, `run_smc` (`pm.sample_smc`), and `run_compute_log_likelihood`. They mount as `@modal.method()`s on the persistent `Sampler` Cls and are driven client-side by `_run_blocking_op`.
+
+**Custom `step=` over the wire**: a step instance pickled separately from the model has value variables in a different graph than the worker's Volume-loaded model (PyMC raises "not a value variable in the model"). So `intercepted_sample` ships a combined `{model, step}` blob via `serialize_model_with_step`; `_unpack_model_payload` on the worker detects the dict, re-injects the step, and forces the pymc sampler (so the per-draw callback / live progress still work).
+
+### Samplers and arviz compatibility
+
+- **Default sampler**: `api._default_sampler()` picks nutpie for fully continuous models (PyMC's own default, ~2x faster) and the pymc sampler when there are discrete free RVs; locally it falls back to pymc when nutpie isn't installed. nutpie is always installed in CPU remote images (`_build_pip_specs`).
+- **Callback constraint**: PyMC's per-draw `callback` only fires for `nuts_sampler="pymc"`; PyMC 6 *raises* if a callback is passed to an external sampler. Only attach a callback on the pymc path (worker + `_run_local`).
+- **`_idata.py`**: thin shims so the codebase works on **both arviz 0.x (PyMC 5) and arviz 1.x (PyMC 6, DataTree)** -- `.groups()` vs `.groups`, removed `convert_to_inference_data`, changed `ess(method="tail")`, the dict-valued `sample_stats` attr nutpie writes, and object-dtype data vars from SMC's `sample_stats` (`beta`/`accept_rate`/`log_marginal_likelihood`, which even native `to_netcdf` rejects) -- both handled by `sanitize_inference_data`. `add_group` merges a remotely-computed group (e.g. `log_likelihood`) into a local idata in place. Always go through these helpers instead of calling arviz idata methods directly.
+
+### Auto-sizing
+
+`RemoteConfig._auto()` in `config.py` inspects the model's observed data size, parameter count, and chain count to right-size VM resources (CPU cores and memory).

cloudposterior-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spencer Boucher
+
+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.

cloudposterior-0.6.0/PKG-INFO

@@ -0,0 +1,403 @@
+Metadata-Version: 2.4
+Name: cloudposterior
+Version: 0.6.0
+Summary: Run PyMC MCMC sampling on cloud VMs with one line of code. Caching, live progress, and phone notifications included.
+Project-URL: Homepage, https://github.com/justmytwospence/cloudposterior
+Project-URL: Repository, https://github.com/justmytwospence/cloudposterior
+Project-URL: Issues, https://github.com/justmytwospence/cloudposterior/issues
+Author: Spencer Boucher
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bayesian,cloud,mcmc,modal,pymc,sampling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: anywidget>=0.9
+Requires-Dist: arviz<2.0,>=0.17
+Requires-Dist: cloudpickle>=3.0
+Requires-Dist: coolname>=4.0
+Requires-Dist: fastapi>=0.100
+Requires-Dist: ipywidgets>=8.0
+Requires-Dist: lz4>=4.0
+Requires-Dist: modal>=1.0
+Requires-Dist: msgpack>=1.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pymc>=5
+Requires-Dist: qrcode>=7.0
+Requires-Dist: requests>=2.28
+Requires-Dist: rich>=13.0
+Provides-Extra: nutpie
+Requires-Dist: nutpie>=0.13; extra == 'nutpie'
+Description-Content-Type: text/markdown
+
+# cloudposterior
+
+**Stop waiting for MCMC. Start shipping posteriors.**
+
+cloudposterior lets you run PyMC models on cloud VMs without changing your sampling code. One extra line gives you cloud compute, automatic caching, and phone notifications -- while `pm.sample()` stays exactly the same.
+
+```python
+import cloudposterior as cp
+
+with cp.cloud(model, remote=True):
+    idata = pm.sample(draws=5000, chains=8)  # 8 cores in the cloud, zero config
+```
+
+---
+
+## Why?
+
+You've built a hierarchical model. It's beautiful. But sampling takes 45 minutes on your laptop, your fans sound like a jet engine, and you can't use your machine for anything else.
+
+cloudposterior fixes this:
+
+- **Ship sampling to the cloud** with one line. Your model runs on a VM with as many cores and as much RAM as it needs.
+- **Never re-run the same model twice.** Results are cached automatically -- re-execute a notebook cell and get your posterior back instantly.
+- **Monitor from anywhere.** Get live progress notifications on your phone while your model samples.
+
+All three features work independently. Use any combination, or just the caching.
+
+---
+
+## Quick start
+
+```bash
+uv add cloudposterior
+
+# For cloud execution (optional):
+uv add modal && uv run modal setup
+```
+
+```python
+import pymc as pm
+import cloudposterior as cp
+
+with pm.Model() as my_model:
+    mu = pm.Normal("mu", 0, 5)
+    sigma = pm.HalfNormal("sigma", 5)
+    pm.Normal("obs", mu, sigma, observed=data)
+
+# This is the only line you add:
+with cp.cloud(my_model, remote=True, cache="disk"):
+    idata = pm.sample(draws=2000, chains=4)
+```
+
+Second time you run that cell? Instant. The result is already cached.
+
+---
+
+## Features
+
+### Cloud execution
+
+Offload MCMC to cloud VMs. No Docker, no infrastructure, no config files. [Modal](https://modal.com) handles containers, scaling, and cleanup.
+
+```python
+with cp.cloud(model, remote=True):
+    idata = pm.sample(draws=5000, chains=8)
+```
+
+Your model is serialized with cloudpickle, shipped to a container with version-matched dependencies (PyMC, PyTensor, numpy -- all pinned to your exact local versions), sampled there, and the trace is compressed and sent back. The container image is built once and cached, so subsequent runs start in seconds.
+
+### Smart resource sizing
+
+cloudposterior inspects your model and sampling config to right-size the VM automatically:
+
+- **CPU cores** matched to your chain count (8 chains = 8 cores)
+- **Memory** scaled to your observed data size and parameter count
+
+No guessing, no over-provisioning. A small model gets 4 cores and 4GB. A hierarchical model with large datasets gets 8+ cores and 16GB+. The progress display shows what was chosen:
+
+```
+cloudposterior -- Modal (auto-sized: 8 cores, 8GB)
+```
+
+Want explicit control? Use a preset:
+
+```python
+with cp.cloud(model, remote=True, instance="xlarge"):  # 32 cores, 64GB
+    ...
+```
+
+The container is sized on the **first** `pm.sample()` call inside `with cp.cloud(...)` and stays that size for the duration of the block. If a later call uses different `chains`/`draws` that the auto-sizer would have provisioned differently, you'll get a warning -- start a new `cp.cloud()` block to resize.
+
+### Automatic caching
+
+Re-running a notebook cell? If the model, data, and sampling config haven't changed, cloudposterior returns the cached result instantly. No wasted compute. Caching is **on by default**.
+
+```python
+with cp.cloud(model):
+    idata = pm.sample(draws=2000)  # samples normally
+
+with cp.cloud(model):
+    idata = pm.sample(draws=2000)  # instant -- cached
+```
+
+For persistence across kernel restarts, use disk caching:
+
+```python
+with cp.cloud(model, cache="disk"):
+    idata = pm.sample(draws=2000)
+```
+
+Results are stored in a human-readable directory tree:
+
+```
+.cloudposterior/
+├── radon_intercepts/
+│   └── draws2000_tune1000_chains4-a3f7b2c9.nc
+└── radon_slopes/
+    └── draws2000_tune1000_chains4-7c2e5fa8.nc
+```
+
+Model names come from `pm.Model(name="radon_intercepts")`. The hash suffix ensures uniqueness when non-displayed parameters (like `random_seed`) differ.
+
+### Monitoring
+
+Two ways to monitor sampling:
+
+**Live dashboard** (on by default for remote) -- convergence diagnostics, trace plots, and a stop button:
+
+```python
+with cp.cloud(model, remote=True):
+    idata = pm.sample(draws=5000, chains=8)
+```
+
+Scan the QR code or open the URL on your phone. No app install needed.
+
+**Push notifications** -- get notified when sampling starts and completes via [ntfy](https://ntfy.sh):
+
+```python
+with cp.cloud(model, notify=True):              # auto topic
+with cp.cloud(model, notify="my-channel"):      # custom topic
+with cp.cloud(model, remote=True, notify=True): # remote (dashboard on by default) + ntfy
+```
+
+With `remote=True`, the dashboard is on by default; `notify=True` adds ntfy push notifications on top.
+
+### Live progress display
+
+Both Jupyter notebooks and terminals show real-time, in-place progress for every phase:
+
+1. Serialization
+2. Upload
+3. Container provisioning
+4. MCMC sampling -- per-chain progress bars, divergences, step size, grad evals, speed, ETA
+5. Result download
+
+Notebooks get a live anywidget display that animates in-cell in both Jupyter and marimo. Terminals get a Rich TUI. Progress bars turn red when chains diverge, just like PyMC's native display. During a remote run a **Stop** button appears in the cell -- click it to abort early and keep the partial trace.
+
+### Samplers
+
+cloudposterior defaults to **nutpie** -- PyMC's recommended NUTS sampler, roughly 2x faster on CPU -- for fully continuous models, and falls back to PyMC's built-in sampler for models with discrete variables. Override per call:
+
+```python
+with cp.cloud(model, remote=True):
+    idata = pm.sample()                         # nutpie (default for continuous models)
+    idata = pm.sample(nuts_sampler="pymc")      # PyMC's sampler (handles discrete vars)
+    idata = pm.sample(nuts_sampler="numpyro")   # JAX sampler (GPU auto-provisioned)
+```
+
+Live per-chain progress, convergence diagnostics (rank-normalized R-hat and ESS), and the stop button work with **nutpie** and **pymc**. JAX samplers (`numpyro`, `blackjax`) run entirely inside a compiled graph with no per-draw hook, so they report phase-level progress only.
+
+Custom step methods work too -- pass `step=pm.Metropolis()` (or `Slice`, `DEMetropolis`, a `CompoundStep`, ...) and cloudposterior routes to PyMC's sampler and ships the step alongside the model so it samples correctly in the cloud, with live progress. Discrete models that rely on PyMC's automatic step assignment need no `step=` at all -- just call `pm.sample()`.
+
+Works with both **PyMC 5 and PyMC 6** (PyMC 6 ships arviz 1.x's DataTree); the versions installed in the remote container are matched to your local environment.
+
+### Adaptive sampling
+
+Stop as soon as the chains converge instead of guessing a draw count -- `draws` becomes the cap:
+
+```python
+with cp.cloud(model, remote=True, until={"r_hat": 1.01, "ess": 400}):
+    idata = pm.sample(draws=20000)   # stops early once every parameter clears the target
+```
+
+`until=True` uses the Vehtari (2021) defaults shown above. Works with **nutpie** and **pymc** (the samplers with a per-draw hook).
+
+### Parallel fitting
+
+Fit many models at once on a single warm container -- ideal for model comparison and prior sensitivity:
+
+```python
+import arviz as az
+
+idatas = cp.map([pooled, hierarchical, per_county], {"draws": 1000})
+az.compare(dict(zip(["pooled", "hier", "county"], idatas)))
+```
+
+`sample_kwargs` is a shared dict or a list aligned with the models. Results return in input order. See [examples/parallelism.ipynb](examples/parallelism.ipynb).
+
+### Predictive checks and model comparison
+
+`pm.sample_prior_predictive()` and `pm.sample_posterior_predictive()` are intercepted too, so prior/posterior predictive checks (and GP `.conditional()` predictions, which run through posterior predictive) execute on the same cloud container.
+
+`pm.compute_log_likelihood()` is intercepted as well -- compute pointwise log-likelihoods in the cloud, then run `az.loo` / `az.waic` / `az.compare` locally:
+
+```python
+with cp.cloud(model, remote=True):
+    idata = pm.sample(draws=2000)
+    pm.compute_log_likelihood(idata)   # adds the log_likelihood group, in the cloud
+az.loo(idata)
+```
+
+`pm.sample_smc()` (Sequential Monte Carlo) runs in the cloud too, for multimodal posteriors and model evidence.
+
+---
+
+## What runs in the cloud
+
+cloudposterior runs the **entire MCMC workflow** on the cloud container -- posterior sampling (NUTS and step methods, all four backends), prior/posterior predictive checks, SMC, and log-likelihood for model comparison. Optimization-based inference (variational inference, MAP) and a few non-`InferenceData` utilities are not yet routed to the cloud; they still run locally as usual.
+
+| Supported in the cloud | Not yet (runs locally) |
+|------------------------|------------------------|
+| `pm.sample()` -- NUTS (`nutpie`, `pymc`, `numpyro`, `blackjax`) | `pm.fit()` -- variational inference (ADVI, etc.) |
+| `pm.sample()` with custom `step=` (Metropolis, Slice, DEMetropolis, ...) | `pm.find_MAP()` -- MAP point estimation |
+| `pm.sample_smc()` -- Sequential Monte Carlo | `pm.compute_deterministics()` |
+| `pm.sample_prior_predictive()` / `pm.sample_posterior_predictive()` | `pm.draw()` |
+| `pm.compute_log_likelihood()` -- LOO/WAIC/`az.compare` | pymc-extras (`fit_pathfinder`, `fit_laplace`) |
+
+Two `pm.sample` details can't be matched exactly for remote execution and warn rather than silently diverge: `return_inferencedata=False` (a `MultiTrace` can't be transported, so you get an `InferenceData`) and a per-draw `callback=` (it can't run against local state inside a container -- use `remote=False` for that). VI, MAP, and the non-`InferenceData` utilities are a planned follow-up.
+
+---
+
+## Composable features
+
+| Feature | Default | Control |
+|---------|---------|---------|
+| Caching | **on** (in-memory) | `cache=True` / `False` / `"disk"` / `Path(...)` |
+| Cloud execution | off | `remote=True` / `False` |
+| Live dashboard | **on** (when remote) | `dashboard=True` / `False` |
+| Push notifications | off | `notify=True` / `"topic"` / `{"server": ..., "topic": ...}` |
+| Adaptive early-stop | off | `until=True` / `{"r_hat": ..., "ess": ...}` (remote) |
+
+Mix and match:
+
+```python
+with cp.cloud(model):                                          # local + memory cache
+with cp.cloud(model, cache="disk"):                            # local + disk cache
+with cp.cloud(model, remote=True):                             # cloud + dashboard
+with cp.cloud(model, remote=True, cache="disk", notify=True):  # everything
+```
+
+---
+
+## Configuration
+
+### Instance presets
+
+| Name     | CPUs | Memory |
+|----------|------|--------|
+| `small`  | 4    | 8 GB   |
+| `medium` | 8    | 16 GB  |
+| `large`  | 16   | 32 GB  |
+| `xlarge` | 32   | 64 GB  |
+| `gpu`    | 8    | 16 GB + A100 |
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `CLOUDPOSTERIOR_NTFY_TOPIC` | Default ntfy topic |
+| `CLOUDPOSTERIOR_NTFY_SERVER` | Custom ntfy server (default: `https://ntfy.sh`) |
+
+---
+
+## Cloud backend
+
+Cloud execution currently uses [Modal](https://modal.com). Modal provides fast container spin-up, automatic dependency packaging, and a generous free tier.
+
+```bash
+uv add modal
+modal setup  # one-time browser auth
+```
+
+The backend is abstracted behind a `ComputeBackend` interface. Support for additional providers (AWS, GCP, SSH to your own machines) is planned.
+
+---
+
+## How it works
+
+1. **Serialize** -- The model is serialized with cloudpickle + lz4 on the first `pm.sample()` call inside `with cp.cloud(...)`. Cloudpickle bundles your observed data into the model object, so there's a single payload, not two. A version manifest captures your exact package versions.
+2. **Upload once** -- The serialized payload is uploaded to a Modal Volume the first time. Subsequent calls with the same model skip the upload entirely. Old payloads from past edits are pruned automatically.
+3. **Sample** -- `pm.sample()` runs remotely. The container loads the payload from the mounted Volume (fast local read) and streams per-chain progress back in real time via msgpack. Only sample kwargs and a path string are sent over the wire per call.
+4. **Return** -- The InferenceData trace is compressed as NetCDF, sent back, and cached.
+
+The container stays warm for ~20 minutes **after the `with` block exits**, so a re-run of the same model is near-instant and the live dashboard stays browsable in the meantime (open it on your phone, walk away, come back and check). It idles out on its own and is torn down when the kernel exits; stop it immediately with `cp.cleanup_volumes()` or `session.destroy()`.
+
+---
+
+## Cleanup
+
+Model payloads are stored in a project-scoped Modal Volume. The following also stops any kept-warm container/dashboard for the project:
+
+```python
+cp.cleanup_volumes()                        # delete the current project's volume
+cp.cleanup_volumes(project="my-research")   # delete a specific project's volume
+```
+
+For a one-shot teardown that also stops a warm container immediately, use the context manager's `destroy()`:
+
+```python
+session = cp.cloud(model, remote=True)
+with session:
+    idata = pm.sample(draws=2000)
+session.destroy()  # stop the container and delete the project volume
+```
+
+---
+
+## Explicit API
+
+If you prefer not to use the context manager, `cp.sample()` runs a single remote sampling job (always cloud, no persistent container reuse):
+
+```python
+idata = cp.sample(model, draws=2000, chains=4)
+```
+
+For repeated sampling with the same model, the `cp.cloud()` context manager is cheaper -- it keeps the container warm and only sends kwargs after the first call.
+
+---
+
+## Example
+
+Clone and run locally (Jupyter or marimo) for the full live progress display.
+
+- [examples/basics.ipynb](examples/basics.ipynb) -- cloud execution and GPU acceleration with the Minnesota Radon dataset
+- [examples/caching.ipynb](examples/caching.ipynb) -- local and disk caching, model iteration
+- [examples/monitoring.ipynb](examples/monitoring.ipynb) -- live dashboard and push notifications
+- [examples/parallelism.ipynb](examples/parallelism.ipynb) -- fit many models in parallel with `cp.map` and compare them with LOO
+
+---
+
+## Tests
+
+The default suite is fast and free -- it covers serialization, caching, naming, kwarg validation, and runs `cp.cloud(model)` end-to-end against a local PyMC sampler:
+
+```bash
+uv run pytest tests/ -v
+```
+
+A separate suite of end-to-end tests hits real Modal infrastructure to verify the cloud path. These cost a small amount of Modal credit per run and are skipped by default. Opt in with `--run-modal`:
+
+```bash
+uv run pytest tests/test_modal_e2e.py -v --run-modal
+```
+
+Modal tests provision the smallest possible instance, sample 20 draws on a 2-RV model, and use isolated per-test project volumes that are cleaned up at teardown.
+
+---
+
+## Status
+
+Early proof of concept. Works end-to-end with 75+ passing tests, but expect rough edges. Contributions and feedback welcome.
+
+## License
+
+MIT