lex-llm-mlx 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6305c1739c33374352cd5bda241303bd3e4dbfa742a162a7b11276be46eccb97
-  data.tar.gz: f50421895c2cf1472393b0687aed78e8ae98b27a130fd95a2038060faa588377
+  metadata.gz: d4c28dde2944e28432fd8d9f30d927018476fc0879056115b2ff60074a13096e
+  data.tar.gz: 9faff4486487ace84299b5b066e67ce90e58634a50c93e1e4ce33f347acac3c0
 SHA512:
-  metadata.gz: 86b833f891fe19fbb9f8e136a0da466d3a1cd1dc4c6af02eb5cab62fe3fffb2f8684c20c9f6a978859f44f756c4dbbb51004effe42d120d117f02ef13e3545de
-  data.tar.gz: d3f422a95aac94dcd185c754cd5f1806edd86d77ff73b6a429c838dbd6369f51298a7ff1f38019ccc455509b66a9525a2cb30893cd5f7fad0ff8499f2cfebb77
+  metadata.gz: f0fd9fa8260d3e4fd2da783b852189d5ec409b956402ad4fb49487772468a3ff7b63eb35d271174f3996719ba925c7f80954103c3437a8049a788ddbc76127ea
+  data.tar.gz: 5adf6fb8d5f2093fb5381aeb5979510baa0d74efa6b8cfec9c32cd30f4d5ac016e615245045b48d38a7246b9eba94001dbcf0398124e2a7e99eaf3c2c9f58b1b

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.2.0 - 2026-04-30
+
+- Adopt lex-llm 0.1.9 base contract for RegistryPublisher and RegistryEventBuilder.
+- Remove local `RegistryPublisher` and `RegistryEventBuilder` classes in favor of parameterized base versions.
+- Remove local `transport/` directory (exchange and message classes) in favor of shared lex-llm transport layer.
+- Remove deprecated `Provider.register` call; register configuration options directly.
+- Replace `provider_settings` builder with flat `default_settings` hash matching the new consumer contract.
+- Bump gemspec dependency to `lex-llm >= 0.1.9`.
+
+## 0.1.7 - 2026-04-30
+
+- Add `Legion::Logging::Helper` to `Mlx` module and `RegistryPublisher` for standardized logging.
+- Replace all bare rescue blocks with `handle_exception` calls for full observability.
+- Add info-level action logging for health checks, readiness, model discovery, and registry publishing.
+- Remove custom `log_publish_failure` method in favor of `handle_exception`.
+- Update README to document registry event publishing, transport layer, and architecture.
+
 ## 0.1.6 - 2026-04-28
 
 - Publish best-effort `llm.registry` live readiness and discovered-model availability events using `lex-llm` registry envelopes when transport is already available.

data/README.md

@@ -12,7 +12,21 @@ Load it with `require 'legion/extensions/llm/mlx'`.
 - OpenAI-compatible chat, streaming, model listing, and embeddings endpoint wrappers.
 - Heuristic chat, embedding, and vision capability mapping for discovered local models.
 - Local-first defaults for MLX servers running on MacBook, Mac Studio, or local Apple Silicon hosts.
-- Shared Legion settings, JSON, and logging dependencies.
+- Best-effort `llm.registry` event publishing for readiness and model availability when transport is available.
+- Shared Legion settings, JSON, and logging dependencies with full `Legion::Logging::Helper` integration.
+
+## Architecture
+
+```
+Legion::Extensions::Llm::Mlx
+  Mlx (module)             # Extension namespace, provider registration, default settings
+  Provider                 # MLX provider — health, readiness, model listing, OpenAI-compatible adapter
+  RegistryPublisher        # Async publisher for llm.registry readiness/model availability events
+  RegistryEventBuilder     # Builds sanitized lex-llm registry envelopes for MLX provider state
+  Transport::
+    Messages::RegistryEvent  # AMQP message for llm.registry exchange
+    Exchanges::LlmRegistry   # Topic exchange definition for llm.registry
+```
 
 ## Default Settings
 
@@ -41,3 +55,30 @@ end
 - `health_url`: `/health`
 
 The provider uses the shared `Legion::Extensions::Llm::Provider::OpenAICompatible` adapter so Legion routing can treat MLX, vLLM, OpenAI, and other compatible servers consistently while preserving provider-specific settings and health behavior.
+
+## Registry Event Publishing
+
+When `Legion::Transport` and `lex-llm` routing are available, the provider publishes best-effort events to the `llm.registry` topic exchange:
+
+- **Readiness events** — published asynchronously when `readiness(live: true)` is called.
+- **Model availability events** — published asynchronously after `list_models` discovers models.
+
+Publishing is fire-and-forget in background threads; failures never block the provider.
+
+## Dependencies
+
+| Gem | Required | Purpose |
+|-----|----------|---------|
+| `legion-json` (>= 1.2.1) | Yes | JSON serialization |
+| `legion-logging` (>= 1.3.2) | Yes | Structured logging via Helper |
+| `legion-settings` (>= 1.3.14) | Yes | Configuration |
+| `lex-llm` (>= 0.1.5) | Yes | Shared provider base, routing, fleet |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec       # 0 failures
+bundle exec rubocop -A  # auto-fix
+bundle exec rubocop     # lint check
+```

data/lex-llm-mlx.gemspec

@@ -26,5 +26,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-json', '>= 1.2.1'
   spec.add_dependency 'legion-logging', '>= 1.3.2'
   spec.add_dependency 'legion-settings', '>= 1.3.14'
-  spec.add_dependency 'lex-llm', '>= 0.1.5'
+  spec.add_dependency 'lex-llm', '>= 0.2.0'
 end

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

@@ -20,7 +20,7 @@ module Legion
             def capabilities = Capabilities
 
             def registry_publisher
-              @registry_publisher ||= RegistryPublisher.new
+              @registry_publisher ||= Legion::Extensions::Llm::RegistryPublisher.new(provider_family: :mlx)
             end
           end
 
@@ -48,8 +48,12 @@ module Legion
             end
           end
 
+          def settings
+            Mlx.default_settings
+          end
+
           def api_base
-            config.mlx_api_base || 'http://localhost:8000'
+            normalize_url(config.mlx_api_base || 'localhost:8000')
           end
 
           def headers
@@ -62,17 +66,21 @@ module Legion
           def health_url = '/health'
 
           def health
+            log.info("Checking MLX health at #{api_base}#{health_url}")
             connection.get(health_url).body
           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
           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
           end

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Mlx
-        VERSION = '0.1.6'
+        VERSION = '0.2.0'
       end
     end
   end

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

@@ -2,8 +2,6 @@
 
 require 'legion/extensions/llm'
 require 'legion/extensions/llm/mlx/provider'
-require 'legion/extensions/llm/mlx/registry_event_builder'
-require 'legion/extensions/llm/mlx/registry_publisher'
 require 'legion/extensions/llm/mlx/version'
 
 module Legion
@@ -11,21 +9,23 @@ module Legion
     module Llm
       # Mlx provider extension namespace.
       module Mlx
+        extend Legion::Logging::Helper
         extend ::Legion::Extensions::Core if ::Legion::Extensions.const_defined?(:Core, false)
 
         PROVIDER_FAMILY = :mlx
 
         def self.default_settings
-          ::Legion::Extensions::Llm.provider_settings(
-            family: PROVIDER_FAMILY,
-            instance: {
-              endpoint: 'http://localhost:8000',
-              tier: :local,
-              transport: :local,
-              usage: { inference: true, embedding: true },
-              limits: { concurrency: 1 }
-            }
-          )
+          {
+            enabled: false,
+            base_url: 'localhost:8000',
+            default_model: nil,
+            api_key: nil,
+            model_whitelist: [],
+            model_blacklist: [],
+            model_cache_ttl: 60,
+            tls: { enabled: false, verify: :peer },
+            instances: {}
+          }
         end
 
         def self.provider_class
@@ -36,5 +36,6 @@ module Legion
   end
 end
 
-Legion::Extensions::Llm::Provider.register(Legion::Extensions::Llm::Mlx::PROVIDER_FAMILY,
-                                           Legion::Extensions::Llm::Mlx::Provider)
+Legion::Extensions::Llm::Configuration.register_provider_options(
+  Legion::Extensions::Llm::Mlx::Provider.configuration_options
+)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-mlx
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.0
 platform: ruby
 authors:
 - LegionIO
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: 0.2.0
 description: MLX provider integration for the LegionIO LLM routing framework.
 email:
 - matthewdiverson@gmail.com
@@ -84,10 +84,6 @@ files:
 - lex-llm-mlx.gemspec
 - lib/legion/extensions/llm/mlx.rb
 - lib/legion/extensions/llm/mlx/provider.rb
-- lib/legion/extensions/llm/mlx/registry_event_builder.rb
-- lib/legion/extensions/llm/mlx/registry_publisher.rb
-- lib/legion/extensions/llm/mlx/transport/exchanges/llm_registry.rb
-- lib/legion/extensions/llm/mlx/transport/messages/registry_event.rb
 - lib/legion/extensions/llm/mlx/version.rb
 homepage: https://github.com/LegionIO/lex-llm-mlx
 licenses:

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

@@ -1,118 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Llm
-      module Mlx
-        # Builds sanitized lex-llm registry envelopes for MLX provider state.
-        class RegistryEventBuilder
-          def readiness(readiness)
-            registry_event_class.public_send(
-              readiness[:ready] ? :available : :unavailable,
-              provider_offering(readiness),
-              runtime: runtime_metadata,
-              health: readiness_health(readiness),
-              metadata: readiness_metadata(readiness)
-            )
-          end
-
-          def model_available(model, readiness:)
-            registry_event_class.available(
-              model_offering(model),
-              runtime: runtime_metadata,
-              health: model_health(readiness),
-              metadata: model_metadata(model)
-            )
-          end
-
-          private
-
-          def provider_offering(readiness)
-            {
-              provider_family: :mlx,
-              provider_instance: provider_instance,
-              transport: :http,
-              model: 'provider-readiness',
-              usage_type: :inference,
-              capabilities: [],
-              health: readiness_health(readiness),
-              metadata: { lex: :llm_mlx, provider_readiness: true }
-            }
-          end
-
-          def model_offering(model)
-            {
-              provider_family: :mlx,
-              provider_instance: provider_instance,
-              transport: :http,
-              model: model.id,
-              usage_type: usage_type_for(model),
-              capabilities: Array(model.capabilities).map(&:to_sym),
-              limits: model_limits(model),
-              metadata: { lex: :llm_mlx, model_name: model.name }.compact
-            }
-          end
-
-          def readiness_health(readiness)
-            health = {
-              ready: readiness[:ready] == true,
-              status: readiness[:ready] ? :available : :unavailable,
-              checked: readiness.dig(:health, :checked) != false
-            }
-            add_readiness_error(health, readiness[:health])
-          end
-
-          def add_readiness_error(health, source)
-            error = source.is_a?(Hash) ? source : {}
-            error_class = error[:error] || error['error']
-            error_message = error[:message] || error['message']
-            health[:error_class] = error_class if error_class
-            health[:error] = error_message if error_message
-            health
-          end
-
-          def model_health(readiness)
-            ready = readiness.fetch(:ready, true) == true
-            { ready:, status: ready ? :available : :degraded }
-          end
-
-          def readiness_metadata(readiness)
-            {
-              extension: :lex_llm_mlx,
-              provider: :mlx,
-              configured: readiness[:configured] == true,
-              live: readiness[:live] == true
-            }
-          end
-
-          def model_metadata(model)
-            { extension: :lex_llm_mlx, provider: :mlx, model_type: model.type }
-          end
-
-          def runtime_metadata
-            { node: provider_instance }
-          end
-
-          def model_limits(model)
-            {
-              context_window: model.context_window,
-              max_output_tokens: model.max_output_tokens
-            }.compact
-          end
-
-          def usage_type_for(model)
-            model.type == 'embedding' ? :embedding : :inference
-          end
-
-          def provider_instance
-            :mlx
-          end
-
-          def registry_event_class
-            ::Legion::Extensions::Llm::Routing::RegistryEvent
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,100 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Llm
-      module Mlx
-        # Best-effort publisher for MLX provider availability events.
-        class RegistryPublisher
-          APP_ID = 'lex-llm-mlx'
-
-          def initialize(builder: RegistryEventBuilder.new)
-            @builder = builder
-          end
-
-          def publish_readiness_async(readiness)
-            schedule { publish_event(@builder.readiness(readiness)) }
-          end
-
-          def publish_models_async(models, readiness:)
-            schedule do
-              Array(models).each do |model|
-                publish_event(@builder.model_available(model, readiness:))
-              end
-            end
-          end
-
-          private
-
-          def schedule(&)
-            return false unless publishing_available?
-
-            Thread.new do
-              Thread.current.abort_on_exception = false
-              yield
-            rescue StandardError => e
-              log_publish_failure(e, level: :debug)
-            end
-          rescue StandardError => e
-            log_publish_failure(e, level: :debug)
-            false
-          end
-
-          def publish_event(event)
-            return false unless publishing_available?
-
-            message_class.new(event:, app_id: APP_ID).publish(spool: false)
-          rescue StandardError => e
-            log_publish_failure(e)
-            false
-          end
-
-          def publishing_available?
-            return false unless registry_event_available?
-            return false unless transport_message_available?
-            return true unless defined?(::Legion::Transport::Connection)
-            return true unless ::Legion::Transport::Connection.respond_to?(:session_open?)
-
-            ::Legion::Transport::Connection.session_open?
-          rescue StandardError
-            false
-          end
-
-          def registry_event_available?
-            defined?(::Legion::Extensions::Llm::Routing::RegistryEvent)
-          end
-
-          def transport_message_available?
-            return true if message_class_defined?
-            return false unless defined?(::Legion::Transport::Message) && defined?(::Legion::Transport::Exchange)
-
-            require 'legion/extensions/llm/mlx/transport/messages/registry_event'
-            message_class_defined?
-          rescue LoadError
-            false
-          end
-
-          def message_class_defined?
-            defined?(::Legion::Extensions::Llm::Mlx::Transport::Messages::RegistryEvent)
-          end
-
-          def message_class
-            ::Legion::Extensions::Llm::Mlx::Transport::Messages::RegistryEvent
-          end
-
-          def log_publish_failure(error, level: :warn)
-            message = "[lex-llm-mlx] llm.registry publish failed: #{error.class}: #{error.message}"
-            logger = ::Legion::Extensions::Llm.logger if defined?(::Legion::Extensions::Llm)
-            if logger.respond_to?(level)
-              logger.public_send(level, message)
-            elsif logger.respond_to?(:debug)
-              logger.debug(message)
-            end
-          rescue StandardError
-            nil
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/llm/mlx/transport/exchanges/llm_registry.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Llm
-      module Mlx
-        module Transport
-          module Exchanges
-            # Topic exchange for MLX provider availability events.
-            class LlmRegistry < ::Legion::Transport::Exchange
-              def exchange_name
-                'llm.registry'
-              end
-
-              def default_type
-                'topic'
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/llm/mlx/transport/messages/registry_event.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-require 'legion/extensions/llm/mlx/transport/exchanges/llm_registry'
-
-module Legion
-  module Extensions
-    module Llm
-      module Mlx
-        module Transport
-          module Messages
-            # Publishes lex-llm RegistryEvent envelopes to the llm.registry exchange.
-            class RegistryEvent < ::Legion::Transport::Message
-              def initialize(event:, **options)
-                super(**event.to_h.merge(options))
-              end
-
-              def exchange
-                Transport::Exchanges::LlmRegistry
-              end
-
-              def routing_key
-                @options[:routing_key] || "llm.registry.#{@options.fetch(:event_type)}"
-              end
-
-              def type
-                'llm.registry.event'
-              end
-
-              def app_id
-                @options[:app_id] || RegistryPublisher::APP_ID
-              end
-
-              def persistent # rubocop:disable Naming/PredicateMethod
-                false
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-end