lex-metering 0.1.12 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecc76227d82fc80c0d3c83736e87af31806eac48bba30352bbbd01007732ef1c
-  data.tar.gz: 2172ef8c6d8894febe2205b3834cd62aac6fd7be28b3f66018144c3a47422cb1
+  metadata.gz: d74b4188d55fe8f0b4b904f04345a241b09040eec1104d5c4dcfb83ebfd6a17e
+  data.tar.gz: 38bb6a9e985e52d2dcdf12bb4e1b7223e0f0c0b13c7705ea5c365618e356537c
 SHA512:
-  metadata.gz: '0791bb4acbb2c1ac909259effeca27777f8b3f7969eabc67acb8651875738f41e4030e5abfaf03c6d7f300c6868d58b9042fdf31aea11c74f107e0cafb70147e'
-  data.tar.gz: c1256eda507e1a3742432ddf38d9036be6d72ede02f51f021a6b34f0849da1ab553aa6fabcf2e4b735eef76a844b8b6aaacaa0a456f408d044d7d1adf5855247
+  metadata.gz: 6a3458e571639fdf876cf85247885e62591b6e0fb2b36a3e49f4039dd0cfe293eb5b78c244c0fa6e200c8c1c5a97b458acd4b759409eca603dd4f31d468f5f57
+  data.tar.gz: 283af82b8353acd86eb1b2446a97b03a4f415e352cbaf06b2807ae145b2f92da1a1c05419785f42143dba60c31aa77325972eef0cd9d8eccea4c56f6d3b45ad4

data/.github/workflows/ci.yml

@@ -10,8 +10,8 @@ jobs:
   ci:
     uses: LegionIO/.github/.github/workflows/ci.yml@main
 
-  lint:
-    uses: LegionIO/.github/.github/workflows/lint-patterns.yml@main
+  excluded-files:
+    uses: LegionIO/.github/.github/workflows/excluded-files.yml@main
 
   security:
     uses: LegionIO/.github/.github/workflows/security-scan.yml@main
@@ -27,8 +27,8 @@ jobs:
     uses: LegionIO/.github/.github/workflows/stale.yml@main
 
   release:
-    needs: [ci, lint]
+    needs: [ci, excluded-files]
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     uses: LegionIO/.github/.github/workflows/release.yml@main
     secrets:
-      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.rubocop.yml

@@ -1,59 +1,2 @@
-AllCops:
-  TargetRubyVersion: 3.4
-  NewCops: enable
-  SuggestExtensions: false
-
-Layout/LineLength:
-  Max: 160
-
-Layout/SpaceAroundEqualsInParameterDefault:
-  EnforcedStyle: space
-
-Layout/HashAlignment:
-  EnforcedHashRocketStyle: table
-  EnforcedColonStyle: table
-
-Metrics/MethodLength:
-  Max: 50
-
-Metrics/ClassLength:
-  Max: 1500
-
-Metrics/ModuleLength:
-  Max: 1500
-
-Metrics/BlockLength:
-  Max: 40
-  Exclude:
-    - 'spec/**/*'
-
-Metrics/AbcSize:
-  Max: 60
-
-Metrics/CyclomaticComplexity:
-  Max: 15
-
-Metrics/PerceivedComplexity:
-  Max: 17
-
-Style/Documentation:
-  Enabled: false
-
-Style/SymbolArray:
-  Enabled: true
-
-Style/FrozenStringLiteralComment:
-  Enabled: true
-  EnforcedStyle: always
-
-Naming/FileName:
-  Enabled: false
-
-Naming/PredicateMethod:
-  Enabled: false
-
-Gemspec/DevelopmentDependencies:
-  Enabled: false
-
-Metrics/ParameterLists:
-  Enabled: false
+inherit_gem:
+  rubocop-legion: config/lex.yml

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.1.13] - 2026-03-30
+
+### Changed
+- update to rubocop-legion 0.1.7, resolve all offenses
+
 ## [0.1.12] - 2026-03-27
 
 ### Fixed

data/CLAUDE.md

@@ -6,12 +6,12 @@
 
 ## Purpose
 
-Captures LLM token usage metrics per task for cost attribution and intelligent routing. Records input/output/thinking tokens, latency, wall-clock time, CPU time, external API call counts, and routing reason per metered call. Supports per-worker, per-team, and aggregate routing statistics queries.
+Captures LLM token usage metrics per task for cost attribution and intelligent routing. Records input/output/thinking tokens, latency, wall-clock time, CPU time, external API call counts, cost in USD, trace context (extension, runner_function, event_type, status), and routing reason per metered call. Supports per-worker, per-team, and aggregate routing statistics queries. Hourly rollup to a summary table for reporting efficiency.
 
 ## Gem Info
 
 - **Gem name**: `lex-metering`
-- **Version**: `0.1.6`
+- **Version**: `0.1.11`
 - **Module**: `Legion::Extensions::Metering`
 - **Ruby**: `>= 3.4`
 - **License**: MIT
@@ -23,12 +23,17 @@ 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
+    cleanup.rb       # Every actor (86400s/daily): calls cleanup_old_records
+    cost_optimizer.rb # Every actor (604800s/weekly): calls analyze_costs; Singleton mixin
+    rollup.rb        # Every actor (3600s/hourly): calls rollup_hour; run_now? false
   data/
     migrations/
-      001_add_metering_records.rb  # Creates metering_records table
+      001_add_metering_records.rb  # Creates metering_records table (base schema)
+      002_add_trace_columns.rb     # Adds cost_usd, status, event_type, extension, runner_function
   runners/
-    metering.rb   # record, worker_costs, team_costs, routing_stats, cleanup_old_records
+    metering.rb       # record, worker_costs, team_costs, routing_stats, cleanup_old_records
+    cost_optimizer.rb # analyze_costs (LLM-powered model rightsizing recommendations)
+    rollup.rb         # rollup_hour, purge_raw_records
 ```
 
 ## Database Schema (`metering_records`)
@@ -49,34 +54,60 @@ lib/legion/extensions/metering/
 | `cpu_time_ms` | Integer | CPU time consumed |
 | `external_api_calls` | Integer | Non-LLM external API calls made |
 | `routing_reason` | String(255) | Why this model/provider was chosen |
+| `cost_usd` | Float | Estimated cost in USD (default: 0.0) |
+| `status` | String(50) | Pipeline status at time of record |
+| `event_type` | String(100) | Event type for SIEM/audit correlation |
+| `extension` | String(255) | Calling extension name |
+| `runner_function` | String(255) | Calling runner function name |
 | `recorded_at` | DateTime | Timestamp (indexed) |
 
 ## Runner Methods
 
 | Method | Parameters | Returns |
 |--------|-----------|---------|
-| `record` | All schema fields as kwargs | Record hash (also inserted to DB) |
+| `record` | All schema fields as kwargs | Record hash (also inserted to DB when connected) |
 | `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: }` |
+| `cleanup_old_records` | `retention_days: 90` | Deletes records older than cutoff |
 
 `period` values: `'daily'`, `'weekly'`, `'monthly'`
 
-## Cleanup Actor
+### Rollup (`Runners::Rollup`)
 
-`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.
+`rollup_hour` — groups `metering_records` by worker/provider/model for the current hour into `metering_hourly_rollup` table with upsert semantics (one row per worker+provider+model+hour).
+
+`purge_raw_records(retention_days: 7)` — deletes raw `metering_records` older than the retention window after they have been rolled up.
+
+### CostOptimizer (`Runners::CostOptimizer`)
+
+`analyze_costs(window_days: 7, top_n: 10)` — aggregates cost drivers from `metering_records` for the past `window_days` days. Calls `Legion::LLM.chat` (with `caller: { extension: 'lex-metering', operation: 'cost_optimization' }`) to generate model rightsizing recommendations. Returns `{ status:, cost_drivers:, recommendations: }`.
+
+Built-in rate table (per 1M tokens): Anthropic claude-opus-4-6 $15, claude-sonnet-4-6 $3, claude-haiku-4-5 $0.25; OpenAI gpt-4o $5, gpt-4o-mini $0.15; Bedrock/Azure default $3.
+
+## Actors
+
+| Actor | Interval | Behaviour |
+|-------|----------|-----------|
+| `Cleanup` | 86400s daily | `cleanup_old_records`; `use_runner? false` |
+| `CostOptimizer` | 604800s weekly | `analyze_costs`; `use_runner? false`; Singleton mixin |
+| `Rollup` | 3600s hourly | `rollup_hour`; `run_now? false` |
 
 ## 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.
+- **legion-data**: `data_required? false` — loads without DB. `record` returns hash for RMQ publishing; query methods require `Legion::Data`.
 - **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
+- **lex-llm-gateway**: MeteringWriter actor writes to the same `metering_records` table
 
 ## Development Notes
 
-- 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
+- Actor module is `module Actor` (singular) per framework convention
 - `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)
+- Time interval filtering uses `Sequel.lit('recorded_at >= ?', cutoff)` with Ruby `Time` arithmetic for cross-database compatibility
+- `CostOptimizer` actor includes `Legion::Extensions::Actors::Singleton` when available to prevent duplicate weekly runs in a cluster
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Gemfile

@@ -5,5 +5,6 @@ gemspec
 
 gem 'rspec',         '~> 3.13'
 gem 'rubocop',       '~> 1.75', require: false
+gem 'rubocop-legion', '~> 0.1', require: false
 gem 'rubocop-rspec',             require: false
 gem 'simplecov',                 require: false

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Metering
       module Actor
-        class Cleanup < Legion::Extensions::Actors::Every
+        class Cleanup < Legion::Extensions::Actors::Every # rubocop:disable Legion/Extension/EveryActorRequiresTime
           include Legion::Extensions::Actors::Singleton if defined?(Legion::Extensions::Actors::Singleton)
 
           def runner_class

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Metering
       module Actor
-        class CostOptimizer < Legion::Extensions::Actors::Every
+        class CostOptimizer < Legion::Extensions::Actors::Every # rubocop:disable Legion/Extension/EveryActorRequiresTime
           include Legion::Extensions::Actors::Singleton if defined?(Legion::Extensions::Actors::Singleton)
 
           def runner_class

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Metering
       module Actor
-        class Rollup < Legion::Extensions::Actors::Every
+        class Rollup < Legion::Extensions::Actors::Every # rubocop:disable Legion/Extension/EveryActorRequiresTime
           include Legion::Extensions::Actors::Singleton if defined?(Legion::Extensions::Actors::Singleton)
 
           def runner_class

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

@@ -76,7 +76,7 @@ module Legion
             return :unknown unless defined?(Legion::Extensions::Synapse)
 
             Legion::Extensions::Synapse::Client.new.autonomy_level(worker_id: worker_id)
-          rescue StandardError
+          rescue StandardError => _e
             :unknown
           end
         end

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

@@ -5,6 +5,8 @@ module Legion
     module Metering
       module Runners
         module CostOptimizer
+          extend self
+
           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?
@@ -23,7 +25,7 @@ module Legion
           private
 
           def collect_cost_data(window_days:)
-            return [] unless defined?(Legion::Data) && Legion::Data.respond_to?(:connection) && Legion::Data.connection
+            return [] unless defined?(Legion::Data) && Legion::Data.respond_to?(:connection) && Legion::Data.connection # rubocop:disable Legion/Extension/RunnerReturnHash
 
             cutoff = Time.now.utc - (window_days * 86_400)
             ds = Legion::Data.connection[:metering_records]
@@ -46,7 +48,7 @@ module Legion
                 call_count:   row[:call_count] || 0
               }
             end
-          rescue StandardError
+          rescue StandardError => _e
             []
           end
 
@@ -70,9 +72,9 @@ module Legion
             return { recommendations: [] } unless defined?(Legion::LLM)
 
             prompt = build_recommendation_prompt(drivers)
-            result = Legion::LLM.chat(message: prompt, caller: { extension: 'lex-metering', operation: 'cost_optimization' })
+            result = llm_chat(message: prompt, caller: { extension: 'lex-metering', operation: 'cost_optimization' })
             ::JSON.parse(result[:content] || '{}', symbolize_names: true)
-          rescue StandardError
+          rescue StandardError => _e
             { recommendations: [] }
           end
 

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

@@ -5,9 +5,11 @@ module Legion
     module Metering
       module Runners
         module Metering
+          extend self
+
           PERIOD_DAYS = { 'daily' => 1, 'weekly' => 7, 'monthly' => 30 }.freeze
 
-          def record(worker_id: nil, task_id: nil, provider: nil, model_id: nil,
+          def record(worker_id: nil, task_id: nil, provider: nil, model_id: nil, # rubocop:disable Metrics/ParameterLists
                      input_tokens: 0, output_tokens: 0, thinking_tokens: 0,
                      input_context_bytes: 0, latency_ms: 0, routing_reason: nil,
                      wall_clock_ms: 0, cpu_time_ms: 0, external_api_calls: 0,
@@ -36,8 +38,8 @@ module Legion
               recorded_at:         Time.now.utc
             }
 
-            Legion::Logging.debug "[metering] recorded: provider=#{provider} model=#{model_id} " \
-                                  "tokens=#{record[:total_tokens]} latency=#{latency_ms}ms wall_clock=#{wall_clock_ms}ms"
+            log.debug("[metering] recorded: provider=#{provider} model=#{model_id} " \
+                      "tokens=#{record[:total_tokens]} latency=#{latency_ms}ms wall_clock=#{wall_clock_ms}ms")
             record
           end
 
@@ -90,7 +92,7 @@ module Legion
 
             cutoff = Time.now.utc - (retention_days * 86_400)
             count = Legion::Data.connection[:metering_records].where { recorded_at < cutoff }.delete
-            Legion::Logging.info "[metering] cleanup: purged=#{count} retention_days=#{retention_days} cutoff=#{cutoff}"
+            log.info("[metering] cleanup: purged=#{count} retention_days=#{retention_days} cutoff=#{cutoff}")
             { purged: count, retention_days: retention_days, cutoff: cutoff }
           end
 
@@ -98,7 +100,7 @@ module Legion
 
           def apply_period_filter(dataset, period)
             days = PERIOD_DAYS[period]
-            return dataset unless days
+            return dataset unless days # rubocop:disable Legion/Extension/RunnerReturnHash
 
             cutoff = Time.now.utc - (days * 86_400)
             dataset.where(::Sequel.lit('recorded_at >= ?', cutoff))

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

@@ -5,6 +5,8 @@ module Legion
     module Metering
       module Runners
         module Rollup
+          extend self
+
           def rollup_hour(hour: nil, **)
             return { status: 'skipped', reason: 'data_unavailable' } unless data_available?
 
@@ -35,7 +37,7 @@ module Legion
               rolled_up += 1
             end
 
-            Legion::Logging.info "[metering] rollup_hour: hour=#{hour.iso8601} groups=#{rolled_up} raw_records=#{raw_count}"
+            log.info("[metering] rollup_hour: hour=#{hour.iso8601} groups=#{rolled_up} raw_records=#{raw_count}")
             { rolled_up: rolled_up, hour: hour.iso8601, raw_records: raw_count }
           end
 
@@ -47,14 +49,14 @@ module Legion
                                 .where(::Sequel.lit('recorded_at < ?', cutoff))
                                 .delete
 
-            Legion::Logging.info "[metering] purge_raw_records: purged=#{count} retention_days=#{retention_days} cutoff=#{cutoff.iso8601}"
+            log.info("[metering] purge_raw_records: purged=#{count} retention_days=#{retention_days} cutoff=#{cutoff.iso8601}")
             { purged: count, retention_days: retention_days, cutoff: cutoff.iso8601 }
           end
 
           private
 
           def data_available?(table = nil)
-            return false unless defined?(Legion::Data) && Legion::Data.respond_to?(:connection) && Legion::Data.connection
+            return false unless defined?(Legion::Data) && Legion::Data.respond_to?(:connection) && Legion::Data.connection # rubocop:disable Legion/Extension/RunnerReturnHash
 
             if table
               Legion::Data.connection.table_exists?(table)
@@ -65,7 +67,7 @@ module Legion
           end
 
           def resolve_hour(hour)
-            return hour if hour
+            return hour if hour # rubocop:disable Legion/Extension/RunnerReturnHash
 
             now = Time.now.utc
             floored = Time.utc(now.year, now.month, now.day, now.hour)
@@ -73,7 +75,7 @@ module Legion
           end
 
           def build_rollup_row(worker_id, provider, model_id, hour, rows)
-            latencies = rows.map { |r| r[:latency_ms] }.compact
+            latencies = rows.filter_map { |r| r[:latency_ms] }
             avg_latency = latencies.empty? ? 0 : (latencies.sum.to_f / latencies.size).round(2)
 
             {

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Metering
-      VERSION = '0.1.12'
+      VERSION = '0.1.13'
     end
   end
 end

data/lib/legion/extensions/metering.rb

@@ -7,7 +7,7 @@ require 'legion/extensions/metering/runners/rollup'
 module Legion
   module Extensions
     module Metering
-      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core, false
 
       def self.data_required?
         false

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-metering
 version: !ruby/object:Gem::Version
-  version: 0.1.12
+  version: 0.1.13
 platform: ruby
 authors:
 - Esity