lex-llm-mlx 0.3.0 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38cb4fb34920395c6af9d7d86f8fbc104c92b632cb886acc601a80815fd64d02
-  data.tar.gz: 29ef77ad4cc5ff70720aa9ce298f6d5fbdde58e7dc4836369e4a60bbaf1e70d8
+  metadata.gz: 5c591beb817516c542e92352ffd580449e5b966f290a3440a753dbcbb45ea9b6
+  data.tar.gz: 05c1a37ec94439268940e2e883136661eec0fdf37ac82111aea0503e037a81c1
 SHA512:
-  metadata.gz: c8a71c4d81eaaa3d1aeb66256ae163b922d1ef139317a540fbc62423bbf5d2edc67ca9f9def102420bd9da2d862097ed493dd028a740d58d14ca523f36068ef4
-  data.tar.gz: '049f44b3ec25a8ceffa50b6228a7d5a5e20941fa3a54cc142127caa93b075931ad3613ea39dc23bff469fc24c31f5ff5256adc0153a2f53926894403a5c49a34'
+  metadata.gz: 2a81d1aca40035296633d2b37af08b464d8fe7ecb4e7f210bc0dd856e10f1599d88bb43a2998557413ad53e31923fb6ca6d44fb6c95a919561ca405daf398644
+  data.tar.gz: 3dcfc07aab6db3e5972f5b18313d864f54fc64aa3b81527c3f5b1f4d306b8f33327acb5359c300a824ccce24e87705b66be4ce4fb7af80d1fb3e816e433fb99f

data/.github/workflows/ci.yml

@@ -8,8 +8,20 @@ jobs:
   ci:
     uses: LegionIO/.github/.github/workflows/ci.yml@main
 
+  excluded-files:
+    uses: LegionIO/.github/.github/workflows/excluded-files.yml@main
+
+  security:
+    uses: LegionIO/.github/.github/workflows/security-scan.yml@main
+
+  version-changelog:
+    uses: LegionIO/.github/.github/workflows/version-changelog.yml@main
+
+  dependency-review:
+    uses: LegionIO/.github/.github/workflows/dependency-review.yml@main
+
   release:
-    needs: ci
+    needs: [ci, excluded-files, security]
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     uses: LegionIO/.github/.github/workflows/release.yml@main
     secrets:

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.3.5 - 2026-05-06
+
+- Load provider-owned fleet actors through the LegionIO subscription base and the canonical MLX provider root.
+- Keep fleet runners anchored on the provider root namespace so provider constants and instance discovery are always loaded.
+- Gate release publishing on the shared security workflow.
+
+## 0.3.4 - 2026-05-06
+
+- Use the shared `lex-llm` fleet provider responder helper for provider-owned fleet workers.
+- Remove the runtime `legion-llm` dependency and require `lex-llm >= 0.4.3` for responder-side fleet execution.
+
+## 0.3.3 - 2026-05-06
+
+- Remove require-time provider self-registration; `legion-llm` now owns adapter creation and registry writes from loaded provider discovery metadata.
+- Bump dependency floors to `lex-llm >= 0.4.1` and `legion-llm >= 0.9.1`.
+
+## 0.3.2 - 2026-05-06
+
+- Enforce the shared keyword-only `lex-llm` provider contract and accept `health(live:)`.
+- Move MLX defaults back to `Legion::Extensions::Llm.provider_settings` with instance-level fleet responder settings.
+- Add provider-owned fleet responder actor and runner backed by `legion-llm` fleet policy execution.
+- Bump the transport dependency floor to `legion-transport >= 1.4.14`.
+
+## 0.3.1 - 2026-05-03
+
+- Normalize generic settings keys to MLX provider config keys during instance discovery.
+- Strip trailing `/v1` from configured OpenAI-compatible MLX API roots.
+
 ## 0.3.0 - 2026-05-01
 
 - Add auto-discovery via CredentialSources and AutoRegistration from lex-llm 0.3.0

data/Gemfile

@@ -4,6 +4,8 @@ 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
 

data/README.md

@@ -2,42 +2,47 @@
 
 LegionIO LLM provider extension for MLX-backed OpenAI-compatible servers on Apple Silicon.
 
-This gem lives under `Legion::Extensions::Llm::Mlx` and depends on `lex-llm` for shared provider-neutral routing, fleet, and schema primitives.
+This gem lives under `Legion::Extensions::Llm::Mlx` and depends on `lex-llm >= 0.4.3` for shared provider-neutral routing, response normalization, fleet envelopes, fleet responder execution, and schema primitives.
 
 Load it with `require 'legion/extensions/llm/mlx'`.
 
 ## What It Provides
 
-- `Legion::Extensions::Llm::Mlx::Provider`, registered as `:mlx`.
+- `Legion::Extensions::Llm::Mlx::Provider`, exposed to `legion-llm` as the `:mlx` provider family.
 - 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.
-- Best-effort `llm.registry` event publishing for readiness and model availability when transport is available.
+- Local-first defaults for MLX servers running on Apple Silicon hosts.
+- Best-effort `llm.registry` event publishing through shared `lex-llm` registry helpers when transport is available.
+- Provider-owned fleet request actor and runner backed by `lex-llm`.
 - 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
+  Mlx                          # Extension namespace, discovery metadata, default settings
+  Provider                     # Health, readiness, model listing, OpenAI-compatible adapter
+  Actor::FleetWorker           # Subscription actor enabled by provider instance fleet settings
+  Runners::FleetWorker         # Delegates fleet execution to Legion::Extensions::Llm::Fleet::ProviderResponder
+  (shared from lex-llm)
+    RegistryPublisher          # Async llm.registry event publishing
+    RegistryEventBuilder       # Sanitized registry envelope construction
 ```
 
+The extension no longer writes provider adapters into the registry at require time. Loaded provider discovery metadata is consumed by `legion-llm`, which owns adapter creation and registry writes.
+
 ## Default Settings
 
 ```ruby
 Legion::Extensions::Llm::Mlx.default_settings
 ```
 
-Defaults target `http://localhost:8000`, mark the provider as `:local`, and allow one concurrent local request. Fleet participation stays disabled unless the host opts in through `Legion::Settings`.
+Defaults target `http://localhost:8000`, mark the default instance as `:local`, allow one concurrent local request, and keep fleet participation disabled until a host opts in through extension settings.
 
 ## Configuration
 
+The provider accepts the shared `lex-llm` configuration options:
+
 ```ruby
 Legion::Extensions::Llm.configure do |config|
   config.mlx_api_base = 'http://localhost:8000'
@@ -47,6 +52,47 @@ end
 
 `mlx_api_key` is optional because most local MLX servers run without authentication. Set it when a proxy or hosted MLX gateway requires bearer authentication.
 
+Provider discovery also reads named instances from `extensions.llm.mlx.instances`. Generic keys are normalized for the MLX provider:
+
+```yaml
+extensions:
+  llm:
+    mlx:
+      instances:
+        local:
+          base_url: http://localhost:8000
+          api_key: null
+          fleet:
+            enabled: false
+            respond_to_requests: false
+            capabilities:
+              - chat
+              - stream_chat
+              - embed
+```
+
+Accepted instance URL keys are `base_url`, `api_base`, `endpoint`, or `mlx_api_base`. A trailing `/v1` is stripped because the shared OpenAI-compatible adapter appends endpoint paths itself.
+
+## Fleet Responder
+
+Provider instances can opt in to consuming Legion LLM fleet requests. The provider-owned fleet actor only starts when at least one configured instance enables `respond_to_requests`.
+
+```yaml
+extensions:
+  llm:
+    mlx:
+      instances:
+        local:
+          base_url: http://localhost:8000
+          fleet:
+            enabled: true
+            respond_to_requests: true
+            capabilities:
+              - chat
+              - stream_chat
+              - embed
+```
+
 ## Endpoint Helpers
 
 - `completion_url` and `stream_url`: `/v1/chat/completions`
@@ -65,6 +111,13 @@ When `Legion::Transport` and `lex-llm` routing are available, the provider publi
 
 Publishing is fire-and-forget in background threads; failures never block the provider.
 
+## Failure Modes
+
+- `readiness(live: true)` calls the MLX `/health` endpoint and publishes readiness metadata only when the live check succeeds.
+- `list_models` expects an OpenAI-compatible `/v1/models` response and publishes discovered model availability through the shared registry publisher.
+- Fleet request handling is disabled unless at least one discovered instance opts in with `fleet.respond_to_requests: true`.
+- Local instance discovery checks `localhost:8080`; explicitly configured instances can point at any OpenAI-compatible MLX endpoint.
+
 ## Dependencies
 
 | Gem | Required | Purpose |
@@ -72,13 +125,13 @@ Publishing is fire-and-forget in background threads; failures never block the pr
 | `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 |
+| `lex-llm` (>= 0.4.3) | Yes | Shared provider base, response normalization, routing, fleet envelopes, and fleet responder execution |
+| `legion-transport` (>= 1.4.14) | Yes | AMQP subscriptions and replies |
 
 ## Development
 
 ```bash
 bundle install
-bundle exec rspec       # 0 failures
-bundle exec rubocop -A  # auto-fix
-bundle exec rubocop     # lint check
+bundle exec rspec --format json --out tmp/rspec_results.json --format progress --out tmp/rspec_progress.txt
+bundle exec rubocop -A
 ```

data/lex-llm-mlx.gemspec

@@ -26,5 +26,6 @@ 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.3.0'
+  spec.add_dependency 'legion-transport', '>= 1.4.14'
+  spec.add_dependency 'lex-llm', '>= 0.4.3'
 end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+begin
+  require 'legion/extensions/actors/subscription'
+rescue LoadError => e
+  warn(e.message) if $VERBOSE
+end
+
+unless defined?(Legion::Extensions::Actors::Subscription)
+  raise LoadError, 'LegionIO actor runtime is required for MLX fleet worker'
+end
+
+require 'legion/extensions/llm/mlx'
+require 'legion/extensions/llm/fleet/provider_responder'
+
+module Legion
+  module Extensions
+    module Llm
+      module Mlx
+        module Actor
+          # Subscription actor for MLX fleet request consumption.
+          class FleetWorker < Legion::Extensions::Actors::Subscription
+            def runner_class
+              'Legion::Extensions::Llm::Mlx::Runners::FleetWorker'
+            end
+
+            def runner_function
+              'handle_fleet_request'
+            end
+
+            def use_runner?
+              false
+            end
+
+            def enabled?
+              Legion::Extensions::Llm::Fleet::ProviderResponder.enabled_for?(Mlx.discover_instances)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -65,8 +65,8 @@ module Legion
 
           def health_url = '/health'
 
-          def health
-            log.info("Checking MLX health at #{api_base}#{health_url}")
+          def health(live: false)
+            log.info("Checking MLX health live=#{live} at #{api_base}#{health_url}")
             connection.get(health_url).body
           end
 

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm/fleet/provider_responder'
+require 'legion/extensions/llm/mlx'
+
+module Legion
+  module Extensions
+    module Llm
+      module Mlx
+        module Runners
+          # Runner entrypoint for MLX fleet request execution.
+          module FleetWorker
+            module_function
+
+            def handle_fleet_request(payload, delivery: nil, properties: nil)
+              Legion::Extensions::Llm::Fleet::ProviderResponder.call(
+                payload: payload,
+                provider_family: Mlx::PROVIDER_FAMILY,
+                provider_class: Mlx::Provider,
+                provider_instances: -> { Mlx.discover_instances },
+                delivery: delivery,
+                properties: properties
+              )
+            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.3.0'
+        VERSION = '0.3.5'
       end
     end
   end

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

@@ -16,17 +16,25 @@ module Legion
         PROVIDER_FAMILY = :mlx
 
         def self.default_settings
-          {
-            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: {}
-          }
+          ::Legion::Extensions::Llm.provider_settings(
+            family: PROVIDER_FAMILY,
+            instance: {
+              endpoint: 'http://localhost:8000',
+              tier: :local,
+              transport: :http,
+              credentials: { api_key: nil },
+              usage: { inference: true, embedding: true, image: false },
+              limits: { concurrency: 1 },
+              fleet: {
+                enabled: false,
+                respond_to_requests: false,
+                capabilities: %i[chat stream_chat embed],
+                lanes: [],
+                concurrency: 1,
+                queue_suffix: nil
+              }
+            }
+          )
         end
 
         def self.provider_class
@@ -55,18 +63,30 @@ module Legion
           return unless cfg.is_a?(Hash)
 
           cfg.each do |name, config|
-            instances[name.to_sym] = config.merge(tier: :direct)
+            instances[name.to_sym] = normalize_instance_config(config).merge(tier: :direct)
           end
         end
 
-        private_class_method :discover_local_instance, :discover_settings_instances
+        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 }
+          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
+
+        Legion::Extensions::Llm::Configuration.register_provider_options(Provider.configuration_options) if
+          Legion::Extensions::Llm::Configuration.respond_to?(:register_provider_options)
       end
     end
   end
 end
-
-Legion::Extensions::Llm::Configuration.register_provider_options(
-  Legion::Extensions::Llm::Mlx::Provider.configuration_options
-)
-
-Legion::Extensions::Llm::Mlx.register_discovered_instances

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-mlx
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.5
 platform: ruby
 authors:
 - LegionIO
@@ -51,20 +51,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.3.14
+- !ruby/object:Gem::Dependency
+  name: legion-transport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.14
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.14
 - !ruby/object:Gem::Dependency
   name: lex-llm
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.3
 description: MLX provider integration for the LegionIO LLM routing framework.
 email:
 - matthewdiverson@gmail.com
@@ -83,7 +97,9 @@ files:
 - README.md
 - lex-llm-mlx.gemspec
 - lib/legion/extensions/llm/mlx.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
 - lib/legion/extensions/llm/mlx/version.rb
 homepage: https://github.com/LegionIO/lex-llm-mlx
 licenses: