lex-llm-gateway 0.2.8 → 0.2.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 893662bdc056fd78efe87c3fa3874746bc1284d436b3233a49bed368370506b2
-  data.tar.gz: c62e301286b6690a66c12445990424bb811d9faef6783986a4e93dca4c015672
+  metadata.gz: bce7fb746d14ff63db46cb4fc87613a5a0834c61e5e067dc4e5bf6122dbd251a
+  data.tar.gz: 2d7c0d14bef999fece93d633dd74c700d2594e76d1aae216a2afd3b51f13a534
 SHA512:
-  metadata.gz: 9ad0d8c1dcf0df6b447c1a12653bf7799ef95f6c8b1fba8167cd54652f7ef7aadc6414fe03397ecb3307564b48b06fd6b1ce7604d9d1b6d72886dfe4608b422a
-  data.tar.gz: c9d3c90429a44efa0cdb15309161d67182f8136815a119e4a4f4d76b014d0e5982bc0e161bab3db8423d69c68950a5f6cf5ef30fec176e567db2bc5d4a87fab3
+  metadata.gz: 488014e8667b9782d18a56dee95250ce8869aff2f9d9e0a5254d77f3d6a5ffd9a1cea802c66766fa50da1e2fa0b5801fb6b1b17b460dfb39305ddd3eaa2aeb81
+  data.tar.gz: a65be2e6996f18b98cbdafb3f1e6145671a6eb4f37f63e7b6e500e272d8d16ba26e5414f32489cd5569c16c6881c17dab601833f1eae5edf2516c177077e54f3

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.2.9] - 2026-03-23
+
+### Added
+- UsageReporter runner: summary, worker_usage, budget_check, top_consumers from metering_records
+- UsageQueries helper: extracted query building, aggregation, and period calculation
+- Budget enforcement with configurable monthly_usd and alert_threshold via settings
+- 15 specs covering all reporter methods with in-memory SQLite
+
 ## [0.2.8] - 2026-03-23
 
 ### Added

data/lib/legion/extensions/llm/gateway/helpers/usage_queries.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LLM
+      module Gateway
+        module Helpers
+          module UsageQueries
+            module_function
+
+            def metering_records
+              Legion::Data.connection[:metering_records]
+            end
+
+            def metering_since(since)
+              metering_records.where { recorded_at >= since }
+            end
+
+            def aggregate_totals(dataset)
+              {
+                total_requests: dataset.count,
+                total_cost_usd: dataset.sum(:cost_usd).to_f.round(4),
+                total_input: dataset.sum(:input_tokens).to_i,
+                total_output: dataset.sum(:output_tokens).to_i
+              }
+            end
+
+            def grouped_rows(dataset, column)
+              grouped_query(dataset, column).limit(20).all.map do |row|
+                format_grouped_row(row, column, name_key: true)
+              end
+            end
+
+            def aggregate_by_column(dataset, column, limit)
+              grouped_query(dataset, column).limit(limit).all.map do |row|
+                format_grouped_row(row, column)
+              end
+            end
+
+            def grouped_query(dataset, column)
+              base = dataset.exclude(column => nil).group_and_count(column)
+              append_aggregates(base).order(::Sequel.desc(:total_cost))
+            end
+
+            def append_aggregates(query)
+              query.select_append { sum(cost_usd).as(total_cost) }
+                   .select_append { sum(input_tokens).as(total_input) }
+                   .select_append { sum(output_tokens).as(total_output) }
+            end
+
+            def format_grouped_row(row, column, name_key: false)
+              key = name_key ? :name : column
+              {
+                key => row[column],
+                total_cost: row[:total_cost].to_f.round(4),
+                total_input: row[:total_input].to_i,
+                total_output: row[:total_output].to_i,
+                requests: row[:count].to_i
+              }
+            end
+
+            def period_start(period)
+              now = Time.now.utc
+              case period.to_sym
+              when :hour  then now - 3600
+              when :week  then day_start(now) - ((now.wday % 7) * 86_400)
+              when :month then Time.utc(now.year, now.month, 1)
+              else day_start(now)
+              end
+            end
+
+            def day_start(time)
+              Time.utc(time.year, time.month, time.day)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/gateway/runners/usage_reporter.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/usage_queries'
+
+module Legion
+  module Extensions
+    module LLM
+      module Gateway
+        module Runners
+          module UsageReporter
+            DEFAULT_BUDGET_USD = 100.0
+            DEFAULT_ALERT_THRESHOLD = 0.8
+
+            module_function
+
+            def summary(since: nil, period: :day)
+              return unavailable_result unless data_connected?
+
+              since ||= queries.period_start(period)
+              dataset = queries.metering_since(since)
+              build_summary(dataset, period, since)
+            end
+
+            def worker_usage(worker_id:, since: nil, period: :day)
+              return unavailable_result unless data_connected?
+
+              since ||= queries.period_start(period)
+              dataset = queries.metering_since(since).where(worker_id: worker_id)
+              build_worker_summary(dataset, worker_id, period, since)
+            end
+
+            def budget_check(budget_usd: nil, threshold: nil, period: :month)
+              return unavailable_result unless data_connected?
+
+              budget = budget_usd || configured_budget
+              alert_at = threshold || configured_threshold
+              spent = queries.metering_since(queries.period_start(period)).sum(:cost_usd).to_f
+              build_budget_result(budget, spent, alert_at, period)
+            end
+
+            def top_consumers(since: nil, period: :day, limit: 10, group_by: :worker_id)
+              return unavailable_result unless data_connected?
+
+              since ||= queries.period_start(period)
+              queries.aggregate_by_column(queries.metering_since(since), group_by.to_sym, limit)
+            end
+
+            def queries
+              Helpers::UsageQueries
+            end
+
+            def data_connected?
+              MeteringWriter.data_connected?
+            end
+
+            def build_summary(dataset, period, since)
+              queries.aggregate_totals(dataset).merge(
+                period: period.to_s,
+                since: since.iso8601,
+                by_provider: queries.grouped_rows(dataset, :provider),
+                by_model: queries.grouped_rows(dataset, :model_id)
+              )
+            end
+
+            def build_worker_summary(dataset, worker_id, period, since)
+              queries.aggregate_totals(dataset).merge(
+                worker_id: worker_id,
+                period: period.to_s,
+                since: since.iso8601,
+                by_model: queries.grouped_rows(dataset, :model_id)
+              )
+            end
+
+            def build_budget_result(budget, spent, alert_at, period)
+              ratio = budget.positive? ? (spent / budget) : 0.0
+              {
+                period: period.to_s,
+                budget: budget.round(2),
+                spent: spent.round(4),
+                remaining: [(budget - spent), 0.0].max.round(4),
+                ratio: ratio.round(4),
+                status: budget_status(ratio, alert_at)
+              }
+            end
+
+            def budget_status(ratio, alert_at)
+              return :exceeded if ratio >= 1.0
+              return :warning if ratio >= alert_at
+
+              :ok
+            end
+
+            def configured_budget
+              llm_setting(:budget, :monthly_usd)&.to_f || DEFAULT_BUDGET_USD
+            end
+
+            def configured_threshold
+              llm_setting(:budget, :alert_threshold)&.to_f || DEFAULT_ALERT_THRESHOLD
+            end
+
+            def llm_setting(*keys)
+              return nil unless defined?(Legion::Settings)
+
+              settings = Legion::Settings[:llm] rescue nil # rubocop:disable Style/RescueModifier
+              return nil unless settings.is_a?(Hash)
+
+              settings.dig(*keys)
+            end
+
+            def unavailable_result
+              { success: false, error: 'data_not_connected' }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/gateway/version.rb

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module LLM
       module Gateway
-        VERSION = '0.2.8'
+        VERSION = '0.2.9'
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-gateway
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.2.9
 platform: ruby
 authors:
 - Esity
@@ -185,11 +185,13 @@ files:
 - lib/legion/extensions/llm/gateway/helpers/cost_estimator.rb
 - lib/legion/extensions/llm/gateway/helpers/reply_dispatcher.rb
 - lib/legion/extensions/llm/gateway/helpers/rpc.rb
+- lib/legion/extensions/llm/gateway/helpers/usage_queries.rb
 - lib/legion/extensions/llm/gateway/runners/fleet.rb
 - lib/legion/extensions/llm/gateway/runners/fleet_handler.rb
 - lib/legion/extensions/llm/gateway/runners/inference.rb
 - lib/legion/extensions/llm/gateway/runners/metering.rb
 - lib/legion/extensions/llm/gateway/runners/metering_writer.rb
+- lib/legion/extensions/llm/gateway/runners/usage_reporter.rb
 - lib/legion/extensions/llm/gateway/transport/exchanges/inference.rb
 - lib/legion/extensions/llm/gateway/transport/exchanges/metering.rb
 - lib/legion/extensions/llm/gateway/transport/messages/inference_request.rb