quivers 0.3.0

Computational category theory as differentiable tensor programs

Quivers

Computational category theory as differentiable tensor programs.

Quivers is a Python library for building categorical and probabilistic models as differentiable PyTorch programs. It represents morphisms between finite sets as tensors valued in a quantale (a lattice with a monoidal product), then extends this to stochastic morphisms (Markov kernels), continuous distribution families, monadic probabilistic programs, and variational inference. A built-in functional DSL compiles .qvr specifications into trainable nn.Module instances.

Features

• Core categorical algebra: finite sets, product/coproduct constructions, and free monoids as objects; quantales (Boolean, product fuzzy, Łukasiewicz, Gödel, tropical) as enrichment algebras; $\mathcal{V}$-enriched relations as parametrized tensors with composition via quantale operations.
• Categorical structures: functors, natural transformations, adjunctions, monoidal categories, traced monoidal categories, base change between quantales.
• Enriched category theory: ends, coends, Kan extensions, weighted limits/colimits, profunctors, Yoneda embedding, Day convolution, optics (lenses, prisms, adapters, grates).
• Monadic constructs: monads, comonads, Kleisli/coKleisli categories, algebras, coalgebras, Eilenberg-Moore categories, distributive laws.
• Stochastic morphisms: the FinStoch category of Markov kernels; discretized distribution families (normal, logit-normal, beta, truncated normal); conditioning, mixing, and normalization transforms; the Giry monad; query functions (prob, marginal_prob, expectation).
• Continuous morphisms: 30+ parameterized conditional distribution families; continuous spaces (Euclidean, simplex, unit interval, positive reals); sampled composition; normalizing flows; discrete-continuous boundaries (discretize/embed).
• Monadic programs: probabilistic programs with draw, observe, and return statements; ancestral sampling; log-joint computation; hybrid discrete-continuous random variables.
• QVR DSL: a .qvr file format whose tree-sitter grammar is registered in panproto and whose AST nodes, value types, and resolution lenses are built on didactic Models; supports object/morphism declarations, program blocks, let bindings, type expressions, and grammar-based parsers (PCFG, CCG, Lambek, multimodal type-logical). Each .qvr program also extracts to a panproto Schema for diff/migrate workflows.
• Variational inference: execution traces, conditioning, automatic variational guides (normal, delta), ELBO computation, stochastic variational inference (SVI), posterior predictive sampling.

Installation

pip install quivers

Or install from source:

git clone https://github.com/FACTSlab/quivers
cd quivers
pip install -e .

For development (includes pytest, ruff, pyright):

pip install -e ".[dev]"

Quick Start

Discrete morphisms and composition

Define finite sets, create learnable and observed morphisms, and compose them:

from quivers import FinSet, morphism, observed, Program
import torch

X = FinSet("X", 3)
Y = FinSet("Y", 4)
Z = FinSet("Z", 2)

f = morphism(X, Y)                # learnable (sigmoid over raw params)
g = observed(Y, Z, torch.rand(4, 2))  # fixed tensor

h = f >> g                         # V-enriched composition: X -> Z
program = Program(h)
output = program()                 # shape (3, 2), values in [0, 1]

Composition uses the product fuzzy quantale by default: AND is multiplication, OR is noisy-OR ($1 - \prod(1 - x_i)$). The result is a differentiable tensor, trainable via program.parameters().

Stochastic morphisms

Work with Markov kernels in the FinStoch category:

from quivers import FinSet, stochastic, condition, prob

S = FinSet("S", 3)
O = FinSet("O", 5)

transition = stochastic(S, S)   # learnable row-stochastic matrix
emission = stochastic(S, O)     # learnable row-stochastic matrix

# condition on an observation
conditioned = condition(emission, obs_index=2)

# query probabilities
p = prob(transition, domain_idx=0, codomain_idx=1)

The QVR DSL

Write probabilistic programs in .qvr syntax and compile to nn.Module:

from quivers.dsl import loads

source = """
object Predictor : 1
object Response : 1

program regression : Predictor -> Response
    sigma <- HalfCauchy(2.0)
    beta_0 <- Normal(0.0, 5.0)
    beta_1 <- Normal(0.0, 2.0)
    x <- Normal(0.0, 1.0)
    let mu = beta_0 + beta_1 * x
    observe y ~ Normal(mu, sigma)
    return y

output regression
"""

model = loads(source)

Project Structure

src/quivers/
├── core/           # objects, quantales, morphisms, tensor ops
├── categorical/    # functors, natural transformations, adjunctions, monoidal, traced
├── monadic/        # monads, comonads, algebras, distributive laws
├── enriched/       # ends/coends, Kan extensions, profunctors, Yoneda, Day, optics
├── stochastic/     # Markov kernels, Giry monad, grammar parsers, chart algorithms
├── continuous/     # distribution families, spaces, flows, monadic programs
├── dsl/            # panproto-driven parser, AST (didactic Models),
│                   # compiler, resolution lenses, Program Theory
├── inference/      # traces, conditioning, guides, ELBO, SVI, predictive
├── program.py      # Program: wraps morphisms as nn.Module
└── giry.py         # GiryMonad, FinStoch

The tree-sitter grammar lives at the repo root under grammars/qvr/ and is vendored by panproto's panproto-grammars-all distribution.

Documentation

Full documentation: https://FACTSlab.github.io/quivers

• Installation
• Quickstart
• Conceptual Guides
• Tutorials
• Examples Gallery
• API Reference

Requirements

• Python 3.14+
• PyTorch 2.0+
• didactic 0.6.0+ (typed-data layer over panproto)
• panproto 0.45.0+ and panproto-grammars-all 0.45.0+ (QVR tree-sitter parser)

Contributing

See CONTRIBUTING.md for development setup, code style conventions, and the git workflow.

License

MIT. See LICENSE for details.