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.7 and TypeScript eve-ai-governance 0.3.1 are release-candidate core clients (SDK core is a RELEASE CANDIDATE WITH EXCLUSIONS).
• Both packages are published to public registries — pip install eve-coreguard (PyPI) and npm install eve-ai-governance (npm).
• 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 ECDSA P-384 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 CoreGuardClient — the primary entry point.

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
    # -> .decision.status (ALLOWED|BLOCKED|MODIFIED), .decision.action,
    #    .risk.score, .risk.level; with include_evidence=True, .signed_governance

client.verify(ai_output, confidence=0.85, domain="factual") -> VerifyResult
    # -> .crd (0..1), .blocked

client.authorize_execution(...) ; client.export_audit(limit=10)
client.verify_chain() ; client.get_proof(proof_id)

Offline verifiers (also exported from eve_coreguard):

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

eve-ai-governance (0.3.1) is an offline verification library — plain functions, no client class. e.g. import { verifyDecisionCertificate } from "eve-ai-governance".

// Offline verifiers (public keys only, no network). Each returns a result with a boolean .valid:
verifyDecisionCertificate(cert)          // decision certificate
verifyDecisionRecord(record)             // signed decision record
verifyChain(chain)                       // audit hash-chain
verifyBundle(bundle)                     // replay / export bundle
verifyHmac(payload, signature, key)      // HMAC evidence
verifyDeploymentAttestation(attestation) // deployment attestation
verifyTrustCertificate(cert)             // trust certificate
verifyOnboardingBundle(bundle)           // onboarding bundle
verifyItiSnapshot(snapshot)              // ITI snapshot
verifyTrustRootClosure(closure)          // trust-root closure
validatePolicyPack(pack)                 // policy pack
healthBand(score)                        // health band

// Example:
const result = await verifyDecisionCertificate(cert);
console.log(result.valid ? "VERIFIED" : "FAILED");

The library verifies signed evidence offline and holds no signing secret. There is no TypeScript enforcement client; enforce over the hosted service via the REST API (see below).

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": "kms-ecdsa-p384-...",
    "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: kms-ecdsa-p384- / 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 (kms-ecdsa-p384-/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

GovernanceConfig — configuration for the Python facade and the hosted service (the TS column lists the equivalent camelCase keys). The npm eve-ai-governance package is a verification-only library and is not configured this way:

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