# kevros

Python SDK for the Kevros Governance Gateway. Seven endpoints for autonomous agent control: verify (ALLOW/CLAMP/DENY), attest (hash-chained provenance), bind (cryptographic intent binding), bundle (compliance evidence export), scan (threat detection), media/attest (PQC-signed media certificates), and batch operations.

## Installation

```bash
pip install kevros
```

## Quick Start

```python
from kevros_governance import GovernanceClient

# Zero config — auto-signs up for free tier (1,000 calls/month) on first use
# Key is cached at ~/.kevros/api_key for future sessions
client = GovernanceClient()

# Verify an agent action against policy bounds
result = client.verify(
    agent_id="agent-001",
    action_type="transfer",
    parameters={"amount": 150.00, "recipient": "vendor-xyz"},
    context={"session_id": "abc123"}
)

if result.decision == "ALLOW":
    # Attest the decision with hash-chained provenance
    attestation = client.attest(
        decision_id=result.decision_id,
        evidence=result.evidence
    )
    print(f"Attestation hash: {attestation.hash}")
elif result.decision == "CLAMP":
    print(f"Action clamped: {result.clamped_parameters}")
else:
    print(f"Action denied: {result.reason}")
```

## Endpoints

| Endpoint | Method | Price | Description |
|---|---|---|---|
| `/governance/verify` | POST | $0.01 | Action verification. Returns signed ALLOW, CLAMP, or DENY. |
| `/governance/attest` | POST | $0.02 | Provenance attestation. Hash-chained evidence trail. |
| `/governance/bind` | POST | $0.02 | Cryptographic intent-to-command binding proof. |
| `/governance/bundle` | POST | $0.05 | Compliance evidence export. Full audit chain. |
| `/shield/scan` | POST | $0.01 | Threat detection and input validation. |
| `/media/attest` | POST | $0.05 | PQC-signed media attestation certificate. |
| `/governance/batch` | POST | $0.01 | Batch operations. Multiple calls, one request. |

## Payment Protocols

Three ways to pay. No vendor lock-in.

| Protocol | Rail | Settlement |
|---|---|---|
| x402 | USDC on Base | Per-call. Coinbase Commerce + Cloudflare. |
| L402 | Lightning Network | Per-call. Instant sats, cryptographic token auth. |
| MPP / Stripe Tempo | Fiat (USD) | Subscription or credit packs via Stripe. |

## Pricing

| Tier | Monthly | Included Calls |
|---|---|---|
| Free | $0 | 10 |
| Scout | $29 | 5,000 |
| Sentinel | $149 | 50,000 |
| Sovereign | $499 | 500,000 |

1,000 calls/month free. No credit card required. Overage billed at standard per-call rates.

## Core Concepts

**Fail-closed by default.** If the gateway is unreachable or returns an error, the SDK returns DENY. No silent failures. No open-by-default fallbacks.

**Hash-chained provenance.** Every attestation links to the previous one via SHA-256 chain. Tampering with any record breaks the chain and is detectable by any verifier.

**Signed decisions.** Every ALLOW, CLAMP, and DENY response is cryptographically signed. Decisions are independently verifiable without trusting the gateway.

## Configuration

```python
client = KevrosClient(
    api_key="your-api-key",
    base_url="https://governance.taskhawktech.com",  # default
    timeout=10,          # seconds
    fail_closed=True     # default; DENY on any error
)
```

## Environment Variables

```
KEVROS_API_KEY=your-api-key
KEVROS_BASE_URL=https://governance.taskhawktech.com
```

## Links

| Resource | URL |
|---|---|
| Gateway | https://governance.taskhawktech.com |
| API Docs | https://governance.taskhawktech.com/docs |
| Status | https://governance.taskhawktech.com/status |
| Pricing | https://governance.taskhawktech.com/upgrade |

## License

Proprietary. Copyright 2026 TaskHawk Systems, LLC.

CAGE Code 10YV4. SAM.gov registered. NIST 800-171 / DFARS 252.204-7012 aligned.

## Contact

info@taskhawktech.com
