veya-py — Python bindings for Veya

PyO3 bindings exposing the important public API of Veya — a hardware-neutral real-time perception and dataflow runtime — to Python. Published to PyPI as veya.

Install

pip install veya

Wheels are published for CPython 3.9–3.13 (abi3) on Linux x86_64 and macOS (x86_64 + arm64).

Bound API surface (0.0.1)

The bindings cover the veya-core semantic foundation:

Not yet exposed (0.0.1): the async runtime / provider instances (veya-runtime has no engine yet), GPU memory backends, codecs and inference providers, and the metadata-serialization (serde/JSON) feature. The Tensor/Frame buffer handles are identity references into the memory model (RFC-002), not inline bytes.

Usage

import veya
from veya import data, graph

# Data model
stream_id = veya.PyStreamId.new()
ts = data.PyTimestamp.from_nanos(1_500_000)
bbox = data.PyBoundingBox(10.0, 20.0, 100.0, 50.0)
print(bbox.right())  # 110.0

# Graph building and validation (RFC-003 §16)
src = graph.PyElement(
    graph.PyElementId.new(),
    graph.PyElementTypeId("veya.source.synthetic"),
    "src",
    graph.PyElementKind.Source,
).with_output(graph.PyPort.output("out", graph.PyDataContract.frame()))

sink = graph.PyElement(
    graph.PyElementId.new(),
    graph.PyElementTypeId("veya.sink.fake"),
    "sink",
    graph.PyElementKind.Sink,
).with_input(graph.PyPort.input("in", graph.PyDataContract.frame()))

g = graph.PyGraphBuilder().add_element(src).add_element(sink).connect(
    src.outputs[0].id, sink.inputs[0].id
).build()

report = g.validate()
assert report.is_valid()

# Provider registry and selection (RFC-004 §20)
registry = veya.PyProviderRegistry()
registry.register(
    veya.PyProviderDescriptor(
        veya.PyProviderId("native.detector"), veya.PyVersion(0, 1, 0)
    )
    .with_element_type(graph.PyElementTypeId("veya.detector"))
    .with_priority(10)
)
selected = veya.select_provider(
    graph.PyElementTypeId("veya.detector"),
    registry,
    [],
    veya.PySelectionPolicy.highest_priority(),
)
assert selected.id.as_str() == "native.detector"

Development

Build and install into the active virtualenv:

pip install maturin pytest
cd crates/veya-py
maturin develop --release
pytest tests/ -v

Or from the repository root: make py-install && make py-test.

The compiled extension is built as veya.rust from this crate ([lib] name = "rust", cdylib) and glued to the python/veya package by maturin (module-name = "veya.rust", python-source = "python"). Wheels use the abi3-py39 stable ABI.

Versioning

The crate pins its own version (currently 0.0.1) instead of the Rust workspace version, kept in sync with pyproject.toml — the PyPI package version line is independent of the workspace releases.

Publishing to PyPI

Publishing is automated by .github/workflows/python-publish.yml: pushing a v* tag builds wheels (Linux x86_64 via manylinux, macOS x86_64 + arm64) and an sdist, then publishes with PyPI trusted publishing (OIDC — no stored tokens).

One-time setup (required before the first release):

1. On PyPI, create the veya project.
2. Add a trusted publisher pointing at the mirasoth/veya repository, workflow python-publish.yml, environment pypi.
3. In the GitHub repository settings, create a pypi deployment environment.