EVE CoreGuard Python SDK

The eve-coreguard Python SDK provides a typed, ergonomic interface to the EVE CoreGuard governance decision engine. Install it from PyPI, configure your API key, and your first governance-enforced evaluation is running in under five minutes.

Installation

The SDK requires Python 3.9 or later. It has zero required dependencies — it uses only the Python standard library (urllib) for HTTP transport. Install from PyPI:

The package is published on PyPI: pypi.org/project/eve-coreguard.

To pin to a specific version (recommended for production):

For projects using pyproject.toml:

[project]
dependencies = [
    "eve-coreguard>=0.1.0,<1.0.0",
]

Verify the installation:

Quick Start — 5 Lines

The following example evaluates a loan approval against the lending_v1 policy pack and prints the disposition. evaluate() takes keyword arguments directly — there is no request object to construct:

from eve_coreguard import CoreGuardClient

client = CoreGuardClient(api_key="eve_sk_...")
result = client.evaluate(
    tenant_id="bank_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",
)
print(result.verdict)  # ALLOWED | BLOCKED | MODIFIED

Configuration

The CoreGuardClient accepts the following constructor parameters:

Load the API key from the environment rather than hardcoding it:

import os
from eve_coreguard import CoreGuardClient

client = CoreGuardClient(api_key=os.environ["COREGUARD_API_KEY"])

evaluate() Parameters

Call client.evaluate() with keyword arguments. They map directly to the POST /v1/decisions/evaluate request body.

Full example

result = client.evaluate(
    tenant_id="bank_001",
    user={"id": "u_892", "role": "loan_officer"},
    proposed_action={
        "type": "loan_approval",
        "applicant_id": "app_7823",
        "amount": 85000,
    },
    model_output={"decision": "approve", "confidence": 0.88},
    context={"credit_score": 712, "debt_to_income": 0.31, "employment_verified": True},
    policy_set="lending_v1",
    request_id="req_unique_0001",  # idempotency key (optional)
)

EvaluationResult Fields

The evaluate() method returns a frozen EvaluationResult dataclass with the following structure (plus convenience properties .verdict, .allowed, .blocked, .decision_id, .signature, .audit_hash):

Error Handling

The SDK uses a structured exception hierarchy. All exceptions inherit from CoreGuardError:

from eve_coreguard import (
    CoreGuardClient,
    CoreGuardError,
    AuthError,                # 401 — invalid or expired API key
    PaymentRequiredError,     # 402 — subscription past due / restricted
    RateLimitError,           # 429 — rate limit exceeded (has .retry_after)
    PolicySetNotFoundError,   # 404 — policy_set does not exist
    VetoError,                # raised by verify() when raise_on_veto=True
)

client = CoreGuardClient(api_key=os.environ["COREGUARD_API_KEY"])

try:
    result = client.evaluate(tenant_id="bank_001", proposed_action=action)
except AuthError:
    # Rotate API key; alert on-call
    raise
except RateLimitError as e:
    # Back off for e.retry_after seconds
    time.sleep(e.retry_after)
except PolicySetNotFoundError:
    # Unknown policy_set — check list_policies()
    raise
except PaymentRequiredError:
    # Subscription past due — inspect client.subscription_state
    raise
except CoreGuardError as e:
    logger.error(f"CoreGuard evaluation failed: {e} (status {e.status_code})")
    raise

Output Verification & Policy Discovery

Beyond decision enforcement, the same client verifies AI-generated text through the 8-stage governance pipeline, and discovers the policy packs available to your tenant.

Verify AI output

vr = client.verify(
    ai_output="The current prime rate is 8.5%.",
    confidence=0.9,
    domain="financial",  # factual | financial | legal | medical | safety | creative | general
)
print(vr.passed, vr.blocked, vr.crd)  # bool, bool, CRD score
if vr.blocked:
    print(vr.veto.type, vr.veto.reason)

Discover policy packs

# List the catalog (optionally filter by regulatory domain)
for p in client.list_policies(domain="fair_lending"):
    print(p.policy_id, p.version, p.rule_count)

# Fetch metadata for one pack
pack = client.get_policy("lending_v1")
print(pack.jurisdiction, pack.notes)

Advanced Usage

Batch Evaluation

The decision API evaluates one action per call. For high-throughput scenarios, evaluate concurrently with a thread pool — each call is an independent, idempotent HTTP request:

from concurrent.futures import ThreadPoolExecutor
from eve_coreguard import CoreGuardClient

client = CoreGuardClient(api_key=os.environ["COREGUARD_API_KEY"])

def check(app):
    return client.evaluate(
        tenant_id="bank_001",
        proposed_action=app["action"],
        context=app["context"],
        policy_set="lending_v1",
    )

with ThreadPoolExecutor(max_workers=8) as pool:
    for app, res in zip(application_batch, pool.map(check, application_batch)):
        if res.blocked:
            handle_blocked(app, res)

Custom Policy Sets

Organizations on Enterprise plans may have custom policy packs deployed under organization-specific identifiers. Use them the same way as first-party packs — just pass the id as policy_set:

result = client.evaluate(
    tenant_id="regional_bank_07",
    policy_set="regional_lending_v1",  # Custom pack for a regional lender
    user={"id": "u_100", "role": "underwriter"},
    proposed_action={"type": "loan_approval", "amount": 420000},
)

Offline Proof Verification

Every decision can be retrieved as a self-contained proof bundle and verified locally — no server call; it recomputes the SHA-256 content hash and checks the HMAC-SHA256 signature:

# Retrieve a proof bundle for a past decision
proof = client.get_proof("proof_abc123")

# Verify it offline with the server's signing key (static method, no network)
is_valid = CoreGuardClient.verify_proof(proof.raw, signing_key=key_hex)
print(f"Proof valid: {is_valid}")

# Export a batch of records for compliance review
export = client.export_audit(action_type="loan_approval", limit=100)
print(export.count, "records")

Changelog

For upcoming releases and the full commit history, see the GitHub repository. Bug reports and feature requests are welcome via GitHub Issues or support@eveaicore.com.