lex-metering 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7c946a94465b617a2dd09a892a954f82e6877d69ca5e95deab2e12323c4baeb5
+  data.tar.gz: 6045e0987b95775a42f940ab9dfbe51a8c3c331bb2ccd41dcb1470d8b5dd6022
+SHA512:
+  metadata.gz: a2b33f3404050a72676eba080f1bc94bd1a1680ef3bd869385c1d3a47c94eaa36453bd1426603018f2a4bb495eadf0e8f454198dfebb4de34f4621366ff39fdc
+  data.tar.gz: 36c8fb718ab7a60ebd81ab210344832bd9981fd68ded369890a9abf68e9045dab4eea7220cc23b6cfb497c4fefb4351e47e22bd9e33976b0c6f7ab59c786156f

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    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 }}

data/.gitignore

@@ -0,0 +1,6 @@
+*.gem
+.bundle
+Gemfile.lock
+.rspec_status
+pkg/
+coverage/

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,59 @@
+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

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.1.1] - 2026-03-15
+
+### Added
+- `cleanup_old_records` runner method with configurable retention (default 90 days)
+- `Cleanup` periodic actor (runs daily) to prune old metering records
+
+## [0.1.0] - 2026-03-13
+
+### Added
+- `record` method for capturing LLM token usage metrics
+- `worker_costs` aggregation by worker ID and time period
+- `team_costs` aggregation across team members
+- `routing_stats` breakdown by routing reason, provider, and model
+- Database migration for `metering_records` table
+- Full RSpec test coverage for all runner methods

data/CLAUDE.md

@@ -0,0 +1,75 @@
+# lex-metering: LLM Cost Metering for LegionIO
+
+**Repository Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-core/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## 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.
+
+## Gem Info
+
+- **Gem name**: `lex-metering`
+- **Version**: `0.1.0`
+- **Module**: `Legion::Extensions::Metering`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+- **GitHub**: https://github.com/LegionIO/lex-metering
+
+## File Structure
+
+```
+lib/legion/extensions/metering/
+  version.rb
+  data/
+    migrations/
+      001_add_metering_records.rb  # Creates metering_records table
+  runners/
+    metering.rb   # record, worker_costs, team_costs, routing_stats
+```
+
+## Database Schema (`metering_records`)
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `worker_id` | String(36) | Digital worker ID (nullable for non-worker tasks) |
+| `task_id` | Integer | Legion task ID |
+| `provider` | String(100) | LLM provider (e.g., 'anthropic', 'openai', 'bedrock') |
+| `model_id` | String(255) | Model identifier |
+| `input_tokens` | Integer | Prompt tokens |
+| `output_tokens` | Integer | Completion tokens |
+| `thinking_tokens` | Integer | Thinking/reasoning tokens (Anthropic extended thinking) |
+| `total_tokens` | Integer | Sum of all token types |
+| `input_context_bytes` | Integer | Raw context size in bytes |
+| `latency_ms` | Integer | LLM API round-trip time |
+| `wall_clock_ms` | Integer | Total wall-clock time for the task |
+| `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 |
+| `recorded_at` | DateTime | Timestamp (indexed) |
+
+## Runner Methods
+
+| Method | Parameters | Returns |
+|--------|-----------|---------|
+| `record` | All schema fields as kwargs | Record hash (also inserted to DB) |
+| `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 |
+
+`period` values: `'daily'`, `'weekly'`, `'monthly'`
+
+## 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).
+- **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
+- `routing_stats` uses `select_append { avg(latency_ms).as(avg_latency) }` — Sequel virtual row syntax
+- Time interval filtering uses `Sequel.lit("CURRENT_TIMESTAMP - INTERVAL '...'")` which is PostgreSQL syntax; SQLite uses different interval syntax (known limitation)

data/Gemfile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,59 @@
+# lex-metering
+
+Captures LLM token usage, latency, and routing metrics per task for cost attribution and intelligent routing decisions.
+
+**Ruby >= 3.4** | **License**: MIT | **Author**: [@Esity](https://github.com/Esity)
+
+## 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.
+
+## Installation
+
+Included with the LegionIO framework. No separate installation needed.
+
+## Usage
+
+```ruby
+# Record an LLM call
+Legion::Extensions::Metering::Runners::Metering.record(
+  worker_id: 'my-worker',
+  task_id:   42,
+  provider:  'anthropic',
+  model_id:  'claude-opus-4-6',
+  input_tokens:  1000,
+  output_tokens: 500,
+  latency_ms:    1200,
+  routing_reason: 'cost_optimization'
+)
+
+# Query worker costs
+costs = Legion::Extensions::Metering::Runners::Metering.worker_costs(
+  worker_id: 'my-worker',
+  period:    'daily'
+)
+
+# Query routing statistics
+stats = Legion::Extensions::Metering::Runners::Metering.routing_stats
+```
+
+## Database
+
+Requires `legion-data`. Creates the `metering_records` table via Sequel migration.
+
+## Record Retention
+
+Metering records are pruned automatically by the `Cleanup` actor, which runs once per day. The default retention period is 90 days. Records with a `recorded_at` older than the cutoff are permanently deleted.
+
+To trigger cleanup manually:
+
+```ruby
+Legion::Extensions::Metering::Runners::Metering.cleanup_old_records(retention_days: 90)
+# => { purged: 1234, retention_days: 90, cutoff: 2025-12-15 00:00:00 UTC }
+```
+
+## 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

data/lex-metering.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'legion/extensions/metering/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-metering'
+  spec.version       = Legion::Extensions::Metering::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'Legion::Extensions::Metering'
+  spec.description   = 'Captures LLM token usage metrics per task for cost attribution and intelligent routing'
+  spec.homepage      = 'https://github.com/LegionIO/lex-metering'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-metering'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-metering/blob/main/CHANGELOG.md'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-metering'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-metering/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'legionio'
+
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'simplecov'
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Metering
+      module Actors
+        class Cleanup < Legion::Extensions::Actors::Every
+          def runner_class
+            'Legion::Extensions::Metering::Runners::Metering'
+          end
+
+          def runner_function
+            'cleanup_old_records'
+          end
+
+          def time
+            86_400 # once per day
+          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/data/migrations/001_add_metering_records.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    create_table(:metering_records) do
+      primary_key :id
+      String  :worker_id,           null: true, size: 36, index: true
+      Integer :task_id,             null: true,             index: true
+      String  :provider,            null: true,  size: 100, index: true
+      String  :model_id,            null: true,  size: 255
+      Integer :input_tokens,        null: false, default: 0
+      Integer :output_tokens,       null: false, default: 0
+      Integer :thinking_tokens,     null: false, default: 0
+      Integer :total_tokens,        null: false, default: 0
+      Integer :input_context_bytes, null: false, default: 0
+      Integer :latency_ms,          null: false, default: 0
+      Integer :wall_clock_ms,       null: false, default: 0
+      Integer :cpu_time_ms,         null: false, default: 0
+      Integer :external_api_calls,  null: false, default: 0
+      String  :routing_reason,      null: true,  size: 255
+      DateTime :recorded_at, null: false, default: Sequel::CURRENT_TIMESTAMP, index: true
+    end
+  end
+
+  down do
+    drop_table :metering_records
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Metering
+      module Runners
+        module Metering
+          def record(worker_id: nil, task_id: nil, provider: nil, model_id: nil,
+                     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, **)
+            record = {
+              worker_id:           worker_id,
+              task_id:             task_id,
+              provider:            provider,
+              model_id:            model_id,
+              input_tokens:        input_tokens,
+              output_tokens:       output_tokens,
+              thinking_tokens:     thinking_tokens,
+              total_tokens:        input_tokens + output_tokens + thinking_tokens,
+              input_context_bytes: input_context_bytes,
+              latency_ms:          latency_ms,
+              wall_clock_ms:       wall_clock_ms,
+              cpu_time_ms:         cpu_time_ms,
+              external_api_calls:  external_api_calls,
+              routing_reason:      routing_reason,
+              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
+          end
+
+          def worker_costs(worker_id:, period: 'daily', **)
+            ds = Legion::Data.connection[:metering_records].where(worker_id: worker_id)
+
+            case period
+            when 'daily'
+              ds = ds.where { recorded_at >= Sequel.lit("CURRENT_TIMESTAMP - INTERVAL '1 day'") }
+            when 'weekly'
+              ds = ds.where { recorded_at >= Sequel.lit("CURRENT_TIMESTAMP - INTERVAL '7 days'") }
+            when 'monthly'
+              ds = ds.where { recorded_at >= Sequel.lit("CURRENT_TIMESTAMP - INTERVAL '30 days'") }
+            end
+
+            {
+              worker_id:       worker_id,
+              period:          period,
+              total_tokens:    ds.sum(:total_tokens) || 0,
+              input_tokens:    ds.sum(:input_tokens) || 0,
+              output_tokens:   ds.sum(:output_tokens) || 0,
+              thinking_tokens: ds.sum(:thinking_tokens) || 0,
+              total_calls:     ds.count,
+              avg_latency_ms:  ds.avg(:latency_ms)&.round(1) || 0,
+              by_provider:     ds.group_and_count(:provider).all,
+              by_model:        ds.group_and_count(:model_id).all
+            }
+          end
+
+          def team_costs(team:, period: 'daily', **)
+            workers = Legion::Data::Model::DigitalWorker.where(team: team).select_map(:worker_id)
+            ds = Legion::Data.connection[:metering_records].where(worker_id: workers)
+
+            {
+              team:         team,
+              period:       period,
+              worker_count: workers.size,
+              total_tokens: ds.sum(:total_tokens) || 0,
+              total_calls:  ds.count,
+              by_worker:    ds.group_and_count(:worker_id).all
+            }
+          end
+
+          def routing_stats(worker_id: nil, **)
+            ds = Legion::Data.connection[:metering_records]
+            ds = ds.where(worker_id: worker_id) if worker_id
+
+            {
+              by_routing_reason:       ds.group_and_count(:routing_reason).all,
+              by_provider:             ds.group_and_count(:provider).all,
+              by_model:                ds.group_and_count(:model_id).all,
+              avg_latency_by_provider: ds.group(:provider).select_append { avg(latency_ms).as(avg_latency) }.all
+            }
+          end
+
+          def cleanup_old_records(retention_days: 90, **)
+            return { purged: 0, retention_days: retention_days, cutoff: nil } unless defined?(Legion::Data) && Legion::Data.connection
+
+            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}"
+            { purged: count, retention_days: retention_days, cutoff: cutoff }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Metering
+      VERSION = '0.1.1'
+    end
+  end
+end

data/lib/legion/extensions/metering.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/metering/version'
+
+module Legion
+  module Extensions
+    module Metering
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+
+      def self.data_required?
+        true
+      end
+
+      def data_required?
+        true
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: lex-metering
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legionio
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Captures LLM token usage metrics per task for cost attribution and intelligent
+  routing
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- Gemfile
+- LICENSE
+- README.md
+- lex-metering.gemspec
+- 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/runners/metering.rb
+- lib/legion/extensions/metering/version.rb
+homepage: https://github.com/LegionIO/lex-metering
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-metering
+  source_code_uri: https://github.com/LegionIO/lex-metering
+  changelog_uri: https://github.com/LegionIO/lex-metering/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/LegionIO/lex-metering
+  bug_tracker_uri: https://github.com/LegionIO/lex-metering/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Legion::Extensions::Metering
+test_files: []