@spendgraph/llms 0.2.0

package/dist/llm/llm.js

@@ -0,0 +1,238 @@
+import { adapterFor as adapterForProvider, adapterOfShape } from "../adapters/index.js";
+import { pricingId } from "../model.js";
+import { ingestFor, newEventId } from "../report/index.js";
+import { collect } from "../stream.js";
+import { addUsage, reply as build, emptyUsage } from "../usage.js";
+import { driverFor } from "./drivers.js";
+import { readStructured } from "./schema/index.js";
+export class UnsupportedClientError extends Error {
+    constructor() {
+        super("Could not tell how to call this client. Llm drives the Anthropic, OpenAI chat completions and Gemini SDKs; for anything else use read() or stream().");
+        this.name = "UnsupportedClientError";
+    }
+}
+const DEFAULT_MAX_STEPS = 8;
+/**
+ * Worth trying another model for.
+ *
+ * Overload, rate limit and server fault are about the provider's day. A 400 or
+ * a 401 is about the request, and is the same answer everywhere — retrying it
+ * across three models spends three round trips to be told so three times.
+ */
+function worthAnotherModel(err) {
+    const status = err?.status;
+    if (typeof status !== "number")
+        return true;
+    return status === 429 || status === 529 || status >= 500;
+}
+let warnedAboutTokens = false;
+function warnOnEmptyUsage(reply) {
+    if (warnedAboutTokens || reply.status === "failed")
+        return;
+    if ((reply.inputTokens ?? 0) > 0 || (reply.outputTokens ?? 0) > 0)
+        return;
+    warnedAboutTokens = true;
+    console.warn("[llms] recorded a call with no tokens, which prices as nothing. The provider " +
+        "reported no usage — on a stream, ask for it (OpenAI needs stream_options.include_usage).");
+}
+/** A bare schema is shorthand for `{ schema }`. */
+function asStructured(schema) {
+    if (!schema)
+        return undefined;
+    return "schema" in schema ? schema : { schema };
+}
+/**
+ * A provider client and its defaults. Calls the model, normalises the reply,
+ * and records what it consumed.
+ */
+export class Llm {
+    opts;
+    driver;
+    ingest;
+    constructor(opts) {
+        this.opts = opts;
+        const driver = driverFor(opts.client);
+        if (!driver)
+            throw new UnsupportedClientError();
+        this.driver = driver;
+        this.ingest = opts.spendgraph ? ingestFor(opts.spendgraph) : undefined;
+    }
+    get provider() {
+        return this.opts.provider ?? this.driver.shape;
+    }
+    get model() {
+        return this.opts.model;
+    }
+    /** The same client with different defaults — another model, tools, no tracing. */
+    with(overrides) {
+        return new Llm({
+            ...this.opts,
+            ...overrides,
+            params: { ...this.opts.params, ...overrides.params },
+            metadata: { ...this.opts.metadata, ...overrides.metadata },
+        });
+    }
+    /** Calls the model, looping over tools when a bus is attached. */
+    async call(messages, opts = {}) {
+        const settings = this.settings(opts);
+        const reply = await this.attempt(messages, settings);
+        return this.record(this.withData(reply, settings), settings, opts);
+    }
+    /**
+     * 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.
+     */
+    async attempt(messages, settings) {
+        const models = [settings.model, ...(this.opts.fallbacks ?? [])];
+        let last;
+        for (const [index, model] of models.entries()) {
+            const attempt = { ...settings, model };
+            try {
+                return attempt.tools
+                    ? await this.loop(messages, attempt.tools, attempt)
+                    : await this.once(messages, attempt);
+            }
+            catch (err) {
+                last = err;
+                const next = models[index + 1];
+                if (!next || !worthAnotherModel(err))
+                    throw err;
+                this.opts.onFallback?.({ from: model, to: next, error: err });
+            }
+        }
+        throw last;
+    }
+    /** The same, streamed. `onText` receives each delta as it arrives. */
+    async stream(messages, opts = {}) {
+        const settings = this.settings(opts);
+        if (settings.tools) {
+            throw new Error("stream() does not drive tool loops. Use call(), or pass { tools: undefined } to stream without them.");
+        }
+        const convo = this.driver.start(messages);
+        const started = Date.now();
+        const source = await this.driver.stream(this.opts.client, convo, this.body(settings));
+        const reply = await collect(source, {
+            shape: this.driver.shape,
+            provider: this.provider,
+            onText: settings.onText,
+        });
+        return this.record({ ...reply, latencyMs: Date.now() - started }, settings, opts);
+    }
+    async once(messages, settings) {
+        const convo = this.driver.start(messages);
+        const started = Date.now();
+        const raw = await this.driver.create(this.opts.client, convo, this.body(settings));
+        return { ...this.read(raw), latencyMs: Date.now() - started };
+    }
+    async loop(messages, tools, settings) {
+        if (!this.driver.supportsTools) {
+            throw new Error(`Llm does not drive tool loops for ${this.driver.shape} clients.`);
+        }
+        const convo = this.driver.start(messages);
+        const started = Date.now();
+        const spent = emptyUsage();
+        const body = {
+            ...this.body(settings),
+            tools: this.driver.declarations(tools),
+        };
+        for (let step = 0; step < settings.maxSteps; step++) {
+            const raw = await this.driver.create(this.opts.client, convo, body);
+            const reply = this.read(raw);
+            addUsage(spent, reply.usage);
+            this.driver.pushReply(convo, raw);
+            if (reply.toolCalls.length === 0) {
+                return {
+                    ...build({ ...reply, usage: spent }),
+                    latencyMs: Date.now() - started,
+                };
+            }
+            const done = [];
+            for (const call of reply.toolCalls) {
+                done.push({ call, result: await tools.invoke(call.name, call.args) });
+            }
+            this.driver.pushResults(convo, done);
+        }
+        throw new Error(`Tool loop did not settle in ${settings.maxSteps} steps.`);
+    }
+    async record(reply, settings, opts) {
+        const target = this.opts.spendgraph;
+        if (!this.ingest || !target || settings.trace === false)
+            return reply;
+        const eventId = opts.eventId ?? newEventId();
+        warnOnEmptyUsage(reply);
+        try {
+            await this.ingest.send([
+                {
+                    eventId,
+                    model: reply.model,
+                    inputTokens: reply.inputTokens ?? 0,
+                    outputTokens: reply.outputTokens ?? 0,
+                    cacheReadTokens: reply.cacheReadTokens,
+                    cacheWriteTokens: reply.cacheWriteTokens,
+                    ...(reply.citationTokens ? { citationTokens: reply.citationTokens } : {}),
+                    ...(reply.reasoningTokens ? { reasoningTokens: reply.reasoningTokens } : {}),
+                    metadata: { ...target.metadata, ...settings.metadata },
+                },
+            ]);
+        }
+        catch (err) {
+            target.onError?.(err);
+        }
+        return { ...reply, eventId };
+    }
+    settings(opts) {
+        return {
+            model: opts.model ?? this.opts.model,
+            trace: opts.trace ?? this.opts.trace,
+            tools: "tools" in opts ? opts.tools : this.opts.tools,
+            maxTokens: opts.maxTokens ?? this.opts.maxTokens,
+            maxSteps: opts.maxSteps ?? this.opts.maxSteps ?? DEFAULT_MAX_STEPS,
+            onText: opts.onText ?? this.opts.onText,
+            schema: opts.schema ?? this.opts.schema,
+            params: { ...this.opts.params, ...opts.params },
+            metadata: { ...this.opts.metadata, ...opts.metadata },
+        };
+    }
+    body(settings) {
+        return {
+            model: settings.model,
+            maxTokens: settings.maxTokens,
+            structured: asStructured(settings.schema),
+            params: settings.params ?? {},
+        };
+    }
+    /**
+     * 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.
+     */
+    withData(reply, settings) {
+        if (!settings.schema || reply.status === "failed")
+            return reply;
+        const forced = reply.toolCalls[0]?.args;
+        const data = readStructured(reply.output, forced);
+        const output = reply.output.trim() ? reply.output : JSON.stringify(data);
+        return { ...reply, data, output };
+    }
+    read(raw) {
+        const reply = this.adapterFor(raw).read(raw, {
+            provider: this.provider,
+        });
+        if (reply.model)
+            return reply;
+        return { ...reply, model: pricingId(this.provider, this.opts.model) };
+    }
+    adapterFor(raw) {
+        const byProvider = adapterForProvider(this.provider);
+        return byProvider.detect(raw) ? byProvider : adapterOfShape(this.driver.shape);
+    }
+}

package/dist/llm/schema/index.d.ts

@@ -0,0 +1 @@
+export { anthropicStructured, geminiStructured, type JsonSchema, openaiStructured, readStructured, type StructuredOutput, StructuredOutputError, } from "./schema.js";

package/dist/llm/schema/index.js

@@ -0,0 +1 @@
+export { anthropicStructured, geminiStructured, openaiStructured, readStructured, StructuredOutputError, } from "./schema.js";

package/dist/llm/schema/schema.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A JSON Schema object, as the providers take it.
+ *
+ * Deliberately structural and not built here: `@spendgraph/tools` turns a
+ * `FieldSpec[]` into one, zod emits one, and hand-writing one is three lines.
+ * Accepting the wire format is what keeps this package dependency-free.
+ */
+export interface JsonSchema {
+    type?: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    items?: unknown;
+    [key: string]: unknown;
+}
+export interface StructuredOutput {
+    /** The shape the reply must take. */
+    schema: JsonSchema;
+    /** Names it for the provider. Defaults to "reply". */
+    name?: string;
+    description?: string;
+}
+/**
+ * Anthropic has no JSON mode, so a forced tool call is the schema.
+ *
+ * `tool_choice` pins it, which is the difference between "you may" and "you
+ * will" — asking politely in the prompt gets prose back often enough to matter.
+ */
+export declare function anthropicStructured(output: StructuredOutput): Record<string, unknown>;
+/** OpenAI takes a schema directly, and `strict` is what makes it a guarantee. */
+export declare function openaiStructured(output: StructuredOutput): Record<string, unknown>;
+/** Gemini needs the mime type as well; the schema alone still returns prose. */
+export declare function geminiStructured(output: StructuredOutput): Record<string, unknown>;
+export declare class StructuredOutputError extends Error {
+    readonly raw: string;
+    constructor(message: string, raw: string);
+}
+/**
+ * The object the model was asked for.
+ *
+ * A tool-forced reply already arrives parsed; a JSON-mode reply arrives as text
+ * and is parsed here. A reply that is neither throws rather than returning
+ * undefined, because a caller that asked for a shape and silently got nothing
+ * writes the empty case into their data.
+ */
+export declare function readStructured(output: string, toolArgs?: Record<string, unknown>): unknown;

package/dist/llm/schema/schema.js

@@ -0,0 +1,80 @@
+const DEFAULT_NAME = "reply";
+function named(output) {
+    return output.name ?? DEFAULT_NAME;
+}
+/**
+ * Anthropic has no JSON mode, so a forced tool call is the schema.
+ *
+ * `tool_choice` pins it, which is the difference between "you may" and "you
+ * will" — asking politely in the prompt gets prose back often enough to matter.
+ */
+export function anthropicStructured(output) {
+    return {
+        tools: [
+            {
+                name: named(output),
+                description: output.description ?? "Return the answer in this shape.",
+                input_schema: output.schema,
+            },
+        ],
+        tool_choice: { type: "tool", name: named(output) },
+    };
+}
+/** OpenAI takes a schema directly, and `strict` is what makes it a guarantee. */
+export function openaiStructured(output) {
+    return {
+        response_format: {
+            type: "json_schema",
+            json_schema: {
+                name: named(output),
+                strict: true,
+                schema: { additionalProperties: false, ...output.schema },
+            },
+        },
+    };
+}
+/** Gemini needs the mime type as well; the schema alone still returns prose. */
+export function geminiStructured(output) {
+    return {
+        responseMimeType: "application/json",
+        responseSchema: output.schema,
+    };
+}
+export class StructuredOutputError extends Error {
+    raw;
+    constructor(message, raw) {
+        super(message);
+        this.raw = raw;
+        this.name = "StructuredOutputError";
+    }
+}
+/**
+ * The object the model was asked for.
+ *
+ * A tool-forced reply already arrives parsed; a JSON-mode reply arrives as text
+ * and is parsed here. A reply that is neither throws rather than returning
+ * undefined, because a caller that asked for a shape and silently got nothing
+ * writes the empty case into their data.
+ */
+export function readStructured(output, toolArgs) {
+    if (toolArgs && Object.keys(toolArgs).length > 0)
+        return toolArgs;
+    const text = output.trim();
+    if (!text)
+        throw new StructuredOutputError("The model returned nothing to parse.", output);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        const fenced = /```(?:json)?\s*([\s\S]+?)\s*```/.exec(text);
+        if (fenced) {
+            try {
+                return JSON.parse(fenced[1]);
+            }
+            catch {
+                // falls through to the throw below
+            }
+        }
+        throw new StructuredOutputError("The model did not return JSON.", output);
+    }
+}

package/dist/llm/types.d.ts

@@ -0,0 +1,62 @@
+import type { SpendgraphOptions, Tag } from "../report/index.js";
+import type { Provider } from "../types.js";
+import type { JsonSchema, StructuredOutput } from "./schema/index.js";
+export interface ToolResult {
+    status: "completed" | "failed";
+    output: string;
+    error?: string;
+}
+/** A tool bus — structurally what `@spendgraph/tools` `toolbus()` returns. */
+export interface ToolBus {
+    anthropic(): unknown[];
+    openai(): unknown[];
+    invoke(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+}
+/** Settable on the client and overridable on any single call. */
+export interface CallDefaults {
+    model?: string;
+    /** false calls the model and records no usage. */
+    trace?: boolean;
+    tools?: ToolBus;
+    /**
+     * A shape the reply must take. The parsed object comes back on `data`.
+     *
+     * A bare JSON Schema is shorthand for `{ schema }`. Anthropic gets a forced
+     * tool call, OpenAI a strict `json_schema`, Gemini a `responseSchema` — the
+     * three ways of saying the same thing.
+     */
+    schema?: JsonSchema | StructuredOutput;
+    maxTokens?: number;
+    maxSteps?: number;
+    /** Merged into the request body, call over client. */
+    params?: Record<string, unknown>;
+    /** Attached to the usage event, call over client. */
+    metadata?: Record<string, Tag>;
+    onText?: (delta: string) => void;
+}
+export interface LlmOptions extends CallDefaults {
+    /** A provider SDK client, called by duck typing and never imported. */
+    client: unknown;
+    model: string;
+    /** Pricing slug. Needed for OpenAI-compatible gateways, which share a shape. */
+    provider?: Provider;
+    /** Where usage goes. Omit and nothing is recorded. */
+    spendgraph?: SpendgraphOptions;
+    /**
+     * Models to try, in order, when the call throws.
+     *
+     * For an overloaded provider, not a bad request — a 400 fails the same way on
+     * every model and trying three of them spends three round trips saying so.
+     * `onFallback` is called before each attempt so the switch is not silent.
+     */
+    fallbacks?: string[];
+    onFallback?: (info: {
+        from: string;
+        to: string;
+        error: unknown;
+    }) => void;
+}
+export interface CallOptions extends CallDefaults {
+    /** Supply your own so a retried job counts once. */
+    eventId?: string;
+}

package/dist/llm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/model.d.ts

@@ -0,0 +1,7 @@
+import type { Provider } from "./types.js";
+/**
+ * The model id `model_pricing` is keyed on. An unmatched id records a call
+ * costing zero, so this is the difference between a priced call and an
+ * unpriced one.
+ */
+export declare function pricingId(provider: Provider, reported: string): string;

package/dist/model.js

@@ -0,0 +1,22 @@
+/**
+ * Providers whose `model_pricing` rows are keyed on the id the API reports.
+ * `anthropic` and `openai` because litellm treats them as the unprefixed
+ * defaults, `bedrock` because its ids are already namespaced by the lab that
+ * made the model.
+ */
+const KEYED_ON_REPORTED_ID = new Set(["anthropic", "openai", "bedrock"]);
+/**
+ * The model id `model_pricing` is keyed on. An unmatched id records a call
+ * costing zero, so this is the difference between a priced call and an
+ * unpriced one.
+ */
+export function pricingId(provider, reported) {
+    const id = reported.trim();
+    if (!id)
+        return "";
+    if (KEYED_ON_REPORTED_ID.has(provider))
+        return id;
+    if (id.startsWith(`${provider}/`))
+        return id;
+    return `${provider}/${id}`;
+}

package/dist/read.d.ts

@@ -0,0 +1,10 @@
+import type { LlmReply, ReadOptions } from "./types.js";
+export declare class UnknownReplyError extends Error {
+    constructor();
+}
+/**
+ * Reads any supported provider reply into the shape `prompt.trace()` returns.
+ * Without `provider` the shape is sniffed, which cannot tell OpenAI-compatible
+ * gateways apart and so prices them as OpenAI.
+ */
+export declare function read(value: unknown, opts?: ReadOptions): LlmReply;

package/dist/read.js

@@ -0,0 +1,18 @@
+import { adapterFor, detect } from "./adapters/index.js";
+export class UnknownReplyError extends Error {
+    constructor() {
+        super("Could not tell which provider this reply came from. Pass { provider } to choose an adapter.");
+        this.name = "UnknownReplyError";
+    }
+}
+/**
+ * Reads any supported provider reply into the shape `prompt.trace()` returns.
+ * Without `provider` the shape is sniffed, which cannot tell OpenAI-compatible
+ * gateways apart and so prices them as OpenAI.
+ */
+export function read(value, opts = {}) {
+    const adapter = opts.provider ? adapterFor(opts.provider) : detect(value);
+    if (!adapter)
+        throw new UnknownReplyError();
+    return adapter.read(value, opts);
+}

package/dist/report/index.d.ts

@@ -0,0 +1,2 @@
+export { ingestFor, MAX_EVENTS, MissingCredentialsError, newEventId, } from "./ingest.js";
+export type { Ingest, SpendgraphOptions, Tag, UsageEvent } from "./types.js";

package/dist/report/index.js

@@ -0,0 +1 @@
+export { ingestFor, MAX_EVENTS, MissingCredentialsError, newEventId, } from "./ingest.js";

package/dist/report/ingest.d.ts

@@ -0,0 +1,15 @@
+import { MAX_EVENTS } from "@spendgraph/sdk";
+import type { Ingest, SpendgraphOptions } from "./types.js";
+/** The route takes up to this many events per request. */
+export { MAX_EVENTS };
+export declare function newEventId(): string;
+export declare class MissingCredentialsError extends Error {
+    constructor();
+}
+/**
+ * Where usage goes.
+ *
+ * The HTTP call belongs to `@spendgraph/sdk`, which is the one package that
+ * talks to the app — this one never opens a socket.
+ */
+export declare function ingestFor(opts: SpendgraphOptions): Ingest;

package/dist/report/ingest.js

@@ -0,0 +1,29 @@
+import { MAX_EVENTS, Spendgraph } from "@spendgraph/sdk";
+/** The route takes up to this many events per request. */
+export { MAX_EVENTS };
+export function newEventId() {
+    return `ev_${crypto.randomUUID().replace(/-/g, "")}`;
+}
+export class MissingCredentialsError extends Error {
+    constructor() {
+        super("spendgraph needs { apiKey, baseUrl }, or { via } to send usage yourself.");
+        this.name = "MissingCredentialsError";
+    }
+}
+/**
+ * Where usage goes.
+ *
+ * The HTTP call belongs to `@spendgraph/sdk`, which is the one package that
+ * talks to the app — this one never opens a socket.
+ */
+export function ingestFor(opts) {
+    if (opts.via)
+        return opts.via;
+    if (!opts.apiKey || !opts.baseUrl)
+        throw new MissingCredentialsError();
+    return new Spendgraph({
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl,
+        project: opts.project,
+    }).ingest;
+}

package/dist/report/types.d.ts

@@ -0,0 +1,30 @@
+export type Tag = string | number | boolean;
+/** One call's consumption. The server prices it from the model id. */
+export interface UsageEvent {
+    eventId?: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** Billed on their own by search-grounded providers, not folded into output. */
+    citationTokens?: number;
+    reasoningTokens?: number;
+    timestamp?: string;
+    metadata?: Record<string, Tag>;
+}
+/** Anything that can deliver usage — the built-in sender, a queue, a buffer. */
+export interface Ingest {
+    send(events: UsageEvent[]): Promise<void>;
+}
+export interface SpendgraphOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    /** Used instead of `apiKey`/`baseUrl` — batch, queue, or send it yourself. */
+    via?: Ingest;
+    project?: string;
+    /** Attached to every event, merged with per-call metadata. */
+    metadata?: Record<string, Tag>;
+    /** Called when usage is dropped. Recording never throws. */
+    onError?: (err: unknown) => void;
+}

package/dist/report/types.js

@@ -0,0 +1 @@
+export {};

package/dist/request.d.ts

@@ -0,0 +1,26 @@
+import type { PromptMessage } from "./types.js";
+/** Anthropic and Bedrock Converse take the system prompt beside the messages. */
+export declare function anthropicMessages(messages: PromptMessage[]): {
+    system?: string;
+    messages: {
+        role: "user" | "assistant";
+        content: string;
+    }[];
+};
+export declare function openaiMessages(messages: PromptMessage[]): {
+    messages: PromptMessage[];
+};
+/** Gemini calls the assistant "model", which is the one role name it renames. */
+export declare function geminiMessages(messages: PromptMessage[]): {
+    systemInstruction?: {
+        parts: {
+            text: string;
+        }[];
+    };
+    contents: {
+        role: "user" | "model";
+        parts: {
+            text: string;
+        }[];
+    }[];
+};

package/dist/request.js

@@ -0,0 +1,32 @@
+function split(messages) {
+    const preamble = [];
+    const turns = [];
+    for (const message of messages) {
+        if (message.role === "system")
+            preamble.push(message.content);
+        else
+            turns.push(message);
+    }
+    return { system: preamble.length ? preamble.join("\n\n") : undefined, turns };
+}
+/** Anthropic and Bedrock Converse take the system prompt beside the messages. */
+export function anthropicMessages(messages) {
+    const { system, turns } = split(messages);
+    const turned = turns.map((m) => ({
+        role: m.role === "assistant" ? "assistant" : "user",
+        content: m.content,
+    }));
+    return system ? { system, messages: turned } : { messages: turned };
+}
+export function openaiMessages(messages) {
+    return { messages: [...messages] };
+}
+/** Gemini calls the assistant "model", which is the one role name it renames. */
+export function geminiMessages(messages) {
+    const { system, turns } = split(messages);
+    const contents = turns.map((m) => ({
+        role: m.role === "assistant" ? "model" : "user",
+        parts: [{ text: m.content }],
+    }));
+    return system ? { systemInstruction: { parts: [{ text: system }] }, contents } : { contents };
+}

package/dist/stream.d.ts

@@ -0,0 +1,26 @@
+import { type Shape } from "./adapters/index.js";
+import type { LlmReply, ReadOptions } from "./types.js";
+export interface StreamOptions extends ReadOptions {
+    shape?: Shape;
+    onText?: (delta: string) => void;
+}
+/**
+ * A provider stream as an async iterable of text deltas, with the finished
+ * reply available once it drains. Built by `stream()`.
+ */
+export type { LlmStream };
+declare class LlmStream implements AsyncIterable<string> {
+    private readonly source;
+    private readonly opts;
+    private readonly state;
+    private readonly adapter;
+    private done;
+    constructor(source: AsyncIterable<unknown>, opts?: StreamOptions);
+    [Symbol.asyncIterator](): AsyncIterator<string>;
+    /** Drains any events not yet read, then assembles the reply. */
+    reply(): Promise<LlmReply>;
+}
+/** A stream to iterate for text deltas, then ask for the finished reply. */
+export declare function stream(source: AsyncIterable<unknown>, opts?: StreamOptions): LlmStream;
+/** Consumes a stream whole, calling `onText` per delta. */
+export declare function collect(source: AsyncIterable<unknown>, opts?: StreamOptions): Promise<LlmReply>;