lex-ollama 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f82aeecea946b03e08e2dc80a8ec66504276a2bb28aaaca5528d02105328166
-  data.tar.gz: 6b7b392634ec069693a0b0b030b1619a0a5ae1d3cbb34c2440124c1c52d15e4a
+  metadata.gz: 7477574f919b18b85c79afba3a1f65c8540d9eff9ca02b9e0c807b3740fed452
+  data.tar.gz: a5c69878c8518caf02c2e238c94243fd49c320f20bfaede00252bfdc87be5cbb
 SHA512:
-  metadata.gz: 25b18ed44dbad71930004a3384dc897e37b245d3cdafa98122e0210a22ac5d5e6be343ab0133e519f8228f026d254e4993ee597f13368590c2fa81971329c6a8
-  data.tar.gz: 39b9f4ed1e8a7ccd447b03770a9757c7e2cdbcea03341f07c2dda561db72e3556029152c76256e6f8b85b6d0cb858773e2d7ee9989d5559ffdc9daccfcf6b966
+  metadata.gz: 31566bf77244dd3cfc097531a3af1da186e8d0e7e0ec675be0b7471f8b7654649fa666d4c3d2f6bb34c46d73d29aa72a64dfa07f7beb35ae01d23c8f2bc6c797
+  data.tar.gz: f900e723d2db75dbdb266fcf33d01be56d7614b992be9e0b6d29345a85012be0d226ff9a2f42cb2d5a9f932cb1e641e6ecbfc033ccd3c6c98bbe4d2a7207ad13

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.3.0] - 2026-04-01
+
+### Added
+- S3 model distribution via new `Runners::S3Models` module
+- `list_s3_models` to discover models available in an S3 mirror
+- `import_from_s3` for direct filesystem model import (works without Ollama running)
+- `sync_from_s3` for Ollama API-based model import (push_blob + manifest write)
+- `import_default_models` convenience method for fleet provisioning
+- Runtime dependency on `lex-s3` for S3 operations
+- Streaming S3 downloads via `response_target` to avoid loading multi-GB blobs into memory
+- Error propagation in `sync_from_s3` — returns failure with error details when blob push fails
+- SHA256 digest verification for all downloaded blobs (import and sync paths)
+- Atomic blob writes via temp file + rename (prevents partial/corrupt blobs on failure)
+- Cache hits verified by SHA256 digest, not just file size — corrupted local blobs are re-downloaded
+- `DigestMismatchError` raised when S3 blob content does not match manifest digest
+
 ## [0.2.0] - 2026-03-31
 
 ### Added

data/Gemfile

@@ -8,5 +8,6 @@ group :test do
   gem 'rspec'
   gem 'rspec_junit_formatter'
   gem 'rubocop'
+  gem 'rubocop-legion'
   gem 'simplecov'
 end

data/README.md

@@ -35,6 +35,12 @@ gem install lex-ollama
 - `check_blob` - Check if a blob exists on the server (HEAD /api/blobs/:digest)
 - `push_blob` - Upload a binary blob to the server (POST /api/blobs/:digest)
 
+### S3 Model Distribution
+- `list_s3_models` - List models available in an S3 mirror
+- `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)
+
 ### Version
 - `server_version` - Retrieve the Ollama server version (GET /api/version)
 
@@ -71,6 +77,34 @@ client.chat_stream(model: 'llama3.2', messages: [{ role: 'user', content: 'Hello
 end
 ```
 
+## S3 Model Distribution
+
+Pull models from an internal S3 mirror instead of the public Ollama registry:
+
+```ruby
+client = Legion::Extensions::Ollama::Client.new
+
+# List available models in S3
+client.list_s3_models(bucket: 'legion', endpoint: 'https://mesh.s3api-core.optum.com')
+
+# Import directly to filesystem (works without Ollama running)
+client.import_from_s3(model: 'llama3:latest', bucket: 'legion',
+                      endpoint: 'https://mesh.s3api-core.optum.com')
+
+# Push through Ollama API (requires Ollama running)
+client.sync_from_s3(model: 'llama3:latest', bucket: 'legion',
+                    endpoint: 'https://mesh.s3api-core.optum.com')
+
+# 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'
+)
+```
+
+S3 operations use [lex-s3](https://github.com/LegionIO/lex-s3). The S3 bucket should mirror the Ollama models directory structure (`manifests/` and `blobs/` under the configured prefix).
+
 All API calls include automatic retry with exponential backoff on connection failures and timeouts.
 
 Generate and chat responses include standardized `usage:` data:

data/docs/plans/2026-04-01-s3-model-distribution-design.md

@@ -0,0 +1,131 @@
+# S3 Model Distribution for lex-ollama
+
+## Problem
+
+Thousands of engineers pulling models from the public Ollama registry is wasteful and unreliable. Models should be cached in internal S3 and distributed from there. Fleet-wide model updates should be broadcast via RabbitMQ.
+
+## Design
+
+### New Runner: `Runners::S3Models`
+
+A new runner module alongside the existing `Models` runner. Three primary methods plus one convenience method.
+
+#### `import_from_s3` (filesystem write)
+
+Downloads manifest + blobs from S3, writes directly to `~/.ollama/models/`.
+
+```ruby
+import_from_s3(
+  model:,                    # e.g. "llama3:latest"
+  bucket:,                   # S3 bucket name
+  prefix: "ollama/models",   # S3 key prefix
+  models_path: nil,          # local Ollama models dir, defaults to ~/.ollama/models
+  **s3_opts                  # passed through to lex-s3 (endpoint:, region:, access_key_id:, etc.)
+)
+```
+
+Flow:
+1. Parse `model` into `name` + `tag` (default tag: `latest`)
+2. Download manifest from S3: `{prefix}/manifests/registry.ollama.ai/library/{name}/{tag}`
+3. Parse manifest JSON to get the list of blob digests
+4. For each blob, check if it already exists locally with matching SHA256 digest (skip if valid)
+5. Stream blob from S3 to `.tmp` file, verify SHA256, atomic rename to final path
+6. Raise `DigestMismatchError` if any blob fails verification (temp file cleaned up)
+7. Write the manifest file
+8. Return `{ result: true, model:, blobs_downloaded:, blobs_skipped:, status: 200 }`
+
+Best for: provisioning, bootstrapping, when Ollama is not yet running.
+
+#### `sync_from_s3` (Ollama API + filesystem manifest)
+
+Downloads from S3, pushes blobs through Ollama's API, writes manifest to filesystem.
+
+```ruby
+sync_from_s3(
+  model:,
+  bucket:,
+  prefix: "ollama/models",
+  host: nil,                   # Ollama server host
+  models_path: nil,            # local models dir for manifest write
+  **s3_opts                    # passed to lex-s3
+)
+```
+
+Flow:
+1. Parse model, download manifest from S3
+2. For each blob digest, `check_blob` via Ollama API -- skip if already present
+3. Stream blob from S3 to tempfile, verify SHA256 digest
+4. `push_blob` to Ollama API, check return value for success
+5. If any blob fails: return `{ result: false, errors: [...], status: 500 }`
+6. Write manifest to `{models_path}/manifests/registry.ollama.ai/library/{name}/{tag}`
+7. Return `{ result: true, model:, blobs_pushed:, blobs_skipped:, status: 200 }`
+
+Best for: when Ollama is running and you want blob validation through the API.
+
+#### `list_s3_models`
+
+Lists available models in the S3 mirror.
+
+```ruby
+list_s3_models(
+  bucket:,
+  prefix: "ollama/models",
+  **s3_opts
+)
+```
+
+Lists manifest keys under the prefix and parses them into model name/tag pairs.
+
+#### `import_default_models`
+
+Convenience method that reads `default_models` from settings and calls `import_from_s3` for each.
+
+### Settings
+
+```yaml
+legion:
+  ollama:
+    s3:
+      bucket: "legion"
+      prefix: "ollama/models"
+      endpoint: "https://mesh.s3api-core.optum.com"
+      region: "us-east-2"
+    default_models:
+      - "llama3:latest"
+      - "nomic-embed-text:latest"
+    models_path: null  # defaults to ~/.ollama/models, respects OLLAMA_MODELS env var
+```
+
+### Dependency
+
+`lex-ollama.gemspec` adds a runtime dependency on `lex-s3` (`>= 0.1`). The `S3Models` runner uses `Legion::Extensions::S3::Client` for all S3 operations.
+
+### Data Flow
+
+```
+S3 (mesh.s3api-core.optum.com)
+  |
+  | HTTPS (direct, no AMQP)
+  v
+Node: S3Models runner
+  |
+  |-- import_from_s3 --> filesystem write to ~/.ollama/models/
+  |-- sync_from_s3   --> Ollama HTTP API (push_blob + create_model)
+```
+
+Fleet broadcast: publish a message to the `ollama.s3_models` queue (natural LEX runner behavior). Each node picks it up and runs the download independently from S3.
+
+### File Layout
+
+```
+lib/legion/extensions/ollama/
+  runners/
+    models.rb          # existing, unchanged
+    s3_models.rb       # NEW
+  client.rb            # updated to include Runners::S3Models
+
+spec/legion/extensions/ollama/runners/
+  s3_models_spec.rb    # NEW
+```
+
+No changes to existing runner methods or the Helpers::Client module.

data/docs/plans/2026-04-01-s3-model-distribution-plan.md

@@ -0,0 +1,655 @@
+# S3 Model Distribution Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add S3-based model distribution to lex-ollama so fleet nodes pull models from internal S3 instead of the public Ollama registry.
+
+**Architecture:** New `Runners::S3Models` module uses `lex-s3` to download Ollama model manifests and blobs from S3. Two pull strategies: filesystem write (fast, works offline) and Ollama API (push_blob + create_model). Fleet broadcast is free via the LEX runner queue.
+
+**Tech Stack:** Ruby, lex-s3 (aws-sdk-s3), Faraday, Ollama REST API
+
+**Design doc:** `docs/plans/2026-04-01-s3-model-distribution-design.md`
+
+---
+
+### Task 1: Add lex-s3 dependency
+
+**Files:**
+- Modify: `lex-ollama.gemspec:29`
+- Modify: `Gemfile` (if present, for local dev)
+
+**Step 1: Add runtime dependency to gemspec**
+
+In `lex-ollama.gemspec`, after the existing `faraday` dependency (line 29), add:
+
+```ruby
+spec.add_dependency 'lex-s3', '>= 0.2'
+```
+
+**Step 2: Run bundle install**
+
+Run: `bundle install`
+Expected: resolves lex-s3 and aws-sdk-s3 successfully
+
+**Step 3: Commit**
+
+```bash
+git add lex-ollama.gemspec Gemfile.lock
+git commit -m "add lex-s3 dependency for s3 model distribution"
+```
+
+---
+
+### Task 2: Create S3Models runner with `list_s3_models`
+
+**Files:**
+- Create: `lib/legion/extensions/ollama/runners/s3_models.rb`
+- Test: `spec/legion/extensions/ollama/runners/s3_models_spec.rb`
+
+**Step 1: Write the failing test for `list_s3_models`**
+
+```ruby
+# spec/legion/extensions/ollama/runners/s3_models_spec.rb
+# frozen_string_literal: true
+
+require 'legion/extensions/s3/client'
+
+RSpec.describe Legion::Extensions::Ollama::Runners::S3Models do
+  let(:client_instance) { Legion::Extensions::Ollama::Client.new }
+  let(:s3_client) { instance_double(Legion::Extensions::S3::Client) }
+
+  before do
+    allow(Legion::Extensions::S3::Client).to receive(:new).and_return(s3_client)
+  end
+
+  describe '#list_s3_models' do
+    it 'lists models from S3 manifest keys' do
+      allow(s3_client).to receive(:list_objects).with(
+        bucket: 'legion',
+        prefix: 'ollama/models/manifests/registry.ollama.ai/library/',
+        max_keys: 1000
+      ).and_return({
+        objects: [
+          { key: 'ollama/models/manifests/registry.ollama.ai/library/llama3/latest', size: 512, last_modified: '2026-04-01' },
+          { key: 'ollama/models/manifests/registry.ollama.ai/library/nomic-embed-text/latest', size: 256, last_modified: '2026-04-01' }
+        ],
+        count: 2
+      })
+
+      result = client_instance.list_s3_models(bucket: 'legion', prefix: 'ollama/models')
+      expect(result[:models]).to eq([
+        { name: 'llama3', tag: 'latest' },
+        { name: 'nomic-embed-text', tag: 'latest' }
+      ])
+      expect(result[:status]).to eq(200)
+    end
+
+    it 'returns empty list when no models exist' do
+      allow(s3_client).to receive(:list_objects).and_return({ objects: [], count: 0 })
+
+      result = client_instance.list_s3_models(bucket: 'legion', prefix: 'ollama/models')
+      expect(result[:models]).to eq([])
+    end
+  end
+end
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/legion/extensions/ollama/runners/s3_models_spec.rb -v`
+Expected: FAIL — `NoMethodError: undefined method 'list_s3_models'`
+
+**Step 3: Write the runner module**
+
+```ruby
+# lib/legion/extensions/ollama/runners/s3_models.rb
+# frozen_string_literal: true
+
+require 'legion/extensions/s3/client'
+require 'legion/extensions/ollama/helpers/client'
+
+module Legion
+  module Extensions
+    module Ollama
+      module Runners
+        module S3Models
+          extend Legion::Extensions::Ollama::Helpers::Client
+
+          OLLAMA_REGISTRY_PREFIX = 'manifests/registry.ollama.ai/library'
+
+          def default_models_path
+            ENV.fetch('OLLAMA_MODELS', File.join(Dir.home, '.ollama', 'models'))
+          end
+
+          def s3_model_client(**s3_opts)
+            Legion::Extensions::S3::Client.new(**s3_opts)
+          end
+
+          def parse_model_ref(model)
+            parts = model.split(':')
+            { name: parts[0], tag: parts[1] || 'latest' }
+          end
+
+          def list_s3_models(bucket:, prefix: 'ollama/models', **s3_opts)
+            s3 = s3_model_client(**s3_opts)
+            manifest_prefix = "#{prefix}/#{OLLAMA_REGISTRY_PREFIX}/"
+            resp = s3.list_objects(bucket: bucket, prefix: manifest_prefix, max_keys: 1000)
+
+            models = resp[:objects].filter_map do |obj|
+              relative = obj[:key].delete_prefix(manifest_prefix)
+              parts = relative.split('/')
+              next unless parts.length == 2
+
+              { name: parts[0], tag: parts[1] }
+            end
+
+            { models: models, status: 200 }
+          end
+
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+        end
+      end
+    end
+  end
+end
+```
+
+**Step 4: Wire into the module loader and Client class**
+
+In `lib/legion/extensions/ollama.rb`, add after the blobs require (line 11):
+
+```ruby
+require 'legion/extensions/ollama/runners/s3_models'
+```
+
+In `lib/legion/extensions/ollama/client.rb`, add after `include Runners::Blobs` (line 21):
+
+```ruby
+include Runners::S3Models
+```
+
+**Step 5: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/legion/extensions/ollama/runners/s3_models_spec.rb -v`
+Expected: 2 examples, 0 failures
+
+**Step 6: Commit**
+
+```bash
+git add lib/legion/extensions/ollama/runners/s3_models.rb \
+        lib/legion/extensions/ollama.rb \
+        lib/legion/extensions/ollama/client.rb \
+        spec/legion/extensions/ollama/runners/s3_models_spec.rb
+git commit -m "add list_s3_models runner for s3 model distribution"
+```
+
+---
+
+### Task 3: Add `import_from_s3` (filesystem write)
+
+**Files:**
+- Modify: `lib/legion/extensions/ollama/runners/s3_models.rb`
+- Modify: `spec/legion/extensions/ollama/runners/s3_models_spec.rb`
+
+**Step 1: Write the failing test**
+
+Add to the s3_models_spec.rb, inside the main describe block:
+
+```ruby
+  describe '#import_from_s3' do
+    let(:models_path) { Dir.mktmpdir('ollama_models') }
+    let(:manifest_body) do
+      {
+        'schemaVersion' => 2,
+        'mediaType' => 'application/vnd.docker.distribution.manifest.v2+json',
+        'config' => { 'digest' => 'sha256:aaa111', 'size' => 100 },
+        'layers' => [
+          { 'digest' => 'sha256:bbb222', 'size' => 4_000_000_000 },
+          { 'digest' => 'sha256:ccc333', 'size' => 512 }
+        ]
+      }
+    end
+    let(:manifest_json) { JSON.generate(manifest_body) }
+
+    after { FileUtils.remove_entry(models_path) }
+
+    it 'downloads manifest and blobs to local filesystem' do
+      allow(s3_client).to receive(:get_object)
+        .with(bucket: 'legion', key: 'ollama/models/manifests/registry.ollama.ai/library/llama3/latest')
+        .and_return({ body: manifest_json, content_type: 'application/json', content_length: manifest_json.length, key: '' })
+
+      %w[sha256:aaa111 sha256:bbb222 sha256:ccc333].each do |digest|
+        file_digest = digest.tr(':', '-')
+        allow(s3_client).to receive(:get_object)
+          .with(bucket: 'legion', key: "ollama/models/blobs/#{file_digest}")
+          .and_return({ body: "blob_data_#{digest}", content_type: 'application/octet-stream', content_length: 10, key: '' })
+      end
+
+      result = client_instance.import_from_s3(model: 'llama3:latest', bucket: 'legion', models_path: models_path)
+
+      expect(result[:result]).to be(true)
+      expect(result[:blobs_downloaded]).to eq(3)
+      expect(result[:status]).to eq(200)
+
+      manifest_file = File.join(models_path, 'manifests', 'registry.ollama.ai', 'library', 'llama3', 'latest')
+      expect(File.exist?(manifest_file)).to be(true)
+      expect(File.read(manifest_file)).to eq(manifest_json)
+
+      expect(File.exist?(File.join(models_path, 'blobs', 'sha256-bbb222'))).to be(true)
+    end
+
+    it 'skips blobs that already exist with matching size' do
+      allow(s3_client).to receive(:get_object)
+        .with(bucket: 'legion', key: 'ollama/models/manifests/registry.ollama.ai/library/llama3/latest')
+        .and_return({ body: manifest_json, content_type: 'application/json', content_length: manifest_json.length, key: '' })
+
+      # Pre-create one blob with matching size
+      blob_dir = File.join(models_path, 'blobs')
+      FileUtils.mkdir_p(blob_dir)
+      File.write(File.join(blob_dir, 'sha256-aaa111'), 'x' * 100)
+
+      # Only the other two blobs should be downloaded
+      %w[sha256:bbb222 sha256:ccc333].each do |digest|
+        file_digest = digest.tr(':', '-')
+        allow(s3_client).to receive(:get_object)
+          .with(bucket: 'legion', key: "ollama/models/blobs/#{file_digest}")
+          .and_return({ body: "blob_data_#{digest}", content_type: 'application/octet-stream', content_length: 10, key: '' })
+      end
+
+      result = client_instance.import_from_s3(model: 'llama3:latest', bucket: 'legion', models_path: models_path)
+
+      expect(result[:blobs_downloaded]).to eq(2)
+      expect(result[:blobs_skipped]).to eq(1)
+    end
+
+    it 'defaults tag to latest when not specified' do
+      allow(s3_client).to receive(:get_object)
+        .with(bucket: 'legion', key: 'ollama/models/manifests/registry.ollama.ai/library/llama3/latest')
+        .and_return({ body: manifest_json, content_type: 'application/json', content_length: manifest_json.length, key: '' })
+
+      %w[sha256:aaa111 sha256:bbb222 sha256:ccc333].each do |digest|
+        file_digest = digest.tr(':', '-')
+        allow(s3_client).to receive(:get_object)
+          .with(bucket: 'legion', key: "ollama/models/blobs/#{file_digest}")
+          .and_return({ body: "blob_data_#{digest}", content_type: 'application/octet-stream', content_length: 10, key: '' })
+      end
+
+      result = client_instance.import_from_s3(model: 'llama3', bucket: 'legion', models_path: models_path)
+      expect(result[:result]).to be(true)
+    end
+  end
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/legion/extensions/ollama/runners/s3_models_spec.rb -v`
+Expected: FAIL — `NoMethodError: undefined method 'import_from_s3'`
+
+**Step 3: Implement `import_from_s3`**
+
+Add to `lib/legion/extensions/ollama/runners/s3_models.rb`, inside the `S3Models` module, before the `include` guard:
+
+```ruby
+          def import_from_s3(model:, bucket:, prefix: 'ollama/models', models_path: nil, **s3_opts)
+            models_path ||= default_models_path
+            ref = parse_model_ref(model)
+            s3 = s3_model_client(**s3_opts)
+
+            manifest_key = "#{prefix}/#{OLLAMA_REGISTRY_PREFIX}/#{ref[:name]}/#{ref[:tag]}"
+            manifest_resp = s3.get_object(bucket: bucket, key: manifest_key)
+            manifest = JSON.parse(manifest_resp[:body])
+
+            all_digests = [manifest['config'], *manifest['layers']].compact
+            downloaded = 0
+            skipped = 0
+
+            all_digests.each do |layer|
+              digest = layer['digest']
+              size = layer['size']
+              file_digest = digest.tr(':', '-')
+              local_path = File.join(models_path, 'blobs', file_digest)
+
+              if File.exist?(local_path) && File.size(local_path) == size
+                skipped += 1
+                next
+              end
+
+              FileUtils.mkdir_p(File.dirname(local_path))
+              blob_resp = s3.get_object(bucket: bucket, key: "#{prefix}/blobs/#{file_digest}")
+              File.binwrite(local_path, blob_resp[:body])
+              downloaded += 1
+            end
+
+            manifest_dir = File.join(models_path, 'manifests', 'registry.ollama.ai', 'library', ref[:name])
+            FileUtils.mkdir_p(manifest_dir)
+            File.write(File.join(manifest_dir, ref[:tag]), manifest_resp[:body])
+
+            { result: true, model: model, blobs_downloaded: downloaded, blobs_skipped: skipped, status: 200 }
+          end
+```
+
+Also add `require 'json'` and `require 'fileutils'` at the top of the file.
+
+**Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/legion/extensions/ollama/runners/s3_models_spec.rb -v`
+Expected: 5 examples, 0 failures
+
+**Step 5: Commit**
+
+```bash
+git add lib/legion/extensions/ollama/runners/s3_models.rb \
+        spec/legion/extensions/ollama/runners/s3_models_spec.rb
+git commit -m "add import_from_s3 for filesystem-based model distribution"
+```
+
+---
+
+### Task 4: Add `sync_from_s3` (Ollama API)
+
+**Files:**
+- Modify: `lib/legion/extensions/ollama/runners/s3_models.rb`
+- Modify: `spec/legion/extensions/ollama/runners/s3_models_spec.rb`
+
+**Step 1: Write the failing test**
+
+Add to the s3_models_spec.rb, inside the main describe block:
+
+```ruby
+  describe '#sync_from_s3' do
+    let(:faraday_conn) { instance_double(Faraday::Connection) }
+    let(:manifest_body) do
+      {
+        'schemaVersion' => 2,
+        'mediaType' => 'application/vnd.docker.distribution.manifest.v2+json',
+        'config' => { 'digest' => 'sha256:aaa111', 'size' => 100 },
+        'layers' => [
+          { 'digest' => 'sha256:bbb222', 'size' => 4_000_000_000, 'mediaType' => 'application/vnd.ollama.image.model' },
+          { 'digest' => 'sha256:ccc333', 'size' => 512, 'mediaType' => 'application/vnd.ollama.image.template' }
+        ]
+      }
+    end
+    let(:manifest_json) { JSON.generate(manifest_body) }
+
+    before do
+      allow(client_instance).to receive(:client).and_return(faraday_conn)
+    end
+
+    it 'pushes blobs through Ollama API and creates model' do
+      allow(s3_client).to receive(:get_object)
+        .with(bucket: 'legion', key: 'ollama/models/manifests/registry.ollama.ai/library/llama3/latest')
+        .and_return({ body: manifest_json, content_type: 'application/json', content_length: manifest_json.length, key: '' })
+
+      # check_blob returns false for all (none cached)
+      %w[sha256:aaa111 sha256:bbb222 sha256:ccc333].each do |digest|
+        allow(faraday_conn).to receive(:head).with("/api/blobs/#{digest}")
+          .and_return(instance_double(Faraday::Response, status: 404))
+
+        file_digest = digest.tr(':', '-')
+        allow(s3_client).to receive(:get_object)
+          .with(bucket: 'legion', key: "ollama/models/blobs/#{file_digest}")
+          .and_return({ body: "blob_data_#{digest}", content_type: 'application/octet-stream', content_length: 10, key: '' })
+
+        allow(faraday_conn).to receive(:post).with("/api/blobs/#{digest}")
+          .and_yield(instance_double(Faraday::Request, headers: {}).tap do |req|
+            allow(req).to receive(:body=)
+            allow(req).to receive(:headers).and_return({})
+          end).and_return(instance_double(Faraday::Response, status: 201))
+      end
+
+      allow(faraday_conn).to receive(:post).with('/api/create', hash_including(model: 'llama3:latest'))
+        .and_return(instance_double(Faraday::Response, body: { 'status' => 'success' }, status: 200))
+
+      result = client_instance.sync_from_s3(model: 'llama3:latest', bucket: 'legion')
+      expect(result[:result]).to be(true)
+      expect(result[:status]).to eq(200)
+    end
+
+    it 'skips blobs already present in Ollama' do
+      allow(s3_client).to receive(:get_object)
+        .with(bucket: 'legion', key: 'ollama/models/manifests/registry.ollama.ai/library/llama3/latest')
+        .and_return({ body: manifest_json, content_type: 'application/json', content_length: manifest_json.length, key: '' })
+
+      # aaa111 already exists, others do not
+      allow(faraday_conn).to receive(:head).with('/api/blobs/sha256:aaa111')
+        .and_return(instance_double(Faraday::Response, status: 200))
+
+      %w[sha256:bbb222 sha256:ccc333].each do |digest|
+        allow(faraday_conn).to receive(:head).with("/api/blobs/#{digest}")
+          .and_return(instance_double(Faraday::Response, status: 404))
+
+        file_digest = digest.tr(':', '-')
+        allow(s3_client).to receive(:get_object)
+          .with(bucket: 'legion', key: "ollama/models/blobs/#{file_digest}")
+          .and_return({ body: "blob_data_#{digest}", content_type: 'application/octet-stream', content_length: 10, key: '' })
+
+        allow(faraday_conn).to receive(:post).with("/api/blobs/#{digest}")
+          .and_yield(instance_double(Faraday::Request, headers: {}).tap do |req|
+            allow(req).to receive(:body=)
+            allow(req).to receive(:headers).and_return({})
+          end).and_return(instance_double(Faraday::Response, status: 201))
+      end
+
+      allow(faraday_conn).to receive(:post).with('/api/create', hash_including(model: 'llama3:latest'))
+        .and_return(instance_double(Faraday::Response, body: { 'status' => 'success' }, status: 200))
+
+      result = client_instance.sync_from_s3(model: 'llama3:latest', bucket: 'legion')
+      expect(result[:result]).to be(true)
+
+      expect(s3_client).not_to have_received(:get_object)
+        .with(bucket: 'legion', key: 'ollama/models/blobs/sha256-aaa111')
+    end
+  end
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/legion/extensions/ollama/runners/s3_models_spec.rb -v`
+Expected: FAIL — `NoMethodError: undefined method 'sync_from_s3'`
+
+**Step 3: Implement `sync_from_s3`**
+
+Add to `lib/legion/extensions/ollama/runners/s3_models.rb`, inside the `S3Models` module:
+
+```ruby
+          def sync_from_s3(model:, bucket:, prefix: 'ollama/models', **opts)
+            ref = parse_model_ref(model)
+            s3_opts = opts.reject { |k, _| k == :host }
+            s3 = s3_model_client(**s3_opts)
+
+            manifest_key = "#{prefix}/#{OLLAMA_REGISTRY_PREFIX}/#{ref[:name]}/#{ref[:tag]}"
+            manifest_resp = s3.get_object(bucket: bucket, key: manifest_key)
+            manifest = JSON.parse(manifest_resp[:body])
+
+            all_digests = [manifest['config'], *manifest['layers']].compact
+
+            all_digests.each do |layer|
+              digest = layer['digest']
+              existing = check_blob(digest: digest, **opts)
+              next if existing[:result]
+
+              file_digest = digest.tr(':', '-')
+              blob_resp = s3.get_object(bucket: bucket, key: "#{prefix}/blobs/#{file_digest}")
+              push_blob(digest: digest, body: blob_resp[:body], **opts)
+            end
+
+            model_name = "#{ref[:name]}:#{ref[:tag]}"
+            create_model(model: model_name, from: model_name, **opts)
+
+            { result: true, model: model_name, status: 200 }
+          end
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/legion/extensions/ollama/runners/s3_models_spec.rb -v`
+Expected: 7 examples, 0 failures
+
+**Step 5: Commit**
+
+```bash
+git add lib/legion/extensions/ollama/runners/s3_models.rb \
+        spec/legion/extensions/ollama/runners/s3_models_spec.rb
+git commit -m "add sync_from_s3 for api-based model distribution"
+```
+
+---
+
+### Task 5: Add `import_default_models` convenience method
+
+**Files:**
+- Modify: `lib/legion/extensions/ollama/runners/s3_models.rb`
+- Modify: `spec/legion/extensions/ollama/runners/s3_models_spec.rb`
+
+**Step 1: Write the failing test**
+
+Add to the s3_models_spec.rb:
+
+```ruby
+  describe '#import_default_models' do
+    let(:models_path) { Dir.mktmpdir('ollama_models') }
+    let(:manifest_body) do
+      {
+        'schemaVersion' => 2,
+        'config' => { 'digest' => 'sha256:aaa111', 'size' => 100 },
+        'layers' => []
+      }
+    end
+    let(:manifest_json) { JSON.generate(manifest_body) }
+
+    after { FileUtils.remove_entry(models_path) }
+
+    it 'imports each model from the default_models list' do
+      allow(s3_client).to receive(:get_object).and_return({
+        body: manifest_json, content_type: 'application/json', content_length: manifest_json.length, key: ''
+      })
+      allow(s3_client).to receive(:get_object)
+        .with(hash_including(key: /blobs/))
+        .and_return({ body: 'data', content_type: 'application/octet-stream', content_length: 4, key: '' })
+
+      result = client_instance.import_default_models(
+        default_models: ['llama3:latest', 'nomic-embed-text:latest'],
+        bucket: 'legion',
+        models_path: models_path
+      )
+
+      expect(result[:result].length).to eq(2)
+      expect(result[:result]).to all(include(result: true))
+      expect(result[:status]).to eq(200)
+    end
+  end
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/legion/extensions/ollama/runners/s3_models_spec.rb -v`
+Expected: FAIL — `NoMethodError: undefined method 'import_default_models'`
+
+**Step 3: Implement `import_default_models`**
+
+Add to the `S3Models` module:
+
+```ruby
+          def import_default_models(default_models:, bucket:, **opts)
+            results = default_models.map do |model|
+              import_from_s3(model: model, bucket: bucket, **opts)
+            end
+
+            { result: results, status: 200 }
+          end
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/legion/extensions/ollama/runners/s3_models_spec.rb -v`
+Expected: 8 examples, 0 failures
+
+**Step 5: Commit**
+
+```bash
+git add lib/legion/extensions/ollama/runners/s3_models.rb \
+        spec/legion/extensions/ollama/runners/s3_models_spec.rb
+git commit -m "add import_default_models convenience method"
+```
+
+---
+
+### Task 6: Update Client spec for new runner methods
+
+**Files:**
+- Modify: `spec/legion/extensions/ollama/client_spec.rb`
+
+**Step 1: Add respond_to expectations**
+
+Add to the `'runner inclusion'` describe block in `client_spec.rb`:
+
+```ruby
+    it { is_expected.to respond_to(:list_s3_models) }
+    it { is_expected.to respond_to(:import_from_s3) }
+    it { is_expected.to respond_to(:sync_from_s3) }
+    it { is_expected.to respond_to(:import_default_models) }
+```
+
+**Step 2: Run full test suite**
+
+Run: `bundle exec rspec -v`
+Expected: all examples pass, 0 failures
+
+**Step 3: Commit**
+
+```bash
+git add spec/legion/extensions/ollama/client_spec.rb
+git commit -m "add s3_models runner inclusion tests to client spec"
+```
+
+---
+
+### Task 7: Run pre-push pipeline
+
+**Step 1: Run full test suite**
+
+Run: `bundle exec rspec`
+Expected: 0 failures
+
+**Step 2: Run rubocop auto-fix**
+
+Run: `bundle exec rubocop -A`
+Stage all modified files.
+
+**Step 3: Run rubocop lint check**
+
+Run: `bundle exec rubocop`
+Expected: 0 offenses
+
+**Step 4: Bump version**
+
+In `lib/legion/extensions/ollama/version.rb`, bump `VERSION` from `'0.2.0'` to `'0.3.0'` (minor bump — new feature).
+
+**Step 5: Update CHANGELOG.md**
+
+Add entry:
+
+```markdown
+## [0.3.0] - 2026-04-01
+
+### Added
+- S3 model distribution via new `Runners::S3Models` module
+- `list_s3_models` to discover models in S3 mirror
+- `import_from_s3` for direct filesystem model import (works without Ollama running)
+- `sync_from_s3` for Ollama API-based model import (push_blob + create_model)
+- `import_default_models` convenience method for fleet provisioning
+- Runtime dependency on `lex-s3` for S3 operations
+```
+
+**Step 6: Update README.md**
+
+Add S3 model distribution section documenting the four new methods and settings.
+
+**Step 7: Commit and push**
+
+```bash
+git add -A
+git commit -m "bump version to 0.3.0, update changelog and readme for s3 model distribution"
+git push # pipeline-complete
+```

data/lex-ollama.gemspec

@@ -27,4 +27,5 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'faraday', '>= 2.0'
+  spec.add_dependency 'lex-s3', '>= 0.2'
 end

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

@@ -6,6 +6,7 @@ require_relative 'runners/chat'
 require_relative 'runners/models'
 require_relative 'runners/embeddings'
 require_relative 'runners/blobs'
+require_relative 'runners/s3_models'
 require_relative 'runners/version'
 
 module Legion
@@ -18,6 +19,7 @@ module Legion
         include Runners::Models
         include Runners::Embeddings
         include Runners::Blobs
+        include Runners::S3Models
         include Runners::Version
 
         attr_reader :opts

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

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'fileutils'
+require 'tempfile'
+require 'legion/extensions/s3/client'
+require 'legion/extensions/ollama/helpers/client'
+require 'legion/extensions/ollama/helpers/errors'
+
+module Legion
+  module Extensions
+    module Ollama
+      module Runners
+        module S3Models
+          extend Legion::Extensions::Ollama::Helpers::Client
+
+          OLLAMA_REGISTRY_PREFIX = 'manifests/registry.ollama.ai/library'
+
+          class DigestMismatchError < StandardError; end
+
+          def list_s3_models(bucket:, prefix: 'ollama/models', **s3_opts)
+            s3 = s3_model_client(**s3_opts)
+            manifest_prefix = "#{prefix}/#{OLLAMA_REGISTRY_PREFIX}/"
+            resp = s3.list_objects(bucket: bucket, prefix: manifest_prefix, max_keys: 1000)
+
+            models = resp[:objects].filter_map do |obj|
+              relative = obj[:key].delete_prefix(manifest_prefix)
+              parts = relative.split('/')
+              next unless parts.length == 2
+
+              { name: parts[0], tag: parts[1] }
+            end
+
+            { models: models, status: 200 }
+          end
+
+          def import_from_s3(model:, bucket:, prefix: 'ollama/models', models_path: nil, **s3_opts)
+            s3 = s3_model_client(**s3_opts)
+            path = models_path || default_models_path
+            ref = parse_model_ref(model)
+            name = ref[:name]
+            tag  = ref[:tag]
+
+            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)
+
+            digests = []
+            digests << manifest_data['config'].slice('digest', 'size')
+            digests.concat(manifest_data['layers'].map { |l| l.slice('digest', 'size') })
+
+            blobs_downloaded = 0
+            blobs_skipped    = 0
+
+            digests.each do |entry|
+              digest = entry['digest']
+              expected_hex = extract_hex(digest)
+              blob_filename = digest.sub(':', '-')
+              local_path    = File.join(path, 'blobs', blob_filename)
+
+              if File.exist?(local_path) && verify_digest(local_path, expected_hex)
+                blobs_skipped += 1
+                next
+              end
+
+              FileUtils.mkdir_p(File.dirname(local_path))
+              download_and_verify_blob(s3, bucket: bucket, key: "#{prefix}/blobs/#{blob_filename}",
+                                           target: local_path, expected_hex: expected_hex)
+              blobs_downloaded += 1
+            end
+
+            manifest_path = File.join(path, 'manifests', 'registry.ollama.ai', 'library', name, tag)
+            FileUtils.mkdir_p(File.dirname(manifest_path))
+            File.binwrite(manifest_path, manifest_body)
+
+            { result: true, model: model, blobs_downloaded: blobs_downloaded, blobs_skipped: blobs_skipped,
+              status: 200 }
+          end
+
+          def sync_from_s3(model:, bucket:, prefix: 'ollama/models', host: nil, models_path: nil, **s3_opts)
+            ollama_opts = host ? { host: host } : {}
+            path = models_path || default_models_path
+            s3 = s3_model_client(**s3_opts)
+            ref = parse_model_ref(model)
+            name = ref[:name]
+            tag  = ref[:tag]
+            model_ref = "#{name}:#{tag}"
+
+            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])
+
+            digests = []
+            digests << manifest_data['config']['digest']
+            digests.concat(manifest_data['layers'].map { |l| l['digest'] })
+
+            blobs_pushed = 0
+            blobs_skipped = 0
+            errors = []
+
+            digests.each do |digest|
+              if check_blob(digest: digest, **ollama_opts)[:result]
+                blobs_skipped += 1
+                next
+              end
+
+              expected_hex = extract_hex(digest)
+              blob_filename = digest.sub(':', '-')
+              tempfile = Tempfile.new(['ollama_blob_', blob_filename], binmode: true)
+              begin
+                stream_s3_to_file(s3, bucket: bucket, key: "#{prefix}/blobs/#{blob_filename}", target: tempfile.path)
+                unless verify_digest(tempfile.path, expected_hex)
+                  errors << { digest: digest, error: 'digest mismatch' }
+                  next
+                end
+                result = push_blob(digest: digest, body: File.binread(tempfile.path), **ollama_opts)
+                unless result[:result]
+                  errors << { digest: digest, status: result[:status] }
+                  next
+                end
+                blobs_pushed += 1
+              ensure
+                tempfile.close
+                tempfile.unlink
+              end
+            end
+
+            return { result: false, model: model_ref, errors: errors, status: 500 } if errors.any?
+
+            manifest_path = File.join(path, 'manifests', 'registry.ollama.ai', 'library', name, tag)
+            FileUtils.mkdir_p(File.dirname(manifest_path))
+            File.binwrite(manifest_path, manifest_resp[:body])
+
+            { result: true, model: model_ref, blobs_pushed: blobs_pushed, blobs_skipped: blobs_skipped,
+              status: 200 }
+          end
+
+          def import_default_models(default_models:, bucket:, **)
+            results = default_models.map do |model|
+              import_from_s3(model: model, bucket: bucket, **)
+            end
+
+            { result: results, status: 200 }
+          end
+
+          private
+
+          def default_models_path
+            ENV.fetch('OLLAMA_MODELS', File.join(Dir.home, '.ollama', 'models'))
+          end
+
+          def s3_model_client(**s3_opts)
+            Legion::Extensions::S3::Client.new(**s3_opts)
+          end
+
+          def parse_model_ref(model)
+            parts = model.split(':')
+            { name: parts[0], tag: parts[1] || 'latest' }
+          end
+
+          def extract_hex(digest)
+            digest.split(':').last
+          end
+
+          def verify_digest(file_path, expected_hex)
+            Digest::SHA256.file(file_path).hexdigest == expected_hex
+          end
+
+          def stream_s3_to_file(s3_inst, bucket:, key:, target:)
+            s3_inst.s3_client.get_object(bucket: bucket, key: key, response_target: target)
+          end
+
+          def download_and_verify_blob(s3_inst, bucket:, key:, target:, expected_hex:)
+            tmpfile = "#{target}.tmp"
+            begin
+              stream_s3_to_file(s3_inst, bucket: bucket, key: key, target: tmpfile)
+              raise DigestMismatchError, "digest mismatch for #{key}: expected sha256:#{expected_hex}" unless verify_digest(tmpfile, expected_hex)
+
+              File.rename(tmpfile, target)
+            rescue StandardError
+              FileUtils.rm_f(tmpfile)
+              raise
+            end
+          end
+
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/ollama.rb

@@ -9,6 +9,7 @@ require 'legion/extensions/ollama/runners/chat'
 require 'legion/extensions/ollama/runners/models'
 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/client'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-ollama
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Esity
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: lex-s3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
 description: Connects LegionIO to Ollama local LLM server
 email:
 - matthewdiverson@gmail.com
@@ -40,6 +54,8 @@ files:
 - Gemfile
 - LICENSE
 - README.md
+- docs/plans/2026-04-01-s3-model-distribution-design.md
+- docs/plans/2026-04-01-s3-model-distribution-plan.md
 - lex-ollama.gemspec
 - lib/legion/extensions/ollama.rb
 - lib/legion/extensions/ollama/client.rb
@@ -51,6 +67,7 @@ files:
 - lib/legion/extensions/ollama/runners/completions.rb
 - lib/legion/extensions/ollama/runners/embeddings.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/version.rb
 homepage: https://github.com/LegionIO/lex-ollama