Kerneva Runtime Trust

Behavioral safety for financial AI agents.

from kerneva_runtime_trust import guard, RuntimeTrustBlock

@guard(action_type="refund")
def process_refund(amount, customer_id):
    return billing_api.refund(customer_id, amount)

try:
    process_refund(amount=150.0, customer_id="cust_123")
except RuntimeTrustBlock as e:
    print(f"Blocked: {e}")

guard (also available as with_runtime_trust) evaluates every call through Kerneva's /evaluate before the function body runs. On BLOCK the function never executes and RuntimeTrustBlock is raised.

Install

pip install kerneva-runtime-trust

Setup

export KERNEVA_API_KEY="krv_test_abc123"
export KERNEVA_API_URL="https://api.kerneva.com"   # or http://localhost:8080

Getting good signals

Kerneva reasons over an agent's trajectory — within a session and across your end-customers. A single function call doesn't carry that context, so declare it. The two that matter most:

• action_type — match a configured threshold (e.g. "refund"). If it has no threshold the call is observation-only; the SDK logs a warning so you know.
• customer_id — the end-customer, so one customer's trajectory doesn't bleed into another's.

Set them per-call, or ambiently for a whole interaction with session(...):

import kerneva_runtime_trust as kerneva

with kerneva.session(session_id=ticket_id, agent_id="refund-bot",
                     customer_id="cust_123"):
    process_refund(amount=40.0, customer_id="cust_123")
    process_refund(amount=75.0, customer_id="cust_123")   # shares one trajectory

Without a session, each call gets its own session id (so unrelated calls are never merged) and the SDK warns once that session-scoped analysis is off.

Handling REVIEW

By default a REVIEW decision emits a Python warning and proceeds. To route it to a human (hold, queue, escalate), pass an on_review hook — it may raise to halt execution:

def hold_for_approval(ctx):
    if ctx.recommended_decision == "REVIEW":
        raise NeedsApproval(ctx.reason)   # stops the wrapped function

@guard(action_type="refund", on_review=hold_for_approval)
def process_refund(amount, customer_id): ...

Reliability

• Fail-closed by default: if the API is unreachable the action does not run. Pass fail_open=True for non-critical workflows.
• strict=True turns integration warnings (misconfiguration) into a raised KernevaConfigError — useful in development/CI to catch a broken integration.
• Async: decorating an async def returns an async wrapper.

Low-level client

from kerneva_runtime_trust import KernevaClient

client = KernevaClient(api_key="krv_test_abc123")
result = client.evaluate(
    agent_id="refund-bot", session_id="ticket-8842",
    action_type="refund", amount=82.0, customer_id="cust_123",
)
# In Observation Mode nothing is blocked; recommended_decision is the shadow
# verdict — what enforcement WOULD do.
print(result.decision, result.recommended_decision, result.warnings)

See https://github.com/kerneva/runtime-trust for full documentation.