# kevros

[![Smithery](https://smithery.ai/badge/ndl-systems/kevros)](https://smithery.ai/servers/ndl-systems/kevros)

Python SDK for the **Kevros A2A Governance Gateway** — five governance primitives for autonomous agents: verify, attest, bind, verify outcome, and bundle.

```
pip install kevros
```

## 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."**

When you need proof, ask Kevros: **"Did the outcome match the intent?"**

Every decision is HMAC-signed. Every action is hash-chained. Every intent is cryptographically bound to its command. Downstream services verify independently — no callbacks, no trust assumptions.

## Five Governance Primitives

| Primitive | Description | Cost |
|-----------|-------------|------|
| **Verify** | Evaluate an action against policy bounds. Returns ALLOW, CLAMP, or DENY with a cryptographic release token. | $0.01 |
| **Attest** | Record an action in a hash-chained, tamper-evident provenance ledger. | $0.02 |
| **Bind** | Cryptographically bind a declared intent to the command that fulfills it. | $0.02 |
| **Verify Outcome** | Confirm the executed action achieved its declared intent. Closes the governance loop. | Free |
| **Bundle** | Generate a certifier-grade compliance evidence package. Independently verifiable. | $0.25 |

## Quick Start

```python
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 + Outcome Verification

Bind a declared intent to a specific command, then verify the outcome matched.

```python
from kevros_governance import GovernanceClient, IntentType

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

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

# ... execute the command ...

# 4. VERIFY OUTCOME — did the action achieve 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.0293, "lon": -78.4768},
)
print(f"Status: {outcome.status}")  # ACHIEVED or FAILED
```

## Compliance Evidence Bundle

Generate an audit-ready evidence package for any agent.

```python
# 5. BUNDLE — certifier-grade compliance package
bundle = client.bundle(
    agent_id="trading-bot-001",
    include_intent_chains=True,
    include_pqc_signatures=True,
)
print(f"Records: {bundle.record_count}, Chain intact: {bundle.chain_integrity}")
```

## Async Support

Every method has an async counterpart prefixed with `a`:

```python
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

- **Free tier:** 100 calls/month, instant signup, no payment required
- **Scout:** $29/mo — 5,000 calls
- **Sentinel:** $149/mo — 50,000 calls
- **Sovereign:** $499/mo — 500,000 calls

## Agent Card

The gateway publishes an [A2A Agent Card](https://governance.taskhawktech.com/.well-known/agent.json) for agent-to-agent discovery.

## MCP

For MCP-native agents, connect via streamable-http transport:

```
https://governance.taskhawktech.com/mcp/
```

## Links

- Gateway: https://governance.taskhawktech.com
- Agent Card: https://governance.taskhawktech.com/.well-known/agent.json
- Website: https://taskhawktech.com
