Verrik docs

Verrik is the independent trust layer for AI decisions in regulated industries. These docs cover how to capture, ground, evaluate, and report on every decision your agents make.

Introduction

Verrik sits beside your agents — your own or a vendor's — and turns every autonomous decision into evidence a regulator can trust. It does four things, the four “organs”:

Capture records each decision as a durable, tamper-evident trace. Ground resolves it against your real policy and regulatory rules. Evaluate runs insurance-native graders (fairness, explainability) in shadow mode. Report emits plain-language decision passports and NAIC / EU AI Act documentation.

Quickstart

Install the capture SDK:

npm install @verrik/capture-sdk

Wrap a decision in verrik.record(). Every ctx.tool() and ctx.model() call inside is captured as a hash-chained step:

import { Verrik, InMemoryTraceStore } from "@verrik/capture-sdk";

const verrik = new Verrik({ store: new InMemoryTraceStore() });

const { trace, output } = await verrik.record(
  {
    name: "auto_underwriting_decision",
    subjectId: "APP-1001",
    input: applicant,
    agent: { name: "toy-underwriter", version: "0.1.0", vendor: "in-house" },
  },
  async (ctx) => {
    const risk = await ctx.tool("risk_api.score", { id: applicant.id }, () =>
      scoreRisk(applicant),
    );
    return ctx.model("llm.underwriting_decision", { score: risk.score }, () =>
      decide(risk.score),
    );
  },
);

Independently verify the trace wasn't altered — anyone can, without trusting Verrik:

import { verifyTrace } from "@verrik/capture-sdk";

const result = verifyTrace(trace); // { ok: true, steps: 3 }

Decision traces

A trace is the full, replayable record of one decision: its inputs, every tool and model step, and the outcome. Each step is hashed and chained to the previous (GENESIS_HASH → step 1 → step 2 …), so any tampering breaks the chain and verifyTrace() catches it.

Deterministic replay

Because the DecisionContext captures model, tool, now, uuid, and random, a trace can be replayed bit-for-bit months later — and divergence from the original is reported.

const { divergences } = await verrik.replay(trace);
// [] → reproduced exactly

Decision passport

A decision passport is the per-decision, regulator-ready document: integrity status, outcome, how it was reached, fairness result, and inputs — as plain-language markdown a non-technical examiner can read.

import { renderDecisionPassport } from "@verrik/decision-passport";

const markdown = renderDecisionPassport({ trace, fairness });

Fairness grading

@verrik/grader-fairness computes the adverse-impact (four-fifths) ratio across protected groups, the statistical-parity difference, and per-group rates — with small-sample warnings.

import { gradeFairness, toRecords } from "@verrik/grader-fairness";

const fairness = gradeFairness({
  records: toRecords(traces, { group: "age_band", outcome: "action" }),
  favorable: "quote",
  threshold: 0.8, // four-fifths rule
});

// fairness.adverseImpactRatio → 0.33  (fails four-fifths → review)

NAIC & EU AI Act reports

@verrik/report-naic rolls a portfolio of traces into a model inventory (risk-tiered), an integrity attestation (re-verifies every trace), decision volume, and bias testing — the document a carrier hands an examiner.

import { generateNaicReport, renderNaicReportMarkdown } from "@verrik/report-naic";

const report = generateNaicReport({ traces });
const markdown = renderNaicReportMarkdown(report);

SDK reference

Key exports from @verrik/capture-sdk:

• new Verrik({ store }) — tracer; .record(spec, fn) and .replay(trace).
• DecisionContext — ctx.model, ctx.tool, ctx.now, ctx.uuid, ctx.random.
• verifyTrace(trace) — independent hash-chain integrity check.
• InMemoryTraceStore / FileTraceStore — trace persistence.
• sha256Hex, canonicalize, hashStep, GENESIS_HASH — hashing primitives.

Ingest API

The ingest-api service (Fastify) ingests and serves traces. It uses Postgres when DATABASE_URL is set, otherwise an in-memory store.

POST /v1/traces                # ingest a trace
GET  /v1/traces                # list traces
GET  /v1/traces/:id            # fetch one trace
GET  /v1/traces/:id/passport   # decision passport (markdown)
GET  /v1/reports/naic          # portfolio NAIC report