Metadata-Version: 2.1
Name: oapython
Version: 0.7.0
Summary: OA — Vulkan GPU compute & ML foundation library (SUPER EXPERIMENTAL Python bindings)
Author: Lukasz Biernat
License: BUSL-1.1
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: POSIX :: Linux
Project-URL: Homepage, https://github.com/realminc/oa
Project-URL: Source, https://github.com/realminc/oa
Requires-Python: >=3.9
Requires-Dist: numpy
Description-Content-Type: text/markdown

![OA — Realm Foundation Library](assets/hero-21x9.jpg)

# OA — Realm Foundation Library

Vulkan 1.4 compute substrate. Types, memory, GPU engine, ML primitives, crypto.
Shaders in Slang. No CUDA. No ROCm.

## Quick Start

```cpp
#include <Oa/Oa.h>                 // Everything
#include <Oa/Runtime/Engine.h>     // Compute engine only
#include <Oa/Core/Memory.h>        // e.g. AVX2 memcpy

int main() {
	auto rt = OaEngine::Create({.AppName = "MyApp"}).Unwrap();
	// ...
	rt.Destroy();
}
```

## Install

### Arch Linux (AUR)

Prebuilt (fast — pulls the release binaries):

```bash
yay -S oa-bin oa-sdk-bin        # or: paru -S oa-bin oa-sdk-bin
```

Or build from source (tracks the latest tagged release):

```bash
yay -S oa-git oa-sdk-git
```

`oa-bin`/`oa-git` install the runtime library; the `-sdk-*` packages add the headers,
CMake config, and shader sources needed to build against OA.

### Other Linux

Download from the [latest release](https://github.com/realminc/oa/releases) — a
universal tarball plus `.deb` / `.rpm` / `.pkg.tar.zst`:

```bash
tar -xzf oa-<ver>-linux-x86_64.tar.gz -C /usr/local          # runtime
tar -xzf oa-sdk-<ver>-linux-x86_64.tar.gz -C /usr/local      # + dev files
```

The `.deb` / `.rpm` are convenience prebuilts and require **glibc ≥ 2.39**
(Ubuntu 24.04+ / Debian 13+ / Fedora 39+). Verify with `sha256sum -c SHA256SUMS.txt`.

### Python (super experimental)

```bash
pip install oapython        # import oa
```

## Build

```bash
cmake --preset release && ninja -C Build/Release
cd Build/Release && ctest --output-on-failure
cmake --install Build/Release --prefix ~/.local
```

Consumers link via vcpkg (`find_package(oa CONFIG REQUIRED)`) or `CMAKE_PREFIX_PATH`.

## Layout (golden rule)

Public API lives under `Source/Public/Oa/` (installed as `#include <Oa/...>`). Implementations and internal-only code under `Source/Private/Oa/`. Tests under `Test/`. On-disk public headers use **PascalCase** (e.g. `OaVk.h`, `OaVma.h`, `Engine.h`).

```
oa/
├── Source/Public/Oa/       # <Oa/Oa.h>, <Oa/Core/*.h>, <Oa/Runtime/*.h>, …
├── Source/Private/Oa/      # .cpp/.c, internal headers, Slang under Ml/Shaders/, Vma/, …
├── Test/
├── Apps/
└── CMakeLists.txt
```

Vulkan loader and allocator: `Source/Private/Oa/Runtime/OaVk.c`, `OaVma.cpp` (implementation); public headers `Source/Public/Oa/Runtime/OaVk.h`, `OaVma.h`.

## Documentation

- **Docs & guides:** [dev.realm.software](https://dev.realm.software/)
- **Project home:** [realm.software](https://realm.software/)
- `Docs/Release.md` — release-readiness status and roadmap (in-repo)

## Supported hardware

| Hardware | Status | Notes |
|---|---|---|
| NVIDIA (Turing+) | Full | bf16 cooperative-matrix tensor cores; CoopVec GEMV decode on Blackwell+ |
| AMD RDNA3+ (RADV or proprietary) | Full | KHR cooperative-matrix bf16; RADV trusted on all gens |
| Intel Xe2+ (Lunar Lake / Battlemage) | Full | native coopmat + bf16 |
| Intel Xe pre-Xe2 (Tiger Lake etc.) / other iGPU | Compute (fp32) | coopmat + native bf16 auto-disabled (driver-trust gated); tiled fp32 path |
| CPU (lavapipe / SwiftShader) | Works, slow | for CI and correctness testing, not performance |

Cooperative-matrix and native bf16 are gated by a vendor/driver trust check (some
drivers advertise support they miscompile). Override with `OA_FORCE_COOPMAT=1` /
`OA_FORCE_BF16=1`, or force them off with `OA_DISABLE_COOPMAT=1` / `OA_DISABLE_BF16=1`.
Bindless buffer capacity is capped per device (1M discrete / 256K integrated) and
overridable with `OA_BINDLESS_BUFFER_CAP=N`.

## Benchmarks — Python at C++ throughput

The nanobind bindings call the *same* compute kernels as the C++ engine, so the Python
API pays no measurable tax. Byte-level NLP training, identical models, same Intel Xe iGPU:

| Model | Python wall/step | C++ wall/step | Accuracy (Py / C++) |
|---|---|---|---|
| RNN | 5.53 ms | 6.77 ms | 93.5 / 93.5 |
| GRU | 9.78 ms | 14.58 ms | 93.3 / 94.3 |
| GRU (char) | 9.03 ms | 14.62 ms | 93.5 / 94.2 |
| Transformer | 12.59 ms | 19.71 ms | 91.8 / 94.0 |
| Mamba-3 | 27.21 ms | 49.00 ms | 92.8 / 93.8 |

Both suites are GPU-bound on identical dispatch sequences; the nanobind layer is ~100 ns/call,
negligible against GPU-op latency. Wall-time gaps track async pipelining, not the binding.
*(Single run, n=5, iGPU GPU-timer sampling is ±20% indicative — read this as parity, not a
Python-beats-C++ claim.)*

## Status & limitations (0.7 preview)

This is a preview. The following are **experimental** (may be unstable; off by default):

- bf16 on drivers outside the trust list (auto-routes to fp32 unless forced)
- Bidirectional SSM scan in `MaskedTokenModel` / `EmpyrealmGen3dAnim` (training-unstable; warns at runtime)
- SSM models (Mamba-3, Empyrealm) and the generative training apps (MotionGPT / Gen3dAnim) — demo-quality
- Vulkan Video decode (H.264 / H.265 / AV1) — functional, some tails + benchmarks not finished
- Python bindings (nanobind) — **super experimental**, `OA_BUILD_PYTHON=OFF` by default.
  Preview wheels publish to PyPI as [`oapython`](https://pypi.org/project/oapython/) (`pip install oapython`;
  import stays `import oa`). Expect breakage — this is a tech preview, not a supported API.

**Not in this preview** (present but return an explicit error, not silently wrong):

- Multi-node distributed (`OaCluster` Send/Recv) — single-machine multi-GPU collectives work; cross-node returns `Unimplemented`
- MoE training — runs, but expert-FFN backward gradients are not precision-verified (don't rely on it for training)
- Video encode / transcode (`OaVideoTranscoder`) — returns an error

Test coverage is ~62% of ops. See [Docs/Release.md](Docs/Release.md) for the full gap analysis.

## License

[Business Source License 1.1](LICENSE). Copyright (c) 2025-2026 Lukasz Biernat (trading as Realm).

Source-available: you may read, copy, modify, and make non-production use
freely. Production use is permitted **except** offering OA as a competing
commercial ML/GPU-compute/inference product or service (see the Additional Use
Grant in [LICENSE](LICENSE)). Each version converts to **Apache-2.0** four years
after its release (Change Date 2030-07-09 for this one). For a commercial
license, contact realminc.depravity737@passinbox.com.

Third-party trademarks and interop-data attributions (Epic Games MetaHuman /
Unreal, Autodesk HumanIK / FBX, etc.) are recorded in [NOTICE.md](NOTICE.md).

## Support OA

OA is independent, self-funded work. If it's useful to you, funding helps keep
development moving.

- **GitHub Sponsors:** [github.com/sponsors/empyrealm](https://github.com/sponsors/empyrealm)
- **Bitcoin (BTC):** `bc1q732ytlwnmwys2at4wyd46zewj20n3s55xwq5yt`
- **USD Coin (USDC, ERC-20 / Ethereum):** `0x23Efe433cd0476b2d126120fEf4C1c5903b02250`

## Acknowledgments

OA stands on some excellent permissively-licensed work. In particular:

- **[volk](https://github.com/zeux/volk)** by Arseny Kapoulkine (MIT) — OA's Vulkan
  function loader (`OaVk`) is a hard fork of it. A genuinely great piece of software.
- **[Vulkan Memory Allocator](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator)**
  by AMD (MIT) — OA's GPU allocator (`OaVma`) is vendored from it.
- **[GLM](https://github.com/g-truc/glm)** (MIT), **[miniaudio](https://github.com/mackron/miniaudio)**
  by David Reid (public domain / MIT-0), and **[stb](https://github.com/nothings/stb)**
  by Sean Barrett (public domain).

Full license text and per-component details are in [NOTICE.md](NOTICE.md).