@outputai/llm 0.12.0 → 0.12.1-next.69255d7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outputai/llm",
-  "version": "0.12.0",
+  "version": "0.12.1-next.69255d7.0",
   "description": "Framework abstraction to interact with LLM models",
   "type": "module",
   "main": "src/index.js",
@@ -21,7 +21,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.69255d7.0"
   },
   "devDependencies": {
     "@ai-sdk/amazon-bedrock": "5.0.57",

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;
 }
@@ -386,7 +386,7 @@ export type LLMGenerationCostStatus = 'precise' | 'imprecise' | 'incomplete';
 
 /** 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,6 +401,7 @@ export interface LLMGenerationCost extends BaseAttribute {
   modelId: string;
   input: number | null;
   output: number | null;
+  request: number | null;
   total: number | null;
   status: LLMGenerationCostStatus;
   items: LLMGenerationCostItem[];

package/src/utils/cost.js

@@ -1,6 +1,7 @@
 import { fetchModelsPricing } 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,6 +42,7 @@ export class LLMGenerationCost extends Tracing.Attribute.BaseAttribute {
   modelId;
   input = null;
   output = null;
+  request = null;
   total = null;
   status = LLMGenerationCost.Status.INCOMPLETE;
   items = [];
@@ -60,16 +62,15 @@ export class LLMGenerationCost extends Tracing.Attribute.BaseAttribute {
     } 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 +87,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( [] );
   }
@@ -133,5 +138,11 @@ export const calculateCosts = async usage => {
     return new LLMGenerationCostItem( group, label, amount, ppm, total, 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 );
 };

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/usage.js

@@ -1,12 +1,13 @@
 import Decimal from 'decimal.js';
 import { Tracing } from '@outputai/core/sdk/runtime';
+import { parseGroundingUsage } from './grounding.js';
 
 const exists = v => Number.isSafeInteger( v ) && v >= 0;
 
 const safeSum = ( ...values ) => values.filter( exists ).reduce( ( t, v ) => t + v, 0 );
 
 export class LLMGenerationUsageItem {
-  static Group = { INPUT: 'input', OUTPUT: 'output' };
+  static Group = { INPUT: 'input', OUTPUT: 'output', REQUEST: 'request' };
 
   group;
   label;
@@ -65,10 +66,11 @@ export class LLMGenerationUsage extends Tracing.Attribute.BaseAttribute {
  * @param {string} args.prompt.config.provider - Id of the provider
  * @param {string} args.prompt.config.model - Id of the model
  * @param {object} args.usage - AI SDK usage with aggregate token counts and optional input/output token details
+ * @param {object[]} [args.steps] - AI SDK steps, each with its own `providerMetadata`, used for per-request charges
  *
  * @returns {LLMGenerationUsage | null} LLM generation usage with input, output, total and detailed breakdown
  */
-export const parseLLMUsage = ( { prompt, usage } ) => {
+export const parseLLMUsage = ( { prompt, usage, steps } ) => {
   const { provider: providerId, model: modelId } = prompt.config;
   const { inputTokens, inputTokenDetails, outputTokens, outputTokenDetails } = usage;
   const { noCacheTokens, cacheReadTokens, cacheWriteTokens } = inputTokenDetails ?? {};
@@ -113,6 +115,18 @@ export const parseLLMUsage = ( { prompt, usage } ) => {
     }
   }
 
+  // Grounding is billed per step, so aggregate across every step rather than only the final one.
+  // Per-query families (Gemini 3) return queries.length per step; per-prompt families (Gemini 2.x)
+  // return 1 per grounded step. Summing yields total queries and grounded-step count respectively.
+  const grounding = ( steps ?? [] )
+    .filter( step => step?.providerMetadata )
+    .map( step => parseGroundingUsage( modelId, step.providerMetadata ) )
+    .filter( Boolean );
+  if ( grounding.length > 0 ) {
+    const amount = grounding.reduce( ( sum, g ) => sum + g.amount, 0 );
+    items.push( new LLMGenerationUsageItem( LLMGenerationUsageItem.Group.REQUEST, grounding[0].label, amount ) );
+  }
+
   if ( items.length === 0 ) {
     return null;
   }

package/src/utils/wrap.js

@@ -31,8 +31,8 @@ const handleError = ( { traceId, error: originalError } ) => {
 };
 
 /** Normalize raw AI SDK usage, calculate cost, attach trace attributes, and emit metering events */
-const handleMetering = async ( { traceId, usage: sdkUsage, prompt } ) => {
-  const usageAttribute = parseLLMUsage( { usage: sdkUsage, prompt } );
+const handleMetering = async ( { traceId, usage: sdkUsage, prompt, steps } ) => {
+  const usageAttribute = parseLLMUsage( { usage: sdkUsage, prompt, steps } );
   if ( !usageAttribute ) {
     return null;
   }
@@ -74,7 +74,7 @@ export const wrapGeneration = async ( { name, prompt, fn } ) => {
   try {
     const response = await fn();
     const { usage } = response;
-    const cost = await handleMetering( { traceId, usage, prompt } );
+    const cost = await handleMetering( { traceId, usage, prompt, steps: response.steps } );
 
     if ( Array.isArray( response.images ) ) {
       const { image, images, providerMetadata } = response;
@@ -149,9 +149,9 @@ export const wrapStream = ( { name, prompt, abortSignal, fn } ) => {
     const state = { proxyResponse: null };
     removeAbortListener();
     try {
-      const { text: result, finalStep, usage } = response;
+      const { text: result, finalStep, usage, steps } = response;
       const { providerMetadata } = finalStep;
-      const cost = await handleMetering( { traceId, usage, prompt } );
+      const cost = await handleMetering( { traceId, usage, prompt, steps } );
       const sources = extractSources( response );
       Tracing.addEventEnd( { id: traceId, details: { result, usage, providerMetadata, sources } } );
       state.proxyResponse = createResponseProxy( { response, properties: { cost, sources, result } } );