feat: add Python bindings for batch kernel execution via PyO3

Introduce `rustkernel-python` crate providing native Python access to all
106 batch kernels. Users can `pip install rustkernels` and call kernels
directly from Python/Jupyter without a REST/gRPC server.

- PyKernelRegistry with discovery (by_domain, by_mode, search) and execute
- Module-level convenience functions (execute, list_domains, enabled_domains)
- Exception hierarchy mapping all KernelError variants
- GIL-releasing async bridge (py.allow_threads + internal tokio runtime)
- Feature pass-through mirroring the facade crate (--features full)
- Python package README, CHANGELOG, publish-python.sh script
- CI job for Python 3.10/3.12 matrix (maturin develop + pytest)
- Crate excluded from default-members (requires Python dev headers)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mivertowski

.github/workflows/ci.yml

@@ -258,3 +258,39 @@ jobs:
       - name: Run security audit
         working-directory: RustKernels/RustKernels
         run: cargo audit
+
+  python-bindings:
+    name: Python Bindings
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: RustKernels/RustKernels
+
+      - name: Checkout RustCompute
+        uses: actions/checkout@v4
+        with:
+          repository: mivertowski/RustCompute
+          path: RustCompute/RustCompute
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install maturin and pytest
+        run: pip install maturin pytest
+
+      - name: Build and install Python package
+        working-directory: RustKernels/RustKernels/crates/rustkernel-python
+        run: maturin develop --features full
+
+      - name: Run Python tests
+        working-directory: RustKernels/RustKernels/crates/rustkernel-python
+        run: pytest tests/ -v

.gitignore

@@ -20,6 +20,17 @@ target
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
 
+# Python artifacts
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.venv/
+dist/
+*.whl
+*.so
+*.pyd
+
 # Generated documentation
 docs/book/
 docs/rustkernels-executive-overview.aux

CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2025-05-15
+
+### Added
+
+- **Python bindings** (`rustkernel-python`) — native Python access to all 106 batch kernels via PyO3
+  - `pip install rustkernels` for Python 3.10+
+  - `KernelRegistry` class with discovery (`kernel_ids`, `by_domain`, `search`) and `execute()` for batch kernels
+  - Module-level `execute()` convenience function with cached default registry
+  - Catalog API: `list_domains()`, `total_kernel_count()`, `enabled_domains()`
+  - Full exception hierarchy mapping all `KernelError` variants
+  - GIL-releasing async bridge (`py.allow_threads()` + internal tokio runtime)
+  - Feature pass-through: `--features full` enables all 14 domains
+  - `scripts/publish-python.sh` for PyPI publishing via maturin
+- **Deep RingKernel 0.4.2 integration** across all crates
+  - Bidirectional `Domain` conversion between RustKernels and RingKernel
+  - Re-exports: `ControlBlock`, `Backend`, `KernelStatus`, `RuntimeMetrics`, `K2KConfig`, `Priority`
+  - Submodule re-exports: `checkpoint`, `dispatcher`, `health`, `pubsub`
+- **Production-ready kernel execution** — all 106 kernels fully implemented with real dispatch (no stubs)
+- **Enterprise modules** in `rustkernel-core`:
+  - Security: JWT/API key auth, RBAC, multi-tenancy, secrets management
+  - Observability: Prometheus metrics, OTLP tracing, structured logging, SLO alerting
+  - Resilience: circuit breakers, exponential retry, timeout propagation, health probes
+  - Runtime: lifecycle state machine, graceful shutdown, production config presets
+  - Memory: size-stratified pools, pressure handling, inter-phase reductions
+- **Ecosystem service layer** (`rustkernel-ecosystem`):
+  - Axum REST API (`KernelRouter`)
+  - Tower middleware (timeout, rate limiting)
+  - Tonic gRPC server (`KernelGrpcServer`)
+  - Actix actor integration (`KernelActor`)
+- **New kernels**:
+  - Graph: `GNNInference`, `GraphAttention`
+  - ML: `EmbeddingGeneration`, `SemanticSimilarity`, `SecureAggregation`, `DrugInteractionPrediction`, `ClinicalPathwayConformance`, `StreamingIsolationForest`, `AdaptiveThreshold`, `SHAPValues`, `FeatureImportance`
+  - Process Intelligence: `DigitalTwin`, `NextActivityPrediction`, `EventLogImputation`
+- **K2K coordination** patterns: `IterativeState`, `ScatterGatherState`, `FanOutTracker`, `PipelineTracker`
+- **Type-erased batch execution** via `KernelRegistry::execute_batch(kernel_id, json_bytes)`
+- **CLI tool** (`rustkernel-cli`) for kernel management
+
+### Changed
+
+- Workspace expanded to 20 crates (added `rustkernel-python`)
+- `rustkernel-python` excluded from `default-members` (requires Python dev headers)
+- `pyo3 = "0.23"` added to workspace dependencies
+
+## [0.3.0] - 2025-03-01
+
+### Added
+
+- Initial 14-domain workspace with 106 kernel stubs
+- Core traits: `GpuKernel`, `BatchKernel`, `RingKernelHandler`, `IterativeKernel`
+- Kernel registry with typed factory registration
+- Domain-based licensing system
+- Proc macro derive: `#[gpu_kernel]`, `#[derive(KernelMessage)]`
+
+[0.4.0]: https://github.com/mivertowski/RustKernels/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/mivertowski/RustKernels/releases/tag/v0.3.0

Cargo.lock

@@ -20,6 +20,30 @@ members = [
     "crates/rustkernel-audit",
     "crates/rustkernel-cli",
     "crates/rustkernel-ecosystem",
+    "crates/rustkernel-python",
+]
+
+# Exclude rustkernel-python from default builds (requires Python dev headers + maturin)
+default-members = [
+    "crates/rustkernels",
+    "crates/rustkernel-core",
+    "crates/rustkernel-derive",
+    "crates/rustkernel-graph",
+    "crates/rustkernel-ml",
+    "crates/rustkernel-compliance",
+    "crates/rustkernel-temporal",
+    "crates/rustkernel-risk",
+    "crates/rustkernel-banking",
+    "crates/rustkernel-behavioral",
+    "crates/rustkernel-orderbook",
+    "crates/rustkernel-procint",
+    "crates/rustkernel-clearing",
+    "crates/rustkernel-treasury",
+    "crates/rustkernel-accounting",
+    "crates/rustkernel-payments",
+    "crates/rustkernel-audit",
+    "crates/rustkernel-cli",
+    "crates/rustkernel-ecosystem",
 ]
 
 [workspace.package]
@@ -149,6 +173,9 @@ quote = "1.0"
 proc-macro2 = "1.0"
 darling = "0.20"
 
+# Python bindings
+pyo3 = { version = "0.23", features = ["extension-module"] }
+
 # Runtime registration
 inventory = "0.3"