Quickstart

Get an API key

Sign in with Google or GitHub at app.kerneva.com. A Sandbox and a test API key (krv_test_…) are created automatically — the key is shown once in the welcome banner, and you can mint more under Settings → API Keys.

Install the SDK and point it at the API

pip install kerneva-runtime-trust

export KERNEVA_API_KEY="krv_test_..."
export KERNEVA_API_URL="https://api.kerneva.com"

Guard a function

Wrap the function that moves money. Kerneva evaluates the call first; on BLOCK it raises before your code runs, so no money moves.

from kerneva_runtime_trust import guard, session, RuntimeTrustBlock

@guard(action_type="refund")   # match a configured policy limit explicitly
def refund(amount: float, customer_id: str):
    return billing_api.refund(customer_id, amount)

# Scope a whole conversation to one behavioral trajectory:
with session(session_id=ticket_id, agent_id="support-bot", customer_id="cust_123"):
    try:
        refund(amount=150.00, customer_id="cust_123")
    except RuntimeTrustBlock as e:
        # BLOCK, or a REVIEW hold (RuntimeTrustHeld, a subclass) — the refund never ran.
        log.warning("Kerneva stopped the refund: %s", e)

Pass action_type explicitly so it matches a configured policy limit, and wrap related calls in session(...) so Kerneva sees one trajectory per conversation and per end-customer — drift detection is longitudinal, so identity and session scope are what make the signals meaningful. In Observation Mode (the default), BLOCK is never raised — Kerneva records what it would have done (recommended_decision) so you can build confidence before enforcing.

Prefer raw HTTP?

Any language can call /evaluate directly.

curl -X POST https://api.kerneva.com/evaluate \
  -H "Authorization: Bearer $KERNEVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "payment-bot",
    "session_id": "ses-abc-123",
    "action_type": "refund",
    "amount": 150.00,
    "customer_id": "cust_123"
  }'

You get back a decision plus the reasoning behind it:

{
  "decision": "ALLOW",
  "recommended_decision": "REVIEW",
  "risk_score": 0.58,
  "trust_score": 0.72,
  "reason": "Amount is near the configured review boundary",
  "failure_classes_detected": ["Optimization Drift"],
  "observation_mode": true,
  "evaluation_id": "a1b2c3d4-..."
}

In Observation Mode the enforced decision is always ALLOW; recommended_decision is what Kerneva would enforce.