lex-llm-mlx 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f02dcdce8e8d6c755dfc0823ad9f22cfda099675efa26c09a39de9573ba484cb
-  data.tar.gz: a32ce7c861f05eb42bb73253b15e4c9b2b078e583456d4f135d01ea52fcf48a4
+  metadata.gz: b4c018fd3b44a629665783ce38fd5c0f5429ab41452b2e8829079a08c2807860
+  data.tar.gz: d75bf991619c7d3bf8bc4d7b0aaf77cdb11e6a352595e210ef36f2b6e094cecb
 SHA512:
-  metadata.gz: 96cf438ecdc6f331304fafe09bfd46c9baf56992dcb46ecc5b901bda4775e4566dd1adfeebcccf74d59a234bdeacc9f751b540201b3b6209c9f6ca89bfa7a44d
-  data.tar.gz: aa4b04058524f283e52974b4feb5b16d02c6b1ddcab8191bce7c8fc5e8f0f587fdd08a7b3109ec9978973ce8d8391a21d1dfcec09c9da31eada0ef15783995b6
+  metadata.gz: cee424e550ad1ee7cf3a19f791f3bf72434b170efbb50e3e952d5eb502943f442b14ba29344b26575657a390785ad4749ad8d95f7c34454f9d7852160584ff4a
+  data.tar.gz: 287b5609ee6788ce4865d1b4f1fb49e344198fe5ca1b828f806742810d82d29e1a18fa28c2404b9a8b0144878ea3d52154fb3e702286f02f2a836239f0d7f316

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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.
+
 ## 0.1.5 - 2026-04-28
 
 - Require current shared Legion JSON, logging, settings, and `lex-llm >= 0.1.5` runtime dependencies.

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/lib/legion/extensions/llm/mlx/provider.rb

@@ -11,11 +11,17 @@ module Legion
           include Legion::Extensions::Llm::Provider::OpenAICompatible
 
           class << self
+            attr_writer :registry_publisher
+
             def slug = 'mlx'
             def local? = true
             def configuration_options = %i[mlx_api_base mlx_api_key]
             def configuration_requirements = []
             def capabilities = Capabilities
+
+            def registry_publisher
+              @registry_publisher ||= RegistryPublisher.new
+            end
           end
 
           # Conservative capability predicates for local MLX OpenAI-compatible servers.
@@ -56,8 +62,24 @@ 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
         end
       end
     end

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

@@ -0,0 +1,118 @@
+# 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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Mlx
+        # Best-effort publisher for MLX provider availability events.
+        class RegistryPublisher
+          include Legion::Logging::Helper if defined?(Legion::Logging::Helper)
+
+          APP_ID = 'lex-llm-mlx'
+
+          def initialize(builder: RegistryEventBuilder.new)
+            @builder = builder
+          end
+
+          def publish_readiness_async(readiness)
+            log.info('Publishing MLX readiness event asynchronously')
+            schedule { publish_event(@builder.readiness(readiness)) }
+          end
+
+          def publish_models_async(models, readiness:)
+            log.info("Publishing #{Array(models).size} MLX model availability events asynchronously")
+            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
+              handle_exception(e, level: :debug, handled: true, operation: 'mlx.registry_publisher.schedule_thread')
+            end
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'mlx.registry_publisher.schedule')
+            false
+          end
+
+          def publish_event(event)
+            return false unless publishing_available?
+
+            log.info("Publishing MLX registry event: #{event.class}")
+            message_class.new(event:, app_id: APP_ID).publish(spool: false)
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'mlx.registry_publisher.publish_event')
+            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 => e
+            handle_exception(e, level: :debug, handled: true,
+                                operation: 'mlx.registry_publisher.publishing_available?')
+            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 => e
+            handle_exception(e, level: :debug, handled: true,
+                                operation: 'mlx.registry_publisher.transport_message_available?')
+            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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# 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

@@ -0,0 +1,42 @@
+# 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

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Mlx
-        VERSION = '0.1.5'
+        VERSION = '0.1.7'
       end
     end
   end

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

@@ -2,6 +2,8 @@
 
 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
@@ -9,6 +11,7 @@ module Legion
     module Llm
       # Mlx provider extension namespace.
       module Mlx
+        extend Legion::Logging::Helper if defined?(Legion::Logging::Helper)
         extend ::Legion::Extensions::Core if ::Legion::Extensions.const_defined?(:Core, false)
 
         PROVIDER_FAMILY = :mlx
@@ -36,3 +39,6 @@ end
 
 Legion::Extensions::Llm::Provider.register(Legion::Extensions::Llm::Mlx::PROVIDER_FAMILY,
                                            Legion::Extensions::Llm::Mlx::Provider)
+if Legion::Extensions::Llm::Mlx.respond_to?(:log)
+  Legion::Extensions::Llm::Mlx.log.info('Registered MLX provider as :mlx')
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-mlx
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - LegionIO
@@ -84,6 +84,10 @@ 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: