@outputai/core 0.15.1-next.4a437bf.0 → 0.15.1-next.8ef04e2.0

package/src/llm/utils/google_vertex_auth.js

@@ -0,0 +1,31 @@
+import { ValidationError } from '#errors';
+
+const envVar = 'GCP_CREDENTIALS_JSON';
+
+const unescapeLinebreaks = v => v.replaceAll( '\\n', '\n' );
+
+const decodeBase64 = v => Buffer.from( v, 'base64' ).toString( 'utf8' );
+
+const parseJson = v => {
+  try {
+    return JSON.parse( v );
+  } catch ( cause ) {
+    throw new ValidationError( `Invalid ${envVar}: value is neither JSON nor base64 encoded JSON`, { cause } );
+  }
+};
+
+export const resolveGoogleVertexAuthOptions = () => {
+  const value = process.env[envVar]?.trim();
+
+  if ( !value ) {
+    return {};
+  }
+
+  const credentials = parseJson( value.startsWith( '{' ) ? value : decodeBase64( value ) );
+
+  if ( credentials.private_key ) {
+    credentials.private_key = unescapeLinebreaks( credentials.private_key );
+  }
+
+  return { googleAuthOptions: { credentials } };
+};

package/src/llm/utils/grounding.js

@@ -0,0 +1,49 @@
+/**
+ * Grounding with Google Search is billed per request, not per token, and models.dev carries no
+ * per-request rate, so the table lives here. Gemini 3 bills per Grounding Query; Gemini 2.x bills
+ * per Grounding Prompt, once, regardless of query count. Different units, so the family decides
+ * both the label and the amount. Rates are price-per-million to match `ppm` semantics.
+ * Verified 2026-09-01: https://cloud.google.com/vertex-ai/generative-ai/pricing
+ */
+const UNITS = [
+  { match: /^gemini-3/, label: 'grounding_query', ppm: 14_000, perQuery: true },
+  { match: /^gemini-2/, label: 'grounding_prompt', ppm: 35_000, perQuery: false }
+];
+
+/**
+ * Unknown family: still record the quantity so the call is visibly unpriced rather than silently
+ * token-only. No rate resolves for this label, so the item lands MISSING and the cost attribute
+ * goes INCOMPLETE.
+ */
+export const GROUNDING_UNKNOWN_LABEL = 'grounding';
+
+export const GroundingPpmMap = new Map( UNITS.map( u => [ u.label, u.ppm ] ) );
+
+/**
+ * Extracts the billable grounding quantity from provider metadata.
+ *
+ * Counts web-search grounding only. `groundingMetadata` also carries `imageSearchQueries` and
+ * `retrievalQueries`, which bill on their own terms; neither appears in current traffic. Extend
+ * here if image or retrieval grounding is enabled.
+ *
+ * @param {string} modelId - Id of the model that produced the response
+ * @param {object} [providerMetadata] - AI SDK provider metadata of a single step
+ * @returns {{ label: string, amount: number } | null} Grounding label and amount, or null when ungrounded
+ */
+export const parseGroundingUsage = ( modelId, providerMetadata ) => {
+  const meta = providerMetadata?.vertex ?? providerMetadata?.google;
+  const queries = meta?.groundingMetadata?.webSearchQueries;
+  if ( !Array.isArray( queries ) || queries.length === 0 ) {
+    return null;
+  }
+
+  const unit = UNITS.find( u => u.match.test( modelId ) );
+  if ( !unit ) {
+    return { label: GROUNDING_UNKNOWN_LABEL, amount: queries.length };
+  }
+
+  return {
+    label: unit.label,
+    amount: unit.perQuery ? queries.length : 1
+  };
+};

package/src/llm/utils/image.js

@@ -0,0 +1,37 @@
+import { Logger } from '#runtime_logger';
+
+/**
+ * Get the approximate file size from a base64 string.
+ * @param {string} b64data
+ * @returns {number} Size in bytes
+ */
+export const calculateBase64FileSize = b64data => {
+  if ( typeof b64data !== 'string' ) {
+    return null;
+  }
+  const baseSize = b64data.length * ( 3 / 4 );
+  const paddingSize = [ b64data.at( -2 ), b64data.at( -1 ) ].filter( v => v === '=' ).length;
+  return baseSize - paddingSize;
+};
+
+/**
+ * Return a serialized version of the images from the AI SDK response.
+ * It contains only the file size and the media-type
+ *
+ * @param {object} response
+ * @returns {Array<{size: number, mediaType: string}>}
+ */
+export const serializeImagesFromResponse = response => {
+  try {
+    if ( !Array.isArray( response?.images ) ) {
+      return [];
+    }
+    return response.images
+      .filter( image => image !== null && typeof image === 'object' )
+      .map( ( { base64, mediaType } ) => ( { size: calculateBase64FileSize( base64 ), mediaType } ) );
+
+  } catch ( error ) {
+    Logger.error( 'Image serialization failed', { namespace: 'LLM', error: error?.message || String( error ) } );
+    return [];
+  }
+};

package/src/llm/utils/legacy_cost_attribute.js

@@ -0,0 +1,75 @@
+import { BaseAttribute } from '#trace_attribute';
+import Decimal from 'decimal.js';
+
+const exists = v => Number.isFinite( v );
+
+/** Legacy priced usage attribute retained for trace compatibility. */
+export class LLMUsageLegacy extends BaseAttribute {
+  static TYPE = 'llm:usage';
+  modelId;
+  usage = [];
+  total;
+  tokensUsed;
+
+  constructor( modelId, usage ) {
+    super( LLMUsageLegacy.TYPE );
+    this.modelId = modelId;
+    this.usage = usage;
+    this.total = Decimal( 0 );
+    this.tokensUsed = Decimal( 0 );
+
+    for ( const item of usage ) {
+      item.total = Decimal( item.amount ).div( 1_000_000 ).mul( item.ppm ).toNumber();
+      this.total = this.total.add( item.total );
+      this.tokensUsed = this.tokensUsed.add( item.amount );
+    }
+
+    this.total = this.total.toNumber();
+    this.tokensUsed = this.tokensUsed.toNumber();
+  }
+}
+
+export const convertCostToLegacy = cost => {
+  if ( !cost || cost.items.every( v => v.status === 'missing' ) ) {
+    return null;
+  }
+
+  const usage = [];
+
+  // items
+  const inputItem = cost.items.find( ( { group, label, total } ) => group === 'input' && !label && exists( total ) );
+  const noCacheItem = cost.items.find( ( { label, total } ) => label === 'no_cache' && exists( total ) );
+  const cacheReadItem = cost.items.find( ( { label } ) => label === 'cache_read' ); // even when it doesn't have total
+  const cacheWriteItem = cost.items.find( ( { label, total } ) => label === 'cache_write' && exists( total ) );
+  const outputItem = cost.items.find( ( { group, label, total } ) => group === 'output' && !label && exists( total ) );
+  const textItem = cost.items.find( ( { label, total } ) => label === 'text' && exists( total ) );
+  const reasoningItem = cost.items.find( ( { label, total } ) => label === 'reasoning' && exists( total ) );
+
+  if ( inputItem ) {
+    usage.push( { type: 'input', ppm: inputItem.ppm, amount: inputItem.amount } );
+  } else {
+    if ( noCacheItem || cacheWriteItem ) {
+      const totalInput = ( noCacheItem?.amount ?? 0 ) + ( cacheWriteItem?.amount ?? 0 );
+      const ppm = noCacheItem?.ppm ?? cacheWriteItem?.ppm;
+      usage.push( { type: 'input', ppm, amount: totalInput } );
+    }
+
+    if ( cacheReadItem ) {
+      const ppm = [ 'fallback', 'missing' ].includes( cacheReadItem.status ) ? 0 : cacheReadItem.ppm;
+      usage.push( { type: 'input_cached', ppm, amount: cacheReadItem.amount } );
+    }
+  }
+
+  if ( outputItem ) {
+    usage.push( { type: 'output', ppm: outputItem.ppm, amount: outputItem.amount } );
+  } else {
+    if ( textItem ) {
+      usage.push( { type: 'output', ppm: textItem.ppm, amount: textItem.amount } );
+    }
+    if ( reasoningItem ) {
+      usage.push( { type: 'reasoning', ppm: reasoningItem.ppm, amount: reasoningItem.amount } );
+    }
+  }
+
+  return new LLMUsageLegacy( cost.modelId, usage );
+};

package/src/llm/utils/metering.js

@@ -0,0 +1,126 @@
+import { parseLLMUsage } from './usage.js';
+import { calculateCosts } from './cost.js';
+import { stepEventBus } from '#bus';
+import { addEventActionWithContext, EventAction } from '#tracing';
+import { Logger } from '#runtime_logger';
+import { convertCostToLegacy } from './legacy_cost_attribute.js';
+
+/**
+ * Collects the usage of a single LLM call and bills it once.
+ *
+ * Steps are recorded as the SDK lifecycle reports them, and the response is handed to `bill()` by
+ * the paths that have one, so a call that throws after the model ran is still billed for what it
+ * spent. `bill()` parses the usage, costs it, attaches both as trace attributes and emits the
+ * metering events; it never throws.
+ */
+export class Metering {
+  #recordedSteps = [];
+  #billed = false;
+  #prompt;
+  #traceId;
+  #attributes = {
+    usage: null,
+    cost: null,
+    legacy: null
+  };
+
+  async #createAttributes( { usage, steps } ) {
+    this.#attributes.usage = parseLLMUsage( { prompt: this.#prompt, usage, steps } );
+    if ( this.#attributes.usage ) {
+      this.#attributes.cost = await calculateCosts( this.#attributes.usage );
+      if ( this.#attributes.cost ) {
+        // @TEMP Preserve the deprecated event and trace attribute for legacy consumers.
+        this.#attributes.legacy = convertCostToLegacy( this.#attributes.cost );
+      }
+    }
+  }
+
+  #attachAttributes() {
+    if ( this.#attributes.usage ) {
+      addEventActionWithContext( EventAction.ADD_ATTR, { id: this.#traceId, details: this.#attributes.usage } );
+    }
+    if ( this.#attributes.cost ) {
+      addEventActionWithContext( EventAction.ADD_ATTR, { id: this.#traceId, details: this.#attributes.cost } );
+    }
+    if ( this.#attributes.legacy ) {
+      addEventActionWithContext( EventAction.ADD_ATTR, { id: this.#traceId, details: this.#attributes.legacy } );
+    }
+  }
+
+  #emitEvents() {
+    if ( this.#attributes.usage ) {
+      stepEventBus.emit( 'sdk:llm:generation:metering', structuredClone( { cost: this.#attributes.cost, usage: this.#attributes.usage } ) );
+    }
+    if ( this.#attributes.legacy ) {
+      stepEventBus.emit( 'sdk:cost:llm:request', structuredClone( this.#attributes.legacy ) );
+    }
+  }
+
+  /**
+   * @param {object} args
+   * @param {string} args.traceId - Trace event the usage and cost attributes are attached to
+   * @param {object} args.prompt - Loaded prompt (`config.provider` / `config.model` used for cost)
+   */
+  constructor( { traceId, prompt } ) {
+    this.#traceId = traceId;
+    this.#prompt = prompt;
+  }
+
+  /**
+   * Records a completed step, used as the usage source when the call ends without a response.
+   *
+   * @param {object} step - AI SDK step
+   */
+  recordStep = step => {
+    if ( !this.#billed ) {
+      this.#recordedSteps.push( step );
+    }
+  };
+
+  /**
+   * Bills the recorded usage: parses it, costs it, attaches the trace attributes and emits the
+   * metering events. Later calls and later records are ignored, so it is safe to call from every
+   * path that can end the call. Read the result from `attributes`.
+   *
+   * An empty collector is not a final answer: the SDK reports a stream error before the steps that
+   * preceded it, so billing stays open until there is usage or a step to report.
+   *
+   * @param {object} [response] - AI SDK response, whose aggregate usage and steps take precedence
+   *   over the recorded steps; omitted by the paths that end without one
+   * @returns {Promise<void>}
+   */
+  bill = async ( response = null ) => {
+    if ( this.#billed ) {
+      return;
+    }
+
+    try {
+      const responseSteps = response?.steps;
+      const steps = Array.isArray( responseSteps ) && responseSteps.length > 0 ? responseSteps : this.#recordedSteps;
+      const usage = response?.usage;
+
+      if ( !usage && steps.length === 0 ) {
+        return;
+      }
+
+      this.#billed = true;
+
+      await this.#createAttributes( { usage, steps } );
+      this.#attachAttributes();
+      this.#emitEvents();
+
+    } catch ( error ) {
+      Logger.error( 'Metering failed', { namespace: 'LLM', error: error?.message || String( error ) } );
+    }
+  };
+
+  /**
+   * Attributes produced by `bill()`; each one is null until billed, and stays null when there is
+   * nothing to report.
+   *
+   * @returns {{ usage: object|null, cost: object|null, legacy: object|null }}
+   */
+  get attributes() {
+    return this.#attributes;
+  }
+}

package/src/llm/utils/models.js

@@ -0,0 +1,15 @@
+import { ValidationError } from '#errors';
+import { getProvider } from '../ai_provider.js';
+
+/** Load a model from a prompt */
+export const loadTextModel = prompt => getProvider( prompt.config.provider )( prompt.config.model );
+
+/** Load an image model from a prompt. */
+export const loadImageModel = prompt => {
+  const provider = getProvider( prompt.config.provider );
+  const imageModelFactory = provider.image ?? provider.imageModel;
+  if ( typeof imageModelFactory !== 'function' ) {
+    throw new ValidationError( `Provider "${prompt.config.provider}" used by prompt "${prompt.name}" does not support image models.` );
+  }
+  return imageModelFactory( prompt.config.model );
+};

package/src/llm/utils/models_pricing.js

@@ -0,0 +1,93 @@
+import { Logger } from '#runtime_logger';
+import { EnvHttpProxyAgent, fetch } from 'undici';
+import modelsPricingSnapshot from './models_pricing_snapshot.json' with { type: 'json' };
+
+const logger = Logger.createLogger( 'LLM' );
+const costTableUrl = 'https://models.dev/api.json';
+const cacheTTL = 1000 * 60 * 60 * 24; // 1 day
+const cooldownTTL = 1000 * 60 * 10; // 10 minutes
+
+/* Ignore HTTP/2. Check: https://github.com/growthxai/output/issues/299 */
+const dispatcher = new EnvHttpProxyAgent( { allowH2: false } );
+
+export const cache = {
+  content: null,
+  expiresAt: 0
+};
+
+export const Freshness = {
+  LIVE: 'live',
+  CACHED: 'cached',
+  STALE: 'stale',
+  SNAPSHOT: 'snapshot'
+};
+
+export const state = {
+  ignoreLiveRequestsUntil: 0
+};
+
+const parseData = data => {
+  const map = new Map();
+  try {
+    for ( const [ providerId, provider ] of Object.entries( data ) ) {
+      if ( providerId === '_meta' ) {
+        continue;
+      }
+      for ( const [ modelName, { cost } ] of Object.entries( provider.models ?? {} ) ) {
+        if ( cost ) { // some models don't have cost
+          map.set( `${providerId}/${modelName}`, cost );
+        }
+      }
+    }
+    if ( map.size === 0 ) {
+      throw new Error( 'Empty response' );
+    }
+    return map;
+  } catch ( error ) {
+    logger.error( `Models pricing: Data parsing failure "${error.message}".` );
+    return null;
+  }
+};
+
+const fallbackTable = parseData( modelsPricingSnapshot );
+
+const fetchData = async () => {
+  try {
+    const res = await fetch( costTableUrl, { dispatcher } );
+    if ( res.ok ) {
+      return await res.json();
+    } else {
+      logger.error( `Models pricing: Data fetch HTTP error ${res.status}.` );
+      return null;
+    }
+  } catch ( error ) {
+    logger.error( `Models pricing: Data fetch failure "${error.code ?? error.name}".` );
+    return null;
+  }
+};
+
+export const fetchModelsPricing = async () => {
+  if ( cache.content && cache.expiresAt > Date.now() ) {
+    return { models: cache.content, freshness: Freshness.CACHED };
+  }
+
+  if ( state.ignoreLiveRequestsUntil < Date.now() ) {
+    const table = await fetchData();
+    const models = table ? parseData( table ) : null;
+
+    if ( models ) {
+      cache.content = models;
+      cache.expiresAt = Date.now() + cacheTTL;
+      return { models, freshness: Freshness.LIVE };
+    } else {
+      state.ignoreLiveRequestsUntil = Date.now() + cooldownTTL;
+    }
+  }
+
+  if ( cache.content ) {
+    logger.warn( 'Models pricing: using stale cache.' );
+    return { models: cache.content, freshness: Freshness.STALE };
+  }
+  logger.warn( 'Models pricing: using built-in fallback.' );
+  return { models: fallbackTable, freshness: Freshness.SNAPSHOT };
+};