quivers 0.1.0__tar.gz

quivers-0.1.0/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add:*)",
+      "Bash(source /Users/awhite48/Projects/quivers/.venv/bin/activate)",
+      "Bash(ruff check:*)",
+      "Bash(python -m pytest tests/ -x -q)",
+      "Bash(source .venv/bin/activate)",
+      "Bash(for f:*)",
+      "Bash(do echo:*)",
+      "Bash(pyright /Users/awhite48/Projects/quivers/src/quivers/stochastic/$f)",
+      "Bash(done)",
+      "Bash(python3 -c \":*)",
+      "Bash(ruff format:*)"
+    ]
+  }
+}

quivers-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install -e ".[dev]"
+      - run: pyright src/quivers
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest tests/ -x -q

quivers-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[docs]"
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

quivers-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+pytest-cache-files-*/
+.coverage
+htmlcov/
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+
+# Documentation build
+site/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

quivers-0.1.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to the quivers library are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-26
+
+### Added
+
+#### Core Categorical Algebra
+
+- Fundamental category types and morphisms
+- Object declarations and morphism composition
+- Support for latent and observed morphisms
+- Basic categorical operations and abstractions
+
+#### Stochastic Morphisms
+
+- Stochastic morphism declarations and semantics
+- Integration with probability theory
+- Support for morphism composition in stochastic settings
+
+#### Continuous Distributions (30+ Families)
+
+- Normal distribution and variants (LogitNormal, TruncatedNormal)
+- Beta, Dirichlet for probability simplices
+- Exponential family: Exponential, Gamma, Chi2
+- Heavy-tailed: Cauchy, StudentT, Pareto
+- Bounded: Uniform, Kumaraswamy
+- Half-variants: HalfCauchy, HalfNormal
+- Transformed: LogNormal, Gumbel, Laplace, Weibull
+- Multivariate: MultivariateNormal, LowRankMVN, Wishart
+- Bernoulli variants: Bernoulli, ContinuousBernoulli, RelaxedBernoulli
+- Advanced: RelaxedOneHotCategorical, FisherSnedecor
+- Normalized flows: Flow
+- Categorical and discrete approximations
+
+#### Monadic Programs
+
+- Draw statements for sampling from morphisms
+- Observe statements for conditioning and likelihood
+- Return statements with optional labeled outputs
+- Variable binding and destructuring in patterns
+- Program parameters and composition
+
+#### QVR DSL
+
+- Complete lexer with token recognition for all language constructs
+- Recursive descent parser with full grammar support
+- Abstract syntax tree (AST) node definitions
+- Program block execution with proper scoping
+- Let bindings for expression computation
+- Built-in let functions: sigmoid, exp, log, abs, softplus
+- Comment support (#)
+- Type expressions: products (*), coproducts (+)
+- Expression operators: composition (>>), tensor product (@), marginalization
+- Indentation-aware program body parsing
+- Specialized handling for draw/observe arguments
+
+#### Variational Inference Layer
+
+- Inference interface for probabilistic programs
+- Support for approximate posterior computation
+- Integration with continuous distribution families

quivers-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,270 @@
+# Contributing to Quivers
+
+This guide covers setting up a development environment, understanding the project structure, and contributing code to the quivers library.
+
+## Development Environment Setup
+
+### Prerequisites
+
+- Python 3.12 or later
+- pip or conda
+- git
+
+### Installation
+
+Clone the repository and install in development mode:
+
+```bash
+git clone https://github.com/FACTSlab/quivers
+cd quivers
+pip install -e ".[dev]"
+```
+
+This installs the package in editable mode along with development dependencies.
+
+### Running Tests
+
+Run the full test suite:
+
+```bash
+python -m pytest tests/ -x
+```
+
+The `-x` flag stops at the first failure, which is useful for iterative development. For more options:
+
+```bash
+python -m pytest tests/ -v                  # verbose
+python -m pytest tests/ -k test_name        # run specific tests
+python -m pytest tests/path/to/test_file.py # run specific file
+```
+
+## Project Structure
+
+```
+quivers/
+├── docs/                          # Documentation
+│   ├── api/                       # API reference
+│   ├── developer/                 # Developer documentation
+│   ├── getting-started/           # User guides
+│   ├── guides/                    # Long-form guides
+│   └── tutorials/                 # Tutorials
+├── src/quivers/                   # Main package
+│   ├── __init__.py
+│   ├── categorical/               # Categorical algebra
+│   ├── continuous/                # Continuous distributions (30+ families)
+│   ├── core/                      # Core types and utilities
+│   ├── dsl/                       # QVR DSL (lexer, parser, compiler)
+│   ├── enriched/                  # Enriched categories
+│   ├── inference/                 # Variational inference
+│   ├── monadic/                   # Monadic programs (draw, observe, return)
+│   └── stochastic/                # Stochastic morphisms
+├── tests/                         # Test suite (mirrors src structure)
+├── pyproject.toml                 # Package metadata
+└── mkdocs.yml                     # Documentation config
+```
+
+## Code Style Conventions
+
+### Type Hints
+
+Include type hints in all function signatures. Use modern Python 3.12+ syntax:
+
+- Use `dict[K, V]` not `Dict[K, V]`
+- Use `list[T]` not `List[T]`
+- Use `X | None` not `Optional[X]`
+- Use `tuple[T, ...]` for variable-length tuples
+
+```python
+def process_data(values: list[float], multiplier: float = 1.0) -> dict[str, float]:
+    """Process numeric data."""
+    return {str(i): v * multiplier for i, v in enumerate(values)}
+```
+
+Do not use type hints in function bodies or variable assignments unless necessary for clarity in complex code sections.
+
+### Docstrings
+
+Use numpy-style docstrings for all public modules, classes, and functions:
+
+```python
+def calculate_entropy(probabilities: list[float]) -> float:
+    """Calculate Shannon entropy of a probability distribution.
+
+    Parameters
+    ----------
+    probabilities : list[float]
+        Probabilities that sum to 1.0.
+
+    Returns
+    -------
+    float
+        Shannon entropy in nats.
+
+    Raises
+    ------
+    ValueError
+        If probabilities do not sum to approximately 1.0.
+
+    Examples
+    --------
+    >>> entropy([0.5, 0.5])
+    0.6931471805599453
+    """
+```
+
+### Comments
+
+Use lowercase inline comments to clarify non-obvious logic:
+
+```python
+# compute sufficient statistics for exponential family
+sufficient_stats = compute_stats(data)
+
+# handle edge case where prior is uniform
+if prior_strength == 0:
+    posterior = likelihood
+```
+
+Avoid stating the obvious. Comments should explain "why," not "what."
+
+### Python Version and Modern Features
+
+Maintain compatibility with Python 3.12 and later. Use modern features:
+
+- Type union syntax: `X | None` instead of `Union[X, None]`
+- Positional-only parameters: `def func(a, /, b)`
+
+## The DSL Pipeline
+
+The QVR DSL processes `.qvr` files through these stages:
+
+### 1. Tokenization (tokens.py)
+
+The lexer breaks source text into tokens. Each token carries type, value, line, and column:
+
+```python
+class TokenType(Enum):
+    QUANTALE = auto()
+    OBJECT = auto()
+    PROGRAM = auto()
+    DRAW = auto()
+    OBSERVE = auto()
+    ...
+```
+
+Keywords like `program`, `draw`, `observe`, `return` map to specific token types. Operators (`->`, `>>`, `@`, `~`) and punctuation are also tokenized.
+
+### 2. Parsing (parser.py)
+
+The recursive descent parser transforms the token stream into an Abstract Syntax Tree (AST). The grammar is documented in the module docstring:
+
+- **Statements**: quantale, object, morphism, space, continuous, stochastic, discretize, embed, program, let, output declarations
+- **Programs**: blocks with draw/observe steps and return statements
+- **Expressions**: identity, composition (>>), tensor product (@), marginalization
+- **Types**: products (*), coproducts (+)
+
+### 3. AST Nodes (ast_nodes.py)
+
+Each syntax construct maps to a dataclass:
+
+```python
+@dataclass
+class ProgramDecl(Statement):
+    name: str
+    params: tuple[str, ...] | None
+    domain: TypeExpr
+    codomain: TypeExpr
+    draws: tuple[DrawStep | LetStep, ...]
+    return_vars: tuple[str, ...]
+    return_labels: tuple[str, ...] | None
+```
+
+### 4. Compilation (compiler.py)
+
+The compiler walks the AST and builds executable programs:
+
+- Builds up a scope mapping variable names to values
+- Executes draw steps by sampling from morphism distributions
+- Executes observe steps by conditioning
+- Processes let steps to bind computed expressions
+- Returns final values according to the return statement
+
+## Adding a New Distribution Family
+
+To add a new continuous distribution family:
+
+### 1. Define the Distribution Class
+
+Create a new class in `src/quivers/continuous/families.py` or a new module:
+
+```python
+from dataclasses import dataclass
+import torch
+
+@dataclass(frozen=True)
+class MyDistribution:
+    """My custom probability distribution.
+
+    Parameters
+    ----------
+    param1 : float
+        First parameter.
+    param2 : float
+        Second parameter.
+    """
+    param1: float
+    param2: float
+
+    def sample(self, size: int) -> torch.Tensor:
+        """Draw samples from this distribution."""
+        pass
+
+    def log_prob(self, value: torch.Tensor) -> torch.Tensor:
+        """Compute log probability density."""
+        pass
+```
+
+### 2. Register in the DSL
+
+Add the distribution to the DSL's family registry so it can be used in `.qvr` files.
+
+### 3. Add Tests
+
+Create test cases in `tests/continuous/`:
+
+```python
+def test_mydistribution_sample_shape():
+    dist = MyDistribution(param1=1.0, param2=2.0)
+    samples = dist.sample(1000)
+    assert samples.shape == (1000,)
+
+def test_mydistribution_log_prob():
+    dist = MyDistribution(param1=1.0, param2=2.0)
+    value = torch.tensor([0.5])
+    log_prob = dist.log_prob(value)
+    assert log_prob.shape == ()
+```
+
+### 4. Update Documentation
+
+Add the distribution to the API reference with usage examples and parameter descriptions.
+
+## Testing Philosophy
+
+- Write tests for all public APIs
+- Test both happy paths and edge cases
+- Use pytest fixtures for common setup
+- Organize tests to mirror the source tree structure
+- Aim for clear, descriptive test names: `test_<function>_<condition>_<expected>`
+
+## Git Workflow
+
+1. Create a feature branch: `git checkout -b feature/description`
+2. Make focused commits with clear messages
+3. Push to your fork and open a pull request
+4. Ensure all tests pass before requesting review
+5. Respond to feedback and update as needed
+
+## Questions and Issues
+
+Open an issue on the [GitHub repository](https://github.com/FACTSlab/quivers) for bugs, feature requests, or questions.

quivers-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Steven White
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quivers-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: quivers
+Version: 0.1.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.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.13
+Requires-Dist: torch>=2.0
+Provides-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-cinder; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; 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.13+](https://img.shields.io/badge/python-3.13%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 draw, observe, and return statements; ancestral sampling; log-joint computation; hybrid discrete-continuous random variables.
+- **QVR DSL**: a `.qvr` file format with lexer, recursive descent parser, AST, and compiler; supports object/morphism declarations, program blocks, let bindings, type expressions, and grammar-based parsers (PCFG, CCG, Lambek, multimodal type-logical).
+- **Variational inference**: execution traces, conditioning, automatic variational guides (normal, delta), ELBO computation, stochastic variational inference (SVI), posterior predictive sampling.
+
+## 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
+    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
+
+```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/            # lexer, parser, AST, compiler for .qvr files
+├── inference/      # traces, conditioning, guides, ELBO, SVI, predictive
+├── program.py      # Program: wraps morphisms as nn.Module
+└── giry.py         # GiryMonad, FinStoch
+```
+
+## 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.13+
+- PyTorch 2.0+
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style conventions, and the git workflow.
+
+## License
+
+MIT. See [LICENSE](LICENSE) for details.