@graphorin/pricing 0.6.1 → 0.7.0

package/src/refresh.ts

@@ -0,0 +1,197 @@
+/**
+ * `refreshPricing(...)` - opt-in network call. The framework never
+ * invokes this automatically; it exists so the CLI (`graphorin
+ * pricing refresh`) and operator scripts can pull a fresh snapshot
+ * without re-installing the package.
+ *
+ * The function fetches the supplied URL as JSON and validates the
+ * shape against the {@link PricingSnapshot} contract. The bundled
+ * snapshot is **not** mutated; callers persist the refreshed
+ * snapshot to disk and reload it explicitly.
+ *
+ * @packageDocumentation
+ */
+
+import { convertGenaiPrices, isGenaiPricesShape } from './convert-genai-prices.js';
+import { computeEntriesDigest } from './snapshot/bundled.js';
+import type { ModelPrice, PricingSnapshot } from './types.js';
+
+/**
+ * Configuration shape for {@link refreshPricing}. The `fetchImpl`
+ * override exists so tests can exercise the function without making
+ * a real network call.
+ *
+ * @stable
+ */
+export interface RefreshPricingOptions {
+  /** Snapshot URL - typically the upstream pricing JSON. */
+  readonly url: string;
+  /** Optional headers (auth, conditional GET, etc.). */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Optional fetch override - useful in tests. */
+  readonly fetchImpl?: typeof fetch;
+  /** Override the snapshot date stamped on the result. Defaults to today. */
+  readonly snapshotDate?: string;
+  /** Override the snapshot version string. Defaults to `'graphorin/0.1+refreshed'`. */
+  readonly version?: string;
+  /**
+   * Hard timeout for the network fetch in milliseconds. Default
+   * `30000`. Aborts the request (and throws) if the upstream is slow
+   * or unreachable so `graphorin pricing refresh` cannot hang. Pass an
+   * explicit {@link RefreshPricingOptions.signal} to manage
+   * cancellation yourself; the two are combined.
+   */
+  readonly timeoutMs?: number;
+  /** Caller-supplied abort signal, combined with the timeout. */
+  readonly signal?: AbortSignal;
+  /**
+   * W-097: accepted body format. `'auto'` (default) tries the native
+   * graphorin shape, then auto-detects + converts the
+   * `@pydantic/genai-prices` dataset; the explicit values pin one
+   * format and fail fast on anything else.
+   */
+  readonly format?: 'auto' | 'graphorin' | 'genai-prices';
+}
+
+/**
+ * Pull a fresh snapshot from the supplied URL and return it. Network
+ * failures and shape mismatches surface as thrown errors so the CLI
+ * can surface them to the operator.
+ *
+ * @stable
+ */
+export async function refreshPricing(opts: RefreshPricingOptions): Promise<PricingSnapshot> {
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchImpl !== 'function') {
+    throw new TypeError(
+      'refreshPricing: no fetch implementation available. Provide `fetchImpl` ' +
+        'explicitly or run on a Node.js version with global fetch (>= 18).',
+    );
+  }
+  const timeoutMs = opts.timeoutMs ?? 30_000;
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const signal =
+    opts.signal === undefined ? timeoutSignal : AbortSignal.any([opts.signal, timeoutSignal]);
+  let res: Awaited<ReturnType<typeof fetchImpl>>;
+  try {
+    res = await fetchImpl(opts.url, { headers: opts.headers ?? {}, signal });
+  } catch (err) {
+    if (timeoutSignal.aborted) {
+      throw new Error(`refreshPricing: timed out after ${timeoutMs} ms fetching ${opts.url}`, {
+        cause: err,
+      });
+    }
+    throw err;
+  }
+  if (!res.ok) {
+    throw new Error(`refreshPricing: HTTP ${res.status} ${res.statusText} from ${opts.url}`);
+  }
+  const body = (await res.json()) as unknown;
+  const format = opts.format ?? 'auto';
+  let entries: ReadonlyArray<ModelPrice>;
+  let conversion: PricingSnapshot['conversion'];
+  if (format === 'graphorin') {
+    entries = parseEntries(body);
+  } else if (format === 'genai-prices') {
+    ({ entries, conversion } = convertForeign(body, opts.url));
+  } else {
+    // 'auto': native first; a shape miss falls through to detection so
+    // the operator error names the NATIVE expectation when neither fits.
+    try {
+      entries = parseEntries(body);
+    } catch (nativeError) {
+      if (!isGenaiPricesShape(body)) throw nativeError;
+      ({ entries, conversion } = convertForeign(body, opts.url));
+    }
+  }
+  const snapshotDate = opts.snapshotDate ?? new Date().toISOString().slice(0, 10);
+  const version =
+    opts.version ??
+    (conversion !== undefined ? 'genai-prices+converted' : 'graphorin/0.1+refreshed');
+  return Object.freeze<PricingSnapshot>({
+    version,
+    source: opts.url,
+    snapshotDate,
+    currency: 'USD',
+    sha256: computeEntriesDigest(entries),
+    entries,
+    ...(conversion !== undefined ? { conversion } : {}),
+  });
+}
+
+/**
+ * W-097: convert a genai-prices dataset body, guarding the currency -
+ * `PricingSnapshot.currency` is a `'USD'` literal, so a body that
+ * DECLARES another currency must fail loudly instead of being stamped
+ * dollars.
+ */
+function convertForeign(
+  body: unknown,
+  url: string,
+): { entries: ReadonlyArray<ModelPrice>; conversion: NonNullable<PricingSnapshot['conversion']> } {
+  const declared = (body as { currency?: unknown }).currency;
+  if (typeof declared === 'string' && declared.toUpperCase() !== 'USD') {
+    throw new Error(
+      `refreshPricing: dataset at ${url} declares currency '${declared}' - graphorin snapshots are USD-only and no conversion rate is available`,
+    );
+  }
+  const { entries, skipped } = convertGenaiPrices(body);
+  if (entries.length === 0) {
+    throw new Error(
+      `refreshPricing: the genai-prices dataset at ${url} converted to zero usable entries (${skipped} skipped) - the supported subset may have drifted; see convert-genai-prices.ts`,
+    );
+  }
+  return { entries, conversion: { format: 'genai-prices', skipped } };
+}
+
+function parseEntries(body: unknown): ReadonlyArray<ModelPrice> {
+  if (body === null || typeof body !== 'object') {
+    throw new Error('refreshPricing: response body is not an object');
+  }
+  // Two accepted shapes:
+  //   - `{ entries: ModelPrice[] }`
+  //   - `ModelPrice[]`
+  let raw: unknown;
+  if (Array.isArray(body)) {
+    raw = body;
+  } else {
+    raw = (body as { entries?: unknown }).entries;
+    if (!Array.isArray(raw)) {
+      throw new Error('refreshPricing: response object is missing the `entries` array');
+    }
+  }
+  const entries = (raw as ReadonlyArray<unknown>).map(parseEntry);
+  return Object.freeze(entries);
+}
+
+function parseEntry(raw: unknown): ModelPrice {
+  if (raw === null || typeof raw !== 'object') {
+    throw new Error('refreshPricing: pricing entry is not an object');
+  }
+  const e = raw as Partial<ModelPrice>;
+  if (typeof e.provider !== 'string' || typeof e.model !== 'string') {
+    throw new Error('refreshPricing: pricing entry is missing provider / model');
+  }
+  if (typeof e.inputUsdPerToken !== 'number' || typeof e.outputUsdPerToken !== 'number') {
+    throw new Error(
+      `refreshPricing: pricing entry ${e.provider}/${e.model} is missing input / output prices`,
+    );
+  }
+  return Object.freeze({
+    provider: e.provider,
+    model: e.model,
+    inputUsdPerToken: e.inputUsdPerToken,
+    outputUsdPerToken: e.outputUsdPerToken,
+    ...(typeof e.cachedReadUsdPerToken === 'number'
+      ? { cachedReadUsdPerToken: e.cachedReadUsdPerToken }
+      : {}),
+    ...(typeof e.cacheWriteUsdPerToken === 'number'
+      ? { cacheWriteUsdPerToken: e.cacheWriteUsdPerToken }
+      : {}),
+    ...(typeof e.reasoningUsdPerToken === 'number'
+      ? { reasoningUsdPerToken: e.reasoningUsdPerToken }
+      : {}),
+    ...(typeof e.region === 'string' ? { region: e.region } : {}),
+    ...(typeof e.notes === 'string' ? { notes: e.notes } : {}),
+  });
+}

package/src/snapshot/bundled.ts

@@ -0,0 +1,306 @@
+/**
+ * Bundled pricing snapshot. The catalogue is intentionally small -
+ * operators wanting the full upstream catalogue should run the opt-in
+ * `refreshPricing(...)` flow at build time and persist the result to
+ * a custom snapshot file.
+ *
+ * Prices are stored in **USD per token** (i.e. divide the per-million
+ * upstream prices by 1_000_000). Numbers are accurate to the snapshot
+ * date; consumers are expected to refresh on a regular cadence.
+ *
+ * @packageDocumentation
+ */
+
+import { createHash } from 'node:crypto';
+
+import type { ModelPrice, PricingSnapshot } from '../types.js';
+
+/** @internal - used for `lookupPrice` defaults. */
+export const SNAPSHOT_DATE = '2026-07-04';
+
+const ENTRIES: ReadonlyArray<ModelPrice> = Object.freeze([
+  // -----------------------------------------------------------------
+  // Anthropic - current families (core-provider-03). Dateless alias ids;
+  // dated ids (`claude-haiku-4-5-20251001`) resolve through the lookup's
+  // date-suffix fallback. Cache-write = 1.25x input (5-minute cache).
+  // NOTE: the Claude 5 family (fable/mythos) and any tier released after
+  // this snapshot date have NO entry on purpose - cost tracking reports
+  // null + one WARN instead of an invented number. Refresh via
+  // `refreshPricing(...)` or contribute the entry when pricing is public.
+  // -----------------------------------------------------------------
+  {
+    provider: 'anthropic',
+    model: 'claude-opus-4-5',
+    inputUsdPerToken: 5 / 1_000_000,
+    outputUsdPerToken: 25 / 1_000_000,
+    cachedReadUsdPerToken: 0.5 / 1_000_000,
+    cacheWriteUsdPerToken: 6.25 / 1_000_000,
+  },
+  {
+    provider: 'anthropic',
+    model: 'claude-opus-4-1',
+    inputUsdPerToken: 15 / 1_000_000,
+    outputUsdPerToken: 75 / 1_000_000,
+    cachedReadUsdPerToken: 1.5 / 1_000_000,
+    cacheWriteUsdPerToken: 18.75 / 1_000_000,
+  },
+  {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-5',
+    inputUsdPerToken: 3 / 1_000_000,
+    outputUsdPerToken: 15 / 1_000_000,
+    cachedReadUsdPerToken: 0.3 / 1_000_000,
+    cacheWriteUsdPerToken: 3.75 / 1_000_000,
+    notes: 'Prompts <= 200k tokens; the long-context tier is priced higher.',
+  },
+  {
+    provider: 'anthropic',
+    model: 'claude-haiku-4-5',
+    inputUsdPerToken: 1 / 1_000_000,
+    outputUsdPerToken: 5 / 1_000_000,
+    cachedReadUsdPerToken: 0.1 / 1_000_000,
+    cacheWriteUsdPerToken: 1.25 / 1_000_000,
+  },
+  // Retired / legacy ids retained for historical cost attribution.
+  {
+    provider: 'anthropic',
+    model: 'claude-3-5-sonnet-20241022',
+    inputUsdPerToken: 3 / 1_000_000,
+    outputUsdPerToken: 15 / 1_000_000,
+    cachedReadUsdPerToken: 0.3 / 1_000_000,
+    cacheWriteUsdPerToken: 3.75 / 1_000_000,
+  },
+  {
+    provider: 'anthropic',
+    model: 'claude-3-5-haiku-20241022',
+    inputUsdPerToken: 0.8 / 1_000_000,
+    outputUsdPerToken: 4 / 1_000_000,
+    cachedReadUsdPerToken: 0.08 / 1_000_000,
+    cacheWriteUsdPerToken: 1 / 1_000_000,
+  },
+  {
+    provider: 'anthropic',
+    model: 'claude-3-opus-20240229',
+    inputUsdPerToken: 15 / 1_000_000,
+    outputUsdPerToken: 75 / 1_000_000,
+    cachedReadUsdPerToken: 1.5 / 1_000_000,
+    cacheWriteUsdPerToken: 18.75 / 1_000_000,
+  },
+  // -----------------------------------------------------------------
+  // OpenAI - cache reads are automatic (no breakpoints) and there is no
+  // cache-write charge, so entries carry only `cachedReadUsdPerToken`.
+  // -----------------------------------------------------------------
+  {
+    provider: 'openai',
+    model: 'gpt-5',
+    inputUsdPerToken: 1.25 / 1_000_000,
+    outputUsdPerToken: 10 / 1_000_000,
+    cachedReadUsdPerToken: 0.125 / 1_000_000,
+  },
+  {
+    provider: 'openai',
+    model: 'gpt-5-mini',
+    inputUsdPerToken: 0.25 / 1_000_000,
+    outputUsdPerToken: 2 / 1_000_000,
+    cachedReadUsdPerToken: 0.025 / 1_000_000,
+  },
+  {
+    provider: 'openai',
+    model: 'gpt-5-nano',
+    inputUsdPerToken: 0.05 / 1_000_000,
+    outputUsdPerToken: 0.4 / 1_000_000,
+    cachedReadUsdPerToken: 0.005 / 1_000_000,
+  },
+  {
+    provider: 'openai',
+    model: 'gpt-4.1',
+    inputUsdPerToken: 2 / 1_000_000,
+    outputUsdPerToken: 8 / 1_000_000,
+    cachedReadUsdPerToken: 0.5 / 1_000_000,
+  },
+  {
+    provider: 'openai',
+    model: 'gpt-4.1-mini',
+    inputUsdPerToken: 0.4 / 1_000_000,
+    outputUsdPerToken: 1.6 / 1_000_000,
+    cachedReadUsdPerToken: 0.1 / 1_000_000,
+  },
+  {
+    provider: 'openai',
+    model: 'gpt-4.1-nano',
+    inputUsdPerToken: 0.1 / 1_000_000,
+    outputUsdPerToken: 0.4 / 1_000_000,
+    cachedReadUsdPerToken: 0.025 / 1_000_000,
+  },
+  {
+    provider: 'openai',
+    model: 'o3',
+    inputUsdPerToken: 2 / 1_000_000,
+    outputUsdPerToken: 8 / 1_000_000,
+    cachedReadUsdPerToken: 0.5 / 1_000_000,
+  },
+  {
+    provider: 'openai',
+    model: 'o4-mini',
+    inputUsdPerToken: 1.1 / 1_000_000,
+    outputUsdPerToken: 4.4 / 1_000_000,
+    cachedReadUsdPerToken: 0.275 / 1_000_000,
+  },
+  // Retired / legacy ids retained for historical cost attribution.
+  {
+    provider: 'openai',
+    model: 'gpt-4o-2024-11-20',
+    inputUsdPerToken: 2.5 / 1_000_000,
+    outputUsdPerToken: 10 / 1_000_000,
+    cachedReadUsdPerToken: 1.25 / 1_000_000,
+  },
+  {
+    provider: 'openai',
+    model: 'gpt-4o-mini-2024-07-18',
+    inputUsdPerToken: 0.15 / 1_000_000,
+    outputUsdPerToken: 0.6 / 1_000_000,
+    cachedReadUsdPerToken: 0.075 / 1_000_000,
+  },
+  {
+    provider: 'openai',
+    model: 'o1-2024-12-17',
+    inputUsdPerToken: 15 / 1_000_000,
+    outputUsdPerToken: 60 / 1_000_000,
+    cachedReadUsdPerToken: 7.5 / 1_000_000,
+  },
+  {
+    provider: 'openai',
+    model: 'o3-mini-2025-01-31',
+    inputUsdPerToken: 1.1 / 1_000_000,
+    outputUsdPerToken: 4.4 / 1_000_000,
+    cachedReadUsdPerToken: 0.55 / 1_000_000,
+  },
+  // -----------------------------------------------------------------
+  // Google - implicit-caching read discount; context-cache storage is
+  // billed per hour upstream and is not modelled here.
+  // -----------------------------------------------------------------
+  {
+    provider: 'google',
+    model: 'gemini-2.5-pro',
+    inputUsdPerToken: 1.25 / 1_000_000,
+    outputUsdPerToken: 10 / 1_000_000,
+    cachedReadUsdPerToken: 0.3125 / 1_000_000,
+    notes: 'Prompts <= 200k tokens; the long-context tier is priced higher.',
+  },
+  {
+    provider: 'google',
+    model: 'gemini-2.5-flash',
+    inputUsdPerToken: 0.3 / 1_000_000,
+    outputUsdPerToken: 2.5 / 1_000_000,
+    cachedReadUsdPerToken: 0.075 / 1_000_000,
+  },
+  {
+    provider: 'google',
+    model: 'gemini-2.5-flash-lite',
+    inputUsdPerToken: 0.1 / 1_000_000,
+    outputUsdPerToken: 0.4 / 1_000_000,
+    cachedReadUsdPerToken: 0.025 / 1_000_000,
+  },
+  // Retired / legacy ids retained for historical cost attribution.
+  {
+    provider: 'google',
+    model: 'gemini-1.5-pro-002',
+    inputUsdPerToken: 1.25 / 1_000_000,
+    outputUsdPerToken: 5 / 1_000_000,
+    cachedReadUsdPerToken: 0.3125 / 1_000_000,
+  },
+  {
+    provider: 'google',
+    model: 'gemini-1.5-flash-002',
+    inputUsdPerToken: 0.075 / 1_000_000,
+    outputUsdPerToken: 0.3 / 1_000_000,
+    cachedReadUsdPerToken: 0.01875 / 1_000_000,
+  },
+  // -----------------------------------------------------------------
+  // Mistral
+  // -----------------------------------------------------------------
+  {
+    provider: 'mistral',
+    model: 'mistral-large-2411',
+    inputUsdPerToken: 2 / 1_000_000,
+    outputUsdPerToken: 6 / 1_000_000,
+  },
+  {
+    provider: 'mistral',
+    model: 'mistral-small-2503',
+    inputUsdPerToken: 0.2 / 1_000_000,
+    outputUsdPerToken: 0.6 / 1_000_000,
+  },
+  // -----------------------------------------------------------------
+  // Cohere
+  // -----------------------------------------------------------------
+  {
+    provider: 'cohere',
+    model: 'command-r-plus-08-2024',
+    inputUsdPerToken: 2.5 / 1_000_000,
+    outputUsdPerToken: 10 / 1_000_000,
+  },
+  {
+    provider: 'cohere',
+    model: 'command-r-08-2024',
+    inputUsdPerToken: 0.15 / 1_000_000,
+    outputUsdPerToken: 0.6 / 1_000_000,
+  },
+  // -----------------------------------------------------------------
+  // Local providers - documented as zero-cost so cost rollups still
+  // include the call counts.
+  // -----------------------------------------------------------------
+  {
+    provider: 'ollama',
+    model: '*',
+    inputUsdPerToken: 0,
+    outputUsdPerToken: 0,
+    notes: 'Local Ollama deployment - operator-priced.',
+  },
+  {
+    provider: 'graphorin-llamacpp',
+    model: '*',
+    inputUsdPerToken: 0,
+    outputUsdPerToken: 0,
+    notes: 'Local llama.cpp deployment - operator-priced.',
+  },
+] as const);
+
+/**
+ * Compute a deterministic SHA-256 of the entries. Sorting the entry
+ * keys before serialisation keeps the digest stable across Node
+ * versions / object-property-iteration orderings.
+ *
+ * @internal
+ */
+export function computeEntriesDigest(entries: ReadonlyArray<ModelPrice>): string {
+  const canonical = JSON.stringify(entries.map((entry) => sortKeys(entry as unknown)));
+  return createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+
+function sortKeys(value: unknown): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(sortKeys);
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+    out[key] = sortKeys((value as Record<string, unknown>)[key]);
+  }
+  return out;
+}
+
+/**
+ * The bundled snapshot. The `sha256` digest is computed over the
+ * canonical JSON form of `entries` at module load time so consumers
+ * can verify integrity without trusting the package metadata.
+ *
+ * @stable
+ */
+export const BUNDLED_SNAPSHOT: PricingSnapshot = Object.freeze({
+  version: 'graphorin/0.1',
+  source:
+    'https://github.com/o-stepper/graphorin/tree/main/packages/pricing/src/snapshot/bundled.ts',
+  snapshotDate: SNAPSHOT_DATE,
+  currency: 'USD',
+  sha256: computeEntriesDigest(ENTRIES),
+  entries: ENTRIES,
+});

package/src/snapshot/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Bundled pricing snapshot surface.
+ *
+ * @packageDocumentation
+ */
+
+export { BUNDLED_SNAPSHOT, computeEntriesDigest, SNAPSHOT_DATE } from './bundled.js';

package/src/types.ts

@@ -0,0 +1,122 @@
+/**
+ * Public types for the pricing package.
+ *
+ * @packageDocumentation
+ */
+
+import type { Cost } from '@graphorin/core';
+
+/**
+ * Per-model pricing entry. All amounts are in **USD per token** unless
+ * the snapshot declares an alternative currency. Reasoning tokens
+ * (when supported) follow the same pricing as completion tokens unless
+ * the entry declares an explicit `reasoningUsdPerToken`.
+ *
+ * @stable
+ */
+export interface ModelPrice {
+  /** Lower-case provider id (e.g. `'anthropic'`, `'openai'`, `'ollama'`). */
+  readonly provider: string;
+  /** Lower-case model id, e.g. `'claude-3-5-sonnet-20241022'`. */
+  readonly model: string;
+  /** Price per input token, in USD. */
+  readonly inputUsdPerToken: number;
+  /** Price per output token, in USD. */
+  readonly outputUsdPerToken: number;
+  /** Optional cached-read price (Anthropic / OpenAI prompt caching). */
+  readonly cachedReadUsdPerToken?: number;
+  /**
+   * Optional cache-write (cache-creation) price. Anthropic bills prompt
+   * tokens written to the 5-minute cache at 1.25x the input rate; OpenAI
+   * does not charge (or report) cache writes, so its entries omit this.
+   */
+  readonly cacheWriteUsdPerToken?: number;
+  /** Optional reasoning-token price (OpenAI o1 / Gemini 2 thinking). */
+  readonly reasoningUsdPerToken?: number;
+  /** Optional region label (e.g. `'us-east-1'`). */
+  readonly region?: string;
+  /** Free-form notes for tooling / docs. */
+  readonly notes?: string;
+}
+
+/**
+ * Single bundled snapshot.
+ *
+ * @stable
+ */
+export interface PricingSnapshot {
+  readonly version: string;
+  readonly source: string;
+  readonly snapshotDate: string;
+  readonly currency: 'USD';
+  readonly sha256: string;
+  readonly entries: ReadonlyArray<ModelPrice>;
+  /**
+   * W-097: present when `refreshPricing` converted a foreign dataset
+   * (today: `@pydantic/genai-prices`) instead of consuming the native
+   * shape. `skipped` counts model entries the supported subset could
+   * not represent (tiered / conditional pricing).
+   */
+  readonly conversion?: {
+    readonly format: 'genai-prices';
+    readonly skipped: number;
+  };
+}
+
+/**
+ * Lookup criteria.
+ *
+ * @stable
+ */
+export interface LookupPriceArgs {
+  readonly provider: string;
+  readonly model: string;
+  readonly region?: string;
+}
+
+/**
+ * Result of {@link lookupPrice} when the model is known.
+ *
+ * @stable
+ */
+export interface LookupPriceResult {
+  readonly inputUsdPerToken: number;
+  readonly outputUsdPerToken: number;
+  readonly cachedReadUsdPerToken?: number;
+  readonly cacheWriteUsdPerToken?: number;
+  readonly reasoningUsdPerToken?: number;
+  readonly source: string;
+  readonly snapshotDate: string;
+}
+
+/**
+ * Result row reported by {@link diffPricing}.
+ *
+ * @stable
+ */
+export interface PricingDiffEntry {
+  readonly provider: string;
+  readonly model: string;
+  readonly kind: 'added' | 'removed' | 'changed';
+  readonly before?: ModelPrice;
+  readonly after?: ModelPrice;
+  readonly changedFields?: ReadonlyArray<keyof ModelPrice>;
+}
+
+/**
+ * Span-shape input accepted by {@link listMissingModels}. Lightweight
+ * subset of `SpanRecord` from `@graphorin/observability` so the
+ * pricing package stays free of an observability dependency.
+ *
+ * @stable
+ */
+export interface PricingTraceSpanLike {
+  readonly attributes: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Re-export the `@graphorin/core` `Cost` shape for caller convenience.
+ *
+ * @stable
+ */
+export type { Cost };