@procedures/llm 0.0.0-stage → 0.3.0

package/src/anthropic.ts

@@ -0,0 +1,255 @@
+/**
+ * The Anthropic Messages API over `fetch` (roadmap R46).
+ *
+ * The procedures send each request with the `fetch` of the module settings, not through
+ * `http.request`: the API key goes in a header, and the input of a nested call is visible to the
+ * interceptors and to the traces of the host. The key comes from an environment variable that the
+ * module names. An input cannot give a key.
+ *
+ * A call stops at the earliest of its time limit, the deadline of its capability and the abort of
+ * the caller. A stop is an `InvocationError` with the code `TIMEOUT` or `ABORTED`.
+ */
+
+import { InvocationError, type ProcedureContext, type ProcedurePath } from "@procedures/client";
+import { LlmError } from "./errors.js";
+import type { LlmEffort, LlmUsage } from "./types.js";
+
+/** The variables that the module reads: a name and a value, or undefined for a variable that is not set. */
+export type EnvSource = Readonly<Record<string, string | undefined>>;
+
+/** The `fetch` that the procedures use. A test gives a fake one. */
+export type FetchFunction = (url: string, init: RequestInit) => Promise<Response>;
+
+/** The default model of the module. */
+export const DEFAULT_MODEL = "claude-sonnet-5-5";
+/** The default environment variable of the API key. */
+export const DEFAULT_API_KEY_ENV = "ANTHROPIC_API_KEY";
+/** The default base URL of the API. */
+export const DEFAULT_BASE_URL = "https://api.anthropic.com";
+/** The default of `maxTokens`. */
+export const DEFAULT_MAX_TOKENS = 16_000;
+/** The default time limit of a call: 10 minutes. */
+export const DEFAULT_TIMEOUT_MS = 600_000;
+/** The version header of the Messages API. */
+export const ANTHROPIC_VERSION = "2023-06-01";
+/** The beta header of the server-side fallback with `fallbacks: "default"`. */
+export const FALLBACK_BETA = "server-side-fallback-2026-07-01";
+/** The largest answer that the procedures read, in bytes. */
+const MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
+
+/** What the procedures of a module use. */
+export interface LlmSettings {
+  readonly apiKeyEnv: string;
+  /** This function gives the variables at the time of a call. */
+  readonly env: () => EnvSource;
+  readonly fetch: FetchFunction;
+  readonly baseUrl: string;
+  readonly defaultModel: string;
+  /** The default of the `fallback` input. */
+  readonly fallback: boolean;
+}
+
+/** The settings of the default module. */
+export const DEFAULT_LLM_SETTINGS: LlmSettings = Object.freeze({
+  apiKeyEnv: DEFAULT_API_KEY_ENV,
+  env: () => process.env,
+  fetch: (url: string, init: RequestInit) => globalThis.fetch(url, init),
+  baseUrl: DEFAULT_BASE_URL,
+  defaultModel: DEFAULT_MODEL,
+  fallback: true,
+});
+
+/** One content block of a message. The procedures read only the text blocks. */
+export interface ContentBlock {
+  readonly type: string;
+  readonly text?: string;
+  readonly [key: string]: unknown;
+}
+
+/** One message of a request. The content of an assistant turn is the content of the answer, unchanged. */
+export interface MessageParam {
+  readonly role: "user" | "assistant";
+  readonly content: string | readonly ContentBlock[];
+}
+
+/** The request body of the Messages API, as the procedures send it. */
+export interface MessagesRequest {
+  model: string;
+  max_tokens: number;
+  messages: MessageParam[];
+  system?: string;
+  temperature?: number;
+  output_config?: { effort?: LlmEffort; format?: { type: "json_schema"; schema: unknown } };
+  fallbacks?: "default";
+}
+
+/** The parts of an answer that the procedures use. */
+export interface MessagesResponse {
+  readonly model: string;
+  readonly content: readonly ContentBlock[];
+  readonly stopReason: string;
+  readonly stopDetails: { readonly category?: string | null; readonly explanation?: string | null } | undefined;
+  readonly usage: LlmUsage;
+}
+
+/** The time limit and the stop of one procedure call. */
+export interface CallLimits {
+  readonly path: ProcedurePath;
+  readonly ctx: Pick<ProcedureContext, "signal" | "capability"> | undefined;
+  readonly timeoutMs: number;
+}
+
+/** The API key, or a `NO_API_KEY` error that names the variable. */
+export function apiKey(settings: LlmSettings): string {
+  const value = settings.env()[settings.apiKeyEnv];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new LlmError("NO_API_KEY", `llm: the environment variable ${settings.apiKeyEnv} has no API key`);
+  }
+  return value.trim();
+}
+
+/** The text blocks of an answer, joined. */
+export function textOf(content: readonly ContentBlock[]): string {
+  return content
+    .filter((block) => block.type === "text" && typeof block.text === "string")
+    .map((block) => block.text)
+    .join("");
+}
+
+/** The sum of two usages. */
+export function addUsage(a: LlmUsage, b: LlmUsage): LlmUsage {
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    cacheReadInputTokens: a.cacheReadInputTokens + b.cacheReadInputTokens,
+    cacheCreationInputTokens: a.cacheCreationInputTokens + b.cacheCreationInputTokens,
+  };
+}
+
+/** A usage of zero tokens. */
+export const NO_USAGE: LlmUsage = Object.freeze({ inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, cacheCreationInputTokens: 0 });
+
+const count = (value: unknown): number => (typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0);
+
+/** The answer of the API, checked: an answer of another form is a `BAD_RESPONSE`. */
+function parseResponse(text: string): MessagesResponse {
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw new LlmError("BAD_RESPONSE", `llm: the answer of the API is not JSON: ${text.slice(0, 200)}`);
+  }
+  const record = body as Record<string, unknown> | null;
+  if (record === null || typeof record !== "object" || !Array.isArray(record["content"]) || typeof record["stop_reason"] !== "string") {
+    throw new LlmError("BAD_RESPONSE", "llm: the answer of the API is not a message with content and stop_reason");
+  }
+  const usage = (record["usage"] ?? {}) as Record<string, unknown>;
+  const details = record["stop_details"];
+  return {
+    model: typeof record["model"] === "string" ? record["model"] : "",
+    content: (record["content"] as unknown[]).filter((block): block is ContentBlock => block !== null && typeof block === "object" && typeof (block as ContentBlock).type === "string"),
+    stopReason: record["stop_reason"],
+    stopDetails: details !== null && typeof details === "object" ? (details as MessagesResponse["stopDetails"]) : undefined,
+    usage: {
+      inputTokens: count(usage["input_tokens"]),
+      outputTokens: count(usage["output_tokens"]),
+      cacheReadInputTokens: count(usage["cache_read_input_tokens"]),
+      cacheCreationInputTokens: count(usage["cache_creation_input_tokens"]),
+    },
+  };
+}
+
+/** The error of an answer with an error status. The message has the type and the message of the API. */
+function apiError(status: number, text: string, key: string): LlmError {
+  let detail = text.slice(0, 500);
+  try {
+    const error = (JSON.parse(text) as { error?: { type?: unknown; message?: unknown } }).error;
+    if (error && typeof error.message === "string") detail = `${typeof error.type === "string" ? `${error.type}: ` : ""}${error.message}`;
+  } catch {
+    // The text of the answer stays the detail
+  }
+  // The API does not repeat the key, but the message must not carry it in any case
+  const safe = detail.split(key).join("[key]");
+  const retryable = status === 408 || status === 409 || status === 429 || status >= 500;
+  return new LlmError("API_ERROR", `llm: the API answered ${status}: ${safe}`, { status, retryable });
+}
+
+/** The time that is left before the deadline of the capability, or undefined. */
+function deadlineLeft(ctx: CallLimits["ctx"]): number | undefined {
+  const deadline = ctx?.capability?.deadline;
+  return typeof deadline === "number" ? deadline - Date.now() : undefined;
+}
+
+/** The body of an answer as text, with a size limit. */
+async function readText(response: Response): Promise<string> {
+  const declared = Number(response.headers.get("content-length") ?? "0");
+  if (declared > MAX_RESPONSE_BYTES) throw new LlmError("BAD_RESPONSE", `llm: the answer of the API is larger than ${MAX_RESPONSE_BYTES} bytes`);
+  const text = await response.text();
+  if (text.length > MAX_RESPONSE_BYTES) throw new LlmError("BAD_RESPONSE", `llm: the answer of the API is larger than ${MAX_RESPONSE_BYTES} bytes`);
+  return text;
+}
+
+/**
+ * This function sends one request to the Messages API and gives the checked answer. It throws a
+ * `REFUSAL` error when a safety classifier declined the request.
+ */
+export async function sendMessages(request: MessagesRequest, settings: LlmSettings, limits: CallLimits): Promise<MessagesResponse> {
+  const key = apiKey(settings);
+  const { path, ctx } = limits;
+  const left = deadlineLeft(ctx);
+  if (left !== undefined && left <= 0) throw new InvocationError("TIMEOUT", `The deadline of ${path.join(".")} passed before the call`, path);
+  const timeoutMs = left === undefined ? limits.timeoutMs : Math.min(limits.timeoutMs, left);
+  if (ctx?.signal?.aborted) throw new InvocationError("ABORTED", `Procedure was aborted: ${path.join(".")}`, path);
+
+  const controller = new AbortController();
+  let stop: "timeout" | "caller" | undefined;
+  const timer = setTimeout(() => {
+    stop ??= "timeout";
+    controller.abort();
+  }, timeoutMs);
+  const onAbort = (): void => {
+    stop ??= "caller";
+    controller.abort();
+  };
+  ctx?.signal?.addEventListener("abort", onAbort, { once: true });
+
+  const headers: Record<string, string> = {
+    "content-type": "application/json",
+    "x-api-key": key,
+    "anthropic-version": ANTHROPIC_VERSION,
+  };
+  if (request.fallbacks !== undefined) headers["anthropic-beta"] = FALLBACK_BETA;
+
+  try {
+    let response: Response;
+    try {
+      response = await settings.fetch(`${settings.baseUrl.replace(/\/+$/, "")}/v1/messages`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(request),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (stop === undefined) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new LlmError("CONNECTION", `llm: the connection to the API failed: ${message.split(key).join("[key]")}`, { retryable: true });
+      }
+      throw error;
+    }
+    const text = await readText(response);
+    if (!response.ok) throw apiError(response.status, text, key);
+    const answer = parseResponse(text);
+    if (answer.stopReason === "refusal") {
+      const category = answer.stopDetails?.category ?? "not given";
+      throw new LlmError("REFUSAL", `llm: a safety classifier declined the request (category: ${category})`);
+    }
+    return answer;
+  } catch (error) {
+    if (stop === "timeout") throw new InvocationError("TIMEOUT", `${path.join(".")} passed its time limit of ${timeoutMs} ms`, path);
+    if (stop === "caller") throw new InvocationError("ABORTED", `Procedure was aborted: ${path.join(".")}`, path);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    ctx?.signal?.removeEventListener("abort", onAbort);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,38 @@
+/**
+ * The errors of the llm procedures. A stop of the call (its time limit, its deadline, the abort of
+ * the caller) is an `InvocationError` with the code `TIMEOUT` or `ABORTED`.
+ */
+
+/** The reason of an `LlmError`. */
+export type LlmErrorCode =
+  /** The environment variable of the API key has no value. */
+  | "NO_API_KEY"
+  /** The API answered with an error status. `status` has it. */
+  | "API_ERROR"
+  /** The connection to the API failed. */
+  | "CONNECTION"
+  /** The answer of the API does not have the form of a message. */
+  | "BAD_RESPONSE"
+  /** A safety classifier declined the request (`stop_reason: "refusal"`). */
+  | "REFUSAL"
+  /** `llm.structured`: the output stopped at `maxTokens`, so the JSON is not complete. */
+  | "MAX_TOKENS"
+  /** `llm.structured`: no answer gave a value that the schema accepts. */
+  | "INVALID_OUTPUT";
+
+/** An error of a call to the model. */
+export class LlmError extends Error {
+  override readonly name = "LlmError";
+  readonly code: LlmErrorCode;
+  /** The HTTP status of an `API_ERROR`. */
+  readonly status: number | undefined;
+  /** True when the same call can succeed later: a rate limit, an overload, a server error or a connection error. */
+  readonly retryable: boolean;
+
+  constructor(code: LlmErrorCode, message: string, options: { status?: number | undefined; retryable?: boolean | undefined } = {}) {
+    super(message);
+    this.code = code;
+    this.status = options.status;
+    this.retryable = options.retryable ?? false;
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// The root registers nothing: import "<package>/register", or give the module to createRegistry()
+export * from "./module.js";
+export * from "./types.js";
+export { llmComplete, llmStructured, MAX_RETRIES } from "./procedures/llm/index.js";
+// The provider (roadmap R46)
+export {
+  ANTHROPIC_VERSION,
+  DEFAULT_API_KEY_ENV,
+  DEFAULT_BASE_URL,
+  DEFAULT_LLM_SETTINGS,
+  DEFAULT_MAX_TOKENS,
+  DEFAULT_MODEL,
+  DEFAULT_TIMEOUT_MS,
+  FALLBACK_BETA,
+  type EnvSource,
+  type FetchFunction,
+  type LlmSettings,
+} from "./anthropic.js";
+export { LlmError, type LlmErrorCode } from "./errors.js";
+export { constrainedSchema, parseAnswer, UNSUPPORTED_KEYWORDS } from "./schema.js";

package/src/module.ts

@@ -0,0 +1,186 @@
+/**
+ * The procedures of @procedures/llm as data. Importing this file registers nothing.
+ *
+ * Scaffold a procedure with: mark procedure new <name> --path packages/llm
+ *
+ * `llmModule` sends each request to the Anthropic Messages API with the key of the environment
+ * variable `ANTHROPIC_API_KEY`. `createLlmModule()` gives the same procedures with another
+ * variable, another default model, another base URL or another `fetch` (roadmap R46).
+ */
+
+import { z } from "zod";
+import {
+  defineModule,
+  registerModules,
+  PROCEDURE_REGISTRY,
+  createProcedure,
+  zodAdapter,
+  type AnyProcedure,
+  type Effects,
+  type ProcedureContext,
+  type ProcedureModule,
+  type ProcedureRegistry,
+} from "@procedures/client";
+import { llmComplete } from "./procedures/llm/complete.js";
+import { llmStructured, MAX_RETRIES } from "./procedures/llm/structured.js";
+import { DEFAULT_LLM_SETTINGS, type EnvSource, type FetchFunction, type LlmSettings } from "./anthropic.js";
+import type { LlmCompleteInput, LlmCompleteOutput, LlmStructuredInput, LlmStructuredOutput } from "./types.js";
+
+// =============================================================================
+// Schemas
+// =============================================================================
+
+const requestFields = {
+  prompt: z.string().min(1).max(4_000_000).describe("The text of the user"),
+  system: z.string().max(4_000_000).optional().describe("The system text: the instructions to the model"),
+  model: z
+    .string()
+    .min(1)
+    .max(200)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._:@/-]*$/, "A model ID")
+    .optional()
+    .describe("The model (default: the model of the module, claude-sonnet-5-5)"),
+  maxTokens: z.number().int().min(1).max(64_000).optional().describe("The most tokens of the output, with the thinking (default 16000)"),
+  temperature: z.number().min(0).max(1).optional().describe("The temperature, 0 to 1. Some models accept only the default"),
+  effort: z.enum(["low", "medium", "high", "xhigh", "max"]).optional().describe("The effort of the model (default: the default of the model)"),
+  timeoutMs: z.number().int().positive().max(3_600_000).optional().describe("The time limit of the call, in milliseconds (default 600000)"),
+  fallback: z.boolean().optional().describe("True: the API runs a declined request again on its fallback model (default: the option of the module, true)"),
+};
+
+const usage = z
+  .object({
+    inputTokens: z.number().int().describe("The tokens of the input that the cache did not have"),
+    outputTokens: z.number().int().describe("The tokens of the output, with the thinking"),
+    cacheReadInputTokens: z.number().int().describe("The tokens of the input from the cache"),
+    cacheCreationInputTokens: z.number().int().describe("The tokens of the input that went into the cache"),
+  })
+  .describe("The tokens of the call");
+
+const LlmCompleteInputSchema = z.object(requestFields);
+
+const LlmCompleteOutputSchema = z.object({
+  text: z.string().describe("The text of the answer"),
+  model: z.string().describe("The model that answered"),
+  stopReason: z.string().describe("Why the model stopped: end_turn, max_tokens, stop_sequence or another reason"),
+  usage,
+});
+
+const LlmStructuredInputSchema = z.object({
+  ...requestFields,
+  schema: z.record(z.string(), z.unknown()).describe("The JSON Schema of the value"),
+  constrained: z.boolean().optional().describe("True (default): the API constrains the output to the schema. False: the system text gives the schema"),
+  retries: z.number().int().min(0).max(MAX_RETRIES).optional().describe("The new tries after an answer that is not valid, 0 to 2 (default 2)"),
+});
+
+const LlmStructuredOutputSchema = z.object({
+  value: z.unknown().describe("The value: the schema accepts it"),
+  model: z.string().describe("The model that gave the value"),
+  attempts: z.number().int().describe("The number of calls to the model"),
+  usage,
+  unchecked: z.array(z.string()).describe("The keywords of the schema that the check does not examine fully"),
+});
+
+// =============================================================================
+// Procedures
+// =============================================================================
+
+/**
+ * The effects of each procedure: it sends data to a system outside the host and gets an answer.
+ * A call costs money and can change the state of an account, so it declares a write. It deletes
+ * nothing and a second call is a new call.
+ */
+const SENDS_TO_MODEL: Effects = Object.freeze({ reads: Object.freeze(["network"]), writes: Object.freeze(["network"]), destructive: false, idempotent: false });
+
+/** The two procedures, with handlers that use the settings. */
+function llmProcedures(settings: LlmSettings): AnyProcedure[] {
+  const llmCompleteProcedure = createProcedure()
+    .path(["llm", "complete"])
+    .input(zodAdapter<LlmCompleteInput>(LlmCompleteInputSchema))
+    .output(zodAdapter<LlmCompleteOutput>(LlmCompleteOutputSchema))
+    .meta({
+      description: "Send a prompt to a language model and give the text and the usage",
+      tags: ["llm", "anthropic"],
+      args: ["prompt"],
+      shorts: { model: "m", system: "s" },
+      output: "json",
+      effects: SENDS_TO_MODEL,
+    })
+    .handler(async (input: LlmCompleteInput, ctx: ProcedureContext): Promise<LlmCompleteOutput> => llmComplete(input, ctx, settings))
+    .build();
+
+  const llmStructuredProcedure = createProcedure()
+    .path(["llm", "structured"])
+    .input(zodAdapter<LlmStructuredInput>(LlmStructuredInputSchema))
+    .output(zodAdapter<LlmStructuredOutput>(LlmStructuredOutputSchema))
+    .meta({
+      description: "Send a prompt and a JSON Schema to a language model and give a value that the schema accepts",
+      tags: ["llm", "anthropic", "json-schema"],
+      args: ["prompt"],
+      shorts: { model: "m", system: "s" },
+      output: "json",
+      effects: SENDS_TO_MODEL,
+    })
+    .handler(async (input: LlmStructuredInput, ctx: ProcedureContext): Promise<LlmStructuredOutput> => llmStructured(input, ctx, settings))
+    .build();
+
+  return [llmCompleteProcedure, llmStructuredProcedure];
+}
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Each call reads the
+ * key from `ANTHROPIC_API_KEY`. Importing this file registers nothing.
+ */
+export const llmModule: ProcedureModule = defineModule("@procedures/llm", llmProcedures(DEFAULT_LLM_SETTINGS));
+
+export default llmModule;
+
+/** The options of `createLlmModule()`. */
+export interface LlmModuleOptions {
+  /** The environment variable of the API key. The default is `ANTHROPIC_API_KEY`. */
+  readonly apiKeyEnv?: string | undefined;
+  /** The model of an input without `model`. The default is `claude-sonnet-5-5`. */
+  readonly defaultModel?: string | undefined;
+  /** The base URL of the API. The default is `https://api.anthropic.com`. */
+  readonly baseUrl?: string | undefined;
+  /** The default of the `fallback` input. The default is true. */
+  readonly fallback?: boolean | undefined;
+  /** The `fetch` of the requests. The default is the global `fetch`. A test gives a fake one. */
+  readonly fetch?: FetchFunction | undefined;
+  /** The variables: a record, or a function that gives them at each call. The default is `process.env`. */
+  readonly env?: EnvSource | (() => EnvSource) | undefined;
+}
+
+/**
+ * This function gives the module of this package with other settings. Without options, it gives
+ * `llmModule`. A host gives it to `createRegistry()` before its bundles, so it replaces the
+ * `llmModule` that a bundle requires (the first module of a name counts). A bad option throws here.
+ *
+ * ```ts
+ * createRegistry(createLlmModule({ apiKeyEnv: "WORK_ANTHROPIC_KEY", defaultModel: "claude-haiku-5-5" }));
+ * ```
+ */
+export function createLlmModule(options: LlmModuleOptions = {}): ProcedureModule {
+  if (Object.values(options).every((value) => value === undefined)) return llmModule;
+  const apiKeyEnv = options.apiKeyEnv ?? DEFAULT_LLM_SETTINGS.apiKeyEnv;
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(apiKeyEnv)) throw new TypeError(`createLlmModule: apiKeyEnv must be the name of a variable, not ${JSON.stringify(apiKeyEnv)}`);
+  const baseUrl = options.baseUrl ?? DEFAULT_LLM_SETTINGS.baseUrl;
+  if (!/^https?:\/\//.test(baseUrl)) throw new TypeError("createLlmModule: baseUrl must be an http or https URL");
+  const env = options.env;
+  const settings: LlmSettings = {
+    apiKeyEnv,
+    env: env === undefined ? DEFAULT_LLM_SETTINGS.env : typeof env === "function" ? env : () => env,
+    fetch: options.fetch ?? DEFAULT_LLM_SETTINGS.fetch,
+    baseUrl,
+    defaultModel: options.defaultModel ?? DEFAULT_LLM_SETTINGS.defaultModel,
+    fallback: options.fallback ?? DEFAULT_LLM_SETTINGS.fallback,
+  };
+  return defineModule("@procedures/llm", llmProcedures(settings));
+}
+
+/**
+ * This function registers the procedures of @procedures/llm in a registry. The default is the
+ * global registry. The options are the options of `createLlmModule()`.
+ */
+export function registerLlmProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY, options: LlmModuleOptions = {}): void {
+  registerModules(registry, [createLlmModule(options)]);
+}

package/src/procedures/llm/complete.ts

@@ -0,0 +1,26 @@
+/**
+ * llm.complete procedure
+ *
+ * Send a prompt to a language model and give the text and the usage. The text is the text
+ * blocks of the answer, joined: the thinking blocks are not in it.
+ */
+
+import { DEFAULT_LLM_SETTINGS, sendMessages, textOf, type CallLimits, type LlmSettings } from "../../anthropic.js";
+import { baseRequest, timeoutOf } from "../../request.js";
+import type { LlmCompleteInput, LlmCompleteOutput } from "../../types.js";
+
+const PATH = ["llm", "complete"];
+
+/**
+ * Send a prompt to a language model and give the text and the usage
+ */
+export async function llmComplete(input: LlmCompleteInput, ctx?: CallLimits["ctx"], settings: LlmSettings = DEFAULT_LLM_SETTINGS): Promise<LlmCompleteOutput> {
+  const request = baseRequest(input, settings, input.system);
+  const answer = await sendMessages(request, settings, { path: PATH, ctx, timeoutMs: timeoutOf(input) });
+  return {
+    text: textOf(answer.content),
+    model: answer.model || request.model,
+    stopReason: answer.stopReason,
+    usage: answer.usage,
+  };
+}

package/src/procedures/llm/index.ts

@@ -0,0 +1,2 @@
+export { llmComplete } from "./complete.js";
+export { llmStructured, MAX_RETRIES } from "./structured.js";

package/src/procedures/llm/structured.ts

@@ -0,0 +1,79 @@
+/**
+ * llm.structured procedure
+ *
+ * Send a prompt and a JSON Schema to a language model and give a value that the schema accepts.
+ * An answer that is not JSON, or that the schema refuses, gets a new try: the request then has
+ * the answer (its content, unchanged) and a user turn with the problems. At most 2 new tries.
+ */
+
+import { validateJson, type JsonValue } from "@procedures/json";
+import { LlmError } from "../../errors.js";
+import { addUsage, DEFAULT_LLM_SETTINGS, NO_USAGE, sendMessages, textOf, type CallLimits, type LlmSettings, type MessagesRequest } from "../../anthropic.js";
+import { baseRequest, timeoutOf } from "../../request.js";
+import { constrainedSchema, parseAnswer } from "../../schema.js";
+import type { LlmStructuredInput, LlmStructuredOutput, LlmUsage } from "../../types.js";
+
+const PATH = ["llm", "structured"];
+
+/** The most new tries after an answer that is not valid. */
+export const MAX_RETRIES = 2;
+
+/** The instruction of the system text: one JSON value and nothing else. */
+function instruction(input: LlmStructuredInput, constrained: boolean): string {
+  const lines = ["Answer with one JSON value that the JSON Schema below accepts. Give only the JSON value, with no other text and no code fence."];
+  if (!constrained) lines.push("", "JSON Schema:", JSON.stringify(input.schema));
+  return lines.join("\n");
+}
+
+/** The problems of a value against the schema, as one text, or undefined for a valid value. */
+function problemsOf(value: unknown, schema: Record<string, unknown>): { problems: string | undefined; unchecked: string[] } {
+  const result = validateJson(value as JsonValue, schema);
+  if (result.valid) return { problems: undefined, unchecked: [...result.unchecked] };
+  const problems = result.errors
+    .slice(0, 20)
+    .map((issue) => `${issue.pointer === "" ? "(root)" : issue.pointer}: ${issue.message}`)
+    .join("; ");
+  return { problems, unchecked: [...result.unchecked] };
+}
+
+/**
+ * Send a prompt and a JSON Schema to a language model and give a value that the schema accepts
+ */
+export async function llmStructured(input: LlmStructuredInput, ctx?: CallLimits["ctx"], settings: LlmSettings = DEFAULT_LLM_SETTINGS): Promise<LlmStructuredOutput> {
+  const constrained = input.constrained ?? true;
+  const retries = Math.min(Math.max(input.retries ?? MAX_RETRIES, 0), MAX_RETRIES);
+  const system = [input.system, instruction(input, constrained)].filter((part) => part !== undefined && part !== "").join("\n\n");
+  const request: MessagesRequest = baseRequest(input, settings, system);
+  if (constrained) {
+    request.output_config = { ...request.output_config, format: { type: "json_schema", schema: constrainedSchema(input.schema) } };
+  }
+
+  let usage: LlmUsage = NO_USAGE;
+  let lastProblem = "";
+  for (let attempt = 1; attempt <= retries + 1; attempt++) {
+    const answer = await sendMessages(request, settings, { path: PATH, ctx, timeoutMs: timeoutOf(input) });
+    usage = addUsage(usage, answer.usage);
+    if (answer.stopReason === "max_tokens") {
+      throw new LlmError("MAX_TOKENS", `llm.structured: the answer stopped at maxTokens (${request.max_tokens}), so the JSON is not complete`);
+    }
+    const parsed = parseAnswer(textOf(answer.content));
+    let problem: string;
+    if (parsed.ok) {
+      const { problems, unchecked } = problemsOf(parsed.value, input.schema);
+      if (problems === undefined) {
+        return { value: parsed.value, model: answer.model || request.model, attempts: attempt, usage, unchecked };
+      }
+      problem = `the schema refuses the value: ${problems}`;
+    } else {
+      problem = parsed.problem;
+    }
+    lastProblem = problem;
+    // The next request continues the conversation: the answer as it came, then the problems
+    request.messages = [
+      ...request.messages,
+      { role: "assistant", content: answer.content },
+      { role: "user", content: `That answer is not valid: ${problem}. Answer again with only the JSON value.` },
+    ];
+  }
+  throw new LlmError("INVALID_OUTPUT", `llm.structured: no answer of ${retries + 1} gave a valid value. The last problem: ${lastProblem}`);
+}

package/src/register.ts

@@ -0,0 +1,10 @@
+/**
+ * Importing this file registers the procedures of @procedures/llm in the global registry:
+ * `import "@procedures/llm/register"`. The package root registers nothing.
+ */
+
+import { registerLlmProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerLlmProcedures();

package/src/request.ts

@@ -0,0 +1,25 @@
+/**
+ * The request of the fields that both procedures take (`LlmRequestInput`).
+ */
+
+import { DEFAULT_MAX_TOKENS, DEFAULT_TIMEOUT_MS, type LlmSettings, type MessagesRequest } from "./anthropic.js";
+import type { LlmRequestInput } from "./types.js";
+
+/** This function gives the body of a request: the model, the limits, the system text and the user text. */
+export function baseRequest(input: LlmRequestInput, settings: LlmSettings, system: string | undefined): MessagesRequest {
+  const request: MessagesRequest = {
+    model: input.model ?? settings.defaultModel,
+    max_tokens: input.maxTokens ?? DEFAULT_MAX_TOKENS,
+    messages: [{ role: "user", content: input.prompt }],
+  };
+  if (system !== undefined && system !== "") request.system = system;
+  if (input.temperature !== undefined) request.temperature = input.temperature;
+  if (input.effort !== undefined) request.output_config = { effort: input.effort };
+  if (input.fallback ?? settings.fallback) request.fallbacks = "default";
+  return request;
+}
+
+/** The time limit of a call. */
+export function timeoutOf(input: LlmRequestInput): number {
+  return input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+}