@wrenautomation/models 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,91 @@
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.
+
+Required Notice: Copyright 2026 William Jin (https://wrenautomation.com)

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# models
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One door to every model call in Wren's repos. A `Model` takes text, image, video, audio and PDF
+parts. It answers with text, tokens, USD and why it stopped. `ask` parses the answer to a zod
+shape and asks again once when the answer does not fit.
+
+The rule: code that calls a model calls it through this package. A new vendor, a new part kind or
+a new price goes here, never in the caller. No guard enforces this; this file and wren's
+`designs/2026-10-26-research-engine.md` record it.
+
+| Import | Does | Runs in |
+|---|---|---|
+| `@wrenautomation/models` | `Model`, `Part`, `Usage`; `anthropic`, `gemini`, `cohere`, `compatible` (Groq, OpenRouter, Mistral, Cerebras, OpenAI), `gateway`; `rotating` key rings; `fakeModel`, `scriptedModel`; the errors | Node, Workers |
+| `@wrenautomation/models/hear` | speech to text: `groqEar`, `cohereEar`, `compatibleEar` (any `/audio/transcriptions` server) | Node, Workers |
+| `@wrenautomation/models/prices` | one price table: `MODEL_PRICES`, `SPEECH_PRICES`, `priceUsd`, `priced`, `speechUsd`, `addUsage`, `pricesText` | Node, Workers |
+| `@wrenautomation/models/command` | a shell command as a model (`commandModel`), Claude Code on the subscription (`claudeCode`) | Node |
+| `@wrenautomation/models/spec` | a model from a setting string: `modelFromSpec("anthropic:sonnet", env)` | Node |
+
+## Use
+
+```ts
+import { anthropic, gemini } from "@wrenautomation/models";
+import { z } from "zod";
+
+const claude = anthropic({ key: [key1, key2], model: "sonnet" });
+const { value, usage } = await claude.ask("Name three colours.", z.object({ colours: z.array(z.string()) }));
+// usage: { input, output, cacheRead?, cacheWrite?, usd }
+
+const eyes = gemini({ key: geminiKeys });
+const reply = await eyes.complete({
+  prompt: [
+    { type: "text", text: "What is on this slide?" },
+    { type: "image", data: pngBytes, mediaType: "image/png" },
+  ],
+  effort: "low",
+});
+```
+
+Spec strings: `fake`, `claude-code[:model]`, `anthropic[:haiku|sonnet|opus|id]`, `gateway[:alias]`,
+`gemini[:id]`, `cohere[:id]`, `groq|openrouter|mistral|cerebras|openai[:id]`, `command:<shell command>`.
+Keys come from `<VENDOR>_API_KEY`, or a ring `NUM_<VENDOR>` + `<VENDOR>_API_KEY_1..n`.
+
+## Errors
+
+Each error says what the caller does next. Each check (`isTransient`, `isCut`...) also matches by
+name, so a host that holds two copies of this package still sorts them.
+
+| Error | When | Next |
+|---|---|---|
+| `Transient` | 408, 429, 5xx, a dropped connection, a timeout | wait `retryAfter`, try again |
+| `Refused` | 401, 402, 403 | the key ring moves to the next key |
+| `InputRejected` | 400, 413, 422 | change the request |
+| `Unsupported` | a part kind the model does not take | pick another model; parts are never dropped |
+| `Cut` | the output cap stopped the answer | `partial` holds the text so far, `usage` its cost |
+| `NoAnswer` | `ask` found no object of the shape after its repairs | `issues` says why |
+
+A key ring moves past a refused or busy key at once. When every key is busy, it waits 2 s, then
+doubles up to 30 s, for `passes` passes (default 1). Retries inside the SDK are off.
+
+## Prices
+
+USD per million tokens, as of `PRICES_AS_OF`. A call on a free key ring (Cohere, Gemini, Groq,
+OpenRouter `:free`, the gateway's `free`, Claude Code on the subscription) records `usd: 0`,
+`free: true`, and `listUsd` (what it would have cost). Anthropic cache writes are 1.25x input
+(5 minutes) or 2x (1 hour); reads are 0.1x (0.05x on Opus 5.5). Haiku 5.5 has two tiers: a
+prompt over 100K tokens costs 5x. A model with no row keeps its tokens and has no `usd`.
+
+Sources: Anthropic's pricing page; Cohere from activepieces.com and pricepertoken.com; Groq from
+groq.com/pricing; Gemini from anotherwrapper.com and benchlm.ai.
+
+## Why the AI SDK
+
+The adapters sit on the [AI SDK](https://ai-sdk.dev) 7 (Apache 2.0): one call shape for Anthropic,
+Google, Cohere and every OpenAI-compatible server, with media parts and token details per vendor.
+The other choices were each vendor's own SDK (four call shapes and four usage formats to keep) and
+plain `fetch` (every wire format kept by hand). This package adds only what the SDK leaves out:
+errors sorted by what to do next, key rings, prices, the zod parse with repair, and speech.
+
+## Develop
+
+```sh
+pnpm install
+pnpm lint && pnpm typecheck && pnpm test
+```
+
+A `v*` tag publishes to npm (`.github/workflows/release.yml`, trusted publishing: no stored token).
+
+License: PolyForm Shield 1.0.0 (`LICENSE.md`).

package/dist/command.d.ts

@@ -0,0 +1,44 @@
+import type { Model, Usage } from "./types.js";
+/** What `claude -p --output-format json` prints; only what is read. */
+interface Envelope {
+    type?: string;
+    subtype?: string;
+    is_error?: boolean;
+    result?: string;
+    total_cost_usd?: number;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
+    };
+}
+/** The answer and usage from a command's stdout: Claude Code's envelope, else the whole text. */
+export declare function readOutput(stdout: string): {
+    text: string;
+    usage?: Usage;
+    envelope?: Envelope;
+};
+/**
+ * Any shell command as a model. A command that says nothing for `timeoutMs` (3 minutes) is
+ * killed and the call throws `Transient`, so a hung model never hangs the run.
+ */
+export declare function commandModel(command: string, o?: {
+    id?: string;
+    timeoutMs?: number;
+}): Model;
+export type ClaudeRun = (args: string[], stdin: string, timeoutMs: number) => Promise<string>;
+/** The subscription pays: an `ANTHROPIC_API_KEY` would take over from the login, so the child never sees one. */
+export declare function claudeChildEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Claude Code headless (`claude -p`), one process per call, on the person's subscription: its
+ * cost is 0 and its list price kept. Tools, MCP servers, skills and settings are off, and it runs
+ * in a scratch folder, so nothing on disk is touched. About 2 s to start: right for a few big
+ * calls, wrong for thousands of rows. `maxTokens` has no flag here; the prompt bounds the answer.
+ */
+export declare function claudeCode(model?: string, o?: {
+    bin?: string;
+    timeoutMs?: number;
+    run?: ClaudeRun;
+}): Model;
+export {};

package/dist/command.js

@@ -0,0 +1,151 @@
+/**
+ * A model that is a local process (Node only, its own door): any shell command with the prompt on
+ * stdin and the answer on stdout, or Claude Code headless on the person's own subscription.
+ */
+import { execFile, spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import { Transient } from "./errors.js";
+import { modelOf, promptText, TEXT_ONLY } from "./model.js";
+const isEnvelope = (v) => typeof v === "object" && v !== null && typeof v.result === "string";
+/** The answer and usage from a command's stdout: Claude Code's envelope, else the whole text. */
+export function readOutput(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return { text: stdout };
+    }
+    if (!isEnvelope(parsed))
+        return { text: stdout };
+    const u = parsed.usage;
+    const usage = {};
+    const read = u?.cache_read_input_tokens ?? 0;
+    const write = u?.cache_creation_input_tokens ?? 0;
+    if (u?.input_tokens !== undefined)
+        usage.input = u.input_tokens + read + write;
+    if (u?.output_tokens !== undefined)
+        usage.output = u.output_tokens;
+    if (read)
+        usage.cacheRead = read;
+    if (write)
+        usage.cacheWrite = write;
+    if (parsed.total_cost_usd !== undefined)
+        usage.usd = parsed.total_cost_usd;
+    return { text: parsed.result, usage, envelope: parsed };
+}
+const textOf = (id, req) => {
+    const text = promptText(req.prompt);
+    if (text === null)
+        throw new Error(`${id} takes text only`);
+    return req.system ? `${req.system}\n\n${text}` : text;
+};
+const reply = (id, stdout, ms, free) => {
+    const { text, usage = {}, envelope } = readOutput(stdout);
+    if (envelope?.is_error || !text.trim())
+        throw new Error(`${id}: ${envelope?.subtype ?? "empty answer"}: ${text.slice(0, 300)}`);
+    const cost = free && usage.usd !== undefined ? { ...usage, usd: 0, free: true, listUsd: usage.usd } : usage;
+    return {
+        text,
+        usage: cost,
+        model: id,
+        stop: envelope?.subtype,
+        ms,
+        raw: envelope ? { ...envelope, result: undefined } : {},
+    };
+};
+/**
+ * Any shell command as a model. A command that says nothing for `timeoutMs` (3 minutes) is
+ * killed and the call throws `Transient`, so a hung model never hangs the run.
+ */
+export function commandModel(command, o = {}) {
+    const id = o.id ?? command;
+    const timeoutMs = o.timeoutMs ?? 180_000;
+    return modelOf({
+        id,
+        provider: "command",
+        takes: TEXT_ONLY,
+        complete: (req) => new Promise((resolve, reject) => {
+            const started = performance.now();
+            const child = spawn(command, { shell: true, stdio: ["pipe", "pipe", "inherit"] });
+            const out = [];
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                child.kill();
+            }, timeoutMs);
+            child.stdout.on("data", (b) => out.push(b));
+            child.on("error", (e) => {
+                clearTimeout(timer);
+                reject(e);
+            });
+            child.on("close", (code) => {
+                clearTimeout(timer);
+                const stdout = Buffer.concat(out).toString("utf8");
+                if (timedOut)
+                    return reject(new Transient(`${id}: no answer in ${Math.round(timeoutMs / 1000)}s`));
+                if (code !== 0)
+                    return reject(new Error(`${id} exited ${code}: ${stdout.slice(0, 400)}`));
+                try {
+                    resolve(reply(id, stdout, Math.round(performance.now() - started), false));
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+            child.stdin.end(textOf(id, req));
+        }),
+    });
+}
+/** The subscription pays: an `ANTHROPIC_API_KEY` would take over from the login, so the child never sees one. */
+export function claudeChildEnv(env = process.env) {
+    const { ANTHROPIC_API_KEY: _drop, ...rest } = env;
+    return rest;
+}
+function spawnClaude(bin) {
+    return (args, stdin, timeoutMs) => new Promise((resolve, reject) => {
+        const child = execFile(bin, args, { cwd: tmpdir(), timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024, env: claudeChildEnv() }, (err, stdout, stderr) => {
+            // A failed call still prints its JSON (is_error, why) on stdout: the reader says it.
+            if (!err || (!err.killed && stdout.trim().startsWith("{")))
+                return resolve(stdout);
+            if (err.killed)
+                return reject(new Transient(`claude -p: killed after ${timeoutMs}ms`));
+            reject(new Error(`claude -p exit ${err.code ?? "?"}: ${(stderr || stdout).slice(0, 400)}`));
+        });
+        child.stdin?.end(stdin);
+    });
+}
+/** Kept short: the prompt carries the task and the output shape. */
+const SYSTEM = "Do exactly what the message asks. Reply with only the answer, no preamble.";
+/**
+ * Claude Code headless (`claude -p`), one process per call, on the person's subscription: its
+ * cost is 0 and its list price kept. Tools, MCP servers, skills and settings are off, and it runs
+ * in a scratch folder, so nothing on disk is touched. About 2 s to start: right for a few big
+ * calls, wrong for thousands of rows. `maxTokens` has no flag here; the prompt bounds the answer.
+ */
+export function claudeCode(model = "sonnet", o = {}) {
+    const id = `claude-code:${model}`;
+    const run = o.run ?? spawnClaude(o.bin ?? "claude");
+    const timeoutMs = o.timeoutMs ?? 300_000;
+    return modelOf({
+        id,
+        provider: "claude-code",
+        takes: TEXT_ONLY,
+        async complete(req) {
+            const text = promptText(req.prompt);
+            if (text === null)
+                throw new Error(`${id} takes text only`);
+            const args = [
+                "-p",
+                ...["--output-format", "json", "--model", model],
+                ...["--system-prompt", req.system ?? SYSTEM],
+                ...["--tools", "", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}'],
+                ...["--disable-slash-commands", "--setting-sources", "", "--no-session-persistence"],
+            ];
+            const started = performance.now();
+            const out = await run(args, text, timeoutMs);
+            return reply(id, out, Math.round(performance.now() - started), true);
+        },
+    });
+}
+//# sourceMappingURL=command.js.map

package/dist/command.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What a model call throws, by what the caller does next. `Transient`: try again later (429, 5xx,
+ * a dropped connection). `Refused`: this key is bad (401, 402, 403); the key ring moves on.
+ * `InputRejected`: the vendor refused this input (400, 413, 422); record it and go on.
+ * `Unsupported`: the model cannot take a part it was given. `Cut`: the output cap stopped the
+ * answer; the text so far and its tokens come with it. Each is checked by shape too (`isCut`):
+ * a host may hold two copies of this package while its pins catch up.
+ */
+import type { PartKind, Usage } from "./types.js";
+export declare class Transient extends Error {
+    /** ISO time, from the server's `retry-after` when it sent one. */
+    readonly retryAfter: string | undefined;
+    readonly status: number | undefined;
+    constructor(message: string, o?: {
+        retryAfter?: string | number | null | undefined;
+        status?: number;
+        cause?: unknown;
+    });
+}
+export declare class Refused extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare class InputRejected extends Error {
+    readonly status: number | undefined;
+    constructor(message: string, status?: number);
+}
+export declare class Unsupported extends Error {
+    readonly kind: PartKind;
+    constructor(model: string, kind: PartKind);
+}
+export declare class Cut extends Error {
+    readonly partial: string;
+    readonly usage: Usage | undefined;
+    constructor(message: string, partial: string, usage?: Usage);
+}
+export declare const isCut: (err: unknown) => err is Cut;
+export declare const isTransient: (err: unknown) => err is Transient;
+export declare const isRefused: (err: unknown) => err is Refused;
+export declare const isInputRejected: (err: unknown) => err is InputRejected;
+/** A `retry-after` value (seconds, an HTTP date or ISO time) as ISO time; undefined when unreadable. */
+export declare function retryAfterIso(value: string | number | null | undefined, now?: () => Date): string | undefined;
+/** A status worth another try: 408, 429 and every 5xx. */
+export declare const transientStatus: (status: number) => boolean;
+/** The error for an HTTP status, by what the caller does next. */
+export declare function statusError(message: string, status: number, retryAfter?: string | number | null): Error;
+/** The error for a response that is not ok. */
+export declare const httpError: (what: string, res: Response, detail?: string) => Error;
+/** A fetch that threw (the network, a timeout): always transient. */
+export declare const transport: (what: string, err: unknown) => Transient;

package/dist/errors.js

@@ -0,0 +1,79 @@
+export class Transient extends Error {
+    /** ISO time, from the server's `retry-after` when it sent one. */
+    retryAfter;
+    status;
+    constructor(message, o = {}) {
+        super(message, o.cause === undefined ? undefined : { cause: o.cause });
+        this.name = "Transient";
+        this.retryAfter = retryAfterIso(o.retryAfter);
+        this.status = o.status;
+    }
+}
+export class Refused extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "Refused";
+        this.status = status;
+    }
+}
+export class InputRejected extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "InputRejected";
+        this.status = status;
+    }
+}
+export class Unsupported extends Error {
+    kind;
+    constructor(model, kind) {
+        super(`${model} takes no ${kind} part`);
+        this.name = "Unsupported";
+        this.kind = kind;
+    }
+}
+export class Cut extends Error {
+    partial;
+    usage;
+    constructor(message, partial, usage) {
+        super(message);
+        this.name = "Cut";
+        this.partial = partial;
+        this.usage = usage;
+    }
+}
+const named = (err, name) => err instanceof Error && err.name === name;
+export const isCut = (err) => named(err, "Cut") && typeof err.partial === "string";
+export const isTransient = (err) => named(err, "Transient");
+export const isRefused = (err) => named(err, "Refused");
+export const isInputRejected = (err) => named(err, "InputRejected");
+/** A `retry-after` value (seconds, an HTTP date or ISO time) as ISO time; undefined when unreadable. */
+export function retryAfterIso(value, now = () => new Date()) {
+    if (value === null || value === undefined || value === "")
+        return undefined;
+    const seconds = typeof value === "number" ? value : Number(value);
+    if (Number.isFinite(seconds))
+        return new Date(now().getTime() + seconds * 1000).toISOString();
+    const t = Date.parse(String(value));
+    return Number.isNaN(t) ? undefined : new Date(t).toISOString();
+}
+/** A status worth another try: 408, 429 and every 5xx. */
+export const transientStatus = (status) => status === 408 || status === 429 || status >= 500;
+const REFUSED = new Set([401, 402, 403]);
+const REJECTED = new Set([400, 413, 422]);
+/** The error for an HTTP status, by what the caller does next. */
+export function statusError(message, status, retryAfter) {
+    if (transientStatus(status))
+        return new Transient(message, { retryAfter, status });
+    if (REFUSED.has(status))
+        return new Refused(message, status);
+    if (REJECTED.has(status))
+        return new InputRejected(message, status);
+    return new Error(message);
+}
+/** The error for a response that is not ok. */
+export const httpError = (what, res, detail) => statusError(`${what}: HTTP ${res.status}${detail ? ` ${detail}` : ""}`, res.status, res.headers.get("retry-after"));
+/** A fetch that threw (the network, a timeout): always transient. */
+export const transport = (what, err) => new Transient(`${what}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/fake.d.ts

@@ -0,0 +1,5 @@
+import type { Model, Request } from "./types.js";
+/** Answers each call from `respond` (the prompt's text and the system), or a fixed string. */
+export declare function fakeModel(respond?: string | ((prompt: string, req: Request) => string | Promise<string>), id?: string): Model;
+/** Answers from a fixed list, in order; an object answer is sent as its JSON. Throws past the end. */
+export declare function scriptedModel(answers: readonly unknown[], id?: string): Model;

package/dist/fake.js

@@ -0,0 +1,33 @@
+/** Models for tests and dry runs: no network, no keys. */
+import { modelOf, promptText } from "./model.js";
+const reply = (text, model) => ({
+    text,
+    usage: {},
+    model,
+    stop: "end_turn",
+    ms: 0,
+    raw: { fake: true },
+});
+/** Answers each call from `respond` (the prompt's text and the system), or a fixed string. */
+export function fakeModel(respond = "{}", id = "fake") {
+    return modelOf({
+        id,
+        provider: "fake",
+        takes: new Set(["text", "image", "video", "audio", "pdf"]),
+        async complete(req) {
+            const text = typeof respond === "string" ? respond : await respond(promptText(req.prompt) ?? "", req);
+            return reply(text, id);
+        },
+    });
+}
+/** Answers from a fixed list, in order; an object answer is sent as its JSON. Throws past the end. */
+export function scriptedModel(answers, id = "scripted") {
+    let i = 0;
+    return fakeModel(() => {
+        const a = answers[i++];
+        if (a === undefined)
+            throw new Error(`scripted model has no answer ${i}`);
+        return typeof a === "string" ? a : JSON.stringify(a);
+    }, id);
+}
+//# sourceMappingURL=fake.js.map

package/dist/fake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake.js","sourceRoot":"","sources":["../src/fake.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGjD,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,KAAa,EAAS,EAAE,CAAC,CAAC;IACrD,IAAI;IACJ,KAAK,EAAE,EAAE;IACT,KAAK;IACL,IAAI,EAAE,UAAU;IAChB,EAAE,EAAE,CAAC;IACL,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;CACpB,CAAC,CAAC;AAEH,8FAA8F;AAC9F,MAAM,UAAU,SAAS,CACvB,UAAiF,IAAI,EACrF,EAAE,GAAG,MAAM;IAEX,OAAO,OAAO,CAAC;QACb,EAAE;QACF,QAAQ,EAAE,MAAM;QAChB,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QAC1D,KAAK,CAAC,QAAQ,CAAC,GAAG;YAChB,MAAM,IAAI,GACR,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;YAC3F,OAAO,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACzB,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,aAAa,CAAC,OAA2B,EAAE,EAAE,GAAG,UAAU;IACxE,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,SAAS,CAAC,GAAG,EAAE;QACpB,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,EAAE,CAAC,CAAC;QAC1E,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC,EAAE,EAAE,CAAC,CAAC;AACT,CAAC"}

package/dist/hear.d.ts

@@ -0,0 +1,63 @@
+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;