kevros-governance

Python SDK for the Kevros A2A Governance Gateway — cryptographic action verification, hash-chained provenance, and compliance packaging for AI agents.

pip install kevros-governance

Or install directly from GitHub:

pip install git+https://github.com/ndl-systems/kevros.git#subdirectory=sdk/governance

What This Does

Before your AI agent takes an action, ask Kevros: "Is this within policy bounds?"

After your agent acts, tell Kevros: "Here's what I did."

Every decision is recorded in a hash-chained, tamper-evident provenance ledger. When auditors, regulators, or lawyers ask "what did your AI decide and why?" — you have cryptographic proof.

Quick Start

from kevros_governance import GovernanceClient

client = GovernanceClient(api_key="kvrs_...")

# 1. VERIFY before acting — get ALLOW, CLAMP, or DENY
result = client.verify(
    action_type="trade",
    action_payload={"symbol": "AAPL", "shares": 100, "price": 185.50},
    policy_context={"max_values": {"shares": 500, "price": 200.0}},
    agent_id="trading-bot-001",
)

if result.decision.value == "ALLOW":
    execute_trade(result.applied_action)

    # 2. ATTEST after acting — create provenance record
    attestation = client.attest(
        agent_id="trading-bot-001",
        action_description="Executed AAPL buy order",
        action_payload={"symbol": "AAPL", "shares": 100, "filled_price": 185.42},
    )
    print(f"Provenance hash: {attestation.hash_curr}")

Intent Binding (prove what your agent intended)

from kevros_governance import GovernanceClient, IntentType

client = GovernanceClient(api_key="kvrs_...")

# Declare intent and bind to command
binding = client.bind(
    agent_id="nav-agent-001",
    intent_type=IntentType.NAVIGATION,
    intent_description="Navigate to waypoint Alpha",
    command_payload={"lat": 38.8977, "lon": -77.0365, "alt": 100},
    goal_state={"lat": 38.8977, "lon": -77.0365},
)

# ... execute the action ...

# Verify the outcome matched the intent
outcome = client.verify_outcome(
    agent_id="nav-agent-001",
    intent_id=binding.intent_id,
    binding_id=binding.binding_id,
    actual_state={"lat": 38.8978, "lon": -77.0364},
    tolerance=0.01,
)
print(f"Outcome: {outcome.status}")  # ACHIEVED, PARTIALLY_ACHIEVED, or FAILED

Compliance Bundle (auditor-grade evidence)

bundle = client.bundle(
    agent_id="trading-bot-001",
    time_range_start="2026-02-01T00:00:00Z",
    time_range_end="2026-02-28T23:59:59Z",
)

print(f"Records: {bundle.record_count}")
print(f"Chain intact: {bundle.chain_integrity}")
print(f"Bundle hash: {bundle.bundle_hash}")
# Give bundle to auditor — independently verifiable without Kevros access

Async Support

Every method has an async counterpart prefixed with a:

async with GovernanceClient(api_key="kvrs_...") as client:
    result = await client.averify(
        action_type="trade",
        action_payload={"symbol": "AAPL", "shares": 50},
        agent_id="async-bot-001",
    )

Pricing

Endpoint	Cost	What it does
`verify`	$0.01	Action verification (ALLOW/CLAMP/DENY)
`attest`	$0.02	Hash-chained provenance record
`bind`	$0.02	Intent-command binding
`verify_outcome`	Free	Outcome verification (included with bind)
`bundle`	$0.25	Compliance evidence package

Subscription tiers: Scout ($29/mo, 5K calls) | Sentinel ($149/mo, 50K calls) | Sovereign ($499/mo, 500K calls)

Agent Card

The gateway publishes an A2A Agent Card for agent-to-agent discovery.

kevros-governance