@procedures/llm 0.4.0 → 0.5.0

package/dist/tools.js

@@ -0,0 +1,162 @@
+/**
+ * Procedures as tools of the model (`llm.complete` with `procedures`).
+ *
+ * The caller names the procedures. `llm.complete` gives the model a tool for each one. The name
+ * is the key with `_` in place of each `.`. The description and the input schema come from the
+ * procedure. When the model asks for a tool, `llm.complete` calls the procedure through
+ * `ctx.client` with the input of the model. The output goes back as a `tool_result`.
+ *
+ * The procedure `llm.complete` is data-driven (`markDataDriven`): its input chooses its callees.
+ * Thus the admission of the host examines each nested call: its capability and its expose rule.
+ * Before the first request, the same rules examine each named procedure, so a refused tool costs
+ * no request.
+ */
+import { capabilityRefusal, InvocationError, jsonSchemaOf, PROCEDURE_REGISTRY, } from "@procedures/client";
+import { LlmError } from "./errors.js";
+import { deadlineLeft } from "./retry.js";
+/** The default of `maxRounds`: the most requests to the model in one call of `llm.complete`. */
+export const DEFAULT_MAX_ROUNDS = 8;
+/** The most characters of the output of a tool that the model gets. */
+export const MAX_TOOL_RESULT_CHARS = 200_000;
+/** The names that the API accepts for a tool. */
+const TOOL_NAME = /^[a-zA-Z0-9_-]{1,128}$/;
+/** The reasons of a refusal of the capability. Such a refusal stops the call: the model cannot change it. */
+const CAPABILITY_REASONS = new Set(["effects-undeclared", "effects-exceeded", "clearance", "deadline"]);
+/** The codes of a refusal of the host. Such a refusal stops the call. */
+const HOST_REFUSALS = new Set(["NOT_EXPOSED", "NOT_DECLARED", "NOT_FOUND", "NO_HANDLER"]);
+/** The name of the tool of a procedure: the key with `_` in place of each `.`. */
+export function toolNameOf(key) {
+    return key.split(".").join("_");
+}
+/** The input schema of a procedure as a tool: an object schema, or a `BAD_TOOL` error. */
+function inputSchemaOf(procedure, key) {
+    const schema = jsonSchemaOf(procedure.input);
+    if (schema === undefined || Object.keys(schema).length === 0)
+        return { type: "object" };
+    if (schema["type"] === "object")
+        return schema;
+    throw new LlmError("BAD_TOOL", `llm: the input of ${key} is not an object, so the model cannot use it as a tool`);
+}
+/**
+ * This function gives the tools of the procedures that the input names. It throws before a
+ * request goes out. It throws for a refusal of the expose rule or of the capability. It also
+ * throws for a procedure that is not in the registry, and for a stream without an end.
+ */
+export function procedureTools(keys, ctx, caller) {
+    if (keys.length === 0)
+        return [];
+    if (ctx?.client === undefined)
+        throw new LlmError("BAD_TOOL", `${caller.join(".")}: procedure tools need the context of a procedure call`);
+    const registry = ctx.registry ?? PROCEDURE_REGISTRY;
+    const seen = new Set();
+    return keys.map((key) => {
+        if (seen.has(key))
+            throw new LlmError("BAD_TOOL", `llm: the input names the procedure ${key} two times`);
+        seen.add(key);
+        const path = key.split(".");
+        // The expose rule first: a refused path tells nothing about the procedure
+        if (ctx.expose !== undefined && !ctx.expose(path)) {
+            throw new InvocationError("NOT_EXPOSED", `Procedure not exposed: ${key}. ${caller.join(".")} runs the procedures that its input names, so it can call only the procedures that this host exposes.`, path);
+        }
+        const procedure = registry.get(path);
+        if (procedure === undefined)
+            throw new InvocationError("NOT_FOUND", `No procedure at ${key}`, path);
+        if (procedure.handler === undefined)
+            throw new InvocationError("NO_HANDLER", `The procedure ${key} has no handler`, path);
+        const refusal = capabilityRefusal(procedure, ctx.capability);
+        if (refusal?.reason === "deadline")
+            throw new InvocationError("TIMEOUT", refusal.message, path);
+        if (refusal)
+            throw new InvocationError("FORBIDDEN", `${refusal.message}, so the model cannot use it as a tool`, path, refusal.reason);
+        if (procedure.metadata?.stream?.unbounded === true) {
+            throw new LlmError("BAD_TOOL", `llm: ${key} is a stream without an end, so the model cannot use it as a tool`);
+        }
+        const name = toolNameOf(key);
+        if (!TOOL_NAME.test(name))
+            throw new LlmError("BAD_TOOL", `llm: the tool name ${name} of ${key} has characters that the API refuses`);
+        const description = procedure.metadata?.description;
+        return {
+            key,
+            path,
+            param: {
+                name,
+                description: typeof description === "string" && description !== "" ? description : `The procedure ${key}`,
+                input_schema: inputSchemaOf(procedure, key),
+            },
+        };
+    });
+}
+/** The `tool_use` blocks of the content of an answer. */
+export function toolUsesOf(content) {
+    const uses = [];
+    for (const block of content) {
+        if (block.type === "tool_use" && typeof block["id"] === "string" && typeof block["name"] === "string") {
+            uses.push({ id: block["id"], name: block["name"], input: block["input"] ?? {} });
+        }
+    }
+    return uses;
+}
+/**
+ * This function is true when an error of a nested call stops the whole call. The causes are a
+ * refusal of the host, the abort of the caller and the deadline. The model gets each other error.
+ */
+function stopsTheCall(error, ctx) {
+    if (!(error instanceof InvocationError))
+        return false;
+    if (HOST_REFUSALS.has(error.code))
+        return true;
+    if (error.code === "FORBIDDEN")
+        return error.reason !== undefined && CAPABILITY_REASONS.has(error.reason);
+    if (error.code === "ABORTED")
+        return ctx.signal?.aborted === true;
+    if (error.code === "TIMEOUT") {
+        const left = deadlineLeft(ctx);
+        return left !== undefined && left <= 0;
+    }
+    return false;
+}
+/** The output of a tool as the text of its `tool_result`, at most `MAX_TOOL_RESULT_CHARS` characters. */
+function resultText(output) {
+    let text;
+    if (typeof output === "string") {
+        text = output;
+    }
+    else {
+        try {
+            text = JSON.stringify(output) ?? "null";
+        }
+        catch {
+            text = String(output);
+        }
+    }
+    if (text.length <= MAX_TOOL_RESULT_CHARS)
+        return text;
+    return `${text.slice(0, MAX_TOOL_RESULT_CHARS)}\n[llm: the output has ${text.length} characters, and this result has the first ${MAX_TOOL_RESULT_CHARS}]`;
+}
+/**
+ * This function runs one `tool_use` block with the procedure of its tool, through `ctx.client`.
+ * It gives the record of the call and the `tool_result` block. An error of the procedure goes to
+ * the model with `is_error: true`. A refusal of the host, the abort and the deadline stop the call.
+ */
+export async function runToolUse(use, tool, ctx) {
+    const base = { id: use.id, name: use.name, procedure: tool.key, input: use.input };
+    try {
+        const output = await ctx.client.call(tool.path, use.input);
+        return {
+            call: { ...base, isError: false, output },
+            result: { type: "tool_result", tool_use_id: use.id, content: resultText(output) },
+        };
+    }
+    catch (error) {
+        if (stopsTheCall(error, ctx))
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        const code = error?.code;
+        const content = typeof code === "string" ? `${code}: ${message}` : message;
+        return {
+            call: { ...base, isError: true, error: content },
+            result: { type: "tool_result", tool_use_id: use.id, content: resultText(content), is_error: true },
+        };
+    }
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/dist/types.d.ts

@@ -31,7 +31,7 @@ export interface LlmRequestInput {
     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). */
+    /** The time limit of each request to the API, 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
@@ -39,15 +39,97 @@ export interface LlmRequestInput {
      */
     fallback?: boolean | undefined;
 }
-export type LlmCompleteInput = LlmRequestInput;
+/** A tool that the model can use: the API gets its name, its description and the schema of its input. */
+export interface LlmTool {
+    /** The name of the tool: 1 to 128 letters, digits, `_` and `-`. */
+    name: string;
+    /** The text that tells the model what the tool does and when to use it. */
+    description?: string | undefined;
+    /** The JSON Schema of the input of the tool. Its type is `object`. */
+    inputSchema: Record<string, unknown>;
+    /** True: the API makes the input of each call agree with the schema (strict tool use). */
+    strict?: boolean | undefined;
+}
+/**
+ * How the model uses the tools. `auto` (the default): the model decides. `any`: the model uses a
+ * tool. `tool`: the model uses the tool that `name` gives. `none`: the model uses no tool.
+ * Some models refuse `any` and `tool` with a 400 error: Claude Sonnet 5.5, Claude Opus 5.5 and
+ * Claude Fable 5.1.
+ */
+export type LlmToolChoice = {
+    type: "auto";
+    disableParallelToolUse?: boolean | undefined;
+} | {
+    type: "any";
+    disableParallelToolUse?: boolean | undefined;
+} | {
+    type: "tool";
+    name: string;
+    disableParallelToolUse?: boolean | undefined;
+} | {
+    type: "none";
+};
+/** The tool fields of `llm.complete` and `llm.stream`. */
+export interface LlmToolInput {
+    /** The tools that the model can use. The caller runs them: the output gives each `tool_use` block. */
+    tools?: LlmTool[] | undefined;
+    /** How the model uses the tools (`tool_choice`). */
+    toolChoice?: LlmToolChoice | undefined;
+    /** The number of new tries after an error with `retryable: true`: 0 to 10. The default is the option of the module (2). */
+    retries?: number | undefined;
+}
+/** A `tool_use` block of an answer: a call of a tool that the model asks for. */
+export interface LlmToolUse {
+    /** The ID of the block. A `tool_result` gives it back. */
+    id: string;
+    /** The name of the tool. */
+    name: string;
+    /** The input of the call. */
+    input: unknown;
+}
+/** A call of a procedure tool that `llm.complete` made for the model. */
+export interface LlmToolCall {
+    /** The ID of the `tool_use` block. */
+    id: string;
+    /** The name of the tool. */
+    name: string;
+    /** The key of the procedure, for example `weather.current`. */
+    procedure: string;
+    /** The input that the model gave. */
+    input: unknown;
+    /** True when the procedure failed. The model got the error as a `tool_result` with `is_error: true`. */
+    isError: boolean;
+    /** The output of the procedure. */
+    output?: unknown;
+    /** The message of the error of the procedure. */
+    error?: string | undefined;
+}
+export interface LlmCompleteInput extends LlmRequestInput, LlmToolInput {
+    /**
+     * The keys of the procedures that the model can use as tools, for example `weather.current`.
+     * `llm.complete` calls each one through `ctx.client`, sends the result to the model, and asks again.
+     */
+    procedures?: string[] | undefined;
+    /** The most requests to the model in one call: 1 to 64. The default is 8. */
+    maxRounds?: number | undefined;
+}
 export interface LlmCompleteOutput {
-    /** The text of the answer: the text blocks, joined. */
+    /** The text of the last answer: its 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. */
+    /** Why the model stopped: `end_turn`, `max_tokens`, `stop_sequence`, `tool_use` or another reason of the API. */
     stopReason: string;
+    /** The tokens of all the requests. */
     usage: LlmUsage;
+    /** The `tool_use` blocks of the last answer that no procedure ran. */
+    toolUses: LlmToolUse[];
+    /** The calls of procedure tools, in their sequence. */
+    toolCalls: LlmToolCall[];
+    /** The number of requests to the model. */
+    rounds: number;
+    /** True when `maxRounds` stopped the loop before the model stopped. */
+    roundLimit: boolean;
 }
 export interface LlmStructuredInput extends LlmRequestInput {
     /** The JSON Schema of the value. */
@@ -60,6 +142,8 @@ export interface LlmStructuredInput extends LlmRequestInput {
     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;
+    /** The number of new tries of a request after an error with `retryable: true`: 0 to 10. The default is the option of the module (2). */
+    requestRetries?: number | undefined;
 }
 export interface LlmStructuredOutput {
     /** The value: the schema accepts it. */
@@ -73,4 +157,54 @@ export interface LlmStructuredOutput {
     /** The keywords of the schema that the check does not examine, or examines only in part. */
     unchecked: string[];
 }
+export interface LlmStreamInput extends LlmRequestInput, LlmToolInput {
+}
+/** The first item of a stream: the event `message_start`. */
+export interface LlmStreamStart {
+    type: "start";
+    /** The ID of the message. */
+    id: string;
+    /** The model that answers. */
+    model: string;
+    /** The tokens at the start: the tokens of the input. */
+    usage: LlmUsage;
+}
+/** A part of the text of a text block: the delta `text_delta`. */
+export interface LlmStreamText {
+    type: "text";
+    /** The index of the content block. */
+    index: number;
+    /** The new text. */
+    text: string;
+}
+/** A complete `tool_use` block, after its event `content_block_stop`. */
+export interface LlmStreamToolUse {
+    type: "tool_use";
+    /** The index of the content block. */
+    index: number;
+    /** The ID of the block. */
+    id: string;
+    /** The name of the tool. */
+    name: string;
+    /** The input of the call, or null when its JSON is not complete. */
+    input: unknown;
+    /** The JSON text of an input that does not parse: for example, the output stopped at `maxTokens`. */
+    partialJson?: string | undefined;
+}
+/** The last item of a stream: the event `message_stop`, with the stop reason and the usage. */
+export interface LlmStreamStop {
+    type: "stop";
+    /** The model that answered. After a fallback, it is the fallback model. */
+    model: string;
+    /** Why the model stopped. */
+    stopReason: string;
+    /** The tokens of the call. */
+    usage: LlmUsage;
+    /** The text of the answer: all the text deltas, joined. */
+    text: string;
+    /** The `tool_use` blocks of the answer. */
+    toolUses: LlmToolUse[];
+}
+/** One item of `llm.stream`. */
+export type LlmStreamOutput = LlmStreamStart | LlmStreamText | LlmStreamToolUse | LlmStreamStop;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC;AAEpE,4BAA4B;AAC5B,MAAM,WAAW,QAAQ;IACvB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,wDAAwD;IACxD,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAED,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,4GAA4G;IAC5G,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,uEAAuE;IACvE,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/B,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAMD,MAAM,MAAM,gBAAgB,GAAG,eAAe,CAAC;AAE/C,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,qGAAqG;IACrG,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,QAAQ,CAAC;CACjB;AAMD,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAClC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,KAAK,EAAE,OAAO,CAAC;IACf,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,KAAK,EAAE,QAAQ,CAAC;IAChB,4FAA4F;IAC5F,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,15 +1,17 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/llm",
-  "version": "0.4.0",
-  "description": "A language model as procedures: a completion and a structured answer that a JSON Schema accepts, through the Anthropic Messages API, with the key from the environment.",
+  "version": "0.5.0",
+  "description": "A language model as procedures: a completion with tools, a stream of the answer and a structured answer, through the Anthropic Messages API, with the key from the environment.",
   "keywords": [
     "procedures",
     "llm",
     "anthropic",
     "claude",
     "structured-output",
-    "json-schema"
+    "json-schema",
+    "streaming",
+    "tool-use"
   ],
   "homepage": "https://mark1russell7.github.io/client/",
   "bugs": {
@@ -62,8 +64,10 @@
     "procedures": "./dist/register.js"
   },
   "dependencies": {
-    "@procedures/client": "0.4.0",
-    "@procedures/json": "0.4.0",
+    "@mark1russell7/service": "^0.4.1",
+    "@procedures/client": "0.5.0",
+    "@procedures/http": "0.5.0",
+    "@procedures/json": "0.5.0",
     "zod": "^4.6.5"
   },
   "publishConfig": {