sbi-dev · Jocho-Smith · Jul 20, 2026 · Jul 20, 2026 · Jul 20, 2026 · Jul 21, 2026
diff --git a/.github/workflows/docs-link-check.yml b/.github/workflows/docs-link-check.yml
@@ -0,0 +1,38 @@
+name: Docs Link Check
+
+# Validates the hard-coded URLs in llms.txt and AGENTS.md, which are not covered by
+# any other CI. Runs monthly rather than per-PR so transient or rate-limited external
+# responses don't block contributors.
+
+on:
+  schedule:
+    - cron: '0 6 1 * *'  # 06:00 UTC on the 1st of each month
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  link-check:
+    name: Check documentation links
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          lfs: false
+          persist-credentials: false
+
+      - name: Check links with lychee
+        uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # authenticate github.com links (avoid 60/hr rate limit)
+        with:
+          args: >-
+            --no-progress --verbose
+            docs/llms.txt AGENTS.md
+          fail: true
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,55 @@
+# AGENTS.md — sbi
+
+Shared guidance for coding agents working in this repository.
+
+## Setup
+
+```bash
+uv venv --python 3.12
+uv pip install -e ".[dev]"
+```
+
+Run validation commands through `uv run`; activating the virtual environment is
+optional. See `docs/contributing.md` for the full development workflow and
+`pyproject.toml` for the authoritative tool configuration.
+
+## Validation
+
+Start with checks targeted to the files and behavior you changed, then broaden as
+appropriate:
+
+```bash
+uv run pytest tests/path_to_relevant_test.py
+uv run pytest -n auto -m "not slow and not gpu"
+uv run ruff check <changed Python paths>
+uv run ruff format --check <changed Python paths>
+uv run pyright sbi
+uv run pre-commit run --files <changed files>
+```
+
+Tests live in `*_test.py` files. Available markers include `slow`, `gpu`, `mcmc`, and
+`benchmark`; their definitions are in `pyproject.toml`.
+
+## Code conventions
+
+- Use Google-style docstrings.
+- Put shared public type aliases in `sbi/sbi_types.py`.
+- Keep string identifiers for estimators lowercase (for example, `"maf"`, `"nsf"`,
+  and `"mdn"`).
+- Add or update tests when behavior changes.
+- Preserve unrelated local changes. If a checkout is already in use, work in a
+  separate Git worktree.
+
+## Code map
+
+Inspect the current code rather than relying on a duplicated class inventory:
+
+- `sbi/inference/__init__.py` — public inference methods
+- `sbi/inference/trainers/` — training workflows
+- `sbi/inference/posteriors/` — posterior implementations
+- `sbi/inference/potentials/` — estimator-to-sampler bridges
+- `sbi/neural_nets/estimators/` — estimator contracts and implementations
+- `sbi/samplers/` — sampling backends
+
+The documentation is built from `docs/`. Its curated `docs/llms.txt` index is served
+at `https://sbi.readthedocs.io/en/latest/llms.txt` for tools that support it.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,6 @@
+# CLAUDE.md
+
+This repository's instructions for AI coding agents live in `AGENTS.md` (shared across
+all tools). Claude Code imports them here:
+
+@AGENTS.md
diff --git a/docs/conf.py b/docs/conf.py
@@ -55,6 +55,9 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+# Serve llms.txt at the docs URL root for AI agent discoverability.
+html_extra_path = ['llms.txt']
+
 # Myst-NB
 myst_enable_extensions = [
     "dollarmath",

diff --git a/docs/contributor_guide.rst b/docs/contributor_guide.rst
@@ -5,7 +5,8 @@ Developer notes
 
 `sbi` welcomes contributions from the community.
 These are guides to get set up as a developer, as well as
-developer-focused resources.
+developer-focused resources. For a list of current and former project
+maintainers, see the :doc:`credits page <credits>`.
 
 
 .. toctree::

diff --git a/docs/credits.md b/docs/credits.md
@@ -6,6 +6,22 @@
 played a significant role in shaping `sbi`. Their valuable input, suggestions, and
 direct contributions to the codebase have been instrumental in the development of `sbi`.
 
+## Maintainers
+
+`sbi` is maintained by the following people. Current maintainers are
+
+- [Jan Teusen (né Boelts)](https://github.com/janfb)
+- [Manuel Gloeckler](https://github.com/manuelgloeckler)
+- [Daniel Gedon](https://github.com/dgedon)
+- [Stefan Wahl](https://github.com/StefanWahl)
+
+Former maintainers are
+
+- [Michael Deistler](https://github.com/michaeldeistler)
+- [Guy Moss](https://github.com/gmoss13)
+- [Jan-Matthis Lückmann](https://github.com/jan-matthis)
+- [Alvaro Tejero-Cantero](https://github.com/alvorithm)
+
 ## License
 
 `sbi` is licensed under the [Apache License

diff --git a/docs/llms.txt b/docs/llms.txt
@@ -0,0 +1,72 @@
+# sbi: Simulation-Based Inference
+
+> sbi is a PyTorch-based Python package for simulation-based inference (SBI).
+> It estimates full Bayesian posterior distributions over simulator parameters
+> from observed data, without requiring access to the simulator's likelihood
+> function. Methods include Neural Posterior Estimation (NPE), Neural Likelihood
+> Estimation (NLE), Neural Ratio Estimation (NRE), and flow/score matching (FMPE, NPSE).
+
+sbi provides both a simple one-line interface (`sbi.inference.infer`) and a
+flexible class-based interface (`NPE`, `NLE`, `NRE`, `FMPE`). The typical
+workflow is: define a prior and simulator, generate simulations, train a neural
+density estimator, build a posterior, and validate with diagnostics (SBC,
+expected coverage, TARP, L-C2ST).
+
+## Tutorials
+
+- [Getting Started](https://sbi.readthedocs.io/en/latest/tutorials/00_getting_started.html): Minimal NPE example from prior to posterior
+- [Bayesian Workflow](https://sbi.readthedocs.io/en/latest/tutorials/01_Bayesian_workflow.html): Full workflow with diagnostics and analysis
+- [Implemented Methods](https://sbi.readthedocs.io/en/latest/tutorials/16_implemented_methods.html): All NPE, NLE, NRE, FMPE variants with code
+- [Vector Field Methods](https://sbi.readthedocs.io/en/latest/advanced_tutorials/19_vector_field_methods.html): FMPE and NPSE — flow matching and score matching for SBI
+
+## How-To Guides
+
+- [Custom Priors](https://sbi.readthedocs.io/en/latest/how_to_guide/00_custom_prior.html): MultipleIndependent, process_prior, non-torch priors
+- [Summary Statistics](https://sbi.readthedocs.io/en/latest/how_to_guide/01_crafting_summary_statistics.html): Hand-crafted features for high-dim data
+- [Multi-Round Inference](https://sbi.readthedocs.io/en/latest/how_to_guide/02_multiround_inference.html): Sequential methods (SNPE, SNLE, SNRE)
+- [Density Estimators](https://sbi.readthedocs.io/en/latest/how_to_guide/03_density_estimators.html): Choosing and configuring neural networks
+- [Embedding Networks](https://sbi.readthedocs.io/en/latest/how_to_guide/04_embedding_networks.html): FCEmbedding, CNNEmbedding, custom nn.Module
+- [Choosing Inference Method](https://sbi.readthedocs.io/en/latest/how_to_guide/06_choosing_inference_method.html): NPE vs NLE vs NRE decision guide
+- [Sampler Interface](https://sbi.readthedocs.io/en/latest/how_to_guide/09_sampler_interface.html): MCMC, VI, rejection for NLE/NRE posteriors
+- [i.i.d. Observations](https://sbi.readthedocs.io/en/latest/how_to_guide/11_iid_sampling_with_nle_or_nre.html): Multiple observations with NLE/NRE
+- [Hyperparameter Tuning](https://sbi.readthedocs.io/en/latest/how_to_guide/21_hyperparameter_tuning.html): Optuna integration for architecture search
+- [Abstraction Levels](https://sbi.readthedocs.io/en/latest/how_to_guide/24_abstraction_levels.html): Four levels of control over the density estimator (Trainer classes to custom `nn.Module`), plus sampling-control levels for NLE
+- [FMPE and NPSE Recommendations](https://sbi.readthedocs.io/en/latest/how_to_guide/25_choosing_vector_field_options.html): Practical guide for choosing between vector field methods and configuring them
+
+## Diagnostics
+
+- [Choosing a Diagnostic](https://sbi.readthedocs.io/en/latest/how_to_guide/14_choose_diagnostic_tool.html): Which validation tool to use
+- [Expected Coverage](https://sbi.readthedocs.io/en/latest/how_to_guide/15_expected_coverage.html): Joint posterior calibration check
+- [Simulation-Based Calibration](https://sbi.readthedocs.io/en/latest/how_to_guide/16_sbc.html): Per-parameter marginal calibration
+- [TARP](https://sbi.readthedocs.io/en/latest/how_to_guide/17_tarp.html): Calibration without density evaluation
+- [L-C2ST](https://sbi.readthedocs.io/en/latest/how_to_guide/13_diagnostics_lc2st.html): Per-observation local coverage test
+- [Model Misspecification](https://sbi.readthedocs.io/en/latest/how_to_guide/18_model_misspecification.html): Detecting if x_o is outside simulator range
+
+## Advanced Topics
+
+- [Time Series Embeddings](https://sbi.readthedocs.io/en/latest/how_to_guide/20_time_series_embedding.html): CausalCNN, Transformer for temporal data
+- [Restriction Estimator](https://sbi.readthedocs.io/en/latest/advanced_tutorials/06_restriction_estimator.html): Handling invalid simulations (NaN/Inf)
+- [Sensitivity Analysis](https://sbi.readthedocs.io/en/latest/advanced_tutorials/07_sensitivity_analysis.html): ActiveSubspace for parameter importance
+- [Posterior Parameters](https://sbi.readthedocs.io/en/latest/how_to_guide/19_posterior_parameters.html): Dataclass-based sampler configuration
+- [Experiment Tracking](https://sbi.readthedocs.io/en/latest/how_to_guide/22_experiment_tracking.html): TensorBoard, WandB, MLflow adapters
+- [Pyro Integration](https://sbi.readthedocs.io/en/latest/how_to_guide/23_using_pyro_with_sbi.html): Neural likelihoods in Pyro hierarchical models
+
+## API Reference
+
+- [Inference API](https://sbi.readthedocs.io/en/latest/api_reference.html): NPE, NLE, NRE, FMPE trainers and posteriors
+- [Installation](https://sbi.readthedocs.io/en/latest/installation.html): pip install sbi, optional dependencies
+- [Changelog](https://sbi.readthedocs.io/en/latest/changelog.html): Version history and migration notes
+- [FAQ](https://sbi.readthedocs.io/en/latest/faq.html): Common issues (leakage, NaNs, pickling, unconstrained space)
+
+## Optional
+
+- [Hodgkin-Huxley Example](https://sbi.readthedocs.io/en/latest/tutorials/Example_00_HodgkinHuxleyModel.html): Neuroscience application
+- [Decision-Making Model](https://sbi.readthedocs.io/en/latest/tutorials/Example_01_DecisionMakingModel.html): Cognitive science application
+- [GPU Training](https://sbi.readthedocs.io/en/latest/how_to_guide/07_gpu_training.html): CUDA and MPS device configuration
+- [Save and Load](https://sbi.readthedocs.io/en/latest/how_to_guide/07_save_and_load.html): Pickling posteriors, CPU_Unpickler
+- [Resume Training](https://sbi.readthedocs.io/en/latest/how_to_guide/07_resume_training.html): Checkpoint and resume
+- [MCMC Diagnostics](https://sbi.readthedocs.io/en/latest/how_to_guide/12_mcmc_diagnostics_with_arviz.html): ArviZ trace plots and R-hat
+- [Conditional Distributions](https://sbi.readthedocs.io/en/latest/how_to_guide/05_conditional_distributions.html): Conditional pairplots
+- [Importance Sampling](https://sbi.readthedocs.io/en/latest/how_to_guide/10_refine_posterior_with_importance_sampling.html): Refining posteriors
+- [Permutation-Invariant Embeddings](https://sbi.readthedocs.io/en/latest/how_to_guide/08_permutation_invariant_embeddings.html): i.i.d. data with NPE
+- [Contributing Guide](https://sbi.readthedocs.io/en/latest/contributing.html): How to contribute to sbi
diff --git a/sbi/inference/posteriors/base_posterior.py b/sbi/inference/posteriors/base_posterior.py
@@ -93,7 +93,7 @@ def potential(
                 This can be helpful for e.g. sensitivity analysis, but increases memory
                 consumption.
         """
-        self.potential_fn.set_x(self._x_else_default_x(x))
+        self.potential_fn = self.potential_fn.bind(self._x_else_default_x(x))
 
         theta = ensure_theta_batched(torch.as_tensor(theta))
         return self.potential_fn(
@@ -294,7 +294,7 @@ def map(
             )
 
         if self._map is None or force_update:
-            self.potential_fn.set_x(self.default_x)
+            self.potential_fn = self.potential_fn.bind(self.default_x)
             self._map = self._calculate_map(
                 num_iter=num_iter,
                 num_to_optimize=num_to_optimize,

diff --git a/sbi/inference/posteriors/ensemble_posterior.py b/sbi/inference/posteriors/ensemble_posterior.py
@@ -317,7 +317,7 @@ def potential(
                 This can be helpful for e.g. sensitivity analysis, but increases memory
                 consumption.
         """
-        self.potential_fn.set_x(self._x_else_default_x(x))
+        self.potential_fn = self.potential_fn.bind(self._x_else_default_x(x))
 
         theta = ensure_theta_batched(torch.as_tensor(theta))
 
@@ -398,7 +398,7 @@ def map(
             return log_weights, maps
 
         else:
-            self.potential_fn.set_x(self._x_else_default_x(x))
+            self.potential_fn = self.potential_fn.bind(self._x_else_default_x(x))
 
             if init_method == "posterior":
                 inits = self.sample((num_init_samples,), self._x_else_default_x(x))
@@ -488,6 +488,28 @@ def set_x(self, x_o: Optional[Tensor]):
         for comp_potential in self.potential_fns:
             comp_potential.set_x(x_o)
 
+    def bind(
+        self,
+        x_o: Tensor,
+        x_is_iid: bool = True,
+        **kwargs,
+    ) -> "EnsemblePotential":
+        """Return a new EnsemblePotential with x_o bound to all component potentials."""
+        if x_o is not None:
+            x_o = process_x(x_o).to(self.device)
+
+        bound_potentials = [
+            p.bind(x_o, x_is_iid=x_is_iid, **kwargs) for p in self.potential_fns
+        ]
+
+        return EnsemblePotential(
+            potential_fns=bound_potentials,
+            weights=self._weights,
+            prior=self.prior,
+            x_o=x_o,
+            device=self.device,
+        )
+
     def __call__(self, theta: Tensor, track_gradients: bool = True) -> Tensor:
         r"""Returns the potential for posterior-based methods.
 

diff --git a/sbi/inference/posteriors/importance_posterior.py b/sbi/inference/posteriors/importance_posterior.py
@@ -128,7 +128,7 @@ def log_prob(
             `len($\theta$)`-shaped log-probability.
         """
         x = self._x_else_default_x(x)
-        self.potential_fn.set_x(x)
+        self.potential_fn = self.potential_fn.bind(x)
 
         theta = ensure_theta_batched(torch.as_tensor(theta))
 
@@ -212,7 +212,7 @@ def sample(
 
         method = self.method if method is None else method
 
-        self.potential_fn.set_x(self._x_else_default_x(x))
+        self.potential_fn = self.potential_fn.bind(self._x_else_default_x(x))
 
         if method == "sir":
             return self._sir_sample(

diff --git a/sbi/inference/posteriors/mcmc_posterior.py b/sbi/inference/posteriors/mcmc_posterior.py
@@ -2,7 +2,6 @@
 # under the Apache License Version 2.0, see <https://www.apache.org/licenses/>
 import inspect
 import warnings
-from copy import deepcopy
 from functools import partial
 from math import ceil
 from typing import Any, Callable, Dict, Literal, Optional, Union
@@ -237,7 +236,7 @@ def log_prob(
         warn("The log-probability is unnormalized!", stacklevel=2)
 
         x = self._x_else_default_x(x)
-        self.potential_fn.set_x(x, x_is_iid=True)
+        self.potential_fn = self.potential_fn.bind(x, x_is_iid=True)
 
         theta = ensure_theta_batched(torch.as_tensor(theta))
         return self.potential_fn(
@@ -291,7 +290,7 @@ def sample(
         """
 
         x = self._x_else_default_x(x)
-        self.potential_fn.set_x(x, x_is_iid=True)
+        self.potential_fn = self.potential_fn.bind(x, x_is_iid=True)
 
         # Replace arguments that were not passed with their default.
         method = self.method if method is None else method
@@ -451,7 +450,7 @@ def sample_batched(
         # in the order of the observations.
         x_ = x.repeat_interleave(num_chains, dim=0)
 
-        self.potential_fn.set_x(x_, x_is_iid=False)
+        self.potential_fn = self.potential_fn.bind(x_, x_is_iid=False)
         self.potential_ = self._prepare_potential(method)  # type: ignore
 
         # For each observation in the batch, we have num_chains independent chains.
@@ -662,25 +661,25 @@ def _get_initial_params_batched(
             Tensor: initial parameters, one for each chain
         """
 
-        potential_ = deepcopy(self.potential_fn)
+        potential_ = self.potential_fn
         initial_params = []
-        init_fn = self._build_mcmc_init_fn(
-            self.proposal,
-            potential_fn=potential_,
-            transform=self.theta_transform,
-            init_strategy=init_strategy,  # type: ignore
-            **kwargs,
-        )
         for xi in x:
-            # Build init function
-            potential_.set_x(xi)
+            # Build init function with bound potential for this specific xi
+            potential_bound = potential_.bind(xi)
+            init_fn = self._build_mcmc_init_fn(
+                self.proposal,
+                potential_fn=potential_bound,
+                transform=self.theta_transform,
+                init_strategy=init_strategy,  # type: ignore
+                **kwargs,
+            )
 
             # Parallelize inits for resampling or sir.
             if num_workers > 1 and (
                 init_strategy == "resample" or init_strategy == "sir"
             ):
 
-                def seeded_init_fn(seed):
+                def seeded_init_fn(seed, init_fn=init_fn):
                     torch.manual_seed(seed)
                     return init_fn()
 

diff --git a/sbi/inference/posteriors/rejection_posterior.py b/sbi/inference/posteriors/rejection_posterior.py
@@ -120,7 +120,7 @@ def log_prob(
         )
         warn("The log-probability is unnormalized!", stacklevel=2)
 
-        self.potential_fn.set_x(self._x_else_default_x(x))
+        self.potential_fn = self.potential_fn.bind(self._x_else_default_x(x))
 
         theta = ensure_theta_batched(torch.as_tensor(theta))
         return self.potential_fn(
@@ -174,7 +174,7 @@ def sample(
             Samples from posterior.
         """
         num_samples = torch.Size(sample_shape).numel()
-        self.potential_fn.set_x(self._x_else_default_x(x))
+        self.potential_fn = self.potential_fn.bind(self._x_else_default_x(x))
 
         potential = partial(self.potential_fn, track_gradients=True)