@procedures/llm 0.0.0-stage → 0.3.0

package/src/schema.ts

@@ -0,0 +1,85 @@
+/**
+ * The JSON Schema of `llm.structured`: the schema that the API gets, and the parse of an answer.
+ *
+ * The structured outputs of the API support a subset of JSON Schema. The API refuses the
+ * numerical constraints, the string lengths, the array constraints and an `additionalProperties`
+ * other than `false`. `constrainedSchema()` removes those keywords, as the Anthropic SDKs do. The
+ * procedure examines the full schema after the answer, so the removed keywords still apply.
+ */
+
+/** The keywords that the structured outputs of the API do not support. */
+export const UNSUPPORTED_KEYWORDS: readonly string[] = Object.freeze([
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf",
+  "minLength",
+  "maxLength",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "contains",
+  "minContains",
+  "maxContains",
+  "minProperties",
+  "maxProperties",
+]);
+
+/** The keywords whose value is one schema. */
+const ONE_SCHEMA = ["items", "additionalItems", "not", "if", "then", "else", "propertyNames"];
+/** The keywords whose value is a list of schemas. */
+const SCHEMA_LIST = ["anyOf", "allOf", "oneOf", "prefixItems", "items"];
+/** The keywords whose value is a map of schemas. */
+const SCHEMA_MAP = ["properties", "patternProperties", "$defs", "definitions"];
+
+const isRecord = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** True when a schema describes an object. */
+function isObjectSchema(schema: Record<string, unknown>): boolean {
+  const type = schema["type"];
+  return type === "object" || (Array.isArray(type) && type.includes("object")) || (type === undefined && isRecord(schema["properties"]));
+}
+
+/**
+ * This function gives a copy of a schema for the structured outputs of the API: without the
+ * unsupported keywords, and with `additionalProperties: false` on each object. Without its
+ * constraints, the copy can accept a value that the full schema refuses. Thus the procedure
+ * examines each answer against the full schema.
+ */
+export function constrainedSchema(schema: unknown): unknown {
+  if (Array.isArray(schema)) return schema.map(constrainedSchema);
+  if (!isRecord(schema)) return schema;
+  const copy: Record<string, unknown> = {};
+  for (const [keyword, value] of Object.entries(schema)) {
+    if (UNSUPPORTED_KEYWORDS.includes(keyword)) continue;
+    if (SCHEMA_MAP.includes(keyword) && isRecord(value)) {
+      copy[keyword] = Object.fromEntries(Object.entries(value).map(([name, sub]) => [name, constrainedSchema(sub)]));
+    } else if (SCHEMA_LIST.includes(keyword) || ONE_SCHEMA.includes(keyword)) {
+      copy[keyword] = constrainedSchema(value);
+    } else {
+      copy[keyword] = value;
+    }
+  }
+  if (isObjectSchema(copy)) copy["additionalProperties"] = false;
+  return copy;
+}
+
+/** The result of the parse of an answer. */
+export type ParsedAnswer = { readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly problem: string };
+
+/**
+ * This function parses the text of an answer as one JSON value. It removes a code fence around
+ * the value (` ```json ... ``` `), because a model can add one without the constraint.
+ */
+export function parseAnswer(text: string): ParsedAnswer {
+  let body = text.trim();
+  const fence = /^```[a-zA-Z0-9_-]*\s*\n([\s\S]*?)\n?```$/.exec(body);
+  if (fence) body = fence[1]!.trim();
+  if (body === "") return { ok: false, problem: "the answer is empty" };
+  try {
+    return { ok: true, value: JSON.parse(body) as unknown };
+  } catch (error) {
+    return { ok: false, problem: `the answer is not JSON (${error instanceof Error ? error.message : String(error)})` };
+  }
+}

package/src/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here. The zod schemas are in
+ * `module.ts`: an exported schema needs a written type (isolatedDeclarations).
+ */
+
+/** The effort of the model: how much it thinks and how many tokens it spends. */
+export type LlmEffort = "low" | "medium" | "high" | "xhigh" | "max";
+
+/** The tokens of a call. */
+export interface LlmUsage {
+  /** The tokens of the input that the cache did not have. */
+  inputTokens: number;
+  /** The tokens of the output, with the tokens of the thinking. */
+  outputTokens: number;
+  /** The tokens of the input that came from the cache. */
+  cacheReadInputTokens: number;
+  /** The tokens of the input that went into the cache. */
+  cacheCreationInputTokens: number;
+}
+
+/** The fields of a request that each procedure takes. */
+export interface LlmRequestInput {
+  /** The text of the user. */
+  prompt: string;
+  /** The system text: the instructions to the model. */
+  system?: string | undefined;
+  /** The model. The default is the model of the module (`claude-sonnet-5-5`). */
+  model?: string | undefined;
+  /** The most tokens of the output, with the thinking. The default is 16000. */
+  maxTokens?: number | undefined;
+  /** The temperature, from 0 to 1. Some models accept only the default, and the API refuses another value. */
+  temperature?: number | undefined;
+  /** The effort of the model. Without it, the model uses its default. */
+  effort?: LlmEffort | undefined;
+  /** The time limit of the call, in milliseconds. The default is 600000 (10 minutes). */
+  timeoutMs?: number | undefined;
+  /**
+   * True: when a safety classifier declines the request, the API runs it again on the fallback
+   * model that it recommends. The default is the option of the module (true).
+   */
+  fallback?: boolean | undefined;
+}
+
+// =============================================================================
+// llm.complete
+// =============================================================================
+
+export type LlmCompleteInput = LlmRequestInput;
+
+export interface LlmCompleteOutput {
+  /** The text of the answer: the text blocks, joined. */
+  text: string;
+  /** The model that answered. After a fallback, it is the fallback model. */
+  model: string;
+  /** Why the model stopped: `end_turn`, `max_tokens`, `stop_sequence` or another reason of the API. */
+  stopReason: string;
+  usage: LlmUsage;
+}
+
+// =============================================================================
+// llm.structured
+// =============================================================================
+
+export interface LlmStructuredInput extends LlmRequestInput {
+  /** The JSON Schema of the value. */
+  schema: Record<string, unknown>;
+  /**
+   * True (default): the API constrains the output to the schema (structured outputs). The
+   * procedure removes the keywords that the API does not support, and examines them after the
+   * answer. False: the system text gives the schema, and the procedure examines the answer.
+   */
+  constrained?: boolean | undefined;
+  /** The number of new tries after an answer that is not valid: 0 to 2. The default is 2. */
+  retries?: number | undefined;
+}
+
+export interface LlmStructuredOutput {
+  /** The value: the schema accepts it. */
+  value: unknown;
+  /** The model that gave the value. */
+  model: string;
+  /** The number of calls to the model: 1 to 3. */
+  attempts: number;
+  /** The tokens of all the calls. */
+  usage: LlmUsage;
+  /** The keywords of the schema that the check does not examine, or examines only in part. */
+  unchecked: string[];
+}