aperture-gate

Deploy a honesty.tools calibration certificate in JavaScript — gate an LLM's answers as ON_MAP / UNCERTAIN / OFF_MAP. The JS port of the Python aperture-gate, byte-identical in behaviour (verified to 6 decimal places against the same conformance vectors).

Two instruments, words first:

1. words — if the answer itself refuses or hedges ("no such company", "I couldn't find any record…"), the verdict is OFF_MAP. The model said so; believe it.
2. fingerprint — otherwise the gate scores [mean logprob, min logprob, mean top-5 entropy, max top-5 entropy] through the certificate's per-model probe. score >= off_map_thr → OFF_MAP; >= uncertain_thr → UNCERTAIN; else ON_MAP.
3. With no logprobs and no refusal, the read degrades honestly to ON_MAP (instrument words-only).

The probe is calibrated per model — deploy the certificate for the model you actually serve. It separates grounded answers from confabulated ones about entities; it is not a general lie detector.

Zero runtime dependencies, Node ≥ 18 (uses global fetch), ESM + CJS, TypeScript types included. MIT.

Install

npm install aperture-gate

Quickstart

import { Gate } from "aperture-gate";

// a registry cert id, a model alias, a URL, or the cert object itself
const gate = await Gate.fromCert("openai/gpt-4o-mini");

// 1) words-only read of any text
gate.readText("I couldn't find any record of that company.");
// { verdict: "OFF_MAP", band: "off-map", instrument: "words", ... }

// 2) read a chat.completions response (request logprobs yourself)
const verdict = gate.readResponse(response);

// 3) wrap an openai client (openai>=4) — logprobs requested automatically, verdict on response.aperture
import OpenAI from "openai";
const client = gate.wrap(new OpenAI());
const r = await client.chat.completions.create({ model: "gpt-4o-mini", messages });
console.log(r.aperture.verdict);

// 4) gate a STREAM in real time — the verdict lands before the answer finishes, and can abort it
const client2 = gate.wrap(new OpenAI(), v => v.verdict === "OFF_MAP");   // onVerdict -> truthy aborts
const stream = await client2.chat.completions.create({ model: "gpt-4o-mini", messages, stream: true });
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");   // stops early if it reads off-map
}
console.log(stream.aperture);   // scored on the first `window` tokens

The verdict

{ verdict, band, instrument, score, refused, hedge, matched, model, expired, signature_verified, n_tokens, n_scored }

instrument is "words" (a refusal won), "fingerprint" (the logprob probe scored it), or "words-only" (no logprobs were available). expired rides every verdict.

Notes

• Certificates are ed25519-signed. The Python SDK verifies signatures against the registry's pinned key (pip install 'aperture-gate[verify]'). JS signature verification is a roadmap item — this package surfaces signature_verified: null rather than claim a check it didn't perform.
• Full method, evidence, and the certificate registry: honesty.tools/docs.