jevascript 0.1.0

package/dist/questions.d.ts

@@ -0,0 +1,98 @@
+import type { ChoiceOptionSpec, ChoiceQuestion, JsonValue, LevelSpec, SemanticProvider, SemanticQuestion, TruthQuestion } from "./types.ts";
+export interface SharedOptions {
+    provider?: SemanticProvider;
+    timeoutMs?: number;
+    cache?: string | number;
+    /** Rounds used to measure confidence. Implied by `minConfidence`. */
+    samples?: number;
+    minConfidence?: number;
+    detailed?: boolean;
+    /** Identity of the definition this came from, surfaced in observability. */
+    metric?: {
+        name: string;
+        version?: string;
+    };
+}
+export interface TruthCriteria {
+    /** What clearly counts as true. */
+    trueWhen?: string | JsonValue;
+    /** What clearly does not count, even when it looks close. */
+    falseWhen?: string | JsonValue;
+}
+export interface IsOptions extends SharedOptions, TruthCriteria {
+    /** Probability above which the answer reads as true. Defaults to 0.5. */
+    threshold?: number;
+    /** Report probabilities inside the uncertainty band as "unknown". */
+    allowUnknown?: boolean;
+    uncertaintyBand?: readonly [number, number];
+    fallback?: boolean | (() => boolean | Promise<boolean>);
+}
+export interface ScoreOptions extends SharedOptions, TruthCriteria {
+    range?: readonly [number, number];
+    /**
+     * Ordered rubric levels, 2–10 of them, each describing a *situation* rather
+     * than a degree. Supplying these switches from a probability-backed score to
+     * a rubric-backed one.
+     */
+    levels?: readonly (string | LevelSpec)[];
+    /** Treat the criterion as a complete proposition instead of framing it. */
+    asProposition?: boolean;
+    fallback?: number | (() => number | Promise<number>);
+}
+export interface ChooseOptions extends SharedOptions {
+    instructions?: string;
+    fallback?: string | (() => string | Promise<string>);
+}
+/**
+ * Default framing that turns a noun-phrase criterion into a proposition.
+ *
+ * `score("fraud risk")` on its own is a noun phrase, and the model answers what
+ * it is literally asked. Framing it as "This has high fraud risk." gives the
+ * probability a well-defined referent. Override for other languages via
+ * `configureSemantic({ defaults: { scoreFrame } })`.
+ */
+export declare const DEFAULT_SCORE_FRAME: (criterion: string) => string;
+export interface BuiltQuestion {
+    question: SemanticQuestion;
+    options: SharedOptions;
+    operation: "is" | "score" | "choose";
+    range?: readonly [number, number];
+    optionKeys?: readonly string[];
+}
+/** A question that has not been bound to a state yet. Used by `batch()`. */
+export interface QuestionSpec<TValue = unknown> {
+    readonly __value?: TValue;
+    readonly build: (frame: (criterion: string) => string) => BuiltQuestion;
+}
+export declare function buildIs(condition: string | JsonValue, options?: IsOptions): {
+    question: TruthQuestion;
+    options: IsOptions;
+    operation: "is";
+};
+export declare function buildScore(criterion: string, options?: ScoreOptions, frame?: (criterion: string) => string): {
+    question: {
+        kind: "level";
+        instructions: string;
+        levels: readonly (string | LevelSpec)[];
+    };
+    options: ScoreOptions;
+    operation: "score";
+    range: readonly [number, number];
+} | {
+    question: TruthQuestion;
+    options: ScoreOptions;
+    operation: "score";
+    range: readonly [number, number];
+};
+export type ChoiceInput = readonly string[] | Readonly<Record<string, string | ChoiceOptionSpec>>;
+export declare function buildChoose(input: ChoiceInput, options?: ChooseOptions): {
+    question: ChoiceQuestion;
+    options: ChooseOptions;
+    operation: "choose";
+    optionKeys: string[];
+};
+export declare function is(condition: string, options?: IsOptions): QuestionSpec<boolean>;
+export declare function score(criterion: string, options?: ScoreOptions): QuestionSpec<number>;
+export declare function choose<const T extends readonly string[]>(options: T, extra?: ChooseOptions): QuestionSpec<T[number]>;
+export declare function choose<const T extends Readonly<Record<string, string | ChoiceOptionSpec>>>(options: T, extra?: ChooseOptions): QuestionSpec<keyof T & string>;
+//# sourceMappingURL=questions.d.ts.map

package/dist/questions.d.ts.map

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

package/dist/questions.js

@@ -0,0 +1,57 @@
+/**
+ * Default framing that turns a noun-phrase criterion into a proposition.
+ *
+ * `score("fraud risk")` on its own is a noun phrase, and the model answers what
+ * it is literally asked. Framing it as "This has high fraud risk." gives the
+ * probability a well-defined referent. Override for other languages via
+ * `configureSemantic({ defaults: { scoreFrame } })`.
+ */
+export const DEFAULT_SCORE_FRAME = (criterion) => `This has high ${criterion}.`;
+function truthQuestion(instructions, criteria) {
+    return {
+        kind: "truth",
+        instructions,
+        ...(criteria.trueWhen !== undefined ? { trueWhen: criteria.trueWhen } : {}),
+        ...(criteria.falseWhen !== undefined ? { falseWhen: criteria.falseWhen } : {}),
+    };
+}
+export function buildIs(condition, options = {}) {
+    return { question: truthQuestion(condition, options), options, operation: "is" };
+}
+export function buildScore(criterion, options = {}, frame = DEFAULT_SCORE_FRAME) {
+    const range = options.range ?? [0, 100];
+    if (options.levels) {
+        return {
+            question: { kind: "level", instructions: criterion, levels: options.levels },
+            options,
+            operation: "score",
+            range,
+        };
+    }
+    const instructions = options.asProposition ? criterion : frame(criterion);
+    return { question: truthQuestion(instructions, options), options, operation: "score", range };
+}
+export function buildChoose(input, options = {}) {
+    const optionMap = Array.isArray(input)
+        ? Object.fromEntries(input.map((key) => [key, key]))
+        : { ...input };
+    const question = {
+        kind: "choice",
+        instructions: options.instructions ?? "Select the option that best fits the state.",
+        options: optionMap,
+    };
+    return { question, options, operation: "choose", optionKeys: Object.keys(optionMap) };
+}
+// ---------------------------------------------------------------------------
+// Standalone builders, for composing inside `batch()`.
+// ---------------------------------------------------------------------------
+export function is(condition, options = {}) {
+    return { build: () => buildIs(condition, options) };
+}
+export function score(criterion, options = {}) {
+    return { build: (frame) => buildScore(criterion, options, frame) };
+}
+export function choose(options, extra = {}) {
+    return { build: () => buildChoose(options, extra) };
+}
+//# sourceMappingURL=questions.js.map

package/dist/questions.js.map

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

package/dist/runner.d.ts

@@ -0,0 +1,52 @@
+import { parseTtlOrUndefined } from "./internal.ts";
+import type { SemanticCache } from "./cache.ts";
+import type { SemanticConfig } from "./config.ts";
+import type { EvaluationEvent, SemanticAnswer, SemanticProvider, SemanticQuestion, State, Usage } from "./types.ts";
+export interface PlannedQuestion {
+    key: string;
+    question: SemanticQuestion;
+    /** Rounds to run. 1 means a single pass with no measured confidence. */
+    samples: number;
+    cacheTtlMs?: number;
+}
+export interface RunResult {
+    answers: Record<string, SemanticAnswer>;
+    /** Per-key confidence measured across sample rounds, when samples > 1. */
+    measured: Record<string, number | undefined>;
+    cachedKeys: Set<string>;
+    usage: Usage;
+    latencyMs: number;
+    requestCount: number;
+}
+export declare function cacheKeyFor(provider: SemanticProvider, state: State, question: SemanticQuestion, samples: number): string;
+/**
+ * Validates a question against what the provider can actually express, so an
+ * impossible request fails here rather than as a confusing 4xx.
+ */
+export declare function assertSupported(provider: SemanticProvider, question: SemanticQuestion): void;
+/**
+ * Turns observed spread across sample rounds into a 0–1 confidence.
+ *
+ * A truth answer has no provider-reported confidence: the probability itself
+ * carries the uncertainty. Deriving confidence from the probability (e.g.
+ * |p-0.5|*2) is wrong for scores, where a mid-range value means "middling",
+ * not "unsure". So we measure instead: re-ask and see how much the answer moves.
+ *
+ * sigma of 0 maps to 1.0, and 0.5 (the widest meaningful spread on [0,1]) to 0.
+ */
+export declare function confidenceFromSpread(samples: readonly number[]): number;
+/**
+ * Executes a plan as few provider requests as possible.
+ *
+ * Round 0 carries every question. Later rounds carry only the questions that
+ * asked for more samples, so raising `samples` on one question does not
+ * multiply the cost of its neighbours.
+ */
+export declare function runPlan(provider: SemanticProvider, state: State, planned: readonly PlannedQuestion[], options?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    store?: SemanticCache;
+}): Promise<RunResult>;
+export declare function emit(event: EvaluationEvent, config?: SemanticConfig): void;
+export { parseTtlOrUndefined };
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGjD,OAAO,KAAK,EAGV,eAAe,EAGf,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,EAEL,KAAK,EACN,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;IACvC,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IAC5C,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACvB,KAAK,EAAE,KAAK,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;CACrB;AAUD,wBAAgB,WAAW,CACzB,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,MAAM,GACd,MAAM,CAIR;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CA2B5F;AA2BD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEvE;AA8CD;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAAO,GAChF,OAAO,CAAC,SAAS,CAAC,CAqEpB;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,GAAE,cAA4B,GAAG,IAAI,CAQvF;AAED,OAAO,EAAE,mBAAmB,EAAE,CAAA"}

package/dist/runner.js

@@ -0,0 +1,208 @@
+import { getCacheStore, getConfig, parseTtlOrUndefined } from "./internal.js";
+import { hashKey } from "./cache.js";
+import { UnsupportedByProviderError } from "./errors.js";
+/** Stable stringify so cache keys survive key reordering. */
+function stable(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(",")}]`;
+    const entries = Object.entries(value).sort(([a], [b]) => (a < b ? -1 : 1));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stable(v)}`).join(",")}}`;
+}
+export function cacheKeyFor(provider, state, question, samples) {
+    return hashKey(stable({ p: provider.name, m: provider.model, s: state, q: question, n: samples }));
+}
+/**
+ * Validates a question against what the provider can actually express, so an
+ * impossible request fails here rather than as a confusing 4xx.
+ */
+export function assertSupported(provider, question) {
+    const caps = provider.capabilities;
+    if (question.kind === "choice") {
+        const count = Object.keys(question.options).length;
+        if (count > caps.maxChoiceOptions) {
+            throw new UnsupportedByProviderError(provider.name, `a choice over ${count} options`, `The limit is ${caps.maxChoiceOptions}. Narrow the set first, or classify hierarchically.`);
+        }
+        if (count < 2) {
+            throw new UnsupportedByProviderError(provider.name, "a choice over fewer than 2 options", "Add options.");
+        }
+    }
+    if (question.kind === "level") {
+        const count = question.levels.length;
+        const [min, max] = caps.levelRange;
+        if (count < min || count > max) {
+            throw new UnsupportedByProviderError(provider.name, `a rubric with ${count} levels`, `Supported range is ${min}–${max}. Use fewer, well-separated levels, or drop \`levels\` to get a ` +
+                "probability-backed score instead.");
+        }
+    }
+}
+function argmax(probabilities) {
+    let best = "";
+    let bestValue = -Infinity;
+    for (const [key, value] of Object.entries(probabilities)) {
+        if (value > bestValue) {
+            bestValue = value;
+            best = key;
+        }
+    }
+    return best;
+}
+function mean(values) {
+    return values.reduce((a, b) => a + b, 0) / values.length;
+}
+function stdev(values) {
+    if (values.length < 2)
+        return 0;
+    const m = mean(values);
+    const variance = values.reduce((a, b) => a + (b - m) ** 2, 0) / (values.length - 1);
+    // Identical samples can leave a sub-epsilon residue behind, which would
+    // otherwise report a perfectly stable answer as slightly less than certain.
+    return variance < 1e-12 ? 0 : Math.sqrt(variance);
+}
+/**
+ * Turns observed spread across sample rounds into a 0–1 confidence.
+ *
+ * A truth answer has no provider-reported confidence: the probability itself
+ * carries the uncertainty. Deriving confidence from the probability (e.g.
+ * |p-0.5|*2) is wrong for scores, where a mid-range value means "middling",
+ * not "unsure". So we measure instead: re-ask and see how much the answer moves.
+ *
+ * sigma of 0 maps to 1.0, and 0.5 (the widest meaningful spread on [0,1]) to 0.
+ */
+export function confidenceFromSpread(samples) {
+    return Math.min(1, Math.max(0, 1 - 2 * stdev(samples)));
+}
+function aggregate(kind, rounds) {
+    if (rounds.length === 1)
+        return rounds[0];
+    if (kind === "truth") {
+        const ps = rounds.map((r) => r.probability);
+        return { kind: "truth", probability: mean(ps) };
+    }
+    if (kind === "choice") {
+        const all = rounds;
+        const keys = Object.keys(all[0].probabilities);
+        const averaged = {};
+        for (const key of keys)
+            averaged[key] = mean(all.map((r) => r.probabilities[key] ?? 0));
+        return {
+            kind: "choice",
+            choice: argmax(averaged),
+            probabilities: averaged,
+            confidence: mean(all.map((r) => r.confidence)),
+        };
+    }
+    const all = rounds;
+    const width = all[0].probabilities.length;
+    const averaged = [];
+    for (let i = 0; i < width; i++)
+        averaged.push(mean(all.map((r) => r.probabilities[i] ?? 0)));
+    return {
+        kind: "level",
+        level: mean(all.map((r) => r.level)),
+        probabilities: averaged,
+        confidence: mean(all.map((r) => r.confidence)),
+    };
+}
+/** Numeric series a measured confidence can be computed from, per kind. */
+function series(kind, rounds) {
+    if (kind === "truth")
+        return rounds.map((r) => r.probability);
+    if (kind === "level") {
+        // Normalise rubric position onto 0–1 so the spread formula stays comparable.
+        const all = rounds;
+        const width = Math.max(1, all[0].probabilities.length - 1);
+        return all.map((r) => r.level / width);
+    }
+    const all = rounds;
+    const winner = argmax(all[0].probabilities);
+    return all.map((r) => r.probabilities[winner] ?? 0);
+}
+/**
+ * Executes a plan as few provider requests as possible.
+ *
+ * Round 0 carries every question. Later rounds carry only the questions that
+ * asked for more samples, so raising `samples` on one question does not
+ * multiply the cost of its neighbours.
+ */
+export async function runPlan(provider, state, planned, options = {}) {
+    const started = Date.now();
+    const store = options.store ?? getCacheStore();
+    const answers = {};
+    const measured = {};
+    const cachedKeys = new Set();
+    const usage = { inputTokens: 0, outputTokens: 0 };
+    const live = [];
+    for (const item of planned) {
+        assertSupported(provider, item.question);
+        if (item.cacheTtlMs && item.cacheTtlMs > 0) {
+            const hit = await store.get(cacheKeyFor(provider, state, item.question, item.samples));
+            if (hit) {
+                answers[item.key] = hit;
+                cachedKeys.add(item.key);
+                continue;
+            }
+        }
+        live.push(item);
+    }
+    let requestCount = 0;
+    if (live.length > 0) {
+        const maxRounds = Math.max(...live.map((q) => q.samples));
+        const rounds = {};
+        for (const item of live)
+            rounds[item.key] = [];
+        for (let round = 0; round < maxRounds; round++) {
+            const inRound = live.filter((q) => q.samples > round);
+            if (inRound.length === 0)
+                break;
+            const questions = {};
+            for (const item of inRound)
+                questions[item.key] = item.question;
+            const response = await provider.evaluate({
+                state,
+                questions,
+                ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+            requestCount++;
+            usage.inputTokens += response.usage?.inputTokens ?? 0;
+            usage.outputTokens += response.usage?.outputTokens ?? 0;
+            for (const item of inRound) {
+                const answer = response.answers[item.key];
+                if (!answer)
+                    throw new Error(`Provider "${provider.name}" returned no answer for key "${item.key}".`);
+                rounds[item.key].push(answer);
+            }
+        }
+        for (const item of live) {
+            const collected = rounds[item.key];
+            answers[item.key] = aggregate(item.question.kind, collected);
+            measured[item.key] = collected.length > 1 ? confidenceFromSpread(series(item.question.kind, collected)) : undefined;
+            if (item.cacheTtlMs && item.cacheTtlMs > 0) {
+                await store.set(cacheKeyFor(provider, state, item.question, item.samples), answers[item.key], item.cacheTtlMs);
+            }
+        }
+    }
+    return {
+        answers,
+        measured,
+        cachedKeys,
+        usage,
+        latencyMs: Date.now() - started,
+        requestCount,
+    };
+}
+export function emit(event, config = getConfig()) {
+    const hook = config.observability?.onEvaluation;
+    if (!hook)
+        return;
+    try {
+        hook(event);
+    }
+    catch {
+        // Observability must never break the call path it observes.
+    }
+}
+export { parseTtlOrUndefined };
+//# sourceMappingURL=runner.js.map

package/dist/runner.js.map

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

package/dist/schema.d.ts

@@ -0,0 +1,49 @@
+import { type Runtime } from "./config.ts";
+import type { AnyOutput, OutputValue } from "./outputs.ts";
+import type { SemanticProvider, State } from "./types.ts";
+export interface SchemaDefinition<O extends AnyOutput> {
+    name: string;
+    /** Bump when the wording changes, so old results stay interpretable. */
+    version?: string;
+    /**
+     * Domain context applied to every field of the schema.
+     *
+     * This is the closest thing to a system prompt, but it is not one: it is not
+     * an instruction the model obeys, it is the frame each question is asked in.
+     * Say what the data is and what the words mean in your business. Do not say
+     * how to behave — there is no behaviour to steer.
+     */
+    instructions: string;
+    /**
+     * Background merged into the state on every call — a policy, a price list, a
+     * tier definition. Kept separate from the input so the two never blur.
+     */
+    context?: Record<string, unknown>;
+    output: O;
+    defaults?: {
+        timeoutMs?: number;
+        cache?: string | number;
+        samples?: number;
+    };
+}
+export interface SchemaOptions {
+    provider?: SemanticProvider;
+    timeoutMs?: number;
+    cache?: string | number;
+    samples?: number;
+}
+export interface Evaluator<O extends AnyOutput> {
+    (data: State, options?: SchemaOptions): Promise<OutputValue<O>>;
+    readonly name: string;
+    readonly version: string | undefined;
+    readonly definition: SchemaDefinition<O>;
+}
+/**
+ * A reusable evaluator: instructions, background and output shape declared
+ * once, then applied to data.
+ *
+ * Every field resolves in a single request, however many there are.
+ */
+export declare function defineSchema<const O extends AnyOutput>(definition: SchemaDefinition<O>): Evaluator<O>;
+export declare function defineSchemaWith<const O extends AnyOutput>(runtime: Runtime, definition: SchemaDefinition<O>): Evaluator<O>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEzD,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,SAAS;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;;OAOG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,MAAM,EAAE,CAAC,CAAA;IACT,QAAQ,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;QACvB,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB,CAAA;CACF;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,SAAS;IAC5C,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAA;CACzC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAErG;AAED,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAmB3H"}

package/dist/schema.js

@@ -0,0 +1,30 @@
+import { evaluateWith } from "./evaluate.js";
+import { globalRuntime } from "./config.js";
+/**
+ * A reusable evaluator: instructions, background and output shape declared
+ * once, then applied to data.
+ *
+ * Every field resolves in a single request, however many there are.
+ */
+export function defineSchema(definition) {
+    return defineSchemaWith(globalRuntime, definition);
+}
+export function defineSchemaWith(runtime, definition) {
+    const call = (data, options = {}) => evaluateWith(runtime, {
+        data,
+        question: definition.instructions,
+        // Background stays in its own labelled field rather than merged, so input
+        // can never quietly overwrite the policy it is being judged against.
+        ...(definition.context ? { context: definition.context } : {}),
+        output: definition.output,
+        ...definition.defaults,
+        ...options,
+        metric: { name: definition.name, ...(definition.version ? { version: definition.version } : {}) },
+    });
+    const evaluator = call;
+    Object.defineProperty(evaluator, "name", { value: definition.name, configurable: true });
+    Object.defineProperty(evaluator, "version", { value: definition.version, configurable: true });
+    Object.defineProperty(evaluator, "definition", { value: definition, configurable: true });
+    return evaluator;
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAgB,MAAM,aAAa,CAAA;AA4CzD;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAA4B,UAA+B;IACrF,OAAO,gBAAgB,CAAC,aAAa,EAAE,UAAU,CAAC,CAAA;AACpD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAA4B,OAAgB,EAAE,UAA+B;IAC3G,MAAM,IAAI,GAAG,CAAC,IAAW,EAAE,UAAyB,EAAE,EAA2B,EAAE,CACjF,YAAY,CAAC,OAAO,EAAE;QACpB,IAAI;QACJ,QAAQ,EAAE,UAAU,CAAC,YAAY;QACjC,0EAA0E;QAC1E,qEAAqE;QACrE,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,GAAG,UAAU,CAAC,QAAQ;QACtB,GAAG,OAAO;QACV,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;KAClG,CAAC,CAAA;IAEJ,MAAM,SAAS,GAAG,IAAoB,CAAA;IACtC,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAA;IACxF,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAA;IAC9F,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAA;IACzF,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,34 @@
+import type { ProviderCapabilities, SemanticAnswer, SemanticProvider, SemanticQuestion, SemanticRequest } from "./types.ts";
+export interface MockCall {
+    state: SemanticRequest["state"];
+    questions: Record<string, SemanticQuestion>;
+}
+/**
+ * What a stubbed answer may look like.
+ *
+ * A bare number stands in for a probability (truth) or a rubric position
+ * (level); a boolean becomes 0.95/0.05; a string selects a choice option.
+ */
+export type MockValue = number | boolean | string | SemanticAnswer;
+export interface MockProviderOptions {
+    capabilities?: Partial<ProviderCapabilities>;
+    model?: string;
+    /** Answer used when no rule matches. Defaults to 0.5 / the first option. */
+    fallback?: MockValue;
+    /** Adds jitter to probabilities so sampling-based confidence can be exercised. */
+    jitter?: number;
+}
+export interface MockProvider extends SemanticProvider {
+    readonly calls: MockCall[];
+    /** Number of requests actually issued — the assertion that proves batching. */
+    readonly requestCount: number;
+    reset(): void;
+}
+/**
+ * A provider that answers from a lookup table instead of a network call.
+ *
+ * Keys are matched as substrings of a question's instructions, so a rule like
+ * `"urgency"` answers `score("urgency")` regardless of how it was framed.
+ */
+export declare function createMockSemanticProvider(rules?: Record<string, MockValue>, options?: MockProviderOptions): MockProvider;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAEhB,gBAAgB,EAChB,eAAe,EAChB,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,CAAA;IAC/B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CAC5C;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,cAAc,CAAA;AAElE,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAA;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IACpD,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,KAAK,IAAI,IAAI,CAAA;CACd;AA8BD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAM,EACrC,OAAO,GAAE,mBAAwB,GAChC,YAAY,CAoCd"}

package/dist/testing.js

@@ -0,0 +1,68 @@
+function instructionsText(question) {
+    const raw = question.instructions;
+    return typeof raw === "string" ? raw : JSON.stringify(raw);
+}
+function toAnswer(question, value, jitter) {
+    if (typeof value === "object")
+        return value;
+    if (question.kind === "truth") {
+        const base = typeof value === "boolean" ? (value ? 0.95 : 0.05) : Number(value);
+        const noise = jitter > 0 ? (Math.random() - 0.5) * 2 * jitter : 0;
+        return { kind: "truth", probability: Math.min(1, Math.max(0, base + noise)) };
+    }
+    if (question.kind === "choice") {
+        const keys = Object.keys(question.options);
+        const picked = typeof value === "string" && keys.includes(value) ? value : keys[0];
+        const probabilities = {};
+        for (const key of keys)
+            probabilities[key] = key === picked ? 1 : 0;
+        return { kind: "choice", choice: picked, probabilities, confidence: 1 };
+    }
+    const width = question.levels.length;
+    const level = Math.min(width - 1, Math.max(0, typeof value === "number" ? value : 0));
+    const probabilities = Array.from({ length: width }, (_, index) => (index === Math.round(level) ? 1 : 0));
+    return { kind: "level", level, probabilities, confidence: 1 };
+}
+/**
+ * A provider that answers from a lookup table instead of a network call.
+ *
+ * Keys are matched as substrings of a question's instructions, so a rule like
+ * `"urgency"` answers `score("urgency")` regardless of how it was framed.
+ */
+export function createMockSemanticProvider(rules = {}, options = {}) {
+    const calls = [];
+    const jitter = options.jitter ?? 0;
+    const provider = {
+        name: "mock",
+        model: options.model ?? "mock-1",
+        capabilities: {
+            maxChoiceOptions: 255,
+            levelRange: [2, 10],
+            generatesText: false,
+            batching: true,
+            ...options.capabilities,
+        },
+        get calls() {
+            return calls;
+        },
+        get requestCount() {
+            return calls.length;
+        },
+        reset() {
+            calls.length = 0;
+        },
+        async evaluate(request) {
+            calls.push({ state: request.state, questions: { ...request.questions } });
+            const answers = {};
+            for (const [key, question] of Object.entries(request.questions)) {
+                const text = instructionsText(question).toLowerCase();
+                const match = Object.entries(rules).find(([needle]) => text.includes(needle.toLowerCase()));
+                const value = match ? match[1] : (options.fallback ?? 0.5);
+                answers[key] = toAnswer(question, value, jitter);
+            }
+            return { answers, model: provider.model, usage: { inputTokens: 0, outputTokens: 0 } };
+        },
+    };
+    return provider;
+}
+//# sourceMappingURL=testing.js.map