Package com.tnsai.llm.cost

Class BudgetManager

java.lang.Object
com.tnsai.llm.cost.BudgetManager
public class BudgetManager extends Object
Manages budget limits and alerts for LLM usage.

BudgetManager provides configurable spending limits with automatic enforcement and alerting capabilities.

Features

  • Set overall budget limits
  • Specure alert thresholds (e.g., 80%, 90%)
  • Time-based budget periods (daily, monthly)
  • Callback notifications for alerts and limit breaches
  • Hard/soft limit modes

Usage Example


 BudgetManager budget = BudgetManager.builder()
     .limit(new BigDecimal("100.00"))        // $100 budget
     .period(Duration.ofDays(30))            // Monthly
     .alertThreshold(0.80)                   // Alert at 80%
     .onAlert(alert -> log.warn(alert))
     .onLimitExceeded(cost -> stopRequests())
     .build();

 // Check before making request
 if (budget.canSpend(estimatedCost)) {
     // Make API call
     budget.recordSpend(actualCost);
 }

  • Method Details

    • builder

      public static BudgetManager.Builder builder()

    • canSpend

      public boolean canSpend(BigDecimal amount)
      Checks if a spend amount is within budget.
      Parameters:
      amount - Amount to spend
      Returns:
      true if spend is allowed

    • trySpend

      public boolean trySpend(BigDecimal amount)
      Atomically checks budget and records spend in one operation. Prevents TOCTOU race between separate canSpend/recordSpend calls.
      Parameters:
      amount - Amount to spend
      Returns:
      true if spend was within budget and recorded, false if it would exceed the limit

    • recordSpend

      public boolean recordSpend(BigDecimal amount)
      Records a spend and triggers alerts if thresholds crossed.
      Parameters:
      amount - Amount spent
      Returns:
      true if within budget, false if limit exceeded

    • getCurrentSpend

      public BigDecimal getCurrentSpend()
      Gets the current spend in this period.

    • getRemainingBudget

      public BigDecimal getRemainingBudget()
      Gets the remaining budget.
      Returns:
      Remaining budget, or null if no limit set

    • getUsagePercent

      public double getUsagePercent()
      Gets the usage percentage (0.0 to 1.0+).
      Returns:
      Usage as a fraction of the limit

    • getLimit

      public BigDecimal getLimit()
      Gets the budget limit.

    • getPeriod

      public Duration getPeriod()
      Gets the budget period.

    • getPeriodStart

      public Instant getPeriodStart()
      Gets the period start time.

    • getRemainingTime

      public Duration getRemainingTime()
      Gets time remaining in current period.

    • isHardLimit

      public boolean isHardLimit()
      Checks if in hard limit mode.

    • reset

      public void reset()
      Manually resets the budget period.

    • getStatus

      public BudgetManager.BudgetStatus getStatus()
      Gets current budget status.