lex-llm 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acd86ca9d14268a164c9492297186706a93770c93f4e312f45d6e54cec8bd565
-  data.tar.gz: b78f52a9e0cebfedb102b7809aaf3affc20440e1fcd68a9f815e00f4a129b440
+  metadata.gz: d7d400d2739542ca417b189fba9d20f468d32ca6b4c1d4864fcd884a21d31577
+  data.tar.gz: 1c0ffee1ed602d77d2a295d2f4e7904abcef1ac284754553c3c5f883a78fa023
 SHA512:
-  metadata.gz: cb2b53cfc698777af6dbfbd735a8d12c0ed5eb94a3dbea88fb91a4951946ac2c3f42790b316bfa34e9f56f822ce3c1be6a07cdc8298525f8d317895269fb2348
-  data.tar.gz: b7392fe404a9bee6f2cde122522016b43f193c4df546a69732f9d238161f61a8a6dcb93b685fc2de5a1f9703ecf2c14c433e1a790039d8489b302afbb8cce2ef
+  metadata.gz: 07ea1df46e8469e493b89855d983ef1416d38e6907404eae1502340f37f271a43c2de442825b48dbca538907042e520d85f95316803f8a87b08633edf849685a
+  data.tar.gz: 8ee001e548224a71f050c3224d140d33e652603a9308d6301e539a8f984d8aed922e7c8f8ff3313df4a42b5a693acd2dc896914a71c23e47c42eae90f4a62c9d

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.
+- Add shared model alias normalization and an in-memory offering registry for common routing filters.
+
 ## 0.1.4 - 2026-04-28
 
 - Add non-live provider readiness metadata for routing without expensive health or model calls by default.

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.4'
+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.
@@ -90,11 +90,14 @@ A model offering describes one concrete model made available by one provider ins
 
 ```ruby
 offering = Legion::Extensions::Llm::Routing::ModelOffering.new(
+  offering_id: 'ollama:macbook_m4_max:inference:qwen3-6-27b-q4-k-m',
   provider_family: :ollama,
-  instance_id: :macbook_m4_max,
+  provider_instance: :macbook_m4_max,
   transport: :local,
   tier: :local,
   model: 'qwen3.6:27b-q4_K_M',
+  canonical_model_alias: 'qwen3.6:27b-q4_K_M',
+  model_family: :qwen,
   usage_type: :inference,
   capabilities: %i[chat tools vision thinking],
   limits: {
@@ -106,6 +109,10 @@ offering = Legion::Extensions::Llm::Routing::ModelOffering.new(
     latency_ms: 180
   },
   policy_tags: %i[internal_only phi_allowed],
+  routing_metadata: {
+    region: :local,
+    accelerator: :metal
+  },
   metadata: {
     enabled: true,
     eligibility: {
@@ -125,18 +132,75 @@ offering.eligible_for?(
 
 Common offering fields:
 
+- `offering_id`: stable identifier for the concrete offering; generated from provider, instance, usage type, and canonical alias when omitted
 - `provider_family`: provider implementation family, such as `:ollama`, `:vllm`, `:bedrock`, `:anthropic`, or `:openai`
-- `instance_id`: concrete provider instance, account, node, region, or local runtime
+- `provider_instance`: concrete provider instance, account, node, region, or local runtime
+- `instance_id`: compatibility alias for `provider_instance`
+- `model_family`: provider-neutral family such as `:openai`, `:anthropic`, `:gemini`, `:qwen`, or `:llama`
 - `transport`: `:local`, `:http`, `:rabbitmq`, `:sdk`, or another provider-supported transport
 - `tier`: `:local`, `:private`, `:fleet`, `:cloud`, `:frontier`, or deployment-specific policy tier
 - `model`: provider model name or normalized model alias
+- `canonical_model_alias`: provider-neutral alias used by routers and shared fleet lane keys when a provider deployment hides the base model
 - `usage_type`: `:inference` or `:embedding`
 - `capabilities`: normalized feature flags such as `:chat`, `:tools`, `:json_schema`, `:vision`, `:thinking`, or `:embedding`
 - `limits`: context window, output token limits, rate limits, concurrency limits, and provider-specific bounds
 - `health`: readiness, latency, recent failures, and provider-specific health metadata
 - `policy_tags`: routing and compliance tags such as `:internal_only`, `:phi_allowed`, or `:hipaa`
+- `routing_metadata`: provider-neutral scheduling metadata for routers; persistence is intentionally out of scope
 - `metadata`: extension-specific metadata; sensitive values are excluded from fleet eligibility fingerprints
 
+Provider gems that still pass `instance_id`, or that store `model_family`, `canonical_model_alias`, or `alias` under `metadata`, remain compatible. `ModelOffering` lifts those values into first-class readers for routers.
+
+`Legion::Extensions::Llm::Aliases.canonical_model_alias(model, provider)` provides shared alias normalization from `aliases.json`, with an explicit model string fallback.
+
+## Offering Registry
+
+`Legion::Extensions::Llm::Routing::OfferingRegistry` is an in-memory index for discovered or configured offerings. It does not persist state.
+
+```ruby
+registry = Legion::Extensions::Llm::Routing::OfferingRegistry.new
+registry.register(offering)
+
+registry.find(offering.offering_id)
+registry.find_by_model_alias('qwen3.6:27b-q4_K_M')
+registry.filter(
+  provider_family: :ollama,
+  provider_instance: :macbook_m4_max,
+  model_family: :qwen,
+  capability: :tools
+)
+```
+
+## 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/aliases.rb

@@ -16,6 +16,23 @@ module Legion
             end
           end
 
+          def normalize_model_alias(model_id)
+            model_id.to_s.strip
+          end
+
+          def canonical_model_alias(model_id, provider = nil)
+            normalized = normalize_model_alias(model_id)
+            provider_name = provider&.to_s
+
+            aliases.each do |alias_name, provider_map|
+              next unless alias_matches?(provider_map, normalized, provider_name)
+
+              return alias_name
+            end
+
+            normalized
+          end
+
           def aliases
             @aliases ||= load_aliases
           end
@@ -35,6 +52,14 @@ module Legion
           def reload!
             @aliases = load_aliases
           end
+
+          private
+
+          def alias_matches?(provider_map, model_id, provider)
+            return provider_map[provider] == model_id if provider
+
+            provider_map.value?(model_id)
+          end
         end
       end
     end

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

@@ -9,7 +9,7 @@ module Legion
           module_function
 
           def for(offering, prefix: 'llm.fleet', include_context: true, include_fingerprint: false)
-            parts = [prefix, lane_kind(offering), model_slug(offering.model)]
+            parts = [prefix, lane_kind(offering), model_slug(lane_model(offering))]
             if include_context && offering.inference? && offering.context_window
               parts << "ctx#{offering.context_window}"
             end
@@ -17,6 +17,13 @@ module Legion
             parts.join('.')
           end
 
+          def lane_model(offering)
+            return offering.canonical_model_alias if offering.respond_to?(:canonical_model_alias) &&
+                                                     offering.canonical_model_alias.to_s != ''
+
+            offering.model
+          end
+
           def lane_kind(offering)
             offering.embedding? ? 'embed' : 'inference'
           end

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

@@ -6,15 +6,23 @@ module Legion
       module Routing
         # Describes one concrete model made available by one provider instance.
         class ModelOffering
-          attr_reader :provider_family, :instance_id, :transport, :tier, :model, :usage_type, :capabilities, :limits,
+          attr_reader :offering_id, :provider_family, :model_family, :provider_instance, :instance_id, :transport,
+                      :tier, :model, :canonical_model_alias, :routing_metadata, :usage_type, :capabilities, :limits,
                       :credentials, :health, :cost, :policy_tags, :metadata
 
           def initialize(data)
+            @metadata = normalize_hash(fetch_value(data, :metadata))
             @provider_family = normalize_symbol(fetch_value(data, :provider_family, fetch_value(data, :provider)))
-            @instance_id = normalize_symbol(fetch_value(data, :instance_id, @provider_family))
+            @model_family = normalize_symbol(fetch_value(data, :model_family, @metadata[:model_family]))
+            @provider_instance = normalize_symbol(fetch_value(data, :provider_instance,
+                                                              fetch_value(data, :instance_id, @provider_family)))
+            @instance_id = @provider_instance
             @transport = normalize_symbol(fetch_value(data, :transport, :http))
             @tier = normalize_symbol(fetch_value(data, :tier, default_tier))
             @model = fetch_value(data, :model).to_s
+            @canonical_model_alias = normalize_model_alias(fetch_value(data, :canonical_model_alias,
+                                                                       metadata_canonical_model_alias))
+            @routing_metadata = normalize_hash(fetch_value(data, :routing_metadata))
             @usage_type = normalize_usage_type(fetch_value(data, :usage_type,
                                                            fetch_value(data, :type) ||
                                                            fetch_value(data, :kind) ||
@@ -25,7 +33,7 @@ module Legion
             @health = normalize_hash(fetch_value(data, :health))
             @cost = normalize_hash(fetch_value(data, :cost))
             @policy_tags = normalize_array(fetch_value(data, :policy_tags)).map(&:to_sym)
-            @metadata = normalize_hash(fetch_value(data, :metadata))
+            @offering_id = normalize_offering_id(fetch_value(data, :offering_id, default_offering_id))
           end
 
           def enabled?
@@ -70,13 +78,23 @@ module Legion
             LaneKey.eligibility_fingerprint(self)
           end
 
+          def model_alias?(alias_name)
+            normalized = normalize_model_alias(alias_name)
+            [canonical_model_alias, model].compact.any? { |candidate| normalize_model_alias(candidate) == normalized }
+          end
+
           def to_h
             {
+              offering_id: offering_id,
               provider_family: provider_family,
+              model_family: model_family,
+              provider_instance: provider_instance,
               instance_id: instance_id,
               transport: transport,
               tier: tier,
               model: model,
+              canonical_model_alias: canonical_model_alias,
+              routing_metadata: routing_metadata,
               usage_type: usage_type,
               capabilities: capabilities,
               limits: limits,
@@ -166,6 +184,28 @@ module Legion
           rescue ArgumentError, TypeError
             nil
           end
+
+          def metadata_canonical_model_alias
+            metadata[:canonical_model_alias] || metadata[:alias] ||
+              Legion::Extensions::Llm::Aliases.canonical_model_alias(@model, @provider_family)
+          end
+
+          def normalize_model_alias(value)
+            Legion::Extensions::Llm::Aliases.normalize_model_alias(value)
+          end
+
+          def normalize_offering_id(value)
+            value.to_s.strip
+          end
+
+          def default_offering_id
+            [
+              provider_family,
+              provider_instance,
+              usage_type,
+              canonical_model_alias || model
+            ].compact.map { |part| LaneKey.model_slug(part) }.join(':')
+          end
         end
       end
     end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Routing
+        # In-memory index of provider-neutral model offerings.
+        class OfferingRegistry
+          include Enumerable
+
+          def initialize(offerings = [])
+            @offerings = []
+            Array(offerings).each { |offering| register(offering) }
+          end
+
+          def register(offering)
+            normalized = normalize_offering(offering)
+            @offerings.reject! { |existing| existing.offering_id == normalized.offering_id }
+            @offerings << normalized
+            normalized
+          end
+
+          def each(&)
+            @offerings.each(&)
+          end
+
+          def all
+            @offerings.dup
+          end
+          alias list all
+
+          def find(offering_id)
+            @offerings.find { |offering| offering.offering_id == offering_id.to_s }
+          end
+
+          def find_by_model_alias(alias_name)
+            @offerings.find { |offering| offering.model_alias?(alias_name) }
+          end
+
+          def filter(**criteria)
+            @offerings.select do |offering|
+              matches_symbol?(offering.provider_family, criteria[:provider_family]) &&
+                matches_symbol?(offering.model_family, criteria[:model_family]) &&
+                matches_symbol?(offering.provider_instance, criteria[:provider_instance]) &&
+                matches_capability?(offering, criteria[:capability]) &&
+                matches_model_alias?(offering, criteria[:model_alias]) &&
+                matches_model?(offering, criteria[:model]) &&
+                matches_usage_type?(offering, criteria[:usage_type])
+            end
+          end
+
+          def by_provider_family(provider_family)
+            filter(provider_family:)
+          end
+
+          def by_model_family(model_family)
+            filter(model_family:)
+          end
+
+          def by_provider_instance(provider_instance)
+            filter(provider_instance:)
+          end
+
+          def by_capability(capability)
+            filter(capability:)
+          end
+
+          private
+
+          def normalize_offering(offering)
+            return offering if offering.is_a?(ModelOffering)
+
+            ModelOffering.new(offering)
+          end
+
+          def matches_symbol?(actual, expected)
+            expected.nil? || actual == expected.to_sym
+          end
+
+          def matches_capability?(offering, capability)
+            capability.nil? || offering.supports?(capability)
+          end
+
+          def matches_model_alias?(offering, model_alias)
+            model_alias.nil? || offering.model_alias?(model_alias)
+          end
+
+          def matches_model?(offering, model)
+            model.nil? || offering.model == model.to_s
+          end
+
+          def matches_usage_type?(offering, usage_type)
+            usage_type.nil? || offering.usage_type == usage_type.to_sym
+          end
+        end
+      end
+    end
+  end
+end

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.4'
+      VERSION = '0.1.6'
     end
   end
 end

data/lib/legion/extensions/llm.rb

@@ -38,11 +38,16 @@ module Legion
       # Provider-neutral value objects exposed under the Legion extension namespace.
       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.
       module Routing
         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.4
+  version: 0.1.6
 platform: ruby
 authors:
 - LegionIO
@@ -228,6 +228,8 @@ files:
 - lib/legion/extensions/llm/routing.rb
 - 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