kaval-clients

# Kaval clients

Open-source client libraries for [Kaval](https://usekaval.com). **Register the payers and pages you
care about once. Kaval watches them, extracts structured records against a schema you define, and
delivers each extraction — plus a monthly PDF + manifest rollup — as a webhook the moment it
lands, instead of you polling or re-researching it.** `check()` is the second half: before an agent
acts on one of those facts, send Kaval the action and it answers `ALLOW`, `REVIEW`, or `BLOCK` with a
signed receipt.

**Policy engines decide whether an action is permitted under the rules; Kaval verifies whether the
facts those rules depend on are still true.**

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

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

The 0.7.3 portfolio methods are available in the Node SDK and MCP server.

The Python SDK does not yet expose contracts, fact imports, bulletins, or training review.

## Sources → Extractions → Webhooks

The primary loop needs no LLM call and no polling loop of your own:

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

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

// 1. Watch a payer.
const { source } = await kaval.addSource({
  kind: "entity",
  name: "Aetna",
  intent: "payer policy bulletins",
});

// 2. Register the shape you want extracted, and bind it to the source.
const schema = await kaval.createExtractionSchema({
  name: "prior-auth-bulletin",
  json_schema: {
    type: "object",
    properties: { cpt_code: { type: "string" }, requires_prior_auth: { type: "boolean" } },
    required: ["cpt_code", "requires_prior_auth"],
  },
});
await kaval.updateSource({ id: source.id, extraction_schema_id: schema.id });
// reprocess: true also re-extracts versions that already ran under another schema
// (webhook source_change: "schema_changed"; join on source_version_id).

// 3. Get pushed an extraction.document webhook every time a new bulletin lands, already
//    extracted against the schema — or poll listExtractionRuns() for the same records.
const { webhook_verification } = await kaval.subscribeExtractions({
  callback_url: "https://your-app.example.com/hooks/kaval",
});
```

```py
import os

from kaval import KavalClient

kaval = KavalClient(api_key=os.environ["KAVAL_API_KEY"])

source = kaval.add_source(kind="entity", name="Aetna", intent="payer policy bulletins")
schema = kaval.create_extraction_schema(
    name="prior-auth-bulletin",
    json_schema={
        "type": "object",
        "properties": {"cpt_code": {"type": "string"}, "requires_prior_auth": {"type": "boolean"}},
        "required": ["cpt_code", "requires_prior_auth"],
    },
)
kaval.update_source(source["id"], extraction_schema_id=schema["id"])
# reprocess=True also re-extracts versions that already ran under another schema
# (webhook source_change="schema_changed"; join on source_version_id).
kaval.subscribe_extractions(callback_url="https://your-app.example.com/hooks/kaval")
```

No schema, or want a one-off pull instead of waiting for the next document? `createExtractionRun({
publisher_id, period, extraction_schema_id })` requests a single publisher + period run on demand;
`getExtractionRun()` / `listExtractionRuns()` report its lifecycle
(`processing` → `retry` → `succeeded` / `review_required` / `failed`), and
`listExtractionPackages()` lists the monthly PDF + manifest rollup each publisher/period is packaged
into. This is the schema-bound successor to the free-text bulletin methods (`listBulletins()`,
`getBulletin()`), which are soft-deprecated but keep working.

`check()` is what you call next, right before an agent acts on a fact this loop delivered — it is
covered in the next section.

> **0.6 was a breaking release.** Nine MCP tools collapsed to seven (before later portfolio/extraction tools landed). The whole verification
> surface collapsed to one call. Every removed endpoint now answers a structured
> `410 {"error":"tool_retired","replacement":"/v1/check"}`, and the clients translate that into an
> error that names `check` by name. See [Migrating from 0.5](#migrating-from-05).

## Optional: verify before an agent acts

`check()` is not required to keep facts current — the webhook loop above does that — but it is the
call to make right before an agent relies on one, because it re-derives the verdict from current
state and hands back a signed receipt:

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

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

const result = await kaval.check({
  action: "Approve this prior-authorization request at the in-network rate",
  context: "payer: Aetna; CPT 12345; plan HMO",
  materiality: "critical",
});

if (result.decision !== "ALLOW") {
  // REVIEW is never permission to act.
  holdForHuman(result.facts.filter((fact) => fact.status !== "holds"));
}
```

```py
import os

from kaval import KavalClient

kaval = KavalClient(api_key=os.environ["KAVAL_API_KEY"])
result = kaval.check(action="Approve this prior-authorization request at the in-network rate")
if result["decision"] != "ALLOW":
    hold_for_human(result["facts"])
```

What comes back:

| field          | meaning                                                                                              |
| -------------- | ---------------------------------------------------------------------------------------------------- |
| `decision`     | `ALLOW` (every material fact holds on fresh evidence) · `REVIEW` · `BLOCK`                           |
| `reason_codes` | why, from a closed eight-code taxonomy                                                               |
| `facts[]`      | one row per fact: `status` (`holds`/`changed`/`unknown`), `materiality`, and the sources it rests on |
| `receipt`      | `{ id, signature, signed_at }` — fetch the full signed document with `getReceipt(id)`                |
| `latency_ms`   | `{ compile, lookup, live, total }`                                                                   |

A check on facts a watched source already covers is a database read: no model call, no fetch,
nothing on the wire. A **cold** check does live research before it answers — search, fetch, adjudicate —
and the server lets that run for up to 100s by default, so give the call room. `mode: "fast"`
(equivalently `max_wait_ms: 0`) skips research entirely and reports anything it could not settle as
`unknown`, which is `REVIEW`.

The decision table is published, so the receipt's fact list re-derives the verdict offline, and the
Ed25519 public keys are served unauthenticated at `GET /v1/proof-verification-keys/:kid` — checking a
receipt needs no Kaval account and no API key.

The verifier that does it for you ships **inside the SDK**: `@usekaval/kaval/verify` is a
dependency-free subpath export of `@usekaval/kaval`, and the same package ships a
`kaval-receipt-verify` CLI. Neither needs a Kaval account, an API key, or Kaval's database; the only
request either can make is for the public keyset, and that request is optional. Hand it a receipt and
a keyset. It answers three questions by default and one optional verdict question:

1. **Cryptographic validity** — does the Ed25519 signature cover the exact canonical unsigned bytes?
2. **Key trust** — is that `key_id` active or benignly retired, rather than revoked or compromised?
3. **Freshness** — `fresh`, `recheck_due`, `expired`, `not_yet_issued`, or `unknown`.
4. **Verdict derivation** — does the receipt's fact list produce its stated verdict and reason codes?

A valid signature proves who sealed those exact bytes. It does not prove the claim is still true, or
that the key is still trusted, which is why the three answers never collapse into one boolean.

```ts
import {
  extractReceipt,
  parseJsonStrict,
  verifyReceipt,
} from "@usekaval/kaval/verify";

const receipt = extractReceipt(parseJsonStrict(receiptText));
const result = verifyReceipt(receipt, parseJsonStrict(keysetText), {
  derive_verdict: true,
});

result.cryptographic.valid; // the signature covers these exact canonical bytes
result.key.trusted; // the signing key is not revoked or compromised
result.freshness.status; // separate fact — a check receipt carries no expiry, so `unknown`
result.decision?.matches; // the published table reproduced the verdict and reason codes
```

```bash
# Reproducible audit: archive the keyset beside the receipt and stay entirely offline.
npx -p @usekaval/kaval kaval-receipt-verify verify receipt.json --keyset keys.json
npx -p @usekaval/kaval kaval-receipt-verify verify receipt.json --keyset keys.json --derive-verdict

# Or resolve the key over HTTPS from the unauthenticated endpoint.
npx -p @usekaval/kaval kaval-receipt-verify verify receipt.json \
  --key-url https://api.usekaval.com/v1/proof-verification-keys
```

Exit `0` means the signature is valid and the key is trusted; a stale receipt still exits `0`,
because freshness is a separate fact — pass `--require-fresh` to make anything but `fresh` non-zero.
Exit `1` is a completed but unaccepted verification, `2` an input, I/O, or discovery failure. Parse
untrusted receipt text with `parseJsonStrict`, not `JSON.parse`: duplicate members and lossy numbers
are evidence, and `JSON.parse` throws that evidence away before any verifier can see it.

## Keep it warm: watch the sources

A check is a database read when the facts it needs are already backed