lex-metering 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db002082af15a2d97671a7b9ed75897f21ec03d16e360962517fc848527c9ec6
-  data.tar.gz: cb642644b254256b1fef4a17933f9276a3a972ebee52a37c80e4bf88786e1b57
+  metadata.gz: f0014a77ce8b15e51cc4f1ae2edc8804fdd22fc85042fdabe7a556c275ed9d3c
+  data.tar.gz: 26b9fd1245b65d5ae61ec9832c2ec3c80fe857ebb13ec28526d828f873ebb33f
 SHA512:
-  metadata.gz: 7e107e84a2d199254a12daad43880e9f3b593b3076b0e42964a7fe0ef07410c4a75923761da4128cb0942c4b45db1b791b4923e4e2263484c3b61621d54cf979
-  data.tar.gz: 60c7c096ea83b68c01fef84244449764ac3ff357465a9aa2a5e74f71f72b94f838ac2bd8805dd969c9cbbe613bdf3a04145e62a47c8d6923134b96399828a767
+  metadata.gz: ca6352cb2ff5ef6b9067f962561679e03042ec6ee9780b2efda08f2d1198cb4bc8013884bc6756e713221193bb4ca949ddcc979b8bd09e2f094800535d170d63
+  data.tar.gz: 30afaffe29668eb64d0a17d52c566c6e87a98cd8d92b08ffc54f7e9552ffc46b5a06d2302558382cf712dcba06a3081282aa78414185bf55bea29a2ceeaabc8f

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.1.6] - 2026-03-21
+
+### Added
+- `Runners::CostOptimizer` module with `analyze_costs` method for weekly LLM cost analysis
+- `Actor::CostOptimizer` periodic actor (runs weekly) to trigger cost analysis
+- Cost rate tables for Anthropic, OpenAI, Bedrock, and Azure AI models
+- LLM-powered recommendation generation for model rightsizing
+
+## [0.1.5] - 2026-03-20
+
+### Added
+- `Helpers::Economics` module with `payroll_summary`, `worker_report`, and `budget_forecast` methods for labor economics reporting
+
 ## [0.1.4] - 2026-03-18
 
 ### Changed

data/CLAUDE.md

@@ -22,11 +22,13 @@ Captures LLM token usage metrics per task for cost attribution and intelligent r
 ```
 lib/legion/extensions/metering/
   version.rb
+  actors/
+    cleanup.rb    # Every actor (86400s/daily): calls cleanup_old_records
   data/
     migrations/
       001_add_metering_records.rb  # Creates metering_records table
   runners/
-    metering.rb   # record, worker_costs, team_costs, routing_stats
+    metering.rb   # record, worker_costs, team_costs, routing_stats, cleanup_old_records
 ```
 
 ## Database Schema (`metering_records`)
@@ -57,9 +59,14 @@ lib/legion/extensions/metering/
 | `worker_costs` | `worker_id:`, `period: 'daily'` | Aggregated token/call/latency metrics |
 | `team_costs` | `team:`, `period: 'daily'` | Team-wide aggregation across all team workers |
 | `routing_stats` | `worker_id: nil` | Breakdowns by routing_reason, provider, model, avg latency |
+| `cleanup_old_records` | `retention_days: 90` | Deletes records older than cutoff; returns `{ purged:, retention_days:, cutoff: }` |
 
 `period` values: `'daily'`, `'weekly'`, `'monthly'`
 
+## Cleanup Actor
+
+`Actor::Cleanup` is an Every actor that calls `cleanup_old_records` once per day (86,400s). It runs with `run_now? false`, `use_runner? false`, `check_subtask? false`, `generate_task? false` — a minimal background trigger that delegates directly to the runner method.
+
 ## Integration Points
 
 - **legion-data**: `data_required? false` — loads without DB. `record` returns hash only (for RabbitMQ publishing). Query methods (`worker_costs`, `team_costs`, `routing_stats`, `cleanup_old_records`) still access `metering_records` as a raw Sequel dataset when `Legion::Data` is available.
@@ -70,6 +77,6 @@ lib/legion/extensions/metering/
 ## Development Notes
 
 - Extension has `data_required? false` — loads without `legion-data`; `record` builds hash only (no DB insert), query methods still require `Legion::Data`
-- No explicit actors — gets auto-generated subscription actors from the framework
+- Has one explicit actor (`Cleanup`); auto-generated subscription actors are created for runner methods
 - `routing_stats` uses `select_append { avg(latency_ms).as(avg_latency) }` — Sequel virtual row syntax
 - Time interval filtering uses `Sequel.lit('recorded_at >= ?', cutoff)` with Ruby `Time` arithmetic for cross-database compatibility (PostgreSQL, SQLite, MySQL)

data/Gemfile

@@ -2,3 +2,8 @@
 
 source 'https://rubygems.org'
 gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop-rspec', require: false
+gem 'simplecov', require: false

data/README.md

@@ -6,7 +6,7 @@ Captures LLM token usage, latency, and routing metrics per task for cost attribu
 
 ## Purpose
 
-`lex-metering` records every LLM call made through a Legion digital worker — tokens consumed, latency, wall-clock time, CPU time, external API calls, and routing reason. Data is persisted to the `metering_records` table and queried for cost attribution and routing statistics.
+`lex-metering` records every LLM call made through a Legion digital worker: tokens consumed (input, output, thinking), latency, wall-clock time, CPU time, external API calls, and routing reason. Data is persisted to the `metering_records` table and queried for cost attribution and routing statistics.
 
 ## Installation
 
@@ -39,7 +39,7 @@ stats = Legion::Extensions::Metering::Runners::Metering.routing_stats
 
 ## Database
 
-Requires `legion-data`. Creates the `metering_records` table via Sequel migration.
+Requires `legion-data`. Creates the `metering_records` table via Sequel migration. Extension loads without `legion-data` (`data_required? false`) — `record` returns a hash for RMQ publishing; query methods require `Legion::Data` to be available.
 
 ## Record Retention
 
@@ -52,8 +52,16 @@ Legion::Extensions::Metering::Runners::Metering.cleanup_old_records(retention_da
 # => { purged: 1234, retention_days: 90, cutoff: 2025-12-15 00:00:00 UTC }
 ```
 
+## Query Methods
+
+| Method | Parameters | Period Values |
+|--------|-----------|---------------|
+| `worker_costs` | `worker_id:`, `period: 'daily'` | `'daily'`, `'weekly'`, `'monthly'` |
+| `team_costs` | `team:`, `period: 'daily'` | `'daily'`, `'weekly'`, `'monthly'` |
+| `routing_stats` | `worker_id: nil` | — |
+
 ## Related
 
-- [LegionIO](https://github.com/LegionIO/LegionIO) — Framework
-- [legion-data](https://github.com/LegionIO/legion-data) — Persistence layer
-- [Digital Worker Platform](../../../docs/spec-digital-worker-integration.md) — Cost governance
+- [LegionIO](https://github.com/LegionIO/LegionIO) - Framework
+- [legion-data](https://github.com/LegionIO/legion-data) - Persistence layer
+- [lex-llm-gateway](https://github.com/LegionIO/lex-llm-gateway) - Gateway that publishes metering events over RMQ

data/lib/legion/extensions/metering/actors/cost_optimizer.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Metering
+      module Actor
+        class CostOptimizer < Legion::Extensions::Actors::Every
+          def runner_class
+            'Legion::Extensions::Metering::Runners::CostOptimizer'
+          end
+
+          def runner_function
+            'analyze_costs'
+          end
+
+          def time
+            604_800 # once per week
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/metering/helpers/economics.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Metering
+      module Helpers
+        module Economics
+          PERIOD_DAYS = { daily: 1, weekly: 7, monthly: 30 }.freeze
+
+          def payroll_summary(period: :daily, **)
+            return { workers: [], total_cost: 0, avg_productivity: 0 } unless defined?(Legion::Data)
+
+            days = PERIOD_DAYS.fetch(period.to_sym, 1)
+            cutoff = Time.now - (days * 86_400)
+            ds = Legion::Data.connection[:metering_records].where(Sequel.lit('recorded_at >= ?', cutoff))
+
+            workers = ds.group_and_count(:worker_id).all.map do |row|
+              {
+                worker_id:  row[:worker_id],
+                task_count: row[:count],
+                cost:       ds.where(worker_id: row[:worker_id]).sum(:input_tokens).to_f * cost_per_token,
+                autonomy:   synapse_autonomy(row[:worker_id])
+              }
+            end
+
+            total = workers.sum { |w| w[:cost] }
+            avg_prod = workers.empty? ? 0 : workers.sum { |w| w[:task_count] } / workers.size.to_f
+
+            { workers: workers, total_cost: total, avg_productivity: avg_prod, period: period }
+          end
+
+          def worker_report(worker_id:, period: :daily, **)
+            return { salary: 0, overtime: 0, productivity: 0 } unless defined?(Legion::Data)
+
+            days = PERIOD_DAYS.fetch(period.to_sym, 1)
+            cutoff = Time.now - (days * 86_400)
+            ds = Legion::Data.connection[:metering_records]
+                             .where(worker_id: worker_id)
+                             .where(Sequel.lit('recorded_at >= ?', cutoff))
+
+            task_count = ds.count
+            total_tokens = ds.sum(:input_tokens).to_i + ds.sum(:output_tokens).to_i
+            salary = total_tokens.to_f * cost_per_token
+            avg_latency = ds.avg(:latency_ms).to_f
+
+            {
+              worker_id:      worker_id,
+              salary:         salary,
+              overtime:       0,
+              productivity:   task_count,
+              avg_latency:    avg_latency,
+              autonomy_level: synapse_autonomy(worker_id),
+              period:         period
+            }
+          end
+
+          def budget_forecast(days: 30, **)
+            return { projected_cost: 0, trend: :flat } unless defined?(Legion::Data)
+
+            recent_ds = Legion::Data.connection[:metering_records]
+                                    .where(Sequel.lit('recorded_at >= ?', Time.now - 86_400))
+            daily_cost = (recent_ds.sum(:input_tokens).to_i + recent_ds.sum(:output_tokens).to_i) *
+                         cost_per_token
+
+            { projected_cost: daily_cost * days, daily_average: daily_cost, days: days,
+              trend: daily_cost.positive? ? :active : :flat }
+          end
+
+          private
+
+          def cost_per_token
+            0.000003
+          end
+
+          def synapse_autonomy(worker_id)
+            return :unknown unless defined?(Legion::Extensions::Synapse)
+
+            Legion::Extensions::Synapse::Client.new.autonomy_level(worker_id: worker_id)
+          rescue StandardError
+            :unknown
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/metering/runners/cost_optimizer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Metering
+      module Runners
+        module CostOptimizer
+          def analyze_costs(window_days: 7, top_n: 10)
+            drivers = collect_cost_data(window_days: window_days)
+            return { status: 'no_data', window_days: window_days, cost_drivers: [], recommendations: [] } if drivers.empty?
+
+            top_drivers = drivers.sort_by { |d| -(d[:total_cost] || 0) }.first(top_n)
+            recommendations = generate_recommendations(top_drivers)
+
+            {
+              status:          'analyzed',
+              window_days:     window_days,
+              cost_drivers:    top_drivers,
+              recommendations: recommendations[:recommendations] || []
+            }
+          end
+
+          private
+
+          def collect_cost_data(window_days:)
+            return [] unless defined?(Legion::Data) && Legion::Data.respond_to?(:connection) && Legion::Data.connection
+
+            cutoff = Time.now.utc - (window_days * 86_400)
+            ds = Legion::Data.connection[:metering_records]
+                             .where(::Sequel.lit('recorded_at >= ?', cutoff))
+
+            grouped = ds.group(:provider, :model_id)
+                        .select_append do
+                          [sum(total_tokens).as(total_tokens),
+                           sum(input_tokens).as(input_tokens),
+                           sum(output_tokens).as(output_tokens),
+                           count(Sequel.lit('*')).as(call_count)]
+                        end
+
+            grouped.all.map do |row|
+              {
+                extension:    row[:provider],
+                model:        row[:model_id],
+                total_tokens: row[:total_tokens] || 0,
+                total_cost:   estimate_cost(row[:provider], row[:model_id], row[:total_tokens] || 0),
+                call_count:   row[:call_count] || 0
+              }
+            end
+          rescue StandardError
+            []
+          end
+
+          def estimate_cost(provider, model, total_tokens)
+            rate = cost_rate(provider, model)
+            (total_tokens * rate / 1_000_000.0).round(4)
+          end
+
+          def cost_rate(provider, model)
+            rates = {
+              'anthropic' => { 'claude-opus-4-6' => 15.0, 'claude-sonnet-4-6' => 3.0, 'claude-haiku-4-5' => 0.25 },
+              'openai'    => { 'gpt-4o' => 5.0, 'gpt-4o-mini' => 0.15, 'gpt-4.1' => 2.0 },
+              'bedrock'   => { 'default' => 3.0 },
+              'azure-ai'  => { 'default' => 3.0 }
+            }
+            provider_rates = rates[provider&.to_s] || {}
+            provider_rates[model&.to_s] || provider_rates['default'] || 1.0
+          end
+
+          def generate_recommendations(drivers)
+            return { recommendations: [] } unless defined?(Legion::LLM)
+
+            prompt = build_recommendation_prompt(drivers)
+            result = Legion::LLM.chat(message: prompt)
+            ::JSON.parse(result[:content] || '{}', symbolize_names: true)
+          rescue StandardError
+            { recommendations: [] }
+          end
+
+          def build_recommendation_prompt(drivers)
+            lines = drivers.map do |d|
+              "#{d[:extension]}/#{d[:model]}: #{d[:total_tokens]} tokens, $#{d[:total_cost]}, #{d[:call_count]} calls"
+            end
+
+            <<~PROMPT
+              Analyze these LLM cost drivers from the past week and recommend model rightsizing.
+              Focus on cases where a cheaper model could handle the workload.
+
+              #{lines.join("\n")}
+
+              Return JSON: { "recommendations": [{ "extension": "...", "current_model": "...", "suggested_model": "...", "rationale": "...", "estimated_savings_pct": N }] }
+            PROMPT
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/metering/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Metering
-      VERSION = '0.1.4'
+      VERSION = '0.1.6'
     end
   end
 end

data/lib/legion/extensions/metering.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'legion/extensions/metering/version'
+require 'legion/extensions/metering/runners/cost_optimizer'
 
 module Legion
   module Extensions

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-metering
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Esity
@@ -113,7 +113,10 @@ files:
 - lex-metering.gemspec
 - lib/legion/extensions/metering.rb
 - lib/legion/extensions/metering/actors/cleanup.rb
+- lib/legion/extensions/metering/actors/cost_optimizer.rb
 - lib/legion/extensions/metering/data/migrations/001_add_metering_records.rb
+- lib/legion/extensions/metering/helpers/economics.rb
+- lib/legion/extensions/metering/runners/cost_optimizer.rb
 - lib/legion/extensions/metering/runners/metering.rb
 - lib/legion/extensions/metering/version.rb
 homepage: https://github.com/LegionIO/lex-metering