kailash-pact

PACT governance framework — D/T/R accountability grammar, operating envelopes, knowledge clearance, and verification gradient for AI agent organizations.

Part of the Kailash enterprise AI platform.

Quick Start

from pact.governance import GovernanceEngine

engine = GovernanceEngine.from_yaml("my-org.yaml")
verdict = engine.verify_action("D1-R1-T1-R1", "write_report", {"cost": 50.0})

if verdict.allowed:
    print("Approved:", verdict.reason)
else:
    print("Blocked:", verdict.reason)

Installation

pip install kailash-pact

With Kaizen agent integration:

pip install kailash-pact[kaizen]

Features

• D/T/R Grammar Engine — Accountability grammar (Department/Team/Role) with positional addressing
• Three-Layer Envelopes — Role (standing) + Task (ephemeral) = Effective (computed intersection)
• Knowledge Clearance — Five-level classification independent of authority/seniority
• 5-Step Access Enforcement — Clearance → Classification → Compartment → Containment → Deny
• GovernanceEngine — Single facade composing all primitives
• PactGovernedAgent — Wrap any Kaizen agent with governance enforcement
• SQLite/PostgreSQL Stores — Persistent governance state
• REST API — 9 governance endpoints with auth and rate limiting
• CLI — kailash-pact validate org.yaml

MCP Governance — Tenant Isolation (Pre-Pledge v0)

pact.mcp adds deterministic governance to MCP (Model Context Protocol) tool calls and resource reads, including first-class multi-tenant isolation (issue #1843, shipped in 0.16.0). Because kailash-pact is still pre-1.0, this section is an explicit pledge of what the tenant-isolation surface enforces today versus what remains open — read it before relying on McpGovernanceConfig.tenant_grants in a multi-tenant deployment.

• Enforced today: McpGovernanceConfig.tenant_grants (a dict[str, McpTenantGrant]) scopes both tools/call and resources/read to the caller's tenant through one shared, fail-closed restrictiveness function, evaluated before tool registration (so it applies even under DefaultPolicy.ALLOW). McpCallerIdentity.tenant — resolved by your transport/auth layer and passed to check_tool_call/check_resource_read — always overwrites a self-asserted metadata["tenant_id"], defeating impersonation. require_caller_identity defaults to True: with no trusted identity wired, the self-asserted body value is never trusted and the call fails closed rather than silently falling back to it.
• Deferred: resources/read has ONLY the tenant-isolation check today — no cost, argument, clearance, or rate-limit governance layer exists yet for that surface (that richer contract exists only for tools/call via McpToolPolicy). No first-class serialized tenant_id field exists on the wire envelope; tenant rides the existing free-form metadata["tenant_id"] channel by design (byte-neutral with the Rust SDK's frozen envelope) and may change if the ecosystems converge on a first-class field later.
• Non-promises: tenant_grants being empty is NOT "tenant isolation enabled with an empty allowlist" — it is isolation OFF entirely (every call auto-approved on that axis, byte-identical to pre-0.16.0 behavior). Passing require_caller_identity=False is NOT a recommended production setting — it exists only for deployments with no transport-level identity resolution, and re-enables the weaker, spoofable metadata fallback.
• Verify: pytest packages/kailash-pact/tests/regression/test_issue_1843_mcp_tenant_isolation.py -v exercises the fail-closed defaults, the impersonation-defeat contract, and the resources/read isolation-only surface end-to-end.
• Status: v0 within a pre-1.0 package (kailash-pact 0.16.0) — the isolation contract above is stable for this release; the deferred items may change shape (not just grow) before a 1.0 cut.

Documentation

• Quickstart — Zero to governance in 10 minutes
• Architecture — How it all fits together
• Vertical Guide — Build your own governed platform
• API Reference — REST endpoints
• Cookbook — Common patterns
• YAML Schema — Org definition format

Cross-SDK Conformance (PACT N4/N5)

The PACT N6 cross-SDK conformance contract pins byte-for-byte canonical JSON across language SDKs. The Python implementation lives in pact.conformance and drives the same vector files the Rust SDK does.

Run the runner programmatically

from pact.conformance import ConformanceRunner, load_vectors_from_dir

vectors = load_vectors_from_dir(
    "/path/to/kailash-rs/crates/kailash-pact/tests/conformance/vectors"
)
report = ConformanceRunner().run(vectors)
if not report.all_passed:
    raise SystemExit(report.render_failure_report())
print(f"PACT conformance: {report.passed}/{report.total} passed")

Run via pytest

The Tier 1 unit tests at tests/unit/conformance/test_runner.py::test_runner_passes_against_real_cross_sdk_vectors auto-discover the kailash-rs sibling checkout and exercise every vector. The test SKIPS gracefully when the sibling repo is absent, so unit-only CI hosts do not fail.

pytest packages/kailash-pact/tests/unit/conformance/ -v

Vector schema

Each vector is a JSON document at crates/kailash-pact/tests/conformance/vectors/ with:

• id: unique identifier (sort key)
• contract: "N4" (TieredAuditEvent canonicalisation) or "N5" (Evidence canonicalisation)
• input.verdict: {zone, reason, action, role_address, details}
• input.posture: required for N4 (PseudoAgent, Supervised, SharedPlanning, ContinuousInsight, Delegated)
• input.fixed_event_id / input.fixed_timestamp: required for determinism
• expected.canonical_json: the byte-for-byte JSON the SDK MUST emit
• expected.tier / durable / requires_signature / requires_replication: optional N4 invariants

The runner compares actual vs expected via byte equality (NOT JSON-equal); a single-byte drift surfaces as a FAILED outcome with both SHA-256 fingerprints populated for forensic correlation.

License

Apache 2.0 — Terrene Foundation