@graphorin/pricing 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @graphorin/pricing
+
+## 0.1.0
+
+Initial release. See the workspace root `CHANGELOG.md` for the full
+release notes; the per-package changelog is generated by Changesets
+and tracks subsequent updates.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+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

@@ -0,0 +1,69 @@
+# @graphorin/pricing
+
+> Bundled LLM pricing snapshot for the [Graphorin](https://github.com/o-stepper/graphorin) framework.
+
+`@graphorin/pricing` is a tiny dependency-free package that ships a
+representative LLM pricing catalogue, a `lookupPrice(...)` resolver, a
+snapshot-diff utility, an opt-in `refreshPricing(...)` hook, and the
+`listMissingModels(...)` utility used by trace audits.
+
+The package is intentionally separate from `@graphorin/observability`
+so consumers can:
+
+- pin the pricing snapshot independently of the framework version,
+- ship a custom snapshot without forking the observability package,
+- decline the bundled snapshot entirely (just don't import it).
+
+## Install
+
+```bash
+pnpm add @graphorin/pricing
+```
+
+## Quick start
+
+```ts
+import {
+  BUNDLED_SNAPSHOT,
+  calculateCost,
+  lookupPrice,
+} from '@graphorin/pricing';
+
+const price = lookupPrice({ provider: 'anthropic', model: 'claude-3-5-sonnet-20241022' });
+if (price !== null) {
+  console.log(`Input: $${price.inputUsdPerToken} / token`);
+}
+
+const cost = calculateCost(
+  {
+    provider: 'openai',
+    model: 'gpt-4o-2024-11-20',
+    inputTokens: 1_000,
+    outputTokens: 500,
+  },
+  BUNDLED_SNAPSHOT,
+);
+```
+
+## Refreshing
+
+```ts
+import { refreshPricing } from '@graphorin/pricing';
+import { writeFile } from 'node:fs/promises';
+
+const snapshot = await refreshPricing({
+  url: 'https://example.com/pricing.json',
+});
+await writeFile('./pricing.json', JSON.stringify(snapshot, null, 2));
+```
+
+The framework never invokes `refreshPricing(...)` automatically per
+the zero-default-telemetry policy; the operator runs it on demand.
+
+## License
+
+MIT © 2026 [Oleksiy Stepurenko](https://github.com/o-stepper).
+
+---
+
+**Project Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/config.d.ts

@@ -0,0 +1,37 @@
+//#region src/config.d.ts
+/**
+ * Configuration shapes consumed by `pricing.*`.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Auto-refresh configuration. The `enabled` flag exists in the type
+ * for forward compatibility but is **enforced false** in v0.1 per the
+ * zero-default-telemetry policy: refreshing the snapshot makes an
+ * outbound HTTP call, so it must remain an explicit user action.
+ *
+ * @stable
+ */
+interface PricingAutoRefreshConfig {
+  /** Always `false` in v0.1. Reserved for v0.2+. */
+  readonly enabled: false;
+  /** Suggested cadence for v0.2+. Ignored at runtime in v0.1. */
+  readonly intervalHours?: number;
+}
+/**
+ * Default auto-refresh configuration.
+ *
+ * @stable
+ */
+declare const DEFAULT_PRICING_AUTO_REFRESH: PricingAutoRefreshConfig;
+/**
+ * Container shape for the broader `pricing.*` configuration.
+ *
+ * @stable
+ */
+interface PricingConfig {
+  readonly autoRefresh?: PricingAutoRefreshConfig;
+}
+//#endregion
+export { DEFAULT_PRICING_AUTO_REFRESH, PricingAutoRefreshConfig, PricingConfig };
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","names":[],"sources":["../src/config.ts"],"sourcesContent":[],"mappings":";;AAcA;AAYA;AAUA;;;;;;;;;;UAtBiB,wBAAA;;;;;;;;;;;cAYJ,8BAA8B;;;;;;UAU1B,aAAA;yBACQ"}

package/dist/config.js

@@ -0,0 +1,14 @@
+//#region src/config.ts
+/**
+* Default auto-refresh configuration.
+*
+* @stable
+*/
+const DEFAULT_PRICING_AUTO_REFRESH = Object.freeze({
+	enabled: false,
+	intervalHours: 24
+});
+
+//#endregion
+export { DEFAULT_PRICING_AUTO_REFRESH };
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":["DEFAULT_PRICING_AUTO_REFRESH: PricingAutoRefreshConfig"],"sources":["../src/config.ts"],"sourcesContent":["/**\n * Configuration shapes consumed by `pricing.*`.\n *\n * @packageDocumentation\n */\n\n/**\n * Auto-refresh configuration. The `enabled` flag exists in the type\n * for forward compatibility but is **enforced false** in v0.1 per the\n * zero-default-telemetry policy: refreshing the snapshot makes an\n * outbound HTTP call, so it must remain an explicit user action.\n *\n * @stable\n */\nexport interface PricingAutoRefreshConfig {\n  /** Always `false` in v0.1. Reserved for v0.2+. */\n  readonly enabled: false;\n  /** Suggested cadence for v0.2+. Ignored at runtime in v0.1. */\n  readonly intervalHours?: number;\n}\n\n/**\n * Default auto-refresh configuration.\n *\n * @stable\n */\nexport const DEFAULT_PRICING_AUTO_REFRESH: PricingAutoRefreshConfig = Object.freeze({\n  enabled: false as const,\n  intervalHours: 24,\n});\n\n/**\n * Container shape for the broader `pricing.*` configuration.\n *\n * @stable\n */\nexport interface PricingConfig {\n  readonly autoRefresh?: PricingAutoRefreshConfig;\n}\n"],"mappings":";;;;;;AA0BA,MAAaA,+BAAyD,OAAO,OAAO;CAClF,SAAS;CACT,eAAe;CAChB,CAAC"}

package/dist/diff.d.ts

@@ -0,0 +1,15 @@
+import { PricingDiffEntry, PricingSnapshot } from "./types.js";
+
+//#region src/diff.d.ts
+
+/**
+ * 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
+ */
+declare function diffPricing(before: PricingSnapshot, after: PricingSnapshot): ReadonlyArray<PricingDiffEntry>;
+//#endregion
+export { diffPricing };
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","names":[],"sources":["../src/diff.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;iBA0BgB,WAAA,SACN,wBACD,kBACN,cAAc"}

package/dist/diff.js

@@ -0,0 +1,65 @@
+//#region src/diff.ts
+const COMPARED_FIELDS = [
+	"inputUsdPerToken",
+	"outputUsdPerToken",
+	"cachedReadUsdPerToken",
+	"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
+*/
+function diffPricing(before, after) {
+	const beforeMap = indexBy(before.entries);
+	const afterMap = indexBy(after.entries);
+	const out = [];
+	for (const [key, entry] of beforeMap) {
+		const next = afterMap.get(key);
+		if (next === void 0) {
+			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) {
+	const out = /* @__PURE__ */ new Map();
+	for (const entry of entries) out.set(`${entry.provider}/${entry.model}/${entry.region ?? ""}`, entry);
+	return out;
+}
+
+//#endregion
+export { diffPricing };
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","names":["COMPARED_FIELDS: ReadonlyArray<keyof ModelPrice>","out: PricingDiffEntry[]"],"sources":["../src/diff.ts"],"sourcesContent":["/**\n * `diffPricing(...)` — produce a row-by-row delta between two pricing\n * snapshots. Used by the upcoming `graphorin pricing diff` CLI to\n * surface upstream changes after a `refresh`.\n *\n * @packageDocumentation\n */\n\nimport type { ModelPrice, PricingDiffEntry, PricingSnapshot } from './types.js';\n\nconst COMPARED_FIELDS: ReadonlyArray<keyof ModelPrice> = [\n  'inputUsdPerToken',\n  'outputUsdPerToken',\n  'cachedReadUsdPerToken',\n  'reasoningUsdPerToken',\n  'region',\n  'notes',\n];\n\n/**\n * Compare two snapshots and return one entry per (provider, model)\n * pair that has been added, removed, or changed. The result is sorted\n * by `(provider, model, kind)` for deterministic output.\n *\n * @stable\n */\nexport function diffPricing(\n  before: PricingSnapshot,\n  after: PricingSnapshot,\n): ReadonlyArray<PricingDiffEntry> {\n  const beforeMap = indexBy(before.entries);\n  const afterMap = indexBy(after.entries);\n  const out: PricingDiffEntry[] = [];\n\n  for (const [key, entry] of beforeMap) {\n    const next = afterMap.get(key);\n    if (next === undefined) {\n      out.push({ provider: entry.provider, model: entry.model, kind: 'removed', before: entry });\n      continue;\n    }\n    const changedFields = COMPARED_FIELDS.filter((field) => entry[field] !== next[field]);\n    if (changedFields.length > 0) {\n      out.push({\n        provider: entry.provider,\n        model: entry.model,\n        kind: 'changed',\n        before: entry,\n        after: next,\n        changedFields,\n      });\n    }\n  }\n\n  for (const [key, entry] of afterMap) {\n    if (beforeMap.has(key)) continue;\n    out.push({ provider: entry.provider, model: entry.model, kind: 'added', after: entry });\n  }\n\n  return out.sort((a, b) => {\n    if (a.provider !== b.provider) return a.provider < b.provider ? -1 : 1;\n    if (a.model !== b.model) return a.model < b.model ? -1 : 1;\n    return a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0;\n  });\n}\n\nfunction indexBy(entries: ReadonlyArray<ModelPrice>): Map<string, ModelPrice> {\n  const out = new Map<string, ModelPrice>();\n  for (const entry of entries) {\n    out.set(`${entry.provider}/${entry.model}/${entry.region ?? ''}`, entry);\n  }\n  return out;\n}\n"],"mappings":";AAUA,MAAMA,kBAAmD;CACvD;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;AASD,SAAgB,YACd,QACA,OACiC;CACjC,MAAM,YAAY,QAAQ,OAAO,QAAQ;CACzC,MAAM,WAAW,QAAQ,MAAM,QAAQ;CACvC,MAAMC,MAA0B,EAAE;AAElC,MAAK,MAAM,CAAC,KAAK,UAAU,WAAW;EACpC,MAAM,OAAO,SAAS,IAAI,IAAI;AAC9B,MAAI,SAAS,QAAW;AACtB,OAAI,KAAK;IAAE,UAAU,MAAM;IAAU,OAAO,MAAM;IAAO,MAAM;IAAW,QAAQ;IAAO,CAAC;AAC1F;;EAEF,MAAM,gBAAgB,gBAAgB,QAAQ,UAAU,MAAM,WAAW,KAAK,OAAO;AACrF,MAAI,cAAc,SAAS,EACzB,KAAI,KAAK;GACP,UAAU,MAAM;GAChB,OAAO,MAAM;GACb,MAAM;GACN,QAAQ;GACR,OAAO;GACP;GACD,CAAC;;AAIN,MAAK,MAAM,CAAC,KAAK,UAAU,UAAU;AACnC,MAAI,UAAU,IAAI,IAAI,CAAE;AACxB,MAAI,KAAK;GAAE,UAAU,MAAM;GAAU,OAAO,MAAM;GAAO,MAAM;GAAS,OAAO;GAAO,CAAC;;AAGzF,QAAO,IAAI,MAAM,GAAG,MAAM;AACxB,MAAI,EAAE,aAAa,EAAE,SAAU,QAAO,EAAE,WAAW,EAAE,WAAW,KAAK;AACrE,MAAI,EAAE,UAAU,EAAE,MAAO,QAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK;AACzD,SAAO,EAAE,OAAO,EAAE,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,IAAI;GACpD;;AAGJ,SAAS,QAAQ,SAA6D;CAC5E,MAAM,sBAAM,IAAI,KAAyB;AACzC,MAAK,MAAM,SAAS,QAClB,KAAI,IAAI,GAAG,MAAM,SAAS,GAAG,MAAM,MAAM,GAAG,MAAM,UAAU,MAAM,MAAM;AAE1E,QAAO"}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { DEFAULT_PRICING_AUTO_REFRESH, PricingAutoRefreshConfig, PricingConfig } from "./config.js";
+import { Cost, LookupPriceArgs, LookupPriceResult, ModelPrice, PricingDiffEntry, PricingSnapshot, PricingTraceSpanLike } from "./types.js";
+import { diffPricing } from "./diff.js";
+import { _resetLookupWarningsForTesting, calculateCost, lookupPrice, setLookupWarnSink } from "./lookup.js";
+import { MissingModelEntry, listMissingModels } from "./missing.js";
+import { RefreshPricingOptions, refreshPricing } from "./refresh.js";
+import { BUNDLED_SNAPSHOT, SNAPSHOT_DATE, computeEntriesDigest } from "./snapshot/bundled.js";
+
+//#region src/index.d.ts
+
+/**
+ * @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. Mirrors the `package.json` version. */
+declare const VERSION = "0.5.0";
+//#endregion
+export { BUNDLED_SNAPSHOT, type Cost, DEFAULT_PRICING_AUTO_REFRESH, type LookupPriceArgs, type LookupPriceResult, type MissingModelEntry, type ModelPrice, type PricingAutoRefreshConfig, type PricingConfig, type PricingDiffEntry, type PricingSnapshot, type PricingTraceSpanLike, type RefreshPricingOptions, SNAPSHOT_DATE, VERSION, _resetLookupWarningsForTesting, calculateCost, computeEntriesDigest, diffPricing, listMissingModels, lookupPrice, refreshPricing, setLookupWarnSink };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;AA4BA;;;;;;;;;;;;;;;;;;cAAa,OAAA"}

package/dist/index.js

@@ -0,0 +1,41 @@
+import { DEFAULT_PRICING_AUTO_REFRESH } from "./config.js";
+import { diffPricing } from "./diff.js";
+import { BUNDLED_SNAPSHOT, SNAPSHOT_DATE, computeEntriesDigest } from "./snapshot/bundled.js";
+import { _resetLookupWarningsForTesting, calculateCost, lookupPrice, setLookupWarnSink } from "./lookup.js";
+import { listMissingModels } from "./missing.js";
+import { refreshPricing } from "./refresh.js";
+import "./snapshot/index.js";
+
+//#region src/index.ts
+/**
+* @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. Mirrors the `package.json` version. */
+const VERSION = "0.5.0";
+
+//#endregion
+export { BUNDLED_SNAPSHOT, DEFAULT_PRICING_AUTO_REFRESH, SNAPSHOT_DATE, VERSION, _resetLookupWarningsForTesting, calculateCost, computeEntriesDigest, diffPricing, listMissingModels, lookupPrice, refreshPricing, setLookupWarnSink };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/lookup.d.ts

@@ -0,0 +1,52 @@
+import { LookupPriceArgs, LookupPriceResult, PricingSnapshot } from "./types.js";
+
+//#region src/lookup.d.ts
+
+/**
+ * Optional sink for the deduplicated WARN emitted on unknown models.
+ * Defaults to `console.warn`. Override in tests.
+ *
+ * @internal
+ */
+declare function setLookupWarnSink(sink: (line: string) => void): void;
+/**
+ * @internal — exposed for tests so the WARN-once cache can be reset.
+ */
+declare function _resetLookupWarningsForTesting(): void;
+/**
+ * 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
+ */
+declare function lookupPrice(args: LookupPriceArgs, snapshot?: PricingSnapshot): LookupPriceResult | null;
+/**
+ * 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` — cached reads are billed
+ *   separately at the cheaper cached rate, so pass the non-cached prompt count
+ *   to avoid double-billing.
+ * - `reasoningTokens` are billed at `outputUsdPerToken` unless the model entry
+ *   declares an explicit `reasoningUsdPerToken`.
+ *
+ * @stable
+ */
+declare function calculateCost(args: LookupPriceArgs & {
+  /** Non-cached prompt tokens (excludes `cachedReadTokens`). */
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly cachedReadTokens?: number;
+  readonly reasoningTokens?: number;
+}, snapshot?: PricingSnapshot): {
+  readonly amount: number;
+  readonly currency: 'USD';
+} | null;
+//#endregion
+export { _resetLookupWarningsForTesting, calculateCost, lookupPrice, setLookupWarnSink };
+//# sourceMappingURL=lookup.d.ts.map

package/dist/lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.d.ts","names":[],"sources":["../src/lookup.ts"],"sourcesContent":[],"mappings":";;;;;AAyGA;;;;;iBArFgB,iBAAA;;;;iBASA,8BAAA,CAAA;;;;;;;;;;iBAaA,WAAA,OACR,4BACI,kBACT;;;;;;;;;;;;;;;iBA4Da,aAAA,OACR;;;;;;cAOI"}

package/dist/lookup.js

@@ -0,0 +1,92 @@
+import { BUNDLED_SNAPSHOT } from "./snapshot/bundled.js";
+
+//#region src/lookup.ts
+/**
+* `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
+*/
+const WARNED = /* @__PURE__ */ new Set();
+/**
+* Optional sink for the deduplicated WARN emitted on unknown models.
+* Defaults to `console.warn`. Override in tests.
+*
+* @internal
+*/
+function setLookupWarnSink(sink) {
+	WARN_SINK = sink;
+}
+let WARN_SINK = (line) => console.warn(line);
+/**
+* @internal — exposed for tests so the WARN-once cache can be reset.
+*/
+function _resetLookupWarningsForTesting() {
+	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
+*/
+function lookupPrice(args, snapshot = BUNDLED_SNAPSHOT) {
+	const exact = snapshot.entries.find((entry) => entry.provider === args.provider && entry.model === args.model && (args.region === void 0 || entry.region === void 0 || entry.region === args.region));
+	if (exact !== void 0) return entryToResult(exact, snapshot);
+	const wildcard = snapshot.entries.find((entry) => entry.provider === args.provider && entry.model === "*");
+	if (wildcard !== void 0) return entryToResult(wildcard, snapshot);
+	warnOnce(args);
+	return null;
+}
+function entryToResult(entry, snapshot) {
+	return {
+		inputUsdPerToken: entry.inputUsdPerToken,
+		outputUsdPerToken: entry.outputUsdPerToken,
+		...entry.cachedReadUsdPerToken === void 0 ? {} : { cachedReadUsdPerToken: entry.cachedReadUsdPerToken },
+		...entry.reasoningUsdPerToken === void 0 ? {} : { reasoningUsdPerToken: entry.reasoningUsdPerToken },
+		source: snapshot.source,
+		snapshotDate: snapshot.snapshotDate
+	};
+}
+function warnOnce(args) {
+	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` — cached reads are billed
+*   separately at the cheaper cached rate, so pass the non-cached prompt count
+*   to avoid double-billing.
+* - `reasoningTokens` are billed at `outputUsdPerToken` unless the model entry
+*   declares an explicit `reasoningUsdPerToken`.
+*
+* @stable
+*/
+function calculateCost(args, snapshot = BUNDLED_SNAPSHOT) {
+	const price = lookupPrice(args, snapshot);
+	if (price === null) return null;
+	let amount = 0;
+	amount += price.inputUsdPerToken * args.inputTokens;
+	amount += price.outputUsdPerToken * args.outputTokens;
+	if (args.cachedReadTokens !== void 0 && price.cachedReadUsdPerToken !== void 0) amount += price.cachedReadUsdPerToken * args.cachedReadTokens;
+	if (args.reasoningTokens !== void 0) amount += (price.reasoningUsdPerToken ?? price.outputUsdPerToken) * args.reasoningTokens;
+	return {
+		amount,
+		currency: "USD"
+	};
+}
+
+//#endregion
+export { _resetLookupWarningsForTesting, calculateCost, lookupPrice, setLookupWarnSink };
+//# sourceMappingURL=lookup.js.map

package/dist/lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.js","names":["WARN_SINK: (line: string) => void"],"sources":["../src/lookup.ts"],"sourcesContent":["/**\n * `lookupPrice(...)` — resolve a per-token price for a given\n * (provider, model) pair against a snapshot. Returns `null` when the\n * model is unknown and emits one WARN per process-lifetime per\n * unknown (provider, model) pair.\n *\n * @packageDocumentation\n */\n\nimport { BUNDLED_SNAPSHOT } from './snapshot/bundled.js';\nimport type { LookupPriceArgs, LookupPriceResult, ModelPrice, PricingSnapshot } from './types.js';\n\nconst WARNED = new Set<string>();\n\n/**\n * Optional sink for the deduplicated WARN emitted on unknown models.\n * Defaults to `console.warn`. Override in tests.\n *\n * @internal\n */\nexport function setLookupWarnSink(sink: (line: string) => void): void {\n  WARN_SINK = sink;\n}\n\nlet WARN_SINK: (line: string) => void = (line) => console.warn(line);\n\n/**\n * @internal — exposed for tests so the WARN-once cache can be reset.\n */\nexport function _resetLookupWarningsForTesting(): void {\n  WARNED.clear();\n}\n\n/**\n * Resolve a per-token price for the (provider, model) pair. Returns\n * `null` when the snapshot does not contain an entry for the model.\n *\n * The function emits one WARN per process per unknown (provider, model)\n * pair so cost dashboards surface drift without spamming the log.\n *\n * @stable\n */\nexport function lookupPrice(\n  args: LookupPriceArgs,\n  snapshot: PricingSnapshot = BUNDLED_SNAPSHOT,\n): LookupPriceResult | null {\n  const exact = snapshot.entries.find(\n    (entry) =>\n      entry.provider === args.provider &&\n      entry.model === args.model &&\n      (args.region === undefined || entry.region === undefined || entry.region === args.region),\n  );\n\n  if (exact !== undefined) return entryToResult(exact, snapshot);\n\n  // Wildcard fallback — used by local providers (`provider: 'ollama', model: '*'`).\n  const wildcard = snapshot.entries.find(\n    (entry) => entry.provider === args.provider && entry.model === '*',\n  );\n  if (wildcard !== undefined) return entryToResult(wildcard, snapshot);\n\n  warnOnce(args);\n  return null;\n}\n\nfunction entryToResult(entry: ModelPrice, snapshot: PricingSnapshot): LookupPriceResult {\n  return {\n    inputUsdPerToken: entry.inputUsdPerToken,\n    outputUsdPerToken: entry.outputUsdPerToken,\n    ...(entry.cachedReadUsdPerToken === undefined\n      ? {}\n      : { cachedReadUsdPerToken: entry.cachedReadUsdPerToken }),\n    ...(entry.reasoningUsdPerToken === undefined\n      ? {}\n      : { reasoningUsdPerToken: entry.reasoningUsdPerToken }),\n    source: snapshot.source,\n    snapshotDate: snapshot.snapshotDate,\n  };\n}\n\nfunction warnOnce(args: LookupPriceArgs): void {\n  const key = `${args.provider}/${args.model}`;\n  if (WARNED.has(key)) return;\n  WARNED.add(key);\n  WARN_SINK(\n    `[graphorin/pricing] WARN: no pricing entry for ${args.provider}/${args.model}; ` +\n      'cost is null. Consider running `graphorin pricing refresh` or contributing the ' +\n      'entry upstream.',\n  );\n}\n\n/**\n * Multiply a per-token price by an integer token count. Returns `null`\n * when the price is unknown. Useful when caller wants to compute cost\n * for a single LLM call without instantiating the cost tracker.\n *\n * Token-count contract (PS-19):\n * - `inputTokens` **excludes** `cachedReadTokens` — cached reads are billed\n *   separately at the cheaper cached rate, so pass the non-cached prompt count\n *   to avoid double-billing.\n * - `reasoningTokens` are billed at `outputUsdPerToken` unless the model entry\n *   declares an explicit `reasoningUsdPerToken`.\n *\n * @stable\n */\nexport function calculateCost(\n  args: LookupPriceArgs & {\n    /** Non-cached prompt tokens (excludes `cachedReadTokens`). */\n    readonly inputTokens: number;\n    readonly outputTokens: number;\n    readonly cachedReadTokens?: number;\n    readonly reasoningTokens?: number;\n  },\n  snapshot: PricingSnapshot = BUNDLED_SNAPSHOT,\n): { readonly amount: number; readonly currency: 'USD' } | null {\n  const price = lookupPrice(args, snapshot);\n  if (price === null) return null;\n  let amount = 0;\n  // `inputTokens` is the NON-cached prompt; cached reads are billed separately\n  // at their own (cheaper) rate, so they must be excluded from `inputTokens` to\n  // avoid double-counting (PS-19).\n  amount += price.inputUsdPerToken * args.inputTokens;\n  amount += price.outputUsdPerToken * args.outputTokens;\n  if (args.cachedReadTokens !== undefined && price.cachedReadUsdPerToken !== undefined) {\n    amount += price.cachedReadUsdPerToken * args.cachedReadTokens;\n  }\n  if (args.reasoningTokens !== undefined) {\n    // PS-19: reasoning tokens follow completion (output) pricing unless the\n    // entry declares an explicit `reasoningUsdPerToken` — the documented\n    // contract that was previously billed at $0 for every bundled entry.\n    amount += (price.reasoningUsdPerToken ?? price.outputUsdPerToken) * args.reasoningTokens;\n  }\n  return { amount, currency: 'USD' };\n}\n"],"mappings":";;;;;;;;;;;AAYA,MAAM,yBAAS,IAAI,KAAa;;;;;;;AAQhC,SAAgB,kBAAkB,MAAoC;AACpE,aAAY;;AAGd,IAAIA,aAAqC,SAAS,QAAQ,KAAK,KAAK;;;;AAKpE,SAAgB,iCAAuC;AACrD,QAAO,OAAO;;;;;;;;;;;AAYhB,SAAgB,YACd,MACA,WAA4B,kBACF;CAC1B,MAAM,QAAQ,SAAS,QAAQ,MAC5B,UACC,MAAM,aAAa,KAAK,YACxB,MAAM,UAAU,KAAK,UACpB,KAAK,WAAW,UAAa,MAAM,WAAW,UAAa,MAAM,WAAW,KAAK,QACrF;AAED,KAAI,UAAU,OAAW,QAAO,cAAc,OAAO,SAAS;CAG9D,MAAM,WAAW,SAAS,QAAQ,MAC/B,UAAU,MAAM,aAAa,KAAK,YAAY,MAAM,UAAU,IAChE;AACD,KAAI,aAAa,OAAW,QAAO,cAAc,UAAU,SAAS;AAEpE,UAAS,KAAK;AACd,QAAO;;AAGT,SAAS,cAAc,OAAmB,UAA8C;AACtF,QAAO;EACL,kBAAkB,MAAM;EACxB,mBAAmB,MAAM;EACzB,GAAI,MAAM,0BAA0B,SAChC,EAAE,GACF,EAAE,uBAAuB,MAAM,uBAAuB;EAC1D,GAAI,MAAM,yBAAyB,SAC/B,EAAE,GACF,EAAE,sBAAsB,MAAM,sBAAsB;EACxD,QAAQ,SAAS;EACjB,cAAc,SAAS;EACxB;;AAGH,SAAS,SAAS,MAA6B;CAC7C,MAAM,MAAM,GAAG,KAAK,SAAS,GAAG,KAAK;AACrC,KAAI,OAAO,IAAI,IAAI,CAAE;AACrB,QAAO,IAAI,IAAI;AACf,WACE,kDAAkD,KAAK,SAAS,GAAG,KAAK,MAAM,oGAG/E;;;;;;;;;;;;;;;;AAiBH,SAAgB,cACd,MAOA,WAA4B,kBACkC;CAC9D,MAAM,QAAQ,YAAY,MAAM,SAAS;AACzC,KAAI,UAAU,KAAM,QAAO;CAC3B,IAAI,SAAS;AAIb,WAAU,MAAM,mBAAmB,KAAK;AACxC,WAAU,MAAM,oBAAoB,KAAK;AACzC,KAAI,KAAK,qBAAqB,UAAa,MAAM,0BAA0B,OACzE,WAAU,MAAM,wBAAwB,KAAK;AAE/C,KAAI,KAAK,oBAAoB,OAI3B,YAAW,MAAM,wBAAwB,MAAM,qBAAqB,KAAK;AAE3E,QAAO;EAAE;EAAQ,UAAU;EAAO"}

package/dist/missing.d.ts

@@ -0,0 +1,24 @@
+import { PricingSnapshot, PricingTraceSpanLike } from "./types.js";
+
+//#region src/missing.d.ts
+
+/**
+ * Single missing-model row.
+ *
+ * @stable
+ */
+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
+ */
+declare function listMissingModels(spans: Iterable<PricingTraceSpanLike>, snapshot?: PricingSnapshot): ReadonlyArray<MissingModelEntry>;
+//#endregion
+export { MissingModelEntry, listMissingModels };
+//# sourceMappingURL=missing.d.ts.map

package/dist/missing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing.d.ts","names":[],"sources":["../src/missing.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAsBiB,iBAAA;;;;;;;;;;;iBAYD,iBAAA,QACP,SAAS,kCACN,kBACT,cAAc"}

package/dist/missing.js

@@ -0,0 +1,62 @@
+import { BUNDLED_SNAPSHOT } from "./snapshot/bundled.js";
+import { lookupPrice } from "./lookup.js";
+
+//#region src/missing.ts
+/**
+* `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
+*/
+/**
+* Return one entry per (provider, model) pair that the snapshot does
+* not recognise, sorted by descending occurrence count.
+*
+* @stable
+*/
+function listMissingModels(spans, snapshot = BUNDLED_SNAPSHOT) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const span of spans) {
+		const provider = stringAttr(span, ["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 === void 0) 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, keys) {
+	for (const key of keys) {
+		const value = span.attributes[key];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+	return null;
+}
+
+//#endregion
+export { listMissingModels };
+//# sourceMappingURL=missing.js.map

package/dist/missing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing.js","names":[],"sources":["../src/missing.ts"],"sourcesContent":["/**\n * `listMissingModels(...)` — scan a sequence of trace spans and return\n * the unique (provider, model) pairs that the snapshot does not\n * recognise.\n *\n * The function reads `gen_ai.system` + `gen_ai.request.model` (the\n * canonical OpenTelemetry GenAI attributes) and falls back to the\n * Graphorin-prefixed `graphorin.provider.id` /\n * `graphorin.provider.model` pair when `gen_ai.*` is absent.\n *\n * @packageDocumentation\n */\n\nimport { lookupPrice } from './lookup.js';\nimport { BUNDLED_SNAPSHOT } from './snapshot/bundled.js';\nimport type { PricingSnapshot, PricingTraceSpanLike } from './types.js';\n\n/**\n * Single missing-model row.\n *\n * @stable\n */\nexport interface MissingModelEntry {\n  readonly provider: string;\n  readonly model: string;\n  readonly count: number;\n}\n\n/**\n * Return one entry per (provider, model) pair that the snapshot does\n * not recognise, sorted by descending occurrence count.\n *\n * @stable\n */\nexport function listMissingModels(\n  spans: Iterable<PricingTraceSpanLike>,\n  snapshot: PricingSnapshot = BUNDLED_SNAPSHOT,\n): ReadonlyArray<MissingModelEntry> {\n  const seen = new Map<string, MissingModelEntry & { count: number }>();\n  for (const span of spans) {\n    const provider = stringAttr(span, ['gen_ai.system', 'graphorin.provider.id']);\n    const model = stringAttr(span, [\n      'gen_ai.request.model',\n      'gen_ai.response.model',\n      'graphorin.provider.model',\n    ]);\n    if (provider === null || model === null) continue;\n    if (lookupPrice({ provider, model }, snapshot) !== null) continue;\n    const key = `${provider}/${model}`;\n    const existing = seen.get(key);\n    if (existing === undefined) {\n      seen.set(key, { provider, model, count: 1 });\n    } else {\n      seen.set(key, { provider, model, count: existing.count + 1 });\n    }\n  }\n  return [...seen.values()].sort((a, b) => b.count - a.count);\n}\n\nfunction stringAttr(span: PricingTraceSpanLike, keys: ReadonlyArray<string>): string | null {\n  for (const key of keys) {\n    const value = span.attributes[key];\n    if (typeof value === 'string' && value.length > 0) return value;\n  }\n  return null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAkCA,SAAgB,kBACd,OACA,WAA4B,kBACM;CAClC,MAAM,uBAAO,IAAI,KAAoD;AACrE,MAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,WAAW,WAAW,MAAM,CAAC,iBAAiB,wBAAwB,CAAC;EAC7E,MAAM,QAAQ,WAAW,MAAM;GAC7B;GACA;GACA;GACD,CAAC;AACF,MAAI,aAAa,QAAQ,UAAU,KAAM;AACzC,MAAI,YAAY;GAAE;GAAU;GAAO,EAAE,SAAS,KAAK,KAAM;EACzD,MAAM,MAAM,GAAG,SAAS,GAAG;EAC3B,MAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,MAAI,aAAa,OACf,MAAK,IAAI,KAAK;GAAE;GAAU;GAAO,OAAO;GAAG,CAAC;MAE5C,MAAK,IAAI,KAAK;GAAE;GAAU;GAAO,OAAO,SAAS,QAAQ;GAAG,CAAC;;AAGjE,QAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM;;AAG7D,SAAS,WAAW,MAA4B,MAA4C;AAC1F,MAAK,MAAM,OAAO,MAAM;EACtB,MAAM,QAAQ,KAAK,WAAW;AAC9B,MAAI,OAAO,UAAU,YAAY,MAAM,SAAS,EAAG,QAAO;;AAE5D,QAAO"}

package/dist/refresh.d.ts

@@ -0,0 +1,44 @@
+import { PricingSnapshot } from "./types.js";
+
+//#region src/refresh.d.ts
+
+/**
+ * Configuration shape for {@link refreshPricing}. The `fetchImpl`
+ * override exists so tests can exercise the function without making
+ * a real network call.
+ *
+ * @stable
+ */
+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;
+}
+/**
+ * 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
+ */
+declare function refreshPricing(opts: RefreshPricingOptions): Promise<PricingSnapshot>;
+//#endregion
+export { RefreshPricingOptions, refreshPricing };
+//# sourceMappingURL=refresh.d.ts.map

package/dist/refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.d.ts","names":[],"sources":["../src/refresh.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;UAwBiB,qBAAA;;;;qBAII,SAAS;;8BAEA;;;;;;;;;;;;;;oBAcV;;;;;;;;;iBAUE,cAAA,OAAqB,wBAAwB,QAAQ"}

package/dist/refresh.js

@@ -0,0 +1,83 @@
+import { computeEntriesDigest } from "./snapshot/bundled.js";
+
+//#region src/refresh.ts
+/**
+* `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
+*/
+/**
+* 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
+*/
+async function refreshPricing(opts) {
+	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 ?? 3e4;
+	const timeoutSignal = AbortSignal.timeout(timeoutMs);
+	const signal = opts.signal === void 0 ? timeoutSignal : AbortSignal.any([opts.signal, timeoutSignal]);
+	let res;
+	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 entries = parseEntries(await res.json());
+	const snapshotDate = opts.snapshotDate ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+	const version = opts.version ?? "graphorin/0.1+refreshed";
+	return Object.freeze({
+		version,
+		source: opts.url,
+		snapshotDate,
+		currency: "USD",
+		sha256: computeEntriesDigest(entries),
+		entries
+	});
+}
+function parseEntries(body) {
+	if (body === null || typeof body !== "object") throw new Error("refreshPricing: response body is not an object");
+	let raw;
+	if (Array.isArray(body)) raw = body;
+	else {
+		raw = body.entries;
+		if (!Array.isArray(raw)) throw new Error("refreshPricing: response object is missing the `entries` array");
+	}
+	const entries = raw.map(parseEntry);
+	return Object.freeze(entries);
+}
+function parseEntry(raw) {
+	if (raw === null || typeof raw !== "object") throw new Error("refreshPricing: pricing entry is not an object");
+	const e = raw;
+	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.reasoningUsdPerToken === "number" ? { reasoningUsdPerToken: e.reasoningUsdPerToken } : {},
+		...typeof e.region === "string" ? { region: e.region } : {},
+		...typeof e.notes === "string" ? { notes: e.notes } : {}
+	});
+}
+
+//#endregion
+export { refreshPricing };
+//# sourceMappingURL=refresh.js.map

package/dist/refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.js","names":["res: Awaited<ReturnType<typeof fetchImpl>>","raw: unknown"],"sources":["../src/refresh.ts"],"sourcesContent":["/**\n * `refreshPricing(...)` — opt-in network call. The framework never\n * invokes this automatically; it exists so the CLI (`graphorin\n * pricing refresh`) and operator scripts can pull a fresh snapshot\n * without re-installing the package.\n *\n * The function fetches the supplied URL as JSON and validates the\n * shape against the {@link PricingSnapshot} contract. The bundled\n * snapshot is **not** mutated; callers persist the refreshed\n * snapshot to disk and reload it explicitly.\n *\n * @packageDocumentation\n */\n\nimport { computeEntriesDigest } from './snapshot/bundled.js';\nimport type { ModelPrice, PricingSnapshot } from './types.js';\n\n/**\n * Configuration shape for {@link refreshPricing}. The `fetchImpl`\n * override exists so tests can exercise the function without making\n * a real network call.\n *\n * @stable\n */\nexport interface RefreshPricingOptions {\n  /** Snapshot URL — typically the upstream pricing JSON. */\n  readonly url: string;\n  /** Optional headers (auth, conditional GET, etc.). */\n  readonly headers?: Readonly<Record<string, string>>;\n  /** Optional fetch override — useful in tests. */\n  readonly fetchImpl?: typeof fetch;\n  /** Override the snapshot date stamped on the result. Defaults to today. */\n  readonly snapshotDate?: string;\n  /** Override the snapshot version string. Defaults to `'graphorin/0.1+refreshed'`. */\n  readonly version?: string;\n  /**\n   * Hard timeout for the network fetch in milliseconds. Default\n   * `30000`. Aborts the request (and throws) if the upstream is slow\n   * or unreachable so `graphorin pricing refresh` cannot hang. Pass an\n   * explicit {@link RefreshPricingOptions.signal} to manage\n   * cancellation yourself; the two are combined.\n   */\n  readonly timeoutMs?: number;\n  /** Caller-supplied abort signal, combined with the timeout. */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Pull a fresh snapshot from the supplied URL and return it. Network\n * failures and shape mismatches surface as thrown errors so the CLI\n * can surface them to the operator.\n *\n * @stable\n */\nexport async function refreshPricing(opts: RefreshPricingOptions): Promise<PricingSnapshot> {\n  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;\n  if (typeof fetchImpl !== 'function') {\n    throw new TypeError(\n      'refreshPricing: no fetch implementation available. Provide `fetchImpl` ' +\n        'explicitly or run on a Node.js version with global fetch (>= 18).',\n    );\n  }\n  const timeoutMs = opts.timeoutMs ?? 30_000;\n  const timeoutSignal = AbortSignal.timeout(timeoutMs);\n  const signal =\n    opts.signal === undefined ? timeoutSignal : AbortSignal.any([opts.signal, timeoutSignal]);\n  let res: Awaited<ReturnType<typeof fetchImpl>>;\n  try {\n    res = await fetchImpl(opts.url, { headers: opts.headers ?? {}, signal });\n  } catch (err) {\n    if (timeoutSignal.aborted) {\n      throw new Error(`refreshPricing: timed out after ${timeoutMs} ms fetching ${opts.url}`, {\n        cause: err,\n      });\n    }\n    throw err;\n  }\n  if (!res.ok) {\n    throw new Error(`refreshPricing: HTTP ${res.status} ${res.statusText} from ${opts.url}`);\n  }\n  const body = (await res.json()) as unknown;\n  const entries = parseEntries(body);\n  const snapshotDate = opts.snapshotDate ?? new Date().toISOString().slice(0, 10);\n  const version = opts.version ?? 'graphorin/0.1+refreshed';\n  return Object.freeze<PricingSnapshot>({\n    version,\n    source: opts.url,\n    snapshotDate,\n    currency: 'USD',\n    sha256: computeEntriesDigest(entries),\n    entries,\n  });\n}\n\nfunction parseEntries(body: unknown): ReadonlyArray<ModelPrice> {\n  if (body === null || typeof body !== 'object') {\n    throw new Error('refreshPricing: response body is not an object');\n  }\n  // Two accepted shapes:\n  //   - `{ entries: ModelPrice[] }`\n  //   - `ModelPrice[]`\n  let raw: unknown;\n  if (Array.isArray(body)) {\n    raw = body;\n  } else {\n    raw = (body as { entries?: unknown }).entries;\n    if (!Array.isArray(raw)) {\n      throw new Error('refreshPricing: response object is missing the `entries` array');\n    }\n  }\n  const entries = (raw as ReadonlyArray<unknown>).map(parseEntry);\n  return Object.freeze(entries);\n}\n\nfunction parseEntry(raw: unknown): ModelPrice {\n  if (raw === null || typeof raw !== 'object') {\n    throw new Error('refreshPricing: pricing entry is not an object');\n  }\n  const e = raw as Partial<ModelPrice>;\n  if (typeof e.provider !== 'string' || typeof e.model !== 'string') {\n    throw new Error('refreshPricing: pricing entry is missing provider / model');\n  }\n  if (typeof e.inputUsdPerToken !== 'number' || typeof e.outputUsdPerToken !== 'number') {\n    throw new Error(\n      `refreshPricing: pricing entry ${e.provider}/${e.model} is missing input / output prices`,\n    );\n  }\n  return Object.freeze({\n    provider: e.provider,\n    model: e.model,\n    inputUsdPerToken: e.inputUsdPerToken,\n    outputUsdPerToken: e.outputUsdPerToken,\n    ...(typeof e.cachedReadUsdPerToken === 'number'\n      ? { cachedReadUsdPerToken: e.cachedReadUsdPerToken }\n      : {}),\n    ...(typeof e.reasoningUsdPerToken === 'number'\n      ? { reasoningUsdPerToken: e.reasoningUsdPerToken }\n      : {}),\n    ...(typeof e.region === 'string' ? { region: e.region } : {}),\n    ...(typeof e.notes === 'string' ? { notes: e.notes } : {}),\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsDA,eAAsB,eAAe,MAAuD;CAC1F,MAAM,YAAY,KAAK,aAAa,WAAW;AAC/C,KAAI,OAAO,cAAc,WACvB,OAAM,IAAI,UACR,2IAED;CAEH,MAAM,YAAY,KAAK,aAAa;CACpC,MAAM,gBAAgB,YAAY,QAAQ,UAAU;CACpD,MAAM,SACJ,KAAK,WAAW,SAAY,gBAAgB,YAAY,IAAI,CAAC,KAAK,QAAQ,cAAc,CAAC;CAC3F,IAAIA;AACJ,KAAI;AACF,QAAM,MAAM,UAAU,KAAK,KAAK;GAAE,SAAS,KAAK,WAAW,EAAE;GAAE;GAAQ,CAAC;UACjE,KAAK;AACZ,MAAI,cAAc,QAChB,OAAM,IAAI,MAAM,mCAAmC,UAAU,eAAe,KAAK,OAAO,EACtF,OAAO,KACR,CAAC;AAEJ,QAAM;;AAER,KAAI,CAAC,IAAI,GACP,OAAM,IAAI,MAAM,wBAAwB,IAAI,OAAO,GAAG,IAAI,WAAW,QAAQ,KAAK,MAAM;CAG1F,MAAM,UAAU,aADF,MAAM,IAAI,MAAM,CACI;CAClC,MAAM,eAAe,KAAK,iCAAgB,IAAI,MAAM,EAAC,aAAa,CAAC,MAAM,GAAG,GAAG;CAC/E,MAAM,UAAU,KAAK,WAAW;AAChC,QAAO,OAAO,OAAwB;EACpC;EACA,QAAQ,KAAK;EACb;EACA,UAAU;EACV,QAAQ,qBAAqB,QAAQ;EACrC;EACD,CAAC;;AAGJ,SAAS,aAAa,MAA0C;AAC9D,KAAI,SAAS,QAAQ,OAAO,SAAS,SACnC,OAAM,IAAI,MAAM,iDAAiD;CAKnE,IAAIC;AACJ,KAAI,MAAM,QAAQ,KAAK,CACrB,OAAM;MACD;AACL,QAAO,KAA+B;AACtC,MAAI,CAAC,MAAM,QAAQ,IAAI,CACrB,OAAM,IAAI,MAAM,iEAAiE;;CAGrF,MAAM,UAAW,IAA+B,IAAI,WAAW;AAC/D,QAAO,OAAO,OAAO,QAAQ;;AAG/B,SAAS,WAAW,KAA0B;AAC5C,KAAI,QAAQ,QAAQ,OAAO,QAAQ,SACjC,OAAM,IAAI,MAAM,iDAAiD;CAEnE,MAAM,IAAI;AACV,KAAI,OAAO,EAAE,aAAa,YAAY,OAAO,EAAE,UAAU,SACvD,OAAM,IAAI,MAAM,4DAA4D;AAE9E,KAAI,OAAO,EAAE,qBAAqB,YAAY,OAAO,EAAE,sBAAsB,SAC3E,OAAM,IAAI,MACR,iCAAiC,EAAE,SAAS,GAAG,EAAE,MAAM,mCACxD;AAEH,QAAO,OAAO,OAAO;EACnB,UAAU,EAAE;EACZ,OAAO,EAAE;EACT,kBAAkB,EAAE;EACpB,mBAAmB,EAAE;EACrB,GAAI,OAAO,EAAE,0BAA0B,WACnC,EAAE,uBAAuB,EAAE,uBAAuB,GAClD,EAAE;EACN,GAAI,OAAO,EAAE,yBAAyB,WAClC,EAAE,sBAAsB,EAAE,sBAAsB,GAChD,EAAE;EACN,GAAI,OAAO,EAAE,WAAW,WAAW,EAAE,QAAQ,EAAE,QAAQ,GAAG,EAAE;EAC5D,GAAI,OAAO,EAAE,UAAU,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE;EAC1D,CAAC"}

package/dist/snapshot/bundled.d.ts

@@ -0,0 +1,25 @@
+import { ModelPrice, PricingSnapshot } from "../types.js";
+
+//#region src/snapshot/bundled.d.ts
+
+/** @internal — used for `lookupPrice` defaults. */
+declare const SNAPSHOT_DATE = "2026-04-30";
+/**
+ * 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
+ */
+declare function computeEntriesDigest(entries: ReadonlyArray<ModelPrice>): string;
+/**
+ * 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
+ */
+declare const BUNDLED_SNAPSHOT: PricingSnapshot;
+//#endregion
+export { BUNDLED_SNAPSHOT, SNAPSHOT_DATE, computeEntriesDigest };
+//# sourceMappingURL=bundled.d.ts.map

package/dist/snapshot/bundled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundled.d.ts","names":[],"sources":["../../src/snapshot/bundled.ts"],"sourcesContent":[],"mappings":";;;;;cAkBa,aAAA;;;;;;;;iBAoIG,oBAAA,UAA8B,cAAc;;;;;;;;cAsB/C,kBAAkB"}

package/dist/snapshot/bundled.js

@@ -0,0 +1,157 @@
+import { createHash } from "node:crypto";
+
+//#region src/snapshot/bundled.ts
+/**
+* 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
+*/
+/** @internal — used for `lookupPrice` defaults. */
+const SNAPSHOT_DATE = "2026-04-30";
+const ENTRIES = Object.freeze([
+	{
+		provider: "anthropic",
+		model: "claude-3-5-sonnet-20241022",
+		inputUsdPerToken: 3 / 1e6,
+		outputUsdPerToken: 15 / 1e6,
+		cachedReadUsdPerToken: .3 / 1e6
+	},
+	{
+		provider: "anthropic",
+		model: "claude-3-5-haiku-20241022",
+		inputUsdPerToken: .8 / 1e6,
+		outputUsdPerToken: 4 / 1e6,
+		cachedReadUsdPerToken: .08 / 1e6
+	},
+	{
+		provider: "anthropic",
+		model: "claude-3-opus-20240229",
+		inputUsdPerToken: 15 / 1e6,
+		outputUsdPerToken: 75 / 1e6,
+		cachedReadUsdPerToken: 1.5 / 1e6
+	},
+	{
+		provider: "openai",
+		model: "gpt-4o-2024-11-20",
+		inputUsdPerToken: 2.5 / 1e6,
+		outputUsdPerToken: 10 / 1e6,
+		cachedReadUsdPerToken: 1.25 / 1e6
+	},
+	{
+		provider: "openai",
+		model: "gpt-4o-mini-2024-07-18",
+		inputUsdPerToken: .15 / 1e6,
+		outputUsdPerToken: .6 / 1e6,
+		cachedReadUsdPerToken: .075 / 1e6
+	},
+	{
+		provider: "openai",
+		model: "o1-2024-12-17",
+		inputUsdPerToken: 15 / 1e6,
+		outputUsdPerToken: 60 / 1e6,
+		cachedReadUsdPerToken: 7.5 / 1e6
+	},
+	{
+		provider: "openai",
+		model: "o3-mini-2025-01-31",
+		inputUsdPerToken: 1.1 / 1e6,
+		outputUsdPerToken: 4.4 / 1e6,
+		cachedReadUsdPerToken: .55 / 1e6
+	},
+	{
+		provider: "google",
+		model: "gemini-1.5-pro-002",
+		inputUsdPerToken: 1.25 / 1e6,
+		outputUsdPerToken: 5 / 1e6,
+		cachedReadUsdPerToken: .3125 / 1e6
+	},
+	{
+		provider: "google",
+		model: "gemini-1.5-flash-002",
+		inputUsdPerToken: .075 / 1e6,
+		outputUsdPerToken: .3 / 1e6,
+		cachedReadUsdPerToken: .01875 / 1e6
+	},
+	{
+		provider: "mistral",
+		model: "mistral-large-2411",
+		inputUsdPerToken: 2 / 1e6,
+		outputUsdPerToken: 6 / 1e6
+	},
+	{
+		provider: "mistral",
+		model: "mistral-small-2503",
+		inputUsdPerToken: .2 / 1e6,
+		outputUsdPerToken: .6 / 1e6
+	},
+	{
+		provider: "cohere",
+		model: "command-r-plus-08-2024",
+		inputUsdPerToken: 2.5 / 1e6,
+		outputUsdPerToken: 10 / 1e6
+	},
+	{
+		provider: "cohere",
+		model: "command-r-08-2024",
+		inputUsdPerToken: .15 / 1e6,
+		outputUsdPerToken: .6 / 1e6
+	},
+	{
+		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."
+	}
+]);
+/**
+* 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
+*/
+function computeEntriesDigest(entries) {
+	const canonical = JSON.stringify(entries.map((entry) => sortKeys(entry)));
+	return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+function sortKeys(value) {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(sortKeys);
+	const out = {};
+	for (const key of Object.keys(value).sort()) out[key] = sortKeys(value[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
+*/
+const BUNDLED_SNAPSHOT = 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
+});
+
+//#endregion
+export { BUNDLED_SNAPSHOT, SNAPSHOT_DATE, computeEntriesDigest };
+//# sourceMappingURL=bundled.js.map

package/dist/snapshot/bundled.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundled.js","names":["ENTRIES: ReadonlyArray<ModelPrice>","out: Record<string, unknown>","BUNDLED_SNAPSHOT: PricingSnapshot"],"sources":["../../src/snapshot/bundled.ts"],"sourcesContent":["/**\n * Bundled pricing snapshot. The catalogue is intentionally small —\n * operators wanting the full upstream catalogue should run the opt-in\n * `refreshPricing(...)` flow at build time and persist the result to\n * a custom snapshot file.\n *\n * Prices are stored in **USD per token** (i.e. divide the per-million\n * upstream prices by 1_000_000). Numbers are accurate to the snapshot\n * date; consumers are expected to refresh on a regular cadence.\n *\n * @packageDocumentation\n */\n\nimport { createHash } from 'node:crypto';\n\nimport type { ModelPrice, PricingSnapshot } from '../types.js';\n\n/** @internal — used for `lookupPrice` defaults. */\nexport const SNAPSHOT_DATE = '2026-04-30';\n\nconst ENTRIES: ReadonlyArray<ModelPrice> = Object.freeze([\n  // -----------------------------------------------------------------\n  // Anthropic\n  // -----------------------------------------------------------------\n  {\n    provider: 'anthropic',\n    model: 'claude-3-5-sonnet-20241022',\n    inputUsdPerToken: 3 / 1_000_000,\n    outputUsdPerToken: 15 / 1_000_000,\n    cachedReadUsdPerToken: 0.3 / 1_000_000,\n  },\n  {\n    provider: 'anthropic',\n    model: 'claude-3-5-haiku-20241022',\n    inputUsdPerToken: 0.8 / 1_000_000,\n    outputUsdPerToken: 4 / 1_000_000,\n    cachedReadUsdPerToken: 0.08 / 1_000_000,\n  },\n  {\n    provider: 'anthropic',\n    model: 'claude-3-opus-20240229',\n    inputUsdPerToken: 15 / 1_000_000,\n    outputUsdPerToken: 75 / 1_000_000,\n    cachedReadUsdPerToken: 1.5 / 1_000_000,\n  },\n  // -----------------------------------------------------------------\n  // OpenAI\n  // -----------------------------------------------------------------\n  {\n    provider: 'openai',\n    model: 'gpt-4o-2024-11-20',\n    inputUsdPerToken: 2.5 / 1_000_000,\n    outputUsdPerToken: 10 / 1_000_000,\n    cachedReadUsdPerToken: 1.25 / 1_000_000,\n  },\n  {\n    provider: 'openai',\n    model: 'gpt-4o-mini-2024-07-18',\n    inputUsdPerToken: 0.15 / 1_000_000,\n    outputUsdPerToken: 0.6 / 1_000_000,\n    cachedReadUsdPerToken: 0.075 / 1_000_000,\n  },\n  {\n    provider: 'openai',\n    model: 'o1-2024-12-17',\n    inputUsdPerToken: 15 / 1_000_000,\n    outputUsdPerToken: 60 / 1_000_000,\n    cachedReadUsdPerToken: 7.5 / 1_000_000,\n  },\n  {\n    provider: 'openai',\n    model: 'o3-mini-2025-01-31',\n    inputUsdPerToken: 1.1 / 1_000_000,\n    outputUsdPerToken: 4.4 / 1_000_000,\n    cachedReadUsdPerToken: 0.55 / 1_000_000,\n  },\n  // -----------------------------------------------------------------\n  // Google\n  // -----------------------------------------------------------------\n  {\n    provider: 'google',\n    model: 'gemini-1.5-pro-002',\n    inputUsdPerToken: 1.25 / 1_000_000,\n    outputUsdPerToken: 5 / 1_000_000,\n    cachedReadUsdPerToken: 0.3125 / 1_000_000,\n  },\n  {\n    provider: 'google',\n    model: 'gemini-1.5-flash-002',\n    inputUsdPerToken: 0.075 / 1_000_000,\n    outputUsdPerToken: 0.3 / 1_000_000,\n    cachedReadUsdPerToken: 0.01875 / 1_000_000,\n  },\n  // -----------------------------------------------------------------\n  // Mistral\n  // -----------------------------------------------------------------\n  {\n    provider: 'mistral',\n    model: 'mistral-large-2411',\n    inputUsdPerToken: 2 / 1_000_000,\n    outputUsdPerToken: 6 / 1_000_000,\n  },\n  {\n    provider: 'mistral',\n    model: 'mistral-small-2503',\n    inputUsdPerToken: 0.2 / 1_000_000,\n    outputUsdPerToken: 0.6 / 1_000_000,\n  },\n  // -----------------------------------------------------------------\n  // Cohere\n  // -----------------------------------------------------------------\n  {\n    provider: 'cohere',\n    model: 'command-r-plus-08-2024',\n    inputUsdPerToken: 2.5 / 1_000_000,\n    outputUsdPerToken: 10 / 1_000_000,\n  },\n  {\n    provider: 'cohere',\n    model: 'command-r-08-2024',\n    inputUsdPerToken: 0.15 / 1_000_000,\n    outputUsdPerToken: 0.6 / 1_000_000,\n  },\n  // -----------------------------------------------------------------\n  // Local providers — documented as zero-cost so cost rollups still\n  // include the call counts.\n  // -----------------------------------------------------------------\n  {\n    provider: 'ollama',\n    model: '*',\n    inputUsdPerToken: 0,\n    outputUsdPerToken: 0,\n    notes: 'Local Ollama deployment — operator-priced.',\n  },\n  {\n    provider: 'graphorin-llamacpp',\n    model: '*',\n    inputUsdPerToken: 0,\n    outputUsdPerToken: 0,\n    notes: 'Local llama.cpp deployment — operator-priced.',\n  },\n] as const);\n\n/**\n * Compute a deterministic SHA-256 of the entries. Sorting the entry\n * keys before serialisation keeps the digest stable across Node\n * versions / object-property-iteration orderings.\n *\n * @internal\n */\nexport function computeEntriesDigest(entries: ReadonlyArray<ModelPrice>): string {\n  const canonical = JSON.stringify(entries.map((entry) => sortKeys(entry as unknown)));\n  return createHash('sha256').update(canonical, 'utf8').digest('hex');\n}\n\nfunction sortKeys(value: unknown): unknown {\n  if (value === null || typeof value !== 'object') return value;\n  if (Array.isArray(value)) return value.map(sortKeys);\n  const out: Record<string, unknown> = {};\n  for (const key of Object.keys(value as Record<string, unknown>).sort()) {\n    out[key] = sortKeys((value as Record<string, unknown>)[key]);\n  }\n  return out;\n}\n\n/**\n * The bundled snapshot. The `sha256` digest is computed over the\n * canonical JSON form of `entries` at module load time so consumers\n * can verify integrity without trusting the package metadata.\n *\n * @stable\n */\nexport const BUNDLED_SNAPSHOT: PricingSnapshot = Object.freeze({\n  version: 'graphorin/0.1',\n  source:\n    'https://github.com/o-stepper/graphorin/tree/main/packages/pricing/src/snapshot/bundled.ts',\n  snapshotDate: SNAPSHOT_DATE,\n  currency: 'USD',\n  sha256: computeEntriesDigest(ENTRIES),\n  entries: ENTRIES,\n});\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,MAAa,gBAAgB;AAE7B,MAAMA,UAAqC,OAAO,OAAO;CAIvD;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,IAAI;EACtB,mBAAmB,KAAK;EACxB,uBAAuB,KAAM;EAC9B;CACD;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,KAAM;EACxB,mBAAmB,IAAI;EACvB,uBAAuB,MAAO;EAC/B;CACD;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,KAAK;EACvB,mBAAmB,KAAK;EACxB,uBAAuB,MAAM;EAC9B;CAID;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,MAAM;EACxB,mBAAmB,KAAK;EACxB,uBAAuB,OAAO;EAC/B;CACD;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,MAAO;EACzB,mBAAmB,KAAM;EACzB,uBAAuB,OAAQ;EAChC;CACD;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,KAAK;EACvB,mBAAmB,KAAK;EACxB,uBAAuB,MAAM;EAC9B;CACD;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,MAAM;EACxB,mBAAmB,MAAM;EACzB,uBAAuB,MAAO;EAC/B;CAID;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,OAAO;EACzB,mBAAmB,IAAI;EACvB,uBAAuB,QAAS;EACjC;CACD;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,OAAQ;EAC1B,mBAAmB,KAAM;EACzB,uBAAuB,SAAU;EAClC;CAID;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,IAAI;EACtB,mBAAmB,IAAI;EACxB;CACD;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,KAAM;EACxB,mBAAmB,KAAM;EAC1B;CAID;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,MAAM;EACxB,mBAAmB,KAAK;EACzB;CACD;EACE,UAAU;EACV,OAAO;EACP,kBAAkB,MAAO;EACzB,mBAAmB,KAAM;EAC1B;CAKD;EACE,UAAU;EACV,OAAO;EACP,kBAAkB;EAClB,mBAAmB;EACnB,OAAO;EACR;CACD;EACE,UAAU;EACV,OAAO;EACP,kBAAkB;EAClB,mBAAmB;EACnB,OAAO;EACR;CACF,CAAU;;;;;;;;AASX,SAAgB,qBAAqB,SAA4C;CAC/E,MAAM,YAAY,KAAK,UAAU,QAAQ,KAAK,UAAU,SAAS,MAAiB,CAAC,CAAC;AACpF,QAAO,WAAW,SAAS,CAAC,OAAO,WAAW,OAAO,CAAC,OAAO,MAAM;;AAGrE,SAAS,SAAS,OAAyB;AACzC,KAAI,UAAU,QAAQ,OAAO,UAAU,SAAU,QAAO;AACxD,KAAI,MAAM,QAAQ,MAAM,CAAE,QAAO,MAAM,IAAI,SAAS;CACpD,MAAMC,MAA+B,EAAE;AACvC,MAAK,MAAM,OAAO,OAAO,KAAK,MAAiC,CAAC,MAAM,CACpE,KAAI,OAAO,SAAU,MAAkC,KAAK;AAE9D,QAAO;;;;;;;;;AAUT,MAAaC,mBAAoC,OAAO,OAAO;CAC7D,SAAS;CACT,QACE;CACF,cAAc;CACd,UAAU;CACV,QAAQ,qBAAqB,QAAQ;CACrC,SAAS;CACV,CAAC"}

package/dist/snapshot/index.d.ts

@@ -0,0 +1,2 @@
+import { BUNDLED_SNAPSHOT, SNAPSHOT_DATE, computeEntriesDigest } from "./bundled.js";
+export { BUNDLED_SNAPSHOT, SNAPSHOT_DATE, computeEntriesDigest };

package/dist/snapshot/index.js

@@ -0,0 +1,3 @@
+import { BUNDLED_SNAPSHOT, SNAPSHOT_DATE, computeEntriesDigest } from "./bundled.js";
+
+export { BUNDLED_SNAPSHOT, SNAPSHOT_DATE, computeEntriesDigest };

package/dist/types.d.ts

@@ -0,0 +1,92 @@
+import { Cost } from "@graphorin/core";
+
+//#region src/types.d.ts
+
+/**
+ * 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
+ */
+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 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
+ */
+interface PricingSnapshot {
+  readonly version: string;
+  readonly source: string;
+  readonly snapshotDate: string;
+  readonly currency: 'USD';
+  readonly sha256: string;
+  readonly entries: ReadonlyArray<ModelPrice>;
+}
+/**
+ * Lookup criteria.
+ *
+ * @stable
+ */
+interface LookupPriceArgs {
+  readonly provider: string;
+  readonly model: string;
+  readonly region?: string;
+}
+/**
+ * Result of {@link lookupPrice} when the model is known.
+ *
+ * @stable
+ */
+interface LookupPriceResult {
+  readonly inputUsdPerToken: number;
+  readonly outputUsdPerToken: number;
+  readonly cachedReadUsdPerToken?: number;
+  readonly reasoningUsdPerToken?: number;
+  readonly source: string;
+  readonly snapshotDate: string;
+}
+/**
+ * Result row reported by {@link diffPricing}.
+ *
+ * @stable
+ */
+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
+ */
+interface PricingTraceSpanLike {
+  readonly attributes: Readonly<Record<string, unknown>>;
+}
+//#endregion
+export { type Cost, LookupPriceArgs, LookupPriceResult, ModelPrice, PricingDiffEntry, PricingSnapshot, PricingTraceSpanLike };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";;;;AAiEA;AAcA;;;;;;AAgBA;UA/EiB,UAAA;;;;;;;;;;;;;;;;;;;;;;;UAwBA,eAAA;;;;;;oBAMG,cAAc;;;;;;;UAQjB,eAAA;;;;;;;;;;UAWA,iBAAA;;;;;;;;;;;;;UAcA,gBAAA;;;;oBAIG;mBACD;2BACQ,oBAAoB;;;;;;;;;UAU9B,oBAAA;uBACM,SAAS"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@graphorin/pricing",
+  "version": "0.5.0",
+  "description": "Bundled LLM pricing snapshot for the Graphorin framework. Ships per-provider, per-model input / output / cached-read prices alongside provenance metadata, a `lookupPrice(...)` resolver, snapshot diffing utilities, an opt-in `refreshPricing(...)` hook (network gated; never automatic), and `listMissingModels(...)` for trace audits.",
+  "license": "MIT",
+  "author": "Oleksiy Stepurenko",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/pricing",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/pricing"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "pricing",
+    "tokens",
+    "cost",
+    "llm"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./snapshot": {
+      "types": "./dist/snapshot/index.d.ts",
+      "import": "./dist/snapshot/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@graphorin/core": "0.5.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {},
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}