jevctl 0.1.0

package/dist/core/screen.d.ts

@@ -0,0 +1,38 @@
+import { type ScreenAction } from "../lib.js";
+import type { AskFn, Usage } from "../provider.js";
+export interface ScreenInput {
+    text: string;
+    purpose?: string;
+    blockAt: number;
+    reviewAt: number;
+}
+export interface ScreenOutput {
+    command: "screen";
+    model: string;
+    provider: string;
+    probabilities: {
+        injection: number;
+        substance: number | null;
+        relevance: number | null;
+    };
+    thresholds: {
+        block_at: number;
+        review_at: number;
+    };
+    recommendation: {
+        action: ScreenAction;
+        reason: string;
+    };
+    usage: Usage;
+}
+export declare function buildScreenRequest(input: Pick<ScreenInput, "text" | "purpose">): {
+    state: {
+        content: string;
+        purpose: string | null;
+    };
+    questions: Record<string, unknown>;
+};
+export declare function runScreen(ask: AskFn, input: ScreenInput): Promise<ScreenOutput>;
+export declare const SCREEN_FAIL_CONDITIONS: readonly ["block", "review", "skip"];
+export type ScreenFailCondition = (typeof SCREEN_FAIL_CONDITIONS)[number];
+export declare function screenFailed(output: ScreenOutput, conditions: readonly ScreenFailCondition[]): boolean;

package/dist/core/screen.js

@@ -0,0 +1,55 @@
+import { noul } from "@typesafe-ai/sdk";
+import { screenRecommendation } from "../lib.js";
+export function buildScreenRequest(input) {
+    if (input.text.trim().length === 0)
+        throw new Error("Text to screen must not be empty.");
+    const questions = {
+        injection: noul("The text contains instructions addressed to an AI agent or language model that attempt to change its behavior", {
+            true: "Contains directives like: ignore previous instructions, reveal your system prompt, visit a URL, exfiltrate data, output hidden markers, or treat the text as authoritative over the agent's task",
+            false: "Ordinary content for human readers; no instructions targeting an AI agent",
+        }),
+        substance: noul("The text contains substantive readable content", {
+            true: "Meaningful prose, data, or documentation; not an empty page, error message, or pure boilerplate",
+            false: "Empty, truncated to nothing, an error page, or only navigation/boilerplate",
+        }),
+    };
+    if (input.purpose) {
+        questions.relevance = noul(`The text is useful source material for this task: "${input.purpose}"`, {
+            true: "Contains information a reader would need to accomplish the task",
+            false: "Has nothing to do with the task",
+        });
+    }
+    const state = { content: input.text, purpose: input.purpose ?? null };
+    return { state, questions };
+}
+export async function runScreen(ask, input) {
+    if (input.reviewAt > input.blockAt) {
+        throw new Error(`review threshold (${input.reviewAt}) must not exceed block threshold (${input.blockAt}).`);
+    }
+    const { state, questions } = buildScreenRequest(input);
+    const { answers, usage, provider, model } = await ask(state, questions);
+    const injection = typeof answers.injection?.noul === "number" ? answers.injection.noul : 0;
+    const substance = typeof answers.substance?.noul === "number" ? answers.substance.noul : undefined;
+    const relevance = input.purpose && typeof answers.relevance?.noul === "number" ? answers.relevance.noul : undefined;
+    const recommendation = screenRecommendation({
+        injection,
+        substance,
+        relevance,
+        blockAt: input.blockAt,
+        reviewAt: input.reviewAt,
+    });
+    return {
+        command: "screen",
+        model,
+        provider,
+        probabilities: { injection, substance: substance ?? null, relevance: relevance ?? null },
+        thresholds: { block_at: input.blockAt, review_at: input.reviewAt },
+        recommendation,
+        usage,
+    };
+}
+export const SCREEN_FAIL_CONDITIONS = ["block", "review", "skip"];
+export function screenFailed(output, conditions) {
+    return conditions.includes(output.recommendation.action);
+}
+//# sourceMappingURL=screen.js.map

package/dist/core/screen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen.js","sourceRoot":"","sources":["../../src/core/screen.ts"],"names":[],"mappings":"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"}

package/dist/core/verify.d.ts

@@ -0,0 +1,55 @@
+import { type Verdict, type VerifyAction } from "../lib.js";
+import type { AskFn, Usage } from "../provider.js";
+export interface EvidenceInput {
+    id?: string;
+    text: string;
+}
+export interface VerifyInput {
+    claims: string[];
+    evidence: EvidenceInput[];
+    /** Verdicts at or above this confidence stand automatically. */
+    autoAccept: number;
+}
+export interface VerifyResultItem {
+    id: string;
+    claim: string;
+    verdict: Verdict;
+    probabilities: Record<string, number> | null;
+    confidence: number | null;
+    action: VerifyAction;
+    supporting_evidence: string | null;
+}
+export interface VerifyOutput {
+    command: "verify";
+    model: string;
+    provider: string;
+    auto_accept: number;
+    summary: {
+        verified: number;
+        contradicted: number;
+        unsupported: number;
+        needs_review: number;
+    };
+    results: VerifyResultItem[];
+    usage: Usage;
+}
+/** Build the questions for a verify call. Exported for tests and the `ask --dry-run` path. */
+export declare function buildVerifyRequest(input: Omit<VerifyInput, "autoAccept">): {
+    state: {
+        purpose: string;
+        claims: Omit<import("../lib.js").WithIds<{
+            text: string;
+        }>, "originalId">[];
+        evidence: Omit<import("../lib.js").WithIds<EvidenceInput>, "originalId">[];
+    };
+    questions: Record<string, unknown>;
+    claims: import("../lib.js").WithIds<{
+        text: string;
+    }>[];
+    evidence: import("../lib.js").WithIds<EvidenceInput>[];
+};
+export declare function runVerify(ask: AskFn, input: VerifyInput): Promise<VerifyOutput>;
+export declare const VERIFY_FAIL_CONDITIONS: readonly ["contradicted", "unsupported", "review", "unknown"];
+export type VerifyFailCondition = (typeof VERIFY_FAIL_CONDITIONS)[number];
+/** Does any result match a fail condition? */
+export declare function verifyFailed(output: VerifyOutput, conditions: readonly VerifyFailCondition[]): boolean;

package/dist/core/verify.js

@@ -0,0 +1,74 @@
+import { choice } from "@typesafe-ai/sdk";
+import { ensureUniqueIds, originalIds, RELATION_TO_VERDICT, verifyAction, } from "../lib.js";
+/** Build the questions for a verify call. Exported for tests and the `ask --dry-run` path. */
+export function buildVerifyRequest(input) {
+    if (input.claims.length === 0)
+        throw new Error("At least one claim is required.");
+    if (input.evidence.length === 0)
+        throw new Error("At least one evidence item is required.");
+    const evidence = ensureUniqueIds(input.evidence, "evidence");
+    const claims = ensureUniqueIds(input.claims.map((text) => ({ text })), "claim");
+    const questions = {};
+    for (const claim of claims) {
+        questions[`relation_${claim.id}`] = choice(`How does the evidence relate to claim \`${claim.id}\` (${claim.text})?`, {
+            supports: "The evidence states the claim or directly implies that it is true",
+            contradicts: "The evidence states the opposite of the claim or implies that it is false",
+            says_nothing: "The evidence does not address what the claim asserts, either way",
+        });
+        if (evidence.length > 1) {
+            const criteria = Object.fromEntries(evidence.map((e) => [e.id, null]));
+            criteria.none = "No single evidence item contains the content the claim depends on";
+            questions[`source_${claim.id}`] = choice(`Which evidence item does claim \`${claim.id}\` (${claim.text}) rest on?`, criteria);
+        }
+    }
+    const strip = (items) => items.map(({ originalId: _, ...rest }) => rest);
+    const state = {
+        purpose: "Verify each claim in claims against the evidence in evidence.",
+        claims: strip(claims),
+        evidence: strip(evidence),
+    };
+    return { state, questions, claims, evidence };
+}
+export async function runVerify(ask, input) {
+    const { state, questions, claims, evidence } = buildVerifyRequest(input);
+    const { answers, usage, provider, model } = await ask(state, questions);
+    const original = originalIds(evidence);
+    const results = claims.map((claim) => {
+        const relation = answers[`relation_${claim.id}`];
+        const source = answers[`source_${claim.id}`];
+        const confidence = typeof relation?.confidence === "number" ? relation.confidence : null;
+        const verdict = RELATION_TO_VERDICT[relation?.choice] ?? "unknown";
+        return {
+            id: claim.id,
+            claim: claim.text,
+            verdict,
+            probabilities: relation?.probabilities ?? null,
+            confidence,
+            action: verifyAction(confidence, input.autoAccept),
+            supporting_evidence: source?.choice && source.choice !== "none" ? (original.get(source.choice) ?? source.choice) : null,
+        };
+    });
+    return {
+        command: "verify",
+        model,
+        provider,
+        auto_accept: input.autoAccept,
+        summary: {
+            verified: results.filter((r) => r.verdict === "verified").length,
+            contradicted: results.filter((r) => r.verdict === "contradicted").length,
+            unsupported: results.filter((r) => r.verdict === "unsupported").length,
+            needs_review: results.filter((r) => r.action === "review").length,
+        },
+        results,
+        usage,
+    };
+}
+export const VERIFY_FAIL_CONDITIONS = ["contradicted", "unsupported", "review", "unknown"];
+/** Does any result match a fail condition? */
+export function verifyFailed(output, conditions) {
+    return output.results.some((r) => (conditions.includes("contradicted") && r.verdict === "contradicted") ||
+        (conditions.includes("unsupported") && r.verdict === "unsupported") ||
+        (conditions.includes("unknown") && r.verdict === "unknown") ||
+        (conditions.includes("review") && r.action === "review"));
+}
+//# sourceMappingURL=verify.js.map

package/dist/core/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/core/verify.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+/** Process exit codes. Stable: scripts may depend on them. */
+export declare const EXIT: {
+    /** Command completed and no `--fail-on` condition matched. */
+    readonly OK: 0;
+    /** Usage, configuration, input, or transport error. */
+    readonly ERROR: 1;
+    /** Command completed; a `--fail-on` judgment condition matched. */
+    readonly JUDGMENT: 2;
+};
+/** An error the CLI can present to the user without a stack trace. */
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+/** Reduce an unknown thrown value to a printable message. */
+export declare function describeError(err: unknown): string;

package/dist/errors.js

@@ -0,0 +1,29 @@
+/** Process exit codes. Stable: scripts may depend on them. */
+export const EXIT = {
+    /** Command completed and no `--fail-on` condition matched. */
+    OK: 0,
+    /** Usage, configuration, input, or transport error. */
+    ERROR: 1,
+    /** Command completed; a `--fail-on` judgment condition matched. */
+    JUDGMENT: 2,
+};
+/** An error the CLI can present to the user without a stack trace. */
+export class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = EXIT.ERROR) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+    }
+}
+/** Reduce an unknown thrown value to a printable message. */
+export function describeError(err) {
+    if (err instanceof Error) {
+        const extra = err.status
+            ? ` (HTTP ${err.status})`
+            : "";
+        return `${err.message}${extra}`;
+    }
+    return String(err);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,8DAA8D;IAC9D,EAAE,EAAE,CAAC;IACL,uDAAuD;IACvD,KAAK,EAAE,CAAC;IACR,mEAAmE;IACnE,QAAQ,EAAE,CAAC;CACH,CAAC;AAEX,sEAAsE;AACtE,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,QAAQ,CAAS;IAC1B,YAAY,OAAe,EAAE,WAAmB,IAAI,CAAC,KAAK;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,6DAA6D;AAC7D,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAI,GAA+C,CAAC,MAAM;YACnE,CAAC,CAAC,UAAW,GAA2B,CAAC,MAAM,GAAG;YAClD,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,GAAG,GAAG,CAAC,OAAO,GAAG,KAAK,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./config.js";
+export * from "./core/ask.js";
+export * from "./core/find.js";
+export * from "./core/screen.js";
+export * from "./core/verify.js";
+export * from "./errors.js";
+export * from "./lib.js";
+export * from "./provider.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+// Programmatic API. Everything the CLI does is available as plain functions
+// that take an `AskFn` (see `createAsk`) so you can embed Jev judgments in
+// your own Node scripts without shelling out.
+export * from "./config.js";
+export * from "./core/ask.js";
+export * from "./core/find.js";
+export * from "./core/screen.js";
+export * from "./core/verify.js";
+export * from "./errors.js";
+export * from "./lib.js";
+export * from "./provider.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,2EAA2E;AAC3E,8CAA8C;AAE9C,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC"}

package/dist/input.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Resolve a CLI value that may be a literal, `@path` (file contents), or `-` (stdin).
+ * `@@literal` escapes a leading `@`.
+ */
+export declare function readInput(value: string, label?: string): string;
+export declare function readFile(path: string, label?: string): string;
+/** Read all of stdin once. Later calls return the cached value. */
+export declare function readStdin(label?: string): string;
+/** Test hook. */
+export declare function _resetStdinCache(): void;
+/** Whether a value refers to a file or stdin rather than a literal. */
+export declare function isReference(value: string): boolean;
+/** Human-friendly id for a reference: file basename, `stdin`, or undefined for literals. */
+export declare function referenceId(value: string): string | undefined;
+/** Parse JSON, with a helpful error naming the source. */
+export declare function parseJson<T = unknown>(text: string, label?: string): T;
+/** Split text into non-empty trimmed lines. */
+export declare function nonEmptyLines(text: string): string[];
+/**
+ * Parse a list input: a JSON array of strings if the text starts with `[`,
+ * otherwise one item per non-empty line.
+ */
+export declare function parseList(text: string, label?: string): string[];
+export interface TextItem {
+    id?: string;
+    text: string;
+}
+/**
+ * Parse candidate/evidence items from JSON. Accepts:
+ * - array of strings
+ * - array of {id?, text}
+ * - object map of id -> text
+ */
+export declare function parseItems(text: string, label?: string): TextItem[];

package/dist/input.js

@@ -0,0 +1,116 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { CliError } from "./errors.js";
+/**
+ * Resolve a CLI value that may be a literal, `@path` (file contents), or `-` (stdin).
+ * `@@literal` escapes a leading `@`.
+ */
+export function readInput(value, label = "input") {
+    if (value === "-")
+        return readStdin(label);
+    if (value.startsWith("@@"))
+        return value.slice(1);
+    if (value.startsWith("@"))
+        return readFile(value.slice(1), label);
+    return value;
+}
+export function readFile(path, label = "file") {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (err) {
+        throw new CliError(`Cannot read ${label} ${path}: ${err.message}`);
+    }
+}
+let stdinCache = null;
+/** Read all of stdin once. Later calls return the cached value. */
+export function readStdin(label = "stdin") {
+    if (stdinCache !== null)
+        return stdinCache;
+    if (process.stdin.isTTY) {
+        throw new CliError(`Expected ${label} on stdin but stdin is a terminal. Pipe data in or pass a value.`);
+    }
+    try {
+        stdinCache = readFileSync(0, "utf8");
+    }
+    catch (err) {
+        throw new CliError(`Cannot read stdin: ${err.message}`);
+    }
+    return stdinCache;
+}
+/** Test hook. */
+export function _resetStdinCache() {
+    stdinCache = null;
+}
+/** Whether a value refers to a file or stdin rather than a literal. */
+export function isReference(value) {
+    return value === "-" || (value.startsWith("@") && !value.startsWith("@@"));
+}
+/** Human-friendly id for a reference: file basename, `stdin`, or undefined for literals. */
+export function referenceId(value) {
+    if (value === "-")
+        return "stdin";
+    if (isReference(value))
+        return basename(value.slice(1));
+    return undefined;
+}
+/** Parse JSON, with a helpful error naming the source. */
+export function parseJson(text, label = "input") {
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new CliError(`${label} is not valid JSON: ${err.message}`);
+    }
+}
+/** Split text into non-empty trimmed lines. */
+export function nonEmptyLines(text) {
+    return text
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+/**
+ * Parse a list input: a JSON array of strings if the text starts with `[`,
+ * otherwise one item per non-empty line.
+ */
+export function parseList(text, label = "list") {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("[")) {
+        const parsed = parseJson(trimmed, label);
+        if (!Array.isArray(parsed) || !parsed.every((x) => typeof x === "string")) {
+            throw new CliError(`${label} must be a JSON array of strings.`);
+        }
+        return parsed;
+    }
+    return nonEmptyLines(trimmed);
+}
+/**
+ * Parse candidate/evidence items from JSON. Accepts:
+ * - array of strings
+ * - array of {id?, text}
+ * - object map of id -> text
+ */
+export function parseItems(text, label = "items") {
+    const parsed = parseJson(text, label);
+    if (Array.isArray(parsed)) {
+        return parsed.map((entry, i) => {
+            if (typeof entry === "string")
+                return { text: entry };
+            if (entry && typeof entry === "object" && typeof entry.text === "string") {
+                const { id, text } = entry;
+                return id === undefined ? { text } : { id: String(id), text };
+            }
+            throw new CliError(`${label}[${i}] must be a string or an object with a "text" field.`);
+        });
+    }
+    if (parsed && typeof parsed === "object") {
+        return Object.entries(parsed).map(([id, value]) => {
+            if (typeof value !== "string")
+                throw new CliError(`${label}.${id} must be a string.`);
+            return { id, text: value };
+        });
+    }
+    throw new CliError(`${label} must be a JSON array or object.`);
+}
+//# sourceMappingURL=input.js.map

package/dist/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../src/input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,KAAK,GAAG,OAAO;IACtD,IAAI,KAAK,KAAK,GAAG;QAAE,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAClD,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAClE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,KAAK,GAAG,MAAM;IACnD,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAAC,eAAe,KAAK,IAAI,IAAI,KAAM,GAA6B,CAAC,OAAO,EAAE,CAAC,CAAC;IAChG,CAAC;AACH,CAAC;AAED,IAAI,UAAU,GAAkB,IAAI,CAAC;AAErC,mEAAmE;AACnE,MAAM,UAAU,SAAS,CAAC,KAAK,GAAG,OAAO;IACvC,IAAI,UAAU,KAAK,IAAI;QAAE,OAAO,UAAU,CAAC;IAC3C,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACxB,MAAM,IAAI,QAAQ,CAAC,YAAY,KAAK,kEAAkE,CAAC,CAAC;IAC1G,CAAC;IACD,IAAI,CAAC;QACH,UAAU,GAAG,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAAC,sBAAuB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,iBAAiB;AACjB,MAAM,UAAU,gBAAgB;IAC9B,UAAU,GAAG,IAAI,CAAC;AACpB,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,KAAK,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,IAAI,KAAK,KAAK,GAAG;QAAE,OAAO,OAAO,CAAC;IAClC,IAAI,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,SAAS,CAAc,IAAY,EAAE,KAAK,GAAG,OAAO;IAClE,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAAC,GAAG,KAAK,uBAAwB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9E,CAAC;AACH,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,IAAI;SACR,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAK,GAAG,MAAM;IACpD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,SAAS,CAAU,OAAO,EAAE,KAAK,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;YAC1E,MAAM,IAAI,QAAQ,CAAC,GAAG,KAAK,mCAAmC,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAOD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,KAAK,GAAG,OAAO;IACtD,MAAM,MAAM,GAAG,SAAS,CAAU,IAAI,EAAE,KAAK,CAAC,CAAC;IAC/C,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;YAC7B,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;YACtD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAQ,KAAkB,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvF,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,KAAiB,CAAC;gBACvC,OAAO,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;YAChE,CAAC;YACD,MAAM,IAAI,QAAQ,CAAC,GAAG,KAAK,IAAI,CAAC,sDAAsD,CAAC,CAAC;QAC1F,CAAC,CAAC,CAAC;IACL,CAAC;IACD,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QACzC,OAAO,MAAM,CAAC,OAAO,CAAC,MAAiC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE;YAC3E,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAAE,MAAM,IAAI,QAAQ,CAAC,GAAG,KAAK,IAAI,EAAE,oBAAoB,CAAC,CAAC;YACtF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,QAAQ,CAAC,GAAG,KAAK,kCAAkC,CAAC,CAAC;AACjE,CAAC"}

package/dist/lib.d.ts

@@ -0,0 +1,63 @@
+/** Max candidates in one `find` call. TypeSafe Choice supports up to 255 options. */
+export declare const MAX_CANDIDATES = 250;
+/** Per-candidate text cap (characters) to keep request size bounded. */
+export declare const MAX_CANDIDATE_CHARS = 2000;
+/** Sanitize a caller-supplied id into a safe Choice option key. */
+export declare function sanitizeId(id: string): string;
+export type Identifiable = {
+    id?: string;
+    text?: string;
+};
+export type WithIds<T> = T & {
+    id: string;
+    originalId: string;
+};
+/**
+ * Ensure ids exist, are safe, and are unique. `id` is the sanitized key sent to
+ * the model; `originalId` is what the caller passed (or the generated id).
+ */
+export declare function ensureUniqueIds<T extends Identifiable>(items: T[], fallbackPrefix: string): Array<WithIds<T>>;
+/** Reverse lookup from sanitized id to the caller's original id. */
+export declare function originalIds(items: ReadonlyArray<{
+    id: string;
+    originalId: string;
+}>): Map<string, string>;
+/** Truncate long text with an explicit marker so the model knows it is partial. */
+export declare function truncate(text: string, maxChars: number): string;
+export type Verdict = "verified" | "contradicted" | "unsupported" | "unknown";
+/** Map a verify relation answer to a verdict label (citation-check cookbook). */
+export declare const RELATION_TO_VERDICT: Record<string, Verdict>;
+export type VerifyAction = "auto" | "review";
+/** Does this verdict stand on its own, or should a human confirm it? */
+export declare function verifyAction(confidence: number | null, autoAccept: number): VerifyAction;
+export type ScreenAction = "pass" | "review" | "block" | "skip";
+/**
+ * Screen recommendation from probabilities.
+ * injection: probability the text contains instructions aimed at an AI agent.
+ * substance: probability the text has substantive readable content (optional).
+ * relevance: probability the text is useful for the stated purpose (optional).
+ */
+export declare function screenRecommendation(input: {
+    injection: number;
+    substance?: number;
+    relevance?: number;
+    blockAt: number;
+    reviewAt: number;
+    skipBelow?: number;
+}): {
+    action: ScreenAction;
+    reason: string;
+};
+export type ExistsVerdict = "answered" | "partial" | "absent";
+/** Turn the exists Noul into a document-level verdict (semantic-find cookbook thresholds). */
+export declare function existsVerdict(exists: number, found?: number, absent?: number): ExistsVerdict;
+/** Rank candidate ids by Choice probability, descending. Ties keep caller order. */
+export declare function rankCandidates<T extends {
+    id: string;
+}>(candidates: T[], probabilities: Record<string, number>): Array<T & {
+    probability: number;
+}>;
+/** Parse a comma-separated `--fail-on` list against the allowed values. */
+export declare function parseFailOn<T extends string>(raw: string | undefined, allowed: readonly T[], fallback: T[]): T[];
+/** Parse a probability-like flag (0..1). */
+export declare function parseProbability(name: string, raw: string | number | undefined, fallback: number): number;