diff --git a/packages/ai/src/public.ts b/packages/ai/src/public.ts index a315a147e1b..1f0915efb4e 100644 --- a/packages/ai/src/public.ts +++ b/packages/ai/src/public.ts @@ -3,6 +3,7 @@ export { ProtocolID, RouteID, Model, + calculateCost, ModelID, ProviderID, ResponseID, @@ -101,6 +102,16 @@ export type { RequestOptions, ModelProviderOptions, ModelType, + Cost, + CostCondition, + CostWhen, + CostFactor, + CostUnit, + CachePrices, + CacheCost, + InputCost, + OutputCost, + ModalityCost, LLMRequest, MediaPartInput, RequestTimeout, diff --git a/packages/ai/src/schema/cost.ts b/packages/ai/src/schema/cost.ts new file mode 100644 index 00000000000..cc5a48a96da --- /dev/null +++ b/packages/ai/src/schema/cost.ts @@ -0,0 +1,182 @@ +import type { Usage } from "./events.js" +import type { CacheTTL, OpenString } from "./options.js" + +/** A models.dev v2 cost condition: exactly one operator. Strings compare lexicographically. */ +export type CostCondition = + | { readonly equals: string | number | boolean } + | { readonly in: ReadonlyArray } + | { readonly gt: number | string } + | { readonly gte: number | string } + | { readonly lt: number | string } + | { readonly lte: number | string } + | { readonly minItems: number } + +/** When a cost override or multiplier applies, from models.dev v2 `when` in camelCase. */ +export interface CostWhen { + readonly context?: CostCondition + readonly duration?: CostCondition + readonly megapixels?: CostCondition + readonly inputImages?: CostCondition + readonly serviceTier?: CostCondition + readonly region?: CostCondition + readonly date?: CostCondition + readonly utcDays?: CostCondition + readonly utcHours?: CostCondition + readonly holiday?: CostCondition + readonly thinking?: CostCondition + readonly resolution?: CostCondition + readonly quality?: CostCondition + readonly aspectRatio?: CostCondition + readonly generateAudio?: CostCondition + readonly mode?: CostCondition + readonly inputVideo?: CostCondition + readonly fps?: CostCondition + readonly steps?: CostCondition + readonly searchContextSize?: CostCondition + readonly speakerLabels?: CostCondition + readonly keytermsPrompt?: CostCondition + readonly domain?: CostCondition + readonly websocket?: CostCondition + readonly style?: CostCondition + readonly voiceControl?: CostCondition + readonly all?: ReadonlyArray + readonly any?: ReadonlyArray + readonly not?: CostWhen +} + +/** USD per 1M tokens or characters, else per unit. A cache write price may be keyed by TTL. */ +export interface CachePrices { + readonly read?: number + readonly write?: number | { readonly [ttl: CacheTTL]: number } + readonly storage?: number +} + +export interface CacheCost extends CachePrices { + readonly explicit?: CachePrices +} + +export type CostUnit = OpenString<"token" | "character" | "image" | "megapixel" | "second" | "minute"> + +export interface InputCost { + readonly unit?: CostUnit + readonly price: number + readonly cache?: CacheCost + readonly overrides?: ReadonlyArray<{ readonly when: CostWhen; readonly price?: number; readonly cache?: CacheCost }> +} + +export interface OutputCost { + readonly unit?: CostUnit + readonly price: number + readonly reasoning?: number + readonly overrides?: ReadonlyArray<{ readonly when: CostWhen; readonly price?: number; readonly reasoning?: number }> +} + +export interface ModalityCost { + readonly input?: InputCost + readonly output?: OutputCost +} + +/** A number multiplies every price; an object multiplies only the prices it names. */ +export type CostFactor = number | { readonly [key: string]: CostFactor } + +/** Model pricing, from models.dev v2 `cost` in camelCase. */ +export interface Cost { + readonly text?: ModalityCost + readonly image?: ModalityCost + readonly audio?: ModalityCost + readonly video?: ModalityCost + /** USD per 1,000 web searches. */ + readonly webSearch?: { + readonly price: number + readonly overrides?: ReadonlyArray<{ readonly when: CostWhen; readonly price?: number }> + } + readonly multipliers?: ReadonlyArray<{ readonly when: CostWhen; readonly factor: CostFactor }> +} + +/** + * USD for `usage` at a model's listed prices. Prices per-token text: input, output (reasoning tokens at the output + * price), cache reads and cache writes (the first TTL listed), with `context` overrides as tiers that apply above + * their size. Other units, conditions and multipliers are not priced. A `usage.cost` the endpoint reported is more + * accurate than this when present. + */ +export const calculateCost = (cost: Cost | undefined, usage: Usage) => { + const input = safe(usage.nonCachedInputTokens) + const output = safe(usage.visibleOutputTokens) + const reasoning = safe(usage.reasoningTokens) + const read = safe(usage.cacheReadInputTokens) + const write = safe(usage.cacheWriteInputTokens) + const prices = pricesAt(cost, input + read + write) + if (!prices) return 0 + return ( + (input * finite(prices.input) + + (output + reasoning) * finite(prices.output) + + read * finite(prices.read) + + write * finite(prices.write)) / + 1_000_000 + ) +} + +interface Prices { + readonly input: number + readonly output: number + readonly read: number + readonly write: number +} + +const finite = (value: number) => (Number.isFinite(value) ? value : 0) +const safe = (value: number | undefined) => Math.max(0, finite(value ?? 0)) +const perToken = (unit: CostUnit | undefined) => unit === undefined || unit === "token" + +// The text prices for a request whose context is `context` tokens: the largest tier it exceeds, else the base. +function pricesAt(cost: Cost | undefined, context: number): Prices | undefined { + const text = cost?.text + if (!text?.input || !text.output || !perToken(text.input.unit) || !perToken(text.output.unit)) return undefined + const base: Prices = { + input: text.input.price, + output: text.output.price, + read: text.input.cache?.read ?? 0, + write: cacheWrite(text.input.cache) ?? 0, + } + // An override merges field by field, so a tier keeps every base price it doesn't set. + const tiers = new Map() + const tier = (when: CostWhen) => { + const size = Object.keys(when).length === 1 ? contextSize(when.context) : undefined + if (size === undefined) return undefined + const entry = tiers.get(size) ?? base + tiers.set(size, entry) + return [size, entry] as const + } + for (const override of text.input.overrides ?? []) { + const found = tier(override.when) + if (!found) continue + tiers.set(found[0], { + ...found[1], + input: override.price ?? found[1].input, + read: override.cache?.read ?? found[1].read, + write: cacheWrite(override.cache) ?? found[1].write, + }) + } + for (const override of text.output.overrides ?? []) { + const found = tier(override.when) + if (found) tiers.set(found[0], { ...found[1], output: override.price ?? found[1].output }) + } + const size = Math.max(...[...tiers.keys()].filter((size) => context > size)) + return tiers.get(size) ?? base +} + +// A context tier is a `context` condition with a numeric `gt` or `gte`; either way it applies above that size. +function contextSize(condition: CostCondition | undefined) { + if (typeof condition !== "object" || condition === null) return undefined + const gt = "gt" in condition ? condition.gt : undefined + const gte = "gte" in condition ? condition.gte : undefined + if ((gt !== undefined && !isFiniteNumber(gt)) || (gte !== undefined && !isFiniteNumber(gte))) return undefined + return gt ?? gte +} + +const isFiniteNumber = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) + +// One cache write price: the first TTL listed, else the explicit cache's. +function cacheWrite(cache: CacheCost | undefined) { + const first = (write: CachePrices["write"]) => (typeof write === "object" ? Object.values(write)[0] : write) + return first(cache?.write) ?? first(cache?.explicit?.write) +} diff --git a/packages/ai/src/schema/index.ts b/packages/ai/src/schema/index.ts index 19c5135c95c..31d1180d0a6 100644 --- a/packages/ai/src/schema/index.ts +++ b/packages/ai/src/schema/index.ts @@ -2,6 +2,7 @@ export * from "./ids.js" export * from "./options.js" export * from "./api.js" export * from "./model.js" +export * from "./cost.js" export * from "./messages.js" export * from "./events.js" export * from "./errors.js" diff --git a/packages/ai/src/schema/model.ts b/packages/ai/src/schema/model.ts index 905befcf776..9c292ac9b17 100644 --- a/packages/ai/src/schema/model.ts +++ b/packages/ai/src/schema/model.ts @@ -1,5 +1,6 @@ import { Schema } from "effect" import type { Api } from "./api.js" +import type { Cost } from "./cost.js" import { mergeRequestOptions, type Capabilities, @@ -93,6 +94,8 @@ export namespace Model { readonly limit: Limit readonly modalities: Modalities readonly compatibility?: Compatibility + /** Listed prices, as models.dev v2 `cost`. `calculateCost(model.cost, usage)` turns usage into USD. */ + readonly cost?: Cost /** The provider's implementation of `api`, such as a vendor dialect. Absent means the package's standard one. */ readonly [implementation]?: Route } @@ -124,6 +127,7 @@ export namespace Model { readonly limit?: Limit readonly modalities?: Modalities readonly compatibility?: Compatibility + readonly cost?: Cost readonly [implementation]?: Route } diff --git a/packages/ai/test/cost.test.ts b/packages/ai/test/cost.test.ts new file mode 100644 index 00000000000..15a2db12e3e --- /dev/null +++ b/packages/ai/test/cost.test.ts @@ -0,0 +1,49 @@ +import { describe, expect, test } from "bun:test" +import { calculateCost, Usage, type Cost } from "../src/schema/index.js" + +const cost: Cost = { + text: { + input: { + price: 2, + cache: { read: 0.2, write: { "5m": 2.5, "1h": 4 } }, + overrides: [{ when: { context: { gt: 200_000 } }, price: 4, cache: { read: 0.4 } }], + }, + output: { price: 10, overrides: [{ when: { context: { gt: 200_000 } }, price: 15 }] }, + }, +} + +const usage = (input: Partial[0]>) => new Usage(input) + +describe("calculateCost", () => { + test("prices input, output with reasoning, cache reads and the first cache write TTL", () => { + expect( + calculateCost( + cost, + usage({ + nonCachedInputTokens: 1_000, + outputTokens: 500, + reasoningTokens: 200, + cacheReadInputTokens: 10_000, + cacheWriteInputTokens: 2_000, + }), + ), + ).toBe((1_000 * 2 + 500 * 10 + 10_000 * 0.2 + 2_000 * 2.5) / 1_000_000) + }) + + test("uses the tier above its context size and keeps the prices it doesn't set", () => { + expect( + calculateCost(cost, usage({ nonCachedInputTokens: 150_000, cacheReadInputTokens: 60_000, outputTokens: 1_000 })), + ).toBe((150_000 * 4 + 1_000 * 15 + 60_000 * 0.4) / 1_000_000) + expect(calculateCost(cost, usage({ nonCachedInputTokens: 200_000 }))).toBe((200_000 * 2) / 1_000_000) + }) + + test("prices nothing it can't price per token", () => { + expect(calculateCost(undefined, usage({ nonCachedInputTokens: 1_000 }))).toBe(0) + expect( + calculateCost( + { text: { input: { unit: "character", price: 1 }, output: { price: 1 } } }, + usage({ nonCachedInputTokens: 1_000 }), + ), + ).toBe(0) + }) +})