lex-llm 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acd86ca9d14268a164c9492297186706a93770c93f4e312f45d6e54cec8bd565
-  data.tar.gz: b78f52a9e0cebfedb102b7809aaf3affc20440e1fcd68a9f815e00f4a129b440
+  metadata.gz: aae636ae2e90a5bbbf5b11ba40ae3bd21ab628fa7754e0b9c78539f2535d03fc
+  data.tar.gz: 79a95d21375a4da155f768f8696d408917a8c37391ec5c986afce9dde2033f08
 SHA512:
-  metadata.gz: cb2b53cfc698777af6dbfbd735a8d12c0ed5eb94a3dbea88fb91a4951946ac2c3f42790b316bfa34e9f56f822ce3c1be6a07cdc8298525f8d317895269fb2348
-  data.tar.gz: b7392fe404a9bee6f2cde122522016b43f193c4df546a69732f9d238161f61a8a6dcb93b685fc2de5a1f9703ecf2c14c433e1a790039d8489b302afbb8cce2ef
+  metadata.gz: 88bd2debf160491c93dbd275d332a4563f7d607142105d631114702b68cab98da103ce8b4e1b5a70f0da1aef3bc1727b384e2a1b1340bac3fe3079939e85377f
+  data.tar.gz: 49055e0945460d46444536b0fee9e1fabcba640a97f57b84486e75e5c014d765aaa1c7c33e6f67ae455fb43143b32a3fec80e0c507e20da5b29f34e714cd6d82

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 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.5'
 ```
 
 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,45 @@ 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
+)
+```
+
 ## 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/version.rb

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

data/lib/legion/extensions/llm.rb

@@ -38,11 +38,14 @@ 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)
       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)
       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.5
 platform: ruby
 authors:
 - LegionIO
@@ -228,6 +228,7 @@ 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/stream_accumulator.rb
 - lib/legion/extensions/llm/streaming.rb
 - lib/legion/extensions/llm/thinking.rb