Skip to main content

Quivers

Typed, composable models with PyTorch.

CI Docs PyPI Python 3.14+ License: MIT

Quickstart · Tutorials · Examples · Language reference · Python API


Quivers is a Python library for constructing and fitting models from typed, composable components. It provides weighted relations, Markov kernels, and probabilistic programs backed by PyTorch tensors and automatic differentiation. The Python API exposes these components directly, while QVR, its typed functional probabilistic programming language, lets you describe models in source files that can be checked, executed, and translated to other languages.

The library draws on category theory: components have explicit input and output types, and composition connects compatible components. A choice of algebra specifies how weights combine, supporting probabilistic, Boolean, fuzzy, and optimization-based interpretations. Applications include Bayesian regression, sequence models, weighted parsing, and models of structured data.

Features

  • Composable models: build weighted relations and discrete or continuous probabilistic computations through the Python API or QVR.
  • Learning and inference: train differentiable components with PyTorch optimizers, or fit probabilistic programs with variational inference and Markov chain Monte Carlo (MCMC).
  • Statistical modeling: write mixed-effects regressions with formulas, work with dataframes, and inspect fits with posterior predictive checks, convergence diagnostics, and ArviZ integration.
  • Structured models: define weighted deduction systems, including parsers, and encoders and decoders for recursively structured data.
  • Language tools and interoperability: check QVR programs from the command line, use editor and notebook integrations, and transpile supported models to other probabilistic programming languages. See the target support matrix for supported features and restrictions.

Installation

Quivers requires Python 3.14 or later:

python -m pip install quivers

Install optional dependencies for the features you use:

python -m pip install 'quivers[formulas,diagnostics]'

Other extras include data for dataframe utilities, repl for the interactive shell and Jupyter kernel, lsp for the language server, and targets for Python target runtimes. The installation guide covers these extras, editor setup, and dependencies for individual targets.

Quick start

Compose a model in Python

A Markov kernel maps each input to a probability distribution over outputs. This example composes two learnable kernels through a shared hidden state:

from quivers import FinSet, Program, stochastic

inputs = FinSet(name="Input", cardinality=3)
hidden = FinSet(name="Hidden", cardinality=4)
outputs = FinSet(name="Output", cardinality=2)

encode = stochastic(inputs, hidden)
decode = stochastic(hidden, outputs)
model = Program(encode >> decode)

probabilities = model()
print(probabilities.shape)  # torch.Size([3, 2])

Each row is a distribution over the two outputs, with the hidden state summed out. Program is a PyTorch nn.Module, so its learnable parameters can be trained with PyTorch optimizers. The Python tutorials introduce weighted relations, composition, and learning.

Write a probabilistic program in QVR

QVR separates a model's generative assumptions from the inference algorithm. For instance, save this Bayesian linear regression as regression.qvr:

object Item : FinSet 100

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

export regression

The sample steps specify priors, and observe specifies the likelihood. The predictor x and observed responses y are provided as tensors when fitting the model. Check the file from the command line:

qvr check regression.qvr

Bind and fit the checked model in Python. External names and observation roles come from QVR:

from pathlib import Path
from quivers.modeling import Model, VariationalMethod

regression = Model(Path("regression.qvr").read_text())
fit = regression.fit(data, method=VariationalMethod(num_steps=2000, seed=7))
replicated = fit.predict(num_samples=100)

Here data maps x and y to floating tensors. To infer the row count, replace FinSet 100 with FinSet _. Typed parameters in the program header state the input contract; observe identifies the response. Static parameters go in brackets before the runtime value parameters, as in program model[Row : FinSet](x : Tensor[Real]([Row])) : Row -> Out. The parameter reference explains this convention across computations, programs, and indexed types. The checked fitting tutorial gives an executable example and shows input errors before inference.

The end-to-end quickstart shows how to supply data, fit this model, and summarize its posterior. For regression from a dataframe, the formula interface provides an alternative to writing QVR by hand.

Documentation

  • Getting started: installation, a first fit, and the core concepts.
  • Tutorials: separate tracks for QVR and the Python API.
  • Examples: complete models, including hierarchical models, state-space models, neural networks, and grammars.
  • Guides: inference, data and formulas, diagnostics, and transpilation.
  • Language reference, Python API, and semantics: syntax, public interfaces, and mathematical foundations.

Project status

Quivers is alpha software. The language and Python API may change; see the changelog and releases for details.

Contributing and support

Bug reports, feature requests, and documentation improvements are welcome through GitHub Issues. For a bug report, include a minimal Python or QVR example, the package version, and the full error message. See CONTRIBUTING.md for development setup, tests, and the contribution workflow.

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).

License

Quivers is released under the MIT License.

Metadata

Release files for quivers 0.67.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for quivers 0.67.0
File Size Uploaded Provenance Actions
quivers-0.67.0.tar.gz 16.8 MB With provenance Details for quivers-0.67.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for quivers 0.67.0
File Interpreter ABI Platform Actions
quivers-0.67.0-cp314-cp314-win_amd64.whl CPython 3.14 CPython 3.14 Windows x86-64 Details for quivers-0.67.0-cp314-cp314-win_amd64.whl
quivers-0.67.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.5+ x86-64, Linux glibc 2.28+ x86-64 Details for quivers-0.67.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
quivers-0.67.0-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details for quivers-0.67.0-cp314-cp314-macosx_11_0_arm64.whl

Total release size: 50.3 MB

Release files / quivers-0.67.0.tar.gz

Download URL quivers-0.67.0.tar.gz
Size 16.8 MB
Tags Source
SHA-256 checksum
How to use checksums
d8999a074ee17f4a4002165f40b5ae5095a46a46063c319953375b5087e49e1e
BLAKE2b-256 checksum
How to use checksums
5e2ee296976bfa2c3fbae6dbbb715e4986f03fe2869d1e0aab9b1af7f6e4f52e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / quivers-0.67.0-cp314-cp314-win_amd64.whl

Download URL quivers-0.67.0-cp314-cp314-win_amd64.whl
Size 11.8 MB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
14bcf368accc5410a032361cf168d5803641e815c9c24fa410de21204ba75a21
BLAKE2b-256 checksum
How to use checksums
d1a631cc112e57df0da9d2f8017b6b3b6ab2751d950b9d73056b2a49f5f809b0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / quivers-0.67.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Download URL quivers-0.67.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Size 10.9 MB
Tags CPython 3.14 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64
SHA-256 checksum
How to use checksums
7055119529705292970086ed1512921858fc0555d91d44e2cb1fb08779d62431
BLAKE2b-256 checksum
How to use checksums
3498f9874fb0aac877c74bbb5089a04ed12202ed120bce5859e2e0698d88f183
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / quivers-0.67.0-cp314-cp314-macosx_11_0_arm64.whl

Download URL quivers-0.67.0-cp314-cp314-macosx_11_0_arm64.whl
Size 10.9 MB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
6666bfc267f128549d9067bb8f285327fe4013214b0ae01df901ac4c0eca707a
BLAKE2b-256 checksum
How to use checksums
c228213870070e8b8e0c99b76fb95e523596c1f647f89466cf89ce7088fed9a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for quivers 0.67.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 4 files in this release have been uploaded with provenance metadata.

Select from 4 files

Attestation for quivers-0.67.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.67.0 This release

4 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page