Metadata-Version: 2.4
Name: quivers
Version: 0.4.0
Summary: Computational category theory as differentiable tensor programs
Project-URL: Homepage, https://github.com/FACTSlab/quivers
Project-URL: Repository, https://github.com/FACTSlab/quivers
Project-URL: Documentation, https://FACTSlab.github.io/quivers
Project-URL: Changelog, https://github.com/FACTSlab/quivers/blob/main/CHANGELOG.md
Author: Aaron Steven White
License: MIT
License-File: LICENSE
Keywords: category-theory,enriched-categories,probabilistic-programming,pytorch,quantale,tensor
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.14
Requires-Dist: didactic>=0.7.1
Requires-Dist: panproto-grammars-all>=0.47.0
Requires-Dist: panproto>=0.47.0
Requires-Dist: pygments>=2.10
Requires-Dist: torch>=2.0
Requires-Dist: tree-sitter>=0.21
Provides-Extra: dev
Requires-Dist: numpy; extra == 'dev'
Requires-Dist: pyright; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs; extra == 'docs'
Requires-Dist: mkdocs-terminal; extra == 'docs'
Requires-Dist: mkdocstrings[python]; extra == 'docs'
Requires-Dist: pygments; extra == 'docs'
Requires-Dist: pymdown-extensions; extra == 'docs'
Description-Content-Type: text/markdown

# Quivers

[![CI](https://github.com/FACTSlab/quivers/actions/workflows/ci.yml/badge.svg)](https://github.com/FACTSlab/quivers/actions/workflows/ci.yml)
[![Docs](https://github.com/FACTSlab/quivers/actions/workflows/docs.yml/badge.svg)](https://FACTSlab.github.io/quivers)
[![PyPI](https://img.shields.io/pypi/v/quivers)](https://pypi.org/project/quivers/)
[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

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 a single Kleisli-bind syntax (`v <- F(args)`), scored binds (`observe v <- F(args)`), scoped marginalisation, and `!`-prefixed effect signatures (`! Sample, Score, Marginal, Pure`); ancestral sampling; log-joint computation; hybrid discrete-continuous random variables.
- **QVR DSL**: a `.qvr` file format whose tree-sitter grammar is registered in [panproto](https://panproto.dev) and whose AST nodes, value types, and resolution lenses are built on [didactic](https://panproto.dev/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.
- **Weighted-deduction framework**: a single agenda-engine runtime parameterised by item algebra, arity-n rules, semiring, agenda discipline, and priority function subsumes CKY, Earley, Viterbi, semi-naïve Datalog, A* parsing, Knuth's algorithm, and MLTT proof search. Surface `deduction { … }` blocks declare the seven canonical parameters; charts are first-class differentiable values supporting `weight(item)`, `enumerate(pattern)`, `goal_weight()` operations whose gradients flow back through the agenda's semiring operations. Stdlib ships CCG, Lambek, STLC, MLTT, Datalog, Dijkstra, HMM, ViterbiHMM, EditDistance ready-to-use.
- **Structural compression**: a uniform algebraic interface for compressing arbitrary structured objects (sequences, trees, graphs, parse charts, typed lambda terms with binders) to fixed-length vectors and decoding them back under a learned distribution. `signature { … }` blocks declare multi-sorted constructor algebras with typed binders under a de-Bruijn discipline; `encoder` blocks declare F-algebra homomorphisms `T_Σ → Vec_D` with sequence-recurrent and attention sugar; `decoder` blocks declare Kleisli coalgebras `Vec_D → Kern(T_Σ)` with `sample` and `log_prob`; `loss` declarations attach weighted scalar objectives at any program / deduction / encoder / decoder / rule / chart site. This realises transformers, tree-LSTMs, graph-NNs, autoregressive LMs, variational autoencoders, and the vector-inside-outside parser of Le-Zuidema / Drozdov / Kim as instances of one F-algebra / F-coalgebra pattern. Stdlib ships `Seq[A]` / `Tree[L, B]` / `Graph[V, E]` shapes with canonical RNN / Transformer / TreeLSTM / GNN / autoregressive-decoder implementations.

## Installation

```bash
pip install quivers
```

Or install from source:

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

For development (includes pytest, ruff, pyright):

```bash
pip install -e ".[dev]"
```

## Quick Start

### Discrete morphisms and composition

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

```python
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:

```python
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`:

```python
from quivers.dsl import loads

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

program regression : Predictor -> Response ! Sample, Score
    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

export regression
"""

model = loads(source)
```

## Project Structure

```text
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](https://FACTSlab.github.io/quivers)

- [Installation](https://FACTSlab.github.io/quivers/getting-started/installation/)
- [Quickstart](https://FACTSlab.github.io/quivers/getting-started/quickstart/)
- [Conceptual Guides](https://FACTSlab.github.io/quivers/guides/)
- [Tutorials](https://FACTSlab.github.io/quivers/tutorials/)
- [Examples Gallery](https://FACTSlab.github.io/quivers/examples/)
- [API Reference](https://FACTSlab.github.io/quivers/api/)

## 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](CONTRIBUTING.md) for development setup, code style conventions, and the git workflow.

## License

MIT. See [LICENSE](LICENSE) for details.
