lex-ollama 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7477574f919b18b85c79afba3a1f65c8540d9eff9ca02b9e0c807b3740fed452
-  data.tar.gz: a5c69878c8518caf02c2e238c94243fd49c320f20bfaede00252bfdc87be5cbb
+  metadata.gz: 28df561b00b58c7cb179b9904aed61a5aa7e278140306dadb3b4b2665eaab824
+  data.tar.gz: 446afaab9d80e6a4f62286a1f5ccc1c023bdbb178dba043cb96081412991b2d3
 SHA512:
-  metadata.gz: 31566bf77244dd3cfc097531a3af1da186e8d0e7e0ec675be0b7471f8b7654649fa666d4c3d2f6bb34c46d73d29aa72a64dfa07f7beb35ae01d23c8f2bc6c797
-  data.tar.gz: f900e723d2db75dbdb266fcf33d01be56d7614b992be9e0b6d29345a85012be0d226ff9a2f42cb2d5a9f932cb1e641e6ecbfc033ccd3c6c98bbe4d2a7207ad13
+  metadata.gz: 2915cfe6e4e959e61ee5b8ce68e7da784b4c6001cfe0c3acdb0a4e0f804da79a1e46a17b7c5297b9dd4f26e58bbae504066f5874d8cd82d6ea223b3dfc561bbb
+  data.tar.gz: cb1337292d4bb7c94603612e03dbdbcbd9a41c2a94e56f4bbfad1132d403f6d14b0316091017745ee2d282ccc426bdcdb65b137f66f07f2a505d231792e424b0

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.3.1] - 2026-04-08
+
+### Added
+- `Runners::Fleet` — module-function dispatcher for inbound AMQP LLM request messages; routes by `request_type` to `Client#embed`, `Client#generate`, or `Client#chat`
+- `Transport::Exchanges::LlmRequest` — durable topic exchange `llm.request` for fleet routing
+- `Transport::Queues::ModelRequest` — parametric durable quorum queue per `(type, model)` pair; sanitises colons in model names to dots
+- `Transport::Messages::LlmResponse` — reply message published back to `reply_to` queue after inference
+- `Actor::ModelWorker` — subscription actor; one instance per configured `(type, model)` subscription; enriches inbound messages with `request_type` and `model`, bypasses Legion::Runner task DB (`use_runner? false`)
+- Fleet queue subscription system: when `Legion::Extensions::Core` is present, subscribes to model-scoped queues on `llm.request` topic exchange using routing key `llm.request.ollama.<type>.<model>`
+- Standalone mode: all transport/actor requires guarded behind `const_defined?(:Core, false)` so the gem works as a pure HTTP client library without AMQP
+
+### Fixed
+- `Runners::S3Models`: use `::JSON.parse` (stdlib) instead of bare `JSON.parse` which resolves to `Legion::JSON` (symbol keys) inside the `Legion::` namespace — fixes `import_from_s3` and `sync_from_s3` manifest parsing
+
 ## [0.3.0] - 2026-04-01
 
 ### Added

data/CLAUDE.md

@@ -1,44 +1,178 @@
 # lex-ollama: Ollama Integration for LegionIO
 
-**Parent**: `/Users/miverso2/rubymine/legion/extensions-ai/CLAUDE.md`
+**Repository Level 3 Documentation**
+- **Parent**: `../CLAUDE.md`
+- **Grandparent**: `../../CLAUDE.md`
 
 ## Purpose
 
-Legion Extension that connects LegionIO to Ollama, a local LLM server. Provides text generation, chat completions, embeddings, model management, and blob operations.
+Legion Extension that connects LegionIO to Ollama, a local LLM server. Provides text generation,
+chat completions, embeddings, model management, blob operations, S3 model distribution, version
+reporting, and **fleet queue subscription** for receiving routed LLM requests from the Legion bus.
 
 **GitHub**: https://github.com/LegionIO/lex-ollama
 **License**: MIT
+**Version**: 0.3.1
+**Specs**: 82 examples (12 spec files) — fleet additions add ~35 more
+
+---
 
 ## Architecture
 
 ```
 Legion::Extensions::Ollama
 ├── Runners/
-│   ├── Completions        # POST /api/generate
-│   ├── Chat               # POST /api/chat
-│   ├── Models             # CRUD + pull/push/running
-│   ├── Embeddings         # POST /api/embed
-│   ├── Blobs              # HEAD/POST /api/blobs/:digest
-│   └── Version            # GET /api/version
+│   ├── Completions    # generate, generate_stream
+│   ├── Chat           # chat, chat_stream
+│   ├── Models         # create_model, list_models, show_model, copy_model, delete_model,
+│   │                  #   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
+│   ├── Version        # server_version
+│   └── Fleet          # handle_request (fleet dispatcher — chat/embed/generate)
 ├── Helpers/
-│   └── Client             # Faraday connection to Ollama server
-└── Client                 # Standalone client class
+│   ├── Client         # Faraday connection to Ollama server (module, factory method)
+│   ├── Errors         # error handling + with_retry
+│   └── Usage          # usage normalization (maps Ollama token/duration fields to standard shape)
+├── Client             # Standalone client class (includes all runners, holds @config)
+├── Transport/         # (loaded only when Legion::Extensions::Core is present)
+│   ├── Exchanges/
+│   │   └── LlmRequest   # topic exchange 'llm.request'
+│   ├── Queues/
+│   │   └── ModelRequest # parametric queue — one per (type, model) pair
+│   └── Messages/
+│       └── LlmResponse  # reply message published back to reply_to
+└── Actor/
+    └── ModelWorker    # subscription actor — one per registered model/type
 ```
 
+---
+
+## Fleet Queue Subscription
+
+### Overview
+
+When `Legion::Extensions::Core` is available, lex-ollama subscribes to model-scoped queues on the
+`llm.request` topic exchange, accepting routed inference work from other Legion fleet members
+(lex-llm-gateway, direct publishers, etc.).
+
+### Routing Key Schema
+
+```
+llm.request.ollama.<type>.<model>
+```
+
+| Segment    | Values                     | Notes                              |
+|------------|----------------------------|------------------------------------|
+| `ollama`   | literal                    | provider identifier                |
+| `type`     | `chat`, `embed`, `generate`| maps to a specific runner method   |
+| `model`    | sanitised model name       | `:` replaced with `.` (AMQP rules) |
+
+**Examples:**
+```
+llm.request.ollama.embed.nomic-embed-text
+llm.request.ollama.embed.mxbai-embed-large
+llm.request.ollama.chat.qwen3.5.27b          # was qwen3.5:27b
+llm.request.ollama.chat.llama3.2
+llm.request.ollama.generate.llama3.2
+```
+
+### Queue Strategy
+
+Each model+type combination gets its own **durable quorum queue** with a routing key that matches
+its queue name exactly. Multiple nodes carrying the same model compete fairly (no SAC) — any
+subscriber can serve. The queue name is identical to the routing key for clarity in the management UI.
+
+### Configuration
+
+```yaml
+legion:
+  ollama:
+    host: "http://localhost:11434"
+    subscriptions:
+      - type: embed
+        model: nomic-embed-text
+      - type: embed
+        model: mxbai-embed-large
+      - type: chat
+        model: "qwen3.5:27b"
+      - type: chat
+        model: llama3.2
+```
+
+The extension spawns one `Actor::ModelWorker` per subscription entry at boot.
+
+### Data Flow
+
+```
+Publisher (lex-llm-gateway / any fleet node)
+  │  routing_key: "llm.request.ollama.embed.nomic-embed-text"
+  ▼
+Exchange: llm.request  [topic, durable]
+  │
+  └── Queue: llm.request.ollama.embed.nomic-embed-text  [quorum]
+            ▼
+       Actor::ModelWorker (type=embed, model=nomic-embed-text)
+            ▼
+       Runners::Fleet#handle_request
+            ▼
+       Ollama::Client#embed(model: 'nomic-embed-text', ...)
+            ▼
+       Transport::Messages::LlmResponse → reply_to queue (if present)
+```
+
+### Standalone Mode (no Legion runtime)
+
+All transport/actor requires are guarded behind:
+```ruby
+if Legion::Extensions.const_defined?(:Core, false)
+  # transport + actor requires
+end
+```
+The gem still works as a pure HTTP client library without AMQP, exactly as before.
+
+---
+
+## Key Design Decisions
+
+- `generate_stream` and `chat_stream` yield `{ type: :delta, text: }` and `{ type: :done }` events.
+- `S3Models` runner depends on `lex-s3`. Uses SHA256 digest verification. `import_from_s3` writes
+  directly to the filesystem; `sync_from_s3` pushes blobs through the Ollama API.
+- `S3Models::OLLAMA_REGISTRY_PREFIX = 'manifests/registry.ollama.ai/library'`.
+- `Usage` helper normalizes Ollama's token/duration fields to `{ input_tokens:, output_tokens:, ... }`.
+- All runners return `{ result: body, status: code }`.
+- **`Runners::Fleet` dispatch rules:**
+  - `request_type: 'embed'` → `Client#embed`, uses `:input` then falls back to `:text`.
+  - `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.
+- **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.
+
+---
+
 ## Dependencies
 
 | Gem | Purpose |
 |-----|---------|
-| faraday | HTTP client for Ollama REST API |
+| `faraday` >= 2.0 | HTTP client for Ollama REST API |
+| `lex-s3` >= 0.2 | S3 model distribution operations |
+
+Fleet transport requires Legion runtime gems (`legion-transport`, `LegionIO`) but those are *not*
+gemspec dependencies — they are expected to be present in the runtime environment.
+
+---
 
 ## Testing
 
 ```bash
 bundle install
-bundle exec rspec
+bundle exec rspec        # all examples
 bundle exec rubocop
 ```
 
 ---
 
 **Maintained By**: Matthew Iverson (@Esity)
+**Last Updated**: 2026-04-07

data/README.md

@@ -119,6 +119,10 @@ result[:usage]  # => { input_tokens: 1, output_tokens: 5, total_duration: ..., .
 - [LegionIO](https://github.com/LegionIO/LegionIO) framework
 - [Ollama](https://ollama.com) running locally or on a remote host
 
+## Version
+
+0.3.1
+
 ## License
 
 MIT

data/docs/plans/2026-04-07-fleet-queue-subscription-design.md

@@ -0,0 +1,427 @@
+# Fleet Queue Subscription for lex-ollama
+
+**Date**: 2026-04-07
+**Status**: Design / RFC
+
+---
+
+## Problem
+
+`lex-ollama` currently operates purely as a client library — it wraps the Ollama HTTP API and
+returns results, but it never *subscribes* to any AMQP queue.  That means there is no way for the
+Legion fleet to route LLM/embed work to an Ollama node over the message bus.  Every other
+producer-side extension (`lex-openai`, `lex-claude`, etc.) publishes to the `extensions` exchange;
+there is currently no Ollama-backed consumer on the other side.
+
+---
+
+## Goals
+
+1. **Subscribe** — lex-ollama listens on a dedicated queue and processes `llm.request.*` messages
+   sent by other fleet members (lex-llm-gateway, direct callers, etc.).
+2. **Model-scoped routing keys** — each local model gets its own binding so traffic can be steered
+   precisely without code-level dispatch logic.
+3. **Minimal coupling** — the transport layer is guarded behind `const_defined?` so the gem still
+   works as a standalone library (tests, scripts, irb) without any Legion runtime present.
+4. **Consistent patterns** — follow the same `Transport/Queues`, `Transport/Messages`,
+   `Transport/Exchanges`, `Actors` layout used by every other Legion extension.
+
+---
+
+## Routing Key Schema
+
+```
+llm.request.<provider>.<type>.<model>
+```
+
+| Segment    | Values                                      | Notes                               |
+|------------|---------------------------------------------|-------------------------------------|
+| `provider` | `ollama`                                    | always `ollama` for this extension  |
+| `type`     | `chat`, `generate`, `embed`                 | maps 1-to-1 to a runner method      |
+| `model`    | any Ollama model name (`:` → `.` sanitised) | e.g. `nomic-embed-text`, `qwen3.5.27b` |
+
+### Examples
+
+```
+llm.request.ollama.embed.nomic-embed-text
+llm.request.ollama.embed.mxbai-embed-large
+llm.request.ollama.chat.qwen3.5.27b
+llm.request.ollama.chat.llama3.2
+llm.request.ollama.generate.llama3.2
+```
+
+Colons in model names (`qwen3.5:27b`) are converted to dots (`qwen3.5.27b`) because AMQP topic
+routing keys use `.` as a word separator and `:` is not permitted.
+
+---
+
+## Queue Strategy: Dynamic Per-Model Queues
+
+Each subscribed model gets its **own durable queue** bound to the `llm.request` topic exchange.
+
+```
+Exchange: llm.request  (topic, durable)
+  ├── llm.request.ollama.embed.nomic-embed-text   → Queue: llm.request.ollama.embed.nomic-embed-text
+  ├── llm.request.ollama.embed.mxbai-embed-large  → Queue: llm.request.ollama.embed.mxbai-embed-large
+  ├── llm.request.ollama.chat.qwen3.5.27b         → Queue: llm.request.ollama.chat.qwen3.5.27b
+  └── llm.request.ollama.chat.llama3.2            → Queue: llm.request.ollama.chat.llama3.2
+```
+
+**Why per-model queues instead of a wildcard queue?**
+
+- Multiple nodes can each carry *different* model subsets.  A node with only `nomic-embed-text`
+  should not compete for messages destined for `mxbai-embed-large`.
+- RabbitMQ quorum queues + SAC (`x-single-active-consumer`) per queue let us cleanly support both
+  load-balancing *and* exclusive-consumer topologies without any application-layer coordination.
+- Routing key granularity lets lex-llm-gateway (or any sender) address a specific model precisely
+  rather than relying on message-body dispatch.
+
+---
+
+## New Files
+
+```
+lib/legion/extensions/ollama/
+  transport/
+    exchanges/
+      llm_request.rb          # Topic exchange: 'llm.request'
+    queues/
+      model_request.rb        # Parametric queue class — one instance per (type, model) tuple
+    messages/
+      llm_response.rb         # Response message published back to reply_to
+  actors/
+    model_worker.rb           # Subscription actor — one per registered model
+  runners/
+    fleet.rb                  # NEW: fleet request dispatcher (chat/embed/generate dispatch)
+  transport.rb                # Transport module wiring for the extension
+
+spec/legion/extensions/ollama/
+  transport/
+    exchanges/llm_request_spec.rb
+    queues/model_request_spec.rb
+    messages/llm_response_spec.rb
+  actors/model_worker_spec.rb
+  runners/fleet_spec.rb
+```
+
+---
+
+## Detailed Design
+
+### `Transport::Exchanges::LlmRequest`
+
+```ruby
+module Legion::Extensions::Ollama::Transport::Exchanges
+  class LlmRequest < Legion::Transport::Exchange
+    def exchange_name = 'llm.request'
+    def default_type  = 'topic'
+  end
+end
+```
+
+A single `topic` exchange shared by all AI provider extensions.  If `lex-openai` or `lex-claude`
+declare the same exchange name with the same options, RabbitMQ deduplicates (no `PreconditionFailed`
+because parameters match).
+
+---
+
+### `Transport::Queues::ModelRequest`
+
+A **parametric queue** — one Ruby class, instantiated N times with different `(type, model)` pairs.
+
+```ruby
+module Legion::Extensions::Ollama::Transport::Queues
+  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: true, arguments: { 'x-queue-type': 'quorum' } }
+    end
+
+    private
+
+    def sanitise_model(name)
+      name.to_s.tr(':', '.')
+    end
+  end
+end
+```
+
+The `queue_name` mirrors the routing key exactly, which keeps bindings trivially readable in the
+RabbitMQ management UI.
+
+---
+
+### `Transport::Messages::LlmResponse`
+
+Sent back to `reply_to` (if present) after processing.
+
+```ruby
+module Legion::Extensions::Ollama::Transport::Messages
+  class LlmResponse < Legion::Transport::Message
+    def routing_key  = @options[:reply_to]
+    def exchange     = Legion::Transport::Exchanges::Agent   # direct reply via default exchange
+    def encrypt?     = false
+    def message
+      {
+        correlation_id: @options[:correlation_id],
+        result:         @options[:result],
+        usage:          @options[:usage],
+        model:          @options[:model],
+        provider:       'ollama',
+        status:         @options[:status]
+      }
+    end
+  end
+end
+```
+
+---
+
+### `Runners::Fleet`
+
+New runner module.  Dispatches inbound AMQP payloads to the appropriate Ollama method and
+optionally publishes a reply.
+
+```ruby
+module Legion::Extensions::Ollama::Runners::Fleet
+  module_function
+
+  # Primary entry point called by the actor.
+  def handle_request(model:, request_type: 'chat', reply_to: nil,
+                     correlation_id: nil, **payload)
+    result = dispatch(model: model, request_type: request_type, **payload)
+    publish_reply(reply_to, correlation_id, result) if reply_to
+    result
+  end
+
+  private
+
+  def dispatch(model:, request_type:, **payload)
+    client = Legion::Extensions::Ollama::Client.new
+
+    case request_type.to_s
+    when 'embed'
+      client.embed(model: model, input: payload[:input] || payload[:text])
+    when 'generate'
+      client.generate(model: model, prompt: payload[:prompt], **payload.slice(:options, :system))
+    else  # 'chat' and anything else
+      client.chat(model: model, messages: payload[:messages],
+                  **payload.slice(:tools, :format, :options))
+    end
+  rescue StandardError => e
+    { result: nil, status: 500, error: e.message }
+  end
+
+  def publish_reply(reply_to, correlation_id, result)
+    return unless defined?(Legion::Transport)
+
+    Transport::Messages::LlmResponse.new(
+      reply_to:       reply_to,
+      correlation_id: correlation_id,
+      **result
+    ).publish
+  rescue StandardError
+    nil  # never let a broken reply kill the ack
+  end
+end
+```
+
+---
+
+### `Actors::ModelWorker`
+
+One actor instance per `(type, model)` pair.  Overrides `queue` to return the
+pre-instantiated `ModelRequest` queue bound to its specific routing key.
+
+```ruby
+module Legion::Extensions::Ollama::Actor
+  class ModelWorker < Legion::Extensions::Actors::Subscription
+    attr_reader :request_type, :model_name
+
+    def initialize(request_type:, model:, **)
+      @request_type = request_type.to_s
+      @model_name   = model.to_s
+      super(**)
+    end
+
+    def runner_class    = Legion::Extensions::Ollama::Runners::Fleet
+    def runner_function = 'handle_request'
+    def use_runner?     = false
+
+    # Override to use a model-scoped queue instead of the default convention-based one.
+    def queue
+      @queue_class ||= begin
+        Transport::Queues::ModelRequest.new(
+          request_type: @request_type,
+          model:        @model_name
+        ).tap do |q|
+          exchange = Transport::Exchanges::LlmRequest.new
+          routing_key = "llm.request.ollama.#{@request_type}.#{@model_name.tr(':', '.')}"
+          q.bind(exchange, routing_key: routing_key)
+        end
+      end
+    end
+
+    # Injects request_type + model into every message so Fleet#handle_request
+    # always has them, even if the sender omitted them.
+    def process_message(payload, metadata, delivery_info)
+      msg = super
+      msg[:request_type] ||= @request_type
+      msg[:model]        ||= @model_name
+      msg
+    end
+  end
+end
+```
+
+---
+
+### `transport.rb` (extension-level wiring)
+
+```ruby
+require 'legion/extensions/transport'
+
+module Legion::Extensions::Ollama::Transport
+  extend Legion::Extensions::Transport
+
+  # No additional e_to_q here — all bindings are created dynamically by
+  # ModelWorker#queue.  The exchange declaration is enough for topology mode.
+  def self.additional_e_to_q = []
+end
+```
+
+---
+
+### Settings / Model Registration
+
+Models to subscribe for are read from `Legion::Settings` at boot:
+
+```yaml
+# legion.yml (or legion-settings)
+legion:
+  ollama:
+    host: "http://localhost:11434"
+    subscriptions:
+      - type: embed
+        model: nomic-embed-text
+      - type: embed
+        model: mxbai-embed-large
+      - type: chat
+        model: "qwen3.5:27b"
+      - type: chat
+        model: llama3.2
+      - type: generate
+        model: llama3.2
+```
+
+The extension's `Core` lifecycle hook reads this list and spawns one `ModelWorker` actor per entry.
+
+---
+
+### `ollama.rb` changes (main extension file)
+
+Add the new requires (guarded so the gem still loads without Legion core):
+
+```ruby
+require 'legion/extensions/ollama/runners/fleet'
+
+if Legion::Extensions.const_defined?(:Core)
+  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/transport'
+  require 'legion/extensions/ollama/actors/model_worker'
+end
+```
+
+---
+
+## Transport Topology Diagram
+
+```
+Publisher (lex-llm-gateway / any Legion node)
+  │
+  │  publish routing_key: "llm.request.ollama.embed.nomic-embed-text"
+  ▼
+Exchange: llm.request  [topic, durable]
+  │
+  ├─── binding: llm.request.ollama.embed.nomic-embed-text
+  │         ▼
+  │    Queue: llm.request.ollama.embed.nomic-embed-text  [quorum, durable]
+  │         ▼
+  │    ModelWorker(type: embed, model: nomic-embed-text)
+  │         ▼
+  │    Runners::Fleet.handle_request(...)
+  │         ▼
+  │    Ollama::Client#embed(model: 'nomic-embed-text', ...)
+  │         ▼
+  │    LlmResponse.publish → reply_to queue
+  │
+  ├─── binding: llm.request.ollama.embed.mxbai-embed-large
+  │         ▼  [similar chain]
+  │
+  └─── binding: llm.request.ollama.chat.qwen3.5.27b
+            ▼  [similar chain]
+```
+
+---
+
+## What Stays Unchanged
+
+| Component               | Status       | Reason                                         |
+|-------------------------|--------------|------------------------------------------------|
+| `Runners::Chat`         | Unchanged    | Still used directly + via fleet               |
+| `Runners::Embeddings`   | Unchanged    | Still used directly + via fleet               |
+| `Runners::Completions`  | Unchanged    | Still used directly + via fleet               |
+| `Runners::Models`       | Unchanged    | Not a fleet-dispatched concern                |
+| `Runners::S3Models`     | Unchanged    | Separate distribution concern                 |
+| `Runners::Blobs`        | Unchanged    | Internal implementation detail                |
+| `Helpers::Client`       | Unchanged    | Faraday factory, no transport coupling        |
+| `Helpers::Errors`       | Unchanged    | Retry logic, no transport coupling            |
+| `Helpers::Usage`        | Unchanged    | Token normalisation, no transport coupling    |
+| `Client` class          | Unchanged    | Standalone HTTP client — no AMQP dependency   |
+| All existing specs      | Unchanged    | 82 passing examples must remain green         |
+
+---
+
+## Open Questions
+
+1. **`x-single-active-consumer` per queue?**  If multiple ollama nodes carry the same model, do we
+   want them to compete (round-robin, no SAC) or have a single active + hot-standby (SAC=true)?
+   Default proposal: **no SAC** (any subscribed node can serve), matches how lex-conditioner works.
+
+2. **Wildcard subscription?**  Should there be an opt-in `llm.request.ollama.#` catch-all queue for
+   nodes that want to handle *any* ollama traffic?  Useful for dev/single-node setups.  Proposal:
+   add as a separate `ModelWorker`-compatible setting (`type: '*', model: '*'`) with a wildcard
+   routing key binding.
+
+3. **Streaming over AMQP?**  The current design returns the full accumulated response in a single
+   reply message (non-streaming).  Streaming responses over AMQP (chunked delta messages) is
+   possible but significantly more complex — deferred to a future phase.
+
+4. **`request_type` in routing key vs message body?**  Currently the routing key embeds the type
+   (`chat`, `embed`, `generate`).  The message body should also carry it so `Fleet#handle_request`
+   can dispatch without needing to parse the delivery routing key.  The actor injects it from its
+   own instance vars — this is the agreed approach.
+
+---
+
+## Implementation Phases
+
+| Phase | Scope                                                           | New specs |
+|-------|-----------------------------------------------------------------|-----------|
+| 1     | `Transport::Exchanges::LlmRequest` + `Transport::Queues::ModelRequest` | 2 files   |
+| 2     | `Runners::Fleet` + `Transport::Messages::LlmResponse`          | 2 files   |
+| 3     | `Actors::ModelWorker` + `transport.rb` + settings loading       | 2 files   |
+| 4     | `ollama.rb` integration wiring + CLAUDE.md update               | —         |
+
+Each phase is independently reviewable/mergeable.

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Ollama
+      module Actor
+        # Subscription actor that listens on a model-scoped queue and forwards
+        # inbound LLM request messages to Runners::Fleet#handle_request.
+        #
+        # One instance is created per (request_type, model) entry in settings:
+        #
+        #   legion:
+        #     ollama:
+        #       subscriptions:
+        #         - type: embed
+        #           model: nomic-embed-text
+        #         - 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).
+        class ModelWorker < Legion::Extensions::Actors::Subscription
+          attr_reader :request_type, :model_name
+
+          def initialize(request_type:, model:, **)
+            @request_type = request_type.to_s
+            @model_name   = model.to_s
+            super(**)
+          end
+
+          def runner_class
+            Legion::Extensions::Ollama::Runners::Fleet
+          end
+
+          def runner_function
+            'handle_request'
+          end
+
+          # Bypass Legion::Runner — call the runner module directly so we don't
+          # need a task record in the database for every LLM inference hop.
+          def use_runner?
+            false
+          end
+
+          # Override queue to return a model-scoped queue bound with the precise
+          # routing key for this worker's (type, model) pair.
+          def queue
+            @queue ||= build_and_bind_queue
+          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.
+          def process_message(payload, metadata, delivery_info)
+            msg = super
+            msg[:request_type] ||= @request_type
+            msg[:model]        ||= @model_name
+            msg
+          end
+
+          private
+
+          def build_and_bind_queue
+            sanitised_model = @model_name.tr(':', '.')
+            routing_key     = "llm.request.ollama.#{@request_type}.#{sanitised_model}"
+
+            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
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Ollama
+      module Runners
+        # Fleet runner — handles inbound AMQP LLM request messages and dispatches
+        # them to the appropriate Ollama::Client method based on request_type.
+        #
+        # Called by Actor::ModelWorker with use_runner? = false, meaning the actor
+        # calls this module directly rather than going through Legion::Runner.
+        module Fleet
+          module_function
+
+          # Primary entry point called by the subscription actor.
+          #
+          # @param model [String] Ollama model name, e.g. "nomic-embed-text"
+          # @param request_type [String] "chat", "embed", or "generate"
+          # @param reply_to [String, nil] routing key for the reply queue (RPC pattern)
+          # @param correlation_id [String, nil] echoed back in the reply for caller matching
+          # @param payload [Hash] remaining message keys passed through to the Ollama client
+          def handle_request(model:, request_type: 'chat', reply_to: nil,
+                             correlation_id: nil, **payload)
+            result = dispatch(model: model, request_type: request_type, **payload)
+            publish_reply(reply_to, correlation_id, result.merge(model: model)) if reply_to
+            result
+          end
+
+          def dispatch(model:, request_type:, **payload)
+            ollama = Legion::Extensions::Ollama::Client.new
+
+            case request_type.to_s
+            when 'embed'
+              input = payload[:input] || payload[:text]
+              ollama.embed(model: model, input: input,
+                           **payload.slice(:truncate, :options, :keep_alive, :dimensions))
+            when 'generate'
+              ollama.generate(model: model, prompt: payload[:prompt],
+                              **payload.slice(:images, :format, :options, :system, :keep_alive))
+            else
+              # 'chat' and any unrecognised type falls through to chat
+              ollama.chat(model: model, messages: payload[:messages],
+                          **payload.slice(:tools, :format, :options, :keep_alive, :think))
+            end
+          rescue StandardError => e
+            { result: nil, usage: {}, status: 500, error: e.message }
+          end
+
+          def publish_reply(reply_to, correlation_id, result)
+            return unless defined?(Legion::Transport)
+
+            Transport::Messages::LlmResponse.new(
+              reply_to:       reply_to,
+              correlation_id: correlation_id,
+              **result
+            ).publish
+          rescue StandardError
+            # Never let a broken reply pipeline kill the consumer ack path.
+            nil
+          end
+
+          private :dispatch, :publish_reply
+        end
+      end
+    end
+  end
+end

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

@@ -45,7 +45,7 @@ module Legion
             manifest_key = "#{prefix}/#{OLLAMA_REGISTRY_PREFIX}/#{name}/#{tag}"
             manifest_resp = s3.get_object(bucket: bucket, key: manifest_key)
             manifest_body = manifest_resp[:body]
-            manifest_data = JSON.parse(manifest_body)
+            manifest_data = ::JSON.parse(manifest_body)
 
             digests = []
             digests << manifest_data['config'].slice('digest', 'size')
@@ -90,7 +90,7 @@ module Legion
 
             manifest_key = "#{prefix}/#{OLLAMA_REGISTRY_PREFIX}/#{name}/#{tag}"
             manifest_resp = s3.get_object(bucket: bucket, key: manifest_key)
-            manifest_data = JSON.parse(manifest_resp[:body])
+            manifest_data = ::JSON.parse(manifest_resp[:body])
 
             digests = []
             digests << manifest_data['config']['digest']

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Ollama
+      module Transport
+        module Exchanges
+          class LlmRequest < Legion::Transport::Exchange
+            def exchange_name
+              'llm.request'
+            end
+
+            def default_type
+              'topic'
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Ollama
+      module Transport
+        module Messages
+          # Published back to the caller's reply_to queue after a fleet request is processed.
+          # Uses the default RabbitMQ exchange (direct, empty string) with reply_to as routing key,
+          # which is standard for RPC-style reply routing.
+          class LlmResponse < Legion::Transport::Message
+            def routing_key
+              @options[:reply_to]
+            end
+
+            def exchange
+              Legion::Transport::Exchanges::Agent
+            end
+
+            def encrypt?
+              false
+            end
+
+            def message
+              {
+                correlation_id: @options[:correlation_id],
+                result:         @options[:result],
+                usage:          @options[:usage],
+                model:          @options[:model],
+                provider:       'ollama',
+                status:         @options[:status] || 200
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# 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
+          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: true, arguments: { 'x-queue-type': 'quorum' } }
+            end
+
+            private
+
+            # Project convention: use dots as the only word separator in routing keys
+            # so queue names stay visually consistent (dots are the AMQP topic separator).
+            # e.g. "qwen3.5:27b" → "qwen3.5.27b"
+            def sanitise_model(name)
+              name.to_s.tr(':', '.')
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+begin
+  require 'legion/extensions/transport'
+rescue LoadError
+  nil
+end
+
+module Legion
+  module Extensions
+    module Ollama
+      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
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Ollama
-      VERSION = '0.3.0'
+      VERSION = '0.3.1'
     end
   end
 end

data/lib/legion/extensions/ollama.rb

@@ -11,12 +11,23 @@ require 'legion/extensions/ollama/runners/embeddings'
 require 'legion/extensions/ollama/runners/blobs'
 require 'legion/extensions/ollama/runners/s3_models'
 require 'legion/extensions/ollama/runners/version'
+require 'legion/extensions/ollama/runners/fleet'
 require 'legion/extensions/ollama/client'
 
+# 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/queues/model_request'
+  require 'legion/extensions/ollama/transport/messages/llm_response'
+  require 'legion/extensions/ollama/transport'
+  require 'legion/extensions/ollama/actors/model_worker'
+end
+
 module Legion
   module Extensions
     module Ollama
-      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core, false)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-ollama
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Esity
@@ -56,8 +56,10 @@ files:
 - README.md
 - docs/plans/2026-04-01-s3-model-distribution-design.md
 - docs/plans/2026-04-01-s3-model-distribution-plan.md
+- docs/plans/2026-04-07-fleet-queue-subscription-design.md
 - lex-ollama.gemspec
 - lib/legion/extensions/ollama.rb
+- lib/legion/extensions/ollama/actors/model_worker.rb
 - lib/legion/extensions/ollama/client.rb
 - lib/legion/extensions/ollama/helpers/client.rb
 - lib/legion/extensions/ollama/helpers/errors.rb
@@ -66,9 +68,14 @@ files:
 - lib/legion/extensions/ollama/runners/chat.rb
 - lib/legion/extensions/ollama/runners/completions.rb
 - lib/legion/extensions/ollama/runners/embeddings.rb
+- lib/legion/extensions/ollama/runners/fleet.rb
 - lib/legion/extensions/ollama/runners/models.rb
 - 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_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: