Developer Guide

CoreGuard Python SDK

The eve-coreguard Python SDK provides a typed, ergonomic interface to the 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
Quick Start — 5 Lines
Configuration
EvaluationRequest Schema
EvaluationResponse Fields
Error Handling
Async Usage
Advanced Usage
Changelog

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:

$pip install eve-coreguard

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

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

$pip install "eve-coreguard==0.1.2"

For projects using pyproject.toml:

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

Verify the installation:

$python -c "import eve_coreguard; print(eve_coreguard.__version__)" 0.1.2

Quick Start — 5 Lines

The following example evaluates a loan approval action against the lending_v1 policy pack and prints the disposition:

from eve_coreguard import EveCoreguardClient, EvaluationRequest

client = EveCoreguardClient(api_key="your_api_key_here")
request = EvaluationRequest(policy_set="lending_v1",
               user={"id": "u_001", "role": "loan_officer"},
               action={"type": "approve_loan", "amount": 50000})
result = client.evaluate(request)
print(result.decision.status)  # ALLOWED

API key security: Never hardcode your API key in source code. Load it from an environment variable: api_key=os.environ["COREGUARD_API_KEY"]. See Configuration for all available options.

Configuration

The EveCoreguardClient accepts the following configuration parameters:

Parameter	Type	Default	Description
api_key	str	required	Your CoreGuard API key. Recommended to load from environment variable `COREGUARD_API_KEY`.
base_url	str	`https://api.eveaicore.com`	Base URL for the CoreGuard API. Override for on-premises or private cloud deployments.
timeout	float	`10.0`	Request timeout in seconds. For high-throughput applications, 2.0 seconds is typical.
max_retries	int	`3`	Maximum number of retries on transient errors (5xx, network timeout). Uses exponential backoff.
verify_ssl	bool	`True`	Verify TLS certificate. Do not disable in production.
hmac_verification_key_hex	str or None	`None`	If provided, the client automatically verifies the HMAC signature on every response. Raises `CertificateVerificationError` on failure.

Configuration from environment variables (all parameters can be set via environment):

import os
from eve_coreguard import EveCoreguardClient

# Reads COREGUARD_API_KEY, COREGUARD_BASE_URL, COREGUARD_TIMEOUT automatically
client = EveCoreguardClient.from_env()

EvaluationRequest Schema

Every call to client.evaluate() takes an EvaluationRequest object. The schema mirrors the POST /v1/decisions/evaluate request body.

Field	Type		Description
policy_set	str	required	Policy pack identifier. Example: `"lending_v1"`, `"healthcare_v1"`, `"enterprise_v1"`.
user	dict	required	Dict with at minimum `id` (str) and `role` (str). Recorded in the decision certificate as the actor.
action	dict	required	The action being evaluated. Must include `type` (str). Additional fields are policy-pack-specific.
context	dict	optional	Additional context for policy evaluation: session metadata, prior decisions, environmental signals. Defaults to empty dict.
request_id	str or None	optional	Caller-supplied idempotency key. If provided, duplicate requests with the same `request_id` within 60 seconds return the cached response.
dry_run	bool	optional	If `True`, evaluates the request but does not record a certificate. Useful for testing policy configurations. Defaults to `False`.

Typed Construction

from eve_coreguard import EvaluationRequest

request = EvaluationRequest(
    policy_set="lending_v1",
    user={"id": "u_892", "role": "loan_officer", "department": "retail_lending"},
    action={
        "type": "generate_credit_decision",
        "applicant_id": "app_7823",
        "loan_amount": 85000,
        "stated_rationale": "Strong credit history and stable income.",
    },
    context={
        "session_id": "sess_abc123",
        "origination_channel": "digital",
    },
    request_id="req_unique_0001",  # idempotency key
)

EvaluationResponse Fields

The evaluate() method returns an EvaluationResponse object with the following structure:

Field	Type	Description
decision.status	str	Final disposition: `"ALLOWED"`, `"BLOCKED"`, or `"MODIFIED"`.
decision.risk_level	str	Risk assessment: `"LOW"`, `"MEDIUM"`, or `"HIGH"`.
decision.violations	list[PolicyViolation]	List of policy violations that fired. Empty for ALLOWED decisions.
decision.violations[].rule_id	str	Rule identifier. Example: `"lending.prohibited_basis"`.
decision.violations[].severity	str	`"LOW"`, `"MEDIUM"`, or `"HIGH"`.
decision.violations[].description	str	Human-readable violation description with statutory citation.
decision.violations[].remediation	str	Recommended remediation action.
decision.modifications	dict or None	Required modifications for MODIFIED decisions. Contains pack-specific modification instructions.
audit_record	AuditRecord	The signed Decision Certificate. See Decision Certificates for full schema.
audit_record.decision_id	str	Unique certificate identifier (ULID format).
audit_record.hmac_signature	str	HMAC-SHA256 signature over the canonical audit record.
certificate_verified	bool or None	Set to `True` or `False` if `hmac_verification_key_hex` was provided at client construction. `None` if verification was not configured.

Error Handling

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

from eve_coreguard import (
    EveCoreguardClient, EvaluationRequest,
    CoreGuardError,
    AuthenticationError,   # 401 — invalid or expired API key
    RateLimitError,         # 429 — rate limit exceeded
    PolicyNotFoundError,    # 404 — policy_set does not exist
    ValidationError,        # 422 — request schema validation failed
    ServiceUnavailableError, # 503 — CoreGuard service temporarily unavailable
    CertificateVerificationError,  # HMAC verification failed
)

client = EveCoreguardClient.from_env()

try:
    result = client.evaluate(request)
except AuthenticationError:
    # Rotate API key; alert on-call
    raise
except RateLimitError as e:
    # Back off for e.retry_after seconds
    time.sleep(e.retry_after or 60)
except CertificateVerificationError as e:
    # Tamper detected — do not process the response
    alert_security_team(e)
    raise
except ServiceUnavailableError:
    # Apply circuit breaker; use fail-safe fallback
    return FAIL_SAFE_RESPONSE
except CoreGuardError as e:
    logger.error(f"CoreGuard evaluation failed: {e}")
    raise

Async Usage

The SDK provides a fully async client for use with asyncio-based frameworks (FastAPI, Starlette, Tornado). The async client is API-compatible with the synchronous client:

import asyncio
from eve_coreguard import AsyncEveCoreguardClient, EvaluationRequest

async def evaluate_action(action_data):
    async with AsyncEveCoreguardClient.from_env() as client:
        request = EvaluationRequest(
            policy_set="lending_v1",
            user=action_data["user"],
            action=action_data["action"],
        )
        result = await client.evaluate(request)
        return result

# FastAPI integration example
from fastapi import FastAPI

app = FastAPI()
coreguard = AsyncEveCoreguardClient.from_env()

@app.post("/approve-loan")
async def approve_loan(payload: LoanRequest):
    governance_result = await coreguard.evaluate(
        EvaluationRequest(policy_set="lending_v1", user=payload.user,
                          action=payload.action)
    )
    if governance_result.decision.status == "BLOCKED":
        return {"approved": False, "reason": "Policy violation"}
    return {"approved": True}

Advanced Usage

Batch Evaluation

For high-throughput scenarios, evaluate_batch() sends multiple evaluation requests in a single HTTP call, reducing per-request overhead and improving throughput:

from eve_coreguard import EveCoreguardClient, EvaluationRequest

client = EveCoreguardClient.from_env()

requests = [
    EvaluationRequest(policy_set="lending_v1", user=u, action=a)
    for u, a in application_batch
]

# Evaluate up to 100 requests in a single API call
results = client.evaluate_batch(requests)

for req, res in zip(requests, results):
    if res.decision.status == "BLOCKED":
        handle_blocked(req, res)

Custom Policy Sets

Organizations on Enterprise plans may have custom policy packs deployed under organization-specific identifiers. Use these the same way as first-party packs:

request = EvaluationRequest(
    policy_set="regional_lending_v1",  # Custom pack for a regional lender
    user={"id": "u_100", "role": "underwriter"},
    action={"type": "approve_mortgage", "amount": 420000},
)

Certificate Verification at Scale

from eve_coreguard import EveCoreguardClient

# Configure once with verification key — all responses are auto-verified
client = EveCoreguardClient(
    api_key=os.environ["COREGUARD_API_KEY"],
    hmac_verification_key_hex=os.environ["COREGUARD_HMAC_KEY"],
)

# Verify a stored historical certificate
is_valid = client.verify_certificate(
    audit_record=stored_record,
    key_hex=historical_key_hex,  # use key_id to select correct version
)

# Verify an entire audit chain
chain_result = client.verify_chain(records=sorted_records, key_hex=key_hex)
print(f"Chain valid: {chain_result.valid}, checked: {chain_result.records_checked}")

Changelog

v0.1.0

Released 2026-05-05

Initial public release.

Synchronous EveCoreguardClient with evaluate() and evaluate_batch().
Asynchronous AsyncEveCoreguardClient with identical API surface.
Typed EvaluationRequest and EvaluationResponse models with Pydantic v2 support.
verify_certificate() and verify_chain() for offline HMAC verification.
Automatic retry with exponential backoff on 5xx and network errors.
Full exception hierarchy: AuthenticationError, RateLimitError, PolicyNotFoundError, ValidationError, ServiceUnavailableError, CertificateVerificationError.
EveCoreguardClient.from_env() for environment variable configuration.
28 tests covering happy path, all error cases, certificate verification, and batch evaluation.
Type stubs (.pyi files) for IDE autocompletion.
Compatible with Python 3.9, 3.10, 3.11, 3.12, 3.13.

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].