# factslab/quivers architecture

> Architecture diagram of the GitHub repository factslab/quivers, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/factslab/quivers
- Repository: https://github.com/factslab/quivers

## Overview

Quivers is a typed functional probabilistic programming language with a PyTorch runtime. The principal path is authoring QVR (or generating it from a formula), checking and compiling it to QIEC, then executing and fitting a model or transpiling it to another probabilistic language. The graph also shows the documented diagnostics, structural/categorical API, and language tooling branches. Product relationships are based primarily on the README workflow; sampled source excerpts are partial, so uncertain internal call links are omitted.

Main entry points: [`src/quivers/qiec/module.py`](https://github.com/factslab/quivers/blob/main/src/quivers/qiec/module.py) (Checked QIEC), [`src/quivers/program.py`](https://github.com/factslab/quivers/blob/main/src/quivers/program.py) (Program wrapper), [`grammars/qvr/grammar.js`](https://github.com/factslab/quivers/blob/main/grammars/qvr/grammar.js) (QVR source), [`src/quivers/qiec/program_runtime.py`](https://github.com/factslab/quivers/blob/main/src/quivers/qiec/program_runtime.py) (QIEC execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["QVR language"]
  node_formula["Formula interface<br/>[compile.py]"]
  node_qvr["QVR source<br/>[grammar.js]"]
  node_dsl["Parser and compiler"]
  node_qiec["Checked QIEC<br/>[module.py]"]
end

subgraph group_execution["Execution and inference"]
  node_program["Program wrapper<br/>[program.py]"]
  node_runtime["QIEC execution<br/>[program_runtime.py]"]
  node_effects["Effect handlers<br/>[interpreter.py]"]
  node_inference["Inference methods"]
end

subgraph group_outputs["Analysis and targets"]
  node_diagnostics["Diagnostics"]
  node_analysis["Static analysis"]
  node_transpile["Transpilation pipeline<br/>[_pipeline.py]"]
  node_targets["Target renderers"]
end

subgraph group_tooling["Developer tooling"]
  node_cli["CLI and REPL"]
  node_lsp["Language server<br/>[server.py]"]
  node_editor["Editor grammar<br/>[extension.ts]"]
end

subgraph group_apis["Modeling APIs"]
  node_pythonapi["Categorical and structural API"]
end

node_user(("Model author"))
node_torch["PyTorch"]
node_targets_ext["External target runtimes"]

node_user -->|"authors"| node_qvr
node_user -->|"specifies formula"| node_formula
node_formula -->|"generates QVR"| node_qvr
node_qvr -->|"parses and checks"| node_dsl
node_dsl -->|"compiles to"| node_qiec
node_user -->|"invokes"| node_cli
node_cli -->|"checks source"| node_dsl
node_cli -->|"runs program"| node_program
node_qiec -->|"loads checked module"| node_program
node_program -->|"invokes entry"| node_runtime
node_runtime -->|"dispatches effects"| node_effects
node_runtime -->|"executes with"| node_torch
node_program -->|"fits model"| node_inference
node_inference -->|"uses autodiff"| node_torch
node_inference -->|"produces diagnostics"| node_diagnostics
node_qiec -->|"summarizes program"| node_analysis
node_user -->|"requests target output"| node_transpile
node_transpile -->|"dispatches rendering"| node_targets
node_targets -.->|"emits target code"| node_targets_ext
node_user -->|"edits source"| node_editor
node_editor -.->|"requests language services"| node_lsp
node_lsp -->|"analyzes documents"| node_qvr
node_qiec -->|"provides tooling context"| node_lsp
node_pythonapi -->|"models with"| node_torch

click node_formula "https://github.com/factslab/quivers/blob/main/src/quivers/formulas/compile.py"
click node_qvr "https://github.com/factslab/quivers/blob/main/grammars/qvr/grammar.js"
click node_dsl "https://github.com/factslab/quivers/tree/main/src/quivers/dsl"
click node_qiec "https://github.com/factslab/quivers/blob/main/src/quivers/qiec/module.py"
click node_program "https://github.com/factslab/quivers/blob/main/src/quivers/program.py"
click node_runtime "https://github.com/factslab/quivers/blob/main/src/quivers/qiec/program_runtime.py"
click node_effects "https://github.com/factslab/quivers/blob/main/src/quivers/effects/interpreter.py"
click node_inference "https://github.com/factslab/quivers/tree/main/src/quivers/inference"
click node_diagnostics "https://github.com/factslab/quivers/tree/main/src/quivers/diagnostics"
click node_analysis "https://github.com/factslab/quivers/tree/main/src/quivers/analysis"
click node_transpile "https://github.com/factslab/quivers/blob/main/src/quivers/transpile/_pipeline.py"
click node_targets "https://github.com/factslab/quivers/tree/main/src/quivers/transpile/renderers"
click node_cli "https://github.com/factslab/quivers/tree/main/src/quivers/cli"
click node_lsp "https://github.com/factslab/quivers/blob/main/src/quivers/lsp/server.py"
click node_editor "https://github.com/factslab/quivers/blob/main/editors/vscode-qvr/src/extension.ts"
click node_pythonapi "https://github.com/factslab/quivers/tree/main/src/quivers/categorical"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_formula,node_qvr,node_dsl,node_qiec toneBlue
class node_program,node_runtime,node_effects,node_inference toneAmber
class node_diagnostics,node_analysis,node_transpile,node_targets toneMint
class node_cli,node_lsp,node_editor toneRose
class node_pythonapi,node_user,node_torch,node_targets_ext toneIndigo
```

## Components

### QVR language

- [Formula interface](https://github.com/factslab/quivers/blob/main/src/quivers/formulas/compile.py): `src/quivers/formulas/compile.py`
- [QVR source](https://github.com/factslab/quivers/blob/main/grammars/qvr/grammar.js): `grammars/qvr/grammar.js`
- [Parser and compiler](https://github.com/factslab/quivers/tree/main/src/quivers/dsl): `src/quivers/dsl`
- [Checked QIEC](https://github.com/factslab/quivers/blob/main/src/quivers/qiec/module.py): `src/quivers/qiec/module.py`

### Execution and inference

- [Program wrapper](https://github.com/factslab/quivers/blob/main/src/quivers/program.py): `src/quivers/program.py`
- [QIEC execution](https://github.com/factslab/quivers/blob/main/src/quivers/qiec/program_runtime.py): `src/quivers/qiec/program_runtime.py`
- [Effect handlers](https://github.com/factslab/quivers/blob/main/src/quivers/effects/interpreter.py): `src/quivers/effects/interpreter.py`
- [Inference methods](https://github.com/factslab/quivers/tree/main/src/quivers/inference): `src/quivers/inference`

### Analysis and targets

- [Diagnostics](https://github.com/factslab/quivers/tree/main/src/quivers/diagnostics): `src/quivers/diagnostics`
- [Static analysis](https://github.com/factslab/quivers/tree/main/src/quivers/analysis): `src/quivers/analysis`
- [Transpilation pipeline](https://github.com/factslab/quivers/blob/main/src/quivers/transpile/_pipeline.py): `src/quivers/transpile/_pipeline.py`
- [Target renderers](https://github.com/factslab/quivers/tree/main/src/quivers/transpile/renderers): `src/quivers/transpile/renderers`

### Developer tooling

- [CLI and REPL](https://github.com/factslab/quivers/tree/main/src/quivers/cli): `src/quivers/cli`
- [Language server](https://github.com/factslab/quivers/blob/main/src/quivers/lsp/server.py): `src/quivers/lsp/server.py`
- [Editor grammar](https://github.com/factslab/quivers/blob/main/editors/vscode-qvr/src/extension.ts): `editors/vscode-qvr/src/extension.ts`

### Modeling APIs

- [Categorical and structural API](https://github.com/factslab/quivers/tree/main/src/quivers/categorical): `src/quivers/categorical`

### Other components

- **Model author**
- **PyTorch**
- **External target runtimes**

## Connections

- Model author → QVR source: authors
- Model author → Formula interface: specifies formula
- Formula interface → QVR source: generates QVR
- QVR source → Parser and compiler: parses and checks
- Parser and compiler → Checked QIEC: compiles to
- Model author → CLI and REPL: invokes
- CLI and REPL → Parser and compiler: checks source
- CLI and REPL → Program wrapper: runs program
- Checked QIEC → Program wrapper: loads checked module
- Program wrapper → QIEC execution: invokes entry
- QIEC execution → Effect handlers: dispatches effects
- QIEC execution → PyTorch: executes with
- Program wrapper → Inference methods: fits model
- Inference methods → PyTorch: uses autodiff
- Inference methods → Diagnostics: produces diagnostics
- Checked QIEC → Static analysis: summarizes program
- Model author → Transpilation pipeline: requests target output
- Transpilation pipeline → Target renderers: dispatches rendering
- Target renderers → External target runtimes: emits target code
- Model author → Editor grammar: edits source
- Editor grammar → Language server: requests language services
- Language server → QVR source: analyzes documents
- Checked QIEC → Language server: provides tooling context
- Categorical and structural API → PyTorch: models with