lex-metering 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db002082af15a2d97671a7b9ed75897f21ec03d16e360962517fc848527c9ec6
-  data.tar.gz: cb642644b254256b1fef4a17933f9276a3a972ebee52a37c80e4bf88786e1b57
+  metadata.gz: 13443e923c7850c17785f0e750d1bdb995575da237592758c7578de30c321081
+  data.tar.gz: e054cb9fd8222b5d0616f82afb46669541fccfa54c9de4dbd7f83360cb4e7967
 SHA512:
-  metadata.gz: 7e107e84a2d199254a12daad43880e9f3b593b3076b0e42964a7fe0ef07410c4a75923761da4128cb0942c4b45db1b791b4923e4e2263484c3b61621d54cf979
-  data.tar.gz: 60c7c096ea83b68c01fef84244449764ac3ff357465a9aa2a5e74f71f72b94f838ac2bd8805dd969c9cbbe613bdf3a04145e62a47c8d6923134b96399828a767
+  metadata.gz: 561748036537315786f810e594f005f58de6f4b2793ec497967dd00ae7488ac7c75a7fd4f7ddfeeea0f5cdd2da9442b3ffe434f4a419d3f083c63c3cea958a47
+  data.tar.gz: 0dfdb4731304dadc64f56c02e3c71edd939137026b51f057cf5c181412edc4b4b23c02d7bae8ae65451ce8e41c222bd5bbc5a9944991bec3c3dc282ee08c4b21

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [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/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/version.rb

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

metadata

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