lex-metering 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6ed98a119f0cd8391dfcbabef08384a0ead7ff8f9cfd45added086ce825ddef
-  data.tar.gz: 47b5dc7406297ff5c9bec985b4d4ef2d0d554cc3cea0c0c489305d545c22b07f
+  metadata.gz: 13443e923c7850c17785f0e750d1bdb995575da237592758c7578de30c321081
+  data.tar.gz: e054cb9fd8222b5d0616f82afb46669541fccfa54c9de4dbd7f83360cb4e7967
 SHA512:
-  metadata.gz: be6917d55265e01b080e4165de8c5df74c41ab38738ad6400e0fe84188d61e5e022ec806f0fb19e705fa2d04a5877d33892f744978c18a018e8dda9ef25784ec
-  data.tar.gz: d12d6e44b297b5d533a3f6e49764f9fbd3a4e74a86594c83c1a5e13812a6654f08667f81fc5a84a34368a75cf8b8c8a11933bc894ba4f5aa1833070608749d40
+  metadata.gz: 561748036537315786f810e594f005f58de6f4b2793ec497967dd00ae7488ac7c75a7fd4f7ddfeeea0f5cdd2da9442b3ffe434f4a419d3f083c63c3cea958a47
+  data.tar.gz: 0dfdb4731304dadc64f56c02e3c71edd939137026b51f057cf5c181412edc4b4b23c02d7bae8ae65451ce8e41c222bd5bbc5a9944991bec3c3dc282ee08c4b21

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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
+- `record` no longer writes directly to database; returns hash only for RabbitMQ publishing
+- `data_required?` changed to `false` — extension loads without legion-data
+
 ## [0.1.3] - 2026-03-18
 
 ### Fixed

data/CLAUDE.md

@@ -11,7 +11,7 @@ Captures LLM token usage metrics per task for cost attribution and intelligent r
 ## Gem Info
 
 - **Gem name**: `lex-metering`
-- **Version**: `0.1.3`
+- **Version**: `0.1.4`
 - **Module**: `Legion::Extensions::Metering`
 - **Ruby**: `>= 3.4`
 - **License**: MIT
@@ -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,19 +59,24 @@ 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? true` — will not load if DB unavailable. Accesses `metering_records` as a raw Sequel dataset (no Sequel::Model subclass).
+- **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.
 - **LegionIO MCP**: `legion.routing_stats` MCP tool calls `routing_stats` runner
 - **REST API**: `GET /api/tasks/:id` includes a `:metering` block when lex-metering data exists for the task
 - **Digital Workers**: `legion worker costs` CLI command delegates to `worker_costs` runner
 
 ## Development Notes
 
-- Extension has `data_required? true` (both at module level and instance level) — will skip loading if `legion-data` is not connected
-- No explicit actors — gets auto-generated subscription actors from the framework
+- Extension has `data_required? false` — loads without `legion-data`; `record` builds hash only (no DB insert), query methods still require `Legion::Data`
+- 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/runners/metering.rb

@@ -29,7 +29,6 @@ module Legion
               recorded_at:         Time.now.utc
             }
 
-            Legion::Data.connection[:metering_records].insert(record) if defined?(Legion::Data) && Legion::Data.connection
             Legion::Logging.debug "[metering] recorded: provider=#{provider} model=#{model_id} " \
                                   "tokens=#{record[:total_tokens]} latency=#{latency_ms}ms wall_clock=#{wall_clock_ms}ms"
             record

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

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

data/lib/legion/extensions/metering.rb

@@ -8,11 +8,11 @@ module Legion
       extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
 
       def self.data_required?
-        true
+        false
       end
 
       def data_required?
-        true
+        false
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-metering
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  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