lex-llm-mlx 0.3.7 → 0.3.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddbc30a66deeb8a43b0801bdc7c63e3388ef12a6be22ef1ecf390c588af89be2
-  data.tar.gz: eaecfe996293eec9607012f9e6aaa66af047021502d62eeb2cef34b309816bd8
+  metadata.gz: 5490746e9c970066d163970177812051c9793d6f25f036c94139b63d01b81e4b
+  data.tar.gz: b766dee30291fb2b73cdefc7807f07519776a3c3ba16e87b43c4ef0f0f9efc81
 SHA512:
-  metadata.gz: '0218f8982051c9a54b16c36442545052b36b88670e01548487bcab93572c46f012b447c5936f267e9d5b0b54c321dd30c24a3aef2395fbd08e8f501cc9304900'
-  data.tar.gz: 2763d809a2806f44fed3fb282c4679bfbb1c9b1c8d192fa41c90ac24d55cdd88fc435a8ce3e91822c9e79c595e94518eb49040ec2210e2beb4e070769e744d98
+  metadata.gz: 51dea6c8da8a5e79e54da1281bbcf396bc00b6ada942f1c439fa1bb5556a590f1e839d367f54660731a9eda493c383f03fd88de9feeb5c50f8e9bc57e4f9977c
+  data.tar.gz: 4a228ecb85b060a8eab56ddf1e99f089c9e061ffa106f40fdde158d215a50bd7729f80f44bf221e958c496566ece3913663ee015c31d3ec52ffc275de7bb164d

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.3.13] - 2026-06-20
+
+### Changed
+- Align MLX offerings to the current `lex-llm` contract: `discover_offerings` now works with the shared
+  provider flow, offerings honor configured tier/transport overrides, and provider health is carried onto
+  discovered offerings in the shared shape.
+- Normalize MLX capability override expectations to the shared `:embedding` offering vocabulary.
+
+## [0.3.12] - 2026-06-19
+
+### Changed
+- Adopt `Legion::Extensions::Llm::Inventory::ScopedRefresher` mixin (lex-llm 0.6.0). Discovery
+  refresh actors now write directly to the live `Inventory` catalog via `Inventory.write_lane`.
+- Pin `lex-llm >= 0.6.0` and `legion-llm >= 0.14.0` in gemspec.
+- Standard `weight: 100` default added to provider instance settings schema.
+
+## 0.3.11 - 2026-06-16
+
+- Dependency updates and code quality improvements.
+
+## 0.3.10 - 2026-06-15
+
+- **CapabilityPolicy integration** — Name-pattern heuristics tagged as `:provider_catalog`; streaming from `:provider_envelope`. Settings overrides at provider/instance/model level supported.
+
+## 0.3.9 - 2026-06-13
+
+- **Gemfile cleanup** — Remove local path overrides; dependencies resolve from gemspec via rubygems.
+- **Dependency bump** — Require `lex-llm >= 0.5.0` for canonical types support.
+- **Canonical tool support** — Use `ToolSchema.extract` and add `:tools` capability.
+- 20 examples, 0 failures; 13 files, 0 rubocop offenses.
+
+## 0.3.8 - 2026-06-02
+
+- Add per-provider scoped discovery refresh actor
+
 ## 0.3.7 - 2026-05-21
 
 - Add `default_transport`/`default_tier` class declarations

data/Gemfile

@@ -2,13 +2,6 @@
 
 source 'https://rubygems.org'
 
-group :test do
-  llm_base_path = ENV.fetch('LEX_LLM_PATH', File.expand_path('../lex-llm', __dir__))
-  transport_path = ENV.fetch('LEGION_TRANSPORT_PATH', File.expand_path('../../legion-transport', __dir__))
-  gem 'legion-transport', path: transport_path if File.directory?(transport_path)
-  gem 'lex-llm', path: llm_base_path if File.directory?(llm_base_path)
-end
-
 gemspec
 
 group :development do

data/lex-llm-mlx.gemspec

@@ -27,5 +27,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-logging', '>= 1.3.2'
   spec.add_dependency 'legion-settings', '>= 1.3.14'
   spec.add_dependency 'legion-transport', '>= 1.4.14'
-  spec.add_dependency 'lex-llm', '>= 0.4.3'
+  spec.add_dependency 'lex-llm', '>= 0.6.0'
 end

data/lib/legion/extensions/llm/mlx/actors/discovery_refresh.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+begin
+  require 'legion/extensions/actors/every'
+rescue LoadError => e
+  warn(e.message) if $VERBOSE
+end
+
+begin
+  require 'legion/extensions/llm/inventory/scoped_refresher'
+rescue LoadError => e
+  warn(e.message) if $VERBOSE
+end
+
+return unless defined?(Legion::Extensions::Actors::Every)
+
+module Legion
+  module Extensions
+    module Llm
+      module Mlx
+        module Actor
+          class DiscoveryRefresh < Legion::Extensions::Actors::Every # rubocop:disable Style/Documentation, Metrics/ClassLength
+            include Legion::Logging::Helper
+
+            if defined?(Legion::Extensions::Llm::Inventory::ScopedRefresher)
+              include Legion::Extensions::Llm::Inventory::ScopedRefresher
+            end
+
+            def self.every_seconds = 60
+
+            def runner_class    = self.class
+            def runner_function = 'manual'
+            def run_now?        = true
+            def use_runner?     = false
+            def check_subtask?  = false
+            def generate_task?  = false
+
+            def time
+              return self.class.every_seconds unless defined?(Legion::Settings)
+
+              Legion::Settings.dig(:extensions, :llm, :mlx, :discovery_interval) || self.class.every_seconds
+            end
+
+            def scope_key(**)
+              { provider: :mlx }
+            end
+
+            def compute_lanes_for_scope(**)
+              return [] unless defined?(Legion::LLM::Call::Registry)
+
+              mlx_instances.flat_map { |entry| lanes_for_instance(entry) }
+            rescue StandardError => e
+              handle_exception(e, level: :warn, handled: true, operation: 'mlx.discovery_refresh.compute_lanes')
+              []
+            end
+
+            def credential_hash(**)
+              mlx_settings = Legion::Settings.dig(:extensions, :llm, :mlx) || {}
+              Digest::SHA256.hexdigest(mlx_settings[:api_key].to_s + mlx_settings[:instances].to_s)[0, 16]
+            end
+
+            def manual(**)
+              tick if respond_to?(:tick)
+            rescue StandardError => e
+              handle_exception(e, level: :warn, handled: true, operation: 'mlx.actor.discovery_refresh')
+            end
+
+            private
+
+            def mlx_instances
+              Legion::LLM::Call::Registry.all_instances.select do |e|
+                (e[:provider] || '').to_sym == :mlx
+              end
+            end
+
+            def offerings_for(adapter, instance_id)
+              Array(adapter.discover_offerings(live: true))
+            rescue StandardError => e
+              handle_exception(e, level: :warn, handled: true,
+                                  operation: 'mlx.discovery_refresh.discover_offerings',
+                                  instance: instance_id)
+              []
+            end
+
+            def lanes_for_instance(entry)
+              adapter     = entry[:adapter]
+              instance_id = entry[:instance] || entry[:instance_id] || entry[:id]
+              return [] unless adapter.respond_to?(:discover_offerings)
+
+              offerings_for(adapter, instance_id).filter_map do |raw_offering|
+                offering = offering_to_hash(raw_offering)
+                next unless offering
+
+                build_lanes(offering, instance_id)
+              end.flatten
+            end
+
+            def offering_to_hash(offering)
+              return nil if offering.nil?
+              return offering if offering.is_a?(Hash)
+
+              hash = offering.to_h
+              hash[:type] ||= hash[:usage_type]
+              hash[:enabled] = offering.respond_to?(:enabled?) ? offering.enabled? : true
+              hash
+            end
+
+            def build_lanes(offering, instance_id)
+              type = offering_type(offering[:type])
+              tier = offering[:tier] || :local
+              lane = build_lane(offering, instance_id, type, tier)
+              lanes = [lane]
+              lanes << fleet_lane(lane, instance_id, type) if fleet_enabled? && type == :inference
+              lanes
+            end
+
+            def build_lane(offering, instance_id, type, tier)
+              {
+                id: compose_lane_id(tier: tier, instance_id: instance_id,
+                                    type: type, model: offering[:model]),
+                tier: tier,
+                provider_family: :mlx,
+                instance_id: instance_id,
+                model: offering[:model],
+                canonical_model_alias: offering[:canonical_model_alias],
+                type: type,
+                capabilities: normalize_capabilities(offering[:capabilities]),
+                limits: offering[:limits] || {},
+                enabled: offering.fetch(:enabled, true),
+                cost: offering[:cost] || {}
+              }
+            end
+
+            def fleet_lane(lane, instance_id, type)
+              lane.merge(
+                tier: :fleet,
+                id: compose_lane_id(tier: :fleet, instance_id: instance_id,
+                                    type: type, model: lane[:model])
+              )
+            end
+
+            def offering_type(raw)
+              %i[embed embedding].include?(raw.to_s.to_sym) ? :embedding : :inference
+            end
+
+            def normalize_capabilities(caps)
+              return [] unless defined?(Legion::LLM::Inventory::Capabilities)
+
+              Legion::LLM::Inventory::Capabilities.normalize(caps)
+            end
+
+            def compose_lane_id(tier:, instance_id:, type:, model:)
+              Legion::Extensions::Llm::Inventory::ScopedRefresher.compose_id(
+                tier: tier, provider_family: :mlx, instance_id: instance_id,
+                type: type, model: model
+              )
+            end
+
+            def fleet_enabled?
+              mlx_settings = Legion::Settings.dig(:extensions, :llm, :mlx) || {}
+              mlx_settings.dig(:fleet, :dispatch, :enabled)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -7,7 +7,7 @@ module Legion
     module Llm
       module Mlx
         # MLX provider implementation for local OpenAI-compatible servers.
-        class Provider < Legion::Extensions::Llm::Provider
+        class Provider < Legion::Extensions::Llm::Provider # rubocop:disable Metrics/ClassLength
           include Legion::Extensions::Llm::Provider::OpenAICompatible
 
           class << self
@@ -69,7 +69,19 @@ module Legion
 
           def health(live: false)
             log.info("Checking MLX health live=#{live} at #{api_base}#{health_url}")
-            connection.get(health_url).body
+            raw = connection.get(health_url).body
+            health_payload(raw)
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'mlx.provider.health')
+            {
+              provider: :mlx,
+              instance_id: provider_instance_id,
+              status: 'unhealthy',
+              ready: false,
+              circuit_state: 'open',
+              error: e.class.name,
+              message: e.message
+            }
           end
 
           def readiness(live: false)
@@ -86,6 +98,143 @@ module Legion
               self.class.registry_publisher.publish_models_async(models, readiness: readiness(live: false))
             end
           end
+
+          def offering_from_model(model_info, health: {}) # rubocop:disable Metrics/AbcSize
+            policy = resolve_capability_policy(model_info)
+            ctx = model_info.respond_to?(:context_length) ? model_info.context_length : nil
+
+            Legion::Extensions::Llm::Routing::ModelOffering.new(
+              provider_family: :mlx,
+              instance_id: config.respond_to?(:instance_id) ? config.instance_id : :default,
+              transport: offering_transport,
+              tier: offering_tier,
+              model: model_info.id,
+              canonical_model_alias: model_info.respond_to?(:name) ? model_info.name : nil,
+              model_family: model_info.respond_to?(:family) ? model_info.family : nil,
+              usage_type: embedding_model?(model_info.id) ? :embedding : :inference,
+              capabilities: policy[:capabilities],
+              capability_sources: policy[:sources],
+              limits: { context_window: ctx }.compact,
+              health: health,
+              metadata: offering_metadata_for(model_info).merge(capability_sources: policy[:sources])
+            )
+          end
+
+          def resolve_capability_policy(model_info)
+            Legion::Extensions::Llm::CapabilityPolicy.resolve(
+              real: extract_real_capabilities(model_info),
+              provider_catalog: extract_catalog_capabilities(model_info),
+              probe: {},
+              provider_envelope: provider_envelope_capabilities,
+              provider_config: provider_capability_config,
+              instance_config: instance_capability_config,
+              model_config: model_capability_config(model_info.id)
+            )
+          end
+
+          def extract_real_capabilities(model_info)
+            return {} unless model_info.respond_to?(:metadata)
+
+            meta = model_info.metadata
+            return {} unless meta.is_a?(Hash)
+
+            caps = meta[:capabilities]
+            caps.is_a?(Hash) ? caps : {}
+          end
+
+          def extract_catalog_capabilities(model_info)
+            model_id = model_info.respond_to?(:id) ? model_info.id.to_s : model_info.to_s
+            caps = {}
+            caps[:embeddings] = true if model_id.match?(/embed|bge|e5|nomic/i)
+            caps[:vision] = true if model_id.match?(/vlm|vision|llava|pixtral|qwen.*vl/i)
+            caps[:streaming] = true unless caps[:embeddings]
+            caps
+          end
+
+          def embedding_model?(model_id)
+            model_id.to_s.match?(/embed|bge|e5|nomic/i)
+          end
+
+          def provider_envelope_capabilities
+            { streaming: true }
+          end
+
+          def health_payload(raw)
+            ready = health_ready?(raw)
+            status = health_status(ready)
+
+            {
+              provider: :mlx,
+              instance_id: provider_instance_id,
+              status: status,
+              ready: ready,
+              circuit_state: circuit_state(status),
+              raw: raw
+            }
+          end
+
+          def health_ready?(raw)
+            raw.is_a?(Hash) ? raw.fetch('ready', raw.fetch(:ready, true)) : true
+          end
+
+          def health_status(ready)
+            ready ? 'healthy' : 'unhealthy'
+          end
+
+          def circuit_state(status)
+            status == 'healthy' ? 'closed' : 'open'
+          end
+
+          def provider_capability_config
+            conf = Legion::Extensions::Llm::CredentialSources.setting(:extensions, :llm, :mlx)
+            conf.is_a?(Hash) ? conf.to_h.except(:instances, 'instances') : {}
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'mlx.provider_capability_config')
+            {}
+          end
+
+          def instance_capability_config
+            cfg = config
+            result = {}
+            %i[capabilities enable_thinking enable_tools enable_streaming enable_vision enable_embeddings
+               thinking_flag tools_flag streaming_flag vision_flag embedding_flag embeddings_flag
+               tool_flag images_flag image_flag].each do |key|
+              next unless cfg.respond_to?(key)
+
+              val = cfg.send(key)
+              result[key] = val unless val.nil?
+            rescue StandardError
+              next
+            end
+            result
+          end
+
+          def model_capability_config(model_id)
+            models_conf = fetch_models_config
+            return {} unless models_conf
+
+            hash = models_conf.to_h
+            hash[model_id.to_s] || hash[model_id.to_sym] || {}
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'mlx.model_capability_config')
+            {}
+          end
+
+          def fetch_models_config
+            conf = config.models if config.respond_to?(:models)
+            conf ||= config[:models] if config.respond_to?(:[])
+            conf if conf.respond_to?(:to_h)
+          rescue StandardError
+            nil
+          end
+
+          def offering_metadata_for(model_info)
+            {
+              raw_model: model_info.id,
+              parameter_count: model_info.respond_to?(:parameter_count) ? model_info.parameter_count : nil,
+              quantization: model_info.respond_to?(:quantization) ? model_info.quantization : nil
+            }.compact
+          end
         end
       end
     end

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Mlx
-        VERSION = '0.3.7'
+        VERSION = '0.3.13'
       end
     end
   end

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

@@ -3,6 +3,7 @@
 require 'legion/extensions/llm'
 require 'legion/extensions/llm/mlx/provider'
 require 'legion/extensions/llm/mlx/version'
+require_relative 'mlx/actors/discovery_refresh'
 
 module Legion
   module Extensions
@@ -28,10 +29,7 @@ module Legion
               fleet: {
                 enabled: false,
                 respond_to_requests: false,
-                capabilities: %i[chat stream_chat embed],
-                lanes: [],
-                concurrency: 1,
-                queue_suffix: nil
+                capabilities: %i[chat stream_chat embed]
               }
             }
           )
@@ -49,10 +47,10 @@ module Legion
         end
 
         def self.discover_local_instance(instances)
-          return unless CredentialSources.socket_open?('localhost', 8080, timeout: 0.1)
+          return unless CredentialSources.socket_open?('localhost', 8000, timeout: 0.1)
 
           instances[:local] = {
-            base_url: 'http://localhost:8080',
+            base_url: 'http://localhost:8000',
             tier: :local,
             capabilities: [:completion]
           }
@@ -84,8 +82,7 @@ module Legion
         private_class_method :discover_local_instance, :discover_settings_instances,
                              :normalize_instance_config, :normalize_api_base
 
-        Legion::Extensions::Llm::Configuration.register_provider_options(Provider.configuration_options) if
-          Legion::Extensions::Llm::Configuration.respond_to?(:register_provider_options)
+        Legion::Extensions::Llm::Configuration.register_provider_options(Provider.configuration_options)
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-mlx
 version: !ruby/object:Gem::Version
-  version: 0.3.7
+  version: 0.3.13
 platform: ruby
 authors:
 - LegionIO
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.3
+        version: 0.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.3
+        version: 0.6.0
 description: MLX provider integration for the LegionIO LLM routing framework.
 email:
 - matthewdiverson@gmail.com
@@ -97,6 +97,7 @@ files:
 - README.md
 - lex-llm-mlx.gemspec
 - lib/legion/extensions/llm/mlx.rb
+- lib/legion/extensions/llm/mlx/actors/discovery_refresh.rb
 - lib/legion/extensions/llm/mlx/actors/fleet_worker.rb
 - lib/legion/extensions/llm/mlx/provider.rb
 - lib/legion/extensions/llm/mlx/runners/fleet_worker.rb