<div align="center">

# kevros

**Your agent did something. Can you prove it?**

Cryptographic governance for AI agents. Verify before acting. Attest after. Hash-chain everything.

[![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)

</div>

---

```bash
pip install kevros
```

```python
from kevros_governance import GovernanceClient

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

result = client.verify(
    action_type="trade",
    action_payload={"symbol": "AAPL", "shares": 100},
    agent_id="my-agent",
)

print(result.decision)  # ALLOW | CLAMP | DENY
```

That is it. Your agent now has a governance layer. Every call is hash-chained, tamper-evident, and independently verifiable.

---

## Why

Agents are doing real things now. Trading. Deploying. Sending emails. Modifying databases. Operating hardware.

The question is no longer "can my agent do this?" It is "can I prove what my agent did, why it did it, and that it was authorized?"

Kevros answers that question with five API calls.

- **Pre-flight check** -- ask before acting. Get ALLOW, CLAMP, or DENY.
- **Provenance record** -- attest after acting. SHA-256 hash-chained to every prior action.
- **Intent binding** -- cryptographically prove that a command was issued in service of a declared intent.
- **Outcome verification** -- did the action achieve the goal?
- **Compliance bundle** -- export the full evidence chain for auditors, regulators, or your own peace of mind.

No vendor lock-in. Export your evidence. Verify it yourself. The math does not care who runs it.

---

## Five Primitives

Everything Kevros does fits in five calls.

| Primitive | What it does | Cost |
|-----------|-------------|------|
| `verify` | Pre-flight action check. Returns ALLOW, CLAMP, or DENY. | $0.01 |
| `attest` | Hash-chained provenance record after action. | $0.02 |
| `bind` | Cryptographically bind intent to command. | $0.02 |
| `verify_outcome` | Did the action achieve the intent? | free |
| `bundle` | Compliance evidence package for auditors. | $0.25 |

---

## Quickstart

### Verify before acting

```python
from kevros_governance import GovernanceClient

client = GovernanceClient()

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)
elif result.decision.value == "CLAMP":
    # values were adjusted to fit policy bounds
    execute_trade(result.applied_action)
else:
    log_denied(result.reason)
```

### Attest after acting

```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_curr)    # SHA-256, chained to every prior action
print(proof.chain_length) # total records in your provenance ledger
```

### Bind intent to outcome

```python
from kevros_governance import IntentType

# Step 1: 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},
)

# Step 2: Execute your action
# ...

# Step 3: 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(outcome.status)              # ACHIEVED | PARTIALLY_ACHIEVED | FAILED
print(outcome.achieved_percentage) # 99.2
```

### Export compliance bundle

```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.record_count)    # total records
print(bundle.chain_integrity) # True -- hash chain intact
print(bundle.bundle_hash)     # independently verifiable
# Hand this to an auditor. They don't need Kevros access to verify it.
```

---

## Zero-Friction Start

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

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

Call `GovernanceClient()` with zero arguments and you are on the free tier immediately. The SDK auto-provisions a key on first use and caches it locally.

When you are ready for more volume, upgrade at [governance.taskhawktech.com](https://governance.taskhawktech.com).

---

## Framework Integrations

Kevros ships adapters for the frameworks your agents already use. Every integration in this repo is production-ready.

### Python SDK

```python
from kevros_governance import GovernanceClient

client = GovernanceClient()
result = client.verify(action_type="deploy", action_payload={"service": "api", "version": "2.1.0"}, agent_id="cd-bot")
```

### 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)
# Your agent now has governance_verify, governance_attest, governance_bind,
# governance_verify_outcome, and governance_bundle as callable tools.
```

### CrewAI

```python
from crewai_tools import get_governance_tools

tools = get_governance_tools(api_key="kvrs_...")
agent = Agent(
    role="Compliance-Aware Trader",
    tools=tools,
    goal="Execute trades with full provenance",
)
```

### OpenAI Function Calling

The `openai_tools.json` file contains all five governance primitives as OpenAI function definitions. Drop it into your `tools` parameter:

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

Add to your MCP config (Claude Code: `~/.claude/settings.json`, Cursor: `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "kevros": {
      "command": "python3",
      "args": ["kevros_mcp_server.py"],
      "env": { "KEVROS_API_KEY": "kvrs_..." }
    }
  }
}
```

Your AI coding assistant now has `governance_verify`, `governance_attest`, `governance_bind`, `governance_verify_outcome`, and `governance_bundle` as native tools.

### curl

```bash
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"
  }'
```

---

## Async

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

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

    proof = await client.aattest(
        agent_id="async-bot",
        action_description="Bought 50 AAPL",
        action_payload={"symbol": "AAPL", "shares": 50, "price": 185.42},
    )

    binding = await client.abind(
        agent_id="async-bot",
        intent_type=IntentType.AUTOMATED,
        intent_description="Rebalance portfolio",
        command_payload={"sell": "SPY", "buy": "BND"},
        goal_state={"stock_pct": 60, "bond_pct": 40},
    )

    bundle = await client.abundle(agent_id="async-bot")
```

The async client uses `httpx.AsyncClient` under the hood. Connection pooling, HTTP/2, the works.

---

## 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 five primitives, async support, compliance bundles, and the full hash-chained evidence ledger.

---

## How It Works

```
                  Your Agent
                      |
              1. verify(action)
                      |
                      v
         +------------------------+
         |   Kevros Governance    |
         |       Gateway         |
         |                        |
         |  Policy Engine -----+  |
         |  Hash Chain Engine  |  |
         |  Intent Binder      |  |
         |  Evidence Packager  |  |
         +----------+-----------+
                    |
        +-----------+-----------+
        |           |           |
   ALLOW       CLAMP       DENY
        |           |
        v           v
  2. Execute    Execute
     action     (bounded)
        |           |
        v           v
  3. attest(what happened)
        |
        v
  Hash-chained provenance record
  (SHA-256, append-only, tamper-evident)
        |
        v
  4. bundle() --> Auditor-grade evidence
```

Every `verify` call evaluates your action against policy bounds and returns a decision. Every `attest` call extends an append-only SHA-256 hash chain. Every `bind` call creates a cryptographic link between what your agent intended and what it commanded. The chain is independently verifiable -- no Kevros access required.

---

## 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 governance gateway 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>
