lex-llm-openai 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aab8c5aaa3a502b204f0f97f9eb28672a81d18464090f22eb1f7afd1e1d4a95e
-  data.tar.gz: d4dfda3e0961f241fd71e8f0d3a1a8612ee5911efbe4aac0983111317e9b6481
+  metadata.gz: 923d77b5cf761e20eccb817d66dd36bec5310842f1216c2b403432bf84bf11fa
+  data.tar.gz: e84b863710db389adf98f1b06783c46e4e4b7797c51889026c62939a3e3ad9a6
 SHA512:
-  metadata.gz: 9e0cca53fa0c55b5577da00780013abf66455259c6c996eee570ab68e910bf589c5cb00661281210d26779bd683a1489914cb45b2a8b8096c7e141399ad16a18
-  data.tar.gz: 3a7869846152c7b902a9fdc08bee13f058dec8ebfa57a9ac4538901d07724e550248d0dae7542f4c62bbc0a917c88127f369cdfa2c19791dad83327052f3f27a
+  metadata.gz: 3ea2f8c543f3e8cbdf55a158bb0033d1711b34b3114ea8ebbccc530d398ac3931e95d3c729be869eac5070dac773edec62e3de1dc94b3c00a4560c6b6a998cbe
+  data.tar.gz: 5672bc7469d4a09a12c85fcd343c8008748ccb6a90f85dc54cfdf7feb9d81721a026aa91a11d555b826159fbe61a528732301cf19ab63470800068faa1971a42

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [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
+
 ## 0.1.6 - 2026-04-28
 
 - Publish best-effort `llm.registry` discovered-model availability events when transport is already loaded.

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/lib/legion/extensions/llm/openai/provider.rb

@@ -9,6 +9,7 @@ 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 if defined?(Legion::Logging::Helper)
 
           class << self
             attr_writer :registry_publisher
@@ -73,6 +74,8 @@ module Legion
             end
           end
 
+          def stream_usage_supported? = true
+
           def api_base
             config.openai_api_base || 'https://api.openai.com'
           end
@@ -92,13 +95,28 @@ module Legion
           def images_url(with: nil, mask: nil) = super
 
           def retrieve_model(model)
+            log.info("Retrieving model: #{model}") if respond_to?(:log)
             connection.get("#{models_url}/#{model}").body
+          rescue StandardError => e
+            if respond_to?(:handle_exception)
+              handle_exception(e, level: :error, handled: true,
+                                  operation: 'retrieve_model')
+            end
+            raise
           end
 
           def list_models
+            log.info('Listing OpenAI models') if respond_to?(:log)
             super.tap do |models|
+              log.info("Discovered #{models.size} OpenAI models") if respond_to?(:log)
               self.class.registry_publisher.publish_models_async(models, readiness: readiness(live: false))
             end
+          rescue StandardError => e
+            if respond_to?(:handle_exception)
+              handle_exception(e, level: :error, handled: true,
+                                  operation: 'list_models')
+            end
+            raise
           end
 
           private

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

@@ -6,6 +6,8 @@ module Legion
       module Openai
         # Builds sanitized lex-llm registry envelopes for OpenAI provider state.
         class RegistryEventBuilder
+          include Legion::Logging::Helper if defined?(Legion::Logging::Helper)
+
           def model_available(model, readiness:)
             registry_event_class.available(
               model_offering(model),
@@ -58,7 +60,11 @@ module Legion
             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
+          rescue StandardError => e
+            if respond_to?(:handle_exception)
+              handle_exception(e, level: :debug, handled: true,
+                                  operation: 'provider_instance')
+            end
             :openai
           end
 

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

@@ -6,6 +6,8 @@ module Legion
       module Openai
         # Best-effort publisher for OpenAI provider availability events.
         class RegistryPublisher
+          include Legion::Logging::Helper if defined?(Legion::Logging::Helper)
+
           APP_ID = 'lex-llm-openai'
 
           def initialize(builder: RegistryEventBuilder.new)
@@ -13,6 +15,7 @@ module Legion
           end
 
           def publish_models_async(models, readiness:)
+            log.info("Publishing #{Array(models).size} model(s) to llm.registry") if respond_to?(:log)
             schedule do
               Array(models).each do |model|
                 publish_event(@builder.model_available(model, readiness:))
@@ -29,10 +32,10 @@ module Legion
               Thread.current.abort_on_exception = false
               yield
             rescue StandardError => e
-              log_publish_failure(e, level: :debug)
+              handle_exception(e, level: :debug, handled: true, operation: 'schedule') if respond_to?(:handle_exception)
             end
           rescue StandardError => e
-            log_publish_failure(e, level: :debug)
+            handle_exception(e, level: :debug, handled: true, operation: 'schedule') if respond_to?(:handle_exception)
             false
           end
 
@@ -41,7 +44,10 @@ module Legion
 
             message_class.new(event:, app_id: APP_ID).publish(spool: false)
           rescue StandardError => e
-            log_publish_failure(e)
+            if respond_to?(:handle_exception)
+              handle_exception(e, level: :warn, handled: true,
+                                  operation: 'publish_event')
+            end
             false
           end
 
@@ -52,7 +58,11 @@ module Legion
             return true unless ::Legion::Transport::Connection.respond_to?(:session_open?)
 
             ::Legion::Transport::Connection.session_open?
-          rescue StandardError
+          rescue StandardError => e
+            if respond_to?(:handle_exception)
+              handle_exception(e, level: :debug, handled: true,
+                                  operation: 'publishing_available?')
+            end
             false
           end
 
@@ -66,7 +76,11 @@ module Legion
 
             require 'legion/extensions/llm/openai/transport/messages/registry_event'
             message_class_defined?
-          rescue LoadError
+          rescue LoadError => e
+            if respond_to?(:handle_exception)
+              handle_exception(e, level: :debug, handled: true,
+                                  operation: 'transport_message_available?')
+            end
             false
           end
 
@@ -77,18 +91,6 @@ module Legion
           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

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Openai
-        VERSION = '0.1.6'
+        VERSION = '0.1.8'
       end
     end
   end

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

@@ -12,6 +12,7 @@ module Legion
       # Openai provider extension namespace.
       module Openai
         extend ::Legion::Extensions::Core if ::Legion::Extensions.const_defined?(:Core, false)
+        extend ::Legion::Logging::Helper if defined?(::Legion::Logging::Helper)
 
         PROVIDER_FAMILY = :openai
 
@@ -39,3 +40,6 @@ end
 
 Legion::Extensions::Llm::Provider.register(Legion::Extensions::Llm::Openai::PROVIDER_FAMILY,
                                            Legion::Extensions::Llm::Openai::Provider)
+if defined?(Legion::Logging::Helper) && Legion::Extensions::Llm::Openai.respond_to?(:log)
+  Legion::Extensions::Llm::Openai.log.info('Registered OpenAI provider for :openai family')
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-openai
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - LegionIO