oarust 0.12.0

GPU-first semantic computing engine written in Rust
docs.rs failed to build oarust-0.12.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

OA

OA is a GPU-first semantic computing engine written in Rust. One explicit Engine owns Vulkan devices, memory, queues, scheduling, kernels, and profiling; typed values and domain operations build on that owner without exposing backend machinery through the public API.

This repository is the new primary OA implementation. The earlier C++ codebase continues separately as the donor and compatibility reference.

Release CI Crates.io PyPI License

Three lines of compute

Rust:

use oa::{matrix, Engine};

let engine = Engine::new()?;
let one = matrix::ones(&engine, [2, 3])?;
let two = matrix::full(&engine, [2, 3], 2.0)?;
let total = matrix::add(&one, &two)?;

assert_eq!(total.read_f32()?, [3.0; 6]);
# Ok::<(), oa::Error>(())

Python preview—the same module ownership and native runtime:

import oa

engine = oa.Engine()
one = oa.matrix.ones(engine, [2, 3])
two = oa.matrix.full(engine, [2, 3], 2.0)
total = oa.matrix.add(one, two)

assert total.read_f32() == [3.0] * 6

Python abbreviations are ordinary local imports, not parallel APIs:

import oa.core as oac
import oa.matrix as oam

What works today

OA is an experimental, executable rewrite—not a structure-only stub. Current checked vertical slices include:

  • Vulkan device selection constrained to the compiled Core 1.3 or bounded Compatibility 1.2 profile, VMA-backed storage, profile-specific descriptors, asynchronous retirement, timeline events, eager batching, semantic capture, immutable execution plans, replay, rebinding, hazard analysis, and Vulkan timestamp evidence;
  • schema-owned Matrix elementwise, reduction, indexing, RNG, transpose, gather, tiled FP32 matrix multiplication, broadcasting, and reverse-mode operations;
  • ML modules, autograd, Adam/AdamW/SGD/Muon, training iterators, callbacks, checkpoints, RNN/GRU/Transformer/MoE/Mamba-3 NLP tutorials, reinforcement learning, VQ, and the in-progress Animation Language Model stack;
  • Image operations and codecs, planar Audio and codecs/DSP/sessions, Video containers/decoding, Vision detection/metrics, Render value foundations, cryptographic hashes/Merkle/PQC, secure memory, and Vulkan batch hashing;
  • native PyO3 bindings for Engine/Event, typed dense Matrix construction and operations, the current functional ML spine, Image codecs/transforms, Audio codecs/DSP/features, metadata, and explicit synchronized host observation.

No GPU operation is classified as stable yet. Capability claims are tied to the compatibility ledger, independent oracles, and recorded hardware evidence.

Architecture

semantic values and operations
             │
             ▼
      semantic operation graph
             │ private lowering
             ▼
      executable Vulkan graph
             │
             ▼
 Engine-owned queues, memory, events, profiling
  • Values carry semantics; shared storage does not erase type identity.
  • Operations are stateless. Stateful external or iterative work is a session.
  • The semantic graph stays separate from executable backend work.
  • Eager operations return values; explicit submit/wait is reserved for capture, orchestration, profiling, multi-device, and distributed work.
  • One operation schema owns derivable Rust, Python, validation, autograd, registry, documentation, and test surfaces.
  • Slang kernels are embedded in the binary; runtime users do not ship loose .spv files.

Distribution names

The project and API namespace are oa. The language-specific distribution names are oarust on crates.io and oapython on PyPI; Python uses import oa.

The Rust package is oarust, with library name oa:

[dependencies]
oarust = "0.8.6"

The crate contains the library and its required build inputs, including the source support modules exposed through oa::sdk. Runnable SDK programs are separate release downloads; they are not part of the registry package.

Rust code uses use oa::.... Python installs with python -m pip install oapython==0.8.6 and uses import oa. Tagged CI verifies and publishes both packages, the SDK executables and native Linux packages, source and Rust API documentation archives, and checksums. The old oarust 0.0.1 package is a documentation-only name reservation.

Build

Requirements: Rust 1.98, Python 3, rustfmt, CMake, slangc 2026.14, spirv-val, native audio/window-system development libraries, and a compatible Vulkan driver. The default Core build requires Vulkan 1.3 and the required bindless features. An explicit Compatibility build supports admitted Vulkan 1.2 devices with bounded bindings. Compatibility presentation is not yet qualified. Linux builds use Clang/LLD for native linking while rustc and LLVM compile Rust. SDL3 builds statically from the pinned Cargo source by default (bundled-sdl); --no-default-features uses system SDL3 instead.

cargo build --release
cargo run --release --example core_mat_mul_intro

The compact media applications share OA's GPU viewer:

cargo run --release --bin oa -- view image.png
cargo run --release --bin oa -- record
cargo run --release --bin oa -- record --camera 1
cargo run --release --bin oa -- capture
cargo run --release --bin oa -- capture --window --hide-cursor

oa record previews the selected camera. Click the red circle or press Space to record; click the stop square or press Space again to finish. The elapsed timer runs during recording. Ctrl+S stops and opens Save As, or reopens Save As for the last completed recording. Each recording streams to a unique directory under the desktop's Videos/OA directory (falling back to ~/Videos/OA). Cancelling Save As keeps that original; closing the viewer finalizes it there. Save As creates a separate copy and retains the original for recovery. This first camera route requires hardware H.264 encoding and records video without microphone audio.

Camera and screen previews use the same GPU 2D canvas as image/video viewing: drag or wheel to pan, Ctrl+wheel or right-drag to zoom, +/- to zoom, 0 to fit, 9 for actual size, and 1–5 for channel views. Navigation affects the preview; recordings retain the source resolution. Recording controls overlay the canvas.

oa capture uses the same recording controls for a desktop-selected screen; --window limits the picker to windows and --hide-cursor excludes the pointer. The desktop portal asks for permission before any pixels are captured. Static screens keep recording elapsed time, and a source-size change finishes the current movie before a new one can start. The Linux backend uses the donor's mapped-memory PipeWire route; DMA-BUF zero-copy capture remains planned. Building on Linux requires the PipeWire/SPA development headers, pkg-config, and libclang for their Rust bindings. Screen capture additionally needs libportal and a desktop ScreenCast portal at runtime. Engine initialization does not request screen access.

For older hardware, use OA_BUILD_PROFILE=compatibility cargo build --release. Each build compiles and embeds one shader catalog and one binding backend. Use the same environment variable when building the Python extension or an application that depends on OA; changing it at runtime does not change an already compiled library's profile.

Cargo keeps intermediate artifacts and build-script shader output in target/. Optional generator previews also belong under target/gen/; live schema-owned .gen.rs and Slang sources remain in their owning source directories. OA’s staging tool copies only runnable executables into bin/<profile>/:

python3 tool/oa stage --profile release --target core_mat_mul_intro
./bin/release/sdk/tutorials/core/core_mat_mul_intro

VS Code and Zed expose matching Build and Clean Build tasks for Debug and Release, each with an optional Python variant. The shared command-line workflow is also available directly:

python3 tool/oa build --profile debug
python3 tool/oa build --profile release --clean --python

It stages Rust executables and test runners under bin/debug/ or bin/release/. --python creates the repository-root .venv, installs Maturin there if needed, and installs the matching native extension. Clean builds remove only the selected Cargo profile and staged output; with --python, they also recreate the venv. On Linux, before rebuilding, the workflow stops this user's running executables from that profile's staged tree.

Python preview

The PyPI distribution is oapython; the imported package is oa:

python -m pip install oapython

Python follows the Rust module graph directly:

import oa

engine = oa.Engine()
one = oa.matrix.ones(engine, [2, 3])
two = oa.matrix.full(engine, [2, 3], 2.0)
total = oa.matrix.add(one, two)
assert total.to_list() == [3.0] * 6

For a source checkout, run from the repository root:

python -m venv .venv
.venv/bin/pip install maturin
.venv/bin/maturin develop
.venv/bin/python -m unittest discover -s test/py -v

The native PyO3 implementation and the importable oa package live in src/py/pyo3 (src/py/pyo3/*.rs for the PyO3 crate source, src/py/oa/ for the package). Root pyproject.toml and uv.lock own the checkout-wide Python environment and distribution metadata; the PyO3 crate manifest, examples, and tutorials live in sdk/py. Neither creates a second runtime or CPU implementation.

Release artifacts

Every public release is assembled by the tagged CI workflow and publishes:

  • an exact Rust source archive with the resolved Cargo.lock;
  • a Linux x86-64 SDK archive containing the runnable tutorials, benchmarks, and applications staged from the same Release build;
  • matching oa-sdk packages for Debian, RPM, and Arch Linux;
  • one portable CPython 3.10+ ABI3 wheel, published to PyPI and then downloaded back from PyPI before attachment to GitHub;
  • dependency and toolchain evidence plus one checksum manifest covering every downloadable artifact.

The Rust crate currently links into its consumers and does not expose a stable C ABI. Consequently these releases do not label an internal Rust dylib as an OA runtime .so; a separate oa runtime system package is Planned for the checkpoint that introduces a supported dynamic-library boundary. The Python wheel does contain and test its native ABI3 extension.

GitHub-hosted validation proves the host and compilation contracts. Tests that require a real GPU remain explicit capability gates and are not silently reclassified as CPU-Vulkan validation.

Verification

.venv/bin/python -m unittest discover -s test/py -v
python3 tool/oa gen fn --check
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
git diff --check

Hardware tests are explicitly ignored by the default harness and run serially on admitted devices. See test organization.

SDK and source reference

OA is licensed under the Business Source License 1.1. See LICENSE.