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.66.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.66.0
File Size Uploaded Provenance Actions
quivers-0.66.0.tar.gz 16.7 MB With provenance Details for quivers-0.66.0.tar.gz

Built distributions (wheels)

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

Total release size: 50.2 MB

Release files / quivers-0.66.0.tar.gz

Download URL quivers-0.66.0.tar.gz
Size 16.7 MB
Tags Source
SHA-256 checksum
How to use checksums
0bdd06dce01f14b8f6a2eeead54049d42f863375d652c4333a42323f9883b492
BLAKE2b-256 checksum
How to use checksums
5e0da61ac96a07b00b7efc539f1939a855613a8084d8dbf30131b6176279226c
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.66.0-cp314-cp314-win_amd64.whl

Download URL quivers-0.66.0-cp314-cp314-win_amd64.whl
Size 11.8 MB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
8c33ce1ba380bf4be832bcd74ef5fec2ab476d6cac8cf4bc4d6ca822c5b12fa5
BLAKE2b-256 checksum
How to use checksums
dae0adedfc4bcb510518fb1c260e8b6cf0d47fde3483fda0dfacfbaf6bf9b96c
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.66.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Download URL quivers-0.66.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Size 10.8 MB
Tags CPython 3.14 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64
SHA-256 checksum
How to use checksums
fd4feb6e408de5211172a0bfc99bbf0530d28496af7fbf0c8bfaf2015d26196b
BLAKE2b-256 checksum
How to use checksums
ed0390f6eecb6153b41e9e20f5ab836a10414e6c58d523c73a3ff1e609335a1d
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.66.0-cp314-cp314-macosx_11_0_arm64.whl

Download URL quivers-0.66.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
2a13aa4ea927b2bfb3a64d48a5c2e03ea572edfd37737e41d26c34a327a15c38
BLAKE2b-256 checksum
How to use checksums
d1084f03a0a27fe39a37aa16d218755c0831b8f2096c6dda7279bc0867fac94a
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.66.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.66.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.66.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