# SOVR SDK for Python

The Execution Firewall for AI Agents — Official Python SDK for SOVR.

SOVR is the Responsibility Layer that sits between AI intent and real-world execution, providing policy enforcement, decision auditing, and trust verification for autonomous AI systems.

## Installation

```bash
pip install sovr-sdk
```

## Quick Start

```python
from sovr_sdk import SOVRClient

# Initialize client
client = SOVRClient(
    api_key="your-api-key",
    tenant_id="your-tenant-id",
    endpoint="https://sovr.inc"
)

# Evaluate a decision
result = client.evaluate_decision(
    action="payment",
    resource="order/12345",
    context={"amount": 1000, "currency": "USD"}
)

print(f"Verdict: {result.verdict}")
print(f"Risk Score: {result.risk_score}")
print(f"Value Score: {result.value_score}")

# Act on the decision
if result.verdict == "approved":
    print("✓ Action approved, safe to execute")
elif result.verdict == "pending_approval":
    print("⏳ Human approval required")
else:
    print("✗ Action blocked")
```

## Core Features

### Decision Evaluation

```python
result = client.evaluate_decision(
    action="payment",
    resource="order/12345",
    context={"amount": 1000},
    metadata={"trace_id": "abc123"}
)
```

### Trust Bundle Management

```python
# Create a trust bundle
bundle = client.create_trust_bundle(
    name="Payment Decision Bundle",
    description="Evidence package for order #12345 payment decision"
)

# Add evidence
client.add_evidence(
    bundle_id=bundle.id,
    evidence_type="document",
    content={"title": "Contract", "url": "https://..."},
    weight=0.3
)

# Evaluate sufficiency
evaluation = client.evaluate_sufficiency(bundle.id)
print(f"Sufficiency Score: {evaluation.score}")
```

### Audit Log Query

```python
# Query audit logs
logs = client.get_audit_logs(
    start_date="2026-01-01",
    end_date="2026-01-25",
    limit=100
)

for log in logs:
    print(f"{log.created_at}: {log.event_type} - {log.action}")
```

## Environment Variables

The SDK supports configuration via environment variables:

```bash
export SOVR_API_KEY="your-api-key"
export SOVR_TENANT_ID="your-tenant-id"
export SOVR_API_ENDPOINT="https://api.sovr.example.com"
```

```python
# Automatically reads from environment variables
client = SOVRClient()
```

## Error Handling

```python
from sovr_sdk.exceptions import SOVRError, AuthenticationError, RateLimitError

try:
    result = client.evaluate_decision(...)
except AuthenticationError:
    print("Authentication failed. Please check your API key.")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds.")
except SOVRError as e:
    print(f"SOVR Error: {e.message}")
```

## Documentation

- [API Reference](https://docs.sovr.ai/sdk/python/api)
- [Integration Guide](https://docs.sovr.ai/sdk/python/guide)
- [Examples](https://github.com/sovr-ai/sovr-sdk-python/tree/main/examples)

## License

MIT License
