Metadata-Version: 2.5
Name: quivers
Version: 0.25.1
Summary: A typed functional probabilistic programming language with a PyTorch runtime and eleven transpilation targets.
Project-URL: Homepage, https://quivers.dev
Project-URL: Repository, https://github.com/quivers-dev/quivers
Project-URL: Documentation, https://quivers.dev
Project-URL: Changelog, https://github.com/quivers-dev/quivers/blob/main/CHANGELOG.md
Author: Aaron Steven White
License: MIT
License-File: LICENSE
Keywords: algebra,category-theory,enriched-categories,probabilistic-programming,pytorch,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.17.1
Requires-Dist: panproto-grammars-all>=0.74.4
Requires-Dist: panproto>=0.74.4
Requires-Dist: pygments>=2.10
Requires-Dist: torch>=2.0
Requires-Dist: tree-sitter>=0.21
Provides-Extra: data
Requires-Dist: narwhals>=2.21; extra == 'data'
Requires-Dist: scikit-learn>=1.6; extra == 'data'
Provides-Extra: dev
Requires-Dist: numpy; extra == 'dev'
Requires-Dist: pandas; extra == 'dev'
Requires-Dist: polars; extra == 'dev'
Requires-Dist: pyarrow; extra == 'dev'
Requires-Dist: pyright; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-split>=0.9; extra == 'dev'
Requires-Dist: pytest-timeout; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.15; extra == 'dev'
Provides-Extra: diagnostics
Requires-Dist: arviz>=1.0; extra == 'diagnostics'
Requires-Dist: netcdf4>=1.7; extra == 'diagnostics'
Requires-Dist: xarray>=2025.1; extra == 'diagnostics'
Provides-Extra: docs
Requires-Dist: mkdocs-material<10,>=9; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]; extra == 'docs'
Requires-Dist: pygments; extra == 'docs'
Requires-Dist: pymdown-extensions; extra == 'docs'
Provides-Extra: formulas
Requires-Dist: arviz>=1.0; extra == 'formulas'
Requires-Dist: formulae>=0.6; extra == 'formulas'
Requires-Dist: narwhals>=2.21; extra == 'formulas'
Requires-Dist: netcdf4>=1.7; extra == 'formulas'
Requires-Dist: scikit-learn>=1.6; extra == 'formulas'
Requires-Dist: xarray>=2025.1; extra == 'formulas'
Provides-Extra: lsp
Requires-Dist: lsprotocol>=2024.0.0; extra == 'lsp'
Requires-Dist: pygls>=2.0; extra == 'lsp'
Provides-Extra: repl
Requires-Dist: ipykernel>=6.29; extra == 'repl'
Requires-Dist: jupyter-client>=8.6; extra == 'repl'
Requires-Dist: prompt-toolkit>=3.0; extra == 'repl'
Requires-Dist: rich>=13.7; extra == 'repl'
Requires-Dist: textual>=0.83; extra == 'repl'
Provides-Extra: targets
Requires-Dist: pymc>=5.20; extra == 'targets'
Requires-Dist: pyro-ppl>=1.9; extra == 'targets'
Requires-Dist: scipy>=1.14; extra == 'targets'
Description-Content-Type: text/markdown

<h1 align="center">Quivers</h1>

<p align="center">
  <em>A typed functional probabilistic programming language for PyTorch.</em>
</p>

<p align="center">
  <a href="https://github.com/quivers-dev/quivers/actions/workflows/ci.yml"><img src="https://github.com/quivers-dev/quivers/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://quivers.dev"><img src="https://github.com/quivers-dev/quivers/actions/workflows/docs.yml/badge.svg" alt="Docs"></a>
  <a href="https://pypi.org/project/quivers/"><img src="https://img.shields.io/pypi/v/quivers" alt="PyPI"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.14%2B-blue" alt="Python 3.14+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"></a>
</p>

<p align="center">
  <a href="https://quivers.dev/getting-started/quickstart/"><strong>Quickstart</strong></a>
  ·
  <a href="https://quivers.dev/tutorials/"><strong>Tutorials</strong></a>
  ·
  <a href="https://quivers.dev/examples/"><strong>Examples</strong></a>
  ·
  <a href="https://quivers.dev/reference/qvr/"><strong>Language reference</strong></a>
  ·
  <a href="https://quivers.dev/api/"><strong>Python API</strong></a>
</p>

---

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:

```bash
python -m pip install quivers
```

Optional features are distributed as extras:

```bash
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](https://quivers.dev/getting-started/installation/)
covers editor setup and target-specific dependencies.

## Quick start

This QVR file defines a stochastic GRU language model:

<!-- GitHub Linguist fallback: QVR currently uses the R lexer. -->
```R
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(loc=reset_hidden, scale=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:

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

The [QVR tutorial](https://quivers.dev/tutorials/qvr/01-first-model/)
develops the language and inference workflow from a first model. The
[examples gallery](https://quivers.dev/examples/) 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:

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

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

```python
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](https://github.com/quivers-dev/quivers/tree/main/editors/vscode-qvr)
and [Zed](https://github.com/quivers-dev/quivers/tree/main/editors/zed-extension-qvr).

## How the pieces fit together

```mermaid
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
```

## Documentation

| Resource | Use it for |
| --- | --- |
| [Getting started](https://quivers.dev/getting-started/quickstart/) | Installation and a first working model. |
| [QVR tutorials](https://quivers.dev/tutorials/qvr/01-first-model/) | Guided lessons from core syntax through indexed effects, handlers, inference, and release checks. |
| [Python tutorials](https://quivers.dev/tutorials/python/01-first-quiver/) | The typed categorical library and its composition rules. |
| [Examples](https://quivers.dev/examples/) | Complete models organized by statistical family and language feature. |
| [Language reference](https://quivers.dev/reference/qvr/) | QVR syntax, types, effects, execution, and tooling behavior. |
| [Guides](https://quivers.dev/guides/) | Inference, formulas and data, transpilation, the REPL, the LSP, and extension points. |
| [Python API](https://quivers.dev/api/) | Public classes, functions, and modules. |
| [Semantics](https://quivers.dev/semantics/) | Formal denotations for well-typed programs. |
| [QIEC internals](https://quivers.dev/developer/qiec/) | The stable core, serialization format, and runtime ABI. |

## Project status

Quivers is alpha software. Language and API changes are recorded in the
[changelog](CHANGELOG.md), and published releases are available from
[PyPI](https://pypi.org/project/quivers/) and
[GitHub Releases](https://github.com/quivers-dev/quivers/releases).

## Support

Use [GitHub Issues](https://github.com/quivers-dev/quivers/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](CONTRIBUTING.md) for the development setup, tests,
contribution workflow, and commit conventions.

## Acknowledgments

This project was developed by [Aaron Steven White](https://aaronstevenwhite.io/)
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](LICENSE).
