@node-llm/core 1.17.0 → 1.18.0

package/dist/errors/index.d.ts.map

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

package/dist/errors/index.js

@@ -99,9 +99,12 @@ export class AuthenticationError extends APIError {
  * 429 - Rate limit exceeded
  */
 export class RateLimitError extends APIError {
-    constructor(message, body, provider, model) {
+    /** Seconds to wait before retrying, parsed from a `Retry-After` response header when present. */
+    retryAfter;
+    constructor(message, body, provider, model, retryAfter) {
         super(message, 429, body, provider, model);
         this.name = "RateLimitError";
+        this.retryAfter = retryAfter;
     }
 }
 /**

package/dist/executor/Executor.d.ts

@@ -7,5 +7,11 @@ export declare class Executor {
         delayMs: number;
     });
     executeChat(request: ChatRequest): Promise<ChatResponse>;
+    /**
+     * Computes the wait before the next retry. Honors a server-provided
+     * `Retry-After` (via RateLimitError.retryAfter) when present; otherwise uses
+     * exponential backoff with full jitter to avoid synchronized retry storms.
+     */
+    private backoffDelay;
 }
 //# sourceMappingURL=Executor.d.ts.map

package/dist/executor/Executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Executor.d.ts","sourceRoot":"","sources":["../../src/executor/Executor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG/E,qBAAa,QAAQ;IAEjB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAGzD,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CA4B/D"}
+{"version":3,"file":"Executor.d.ts","sourceRoot":"","sources":["../../src/executor/Executor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG/E,qBAAa,QAAQ;IAEjB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBADL,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAGzD,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IA8B9D;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAYrB"}

package/dist/executor/Executor.js

@@ -22,11 +22,28 @@ export class Executor {
                 if (!isRetryable || attempt >= this.retry.attempts) {
                     throw error;
                 }
-                if (this.retry.delayMs > 0) {
-                    await new Promise((r) => setTimeout(r, this.retry.delayMs));
+                const delay = this.backoffDelay(attempt, error);
+                if (delay > 0) {
+                    await new Promise((r) => setTimeout(r, delay));
                 }
             }
         }
         throw lastError;
     }
+    /**
+     * Computes the wait before the next retry. Honors a server-provided
+     * `Retry-After` (via RateLimitError.retryAfter) when present; otherwise uses
+     * exponential backoff with full jitter to avoid synchronized retry storms.
+     */
+    backoffDelay(attempt, error) {
+        if (error instanceof RateLimitError && typeof error.retryAfter === "number") {
+            return Math.max(0, error.retryAfter * 1000);
+        }
+        const base = this.retry.delayMs > 0 ? this.retry.delayMs : 0;
+        if (base === 0)
+            return 0;
+        // Exponential: base * 2^(attempt-1), capped at 30s, with full jitter.
+        const exponential = Math.min(base * 2 ** (attempt - 1), 30_000);
+        return Math.floor(Math.random() * exponential);
+    }
 }

package/dist/index.d.ts

@@ -8,7 +8,13 @@ export * from "./chat/ChatStream.js";
 export * from "./streaming/Stream.js";
 export * from "./errors/index.js";
 export { Agent, defineAgent } from "./agent/Agent.js";
-export type { AgentConfig } from "./agent/Agent.js";
+export { Judge, defineJudge } from "./judge/Judge.js";
+export type { JudgeCallOptions, QuestionsOf } from "./judge/Judge.js";
+export { probability, choice, score } from "./judge/Question.js";
+export type { Description, JsonValue, ProbabilityCriteria, ProbabilityQuestion, ChoiceQuestion, ScoreQuestion, QuestionDefinition, QuestionMap } from "./judge/Question.js";
+export { Judgment, ProbabilityAnswer, ChoiceAnswer, ScoreAnswer } from "./judge/Judgment.js";
+export type { Answer, AnswerFor, AnswersOf, JudgmentResult } from "./judge/Judgment.js";
+export type { AgentConfig, DefinedAgent } from "./agent/Agent.js";
 export type { Middleware, MiddlewareContext } from "./types/Middleware.js";
 export * from "./middlewares/index.js";
 export { z } from "zod";
@@ -18,9 +24,10 @@ export type { NodeLLMConfig } from "./config.js";
 export { providerRegistry, ProviderInterceptor } from "./providers/registry.js";
 export { Schema } from "./schema/Schema.js";
 export { BaseProvider } from "./providers/BaseProvider.js";
-export { Provider, ProviderCapabilities, ChatRequest, ChatResponse, ChatChunk, ThinkingConfig, ThinkingResult, Usage, ImageRequest, ImageResponse, TranscriptionRequest, TranscriptionResponse, TranscriptionSegment, TranscriptionWord, ModerationRequest, ModerationResponse, ModerationResult, EmbeddingRequest, EmbeddingResponse, ToolChoice } from "./providers/Provider.js";
+export { Provider, ProviderCapabilities, ChatRequest, ChatResponse, ChatChunk, ThinkingConfig, ThinkingResult, Usage, ImageRequest, ImageResponse, TranscriptionRequest, TranscriptionResponse, TranscriptionSegment, TranscriptionWord, ModerationRequest, ModerationResponse, ModerationResult, EmbeddingRequest, EmbeddingResponse, JudgmentRequest, JudgmentResponse, JudgmentInput, JudgmentAnswerData, ToolChoice } from "./providers/Provider.js";
 export { resolveModelAlias } from "./model_aliases.js";
 export { default as MODEL_ALIASES } from "./aliases.js";
+export type { ToolExecutionModeInput } from "./constants.js";
 export { ToolExecutionMode, DEFAULT_MAX_TOOL_CALLS, DEFAULT_MAX_RETRIES, DEFAULT_TOOL_EXECUTION, DEFAULT_OLLAMA_BASE_URL, DEFAULT_MODELS } from "./constants.js";
 export { fetchWithTimeout } from "./utils/fetch.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC3E,cAAc,wBAAwB,CAAC;AAEvC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,OAAO,EACP,aAAa,EACb,SAAS,EACT,WAAW,EACX,aAAa,EACb,UAAU,EACV,SAAS,EACT,aAAa,EACb,eAAe,EAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,cAAc,EACd,cAAc,EACd,KAAK,EACL,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACX,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjE,YAAY,EACV,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC7F,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACxF,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAClE,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC3E,cAAc,wBAAwB,CAAC;AAEvC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,OAAO,EACP,aAAa,EACb,SAAS,EACT,WAAW,EACX,aAAa,EACb,UAAU,EACV,SAAS,EACT,aAAa,EACb,eAAe,EAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,cAAc,EACd,cAAc,EACd,KAAK,EACL,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,UAAU,EACX,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,cAAc,EACf,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -8,6 +8,9 @@ export * from "./chat/ChatStream.js";
 export * from "./streaming/Stream.js";
 export * from "./errors/index.js";
 export { Agent, defineAgent } from "./agent/Agent.js";
+export { Judge, defineJudge } from "./judge/Judge.js";
+export { probability, choice, score } from "./judge/Question.js";
+export { Judgment, ProbabilityAnswer, ChoiceAnswer, ScoreAnswer } from "./judge/Judgment.js";
 export * from "./middlewares/index.js";
 export { z } from "zod";
 export { NodeLLM, LegacyNodeLLM, createLLM, NodeLLMCore, Transcription, Moderation, Embedding, ModelRegistry, PricingRegistry } from "./llm.js";

package/dist/judge/Judge.d.ts

@@ -0,0 +1,107 @@
+import { NodeLLMCore } from "../llm.js";
+import { JudgmentInput } from "../providers/Provider.js";
+import { LazyValue } from "../agent/Agent.js";
+import { QuestionMap } from "./Question.js";
+import { JudgmentResult } from "./Judgment.js";
+/** The questions a Judge class declares, once resolved. */
+export type QuestionsOf<T> = T extends {
+    questions: infer Q;
+} ? Q extends (...args: never[]) => infer R ? R extends QuestionMap ? R : never : Q extends QuestionMap ? Q : never : never;
+export interface JudgeCallOptions<I = Record<string, unknown>> {
+    /** Values for the inputs the judge declares; available to lazy settings. */
+    inputs?: I;
+    /** Overrides the judge's model for this call. */
+    model?: string;
+    /** Overrides the judge's provider for this call. */
+    provider?: string;
+    /** Merged over the judge's own providerOptions. */
+    providerOptions?: Record<string, unknown>;
+    requestTimeout?: number;
+    /** The NodeLLM instance to judge with. Defaults to the global NodeLLM. */
+    llm?: NodeLLMCore;
+}
+/**
+ * A reusable set of typed questions about your application data.
+ *
+ * Subclass it and declare `questions`; call `judge` with the input. Answers are
+ * typed from the declaration, so a choice's answer is a union of its options.
+ *
+ * @example
+ * class TicketTriage extends Judge {
+ *   static questions = {
+ *     urgent: probability("Does this need attention today?"),
+ *     department: choice("Which team should handle this?", {
+ *       billing: "Payments and refunds",
+ *       technical: "Bugs and integrations",
+ *       other: null
+ *     }),
+ *     frustration: score("How frustrated is the customer?", ["Calm", "Frustrated", "Angry"])
+ *   };
+ * }
+ *
+ * const judgment = await TicketTriage.judge("Please refund the duplicate charge today.");
+ * judgment.urgent.probability;  // number
+ * judgment.department.choice;   // "billing" | "technical" | "other"
+ *
+ * Settings can depend on runtime data. Declare the inputs a judge needs and
+ * pass them to `judge`; `questions`, `model` and `providerOptions` may be
+ * functions of those inputs, resolved once per judgment.
+ *
+ * @example
+ * class TeamRouter extends Judge {
+ *   static inputs = ["teams"] as const;
+ *   static questions = ({ teams }: { teams: Team[] }) => ({
+ *     team: choice("Which team should handle this?",
+ *       Object.fromEntries(teams.map((t) => [t.slug, t.description])))
+ *   });
+ * }
+ * await TeamRouter.judge(ticket.body, { inputs: { teams } });
+ */
+export declare abstract class Judge {
+    /** The judgment model. Defaults to the instance default, then `jev-latest`. */
+    static model?: LazyValue<string, never>;
+    /** Routes to a specific provider; normally inferred from the model. */
+    static provider?: string;
+    /** Names of the inputs `judge` must be given. */
+    static inputs?: readonly string[];
+    /** The questions, or a function of the declared inputs returning them. */
+    static questions: LazyValue<QuestionMap, never>;
+    /** Provider-specific request fields, or a function of the inputs. */
+    static providerOptions?: LazyValue<Record<string, unknown>, never>;
+    /**
+     * Judges the input and returns typed answers. The input is text, an object,
+     * or an array of JSON-compatible values - or a function of the inputs that
+     * returns one.
+     */
+    static judge<T extends typeof Judge, I extends Record<string, unknown> = Record<string, unknown>>(this: T, input: LazyValue<JudgmentInput, I>, options?: JudgeCallOptions<I>): Promise<JudgmentResult<QuestionsOf<T>>>;
+}
+/**
+ * Defines a judge without a class, mirroring `defineAgent`.
+ *
+ * @example
+ * const Urgency = defineJudge({
+ *   questions: { urgent: probability("Does this need attention today?") }
+ * });
+ * (await Urgency.judge("The site is down")).urgent.probability;
+ */
+export declare function defineJudge<const Q extends QuestionMap>(definition: {
+    questions: LazyValue<Q, never>;
+    model?: LazyValue<string, never>;
+    provider?: string;
+    inputs?: readonly string[];
+    providerOptions?: LazyValue<Record<string, unknown>, never>;
+}): {
+    new (): {};
+    questions: LazyValue<Q, never>;
+    model: LazyValue<string, never> | undefined;
+    provider: string | undefined;
+    inputs: readonly string[] | undefined;
+    providerOptions: LazyValue<Record<string, unknown>, never> | undefined;
+    /**
+     * Judges the input and returns typed answers. The input is text, an object,
+     * or an array of JSON-compatible values - or a function of the inputs that
+     * returns one.
+     */
+    judge<T extends typeof Judge, I extends Record<string, unknown> = Record<string, unknown>>(this: T, input: LazyValue<JudgmentInput, I>, options?: JudgeCallOptions<I>): Promise<JudgmentResult<QuestionsOf<T>>>;
+};
+//# sourceMappingURL=Judge.d.ts.map

package/dist/judge/Judge.d.ts.map

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

package/dist/judge/Judge.js

@@ -0,0 +1,104 @@
+import { NodeLLM } from "../llm.js";
+/**
+ * A reusable set of typed questions about your application data.
+ *
+ * Subclass it and declare `questions`; call `judge` with the input. Answers are
+ * typed from the declaration, so a choice's answer is a union of its options.
+ *
+ * @example
+ * class TicketTriage extends Judge {
+ *   static questions = {
+ *     urgent: probability("Does this need attention today?"),
+ *     department: choice("Which team should handle this?", {
+ *       billing: "Payments and refunds",
+ *       technical: "Bugs and integrations",
+ *       other: null
+ *     }),
+ *     frustration: score("How frustrated is the customer?", ["Calm", "Frustrated", "Angry"])
+ *   };
+ * }
+ *
+ * const judgment = await TicketTriage.judge("Please refund the duplicate charge today.");
+ * judgment.urgent.probability;  // number
+ * judgment.department.choice;   // "billing" | "technical" | "other"
+ *
+ * Settings can depend on runtime data. Declare the inputs a judge needs and
+ * pass them to `judge`; `questions`, `model` and `providerOptions` may be
+ * functions of those inputs, resolved once per judgment.
+ *
+ * @example
+ * class TeamRouter extends Judge {
+ *   static inputs = ["teams"] as const;
+ *   static questions = ({ teams }: { teams: Team[] }) => ({
+ *     team: choice("Which team should handle this?",
+ *       Object.fromEntries(teams.map((t) => [t.slug, t.description])))
+ *   });
+ * }
+ * await TeamRouter.judge(ticket.body, { inputs: { teams } });
+ */
+export class Judge {
+    /** The judgment model. Defaults to the instance default, then `jev-latest`. */
+    static model;
+    /** Routes to a specific provider; normally inferred from the model. */
+    static provider;
+    /** Names of the inputs `judge` must be given. */
+    static inputs;
+    /** The questions, or a function of the declared inputs returning them. */
+    static questions;
+    /** Provider-specific request fields, or a function of the inputs. */
+    static providerOptions;
+    /**
+     * Judges the input and returns typed answers. The input is text, an object,
+     * or an array of JSON-compatible values - or a function of the inputs that
+     * returns one.
+     */
+    static async judge(input, options = {}) {
+        const inputs = (options.inputs ?? {});
+        checkInputs(this, inputs);
+        const resolve = (value) => typeof value === "function" ? value(inputs) : value;
+        const questions = resolve(this.questions);
+        if (!questions) {
+            throw new Error(`${this.name} declares no questions`);
+        }
+        const declaredOptions = resolve(this.providerOptions);
+        const providerOptions = declaredOptions || options.providerOptions
+            ? { ...declaredOptions, ...options.providerOptions }
+            : undefined;
+        const llm = options.llm ?? NodeLLM;
+        return llm.judge(resolve(input), {
+            questions: questions,
+            model: options.model ?? resolve(this.model),
+            provider: options.provider ?? this.provider,
+            providerOptions,
+            requestTimeout: options.requestTimeout
+        });
+    }
+}
+function checkInputs(judge, inputs) {
+    const declared = judge.inputs ?? [];
+    const given = Object.keys(inputs);
+    const missing = declared.filter((name) => !(name in inputs));
+    const unknown = given.filter((name) => !declared.includes(name));
+    if (missing.length > 0)
+        throw new Error(`${judge.name} is missing inputs: ${missing.join(", ")}`);
+    if (unknown.length > 0)
+        throw new Error(`${judge.name} does not declare inputs: ${unknown.join(", ")}`);
+}
+/**
+ * Defines a judge without a class, mirroring `defineAgent`.
+ *
+ * @example
+ * const Urgency = defineJudge({
+ *   questions: { urgent: probability("Does this need attention today?") }
+ * });
+ * (await Urgency.judge("The site is down")).urgent.probability;
+ */
+export function defineJudge(definition) {
+    return class extends Judge {
+        static questions = definition.questions;
+        static model = definition.model;
+        static provider = definition.provider;
+        static inputs = definition.inputs;
+        static providerOptions = definition.providerOptions;
+    };
+}

package/dist/judge/Judgment.d.ts

@@ -0,0 +1,116 @@
+import { JudgmentResponse, Usage } from "../providers/Provider.js";
+import { ChoiceQuestion, Description, ProbabilityQuestion, NamedQuestion, QuestionDefinition, QuestionMap, ScoreQuestion } from "./Question.js";
+/** The probability that a yes/no statement holds, between 0 and 1. */
+export declare class ProbabilityAnswer {
+    readonly probability: number;
+    readonly type: "probability";
+    constructor(probability: number);
+    toJSON(): {
+        type: "probability";
+        probability: number;
+    };
+}
+/**
+ * The selected option, with a probability for every option. `confidence`
+ * describes how concentrated the distribution is; it is not a guarantee that
+ * the choice is correct.
+ */
+export declare class ChoiceAnswer<K extends string = string> {
+    readonly choice: K;
+    readonly probabilities: Readonly<Record<K, number>>;
+    readonly confidence: number;
+    readonly type: "choice";
+    constructor(choice: K, probabilities: Readonly<Record<K, number>>, confidence: number);
+    toJSON(): {
+        type: "choice";
+        choice: K;
+        probabilities: Readonly<Record<K, number>>;
+        confidence: number;
+    };
+}
+/**
+ * A probability-weighted position on an ordered scale. Level 0 is the first
+ * level, so with three levels the score runs from 0 to 2 and can fall between
+ * them. `probabilities` is keyed by level index.
+ */
+export declare class ScoreAnswer {
+    readonly score: number;
+    readonly levels: readonly Description[];
+    readonly probabilities: Readonly<Record<number, number>>;
+    readonly confidence: number;
+    readonly type: "score";
+    constructor(score: number, levels: readonly Description[], probabilities: Readonly<Record<number, number>>, confidence: number);
+    toJSON(): {
+        type: "score";
+        score: number;
+        levels: readonly Description[];
+        probabilities: Readonly<Record<number, number>>;
+        confidence: number;
+    };
+}
+export type Answer = ProbabilityAnswer | ChoiceAnswer | ScoreAnswer;
+/** The answer type a question produces. */
+export type AnswerFor<D extends QuestionDefinition> = D extends ProbabilityQuestion ? ProbabilityAnswer : D extends ChoiceQuestion<infer K> ? ChoiceAnswer<K> : D extends ScoreQuestion ? ScoreAnswer : never;
+/** Answers keyed by question name, typed from the questions asked. */
+export type AnswersOf<Q extends QuestionMap> = {
+    readonly [N in keyof Q]: AnswerFor<Q[N]>;
+};
+/**
+ * The typed answers to a set of questions, with the model that answered them
+ * and the tokens it used.
+ *
+ * Answers are available by name - `judgment.urgent.probability` - and through
+ * `judgment.answers`. A question named like one of Judgment's own members
+ * (`model`, `usage`, `get`, ...) is only reachable through `answers` or `get`.
+ */
+export declare class Judgment<Q extends QuestionMap = QuestionMap> {
+    readonly answers: AnswersOf<Q>;
+    /** The model that answered, as reported by the provider. */
+    readonly model: string;
+    /** Token usage. `cost` is present only when the model has known pricing. */
+    readonly usage: Usage;
+    /** The provider's raw response. */
+    readonly raw?: unknown | undefined;
+    constructor(answers: AnswersOf<Q>, 
+    /** The model that answered, as reported by the provider. */
+    model: string, 
+    /** Token usage. `cost` is present only when the model has known pricing. */
+    usage: Usage, 
+    /** The provider's raw response. */
+    raw?: unknown | undefined);
+    /** Returns the named answer, or undefined when there is none. */
+    get<N extends keyof Q & string>(name: N): AnswersOf<Q>[N] | undefined;
+    /** Returns the named answer, throwing when there is none. */
+    fetch<N extends keyof Q & string>(name: N): AnswersOf<Q>[N];
+    [Symbol.iterator](): IterableIterator<[keyof Q & string, Answer]>;
+    toJSON(): {
+        model: string;
+        answers: {
+            [k: string]: {
+                type: "probability";
+                probability: number;
+            } | {
+                type: "score";
+                score: number;
+                levels: readonly Description[];
+                probabilities: Readonly<Record<number, number>>;
+                confidence: number;
+            } | {
+                type: "choice";
+                choice: string;
+                probabilities: Readonly<Record<string, number>>;
+                confidence: number;
+            };
+        };
+        usage: Usage;
+    };
+}
+/** A Judgment whose answers can also be read directly by question name. */
+export type JudgmentResult<Q extends QuestionMap = QuestionMap> = Judgment<Q> & Omit<AnswersOf<Q>, keyof Judgment<Q>>;
+/**
+ * Wraps a provider's answers in typed, frozen answer objects. Every question
+ * must come back answered with the type it was asked as; anything else means
+ * the provider and the request disagree, and is reported rather than guessed.
+ */
+export declare function buildJudgment<Q extends QuestionMap>(response: JudgmentResponse, questions: NamedQuestion[]): JudgmentResult<Q>;
+//# sourceMappingURL=Judgment.d.ts.map

package/dist/judge/Judgment.d.ts.map

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

package/dist/judge/Judgment.js

@@ -0,0 +1,159 @@
+/** The probability that a yes/no statement holds, between 0 and 1. */
+export class ProbabilityAnswer {
+    probability;
+    type = "probability";
+    constructor(probability) {
+        this.probability = probability;
+        Object.freeze(this);
+    }
+    toJSON() {
+        return { type: this.type, probability: this.probability };
+    }
+}
+/**
+ * The selected option, with a probability for every option. `confidence`
+ * describes how concentrated the distribution is; it is not a guarantee that
+ * the choice is correct.
+ */
+export class ChoiceAnswer {
+    choice;
+    probabilities;
+    confidence;
+    type = "choice";
+    constructor(choice, probabilities, confidence) {
+        this.choice = choice;
+        this.probabilities = probabilities;
+        this.confidence = confidence;
+        Object.freeze(this.probabilities);
+        Object.freeze(this);
+    }
+    toJSON() {
+        return {
+            type: this.type,
+            choice: this.choice,
+            probabilities: this.probabilities,
+            confidence: this.confidence
+        };
+    }
+}
+/**
+ * A probability-weighted position on an ordered scale. Level 0 is the first
+ * level, so with three levels the score runs from 0 to 2 and can fall between
+ * them. `probabilities` is keyed by level index.
+ */
+export class ScoreAnswer {
+    score;
+    levels;
+    probabilities;
+    confidence;
+    type = "score";
+    constructor(score, levels, probabilities, confidence) {
+        this.score = score;
+        this.levels = levels;
+        this.probabilities = probabilities;
+        this.confidence = confidence;
+        Object.freeze(this.levels);
+        Object.freeze(this.probabilities);
+        Object.freeze(this);
+    }
+    toJSON() {
+        return {
+            type: this.type,
+            score: this.score,
+            levels: this.levels,
+            probabilities: this.probabilities,
+            confidence: this.confidence
+        };
+    }
+}
+/**
+ * The typed answers to a set of questions, with the model that answered them
+ * and the tokens it used.
+ *
+ * Answers are available by name - `judgment.urgent.probability` - and through
+ * `judgment.answers`. A question named like one of Judgment's own members
+ * (`model`, `usage`, `get`, ...) is only reachable through `answers` or `get`.
+ */
+export class Judgment {
+    answers;
+    model;
+    usage;
+    raw;
+    constructor(answers, 
+    /** The model that answered, as reported by the provider. */
+    model, 
+    /** Token usage. `cost` is present only when the model has known pricing. */
+    usage, 
+    /** The provider's raw response. */
+    raw) {
+        this.answers = answers;
+        this.model = model;
+        this.usage = usage;
+        this.raw = raw;
+        Object.freeze(this.answers);
+        for (const name of Object.keys(answers)) {
+            if (name in this)
+                continue;
+            Object.defineProperty(this, name, {
+                value: answers[name],
+                enumerable: false
+            });
+        }
+        Object.freeze(this);
+    }
+    /** Returns the named answer, or undefined when there is none. */
+    get(name) {
+        return Object.prototype.hasOwnProperty.call(this.answers, name)
+            ? this.answers[name]
+            : undefined;
+    }
+    /** Returns the named answer, throwing when there is none. */
+    fetch(name) {
+        const answer = this.get(name);
+        if (answer === undefined)
+            throw new Error(`No answer named '${name}' in this judgment`);
+        return answer;
+    }
+    *[Symbol.iterator]() {
+        for (const [name, answer] of Object.entries(this.answers)) {
+            yield [name, answer];
+        }
+    }
+    toJSON() {
+        return {
+            model: this.model,
+            answers: Object.fromEntries(Object.entries(this.answers).map(([name, answer]) => [name, answer.toJSON()])),
+            usage: this.usage
+        };
+    }
+}
+/**
+ * Wraps a provider's answers in typed, frozen answer objects. Every question
+ * must come back answered with the type it was asked as; anything else means
+ * the provider and the request disagree, and is reported rather than guessed.
+ */
+export function buildJudgment(response, questions) {
+    const answers = {};
+    for (const question of questions) {
+        const data = response.answers[question.name];
+        if (!data)
+            throw new Error(`The provider returned no answer for '${question.name}'`);
+        if (data.type !== question.type) {
+            throw new Error(`The provider answered '${question.name}' as a ${data.type}, but it was asked as a ${question.type}`);
+        }
+        switch (data.type) {
+            case "probability":
+                answers[question.name] = new ProbabilityAnswer(data.probability);
+                break;
+            case "choice":
+                answers[question.name] = new ChoiceAnswer(data.choice, { ...data.probabilities }, data.confidence);
+                break;
+            case "score":
+                // Copy the levels: the answer is frozen, and freezing the caller's own
+                // question definition would be a surprising side effect.
+                answers[question.name] = new ScoreAnswer(data.score, structuredClone(question.levels), { ...data.probabilities }, data.confidence);
+                break;
+        }
+    }
+    return new Judgment(answers, response.model, response.usage, response.raw);
+}