[AAASM-1215] 🔧 (build): Configure maturin build backend for platform wheel generation#53
Merged
Chisanan232 merged 9 commits intoMay 23, 2026
Conversation
Platform-tagged wheels with bundled Rust binary require maturin (PyO3 build tool). Hatchling's pure-Python wheel backend cannot produce per-platform wheels needed for the [runtime] extra. AAASM-1215
Wires maturin to the existing rust/aa-ffi-python crate. module-name matches the #[pyclass(module = "agent_assembly._core")] annotation in rust/aa-ffi-python/src/lib.rs so the compiled cdylib lands at agent_assembly/_core inside the wheel. python-source = "." tells maturin the pure-Python package root is the repo root (i.e. the agent_assembly/ tree alongside pyproject.toml). AAASM-1215
include with format="wheel" pulls the sidecar binary into the wheel artifact only (not sdist), matching where runtime.py's WHEEL_BUNDLED_BIN already searches. Listed unconditionally — maturin skips entries whose path is missing on disk, so non-runtime builds still succeed without the binary. The .exe entry is forward-looking for the Phase 2 Windows wheel target; current matrix omits it. AAASM-1215
Hatchling is no longer the build backend; its sdist/wheel target config is dead config. Maturin's own python-source + include settings cover the same inclusion concerns. AAASM-1215
This was referenced May 22, 2026
…g.toml CI runs uv sync on Python 3.13. With the new maturin build backend, uv sync triggers an editable maturin build → cargo build → pyo3-ffi build script, which errors because pyo3 0.20 (current pin in aa-ffi-python) caps at CPython 3.12. Place the env var in rust/.cargo/config.toml so Cargo (and its child build scripts) see PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 for every aa-ffi-python build, without touching CI workflows or the external reusable workflow that runs uv sync. The forward-compat flag uses the stable Python ABI subset, which is already what abi3 wheels target — safe for the existing crate. AAASM-1215
Cargo discovers .cargo/config.toml by walking PARENT directories of the current working directory (not the manifest directory). When maturin pep517 invokes cargo, the cwd is the python-sdk repo root, not rust/. The previous placement at rust/.cargo/config.toml was never picked up — CI re-ran with the same pyo3-ffi 3.12 ceiling error. Move to .cargo/config.toml at the repo root so cargo finds it regardless of which workspace it's building. AAASM-1215
Hybrid setup: hatchling builds the universal SDK wheel that `pip install agent-assembly` and `uv sync` resolve, while maturin is retained under [tool.maturin] for the release workflow's CLI invocation (AAASM-1217). Why: switching the pep517 backend to maturin forced `uv sync` to compile the Rust extension on every CI shard, which then required the full Rust toolchain (cargo) + protobuf-compiler on each runner (aa-proto's build.rs invokes protoc) — none of which the existing test workflows provide. The native module is already optional at runtime (tests skip when _core isn't built), so keeping the SDK install pure-Python preserves that pattern. Platform wheels are still produced by maturin-action in release-python.yml, which doesn't read [build-system]. AAASM-1215
Companion to the previous commit's hatchling restore. Hatchling needs explicit packages = ["agent_assembly"] to know which directory to bundle into the sdist + universal wheel. AAASM-1215
The PYO3_USE_ABI3_FORWARD_COMPATIBILITY env var was only needed because uv sync triggered the pep517 maturin build chain on Python 3.13 (pyo3 0.20 ceiling). With hatchling restored as the install-time build backend, the Rust extension is no longer built during uv sync; the env var becomes dead config. maturin-action in release-python.yml will still need the forward-compat flag at build time — that's set inline in the workflow's env block (see native-core-build.yml for the established pattern), not via .cargo/config.toml. AAASM-1215
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Configures
[tool.maturin]inpyproject.tomlso AAASM-1217's release workflow (PR #55) can invoke maturin viamaturin-actionto produce per-platform wheels with theaasmsidecar binary bundled atagent_assembly/bin/aasm.Hybrid build-backend architecture
The original AC of AAASM-1215 said "Add
maturinas the build backend in[build-system]". The literal switch was applied in the first commits, but CI surfaced a real architectural cost:uv sync(run by every test shard) would invoke maturin's pep517 hookcargo buildof theaa-ffi-pythoncrate on every shardaa-ffi-pythontransitively needsaa-proto, whosebuild.rsrequiresprotocon the runnerpyo30.20 caps at Python 3.12 while CI runs Python 3.13 (needsPYO3_USE_ABI3_FORWARD_COMPATIBILITY=1env)_corewhen the native module isn't built — making the rust build duringuv syncnet-negativeAfter confirming with @bulls23mj1991, this PR adopts a hybrid backend:
pip install agent-assembly/uv syncrelease-python.yml)maturin-action)agent_assembly/bin/aasmbundledNet diff vs master is 15 lines added — just the new
[tool.maturin]block.maturin-actionreads[tool.maturin]directly via CLI and doesn't require it to be set as the pep517 backend.Type of Change
Breaking Changes
Install path unchanged. New maturin tooling is dormant until the AAASM-1217 release workflow invokes it.
Related Issues
Testing
Local validations:
python -c "import tomllib; tomllib.loads(open('pyproject.toml').read())"parses cleanlyuv lock --check— runtime deps unchanged, lock still in sync[tool.maturin].module-name = "agent_assembly._core"matches the existing#[pyclass(module = "agent_assembly._core")]annotation inrust/aa-ffi-python/src/lib.rsEnd-to-end exercise of the maturin path (with
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1set at the workflow env block) is the verification scope of AAASM-1217 + AAASM-1219.Checklist
Commit trail
Initial attempt (build-backend = maturin) and subsequent investigation:
Hybrid revert after CI showed protoc dependency would explode CI scope:
The commit history preserves the investigation so reviewers see why the hybrid was chosen.