lex-llm-mlx 0.3.13 → 0.5.2

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

@@ -20,14 +20,19 @@ module Legion
         module Actor
           # Subscription actor for MLX fleet request consumption.
           class FleetWorker < Legion::Extensions::Actors::Subscription
+            # The runner module as a constant: the Subscription dispatch
+            # path calls `runner_class.send(runner_function, **message)`,
+            # which a String cannot receive.
             def runner_class
-              'Legion::Extensions::Llm::Mlx::Runners::FleetWorker'
+              Legion::Extensions::Llm::Mlx::Runners::FleetWorker
             end
 
             def runner_function
               'handle_fleet_request'
             end
 
+            # Call the runner module directly — no task record per
+            # inference hop.
             def use_runner?
               false
             end

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

@@ -6,119 +6,113 @@ module Legion
   module Extensions
     module Llm
       module Mlx
-        # MLX provider implementation for local OpenAI-compatible servers.
-        class Provider < Legion::Extensions::Llm::Provider # rubocop:disable Metrics/ClassLength
-          include Legion::Extensions::Llm::Provider::OpenAICompatible
-
-          class << self
-            attr_writer :registry_publisher
-
-            def slug = 'mlx'
-            def local? = true
-            def default_transport = :http
-            def default_tier = :local
-            def configuration_options = %i[mlx_api_base mlx_api_key]
-            def configuration_requirements = []
-            def capabilities = Capabilities
+        # Conservative capability predicates for local MLX OpenAI-compatible servers.
+        module Capabilities
+          module_function
+
+          def chat?(model) = !embeddings?(model)
+          def streaming?(model) = chat?(model)
+          def vision?(model) = model_id(model).match?(/vlm|vision|llava|pixtral|qwen.*vl/i)
+          def functions?(model) = chat?(model)
+          def embeddings?(model) = model_id(model).match?(/embed|bge|e5|nomic/i)
+
+          def critical_capabilities_for(model)
+            [
+              ('streaming' if streaming?(model)),
+              ('function_calling' if functions?(model)),
+              ('vision' if vision?(model)),
+              ('embeddings' if embeddings?(model))
+            ].compact
+          end
 
-            def registry_publisher
-              @registry_publisher ||= Legion::Extensions::Llm::RegistryPublisher.new(provider_family: :mlx)
-            end
+          def model_id(model)
+            model.respond_to?(:id) ? model.id.to_s : model.to_s
           end
+        end
 
-          # Conservative capability predicates for local MLX OpenAI-compatible servers.
-          module Capabilities
-            module_function
+        # Capability config helpers — mix into Provider.
+        module CapabilityConfig
+          private
 
-            def chat?(model) = !embeddings?(model)
-            def streaming?(model) = chat?(model)
-            def vision?(model) = model_id(model).match?(/vlm|vision|llava|pixtral|qwen.*vl/i)
-            def functions?(model) = chat?(model)
-            def embeddings?(model) = model_id(model).match?(/embed|bge|e5|nomic/i)
+          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 critical_capabilities_for(model)
-              [
-                ('streaming' if streaming?(model)),
-                ('function_calling' if functions?(model)),
-                ('vision' if vision?(model)),
-                ('embeddings' if embeddings?(model))
-              ].compact
-            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)
 
-            def model_id(model)
-              model.respond_to?(:id) ? model.id.to_s : model.to_s
+              val = cfg.send(key)
+              result[key] = val unless val.nil?
+            rescue StandardError => e
+              handle_exception(e, level: :warn, handled: true, operation: 'mlx.provider.instance_capability_config')
+              next
             end
+            result
           end
 
-          def settings
-            Mlx.default_settings
-          end
+          def model_capability_config(model_id)
+            models_conf = fetch_models_config
+            return {} unless models_conf
 
-          def api_base
-            normalize_url(config.mlx_api_base || settings[:endpoint] || 'http://localhost:8000')
+            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 headers
-            hdrs = identity_headers
-            token = config.mlx_api_key
-            hdrs['Authorization'] = "Bearer #{token}" unless token.nil? || token.to_s.empty?
-            hdrs
+          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 => e
+            handle_exception(e, level: :warn, handled: true, operation: 'mlx.fetch_models_config')
+            nil
           end
+        end
 
-          def health_url = '/health'
+        # Health payload helpers — mix into Provider.
+        module HealthHelpers
+          private
 
-          def health(live: false)
-            log.info("Checking MLX health live=#{live} at #{api_base}#{health_url}")
-            raw = connection.get(health_url).body
-            health_payload(raw)
-          rescue StandardError => e
-            handle_exception(e, level: :warn, handled: true, operation: 'mlx.provider.health')
+          def health_payload(raw)
+            ready = health_ready?(raw)
+            status = health_status(ready)
             {
               provider: :mlx,
               instance_id: provider_instance_id,
-              status: 'unhealthy',
-              ready: false,
-              circuit_state: 'open',
-              error: e.class.name,
-              message: e.message
+              status: status,
+              ready: ready,
+              circuit_state: circuit_state(status),
+              raw: raw
             }
           end
 
-          def readiness(live: false)
-            log.info("Checking MLX readiness (live=#{live})")
-            super.tap do |metadata|
-              self.class.registry_publisher.publish_readiness_async(metadata) if live
-            end
+          def health_ready?(raw)
+            raw.is_a?(Hash) ? raw.fetch('ready', raw.fetch(:ready, true)) : true
           end
 
-          def list_models(**)
-            log.info('Listing available MLX models')
-            super.tap do |models|
-              log.info("Discovered #{Array(models).size} MLX models")
-              self.class.registry_publisher.publish_models_async(models, readiness: readiness(live: false))
-            end
+          def health_status(ready)
+            ready ? 'healthy' : 'unhealthy'
           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])
-            )
+          def circuit_state(status)
+            status == 'healthy' ? 'closed' : 'open'
           end
+        end
+
+        # Capability resolution helpers — mix into Provider.
+        module CapabilityResolution
+          private
 
           def resolve_capability_policy(model_info)
             Legion::Extensions::Llm::CapabilityPolicy.resolve(
@@ -142,13 +136,10 @@ module Legion
             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
+          def extract_catalog_capabilities(_model_info)
+            # Regex-based name matching is not authoritative evidence.
+            # Unverified capability support is unknown, not promoted to supported.
+            {}
           end
 
           def embedding_model?(model_id)
@@ -156,84 +147,112 @@ module Legion
           end
 
           def provider_envelope_capabilities
-            { streaming: true }
+            # No capabilities are advertised at the envelope level without endpoint evidence.
+            {}
           end
 
-          def health_payload(raw)
-            ready = health_ready?(raw)
-            status = health_status(ready)
-
+          def offering_metadata_for(model_info)
             {
-              provider: :mlx,
-              instance_id: provider_instance_id,
-              status: status,
-              ready: ready,
-              circuit_state: circuit_state(status),
-              raw: raw
-            }
+              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
 
-          def health_ready?(raw)
-            raw.is_a?(Hash) ? raw.fetch('ready', raw.fetch(:ready, true)) : true
+        # MLX provider implementation for local OpenAI-compatible servers.
+        class Provider < Legion::Extensions::Llm::Provider
+          include Legion::Extensions::Llm::Provider::OpenAICompatible
+          include CapabilityConfig
+          include HealthHelpers
+          include CapabilityResolution
+
+          class << self
+            def slug = 'mlx'
+            def local? = true
+            def default_transport = :http
+            def default_tier = :local
+            def configuration_options = %i[mlx_api_base mlx_api_key]
+            def configuration_requirements = []
+            def capabilities = Capabilities
           end
 
-          def health_status(ready)
-            ready ? 'healthy' : 'unhealthy'
+          def settings
+            Mlx.default_settings
           end
 
-          def circuit_state(status)
-            status == 'healthy' ? 'closed' : 'open'
+          def api_base
+            normalize_url(config.mlx_api_base || settings[:instances][:default][:endpoint])
           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')
-            {}
+          def headers
+            hdrs = identity_headers
+            token = config.mlx_api_key
+            hdrs['Authorization'] = "Bearer #{token}" unless token.nil? || token.to_s.empty?
+            hdrs
           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)
+          def health_url = '/health'
 
-              val = cfg.send(key)
-              result[key] = val unless val.nil?
-            rescue StandardError
-              next
-            end
-            result
+          def health(live: false)
+            log.info("Checking MLX health live=#{live} at #{api_base}#{health_url}")
+            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 model_capability_config(model_id)
-            models_conf = fetch_models_config
-            return {} unless models_conf
+          def readiness(live: false)
+            log.info("Checking MLX readiness (live=#{live})")
+            super
+          end
 
-            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')
-            {}
+          def list_models(**)
+            log.info('Listing available MLX models')
+            models = super
+            log.info("Discovered #{Array(models).size} MLX models")
+            models
           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
+          def offering_from_model(model_info, health: {})
+            policy = resolve_capability_policy(model_info)
+            Legion::Extensions::Llm::Routing::ModelOffering.new(**build_offering_kwargs(
+              model_info: model_info, policy: policy, health: health
+            ))
           end
 
-          def offering_metadata_for(model_info)
+          private
+
+          def build_offering_kwargs(model_info:, policy:, health:)
             {
-              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
+              provider_family: :mlx,
+              instance_id: provider_instance_id,
+              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: extract_model_limits(model_info),
+              health: health,
+              metadata: offering_metadata_for(model_info).merge(capability_sources: policy[:sources])
+            }
+          end
+
+          def extract_model_limits(model_info)
+            ctx = model_info.respond_to?(:context_length) ? model_info.context_length : nil
+            { context_window: ctx }.compact
           end
         end
       end

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

@@ -2,6 +2,7 @@
 
 require 'legion/extensions/llm/fleet/provider_responder'
 require 'legion/extensions/llm/mlx'
+require 'legion/logging'
 
 module Legion
   module Extensions
@@ -9,17 +10,35 @@ module Legion
       module Mlx
         module Runners
           # Runner entrypoint for MLX fleet request execution.
+          # Delegates to the shared ProviderResponder with exact-offering
+          # registry support for SSOT v3 execution contracts.
+          #
+          # The fleet Subscription actor dispatches this as
+          # `handle_fleet_request(**message)`, where message is the decoded
+          # request envelope merged with transport metadata, so the
+          # signature is kwargs-only. Ack/reject is owned by the
+          # Subscription actor, so the responder is called with nil
+          # delivery/properties.
           module FleetWorker
+            include Legion::Logging::Helper
+            extend Legion::Logging::Helper
+
             module_function
 
-            def handle_fleet_request(payload, delivery: nil, properties: nil)
+            def handle_fleet_request(**message)
+              log.debug do
+                "handling MLX fleet request request_id=#{message[:request_id].inspect} " \
+                  "provider_instance=#{message[:provider_instance].inspect} " \
+                  "operation=#{message[:operation].inspect}"
+              end
               Legion::Extensions::Llm::Fleet::ProviderResponder.call(
-                payload: payload,
+                payload: message,
                 provider_family: Mlx::PROVIDER_FAMILY,
                 provider_class: Mlx::Provider,
                 provider_instances: -> { Mlx.discover_instances },
-                delivery: delivery,
-                properties: properties
+                registry: Legion::Extensions::Llm::Inventory::Registry,
+                delivery: nil,
+                properties: nil
               )
             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.13'
+        VERSION = '0.5.2'
       end
     end
   end

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

@@ -3,7 +3,7 @@
 require 'legion/extensions/llm'
 require 'legion/extensions/llm/mlx/provider'
 require 'legion/extensions/llm/mlx/version'
-require_relative 'mlx/actors/discovery_refresh'
+require 'legion/extensions/llm/mlx/actors/discovery_refresh'
 
 module Legion
   module Extensions
@@ -11,7 +11,6 @@ module Legion
       # Mlx provider extension namespace.
       module Mlx
         extend Legion::Logging::Helper
-        extend ::Legion::Extensions::Core if ::Legion::Extensions.const_defined?(:Core, false)
         extend Legion::Extensions::Llm::AutoRegistration
 
         PROVIDER_FAMILY = :mlx
@@ -39,48 +38,83 @@ module Legion
           Provider
         end
 
+        # Single source of truth for MLX instance discovery. The SSOT
+        # discovery actor and the fleet responder both read this: only
+        # operator-configured instances. No port-scanning, no fabricated
+        # instances, no tier override.
         def self.discover_instances
+          configured_instances
+        end
+
+        # Only instances the operator actually configured are claimable.
+        # The synthetic instances.default section (provider_settings nests
+        # the extension's own instance defaults there at boot) is skipped
+        # with a once-per-boot warn while it is still the unmodified
+        # extension default — an unconfigured phantom must never be
+        # auto-registered, and a localhost endpoint is never a fallback
+        # identity.
+        def self.configured_instances
+          provider_cfg = Legion::Settings.dig(:extensions, :llm, :mlx) || {}
           instances = {}
-          discover_local_instance(instances)
-          discover_settings_instances(instances)
+          cfg_instances = provider_cfg[:instances]
+          if cfg_instances.is_a?(Hash)
+            cfg_instances.each do |name, config|
+              normalized = normalize_instance_config(config)
+              instances[name.to_sym] = normalized
+            end
+          end
           instances
         end
 
-        def self.discover_local_instance(instances)
-          return unless CredentialSources.socket_open?('localhost', 8000, timeout: 0.1)
-
-          instances[:local] = {
-            base_url: 'http://localhost:8000',
-            tier: :local,
-            capabilities: [:completion]
-          }
+        # The synthetic default is the extension's OWN registered instance
+        # defaults (endpoint http://localhost:8000 + fleet/limits blocks),
+        # deep-merged into instances.default by provider_settings. It is
+        # "configured" only when the operator changed something — a
+        # configured 'default' passes the provider layer and reaches the
+        # claim path (v2 parity: 'default' is a plain instance label). ONE
+        # predicate, TWO consumers: the actor's claim path (tick_refresh
+        # iterates configured_instances into claim_and_activate_instance)
+        # and the fleet responder (discover_instances → configured_instances)
+        # both reach it through this single filter point — no drift.
+        def self.unconfigured_default?(name:, normalized:)
+          name.to_sym == :default && normalized == normalized_synthetic_default_instance
         end
 
-        def self.discover_settings_instances(instances)
-          cfg = CredentialSources.setting(:extensions, :llm, :mlx, :instances)
-          return unless cfg.is_a?(Hash)
+        def self.normalized_synthetic_default_instance
+          @normalized_synthetic_default_instance ||= normalize_instance_config(
+            default_settings.dig(:instances, :default) || {}
+          )
+        end
 
-          cfg.each do |name, config|
-            instances[name.to_sym] = normalize_instance_config(config).merge(tier: :direct)
-          end
+        def self.normalize_instance_config(config)
+          normalized = config.to_h.transform_keys(&:to_sym)
+          promote_api_base_aliases(normalized)
+          normalized[:mlx_api_base] = normalize_api_base(normalized[:mlx_api_base]) if normalized[:mlx_api_base]
+          normalized[:mlx_api_key] ||= normalized.delete(:api_key)
+          resolve_instance_credentials(normalized)
+          normalized[:tier] ||= :local
+          normalized.compact
         end
 
-        def self.normalize_instance_config(config) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
-          normalized = config.to_h.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+        def self.promote_api_base_aliases(normalized)
           normalized[:mlx_api_base] ||= normalized.delete(:base_url)
           normalized[:mlx_api_base] ||= normalized.delete(:api_base)
           normalized[:mlx_api_base] ||= normalized.delete(:endpoint)
-          normalized[:mlx_api_key] ||= normalized.delete(:api_key)
-          normalized[:mlx_api_base] = normalize_api_base(normalized[:mlx_api_base]) if normalized[:mlx_api_base]
-          normalized.compact
         end
 
         def self.normalize_api_base(url)
           url.to_s.sub(%r{/v1/?\z}, '')
         end
 
-        private_class_method :discover_local_instance, :discover_settings_instances,
-                             :normalize_instance_config, :normalize_api_base
+        def self.resolve_instance_credentials(normalized)
+          creds = normalized.delete(:credentials)
+          return unless creds.is_a?(Hash)
+
+          normalized[:mlx_api_key] ||= creds.transform_keys(&:to_sym)[:api_key]
+        end
+
+        private_class_method :normalize_instance_config, :promote_api_base_aliases, :normalize_api_base,
+                             :resolve_instance_credentials
 
         Legion::Extensions::Llm::Configuration.register_provider_options(Provider.configuration_options)
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-mlx
 version: !ruby/object:Gem::Version
-  version: 0.3.13
+  version: 0.5.2
 platform: ruby
 authors:
 - LegionIO
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.10.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.10.0
 - !ruby/object:Gem::Dependency
   name: legion-json
   requirement: !ruby/object:Gem::Requirement
@@ -43,14 +57,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.14
+        version: 1.4.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.14
+        version: 1.4.2
 - !ruby/object:Gem::Dependency
   name: legion-transport
   requirement: !ruby/object:Gem::Requirement
@@ -71,14 +85,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.7.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.7.1
 description: MLX provider integration for the LegionIO LLM routing framework.
 email:
 - matthewdiverson@gmail.com