jevascript 0.1.0

package/dist/context.js

@@ -0,0 +1,251 @@
+import { BUILTIN_DEFAULTS, globalRuntime, shouldWarnUnbatched } from "./config.js";
+import { LowConfidenceError } from "./errors.js";
+import { emit, runPlan } from "./runner.js";
+import { bindCollections } from "./collections.js";
+import { parseTtlOrUndefined } from "./internal.js";
+import { DEFAULT_SCORE_FRAME, buildChoose, buildIs, buildScore, } from "./questions.js";
+function scoreFrame(config) {
+    return config.defaults?.scoreFrame ?? DEFAULT_SCORE_FRAME;
+}
+/** Rounds needed for this question. `minConfidence` implies measurement. */
+function resolveSamples(kind, options, config) {
+    if (options.samples !== undefined)
+        return Math.max(1, options.samples);
+    const needsMeasurement = options.minConfidence !== undefined && kind === "truth";
+    if (!needsMeasurement)
+        return 1;
+    return config.defaults?.samples ?? BUILTIN_DEFAULTS.samples;
+}
+async function applyFallback(confidence, minConfidence, value, fallback) {
+    if (minConfidence === undefined)
+        return value;
+    if (confidence !== undefined && confidence >= minConfidence)
+        return value;
+    if (fallback === undefined)
+        throw new LowConfidenceError(confidence ?? 0, minConfidence, value);
+    return typeof fallback === "function" ? await fallback() : fallback;
+}
+export class SemanticContext {
+    #state;
+    #pending = [];
+    #scheduled = false;
+    #flushes = 0;
+    #warned = false;
+    #counter = 0;
+    #runtime;
+    constructor(state, runtime = globalRuntime) {
+        this.#state = state;
+        this.#runtime = runtime;
+    }
+    get #config() {
+        return this.#runtime.config;
+    }
+    /**
+     * Queues a question and returns its answer.
+     *
+     * Nothing is sent until the current synchronous turn ends, so every question
+     * created in the same turn — `Promise.all([...])` or `batch({...})` — travels
+     * in one request. Sequentially awaited calls cannot be merged: the second
+     * call does not exist until the first has resolved.
+     */
+    #enqueue(provider, question, options) {
+        const key = `q${this.#counter++}`;
+        const ttl = parseTtlOrUndefined(options.cache ?? this.#config.defaults?.cache);
+        const planned = {
+            key,
+            question,
+            samples: resolveSamples(question.kind, options, this.#config),
+            ...(ttl !== undefined ? { cacheTtlMs: ttl } : {}),
+        };
+        return new Promise((resolve, reject) => {
+            this.#pending.push({
+                key,
+                provider,
+                planned,
+                timeoutMs: options.timeoutMs ?? this.#config.defaults?.timeoutMs,
+                metric: options.metric,
+                settle: (answer, measured, cached) => resolve({ answer, measured, cached }),
+                fail: reject,
+            });
+            this.#schedule();
+        });
+    }
+    #schedule() {
+        if (this.#scheduled)
+            return;
+        this.#scheduled = true;
+        queueMicrotask(() => {
+            this.#scheduled = false;
+            void this.#flush();
+        });
+    }
+    async #flush() {
+        const batch = this.#pending;
+        this.#pending = [];
+        if (batch.length === 0)
+            return;
+        this.#flushes++;
+        if (this.#flushes === 2 && !this.#warned && shouldWarnUnbatched(this.#config)) {
+            this.#warned = true;
+            const info = { context: "semantic(state)", flushCount: this.#flushes };
+            const hook = this.#config.observability?.onUnbatched;
+            if (hook)
+                hook(info);
+            else
+                console.warn("[semantic] This context issued a second provider request. Questions awaited one " +
+                    "at a time cannot share a request. Use `batch({...})` or `Promise.all([...])` to " +
+                    "send them together — batching is dramatically cheaper and no slower.");
+        }
+        const byProvider = new Map();
+        for (const item of batch) {
+            const list = byProvider.get(item.provider);
+            if (list)
+                list.push(item);
+            else
+                byProvider.set(item.provider, [item]);
+        }
+        await Promise.all([...byProvider].map(async ([provider, items]) => {
+            const timeouts = items.map((i) => i.timeoutMs).filter((t) => t !== undefined);
+            try {
+                const result = await runPlan(provider, this.#state, items.map((i) => i.planned), { store: this.#runtime.store, ...(timeouts.length > 0 ? { timeoutMs: Math.max(...timeouts) } : {}) });
+                // Only name the batch when every question came from the same
+                // definition; a mixed batch has no single identity to report.
+                const names = new Set(items.map((i) => (i.metric ? `${i.metric.name}@${i.metric.version ?? ""}` : "")));
+                const metric = names.size === 1 ? items[0].metric : undefined;
+                emit({
+                    operation: items.length > 1 ? "batch" : "evaluate",
+                    keys: items.map((i) => i.key),
+                    provider: provider.name,
+                    model: provider.model,
+                    latencyMs: result.latencyMs,
+                    cached: result.cachedKeys.size === items.length,
+                    batched: items.length > 1,
+                    questionCount: items.length,
+                    requestCount: result.requestCount,
+                    samples: Math.max(...items.map((i) => i.planned.samples)),
+                    usage: result.usage,
+                    ...(metric ? { metric } : {}),
+                }, this.#config);
+                for (const item of items) {
+                    item.settle(result.answers[item.key], result.measured[item.key], result.cachedKeys.has(item.key));
+                }
+            }
+            catch (error) {
+                for (const item of items)
+                    item.fail(error);
+            }
+        }));
+    }
+    async is(condition, options = {}) {
+        const provider = this.#runtime.provider(options.provider);
+        const built = buildIs(condition, options);
+        const { answer, measured } = await this.#enqueue(provider, built.question, options);
+        const probability = answer.probability;
+        const defaults = this.#config.defaults;
+        if (options.allowUnknown) {
+            const [low, high] = options.uncertaintyBand ?? defaults?.uncertaintyBand ?? BUILTIN_DEFAULTS.uncertaintyBand;
+            if (probability >= low && probability <= high)
+                return "unknown";
+        }
+        const threshold = options.threshold ?? defaults?.threshold ?? BUILTIN_DEFAULTS.threshold;
+        const raw = probability > threshold;
+        const value = await applyFallback(measured, options.minConfidence ?? defaults?.minConfidence, raw, options.fallback);
+        if (options.detailed) {
+            return { value, probability, ...(measured !== undefined ? { confidence: measured } : {}) };
+        }
+        return value;
+    }
+    async score(criterion, options = {}) {
+        const provider = this.#runtime.provider(options.provider);
+        const built = buildScore(criterion, options, scoreFrame(this.#config));
+        const { answer, measured } = await this.#enqueue(provider, built.question, options);
+        const [min, max] = built.range;
+        const defaults = this.#config.defaults;
+        let raw;
+        let detail;
+        if (answer.kind === "level") {
+            const levels = answer.probabilities.length;
+            const position = levels > 1 ? answer.level / (levels - 1) : 0;
+            raw = min + position * (max - min);
+            detail = { value: raw, level: answer.level, confidence: answer.confidence };
+        }
+        else {
+            const probability = answer.probability;
+            raw = min + probability * (max - min);
+            detail = { value: raw, probability, ...(measured !== undefined ? { confidence: measured } : {}) };
+        }
+        const value = await applyFallback(detail.confidence, options.minConfidence ?? defaults?.minConfidence, raw, options.fallback);
+        return options.detailed ? { ...detail, value } : value;
+    }
+    async choose(input, extra = {}) {
+        const provider = this.#runtime.provider(extra.provider);
+        const built = buildChoose(input, extra);
+        const { answer } = await this.#enqueue(provider, built.question, extra);
+        const choice = answer;
+        const value = await applyFallback(choice.confidence, extra.minConfidence ?? this.#config.defaults?.minConfidence, choice.choice, extra.fallback);
+        return extra.detailed
+            ? { value, confidence: choice.confidence, probabilities: { ...choice.probabilities } }
+            : value;
+    }
+    // -------------------------------------------------------------------------
+    // rank()
+    // -------------------------------------------------------------------------
+    /**
+     * Orders items by how well they fit this state.
+     *
+     * Each candidate is judged against the state in its own request, so this
+     * costs one call per item. When you only need the winner, `semantic.find`
+     * answers in a single call instead.
+     */
+    async rank(items, options) {
+        return bindCollections(this.#runtime).rank(items, { ...options, context: this.#state });
+    }
+    // -------------------------------------------------------------------------
+    // batch()
+    // -------------------------------------------------------------------------
+    /**
+     * Evaluates every question against this state in a single request.
+     *
+     * Equivalent to creating the same questions in one turn and awaiting them
+     * together; this form just makes the intent explicit and names the results.
+     */
+    async batch(spec) {
+        const frame = scoreFrame(this.#config);
+        const entries = Object.entries(spec);
+        const results = await Promise.all(entries.map(async ([, questionSpec]) => {
+            const built = questionSpec.build(frame);
+            const provider = this.#runtime.provider(built.options.provider);
+            const { answer, measured } = await this.#enqueue(provider, built.question, built.options);
+            return this.#interpret(built, answer, measured);
+        }));
+        const output = {};
+        entries.forEach(([key], index) => {
+            output[key] = results[index];
+        });
+        return output;
+    }
+    #interpret(built, answer, measured) {
+        const defaults = this.#config.defaults;
+        if (built.operation === "choose")
+            return answer.choice;
+        if (built.operation === "is") {
+            const options = built.options;
+            const probability = answer.probability;
+            if (options.allowUnknown) {
+                const [low, high] = options.uncertaintyBand ?? defaults?.uncertaintyBand ?? BUILTIN_DEFAULTS.uncertaintyBand;
+                if (probability >= low && probability <= high)
+                    return "unknown";
+            }
+            return probability > (options.threshold ?? defaults?.threshold ?? BUILTIN_DEFAULTS.threshold);
+        }
+        const [min, max] = built.range ?? [0, 100];
+        if (answer.kind === "level") {
+            const levels = answer.probabilities.length;
+            const position = levels > 1 ? answer.level / (levels - 1) : 0;
+            return min + position * (max - min);
+        }
+        void measured;
+        return min + answer.probability * (max - min);
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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

package/dist/define.d.ts

@@ -0,0 +1,52 @@
+import { type Runtime } from "./config.ts";
+import type { IsOptions, QuestionSpec, ScoreOptions, SharedOptions } from "./questions.ts";
+import type { JsonValue, State } from "./types.ts";
+import type { NumberOutput } from "./outputs.ts";
+export interface MetricDefinition {
+    name: string;
+    /** Bump whenever the wording changes. Logged alongside results so old evaluations stay interpretable. */
+    version?: string;
+    /**
+     * The proposition, written out in full. This is the explicit path: unlike the
+     * shorthand `score("urgency")`, nothing is inferred or reframed on your behalf.
+     */
+    description: string;
+    /** What clearly counts as true. */
+    trueWhen?: string | JsonValue;
+    /** What clearly does not count, even when it looks close — the near-misses. */
+    falseWhen?: string | JsonValue;
+    output?: NumberOutput;
+    defaults?: Omit<ScoreOptions, "range" | "levels">;
+}
+export interface Metric {
+    (state: State, options?: ScoreOptions): Promise<number>;
+    readonly name: string;
+    readonly version: string | undefined;
+    readonly definition: MetricDefinition;
+    /** Use inside `batch()` to share a request with other questions. */
+    question(options?: ScoreOptions): QuestionSpec<number>;
+}
+export declare function defineMetric(definition: MetricDefinition): Metric;
+export declare function defineMetricWith(runtime: Runtime, definition: MetricDefinition): Metric;
+export interface RuleDefinition {
+    name: string;
+    version?: string;
+    /** The condition, written as a complete proposition. */
+    condition: string;
+    trueWhen?: string | JsonValue;
+    falseWhen?: string | JsonValue;
+    defaults?: SharedOptions & {
+        threshold?: number;
+        allowUnknown?: boolean;
+    };
+}
+export interface Rule {
+    (state: State, options?: IsOptions): Promise<boolean>;
+    readonly name: string;
+    readonly version: string | undefined;
+    readonly definition: RuleDefinition;
+    question(options?: IsOptions): QuestionSpec<boolean>;
+}
+export declare function defineRule(definition: RuleDefinition): Rule;
+export declare function defineRuleWith(runtime: Runtime, definition: RuleDefinition): Rule;
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAE1F,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEhD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,yGAAyG;IACzG,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,QAAQ,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,QAAQ,CAAC,CAAA;CAClD;AAED,MAAM,WAAW,MAAM;IACrB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAA;IACrC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY,CAAC,MAAM,CAAC,CAAA;CACvD;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,CAEjE;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,gBAAgB,GAAG,MAAM,CAkCvF;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,QAAQ,CAAC,EAAE,aAAa,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAC1E;AAED,MAAM,WAAW,IAAI;IACnB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAA;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,CAAA;CACrD;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI,CAE3D;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,cAAc,GAAG,IAAI,CA4BjF"}

package/dist/define.js

@@ -0,0 +1,59 @@
+import { semanticContext } from "./factory.js";
+import { globalRuntime } from "./config.js";
+import { buildIs, buildScore, DEFAULT_SCORE_FRAME } from "./questions.js";
+export function defineMetric(definition) {
+    return defineMetricWith(globalRuntime, definition);
+}
+export function defineMetricWith(runtime, definition) {
+    const range = [definition.output?.min ?? 0, definition.output?.max ?? 100];
+    const levels = definition.output?.levels;
+    const identity = { name: definition.name, ...(definition.version ? { version: definition.version } : {}) };
+    const baseOptions = (override = {}) => ({
+        ...definition.defaults,
+        ...override,
+        metric: identity,
+        range,
+        asProposition: true,
+        ...(levels ? { levels } : {}),
+        ...(definition.trueWhen !== undefined ? { trueWhen: definition.trueWhen } : {}),
+        ...(definition.falseWhen !== undefined ? { falseWhen: definition.falseWhen } : {}),
+    });
+    const call = (state, options = {}) => semanticContext(state, runtime).score(definition.description, baseOptions(options));
+    const metric = call;
+    Object.defineProperty(metric, "name", { value: definition.name, configurable: true });
+    Object.defineProperty(metric, "version", { value: definition.version, configurable: true });
+    Object.defineProperty(metric, "definition", { value: definition, configurable: true });
+    Object.defineProperty(metric, "question", {
+        value: (options = {}) => ({
+            build: (frame) => buildScore(definition.description, baseOptions(options), frame ?? DEFAULT_SCORE_FRAME),
+        }),
+        configurable: true,
+    });
+    return metric;
+}
+export function defineRule(definition) {
+    return defineRuleWith(globalRuntime, definition);
+}
+export function defineRuleWith(runtime, definition) {
+    const identity = { name: definition.name, ...(definition.version ? { version: definition.version } : {}) };
+    const baseOptions = (override = {}) => ({
+        ...definition.defaults,
+        ...override,
+        metric: identity,
+        ...(definition.trueWhen !== undefined ? { trueWhen: definition.trueWhen } : {}),
+        ...(definition.falseWhen !== undefined ? { falseWhen: definition.falseWhen } : {}),
+    });
+    const call = (state, options = {}) => semanticContext(state, runtime).is(definition.condition, baseOptions(options));
+    const rule = call;
+    Object.defineProperty(rule, "name", { value: definition.name, configurable: true });
+    Object.defineProperty(rule, "version", { value: definition.version, configurable: true });
+    Object.defineProperty(rule, "definition", { value: definition, configurable: true });
+    Object.defineProperty(rule, "question", {
+        value: (options = {}) => ({
+            build: () => buildIs(definition.condition, baseOptions(options)),
+        }),
+        configurable: true,
+    });
+    return rule;
+}
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+export declare class SemanticError extends Error {
+    constructor(message: string);
+}
+export declare class NotConfiguredError extends SemanticError {
+    constructor();
+}
+/** The request cannot be expressed by this provider. Thrown before any network call. */
+export declare class UnsupportedByProviderError extends SemanticError {
+    readonly provider: string;
+    readonly feature: string;
+    constructor(provider: string, feature: string, hint: string);
+}
+export declare class LowConfidenceError extends SemanticError {
+    readonly confidence: number;
+    readonly minConfidence: number;
+    readonly value: unknown;
+    constructor(confidence: number, minConfidence: number, value: unknown);
+}
+export declare class SemanticValidationError extends SemanticError {
+    readonly condition: string;
+    readonly probability: number;
+    constructor(condition: string, probability: number);
+}
+export declare class ProviderError extends SemanticError {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,aAAa;;CAQpD;AAED,wFAAwF;AACxF,qBAAa,0BAA2B,SAAQ,aAAa;IAEzD,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM;gBADf,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACxB,IAAI,EAAE,MAAM;CAKf;AAED,qBAAa,kBAAmB,SAAQ,aAAa;IAEjD,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO;gBAFd,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,OAAO;CAQ1B;AAED,qBAAa,uBAAwB,SAAQ,aAAa;IAEtD,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM;gBADnB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM;CAK/B;AAED,qBAAa,aAAc,SAAQ,aAAa;IAG5C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;gBADxB,OAAO,EAAE,MAAM,EACN,MAAM,CAAC,EAAE,MAAM,YAAA;CAK3B"}

package/dist/errors.js

@@ -0,0 +1,56 @@
+export class SemanticError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SemanticError";
+    }
+}
+export class NotConfiguredError extends SemanticError {
+    constructor() {
+        super("No provider configured. Set JEV_API_KEY in the environment, or call " +
+            "configureSemantic({ provider: jev({ apiKey }) }) before evaluating.");
+        this.name = "NotConfiguredError";
+    }
+}
+/** The request cannot be expressed by this provider. Thrown before any network call. */
+export class UnsupportedByProviderError extends SemanticError {
+    provider;
+    feature;
+    constructor(provider, feature, hint) {
+        super(`Provider "${provider}" cannot do ${feature}. ${hint}`);
+        this.provider = provider;
+        this.feature = feature;
+        this.name = "UnsupportedByProviderError";
+    }
+}
+export class LowConfidenceError extends SemanticError {
+    confidence;
+    minConfidence;
+    value;
+    constructor(confidence, minConfidence, value) {
+        super(`Confidence ${confidence.toFixed(3)} is below minConfidence ${minConfidence}. ` +
+            "Supply `fallback` to degrade gracefully, or lower the threshold.");
+        this.confidence = confidence;
+        this.minConfidence = minConfidence;
+        this.value = value;
+        this.name = "LowConfidenceError";
+    }
+}
+export class SemanticValidationError extends SemanticError {
+    condition;
+    probability;
+    constructor(condition, probability) {
+        super(`Value failed semantic condition ${JSON.stringify(condition)} (p=${probability.toFixed(3)}).`);
+        this.condition = condition;
+        this.probability = probability;
+        this.name = "SemanticValidationError";
+    }
+}
+export class ProviderError extends SemanticError {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "ProviderError";
+    }
+}
+//# 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,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,eAAe,CAAA;IAC7B,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IACnD;QACE,KAAK,CACH,sEAAsE;YACpE,qEAAqE,CACxE,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF;AAED,wFAAwF;AACxF,MAAM,OAAO,0BAA2B,SAAQ,aAAa;IAEhD;IACA;IAFX,YACW,QAAgB,EAChB,OAAe,EACxB,IAAY;QAEZ,KAAK,CAAC,aAAa,QAAQ,eAAe,OAAO,KAAK,IAAI,EAAE,CAAC,CAAA;QAJpD,aAAQ,GAAR,QAAQ,CAAQ;QAChB,YAAO,GAAP,OAAO,CAAQ;QAIxB,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAA;IAC1C,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IAExC;IACA;IACA;IAHX,YACW,UAAkB,EAClB,aAAqB,EACrB,KAAc;QAEvB,KAAK,CACH,cAAc,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,2BAA2B,aAAa,IAAI;YAC7E,kEAAkE,CACrE,CAAA;QAPQ,eAAU,GAAV,UAAU,CAAQ;QAClB,kBAAa,GAAb,aAAa,CAAQ;QACrB,UAAK,GAAL,KAAK,CAAS;QAMvB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,aAAa;IAE7C;IACA;IAFX,YACW,SAAiB,EACjB,WAAmB;QAE5B,KAAK,CAAC,mCAAmC,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QAH3F,cAAS,GAAT,SAAS,CAAQ;QACjB,gBAAW,GAAX,WAAW,CAAQ;QAG5B,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;IACvC,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,aAAa;IAGnC;IAFX,YACE,OAAe,EACN,MAAe;QAExB,KAAK,CAAC,OAAO,CAAC,CAAA;QAFL,WAAM,GAAN,MAAM,CAAS;QAGxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAA;IAC7B,CAAC;CACF"}

package/dist/evaluate.d.ts

@@ -0,0 +1,31 @@
+import { type Runtime } from "./config.ts";
+import type { AnyOutput, OutputValue } from "./outputs.ts";
+import type { SemanticProvider, State } from "./types.ts";
+export interface EvaluateRequest<O extends AnyOutput> {
+    data: State;
+    /**
+     * The frame every field is judged in — what the data is, what your words
+     * mean. Carried once in the state rather than repeated in every question.
+     */
+    question: string;
+    /** Background merged into the state: a policy, a tier list, a price table. */
+    context?: Record<string, unknown>;
+    output: O;
+    provider?: SemanticProvider;
+    timeoutMs?: number;
+    cache?: string | number;
+    samples?: number;
+    /** Identity of the definition this came from, for logs. */
+    metric?: {
+        name: string;
+        version?: string;
+    };
+}
+/**
+ * The low-level entry point. One request regardless of how many fields the
+ * output describes.
+ */
+export declare function evaluate<O extends AnyOutput>(request: EvaluateRequest<O>): Promise<OutputValue<O>>;
+/** `evaluate` against a specific runtime. `createSemantic()` binds this. */
+export declare function evaluateWith<O extends AnyOutput>(runtime: Runtime, request: EvaluateRequest<O>): Promise<OutputValue<O>>;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../src/evaluate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,KAAK,OAAO,EAAE,MAAM,aAAa,CAAA;AAI3E,OAAO,KAAK,EAAE,SAAS,EAAgB,WAAW,EAAE,MAAM,cAAc,CAAA;AACxE,OAAO,KAAK,EAA6B,gBAAgB,EAAoB,KAAK,EAAe,MAAM,YAAY,CAAA;AAEnH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,SAAS;IAClD,IAAI,EAAE,KAAK,CAAA;IACX;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,MAAM,EAAE,CAAC,CAAA;IACT,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;IAChB,2DAA2D;IAC3D,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC5C;AAwED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAExG;AAED,4EAA4E;AAC5E,wBAAsB,YAAY,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAwE9H"}