lex-llm-openai 0.1.7 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0846dcde3031149be5687b648947d0ad1d450e8ff7cb20684d6cc0dd1754fc78'
-  data.tar.gz: ccd47540f56d1d8b7f43bcafb42dc2e0b5edc22e4083d216780d82731d94aa5d
+  metadata.gz: 3adf2416815789eee25cb13dc0ceaadda14549fa6f897ea8c0216a5ebd728793
+  data.tar.gz: 317ad6bcc34b252a9026e9aaae5a9a6fe8f850ab67c7e50e62f67a5c43d3538f
 SHA512:
-  metadata.gz: ba683c96276ec71d4f420688e60613a2db35a22c0af2e726050ce1b1ff2b4f8323fc541581d67cae81317252bc561bb9922c2ac45fd7068d8e09b134c15a9e34
-  data.tar.gz: 7ec2d0bac937e45460281501bd74c41c08ab987f48c631c82fe41ea77d2bc59b53a2974bbff5e5d3185dcd65905b34cca7cbcf6af73ea2e6af142506560d597d
+  metadata.gz: 6e5b1684b8a9a328278bb0ab039940f924f43943847fe45d0b485c82702f4cbb426b142e751d407ed736778b9923bfffd8e8b323549bef335c99056f989c4250
+  data.tar.gz: 0ff1be0c6ccd2fa4e24a3c9bb8dc816e6dc249ff6a88177240be0f5fc4aedade94cb9955d752f28570af099a64e2dea232e3d7bdef0587ab7ef8a308dbe23684

data/.rubocop.yml

@@ -12,7 +12,11 @@ Metrics/BlockLength:
   Exclude:
     - "*.gemspec"
     - spec/**/*
+Metrics/ClassLength:
+  Max: 200
 Metrics/MethodLength:
   Enabled: false
+RSpec/ExampleLength:
+  Max: 10
 RSpec/MultipleExpectations:
   Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.2.0] - 2026-04-30
+- **BREAKING**: Adopt base contract from lex-llm 0.1.9; require `lex-llm >= 0.1.9`
+- Replace `provider_settings`-based `default_settings` with flat provider defaults (enabled, default_model, api_key, etc.)
+- Remove deprecated `Provider.register` call; configuration options are now registered at class-load time
+- Delete local `RegistryPublisher` and `RegistryEventBuilder`; use parameterized base classes from lex-llm
+- Delete local `transport/` directory (exchanges, messages); use shared transport from lex-llm
+- Add static `CAPABILITY_MAP` for known OpenAI model families; `list_models` now returns `Model::Info` structs directly
+- `list_models` no longer delegates to `parse_list_models_response`; builds `Model::Info` via the static capability map
+
+## [0.1.8] - 2026-04-30
+- Add Legion::Logging::Helper to all modules and classes for structured observability
+- Replace bare rescue blocks with handle_exception for unified error telemetry
+- Add info-level action logging for provider registration, model listing, model retrieval, and registry publishing
+- Remove manual log_publish_failure helper in favor of handle_exception
+- Update README to reflect current capabilities and architecture
+
 ## [0.1.7] - 2026-04-30
 - Enable stream_usage_supported? for streaming token usage reporting
 

data/README.md

@@ -9,19 +9,42 @@ Load it with `require 'legion/extensions/llm/openai'`.
 ## What It Provides
 
 - `Legion::Extensions::Llm::Provider` registration as `:openai`
-- chat completions through `POST /v1/chat/completions`
-- streaming chat completions through the same chat completions endpoint
-- model discovery through `GET /v1/models`
-- model retrieval through `GET /v1/models/{model}`
-- embeddings through `POST /v1/embeddings`
-- moderation through `POST /v1/moderations`
-- image generation through `POST /v1/images/generations`
-- image editing through `POST /v1/images/edits`
-- image variation endpoint helper for `POST /v1/images/variations`
-- audio transcription through `POST /v1/audio/transcriptions`
-- shared OpenAI-compatible request/response mapping via `Legion::Extensions::Llm::Provider::OpenAICompatible`
-- normalized chat, embedding, moderation, image, and audio capability mapping for discovered models
-- shared fleet/default settings via `Legion::Extensions::Llm.provider_settings`
+- Chat completions via `POST /v1/chat/completions`
+- Streaming chat completions (same endpoint, `stream: true`)
+- Model discovery via `GET /v1/models`
+- Model retrieval via `GET /v1/models/{model}`
+- Embeddings via `POST /v1/embeddings`
+- Moderation via `POST /v1/moderations`
+- Image generation via `POST /v1/images/generations`
+- Image editing via `POST /v1/images/edits`
+- Image variation via `POST /v1/images/variations`
+- Audio transcription via `POST /v1/audio/transcriptions`
+- Streaming token usage reporting (`stream_usage_supported?`)
+- Shared OpenAI-compatible request/response mapping via `Legion::Extensions::Llm::Provider::OpenAICompatible`
+- Normalized chat, embedding, moderation, image, and audio capability mapping for discovered models
+- Shared fleet/default settings via `Legion::Extensions::Llm.provider_settings`
+- Best-effort `llm.registry` availability event publishing for discovered models
+
+## Architecture
+
+```
+Legion::Extensions::Llm::Openai
+├── Provider                              # OpenAI provider implementation (chat, models, embeddings, etc.)
+│   └── Capabilities                      # Model family capability predicates
+├── RegistryPublisher                     # Async llm.registry event publisher
+├── RegistryEventBuilder                  # Sanitized registry event envelope builder
+└── Transport
+    ├── Exchanges::LlmRegistry            # Topic exchange for llm.registry
+    └── Messages::RegistryEvent           # AMQP message for registry events
+```
+
+## Observability
+
+All classes include `Legion::Logging::Helper` (when available) providing:
+
+- Structured `handle_exception` calls on every rescue block
+- Info-level action logging for provider registration, model listing, model retrieval, and registry publishing
+- Automatic log segment derivation and component type tagging
 
 ## Defaults
 
@@ -47,6 +70,9 @@ Legion::Extensions::Llm::Openai.default_settings
 ```ruby
 Legion::Extensions::Llm.configure do |config|
   config.openai_api_key = ENV.fetch("OPENAI_API_KEY")
+  config.openai_api_base = nil                          # defaults to https://api.openai.com
+  config.openai_organization_id = nil                   # optional OpenAI-Organization header
+  config.openai_project_id = nil                        # optional OpenAI-Project header
   config.default_model = "gpt-5.2"
   config.default_embedding_model = "text-embedding-3-small"
   config.default_moderation_model = "omni-moderation-latest"
@@ -54,3 +80,25 @@ Legion::Extensions::Llm.configure do |config|
   config.default_transcription_model = "gpt-4o-transcribe"
 end
 ```
+
+## Dependencies
+
+| Gem | Purpose |
+|-----|---------|
+| `lex-llm` (>= 0.1.5) | Shared provider contract, fleet settings, routing |
+| `legion-json` (>= 1.2.1) | JSON serialization |
+| `legion-logging` (>= 1.3.2) | Structured logging via Helper |
+| `legion-settings` (>= 1.3.14) | Configuration management |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec --format progress   # all pass
+bundle exec rubocop -A                # auto-fix
+bundle exec rubocop                   # lint check (0 offenses)
+```
+
+## License
+
+MIT

data/lex-llm-openai.gemspec

@@ -26,5 +26,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-json', '>= 1.2.1'
   spec.add_dependency 'legion-logging', '>= 1.3.2'
   spec.add_dependency 'legion-settings', '>= 1.3.14'
-  spec.add_dependency 'lex-llm', '>= 0.1.5'
+  spec.add_dependency 'lex-llm', '>= 0.2.0'
 end

data/lib/legion/extensions/llm/openai/provider.rb

@@ -9,6 +9,84 @@ module Legion
         # OpenAI provider implementation for the Legion::Extensions::Llm base provider contract.
         class Provider < Legion::Extensions::Llm::Provider
           include Legion::Extensions::Llm::Provider::OpenAICompatible
+          include Legion::Logging::Helper
+
+          # ── Static capability map for known OpenAI model families ──────
+          # Maps model-id prefixes to a set of capabilities and modality
+          # vectors. Used by list_models to build Model::Info structs from
+          # the raw /v1/models response.
+          CAPABILITY_MAP = {
+            'gpt-4o' => {
+              capabilities: %i[completion streaming function_calling vision structured_output],
+              modalities_input: %w[text image audio],
+              modalities_output: %w[text]
+            },
+            'gpt-4.1' => {
+              capabilities: %i[completion streaming function_calling vision structured_output],
+              modalities_input: %w[text image],
+              modalities_output: %w[text]
+            },
+            'gpt-4' => {
+              capabilities: %i[completion streaming function_calling vision],
+              modalities_input: %w[text image],
+              modalities_output: %w[text]
+            },
+            'gpt-5' => {
+              capabilities: %i[completion streaming function_calling vision structured_output reasoning],
+              modalities_input: %w[text image],
+              modalities_output: %w[text]
+            },
+            'o4' => {
+              capabilities: %i[completion streaming function_calling vision reasoning],
+              modalities_input: %w[text image],
+              modalities_output: %w[text]
+            },
+            'o3' => {
+              capabilities: %i[completion streaming function_calling vision reasoning],
+              modalities_input: %w[text image],
+              modalities_output: %w[text]
+            },
+            'o1' => {
+              capabilities: %i[completion streaming function_calling vision reasoning],
+              modalities_input: %w[text image],
+              modalities_output: %w[text]
+            },
+            'text-embedding-' => {
+              capabilities: %i[embedding],
+              modalities_input: %w[text],
+              modalities_output: %w[embeddings]
+            },
+            'omni-moderation' => {
+              capabilities: %i[moderation],
+              modalities_input: %w[text image],
+              modalities_output: %w[moderation]
+            },
+            'text-moderation' => {
+              capabilities: %i[moderation],
+              modalities_input: %w[text],
+              modalities_output: %w[moderation]
+            },
+            'gpt-image' => {
+              capabilities: %i[image_generation],
+              modalities_input: %w[text image],
+              modalities_output: %w[image]
+            },
+            'dall-e' => {
+              capabilities: %i[image_generation],
+              modalities_input: %w[text],
+              modalities_output: %w[image]
+            },
+            'whisper' => {
+              capabilities: %i[audio_transcription],
+              modalities_input: %w[audio],
+              modalities_output: %w[text]
+            },
+            'tts' => {
+              capabilities: %i[audio_generation],
+              modalities_input: %w[text],
+              modalities_output: %w[audio]
+            }
+          }.freeze
 
           class << self
             attr_writer :registry_publisher
@@ -29,7 +107,7 @@ module Legion
             def capabilities = Capabilities
 
             def registry_publisher
-              @registry_publisher ||= RegistryPublisher.new
+              @registry_publisher ||= Legion::Extensions::Llm::RegistryPublisher.new(provider_family: :openai)
             end
           end
 
@@ -94,17 +172,66 @@ module Legion
           def images_url(with: nil, mask: nil) = super
 
           def retrieve_model(model)
+            log.info("Retrieving model: #{model}")
             connection.get("#{models_url}/#{model}").body
+          rescue StandardError => e
+            handle_exception(e, level: :error, handled: true,
+                                operation: 'retrieve_model')
+            raise
           end
 
           def list_models
-            super.tap do |models|
-              self.class.registry_publisher.publish_models_async(models, readiness: readiness(live: false))
-            end
+            log.info('Listing OpenAI models')
+            raw = connection.get(models_url)
+            models = build_model_infos(raw.body)
+            log.info("Discovered #{models.size} OpenAI models")
+            self.class.registry_publisher.publish_models_async(models, readiness: readiness(live: false))
+            models
+          rescue StandardError => e
+            handle_exception(e, level: :error, handled: true,
+                                operation: 'list_models')
+            raise
           end
 
           private
 
+          def build_model_infos(body)
+            body.fetch('data', []).map do |raw_model|
+              id = raw_model.fetch('id')
+              cap_entry = capability_entry_for(id)
+
+              Legion::Extensions::Llm::Model::Info.new(
+                id: id,
+                name: id,
+                provider: :openai,
+                capabilities: cap_entry[:capabilities],
+                modalities_input: cap_entry[:modalities_input],
+                modalities_output: cap_entry[:modalities_output],
+                metadata: {
+                  created_at: model_created_at(raw_model['created']),
+                  raw: raw_model
+                }.compact
+              )
+            end
+          end
+
+          def capability_entry_for(model_id)
+            CAPABILITY_MAP.each do |prefix, entry|
+              return entry if model_id.start_with?(prefix)
+            end
+
+            # Fallback for unknown models: assume chat-capable
+            {
+              capabilities: %i[completion streaming],
+              modalities_input: %w[text],
+              modalities_output: %w[text]
+            }
+          end
+
+          def model_created_at(value)
+            value.is_a?(Numeric) ? Time.at(value).utc : value
+          end
+
           def maybe_normalize_temperature(temperature, model)
             model_id = model.id.to_s
             return nil if model_id.include?('-search')
@@ -117,3 +244,8 @@ module Legion
     end
   end
 end
+
+# Register configuration options so Legion::Extensions::Llm::Configuration knows about them.
+Legion::Extensions::Llm::Configuration.register_provider_options(
+  Legion::Extensions::Llm::Openai::Provider.configuration_options
+)

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Openai
-        VERSION = '0.1.7'
+        VERSION = '0.2.0'
       end
     end
   end

data/lib/legion/extensions/llm/openai.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require 'legion/extensions/llm'
-require 'legion/extensions/llm/openai/registry_event_builder'
-require 'legion/extensions/llm/openai/registry_publisher'
 require 'legion/extensions/llm/openai/provider'
 require 'legion/extensions/llm/openai/version'
 
@@ -12,21 +10,23 @@ module Legion
       # Openai provider extension namespace.
       module Openai
         extend ::Legion::Extensions::Core if ::Legion::Extensions.const_defined?(:Core, false)
+        extend ::Legion::Logging::Helper
 
         PROVIDER_FAMILY = :openai
 
         def self.default_settings
-          ::Legion::Extensions::Llm.provider_settings(
-            family: PROVIDER_FAMILY,
-            instance: {
-              endpoint: 'https://api.openai.com',
-              tier: :frontier,
-              transport: :http,
-              credentials: { api_key: 'env://OPENAI_API_KEY' },
-              usage: { inference: true, embedding: true, moderation: true, image: true, audio: true },
-              limits: { concurrency: 4 }
-            }
-          )
+          {
+            enabled: false,
+            default_model: 'gpt-4o',
+            api_key: nil,
+            organization_id: nil,
+            project_id: nil,
+            model_whitelist: [],
+            model_blacklist: [],
+            model_cache_ttl: 3600,
+            tls: { enabled: false, verify: :peer },
+            instances: {}
+          }
         end
 
         def self.provider_class
@@ -36,6 +36,3 @@ module Legion
     end
   end
 end
-
-Legion::Extensions::Llm::Provider.register(Legion::Extensions::Llm::Openai::PROVIDER_FAMILY,
-                                           Legion::Extensions::Llm::Openai::Provider)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-openai
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.2.0
 platform: ruby
 authors:
 - LegionIO
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: 0.2.0
 description: OpenAI provider integration for the LegionIO LLM routing framework.
 email:
 - matthewdiverson@gmail.com
@@ -84,10 +84,6 @@ files:
 - lex-llm-openai.gemspec
 - lib/legion/extensions/llm/openai.rb
 - lib/legion/extensions/llm/openai/provider.rb
-- lib/legion/extensions/llm/openai/registry_event_builder.rb
-- lib/legion/extensions/llm/openai/registry_publisher.rb
-- lib/legion/extensions/llm/openai/transport/exchanges/llm_registry.rb
-- lib/legion/extensions/llm/openai/transport/messages/registry_event.rb
 - lib/legion/extensions/llm/openai/version.rb
 homepage: https://github.com/LegionIO/lex-llm-openai
 licenses:

data/lib/legion/extensions/llm/openai/registry_event_builder.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Llm
-      module Openai
-        # Builds sanitized lex-llm registry envelopes for OpenAI provider state.
-        class RegistryEventBuilder
-          def model_available(model, readiness:)
-            registry_event_class.available(
-              model_offering(model),
-              runtime: runtime_metadata,
-              health: model_health(readiness),
-              metadata: model_metadata(model)
-            )
-          end
-
-          private
-
-          def model_offering(model)
-            {
-              provider_family: :openai,
-              provider_instance: provider_instance,
-              transport: :http,
-              model: model.id,
-              usage_type: usage_type_for(model),
-              capabilities: Array(model.capabilities).map(&:to_sym),
-              limits: model_limits(model),
-              metadata: { lex: :llm_openai, model_name: model.name }.compact
-            }
-          end
-
-          def model_health(readiness)
-            ready = readiness.fetch(:ready, true) == true
-            { ready:, status: ready ? :available : :degraded }
-          end
-
-          def model_metadata(model)
-            { extension: :lex_llm_openai, provider: :openai, model_type: model.type }
-          end
-
-          def runtime_metadata
-            { node: provider_instance }
-          end
-
-          def model_limits(model)
-            {
-              context_window: model.context_window,
-              max_output_tokens: model.max_output_tokens
-            }.compact
-          end
-
-          def usage_type_for(model)
-            model.type == 'embedding' ? :embedding : :inference
-          end
-
-          def provider_instance
-            configured_node = (::Legion::Settings.dig(:node, :canonical_name) if defined?(::Legion::Settings))
-            value = configured_node.to_s.strip
-            value.empty? ? :openai : value.to_sym
-          rescue StandardError
-            :openai
-          end
-
-          def registry_event_class
-            ::Legion::Extensions::Llm::Routing::RegistryEvent
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/llm/openai/registry_publisher.rb

@@ -1,96 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Llm
-      module Openai
-        # Best-effort publisher for OpenAI provider availability events.
-        class RegistryPublisher
-          APP_ID = 'lex-llm-openai'
-
-          def initialize(builder: RegistryEventBuilder.new)
-            @builder = builder
-          end
-
-          def publish_models_async(models, readiness:)
-            schedule do
-              Array(models).each do |model|
-                publish_event(@builder.model_available(model, readiness:))
-              end
-            end
-          end
-
-          private
-
-          def schedule(&)
-            return false unless publishing_available?
-
-            Thread.new do
-              Thread.current.abort_on_exception = false
-              yield
-            rescue StandardError => e
-              log_publish_failure(e, level: :debug)
-            end
-          rescue StandardError => e
-            log_publish_failure(e, level: :debug)
-            false
-          end
-
-          def publish_event(event)
-            return false unless publishing_available?
-
-            message_class.new(event:, app_id: APP_ID).publish(spool: false)
-          rescue StandardError => e
-            log_publish_failure(e)
-            false
-          end
-
-          def publishing_available?
-            return false unless registry_event_available?
-            return false unless transport_message_available?
-            return true unless defined?(::Legion::Transport::Connection)
-            return true unless ::Legion::Transport::Connection.respond_to?(:session_open?)
-
-            ::Legion::Transport::Connection.session_open?
-          rescue StandardError
-            false
-          end
-
-          def registry_event_available?
-            defined?(::Legion::Extensions::Llm::Routing::RegistryEvent)
-          end
-
-          def transport_message_available?
-            return true if message_class_defined?
-            return false unless defined?(::Legion::Transport::Message) && defined?(::Legion::Transport::Exchange)
-
-            require 'legion/extensions/llm/openai/transport/messages/registry_event'
-            message_class_defined?
-          rescue LoadError
-            false
-          end
-
-          def message_class_defined?
-            defined?(::Legion::Extensions::Llm::Openai::Transport::Messages::RegistryEvent)
-          end
-
-          def message_class
-            ::Legion::Extensions::Llm::Openai::Transport::Messages::RegistryEvent
-          end
-
-          def log_publish_failure(error, level: :warn)
-            message = "[lex-llm-openai] llm.registry publish failed: #{error.class}: #{error.message}"
-            logger = ::Legion::Extensions::Llm.logger if defined?(::Legion::Extensions::Llm)
-            if logger.respond_to?(level)
-              logger.public_send(level, message)
-            elsif logger.respond_to?(:debug)
-              logger.debug(message)
-            end
-          rescue StandardError
-            nil
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/llm/openai/transport/exchanges/llm_registry.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Llm
-      module Openai
-        module Transport
-          module Exchanges
-            # Topic exchange for OpenAI provider availability events.
-            class LlmRegistry < ::Legion::Transport::Exchange
-              def exchange_name
-                'llm.registry'
-              end
-
-              def default_type
-                'topic'
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/llm/openai/transport/messages/registry_event.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-require 'legion/extensions/llm/openai/transport/exchanges/llm_registry'
-
-module Legion
-  module Extensions
-    module Llm
-      module Openai
-        module Transport
-          module Messages
-            # Publishes lex-llm RegistryEvent envelopes to the llm.registry exchange.
-            class RegistryEvent < ::Legion::Transport::Message
-              def initialize(event:, **options)
-                super(**event.to_h.merge(options))
-              end
-
-              def exchange
-                Transport::Exchanges::LlmRegistry
-              end
-
-              def routing_key
-                @options[:routing_key] || "llm.registry.#{@options.fetch(:event_type)}"
-              end
-
-              def type
-                'llm.registry.event'
-              end
-
-              def app_id
-                @options[:app_id] || RegistryPublisher::APP_ID
-              end
-
-              def persistent # rubocop:disable Naming/PredicateMethod
-                false
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-end