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 43-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 in their own namespace (org:<org_id>). A custom pack governs a decision once your org admin binds an action type to it; you then call evaluate() exactly as for a built-in pack, and the binding — not policy_set — selects it. (policy_set remains an optional assertion; a value that does not match the bound pack is a signed BLOCK.) With eve-coreguard 0.2.10 (the version currently on PyPI), evaluate() sends policy_set="lending_v1" whenever the argument is omitted, so a non-lending or custom-bound action type comes back as a signed BLOCK (COREGUARD.POLICY_BINDING_MISMATCH). On 0.2.10, pass the bound pack’s policy_id as policy_set explicitly; 0.2.11 omits it.

result = client.evaluate(
    tenant_id="regional_bank_07",
    # loan_approval is governed by the custom pack your org admin bound it to
    user={"id": "u_100", "role": "underwriter"},
    proposed_action={"type": "loan_approval", "amount": 420000},
    # required on 0.2.10 (it would otherwise send "lending_v1"): the custom pack's
    # policy_id, as listed by client.list_policies()
    policy_set=custom_policy_id,
)

Offline Proof Verification

Every decision can be verified locally, with no server call: the SDK recomputes the content hash and checks the signature. Which key you need depends on which artifact you hold — the two are not interchangeable.

For a hosted decision record, verification is asymmetric: it needs only EVE’s public key and no shared secret, so the party checking the record is not the party that produced it. This gives publicly verifiable evidence of record integrity and signing-key possession (not, by itself, legal non-repudiation):

# A governed decision, with the signed evidence plane included
decision = client.evaluate(request_id="req-001", tenant_id="org_abc", proposed_action={"type": "loan_approval", "amount": 50000}, policy_set="lending_v1", include_evidence=True)

# Hosted records: verify against the PUBLISHED PUBLIC KEY — no shared secret, no
# network. The key is auto-fetched from /.well-known/eve-pubkey if not supplied.
result = client.verify_evidence_offline(decision.signed_governance)
print(f"Valid: {result.valid} | algorithm: {result.algorithm} | independent: {result.independently_verifiable}")

# Legacy / self-hosted symmetric proof bundle — DEPRECATED, and NOT independent
# proof: it needs the server's shared signing key, so anyone able to verify can
# also forge. Kept only for pre-existing HMAC records.
proof = client.get_proof("proof_abc123")
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 [email protected].