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 EVE

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.2 (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-07-20). The corrected release-candidate wheel is eve-coreguard 0.2.2 — it exports EVE (SHA-256 wheel 1bee61c3… / sdist 38952487…, reproducible from committed source) and is distributed privately for pilots; not yet on PyPI. The only build currently on PyPI is a pre-release-candidate 0.2.1 (a different build, SHA-256 4fa7e7fa…) whose top-level export is CoreGuardClient and which does not export EVE — so a plain public pip install eve-coreguard + from eve_coreguard import EVE fails today. For the EVE entry point install the pilot 0.2.2 wheel (below); once 0.2.2 is published, pip install eve-coreguard>=0.2.2 will be the public path and the pre-RC 0.2.1 will be yanked. verify_decision_record is available on both builds.

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 Ed25519 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

The package builds from committed source as a wheel/sdist and installs into site-packages outside the repository. During a pilot you install from the private artifact you were given:

# from a local wheel provided for your pilot
pip install ./eve_coreguard-0.2.2-py3-none-any.whl

# or from a private index configured for your pilot
pip install --index-url https://<your-private-index>/simple eve-coreguard==0.2.2

Verify the import resolves from site-packages:

import eve_coreguard
print(eve_coreguard.__version__)   # 0.2.2
from eve_coreguard import EVE

Modes

EVE(mode=...) selects how the client reaches governance:

In the pip client, embedded raises a clear RuntimeError unless the in-process governance package is importable (i.e. you are running inside the EVE service). For client integrations, use hosted with an endpoint.

Configuration

Construct EVE with the policy set, mode, endpoint and API key:

from eve_coreguard import EVE

eve = EVE(
    policy="lending_v1",             # a CoreGuard policy pack id
    mode="hosted",
    endpoint="https://<your-eve-endpoint>",
    api_key="eve_sk_<pilot_key>",    # synthetic/pilot key — never a production secret in code
)

The lower-level CoreGuardClient (below) accepts timeout, max_retries and raise_on_veto.

Governance calls

The primary call governs a proposed tool/function call before it executes:

result = eve.govern_tool_call(
    tool="loan_approval",
    arguments={"amount": 50000},
    context={
        "tenant_id": "org_pilot",
        "principal_id": "agent_7",
        "session_id": "sess_123",
        "credit_score": 720,
        "debt_to_income": 0.30,
        "employment_verified": True,
    },
)

if not result["allowed"]:
    print(result["action"], result["reason_codes"])   # e.g. BLOCK [...]

• tool — the name of the tool/function being proposed.
• arguments — the call arguments. A numeric amount is forwarded into the proposed action; other arguments are passed as-is.
• context — see Context.

govern_message governs a free-form request (mapped to a message action):

result = eve.govern_message(
    message="Wire the full balance to this account.",
    context={"tenant_id": "org_pilot", "principal_id": "agent_7", "session_id": "sess_123"},
)

Only execute the underlying tool when result["allowed"] is True. A BLOCK (or REQUIRE_APPROVAL / QUARANTINE on the in-service facade) 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)      # Ed25519 / 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 Ed25519 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 EVE (0.2.2), plus the lower-level CoreGuardClient and 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 (Ed25519 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 EVE and the offline verifiers above.

Migration: eve-coreguard 0.2.2 adds EVE backward-compatibly — CoreGuardClient and all prior exports are unchanged, and evidence schemas are unchanged (*.v1/*.v2, jcs-1). Legacy imports keep working. Move new integrations to from eve_coreguard import EVE.

See also

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