lex-llm 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aae636ae2e90a5bbbf5b11ba40ae3bd21ab628fa7754e0b9c78539f2535d03fc
-  data.tar.gz: 79a95d21375a4da155f768f8696d408917a8c37391ec5c986afce9dde2033f08
+  metadata.gz: d7d400d2739542ca417b189fba9d20f468d32ca6b4c1d4864fcd884a21d31577
+  data.tar.gz: 1c0ffee1ed602d77d2a295d2f4e7904abcef1ac284754553c3c5f883a78fa023
 SHA512:
-  metadata.gz: 88bd2debf160491c93dbd275d332a4563f7d607142105d631114702b68cab98da103ce8b4e1b5a70f0da1aef3bc1727b384e2a1b1340bac3fe3079939e85377f
-  data.tar.gz: 49055e0945460d46444536b0fee9e1fabcba640a97f57b84486e75e5c014d765aaa1c7c33e6f67ae455fb43143b32a3fec80e0c507e20da5b29f34e714cd6d82
+  metadata.gz: 07ea1df46e8469e493b89855d983ef1416d38e6907404eae1502340f37f271a43c2de442825b48dbca538907042e520d85f95316803f8a87b08633edf849685a
+  data.tar.gz: 8ee001e548224a71f050c3224d140d33e652603a9308d6301e539a8f984d8aed922e7c8f8ff3313df4a42b5a693acd2dc896914a71c23e47c42eae90f4a62c9d

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.6 - 2026-04-28
+
+- Add provider-neutral registry event envelopes for future `llm.registry` offering availability, unavailability, degraded, and heartbeat publishing without persistence.
+- Sanitize registry offering payloads and reject sensitive runtime, capacity, health, lane, and metadata keys before publication.
+
 ## 0.1.5 - 2026-04-28
 
 - Add the expanded provider-neutral model offering contract with offering IDs, provider instances, canonical model aliases, model families, and routing metadata.

data/README.md

@@ -48,7 +48,7 @@ gem 'lex-llm'
 Provider extensions should declare `lex-llm` as a gemspec dependency:
 
 ```ruby
-spec.add_dependency 'lex-llm', '>= 0.1.5'
+spec.add_dependency 'lex-llm', '>= 0.1.6'
 ```
 
 For local development across LegionIO repos, prefer a local path override in the app or test `Gemfile`, not a permanent git dependency in the gemspec.
@@ -171,6 +171,36 @@ registry.filter(
 )
 ```
 
+## Registry Events
+
+`Legion::Extensions::Llm::Routing::RegistryEvent` builds dependency-light envelopes for future `llm.registry` publishing. It does not persist registry state or publish messages by itself.
+
+```ruby
+event = Legion::Extensions::Llm::Routing::RegistryEvent.available(
+  offering,
+  runtime: { host_id: 'macbook-m4-max', process: { pid: 12_345 } },
+  capacity: { concurrency: 4, queued: 0 },
+  health: { ready: true, latency_ms: 180 },
+  lane: offering.lane_key,
+  metadata: { observed_by: :lex_llm_ollama }
+)
+
+event.to_h
+# => {
+#      event_id: "...",
+#      event_type: :offering_available,
+#      occurred_at: "2026-04-28T14:30:15.123456Z",
+#      offering: { ... },
+#      runtime: { host_id: "macbook-m4-max", process: { pid: 12345 } },
+#      capacity: { concurrency: 4, queued: 0 },
+#      health: { ready: true, latency_ms: 180 },
+#      lane: "llm.fleet.inference.qwen3-6-27b-q4-k-m.ctx32768",
+#      metadata: { observed_by: :lex_llm_ollama }
+#    }
+```
+
+Supported event types are `:offering_available`, `:offering_unavailable`, `:offering_degraded`, and `:offering_heartbeat`. Event offerings are derived from `ModelOffering#to_h`, with sensitive offering fields removed. Optional `runtime`, `capacity`, `health`, `lane`, and `metadata` values are intended for non-secret operational context and reject sensitive keys such as credentials, tokens, secrets, URLs, endpoint paths, prompts, and reply queues.
+
 ## Fleet Lanes
 
 Fleet routing uses shared work lanes derived from model offerings. A lane describes the work required, not the worker that happens to do it.

data/lib/legion/extensions/llm/routing/registry_event.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Routing
+        # Serializable provider-neutral envelope for future llm.registry publishing.
+        class RegistryEvent
+          EVENT_TYPES = %i[
+            offering_available
+            offering_unavailable
+            offering_degraded
+            offering_heartbeat
+          ].freeze
+          SENSITIVE_KEYS = %i[
+            access_key
+            api_key
+            authorization
+            bearer
+            client_secret
+            credential
+            credentials
+            endpoint
+            endpoint_url
+            password
+            path
+            private_key
+            prompt
+            reply_to
+            secret
+            secrets
+            token
+            url
+          ].freeze
+
+          attr_reader :event_id, :event_type, :occurred_at, :offering, :runtime, :capacity, :health, :lane, :metadata
+
+          class << self
+            def available(offering, **attributes)
+              new(event_type: :offering_available, offering:, **attributes)
+            end
+
+            def unavailable(offering, **attributes)
+              new(event_type: :offering_unavailable, offering:, **attributes)
+            end
+
+            def degraded(offering, **attributes)
+              new(event_type: :offering_degraded, offering:, **attributes)
+            end
+
+            def heartbeat(offering, **attributes)
+              new(event_type: :offering_heartbeat, offering:, **attributes)
+            end
+          end
+
+          def initialize(event_type:, offering:, **attributes)
+            @event_id = normalize_event_id(attributes.fetch(:event_id, SecureRandom.uuid))
+            @event_type = normalize_event_type(event_type)
+            @occurred_at = normalize_time(attributes.fetch(:occurred_at, Time.now.utc))
+            @offering = normalize_offering(offering)
+            @runtime = sanitize_optional_hash(attributes[:runtime], :runtime)
+            @capacity = sanitize_optional_hash(attributes[:capacity], :capacity)
+            @health = sanitize_optional_hash(attributes[:health], :health)
+            @lane = sanitize_optional_value(attributes[:lane], :lane)
+            @metadata = sanitize_optional_hash(attributes[:metadata], :metadata)
+          end
+
+          def to_h
+            {
+              event_id: event_id,
+              event_type: event_type,
+              occurred_at: occurred_at.utc.iso8601(6),
+              offering: sanitized_offering_hash,
+              runtime: runtime,
+              capacity: capacity,
+              health: health,
+              lane: lane,
+              metadata: metadata
+            }.compact
+          end
+
+          private
+
+          def normalize_event_id(value)
+            normalized = value.to_s.strip
+            raise ArgumentError, 'event_id is required' if normalized.empty?
+
+            normalized
+          end
+
+          def normalize_event_type(value)
+            normalized = value.to_sym
+            raise ArgumentError, "unsupported registry event type: #{value}" unless EVENT_TYPES.include?(normalized)
+
+            normalized
+          end
+
+          def normalize_time(value)
+            return value.utc if value.respond_to?(:utc)
+
+            Time.parse(value.to_s).utc
+          end
+
+          def normalize_offering(value)
+            return value if value.is_a?(ModelOffering)
+
+            ModelOffering.new(value)
+          end
+
+          def sanitized_offering_hash
+            sanitize_hash(offering.to_h, on_sensitive: :drop)
+          end
+
+          def sanitize_optional_hash(value, label)
+            return nil if value.nil?
+
+            sanitize_hash(value.to_h, label:)
+          end
+
+          def sanitize_optional_value(value, label)
+            return nil if value.nil?
+            return sanitize_hash(value.to_h, label:) if value.respond_to?(:to_h)
+            return value unless value.is_a?(Array)
+
+            sanitize_array(value, label:, path: [])
+          end
+
+          def sanitize_hash(hash, label: nil, path: [], on_sensitive: :raise)
+            hash.each_with_object({}) do |(key, value), sanitized|
+              normalized_key = key.to_sym
+              key_path = path + [normalized_key]
+              if sensitive_key?(normalized_key)
+                raise_sensitive_key!(label, key_path) if on_sensitive == :raise
+
+                next
+              end
+
+              sanitized[normalized_key] = sanitize_value(value, label:, path: key_path, on_sensitive:)
+            end
+          end
+
+          def sanitize_array(array, label:, path:, on_sensitive: :raise)
+            array.map { |value| sanitize_value(value, label:, path:, on_sensitive:) }
+          end
+
+          def sanitize_value(value, label:, path:, on_sensitive:)
+            return sanitize_hash(value, label:, path:, on_sensitive:) if value.is_a?(Hash)
+            return sanitize_array(value, label:, path:, on_sensitive:) if value.is_a?(Array)
+
+            value
+          end
+
+          def sensitive_key?(key)
+            normalized = key.to_s.downcase.gsub(/[^a-z0-9]+/, '_').to_sym
+            SENSITIVE_KEYS.include?(normalized) ||
+              normalized.to_s.end_with?('_key', '_secret', '_token', '_password')
+          end
+
+          def raise_sensitive_key!(label, path)
+            prefix = label ? "#{label} contains" : 'registry event contains'
+            raise ArgumentError, "#{prefix} sensitive key: #{path.join('.')}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.1.5'
+      VERSION = '0.1.6'
     end
   end
 end

data/lib/legion/extensions/llm.rb

@@ -39,6 +39,7 @@ module Legion
       module Types
         ModelOffering = Routing::ModelOffering unless const_defined?(:ModelOffering, false)
         OfferingRegistry = Routing::OfferingRegistry unless const_defined?(:OfferingRegistry, false)
+        RegistryEvent = Routing::RegistryEvent unless const_defined?(:RegistryEvent, false)
       end
 
       # Shared routing helpers exposed under the Legion extension namespace.
@@ -46,6 +47,7 @@ module Legion
         LaneKey = ::Legion::Extensions::Llm::Routing::LaneKey unless const_defined?(:LaneKey, false)
         OfferingRegistry = ::Legion::Extensions::Llm::Routing::OfferingRegistry unless const_defined?(:OfferingRegistry,
                                                                                                       false)
+        RegistryEvent = ::Legion::Extensions::Llm::Routing::RegistryEvent unless const_defined?(:RegistryEvent, false)
       end
 
       class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - LegionIO
@@ -229,6 +229,7 @@ files:
 - lib/legion/extensions/llm/routing/lane_key.rb
 - lib/legion/extensions/llm/routing/model_offering.rb
 - lib/legion/extensions/llm/routing/offering_registry.rb
+- lib/legion/extensions/llm/routing/registry_event.rb
 - lib/legion/extensions/llm/stream_accumulator.rb
 - lib/legion/extensions/llm/streaming.rb
 - lib/legion/extensions/llm/thinking.rb