Quivers

A typed functional probabilistic programming language for PyTorch.

Quickstart · Tutorials · Examples · Language reference · Python API

---

Quivers is a typed functional probabilistic programming language and compiler with a PyTorch runtime. It includes the QVR source language, a compiler to the Quivers Indexed Effect Core (QIEC), inference and diagnostics, a mixed-effects formula interface, eleven transpilers, and editor and notebook tooling. Its Python API also exposes categorical, deduction, and structural modeling primitives.

What Quivers includes

Area	What it provides
QVR language and compiler	Typed probabilistic programs with indexed families, lexical effect instances, row-polymorphic computations, and authored handlers. The language includes discrete marginalization and collection operators such as map, fold, and traverse.
Execution and inference	A PyTorch runtime with automatic differentiation and more than forty distribution families. Inference includes SVI with automatic and flow-based guides, HMC, NUTS, and hybrid samplers.
Formulas and data	A brms-style mixed-effects interface for pandas, Polars, and other Narwhals-compatible dataframes. The generated QVR can be saved and edited.
Diagnostics and analysis	ArviZ export, ESS and R-hat, PSIS-LOO, posterior-predictive checks, LOO-PIT, static program summaries, source maps, and algebra-aware initialization advice.
Composition and structure	A typed V-enriched categorical API and algebra-parametric semantics. QVR adds weighted chart deduction and declarations for structural signatures, encoders, decoders, and losses.
Transpilation	Capability-checked output for BUGS, Church, Edward2, Gen, JAGS, NumPyro, PyMC, Pyro, Stan, Turing, and WebPPL. Unsupported target features are reported before code generation.
Developer tooling	A command-line interface, interactive REPL, Jupyter kernel, language server, Pygments and tree-sitter grammars, and first-party extensions for VS Code, Cursor, and Zed.

Installation

Quivers requires Python 3.14 or later. Install the base package with:

python -m pip install quivers

Optional features are distributed as extras:

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

The user-facing extras are formulas, data, diagnostics, repl, lsp, and targets. The dev and docs extras are for work on Quivers itself. Some transpilation targets require their own runtime or compiler. The installation guide covers editor setup and target-specific dependencies.

Quick start

This QVR file defines a stochastic GRU language model:

object Token : FinSet 256
object Resp : FinSet 32
object Embedded : Real 64
object Hidden : Real 128

morphism tok_embed : Token -> Embedded [role=embed]
morphism gate_z, gate_r : Embedded * Hidden -> Hidden ~ LogitNormal
morphism lm_head : Hidden -> Token ~ Categorical

program gru_cell(x_t, h_prev) : Embedded * Hidden -> Hidden
    sample z <- gate_z(x_t, h_prev)
    sample r <- gate_r(x_t, h_prev)

    let reset_hidden = r * h_prev

    sample h_cand <- Normal(reset_hidden, 0.5)

    let z_complement = 1.0 - z
    let h_new = z_complement * h_prev + z * h_cand
    return h_new

define backbone = tok_embed >> scan(gru_cell)

program gru_lm : Token -> Token
    sample h <- backbone

    observe next_token : Resp <- lm_head(h)
    return next_token

export gru_lm

Download the example and check it:

curl -LO https://raw.githubusercontent.com/FACTSlab/quivers/main/docs/examples/source/gru_lm.qvr
qvr check gru_lm.qvr

The QVR tutorial develops the language and inference workflow from a first model. The examples gallery covers hierarchical and state-space models, mixture models, neural language models, formal grammars, and structural autoencoders.

Typical workflows

Check, inspect, and run a QVR file from the command line:

qvr check model.qvr
qvr run model.qvr --list
qvr run model.qvr my_program

Check whether a model is supported by a target before emitting code:

qvr check --target pyro model.qvr
qvr transpile --to pyro model.qvr -o model.py
qvr transpile --to-all model.qvr --out-dir generated

Fit a mixed-effects model from a dataframe, then save the QVR produced by the formula compiler:

from quivers.formulas import fit

result = fit(
    "response ~ predictor + (1 + predictor | participant)",
    data=df,
    family="gaussian",
    method="nuts",
)
result.dump_qvr("model.qvr")

For language work, qvr repl opens the interactive environment, qvr-kernel install registers the Jupyter kernel, and qvr-lsp starts the language server. The repository contains extensions for VS Code and Cursor and Zed.

How the pieces fit together

flowchart LR
    Formula["Formulas + data"] --> QVR["QVR programs"]
    QVR --> Check["Parser + type/effect checker"]
    Check --> QIEC["Typed executable QIEC"]
    QIEC --> Ref["Reference execution"]
    QIEC --> Tools["Analysis + editor diagnostics"]
    QIEC --> Targets["11 target transpilers"]
    QVR --> Torch["PyTorch program"]
    Torch --> Infer["Inference + diagnostics"]
    QVR --> API["Categorical + structural Python APIs"]
    API --> Torch

Loading

Documentation

Resource	Use it for
Getting started	Installation and a first working model.
QVR tutorials	Guided lessons from core syntax through indexed effects, handlers, inference, and release checks.
Python tutorials	The typed categorical library and its composition rules.
Examples	Complete models organized by statistical family and language feature.
Language reference	QVR syntax, types, effects, execution, and tooling behavior.
Guides	Inference, formulas and data, transpilation, the REPL, the LSP, and extension points.
Python API	Public classes, functions, and modules.
Semantics	Formal denotations for well-typed programs.
QIEC internals	The stable core, serialization format, and runtime ABI.

Project status

Quivers is alpha software. Language and API changes are recorded in the changelog, and published releases are available from PyPI and GitHub Releases.

Support

Use GitHub Issues for bug reports, feature requests, and documentation problems. Include a minimal .qvr file, the command you ran, and the complete diagnostic when reporting compiler or runtime behavior.

Contributing

See CONTRIBUTING.md for the development setup, tests, contribution workflow, and commit conventions.

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

Quivers is released under the MIT License.