lex-llm 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 375f971150ba508862d136d724dd61f99ffb49bf3076d6a5debe0e8e12dfe86b
-  data.tar.gz: '092859a51545b6408d0b9342065fcabf32d77184fd7ebd9b2e5739e415c7a43f'
+  metadata.gz: aae636ae2e90a5bbbf5b11ba40ae3bd21ab628fa7754e0b9c78539f2535d03fc
+  data.tar.gz: 79a95d21375a4da155f768f8696d408917a8c37391ec5c986afce9dde2033f08
 SHA512:
-  metadata.gz: fead7c175af6e409b349ac8c6654d2c8ddbc8ed66ac2a158483b2bdd4f78898881e4e5b6aa15728515dcfa46d8ce0c601a8c81d99eeabb87f681f93828e3ce31
-  data.tar.gz: 69df8e7c7b0b09917d23b0de90d518dc9132dc9221a1ff9eef5dd1b30dc585beb0c1682d930a57335b29a9424a0b21f17b8994745e39515c1331dc9ff9a198ce
+  metadata.gz: 88bd2debf160491c93dbd275d332a4563f7d607142105d631114702b68cab98da103ce8b4e1b5a70f0da1aef3bc1727b384e2a1b1340bac3fe3079939e85377f
+  data.tar.gz: 49055e0945460d46444536b0fee9e1fabcba640a97f57b84486e75e5c014d765aaa1c7c33e6f67ae455fb43143b32a3fec80e0c507e20da5b29f34e714cd6d82

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.
+- Map OpenAI-compatible model listings to normalized capabilities and modalities for routing.
+
 ## 0.1.3 - 2026-04-27
 
 - Convert the gem to a standard Legion extension runtime under `Legion::Extensions::Llm`.

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.0'
+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.
@@ -233,6 +267,8 @@ At minimum, a provider extension should define:
 
 Provider extensions should avoid duplicating shared classes, schema logic, fleet lane construction, JSON handling, or common request/response objects.
 
+All providers inherit `#readiness(live: false)`, which returns configured state, provider locality, API base, endpoint helpers, and non-live health metadata without probing remote services. Providers with a cheap health endpoint can pass `live: true` to include that endpoint response. OpenAI-compatible providers also inherit shared model-list parsing that maps discovered models into normalized capabilities and modalities for Legion routing.
+
 ## Schema Status
 
 `lex-llm` still depends on `ruby_llm-schema` because the current schema bridge exposes:

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/provider/open_ai_compatible.rb

@@ -171,18 +171,54 @@ module Legion
             {}
           end
 
-          def parse_list_models_response(response, provider, _capabilities)
+          def parse_list_models_response(response, provider, capabilities)
             response.body.fetch('data', []).map do |model|
+              critical_capabilities = critical_capabilities_for(capabilities, model)
               Legion::Extensions::Llm::Model::Info.new(
                 id: model.fetch('id'),
                 name: model['id'],
                 provider: provider,
-                created_at: model['created'],
+                created_at: model_created_at(model['created']),
+                capabilities: critical_capabilities,
+                modalities: modalities_for_capabilities(critical_capabilities),
                 metadata: model
               )
             end
           end
 
+          def model_created_at(value)
+            value.is_a?(Numeric) ? Time.at(value).utc : value
+          end
+
+          def critical_capabilities_for(capabilities, model)
+            return [] unless capabilities
+            return capabilities.critical_capabilities_for(model) if capabilities.respond_to?(:critical_capabilities_for)
+
+            {
+              'streaming' => :streaming?,
+              'function_calling' => :functions?,
+              'vision' => :vision?,
+              'embeddings' => :embeddings?,
+              'moderation' => :moderation?,
+              'image' => :images?,
+              'audio_transcription' => :audio_transcription?
+            }.filter_map do |capability, predicate|
+              capability if capabilities.respond_to?(predicate) && capabilities.public_send(predicate, model)
+            end
+          end
+
+          def modalities_for_capabilities(capabilities)
+            if capabilities.include?('embeddings') && (capabilities - ['embeddings']).empty?
+              { input: %w[text], output: %w[embeddings] }
+            elsif capabilities.include?('image')
+              { input: %w[text image], output: %w[image] }
+            elsif capabilities.include?('audio_transcription')
+              { input: %w[audio], output: %w[text] }
+            else
+              { input: %w[text image], output: %w[text] }
+            end
+          end
+
           def render_embedding_payload(text, model:, dimensions:)
             { model: model, input: text, dimensions: dimensions }.compact
           end

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

@@ -113,6 +113,38 @@ module Legion
           self.class.assume_models_exist?
         end
 
+        def readiness(live: false)
+          metadata = {
+            provider: slug.to_sym,
+            name: name,
+            configured: configured?,
+            ready: configured?,
+            local: local?,
+            remote: remote?,
+            api_base: api_base,
+            endpoints: endpoint_manifest,
+            live: live
+          }
+
+          return metadata.merge(health: { checked: false }) unless live && metadata[:endpoints][:health]
+
+          response = @connection.get(metadata[:endpoints][:health])
+          metadata.merge(ready: configured? && health_ready?(response.body), health: response.body)
+        rescue StandardError => e
+          metadata.merge(ready: false, health: { error: e.class.name, message: e.message })
+        end
+
+        def endpoint_manifest
+          endpoint_methods.each_with_object({}) do |(key, method_name), result|
+            next unless respond_to?(method_name)
+
+            value = public_send(method_name)
+            result[key] = value unless value.nil?
+          rescue ArgumentError, NotImplementedError
+            next
+          end
+        end
+
         def parse_error(response)
           return if response.body.empty?
 
@@ -270,6 +302,29 @@ module Legion
           temperature
         end
 
+        def endpoint_methods
+          {
+            completion: :completion_url,
+            stream: :stream_url,
+            models: :models_url,
+            embeddings: :embedding_url,
+            moderation: :moderation_url,
+            images: :images_url,
+            transcription: :transcription_url,
+            health: :health_url,
+            version: :version_url
+          }
+        end
+
+        def health_ready?(body)
+          return body unless body.is_a?(Hash)
+
+          status = body['status'] || body[:status] || body['state'] || body[:state]
+          return true if status.nil?
+
+          %w[ok ready healthy running].include?(status.to_s.downcase)
+        end
+
         def sync_response(connection, payload, additional_headers = {})
           response = connection.post completion_url, payload do |req|
             req.headers = additional_headers.merge(req.headers) unless additional_headers.empty?

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.3'
+      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.3
+  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