Python SDK

Govern a tool call

Example status: illustrative, not runnable as written. The Python examples on this page are built on an embedded in-repo facade imported as core.eve_sdk (an EVE(...) object with govern_* methods). That module is not present in the current repository and is not published on any registry, so these snippets raise ModuleNotFoundError if run. They are kept because they show the intended governance flow. For code that runs today, use the published client: pip install eve-coreguard, then from eve_coreguard import CoreGuardClient and call client.evaluate(...), with offline evidence checking via client.verify_evidence(...) or the standalone verify_decision_record. See the CoreGuard integration guide and the Python SDK reference.

Route a tool call through EVE so it is checked before the side effect runs. EVE CoreGuard makes a deterministic ALLOW / BLOCK / MODIFY decision, no LLM is in that decision path, and the decision can produce signed evidence you can verify offline.

Prerequisites

The EVE SDK installed (see install.md).
For a fully local run, the embedded service facade from the EVE repo (from core.eve_sdk import EVE). For a client-only run, a reachable hosted endpoint and from eve_coreguard import CoreGuardClient.
A synthetic tool (recording, no real side effects) for testing. Do not use production credentials.

Installation

pip install eve-coreguard   # hosted client
# or run the embedded example from the EVE repo checkout

Runnable code

This uses the embedded facade and a recording tool (mirrors examples/eve_sdk/govern_tool_call.py):

from core.eve_sdk import EVE, verify_evidence

IDENT = {"tenant_id": "acme", "principal_id": "agent-1", "session_id": "sess-1"}

eve = EVE(policy="lending_v1", mode="embedded")

# Ask EVE before doing anything with a side effect.
decision = eve.govern_tool_call(
    tool="loan_approval",
    arguments={"amount": 1000},
    context={**IDENT, "credit_score": 760, "debt_to_income": 0.15, "employment_verified": True},
)
print("action:", decision.action, "allowed:", decision.allowed)

if decision.allowed:
    # Only now run the real tool.
    print("executing loan_approval")

With the public hosted client, use from eve_coreguard import CoreGuardClient, construct it with CoreGuardClient(api_key="eve_sk_...") (optionally base_url=... to target your hosted CoreGuard API), and call client.evaluate(...) to check the action before the side effect.

Expected result

A low-risk request returns action = ALLOW, allowed = True; you then run the tool.
A high-risk request (for example amount=500000 with credit_score=480, debt_to_income=0.9, employment_verified=False) returns action = BLOCK, allowed = False, with reason_codes explaining why — and the tool is never called.

Evidence output

Each decision carries a signed certificate bound to that decision:

GovernanceResult{action: ALLOW, reason_codes: [...], decision_id: "...", certificate: {...}}
certificate.llm_in_decision_path == false

The certificate is signed with ECDSA P-384 (AWS KMS) in the production configuration (HMAC-SHA256 fallback).

Verification

Verify the decision evidence independently, without trusting the EVE server:

result = verify_evidence("decision", decision.certificate, expected_tenant="acme")
print(result["valid"], result["reason"])

Independent (asymmetric) verification requires the ECDSA P-384 public key. See verify-evidence-offline.md.

Failure example

If the governance service is unreachable, the SDK fails closed:

try:
    eve.govern_tool_call(tool="loan_approval", arguments={"amount": 1000}, context=IDENT)
except Exception as err:
    print("fail-closed (no silent allow):", err)

The hosted client returns a BLOCK on service-unavailable rather than raising. In neither case does the SDK silently allow the action.

Production considerations

Always place the govern_tool_call check before the code path that produces the side effect, and treat BLOCK as terminal for that call.
Identity (tenant_id, principal_id, session_id) should come from your authenticated context; in the hosted/MCP path, server-derived identity is authoritative and forged headers are rejected.
Wrapping a tool in a Python wrapper is convenient but a direct call to the underlying tool bypasses the wrapper. For hard enforcement, use a gateway or sidecar boundary.

Limitations

CoreGuard deterministic evaluation is PILOT_READY. The claim covers the governance verdict only; the governed application may still use LLMs elsewhere.
The pip client reaches CoreGuard via hosted mode (needs an endpoint); embedded in-process evaluation runs inside the EVE service.
Signed decision evidence is SUPPORTED, but independent verification needs the ECDSA P-384 public key; the HMAC fallback is symmetric and not independently verifiable.

Next step

Wrap an entire agent's tool surface with govern-an-agent.md, or require a human approval step with require-human-approval.md.