lex-llm-mlx 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6305c1739c33374352cd5bda241303bd3e4dbfa742a162a7b11276be46eccb97
-  data.tar.gz: f50421895c2cf1472393b0687aed78e8ae98b27a130fd95a2038060faa588377
+  metadata.gz: b4c018fd3b44a629665783ce38fd5c0f5429ab41452b2e8829079a08c2807860
+  data.tar.gz: d75bf991619c7d3bf8bc4d7b0aaf77cdb11e6a352595e210ef36f2b6e094cecb
 SHA512:
-  metadata.gz: 86b833f891fe19fbb9f8e136a0da466d3a1cd1dc4c6af02eb5cab62fe3fffb2f8684c20c9f6a978859f44f756c4dbbb51004effe42d120d117f02ef13e3545de
-  data.tar.gz: d3f422a95aac94dcd185c754cd5f1806edd86d77ff73b6a429c838dbd6369f51298a7ff1f38019ccc455509b66a9525a2cb30893cd5f7fad0ff8499f2cfebb77
+  metadata.gz: cee424e550ad1ee7cf3a19f791f3bf72434b170efbb50e3e952d5eb502943f442b14ba29344b26575657a390785ad4749ad8d95f7c34454f9d7852160584ff4a
+  data.tar.gz: 287b5609ee6788ce4865d1b4f1fb49e344198fe5ca1b828f806742810d82d29e1a18fa28c2404b9a8b0144878ea3d52154fb3e702286f02f2a836239f0d7f316

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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.

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

@@ -62,17 +62,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/registry_publisher.rb

@@ -6,6 +6,8 @@ module Legion
       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)
@@ -13,10 +15,12 @@ module Legion
           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:))
@@ -33,19 +37,20 @@ module Legion
               Thread.current.abort_on_exception = false
               yield
             rescue StandardError => e
-              log_publish_failure(e, level: :debug)
+              handle_exception(e, level: :debug, handled: true, operation: 'mlx.registry_publisher.schedule_thread')
             end
           rescue StandardError => e
-            log_publish_failure(e, level: :debug)
+            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
-            log_publish_failure(e)
+            handle_exception(e, level: :warn, handled: true, operation: 'mlx.registry_publisher.publish_event')
             false
           end
 
@@ -56,7 +61,9 @@ module Legion
             return true unless ::Legion::Transport::Connection.respond_to?(:session_open?)
 
             ::Legion::Transport::Connection.session_open?
-          rescue StandardError
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true,
+                                operation: 'mlx.registry_publisher.publishing_available?')
             false
           end
 
@@ -70,7 +77,9 @@ module Legion
 
             require 'legion/extensions/llm/mlx/transport/messages/registry_event'
             message_class_defined?
-          rescue LoadError
+          rescue LoadError => e
+            handle_exception(e, level: :debug, handled: true,
+                                operation: 'mlx.registry_publisher.transport_message_available?')
             false
           end
 
@@ -81,18 +90,6 @@ module Legion
           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

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.1.7'
       end
     end
   end

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

@@ -11,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
@@ -38,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.6
+  version: 0.1.7
 platform: ruby
 authors:
 - LegionIO