Skip to content

valgebra

Fast runtime validation through a closed Boolean algebra of schemas.

A schema denotes a set of Python values. Validation is membership: you ask whether the object you already hold belongs to the set — no copy, no coercion. Schemas compile once into a Rust validator tree, and the hot path crosses into Rust exactly once per call.

from typing import Annotated, TypedDict

import annotated_types as at

from valgebra import Validator


class User(TypedDict):
    name: str
    age: Annotated[int, at.Ge(0)]


users = Validator(User)
assert users.is_valid({"name": "Ada", "age": 36})
assert not users.is_valid({"name": "Ada", "age": -1})

A set answers two questions: whether a value you hold belongs to it, and whether every value of one set belongs to another, subset, not_subset or undecided. How it works follows a schema from its annotation to both answers, with a diagram for each step.

Pre-alpha

valgebra is under active development and published to PyPI. The APIs described here work, and every 0.0.x release may break them, saying where in its notes. See the release notes for what is built and what counts as a break.

What valgebra is for

valgebra is a contracts-and-checking tool, not a parsing framework. Reach for it when you want to check an object you already hold against a composable, inspectable contract — cheaply enough to run on every request or every agent turn.

For ingesting untrusted input into typed models with coercion and defaults, use pydantic; for decoding bytes into structs, use msgspec. Neither answers the membership question: both check while building a value, and by default hand back one they are given without re-examining it. valgebra occupies the niche neither covers: a closed, lawful algebra of schemas (union, intersection, complement, refinement, fixpoints) with check-only semantics, on a Rust core.

That is a difference in job as well as in speed, and the difference in job has consequences a benchmark does not measure. Both parsers check while building a value from untyped input: handed a value that is already an instance of the target class, each returns it without checking its fields by default. pydantic re-checks one only for a class configured to ask for it (revalidate_instances, read off the class rather than the call), and checks a later mutation only at the assignment it is configured to watch (validate_assignment); msgspec's checking runs on the decode path alone. valgebra checks every field of a held instance, and asks the class alone where the caller writes instance_of. A membership question can be asked again, of the same object, as many times as the contract needs. And because a schema here is a value in an algebra rather than a class declaration, is_subtype_of, is_equivalent and is_empty ask about the schemas themselves, with no value involved. tests/test_pydantic_boundary.py pins each of these against pydantic, including the case that runs the other way: a pydantic BaseModel reaches valgebra as a bare class and is not deep-checked.

What makes it different

  • Schemas denote sets; validation is membership. Subtyping is set inclusion and equivalence is mutual inclusion — decided soundly over a wide fragment and deliberately conservative beyond it. The whole model is one idea.
  • A real Boolean algebra. union, intersection, and complement compose any schema into a lattice whose laws are property-tested, and a schema is built in the lattice normal form: repr shows it and == compares it, so no later pass is needed to reach it.
  • Typing-first. Standard annotations are the primary notation, read through the typing spec's own introspection.
  • Check, don't parse. validate and is_valid never copy or coerce; ensure is the explicit, separate mode that hands back the object it checked, unchanged.
  • Few boundary crossings. Tree walks, key lookups, and bound checks run in Rust; a comparison against a Python object — a literal, a refinement predicate, or an instance or attribute check — is the documented step into Python, never a silent fallback.
  • JSON on the Rust path. validate_json parses and validates JSON in Rust, consistent with the object path.
  • Immutable and thread-safe by design. Free-threaded CPython 3.14 and 3.15 are supported, with cp314t and cp315t wheels for Linux, macOS and Windows x64.

Where to start