Kerneva Docs

Kerneva
Documentation.

Kerneva is the runtime behavior control layer for AI agents performing consequential financial actions. Use these docs to evaluate actions, capture outcomes, investigate reviews, and deploy Kerneva in production.

Start quickstart API reference

Base URLs

Hosted: https://api.kerneva.com
Self-hosted: http://localhost:8080
Auth: Authorization: Bearer <api_key>
Kerneva also supports WorkOS SSO for team-based access control on hosted deployments.

Why Kerneva exists

AI agents increasingly approve refunds, payments, purchases, and other financial actions autonomously. Existing controls validate individual requests. Kerneva evaluates agent behavior over time and returns an execution decision before the business system acts.

Agent -> Kerneva -> Business System
Action -> Evaluation -> Decision -> Operator -> Outcome -> History

What problem it solves: Agent behavior changes over time — amounts creep up, policies get stretched, and individual checks miss the trajectory. Kerneva detects the pattern.

Who it's for: Teams running production AI agents that execute financial actions — refunds, payments, vendor payouts, and purchase approvals.

Integration time

Kerneva is designed for minimal time-to-value. Most teams go from zero to production in under a day.

SDK

30 minutes

Install the Python SDK, configure your API key, and call evaluate() in your agent loop.

REST API

2–4 hours

Integrate via POST /evaluate and PUT /evaluations/{id}/review. Works with any language.

Production rollout

1 day

Deploy in observation mode first, then move through graduated enforcement after calibration passes quality gates. Roll out per agent or per action type.

Code delta

The change is one decision gate before execution.

# Today — direct execution
refund(amount=150.00)

# Tomorrow — gated through Kerneva
decision = kerneva.evaluate(agent_id, session_id, action_type, amount)

if decision == "ALLOW":
  refund(amount=150.00)
elif decision == "REVIEW":
  queue_for_operator_review(evaluation_id)
else:
  stop_execution(reason)

ALLOW

The action is within policy and behavior remains consistent. Execute normally.

REVIEW

The action is unusual or near a boundary. Route it to an operator workflow.

BLOCK

The action exceeds the configured block boundary. Do not execute.

How it works

Request shape

Every evaluation requires these fields:

Field	Type	Required	Description
`agent_id`	string	Yes	Agent performing the action.
`session_id`	string	Yes	Session or workflow identifier.
`action_type`	string	Yes	Action being evaluated, such as `refund` or `vendor_payment`.
`amount`	number	Yes	Financial amount in USD.
`customer_id`	string	No	End-customer identifier. When set, behavioral history is segmented per end-customer so one customer's trajectory does not affect another's.
`metadata`	object	No	Structured context used for review and analysis.

Response shape

Every evaluation returns:

{
  "decision": "REVIEW",
  "risk_score": 0.58,
  "trust_score": 0.72,
  "reason": "Amount is near the configured review boundary",
  "signals": [],
  "failure_classes_detected": ["Optimization Drift"],
  "evaluation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "observation_mode": false,
  "enforcement_mode": "graduated",
  "interaction_count": 5,
  "proposed_action": {"type": "refund", "amount": 150.0},
  "cold_start": {"strategy": "cohort_priors", "confidence": 0.72},
  "trust_signals": {"risk_level": "medium", "near_limit": true},
  "policy_action": "graduated",
  "runtime_version": "1.0.0",
  "signal_version": "1",
  "trust_model_version": "1",
  "taxonomy_version": "1",
  "config_version": "a1b2c3d4"
}

Field	Description
`decision`	`ALLOW`, `REVIEW`, or `BLOCK`.
`risk_score`	Float 0–1. Higher means more likely to exceed policy.
`trust_score`	Float 0–1. Higher means the agent's behavior is consistent with past patterns.
`reason`	Human-readable explanation of the decision.
`signals`	List of detected behavioral signals that contributed to the decision.
`failure_classes_detected`	Failure classifications such as Optimization Drift or Policy Boundary.
`evaluation_id`	UUID for outcome capture, history, and review.
`observation_mode`	When `true`, Kerneva returns a decision but enforcement is advisory.
`enforcement_mode`	Active enforcement mode: `observe`, `graduated`, or `enforce`.
`interaction_count`	Number of interactions in the current session so far.
`proposed_action`	The action that was evaluated, with its type and amount.
`cold_start`	Cold-start confidence and cohort baseline metadata used for graduated enforcement.
`trust_signals`	Summary object: `risk_level` (low / medium / high) and `near_limit`. Detailed detector output is in `signals`.
`policy_action`	The enforcement policy chosen after scoring and cold-start gating.
`runtime_version`	Version of the runtime used for this evaluation.
`signal_version`	Version of the signal detection logic.
`trust_model_version`	Version of the trust model used to compute scores.
`taxonomy_version`	Version of the failure class taxonomy.
`config_version`	Config snapshot identifier for traceability.

Decision lifecycle

Kerneva evaluates actions, applies the configured enforcement mode, and your application records outcomes.

1. Agent requests execution
| 2. Application calls POST /evaluate
| 3. Kerneva returns decision + evaluation_id
| 4. Application executes, queues, or stops
| 5. Application reports outcome via PUT /evaluations/{id}/review
| 6. Kerneva records the session trail for investigation

For money-moving actions, the versioned contract surface adds idempotency and lifecycle on top of this flow: POST /v1/authorize accepts a FinancialAction (operation, amount, counterparty, workflow, declared purpose), returns a DecisionReceipt with a decision token, and guarantees a duplicate request can never produce a second decision; POST /v1/actions/{id}/outcome closes the lifecycle. Schemas at GET /v1/contract. Two zero-integration entry points also exist: the self-hosted evaluation kit, and the Behavioral Findings Report — export your agents' historical actions to CSV and Kerneva replays them offline (nothing persisted) to show what would have been flagged and why. Building on LangChain or LangGraph? See examples/langchain_integration.py for a guarded tool and a pre-execution authorization node.

Outcome capture

After the application acts on the decision, report the result so review trails stay complete.

PUT /evaluations/{evaluation_id}/review

{
  "status": "resolved",
  "resolution": "completed",
  "impact": "{\"external_id\":\"pay_abc123\",\"duration_ms\":842}"
}

Status	Meaning
`unreviewed`	Evaluation is waiting for operator review.
`acknowledged`	An operator has accepted ownership.
`resolved`	The review is complete and an outcome was captured.
`dismissed`	The review was closed as not actionable or abandoned.

History recording

Kerneva stores every evaluation, decision, outcome, and operator note for investigation and audit.

GET /investigations

Query	Description
`decision`	Filter by `ALLOW`, `REVIEW`, or `BLOCK`.
`review_status`	Filter by review state.
`limit`	Maximum number of results.
`assigned_to_user_id`	Show reviews owned by a specific operator.

GET /trace/{session_id}

Returns the session trail used by the investigation UI: events, decisions, scores, signals, reasons, enforcement mode, and runtime versions.

POST /evaluations/{evaluation_id}/notes

Adds operator context to the evaluation review.

Failure modes

Kerneva is designed to fail safely. Every failure mode has a configurable behavior.

Timeout

API timeout

Default client timeout is 5 seconds. The SDK returns a timeout error. Your application should handle the error and apply the configured fallback.

Retry

Retry behavior

The SDK retries on 429 and 503 responses — up to 3 attempts with exponential backoff and jitter. Other server errors fail fast so your fallback policy applies immediately, without hidden retries on the money path.

Fail closed

Fail closed (default)

When Kerneva is unreachable, the action is blocked. This is the SDK default — for financial actions, policy adherence beats availability unless you explicitly decide otherwise.

Fail open

Fail open (opt-in)

Pass fail_open=True to allow the action through when Kerneva is unreachable. Use for non-critical agents where interruption is worse than an unchecked action.

Observation Mode

Observation Mode fallback

Deploy in observation mode first. Kerneva returns decisions but enforcement is advisory. Once calibration passes, move to graduated enforcement and then full enforcement.

Latency and throughput

The evaluation path targets sub-100ms p95. Design targets below are what we engineer against; they are not production SLAs yet.

Metric	Design target	Notes
p95 latency	< 100 ms	Receipt to response for a single evaluation. The engine uses pooled Postgres connections on the hot path.
Scaling behavior	Horizontal	Stateless evaluation nodes; all trajectory state lives in Postgres. Scale out by adding instances.
Hosted rate limits	30 evaluations/min (live), 10/min (test)	Default per-client limits on the hosted API — sized for design-partner integration, not peak production. Higher limits are provisioned per deployment; self-hosted has no imposed limit.
Storage growth	~2 KB per evaluation	Postgres history, signals, and audit rows.

Latency varies by signal configuration and deployment topology. Before enforcement is enabled for an action family, we validate latency and availability targets against your traffic in Observation Mode — measured numbers, not brochure numbers.

Availability

Kerneva behavior under infrastructure degradation depends on deployment mode and client configuration.

Kerneva is down
The SDK surfaces the failure immediately and your configured policy applies: fail-closed blocks the action (default), fail-open allows it. No silent caching or hidden queuing — the failure is explicit, so your fallback is predictable.

Postgres is down
Evaluations fail rather than guess. Behavioral decisions depend on trajectory history, and Kerneva will not return a confident decision without it — the failure propagates to the client, where your fail-open/fail-closed policy applies.

Hosted infra degraded
The hosted API runs on managed serverless infrastructure with Postgres in a single US region today. Platform-level recovery is automatic; multi-region failover is on the roadmap and will ship with published RTO/RPO targets before we accept enforcement traffic that requires them.

Self-hosted mode
Full data residency. No external dependency beyond your Postgres instance. Kerneva operates entirely inside your environment with no egress required.

Hosted vs self-hosted

Kerneva supports two deployment modes. Choose based on your data residency, latency, and operational requirements.

Dimension	Hosted	Self-hosted
Data residency	Stored in Kerneva-managed infrastructure (US region by default).	Fully customer-managed. Data never leaves your VPC, network, or Postgres instance.
Management overhead	Zero — Kerneva manages API, database, signal state, and dashboard upgrades.	Customer responsible for API, Postgres, monitoring, backups, and upgrades.
Latency	~2–10 ms network round-trip from same cloud region. Cross-region adds ~30–80 ms.	Sub-millisecond internal network. No egress overhead. Evaluation overhead is the same.
Throughput	Default rate limits sized for integration and observation-mode rollout (30 evaluations/min live). Higher limits provisioned per deployment.	Dedicated resources. Throughput scales with provisioned CPU and memory. No imposed rate limits.
Upgrades	Managed by Kerneva. Every decision is stamped with the exact runtime, signal, and config versions that produced it.	Customer-controlled. Pull new images or update packages. Full control over upgrade schedule.
Compliance scope	DPA available. SOC 2 program on the roadmap — audit logs, versioned decisions, and config export exist today to support your review.	Customer extends their own compliance boundary. Kerneva provides audit logs and config exports.
Failover	Managed serverless platform, Postgres in a single US region today. Multi-region failover is on the roadmap with published RTO/RPO targets.	Customer-defined. Deploy multi-AZ or multi-region Postgres. Kerneva nodes are stateless and can run behind any load balancer.
Pricing	Per-evaluation pricing with volume tiers. Free development tier available.	Per-instance license. Unlimited evaluations within licensed capacity.
Getting started	Sign up at `api.kerneva.com`. API key in 60 seconds.	Download the Evaluation Kit and run `docker compose up`. No repository required.

Both modes use the same evaluation API, SDK, and signal models. Decisions are identical — the only difference is where the computation runs and who manages the infrastructure.

Versioning

Every evaluation is recorded with the exact versions of every component that produced the decision. Any decision can be explained after the fact with its full context.

Version	Description	What it gives you
Trust model version	The behavioral model version used to compute trust and risk scores.	Stamped on every decision — audit and replay always know which model scored it.
Signal version	The signal detection logic version. New signals may be added in minor versions.	Stamped per decision; detector-level suppression is available today via config.
Taxonomy version	The failure class taxonomy used to classify detected patterns.	Changes are additive. Existing evaluations are not reclassified.
Config version	A content hash of the exact configuration (thresholds, decision policy) applied.	Reverting config restores prior behavior; the audit log records every change with before/after values.

Every evaluation response includes runtime_version, signal_version, trust_model_version, taxonomy_version, and config_version for full traceability. Calibration updates detector quality in config so approved, provisional, and suppressed detectors are visible.

Configuration lifecycle

Thresholds, signal configuration, and taxonomy are managed through the Kerneva API and dashboard. Every change is versioned and audited.

Who changes thresholds
Authenticated team members, through the dashboard or the PUT /config API. Role-based access control (admin / config-manager separation) is on the roadmap.

How changes are audited
Every config change is recorded with the user, timestamp, and before/after values. Exportable via GET /audit-log with event_type=config_change. Two-person approval for production changes is on the roadmap.

How changes take effect
Immediately, and every subsequent decision is stamped with the new config version — so the audit trail shows exactly which decisions ran under which configuration.

How exports work
Full config export via GET /config as JSON. Supports import into another environment via PUT /config. Includes thresholds, decision policy, taxonomy version, and suppressed signals.

Architecture

Every evaluation produces a versioned manifest. This is the full response shape returned by the evaluate endpoint.

{
  "decision": "ALLOW",
  "risk": 0.12,
  "signals": [{"id": "velocity", "details": "Transaction velocity exceeds historical pattern", "failure_class": "Optimization Drift"}, {"id": "near-limit", "details": "Amount within 5% of policy boundary", "failure_class": "Policy Boundary"}],
  "evaluation_id": "evt_9s8K2m",
  "runtime_version": "1.0.0",
  "signal_version": "1",
  "trust_model_version": "1",
  "taxonomy_version": "1",
  "config_version": "a1b2c3d4",
  "evaluated_at": "2026-06-29T14:30:00Z"
}

Every evaluation response includes runtime_version, signal_version, trust_model_version, taxonomy_version, and config_version for full traceability. Manifests are immutable — once written, they cannot be modified or deleted (except by full tenant deletion).

Operator workflow

The operator review loop is the human-in-the-middle for REVIEW decisions: an investigation queue, assignment, notes, and a fully audited resolve/dismiss cycle.

Investigations

Review queue

Every REVIEW decision opens an investigation. Filter by decision, review status, agent, or assignee via GET /investigations or the dashboard.

Review ownership

Assignment

Assign investigations to a named operator and reassign as needed. Assignment changes are recorded in the review audit log.

Context

Notes & replay

Attach operator notes to any evaluation, and replay the full session — every decision, signal, and version stamp — to see how the trajectory developed.

Resolve

Complete review

Mark as resolved with resolution and optional impact notes. The evaluation status moves to resolved, feeding calibration.

Dismiss

Close review

Mark as dismissed. The evaluation is archived but retained for audit — dismissals are labeled data for detector calibration.

Roadmap

Coming next

Slack and webhook notifications, review SLAs with escalation, and bulk actions are on the roadmap — the audit and calibration foundation they build on ships today.

Behavioral evidence

Kerneva's claims are benchmarked, not asserted. The numbers below come from our published benchmark of 1,120 simulated agent trajectories across frontier models — the full methodology and per-model results are in the benchmark report.

Metric	Value	Environment
Trajectories showing behavioral drift	85.2%	1,120 simulated trajectories, all models
Mean detection latency	3.9 sessions	From drift onset to first REVIEW signal
Containment under enforcement	100%	Drifting trajectories held within policy limits
DB / storage growth	~2 KB per evaluation	Postgres, includes history and signals

Latency and throughput figures for your deployment are measured during your own Observation Mode rollout, against your real traffic — not quoted from a brochure.

Appendix

SDK example

Full client example with error handling:

from kerneva_runtime_trust import KernevaClient, KernevaTimeoutError

client = KernevaClient()

try:
    result = client.evaluate(
        agent_id="payment-bot",
        session_id="ses-abc-123",
        action_type="refund",
        amount=150.00,
    )

    if result.decision == "ALLOW":
        execute_refund()
    elif result.decision == "REVIEW":
        queue_for_operator_review(result.evaluation_id)
    else:
        stop_execution(result.reason)

except KernevaTimeoutError:
    logger.warning("Kerneva timeout, applying fail-open")
    execute_refund()

REST examples

Evaluate an action:

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,
    "metadata": {"customer_tier": "premium"}
  }'

Report an outcome:

curl -X PUT https://api.kerneva.com/evaluations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/review \
  -H "Authorization: Bearer $KERNEVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "resolution": "completed",
    "impact": "{\"external_id\":\"pay_abc123\",\"duration_ms\":842}"
  }'

Health check:

curl https://api.kerneva.com/health
# {"status": "ok"}

Deployment example

Self-hosted with Docker Compose (Evaluation Kit — no repo needed):

# Download and start
curl -LO https://kerneva.com/kerneva-evaluation-kit-v0.1.3.zip
mkdir -p evaluation-kit
unzip -q kerneva-evaluation-kit-v0.1.3.zip -d evaluation-kit
cd evaluation-kit
cp .env.example .env
docker compose up

# Verify
curl http://localhost:8080/health

Environment variable	Required	Description
`API_KEY`	Yes	API key for evaluation requests (used as `DEMO_API_KEY` internally).
`POSTGRES_PASSWORD`	Yes	PostgreSQL password.
`CORS_ORIGINS`	No	Allowed dashboard or application origins.
`PORT`	No	API server port. Default is `8080`.

FAQ

Does Kerneva see my agent's prompts or outputs?
No. Kerneva only receives structured action events — agent_id, session_id, action_type, amount, and optional metadata. No prompts, no model output, no conversation text.

Does Kerneva execute actions?
No. Kerneva returns a decision. Your application enforces it. Kerneva never calls refund APIs, payment gateways, or any business system directly.

Can I run Kerneva offline?
Yes. Self-hosted mode runs entirely inside your environment with no external dependencies beyond your Postgres instance.

What happens if I stop sending outcomes?
Evaluations remain in unreviewed state. Operator dashboards show unreviewed counts. History still records the evaluation and decision.

Questions? Email [email protected].

KernevaDocumentation.