floe-guard 0.17.0 → 0.18.0

package/dist/adapters/livekit.cjs

@@ -50,7 +50,7 @@ var UnpriceableLegError = class extends FloeGuardError {
   constructor(vendor, mode) {
     const shown = vendor === null ? "None" : `'${vendor}'`;
     super(
-      `Cannot price ${mode} vendor ${shown}: not in the bundled voice cost map (or its entry has the wrong unit for a ${mode} leg) and no per-unit override was given. The guard cannot enforce a budget on spend it cannot measure. Pass a per-unit rate to enable enforcement.`
+      `Cannot price ${mode} vendor ${shown}: no per-call override, no usable entry in your rate card, and none in the bundled per-unit leg map \u2014 or an entry exists whose mode/unit is wrong for a ${mode} leg, which is refused rather than reinterpreted. The guard cannot enforce a budget on spend it cannot measure. Declare the rate you pay in your rate card (FLOE_RATE_CARD) or pass a per-unit override to enable enforcement.`
     );
     this.name = "UnpriceableVoiceError";
     this.vendor = vendor;
@@ -77,7 +77,7 @@ function preCall(guard, options = {}) {
 var cost_map_default = {
   __meta__: {
     generated_at: "2026-09-14",
-    source: "LiteLLM public model prices (bundled snapshot); voice rates verified from vendor list pages"
+    source: "LiteLLM public model prices (bundled snapshot); per-unit leg rates (stt/tts/telephony/sms/ocr/gpu/avatar) hand-curated from vendor list pages, leg rates last retrieved 2026-09-18"
   },
   "chat-latest": {
     input_cost_per_token: 5e-6,
@@ -1287,7 +1287,7 @@ var cost_map_default = {
     litellm_provider: "openai",
     mode: "embedding"
   },
-  __voice__: {
+  __legs__: {
     "deepgram-nova-3": {
       mode: "stt",
       unit: "usd_per_second",
@@ -1365,29 +1365,355 @@ var cost_map_default = {
       unit: "usd_per_minute",
       rate: 4e-3,
       provider: "twilio"
+    },
+    "twilio-sms-us-outbound": {
+      mode: "sms",
+      unit: "usd_per_segment",
+      rate: 83e-4,
+      provider: "twilio",
+      source_url: "https://www.twilio.com/en-us/sms/pricing/us",
+      retrieved_at: "2026-09-18"
+    },
+    "twilio-sms-us-inbound": {
+      mode: "sms",
+      unit: "usd_per_segment",
+      rate: 83e-4,
+      provider: "twilio",
+      source_url: "https://www.twilio.com/en-us/sms/pricing/us",
+      retrieved_at: "2026-09-18"
+    },
+    "telnyx-sms-us-outbound": {
+      mode: "sms",
+      unit: "usd_per_segment",
+      rate: 4e-3,
+      provider: "telnyx",
+      source_url: "https://telnyx.com/pricing/messaging",
+      retrieved_at: "2026-09-18"
+    },
+    "telnyx-sms-us-inbound": {
+      mode: "sms",
+      unit: "usd_per_segment",
+      rate: 4e-3,
+      provider: "telnyx",
+      source_url: "https://telnyx.com/pricing/messaging",
+      retrieved_at: "2026-09-18"
+    },
+    "modal-b300": {
+      mode: "gpu",
+      unit: "usd_per_gpu_second",
+      rate: 1972e-6,
+      provider: "modal",
+      source_url: "https://modal.com/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "modal-b200": {
+      mode: "gpu",
+      unit: "usd_per_gpu_second",
+      rate: 1736e-6,
+      provider: "modal",
+      source_url: "https://modal.com/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "modal-h200-sxm": {
+      mode: "gpu",
+      unit: "usd_per_gpu_second",
+      rate: 1261e-6,
+      provider: "modal",
+      source_url: "https://modal.com/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "modal-h100-sxm5": {
+      mode: "gpu",
+      unit: "usd_per_gpu_second",
+      rate: 1097e-6,
+      provider: "modal",
+      source_url: "https://modal.com/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "modal-rtx-pro-6000": {
+      mode: "gpu",
+      unit: "usd_per_gpu_second",
+      rate: 842e-6,
+      provider: "modal",
+      source_url: "https://modal.com/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "modal-a100-80gb": {
+      mode: "gpu",
+      unit: "usd_per_gpu_second",
+      rate: 694e-6,
+      provider: "modal",
+      source_url: "https://modal.com/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "modal-a100-40gb": {
+      mode: "gpu",
+      unit: "usd_per_gpu_second",
+      rate: 583e-6,
+      provider: "modal",
+      source_url: "https://modal.com/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "modal-l40s": {
+      mode: "gpu",
+      unit: "usd_per_gpu_second",
+      rate: 542e-6,
+      provider: "modal",
+      source_url: "https://modal.com/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "modal-a10": {
+      mode: "gpu",
+      unit: "usd_per_gpu_second",
+      rate: 306e-6,
+      provider: "modal",
+      source_url: "https://modal.com/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "modal-l4": {
+      mode: "gpu",
+      unit: "usd_per_gpu_second",
+      rate: 222e-6,
+      provider: "modal",
+      source_url: "https://modal.com/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "modal-t4": {
+      mode: "gpu",
+      unit: "usd_per_gpu_second",
+      rate: 164e-6,
+      provider: "modal",
+      source_url: "https://modal.com/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "gcp-vision-text-detection": {
+      mode: "ocr",
+      unit: "usd_per_page",
+      rate: 15e-4,
+      provider: "gcp",
+      source_url: "https://cloud.google.com/vision/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "gcp-vision-document-text-detection": {
+      mode: "ocr",
+      unit: "usd_per_page",
+      rate: 15e-4,
+      provider: "gcp",
+      source_url: "https://cloud.google.com/vision/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "aws-textract-detect-document-text": {
+      mode: "ocr",
+      unit: "usd_per_page",
+      rate: 15e-4,
+      provider: "aws",
+      source_url: "https://aws.amazon.com/textract/pricing/",
+      retrieved_at: "2026-09-18"
+    },
+    "aws-textract-analyze-forms": {
+      mode: "ocr",
+      unit: "usd_per_page",
+      rate: 0.05,
+      provider: "aws",
+      source_url: "https://aws.amazon.com/textract/pricing/",
+      retrieved_at: "2026-09-18"
+    },
+    "aws-textract-analyze-tables": {
+      mode: "ocr",
+      unit: "usd_per_page",
+      rate: 0.015,
+      provider: "aws",
+      source_url: "https://aws.amazon.com/textract/pricing/",
+      retrieved_at: "2026-09-18"
+    },
+    "tavus-cvi-starter": {
+      mode: "avatar",
+      unit: "usd_per_minute",
+      rate: 0.37,
+      provider: "tavus",
+      source_url: "https://www.tavus.io/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "gcp-vision-text-detection-high-volume": {
+      mode: "ocr",
+      unit: "usd_per_page",
+      rate: 6e-4,
+      provider: "gcp",
+      source_url: "https://cloud.google.com/vision/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "gcp-vision-document-text-detection-high-volume": {
+      mode: "ocr",
+      unit: "usd_per_page",
+      rate: 6e-4,
+      provider: "gcp",
+      source_url: "https://cloud.google.com/vision/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "aws-textract-detect-document-text-high-volume": {
+      mode: "ocr",
+      unit: "usd_per_page",
+      rate: 6e-4,
+      provider: "aws",
+      source_url: "https://aws.amazon.com/textract/pricing/",
+      retrieved_at: "2026-09-18"
+    },
+    "tavus-cvi-growth": {
+      mode: "avatar",
+      unit: "usd_per_minute",
+      rate: 0.32,
+      provider: "tavus",
+      source_url: "https://www.tavus.io/pricing",
+      retrieved_at: "2026-09-18"
+    },
+    "tavus-cvi-business": {
+      mode: "avatar",
+      unit: "usd_per_minute",
+      rate: 0.26,
+      provider: "tavus",
+      source_url: "https://www.tavus.io/pricing",
+      retrieved_at: "2026-09-18"
     }
   }
 };
 
-// src/voice-pricing.ts
-var VOICE_MAP = cost_map_default["__voice__"] ?? {};
+// src/leg-units.ts
 var unitForMode = {
   stt: "usd_per_second",
   tts: "usd_per_1k_chars",
-  telephony: "usd_per_minute"
+  telephony: "usd_per_minute",
+  sms: "usd_per_segment",
+  ocr: "usd_per_page",
+  gpu: "usd_per_gpu_second",
+  avatar: "usd_per_minute"
 };
+var LEG_MODES = Object.keys(unitForMode);
+
+// src/rate-card.ts
+var RATE_CARD_ENV = "FLOE_RATE_CARD";
+var ALLOWED_ENTRY_KEYS = /* @__PURE__ */ new Set([
+  "mode",
+  "unit",
+  "rate",
+  "provider",
+  "source_url",
+  "retrieved_at",
+  "confirmed"
+]);
+var REQUIRED_ENTRY_KEYS = ["mode", "unit", "rate"];
+var RATE_CARD = {};
+function envValue(name) {
+  const p = globalThis.process;
+  return p?.env?.[name];
+}
+function validateEntry(key, entry) {
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+    throw new TypeError(`Rate card entry '${key}' must be an object.`);
+  }
+  const e = entry;
+  const extra = Object.keys(e).filter((k) => !ALLOWED_ENTRY_KEYS.has(k)).sort();
+  if (extra.length) {
+    throw new TypeError(
+      `Rate card entry '${key}' has unknown field(s): ${extra.join(", ")}. Allowed: ${[...ALLOWED_ENTRY_KEYS].sort().join(", ")}.`
+    );
+  }
+  const missing = REQUIRED_ENTRY_KEYS.filter((k) => !(k in e));
+  if (missing.length) {
+    throw new TypeError(`Rate card entry '${key}' is missing required field(s): ${missing.join(", ")}.`);
+  }
+  for (const field of ["mode", "unit"]) {
+    if (typeof e[field] !== "string" || !e[field]) {
+      throw new TypeError(`Rate card entry '${key}': ${field} must be a non-empty string.`);
+    }
+  }
+  const mode = e.mode;
+  if (!LEG_MODES.includes(mode)) {
+    throw new TypeError(
+      `Rate card entry '${key}': unknown mode '${mode}'. Expected one of: ${[...LEG_MODES].sort().join(", ")}.`
+    );
+  }
+  const expectedUnit = unitForMode[mode];
+  if (e.unit !== expectedUnit) {
+    throw new TypeError(
+      `Rate card entry '${key}': a '${mode}' leg bills in '${expectedUnit}', got '${String(e.unit)}'. The unit is not a label \u2014 pricing multiplies by it, so the wrong one mis-bills by whatever the conversion factor is.`
+    );
+  }
+  const rate = e.rate;
+  if (typeof rate !== "number" || !Number.isFinite(rate) || rate < 0) {
+    throw new RangeError(
+      `Rate card entry '${key}': rate must be a finite, non-negative number, got ${String(rate)}.`
+    );
+  }
+  if ("confirmed" in e && typeof e.confirmed !== "boolean") {
+    throw new TypeError(`Rate card entry '${key}': confirmed must be true or false.`);
+  }
+  for (const field of ["provider", "source_url", "retrieved_at"]) {
+    if (field in e && typeof e[field] !== "string") {
+      throw new TypeError(`Rate card entry '${key}': ${field} must be a string.`);
+    }
+  }
+}
+function loadRateCard(source) {
+  let input = source;
+  if (input === void 0 || input === null) {
+    const fromEnv = envValue(RATE_CARD_ENV);
+    if (!fromEnv) return {};
+    input = fromEnv;
+  }
+  let raw;
+  if (typeof input === "string") {
+    try {
+      raw = JSON.parse(input);
+    } catch (e) {
+      throw new TypeError(
+        `Rate card is not valid JSON: ${e.message}. ${RATE_CARD_ENV} holds inline JSON in this package, not a file path.`
+      );
+    }
+  } else {
+    raw = input;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError("Rate card must be a JSON object mapping vendor keys to entries.");
+  }
+  const out = {};
+  for (const [key, entry] of Object.entries(raw)) {
+    validateEntry(key, entry);
+    out[key] = { ...entry };
+  }
+  return out;
+}
+function freeze(card) {
+  for (const entry of Object.values(card)) Object.freeze(entry);
+  return Object.freeze(card);
+}
+function currentRateCard() {
+  return RATE_CARD;
+}
+RATE_CARD = freeze(loadRateCard());
+
+// src/voice-pricing.ts
+var rawCostMap = cost_map_default;
+var VOICE_MAP = rawCostMap["__legs__"] ?? rawCostMap["__voice__"] ?? {};
 function finiteNonNegative(value) {
   return typeof value === "number" && Number.isFinite(value) && value >= 0;
 }
-function lookupVoiceRate(model, mode) {
+function entryIsUsable(entry, mode) {
+  if (typeof entry !== "object" || entry === null) return false;
+  const e = entry;
+  if (e.mode !== mode) return false;
+  if (e.unit !== unitForMode[mode]) return false;
+  return finiteNonNegative(e.rate);
+}
+function lookupLegEntry(model, mode) {
   if (model === null || model === void 0) return null;
+  const card = currentRateCard();
+  const declared = Object.prototype.hasOwnProperty.call(card, model) ? card[model] : void 0;
+  if (declared && declared.mode === mode) {
+    return entryIsUsable(declared, mode) ? { entry: declared, source: "rate_card" } : null;
+  }
   const entry = Object.prototype.hasOwnProperty.call(VOICE_MAP, model) ? VOICE_MAP[model] : void 0;
-  if (!entry) return null;
-  if (entry.mode !== mode) return null;
-  if (entry.unit !== unitForMode[mode]) return null;
-  const rate = entry.rate;
-  if (!finiteNonNegative(rate)) return null;
-  return rate;
+  if (entryIsUsable(entry, mode)) return { entry, source: "cost_map" };
+  return null;
 }
 function resolveVoiceRate(model, mode, override) {
   if (override !== void 0 && override !== null) {
@@ -1396,20 +1722,46 @@ function resolveVoiceRate(model, mode, override) {
         `voice ${mode} override must be a finite, non-negative number, got ${override}`
       );
     }
-    return { mode, unit: unitForMode[mode], rate: override, source: "override" };
+    return {
+      mode,
+      unit: unitForMode[mode],
+      rate: override,
+      source: "override",
+      confirmed: true
+    };
   }
-  const rate = lookupVoiceRate(model, mode);
-  if (rate === null) throw new UnpriceableLegError(model ?? null, mode);
-  return { mode, unit: unitForMode[mode], rate, source: "cost_map" };
+  const found = lookupLegEntry(model, mode);
+  if (found === null) throw new UnpriceableLegError(model ?? null, mode);
+  const { entry, source } = found;
+  const str = (v) => typeof v === "string" ? v : void 0;
+  return {
+    mode,
+    unit: unitForMode[mode],
+    rate: entry.rate,
+    source,
+    ...str(entry.provider) !== void 0 ? { provider: str(entry.provider) } : {},
+    ...str(entry.source_url) !== void 0 ? { source_url: str(entry.source_url) } : {},
+    ...str(entry.retrieved_at) !== void 0 ? { retrieved_at: str(entry.retrieved_at) } : {},
+    // A declared rate is confirmed unless the card says otherwise (an imported or
+    // draft card can mark entries unconfirmed); a bundled list price is
+    // UNCONFIRMED until a human accepts it.
+    confirmed: typeof entry.confirmed === "boolean" ? entry.confirmed : source === "rate_card"
+  };
 }
 function voiceLegCost(mode, quantity, rate) {
   if (!Number.isFinite(quantity)) {
     throw new RangeError(`voice ${mode} quantity must be a finite number, got ${quantity}`);
   }
   const q = Math.max(0, quantity);
-  if (mode === "stt") return q * rate;
+  if (mode === "stt" || // seconds * $/second
+  mode === "telephony" || // minutes * $/minute
+  mode === "sms" || // segments * $/segment
+  mode === "ocr" || // pages * $/page
+  mode === "gpu" || // gpu-seconds * $/gpu-second
+  mode === "avatar") {
+    return q * rate;
+  }
   if (mode === "tts") return q / 1e3 * rate;
-  if (mode === "telephony") return q * rate;
   throw new RangeError(`unknown voice mode ${mode}`);
 }
 function priceVoiceLeg(mode, quantity, options = {}) {