jevctl 0.1.0 → 0.2.0

package/dist/core/extract.js

@@ -0,0 +1,214 @@
+// Value extraction without hallucination: regexes find candidate spans in
+// code, Jev selects the intended one, code normalizes the verbatim value.
+// Pattern: pre_parsed_value_extraction_cookbook, date_extraction_cookbook.
+import { choice } from "@typesafe-ai/sdk";
+const MONTHS = "jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec";
+export const BUILTIN_FIELDS = {
+    email: {
+        description: "the email address",
+        pattern: /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,
+        normalize: (s) => s.toLowerCase(),
+    },
+    phone: {
+        description: "the phone number",
+        pattern: /\+?\d[\d\s().-]{7,}\d/g,
+        normalize: (s) => (s.startsWith("+") ? "+" : "") + s.replace(/\D/g, ""),
+    },
+    url: {
+        description: "the web address (URL)",
+        pattern: /https?:\/\/[^\s)>"']+/g,
+        normalize: (s) => s.replace(/[.,;:]+$/, ""),
+    },
+    amount: {
+        description: "the monetary amount",
+        pattern: /(?:[$€£]\s?\d[\d,]*(?:\.\d+)?|\d[\d,]*(?:\.\d+)?\s?(?:USD|EUR|GBP|CAD|AUD|dollars|euros|pounds))/g,
+        normalize: (s) => {
+            const currency = /[$]|USD|dollars/i.test(s)
+                ? "USD"
+                : /€|EUR|euros/i.test(s)
+                    ? "EUR"
+                    : /£|GBP|pounds/i.test(s)
+                        ? "GBP"
+                        : (s.match(/CAD|AUD/i)?.[0]?.toUpperCase() ?? null);
+            const value = Number(s.replace(/[^\d.]/g, ""));
+            return { value: Number.isFinite(value) ? value : null, currency };
+        },
+    },
+    date: {
+        description: "the date",
+        pattern: new RegExp(`\\b(?:\\d{4}-\\d{2}-\\d{2}|\\d{1,2}[/.]\\d{1,2}[/.]\\d{2,4}|(?:${MONTHS})[a-z]*\\.? \\d{1,2}(?:st|nd|rd|th)?,? \\d{4}|\\d{1,2}(?:st|nd|rd|th)? (?:${MONTHS})[a-z]*\\.?,? \\d{4})\\b`, "gi"),
+        normalize: (s) => {
+            const cleaned = s.replace(/(\d)(st|nd|rd|th)/i, "$1");
+            const t = Date.parse(cleaned);
+            if (Number.isNaN(t))
+                return null;
+            const d = new Date(t);
+            const pad = (n) => String(n).padStart(2, "0");
+            return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+        },
+    },
+    percent: {
+        description: "the percentage",
+        pattern: /\d+(?:\.\d+)?\s?%/g,
+        normalize: (s) => Number(s.replace(/[^\d.]/g, "")),
+    },
+    number: {
+        description: "the number",
+        // A leading minus only counts when it is not glued to a word (INV-20931 is not negative).
+        pattern: /(?<!\w)-?\d(?:[\d,]*\d)?(?:\.\d+)?/g,
+        normalize: (s) => Number(s.replace(/,/g, "")),
+    },
+};
+/**
+ * Parse a `--want` entry. Forms:
+ *   email                      builtin
+ *   invoice=/INV-\d+/          custom regex, name only
+ *   invoice=/INV-\d+/:the invoice number      custom regex with description
+ *   sender=email:the sender's address         builtin under a custom name/description
+ */
+export function parseFieldSpec(raw) {
+    const eq = raw.indexOf("=");
+    if (eq === -1) {
+        const builtin = BUILTIN_FIELDS[raw.trim()];
+        if (!builtin)
+            throw new Error(`Unknown field "${raw}". Builtins: ${Object.keys(BUILTIN_FIELDS).join(", ")}. Or use name=/regex/:description.`);
+        return { name: raw.trim(), ...builtin };
+    }
+    const name = raw.slice(0, eq).trim();
+    if (!/^[A-Za-z0-9_.-]+$/.test(name))
+        throw new Error(`Field name "${name}" must be letters, digits, _, -, or .`);
+    const rest = raw.slice(eq + 1).trim();
+    const regexMatch = rest.match(/^\/((?:\\.|[^/])+)\/([a-z]*)(?::(.*))?$/s);
+    if (regexMatch) {
+        const [, source, flags, description] = regexMatch;
+        let pattern;
+        try {
+            pattern = new RegExp(source, flags.includes("g") ? flags : `${flags}g`);
+        }
+        catch (err) {
+            throw new Error(`Field "${name}": invalid regex: ${err.message}`);
+        }
+        return { name, description: description?.trim() || `the ${name.replace(/[_.-]+/g, " ")}`, pattern };
+    }
+    const colon = rest.indexOf(":");
+    const builtinName = (colon === -1 ? rest : rest.slice(0, colon)).trim();
+    const builtin = BUILTIN_FIELDS[builtinName];
+    if (!builtin)
+        throw new Error(`Field "${name}": "${builtinName}" is not a builtin and not a /regex/.`);
+    const description = colon === -1 ? builtin.description : rest.slice(colon + 1).trim() || builtin.description;
+    return { name, ...builtin, description };
+}
+export const MAX_FIELD_CANDIDATES = 50;
+/** Unique matches for a field, in order of appearance, capped. */
+export function findCandidates(text, spec) {
+    const seen = new Set();
+    const out = [];
+    spec.pattern.lastIndex = 0;
+    for (const m of text.matchAll(spec.pattern)) {
+        const v = m[0].trim();
+        if (v && !seen.has(v)) {
+            seen.add(v);
+            out.push(v);
+            if (out.length >= MAX_FIELD_CANDIDATES)
+                break;
+        }
+    }
+    return out;
+}
+export const NONE_KEY = "none";
+export function buildExtractRequest(input) {
+    if (input.fields.length === 0)
+        throw new Error("At least one field is required.");
+    const names = new Set();
+    for (const f of input.fields) {
+        if (names.has(f.name))
+            throw new Error(`Duplicate field "${f.name}".`);
+        names.add(f.name);
+    }
+    const candidates = {};
+    const questions = {};
+    for (const f of input.fields) {
+        const found = findCandidates(input.text, f);
+        candidates[f.name] = found;
+        if (found.length === 0)
+            continue;
+        const criteria = Object.fromEntries(found.map((v, i) => [`c${i}`, v]));
+        criteria[NONE_KEY] = `None of the candidates is ${f.description}`;
+        questions[f.name] = choice(`Which candidate in \`candidates.${f.name}\` is ${f.description}${input.context ? ` in this ${input.context}` : ""}? Candidate keys map to the exact text found in the document.`, criteria);
+    }
+    const state = { document: input.text, context: input.context ?? null, candidates };
+    return { state, questions, candidates };
+}
+export async function runExtract(ask, input) {
+    const { state, questions, candidates } = buildExtractRequest(input);
+    // biome-ignore lint/suspicious/noExplicitAny: answer payloads are the SDK's loosely typed union
+    let answers = {};
+    let usage = { input_tokens: 0, output_tokens: 0 };
+    let model = "";
+    let provider = "";
+    if (Object.keys(questions).length > 0) {
+        const res = await ask(state, questions);
+        answers = res.answers;
+        usage = res.usage;
+        model = res.model;
+        provider = res.provider;
+    }
+    const fields = {};
+    for (const f of input.fields) {
+        const found = candidates[f.name] ?? [];
+        if (found.length === 0) {
+            fields[f.name] = {
+                value: null,
+                normalized: null,
+                probability: null,
+                confidence: null,
+                action: "none",
+                candidates: 0,
+                reason: "no candidates matched the pattern",
+            };
+            continue;
+        }
+        const a = answers[f.name];
+        const key = a?.choice;
+        const confidence = typeof a?.confidence === "number" ? a.confidence : null;
+        const probability = key && typeof a?.probabilities?.[key] === "number" ? a.probabilities[key] : null;
+        if (!key || key === NONE_KEY) {
+            fields[f.name] = {
+                value: null,
+                normalized: null,
+                probability,
+                confidence,
+                action: "none",
+                candidates: found.length,
+                reason: key ? "model judged no candidate to be the field" : "no answer",
+            };
+            continue;
+        }
+        const idx = Number(key.slice(1));
+        const value = found[idx] ?? null;
+        let normalized = value;
+        if (value !== null && f.normalize) {
+            try {
+                normalized = f.normalize(value);
+            }
+            catch {
+                normalized = value;
+            }
+        }
+        fields[f.name] = {
+            value,
+            normalized,
+            probability,
+            confidence,
+            action: confidence !== null && confidence >= input.minConfidence ? "auto" : "review",
+            candidates: found.length,
+        };
+    }
+    return { command: "extract", model, provider, fields, min_confidence: input.minConfidence, usage };
+}
+export const EXTRACT_FAIL_CONDITIONS = ["review", "missing"];
+export function extractFailed(out, conditions) {
+    return Object.values(out.fields).some((f) => (conditions.includes("review") && f.action === "review") ||
+        (conditions.includes("missing") && f.action === "none"));
+}
+//# sourceMappingURL=extract.js.map

package/dist/core/extract.js.map

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

package/dist/core/find.js

@@ -21,6 +21,9 @@ export function buildFindRequest(input) {
     return { state, questions, candidates };
 }
 export async function runFind(ask, input) {
+    if (input.absent > input.found) {
+        throw new Error(`--absent (${input.absent}) must not exceed --found (${input.found}).`);
+    }
     const { state, questions, candidates } = buildFindRequest(input);
     const { answers, usage, provider, model } = await ask(state, questions);
     const probabilities = answers.best?.probabilities ?? {};

package/dist/core/find.js.map

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

package/dist/core/match.d.ts

@@ -0,0 +1,55 @@
+import type { AskFn, Usage } from "../provider.js";
+export interface MatchItem {
+    id?: string;
+    text: string;
+}
+export interface MatchPair {
+    left: MatchItem;
+    right: MatchItem;
+}
+export type MatchDecision = "different" | "unclear" | "same";
+export declare const MATCH_LEVELS: Record<MatchDecision, string>;
+/** Cap on pairs per call so the question count stays well inside the request budget. */
+export declare const MAX_PAIRS = 200;
+/** Pairs per API request; more pairs are sent in sequential chunks. */
+export declare const PAIRS_PER_REQUEST = 50;
+export interface MatchInput {
+    pairs: MatchPair[];
+    /** What kind of thing the records are, e.g. "products in a beer catalogue". */
+    kind?: string;
+}
+export interface MatchResult {
+    left: string;
+    right: string;
+    left_text: string;
+    right_text: string;
+    decision: MatchDecision;
+    score: number | null;
+    confidence: number | null;
+    probabilities: Record<MatchDecision, number>;
+}
+export interface MatchOutput {
+    command: "match";
+    model: string;
+    provider: string;
+    results: MatchResult[];
+    summary: Record<MatchDecision, number>;
+    usage: Usage;
+}
+/** All pairs within one list (i < j). */
+export declare function allPairs(items: MatchItem[]): MatchPair[];
+/** Cross product of two lists. */
+export declare function crossPairs(left: MatchItem[], right: MatchItem[]): MatchPair[];
+export declare function buildMatchRequest(pairs: MatchPair[], kind: string | undefined, offset?: number): {
+    state: {
+        kind: string | null;
+        pairs: Record<string, unknown>;
+    };
+    questions: Record<string, unknown>;
+};
+export declare function runMatch(ask: AskFn, input: MatchInput): Promise<MatchOutput>;
+export declare const MATCH_FAIL_CONDITIONS: readonly ["same", "unclear", "different"];
+export type MatchFailCondition = (typeof MATCH_FAIL_CONDITIONS)[number];
+export declare function matchFailed(out: MatchOutput, conditions: readonly MatchFailCondition[]): boolean;
+/** Stable key for a match item, used for dedupe grouping. */
+export declare function itemKey(item: MatchItem, fallback: string): string;

package/dist/core/match.js

@@ -0,0 +1,114 @@
+// Entity matching: do two records describe the same thing? One Score per pair
+// whose three levels are the three things you can do with a pair: unlink it,
+// hand it to a person, or merge it. No threshold to tune; the winning level is
+// the decision. Pattern: entity_alignment cookbook.
+import { score } from "@typesafe-ai/sdk";
+import { chunk, sanitizeId } from "../lib.js";
+export const MATCH_LEVELS = {
+    different: "Different things: the records disagree on an identifying attribute or clearly describe distinct entities",
+    unclear: "Cannot tell: the records are compatible but neither confirms nor rules out that they are the same",
+    same: "Same thing: the records describe one entity, allowing for formatting, abbreviations, or partial information",
+};
+const LEVEL_ORDER = ["different", "unclear", "same"];
+/** Cap on pairs per call so the question count stays well inside the request budget. */
+export const MAX_PAIRS = 200;
+/** Pairs per API request; more pairs are sent in sequential chunks. */
+export const PAIRS_PER_REQUEST = 50;
+/** All pairs within one list (i < j). */
+export function allPairs(items) {
+    const pairs = [];
+    for (let i = 0; i < items.length; i++) {
+        for (let j = i + 1; j < items.length; j++)
+            pairs.push({ left: items[i], right: items[j] });
+    }
+    return pairs;
+}
+/** Cross product of two lists. */
+export function crossPairs(left, right) {
+    const pairs = [];
+    for (const l of left)
+        for (const r of right)
+            pairs.push({ left: l, right: r });
+    return pairs;
+}
+function labelOf(item, fallback) {
+    return item.id ?? fallback;
+}
+export function buildMatchRequest(pairs, kind, offset = 0) {
+    const what = kind ? `these ${kind}` : "these records";
+    const questions = {};
+    const state = {};
+    pairs.forEach((pair, i) => {
+        const key = `pair${offset + i}`;
+        state[key] = {
+            left: { id: labelOf(pair.left, `left${offset + i}`), text: pair.left.text },
+            right: { id: labelOf(pair.right, `right${offset + i}`), text: pair.right.text },
+        };
+        questions[key] = score(`Do \`${key}.left\` and \`${key}.right\` describe the same one of ${what}?`, [
+            MATCH_LEVELS.different,
+            MATCH_LEVELS.unclear,
+            MATCH_LEVELS.same,
+        ]);
+    });
+    return { state: { kind: kind ?? null, pairs: state }, questions };
+}
+export async function runMatch(ask, input) {
+    if (input.pairs.length === 0)
+        throw new Error("At least one pair is required.");
+    if (input.pairs.length > MAX_PAIRS) {
+        throw new Error(`Too many pairs (${input.pairs.length}); the limit is ${MAX_PAIRS} per call. Pre-block candidates first.`);
+    }
+    const usage = { input_tokens: 0, output_tokens: 0 };
+    let model = "";
+    let provider = "";
+    const results = [];
+    let offset = 0;
+    for (const group of chunk(input.pairs, PAIRS_PER_REQUEST)) {
+        const { state, questions } = buildMatchRequest(group, input.kind, offset);
+        const res = await ask(state, questions);
+        usage.input_tokens += res.usage.input_tokens;
+        usage.output_tokens += res.usage.output_tokens;
+        model = res.model;
+        provider = res.provider;
+        group.forEach((pair, i) => {
+            const a = res.answers[`pair${offset + i}`];
+            const raw = a?.probabilities ?? {};
+            const probabilities = Object.fromEntries(LEVEL_ORDER.map((level, idx) => [level, Number((raw[String(idx)] ?? 0).toFixed(4))]));
+            const decision = a
+                ? LEVEL_ORDER.reduce((best, level) => (probabilities[level] > probabilities[best] ? level : best), "different")
+                : "unclear";
+            results.push({
+                left: labelOf(pair.left, `left${offset + i}`),
+                right: labelOf(pair.right, `right${offset + i}`),
+                left_text: pair.left.text,
+                right_text: pair.right.text,
+                decision,
+                score: typeof a?.score === "number" ? Number(a.score.toFixed(4)) : null,
+                confidence: typeof a?.confidence === "number" ? a.confidence : null,
+                probabilities,
+            });
+        });
+        offset += group.length;
+    }
+    return {
+        command: "match",
+        model,
+        provider,
+        results,
+        summary: {
+            different: results.filter((r) => r.decision === "different").length,
+            unclear: results.filter((r) => r.decision === "unclear").length,
+            same: results.filter((r) => r.decision === "same").length,
+        },
+        usage,
+    };
+}
+export const MATCH_FAIL_CONDITIONS = ["same", "unclear", "different"];
+export function matchFailed(out, conditions) {
+    return out.results.some((r) => conditions.includes(r.decision));
+}
+/** Stable key for a match item, used for dedupe grouping. */
+export function itemKey(item, fallback) {
+    return sanitizeId(item.id ?? "") || fallback;
+}
+//# sourceMappingURL=match.js.map

package/dist/core/match.js.map

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

package/dist/core/rerank.d.ts

@@ -0,0 +1,47 @@
+import type { AskFn, Usage } from "../provider.js";
+export interface RerankCandidate {
+    id?: string;
+    text: string;
+}
+export interface RerankInput {
+    query: string;
+    candidates: RerankCandidate[];
+    topK: number;
+    /** Relevance at or above which a candidate is kept. */
+    min: number;
+    /** Optional description of what counts as relevant, e.g. "a passage that states the legal rule". */
+    criteria?: string;
+}
+export interface RerankHit {
+    id: string;
+    relevance: number;
+    kept: boolean;
+    text: string;
+}
+export interface RerankOutput {
+    command: "rerank";
+    model: string;
+    provider: string;
+    query: string;
+    ranked: RerankHit[];
+    kept: string[];
+    min: number;
+    usage: Usage;
+}
+export declare function buildRerankRequest(input: Pick<RerankInput, "query" | "candidates" | "criteria">): {
+    state: {
+        query: string;
+        candidates: {
+            [k: string]: string;
+        };
+    };
+    questions: Record<string, unknown>;
+    candidates: import("../lib.js").WithIds<{
+        id: string;
+        text: string;
+    }>[];
+};
+export declare function runRerank(ask: AskFn, input: RerankInput): Promise<RerankOutput>;
+export declare const RERANK_FAIL_CONDITIONS: readonly ["empty"];
+export type RerankFailCondition = (typeof RERANK_FAIL_CONDITIONS)[number];
+export declare function rerankFailed(out: RerankOutput, conditions: readonly RerankFailCondition[]): boolean;

package/dist/core/rerank.js

@@ -0,0 +1,60 @@
+// Reranking: one independent relevance judgment (Noul) per candidate, all in
+// one request. Unlike `find` (a Choice that always crowns a winner), scores here
+// do not compete, so several candidates can be relevant or none can.
+// Pattern: rerank_typesafe cookbook.
+import { noul } from "@typesafe-ai/sdk";
+import { ensureUniqueIds, MAX_CANDIDATE_CHARS, MAX_CANDIDATES, originalIds, truncate } from "../lib.js";
+export function buildRerankRequest(input) {
+    if (input.query.trim().length === 0)
+        throw new Error("Query must not be empty.");
+    if (input.candidates.length === 0)
+        throw new Error("At least one candidate is required.");
+    if (input.candidates.length > MAX_CANDIDATES) {
+        throw new Error(`Too many candidates (${input.candidates.length}); the limit is ${MAX_CANDIDATES} per call.`);
+    }
+    const candidates = ensureUniqueIds(input.candidates.map((c) => ({ id: c.id ?? "", text: truncate(c.text, MAX_CANDIDATE_CHARS) })), "candidate");
+    const what = input.criteria ?? "information that answers or directly addresses the query";
+    const questions = {};
+    for (const c of candidates) {
+        questions[c.id] = noul(`Does candidate \`candidates.${c.id}\` contain ${what}?`, {
+            true: "The candidate states or directly implies what the query asks for",
+            false: "The candidate is off-topic or only superficially related",
+        });
+    }
+    const state = {
+        query: input.query,
+        candidates: Object.fromEntries(candidates.map((c) => [c.id, c.text])),
+    };
+    return { state, questions, candidates };
+}
+export async function runRerank(ask, input) {
+    const { state, questions, candidates } = buildRerankRequest(input);
+    const { answers, usage, provider, model } = await ask(state, questions);
+    const original = originalIds(candidates);
+    const scored = candidates
+        .map((c, index) => ({
+        id: original.get(c.id) ?? c.id,
+        relevance: Number((typeof answers[c.id]?.noul === "number" ? answers[c.id].noul : 0).toFixed(4)),
+        text: c.text,
+        index,
+    }))
+        .sort((a, b) => b.relevance - a.relevance || a.index - b.index);
+    const ranked = scored
+        .slice(0, input.topK)
+        .map(({ index: _, ...hit }) => ({ ...hit, kept: hit.relevance >= input.min }));
+    return {
+        command: "rerank",
+        model,
+        provider,
+        query: input.query,
+        ranked,
+        kept: ranked.filter((h) => h.kept).map((h) => h.id),
+        min: input.min,
+        usage,
+    };
+}
+export const RERANK_FAIL_CONDITIONS = ["empty"];
+export function rerankFailed(out, conditions) {
+    return conditions.includes("empty") && out.kept.length === 0;
+}
+//# sourceMappingURL=rerank.js.map

package/dist/core/rerank.js.map

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

package/dist/core/route.d.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import type { AskFn, Usage } from "../provider.js";
+declare const argSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"choice">;
+    instructions: z.ZodOptional<z.ZodString>;
+    options: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>]>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"noul">;
+    instructions: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"score">;
+    instructions: z.ZodOptional<z.ZodString>;
+    levels: z.ZodArray<z.ZodString>;
+}, z.core.$strip>], "type">;
+export declare const handlersSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"choice">;
+        instructions: z.ZodOptional<z.ZodString>;
+        options: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>]>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"noul">;
+        instructions: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"score">;
+        instructions: z.ZodOptional<z.ZodString>;
+        levels: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>], "type">>>;
+}, z.core.$strip>, z.ZodString, z.ZodNull]>>;
+export type ArgSpec = z.infer<typeof argSchema>;
+export interface HandlerSpec {
+    description: string | null;
+    args: Record<string, ArgSpec>;
+}
+export type Handlers = Record<string, HandlerSpec>;
+export declare const NONE_HANDLER = "none";
+/** Accept `{name: "description"}`, `{name: null}`, or `{name: {description, args}}`. */
+export declare function parseHandlers(input: unknown): Handlers;
+/** Parse the `a:description,b,c:description` shorthand. */
+export declare function parseHandlerList(raw: string): Handlers;
+export interface RouteInput {
+    request: unknown;
+    handlers: Handlers;
+    instructions?: string;
+    minConfidence: number;
+}
+export interface RoutedArg {
+    type: ArgSpec["type"];
+    value: string | number | null;
+    probability?: number;
+    confidence?: number;
+    probabilities?: Record<string, number>;
+}
+export interface RouteOutput {
+    command: "route";
+    model: string;
+    provider: string;
+    handler: string | null;
+    confidence: number | null;
+    action: "auto" | "review" | "none";
+    probabilities: Record<string, number>;
+    args: Record<string, RoutedArg>;
+    min_confidence: number;
+    usage: Usage;
+}
+export declare function buildRouteRequest(input: Pick<RouteInput, "request" | "handlers" | "instructions">): {
+    state: unknown;
+    questions: Record<string, unknown>;
+};
+export declare function runRoute(ask: AskFn, input: RouteInput): Promise<RouteOutput>;
+export declare const ROUTE_FAIL_CONDITIONS: readonly ["review", "unrouted"];
+export type RouteFailCondition = (typeof ROUTE_FAIL_CONDITIONS)[number];
+export declare function routeFailed(out: RouteOutput, conditions: readonly RouteFailCondition[]): boolean;
+export {};