Metadata-Version: 2.4
Name: veya
Version: 0.0.1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
Requires-Dist: black>=24.0.0 ; extra == 'dev'
Requires-Dist: ruff>=0.6.0 ; extra == 'dev'
Requires-Dist: pytest>=7.0.0 ; extra == 'test'
Provides-Extra: dev
Provides-Extra: test
Summary: Python bindings for Veya — hardware-neutral real-time perception and dataflow runtime
Author: Veya Project
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/mirasoth/veya
Project-URL: Repository, https://github.com/mirasoth/veya

# veya-py — Python bindings for Veya

[![CI](https://github.com/mirasoth/veya/actions/workflows/ci.yml/badge.svg)](https://github.com/mirasoth/veya/actions/workflows/ci.yml)
[![PyPI](https://github.com/mirasoth/veya/actions/workflows/python-publish.yml/badge.svg)](https://github.com/mirasoth/veya/actions/workflows/python-publish.yml)

PyO3 bindings exposing the important public API of [Veya](https://github.com/mirasoth/veya)
— a hardware-neutral real-time perception and dataflow runtime — to Python.
Published to [PyPI](https://pypi.org/project/veya/) as **`veya`**.

## Install

```bash
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:

| Submodule | RFC | Contents |
|-----------|-----|----------|
| `veya.data` | RFC-001 | Typed IDs, geometry (`PyBoundingBox`, `PyPolygon`, …), `PyTimestamp`, formats (`PyVideoFormat`, `PyPixelFormat`, …), `PyTensor`, `PyStream`, `PyEventType`/`PyEvent`, `PyTrack`, `PyDetectedObject`/`PyMetadata`, spatial math (`PyQuaternion`, `PyRigidTransform`), `PyFrame` |
| `veya.graph` | RFC-003 | `PyElement`, `PyPort`, `PyDataContract`/`PyContractSpec`, `PyEdge`, `PyGraphBuilder`, `PyGraph`, `validate` |
| `veya.provider` | RFC-004 | `PyProviderDescriptor`, `PyCapability`/`PyRequirement`, `PyProviderRegistry`, `select_provider`, ABI version helpers |
| `veya.execution` | RFC-005 | `PyExecutionContract` and its vocabulary enums (`PyConcurrency`, `PyInputRelation`, `PyOverflowPolicy`, …) |

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

```python
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:

```bash
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`](../../.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](https://docs.pypi.org/trusted-publishers/)
(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.

