@spendgraph/llms 0.2.0

package/dist/adapters/openai.js

@@ -0,0 +1,71 @@
+import { pricingId } from "../model.js";
+import { count, parseArgs, reply, setUsage } from "../usage.js";
+function usageOf(raw) {
+    const details = raw?.prompt_tokens_details;
+    return {
+        inputTokens: count(raw?.prompt_tokens),
+        outputTokens: count(raw?.completion_tokens),
+        cacheReadTokens: count(details?.cached_tokens),
+        cacheWriteTokens: count(details?.cache_creation_tokens),
+        citationTokens: 0,
+        reasoningTokens: 0,
+    };
+}
+function toolCallsOf(calls) {
+    return (calls ?? []).map((c) => ({
+        id: c.id ?? "",
+        name: c.function?.name ?? "",
+        args: parseArgs(c.function?.arguments),
+    }));
+}
+export const openai = {
+    provider: "openai",
+    detect(value) {
+        const raw = value;
+        return Boolean(raw &&
+            Array.isArray(raw.choices) &&
+            raw.choices.every((c) => "message" in c || "delta" in c || "finish_reason" in c));
+    },
+    read(value, opts = {}) {
+        const raw = value;
+        const choice = raw.choices?.[0];
+        const refused = choice?.finish_reason === "content_filter";
+        return reply({
+            output: choice?.message?.content ?? "",
+            model: opts.model ?? pricingId(opts.provider ?? "openai", raw.model ?? ""),
+            usage: usageOf(raw.usage),
+            toolCalls: toolCallsOf(choice?.message?.tool_calls),
+            stopReason: choice?.finish_reason ?? undefined,
+            status: refused ? "failed" : "completed",
+            error: refused ? "declined by a content filter" : undefined,
+        });
+    },
+    chunk(event, state) {
+        const raw = event;
+        if (raw.model)
+            state.model = raw.model;
+        if (raw.usage)
+            setUsage(state.usage, usageOf(raw.usage));
+        const choice = raw.choices?.[0];
+        if (!choice)
+            return "";
+        if (choice.finish_reason)
+            state.stopReason = choice.finish_reason;
+        for (const call of choice.delta?.tool_calls ?? []) {
+            const key = String(call.index ?? call.id ?? state.tools.size);
+            const pending = state.tools.get(key) ?? { id: "", name: "", json: "" };
+            if (call.id)
+                pending.id = call.id;
+            if (call.function?.name)
+                pending.name = call.function.name;
+            if (call.function?.arguments)
+                pending.json += call.function.arguments;
+            state.tools.set(key, pending);
+        }
+        const text = choice.delta?.content;
+        if (typeof text !== "string" || !text)
+            return "";
+        state.text += text;
+        return text;
+    },
+};

package/dist/adapters/perplexity.d.ts

@@ -0,0 +1,2 @@
+import type { Adapter } from "../types.js";
+export declare const perplexity: Adapter;

package/dist/adapters/perplexity.js

@@ -0,0 +1,92 @@
+import { pricingId } from "../model.js";
+import { count, parseArgs, reply, setUsage } from "../usage.js";
+function usageOf(raw) {
+    return {
+        inputTokens: count(raw?.prompt_tokens),
+        outputTokens: count(raw?.completion_tokens),
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        citationTokens: count(raw?.citation_tokens),
+        reasoningTokens: count(raw?.reasoning_tokens),
+    };
+}
+function citationsOf(raw) {
+    const urls = [];
+    for (const result of raw.search_results ?? []) {
+        if (typeof result.url === "string" && result.url)
+            urls.push(result.url);
+    }
+    if (urls.length)
+        return urls;
+    for (const url of raw.citations ?? []) {
+        if (typeof url === "string" && url)
+            urls.push(url);
+    }
+    return urls;
+}
+function toolCallsOf(calls) {
+    const parsed = [];
+    for (const call of calls ?? []) {
+        parsed.push({
+            id: call.id ?? "",
+            name: call.function?.name ?? "",
+            args: parseArgs(call.function?.arguments),
+        });
+    }
+    return parsed;
+}
+export const perplexity = {
+    provider: "perplexity",
+    detect(value) {
+        const raw = value;
+        if (!raw || !Array.isArray(raw.choices))
+            return false;
+        return Array.isArray(raw.search_results) || Array.isArray(raw.citations);
+    },
+    read(value, opts = {}) {
+        const raw = value;
+        const choice = raw.choices?.[0];
+        const refused = choice?.finish_reason === "content_filter";
+        return reply({
+            output: choice?.message?.content ?? "",
+            model: opts.model ?? pricingId(opts.provider ?? "perplexity", raw.model ?? ""),
+            usage: usageOf(raw.usage),
+            toolCalls: toolCallsOf(choice?.message?.tool_calls),
+            citations: citationsOf(raw),
+            stopReason: choice?.finish_reason ?? undefined,
+            status: refused ? "failed" : "completed",
+            error: refused ? "declined by a content filter" : undefined,
+        });
+    },
+    chunk(event, state) {
+        const raw = event;
+        if (raw.model)
+            state.model = raw.model;
+        if (raw.usage)
+            setUsage(state.usage, usageOf(raw.usage));
+        const found = citationsOf(raw);
+        if (found.length)
+            state.citations = found;
+        const choice = raw.choices?.[0];
+        if (!choice)
+            return "";
+        if (choice.finish_reason)
+            state.stopReason = choice.finish_reason;
+        for (const call of choice.delta?.tool_calls ?? []) {
+            const key = String(call.index ?? call.id ?? state.tools.size);
+            const pending = state.tools.get(key) ?? { id: "", name: "", json: "" };
+            if (call.id)
+                pending.id = call.id;
+            if (call.function?.name)
+                pending.name = call.function.name;
+            if (call.function?.arguments)
+                pending.json += call.function.arguments;
+            state.tools.set(key, pending);
+        }
+        const text = choice.delta?.content;
+        if (typeof text !== "string" || !text)
+            return "";
+        state.text += text;
+        return text;
+    },
+};

package/dist/adapters/responses.d.ts

@@ -0,0 +1,2 @@
+import type { Adapter } from "../types.js";
+export declare const responses: Adapter;

package/dist/adapters/responses.js

@@ -0,0 +1,100 @@
+import { pricingId } from "../model.js";
+import { count, parseArgs, reply, setUsage } from "../usage.js";
+function usageOf(raw) {
+    const input = raw?.input_tokens_details;
+    return {
+        inputTokens: count(raw?.input_tokens),
+        outputTokens: count(raw?.output_tokens),
+        cacheReadTokens: count(input?.cached_tokens),
+        cacheWriteTokens: 0,
+        citationTokens: 0,
+        reasoningTokens: 0,
+    };
+}
+function textOf(raw) {
+    if (typeof raw.output_text === "string")
+        return raw.output_text;
+    let text = "";
+    for (const item of raw.output ?? []) {
+        if (item.type !== "message")
+            continue;
+        for (const part of item.content ?? []) {
+            if (part.type === "output_text" && typeof part.text === "string")
+                text += part.text;
+        }
+    }
+    return text;
+}
+function toolCallsOf(raw) {
+    const calls = [];
+    for (const item of raw.output ?? []) {
+        if (item.type !== "function_call")
+            continue;
+        calls.push({
+            id: item.call_id ?? item.id ?? "",
+            name: item.name ?? "",
+            args: parseArgs(item.arguments),
+        });
+    }
+    return calls;
+}
+export const responses = {
+    provider: "openai",
+    detect(value) {
+        const raw = value;
+        if (!raw)
+            return false;
+        if (raw.object === "response")
+            return true;
+        return Array.isArray(raw.output) && typeof raw.status === "string";
+    },
+    read(value, opts = {}) {
+        const raw = value;
+        const failed = raw.status === "failed" || raw.status === "incomplete";
+        return reply({
+            output: textOf(raw),
+            model: opts.model ?? pricingId(opts.provider ?? "openai", raw.model ?? ""),
+            usage: usageOf(raw.usage),
+            toolCalls: toolCallsOf(raw),
+            stopReason: raw.status,
+            status: failed ? "failed" : "completed",
+            error: failed ? (raw.incomplete_details?.reason ?? raw.status) : undefined,
+        });
+    },
+    chunk(event, state) {
+        const e = event;
+        switch (e.type) {
+            case "response.created":
+            case "response.in_progress":
+                state.model = e.response?.model ?? state.model;
+                return "";
+            case "response.output_text.delta": {
+                const text = typeof e.delta === "string" ? e.delta : "";
+                state.text += text;
+                return text;
+            }
+            case "response.output_item.done": {
+                const item = e.item;
+                if (item?.type !== "function_call")
+                    return "";
+                state.tools.set(item.call_id ?? item.id ?? String(state.tools.size), {
+                    id: item.call_id ?? item.id ?? "",
+                    name: item.name ?? "",
+                    json: item.arguments ?? "",
+                });
+                return "";
+            }
+            case "response.completed":
+            case "response.incomplete":
+            case "response.failed": {
+                const done = e.response;
+                state.model = done?.model ?? state.model;
+                state.stopReason = done?.status ?? state.stopReason;
+                setUsage(state.usage, usageOf(done?.usage));
+                return "";
+            }
+            default:
+                return "";
+        }
+    },
+};

package/dist/affordable.d.ts

@@ -0,0 +1,44 @@
+export interface AffordableOptions {
+    /**
+     * Refuse to retry below this ceiling. Default 0, which accepts any positive one.
+     *
+     * Worth setting where the reply is a forced tool call: a schema truncated
+     * mid-arguments parses to nothing, which is a worse answer than the refusal it
+     * replaced. A caller that would rather fail than be cut off says so here.
+     */
+    floor?: number;
+    /** Attempts after the first. Default 1. */
+    retries?: number;
+    /** Recognises the refusal and says what is affordable. Replaces the built-in reading. */
+    reads?: (err: unknown) => number | undefined;
+}
+/**
+ * What a provider says it can afford, read off a refusal.
+ *
+ * `402` alone is not enough to act on — it is also what an empty account
+ * returns, and shrinking a ceiling will not fix that. The number is the signal:
+ * a provider that names one is telling you the request would have been accepted
+ * smaller.
+ */
+export declare function affordableCeiling(err: unknown): number | undefined;
+/**
+ * A provider client that lowers its ceiling rather than failing over it.
+ *
+ * `max_tokens` is a request for headroom, not a bill — output is charged on what
+ * is written. A provider that reserves the ceiling against a prepaid balance
+ * refuses the whole call over headroom that was never going to be used:
+ *
+ * ```
+ * 402 You requested up to 4096 tokens, but can only afford 4000.
+ * ```
+ *
+ * This retries that once at the number the provider named. It is a decorator
+ * rather than something inside `Llm` because how a client copes with a
+ * provider's billing is the client's business, and because it then works for
+ * every shape — the wrapper mirrors whatever it is given, so `driverFor` still
+ * recognises an Anthropic, OpenAI or Gemini client through it.
+ *
+ * A `402` that names no number is passed through untouched. That one is an
+ * empty account, and no ceiling will fix it.
+ */
+export declare function affordable<T>(client: T, opts?: AffordableOptions): T;

package/dist/affordable.js

@@ -0,0 +1,87 @@
+/** Every field a provider carries the output ceiling in. */
+const CEILINGS = ["max_tokens", "max_completion_tokens", "maxOutputTokens"];
+const AFFORDS = /can only afford\s+(\d[\d,]*)/i;
+/**
+ * What a provider says it can afford, read off a refusal.
+ *
+ * `402` alone is not enough to act on — it is also what an empty account
+ * returns, and shrinking a ceiling will not fix that. The number is the signal:
+ * a provider that names one is telling you the request would have been accepted
+ * smaller.
+ */
+export function affordableCeiling(err) {
+    const status = err?.status;
+    const message = err instanceof Error ? err.message : String(err ?? "");
+    if (status !== 402 && !/\b402\b/.test(message))
+        return undefined;
+    const found = AFFORDS.exec(message);
+    return found ? Number(found[1].replace(/,/g, "")) : undefined;
+}
+function shrink(body, to) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return undefined;
+    const source = body;
+    for (const key of CEILINGS) {
+        const current = source[key];
+        if (typeof current === "number" && to < current)
+            return { ...source, [key]: to };
+    }
+    for (const [key, value] of Object.entries(source)) {
+        const nested = value && typeof value === "object" ? shrink(value, to) : undefined;
+        if (nested)
+            return { ...source, [key]: nested };
+    }
+    return undefined;
+}
+/**
+ * A provider client that lowers its ceiling rather than failing over it.
+ *
+ * `max_tokens` is a request for headroom, not a bill — output is charged on what
+ * is written. A provider that reserves the ceiling against a prepaid balance
+ * refuses the whole call over headroom that was never going to be used:
+ *
+ * ```
+ * 402 You requested up to 4096 tokens, but can only afford 4000.
+ * ```
+ *
+ * This retries that once at the number the provider named. It is a decorator
+ * rather than something inside `Llm` because how a client copes with a
+ * provider's billing is the client's business, and because it then works for
+ * every shape — the wrapper mirrors whatever it is given, so `driverFor` still
+ * recognises an Anthropic, OpenAI or Gemini client through it.
+ *
+ * A `402` that names no number is passed through untouched. That one is an
+ * empty account, and no ceiling will fix it.
+ */
+export function affordable(client, opts = {}) {
+    const floor = opts.floor ?? 0;
+    const retries = opts.retries ?? 1;
+    const reads = opts.reads ?? affordableCeiling;
+    const call = async (fn, owner, args) => {
+        let attempt = 0;
+        let current = args;
+        for (;;) {
+            try {
+                return await fn.apply(owner, current);
+            }
+            catch (err) {
+                const to = reads(err);
+                const smaller = to === undefined ? undefined : shrink(current[0], to);
+                if (attempt >= retries || to === undefined || to < floor || !smaller)
+                    throw err;
+                current = [smaller, ...current.slice(1)];
+                attempt++;
+            }
+        }
+    };
+    const wrap = (target) => new Proxy(target, {
+        get(node, prop) {
+            const value = Reflect.get(node, prop);
+            if (typeof value === "function") {
+                return (...args) => call(value, node, args);
+            }
+            return value && typeof value === "object" ? wrap(value) : value;
+        },
+    });
+    return wrap(client);
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { affordable, affordableCeiling, type AffordableOptions } from "./affordable.js";
+export type { Shape } from "./adapters/index.js";
+export type { CallOptions, LlmOptions, ToolBus, ToolResult, } from "./llm/index.js";
+export { Llm, UnsupportedClientError } from "./llm/index.js";
+export type { JsonSchema, StructuredOutput } from "./llm/schema/index.js";
+export { StructuredOutputError } from "./llm/schema/index.js";
+export { read, UnknownReplyError } from "./read.js";
+export type { Ingest, SpendgraphOptions, Tag, UsageEvent, } from "./report/index.js";
+export { MissingCredentialsError } from "./report/index.js";
+export { anthropicMessages, geminiMessages, openaiMessages, } from "./request.js";
+export type { LlmStream, StreamOptions } from "./stream.js";
+export { collect, stream } from "./stream.js";
+export type { CallOutcome, LlmReply, LlmToolCall, LlmUsage, PromptMessage, Provider, ReadOptions, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { affordable, affordableCeiling } from "./affordable.js";
+export { Llm, UnsupportedClientError } from "./llm/index.js";
+export { StructuredOutputError } from "./llm/schema/index.js";
+export { read, UnknownReplyError } from "./read.js";
+export { MissingCredentialsError } from "./report/index.js";
+export { anthropicMessages, geminiMessages, openaiMessages, } from "./request.js";
+export { collect, stream } from "./stream.js";

package/dist/llm/drivers.d.ts

@@ -0,0 +1,36 @@
+import type { Shape } from "../adapters/index.js";
+import type { LlmToolCall, PromptMessage } from "../types.js";
+import { type StructuredOutput } from "./schema/index.js";
+import type { ToolBus, ToolResult } from "./types.js";
+export interface Conversation {
+    system?: unknown;
+    messages: unknown[];
+}
+export interface Body {
+    model: string;
+    maxTokens?: number;
+    tools?: unknown[];
+    /** A shape the reply must take. Sent the way each provider wants it. */
+    structured?: StructuredOutput;
+    params: Record<string, unknown>;
+}
+export interface Completed {
+    call: LlmToolCall;
+    result: ToolResult;
+}
+export interface Driver {
+    shape: Shape;
+    supportsTools: boolean;
+    detect(client: unknown): boolean;
+    start(messages: PromptMessage[]): Conversation;
+    create(client: unknown, convo: Conversation, body: Body): Promise<unknown>;
+    stream(client: unknown, convo: Conversation, body: Body): Promise<AsyncIterable<unknown>>;
+    declarations(tools: ToolBus): unknown[];
+    pushReply(convo: Conversation, raw: unknown): void;
+    pushResults(convo: Conversation, done: Completed[]): void;
+}
+export declare const anthropicDriver: Driver;
+export declare const openaiDriver: Driver;
+export declare const geminiDriver: Driver;
+export declare const DRIVERS: Driver[];
+export declare function driverFor(client: unknown): Driver | undefined;

package/dist/llm/drivers.js

@@ -0,0 +1,121 @@
+import { anthropicMessages, geminiMessages, openaiMessages } from "../request.js";
+import { has, invoke } from "./invoke.js";
+import { anthropicStructured, geminiStructured, openaiStructured, } from "./schema/index.js";
+const answer = (result) => result.output || result.error || "";
+function anthropicBody(convo, body) {
+    return {
+        model: body.model,
+        max_tokens: body.maxTokens ?? 16_000,
+        ...(convo.system ? { system: convo.system } : {}),
+        messages: convo.messages,
+        ...(body.tools?.length ? { tools: body.tools } : {}),
+        ...(body.structured ? anthropicStructured(body.structured) : {}),
+        ...body.params,
+    };
+}
+export const anthropicDriver = {
+    shape: "anthropic",
+    supportsTools: true,
+    detect: (client) => has(client, ["messages", "create"]),
+    start(messages) {
+        const { system, messages: turns } = anthropicMessages(messages);
+        return { system, messages: turns };
+    },
+    create: (client, convo, body) => invoke(client, ["messages", "create"], anthropicBody(convo, body)),
+    stream: (client, convo, body) => invoke(client, ["messages", "stream"], anthropicBody(convo, body)),
+    declarations: (tools) => tools.anthropic(),
+    pushReply(convo, raw) {
+        const { content } = (raw ?? {});
+        convo.messages.push({ role: "assistant", content });
+    },
+    pushResults(convo, done) {
+        convo.messages.push({
+            role: "user",
+            content: done.map(({ call, result }) => ({
+                type: "tool_result",
+                tool_use_id: call.id,
+                content: answer(result),
+                is_error: result.status === "failed",
+            })),
+        });
+    },
+};
+function openaiBody(convo, body) {
+    return {
+        model: body.model,
+        messages: convo.messages,
+        ...(body.maxTokens ? { max_completion_tokens: body.maxTokens } : {}),
+        ...(body.tools?.length ? { tools: body.tools } : {}),
+        ...(body.structured ? openaiStructured(body.structured) : {}),
+        ...body.params,
+    };
+}
+export const openaiDriver = {
+    shape: "openai",
+    supportsTools: true,
+    detect: (client) => has(client, ["chat", "completions", "create"]),
+    start: (messages) => ({ messages: openaiMessages(messages).messages }),
+    create: (client, convo, body) => invoke(client, ["chat", "completions", "create"], openaiBody(convo, body)),
+    stream: (client, convo, body) => invoke(client, ["chat", "completions", "create"], {
+        ...openaiBody(convo, body),
+        stream: true,
+        stream_options: { include_usage: true },
+    }),
+    declarations: (tools) => tools.openai(),
+    pushReply(convo, raw) {
+        const { choices } = (raw ?? {});
+        const message = choices?.[0]?.message;
+        if (message)
+            convo.messages.push(message);
+    },
+    pushResults(convo, done) {
+        for (const { call, result } of done) {
+            convo.messages.push({
+                role: "tool",
+                tool_call_id: call.id,
+                content: answer(result),
+            });
+        }
+    },
+};
+function geminiBody(convo, body) {
+    const { generationConfig, ...rest } = body.params;
+    const structured = body.structured ? geminiStructured(body.structured) : {};
+    const config = body.maxTokens || body.structured
+        ? {
+            ...(body.maxTokens ? { maxOutputTokens: body.maxTokens } : {}),
+            ...structured,
+            ...generationConfig,
+        }
+        : generationConfig;
+    return {
+        model: body.model,
+        contents: convo.messages,
+        ...(convo.system ? { systemInstruction: convo.system } : {}),
+        ...rest,
+        ...(config ? { generationConfig: config } : {}),
+    };
+}
+export const geminiDriver = {
+    shape: "gemini",
+    supportsTools: false,
+    detect: (client) => has(client, ["models", "generateContent"]),
+    start(messages) {
+        const { systemInstruction, contents } = geminiMessages(messages);
+        return { system: systemInstruction, messages: contents };
+    },
+    create: (client, convo, body) => invoke(client, ["models", "generateContent"], geminiBody(convo, body)),
+    stream: (client, convo, body) => invoke(client, ["models", "generateContentStream"], geminiBody(convo, body)),
+    declarations: () => [],
+    pushReply(convo, raw) {
+        const { candidates } = (raw ?? {});
+        convo.messages.push(candidates?.[0]?.content ?? { role: "model", parts: [] });
+    },
+    pushResults() {
+        throw new Error("Llm does not drive Gemini tool loops. Use read() and drive it yourself.");
+    },
+};
+export const DRIVERS = [anthropicDriver, openaiDriver, geminiDriver];
+export function driverFor(client) {
+    return DRIVERS.find((driver) => driver.detect(client));
+}

package/dist/llm/index.d.ts

@@ -0,0 +1,2 @@
+export { Llm, UnsupportedClientError } from "./llm.js";
+export type { CallDefaults, CallOptions, LlmOptions, ToolBus, ToolResult, } from "./types.js";

package/dist/llm/index.js

@@ -0,0 +1 @@
+export { Llm, UnsupportedClientError } from "./llm.js";

package/dist/llm/invoke.d.ts

@@ -0,0 +1,3 @@
+export declare function has(client: unknown, path: string[]): boolean;
+/** Calls `client.a.b.c(body)` with `client.a.b` as the receiver. */
+export declare function invoke(client: unknown, path: string[], body: Record<string, unknown>): Promise<unknown>;

package/dist/llm/invoke.js

@@ -0,0 +1,24 @@
+function walk(client, keys) {
+    let node = client;
+    for (let i = 0; i < keys.length - 1; i++) {
+        if (!node || typeof node !== "object")
+            return undefined;
+        node = node[keys[i]];
+    }
+    if (!node || typeof node !== "object")
+        return undefined;
+    const owner = node;
+    return { owner, fn: owner[keys[keys.length - 1]] };
+}
+export function has(client, path) {
+    return typeof walk(client, path)?.fn === "function";
+}
+/** Calls `client.a.b.c(body)` with `client.a.b` as the receiver. */
+export async function invoke(client, path, body) {
+    const found = walk(client, path);
+    if (typeof found?.fn !== "function") {
+        throw new TypeError(`This client has no ${path.join(".")}().`);
+    }
+    const call = found.fn;
+    return call.call(found.owner, body);
+}

package/dist/llm/llm.d.ts

@@ -0,0 +1,50 @@
+import type { LlmReply, PromptMessage } from "../types.js";
+import type { CallOptions, LlmOptions } from "./types.js";
+export declare class UnsupportedClientError extends Error {
+    constructor();
+}
+/**
+ * A provider client and its defaults. Calls the model, normalises the reply,
+ * and records what it consumed.
+ */
+export declare class Llm {
+    private readonly opts;
+    private readonly driver;
+    private readonly ingest?;
+    constructor(opts: LlmOptions);
+    get provider(): string;
+    get model(): string;
+    /** The same client with different defaults — another model, tools, no tracing. */
+    with(overrides: Partial<LlmOptions>): Llm;
+    /** Calls the model, looping over tools when a bus is attached. */
+    call(messages: PromptMessage[], opts?: CallOptions): Promise<LlmReply>;
+    /**
+     * The call, then each fallback model in turn.
+     *
+     * The last error is thrown rather than the first: a caller reading the stack
+     * wants to know how it finished, and the first failure is the one that is
+     * already in the `onFallback` log.
+     */
+    private attempt;
+    /** The same, streamed. `onText` receives each delta as it arrives. */
+    stream(messages: PromptMessage[], opts?: CallOptions): Promise<LlmReply>;
+    private once;
+    private loop;
+    private record;
+    private settings;
+    private body;
+    /**
+     * Attaches the object a `schema` asked for.
+     *
+     * Anthropic answers a forced tool call, so the value is already parsed in the
+     * call's arguments; the JSON modes answer as text. A reply that satisfies
+     * neither throws rather than coming back with `data` quietly missing.
+     *
+     * A forced call leaves no text block, so `output` is filled from the object:
+     * it is what a recorded rollout stores as the reply, and blank there reads as
+     * a model that said nothing.
+     */
+    private withData;
+    private read;
+    private adapterFor;
+}