lex-ollama 0.3.4 → 0.3.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 978c53ff8a178c003a5bb593a934536c20b616500d80ea0624f97014f9a88213
-  data.tar.gz: d700e31e6f38fe2b9c6cac3da627d67ce1ccab9a75d3d6d741cdc04f5cc614bf
+  metadata.gz: 382e4c199c00f2ddd25fe9eea874e9e06340cefe26cc384e7e92a65504263241
+  data.tar.gz: cc45f497e285427b21b899ef1a282c5254fdf19c2d71ebb3a52457440b2892b3
 SHA512:
-  metadata.gz: 6f44dcfc98336bcd0d28e6985ed468f7676b156d5135ff642256120db59563e161d46615b9acab0e3cdac6b578144121d60a23efc17c31f6f6c686349519f076
-  data.tar.gz: b191eacce0844eb0be9b6b4b22f12969007b37f335da700f6ea6bd4936b22fd6aa2eec945dbdfbb419f5b1a9f9f1b0c9e15c004d772e18a1a98c059c133e83e8
+  metadata.gz: 867a24f1bb87195ef55dfeede679eafdf612c5eac98e25fd733dbebb75e79e3e210459694de8feeb068a7808cf0ce55a52a45f35b2254cebfba6af4eeb8c890e
+  data.tar.gz: 3e4b46cbba3ce845379f62209c7ced95879134294e171226b06263d76b1aaa196dc440c34f6c6a6ebbccc5059d796225555da385a3d2ec350ae157365943084e

data/.gitignore

@@ -7,6 +7,9 @@
 /spec/reports/
 /tmp/
 Gemfile.lock
+*.gem
+legionio.key
+/legionio/
 
 # rspec failure tracking
 .rspec_status

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.3.10] - 2026-04-28
+
+### Fixed
+- Require `lex-llm >= 0.1.6` so registry availability publishing always has the shared `RegistryEvent` envelope implementation it depends on.
+
+## [0.3.9] - 2026-04-28
+
+### Fixed
+- Declare explicit shared Legion JSON, logging, and settings dependencies used by the legacy Ollama extension during the LLM uplift transition.
+
+## [0.3.8] - 2026-04-28
+
+### Added
+- Publish nonblocking `llm.registry` availability, unavailability, heartbeat, and degraded events from `Actor::ModelWorker` using `lex-llm` `Legion::Extensions::Llm::Routing::RegistryEvent` envelopes when transport is available.
+- Add local `Transport::Exchanges::LlmRegistry` and `Transport::Messages::RegistryEvent` wrappers for `llm.registry` topic publishing without requiring a database.
+
+## [0.3.7] - 2026-04-28
+
+### Fixed
+- Declare the `legion-llm` runtime dependency required by the fleet exchange, response, and error classes inherited by lex-ollama fleet workers.
+
+## [0.3.6] - 2026-04-28
+
+### Added
+- `Actor::ModelWorker` can now bind opt-in exact offering lanes compatible with legion-llm's `llm.fleet.offering.<instance>.<model>.<operation>` routing style while preserving the existing shared `llm.fleet.*` lanes
+- `legion.ollama.fleet.offering_lanes` settings default to disabled with no instance id, so existing shared-lane fleet workers keep their current behavior unless exact offering lanes are explicitly enabled
+
+## [0.3.5] - 2026-04-28
+
+### Added
+- Fleet model workers now bind transient classic queues to shared `llm.fleet` model lanes, with configurable consumer priority, queue expiration, and message TTL.
+- Subscription entries can provide a context window so inference workers bind lanes like `llm.fleet.inference.qwen3-5-27b.ctx32768`.
+
+### Changed
+- `Actor::ModelWorker` now defaults endpoint fleet workers to explicit `basic_get` polling with a process-wide lane lock so local one-model-at-a-time devices do not reserve messages from multiple model queues; GPU/datacenter workers can opt back into RabbitMQ subscriptions with `legion.ollama.fleet.scheduler: :subscription`
+- Fleet worker queue names and routing keys now use shared `llm.fleet.*` lanes (`llm.fleet.embed.<model>` and `llm.fleet.inference.<model>.ctx<context>`) instead of legacy `llm.request.ollama.*` keys
+- `Ollama.build_actors` now orders generated model workers with embeddings first, then inference/chat workers from smallest to largest configured context window
+
 ## [0.3.4] - 2026-04-24
 
 ### Fixed

data/Gemfile

@@ -3,6 +3,12 @@
 source 'https://rubygems.org'
 gemspec
 
+legion_llm_path = File.expand_path('../../legion-llm', __dir__)
+gem 'legion-llm', path: legion_llm_path if Dir.exist?(legion_llm_path)
+
+lex_llm_path = File.expand_path('../lex-llm', __dir__)
+gem 'lex-llm', path: lex_llm_path if Dir.exist?(lex_llm_path)
+
 group :test do
   gem 'rake'
   gem 'rspec'

data/README.md

@@ -49,11 +49,19 @@ gem install lex-ollama
 - `handle_request` - Dispatch inbound fleet AMQP messages to the appropriate runner (chat/embed/generate)
 
 When `Legion::Extensions::Core` is present, lex-ollama subscribes to model-scoped queues on the
-`llm.request` topic exchange, accepting routed LLM inference work from other Legion fleet members.
+`llm.fleet` topic exchange, accepting routed LLM inference work from other Legion fleet members.
 
-Each configured `(type, model)` pair gets its own auto-delete queue with routing key
-`llm.request.ollama.<type>.<model>`. Multiple nodes serving the same model compete fairly
-via RabbitMQ round-robin with consumer priority.
+Each configured `(type, model)` pair gets its own durable quorum lane queue. Shared lanes use
+`llm.fleet.embed.<model>` for embeddings and `llm.fleet.inference.<model>.ctx<context>` for
+generation/chat subscriptions with a configured context window. Endpoint workers default to
+explicit `basic_get` polling with a process-wide lane lock, so local one-model-at-a-time
+devices do not reserve work from multiple model queues. GPU or datacenter workers can opt into
+RabbitMQ consumer subscriptions with `legion.ollama.fleet.scheduler: :subscription`.
+
+When offering lanes are enabled, workers also bind exact `legion-llm` compatible lanes in the
+form `llm.fleet.offering.<instance>.<model>.<operation>`. Workers publish nonblocking
+availability, heartbeat, degraded, and unavailable events to `llm.registry` when the transport
+runtime is loaded.
 
 ```yaml
 legion:
@@ -67,12 +75,29 @@ legion:
       - "qwen3.5:4b"
       - "nomic-embed-text:latest"
     fleet:
-      consumer_priority: 10        # H100: 10, Mac Studio: 5, MacBook: 1
+      scheduler: basic_get
+      consumer_priority: 10
+      queue_expires_ms: 60000
+      message_ttl_ms: 120000
+      queue_max_length: 100
+      delivery_limit: 3
+      consumer_ack_timeout_ms: 300000
+      endpoint:
+        enabled: false
+        empty_lane_backoff_ms: 250
+        idle_backoff_ms: 1000
+        max_consecutive_pulls_per_lane: 0
+      offering_lanes:
+        enabled: false
+        instance_id: "macbook-m4"
+      registry:
+        heartbeat_interval_seconds: 30
     subscriptions:
       - type: embed
         model: nomic-embed-text
       - type: chat
         model: "qwen3.5:27b"
+        context_window: 32768
 ```
 
 **Auto-provisioning**: When `s3` and `default_models` are configured, the `ModelSync` actor
@@ -163,7 +188,7 @@ result[:usage]  # => { input_tokens: 1, output_tokens: 5, total_duration: ..., .
 
 ## Version
 
-0.3.3
+0.3.10
 
 ## License
 

data/lex-ollama.gemspec

@@ -27,5 +27,10 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'faraday', '>= 2.0'
+  spec.add_dependency 'legion-json', '>= 1.2.1'
+  spec.add_dependency 'legion-llm', '>= 0.8.32'
+  spec.add_dependency 'legion-logging', '>= 1.3.2'
+  spec.add_dependency 'legion-settings', '>= 1.3.14'
+  spec.add_dependency 'lex-llm', '>= 0.1.6'
   spec.add_dependency 'lex-s3', '>= 0.2'
 end

data/lib/legion/extensions/ollama/actors/endpoint_puller.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Ollama
+      module Actor
+        # Polls configured fleet queues with basic_get so endpoint machines choose
+        # when they are ready for work instead of holding prefetched messages.
+        class EndpointPuller < Legion::Extensions::Actors::Every
+          def runner_class
+            self.class
+          end
+
+          def runner_function
+            'action'
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+
+          def enabled?
+            fleet_scheduler == :basic_get && endpoint_enabled? && subscriptions.any?
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true)
+            false
+          end
+
+          def time
+            (setting_value(endpoint_settings, :idle_backoff_ms) || 1_000).to_f / 1000
+          end
+
+          def action
+            return unless enabled?
+
+            now = monotonic_time
+            ordered_subscriptions.each do |sub|
+              next if lane_backed_off?(sub, now)
+
+              pulled = drain_lane(sub)
+              mark_lane_empty(sub) if pulled.zero?
+            end
+          end
+
+          def ordered_subscriptions
+            subscriptions.sort_by do |sub|
+              type = sub[:type].to_s
+              [embed_type?(type) ? 0 : 1, context_limit(sub), sub[:model].to_s]
+            end
+          end
+
+          def drain_lane(subscription)
+            pulls = 0
+            queue = queue_for(subscription)
+
+            loop do
+              break if max_consecutive_pulls_per_lane.positive? && pulls >= max_consecutive_pulls_per_lane
+              break unless pull_one(queue, subscription)
+
+              pulls += 1
+            end
+            pulls
+          end
+
+          def pull_one(queue, subscription)
+            delivery_info, metadata, payload = queue.pop(manual_ack: true)
+            return false unless delivery_info
+
+            message = process_payload(payload, metadata, delivery_info, subscription)
+            Legion::Extensions::Ollama::Runners::Fleet.handle_request(**message)
+            queue.acknowledge(delivery_info.delivery_tag)
+            true
+          rescue StandardError => e
+            handle_exception(e, lex: lex_name, routing_key: delivery_info&.routing_key)
+            queue.reject(delivery_info.delivery_tag, requeue: false) if delivery_info
+            true
+          end
+
+          def queue_for(subscription)
+            @queues ||= {}
+            @queues[lane_key(subscription)] ||= ModelWorker.queue_class_for(
+              request_type:   subscription[:type],
+              model:          subscription[:model],
+              context_window: finite_context_limit(subscription),
+              queue_config:   queue_config
+            ).new
+          end
+
+          def process_payload(payload, metadata, delivery_info, subscription)
+            message = decode_payload(payload, metadata)
+            message = message.merge(metadata.headers.transform_keys(&:to_sym)) if metadata&.headers
+            message[:routing_key] = delivery_info.routing_key if delivery_info.respond_to?(:routing_key)
+            message[:request_type] ||= subscription[:type].to_s
+            message[:model] ||= subscription[:model].to_s
+            message[:message_context] ||= {}
+            message
+          end
+
+          def decode_payload(payload, metadata)
+            decoded = if metadata&.content_encoding == 'encrypted/cs'
+                        Legion::Crypt.decrypt(payload, metadata_header(metadata, :iv))
+                      elsif metadata&.content_encoding == 'encrypted/pk'
+                        Legion::Crypt.decrypt_from_keypair(metadata_header(metadata, :public_key), payload)
+                      else
+                        payload
+                      end
+
+            if metadata&.content_type == 'application/json'
+              Legion::JSON.load(decoded)
+            else
+              { value: decoded }
+            end
+          end
+
+          def subscriptions
+            configured = setting_value(settings, :subscriptions)
+            return [] unless configured.is_a?(Array)
+
+            configured.filter_map do |sub|
+              next unless sub.is_a?(Hash)
+
+              normalized = sub.transform_keys(&:to_sym)
+              next unless normalized[:type] && normalized[:model]
+
+              normalized
+            end
+          end
+
+          def queue_config
+            {
+              queue_expires_ms:        nested_setting(settings, :fleet, :queue_expires_ms),
+              message_ttl_ms:          nested_setting(settings, :fleet, :message_ttl_ms),
+              queue_max_length:        nested_setting(settings, :fleet, :queue_max_length),
+              delivery_limit:          nested_setting(settings, :fleet, :delivery_limit),
+              consumer_ack_timeout_ms: nested_setting(settings, :fleet, :consumer_ack_timeout_ms)
+            }.compact
+          end
+
+          def endpoint_settings
+            nested_setting(settings, :fleet, :endpoint) || {}
+          end
+
+          def endpoint_enabled?
+            setting_value(endpoint_settings, :enabled) == true
+          end
+
+          def max_consecutive_pulls_per_lane
+            setting_value(endpoint_settings, :max_consecutive_pulls_per_lane) || 0
+          end
+
+          def empty_lane_backoff_seconds
+            (setting_value(endpoint_settings, :empty_lane_backoff_ms) || 250).to_f / 1000
+          end
+
+          def lane_backed_off?(subscription, now)
+            (@empty_lanes ||= {}).fetch(lane_key(subscription), 0) > now
+          end
+
+          def mark_lane_empty(subscription)
+            (@empty_lanes ||= {})[lane_key(subscription)] = monotonic_time + empty_lane_backoff_seconds
+          end
+
+          def lane_key(subscription)
+            type = subscription[:type]
+            model = subscription[:model]
+            context = context_limit(subscription)
+            context.finite? ? "#{type}:#{model}:ctx#{context}" : "#{type}:#{model}"
+          end
+
+          def monotonic_time
+            Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          end
+
+          def fleet_scheduler
+            (nested_setting(settings, :fleet, :scheduler) || :basic_get).to_sym
+          end
+
+          def context_limit(subscription)
+            raw = setting_value(subscription, :max_context_size) ||
+                  setting_value(subscription, :context_window) ||
+                  setting_value(subscription, :max_input_tokens) ||
+                  setting_value(subscription, :context) ||
+                  setting_value(subscription, :ctx)
+            Integer(raw || Float::INFINITY)
+          rescue ArgumentError, TypeError, FloatDomainError
+            Float::INFINITY
+          end
+
+          def finite_context_limit(subscription)
+            context = context_limit(subscription)
+            context.finite? ? context : nil
+          end
+
+          def embed_type?(type)
+            %w[embed embedding embeddings].include?(type)
+          end
+
+          def metadata_header(metadata, key)
+            setting_value(metadata&.headers || {}, key)
+          end
+
+          def nested_setting(hash, *keys)
+            keys.reduce(hash) do |current, key|
+              return nil unless current.respond_to?(:key?)
+
+              setting_value(current, key)
+            end
+          end
+
+          def setting_value(hash, key)
+            return nil unless hash.respond_to?(:key?)
+
+            string_key = key.to_s
+            return hash[string_key] if hash.key?(string_key)
+
+            hash[key] if hash.key?(key)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/ollama/actors/model_worker.rb

@@ -4,8 +4,12 @@ module Legion
   module Extensions
     module Ollama
       module Actor
-        # Subscription actor that listens on a model-scoped queue and forwards
+        # Fleet actor that listens on a model-scoped queue and forwards
         # inbound LLM request messages to Runners::Fleet#handle_request.
+        # Endpoint workers default to explicit basic_get polling so a local
+        # one-model-at-a-time device does not reserve messages from every lane.
+        # Set legion.ollama.fleet.scheduler to :subscription for GPU/datacenter
+        # workers that should use RabbitMQ consumer priority and prefetch.
         #
         # One instance is created per (request_type, model) entry in settings:
         #
@@ -19,15 +23,27 @@ module Legion
         #         - type: chat
         #           model: "qwen3.5:27b"
         #
-        # The queue name and routing key both follow the schema:
-        #   llm.request.ollama.<type>.<model>
-        # where model colons are converted to dots (AMQP topic word separator).
+        # Queue names and routing keys follow the shared fleet lane schema:
+        #   llm.fleet.embed.<model-slug>
+        #   llm.fleet.inference.<model-slug>.ctx<context-window>
+        # or, when explicitly enabled, exact offering lanes:
+        #   llm.fleet.offering.<instance>.<model-slug>.<operation>
         class ModelWorker < Legion::Extensions::Actors::Subscription
-          attr_reader :request_type, :model_name
+          POLLING_SCHEDULERS = %i[basic_get poll polling].freeze
+          SUBSCRIPTION_SCHEDULERS = %i[subscribe subscription basic_consume consumer].freeze
+          POLL_LOCK = Mutex.new
+          REGISTRY_HEARTBEAT_INTERVAL = 30.0
 
-          def initialize(request_type:, model:, **)
+          attr_reader :request_type, :model_name, :context_window, :offering_instance_id
+
+          def initialize(request_type:, model:, context_window: nil, lane_style: :shared,
+                         offering_instance_id: nil, **)
             @request_type = request_type.to_s
-            @model_name   = model.to_s
+            @model_name = model.to_s
+            @context_window = normalize_context_window(context_window)
+            @lane_style = lane_style.to_s
+            @offering_instance_id = offering_instance_id&.to_s
+            @polling = false
             super(**)
           end
 
@@ -59,7 +75,27 @@ module Legion
           # Standard scale: GPU server = 10, Mac Studio = 5, developer laptop = 1.
           # Defaults to 0 (equal priority) if not configured.
           def consumer_priority
-            settings.dig(:fleet, :consumer_priority) || 0
+            setting_value(fleet_settings, :consumer_priority) || 0
+          end
+
+          def queue_expires_ms
+            setting_value(fleet_settings, :queue_expires_ms) || 60_000
+          end
+
+          def message_ttl_ms
+            setting_value(fleet_settings, :message_ttl_ms) || 120_000
+          end
+
+          def queue_max_length
+            setting_value(fleet_settings, :queue_max_length) || 100
+          end
+
+          def delivery_limit
+            setting_value(fleet_settings, :delivery_limit) || 3
+          end
+
+          def consumer_ack_timeout_ms
+            setting_value(fleet_settings, :consumer_ack_timeout_ms) || 300_000
           end
 
           # Subscribe options include x-priority argument so RabbitMQ can honour
@@ -73,44 +109,467 @@ module Legion
             base.merge(arguments: { 'x-priority' => consumer_priority })
           end
 
-          # Returns a queue CLASS (not instance) bound to the llm.request exchange
-          # with the routing key for this worker's (type, model) pair.
+          def prepare
+            return super unless endpoint_polling?
+
+            @queue = queue.new
+            @polling = true
+            log.info "[ModelWorker] prepared polling lane #{lane_key}" if defined?(log)
+          rescue StandardError => e
+            handle_exception(e, level: :fatal)
+          end
+
+          def activate
+            result = if endpoint_polling?
+                       @polling = true
+                       @poll_task = async.run_basic_get_loop
+                       log.info "[ModelWorker] activated polling lane #{lane_key}" if defined?(log)
+                       @poll_task
+                     else
+                       super
+                     end
+            publish_registry_event_async(:available)
+            start_registry_heartbeat
+            result
+          rescue StandardError => e
+            publish_registry_event_async(:degraded, error: e)
+            handle_exception(e, level: :fatal)
+          end
+
+          def cancel
+            @polling = false
+            stop_registry_heartbeat
+            publish_registry_event_async(:unavailable)
+            return true unless instance_variable_defined?(:@consumer) && @consumer
+
+            super
+          end
+
+          def endpoint_polling?
+            scheduler = fleet_scheduler
+            return true if POLLING_SCHEDULERS.include?(scheduler)
+            return false if SUBSCRIPTION_SCHEDULERS.include?(scheduler)
+
+            nested_setting(settings, :fleet, :endpoint, :enabled) == true
+          rescue StandardError
+            false
+          end
+
+          def lane_key
+            @lane_key ||= offering_lane? ? offering_lane_key : shared_lane_key
+          end
+          alias routing_key lane_key
+
+          def run_basic_get_loop
+            consecutive_pulls = 0
+            while @polling && !shutting_down?
+              pulled = POLL_LOCK.synchronize { pull_one_message }
+              consecutive_pulls = pulled ? consecutive_pulls + 1 : 0
+              sleep(pulled ? post_pull_backoff(consecutive_pulls) : empty_lane_backoff)
+            end
+          end
+
+          def pull_one_message
+            delivery_info, metadata, payload = @queue.pop(manual_ack: manual_ack)
+            return false unless delivery_info
+
+            handle_delivery(delivery_info, metadata, payload)
+            true
+          rescue StandardError => e
+            handle_exception(e)
+            reject_or_retry(delivery_info, metadata, payload) if manual_ack && delivery_info
+            true
+          end
+
+          # Returns a queue CLASS (not instance) bound to the llm.fleet exchange
+          # with the routing key for this worker's model lane.
           # The Subscription base class calls queue.new in initialize, so this must
           # return a class, not an instance.
           def queue
             @queue ||= build_queue_class
           end
 
+          def self.queue_class_for(request_type:, model:, context_window: nil, queue_config: {},
+                                   lane_style: :shared, offering_instance_id: nil)
+            worker = allocate
+            worker.instance_variable_set(:@request_type, request_type.to_s)
+            worker.instance_variable_set(:@model_name, model.to_s)
+            worker.instance_variable_set(:@context_window, context_window&.to_i)
+            worker.instance_variable_set(:@lane_style, lane_style.to_s)
+            worker.instance_variable_set(:@offering_instance_id, offering_instance_id&.to_s)
+            worker.send(:build_queue_class, queue_config)
+          end
+
+          def self.fallback_queue_options(settings)
+            {
+              durable:     true,
+              auto_delete: false,
+              arguments:   {
+                'x-queue-type'           => 'quorum',
+                'x-queue-leader-locator' => 'balanced',
+                'x-expires'              => settings.fetch(:queue_expires_ms),
+                'x-message-ttl'          => settings.fetch(:message_ttl_ms),
+                'x-overflow'             => 'reject-publish',
+                'x-max-length'           => settings.fetch(:queue_max_length),
+                'x-delivery-limit'       => settings.fetch(:delivery_limit),
+                'x-consumer-timeout'     => settings.fetch(:consumer_ack_timeout_ms)
+              }
+            }
+          end
+
           # Enrich every inbound message with the worker's own request_type and model
           # so Runners::Fleet#handle_request always has them, even if the sender omitted
           # them. Also defaults message_context to {} if absent.
           def process_message(payload, metadata, delivery_info)
             msg = super
-            msg[:request_type]    ||= @request_type
-            msg[:model]           ||= @model_name
+            msg[:request_type] ||= @request_type
+            msg[:model] ||= @model_name
             msg[:message_context] ||= {}
             msg
           end
 
           private
 
-          def build_queue_class
-            sanitised_model = @model_name.tr(':', '.')
-            routing_key     = "llm.request.ollama.#{@request_type}.#{sanitised_model}"
-            exchange_class  = Transport::Exchanges::LlmRequest
+          def start_registry_heartbeat
+            return unless registry_publishing_available?
+            return if @registry_heartbeat_thread&.alive?
 
-            Class.new(Legion::Transport::Queue) do
-              define_method(:queue_name) { routing_key }
-              define_method(:queue_options) do
-                { durable: false, auto_delete: true, arguments: { 'x-max-priority' => 10 } }
+            @registry_heartbeat_running = true
+            @registry_heartbeat_thread = Thread.new do
+              Thread.current.abort_on_exception = false
+              while @registry_heartbeat_running && !shutting_down?
+                sleep registry_heartbeat_interval
+                publish_registry_event(:heartbeat) if @registry_heartbeat_running && !shutting_down?
               end
+            rescue StandardError => e
+              log_registry_publish_failure(e, level: :debug)
+            end
+          rescue StandardError => e
+            log_registry_publish_failure(e, level: :debug)
+          end
+
+          def stop_registry_heartbeat
+            @registry_heartbeat_running = false
+            @registry_heartbeat_thread&.kill if @registry_heartbeat_thread&.alive?
+          end
+
+          def registry_heartbeat_interval
+            configured = nested_setting(settings, :fleet, :registry, :heartbeat_interval_seconds) ||
+                         nested_setting(settings, :fleet, :registry_heartbeat_interval_seconds)
+            interval = configured.nil? ? REGISTRY_HEARTBEAT_INTERVAL : Float(configured)
+            interval.positive? ? interval : REGISTRY_HEARTBEAT_INTERVAL
+          rescue StandardError
+            REGISTRY_HEARTBEAT_INTERVAL
+          end
+
+          def publish_registry_event_async(kind, error: nil)
+            return unless registry_publishing_available?
+
+            Thread.new do
+              Thread.current.abort_on_exception = false
+              publish_registry_event(kind, error: error)
+            rescue StandardError => e
+              log_registry_publish_failure(e, level: :debug)
+            end
+          rescue StandardError => e
+            log_registry_publish_failure(e, level: :debug)
+          end
+
+          def publish_registry_event(kind, error: nil)
+            event = registry_event_for(kind, error: error)
+            Transport::Messages::RegistryEvent.new(event: event).publish(spool: false)
+          rescue StandardError => e
+            log_registry_publish_failure(e)
+          end
+
+          def registry_event_for(kind, error: nil)
+            registry_event_class.public_send(
+              registry_event_method(kind),
+              registry_offering,
+              runtime:  registry_runtime,
+              capacity: registry_capacity,
+              health:   registry_health(kind, error: error),
+              lane:     lane_key,
+              metadata: registry_metadata
+            )
+          end
+
+          def registry_event_method(kind)
+            case kind.to_sym
+            when :available then :available
+            when :unavailable then :unavailable
+            when :heartbeat then :heartbeat
+            else :degraded
+            end
+          end
+
+          def registry_offering
+            limits = {}
+            limits[:context_window] = @context_window if @context_window
+            {
+              provider_family:   :ollama,
+              provider_instance: registry_provider_instance,
+              transport:         :rabbitmq,
+              model:             @model_name,
+              usage_type:        registry_usage_type,
+              capabilities:      registry_capabilities,
+              limits:            limits,
+              routing_metadata:  { lane: lane_key },
+              metadata:          { lex: :ollama, lane_style: @lane_style || 'shared' }
+            }
+          end
+
+          def registry_runtime
+            {
+              node:      registry_provider_instance,
+              scheduler: fleet_scheduler,
+              polling:   endpoint_polling?
+            }
+          end
+
+          def registry_capacity
+            {
+              concurrency:       1,
+              consumer_priority: consumer_priority,
+              queue_max_length:  queue_max_length
+            }
+          end
+
+          def registry_health(kind, error: nil)
+            health = {
+              ready:  %i[available heartbeat].include?(kind.to_sym),
+              status: registry_health_status(kind)
+            }
+            health[:error_class] = error.class.name if error
+            health[:error] = error.message if error
+            health
+          end
+
+          def registry_health_status(kind)
+            case kind.to_sym
+            when :available, :heartbeat then :available
+            when :unavailable then :unavailable
+            else :degraded
+            end
+          end
+
+          def registry_metadata
+            {
+              extension:    :lex_ollama,
+              request_type: @request_type,
+              lane_kind:    lane_kind
+            }
+          end
+
+          def registry_usage_type
+            lane_kind == 'embed' ? :embedding : :inference
+          end
+
+          def registry_capabilities
+            return %i[embedding] if lane_kind == 'embed'
+            return %i[completion] if @request_type == 'generate'
+
+            %i[chat]
+          end
+
+          def registry_provider_instance
+            @offering_instance_id || node_identity
+          end
+
+          def node_identity
+            return Legion::Settings.dig(:node, :canonical_name).to_s if defined?(Legion::Settings) &&
+                                                                        Legion::Settings.dig(:node, :canonical_name)
+
+            'unknown'
+          rescue StandardError
+            'unknown'
+          end
+
+          def registry_publishing_available?
+            defined?(::Legion::Transport) &&
+              defined?(::Legion::Extensions::Llm::Routing::RegistryEvent) &&
+              defined?(Transport::Messages::RegistryEvent)
+          end
+
+          def registry_event_class
+            ::Legion::Extensions::Llm::Routing::RegistryEvent
+          end
+
+          def log_registry_publish_failure(error, level: :warn)
+            message = "[ModelWorker] llm.registry publish failed lane=#{lane_key}: #{error.class}: #{error.message}"
+            if defined?(log) && log.respond_to?(level)
+              log.public_send(level, message)
+            elsif defined?(log) && log.respond_to?(:debug)
+              log.debug(message)
+            end
+          rescue StandardError
+            nil
+          end
+
+          def build_queue_class(queue_config = {})
+            lane_key = self.lane_key
+            exchange_class = Transport::Exchanges::LlmRequest
+            queue_settings = {
+              queue_expires_ms:        queue_expires_ms,
+              message_ttl_ms:          message_ttl_ms,
+              queue_max_length:        queue_max_length,
+              delivery_limit:          delivery_limit,
+              consumer_ack_timeout_ms: consumer_ack_timeout_ms
+            }.merge((queue_config || {}).compact)
+
+            if defined?(::Legion::Extensions::Llm::Transport::FleetLane)
+              return ::Legion::Extensions::Llm::Transport::FleetLane.build_queue_class(
+                queue_name:       lane_key,
+                exchange_class:   exchange_class,
+                routing_key:      lane_key,
+                base_queue_class: Legion::Transport::Queue,
+                settings:         queue_settings
+              )
+            end
+
+            queue_options = self.class.fallback_queue_options(queue_settings)
+
+            Class.new(Legion::Transport::Queue) do
+              define_method(:queue_name) { lane_key }
+              define_method(:queue_options) { queue_options }
               define_method(:dlx_enabled) { false }
               define_method(:initialize) do
                 super()
-                bind(exchange_class.new, routing_key: routing_key)
+                bind(exchange_class.new, routing_key: lane_key)
               end
             end
           end
+
+          def handle_delivery(delivery_info, metadata, payload)
+            message = process_message(payload, metadata, delivery_info)
+            fn = find_function(message)
+            log.debug "[ModelWorker] basic_get message received: #{lex_name}/#{fn}" if defined?(log)
+
+            affinity_result = check_region_affinity(message)
+            if affinity_result == :reject
+              log.warn '[ModelWorker] nack: region affinity mismatch' if defined?(log)
+              @queue.reject(delivery_info.delivery_tag) if manual_ack
+              return
+            end
+
+            record_cross_region_metric(message) if affinity_result == :remote
+
+            if use_runner?
+              dispatch_runner(message, runner_class, fn, check_subtask?, generate_task?)
+            else
+              runner_class.send(fn, **message)
+            end
+            @queue.acknowledge(delivery_info.delivery_tag) if manual_ack
+          end
+
+          def fleet_settings
+            setting_value(settings, :fleet) || {}
+          rescue NameError
+            {}
+          end
+
+          def fleet_scheduler
+            (setting_value(fleet_settings, :scheduler) || :basic_get).to_sym
+          end
+
+          def setting_value(hash, key)
+            return nil unless hash.respond_to?(:key?)
+
+            string_key = key.to_s
+            return hash[string_key] if hash.key?(string_key)
+
+            hash[key] if hash.key?(key)
+          end
+
+          def nested_setting(hash, *keys)
+            keys.reduce(hash) do |current, key|
+              return nil unless current.respond_to?(:key?)
+
+              setting_value(current, key)
+            end
+          end
+
+          def lane_kind
+            %w[embed embedding embeddings].include?(@request_type) ? 'embed' : 'inference'
+          end
+
+          def sanitized_model
+            sanitize_segment(@model_name)
+          end
+
+          def offering_lane?
+            @lane_style == 'offering'
+          end
+
+          def shared_lane_key
+            parts = ['llm.fleet', lane_kind, sanitized_model]
+            parts << "ctx#{@context_window}" if lane_kind == 'inference' && @context_window
+            parts.join('.')
+          end
+
+          def offering_lane_key
+            [
+              'llm',
+              'fleet',
+              'offering',
+              public_segment(:offering_instance_id, @offering_instance_id),
+              sanitized_model,
+              lane_kind
+            ].join('.')
+          end
+
+          def sanitize_segment(value)
+            value.to_s.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/\A-+|-+\z/, '').squeeze('-')
+          end
+
+          def public_segment(label, value)
+            segment = sanitize_segment(value)
+            raise ArgumentError, "#{label} is empty after sanitization" if segment.empty?
+            raise ArgumentError, "#{label} exceeds 64 characters" if segment.length > 64
+
+            segment
+          end
+
+          def normalize_context_window(value)
+            return nil if value.nil? || value.to_s.empty?
+
+            Integer(value)
+          rescue ArgumentError, TypeError
+            nil
+          end
+
+          def empty_lane_backoff
+            milliseconds = nested_setting(settings, :fleet, :endpoint, :empty_lane_backoff_ms) || 250
+            milliseconds.to_f / 1000.0
+          rescue StandardError
+            0.25
+          end
+
+          def idle_backoff
+            milliseconds = nested_setting(settings, :fleet, :endpoint, :idle_backoff_ms) || 1_000
+            milliseconds.to_f / 1000.0
+          rescue StandardError
+            1.0
+          end
+
+          def max_consecutive_pulls_per_lane
+            Integer(nested_setting(settings, :fleet, :endpoint, :max_consecutive_pulls_per_lane) || 0)
+          rescue StandardError
+            0
+          end
+
+          def post_pull_backoff(consecutive_pulls)
+            max_pulls = max_consecutive_pulls_per_lane
+            return 0 if max_pulls.zero? || consecutive_pulls < max_pulls
+
+            idle_backoff
+          end
+
+          def shutting_down?
+            defined?(Legion::Settings) && Legion::Settings.dig(:client, :shutting_down)
+          rescue StandardError
+            false
+          end
         end
       end
     end

data/lib/legion/extensions/ollama/transport/exchanges/llm_registry.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Ollama
+      module Transport
+        module Exchanges
+          # Topic exchange for provider availability events consumed by LLM routing registries.
+          class LlmRegistry < Legion::Transport::Exchange
+            def exchange_name
+              'llm.registry'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/ollama/transport/messages/registry_event.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/ollama/transport/exchanges/llm_registry'
+
+module Legion
+  module Extensions
+    module Ollama
+      module Transport
+        module Messages
+          # Publishes lex-llm RegistryEvent envelopes to the llm.registry exchange.
+          class RegistryEvent < Legion::Transport::Message
+            def initialize(event:, **options)
+              envelope = event.to_h
+              super(**envelope.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
+              'lex-ollama'
+            end
+
+            def persistent
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/ollama/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Ollama
-      VERSION = '0.3.4'
+      VERSION = '0.3.10'
     end
   end
 end

data/lib/legion/extensions/ollama.rb

@@ -14,13 +14,22 @@ require 'legion/extensions/ollama/runners/version'
 require 'legion/extensions/ollama/runners/fleet'
 require 'legion/extensions/ollama/client'
 
+begin
+  require 'legion/extensions/llm'
+rescue LoadError
+  nil
+end
+
 # Fleet transport and actor wiring — only loaded when Legion::Extensions::Core is present
 # so the gem still works as a standalone HTTP client without any AMQP runtime.
 if Legion::Extensions.const_defined?(:Core, false)
   require 'legion/extensions/ollama/transport/exchanges/llm_request'
+  require 'legion/extensions/ollama/transport/exchanges/llm_registry'
   require 'legion/extensions/ollama/transport/messages/llm_response'
+  require 'legion/extensions/ollama/transport/messages/registry_event'
   require 'legion/extensions/ollama/transport'
   require 'legion/extensions/ollama/actors/model_worker'
+  require 'legion/extensions/ollama/actors/endpoint_puller'
   require 'legion/extensions/ollama/actors/model_sync'
 end
 
@@ -32,7 +41,26 @@ module Legion
       def self.default_settings
         {
           s3:    {},
-          fleet: {}
+          fleet: {
+            consumer_priority:       0,
+            scheduler:               :basic_get,
+            queue_expires_ms:        60_000,
+            message_ttl_ms:          120_000,
+            queue_max_length:        100,
+            delivery_limit:          3,
+            consumer_ack_timeout_ms: 300_000,
+            endpoint:                {
+              enabled:                        false,
+              empty_lane_backoff_ms:          250,
+              idle_backoff_ms:                1_000,
+              max_consecutive_pulls_per_lane: 0,
+              accept_when:                    []
+            },
+            offering_lanes:          {
+              enabled:     false,
+              instance_id: nil
+            }
+          }
         }
       end
 
@@ -43,26 +71,149 @@ module Legion
         super
         @actors.delete(:model_worker)
 
-        subs = settings[:subscriptions]
+        subs = setting_value(settings, :subscriptions)
+        valid_subscriptions = valid_fleet_subscriptions(subs)
+        endpoint_configured = fleet_scheduler == :basic_get &&
+                              nested_setting(settings, :fleet, :endpoint, :enabled) == true &&
+                              valid_subscriptions.any?
+        @actors.delete(:endpoint_puller) unless endpoint_configured
+
         return unless subs.is_a?(Array)
+        return if fleet_scheduler == :basic_get
 
-        subs.each do |sub|
-          request_type = sub[:type]&.to_s
-          model        = sub[:model]&.to_s
+        sorted_subscriptions(subs).each do |sub|
+          request_type = setting_value(sub, :type)&.to_s
+          model = setting_value(sub, :model)&.to_s
+          context_window = context_window_for(sub)
           next unless request_type && model
 
-          actor_name   = :"model_worker_#{request_type}_#{model.tr(':.', '__')}"
-          worker_class = Class.new(Legion::Extensions::Ollama::Actor::ModelWorker) do
-            define_method(:initialize) { super(request_type: request_type, model: model) }
+          register_model_worker(request_type: request_type, model: model, context_window: context_window)
+
+          offering_instance_id = offering_instance_for(sub)
+          next unless offering_instance_id
+
+          register_model_worker(request_type: request_type, model: model, context_window: context_window,
+                                lane_style: :offering, offering_instance_id: offering_instance_id)
+        end
+      end
+
+      def self.sorted_subscriptions(subscriptions)
+        subscriptions.sort_by do |sub|
+          type = setting_value(sub, :type).to_s
+          [
+            type == 'embed' ? 0 : 1,
+            context_window_for(sub) || Float::INFINITY,
+            setting_value(sub, :model).to_s
+          ]
+        end
+      end
+
+      def self.context_window_for(subscription)
+        limits = setting_value(subscription, :limits) || {}
+        raw = setting_value(subscription, :context_window) ||
+              setting_value(subscription, :max_context) ||
+              setting_value(subscription, :max_input_tokens) ||
+              setting_value(limits, :context_window) ||
+              setting_value(limits, :max_input_tokens)
+        return nil if raw.nil? || raw.to_s.empty?
+
+        Integer(raw)
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def self.register_model_worker(request_type:, model:, context_window:, lane_style: :shared,
+                                     offering_instance_id: nil)
+        actor_name = model_worker_actor_name(
+          request_type:         request_type,
+          model:                model,
+          lane_style:           lane_style,
+          offering_instance_id: offering_instance_id
+        )
+        worker_class = Class.new(Legion::Extensions::Ollama::Actor::ModelWorker) do
+          define_method(:initialize) do
+            super(
+              request_type:         request_type,
+              model:                model,
+              context_window:       context_window,
+              lane_style:           lane_style,
+              offering_instance_id: offering_instance_id
+            )
           end
+        end
 
-          @actors[actor_name] = {
-            extension:      'lex-ollama',
-            extension_name: :ollama,
-            actor_name:     actor_name,
-            actor_class:    worker_class,
-            type:           'literal'
-          }
+        @actors[actor_name] = {
+          extension:      'lex-ollama',
+          extension_name: :ollama,
+          actor_name:     actor_name,
+          actor_class:    worker_class,
+          type:           'literal'
+        }
+      end
+
+      def self.offering_instance_for(subscription)
+        return nil unless offering_lanes_enabled?
+
+        raw = setting_value(subscription, :offering_instance_id) ||
+              setting_value(subscription, :provider_instance) ||
+              setting_value(subscription, :instance_id) ||
+              fleet_offering_lane_setting(:instance_id) ||
+              fleet_offering_lane_setting(:provider_instance) ||
+              fleet_offering_lane_setting(:offering_instance_id)
+        normalized = raw&.to_s
+        return nil if normalized.nil? || normalized.empty?
+
+        normalized
+      end
+
+      def self.offering_lanes_enabled?
+        fleet_offering_lane_setting(:enabled) == true
+      rescue StandardError
+        false
+      end
+
+      def self.fleet_offering_lane_setting(key)
+        offering_lanes = nested_setting(settings, :fleet, :offering_lanes) || {}
+        setting_value(offering_lanes, key)
+      end
+
+      def self.model_worker_actor_name(request_type:, model:, lane_style:, offering_instance_id:)
+        return :"model_worker_#{request_type}_#{model.tr(':.', '__')}" if lane_style.to_s == 'shared'
+
+        suffix = [lane_style, request_type, model, offering_instance_id].compact.join('_')
+        :"model_worker_#{actor_suffix(suffix)}"
+      end
+
+      def self.actor_suffix(value)
+        value.to_s.downcase.gsub(/[^a-z0-9]+/, '_').gsub(/\A_+|_+\z/, '')
+      end
+
+      def self.fleet_scheduler
+        (nested_setting(settings, :fleet, :scheduler) || :basic_get).to_sym
+      end
+
+      def self.valid_fleet_subscriptions(subscriptions)
+        return [] unless subscriptions.is_a?(Array)
+
+        subscriptions.select do |sub|
+          setting_value(sub, :type) && setting_value(sub, :model)
+        end
+      end
+
+      def self.setting_value(hash, key)
+        return nil unless hash.respond_to?(:key?)
+
+        string_key = key.to_s
+        return hash[string_key] if hash.key?(string_key)
+
+        hash[key] if hash.key?(key)
+      end
+
+      def self.nested_setting(hash, *keys)
+        keys.reduce(hash) do |current, key|
+          return nil unless current.respond_to?(:key?)
+
+          setting_value(current, key)
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-ollama
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.10
 platform: ruby
 authors:
 - Esity
@@ -23,6 +23,76 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: legion-json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: legion-llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.32
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.8.32
+- !ruby/object:Gem::Dependency
+  name: legion-logging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+- !ruby/object:Gem::Dependency
+  name: legion-settings
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.14
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.14
+- !ruby/object:Gem::Dependency
+  name: lex-llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.6
 - !ruby/object:Gem::Dependency
   name: lex-s3
   requirement: !ruby/object:Gem::Requirement
@@ -56,6 +126,7 @@ files:
 - README.md
 - lex-ollama.gemspec
 - lib/legion/extensions/ollama.rb
+- lib/legion/extensions/ollama/actors/endpoint_puller.rb
 - lib/legion/extensions/ollama/actors/model_sync.rb
 - lib/legion/extensions/ollama/actors/model_worker.rb
 - lib/legion/extensions/ollama/client.rb
@@ -71,8 +142,10 @@ files:
 - lib/legion/extensions/ollama/runners/s3_models.rb
 - lib/legion/extensions/ollama/runners/version.rb
 - lib/legion/extensions/ollama/transport.rb
+- lib/legion/extensions/ollama/transport/exchanges/llm_registry.rb
 - lib/legion/extensions/ollama/transport/exchanges/llm_request.rb
 - lib/legion/extensions/ollama/transport/messages/llm_response.rb
+- lib/legion/extensions/ollama/transport/messages/registry_event.rb
 - lib/legion/extensions/ollama/version.rb
 homepage: https://github.com/LegionIO/lex-ollama
 licenses: