jevctl 0.1.0 → 0.2.1

package/dist/core/classify.d.ts

@@ -0,0 +1,103 @@
+import type { AskFn, Usage } from "../provider.js";
+export interface LabelDef {
+    label: string;
+    description: string | null;
+}
+/** Nested taxonomy: label -> children (or null for a leaf). */
+export type Taxonomy = {
+    [label: string]: Taxonomy | null;
+};
+export declare const OTHER_LABEL = "other";
+/** Parse `a,b:description,c` into label definitions. Escape a literal comma as `\,`. */
+export declare function parseLabelList(raw: string): LabelDef[];
+/** Accept a JSON array of strings, array of {label, description}, or {label: description} map. */
+export declare function parseLabelJson(parsed: unknown): LabelDef[];
+export interface ClassifyInput {
+    text: unknown;
+    labels: LabelDef[];
+    instructions?: string;
+    /** Add an `other` escape option. */
+    other: boolean;
+    /** Confidence at or above which the label is `auto`; below it, `review`. */
+    minConfidence: number;
+}
+export interface ClassifyOutput {
+    command: "classify";
+    mode: "single";
+    model: string;
+    provider: string;
+    label: string | null;
+    confidence: number | null;
+    action: "auto" | "review";
+    probabilities: Record<string, number>;
+    min_confidence: number;
+    usage: Usage;
+}
+export declare function buildClassifyRequest(input: Pick<ClassifyInput, "text" | "labels" | "instructions" | "other">): {
+    state: unknown;
+    questions: {
+        label: import("@typesafe-ai/sdk").ChoiceQuestion<Record<string, string | null>>;
+    };
+    byKey: Map<string, LabelDef>;
+};
+export declare function runClassify(ask: AskFn, input: ClassifyInput): Promise<ClassifyOutput>;
+export interface ClassifyMultiInput {
+    text: unknown;
+    labels: LabelDef[];
+    instructions?: string;
+    /** Probability at or above which a label applies. */
+    threshold: number;
+}
+export interface ClassifyMultiOutput {
+    command: "classify";
+    mode: "multi";
+    model: string;
+    provider: string;
+    labels: Array<{
+        label: string;
+        probability: number;
+        applies: boolean;
+    }>;
+    applied: string[];
+    threshold: number;
+    usage: Usage;
+}
+export declare function buildClassifyMultiRequest(input: Pick<ClassifyMultiInput, "text" | "labels" | "instructions">): {
+    state: unknown;
+    questions: Record<string, unknown>;
+    byKey: Map<string, LabelDef>;
+};
+export declare function runClassifyMulti(ask: AskFn, input: ClassifyMultiInput): Promise<ClassifyMultiOutput>;
+export interface ClassifyTaxonomyInput {
+    text: unknown;
+    taxonomy: Taxonomy;
+    instructions?: string;
+    other: boolean;
+    minConfidence: number;
+}
+export interface TaxonomyStep {
+    label: string;
+    confidence: number | null;
+    probabilities: Record<string, number>;
+}
+export interface ClassifyTaxonomyOutput {
+    command: "classify";
+    mode: "taxonomy";
+    model: string;
+    provider: string;
+    path: string[];
+    steps: TaxonomyStep[];
+    /** Lowest confidence along the path. */
+    confidence: number | null;
+    action: "auto" | "review";
+    stopped_at_other: boolean;
+    min_confidence: number;
+    usage: Usage;
+}
+export declare function parseTaxonomy(parsed: unknown, path?: string): Taxonomy;
+/** Greedy descent: one Choice per level, follow the winner until a leaf or `other`. */
+export declare function runClassifyTaxonomy(ask: AskFn, input: ClassifyTaxonomyInput): Promise<ClassifyTaxonomyOutput>;
+export type AnyClassifyOutput = ClassifyOutput | ClassifyMultiOutput | ClassifyTaxonomyOutput;
+export declare const CLASSIFY_FAIL_CONDITIONS: readonly ["review", "other", "unlabeled"];
+export type ClassifyFailCondition = (typeof CLASSIFY_FAIL_CONDITIONS)[number];
+export declare function classifyFailed(out: AnyClassifyOutput, conditions: readonly ClassifyFailCondition[]): boolean;

package/dist/core/classify.js

@@ -0,0 +1,216 @@
+// Classification: one label from a set (Choice), one probability per label
+// (Nouls, for multi-label), or a path through a label hierarchy (greedy
+// level-by-level Choice). Patterns: classification_using_confidence,
+// hierarchical_classification.
+import { choice, noul } from "@typesafe-ai/sdk";
+import { sanitizeId } from "../lib.js";
+export const OTHER_LABEL = "other";
+/** Parse `a,b:description,c` into label definitions. Escape a literal comma as `\,`. */
+export function parseLabelList(raw) {
+    return raw
+        .split(/(?<!\\),/)
+        .map((s) => s.replace(/\\,/g, ",").trim())
+        .filter(Boolean)
+        .map((opt) => {
+        const colon = opt.indexOf(":");
+        if (colon === -1)
+            return { label: opt, description: null };
+        return { label: opt.slice(0, colon).trim(), description: opt.slice(colon + 1).trim() || null };
+    });
+}
+/** Accept a JSON array of strings, array of {label, description}, or {label: description} map. */
+export function parseLabelJson(parsed) {
+    if (Array.isArray(parsed)) {
+        return parsed.map((entry, i) => {
+            if (typeof entry === "string")
+                return { label: entry, description: null };
+            if (entry && typeof entry === "object" && typeof entry.label === "string") {
+                const e = entry;
+                return { label: e.label, description: typeof e.description === "string" ? e.description : null };
+            }
+            throw new Error(`labels[${i}] must be a string or an object with a "label" field.`);
+        });
+    }
+    if (parsed && typeof parsed === "object") {
+        return Object.entries(parsed).map(([label, description]) => ({
+            label,
+            description: typeof description === "string" ? description : null,
+        }));
+    }
+    throw new Error("labels must be a JSON array or object.");
+}
+function validateLabels(labels, min = 2) {
+    if (labels.length < min)
+        throw new Error(`At least ${min} labels are required.`);
+    const byKey = new Map();
+    for (const l of labels) {
+        const key = sanitizeId(l.label);
+        if (!key)
+            throw new Error(`Label "${l.label}" has no usable characters.`);
+        if (byKey.has(key))
+            throw new Error(`Labels "${byKey.get(key).label}" and "${l.label}" collide.`);
+        byKey.set(key, l);
+    }
+    return byKey;
+}
+function criteriaFor(byKey, other) {
+    const criteria = Object.fromEntries([...byKey.entries()].map(([k, l]) => [k, l.description]));
+    if (other)
+        criteria[OTHER_LABEL] = "None of the other labels fits";
+    return criteria;
+}
+export function buildClassifyRequest(input) {
+    const byKey = validateLabels(input.labels);
+    const questions = {
+        label: choice(input.instructions ?? "Which label best describes the content?", criteriaFor(byKey, input.other)),
+    };
+    return { state: input.text, questions, byKey };
+}
+export async function runClassify(ask, input) {
+    const { state, questions, byKey } = buildClassifyRequest(input);
+    const { answers, usage, provider, model } = await ask(state, questions);
+    const a = answers.label;
+    const key = a?.choice;
+    const label = key === undefined ? null : key === OTHER_LABEL ? OTHER_LABEL : (byKey.get(key)?.label ?? key);
+    const confidence = typeof a?.confidence === "number" ? a.confidence : null;
+    const probabilities = {};
+    for (const [k, p] of Object.entries((a?.probabilities ?? {}))) {
+        probabilities[k === OTHER_LABEL ? OTHER_LABEL : (byKey.get(k)?.label ?? k)] = p;
+    }
+    return {
+        command: "classify",
+        mode: "single",
+        model,
+        provider,
+        label,
+        confidence,
+        action: confidence !== null && confidence >= input.minConfidence ? "auto" : "review",
+        probabilities,
+        min_confidence: input.minConfidence,
+        usage,
+    };
+}
+export function buildClassifyMultiRequest(input) {
+    const byKey = validateLabels(input.labels, 1);
+    const questions = {};
+    for (const [key, l] of byKey) {
+        const base = input.instructions ?? "Does this label apply to the content?";
+        questions[key] = noul(`${base} Label: "${l.label}"${l.description ? ` (${l.description})` : ""}`, {
+            true: `The label "${l.label}" applies`,
+            false: `The label "${l.label}" does not apply`,
+        });
+    }
+    return { state: input.text, questions, byKey };
+}
+export async function runClassifyMulti(ask, input) {
+    const { state, questions, byKey } = buildClassifyMultiRequest(input);
+    const { answers, usage, provider, model } = await ask(state, questions);
+    const labels = [...byKey.entries()].map(([key, l]) => {
+        const p = typeof answers[key]?.noul === "number" ? answers[key].noul : 0;
+        return { label: l.label, probability: Number(p.toFixed(4)), applies: p >= input.threshold };
+    });
+    return {
+        command: "classify",
+        mode: "multi",
+        model,
+        provider,
+        labels,
+        applied: labels.filter((l) => l.applies).map((l) => l.label),
+        threshold: input.threshold,
+        usage,
+    };
+}
+export function parseTaxonomy(parsed, path = "taxonomy") {
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${path} must be an object mapping labels to children or null.`);
+    }
+    const out = {};
+    for (const [label, children] of Object.entries(parsed)) {
+        if (children === null)
+            out[label] = null;
+        else if (Array.isArray(children)) {
+            // Leaf list shorthand: ["a", "b"] == {"a": null, "b": null}
+            out[label] = Object.fromEntries(children.map((c) => [String(c), null]));
+        }
+        else
+            out[label] = parseTaxonomy(children, `${path}.${label}`);
+    }
+    if (Object.keys(out).length === 0)
+        throw new Error(`${path} has no labels.`);
+    return out;
+}
+/** Greedy descent: one Choice per level, follow the winner until a leaf or `other`. */
+export async function runClassifyTaxonomy(ask, input) {
+    let level = input.taxonomy;
+    const path = [];
+    const steps = [];
+    const usage = { input_tokens: 0, output_tokens: 0 };
+    let model = "";
+    let provider = "";
+    let stoppedAtOther = false;
+    while (level && Object.keys(level).length > 0) {
+        const labels = Object.keys(level).map((label) => ({ label, description: null }));
+        const single = labels.length === 1 && !input.other;
+        if (single) {
+            // Nothing to decide at this level.
+            path.push(labels[0].label);
+            steps.push({ label: labels[0].label, confidence: 1, probabilities: { [labels[0].label]: 1 } });
+            level = level[labels[0].label] ?? null;
+            continue;
+        }
+        const byKey = validateLabels(labels, 1);
+        const where = path.length ? ` within "${path.join(" > ")}"` : "";
+        const questions = {
+            label: choice(`${input.instructions ?? "Which category best describes the content"}${where}?`, criteriaFor(byKey, input.other)),
+        };
+        const res = await ask(input.text, questions);
+        usage.input_tokens += res.usage.input_tokens;
+        usage.output_tokens += res.usage.output_tokens;
+        model = res.model;
+        provider = res.provider;
+        const a = res.answers.label;
+        const key = a?.choice;
+        const probabilities = {};
+        for (const [k, p] of Object.entries((a?.probabilities ?? {}))) {
+            probabilities[k === OTHER_LABEL ? OTHER_LABEL : (byKey.get(k)?.label ?? k)] = p;
+        }
+        const confidence = typeof a?.confidence === "number" ? a.confidence : null;
+        if (key === undefined)
+            break;
+        if (key === OTHER_LABEL) {
+            stoppedAtOther = true;
+            steps.push({ label: OTHER_LABEL, confidence, probabilities });
+            break;
+        }
+        const label = byKey.get(key)?.label ?? key;
+        path.push(label);
+        steps.push({ label, confidence, probabilities });
+        level = level[label] ?? null;
+    }
+    const confidences = steps.map((s) => s.confidence).filter((c) => c !== null);
+    const confidence = confidences.length ? Math.min(...confidences) : null;
+    return {
+        command: "classify",
+        mode: "taxonomy",
+        model,
+        provider,
+        path,
+        steps,
+        confidence,
+        action: confidence !== null && confidence >= input.minConfidence && !stoppedAtOther ? "auto" : "review",
+        stopped_at_other: stoppedAtOther,
+        min_confidence: input.minConfidence,
+        usage,
+    };
+}
+export const CLASSIFY_FAIL_CONDITIONS = ["review", "other", "unlabeled"];
+export function classifyFailed(out, conditions) {
+    if (out.mode === "multi")
+        return conditions.includes("unlabeled") && out.applied.length === 0;
+    if (conditions.includes("review") && out.action === "review")
+        return true;
+    if (out.mode === "single")
+        return conditions.includes("other") && out.label === OTHER_LABEL;
+    return conditions.includes("other") && out.stopped_at_other;
+}
+//# sourceMappingURL=classify.js.map

package/dist/core/classify.js.map

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

package/dist/core/compact.d.ts

@@ -0,0 +1,32 @@
+import type { AskFn, Usage } from "../provider.js";
+import type { CallDecision, CompactOptions, CompactResult, JevAsker, Message } from "../vendor/compaction/types.js";
+export interface CompactInput extends CompactOptions {
+    messages: readonly Message[];
+    /** Below this reduction ratio the compaction is reported as not worth applying. */
+    minReduction: number;
+}
+export interface CompactOutput {
+    command: "compact";
+    model: string;
+    provider: string;
+    reduction: number;
+    worth_it: boolean;
+    min_reduction: number;
+    stats: CompactResult["stats"];
+    decisions: CallDecision[];
+    messages: Message[];
+    usage: Usage;
+}
+/** Adapt an `AskFn` to the library's `JevAsker`, accumulating usage across requests. */
+export declare function askerFrom(ask: AskFn): {
+    asker: JevAsker;
+    usage: Usage;
+    meta: () => {
+        model: string;
+        provider: string;
+    };
+};
+export declare function runCompact(ask: AskFn, input: CompactInput): Promise<CompactOutput>;
+export declare const COMPACT_FAIL_CONDITIONS: readonly ["low-reduction"];
+export type CompactFailCondition = (typeof COMPACT_FAIL_CONDITIONS)[number];
+export declare function compactFailed(out: CompactOutput, conditions: readonly CompactFailCondition[]): boolean;

package/dist/core/compact.js

@@ -0,0 +1,47 @@
+// Verbatim context compaction: ask Jev which old tool calls and results still
+// matter, drop or truncate only those, never summarize. Wraps the vendored
+// fast-jev-compaction library and feeds it jev-cli's provider.
+import { compact, reductionRatio } from "../vendor/compaction/compact.js";
+/** Adapt an `AskFn` to the library's `JevAsker`, accumulating usage across requests. */
+export function askerFrom(ask) {
+    const usage = { input_tokens: 0, output_tokens: 0 };
+    let model = "";
+    let provider = "";
+    const asker = {
+        async ask(state, questions) {
+            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;
+            return { answers: res.answers, model: res.model, usage: res.usage };
+        },
+    };
+    return { asker, usage, meta: () => ({ model, provider }) };
+}
+export async function runCompact(ask, input) {
+    const { messages, minReduction, ...options } = input;
+    if (messages.length === 0)
+        throw new Error("Transcript has no messages.");
+    const { asker, usage, meta } = askerFrom(ask);
+    const result = await compact(messages, asker, options);
+    const reduction = Number(reductionRatio(result).toFixed(4));
+    const { model, provider } = meta();
+    return {
+        command: "compact",
+        model,
+        provider,
+        reduction,
+        worth_it: reduction >= minReduction,
+        min_reduction: minReduction,
+        stats: result.stats,
+        decisions: result.decisions,
+        messages: result.messages,
+        usage,
+    };
+}
+export const COMPACT_FAIL_CONDITIONS = ["low-reduction"];
+export function compactFailed(out, conditions) {
+    return conditions.includes("low-reduction") && !out.worth_it;
+}
+//# sourceMappingURL=compact.js.map

package/dist/core/compact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact.js","sourceRoot":"","sources":["../../src/core/compact.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2EAA2E;AAC3E,+DAA+D;AAG/D,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AA8B1E,wFAAwF;AACxF,MAAM,UAAU,SAAS,CAAC,GAAU;IAClC,MAAM,KAAK,GAAU,EAAE,YAAY,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;IAC3D,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,MAAM,KAAK,GAAa;QACtB,KAAK,CAAC,GAAG,CAAC,KAAe,EAAE,SAAuB;YAChD,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YACxC,KAAK,CAAC,YAAY,IAAI,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC;YAC7C,KAAK,CAAC,aAAa,IAAI,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC;YAC/C,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;YAClB,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;YACxB,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;QACtE,CAAC;KACF,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAU,EAAE,KAAmB;IAC9D,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC;IACrD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IAC1E,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,CAAC;IACnC,OAAO;QACL,OAAO,EAAE,SAAS;QAClB,KAAK;QACL,QAAQ;QACR,SAAS;QACT,QAAQ,EAAE,SAAS,IAAI,YAAY;QACnC,aAAa,EAAE,YAAY;QAC3B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,KAAK;KACN,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,eAAe,CAAU,CAAC;AAGlE,MAAM,UAAU,aAAa,CAAC,GAAkB,EAAE,UAA2C;IAC3F,OAAO,UAAU,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC;AAC/D,CAAC"}

package/dist/core/extract.d.ts

@@ -0,0 +1,58 @@
+import type { AskFn, Usage } from "../provider.js";
+export interface FieldSpec {
+    name: string;
+    /** What the field means; drives the question. */
+    description: string;
+    pattern: RegExp;
+    normalize?: (raw: string) => unknown;
+}
+export declare const BUILTIN_FIELDS: Record<string, Omit<FieldSpec, "name">>;
+/**
+ * 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 declare function parseFieldSpec(raw: string): FieldSpec;
+export declare const MAX_FIELD_CANDIDATES = 50;
+/** Unique matches for a field, in order of appearance, capped. */
+export declare function findCandidates(text: string, spec: FieldSpec): string[];
+export interface ExtractInput {
+    text: string;
+    fields: FieldSpec[];
+    /** Optional context, e.g. "an invoice from a supplier". */
+    context?: string;
+    minConfidence: number;
+}
+export interface ExtractedField {
+    value: string | null;
+    normalized: unknown;
+    probability: number | null;
+    confidence: number | null;
+    action: "auto" | "review" | "none";
+    candidates: number;
+    reason?: string;
+}
+export interface ExtractOutput {
+    command: "extract";
+    model: string;
+    provider: string;
+    fields: Record<string, ExtractedField>;
+    min_confidence: number;
+    usage: Usage;
+}
+export declare const NONE_KEY = "none";
+export declare function buildExtractRequest(input: Pick<ExtractInput, "text" | "fields" | "context">): {
+    state: {
+        document: string;
+        context: string | null;
+        candidates: Record<string, string[]>;
+    };
+    questions: Record<string, unknown>;
+    candidates: Record<string, string[]>;
+};
+export declare function runExtract(ask: AskFn, input: ExtractInput): Promise<ExtractOutput>;
+export declare const EXTRACT_FAIL_CONDITIONS: readonly ["review", "missing"];
+export type ExtractFailCondition = (typeof EXTRACT_FAIL_CONDITIONS)[number];
+export declare function extractFailed(out: ExtractOutput, conditions: readonly ExtractFailCondition[]): boolean;