Quivers

A functional probabilistic programming language for PyTorch.

Tutorial · Examples · Guides · API · Semantics

---

Quivers is a functional probabilistic programming language for PyTorch. The surface will look familiar if you have used Pyro, NumPyro, Stan, or PyMC. But it has a few distinguishing features:

• Programs are first-class composable typed values. A program has a domain, codomain, algebra, and effect signature ([effects=[Sample, Score, Marginal]]), checked at compile time. Programs compose with >>, parallel-compose with @, change base across algebras with change_base, and marginalize discrete latents with a scoped marginalize z : K <- ... block.
• Shared substrate for inference, deduction, and structural compression. A CKY parser in a deduction block (its atoms, rule, and lexicon entries), a transformer-as-encoder over a signature block, and a Bayesian regression all compile to the same underlying semantics, with the same composition operators, and can thus compose with each other.
• Algebra-parametric semantics. Programs can be parameterized by eleven built-in or user-defined algebras. Homomorphisms between algebras are values along which models can be transported. The compiler checks their source and target types; the algebraic laws remain assumptions of each instance.

The probabilistic-programming surface also includes:

• An inference toolkit. More than forty distribution families. SVI with automatic guides from mean-field and full-rank multivariate normals through low-rank, mixture, structured, IAF, neural-spline flow, and AutoDAIS guides; seven objectives (ELBO, IWAE, Renyi, VR-IWAE, ChiVI, RWS, and DReGs); and reparameterized, score-function, sticking-the-landing, and DReG gradient estimators. NUTS and HMC use dual-averaging step-size adaptation and Welford mass-matrix adaptation.
• An analysis toolkit. Static introspection of compiled programs (per-step algebra, chain depth, intermediate shape, source mapping); algebra-aware, saturation-free initialization recipes that adapt to whichever value algebra a program is parameterized over; compile-time diagnostics flagging latents whose default initialization would saturate the active algebra.
• Diagnostics and model comparison. ArviZ ecosystem integration: posteriors from any inference method (NUTS, HMC, or SVI) export to ArviZ for trace plots, rank plots, ESS, and $\hat R$. PSIS-LOO (Pareto-smoothed importance-sampling leave-one-out cross-validation) for ranking competing models; posterior-predictive checks against user-defined test statistics; LOO-PIT for calibration.
• A mixed-effect model API. A brms-style formula frontend for mixed-effect regression compiles formulas to typed QVR programs through a bidirectional lens, with pandas / polars dataframes as the input surface and R-canonical conventions (orthogonal polynomials, R-style transforms in the formula evaluation namespace) as defaults. The emitted QVR is inspectable, so a formula-fitted model is a starting point you can hand-edit rather than a closed black box.
• Interactive tooling. qvr repl is a GHCi-style four-pane Textual TUI with live syntax highlighting, an environment browser, file-watcher reloads, a command palette, and meta-commands (:type, :info, :browse, :edit, :save, :watch, …). qvr-lsp implements LSP 3.17 features including hover, definition, references, document symbols, semantic tokens, completion, formatting, and live diagnostics for VS Code, Cursor, Zed, and Neovim. A Jupyter kernel (qvr-kernel install) drives the same elaborator from notebooks.

Quick start

pip install quivers

object Item : FinSet 100

program regression : Item -> Item [effects=[Sample, Score]]
    sample sigma  <- HalfNormal(1.0)
    sample beta_0 <- Normal(0.0, 5.0)
    sample beta_1 <- Normal(0.0, 2.0)
    let mu = beta_0 + beta_1 * x
    observe y : Item <- Normal(mu, sigma)
    return y

export regression

from quivers.dsl import loads
from quivers.inference import AutoNormalGuide, ELBO, SVI
import torch

program = loads(open("regression.qvr").read())
model   = program.morphism
guide   = AutoNormalGuide(model, observed_names={"y"})
optim   = torch.optim.Adam(guide.parameters(), lr=1e-2)
svi     = SVI(model, guide, optim, ELBO())
for _ in range(2000):
    svi.step(x_data, {"y": y_data})

The full walkthrough is in the tutorial.

Documentation

• Tutorial: the QVR DSL tutorial walks probabilistic-programming users from linear regression to inference-algorithm choice with PyMC, NumPyro, and Stan equivalents shown side-by-side, while the Python API tutorial covers the typed categorical surface.
• Examples gallery: 46 end-to-end models covering regression, latent-variable, state-space, language models, seq2seq, and formal grammars.
• Conceptual guides: feature-area deep dives.
• API reference: the typed Python surface.
• Denotational semantics: the meaning of every well-typed program in a $\mathcal{V}$-enriched symmetric monoidal closed category.

Installation

pip install quivers

From source:

git clone https://github.com/FACTSlab/quivers
cd quivers
pip install -e ".[dev]"

Requirements: Python 3.14+, PyTorch 2.0+, didactic 0.7.1+, panproto 0.58.0+, panproto-grammars-all 0.58.0+.

Optional extras:

pip install 'quivers[repl]'    # Textual TUI, prompt_toolkit, rich, ipykernel
pip install 'quivers[lsp]'     # pygls language server
pip install 'quivers[repl,lsp]'  # both

After installing [repl] you can drop into the interactive type explorer:

qvr repl path/to/model.qvr

After installing [lsp] you have qvr-lsp on your PATH; the vscode-qvr and zed-extension-qvr extensions auto-discover it.

Contributing

See CONTRIBUTING.md. Issues and pull requests welcome at github.com/FACTSlab/quivers.

Acknowledgments

This project was developed by Aaron Steven White at the University of Rochester with support from the National Science Foundation (NSF-BCS-2237175 CAREER: Logical Form Induction, NSF-BCS-2040831 Computational Modeling of the Internal Structure of Events). It was architected and implemented with the assistance of Claude Code.

License

MIT. See LICENSE.