raptor

raptor: one manifest, any engine

A compiled GPU kernel ships with a small JSON file that says what it takes, what it returns and where it can run. raptor defines that file, so one package can build a kernel and another can run it.

Runs on: CPU, no GPU needed · You need: Python 3.9+, nothing else to install raptor itself

The RAPTOR family

raptor holds the shared contracts of the RAPTOR family: the manifest format and certification contracts that let a kernel built once work with the code you already have. See where RAPTOR fits for how the four pieces combine.

0	4	1
hard dependencies (pure Python)	array libraries certified: NumPy, CuPy, PyTorch, Warp, JAX	JSON manifest per kernel bundle (a kernel's compiled artifact(s) plus its manifest)

See it working: orbits from hand-written physics plus a small learned drag correction, trained in torch and compiled into one kernel — Demos points to the runnable examples.

Docs · the family site

For package authors

from raptor.schema import validate_manifest

manifest = {
    "schema_version": 2,
    "pattern": "pure",
    "aether_abi": "aether-abi/2",
    "exec_targets": ["host", "device"],
    "exec_access": "sample_local",
    "plugins": [{"id": "two_body_step", "order": 0, "enabled": True, "artifact": "two_body_step.ptx",
                "sidecar": "two_body_step.json", "format": "ptx"}],
}
validate_manifest(manifest)  # raises on a malformed or out-of-order document

key	meaning
schema_version	which rules this document follows
pattern	which kind of kernel this is; pure = no side effects
aether_abi	the binary-format tag paired with schema_version (e.g. "aether-abi/2" for v2)
exec_targets	host / device: where this kernel may run
exec_access	how it touches per-sample vs. cross-sample data
plugins	the compiled artifact(s) this manifest describes (ptx = NVIDIA's GPU assembly format)

Any class with a matching build(directory) method satisfies ManifestProvider — "duck typing": judged by which methods exist, checked with isinstance, never by which class it inherits from:

from raptor.protocols import ManifestProvider

class Bundle:
    def build(self, directory):
        return f"{directory}/manifest.json"

isinstance(Bundle(), ManifestProvider)  # True — duck-typed, no inheritance needed

Threading

Free-threaded CPython (3.13t/3.14t) is supported: the compiled modules declare GIL-free operation and the GIL stays disabled after import. Any number of threads may call module-level functions, build, compile, plan and cache concurrently. Distinct objects may be used from distinct threads without synchronisation. One stateful object (a stream, capture, launcher, graph, composer, plan, pipeline, active set, host kernel or arg block) shared by several threads is memory-safe — its calls serialise and a consumed object raises — but the ORDER of those calls is the caller's responsibility, exactly as for a NumPy array or a CuPy stream. CUDA adds two rules of its own: a stream capture is begun, filled and ended by one thread, and while any capture is open no thread may synchronise the whole device (stream-level synchronisation is fine). GPU routes are supported on free-threaded 3.14; on 3.13t the CPU route runs.

Install

pip install raptor-core      # Python 3.9+, no dependencies

The import name is raptor. The rest of the family (hawk, eagle) and the GPU extras: installation.

To work on the code, from a clone: git clone https://github.com/amasat01/raptor.git, then pip install -e .. Test with pip install pytest && pytest tests -m "not cross_repo" (-m "not cross_repo" leaves out the tests that check eagle against raptor's contracts — they need an eagle checkout next to this one, and fail rather than skip without it). To set up a development machine for the whole family, see tools/devbox/.

Demos

The runnable demos live with the packages they show off:

• hawk: the hybrid orbit (analytic physics plus a learned correction in one compiled kernel) and autodiff against torch.
• eagle: early termination with a conditional graph node, and zero-copy interop with NumPy, CuPy, PyTorch, Warp and JAX, with gradients certified.

The measured headline, from eagle's committed performance cards:

hawk + eagle (eagle.simulate) integrates 1,000,000 RK4 oscillators, each stopping at its own step, in 613 µs on an NVIDIA H100 80GB HBM3 (199 µs for 100,000), 2.5×–600× faster than NVIDIA Warp (2.5×), JAX (76×), CuPy (600×), PyTorch with torch.compile (130×) at N = 1,000,000 (1.1×–1700× at N = 100,000), in 40 MiB of GPU memory

Going deeper (optional)

Package internals, none of it needed to install or use raptor.

What's inside

• raptor.schema — the kernel-manifest schema, two layers: schema.manifest (the core layer every producer writes against) and schema.blocks (the neural_block extension; hawk never imports it). schema.dtypes carries the scalar-type tag vocabulary. raptor.schema.validate_manifest(doc) is a minimal shape validator (key order, top keys, schema_version, pattern vocabulary) — not a port of eagle's deep validate_sidecar. Schema versions 1 and 2 both load (manifest.MAX_SCHEMA_VERSION): v2 adds three flat, versioned top-level keys — exec_targets (device/host list), exec_access (sample_local / cross_sample_read / cross_sample_write / mapreduce), exec_op (required iff exec_access="mapreduce") — and requires aether_abi: "aether-abi/2"; v3 is v2 with cells replacing sample_sums in the sidecar; v1 rejects any exec_* key outright (manifest.check_execution_axis).
• raptor.protocols — the typing.Protocol definitions: Backend / Executable (program-level execution), KernelLauncher / Marshal (kernel-level launch/marshal, mirroring eagle's public surface 1:1), ManifestProvider (the kernel-provider protocol's one facet).
• raptor.conformance — the interop certification declaration (UNIVERSE / CERTIFIED / ROADMAP / ROWS) and its reusable matrix-hygiene scanners; the full row-by-row certification matrix is on the interop protocols page.
• goldens/ — the golden conformance corpus (harvested from eagle's test fixtures) that raptor.schema.validate_manifest is exercised against.
• tests/*cross_repo*: the eagle conformance battery (test_verbatim_against_eagle.py, test_goldens.py), marked cross_repo and failing rather than skipping when a sibling checkout is absent — deselected here only via -m "not cross_repo", run for real by the local gate and a downstream package's own CI. raptor.schema.manifest.SCHEMA_VERSION is the cross-repo pin (1; the highest accepted version is MAX_SCHEMA_VERSION, 2); eagle.roles.SCHEMA_VERSION derives from it directly, so no standalone text-scan cross-check is kept as a redundant leg.

---

hawk write it · eagle run it · aether the numerics core · raptor the shared contracts (this repo) — the RAPTOR family

Apache-2.0 (see LICENSE and NOTICE) · cite via "Cite this repository" (CITATION.cff; every tagged release is archived on Zenodo: doi:10.5281/zenodo.23250234) · built to make GPU computing accessible on modest hardware, for research and education. Collaboration is the point, and a citation is the currency — get in touch.