# kevros

[![Smithery](https://smithery.ai/badge/taskhawk-systems/kevros)](https://smithery.ai/servers/taskhawk-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.05 |

## 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",
    )
```

## Zero-Signup Start

No registration needed. The SDK auto-provisions a free-tier API key on first use:

```python
from kevros_governance import GovernanceClient

# Automatically signs up and caches a free-tier key
client = GovernanceClient(agent_id="my-agent")
result = client.verify(
    action_type="deploy",
    action_payload={"service": "api", "version": "2.0"},
    agent_id="my-agent",
)
```

Or skip API keys entirely and pay per call with x402 USDC on Base network.

## Pricing

- **Free tier:** 1,000 calls/month, auto-provisions on first call, no payment needed
- **Scout:** $29/mo -- 5,000 calls
- **Sentinel:** $149/mo -- 50,000 calls
- **Sovereign:** $499/mo -- 500,000 calls
- **x402 pay-per-call:** USDC on Base, no subscription required

## Framework Integrations

Works with every major agent framework:

| Framework | Integration |
|-----------|-------------|
| **LangChain** | `from kevros_tools import get_identity_tools` |
| **CrewAI** | `from crewai_tools import get_identity_tools` |
| **AutoGen** | Register `kevros_verify` / `kevros_attest` as function tools |
| **OpenAI Agents** | `@function_tool` decorator on verify/attest functions |
| **Coinbase AgentKit** | `pip install coinbase-agentkit-kevros` |
| **MS Agent Framework** | `from kevros_agent_framework import KevrosGovernanceMiddleware` |
| **MCP** | Connect to `https://governance.taskhawktech.com/mcp/` |

See the `examples/` directory for complete integration code.

## Agent Discovery

The gateway publishes standard discovery documents:

- **A2A Agent Card:** https://governance.taskhawktech.com/.well-known/agent.json
- **AI Plugin (OpenAI format):** https://governance.taskhawktech.com/.well-known/ai-plugin.json
- **OpenAPI spec:** https://governance.taskhawktech.com/openapi.json
- **x402 payment discovery:** https://governance.taskhawktech.com/.well-known/x402
- **MCP tool discovery:** https://governance.taskhawktech.com/mcp/

## MCP

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

```json
{
  "mcpServers": {
    "kevros": {
      "type": "streamable-http",
      "url": "https://governance.taskhawktech.com/mcp/"
    }
  }
}
```

Or run locally: `pip install kevros && kevros-mcp`

## Links

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