bayeswire 0.3.0__tar.gz

bayeswire-0.3.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.3
+Name: bayeswire
+Version: 0.3.0
+Summary: Model declaration language and wire format for the bayes* toolchain. Stdlib only.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# bayeswire
+
+**The reproducible, agent-verifiable Bayesian workflow — one spec, a reference
+engine, a fast engine that must agree with it, and a harness that refuses to
+let either you or the agent skip a step.**
+
+## Quickstart
+
+You write a model; `bayescycle` provisions the sampling engine and the
+plotting tool for you.
+
+Install the workflow harness (it pins `bayeswire`, so nothing else to
+install yet):
+
+```bash
+uv tool install git+https://github.com/StefanSko/bayescycle.git
+```
+
+Write `model.py`:
+
+```python
+from bayeswire import Data, Observed, Param, model
+from bayeswire.constraints import Positive
+from bayeswire.distributions import Normal, Truncated
+
+@model
+class LinearRegression:
+    alpha = Param(Normal(0.0, 1.0))
+    beta = Param(Normal(0.0, 1.0))
+    sigma = Param(Truncated(Normal(0.0, 1.0), lower=0.0), constraint=Positive())
+
+    x = Data.vector()
+    mu = alpha + beta * x
+    y = Observed(Normal(mu, sigma))
+```
+
+and `data.json`:
+
+```json
+{"x": [-1.0, -0.5, 0.0, 0.5, 1.0], "y": [-1.6, -0.3, 0.4, 1.1, 2.2]}
+```
+
+Sample, then plot:
+
+```bash
+bayescycle sample model.py --data data.json -o run/
+bayescycle plot trace run/
+```
+
+`sample` downloads and sha256-verifies the pinned Bayesite engine release
+into a local cache the first time it runs; later runs reuse it. `plot`
+reaches `bayesite-viz` through `uvx` against a pinned commit, so there is
+nothing else to `pip install`. See
+[bayescycle](https://github.com/StefanSko/bayescycle) for the rest of the
+CLI: prior-predictive checks, simulation/recovery, SBC, and diagnostics.
+
+## The toolchain
+
+| Repository | Role |
+|---|---|
+| **bayeswire** (here) | One spec: eDSL, resolved IR, wire codec, dimension sidecars, normative docs, and fixture corpus |
+| [jaxstanv5](https://github.com/StefanSko/jaxstanv5) | Reference engine: JAX/BlackJAX backend for binding models, compiling log densities, running NUTS, and emitting diagnostics |
+| [bayesite](https://github.com/StefanSko/bayesite) | Fast engine that must agree with the reference: zero-dependency Rust engine that vendors specs and fixtures by file |
+| [bayescycle](https://github.com/StefanSko/bayescycle) | Harness that refuses skipped steps: file-based workflow runner for agents and humans |
+| [bayesite-viz](https://github.com/StefanSko/bayesite-viz) | Downstream visualization: fit-artifact exporter and dashboards |
+
+Every workflow step is a command that reads files and writes files; every run
+is seeded and replayable; run directories are append-only; provenance records
+what was actually done. The customer is an agent and the human auditing it;
+the product is trustworthy process, not a sampler.
+
+Consumers pin bayeswire by exact version and vendor or conformance-test
+against the corpus; the copies of the spec in downstream repositories are
+generated and hash-checked, never edited.
+
+## This repository
+
+**The model declaration language and wire format for the bayes\* toolchain.**
+
+bayeswire owns the language: a declarative Python eDSL for Bayesian models,
+the resolved-metadata IR it compiles to, the `bayeswire_ir` v1 wire format
+that IR serializes as, the dimension-label sidecar format, the normative spec
+for all of it, and the golden fixture corpus every producer and consumer
+conformance-tests against.
+
+It contains no inference, no distribution math, no plotting, and no workflow
+orchestration, and it imports nothing outside the Python standard library.
+
+```python
+from bayeswire import Data, Observed, Param, model
+from bayeswire.constraints import Positive
+from bayeswire.distributions import Normal, Truncated
+from bayeswire.ir import canonical_bytes, meta_to_dict
+from bayeswire.model import model_meta
+
+@model
+class LinearRegression:
+    alpha = Param(Normal(0.0, 1.0))
+    beta = Param(Normal(0.0, 1.0))
+    sigma = Param(Truncated(Normal(0.0, 1.0), lower=0.0), constraint=Positive())
+
+    x = Data.vector()
+    mu = alpha + beta * x
+    y = Observed(Normal(mu, sigma))
+
+meta = model_meta(LinearRegression)
+document = meta_to_dict(meta)          # {"bayeswire_ir": 1, "model": ...}
+wire_bytes = canonical_bytes(meta)     # sha256(wire_bytes) is the model hash
+```
+
+Decoding is code-free: `meta_from_dict(document)` reconstructs resolved
+metadata without executing any user code, and
+`bindable_from_meta(meta, dimensions=...)` returns a pure metadata class that
+backends bind and sample.
+
+## Layout
+
+- `src/bayeswire/` — the package: `model`, `distributions`, `constraints`,
+  `math`, `ir`
+- `spec/` — the normative wire spec: `ir-format-v1.md`, generated
+  `ir-v1-tags.md`, `dimension-sidecar-v1.md`, `data-document-v1.md`,
+  `model-data-fingerprint-v1.md`
+- `src/bayeswire/corpus/` — golden IR documents, canonical hashes, canonical
+  data documents, fingerprint test vectors, and JAX-oracle evaluation
+  fixtures, shipped as package data so Python consumers conformance-test
+  against the installed pin (see its README)
+- `scripts/regenerate_corpus.py` — regenerates corpus documents, hashes,
+  data documents, fingerprints, and the generated tag spec after a
+  deliberate format change
+- `docs/releasing.md` — the release procedure: when to tag, how to cut the
+  tag, and the consumer pin-bump order
+
+## Development
+
+```bash
+uv sync
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
+
+The test suite includes a no-JAX walk (every module must import with `jax`
+and `blackjax` blocked) and produce-conformance (reference declarations must
+reproduce the corpus byte-for-byte). See `AGENTS.md` for the working
+discipline and `docs/invariants.md` for the invariants.

bayeswire-0.3.0/README.md

@@ -0,0 +1,146 @@
+# bayeswire
+
+**The reproducible, agent-verifiable Bayesian workflow — one spec, a reference
+engine, a fast engine that must agree with it, and a harness that refuses to
+let either you or the agent skip a step.**
+
+## Quickstart
+
+You write a model; `bayescycle` provisions the sampling engine and the
+plotting tool for you.
+
+Install the workflow harness (it pins `bayeswire`, so nothing else to
+install yet):
+
+```bash
+uv tool install git+https://github.com/StefanSko/bayescycle.git
+```
+
+Write `model.py`:
+
+```python
+from bayeswire import Data, Observed, Param, model
+from bayeswire.constraints import Positive
+from bayeswire.distributions import Normal, Truncated
+
+@model
+class LinearRegression:
+    alpha = Param(Normal(0.0, 1.0))
+    beta = Param(Normal(0.0, 1.0))
+    sigma = Param(Truncated(Normal(0.0, 1.0), lower=0.0), constraint=Positive())
+
+    x = Data.vector()
+    mu = alpha + beta * x
+    y = Observed(Normal(mu, sigma))
+```
+
+and `data.json`:
+
+```json
+{"x": [-1.0, -0.5, 0.0, 0.5, 1.0], "y": [-1.6, -0.3, 0.4, 1.1, 2.2]}
+```
+
+Sample, then plot:
+
+```bash
+bayescycle sample model.py --data data.json -o run/
+bayescycle plot trace run/
+```
+
+`sample` downloads and sha256-verifies the pinned Bayesite engine release
+into a local cache the first time it runs; later runs reuse it. `plot`
+reaches `bayesite-viz` through `uvx` against a pinned commit, so there is
+nothing else to `pip install`. See
+[bayescycle](https://github.com/StefanSko/bayescycle) for the rest of the
+CLI: prior-predictive checks, simulation/recovery, SBC, and diagnostics.
+
+## The toolchain
+
+| Repository | Role |
+|---|---|
+| **bayeswire** (here) | One spec: eDSL, resolved IR, wire codec, dimension sidecars, normative docs, and fixture corpus |
+| [jaxstanv5](https://github.com/StefanSko/jaxstanv5) | Reference engine: JAX/BlackJAX backend for binding models, compiling log densities, running NUTS, and emitting diagnostics |
+| [bayesite](https://github.com/StefanSko/bayesite) | Fast engine that must agree with the reference: zero-dependency Rust engine that vendors specs and fixtures by file |
+| [bayescycle](https://github.com/StefanSko/bayescycle) | Harness that refuses skipped steps: file-based workflow runner for agents and humans |
+| [bayesite-viz](https://github.com/StefanSko/bayesite-viz) | Downstream visualization: fit-artifact exporter and dashboards |
+
+Every workflow step is a command that reads files and writes files; every run
+is seeded and replayable; run directories are append-only; provenance records
+what was actually done. The customer is an agent and the human auditing it;
+the product is trustworthy process, not a sampler.
+
+Consumers pin bayeswire by exact version and vendor or conformance-test
+against the corpus; the copies of the spec in downstream repositories are
+generated and hash-checked, never edited.
+
+## This repository
+
+**The model declaration language and wire format for the bayes\* toolchain.**
+
+bayeswire owns the language: a declarative Python eDSL for Bayesian models,
+the resolved-metadata IR it compiles to, the `bayeswire_ir` v1 wire format
+that IR serializes as, the dimension-label sidecar format, the normative spec
+for all of it, and the golden fixture corpus every producer and consumer
+conformance-tests against.
+
+It contains no inference, no distribution math, no plotting, and no workflow
+orchestration, and it imports nothing outside the Python standard library.
+
+```python
+from bayeswire import Data, Observed, Param, model
+from bayeswire.constraints import Positive
+from bayeswire.distributions import Normal, Truncated
+from bayeswire.ir import canonical_bytes, meta_to_dict
+from bayeswire.model import model_meta
+
+@model
+class LinearRegression:
+    alpha = Param(Normal(0.0, 1.0))
+    beta = Param(Normal(0.0, 1.0))
+    sigma = Param(Truncated(Normal(0.0, 1.0), lower=0.0), constraint=Positive())
+
+    x = Data.vector()
+    mu = alpha + beta * x
+    y = Observed(Normal(mu, sigma))
+
+meta = model_meta(LinearRegression)
+document = meta_to_dict(meta)          # {"bayeswire_ir": 1, "model": ...}
+wire_bytes = canonical_bytes(meta)     # sha256(wire_bytes) is the model hash
+```
+
+Decoding is code-free: `meta_from_dict(document)` reconstructs resolved
+metadata without executing any user code, and
+`bindable_from_meta(meta, dimensions=...)` returns a pure metadata class that
+backends bind and sample.
+
+## Layout
+
+- `src/bayeswire/` — the package: `model`, `distributions`, `constraints`,
+  `math`, `ir`
+- `spec/` — the normative wire spec: `ir-format-v1.md`, generated
+  `ir-v1-tags.md`, `dimension-sidecar-v1.md`, `data-document-v1.md`,
+  `model-data-fingerprint-v1.md`
+- `src/bayeswire/corpus/` — golden IR documents, canonical hashes, canonical
+  data documents, fingerprint test vectors, and JAX-oracle evaluation
+  fixtures, shipped as package data so Python consumers conformance-test
+  against the installed pin (see its README)
+- `scripts/regenerate_corpus.py` — regenerates corpus documents, hashes,
+  data documents, fingerprints, and the generated tag spec after a
+  deliberate format change
+- `docs/releasing.md` — the release procedure: when to tag, how to cut the
+  tag, and the consumer pin-bump order
+
+## Development
+
+```bash
+uv sync
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
+
+The test suite includes a no-JAX walk (every module must import with `jax`
+and `blackjax` blocked) and produce-conformance (reference declarations must
+reproduce the corpus byte-for-byte). See `AGENTS.md` for the working
+discipline and `docs/invariants.md` for the invariants.

bayeswire-0.3.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "bayeswire"
+version = "0.3.0"
+description = "Model declaration language and wire format for the bayes* toolchain. Stdlib only."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.13.0",
+    "ty==0.0.49",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.0,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ty.environment]
+python = "../../.venv"
+python-version = "3.12"
+root = ["./src", "./tests"]

bayeswire-0.3.0/src/bayeswire/__init__.py

@@ -0,0 +1,23 @@
+"""bayeswire — the model declaration language and wire format for the bayes* toolchain."""
+
+from bayeswire.model import (
+    Data,
+    Dim,
+    Observed,
+    Param,
+    PartiallyObserved,
+    dimension_metadata_to_dict,
+    model,
+    model_dimensions,
+)
+
+__all__ = [
+    "Data",
+    "Dim",
+    "Observed",
+    "Param",
+    "PartiallyObserved",
+    "dimension_metadata_to_dict",
+    "model",
+    "model_dimensions",
+]

bayeswire-0.3.0/src/bayeswire/_ir_registry.py

@@ -0,0 +1,188 @@
+"""Private IR node registry: tag vocabulary and field-kind classification.
+
+The registry maps the closed inventory of resolved model-metadata dataclasses
+to wire tags and records, once per class, how each constructor field is
+represented in the IR document. ``bayeswire.ir`` is the public surface.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields, is_dataclass
+from enum import Enum
+from typing import get_origin, get_type_hints
+
+from bayeswire.constraints import Interval, Ordered, Positive, UnitInterval
+from bayeswire.distributions import (
+    Bernoulli,
+    Beta,
+    BetaBinomial,
+    Binomial,
+    Exponential,
+    HalfNormal,
+    MultivariateNormal,
+    NegativeBinomial,
+    Normal,
+    OrderedLogistic,
+    Poisson,
+    StudentT,
+    Truncated,
+    Uniform,
+)
+from bayeswire.model._data_schema import (
+    DataDimRef,
+    ResolvedDataRankSchema,
+    ResolvedDataShapeSchema,
+)
+from bayeswire.model.decorator import (
+    ModelMeta,
+    ResolvedData,
+    ResolvedFreeValue,
+    ResolvedObserved,
+    ResolvedParam,
+    ResolvedStochasticSite,
+)
+from bayeswire.model.expr import (
+    BinOp,
+    ConstNode,
+    DataRef,
+    FullSlice,
+    IndexOp,
+    IndexTuple,
+    ParamRef,
+    ScalarIndex,
+    UnaryOp,
+    VectorScatterOp,
+)
+
+NODE_KEY = "node"
+
+
+class FieldKind(Enum):
+    """How a registered node field is represented in the IR document."""
+
+    MAP = "map"
+    TUPLE = "tuple"
+    VALUE = "value"
+
+
+@dataclass(frozen=True)
+class NodeSpec:
+    """Registered IR node class with its wire tag and field kinds."""
+
+    cls: type
+    tag: str
+    field_kinds: tuple[tuple[str, FieldKind], ...]
+
+
+NODE_SPECS_BY_TAG: dict[str, NodeSpec] = {}
+NODE_SPECS_BY_CLASS: dict[type, NodeSpec] = {}
+
+
+def register_node(cls: type, *, tag: str | None = None) -> None:
+    """Register a dataclass as a tagged IR node.
+
+    The tag defaults to the class name; pass ``tag=...`` to keep the wire
+    vocabulary stable across Python class renames.
+    """
+    if not is_dataclass(cls):
+        raise TypeError(
+            f"IR node classes must be dataclasses; {cls.__name__} is not. "
+            "Decorate it with @dataclass(frozen=True)."
+        )
+    node_tag = cls.__name__ if tag is None else tag
+    existing = NODE_SPECS_BY_TAG.get(node_tag)
+    if existing is not None:
+        if existing.cls is cls:
+            return
+        raise ValueError(
+            f"IR node tag {node_tag!r} is already registered to {existing.cls.__name__}. "
+            "Pass a unique IR tag when registering the class."
+        )
+    registered = NODE_SPECS_BY_CLASS.get(cls)
+    if registered is not None:
+        raise ValueError(
+            f"{cls.__name__} is already registered as IR tag {registered.tag!r}; "
+            "one class maps to one tag."
+        )
+    spec = NodeSpec(cls=cls, tag=node_tag, field_kinds=_classify_fields(cls))
+    NODE_SPECS_BY_TAG[node_tag] = spec
+    NODE_SPECS_BY_CLASS[cls] = spec
+
+
+def _classify_fields(cls: type) -> tuple[tuple[str, FieldKind], ...]:
+    """Record each constructor field's wire representation once, at registration."""
+    if not is_dataclass(cls):
+        raise TypeError(f"Cannot classify fields of non-dataclass {cls.__name__}")
+    hints = get_type_hints(cls)
+    kinds: list[tuple[str, FieldKind]] = []
+    for field in fields(cls):
+        if not field.init:
+            continue
+        if field.name == NODE_KEY:
+            raise ValueError(
+                f"IR node classes cannot have a field named {NODE_KEY!r}: {cls.__name__}. "
+                "Rename the field before registering the class."
+            )
+        kinds.append((field.name, _field_kind(hints[field.name])))
+    return tuple(kinds)
+
+
+def _field_kind(hint: object) -> FieldKind:
+    origin = get_origin(hint)
+    if origin is dict:
+        return FieldKind.MAP
+    if origin is tuple:
+        return FieldKind.TUPLE
+    return FieldKind.VALUE
+
+
+_BUILTIN_NODE_CLASSES: tuple[type, ...] = (
+    # Expression nodes
+    ParamRef,
+    DataRef,
+    ConstNode,
+    BinOp,
+    UnaryOp,
+    IndexOp,
+    VectorScatterOp,
+    # Index specifications
+    ScalarIndex,
+    FullSlice,
+    IndexTuple,
+    # Resolved data schemas
+    DataDimRef,
+    ResolvedDataShapeSchema,
+    ResolvedDataRankSchema,
+    # Resolved declarations
+    ResolvedParam,
+    ResolvedData,
+    ResolvedObserved,
+    ResolvedFreeValue,
+    ResolvedStochasticSite,
+    ModelMeta,
+    # Constraints
+    Positive,
+    Interval,
+    UnitInterval,
+    Ordered,
+    # Built-in distributions
+    Normal,
+    HalfNormal,
+    StudentT,
+    Exponential,
+    Uniform,
+    Beta,
+    Truncated,
+    Bernoulli,
+    Poisson,
+    Binomial,
+    BetaBinomial,
+    NegativeBinomial,
+    MultivariateNormal,
+    OrderedLogistic,
+)
+
+for _builtin in _BUILTIN_NODE_CLASSES:
+    register_node(_builtin)
+
+CORE_PROFILE_TAGS: tuple[str, ...] = tuple(NODE_SPECS_BY_TAG)

bayeswire-0.3.0/src/bayeswire/constraints/__init__.py

@@ -0,0 +1,22 @@
+"""Parameter constraints and transforms (unconstrained <-> constrained)."""
+
+from bayeswire.constraints.core import (
+    ConstrainedValue,
+    Constraint,
+    LogAbsDetJacobian,
+    UnconstrainedValue,
+)
+from bayeswire.constraints.interval import Interval, UnitInterval
+from bayeswire.constraints.ordered import Ordered
+from bayeswire.constraints.positive import Positive
+
+__all__ = [
+    "Constraint",
+    "ConstrainedValue",
+    "Interval",
+    "LogAbsDetJacobian",
+    "Ordered",
+    "Positive",
+    "UnitInterval",
+    "UnconstrainedValue",
+]

bayeswire-0.3.0/src/bayeswire/constraints/core.py

@@ -0,0 +1,11 @@
+"""Core constraint metadata protocols and value aliases."""
+
+from typing import Protocol
+
+type ConstrainedValue = object
+type UnconstrainedValue = object
+type LogAbsDetJacobian = object
+
+
+class Constraint(Protocol):
+    """Parameter constraint metadata consumed by numerical backends."""

bayeswire-0.3.0/src/bayeswire/constraints/interval.py

@@ -0,0 +1,33 @@
+"""Finite interval constraint metadata."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Interval:
+    """Constraint metadata for values in a finite open interval."""
+
+    lower: float
+    upper: float
+
+    def __post_init__(self) -> None:
+        """Validate finite ordered interval bounds."""
+        if isinstance(self.lower, bool) or isinstance(self.upper, bool):
+            raise TypeError("Interval bounds must be finite real numbers, not bool")
+        if not math.isfinite(self.lower) or not math.isfinite(self.upper):
+            raise ValueError("Interval bounds must be finite")
+        if self.lower >= self.upper:
+            raise ValueError("Interval lower bound must be less than upper bound")
+
+    @property
+    def width(self) -> float:
+        """Return finite interval width."""
+        return self.upper - self.lower
+
+
+@dataclass(frozen=True)
+class UnitInterval:
+    """Constraint metadata for values in the open unit interval."""

bayeswire-0.3.0/src/bayeswire/constraints/ordered.py

@@ -0,0 +1,8 @@
+"""Ordered-vector constraint metadata."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Ordered:
+    """Constraint metadata for strictly increasing vectors along the last axis."""

bayeswire-0.3.0/src/bayeswire/constraints/positive.py

@@ -0,0 +1,8 @@
+"""Positive constraint metadata."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Positive:
+    """Constraint metadata for strictly positive values."""

bayeswire-0.3.0/src/bayeswire/corpus/README.md

@@ -0,0 +1,38 @@
+# Golden fixture corpus
+
+This directory is the conformance corpus for the `bayeswire_ir` v1 wire
+format. Every producer and consumer in the toolchain tests against these
+files; none may substitute private fixtures.
+
+- `<model>.json` — golden IR documents for the reference models declared in
+  `tests/conformance/reference_models.py`, pretty-printed for diffability.
+- `hashes.json` — `sha256(canonical_bytes(meta))` for each reference model:
+  the pinned canonical encoding.
+- `fixtures/<model>.json` — cross-backend evaluation fixtures bundling each
+  IR document with concrete bind data and log-density plus gradient values
+  at deterministic unconstrained points.
+- `data/<model>.json` — the canonical data document
+  (`spec/data-document-v1.md`) for each reference model, wrapping the same
+  values as the fixture's `data` block.
+- `fingerprints.json` — pinned `model_data_fingerprint` test vectors
+  (`spec/model-data-fingerprint-v1.md`) over the exact committed bytes of
+  `<model>.json` and `data/<model>.json`.
+
+The evaluation values in `fixtures/` are **JAX-oracle outputs**: computed by
+the jaxstanv5 backend in float64 (`jax_enable_x64`), regenerated with
+jaxstanv5's `scripts/generate_ir_fixtures.py` against this corpus. Consumers
+reproduce them within the tolerance policy stated in
+`spec/ir-format-v1.md` — the tolerances live in the spec, not in any
+consumer's tests.
+
+- `artifacts/<model>/` — golden **run artifacts**: real run directories
+  (`model.ir.json`, `data.json`, optional `dims.json`, `posterior.ndjson`
+  with `per_draw_v2` sample stats, `diagnostics.json`) produced by a real
+  bayesite binary from corpus models via
+  `scripts/generate_artifact_corpus.py`. Downstream exporters
+  (`bayesite_idata`) consume them as test fixtures instead of synthesizing
+  their own run directories.
+
+Regenerate the documents and hashes with `scripts/regenerate_corpus.py`.
+Any corpus diff is a wire-format change: it requires a spec changelog entry,
+a version decision, and a coordinated consumer-pin bump.