Metadata-Version: 2.4
Name: eve-coreguard
Version: 0.1.2
Summary: EVE CoreGuard SDK - AI Governance Enforcement in One API Call
Project-URL: Homepage, https://eveaicore.com
Project-URL: Documentation, https://docs.eveaicore.com/sdk
Author: EVE NeuroSystems LLC
License-Expression: LicenseRef-Proprietary
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: async
Requires-Dist: aiohttp>=3.8; extra == 'async'
Description-Content-Type: text/markdown

# EVE CoreGuard SDK

**AI Governance Enforcement in One API Call.**

CoreGuard intercepts AI-generated decisions before execution, evaluates them against policy, and returns an auditable enforcement verdict.

## Install

```bash
pip install eve-coreguard
```

## Quick Start

```python
from eve_coreguard import CoreGuardClient

client = CoreGuardClient(
    api_key="eve_sk_...",
    base_url="https://api.eveaicore.com",  # or http://localhost:8000
)

# Evaluate a proposed lending decision against policy
result = client.evaluate(
    tenant_id="bank_001",
    proposed_action={"type": "loan_approval", "amount": 250000, "currency": "USD"},
    model_output={"decision": "approve", "confidence": 0.91},
    context={
        "credit_score": 580,
        "debt_to_income": 0.52,
        "employment_verified": False,
    },
    policy_set="lending_v1",
)

if result.blocked:
    print(f"BLOCKED: {result.decision.action}")
    print(f"Risk: {result.risk.score} ({result.risk.level})")
    for v in result.policy_violations:
        print(f"  - {v.policy_id}: {v.description}")
    if result.liability_prevented:
        print(f"Exposure prevented: {result.liability_prevented.estimated_exposure}")
```

## Core Methods

### Decision Enforcement

```python
result = client.evaluate(
    tenant_id="org_001",
    proposed_action={"type": "loan_approval", "amount": 250000},
    model_output={"decision": "approve", "confidence": 0.91},
    context={"credit_score": 580, "debt_to_income": 0.52},
    policy_set="lending_v1",
)
# result.decision.status: ALLOWED | BLOCKED | MODIFIED
# result.risk.score: 0.0-1.0
# result.policy_violations: list of violated rules
# result.regulatory_impact: ECOA, TILA, etc.
# result.counterfactual: what would have passed
# result.liability_prevented: estimated exposure
# result.audit: cryptographic audit trail
```

### AI Output Verification

```python
vr = client.verify(
    ai_output="The capital of France is Paris.",
    confidence=0.9,
    domain="factual",
)
# vr.passed / vr.blocked
# vr.crd — Confidence-Reality Divergence score
# vr.veto.type — pass | soft_veto | hard_veto | charter
# vr.evidence — step-by-step audit chain
```

### Audit & Compliance

```python
# Retrieve cryptographic proof of a governance decision
proof = client.get_proof("proof_abc123")
# proof.content_hash, proof.signature, proof.chain_position

# Export decision history
export = client.export_audit(since="2026-01-01T00:00:00Z", limit=100)
for record in export.records:
    print(f"{record.decision_type}: {record.decision}")

# Verify hash chain integrity
status = client.verify_chain()
```

## Configuration

| Parameter | Default | Description |
|-----------|---------|-------------|
| `api_key` | *required* | EVE API key (`eve_sk_...`) |
| `base_url` | `https://api.eveaicore.com` | API endpoint |
| `timeout` | `30.0` | Request timeout (seconds) |
| `max_retries` | `3` | Retry count for 5xx errors |
| `raise_on_veto` | `False` | Raise `VetoError` on governance blocks |

## Error Handling

```python
from eve_coreguard import CoreGuardClient, AuthError, RateLimitError, VetoError

try:
    result = client.evaluate(...)
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited — retry in {e.retry_after}s")
except VetoError as e:
    print(f"Governance veto: {e.veto_type}")
```

## Response Metadata (subscription + rate limits)

Every call captures the response's billing and rate-limit headers. Read them
after a call (or after catching an error):

```python
result = client.evaluate(tenant_id="bank_001", ...)

client.subscription_state    # 'active' | 'past_due' | 'restricted' | ...
client.access_state          # 'full_access' | 'warning' | 'read_only' | ...
client.quota_warning         # 'payment_past_due' when degraded-but-allowed, else None
client.rate_limit_limit      # '330' | 'unlimited'
client.rate_limit_remaining  # calls left in the current 60s window (int | None)
client.retry_after           # seconds to wait after a 429 (int | None)
```

The decision endpoint is rate-limited per org by plan tier (Free 10/min,
Pro 330/min, Team 1150/min, Enterprise/Sovereign unlimited). On exhaustion it
returns `429` with `Retry-After`. See
[Response-Header Contract](../../docs/sdk/RESPONSE_HEADER_CONTRACT.md).

## Live Demo (Local)

Run a full end-to-end enforcement decision in 3 steps:

**Step 1: Start the server**

```bash
cd /path/to/EVE
python -m uvicorn saas.app:app --port 8000
```

**Step 2: Install the SDK**

```bash
cd sdks/coreguard
pip install -e .
```

**Step 3: Run the demo**

```bash
python run_demo.py
```

**Expected output:**

```
Decision:   BLOCKED
Action:     deny_loan_approval
Risk:       0.6284 (HIGH)
Violations: 3
  - CREDIT_SCORE_MIN: Credit score 580 is below the minimum threshold of 620
  - DTI_LIMIT: Debt-to-income ratio 0.52 exceeds the maximum threshold of 0.45
  - EMPLOYMENT_REQUIRED: Employment verification is missing or unverified
Regulatory: 3 impact(s)
  - ECOA [CRITICAL]: Potential discriminatory lending decision based on credit criteria
  - ECOA [CRITICAL]: DTI threshold may disproportionately affect protected classes
  - TILA [CRITICAL]: Incomplete underwriting verification
Liability:  $125,000 - $625,000
Audit:      audit_8e6db687d87d
```

## Requirements

- Python 3.9+
- Zero required dependencies (stdlib `urllib` only)
- Optional: `aiohttp` for async support (`pip install eve-coreguard[async]`)

## License

Proprietary. See LICENSE for details.
