Kaval

Open-source client libraries for Kaval — the freshness gate for AI agents. Before your agent acts on a belief it already holds (a cached fact, a stored field, a retrieved RAG chunk, a prior answer), Kaval independently re-derives the truth from the live world and returns a typed, abstaining verdict your agent can branch on.

These are thin HTTP clients for the hosted Kaval API (https://api.usekaval.com). Create an API key at usekaval.com.

The Node, Python, and MCP surfaces automatically attach a unique idempotency key to billable operations and reuse it for one bounded retry only when the transport outcome is ambiguous or the API is still finalizing that operation.

Package	Language	Install	Source
@usekaval/kaval	Node / TypeScript	npm i @usekaval/kaval	sdks/node
kaval	Python	pip install kaval	sdks/python
@usekaval/mcp	MCP server	npx -y @usekaval/mcp	packages/mcp

Node

import { Kaval } from "@usekaval/kaval";

const kaval = new Kaval({ apiKey: process.env.KAVAL_API_KEY });

const proof = await kaval.audit({
  text: "Acme is eligible for a $12,000 refund",
  as_of: new Date().toISOString(),
  intended_action: "Issue the refund",
  materiality: "critical",
  reversibility: "irreversible",
});
const gate = await kaval.gateAction({
  proof_id: proof.proof_id,
  material_claim_ids: proof.action_decision.material_claim_ids,
  threshold: proof.action_decision.threshold,
  action: proof.research_contract.action,
});
if (
  gate.enforcement?.controlApplied === true &&
  gate.enforcement.executionAllowed !== true
) {
  throw new Error("Kaval blocked the action");
}
if (
  gate.enforcement === undefined &&
  (gate.state !== "current" || gate.decision.decision !== "ALLOW")
) {
  throw new Error("Kaval did not allow the action");
}
// controlApplied === false is shadow mode: observe wouldAllow without controlling the action.

const { act, status, reason } = await kaval.verify({
  belief: "Acme is on our Enterprise plan",
  url: "https://billing.acme.com/account",
  held_at: "2026-03-01T00:00:00Z",
});
if (!act) {
  // status ∈ stale | contradicted | unsupported | insufficient — re-research before acting.
}

Python

from kaval import KavalClient

kaval = KavalClient(api_key=os.environ["KAVAL_API_KEY"])
decision = kaval.verify(belief="Acme is on our Enterprise plan")
if not decision["act"]:
    ...  # re-research before acting

MCP

KAVAL_API_KEY=kv_live_… npx -y @usekaval/mcp

Exposes proof_audit + proof_gate for the full action-verification protocol, plus currentness_verify, currentness_check, …_extract_and_check, …_scan_store, …_monitor, and report_outcome over stdio. See packages/mcp.

API origin env vars

Two names exist on purpose — they are not interchangeable:

Consumer	Variable	Reads env?
Python SDK / MCP	KAVAL_BASE_URL	yes
Node @usekaval/kaval	—	pass baseUrl in constructor
Marketing site proxy (apps/web)	KAVAL_API_URL	yes (server only)

Use the same origin value in both vars when self-hosting (e.g. http://localhost:8787). See SELFHOST.md in the core repo.

Development

pnpm install
pnpm check        # build + lint + typecheck + test (the JS packages)

# Python SDK
cd sdks/python && pip install -e ".[dev]" && pytest

License

Apache-2.0.