@wrenautomation/models 0.0.0-stage → 0.7.0

package/dist/hear.d.ts

@@ -0,0 +1,65 @@
+import { type RotateOptions } from "./keys.js";
+export interface Audio {
+    data: Uint8Array;
+    /** `audio/wav`, `audio/mpeg`. */
+    mediaType: string;
+    filename?: string;
+}
+export interface HearOptions {
+    /** ISO 639-1. Default `en`. */
+    language?: string;
+    /** The audio's length, when known: it prices the call. */
+    seconds?: number;
+    signal?: AbortSignal;
+}
+export interface Heard {
+    text: string;
+    /** The model that heard it. */
+    model: string;
+    ms: number;
+    /** 0 on a free key; absent when the model or the length has no price. */
+    usd?: number;
+    free?: boolean;
+    listUsd?: number;
+}
+export interface Ear {
+    /** As spends name it (`groq:whisper-large-v3-turbo`). */
+    readonly id: string;
+    readonly model: string;
+    hear(audio: Audio, o?: HearOptions): Promise<Heard>;
+}
+export interface EarOptions {
+    /** The full `/audio/transcriptions` URL. */
+    url: string;
+    model: string;
+    /** None for a server with no auth. */
+    key?: string | readonly string[];
+    /** The vendor, for the id. Default: the URL's host. */
+    vendor?: string;
+    free?: boolean;
+    /** Send `response_format=json` (OpenAI's field). Default true; Cohere's route takes no such field. */
+    jsonFormat?: boolean;
+    /** Bytes the vendor takes at most; a larger file throws before the call. */
+    maxBytes?: number;
+    limitMs?: number;
+    rotate?: RotateOptions;
+    fetch?: typeof fetch;
+}
+/** Any OpenAI-compatible transcription endpoint. Keys travel in a header, never in an error. */
+export declare function compatibleEar(o: EarOptions): Ear;
+export declare const COHERE_SPEECH_MODEL = "cohere-transcribe-03-2026";
+/** Cohere's transcription on the free key ring. It takes 25 MB at most. */
+export declare const cohereEar: (o: {
+    key: string | readonly string[];
+    rotate?: RotateOptions;
+    fetch?: typeof fetch;
+}) => Ear;
+/** Whisper on Groq's free key ring. */
+export declare const groqEar: (o: {
+    key: string | readonly string[];
+    model?: string;
+    rotate?: RotateOptions;
+    fetch?: typeof fetch;
+}) => Ear;
+/** An ear for tests and dry runs: no network, no keys. Answers each call from `respond`. */
+export declare function fakeEar(respond?: string | ((audio: Audio, o: HearOptions) => string | Promise<string>), id?: string): Ear;

package/dist/hear.js

@@ -0,0 +1,106 @@
+/**
+ * Speech to text: the `Ear` door. Every vendor here takes the OpenAI-style multipart POST to
+ * `/audio/transcriptions` (Groq, Cohere, a self-hosted whisper server). No `node:` import: the
+ * portal Worker uses it.
+ */
+import { httpError, transport } from "./errors.js";
+import { cursor, overRing } from "./keys.js";
+import { speechUsd } from "./prices.js";
+const EXT = {
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "audio/mpeg": "mp3",
+    "audio/mp4": "m4a",
+    "audio/webm": "webm",
+    "audio/ogg": "ogg",
+    "audio/flac": "flac",
+};
+/** Any OpenAI-compatible transcription endpoint. Keys travel in a header, never in an error. */
+export function compatibleEar(o) {
+    const vendor = o.vendor ?? new URL(o.url).hostname;
+    const id = `${vendor}:${o.model}`;
+    const keys = o.key === undefined ? [undefined] : typeof o.key === "string" ? [o.key] : o.key;
+    if (!keys.length)
+        throw new Error(`${id} needs at least one key`);
+    const go = o.fetch ?? fetch;
+    const next = cursor();
+    return {
+        id,
+        model: o.model,
+        async hear(audio, h = {}) {
+            if (o.maxBytes && audio.data.byteLength > o.maxBytes)
+                throw new Error(`${id}: ${(audio.data.byteLength / 1e6).toFixed(1)} MB of audio, over its ${o.maxBytes / 1e6} MB`);
+            const started = performance.now();
+            const once = async (key) => {
+                const form = new FormData();
+                const name = audio.filename ?? `audio.${EXT[audio.mediaType] ?? "bin"}`;
+                form.set("file", new Blob([audio.data], { type: audio.mediaType }), name);
+                form.set("model", o.model);
+                if (o.jsonFormat !== false)
+                    form.set("response_format", "json");
+                form.set("language", h.language ?? "en");
+                const timeout = AbortSignal.timeout(o.limitMs ?? 120_000);
+                let res;
+                try {
+                    res = await go(o.url, {
+                        method: "POST",
+                        headers: key ? { authorization: `Bearer ${key}` } : {},
+                        body: form,
+                        signal: h.signal ? AbortSignal.any([h.signal, timeout]) : timeout,
+                    });
+                }
+                catch (err) {
+                    if (h.signal?.aborted)
+                        throw err;
+                    throw transport(id, err);
+                }
+                if (!res.ok)
+                    throw httpError(id, res, (await res.text().catch(() => "")).slice(0, 200));
+                const body = (await res.json().catch(() => ({})));
+                return typeof body.text === "string" ? body.text.trim() : "";
+            };
+            const text = await overRing(keys, once, next, o.rotate);
+            const list = h.seconds === undefined ? undefined : speechUsd(o.model, h.seconds);
+            const cost = o.free
+                ? { usd: 0, free: true, ...(list !== undefined ? { listUsd: list } : {}) }
+                : list !== undefined
+                    ? { usd: list }
+                    : {};
+            return { text, model: o.model, ms: Math.round(performance.now() - started), ...cost };
+        },
+    };
+}
+export const COHERE_SPEECH_MODEL = "cohere-transcribe-03-2026";
+/** Cohere's transcription on the free key ring. It takes 25 MB at most. */
+export const cohereEar = (o) => compatibleEar({
+    url: "https://api.cohere.com/v2/audio/transcriptions",
+    model: COHERE_SPEECH_MODEL,
+    vendor: "cohere",
+    free: true,
+    jsonFormat: false,
+    maxBytes: 25_000_000,
+    ...o,
+});
+/** Whisper on Groq's free key ring. */
+export const groqEar = (o) => compatibleEar({
+    url: "https://api.groq.com/openai/v1/audio/transcriptions",
+    model: o.model ?? "whisper-large-v3-turbo",
+    vendor: "groq",
+    free: true,
+    maxBytes: 25_000_000,
+    key: o.key,
+    ...(o.rotate ? { rotate: o.rotate } : {}),
+    ...(o.fetch ? { fetch: o.fetch } : {}),
+});
+/** An ear for tests and dry runs: no network, no keys. Answers each call from `respond`. */
+export function fakeEar(respond = "", id = "fake:ear") {
+    return {
+        id,
+        model: id,
+        async hear(audio, o = {}) {
+            const text = typeof respond === "string" ? respond : await respond(audio, o);
+            return { text, model: id, ms: 0, usd: 0 };
+        },
+    };
+}
+//# sourceMappingURL=hear.js.map

package/dist/hear.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The one door to model calls: every Wren repo calls a model through this package. A `Model`
+ * takes text and media parts and answers text, tokens, USD and why it stopped; `ask` parses the
+ * answer to a zod shape. No `node:` import behind this door: it runs in a Worker too.
+ */
+export * from "./errors.js";
+export { fakeModel, scriptedModel } from "./fake.js";
+export { cursor, type EnvMap, fallback, fleetKeys, overRing, type RotateOptions, rotating, } from "./keys.js";
+export { askWith, asRequest, checkParts, modelOf, promptText, TEXT_ONLY } from "./model.js";
+export { NoAnswer, parseAnswer, wellFormed } from "./parse.js";
+export { addUsage, priced } from "./prices.js";
+export * from "./providers.js";
+export { CALL_LIMIT_MS, DEFAULT_MAX_TOKENS, type SdkModelOptions, sdkModel } from "./sdk.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * The one door to model calls: every Wren repo calls a model through this package. A `Model`
+ * takes text and media parts and answers text, tokens, USD and why it stopped; `ask` parses the
+ * answer to a zod shape. No `node:` import behind this door: it runs in a Worker too.
+ */
+export * from "./errors.js";
+export { fakeModel, scriptedModel } from "./fake.js";
+export { cursor, fallback, fleetKeys, overRing, rotating, } from "./keys.js";
+export { askWith, asRequest, checkParts, modelOf, promptText, TEXT_ONLY } from "./model.js";
+export { NoAnswer, parseAnswer, wellFormed } from "./parse.js";
+export { addUsage, priced } from "./prices.js";
+export * from "./providers.js";
+export { CALL_LIMIT_MS, DEFAULT_MAX_TOKENS, sdkModel } from "./sdk.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EACL,MAAM,EAEN,QAAQ,EACR,SAAS,EACT,QAAQ,EAER,QAAQ,GACT,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5F,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC/C,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAwB,QAAQ,EAAE,MAAM,UAAU,CAAC"}

package/dist/keys.d.ts

@@ -0,0 +1,36 @@
+import type { Model } from "./types.js";
+export type EnvMap = Readonly<Record<string, string | undefined>>;
+/**
+ * A vendor's keys, model-keys-file style: `NUM_<V>` plus `<V>_API_KEY_1..N` (gaps passed over),
+ * else one `<V>_API_KEY`. A line may carry an inline note after the key.
+ */
+export declare function fleetKeys(env: EnvMap, vendor: string): string[];
+export interface RotateOptions {
+    /**
+     * Passes over the whole ring while keys only say "later" (429, 5xx). Default 1: the caller
+     * owns waiting. More passes wait between them, doubling from `waitMs` up to `maxWaitMs`.
+     */
+    passes?: number;
+    waitMs?: number;
+    maxWaitMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Call over a ring of keys, round robin from `start()`. A refused key (401, 402, 403) hands the
+ * call to the next at once; a busy one (429, 5xx, a dropped connection) does too, and when the
+ * whole ring is busy the pass ends. Any other error is the call's and is thrown as is.
+ */
+export declare function overRing<K, T>(ring: readonly K[], call: (k: K) => Promise<T>, start: () => number, o?: RotateOptions): Promise<T>;
+/** A round-robin cursor: each call returns the next index. */
+export declare const cursor: () => () => number;
+/**
+ * One model over several keys (one model per key), by `overRing`. A key refused once (401, 402,
+ * 403: suspended, revoked) is passed over on later calls; when every key has been refused, the
+ * whole ring is tried again so the error is a live one.
+ */
+export declare function rotating(models: readonly Model[], o?: RotateOptions): Model;
+/**
+ * Models in order of preference (`gemini-3.8-flash`, then `gemini-3.5-flash`): each call starts at
+ * the first and moves down past a busy or refused one. The reply's `model` names who answered.
+ */
+export declare function fallback(models: readonly Model[], o?: RotateOptions): Model;

package/dist/keys.js

@@ -0,0 +1,110 @@
+/** API keys from the environment and one rotation over them. */
+import { isRefused, isTransient } from "./errors.js";
+import { modelOf } from "./model.js";
+/**
+ * A vendor's keys, model-keys-file style: `NUM_<V>` plus `<V>_API_KEY_1..N` (gaps passed over),
+ * else one `<V>_API_KEY`. A line may carry an inline note after the key.
+ */
+export function fleetKeys(env, vendor) {
+    const upper = vendor.toUpperCase();
+    const first = (v) => v?.trim().split(/\s/)[0] || undefined;
+    const count = Number.parseInt(env[`NUM_${upper}`] ?? "0", 10);
+    const keys = [];
+    for (let n = 1; n <= count; n++) {
+        const key = first(env[`${upper}_API_KEY_${n}`]);
+        if (key)
+            keys.push(key);
+    }
+    const single = first(env[`${upper}_API_KEY`]);
+    if (!keys.length && single)
+        keys.push(single);
+    return keys;
+}
+const nap = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Call over a ring of keys, round robin from `start()`. A refused key (401, 402, 403) hands the
+ * call to the next at once; a busy one (429, 5xx, a dropped connection) does too, and when the
+ * whole ring is busy the pass ends. Any other error is the call's and is thrown as is.
+ */
+export async function overRing(ring, call, start, o = {}) {
+    const { passes = 1, waitMs = 2000, maxWaitMs = 30_000, sleep = nap } = o;
+    let last;
+    for (let pass = 0; pass < passes; pass++) {
+        if (pass > 0)
+            await sleep(Math.min(waitMs * 2 ** (pass - 1), maxWaitMs));
+        let busy = false;
+        for (let tried = 0; tried < ring.length; tried++) {
+            try {
+                return await call(ring[start() % ring.length]);
+            }
+            catch (err) {
+                if (!isRefused(err) && !isTransient(err))
+                    throw err;
+                if (isTransient(err))
+                    busy = true;
+                last = err;
+            }
+        }
+        if (!busy)
+            break;
+    }
+    throw last;
+}
+/** A round-robin cursor: each call returns the next index. */
+export const cursor = () => {
+    let n = 0;
+    return () => n++;
+};
+/**
+ * One model over several keys (one model per key), by `overRing`. A key refused once (401, 402,
+ * 403: suspended, revoked) is passed over on later calls; when every key has been refused, the
+ * whole ring is tried again so the error is a live one.
+ */
+export function rotating(models, o = {}) {
+    const first = models[0];
+    if (!first)
+        throw new Error("rotating needs at least one model");
+    if (models.length === 1 && (o.passes ?? 1) <= 1)
+        return first;
+    const next = cursor();
+    const dead = new Set();
+    const call = (req) => async (m) => {
+        try {
+            return await m.complete(req);
+        }
+        catch (err) {
+            if (isRefused(err))
+                dead.add(m);
+            throw err;
+        }
+    };
+    return modelOf({
+        id: first.id,
+        provider: first.provider,
+        takes: first.takes,
+        complete: (req) => {
+            const live = models.filter((m) => !dead.has(m));
+            return overRing(live.length ? live : models, call(req), next, o);
+        },
+    });
+}
+/**
+ * Models in order of preference (`gemini-3.8-flash`, then `gemini-3.5-flash`): each call starts at
+ * the first and moves down past a busy or refused one. The reply's `model` names who answered.
+ */
+export function fallback(models, o = {}) {
+    const first = models[0];
+    if (!first)
+        throw new Error("fallback needs at least one model");
+    const takes = new Set(models.flatMap((m) => [...m.takes]).filter((k) => models.every((m) => m.takes.has(k))));
+    return modelOf({
+        id: first.id,
+        provider: first.provider,
+        takes,
+        complete: (req) => {
+            const next = cursor();
+            return overRing(models, (m) => m.complete(req), next, o);
+        },
+    });
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

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

package/dist/model.d.ts

@@ -0,0 +1,21 @@
+/** A `Model` from one `complete`: the request checks and the parse-and-repair `ask` live here once. */
+import type { ZodType } from "zod";
+import type { Answer, AskOptions, Model, Part, PartKind, Reply, Request } from "./types.js";
+export declare const TEXT_ONLY: ReadonlySet<PartKind>;
+export declare const asRequest: (r: Request | string) => Request;
+/** The prompt as plain text when it is only text parts; null when it holds media. */
+export declare function promptText(prompt: string | readonly Part[]): string | null;
+/** Throws `Unsupported` for the first part the model does not take. */
+export declare function checkParts(id: string, takes: ReadonlySet<PartKind>, prompt: Request["prompt"]): void;
+/**
+ * Parse a reply to the shape; on a miss, ask again with why, up to `repairs` times (default 1).
+ * The usage of every call is summed into the answer.
+ */
+export declare function askWith<T>(complete: (r: Request) => Promise<Reply>, prompt: string | readonly Part[], shape: ZodType<T>, o?: AskOptions): Promise<Answer<T>>;
+/** A full `Model` from its id, vendor, part kinds and one `complete`. */
+export declare function modelOf(o: {
+    id: string;
+    provider: string;
+    takes?: ReadonlySet<PartKind>;
+    complete: (r: Request) => Promise<Reply>;
+}): Model;

package/dist/model.js

@@ -0,0 +1,68 @@
+import { Unsupported } from "./errors.js";
+import { NoAnswer, parseAnswer } from "./parse.js";
+import { addUsage } from "./prices.js";
+export const TEXT_ONLY = new Set(["text"]);
+export const asRequest = (r) => typeof r === "string" ? { prompt: r } : r;
+/** The prompt as plain text when it is only text parts; null when it holds media. */
+export function promptText(prompt) {
+    if (typeof prompt === "string")
+        return prompt;
+    const texts = [];
+    for (const p of prompt) {
+        if (p.type !== "text")
+            return null;
+        texts.push(p.text);
+    }
+    return texts.join("\n\n");
+}
+/** Throws `Unsupported` for the first part the model does not take. */
+export function checkParts(id, takes, prompt) {
+    if (typeof prompt === "string")
+        return;
+    for (const p of prompt)
+        if (!takes.has(p.type))
+            throw new Unsupported(id, p.type);
+}
+const repairNote = (issues) => `Your last answer was not one JSON object of the asked shape${issues ? ` (${issues})` : ""}. Answer again with only that JSON object.`;
+/**
+ * Parse a reply to the shape; on a miss, ask again with why, up to `repairs` times (default 1).
+ * The usage of every call is summed into the answer.
+ */
+export async function askWith(complete, prompt, shape, o = {}) {
+    const { repairs = 1, ...rest } = o;
+    let usage;
+    let current = prompt;
+    for (let attempt = 0;; attempt++) {
+        const reply = await complete({ ...rest, prompt: current });
+        usage = addUsage(usage, reply.usage);
+        try {
+            return { value: parseAnswer(reply.text, shape), ...(usage ? { usage } : {}) };
+        }
+        catch (err) {
+            if (!(err instanceof NoAnswer) || attempt >= repairs)
+                throw err;
+            const note = `${reply.text}\n\n${repairNote(err.issues)}`;
+            current =
+                typeof prompt === "string"
+                    ? `${prompt}\n\nYour last answer:\n${note}`
+                    : [...prompt, { type: "text", text: `Your last answer:\n${note}` }];
+        }
+    }
+}
+/** A full `Model` from its id, vendor, part kinds and one `complete`. */
+export function modelOf(o) {
+    const takes = o.takes ?? TEXT_ONLY;
+    const complete = async (r) => {
+        const req = asRequest(r);
+        checkParts(o.id, takes, req.prompt);
+        return o.complete(req);
+    };
+    return {
+        id: o.id,
+        provider: o.provider,
+        takes,
+        complete,
+        ask: (prompt, shape, opts) => askWith(complete, prompt, shape, opts),
+    };
+}
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

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

package/dist/parse.d.ts

@@ -0,0 +1,15 @@
+/** The one reader of a model's JSON answer. */
+import type { ZodType } from "zod";
+export declare class NoAnswer extends Error {
+    readonly text: string;
+    /** Why the closest candidate failed the shape; empty when no JSON object parsed. */
+    readonly issues: string;
+    constructor(text: string, issues: string);
+}
+/**
+ * The first JSON object of the shape in a model's text, found by brace balance: fences, prose
+ * and stray braces around it are passed over. Throws `NoAnswer` when nothing parses.
+ */
+export declare function parseAnswer<T>(text: string, shape: ZodType<T>): T;
+/** Lone UTF-16 surrogates out: a vendor's JSON parser refuses them. */
+export declare const wellFormed: (s: string) => string;

package/dist/parse.js

@@ -0,0 +1,66 @@
+/** Every balanced `{...}` in a text, by start position: an outer object comes before its inner ones. */
+function* objects(text) {
+    for (let start = text.indexOf("{"); start >= 0; start = text.indexOf("{", start + 1)) {
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        for (let i = start; i < text.length; i++) {
+            const c = text[i];
+            if (inString) {
+                if (escaped)
+                    escaped = false;
+                else if (c === "\\")
+                    escaped = true;
+                else if (c === '"')
+                    inString = false;
+            }
+            else if (c === '"')
+                inString = true;
+            else if (c === "{")
+                depth++;
+            else if (c === "}" && --depth === 0) {
+                yield text.slice(start, i + 1);
+                break;
+            }
+        }
+    }
+}
+export class NoAnswer extends Error {
+    text;
+    /** Why the closest candidate failed the shape; empty when no JSON object parsed. */
+    issues;
+    constructor(text, issues) {
+        super(`no answer of the expected shape${issues ? ` (${issues})` : ""} in: ${text.slice(0, 400)}`);
+        this.name = "NoAnswer";
+        this.text = text;
+        this.issues = issues;
+    }
+}
+/**
+ * The first JSON object of the shape in a model's text, found by brace balance: fences, prose
+ * and stray braces around it are passed over. Throws `NoAnswer` when nothing parses.
+ */
+export function parseAnswer(text, shape) {
+    let issues = "";
+    for (const candidate of objects(text)) {
+        let json;
+        try {
+            json = JSON.parse(candidate);
+        }
+        catch {
+            continue;
+        }
+        const out = shape.safeParse(json);
+        if (out.success)
+            return out.data;
+        if (!issues)
+            issues = out.error.issues
+                .slice(0, 5)
+                .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+                .join("; ");
+    }
+    throw new NoAnswer(text, issues);
+}
+/** Lone UTF-16 surrogates out: a vendor's JSON parser refuses them. */
+export const wellFormed = (s) => s.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "");
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

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

package/dist/prices.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What a model call costs, in USD, from the tokens it reports: the one price table. Rates are
+ * USD per million tokens (per hour for speech), by model id; a dated id
+ * (`claude-haiku-5-5-20261001`) takes its base's row. A request is priced on its own prompt:
+ * every input token, cache reads and writes included, picks the tier. A model with no row gets
+ * no `usd`: the spend keeps the id and the tokens, so a price can be applied later. A free key
+ * costs 0 and keeps the list price as `listUsd`.
+ *
+ * Sources, read 2026-10-27: Anthropic from the Claude API docs (cache writes 1.25x input for 5
+ * minutes, 2x for 1 hour; reads 0.1x, Opus 5.5 0.05x); Cohere, Groq and Gemini from
+ * third-party price lists that quote the vendor pages. Check a vendor page before a budget.
+ */
+import type { Usage } from "./types.js";
+export declare const PRICES_AS_OF = "2026-10-27";
+export interface Rate {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite5m?: number;
+    cacheWrite1h?: number;
+}
+export interface ModelPrice {
+    /** The model id without a date suffix. */
+    model: string;
+    /** Said to a person. */
+    name: string;
+    vendor: string;
+    /** Rates by prompt length, shortest first; `upTo` is the longest prompt a tier takes (null: any). */
+    tiers: readonly {
+        upTo: number | null;
+        rate: Rate;
+    }[];
+}
+export declare const MODEL_PRICES: readonly ModelPrice[];
+/** Speech to text, USD per hour of audio. */
+export declare const SPEECH_PRICES: Readonly<Record<string, number>>;
+/** The price row for a model id; a dated id takes its base's. */
+export declare function priceOf(model: string): ModelPrice | null;
+/** The call's cost in USD, or undefined when the model has no row. Never throws. */
+export declare function priceUsd(model: string, u: Usage): number | undefined;
+/** The usage with its price. A free call says `usd: 0`, `free: true` and its list price. */
+export declare function priced(model: string, usage: Usage, o?: {
+    free?: boolean;
+}): Usage;
+/** What `seconds` of speech cost on a speech model, or undefined with no row. */
+export declare function speechUsd(model: string, seconds: number): number | undefined;
+/** Two usages added, each field summed where either side has it. */
+export declare function addUsage(a: Usage | undefined, b: Usage | undefined): Usage | undefined;
+/** "Opus 5.5 $4.00 in, $20.00 out; ... per million tokens". */
+export declare function pricesText(vendor?: string): string;