xqffi 0.2.0

PyO3 FFI bindings exposing the XQuad Rust runtime (xqvm + xqasm) to Python

xqffi — PyO3 FFI bindings for the XQuad Rust runtime

The Python extension that exposes the Rust xqvm interpreter and xqasm assembler. Ships as a manylinux wheel built by maturin.

xqffi is a pure FFI shim — it only re-exposes the Rust types and entry points. User-facing conveniences (Program / Session / RunResult, keyword calldata, trace inspection) live in the xquad umbrella package.

Install

pip install xqffi

Surface

xqffi.vm — low-level one-shot

What the conformance harness drives. Small wrapper over xqvm::Vm:

from xqffi.vm import Vm
from xqffi.asm import assemble_source

vm = Vm()
vm.set_calldata([40, 2])
vm.set_output_slots(1)
vm.run(assemble_source(src))
assert vm.outputs() == [42]

XqmxModel and XqmxSample are thin getter/setter wrappers around the Rust types for direct model/sample manipulation.

xqffi.asm — assembly

parse_xqasm(str) → wire dict; assemble_source(str) → raw bytes; disassemble(bytes) → human-readable listing; instruction_count(bytes) → instruction count.

Interactive / multi-run API

Use xquad.program for the REPL / notebook / script workflow:

from xquad.program import Program

program = Program.from_source(src)
session = program.session(output_slots=1)
session.set_calldata([40, 2])
result = session.run()
assert dict(result.outputs) == {0: 42}

Program.load(bytes) takes wire-format bytecode; Session.run() returns a RunResult with dict-keyed outputs (unset slots present as None), residual stack, and step count.

Also see

• xqvm_py — pure-Python reference VM (conformance oracle).
• xqcp — constraint programming DSL that compiles to .xqasm.
• xqsa — solver adapters (dwave-neal).
• xquad — umbrella meta-package with the interactive API.
• docs/python-api-walkthrough.md — full tour.

License

AGPL-3.0-or-later.