@graphorin/pricing 0.6.0 → 0.7.0

package/src/convert-genai-prices.ts

@@ -0,0 +1,164 @@
+/**
+ * W-097: pure converter from the `@pydantic/genai-prices` published
+ * dataset into graphorin-native {@link ModelPrice} entries, so
+ * `graphorin pricing refresh --url <genai-prices raw URL>` actually
+ * works - previously the docs pointed operators at that dataset while
+ * `refreshPricing` only accepted the native shape, leaving every
+ * operator to write their own transformer.
+ *
+ * Supported subset (documented deliberately - the converter is
+ * tolerant and SKIPS what it cannot represent, it never throws on a
+ * strange model entry):
+ *
+ * ```jsonc
+ * {
+ *   "providers": [
+ *     {
+ *       "id": "anthropic",             // or "provider_id" / "name"
+ *       "models": [
+ *         {
+ *           "id": "claude-sonnet-4-5", // or "model" / "name"
+ *           "prices": {
+ *             "input_mtok": 3,          // USD per million tokens
+ *             "output_mtok": 15,
+ *             "cache_read_mtok": 0.3,   // optional
+ *             "cache_write_mtok": 3.75  // optional
+ *           }
+ *         }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * Per-Mtok figures divide by 1e6 into per-token USD. Model entries
+ * whose `prices` is an ARRAY (conditional / time-tiered pricing) are
+ * used only when the array holds exactly one usable record; everything
+ * else - tiered objects, missing input/output figures - lands in the
+ * `skipped` counter instead of failing the refresh. The dataset is
+ * dollar-denominated; the currency guard lives in `refreshPricing`.
+ *
+ * @packageDocumentation
+ */
+
+import type { ModelPrice } from './types.js';
+
+const MTOK = 1_000_000;
+
+/** Result of {@link convertGenaiPrices}. @stable */
+export interface GenaiPricesConversion {
+  readonly entries: ReadonlyArray<ModelPrice>;
+  /** Model entries the supported subset could not represent. */
+  readonly skipped: number;
+}
+
+/**
+ * Cheap structural detector: does this body look like the
+ * genai-prices dataset (a `providers` array of objects carrying
+ * `models` arrays)?
+ *
+ * @stable
+ */
+export function isGenaiPricesShape(body: unknown): boolean {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) return false;
+  const providers = (body as { providers?: unknown }).providers;
+  if (!Array.isArray(providers) || providers.length === 0) return false;
+  return providers.every(
+    (p) => typeof p === 'object' && p !== null && Array.isArray((p as { models?: unknown }).models),
+  );
+}
+
+/**
+ * Convert a genai-prices dataset body. Tolerant: unrepresentable model
+ * entries are counted in `skipped`, never thrown on.
+ *
+ * @stable
+ */
+export function convertGenaiPrices(body: unknown): GenaiPricesConversion {
+  if (!isGenaiPricesShape(body)) {
+    throw new Error('convertGenaiPrices: body does not match the genai-prices dataset shape');
+  }
+  const providers = (body as { providers: ReadonlyArray<unknown> }).providers;
+  const entries: ModelPrice[] = [];
+  let skipped = 0;
+  for (const rawProvider of providers) {
+    const provider = rawProvider as {
+      id?: unknown;
+      provider_id?: unknown;
+      name?: unknown;
+      models: ReadonlyArray<unknown>;
+    };
+    const providerId = firstString(provider.id, provider.provider_id, provider.name);
+    if (providerId === undefined) {
+      skipped += provider.models.length;
+      continue;
+    }
+    for (const rawModel of provider.models) {
+      const entry = convertModel(providerId, rawModel);
+      if (entry === null) skipped += 1;
+      else entries.push(entry);
+    }
+  }
+  return Object.freeze({ entries: Object.freeze(entries), skipped });
+}
+
+function convertModel(providerId: string, rawModel: unknown): ModelPrice | null {
+  if (typeof rawModel !== 'object' || rawModel === null) return null;
+  const model = rawModel as {
+    id?: unknown;
+    model?: unknown;
+    name?: unknown;
+    prices?: unknown;
+  };
+  const modelId = firstString(model.id, model.model, model.name);
+  if (modelId === undefined) return null;
+  const prices = selectPriceRecord(model.prices);
+  if (prices === null) return null;
+  const input = perToken(prices.input_mtok);
+  const output = perToken(prices.output_mtok);
+  if (input === undefined || output === undefined) return null;
+  const cacheRead = perToken(prices.cache_read_mtok);
+  const cacheWrite = perToken(prices.cache_write_mtok);
+  return Object.freeze({
+    provider: providerId.toLowerCase(),
+    model: modelId.toLowerCase(),
+    inputUsdPerToken: input,
+    outputUsdPerToken: output,
+    ...(cacheRead !== undefined ? { cachedReadUsdPerToken: cacheRead } : {}),
+    ...(cacheWrite !== undefined ? { cacheWriteUsdPerToken: cacheWrite } : {}),
+  });
+}
+
+interface GenaiPriceRecord {
+  readonly input_mtok?: unknown;
+  readonly output_mtok?: unknown;
+  readonly cache_read_mtok?: unknown;
+  readonly cache_write_mtok?: unknown;
+}
+
+/**
+ * Pick the price record to convert. A plain object is used directly;
+ * an array is usable only when it holds exactly ONE record (multiple
+ * records mean conditional / time-tiered pricing the flat
+ * {@link ModelPrice} cannot express - skipped, per the module doc).
+ */
+function selectPriceRecord(prices: unknown): GenaiPriceRecord | null {
+  if (Array.isArray(prices)) {
+    if (prices.length !== 1) return null;
+    return selectPriceRecord(prices[0]);
+  }
+  if (typeof prices === 'object' && prices !== null) return prices as GenaiPriceRecord;
+  return null;
+}
+
+/** Per-Mtok USD figure -> per-token USD; non-finite/tiered -> undefined. */
+function perToken(mtok: unknown): number | undefined {
+  return typeof mtok === 'number' && Number.isFinite(mtok) && mtok >= 0 ? mtok / MTOK : undefined;
+}
+
+function firstString(...values: ReadonlyArray<unknown>): string | undefined {
+  for (const value of values) {
+    if (typeof value === 'string' && value.length > 0) return value;
+  }
+  return undefined;
+}

package/src/diff.ts

@@ -0,0 +1,73 @@
+/**
+ * `diffPricing(...)` - produce a row-by-row delta between two pricing
+ * snapshots. Used by the upcoming `graphorin pricing diff` CLI to
+ * surface upstream changes after a `refresh`.
+ *
+ * @packageDocumentation
+ */
+
+import type { ModelPrice, PricingDiffEntry, PricingSnapshot } from './types.js';
+
+const COMPARED_FIELDS: ReadonlyArray<keyof ModelPrice> = [
+  'inputUsdPerToken',
+  'outputUsdPerToken',
+  'cachedReadUsdPerToken',
+  'cacheWriteUsdPerToken',
+  'reasoningUsdPerToken',
+  'region',
+  'notes',
+];
+
+/**
+ * Compare two snapshots and return one entry per (provider, model)
+ * pair that has been added, removed, or changed. The result is sorted
+ * by `(provider, model, kind)` for deterministic output.
+ *
+ * @stable
+ */
+export function diffPricing(
+  before: PricingSnapshot,
+  after: PricingSnapshot,
+): ReadonlyArray<PricingDiffEntry> {
+  const beforeMap = indexBy(before.entries);
+  const afterMap = indexBy(after.entries);
+  const out: PricingDiffEntry[] = [];
+
+  for (const [key, entry] of beforeMap) {
+    const next = afterMap.get(key);
+    if (next === undefined) {
+      out.push({ provider: entry.provider, model: entry.model, kind: 'removed', before: entry });
+      continue;
+    }
+    const changedFields = COMPARED_FIELDS.filter((field) => entry[field] !== next[field]);
+    if (changedFields.length > 0) {
+      out.push({
+        provider: entry.provider,
+        model: entry.model,
+        kind: 'changed',
+        before: entry,
+        after: next,
+        changedFields,
+      });
+    }
+  }
+
+  for (const [key, entry] of afterMap) {
+    if (beforeMap.has(key)) continue;
+    out.push({ provider: entry.provider, model: entry.model, kind: 'added', after: entry });
+  }
+
+  return out.sort((a, b) => {
+    if (a.provider !== b.provider) return a.provider < b.provider ? -1 : 1;
+    if (a.model !== b.model) return a.model < b.model ? -1 : 1;
+    return a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0;
+  });
+}
+
+function indexBy(entries: ReadonlyArray<ModelPrice>): Map<string, ModelPrice> {
+  const out = new Map<string, ModelPrice>();
+  for (const entry of entries) {
+    out.set(`${entry.provider}/${entry.model}/${entry.region ?? ''}`, entry);
+  }
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * @graphorin/pricing - bundled LLM pricing snapshot for the Graphorin
+ * framework.
+ *
+ * Highlights:
+ *
+ * - {@link BUNDLED_SNAPSHOT} - bundled snapshot covering Anthropic,
+ *   OpenAI, Google, Mistral, Cohere + the local providers
+ *   (Ollama / llama.cpp). Each entry carries a per-token price and
+ *   the canonical SHA-256 digest of the `entries` array.
+ * - {@link lookupPrice} - resolve a `(provider, model)` pair against a
+ *   snapshot. Returns `null` for unknown entries plus emits one WARN
+ *   per process-lifetime per unknown pair.
+ * - {@link calculateCost} - multiply a price by token counts for a
+ *   single LLM call.
+ * - {@link diffPricing} - row-by-row delta between two snapshots.
+ * - {@link refreshPricing} - opt-in network call. Never automatic.
+ * - {@link listMissingModels} - scan trace spans for unknown models;
+ *   used by `graphorin pricing missing` (Phase 15).
+ *
+ * The bundled snapshot is intentionally small - operators wanting the
+ * full upstream catalogue should run `refreshPricing(...)` and
+ * persist the result to disk.
+ *
+ * @packageDocumentation
+ */
+
+/** Canonical version constant, derived from `package.json` at build time. */
+import pkg from '../package.json' with { type: 'json' };
+
+export const VERSION: string = pkg.version;
+
+export {
+  DEFAULT_PRICING_AUTO_REFRESH,
+  type PricingAutoRefreshConfig,
+  type PricingConfig,
+} from './config.js';
+export {
+  convertGenaiPrices,
+  type GenaiPricesConversion,
+  isGenaiPricesShape,
+} from './convert-genai-prices.js';
+export { diffPricing } from './diff.js';
+export {
+  _resetLookupWarningsForTesting,
+  calculateCost,
+  lookupPrice,
+  setLookupWarnSink,
+} from './lookup.js';
+export { listMissingModels, type MissingModelEntry } from './missing.js';
+export { type RefreshPricingOptions, refreshPricing } from './refresh.js';
+export { BUNDLED_SNAPSHOT, computeEntriesDigest, SNAPSHOT_DATE } from './snapshot/index.js';
+export type {
+  Cost,
+  LookupPriceArgs,
+  LookupPriceResult,
+  ModelPrice,
+  PricingDiffEntry,
+  PricingSnapshot,
+  PricingTraceSpanLike,
+} from './types.js';

package/src/lookup.ts

@@ -0,0 +1,164 @@
+/**
+ * `lookupPrice(...)` - resolve a per-token price for a given
+ * (provider, model) pair against a snapshot. Returns `null` when the
+ * model is unknown and emits one WARN per process-lifetime per
+ * unknown (provider, model) pair.
+ *
+ * @packageDocumentation
+ */
+
+import { BUNDLED_SNAPSHOT } from './snapshot/bundled.js';
+import type { LookupPriceArgs, LookupPriceResult, ModelPrice, PricingSnapshot } from './types.js';
+
+const WARNED = new Set<string>();
+
+/**
+ * Optional sink for the deduplicated WARN emitted on unknown models.
+ * Defaults to `console.warn`. Override in tests.
+ *
+ * @internal
+ */
+export function setLookupWarnSink(sink: (line: string) => void): void {
+  WARN_SINK = sink;
+}
+
+let WARN_SINK: (line: string) => void = (line) => console.warn(line);
+
+/**
+ * @internal - exposed for tests so the WARN-once cache can be reset.
+ */
+export function _resetLookupWarningsForTesting(): void {
+  WARNED.clear();
+}
+
+/**
+ * Resolve a per-token price for the (provider, model) pair. Returns
+ * `null` when the snapshot does not contain an entry for the model.
+ *
+ * The function emits one WARN per process per unknown (provider, model)
+ * pair so cost dashboards surface drift without spamming the log.
+ *
+ * @stable
+ */
+export function lookupPrice(
+  args: LookupPriceArgs,
+  snapshot: PricingSnapshot = BUNDLED_SNAPSHOT,
+): LookupPriceResult | null {
+  const exact = snapshot.entries.find(
+    (entry) =>
+      entry.provider === args.provider &&
+      entry.model === args.model &&
+      (args.region === undefined || entry.region === undefined || entry.region === args.region),
+  );
+
+  if (exact !== undefined) return entryToResult(exact, snapshot);
+
+  // Date-suffix fallback (core-provider-03): dated ids like
+  // `claude-haiku-4-5-20251001` resolve to their dateless alias entry
+  // (`claude-haiku-4-5`) so the snapshot does not need one row per
+  // dated release.
+  const dateless = args.model.replace(/-\d{8}$/, '');
+  if (dateless !== args.model) {
+    const alias = snapshot.entries.find(
+      (entry) =>
+        entry.provider === args.provider &&
+        entry.model === dateless &&
+        (args.region === undefined || entry.region === undefined || entry.region === args.region),
+    );
+    if (alias !== undefined) return entryToResult(alias, snapshot);
+  }
+
+  // Wildcard fallback - used by local providers (`provider: 'ollama', model: '*'`).
+  const wildcard = snapshot.entries.find(
+    (entry) => entry.provider === args.provider && entry.model === '*',
+  );
+  if (wildcard !== undefined) return entryToResult(wildcard, snapshot);
+
+  warnOnce(args);
+  return null;
+}
+
+function entryToResult(entry: ModelPrice, snapshot: PricingSnapshot): LookupPriceResult {
+  return {
+    inputUsdPerToken: entry.inputUsdPerToken,
+    outputUsdPerToken: entry.outputUsdPerToken,
+    ...(entry.cachedReadUsdPerToken === undefined
+      ? {}
+      : { cachedReadUsdPerToken: entry.cachedReadUsdPerToken }),
+    ...(entry.cacheWriteUsdPerToken === undefined
+      ? {}
+      : { cacheWriteUsdPerToken: entry.cacheWriteUsdPerToken }),
+    ...(entry.reasoningUsdPerToken === undefined
+      ? {}
+      : { reasoningUsdPerToken: entry.reasoningUsdPerToken }),
+    source: snapshot.source,
+    snapshotDate: snapshot.snapshotDate,
+  };
+}
+
+function warnOnce(args: LookupPriceArgs): void {
+  const key = `${args.provider}/${args.model}`;
+  if (WARNED.has(key)) return;
+  WARNED.add(key);
+  WARN_SINK(
+    `[graphorin/pricing] WARN: no pricing entry for ${args.provider}/${args.model}; ` +
+      'cost is null. Consider running `graphorin pricing refresh` or contributing the ' +
+      'entry upstream.',
+  );
+}
+
+/**
+ * Multiply a per-token price by an integer token count. Returns `null`
+ * when the price is unknown. Useful when caller wants to compute cost
+ * for a single LLM call without instantiating the cost tracker.
+ *
+ * Token-count contract (PS-19):
+ * - `inputTokens` **excludes** `cachedReadTokens` and `cacheWriteTokens` -
+ *   the cache legs are billed separately at their own rates, so pass the
+ *   non-cached prompt count to avoid double-billing.
+ * - `reasoningTokens` are billed at `outputUsdPerToken` unless the model entry
+ *   declares an explicit `reasoningUsdPerToken`.
+ * - `cacheWriteTokens` are billed at `cacheWriteUsdPerToken` when the entry
+ *   declares one, else at the full input rate (a cache write is at minimum a
+ *   normal input token - the fallback never under-bills relative to no cache).
+ *
+ * Units contract (W-045): this is the CANONICAL producer of core
+ * `Cost.amount`, and it returns WHOLE US dollars (per-token USD rates
+ * times token counts) - never cents / minor units. One million input
+ * tokens at `inputUsdPerToken = 3e-6` cost `3` (three dollars).
+ *
+ * @stable
+ */
+export function calculateCost(
+  args: LookupPriceArgs & {
+    /** Non-cached prompt tokens (excludes cache reads AND cache writes). */
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cachedReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+    readonly reasoningTokens?: number;
+  },
+  snapshot: PricingSnapshot = BUNDLED_SNAPSHOT,
+): { readonly amount: number; readonly currency: 'USD' } | null {
+  const price = lookupPrice(args, snapshot);
+  if (price === null) return null;
+  let amount = 0;
+  // `inputTokens` is the NON-cached prompt; cached reads are billed separately
+  // at their own (cheaper) rate, so they must be excluded from `inputTokens` to
+  // avoid double-counting (PS-19).
+  amount += price.inputUsdPerToken * args.inputTokens;
+  amount += price.outputUsdPerToken * args.outputTokens;
+  if (args.cachedReadTokens !== undefined && price.cachedReadUsdPerToken !== undefined) {
+    amount += price.cachedReadUsdPerToken * args.cachedReadTokens;
+  }
+  if (args.cacheWriteTokens !== undefined) {
+    amount += (price.cacheWriteUsdPerToken ?? price.inputUsdPerToken) * args.cacheWriteTokens;
+  }
+  if (args.reasoningTokens !== undefined) {
+    // PS-19: reasoning tokens follow completion (output) pricing unless the
+    // entry declares an explicit `reasoningUsdPerToken` - the documented
+    // contract that was previously billed at $0 for every bundled entry.
+    amount += (price.reasoningUsdPerToken ?? price.outputUsdPerToken) * args.reasoningTokens;
+  }
+  return { amount, currency: 'USD' };
+}

package/src/missing.ts

@@ -0,0 +1,73 @@
+/**
+ * `listMissingModels(...)` - scan a sequence of trace spans and return
+ * the unique (provider, model) pairs that the snapshot does not
+ * recognise.
+ *
+ * The function reads `gen_ai.system` + `gen_ai.request.model` (the
+ * canonical OpenTelemetry GenAI attributes) and falls back to the
+ * Graphorin-prefixed `graphorin.provider.id` /
+ * `graphorin.provider.model` pair when `gen_ai.*` is absent.
+ *
+ * @packageDocumentation
+ */
+
+import { lookupPrice } from './lookup.js';
+import { BUNDLED_SNAPSHOT } from './snapshot/bundled.js';
+import type { PricingSnapshot, PricingTraceSpanLike } from './types.js';
+
+/**
+ * Single missing-model row.
+ *
+ * @stable
+ */
+export interface MissingModelEntry {
+  readonly provider: string;
+  readonly model: string;
+  readonly count: number;
+}
+
+/**
+ * Return one entry per (provider, model) pair that the snapshot does
+ * not recognise, sorted by descending occurrence count.
+ *
+ * @stable
+ */
+export function listMissingModels(
+  spans: Iterable<PricingTraceSpanLike>,
+  snapshot: PricingSnapshot = BUNDLED_SNAPSHOT,
+): ReadonlyArray<MissingModelEntry> {
+  const seen = new Map<string, MissingModelEntry & { count: number }>();
+  for (const span of spans) {
+    // E8: `gen_ai.provider.name` is the current OTel GenAI attribute (what
+    // withTracing emits); `gen_ai.system` is its deprecated predecessor kept
+    // for older recorded traces.
+    const provider = stringAttr(span, [
+      'gen_ai.provider.name',
+      'gen_ai.system',
+      'graphorin.provider.id',
+    ]);
+    const model = stringAttr(span, [
+      'gen_ai.request.model',
+      'gen_ai.response.model',
+      'graphorin.provider.model',
+    ]);
+    if (provider === null || model === null) continue;
+    if (lookupPrice({ provider, model }, snapshot) !== null) continue;
+    const key = `${provider}/${model}`;
+    const existing = seen.get(key);
+    if (existing === undefined) {
+      seen.set(key, { provider, model, count: 1 });
+    } else {
+      seen.set(key, { provider, model, count: existing.count + 1 });
+    }
+  }
+  return [...seen.values()].sort((a, b) => b.count - a.count);
+}
+
+function stringAttr(span: PricingTraceSpanLike, keys: ReadonlyArray<string>): string | null {
+  for (const key of keys) {
+    const value = span.attributes[key];
+    if (typeof value === 'string' && value.length > 0) return value;
+  }
+  return null;
+}