Package com.tnsai.quality.cost

Interface CostBudgetStore

All Known Implementing Classes:
InMemoryCostBudgetStore
public interface CostBudgetStore
SPI for tracking cumulative LLM spend per CostScope per rolling window (issue #82).

Implementations: InMemoryCostBudgetStore (default, process-local — fine for dev / single-tenant); a Redis adapter for distributed multi-process deployments lands as a focused follow-up.

Concurrency

Implementations MUST be thread-safe. record(com.tnsai.quality.cost.CostScope, java.math.BigDecimal) is called from the LLM call wrapper (one per call); currentSpend(com.tnsai.quality.cost.CostScope, java.time.Duration) is called from the enforcement hook (one per call, before the call goes out). Both happen on the request hot path.
Since:
0.5.0 (issue #82)

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Drop every recorded spend entry — reset the store.
    BigDecimal
    currentSpend(CostScope scope, Duration period)
    Sum of recorded spend that falls inside scope within the last period.
    void
    record(CostScope scope, BigDecimal amountUSD)
    Add amountUSD to the recorded spend at scope, dated "now".

  • Method Details

    • record

      void record(CostScope scope, BigDecimal amountUSD)
      Add amountUSD to the recorded spend at scope, dated "now". The store buckets by scope and applies eviction based on the rolling-window query.

    • currentSpend

      BigDecimal currentSpend(CostScope scope, Duration period)
      Sum of recorded spend that falls inside scope within the last period. Spend records at finer scopes (tenant + agent + capability) roll up into coarser-scoped queries (tenant only).

    • clear

      void clear()
      Drop every recorded spend entry — reset the store. Useful in tests; production callers should rely on TTL-based eviction.