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.65.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.65.0
File Size Uploaded Provenance Actions
quivers-0.65.0.tar.gz 14.5 MB With provenance Details for quivers-0.65.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for quivers 0.65.0
File Interpreter ABI Platform Actions
quivers-0.65.0-cp314-cp314-win_amd64.whl CPython 3.14 CPython 3.14 Windows x86-64 Details for quivers-0.65.0-cp314-cp314-win_amd64.whl
quivers-0.65.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.28+ x86-64, Linux glibc 2.5+ x86-64 Details for quivers-0.65.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
quivers-0.65.0-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details for quivers-0.65.0-cp314-cp314-macosx_11_0_arm64.whl

Total release size: 46.6 MB

Release files / quivers-0.65.0.tar.gz

Download URL quivers-0.65.0.tar.gz
Size 14.5 MB
Tags Source
SHA-256 checksum
How to use checksums
85a58de8b19f4e62ac2c894d5b0601b69aaf91c4ec76b2f15d6ba80785aa2542
BLAKE2b-256 checksum
How to use checksums
2f5fe0a0541a96de7d5278ec98be64862177687f156dedf3457a51fdc5ed625d
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 17, 2026.

Transparency log

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

Download URL quivers-0.65.0-cp314-cp314-win_amd64.whl
Size 11.3 MB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
9e265cbf8242f519a1bfc228def667b1cef5c43b3112b1cbb0734714d0faf411
BLAKE2b-256 checksum
How to use checksums
4949cb1414f70849b33efc0cd5632af41157eb2a27715ab902fd964f562ef2d4
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 17, 2026.

Transparency log

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

Download URL quivers-0.65.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Size 10.4 MB
Tags CPython 3.14 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64
SHA-256 checksum
How to use checksums
1afa2d438c86c6410a8fa4f269fa983ab61c35d31222a5e6075b08fb31f1d257
BLAKE2b-256 checksum
How to use checksums
31ecadad07c309d75ebc782bf8e692ac68667f43af94b97b721b2b0ad6173e54
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 17, 2026.

Transparency log

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

Download URL quivers-0.65.0-cp314-cp314-macosx_11_0_arm64.whl
Size 10.4 MB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
f2bb15da1323825b5d81f8bed348ef927c4de4cfe3208576406ead68991a3bc2
BLAKE2b-256 checksum
How to use checksums
eec3fb25fcb1fffdfcec30fa8bdc83ba0dd6e2c20cdb66abf4d13b1578fa7906
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 17, 2026.

Transparency log

Security for quivers 0.65.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.65.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 17, 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.65.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