@outputai/llm 0.12.0 → 0.12.1-next.1243f78.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/llm",
-  "version": "0.12.0",
+  "version": "0.12.1-next.1243f78.0",
   "description": "Framework abstraction to interact with LLM models",
   "type": "module",
   "main": "src/index.js",
@@ -13,7 +13,8 @@
     "./src/index.d.ts",
     "./src/prompt/!(*.spec).js",
     "./src/prompt/markup/!(*.spec).js",
-    "./src/utils/!(*.spec).js"
+    "./src/utils/!(*.spec).js",
+    "./src/utils/*.json"
   ],
   "dependencies": {
     "decimal.js": "10.6.0",
@@ -21,7 +22,7 @@
     "gray-matter": "4.0.3",
     "liquidjs": "10.27.2",
     "undici": "8.9.0",
-    "@outputai/core": "0.12.0"
+    "@outputai/core": "0.12.1-next.1243f78.0"
   },
   "devDependencies": {
     "@ai-sdk/amazon-bedrock": "5.0.57",

package/src/ai_provider.js

@@ -8,6 +8,7 @@ import { createOpenAI } from '@ai-sdk/openai';
 import { createPerplexity } from '@ai-sdk/perplexity';
 import { createVertex } from '@ai-sdk/google-vertex';
 import { deprecatedProviderAliases } from './deprecated_provider_aliases.js';
+import { resolveGoogleVertexAuthOptions } from './utils/google_vertex_auth.js';
 
 /** This custom dispatcher has longer timeouts. */
 const customDispatcher = new EnvHttpProxyAgent( {
@@ -24,7 +25,7 @@ const providerInitializers = {
   'amazon-bedrock': createAmazonBedrock,
   anthropic: createAnthropic,
   azure: createAzure,
-  'google-vertex': createVertex,
+  'google-vertex': options => createVertex( { ...options, ...resolveGoogleVertexAuthOptions() } ),
   openai: createOpenAI,
   perplexity: createPerplexity
 };

package/src/index.d.ts

@@ -341,9 +341,9 @@ export type ExtractedSource =
 
 export type LLMGenerationUsageStatus = 'complete' | 'incomplete';
 
-/** Token usage reported for one normalized LLM usage component. */
+/** Token usage reported for one normalized LLM usage component. `request` counts billable requests, not tokens. */
 export interface LLMGenerationUsageItem {
-  group: 'input' | 'output';
+  group: 'input' | 'output' | 'request';
   label: string | null;
   amount: number;
 }
@@ -383,10 +383,11 @@ export interface LLMUsageEvent {
 
 export type LLMGenerationCostItemStatus = 'ok' | 'fallback' | 'missing';
 export type LLMGenerationCostStatus = 'precise' | 'imprecise' | 'incomplete';
+export type LLMGenerationCostPricingFreshness = 'live' | 'cached' | 'stale' | 'snapshot';
 
 /** Cost calculated for one normalized LLM usage item. */
 export interface LLMGenerationCostItem {
-  group: 'input' | 'output';
+  group: 'input' | 'output' | 'request';
   label: string | null;
   amount: number;
   ppm: number | null;
@@ -401,8 +402,11 @@ export interface LLMGenerationCost extends BaseAttribute {
   modelId: string;
   input: number | null;
   output: number | null;
+  request: number | null;
   total: number | null;
   status: LLMGenerationCostStatus;
+  /** How current the rate table was. Absent on costs recorded before this field existed. */
+  pricingFreshness?: LLMGenerationCostPricingFreshness | null;
   items: LLMGenerationCostItem[];
 }
 

package/src/utils/cost.js

@@ -1,6 +1,7 @@
-import { fetchModelsPricing } from './models_pricing.js';
+import { fetchModelsPricing, Freshness } from './models_pricing.js';
 import { Tracing } from '@outputai/core/sdk/runtime';
 import { LLMGenerationUsage, LLMGenerationUsageItem } from './usage.js';
+import { GroundingPpmMap } from './grounding.js';
 import { Logger } from '@outputai/core';
 import Decimal from 'decimal.js';
 
@@ -41,35 +42,37 @@ export class LLMGenerationCost extends Tracing.Attribute.BaseAttribute {
   modelId;
   input = null;
   output = null;
+  request = null;
   total = null;
   status = LLMGenerationCost.Status.INCOMPLETE;
+  pricingFreshness = null;
   items = [];
 
-  constructor( modelId, providerId, items, usageStatus ) {
+  constructor( modelId, providerId, items, usageStatus, pricingFreshness ) {
     super( LLMGenerationCost.TYPE );
     this.modelId = modelId;
     this.providerId = providerId;
     this.items = items;
+    this.pricingFreshness = pricingFreshness;
 
     const meaningfulItems = items.filter( v => v.amount > 0 );
 
     if ( meaningfulItems.some( v => v.status === LLMGenerationCostItem.Status.MISSING ) || usageStatus === LLMGenerationUsage.Status.INCOMPLETE ) {
       this.status = LLMGenerationCost.Status.INCOMPLETE;
-    } else if ( meaningfulItems.some( v => v.status === LLMGenerationCostItem.Status.FALLBACK ) ) {
+    } else if ( meaningfulItems.some( v => v.status === LLMGenerationCostItem.Status.FALLBACK ) || pricingFreshness === Freshness.SNAPSHOT ) {
       this.status = LLMGenerationCost.Status.IMPRECISE;
     } else {
       this.status = LLMGenerationCost.Status.PRECISE;
     }
-    const inputItems = items.filter( p => p.group === LLMGenerationUsageItem.Group.INPUT && exists( p.total ) );
-    if ( inputItems.length > 0 ) {
-      this.input = inputItems.reduce( ( s, p ) => s.add( p.total ), Decimal( 0 ) ).toNumber();
-    }
-    const outputItems = items.filter( p => p.group === LLMGenerationUsageItem.Group.OUTPUT && exists( p.total ) );
-    if ( outputItems.length > 0 ) {
-      this.output = outputItems.reduce( ( s, p ) => s.add( p.total ), Decimal( 0 ) ).toNumber();
-    }
-    if ( exists( this.input ) || exists( this.output ) ) {
-      this.total = Decimal( this.input ?? 0 ).add( this.output ?? 0 ).toNumber();
+    const sumGroup = group => {
+      const groupItems = items.filter( p => p.group === group && exists( p.total ) );
+      return groupItems.length > 0 ? groupItems.reduce( ( s, p ) => s.add( p.total ), Decimal( 0 ) ).toNumber() : null;
+    };
+    this.input = sumGroup( LLMGenerationUsageItem.Group.INPUT );
+    this.output = sumGroup( LLMGenerationUsageItem.Group.OUTPUT );
+    this.request = sumGroup( LLMGenerationUsageItem.Group.REQUEST );
+    if ( exists( this.input ) || exists( this.output ) || exists( this.request ) ) {
+      this.total = Decimal( this.input ?? 0 ).add( this.output ?? 0 ).add( this.request ?? 0 ).toNumber();
     }
   }
 }
@@ -86,6 +89,10 @@ const resolveValue = values => {
 };
 
 const resolvePrice = ( { group, label, pricing } ) => {
+  // Per-request charges are never token-priced: models.dev has no rate for them.
+  if ( group === LLMGenerationUsageItem.Group.REQUEST ) {
+    return resolveValue( [ GroundingPpmMap.get( label ) ] );
+  }
   if ( !pricing ) {
     return resolveValue( [] );
   }
@@ -113,7 +120,7 @@ const resolvePrice = ( { group, label, pricing } ) => {
  * @returns {Promise<LLMGenerationCost | null>} LLM generation cost with input, output, total and breakdown
  */
 export const calculateCosts = async usage => {
-  const models = await fetchModelsPricing();
+  const { models, freshness: pricingFreshness } = await fetchModelsPricing();
 
   if ( !models ) {
     Logger.warn( 'Failed to fetch models pricing', { namespace: 'LLM' } );
@@ -133,5 +140,11 @@ export const calculateCosts = async usage => {
     return new LLMGenerationCostItem( group, label, amount, ppm, total, status );
   } );
 
-  return new LLMGenerationCost( modelId, providerId, items, usage.status );
+  const unrated = items.some( v =>
+    v.group === LLMGenerationUsageItem.Group.REQUEST && v.status === LLMGenerationCostItem.Status.MISSING );
+  if ( unrated ) {
+    Logger.warn( 'Grounded call with no grounding rate for model', { namespace: 'LLM', modelId, providerId } );
+  }
+
+  return new LLMGenerationCost( modelId, providerId, items, usage.status, pricingFreshness );
 };

package/src/utils/google_vertex_auth.js

@@ -0,0 +1,31 @@
+import { ValidationError } from '@outputai/core';
+
+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/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/utils/models_pricing.js

@@ -1,9 +1,11 @@
 import { Logger } from '@outputai/core';
 import { EnvHttpProxyAgent, fetch } from 'undici';
+import modelsPricingFallback from './models_pricing_fallback.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 } );
@@ -13,23 +15,42 @@ export const cache = {
   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 provider of Object.values( data ) ) {
+    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( `${provider.id}/${modelName}`, 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.name}".` );
+    logger.error( `Models pricing: Data parsing failure "${error.message}".` );
     return null;
   }
 };
 
+const fallbackTable = parseData( modelsPricingFallback );
+
 const fetchData = async () => {
   try {
     const res = await fetch( costTableUrl, { dispatcher } );
@@ -47,22 +68,26 @@ const fetchData = async () => {
 
 export const fetchModelsPricing = async () => {
   if ( cache.content && cache.expiresAt > Date.now() ) {
-    return cache.content;
+    return { models: cache.content, freshness: Freshness.CACHED };
   }
 
-  const table = await fetchData();
-  const content = table ? parseData( table ) : null;
+  if ( state.ignoreLiveRequestsUntil < Date.now() ) {
+    const table = await fetchData();
+    const models = table ? parseData( table ) : null;
 
-  if ( content ) {
-    cache.content = content;
-    cache.expiresAt = Date.now() + cacheTTL;
-    return content;
+    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 cache.content;
+    return { models: cache.content, freshness: Freshness.STALE };
   }
-
-  return null;
+  logger.warn( 'Models pricing: using built-in fallback.' );
+  return { models: fallbackTable, freshness: Freshness.SNAPSHOT };
 };