lex-ollama 0.3.2 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8657f3e11e11fcd2ee34e12317bf7698bcfea1e907006c76f9a07326996c7a69
-  data.tar.gz: d1c1bbb05dc6a3a0071b4474a45a074b0d4929cd4b48b7488b5aa10539a9a6ee
+  metadata.gz: 978c53ff8a178c003a5bb593a934536c20b616500d80ea0624f97014f9a88213
+  data.tar.gz: d700e31e6f38fe2b9c6cac3da627d67ce1ccab9a75d3d6d741cdc04f5cc614bf
 SHA512:
-  metadata.gz: e2a8622a2914cdfbc04b365d1ca7a9e8d35b4daa656931fd23a6e010b25b5a8ed6699246bffdbe0bfe064757ad26cad8f3664fe8c1dd2d1c606220dc932af45f
-  data.tar.gz: ea975e9ac1c89621d41c274b6040bb92760672f9d4a2db223ea6c08371f7ed8e8a2dc810417b9b5b2beb9ce30fccb64544f24c11ae815422e5b99f5a43a48517
+  metadata.gz: 6f44dcfc98336bcd0d28e6985ed468f7676b156d5135ff642256120db59563e161d46615b9acab0e3cdac6b578144121d60a23efc17c31f6f6c686349519f076
+  data.tar.gz: b191eacce0844eb0be9b6b4b22f12969007b37f335da700f6ea6bd4936b22fd6aa2eec945dbdfbb419f5b1a9f9f1b0c9e15c004d772e18a1a98c059c133e83e8

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.3.4] - 2026-04-24
+
+### Fixed
+- `Ollama.build_actors` and `Ollama.default_settings` were absent from the installed 0.3.3 gem (gem was packaged before `bafb124` landed) — `Actor::ModelWorker` (requires `request_type:` and `model:` kwargs) was reaching the subscription actor pool with no zero-arg initializer, raising `ArgumentError: missing keywords: :request_type, :model` on every boot when running under the Homebrew legionio install
+
+## [0.3.3] - 2026-04-16
+
+### Added
+- `Actor::ModelSync` — once actor; runs 5s after extension load; reads `legion.ollama.default_models` and `legion.ollama.s3` from settings; calls `import_from_s3` for any configured model not already present on disk; no-op if either setting is absent
+
+### Fixed
+- `Transport::Queues::ModelRequest` deleted — the framework auto-discovers every file in `transport/queues/` and calls `.new` with no arguments at startup, which crashed because `ModelRequest` required `request_type:` and `model:`; the queue definition is now an anonymous class created inline by `Actor::ModelWorker#build_queue_class`
+- `Actor::ModelWorker#queue` now returns a CLASS instead of an instance — `Subscription#initialize` calls `queue.new`, so returning an instance caused a silent `NoMethodError` on `NilClass#new`; the anonymous queue class has `queue_name`, `queue_options`, `dlx_enabled`, and `initialize` (exchange bind) defined inline via `define_method`
+
 ## [0.3.2] - 2026-04-08
 
 ### Changed

data/CLAUDE.md

@@ -12,8 +12,8 @@ reporting, and **fleet queue subscription** for receiving routed LLM requests fr
 
 **GitHub**: https://github.com/LegionIO/lex-ollama
 **License**: MIT
-**Version**: 0.3.2
-**Specs**: 82 examples (12 spec files) — fleet additions add ~35 more
+**Version**: 0.3.3
+**Specs**: 154 examples (16 spec files)
 
 ---
 
@@ -28,7 +28,8 @@ Legion::Extensions::Ollama
 │   │                  #   pull_model, push_model, list_running
 │   ├── Embeddings     # embed
 │   ├── Blobs          # check_blob, push_blob
-│   ├── S3Models       # list_s3_models, import_from_s3, sync_from_s3, import_default_models
+│   ├── S3Models       # list_s3_models, import_from_s3, sync_from_s3, import_default_models,
+│   │                  #   sync_configured_models
 │   ├── Version        # server_version
 │   └── Fleet          # handle_request (fleet dispatcher — chat/embed/generate)
 ├── Helpers/
@@ -44,7 +45,8 @@ Legion::Extensions::Ollama
 │   └── Messages/
 │       └── LlmResponse  # Legion::LLM::Fleet::Response subclass, reply via default exchange
 └── Actor/
-    └── ModelWorker    # subscription actor — one per registered model/type
+    ├── ModelWorker    # subscription actor — one per registered model/type
+    └── ModelSync      # once actor — fires 5s after boot, pulls default models from S3
 ```
 
 ---
@@ -93,6 +95,15 @@ RabbitMQ policies (applied externally via Terraform) set `max-length` and
 legion:
   ollama:
     host: "http://localhost:11434"
+    s3:
+      bucket: "legion"
+      prefix: "ollama/models"
+      endpoint: "https://s3.example.internal"
+    default_models:
+      - "qwen3.5:4b"
+      - "nomic-embed-text:latest"
+    fleet:
+      consumer_priority: 10          # H100: 10, Mac Studio: 5, MacBook: 1
     subscriptions:
       - type: embed
         model: nomic-embed-text
@@ -104,7 +115,15 @@ legion:
         model: llama3.2
 ```
 
-The extension spawns one `Actor::ModelWorker` per subscription entry at boot.
+**`s3` + `default_models`**: `Actor::ModelSync` fires 5 seconds after extension load and calls
+`Runners::S3Models#sync_configured_models` to import any listed models not already present
+locally. All download logic lives in the runner; the actor is only the trigger. Uses the
+inherited `Actors::Base#manual` path (not `Legion::Runner`) so errors surface via
+`handle_exception` rather than being silently swallowed by `Concurrent::ScheduledTask`.
+
+**`subscriptions`**: `Ollama.build_actors` replaces the base `ModelWorker` actor entry with one
+dynamically generated subclass per subscription entry (each with a zero-arg `initialize`).
+The extension spawns one `Actor::ModelWorker` per entry at boot.
 
 ### Data Flow
 
@@ -154,6 +173,12 @@ The gem still works as a pure HTTP client library without AMQP, exactly as befor
   - `request_type: 'generate'` → `Client#generate`.
   - anything else (including `'chat'` or unknown) → `Client#chat`.
 - **`Actor::ModelWorker#use_runner?` is `false`** — bypasses `Legion::Runner` / task DB entirely.
+- **`Actor::ModelSync#use_runner?` is `false`** — uses inherited `Actors::Base#manual` which calls
+  `runner_class.send(runner_function, **{})` with proper `handle_exception` error handling.
+- **`Ollama.build_actors`** dynamically generates one `ModelWorker` subclass per subscription
+  entry, each with a zero-arg `initialize` that passes the frozen `request_type` and `model`.
+- **`Ollama.default_settings`** returns `{ s3: {}, fleet: {} }` so `settings[:s3]` and
+  `settings[:fleet]` are always hashes even without user configuration.
 - **Reply publishing** never raises — errors are swallowed so the AMQP ack is not blocked.
 - **Colon sanitisation** — `qwen3.5:27b` becomes `qwen3.5.27b` in queue/routing-key strings.
 
@@ -181,8 +206,9 @@ message_context:
 A subset (`conversation_id`, `message_id`, `request_id`) is promoted to AMQP headers
 (`x-legion-llm-conversation-id`, etc.) for filtering without body parsing.
 
-See: `docs/plans/2026-04-08-fleet-wire-protocol.md` for full AMQP property mapping,
-platform-wide standard, and per-message-type specifications.
+The wire protocol spec (AMQP property mapping, platform-wide standard, per-message-type
+specifications) was developed during the fleet design phase and is maintained in the
+legion-llm repository alongside the implementation.
 
 ---
 
@@ -210,4 +236,4 @@ bundle exec rubocop
 ---
 
 **Maintained By**: Matthew Iverson (@Esity)
-**Last Updated**: 2026-04-08
+**Last Updated**: 2026-04-17

data/README.md

@@ -40,10 +40,52 @@ gem install lex-ollama
 - `import_from_s3` - Download model from S3 directly to Ollama's filesystem (works before Ollama starts)
 - `sync_from_s3` - Download model from S3, push blobs through Ollama's API, write manifest to filesystem
 - `import_default_models` - Import a list of models from S3 (fleet provisioning)
+- `sync_configured_models` - Import all `default_models` from S3 that aren't already present locally
 
 ### Version
 - `server_version` - Retrieve the Ollama server version (GET /api/version)
 
+### Fleet Queue Subscription
+- `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.
+
+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.
+
+```yaml
+legion:
+  ollama:
+    host: "http://localhost:11434"
+    s3:
+      bucket: "legion"
+      prefix: "ollama/models"
+      endpoint: "https://s3.example.internal"
+    default_models:
+      - "qwen3.5:4b"
+      - "nomic-embed-text:latest"
+    fleet:
+      consumer_priority: 10        # H100: 10, Mac Studio: 5, MacBook: 1
+    subscriptions:
+      - type: embed
+        model: nomic-embed-text
+      - type: chat
+        model: "qwen3.5:27b"
+```
+
+**Auto-provisioning**: When `s3` and `default_models` are configured, the `ModelSync` actor
+fires 5 seconds after boot and imports any listed models not already present on disk from the
+S3 mirror. No manual pull step needed for fleet nodes.
+
+Fleet messages use the wire protocol defined in `legion-llm`: typed AMQP messages
+(`llm.fleet.request` / `llm.fleet.response` / `llm.fleet.error`) with `message_context`
+propagation for end-to-end tracing.
+
+Without `Legion::Extensions::Core`, the gem works as a pure HTTP client library with no
+AMQP dependency.
+
 ## Standalone Client
 
 ```ruby
@@ -85,21 +127,21 @@ Pull models from an internal S3 mirror instead of the public Ollama registry:
 client = Legion::Extensions::Ollama::Client.new
 
 # List available models in S3
-client.list_s3_models(bucket: 'legion', endpoint: 'https://mesh.s3api-core.optum.com')
+client.list_s3_models(bucket: 'legion', endpoint: 'https://s3.example.internal')
 
 # Import directly to filesystem (works without Ollama running)
 client.import_from_s3(model: 'llama3:latest', bucket: 'legion',
-                      endpoint: 'https://mesh.s3api-core.optum.com')
+                      endpoint: 'https://s3.example.internal')
 
 # Push through Ollama API (requires Ollama running)
 client.sync_from_s3(model: 'llama3:latest', bucket: 'legion',
-                    endpoint: 'https://mesh.s3api-core.optum.com')
+                    endpoint: 'https://s3.example.internal')
 
 # Provision fleet with default models
 client.import_default_models(
   default_models: %w[llama3:latest nomic-embed-text:latest],
   bucket: 'legion',
-  endpoint: 'https://mesh.s3api-core.optum.com'
+  endpoint: 'https://s3.example.internal'
 )
 ```
 
@@ -121,7 +163,7 @@ result[:usage]  # => { input_tokens: 1, output_tokens: 5, total_duration: ..., .
 
 ## Version
 
-0.3.1
+0.3.3
 
 ## License
 

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Ollama
+      module Actor
+        # Once actor — fires 5s after extension load and calls
+        # Runners::S3Models#sync_configured_models to pull any configured
+        # default models from S3 that are not already present locally.
+        #
+        # All download logic lives in the runner. This actor is only the trigger.
+        class ModelSync < Legion::Extensions::Actors::Once
+          def delay
+            5.0
+          end
+
+          def runner_class
+            Legion::Extensions::Ollama::Runners::S3Models
+          end
+
+          def runner_function
+            'sync_configured_models'
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+
+          def enabled?
+            s3_cfg = settings[:s3]
+            models = settings[:default_models]
+            s3_cfg.is_a?(Hash) && !s3_cfg[:bucket].nil? && models.is_a?(Array) && !models.empty?
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true)
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -59,9 +59,7 @@ module Legion
           # Standard scale: GPU server = 10, Mac Studio = 5, developer laptop = 1.
           # Defaults to 0 (equal priority) if not configured.
           def consumer_priority
-            return 0 unless defined?(Legion::Settings)
-
-            Legion::Settings.dig(:ollama, :fleet, :consumer_priority) || 0
+            settings.dig(:fleet, :consumer_priority) || 0
           end
 
           # Subscribe options include x-priority argument so RabbitMQ can honour
@@ -75,10 +73,12 @@ module Legion
             base.merge(arguments: { 'x-priority' => consumer_priority })
           end
 
-          # Override queue to return a model-scoped queue bound with the precise
-          # routing key for this worker's (type, model) pair.
+          # Returns a queue CLASS (not instance) bound to the llm.request exchange
+          # with the routing key for this worker's (type, model) pair.
+          # The Subscription base class calls queue.new in initialize, so this must
+          # return a class, not an instance.
           def queue
-            @queue ||= build_and_bind_queue
+            @queue ||= build_queue_class
           end
 
           # Enrich every inbound message with the worker's own request_type and model
@@ -94,17 +94,22 @@ module Legion
 
           private
 
-          def build_and_bind_queue
+          def build_queue_class
             sanitised_model = @model_name.tr(':', '.')
             routing_key     = "llm.request.ollama.#{@request_type}.#{sanitised_model}"
+            exchange_class  = Transport::Exchanges::LlmRequest
 
-            queue_obj = Transport::Queues::ModelRequest.new(
-              request_type: @request_type,
-              model:        @model_name
-            )
-            exchange_obj = Transport::Exchanges::LlmRequest.new
-            queue_obj.bind(exchange_obj, routing_key: routing_key)
-            queue_obj
+            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 } }
+              end
+              define_method(:dlx_enabled) { false }
+              define_method(:initialize) do
+                super()
+                bind(exchange_class.new, routing_key: routing_key)
+              end
+            end
           end
         end
       end

data/lib/legion/extensions/ollama/runners/s3_models.rb

@@ -145,6 +145,29 @@ module Legion
             { result: results, status: 200 }
           end
 
+          def sync_configured_models(**)
+            s3_cfg = settings[:s3]
+            models = settings[:default_models]
+
+            return { result: false, status: 412, error: 'no s3 config' } unless s3_cfg.is_a?(Hash) && s3_cfg[:bucket]
+            return { result: false, status: 412, error: 'no default_models configured' } unless models.is_a?(Array) && !models.empty?
+
+            bucket      = s3_cfg[:bucket]
+            s3_opts     = s3_cfg.except(:bucket)
+            models_path = ENV.fetch('OLLAMA_MODELS', File.join(Dir.home, '.ollama', 'models'))
+
+            results = models.filter_map do |model|
+              name, tag = model.split(':')
+              tag ||= 'latest'
+              manifest = File.join(models_path, 'manifests', 'registry.ollama.ai', 'library', name, tag)
+              next if File.exist?(manifest)
+
+              import_from_s3(model: model, bucket: bucket, models_path: models_path, **s3_opts)
+            end
+
+            { result: results, status: 200 }
+          end
+
           private
 
           def default_models_path

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

@@ -12,13 +12,8 @@ module Legion
       module Transport
         extend Legion::Extensions::Transport if Legion::Extensions.const_defined?(:Transport, false)
 
-        # All queue-to-exchange bindings are established dynamically by
-        # Actor::ModelWorker#build_and_bind_queue at subscription time.
-        # This file only needs to declare the exchange so topology/infra mode
-        # can introspect the full routing graph.
-        def self.additional_e_to_q
-          []
-        end
+        # All queue-to-exchange bindings for fleet queues are established dynamically by
+        # Actor::ModelWorker at subscription time via build_queue_class.
       end
     end
   end

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

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

data/lib/legion/extensions/ollama.rb

@@ -18,16 +18,53 @@ require 'legion/extensions/ollama/client'
 # 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/queues/model_request'
   require 'legion/extensions/ollama/transport/messages/llm_response'
   require 'legion/extensions/ollama/transport'
   require 'legion/extensions/ollama/actors/model_worker'
+  require 'legion/extensions/ollama/actors/model_sync'
 end
 
 module Legion
   module Extensions
     module Ollama
       extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core, false)
+
+      def self.default_settings
+        {
+          s3:    {},
+          fleet: {}
+        }
+      end
+
+      # Called by the framework during autobuild. Runs normal actor discovery,
+      # then replaces the single ModelWorker entry with one concrete subclass
+      # per subscription entry in settings (each has a zero-arg initialize).
+      def self.build_actors
+        super
+        @actors.delete(:model_worker)
+
+        subs = settings[:subscriptions]
+        return unless subs.is_a?(Array)
+
+        subs.each do |sub|
+          request_type = sub[:type]&.to_s
+          model        = sub[:model]&.to_s
+          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) }
+          end
+
+          @actors[actor_name] = {
+            extension:      'lex-ollama',
+            extension_name: :ollama,
+            actor_name:     actor_name,
+            actor_class:    worker_class,
+            type:           'literal'
+          }
+        end
+      end
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-ollama
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.4
 platform: ruby
 authors:
 - Esity
@@ -56,6 +56,7 @@ files:
 - README.md
 - lex-ollama.gemspec
 - lib/legion/extensions/ollama.rb
+- lib/legion/extensions/ollama/actors/model_sync.rb
 - lib/legion/extensions/ollama/actors/model_worker.rb
 - lib/legion/extensions/ollama/client.rb
 - lib/legion/extensions/ollama/helpers/client.rb
@@ -72,7 +73,6 @@ files:
 - lib/legion/extensions/ollama/transport.rb
 - lib/legion/extensions/ollama/transport/exchanges/llm_request.rb
 - lib/legion/extensions/ollama/transport/messages/llm_response.rb
-- lib/legion/extensions/ollama/transport/queues/model_request.rb
 - lib/legion/extensions/ollama/version.rb
 homepage: https://github.com/LegionIO/lex-ollama
 licenses:

data/lib/legion/extensions/ollama/transport/queues/model_request.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Ollama
-      module Transport
-        module Queues
-          # Parametric queue — one instance per (request_type, model) tuple.
-          #
-          # queue_name mirrors the routing key exactly so bindings are self-documenting
-          # in the RabbitMQ management UI, e.g.:
-          #   llm.request.ollama.embed.nomic-embed-text
-          #   llm.request.ollama.chat.qwen3.5.27b
-          #
-          # Queue strategy:
-          #   - classic (not quorum): quorum queues cannot be auto-delete
-          #   - auto_delete: true — queue deletes when last consumer disconnects + queue empties,
-          #     enabling basic.return feedback to publishers via mandatory: true
-          #   - x-max-priority: 10 — must be a queue argument at declaration time for classic
-          #     queues; policies handle max-length and overflow externally
-          class ModelRequest < Legion::Transport::Queue
-            def initialize(request_type:, model:, **)
-              @request_type = request_type.to_s
-              @model        = sanitise_model(model)
-              super(**)
-            end
-
-            def queue_name
-              "llm.request.ollama.#{@request_type}.#{@model}"
-            end
-
-            def queue_options
-              {
-                durable:     false,
-                auto_delete: true,
-                arguments:   { 'x-max-priority' => 10 }
-              }
-            end
-
-            # Disable dead-letter exchange provisioning. The base class
-            # default_options always adds x-dead-letter-exchange when
-            # dlx_enabled returns true. Fleet queues are ephemeral
-            # (auto-delete) and must not provision persistent DLX queues.
-            def dlx_enabled
-              false
-            end
-
-            private
-
-            def sanitise_model(name)
-              name.to_s.tr(':', '.')
-            end
-          end
-        end
-      end
-    end
-  end
-end