[AAASM-55] ✨ (ffi): Implement PyO3 async IPC bridge runtime core

.github/workflows/native-core-build.yml

@@ -0,0 +1,36 @@
+name: Native Core Build Check
+
+on:
+  pull_request:
+    paths:
+      - "rust/**"
+      - "agent_assembly/**"
+      - ".github/workflows/native-core-build.yml"
+  workflow_dispatch:
+
+jobs:
+  build-native-core:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+      uses: actions/checkout@v5
+
+      - name: Setup Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.13"
+
+      - name: Setup uv
+      uses: astral-sh/setup-uv@v6
+
+      - name: Setup Rust
+      uses: dtolnay/rust-toolchain@stable
+
+      - name: Build native module with maturin
+      env:
+        PYO3_USE_ABI3_FORWARD_COMPATIBILITY: "1"
+      run: uv tool run maturin develop --manifest-path rust/aa-ffi-python/Cargo.toml --release
+
+      - name: Verify native module import
+      run: |
+        uv run python -c "from agent_assembly._core import RuntimeClient, GovernanceEvent, PolicyResult"

.gitignore

@@ -26,6 +26,10 @@ build/
 dist/
 *.egg-info/
 
+## Rust build artifacts
+rust/target/
+rust/Cargo.lock
+
 ## Script
 scripts/ci/get-all-tests.sh
 

README.md

@@ -89,6 +89,27 @@ uv run ruff check .
 uv run mypy agent_assembly
 ```
 
+## Native Core Extension (AAASM-55)
+
+Build and install the PyO3 extension locally:
+
+```bash
+uv tool run maturin develop --manifest-path rust/aa-ffi-python/Cargo.toml --release
+```
+
+Validate native module import:
+
+```python
+from agent_assembly._core import RuntimeClient, GovernanceEvent, PolicyResult
+```
+
+Run opt-in native integration tests:
+
+```bash
+AAASM_RUN_NATIVE_CORE_TESTS=1 uv run pytest test/integration/test_native_core_runtime.py
+AAASM_RUN_MATURIN_TESTS=1 uv run pytest test/integration/test_native_core_maturin.py
+```
+
 ## Documentation
 
 - Project docs source: `docs/`

agent_assembly/__init__.py

@@ -12,6 +12,16 @@
     ToolExecutionBlockedError,
 )
 
+try:
+    from agent_assembly._core import (  # type: ignore[attr-defined]
+        GovernanceEvent,
+        PolicyResult,
+        PolicyTimeoutError,
+        RuntimeClient,
+    )
+except ImportError:
+    pass
+
 __version__ = "0.0.0"
 
 __all__ = [
@@ -28,3 +38,13 @@
     "AdapterValidationError",
     "ToolExecutionBlockedError",
 ]
+
+if "RuntimeClient" in globals():
+    __all__.extend(
+        [
+            "RuntimeClient",
+            "GovernanceEvent",
+            "PolicyResult",
+            "PolicyTimeoutError",
+        ]
+    )

rust/Cargo.toml

@@ -0,0 +1,3 @@
+[workspace]
+members = ["aa-ffi-python"]
+resolver = "2"

rust/aa-ffi-python/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "aa-ffi-python"
+version = "0.0.0"
+edition = "2021"
+description = "PyO3 bridge crate for the Agent Assembly Python SDK"
+license = "MIT"
+
+[lib]
+name = "aa_ffi_python"
+crate-type = ["cdylib"]
+
+[dependencies]
+aa-core = { git = "https://github.com/AI-agent-assembly/agent-assembly.git", package = "aa-core", features = ["serde"] }
+aa-proto = { git = "https://github.com/AI-agent-assembly/agent-assembly.git", package = "aa-proto" }
+once_cell = "1.20"
+prost = "0.13"
+pyo3 = { version = "0.20", features = ["extension-module"] }
+pyo3-asyncio = { version = "0.20", features = ["tokio-runtime"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+tokio = { version = "1.41", features = ["io-util", "net", "rt-multi-thread", "sync", "time"] }

rust/aa-ffi-python/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["maturin>=1.7,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "agent-assembly-core"
+version = "0.0.0"
+description = "Native core extension for Agent Assembly Python SDK"
+requires-python = ">=3.12,<4.0"
+
+[tool.maturin]
+python-source = "../.."
+module-name = "agent_assembly._core"
+features = ["pyo3/extension-module"]