EVE CoreGuard SDK — Reference

Consolidated reference for the Python API, TypeScript API, hosted decision endpoint, the eve CLI, reason codes, evidence schemas, config fields, environment variables, and exit codes. Grounded in the release-candidate SDK surface.

Readiness

• Python eve-coreguard 0.2.2 and TypeScript @eve/coreguard 0.1.0-rc1 are release-candidate core clients (SDK core is a RELEASE CANDIDATE WITH EXCLUSIONS).
• Neither package is published to a public registry yet; install from a pilot/private artifact.
• The pip client governs via hosted mode; embedded (in-process) governance is the EVE service. Framework adapters other than the generic adapter are experimental.

Limitations

• Hosted/sidecar modes require a reachable endpoint. On a service error the SDK fails closed (BLOCK / raises); no path degrades to a permissive allow.
• Offline verification proves evidence authenticity, integrity, schema, and canonicalization — not the correctness of the underlying decision.
• Independent verification needs the Ed25519 public key; an HMAC fallback signature is symmetric and not independently verifiable.
• jcs-1 is a constrained RFC 8785 profile: it does not serialize non-integer floats / NaN / Infinity (fail-closed). Signed governance artifacts stay within the supported value domain (e.g. rates carried as integer permille).
• The eve CLI ships with the EVE service/repo (core.eve_sdk), not with the pip client.

Python API

from eve_coreguard import EVE — the primary entry point.

EVE(policy: str = "enterprise-default", mode: str = "hosted",
    api_key: str = "", endpoint: str = "", **kwargs)

eve.govern_tool_call(*, tool: str,
                     arguments: dict | None = None,
                     context: dict | None = None) -> dict

eve.govern_message(*, message: str, context: dict | None = None) -> dict   # in-service facade

eve.verify(kind: str, evidence: dict, **kwargs) -> dict

Lower-level client and offline verifiers (also exported from eve_coreguard):

CoreGuardClient(api_key, base_url="https://api.eveaicore.com",
                timeout=30.0, max_retries=3, raise_on_veto=False)
client.evaluate(request_id, tenant_id, proposed_action, model_output,
                context, policy_set, include_evidence=False) -> EvaluationResult

verify_decision_record(evidence) -> VerificationResult
recompute_content_hash(...) ; content_digest(...) ; derive_key_metadata(...)
fetch_public_key_pem(...)

# Trust Services (offline artifact verification)
jcs_canonicalize(obj) ; jcs_hash(obj)
verify_custody_manifest(...) ; verify_published_root(...)
verify_merkle_inclusion(...) ; verify_bulk_report(...) ; verify_witness_receipt(...)

In-service facade (from core.eve_sdk import EVE, embedded mode) adds attachment scanning and subsystem namespaces:

eve.govern_tool_call(*, tool, arguments=None, context=None, attachments=None) -> GovernanceResult
eve.scan_artifact(data, *, filename="", context=None, declared_media_type="")
eve.artifacts.scan(...)          # deterministic artifact scan
eve.mcp.enforce(authorization, executed_intent, **kwargs)   # approved-vs-executed binding
eve.verify(kind, evidence, **kwargs)
eve.redteam.run(**kwargs)

from core.eve_sdk import verify_evidence
verify_evidence(kind, evidence, *, strict=False, expected_tenant=None) -> dict

GovernanceResult fields: allowed, action, reason_codes, matched_rules, policy_version, decision_id, approval_status, evidence_ref, certificate, monitoring_findings, sequence_findings, budget_findings, artifact_findings, binding_status, verification_status, warnings, unsupported. Actions: ALLOW, ALLOW_WITH_FINDINGS, MODIFY, REQUIRE_APPROVAL, QUARANTINE, BLOCK.

TypeScript API

import { EVE } from "@eve/coreguard".

new EVE(opts?: GovernanceConfigInput)
eve.governToolCall({ tool, arguments?, context? }): Promise<GovernanceResult>
eve.governMessage({ message?, context? }): Promise<GovernanceResult>

resolveConfig(opts?): Required<GovernanceConfigInput>
verifyEvidence(evidence, { publicKeyPem? }?): VerifyResult

Action     // frozen enum object of ActionType values
Category   // frozen enum object of error categories
EVEError   // { category, reasonCode, message }

GovernContext identity keys are tenantId, principalId, sessionId, role; other keys are decision inputs. GovernanceResult mirrors the Python fields in camelCase.

Hosted API — POST /v1/decisions/evaluate

Both SDKs (hosted mode) call this contract. Authorization: Bearer eve_<api_key>.

Request:

{
  "request_id": "req-001",
  "timestamp": "2026-07-20T00:00:00Z",
  "tenant_id": "org_pilot",
  "user": {"id": "agent_7", "role": "loan_officer"},
  "proposed_action": {"type": "loan_approval", "amount": 50000},
  "model_output": {"decision": "approve", "confidence": 0.9},
  "context": {"credit_score": 720, "debt_to_income": 0.30, "employment_verified": true},
  "policy_set": "lending_v1"
}

Response (shape):

{
  "request_id": "req-001",
  "decision": {"status": "ALLOWED", "action": "approve_loan_approval"},
  "risk": {"score": 0.2, "level": "LOW", "factors": []},
  "policy_violations": [{"policy_id": "...", "description": "..."}],
  "audit": {
    "audit_id": "...", "timestamp": "...", "hash": "...", "signature": "ed25519-...",
    "policy_version": "...", "org_id": "org_pilot",
    "chain_sequence": 0, "chain_previous_hash": "...", "chain_entry_hash": "..."
  }
}

• decision.status: ALLOWED | BLOCKED | MODIFIED (SDKs map to ALLOW/BLOCK/MODIFY).
• risk.level: LOW | MEDIUM | HIGH.
• audit.signature prefix identifies the scheme: ed25519- / ecdsa-p256- (asymmetric, independently verifiable) or hmac- (symmetric).
• GET /v1/decisions/health — health check.

No LLM is in the CoreGuard decision path; the verdict is computed by deterministic policy code.

eve CLI

Ships with the EVE service/repo (python -m core.eve_sdk.cli ...), not the pip client.

eve govern --tool payments.create --arg amount=5000 \
    --tenant t --principal p --session s [--policy lending_v1] [--json]
eve verify <kind> <evidence.json> [--strict] [--tenant <t>]
eve redteam
eve version
eve diagnostics
eve config

verify <kind> accepts: decision/certificate, monitoring, mcp, shadow, scan/artifact, redteam. Output is JSON with stable exit codes; diagnostics redact secrets.

Reason codes

Reason codes are stable, machine-readable strings. Switch on these, not on messages.

Decision / disposition: the mapped action (ALLOW, ALLOW_WITH_FINDINGS, MODIFY, REQUIRE_APPROVAL, QUARANTINE, BLOCK) plus policy rule ids in matched_rules.

SDK / config / transport:

Production config guards (config refuses to disable a fail-closed control in production): SDK_PROD_UNSIGNED_FORBIDDEN, SDK_PROD_PERMISSIVE_FORBIDDEN, SDK_PROD_INMEMORY_FORBIDDEN, SDK_PROD_FAIL_OPEN_FORBIDDEN, SDK_PROD_ANONYMOUS_FORBIDDEN, SDK_PROD_INCOMPLETE_SCAN_FORBIDDEN, SDK_PROD_DEVMODE_FORBIDDEN.

MCP governance (example): MCP_UNTRUSTED_PROXY_IDENTITY (a forged identity header is rejected). MCP execution binding records an unknown remote outcome as OUTCOME_UNKNOWN — it is never silently retried.

Evidence schemas

Every governed subsystem emits a signed evidence envelope carrying a content_hash, signature (ed25519-/ecdsa-p256-/hmac-), and canon: "jcs-1". Schema ids:

Notes:

• Artifact scan (.v1) binds the artifact digest to the decision, so a substituted artifact after approval is detected at verification. Records final_action, findings_digest, and a completeness status; partial extraction is reported as partial.
• Red-team report (.v1) records passed/failed and unauthorized_side_effects; blocked attacks produce zero unauthorized side effects. Signed.
• Shadow report (.v2) carries agreement_permille, divergence_by_class, and critical_regressions; divergence figures are modeled effects from replay/sample, not observed production outcomes.
• MCP execution evidence (.v1) shows approved_digests == executed_digests and authorization_consumed, binding the approved MCP request to the executed request. This is at-most-once authorization consumption, not remote exactly-once execution.

The jcs-1 canonicalization has byte-for-byte parity across Python, TypeScript, and the browser for the supported value domain (16/16 supported vectors byte-identical). It is a constrained RFC 8785 profile (see Limitations).

Config fields

Unified GovernanceConfig (Python) / GovernanceConfigInput (TypeScript):

In production, the config refuses to disable signed_evidence, strict_verification, distributed_consumption, fail_closed, require_authenticated_identity, or require_complete_scanning (and refuses dev_mode), each with a SDK_PROD_* reason code. Precedence (in-service facade): constructor args > config file > environment vars > tenant policy > server config. A tenant policy or request field can only raise the security posture, never lower it.

Environment variables (EVE_SDK_*)

Diagnostics also reads JWT_SECRET_KEY presence (never its value).

Exit codes (eve CLI)

See also

• Python SDK
• TypeScript SDK