lex-llm-ollama 0.2.13 → 0.2.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8edb9398901726a46e399fd9a7ab11a9686c3cf76bd6cd7efc2cc48c89005230
-  data.tar.gz: 89e29c003fac6d296e26f9214cde4f93c499cb5f8ccaa065d8270a587f6bb9f5
+  metadata.gz: 8bbec813c20e8b5c62b97209466439569cfcde42251acfe9e87f2bb0fce79e9d
+  data.tar.gz: 59822c6527476ec0000af57ec2a5884672d03065ca3212e0fb655faf809cc0da
 SHA512:
-  metadata.gz: f9a7f5bb4fd18596bec2b301fd92ed49cf4c2fdb77d592d85ef54c834bef8f5a4770c3c7b773c8a50a84737595309439826e6a4c110cf62497c8a61242251edb
-  data.tar.gz: 927d0afc66e6ef69fbf3754defdbb03e4ff6891d71046c4bf722d88cf5c56ec32b573fa4066ce9421c2a51e1b596378f9f8cd906df8f0ea37da9546bd1b610f2
+  metadata.gz: 6f41591f42a566ab7f3344e6d9963393db977dfea257b61c4a4aea798943804cc1db9f9525522cb690e5ab0448bc4b1451ee2ec3a67b615caccb049e84607bc4
+  data.tar.gz: effc50944c4583c1732ea4b23563c2f1ac00f660c0571e6c001403f3a140027303fe3bd77d2e0e64c61db39828a5230f9a35f30e7a1ab8663a3dd4e8b56bc185

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.14 - 2026-06-05
+
+- Verified specs and RuboCop compliance (52 examples, 0 failures; 15 files, 0 offenses)
+- Updated README with comprehensive extension index covering architecture, classes, configuration, and usage
+
 ## 0.2.13 - 2026-06-02
 
 - **Scope discovery refresh to Ollama only** — `DiscoveryRefresh#manual` now calls `Discovery.refresh_discovered_models!(provider: :ollama)` instead of `Discovery.run`, which previously triggered model discovery for all registered providers (anthropic, bedrock, etc.) and caused cross-provider coupling

data/README.md

@@ -2,38 +2,134 @@
 
 LegionIO LLM provider extension for [Ollama](https://ollama.ai).
 
-This gem lives under `Legion::Extensions::Llm::Ollama` and depends on `lex-llm >= 0.4.3` for shared provider-neutral routing, response normalization, fleet envelopes, responder execution, transport, and registry primitives. It does not carry a runtime `legion-llm` dependency; `legion-llm` owns higher-level routing and can discover this provider through normal extension loading.
+This gem lives under `Legion::Extensions::Llm::Ollama` and depends on `lex-llm >= 0.4.3` for shared provider-neutral routing, response normalization, fleet envelopes, responder execution, transport, and registry primitives. It does not carry a runtime `legion-llm` dependency; `legion-llm` owns higher-level routing and discovers this provider through normal extension loading.
 
 Load it with `require 'legion/extensions/llm/ollama'`.
 
 ## What It Provides
 
-- Ollama-native chat requests through `POST /api/chat`
-- Streaming chat support
-- Model discovery through `GET /api/tags` with automatic embedding capability inference
-- Running model inspection through `GET /api/ps`
-- Model details through `POST /api/show`
-- Model download helper through `POST /api/pull`
-- Embeddings through `POST /api/embed`
-- Best-effort `llm.registry` availability events via the shared `Legion::Extensions::Llm::RegistryPublisher`
-- Local socket discovery plus configured instance discovery through the shared `lex-llm` credential sources
-- Provider-owned fleet response handling through `Legion::Extensions::Llm::Fleet::ProviderResponder`
-- Full `Legion::Logging::Helper` integration with structured `handle_exception` in every rescue block
+| Feature | Endpoint | Provider Method |
+|---------|----------|----------------|
+| Chat completion | `POST /api/chat` | Inherited from `Lex-llm` base provider |
+| Streaming chat | `POST /api/chat` | `stream_response` |
+| List models | `GET /api/tags` | `list_models` |
+| Running models | `GET /api/ps` | `list_running_models` |
+| Model details | `POST /api/show` | `show_model`, `fetch_model_detail` |
+| Pull models | `POST /api/pull` | `pull_model` |
+| Embeddings | `POST /api/embed` | Inherited from `Lex-llm` base provider |
+| Readiness check | `GET /api/version` | `readiness(live: false)` |
+
+All responses pass through the shared `Lex-llm` normalization layer: `Message`, `Chunk`, `Embedding`, and `Model::Info`.
+
+## File Index
+
+```
+lib/
+  legion/extensions/llm/ollama.rb              # Extension entry point, instance discovery, default settings
+  legion/extensions/llm/ollama/provider.rb     # Provider — chat, stream, embed, models, offerings
+  legion/extensions/llm/ollama/version.rb      # VERSION constant
+  legion/extensions/llm/ollama/actors/
+    discovery_refresh.rb                       # Periodic model discovery actor (Every, 30min default)
+    fleet_worker.rb                            # Fleet request subscription actor (Subscription)
+  legion/extensions/llm/ollama/runners/
+    fleet_worker.rb                            # Fleet request execution runner (delegates to lex-llm)
+```
 
 ## Architecture
 
 ```
 Legion::Extensions::Llm::Ollama
-├── Provider                   # Ollama provider (chat, stream, embed, models, readiness)
-├── Actor::FleetWorker         # Optional provider-owned fleet subscription actor
-├── Runners::FleetWorker       # Delegates fleet execution to lex-llm
-└── (shared from lex-llm)
-    ├── Fleet::ProviderResponder
-    ├── RegistryPublisher
-    ├── RegistryEventBuilder
-    └── Transport/
+├── Provider                          # Ollama provider implementation
+│   ├── Capabilities                  # Capability predicates (chat, streaming, vision, functions, embeddings)
+│   ├── #render_payload               # Build Ollama chat payload from messages, tools, schema
+│   ├── #stream_response              # NDJSON streaming via Faraday on_data
+│   ├── #discover_offerings           # Build ModelOffering array from live/cached models
+│   ├── #fetch_model_detail           # Call /api/show, extract context_window + capabilities
+│   ├── #render_embedding_payload     # Build Ollama embedding payload
+│   └── (inherited from lex-llm)      # Chat, embedding, connection, registry helpers
+├── Actor::DiscoveryRefresh           # Every actor; refreshes model list, repopulates auto rules
+├── Actor::FleetWorker                # Subscription actor; gates on respond_to_requests
+└── Runners::FleetWorker              # Module function; delegates to ProviderResponder.call
+
+Shared from lex-llm:
+├── Fleet::ProviderResponder          # Fleet request execution harness
+├── RegistryPublisher                 # Publishes readiness + model events to llm.registry
+├── RegistryEventBuilder              # Builds registry event payloads
+├── AutoRegistration                  # Self-registers discovered instances
+└── CredentialSources                 # Socket probing + setting lookup for instance discovery
 ```
 
+## Key Classes
+
+### `Legion::Extensions::Llm::Ollama` (module)
+
+- **`default_settings`** — Returns the full settings schema via `Lex-llm.provider_settings`.
+- **`provider_class`** — Returns `Provider`.
+- **`discover_instances`** — Probes `127.0.0.1:11434` socket + reads configured instances from settings.
+- **`normalize_instance_config(config)`** — Normalizes `endpoint`/`api_base`/`ollama_api_base` aliases to `base_url`.
+- **`registry_publisher`** — Lazily instantiated `RegistryPublisher` for the `:ollama` family.
+
+### `Provider`
+
+Extends `Legion::Extensions::Llm::Provider`. Implements the Ollama-specific contract:
+
+| Method | Purpose |
+|--------|---------|
+| `api_base` | Resolves base URL from `resolve_base_url`, settings, or default `127.0.0.1:11434` |
+| `completion_url` | `/api/chat` |
+| `stream_url` | `/api/chat` |
+| `models_url` | `/api/tags` |
+| `running_models_url` | `/api/ps` |
+| `show_model_url` | `/api/show` |
+| `embedding_url` | `/api/embed` |
+| `pull_url` | `/api/pull` |
+| `version_url` | `/api/version` |
+| `list_running_models` | GET `/api/ps`, returns array of running model hashes |
+| `readiness(live:)` | Checks Ollama version endpoint; publishes readiness event when `live: true` |
+| `list_models` | GET `/api/tags`, parses and publishes model events via registry |
+| `show_model(model)` | POST `/api/show`, returns raw model detail hash |
+| `fetch_model_detail(model)` | Wraps `show_model`; extracts `context_window` and `capabilities` |
+| `pull_model(model, stream:)` | POST `/api/pull` to download a model |
+| `discover_offerings(live:)` | Builds `ModelOffering` array from live or cached models |
+| `render_payload(...)` | Converts Legion messages/tools to Ollama NDJSON format |
+| `stream_response(conn, payload)` | Posts with Faraday `on_data` handler for NDJSON streaming |
+| `parse_completion_response(resp)` | Normalizes Ollama chat response to `Legion::Extensions::Llm::Message` |
+| `build_chunk(data)` | Normalizes a stream NDJSON line to `Legion::Extensions::Llm::Chunk` |
+| `render_embedding_payload(text, model:, dimensions:)` | Builds embedding request body |
+| `parse_embedding_response(resp, ...)` | Normalizes embedding response to `Legion::Extensions::Llm::Embedding` |
+
+### `Capabilities` (module inside Provider)
+
+Module functions providing capability predicates used during offering construction:
+
+| Method | Always Returns |
+|--------|---------------|
+| `chat?(model)` | `true` |
+| `streaming?(model)` | `true` |
+| `vision?(model)` | `true` |
+| `functions?(model)` | `true` |
+| `embeddings?(model)` | `true` |
+
+### `CONTEXT_WINDOWS` (constant)
+
+Static fallback map keyed by model name prefix (e.g., `'qwen3' => 128_000`). Used when `/api/show` is unavailable to infer context window. Covers qwen, llama, gemma, mistral, deepseek, phi, command-r, codellama, and embedding families.
+
+### `Actor::DiscoveryRefresh`
+
+An `Every` actor that runs every 30 minutes (configurable via `settings[:extensions][:llm][:ollama][:discovery_interval]`). On each tick:
+
+1. Calls `Legion::LLM::Discovery.refresh_discovered_models!(provider: :ollama)`
+2. Repopulates auto routing rules if `Legion::LLM::Router` is available
+3. Invalidates the offerings cache if `Legion::LLM::Inventory` is available
+
+### `Actor::FleetWorker`
+
+A `Subscription` actor that starts only when at least one instance has `fleet.respond_to_requests: true`. Routes messages to the fleet worker runner.
+
+### `Runners::FleetWorker`
+
+A module with `handle_fleet_request(payload, delivery:, properties:)`. Delegates to `Legion::Extensions::Llm::Fleet::ProviderResponder.call` with the Ollama provider family, provider class, and instance discovery lambda.
+
 ## Defaults
 
 ```ruby
@@ -65,21 +161,24 @@ Legion::Extensions::Llm::Ollama.default_settings
 
 ## Configuration
 
-`discover_instances` returns a local `http://127.0.0.1:11434` instance when the Ollama socket is reachable. Additional instances can be supplied under the shared LLM extension configuration and may use `base_url`, `endpoint`, `api_base`, or `ollama_api_base`; the extension normalizes those aliases to `base_url`.
+### Instance Discovery
+
+`discover_instances` auto-detects a local instance when the socket at `127.0.0.1:11434` is reachable. Additional instances can be defined in settings using any of the recognized endpoint aliases (`base_url`, `endpoint`, `api_base`, `ollama_api_base`); the extension normalizes all to `base_url`.
 
 ```yaml
 extensions:
   llm:
     ollama:
+      discovery_interval: 1800          # DiscoveryRefresh actor interval (seconds)
       instances:
         lab:
           base_url: http://ollama-lab:11434
           default_model: qwen3.5:latest
 ```
 
-## Fleet Responder
+### Fleet Responder
 
-Provider instances can opt in to consuming Legion LLM fleet requests. The provider-owned fleet actor only starts when at least one discovered instance enables `respond_to_requests`, and the runner delegates execution to the shared `lex-llm` responder helper.
+Provider instances can opt in to consuming Legion LLM fleet requests. The fleet actor only starts when at least one instance enables `respond_to_requests`, and the runner delegates execution to the shared `lex-llm` responder helper.
 
 ```yaml
 extensions:
@@ -96,14 +195,76 @@ extensions:
               - embed
 ```
 
+## Ollama API Surface
+
+| Legion Method | Ollama Route | HTTP Verb |
+|---------------|-------------|-----------|
+| Chat | `/api/chat` | POST |
+| Stream chat | `/api/chat` | POST |
+| List models | `/api/tags` | GET |
+| Running models | `/api/ps` | GET |
+| Model details | `/api/show` | POST |
+| Pull model | `/api/pull` | POST |
+| Embeddings | `/api/embed` | POST |
+| Readiness | `/api/version` | GET |
+
+## Error Handling
+
+Every rescue block uses `handle_exception` from `Legion::Logging::Helper` with explicit `level`, `handled:`, and `operation:` parameters. Connection failures during `discover_offerings` produce a warn-level log and return an empty array (never raise).
+
+## Usage
+
+```ruby
+require 'legion/extensions/llm/ollama'
+
+# Access the module
+Legion::Extensions::Llm::Ollama.discover_instances
+Legion::Extensions::Llm::Ollama.default_settings
+
+# Create a provider instance (usually done by lex-llm routing)
+provider = Legion::Extensions::Llm::Ollama::Provider.new(config:)
+
+# Discover offerings
+provider.discover_offerings(live: true)
+
+# Chat
+result = provider.chat(messages: [...], model: 'llama3', temperature: 0.7)
+
+# Stream chat
+provider.stream_chat(messages: [...], model: 'llama3') do |chunk|
+  print chunk.content
+end
+
+# Embeddings
+embeddings = provider.embed(text: "Hello world", model: 'nomic-embed-text')
+```
+
+## Dependencies
+
+| Gem | Minimum Version | Purpose |
+|-----|----------------|---------|
+| `lex-llm` | `>= 0.4.3` | Base provider contract, routing, fleet responder, registry, credential sources |
+| `legion-transport` | `>= 1.4.14` | Faraday connection management |
+| `legion-json` | — | JSON serialization (`Legion::JSON`) |
+| `legion-logging` | — | Structured logging (`Legion::Logging::Helper`) |
+| `legion-settings` | — | Configuration access |
+| `legion-extensions` | — | Extension framework (`Core`, `Actors::Every`, `Actors::Subscription`) |
+
 ## Development
 
 ```bash
+cd /Users/matt.iverson@optum.com/rubymine/legion/extensions-ai/lex-llm-ollama
 bundle install
-bundle exec rspec --format json --out tmp/rspec_results.json --format progress --out tmp/rspec_progress.txt
+
+# Run specs
+bundle exec rspec
+
+# Lint (auto-correct)
 bundle exec rubocop -A
 ```
 
+Spec count: 52 examples across 7 spec files.
+
 ## License
 
 MIT

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Ollama
-        VERSION = '0.2.13'
+        VERSION = '0.2.14'
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-ollama
 version: !ruby/object:Gem::Version
-  version: 0.2.13
+  version: 0.2.14
 platform: ruby
 authors:
 - LegionIO