Architecture

The quivers library is organized into eight subpackages, each providing a layer of categorical structure. This document describes the package hierarchy, dependencies, and key abstractions in each module.

Package Structure

quivers/
├── core/              # foundational types and operations
├── categorical/       # functors, transformations, adjunctions, monoidal
├── monadic/           # monads, comonads, algebras, distributive laws
├── enriched/          # ends/coends, Kan, weighted limits, profunctors, Yoneda, optics
├── stochastic/        # FinStoch (Markov kernels), families, conditioning, Giry monad
├── continuous/        # parameterized families, boundaries, flows, monadic programs
├── dsl/               # panproto-driven parser, didactic AST nodes,
│                      # compiler, resolution lenses, Program Theory
├── inference/         # trace-based conditioning, variational guides, SVI
├── program.py         # nn.Module wrapper for morphisms
└── giry.py            # re-exports GiryMonad and FinStoch from stochastic.giry

The QVR tree-sitter grammar lives at the repo root under grammars/qvr/; it is vendored by panproto's panproto-grammars-all distribution and consumed at runtime by quivers' parser.

Module Descriptions

core/

Foundational categorical types and operations. Defines the objects and morphisms that all other modules build on.

categorical/

Categorical structures built from objects and morphisms.

monadic/

Monadic structures: monads, comonads, and their algebras.

enriched/

Enriched category theory: the calculus of \(\mathcal{V}\)-valued hom-functors.

stochastic/

Stochastic morphisms and the category FinStoch of Markov kernels on finite sets.

continuous/

Continuous and hybrid discrete-continuous morphisms and monadic programs.

dsl/

Domain-specific language for quiver expressions in .qvr files. Parsing is delegated to panproto via the qvr tree-sitter grammar (located at grammars/qvr/ in the repo, vendored by panproto-grammars-all); quivers does not run a hand-written lexer.

Top-level DSL API: parse(), parse_file(), loads(), load(), Compiler, Module, QVR_PROGRAM_PROTOCOL, extract_program_schema(), plus exceptions ParseError, CompileError.

inference/

Variational inference for posterior estimation in monadic programs.

Root-level modules

Dependency Graph

The package has a layered dependency structure:

┌─ core (no quivers dependencies)
│
├─ categorical (depends on: core)
│
├─ monadic (depends on: core)
│
├─ enriched (depends on: core, categorical)
│
├─ stochastic (depends on: core, monadic)
│
├─ continuous (depends on: core, categorical, monadic, stochastic)
│
├─ dsl (depends on: core, categorical, monadic, stochastic, continuous)
│
└─ inference (depends on: core, categorical, stochastic, continuous)

program.py (depends on: core, continuous)
giry.py (depends on: stochastic)

Dependency Hierarchy

  1. core: foundational (no internal dependencies)
  2. categorical, monadic: build on core
  3. enriched: builds on categorical
  4. stochastic: builds on core and monadic
  5. continuous: builds on core, categorical, monadic, and stochastic
  6. dsl: synthesizes core, categorical, monadic, stochastic, continuous
  7. inference: builds on core, categorical, stochastic, continuous

This layering ensures that users can work at the level of abstraction appropriate to their task: core algebra only, categorical structures, probabilistic computations, or the full DSL.

Design Principles