llm-tally 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented here. This project follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-10-17
+
+### Added
+
+- Prices for 138 models from 14 providers: OpenAI, Anthropic, Google, xAI, DeepSeek, Mistral, Alibaba Qwen, Moonshot Kimi, Z.ai GLM, MiniMax, Perplexity, Cohere, Amazon Nova and AI21, with cache, long-prompt and per-request prices (as of 2026-10-17).
+- Reasoning effort (`none`, `low`, `medium`, `high`, `max`) in the library (`effort`, `reasoningTokens`), the CLI (`--effort`) and the web calculator; models that don't reason are not charged thinking tokens.
+- `estimateCost`, `compareCosts`, `costFromUsage` and `countTokens`, with one-line shorthands such as `estimateCost(text, "sonnet")`.
+- Short model names (`opus`, `sonnet`, `grok`, `kimi`, `glm`, ...) and support for router, cloud and dated IDs (`x-ai/grok-4.7`, `amazon.nova-pro-v1:0`, `mistral-large-latest`).
+- `llm-tally` CLI with `--model`, `--provider`, `--all`, `--effort`, `--output-tokens`, `--requests`, `--cached`, `--file`, `--json` and a searchable `--list`.
+- A web calculator: `npx llm-tally ui` opens a self-contained page that works offline, also hosted at https://acus9345.github.io/llm-tally/.
+- `LlmTallyError` with error codes and fix-it messages.
+- Works in Node.js 22+, Bun, Deno and browsers; CI covers Windows, macOS and Linux.
+
+[0.1.0]: https://github.com/acus9345/llm-tally/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 acus9345
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# llm-tally
 
-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.
+Estimate what a prompt costs on 138 LLMs from 14 providers (OpenAI, Anthropic, Google, xAI, DeepSeek, Mistral, Qwen, Kimi, GLM, MiniMax, Perplexity, Cohere, Amazon Nova and AI21) in your browser, on the command line, or from code.
+
+- **Reasoning-aware.** Pick a reasoning effort (none → max) and thinking tokens are added only to models that actually reason.
+- **Easy names.** API IDs (`claude-sonnet-5-5`), short names (`sonnet`, `grok`, `kimi`, `glm`) or router/cloud IDs (`x-ai/grok-4.7`, `amazon.nova-pro-v1:0`).
+- **Zero dependencies, typed, offline.** Runs in Node.js, Bun, Deno and browsers.
+
+## Web calculator
+
+Open **https://acus9345.github.io/llm-tally/**: paste a prompt (or drop a text file), pick a reasoning effort and a number of requests, and compare every model, cheapest first. Nothing you type is uploaded.
+
+The same page works offline from the command line:
+
+```sh
+npx llm-tally ui
+```
+
+## Install
+
+```sh
+npm install llm-tally
+```
+
+Run it in your project folder (in a brand-new empty folder, run `npm init -y` first). Requires Node.js 22+, Bun or Deno.
+
+## Command line
+
+```sh
+npx llm-tally "Summarize the plot of Hamlet in three sentences." -o 300 -e medium
+```
+
+```text
+MODEL              PROVIDER   INPUT TOKENS  OUTPUT TOKENS  COST (USD)
+qwen3.8-flash      alibaba               9          4,300    $0.00202
+gpt-6-luna         openai                9          4,300    $0.00215
+claude-haiku-5-5   anthropic            12          4,300    $0.00215
+...
+kimi-k3            moonshot              9          4,300     $0.0645
+claude-opus-5-5    anthropic            12          4,300     $0.0860
+
+Cheapest: qwen3.8-flash ($0.00202), 43x cheaper than claude-opus-5-5.
+Token counts are estimates (usually within 15%). Prices as of 2026-10-17.
+```
+
+`-o 300` is the visible answer; `-e medium` adds about 4,000 thinking tokens to models that reason.
+
+| Option | Meaning |
+| --- | --- |
+| `-m, --model <id>` | Model(s) to price, by ID or short name. Repeat or comma-separate. |
+| `-p, --provider <name>` | Compare every model from a provider. `--all` compares everything. |
+| `-e, --effort <level>` | Reasoning effort: `none` (default), `low`, `medium`, `high`, `max`. |
+| `-o, --output-tokens <n>` | Length of the visible answer: `500`, `2k`. Default `0`. |
+| `-n, --requests <n>` | Also show the total for this many requests: `10k`, `1m`. |
+| `-c, --cached <n>` | Input tokens served from the prompt cache. |
+| `-f, --file <path>` | Read the prompt from a file (UTF-8 or UTF-16). Text can also be piped in. |
+| `-l, --list [filter]` | List models, prices and short names; filter by provider or name. |
+| `--json` | Machine-readable output. |
+| `ui` | Open the web calculator (`--no-open` prints its path instead). |
+
+```sh
+npx llm-tally -f prompt.txt -m sonnet,gpt-5.5 -e high -o 1k
+npx llm-tally -f prompt.txt -p anthropic -e medium -n 10k
+Get-Content prompt.txt | npx llm-tally -m kimi,glm,qwen3.8-max   # cat on macOS/Linux
+npx llm-tally --list qwen
+```
+
+Exit codes: `0` success, `1` unknown model, provider or value, `2` bad command-line usage.
+
+## Library
+
+Save as `tally.mjs` and run `node tally.mjs`:
+
+```js
+import { compareCosts, estimateCost, formatUsd } from "llm-tally";
+
+const prompt = "Summarize the plot of Hamlet in three sentences.";
+
+// One model, one line:
+console.log(formatUsd(estimateCost(prompt, "sonnet").totalCost));
+
+// Several models: a 300-token answer with medium reasoning effort, cheapest first.
+const models = ["gpt-5.5", "sonnet", "gemini-flash", "grok", "deepseek-flash", "kimi", "gpt-4.1"];
+for (const c of compareCosts(prompt, { models, outputTokens: 300, effort: "medium" })) {
+  console.log(c.model.padEnd(18), formatUsd(c.totalCost));
+}
+```
+
+```text
+$0.0000240
+gpt-4.1            $0.00242
+deepseek-flash     $0.00516
+gemini-3.8-flash   $0.0161
+grok-4.7           $0.0258
+claude-sonnet-5-5  $0.0430
+kimi-k3            $0.0645
+gpt-5.5            $0.129
+```
+
+`gpt-4.1` doesn't reason, so it only pays for the 300-token answer. CommonJS works too: `const { estimateCost } = require("llm-tally");`
+
+### API
+
+All amounts are US dollars. Token counts from `countTokens`, `estimateCost` and `compareCosts` are estimates; `costFromUsage` is exact because it uses your provider's reported counts.
+
+- **`estimateCost(input, model | options)`**: price one request. `input` is a string or chat messages (`{ role, content }`). Options: `model`, `outputTokens` (answer length), `effort` (`"none"`…`"max"`) or `reasoningTokens` (exact), `cachedInputTokens`. Returns `{ model, provider, inputTokens, outputTokens, reasoningTokens, inputCost, cachedInputCost, outputCost, requestCost, totalCost, longContext, warnings, ... }`.
+- **`compareCosts(input, models | options)`**: the same for several models, cheapest first. Options add `models` or `providers`.
+- **`costFromUsage({ model, inputTokens, outputTokens?, cachedInputTokens? })`**: exact cost from an API response's usage numbers. `inputTokens` is the total input including cached tokens (for Anthropic: `input_tokens + cache_read_input_tokens`).
+- **`countTokens(input, model?)`**: estimated tokens, imitating that model's tokenizer.
+- **`getModel(id)`**, **`findModel(id)`**, **`listModels(provider?)`**: look up prices and metadata (`reasoning: false` marks models that never think).
+- **`registerModel({ id, provider, input, output, cachedInput?, reasoning?, requestFee?, aliases?, ... })`**: add a model or override a price (USD per 1M tokens).
+- **`EFFORT_REASONING_TOKENS`**, **`PRICES_AS_OF`**, **`formatUsd(amount)`**.
+
+Mistakes throw an `LlmTallyError` with a `code` (`UNKNOWN_MODEL`, `INVALID_INPUT`, `INVALID_OPTION`) and a message that says how to fix it, e.g. `Unknown model "gpt-55". Did you mean "gpt-5.5", "gpt-5", "gpt-5.4"?`.
+
+## Providers and short names
+
+| Provider | Models | Short names |
+| --- | --- | --- |
+| OpenAI | 41 (GPT-6, GPT-5.x, GPT-4.x, o-series, legacy) | — use the API ID, e.g. `gpt-5.5` |
+| Anthropic | 16 (Claude Fable, Opus, Sonnet, Haiku) | `fable`, `opus`, `sonnet`, `haiku` |
+| Google | 10 (Gemini 4, 3.x, 2.5) | `gemini-pro`, `gemini-flash`, `gemini-flash-lite` |
+| xAI | 8 (Grok 4.x) | `grok` |
+| DeepSeek | 2 (V4 Pro, Flash) | `deepseek-pro` |
+| Mistral | 8 (Large, Medium, Small, Ministral, Codestral) | `mistral-large-latest` and other `-latest` IDs |
+| Alibaba Qwen | 13 (Qwen 3.x Max, Plus, Flash, Coder) | — |
+| Moonshot Kimi | 4 (K3, K2.x) | `kimi` |
+| Z.ai GLM | 16 (GLM-5.x, GLM-4.x) | `glm` |
+| MiniMax | 6 (M3, M2.x) | `minimax` |
+| Perplexity | 3 (Sonar, Sonar Pro, Sonar Reasoning Pro) | — |
+| Cohere | 4 (Command A, Command R) | `command-a`, `command-r` |
+| Amazon | 5 (Nova 2 Lite, Premier, Pro, Lite, Micro) | Bedrock IDs like `amazon.nova-pro-v1:0` |
+| AI21 | 2 (Jamba Large, Mini) | — |
+
+Short names point at the newest model in that line. `npx llm-tally --list` shows everything. IDs with provider prefixes (OpenRouter, LiteLLM, Vertex AI, Bedrock) and date suffixes (`gpt-4o-2024-08-06`, `claude-sonnet-4-5-20250929`) also work.
+
+## How accurate is it?
+
+- **Prices** come from each provider's public pricing page (standard tier, as of `PRICES_AS_OF`), including long-prompt tiers. Not included: batch discounts, cache-write surcharges, image/audio pricing. DeepSeek uses peak-hour rates (off-peak is half), Mistral Large its current sale price, Qwen the International region, Perplexity the low search-context request fee.
+- **Thinking tokens** per effort level are typical values (low 1k, medium 4k, high 12k, max 32k); real usage varies a lot by task. Pass `reasoningTokens` when you know yours.
+- **Token counts** are tuned against OpenAI's o200k tokenizer: usually within ~10% for English, code and JSON, ~20% for other languages, and rougher for providers other than OpenAI, Anthropic and Google. For exact counts, use your provider's token-counting endpoint and `costFromUsage`.
+
+## Troubleshooting
+
+- **`Unknown model "..."`**: check `npx llm-tally --list <part of the name>`. New models arrive in new versions; until then use `registerModel()`.
+- **`No input`**: pass the prompt in quotes, use `--file`, or pipe text in.
+- **`$` in PowerShell text**: use single quotes (`'costs $5'`) or `--file`.
+- **Non-English text piped in Windows PowerShell 5.1 becomes `?`**: use `--file`, or run `$OutputEncoding = [Text.Encoding]::UTF8` first.
+- **`ERR_REQUIRE_ESM` or syntax errors**: upgrade to Node.js 22 or newer.
+
+## License
+
+[MIT](LICENSE)

package/dist/catalog.d.ts

@@ -0,0 +1,21 @@
+import { type ModelInfo, type Provider } from "./models.js";
+/**
+ * Looks up a model by ID or short name. Accepts aliases (`sonnet`, `grok`, `gemini-flash`),
+ * provider prefixes (`openai/gpt-5.5`, `x-ai/grok-4.7`, `models/gemini-2.5-pro`),
+ * Bedrock IDs (`anthropic.claude-opus-5-5`) and dated snapshots (`gpt-4o-2024-08-06`, `mistral-large-latest`).
+ *
+ * @throws {LlmTallyError} `UNKNOWN_MODEL` with the closest known IDs when nothing matches.
+ */
+export declare function getModel(id: string): ModelInfo;
+/** Like {@link getModel} but returns `undefined` instead of throwing. */
+export declare function findModel(id: string): ModelInfo | undefined;
+/** Lists known models, optionally only those from one provider. */
+export declare function listModels(provider?: Provider): ModelInfo[];
+/**
+ * Adds a model or replaces a built-in one (for example to apply a negotiated discount).
+ * Prices are USD per 1 million tokens.
+ *
+ * @example
+ * registerModel({ id: "my-finetune", provider: "openai", input: 3, output: 12 });
+ */
+export declare function registerModel(model: ModelInfo): void;

package/dist/catalog.js

@@ -0,0 +1,132 @@
+import { describe, LlmTallyError } from "./errors.js";
+import { BUILTIN_MODELS } from "./models.js";
+const registry = new Map();
+// Lower-case alias ("sonnet", "mistral-small-2603") -> model ID.
+const aliases = new Map();
+for (const model of BUILTIN_MODELS)
+    add(model);
+function add(model) {
+    registry.set(model.id, model);
+    // Lookups are case-insensitive, so "minimax-m3" finds "MiniMax-M3".
+    for (const alias of [model.id, ...(model.aliases ?? [])])
+        aliases.set(alias.toLowerCase(), model.id);
+}
+function lookup(key) {
+    const viaAlias = aliases.get(key);
+    return registry.get(key) ?? (viaAlias === undefined ? undefined : registry.get(viaAlias));
+}
+// Prefixes that other platforms (Vertex, Bedrock, OpenRouter, LiteLLM) put in front of the same model ID.
+const PREFIXES = [
+    /^models\//,
+    /^(openai|anthropic|google|gemini|vertex_ai|bedrock|xai|x-ai|deepseek|mistral|mistralai)\//,
+    /^(qwen|alibaba|dashscope|moonshot|moonshotai|zai|z-ai|zhipu|minimax|perplexity|cohere|amazon|ai21)\//,
+    /^(us\.|eu\.|apac\.|global\.)?(anthropic|amazon|cohere|ai21)\./,
+];
+// Dated snapshots: "gpt-4o-2024-08-06", "claude-haiku-4-5-20251001", "claude-opus-4-5@20251101", "-latest".
+const SUFFIXES = [/-\d{4}-\d{2}-\d{2}$/, /[-@]\d{8}$/, /-latest$/, /-v\d+(:\d+)?$/, /-preview-\d{2}-\d{4}$/];
+function normalize(id) {
+    let key = id.trim().toLowerCase();
+    for (const prefix of PREFIXES)
+        key = key.replace(prefix, "");
+    return key;
+}
+/**
+ * Looks up a model by ID or short name. Accepts aliases (`sonnet`, `grok`, `gemini-flash`),
+ * provider prefixes (`openai/gpt-5.5`, `x-ai/grok-4.7`, `models/gemini-2.5-pro`),
+ * Bedrock IDs (`anthropic.claude-opus-5-5`) and dated snapshots (`gpt-4o-2024-08-06`, `mistral-large-latest`).
+ *
+ * @throws {LlmTallyError} `UNKNOWN_MODEL` with the closest known IDs when nothing matches.
+ */
+export function getModel(id) {
+    if (typeof id !== "string" || id.trim() === "") {
+        throw new LlmTallyError("INVALID_OPTION", `model must be a model ID string like "gpt-5.5", but got ${describe(id)}. Run \`npx llm-tally --list\` to see known models.`);
+    }
+    const found = findModel(id);
+    if (found)
+        return found;
+    const suggestions = closestIds(normalize(id), 3);
+    throw new LlmTallyError("UNKNOWN_MODEL", `Unknown model "${id}". Did you mean ${suggestions.map((s) => `"${s}"`).join(", ")}? ` +
+        "Run `npx llm-tally --list` to see all models, or add your own with registerModel().");
+}
+/** Like {@link getModel} but returns `undefined` instead of throwing. */
+export function findModel(id) {
+    if (typeof id !== "string")
+        return undefined;
+    const exact = registry.get(id);
+    if (exact)
+        return exact;
+    let key = normalize(id);
+    const direct = lookup(key);
+    if (direct)
+        return direct;
+    // Strip one suffix at a time ("...-20240620-v1:0" needs two passes) until something matches.
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const suffix of SUFFIXES) {
+            const stripped = key.replace(suffix, "");
+            if (stripped !== key) {
+                key = stripped;
+                changed = true;
+                const hit = lookup(key);
+                if (hit)
+                    return hit;
+            }
+        }
+    }
+    return undefined;
+}
+/** Lists known models, optionally only those from one provider. */
+export function listModels(provider) {
+    const all = [...registry.values()];
+    return provider === undefined ? all : all.filter((m) => m.provider === provider.toLowerCase());
+}
+/**
+ * Adds a model or replaces a built-in one (for example to apply a negotiated discount).
+ * Prices are USD per 1 million tokens.
+ *
+ * @example
+ * registerModel({ id: "my-finetune", provider: "openai", input: 3, output: 12 });
+ */
+export function registerModel(model) {
+    if (model === null || typeof model !== "object") {
+        throw new LlmTallyError("INVALID_INPUT", `registerModel() needs a model object, but got ${describe(model)}.`);
+    }
+    if (typeof model.id !== "string" || model.id.trim() === "") {
+        throw new LlmTallyError("INVALID_OPTION", 'registerModel(): "id" must be a non-empty string, e.g. "my-model".');
+    }
+    if (typeof model.provider !== "string" || model.provider === "") {
+        throw new LlmTallyError("INVALID_OPTION", `registerModel("${model.id}"): "provider" must be a string, e.g. "openai".`);
+    }
+    for (const field of ["input", "output", "cachedInput"]) {
+        const value = model[field];
+        if (value === undefined && field === "cachedInput")
+            continue;
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+            throw new LlmTallyError("INVALID_OPTION", `registerModel("${model.id}"): "${field}" must be a price in USD per 1M tokens (a number >= 0), but got ${describe(value)}.`);
+        }
+    }
+    if (model.aliases !== undefined && !Array.isArray(model.aliases)) {
+        throw new LlmTallyError("INVALID_OPTION", `registerModel("${model.id}"): "aliases" must be an array of strings.`);
+    }
+    add({ ...model, provider: model.provider.toLowerCase() });
+}
+function closestIds(key, count) {
+    return [...aliases.keys()]
+        .map((id) => ({ id, d: distance(key, id) }))
+        .sort((a, b) => a.d - b.d)
+        .slice(0, count)
+        .map((x) => x.id);
+}
+/** Levenshtein edit distance. */
+function distance(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[b.length];
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./run.js";
+process.exitCode = await main(process.argv.slice(2));

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+/** Machine-readable reason for an {@link LlmTallyError}. */
+export type LlmTallyErrorCode = "UNKNOWN_MODEL" | "INVALID_INPUT" | "INVALID_OPTION";
+/**
+ * The only error type llm-tally throws for caller mistakes.
+ *
+ * `message` says what went wrong and how to fix it; `code` lets you branch on the cause.
+ */
+export declare class LlmTallyError extends Error {
+    /** Why the call failed. */
+    readonly code: LlmTallyErrorCode;
+    constructor(code: LlmTallyErrorCode, message: string);
+}
+/** Throws unless `value` is a finite number >= 0. */
+export declare function assertTokenCount(name: string, value: unknown): asserts value is number;
+/** Short, safe description of a value for error messages. */
+export declare function describe(value: unknown): string;

package/dist/errors.js

@@ -0,0 +1,32 @@
+/**
+ * The only error type llm-tally throws for caller mistakes.
+ *
+ * `message` says what went wrong and how to fix it; `code` lets you branch on the cause.
+ */
+export class LlmTallyError extends Error {
+    /** Why the call failed. */
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "LlmTallyError";
+        this.code = code;
+    }
+}
+/** Throws unless `value` is a finite number >= 0. */
+export function assertTokenCount(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new LlmTallyError("INVALID_OPTION", `${name} must be a number of tokens >= 0, but got ${describe(value)}. Pass a whole number like 500.`);
+    }
+}
+/** Short, safe description of a value for error messages. */
+export function describe(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return value.length > 40 ? `"${value.slice(0, 40)}…"` : `"${value}"`;
+    if (Array.isArray(value))
+        return "an array";
+    if (typeof value === "object")
+        return "an object";
+    return String(value);
+}

package/dist/estimate.d.ts

@@ -0,0 +1,136 @@
+import { type ReasoningEffort } from "./models.js";
+/** One part of a multi-part message. Only text parts are counted. */
+export interface ContentPart {
+    type: string;
+    text?: string;
+}
+/** A chat message in the OpenAI / Anthropic / Gemini-style shape. */
+export interface ChatMessage {
+    role: string;
+    content: string | ContentPart[];
+}
+/** What you can measure: plain text, or a list of chat messages. */
+export type TallyInput = string | readonly ChatMessage[];
+/** Options for {@link countTokens}. */
+export interface CountOptions {
+    /** Model whose tokenizer to imitate. Defaults to OpenAI's o200k (GPT-4o and newer). */
+    model?: string;
+}
+/** Reply-related options shared by {@link estimateCost} and {@link compareCosts}. */
+export interface ReplyOptions {
+    /** Length of the visible answer, in tokens. Defaults to 0. */
+    outputTokens?: number;
+    /**
+     * How hard reasoning models think: `"none"`, `"low"`, `"medium"`, `"high"` or `"max"`.
+     * Adds the typical thinking tokens for that level ({@link EFFORT_REASONING_TOKENS}); models that
+     * cannot think get none. Defaults to `"none"`.
+     */
+    effort?: ReasoningEffort;
+    /** Exact thinking tokens per request, instead of `effort`. */
+    reasoningTokens?: number;
+    /** How many of the input tokens are read from the prompt cache. Defaults to 0. */
+    cachedInputTokens?: number;
+}
+/** Options for {@link estimateCost}. */
+export interface EstimateOptions extends ReplyOptions {
+    /** Model ID to price, e.g. `"gpt-5.5"` or `"sonnet"`. */
+    model: string;
+}
+/** Options for {@link compareCosts}. */
+export interface CompareOptions extends ReplyOptions {
+    /** Models to compare. Defaults to a few current models from each provider. */
+    models?: readonly string[];
+    /** Compare every known model from these providers instead, e.g. `["anthropic", "xai"]`. */
+    providers?: readonly string[];
+}
+/** Token counts reported by a provider's API, for exact pricing with {@link costFromUsage}. */
+export interface Usage {
+    /** Model ID that served the request. */
+    model: string;
+    /**
+     * All input tokens, including any read from cache.
+     * (Anthropic reports cache reads separately: pass `input_tokens + cache_read_input_tokens`.)
+     */
+    inputTokens: number;
+    /** Output tokens, including reasoning/thinking tokens. Defaults to 0. */
+    outputTokens?: number;
+    /** Input tokens served from the prompt cache. Defaults to 0. */
+    cachedInputTokens?: number;
+}
+/** A priced request. All costs are in US dollars. */
+export interface CostEstimate {
+    /** Model ID as found in the catalog. */
+    model: string;
+    /** Provider that serves the model. */
+    provider: string;
+    /** Total input tokens (including cached ones). */
+    inputTokens: number;
+    /** Input tokens priced at the cache rate. */
+    cachedInputTokens: number;
+    /** Billed output tokens: the visible answer plus any thinking. */
+    outputTokens: number;
+    /** The part of `outputTokens` spent thinking (0 for models that don't reason). */
+    reasoningTokens: number;
+    /** Cost of the uncached input tokens. */
+    inputCost: number;
+    /** Cost of the cached input tokens. */
+    cachedInputCost: number;
+    /** Cost of the output tokens, including thinking. */
+    outputCost: number;
+    /** Fixed per-request fee (for example a web-search fee); usually 0. */
+    requestCost: number;
+    /** `inputCost + cachedInputCost + outputCost + requestCost`. */
+    totalCost: number;
+    /** Always `"USD"`. */
+    currency: "USD";
+    /** `true` when the input token count is an estimate rather than reported by the API. */
+    approximate: boolean;
+    /** `true` when the long-context price tier was applied. */
+    longContext: boolean;
+    /** Things worth knowing about this estimate (for example, input larger than the context window). */
+    warnings: string[];
+}
+/**
+ * Estimates how many tokens `input` uses.
+ *
+ * @param options A model ID (`"sonnet"`) or `{ model }`. Without a model, counts like GPT-4o and newer.
+ * @example
+ * countTokens("Hello, world!"); // 4
+ * countTokens(messages, "claude-opus-5-5");
+ */
+export declare function countTokens(input: TallyInput, options?: CountOptions | string): number;
+/**
+ * Estimates what sending `input` to `model` costs, in US dollars.
+ *
+ * @param options A model ID (`"gpt-5.5"`, `"sonnet"`) or `{ model, outputTokens?, effort?, cachedInputTokens? }`.
+ * @example
+ * estimateCost("Summarize this article...", "gpt-5.5").totalCost;
+ * estimateCost("Summarize this article...", { model: "sonnet", outputTokens: 300, effort: "medium" });
+ */
+export declare function estimateCost(input: TallyInput, options: EstimateOptions | string): CostEstimate;
+/**
+ * Prices the same request on several models, cheapest first.
+ *
+ * @param options A list of model IDs, or `{ models?, providers?, outputTokens?, effort?, cachedInputTokens? }`.
+ * @example
+ * compareCosts(prompt, ["gpt-5.5", "sonnet", "grok"]);
+ * compareCosts(prompt, { providers: ["anthropic"], outputTokens: 500 });
+ */
+export declare function compareCosts(input: TallyInput, options?: CompareOptions | readonly string[]): CostEstimate[];
+/**
+ * Exact cost of a finished request, from the token counts in the API response.
+ *
+ * @example
+ * costFromUsage({ model: "gpt-5.5", inputTokens: res.usage.input_tokens, outputTokens: res.usage.output_tokens });
+ */
+export declare function costFromUsage(usage: Usage): CostEstimate;
+/**
+ * Formats a dollar amount for display: cents from $1 up, three significant digits below,
+ * so small costs stay comparable ($0.0100 vs $0.0201).
+ *
+ * @example
+ * formatUsd(12.5);     // "$12.50"
+ * formatUsd(0.010048); // "$0.0100"
+ * formatUsd(0.000123); // "$0.000123"
+ */
+export declare function formatUsd(amount: number): string;