feat: Python bindings (PyO3) (#70)

* docs: add requirements document for python bindings

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

* docs: minor update

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

* docs: add issue 19 implementation plan

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

* docs: add ce implementation plan for issue 19

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

* feat(bindings/python): add PyO3 native bindings for cpex-core PluginManager

Introduces `bindings/python/` — a new maturin-built Rust crate (`cpex-python`)
that wraps `cpex_core::PluginManager` via PyO3 0.29, exposing a native Python
`cpex` package backed entirely by the Rust runtime.

Key design points:
- `PluginManager(config_path)` — sync constructor; registers APL factories then
  loads YAML config (order critical for APL Weak upgrade)
- `initialize()`, `shutdown()`, `invoke_hook()` — async via pyo3-async-runtimes
  `future_into_py`; all guarded by a 60 s wall-clock timeout (PY_WALL_CLOCK_TIMEOUT)
- CMF hooks route payloads through `MessagePayload`; all others use a local
  `GenericPayload<serde_json::Value>`
- `PipelineResult` exposes 7 read-only Python getters; `__repr__` is pointer-free
- `cpex-python` is in `[workspace] members` but not `default-members`, so all
  pure-Rust CI targets remain libpython-independent (`--exclude cpex-python`)
- Makefile gains `bindings-python-{build,build-release,test}` targets
- 22 unit/integration tests; all pass alongside 2058 legacy tests (AE3)

Signed-off-by: habeck <habeck@us.ibm.com>

* chore: Fixed the Python bindings build after the dev branch merge: updated Cargo.toml and builtins.rs to use the new cpex-builtins facade, then resolved two clippy lint failures.

Signed-off-by: habeck <habeck@us.ibm.com>

* chore: remove unused dependencies

Signed-off-by: habeck <habeck@us.ibm.com>

* enh: build and test bindings/python in ci

Signed-off-by: habeck <habeck@us.ibm.com>

* chore: Added panic isolation and timeout coverage to the Python bindings.

Signed-off-by: habeck <habeck@us.ibm.com>

* chore: run cargo update with env set: CARGO_REGISTRIES_CRATES_IO_PROTOCOL=sparse

Signed-off-by: habeck <habeck@us.ibm.com>

* fix: drop swatinem/rust-cache.  rust-cache restores a partial `~/.cargo/registry` index ("full match: false"); with the sparse protocol, , `cargo package --locked` consults that stale local index, finds it can't satisfy the committed lock, and aborts with "cannot update the lock file" (fails ~1.4s in — too fast for a real network fetch) even though Cargo.lock resolves cleanly against a fresh index. Fetching the index fresh each run keeps this dry-run deterministic.

Signed-off-by: habeck <habeck@us.ibm.com>

* fix: Removing the index forces a clean fetch, against which Cargo.lock resolves cleanly — keeping this dry-run deterministic.

Signed-off-by: habeck <habeck@us.ibm.com>

* chore: cargo lock update

Signed-off-by: habeck <habeck@us.ibm.com>

---------

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>
Signed-off-by: habeck <habeck@us.ibm.com>
Co-authored-by: Frederico Araujo <frederico.araujo@ibm.com>
Co-authored-by: Teryl Taylor <terylt@ibm.com>

Author: 3 people

.github/workflows/ci.yml

@@ -109,15 +109,28 @@ jobs:
           fetch-depth: 1
       - name: Install Rust 1.96.0
         uses: dtolnay/rust-toolchain@1.96.0
-      - uses: Swatinem/rust-cache@v2
+      # NOTE: intentionally NO Swatinem/rust-cache here, AND we wipe the registry
+      # index before packaging. The committed Cargo.lock is byte-identical to a
+      # fresh x86_64 resolution (verified in an amd64 container), so the lock is
+      # not the problem. The failure comes from stale `~/.cargo/registry` state
+      # the hosted runner carries: under the sparse protocol `cargo package
+      # --locked` consults that partial local index, decides it can't satisfy the
+      # committed lock, and aborts with "cannot update the lock file ... --locked"
+      # ~1.4s in (too fast for a real network fetch). Removing the index forces a
+      # clean fetch, against which Cargo.lock resolves cleanly — keeping this
+      # dry-run deterministic.
       # Continuous dry-run of the crates.io release: build + verify a .crate for
       # every publishable member without uploading. Catches publishability
       # regressions (missing version reqs, packaging-excluded files, broken
       # inter-crate deps) on every push/PR, long before a release tag. Mirrors
       # `make publish-dry` and the release workflow's dry-run. The two
       # `publish = false` FFI crates are excluded (not part of the registry set).
       - name: cargo package (no upload)
-        run: cargo package --workspace --locked --exclude cpex-ffi --exclude cpex-demo-ffi
+        run: |
+          # Drop any pre-seeded registry index/cache so cargo fetches fresh and
+          # --locked resolves against a clean index (see note above).
+          rm -rf ~/.cargo/registry/index ~/.cargo/registry/cache
+          cargo package --workspace --locked --exclude cpex-ffi --exclude cpex-demo-ffi
 
   docs:
     name: Docs Build

.github/workflows/release.yaml

@@ -70,7 +70,11 @@ jobs:
       - uses: actions/checkout@v7
       - name: Install Rust 1.96.0
         uses: dtolnay/rust-toolchain@1.96.0
-      - uses: Swatinem/rust-cache@v2
+      # NOTE: intentionally NO Swatinem/rust-cache here. A restored partial
+      # `~/.cargo/registry` index makes `cargo package/publish --locked` abort
+      # with "cannot update the lock file" against the sparse index even when
+      # Cargo.lock is correct (see the CI `package` job for the full rationale).
+      # A fresh index each run keeps publish resolution deterministic.
       - name: cargo publish (dependency order)
         env:
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}