kevros 0.2.2
Python SDK for the Kevros A2A Governance Gateway — cryptographic action verification, hash-chained provenance, and compliance packaging for AI agents.
License: MIT
Requires Python: >=3.9
Keywords: a2a, agent-to-agent, ai-governance, ai-safety, audit-trail, compliance, langchain, mcp, openai, provenance

<div align="center">

# kevros

**Agentic identity trust for AI agents.**

Issue and verify trust certificates. Check peer reputation scores. Verify release tokens. Generate tamper-evident audit trails with post-quantum cryptographic signatures.

[![PyPI](https://img.shields.io/pypi/v/kevros?color=blue&label=pypi)](https://pypi.org/project/kevros/)
[![Python](https://img.shields.io/pypi/pyversions/kevros)](https://pypi.org/project/kevros/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Gateway](https://img.shields.io/badge/gateway-live-brightgreen)](https://governance.taskhawktech.com)
[![Smithery](https://smithery.ai/badge/kevros)](https://smithery.ai/server/kevros)

<!-- mcp-name: io.github.ndl-systems/kevros -->

</div>

---

```bash
pip install kevros

# Add to Claude Code as an MCP plugin (one command):
pip install kevros && claude mcp add kevros -- kevros-mcp
```

```python
from kevros_governance import GovernanceClient

client = GovernanceClient()  # auto-provisions identity, no signup

# Verify an action, get a cryptographic release token
result = client.verify(
    action_type="trade",
    action_payload={"symbol": "AAPL", "shares": 100},
    agent_id="my-agent",
)
print(result.decision)       # ALLOW | CLAMP | DENY
print(result.release_token)  # cryptographic proof of authorization

# Check another agent's trust score
peer = client.verify_peer("other-agent-id")
print(peer["trust_score"])   # reputation across the network
```

Your agent now has a verifiable identity. Every action is cryptographically signed, hash-chained, and independently verifiable by any peer.

---

## Why

Agents are talking to other agents now. Trading on behalf of users. Deploying infrastructure. Operating hardware. Calling APIs they've never seen before.

The question isn't "can my agent do this?" It's:

- **Can I trust this agent?** Does it have a verifiable identity and reputation?
- **Was this action authorized?** Is there a cryptographic release token proving it?
- **Can I verify what happened?** Is there a tamper-evident, hash-chained audit trail?
- **Will this hold up post-quantum?** Are the signatures PQC-resilient?

Kevros answers all four.

---

## What Kevros Gives Your Agent

### Identity and Trust

Every agent gets a verifiable identity on first use. No forms, no OAuth dance, no waiting for approval. Call the API and your agent exists in the trust network.

```python
client = GovernanceClient()  # identity auto-provisioned
```

Other agents can look you up:

```python
# Any agent can check any other agent's reputation
peer = client.verify_peer("trading-bot-001")
print(peer["trust_score"])    # 0.0 - 1.0
print(peer["chain_length"])   # total verified actions
print(peer["last_active"])    # last attestation timestamp
```

### Release Tokens

Every `verify()` call returns a cryptographic release token — proof that the action was evaluated against policy and authorized. Peers can verify these tokens independently.

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

# The release token is an HMAC signature over the decision
print(result.release_token)     # verifiable by any peer
print(result.provenance_hash)   # position in the hash chain

# Another agent can verify this token
verified = client.verify_peer_token(
    release_token=result.release_token,
    token_preimage=result.token_preimage,  # provided alongside the release token
)
```

### Trust Certificates

Bundle your agent's entire provenance into an auditor-grade trust certificate. PQC-signed. Independently verifiable. No Kevros access required to validate.

```python
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(bundle.chain_integrity)   # True -- hash chain intact
print(bundle.record_count)      # total attested actions
print(bundle.bundle_hash)       # covers the entire evidence set

# PQC signatures included -- resilient against quantum attacks
print(bundle.pqc_signatures)    # post-quantum attestation references
```

Hand this to an auditor, a regulator, a counterparty, or another agent. The math verifies itself.

### Hash-Chained Provenance

Every action your agent attests is SHA-256 hash-chained to every prior action. Tamper with one record and the entire chain breaks.

```python
proof = client.attest(
    agent_id="trading-bot-001",
    action_description="Bought 100 AAPL at $185.42",
    action_payload={"symbol": "AAPL", "shares": 100, "price": 185.42},
)

print(proof.hash_prev)       # links to previous record
print(proof.hash_curr)       # this record's hash
print(proof.chain_length)    # total records in the ledger
print(proof.pqc_block_ref)   # PQC attestation reference
```

### Intent Binding

Cryptographically prove that a command was issued in service of a declared intent. Close the loop: intent -> command -> action -> outcome -> verification.

```python
from kevros_governance import IntentType

# Declare intent, 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},
)

# After execution: 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.8978, "lon": -77.0364},
    tolerance=0.01,
)

print(outcome.status)              # ACHIEVED | PARTIALLY_ACHIEVED | FAILED
print(outcome.achieved_percentage) # 99.2
```

---

## The Trust Primitives

| Primitive | What it does | Cost |
|-----------|-------------|------|
| `verify` | Pre-flight action check. Returns ALLOW/CLAMP/DENY + release token. | $0.01 |
| `attest` | Hash-chained provenance record with PQC block reference. | $0.02 |
| `bind` | Cryptographic intent-to-command binding. | $0.02 |
| `verify_outcome` | Did the action achieve the declared intent? | free |
| `bundle` | PQC-signed trust certificate. Auditor-grade. | $0.25 |
| `verify_peer` | Look up any agent's trust score and reputation. | free |
| `verify_peer_token` | Independently verify another agent's release token. | free |
| `health` | Gateway health + chain integrity check. | free |

---

## Zero-Friction Identity

```python
client = GovernanceClient()
```

No signup form. No API key dance. No email confirmation.

Call `GovernanceClient()` with zero arguments and your agent has an identity immediately. The SDK auto-provisions a key on first use and caches it at `~/.kevros/api_key`.

Resolution order:
1. `KEVROS_API_KEY` environment variable
2. `~/.kevros/api_key` cached key
3. Auto-signup (free tier, 100 calls/month)

---

## Framework Integrations

Kevros ships adapters for the frameworks your agents already use.

### Python SDK

```python
from kevros_governance import GovernanceClient

client = GovernanceClient()
result = client.verify(action_type="deploy", action_payload={"service": "api"}, agent_id="cd-bot")
peer = client.verify_peer("other-agent")
```

### LangChain

```python
from kevros_tools import get_governance_tools

tools = get_governance_tools(api_key="kvrs_...")
agent = initialize_agent(llm, tools, agent=AgentType.OPENAI_FUNCTIONS)
```

### CrewAI

```python
from crewai_tools import get_governance_tools

tools = get_governance_tools(api_key="kvrs_...")
agent = Agent(role="Trusted Trader", tools=tools, goal="Execute trades with verifiable identity")
```

### OpenAI Function Calling

```python
import json

with open("openai_tools.json") as f:
    governance_tools = json.load(f)

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=governance_tools,
)
```

### MCP Server (Claude Code / Cursor / Windsurf)

```bash
# Recommended: pip install + CLI entry point
pip install kevros
claude mcp add kevros -- kevros-mcp
```

Or configure manually:

```json
{
  "mcpServers": {
    "kevros": {
      "command": "kevros-mcp"
    }
  }
}
```

The MCP server exposes 9 tools (`governance_verify`, `governance_attest`, `governance_bind`, `governance_verify_outcome`, `governance_bundle`, `governance_check_peer`, `governance_verify_token`, `governance_health`, `kevros_status`), 2 resources (`kevros://agent-card`, `kevros://trust-status`), and 2 prompts (`verify-before-act`, `governance-audit`).

### curl

```bash
# Verify an action
curl -X POST https://governance.taskhawktech.com/governance/verify \
  -H "X-API-Key: kvrs_..." \
  -H "Content-Type: application/json" \
  -d '{"action_type":"trade","action_payload":{"symbol":"AAPL","shares":100},"agent_id":"my-agent"}'

# Check a peer's trust score
curl https://governance.taskhawktech.com/governance/reputation/other-agent-id \
  -H "X-API-Key: kvrs_..."
```

---

## Async

Every method has an async twin. Prefix with `a`.

```python
async with GovernanceClient() as client:
    result = await client.averify(...)
    proof  = await client.aattest(...)
    peer   = await client.averify_peer("other-agent")
    bundle = await client.abundle(agent_id="my-agent")
```

---

## Trust Gate and Middleware

Protect your own APIs by requiring Kevros trust credentials from callers.

### FastAPI Trust Gate

```python
from kevros_verifier import KevrosTrustGate

gate = KevrosTrustGate(gateway_url="https://governance.taskhawktech.com")

@app.get("/protected")
async def protected_endpoint(trust=Depends(gate)):
    # trust.verified is True, trust.agent_id is the caller
    return {"msg": f"Hello, {trust.agent_id}"}
```

### ASGI Middleware

```python
from kevros_verifier import KevrosTrustMiddleware

app.add_middleware(KevrosTrustMiddleware, protected_paths=["/api/"])
# All /api/* routes now require X-Kevros-Release-Token headers
```

---

## Pricing

Start free. Scale when you need to.

| Tier | Price | Calls/mo | Best for |
|------|-------|----------|----------|
| **Free** | $0 | 100 | Prototyping, evaluation |
| **Scout** | $29/mo | 5,000 | Single-agent production |
| **Sentinel** | $149/mo | 50,000 | Multi-agent fleets |
| **Sovereign** | $499/mo | 500,000 | Enterprise, regulated industries |

Every tier includes all trust primitives, PQC signatures, peer verification, async support, and the full hash-chained evidence ledger.

---

## How It Works

```
  Agent A                  Kevros Gateway              Agent B
     |                          |                         |
     |-- verify(action) ------->|                         |
     |<-- ALLOW + release_token |                         |
     |                          |--- provenance record -->|
     |   [execute action]       |   (hash-chained, PQC)  |
     |                          |                         |
     |-- attest(outcome) ------>|                         |
     |<-- hash_curr + chain ----|                         |
     |                          |                         |
     |                          |<-- verify_peer(A) ------|
     |                          |--- trust_score: 0.94 -->|
     |                          |                         |
     |-- bundle(time_range) --->|                         |
     |<-- trust certificate ----|                         |
     |   (PQC-signed, portable) |                         |
```

Every record is hash-chained (SHA-256). Trust certificates include PQC signatures for post-quantum resilience. The chain is independently verifiable — export your evidence and validate it anywhere.

---

## A2A Agent Card

The gateway publishes a standard [A2A Agent Card](https://governance.taskhawktech.com/.well-known/agent.json) for agent-to-agent discovery. Any A2A-compatible agent can discover and interact with the trust network programmatically.

---

## Links

- **Gateway**: [governance.taskhawktech.com](https://governance.taskhawktech.com)
- **OpenAPI Spec**: [governance.taskhawktech.com/openapi.json](https://governance.taskhawktech.com/openapi.json)
- **Agent Card**: [governance.taskhawktech.com/.well-known/agent.json](https://governance.taskhawktech.com/.well-known/agent.json)
- **PyPI**: [pypi.org/project/kevros](https://pypi.org/project/kevros/)
- **Source**: [github.com/ndl-systems/kevros-sdk](https://github.com/ndl-systems/kevros-sdk)

---

<div align="center">

**Built by [TaskHawk Systems](https://taskhawktech.com)**

Your agents act. Kevros proves it.

MIT License

</div>