Imported from terrene-foundation/kailash-coc-claude-rs (.claude/skills/06-python-bindings/SKILL.md). Install upstream with npx skills add terrene-foundation/kailash-coc-claude-rs --skill 06-python-bindings. Copyright stays with the author.

Python Bindings — Quick Reference

PyO3-based binding distributed as pip install kailash-enterprise. Import as import kailash.

Key Facts

Binding Scale (v3.12.0)

Total: 667 pyclass types + 27 pyfunctions across 20+ source files. Expanded from 392 types in v3.11.0.

New Files (v3.12.0)

Registered PyO3 Modules

v3.9.0 Binding Modules

align_serving (1299 lines, feature-gated align-serving, enabled by default)

Wraps kailash-align-serving. 16 PyO3 types (PR #344). Uses MockServingBackend by default (llama.cpp backend requires C++ compilation).

Source: bindings/kailash-python/src/align_serving.rs

pact (2634 lines, feature-gated)

Wraps kailash-pact + kailash-governance. 28 PyO3 types covering the full PACT governance surface.

Core: PactAddress (D/T/R parsing), PactGovernanceEngine (thread-safe, fail-closed), PactGovernanceContext (read-only snapshot), PactGovernedAgent (agent with enforcement).

Envelopes & clearance: PactRoleEnvelope, PactTaskEnvelope, PactEffectiveEnvelopeSnapshot, PactClassificationLevel, PactRoleClearance.

Organization: PactCompiledOrg, PactOrgNode, PactRoleSummary, PactVacancyDesignation, PactVacancyStatus.

Decisions: PactGovernanceVerdict, PactAccessDecision, PactEnforcementMode, PactGradientZone, PactApprovalState.

Bridge & knowledge: PactBridge, PactKnowledgeItem, PactKnowledgeSharePolicy, PactBridgeApprovalStatus.

RBAC export: RbacCell, RbacMatrix (CSV, JSON, Markdown export).

Held actions: PactHeldAction, PactMemoryHeldActionStore.

Source: bindings/kailash-python/src/pact.rs

orchestration (4664 lines, feature-gated)

Wraps kaizen-agents orchestration layer. 64 PyO3 types — the largest binding module.

Supervisor: OrchGovernedSupervisor (main entry), OrchSupervisorConfig, OrchSupervisorResult.

Monitor: OrchPlanMonitor, OrchMonitorConfig, OrchMonitorResult, OrchGovernanceHooks.

Governance: OrchAccountabilityTracker, OrchAccountabilityRecord, OrchClearanceEnforcer, OrchDimensionSnapshot, OrchGovernanceSnapshot.

Budget: OrchGovernanceBudgetTracker, OrchBudgetSnapshot, OrchBudgetEvent, OrchBudgetWarning, OrchBudgetWarningConfig, OrchBudgetWarningZone, OrchBudgetEventType.

Lifecycle: OrchAgentLifecycleManager, OrchAgentRecord, OrchLifecycleState.

Cascade & vacancy: OrchCascadeManager, OrchCascadeEvent, OrchCascadeTrigger, OrchVacancyManager, OrchVacancyEvent, OrchVacancyAction, OrchOrphanType.

Dereliction & bypass: OrchDerelictionDetector, OrchDerelictionWarning, OrchDerelictionConfig, OrchDerelictionSeverity, OrchBypassManager, OrchBypassRecord.

Audit & reasoning: OrchAuditTrail, OrchAuditRecord, OrchAuditEventType, OrchReasoningStore, OrchReasoningRecord, OrchTraceEmitter.

Transport: OrchMessageTransport, OrchTransportEnvelope, OrchTransportPayload.

History: OrchConversationHistory, OrchConversationTurn, OrchHistoryConfig, OrchTurnRole.

PACT bridge: OrchPactMcpBridge, OrchPactEngineConfig, OrchMcpVerdict, OrchToolPolicy, OrchAgentContext.

Enums: OrchClearanceLevel, OrchAccountabilityOutcome, OrchDutyType, OrchOrchestrationDecision, OrchEscalationSeverity, OrchRejectionRecord, OrchHeldAction.

Source: bindings/kailash-python/src/orchestration.rs

Value Mapping (Rust <-> Python)

Quick Patterns

Build and install locally

cd bindings/kailash-python
cargo clean -p kailash-python   # Prevent stale binary
maturin develop --release

Register a Python callback as a node

import kailash
reg = kailash.NodeRegistry()
reg.register_callback("MyNode", my_func, ["input"], ["output"])

v2 API (current)

reg = kailash.NodeRegistry()
builder = kailash.WorkflowBuilder()
builder.add_node("NoOpNode", "n1", {})
wf = builder.build(reg)
rt = kailash.Runtime(reg)
result = rt.execute(wf, {})

API Changes (v3.12.0 Convergence)

Breaking changes from the convergence branch that affect binding consumers:

• WorkerAgent::new(name, inner) returns Result — name validation added (^[a-z][a-z0-9_-]{2,63}$). Callers must use ? or .expect().
• SupervisorAgent::new() requires 4 args — (name, workers, routing, max_delegation_depth). The routing arg is Arc<dyn RoutingStrategy> (use RoundRobin::new() for tests).
• with_description() takes String and returns Result<&mut Self, WorkerError> — must split from builder chain into separate statements.
• CallerEvent has new ToolCallDelta variant — all match expressions must be exhaustive.
• BudgetExhausted variant added to CallerEvent — streaming consumers must handle budget termination.
• Debug output standardized to snake_case — e.g., Zone::Active now prints as active.
• 16 new convergence types exported — EatpJwtClaims, PyTrustPostureLevel, PyRoutingStrategy, PyAuditEvent, etc.

Cross-SDK Test Fixtures (v3.12.0+)

Canonical JSON fixtures at workspaces/platform-architecture-convergence/01-analysis/test-vectors/:

• agent-result-wire-v1.json — AgentResult wire format (SPEC-09 section 3.3)

Parity tests: crates/kailash-kaizen/tests/cross_sdk_agent_result.rs, crates/eatp/tests/cross_sdk_envelope.rs, crates/trust-plane/tests/cross_language.rs, crates/kailash-mcp/tests/cross_sdk_jsonrpc.rs.

Binding Gotchas (v3.12.0 Red Team Findings)

These patterns were discovered during the 392-to-667 type expansion and validated by red team cycles.

ML Python Bindings

126 estimator classes + 30 functions wrapping kailash-ml. Feature-gated behind ml (enabled by default).

Module Coverage

Usage

from kailash.ml import LinearRegression, StandardScaler, Pipeline

scaler = StandardScaler()
model = LinearRegression()
pipe = Pipeline([("scaler", scaler), ("model", model)])

Skill Files

Related

• python-binding agent — PyO3 implementation specialist
• python-pattern-expert agent — Debugging PyO3 errors
• rules/release.md — Wheel build and PyPI publishing rules