lex-llm-ledger 0.1.2

data/lib/legion/extensions/llm/ledger/migrations/001_create_metering_records.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+Sequel.migration do # rubocop:disable Metrics/BlockLength
+  change do
+    create_table(:metering_records) do
+      primary_key :id
+
+      String   :message_id,       null: false, unique: true
+      String   :correlation_id,   null: false
+      String   :conversation_id,  null: false
+      String   :message_id_ctx,   null: false
+      String   :parent_message_id
+      Integer  :message_seq
+      String   :request_id, null: false
+      String   :exchange_id
+      String   :request_type,     null: false
+      String   :tier,             null: false
+      String   :provider,         null: false
+      String   :model_id,         null: false
+      String   :node_id,          null: false
+      String   :worker_id
+      String   :agent_id
+      String   :task_id
+      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  :latency_ms,       null: false, default: 0
+      Integer  :wall_clock_ms,    null: false, default: 0
+      Float    :cost_usd,         null: false, default: 0.0
+      String   :routing_reason
+      String   :cost_center
+      String   :budget_id
+      String   :recorded_at,      null: false
+      DateTime :inserted_at,      null: false, default: Sequel::CURRENT_TIMESTAMP
+
+      index [:conversation_id]
+      index [:request_id]
+      index [:message_id_ctx]
+      index [:correlation_id]
+      index %i[provider model_id]
+      index [:node_id]
+      index [:worker_id]
+      index [:recorded_at]
+      index %i[cost_center recorded_at]
+    end
+  end
+end

data/lib/legion/extensions/llm/ledger/migrations/002_create_prompt_records.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+Sequel.migration do # rubocop:disable Metrics/BlockLength
+  change do # rubocop:disable Metrics/BlockLength
+    create_table(:prompt_records) do # rubocop:disable Metrics/BlockLength
+      primary_key :id
+
+      String    :message_id,         null: false, unique: true
+      String    :correlation_id,     null: false
+      String    :conversation_id,    null: false
+      String    :message_id_ctx,     null: false
+      String    :parent_message_id
+      Integer   :message_seq
+      String    :request_id, null: false
+      String    :exchange_id
+      String    :response_message_id
+      String    :provider,           null: false
+      String    :model_id,           null: false
+      String    :tier
+      String    :request_type
+      String    :request_json,       null: false, text: true
+      String    :response_json,      null: false, text: true
+      Integer   :input_tokens,       default: 0
+      Integer   :output_tokens,      default: 0
+      Integer   :total_tokens,       default: 0
+      Float     :cost_usd,           default: 0.0
+      String    :caller_identity
+      String    :caller_type
+      String    :agent_id
+      String    :task_id
+      String    :classification_level
+      TrueClass :contains_phi,       null: false, default: false
+      TrueClass :contains_pii,       null: false, default: false
+      String    :jurisdictions
+      Integer   :quality_score
+      String    :quality_band
+      String    :retention_policy, null: false, default: 'default'
+      DateTime  :expires_at
+      String    :recorded_at,        null: false
+      DateTime  :inserted_at,        null: false, default: Sequel::CURRENT_TIMESTAMP
+
+      index [:conversation_id]
+      index [:request_id]
+      index [:message_id_ctx]
+      index [:correlation_id]
+      index [:response_message_id]
+      index [:caller_identity]
+      index %i[provider model_id]
+      index [:contains_phi]
+      index [:expires_at]
+      index [:inserted_at]
+    end
+  end
+end

data/lib/legion/extensions/llm/ledger/migrations/003_create_tool_records.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+Sequel.migration do # rubocop:disable Metrics/BlockLength
+  change do
+    create_table(:tool_records) do
+      primary_key :id
+
+      String    :message_id,          null: false, unique: true
+      String    :correlation_id,      null: false
+      String    :conversation_id,     null: false
+      String    :message_id_ctx,      null: false
+      String    :parent_message_id
+      Integer   :message_seq
+      String    :request_id, null: false
+      String    :exchange_id
+      String    :tool_call_id,        null: false
+      String    :tool_name,           null: false
+      String    :tool_source_type
+      String    :tool_source_server
+      String    :tool_status,         null: false
+      Integer   :tool_duration_ms,    default: 0
+      String    :arguments_json,      text: true
+      String    :result_json,         text: true
+      String    :error_json,          text: true
+      String    :caller_identity
+      String    :agent_id
+      String    :classification_level
+      TrueClass :contains_phi,        null: false, default: false
+      String    :retention_policy,    null: false, default: 'default'
+      DateTime  :expires_at
+      String    :tool_start_at
+      String    :tool_end_at
+      DateTime  :inserted_at, null: false, default: Sequel::CURRENT_TIMESTAMP
+
+      index [:conversation_id]
+      index [:request_id]
+      index [:message_id_ctx]
+      index [:correlation_id]
+      index [:tool_name]
+      index %i[tool_source_server tool_name]
+      index [:tool_status]
+      index [:contains_phi]
+      index [:expires_at]
+      index [:inserted_at]
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LLM
+      module Ledger
+        module Runners
+          module Metering
+            extend self
+
+            def write_metering_record(payload, metadata = {})
+              ctx   = payload[:message_context] || {}
+              props = metadata[:properties] || {}
+
+              record = build_metering_record(payload, ctx, props)
+              ::Legion::Data::DB[:metering_records].insert(record)
+              { result: :ok }
+            rescue Sequel::UniqueConstraintViolation => _e
+              { result: :duplicate }
+            rescue StandardError => e
+              Legion::Logging.error("[lex-llm-ledger] write_metering_record failed: #{e.message}") # rubocop:disable Legion/HelperMigration/DirectLogging
+              { result: :error, error: e.message }
+            end
+
+            private
+
+            def build_metering_record(payload, ctx, props)
+              billing = payload[:billing] || {}
+              {
+                message_id:        props[:message_id],
+                correlation_id:    props[:correlation_id],
+                conversation_id:   ctx[:conversation_id],
+                message_id_ctx:    ctx[:message_id],
+                parent_message_id: ctx[:parent_message_id],
+                message_seq:       ctx[:message_seq],
+                request_id:        ctx[:request_id],
+                exchange_id:       ctx[:exchange_id],
+                request_type:      payload[:request_type],
+                tier:              payload[:tier],
+                provider:          payload[:provider],
+                model_id:          payload[:model_id],
+                node_id:           payload[:node_id],
+                worker_id:         payload[:worker_id],
+                agent_id:          payload[:agent_id],
+                task_id:           payload[:task_id],
+                input_tokens:      payload[:input_tokens].to_i,
+                output_tokens:     payload[:output_tokens].to_i,
+                thinking_tokens:   payload[:thinking_tokens].to_i,
+                total_tokens:      payload[:total_tokens].to_i,
+                latency_ms:        payload[:latency_ms].to_i,
+                wall_clock_ms:     payload[:wall_clock_ms].to_i,
+                cost_usd:          payload[:cost_usd].to_f,
+                routing_reason:    payload[:routing_reason],
+                cost_center:       billing[:cost_center],
+                budget_id:         billing[:budget_id],
+                recorded_at:       payload[:recorded_at],
+                inserted_at:       Time.now.utc
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/ledger/runners/prompts.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LLM
+      module Ledger
+        module Runners
+          module Prompts
+            extend self
+
+            def write_prompt_record(payload, metadata = {})
+              headers = metadata[:headers] || {}
+              props   = metadata[:properties] || {}
+
+              body = Helpers::Decryption.decrypt_if_needed(payload, metadata)
+              ctx  = body[:message_context] || {}
+
+              expires_at = Helpers::Retention.resolve(
+                retention:    headers['x-legion-retention'],
+                contains_phi: headers['x-legion-contains-phi'] == 'true'
+              )
+
+              record = build_prompt_record(body, ctx, props, headers, expires_at)
+              ::Legion::Data::DB[:prompt_records].insert(record)
+              { result: :ok }
+            rescue Sequel::UniqueConstraintViolation => _e
+              { result: :duplicate }
+            rescue Helpers::DecryptionUnavailable => _e
+              raise
+            rescue StandardError => e
+              Legion::Logging.error("[lex-llm-ledger] write_prompt_record failed: #{e.message}") # rubocop:disable Legion/HelperMigration/DirectLogging
+              { result: :error, error: e.message }
+            end
+
+            private
+
+            def build_prompt_record(body, ctx, props, headers, expires_at)
+              routing = body[:routing] || {}
+              tokens  = body[:tokens]  || {}
+              cost    = body[:cost]    || {}
+              caller  = body.dig(:caller, :requested_by) || {}
+              agent   = body[:agent] || {}
+              cls     = body[:classification] || {}
+              quality = body[:quality] || {}
+              ts      = body[:timestamps] || {}
+
+              {
+                message_id:           props[:message_id],
+                correlation_id:       props[:correlation_id],
+                conversation_id:      ctx[:conversation_id],
+                message_id_ctx:       ctx[:message_id],
+                parent_message_id:    ctx[:parent_message_id],
+                message_seq:          ctx[:message_seq],
+                request_id:           ctx[:request_id],
+                exchange_id:          ctx[:exchange_id],
+                response_message_id:  body[:response_message_id],
+                provider:             routing[:provider],
+                model_id:             routing[:model],
+                tier:                 routing[:tier],
+                request_type:         headers['x-legion-llm-request-type'],
+                request_json:         Legion::JSON.dump(body[:request] || {}), # rubocop:disable Legion/HelperMigration/DirectJson
+                response_json:        Legion::JSON.dump(body[:response] || {}), # rubocop:disable Legion/HelperMigration/DirectJson
+                input_tokens:         tokens[:input].to_i,
+                output_tokens:        tokens[:output].to_i,
+                total_tokens:         tokens[:total].to_i,
+                cost_usd:             cost[:estimated_usd].to_f,
+                caller_identity:      caller[:identity],
+                caller_type:          caller[:type],
+                agent_id:             agent[:id],
+                task_id:              agent[:task_id],
+                classification_level: cls[:level] || headers['x-legion-classification'],
+                contains_phi:         Helpers::Queries.phi_flag?(cls, headers),
+                contains_pii:         cls[:contains_pii] ? true : false,
+                jurisdictions:        Array(cls[:jurisdictions]).join(','),
+                quality_score:        quality[:score],
+                quality_band:         quality[:band],
+                retention_policy:     headers['x-legion-retention'] || 'default',
+                expires_at:           expires_at,
+                recorded_at:          ts[:returned] || ts[:provider_end],
+                inserted_at:          Time.now.utc
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/ledger/runners/provider_stats.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LLM
+      module Ledger
+        module Runners
+          module ProviderStats
+            extend self # rubocop:disable Style/ModuleFunction
+
+            def health_report
+              ds = ::Legion::Data::DB[:metering_records]
+                   .where { inserted_at >= Time.now.utc - 86_400 }
+                   .select(
+                     :provider,
+                     Sequel.function(:COUNT, Sequel.lit('*')).as(:request_count),
+                     Sequel.function(:SUM, :total_tokens).as(:total_tokens),
+                     Sequel.function(:AVG, :latency_ms).as(:avg_latency_ms),
+                     Sequel.function(:MAX, :latency_ms).as(:max_latency_ms)
+                   )
+                   .group(:provider)
+                   .all
+
+              ds.map { |row| row.merge(status: Helpers::Queries.latency_status(row[:avg_latency_ms])) }
+            end
+
+            def circuit_summary(period: 'hour')
+              since = Helpers::Queries.period_start(period)
+              ::Legion::Data::DB[:metering_records]
+                .where { inserted_at >= since }
+                .select(
+                  :provider, :tier,
+                  Sequel.function(:COUNT, Sequel.lit('*')).as(:request_count),
+                  Sequel.function(:AVG, :latency_ms).as(:avg_latency_ms),
+                  Sequel.function(:SUM, :cost_usd).as(:cost_usd)
+                )
+                .group(:provider, :tier)
+                .order(Sequel.desc(:request_count))
+                .all
+            end
+
+            def provider_detail(provider:, period: 'day')
+              since = Helpers::Queries.period_start(period)
+              ::Legion::Data::DB[:metering_records]
+                .where(provider: provider)
+                .where { inserted_at >= since }
+                .select(
+                  :model_id, :request_type,
+                  Sequel.function(:COUNT, Sequel.lit('*')).as(:count),
+                  Sequel.function(:SUM, :total_tokens).as(:total_tokens),
+                  Sequel.function(:AVG, :latency_ms).as(:avg_latency_ms),
+                  Sequel.function(:SUM, :cost_usd).as(:cost_usd)
+                )
+                .group(:model_id, :request_type)
+                .order(Sequel.desc(:count))
+                .all
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/ledger/runners/tools.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LLM
+      module Ledger
+        module Runners
+          module Tools
+            extend self
+
+            def write_tool_record(payload, metadata = {})
+              headers = metadata[:headers] || {}
+              props   = metadata[:properties] || {}
+
+              body = Helpers::Decryption.decrypt_if_needed(payload, metadata)
+              ctx  = body[:message_context] || {}
+              tool = body[:tool_call]       || {}
+
+              expires_at = Helpers::Retention.resolve(
+                retention:    headers['x-legion-retention'],
+                contains_phi: headers['x-legion-contains-phi'] == 'true'
+              )
+
+              record = build_tool_record(body, ctx, tool, props, headers, expires_at)
+              ::Legion::Data::DB[:tool_records].insert(record)
+              { result: :ok }
+            rescue Sequel::UniqueConstraintViolation => _e
+              { result: :duplicate }
+            rescue Helpers::DecryptionUnavailable => _e
+              raise
+            rescue StandardError => e
+              Legion::Logging.error("[lex-llm-ledger] write_tool_record failed: #{e.message}") # rubocop:disable Legion/HelperMigration/DirectLogging
+              { result: :error, error: e.message }
+            end
+
+            private
+
+            def build_tool_record(body, ctx, tool, props, headers, expires_at)
+              src    = tool[:source] || {}
+              cls    = body[:classification] || {}
+              ts     = body[:timestamps] || {}
+              caller = body.dig(:caller, :requested_by) || {}
+              agent  = body[:agent] || {}
+
+              {
+                message_id:           props[:message_id],
+                correlation_id:       props[:correlation_id],
+                conversation_id:      ctx[:conversation_id],
+                message_id_ctx:       ctx[:message_id],
+                parent_message_id:    ctx[:parent_message_id],
+                message_seq:          ctx[:message_seq],
+                request_id:           ctx[:request_id],
+                exchange_id:          ctx[:exchange_id],
+                tool_call_id:         tool[:id],
+                tool_name:            tool[:name] || headers['x-legion-tool-name'],
+                tool_source_type:     src[:type] || headers['x-legion-tool-source-type'],
+                tool_source_server:   src[:server] || headers['x-legion-tool-source-server'],
+                tool_status:          tool[:status] || headers['x-legion-tool-status'],
+                tool_duration_ms:     tool[:duration_ms].to_i,
+                arguments_json:       Legion::JSON.dump(tool[:arguments] || {}), # rubocop:disable Legion/HelperMigration/DirectJson
+                result_json:          Legion::JSON.dump(tool[:result]), # rubocop:disable Legion/HelperMigration/DirectJson
+                error_json:           Legion::JSON.dump(tool[:error]), # rubocop:disable Legion/HelperMigration/DirectJson
+                caller_identity:      caller[:identity],
+                agent_id:             agent[:id],
+                classification_level: cls[:level] || headers['x-legion-classification'],
+                contains_phi:         Helpers::Queries.phi_flag?(cls, headers),
+                retention_policy:     headers['x-legion-retention'] || 'default',
+                expires_at:           expires_at,
+                tool_start_at:        ts[:tool_start],
+                tool_end_at:          ts[:tool_end],
+                inserted_at:          Time.now.utc
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/ledger/runners/usage_reporter.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LLM
+      module Ledger
+        module Runners
+          module UsageReporter
+            extend self
+
+            def summary(since: nil, until_: nil, period: nil, group_by: nil)
+              dataset = ::Legion::Data::DB[:metering_records]
+              dataset = apply_time_window(dataset, since, until_, period)
+              dataset = dataset.group_and_count(group_by.to_sym) if group_by
+              dataset.select_append(
+                Sequel.function(:SUM, :input_tokens).as(:total_input_tokens),
+                Sequel.function(:SUM, :output_tokens).as(:total_output_tokens),
+                Sequel.function(:SUM, :total_tokens).as(:grand_total_tokens),
+                Sequel.function(:SUM, :cost_usd).as(:total_cost_usd),
+                Sequel.function(:AVG, :latency_ms).as(:avg_latency_ms),
+                Sequel.function(:COUNT, Sequel.lit('*')).as(:request_count)
+              ).all
+            end
+
+            def worker_usage(worker_id:, since: nil, until_: nil, period: nil)
+              dataset = ::Legion::Data::DB[:metering_records].where(worker_id: worker_id)
+              dataset = apply_time_window(dataset, since, until_, period)
+              dataset.select(
+                :provider, :model_id, :request_type,
+                Sequel.function(:SUM, :total_tokens).as(:total_tokens),
+                Sequel.function(:SUM, :cost_usd).as(:cost_usd),
+                Sequel.function(:COUNT, Sequel.lit('*')).as(:count)
+              ).group(:provider, :model_id, :request_type).all
+            end
+
+            def budget_check(budget_id:, budget_usd:, threshold: 0.8, period: 'month')
+              dataset = ::Legion::Data::DB[:metering_records].where(budget_id: budget_id)
+              dataset = apply_time_window(dataset, nil, nil, period)
+              spent = dataset.sum(:cost_usd).to_f
+
+              {
+                budget_id:         budget_id,
+                budget_usd:        budget_usd.to_f,
+                spent_usd:         spent,
+                remaining_usd:     [budget_usd.to_f - spent, 0.0].max,
+                exceeded:          spent > budget_usd.to_f,
+                threshold_reached: spent >= (budget_usd.to_f * threshold.to_f)
+              }
+            end
+
+            def top_consumers(limit: 10, group_by: 'node_id', since: nil, until_: nil, period: 'day')
+              col = group_by.to_sym
+              dataset = ::Legion::Data::DB[:metering_records]
+              dataset = apply_time_window(dataset, since, until_, period)
+              dataset.select(
+                col,
+                Sequel.function(:SUM, :total_tokens).as(:total_tokens),
+                Sequel.function(:SUM, :cost_usd).as(:cost_usd),
+                Sequel.function(:COUNT, Sequel.lit('*')).as(:request_count)
+              ).group(col)
+                     .order(Sequel.desc(:cost_usd))
+                     .limit(limit)
+                     .all
+            end
+
+            private
+
+            def apply_time_window(dataset, since, until_, period)
+              if period
+                since  = Helpers::Queries.period_start(period)
+                until_ = Time.now.utc
+              end
+              dataset = dataset.where { inserted_at >= since }  if since
+              dataset = dataset.where { inserted_at <= until_ } if until_
+              dataset
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/ledger/transport/exchanges/audit.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LLM
+      module Ledger
+        module Transport
+          module Exchanges
+            class Audit < Legion::Transport::Exchange
+              def exchange_name
+                'llm.audit'
+              end
+
+              def default_type
+                'topic'
+              end
+
+              def passive?
+                true
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/ledger/transport/exchanges/metering.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LLM
+      module Ledger
+        module Transport
+          module Exchanges
+            class Metering < Legion::Transport::Exchange
+              def exchange_name
+                'llm.metering'
+              end
+
+              def default_type
+                'topic'
+              end
+
+              def passive?
+                true
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/ledger/transport/queues/audit_prompts.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LLM
+      module Ledger
+        module Transport
+          module Queues
+            class AuditPrompts < Legion::Transport::Queue
+              def queue_name
+                'llm.audit.prompts'
+              end
+
+              def queue_options
+                { durable: true }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/ledger/transport/queues/audit_tools.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LLM
+      module Ledger
+        module Transport
+          module Queues
+            class AuditTools < Legion::Transport::Queue
+              def queue_name
+                'llm.audit.tools'
+              end
+
+              def queue_options
+                { durable: true }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/ledger/transport/queues/metering_write.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LLM
+      module Ledger
+        module Transport
+          module Queues
+            class MeteringWrite < Legion::Transport::Queue
+              def queue_name
+                'llm.metering.write'
+              end
+
+              def queue_options
+                { durable: true }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end