Package org.springframework.ai.support

Class UsageCalculator

java.lang.Object
org.springframework.ai.support.UsageCalculator
public final class UsageCalculator extends Object
A utility class to provide support methods handling Usage.
Author:
Ilayaperumal Gopinathan, Jewoo Shin

  • Method Details

    • getCumulativeUsage

      public static Usage getCumulativeUsage(Usage currentUsage, @Nullable ChatResponse previousChatResponse)
      Accumulate usage tokens from the previous chat response to the current usage tokens.

      Note: when the two usages are actually summed, the result is a plain DefaultUsage and the provider-specific native usage object is not preserved (it cannot be merged across responses). Only the token counts and cache metrics carry over. The original currentUsage (native usage included) is returned unchanged when there is nothing to accumulate.

      Parameters:
      currentUsage - the current usage.
      previousChatResponse - the previous chat response.
      Returns:
      accumulated usage.

    • isEmpty

      public static boolean isEmpty(@Nullable Usage usage)
      Check if the Usage is empty. Returns true when the Usage is null. Returns true when the Usage has zero tokens.
      Parameters:
      usage - the usage to check against.
      Returns:
      the boolean value to represent if it is empty.

    • accumulateResponseUsage

      public static @Nullable ChatResponse accumulateResponseUsage(@Nullable ChatResponse currentChatResponse, @Nullable ChatResponse accumulatedChatResponse)
      Folds the usage of the current chat response into the previously accumulated ChatResponse. The returned ChatResponse carries the cumulative usage (current plus previously accumulated). This is the building block for accumulating usage across the iterations of a recursive flow (for example a tool-calling loop or a validation retry loop).
      Parameters:
      currentChatResponse - the chat response produced by the current iteration, or null
      accumulatedChatResponse - the chat response carrying the cumulative usage from previous iterations, or null if none yet
      Returns:
      a chat response carrying the cumulative usage, the previously accumulated response unchanged when the current response is null, or null when no usage has been reported
      Since:
      2.0.0

    • withUsage

      public static ChatResponse withUsage(ChatResponse chatResponse, Usage usage)
      Returns a copy of the given chat response with its usage replaced by the provided Usage, preserving all other response metadata.
      Parameters:
      chatResponse - the chat response to copy
      usage - the usage to set on the copy
      Returns:
      a new chat response carrying the given usage
      Since:
      2.0.0