EVE CoreGuard — Python SDK (eve-coreguard)

eve-coreguard is the Python client for EVE CoreGuard. Its one obvious entry point is:

from eve_coreguard import CoreGuardClient

Use it to block or require approval before a tool executes, produce signed decision evidence, and verify that evidence without trusting the EVE server.

Readiness

• Package: eve-coreguard 0.2.7 (Python >= 3.9; validated on 3.12.8; zero required dependencies). This is a release-candidate core client — part of an SDK core that is a RELEASE CANDIDATE WITH EXCLUSIONS.
• The pip client governs via hosted mode: it reaches CoreGuard over HTTP and needs a reachable endpoint and API key. Embedded (in-process) governance is the EVE service, not the client wheel — the client raises a clear error if you ask for embedded mode without the in-process package.
• The core governed decision (CoreGuard ALLOW/BLOCK/MODIFY) is pilot-validated. Signed evidence and offline verification are SUPPORTED.
• Framework adapters other than the generic adapter are experimental — see Framework adapters.
• Public-registry status (validated 2026-08-03). eve-coreguard 0.2.7 is published on PyPI (released 2026-08-02) and installs with a plain pip install eve-coreguard. The primary client export is CoreGuardClient; offline verification (verify_decision_record, jcs_canonicalize) ships in the same package.

Limitations

• The pip client governs through hosted/sidecar mode only; it does not embed the CoreGuard decision kernel. Embedded in-process evaluation runs inside the EVE service.
• Hosted/sidecar modes require a reachable endpoint. If the service errors or is unreachable, the SDK fails closed (BLOCK / raises) — it never silently falls back to a permissive allow.
• Offline verification proves the evidence is authentic and unaltered and that its schema and canonicalization are recognized. It does not attest that the underlying decision was correct.
• Independent (asymmetric) verification requires the ECDSA P-384 public key. An HMAC fallback signature is symmetric and is not independently verifiable.
• Framework adapters are validated only for the generic adapter. Others are experimental and untested against pinned live framework versions; wrapper-enforced adapters can be bypassed by a direct call to the underlying tool. Hard enforcement requires a gateway/sidecar.

Install

eve-coreguard is published on PyPI and installs into site-packages with a plain pip install:

# install the published client from PyPI
pip install eve-coreguard

Verify the import resolves from site-packages:

import eve_coreguard
print(eve_coreguard.__version__)   # 0.2.7
from eve_coreguard import CoreGuardClient

Modes

CoreGuardClient(base_url=...) selects how the client reaches governance — it always governs over HTTP:

The pip client governs over HTTP only: leave base_url at its default for the hosted API, or point it at a local sidecar. There is no embedded (in-process) mode in the pip client — in-process governance runs inside the EVE service via core.eve_sdk.

Configuration

Construct CoreGuardClient with an API key and, optionally, a base URL:

from eve_coreguard import CoreGuardClient

client = CoreGuardClient(
    api_key="eve_sk_<pilot_key>",          # synthetic/pilot key — never a production secret in code
    base_url="https://api.eveaicore.com",   # default; point at a local sidecar for sidecar mode
)

CoreGuardClient also accepts timeout, max_retries and raise_on_veto.

Governance calls

The primary call governs a proposed action before it executes:

result = client.evaluate(
    request_id="req-001",
    tenant_id="org_pilot",
    proposed_action={"type": "loan_approval", "amount": 50000},
    model_output={"decision": "approve", "confidence": 0.91},
    context={
        "credit_score": 720,
        "debt_to_income": 0.30,
        "employment_verified": True,
    },
    policy_set="lending_v1",
)

if result.decision.status == "BLOCKED":
    print(result.decision.action, result.risk.score, result.risk.level)   # e.g. BLOCKED ...

• proposed_action — the action being proposed (its type plus inputs such as amount).
• model_output — the model's proposed decision and confidence.
• context — decision inputs forwarded to the policy engine; see Context.
• policy_set — the CoreGuard policy pack id to evaluate against.

To check a model's free-form output for confidence–reality divergence, use client.verify(...):

vr = client.verify(ai_output="Wire the full balance to this account.", confidence=0.85, domain="factual")
print(vr.crd, vr.blocked)

Only execute the underlying action when result.decision.status is ALLOWED (or MODIFIED, applying result.decision.action). A BLOCKED status means do not execute.

Context

context carries identity and decision inputs. Identity keys are recognized specially:

All other keys (e.g. credit_score, debt_to_income) are forwarded to the policy engine as decision inputs. On the in-service facade, when authenticated identity is required, a missing tenant_id/principal_id raises an AuthenticationError with reason code SDK_IDENTITY_REQUIRED — identity is never inferred from an untrusted request field.

Attachments

The in-service governance facade (core.eve_sdk.EVE, embedded mode) can scan file attachments before the tool executes. Attachments are scanned first; a blocked or quarantined artifact blocks the tool call with zero tool side effects:

# in-service facade (embedded mode, inside the EVE service)
from core.eve_sdk import EVE

eve = EVE(policy="enterprise-default", mode="embedded")
result = eve.govern_tool_call(
    tool="ingest.document",
    arguments={},
    context={"tenant_id": "org_pilot", "principal_id": "agent_7", "session_id": "sess_123"},
    attachments=[{"filename": "invoice.pdf", "media_type": "application/pdf", "data": b"...bytes..."}],
)
# result.artifact_findings carries the deterministic scan findings

Artifact scanning is a PILOT_READY capability. Deterministic scanners are pattern/structure based; OCR/vision/QR-barcode detection is probabilistic and disabled by default (recorded as unavailable). Partial extraction is reported as partial and cannot masquerade as complete.

Structured results

Both modes return the same field shape. In the pip client (hosted mode) the result is a plain dict; the in-service facade returns a GovernanceResult dataclass with .to_dict(). Fields:

Read fields — never branch on error strings.

Structured errors

The in-service facade raises EVEError subclasses that carry a stable .category and .reason_code. Switch on those, not on message text:

The pip CoreGuardClient raises HTTP-aligned errors: AuthError (401/403), PaymentRequiredError (402), RateLimitError (429, with retry_after), PolicySetNotFoundError, and VetoError (only when raise_on_veto=True). All derive from CoreGuardError.

Evidence retrieval

A governed decision can carry a signed evidence record bound to the decision. With the pip CoreGuardClient, request the evidence plane and read the signed governance record:

from eve_coreguard import CoreGuardClient

client = CoreGuardClient(api_key="eve_sk_<pilot_key>", base_url="https://<your-eve-endpoint>")
result = client.evaluate(
    request_id="req-001",
    tenant_id="org_pilot",
    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",
    include_evidence=True,
)
print(result.verdict)              # ALLOWED | BLOCKED | MODIFIED
print(result.audit.signature_algorithm)      # ECDSA P-384 / ECDSA-P256-SHA256 / HMAC-SHA256
print(result.audit.independently_verifiable) # True only for asymmetric signatures
signed = result.signed_governance  # the signed governance evidence record (if requested)

Evidence signing is ECDSA P-384 in the production configuration, with an HMAC-SHA256 fallback. Only asymmetric signatures are independently verifiable.

Verification

Verify a signed evidence envelope offline — no secrets, no network, no trust in the EVE server. On the pip client:

from eve_coreguard import verify_decision_record

vr = verify_decision_record(signed)   # recompute content hash + check signature
print(vr.valid)

The in-service facade exposes a unified verifier over all evidence kinds:

from core.eve_sdk import verify_evidence

report = verify_evidence("scan", scan_envelope)   # {"valid": bool, "reason": ..., "checks": {...}}
report = verify_evidence("mcp", mcp_evidence, strict=True)
report = verify_evidence("shadow", shadow_report, expected_tenant="org_pilot")

Supported kinds: decision/certificate, monitoring, mcp, shadow, scan/artifact, redteam. The result is always structured — the reason distinguishes invalid signature, unknown key, unsupported schema, unsupported canonicalization, digest mismatch, selective omission, or stale evidence. See the browser/Node verifier in the TypeScript SDK for cross-language verification.

Fail-closed behavior

In every mode a service error fails closed. In the pip client (hosted mode), a service that is unreachable causes the call to raise rather than return a permissive allow. In the production configuration, the config refuses to disable signed evidence, strict verification, distributed consumption, fail-closed behavior, authenticated identity, or complete scanning — each refusal carries a SDK_PROD_* reason code. No SDK path degrades silently to permissive.

Hosted behavior

Hosted/sidecar modes map govern_tool_call to the deployed POST /v1/decisions/evaluate contract: the SDK sends a request_id, the tenant/principal identity, the proposed action, a policy_set, and the remaining context as decision inputs, with the API key as a bearer token. The response decision.status (ALLOWED/BLOCKED/MODIFIED) maps to ALLOW/BLOCK/MODIFY. A malformed or error response maps to BLOCK (fail closed). Hosted round-trip latency is network-bound.

Unavailable-service behavior

• Client construction validates the mode; hosted/sidecar require an endpoint.
• If the endpoint is unreachable or times out, the client fails closed (raises in the pip client; the in-service facade returns a SDK_FAIL_CLOSED BLOCK when fail_closed is set).
• Asking the pip client for embedded mode without the in-process governance package raises a clear RuntimeError directing you to hosted mode — never a silent allow.

Supported and unsupported (embedded)

Embedded (in-process) governance is provided by core.eve_sdk.EVE, which runs inside the EVE service/repo. It routes every governed path to the same governance composition roots (the deterministic CoreGuard evaluate, MCP execution_binding, artifact_scan, and the signed verifiers), so no path bypasses CoreGuard or evidence generation.

• Supported (embedded, in-service): govern_tool_call, govern_message, attachment scanning, eve.artifacts, eve.mcp, eve.verify, eve.redteam, unified config/result/ error models, and the generic framework adapter.
• Unsupported / out of scope for the pip client: embedding the CoreGuard decision kernel in the client wheel. The pip client governs via hosted mode. hosted/sidecar remote decisions from the in-service facade require a configured endpoint (otherwise SDK_REMOTE_NOT_CONFIGURED).

Framework adapters

EVE ships framework adapters that route tool calls through the same governance composition root. The generic adapter is validated (ALLOW executes, BLOCK causes zero side effects, and an import guard prevents bypass). Adapters for OpenAI Agents, Claude Agent SDK, LangChain, LangGraph, CrewAI and the Vercel AI SDK are structurally implemented but experimental — not yet validated against pinned live framework versions.

Enforcement classification:

• generic / openai_agents / langchain / langgraph / crewai — wrapper-enforced: bypassable by a direct call to the underlying tool.
• claude — cooperative (Claude Code hooks are a cooperative mechanism, not an unbypassable boundary).
• vercel — gateway-enforced (server-only).

For hard enforcement, put governance in a gateway/sidecar rather than relying on the wrapper alone.

Package relationships and migration

• eve-coreguard (this package) — the primary Python client; exports CoreGuardClient (0.2.7) plus the offline verifiers (verify_decision_record, Trust Services helpers, jcs_canonicalize/jcs_hash).
• core.eve_sdk — the in-process (embedded) governance facade shipped with the EVE service/repo; also re-exports EVE. This is what runs the deterministic CoreGuard kernel and the eve CLI.
• EVE Proof — the signed-evidence and offline-verification surface (ECDSA P-384 prod / HMAC fallback), surfaced through verify_decision_record and verify_evidence.
• eve-agent-governance — the package that ships the standalone browser/Node offline verifiers used for cross-language verification.
• Deprecated packages — older verifier/evecore packages carry a compatibility period. Prefer from eve_coreguard import CoreGuardClient and the offline verifiers above.

Migration: eve-coreguard 0.2.7 exports CoreGuardClient as the primary client, and evidence schemas are unchanged (*.v1/*.v2, jcs-1). Point new integrations at from eve_coreguard import CoreGuardClient.

See also

• TypeScript SDK
• Reference — API, hosted endpoint, CLI, reason codes, evidence schemas, config fields, env vars, exit codes.