lex-llm-azure-foundry 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 188c4529d8f3fb9fcde5080b22e3768fbe713b609fc86efb1264a1e8595c6bb5
-  data.tar.gz: 3826e3576537bb8b1ba7d26bc4f91a061dbf023578bf21b232b90fe7269981c1
+  metadata.gz: 93b2b78c6462da9e924d9de921741cc21a406b68d47879a23c21d26df0478e88
+  data.tar.gz: a91ed47ace39e1a38db76d35a0475fb9332a60213cbf2bd4816a31fe988c58a6
 SHA512:
-  metadata.gz: bec5704b0a9a1465b0e2404e0eeb436ab22026c3112d47a386b561f1b20c58a09326757d9c180aaf47fbc7a108f8f9f3267710639ae779803ff8a1bc17bea751
-  data.tar.gz: 7b88529d1438f19a893e5d34839bea59b0a2c733a1e273ef0dcc0447fe929a7f44374316bd1377270dfd0036c2adcd24f10f6b8b42bd24a5a7ef98acab733c30
+  metadata.gz: 58ec3150d974660d8f573f282fbafa1c2d5716c817453da7124fa2f1125852dacac0d388e34e406535a43178da29c20e3b5ccd00f54d39c3581bde2bc949cd19
+  data.tar.gz: 1f53bccbe6444087c3269de7ad8d1a82ee00681dd4bf0670477b144dfb4994fe3a9f22c1738e067d38c0dcd4e1fe011ca243d6095adbeb28dc50ec9480d4a693

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.1.5] - 2026-04-30
+
+- Audit all rescue blocks for handle_exception compliance across Provider, RegistryPublisher, and RegistryEventBuilder
+- Add Legion::Logging::Helper to AzureFoundry module, RegistryPublisher, and RegistryEventBuilder
+- Add info-level action logging for discover_offerings, health, readiness, list_models, chat, stream, embed, and registry publish
+- Remove custom log_publish_failure in favour of standard handle_exception
+- Update README to reflect current architecture, file map, and observability
+
 ## [0.1.4] - 2026-04-30
 
 - Enable stream_usage_supported? for streaming token usage reporting

data/README.md

@@ -13,11 +13,49 @@ Load it with `require 'legion/extensions/llm/azure_foundry'`.
 - Azure AI Foundry model inference embeddings through `POST /models/embeddings?api-version=...`
 - Azure AI Foundry model info health check through `GET /models/info?api-version=...` when `live: true`
 - Azure OpenAI v1-compatible endpoint support through `/openai/v1/chat/completions` and `/openai/v1/embeddings`
-- deployment-name-preserving routing offerings for hosted Azure deployments
-- explicit `model_family` and `canonical_model_alias` metadata for deployments whose base model cannot be proven from Azure metadata
-- offline-first discovery from configured deployments
-- shared OpenAI-compatible request and response mapping via `Legion::Extensions::Llm::Provider::OpenAICompatible`
-- conservative token-counting metadata when no portable Azure token-counting REST endpoint is configured
+- Deployment-name-preserving routing offerings for hosted Azure deployments
+- Explicit `model_family` and `canonical_model_alias` metadata for deployments whose base model cannot be proven from Azure metadata
+- Offline-first discovery from configured deployments
+- Shared OpenAI-compatible request and response mapping via `Legion::Extensions::Llm::Provider::OpenAICompatible`
+- Conservative token-counting metadata when no portable Azure token-counting REST endpoint is configured
+- Best-effort `llm.registry` event publishing for readiness and model availability via AMQP when transport is available
+
+## Architecture
+
+```
+Legion::Extensions::Llm::AzureFoundry
+├── Provider              # Azure AI Foundry and Azure OpenAI hosted provider surface
+│   └── Capabilities      # Capability predicates inferred from deployment metadata and model naming
+├── RegistryPublisher     # Best-effort async publisher for llm.registry availability events
+├── RegistryEventBuilder  # Builds sanitized lex-llm registry envelopes for provider state
+├── Transport/
+│   ├── Messages::RegistryEvent  # AMQP message for llm.registry events
+│   └── Exchanges::LlmRegistry  # Topic exchange for provider availability events
+└── VERSION
+```
+
+## File Map
+
+| Path | Purpose |
+|------|---------|
+| `lib/legion/extensions/llm/azure_foundry.rb` | Entry point, provider registration, default settings |
+| `lib/legion/extensions/llm/azure_foundry/provider.rb` | Provider implementation with chat, stream, embed, health, readiness, discovery |
+| `lib/legion/extensions/llm/azure_foundry/registry_publisher.rb` | Async registry event publishing with transport guards |
+| `lib/legion/extensions/llm/azure_foundry/registry_event_builder.rb` | Sanitized registry envelope construction |
+| `lib/legion/extensions/llm/azure_foundry/transport/messages/registry_event.rb` | AMQP message class for registry events |
+| `lib/legion/extensions/llm/azure_foundry/transport/exchanges/llm_registry.rb` | Topic exchange definition for llm.registry |
+| `lib/legion/extensions/llm/azure_foundry/version.rb` | `VERSION` constant |
+
+## Observability
+
+Every class and module uses `Legion::Logging::Helper`:
+
+- **AzureFoundry** module: `extend Legion::Logging::Helper`
+- **Provider**: inherits `include Legion::Logging::Helper` from `Legion::Extensions::Llm::Provider`
+- **RegistryPublisher**: `include Legion::Logging::Helper`
+- **RegistryEventBuilder**: `include Legion::Logging::Helper`
+
+All rescue blocks call `handle_exception(e, level:, handled:, operation:)` for structured exception reporting. Key actions emit info-level log lines including discover_offerings, health checks, readiness, model listing, chat, stream, embed, and registry publish operations.
 
 ## API Contract
 
@@ -97,6 +135,8 @@ provider = Legion::Extensions::Llm::AzureFoundry.provider_class.new(Legion::Exte
 provider.discover_offerings(live: false)
 provider.offering_for(model: "gpt-4o-prod", model_family: :openai, canonical_model_alias: "gpt-4o")
 provider.health(live: false)
+provider.readiness(live: false)
+provider.list_models
 provider.chat(messages, model: "gpt-4o-prod")
 provider.stream(messages, model: "gpt-4o-prod") { |chunk| puts chunk.content }
 provider.embed(["hello"], model: "embedding-prod")

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

@@ -144,12 +144,14 @@ module Legion
           def health_url = models_url
 
           def discover_offerings(live: false, **filters)
+            log.info { "discovering offerings live=#{live} from #{api_base}" }
             offerings = configured_deployments.filter_map { |deployment| offering_from_config(deployment) }
             return filter_offerings(offerings, **filters) unless live
 
             filter_offerings(offerings, **filters).map do |offering|
               with_live_metadata(offering)
             rescue StandardError => e
+              handle_exception(e, level: :warn, handled: true, operation: 'azure_foundry.discover_offerings')
               with_health(offering, ready: false, checked: true, error: e)
             end
           end
@@ -172,43 +174,43 @@ module Legion
           end
 
           def health(live: false)
-            baseline = {
-              provider: :azure_foundry,
-              configured: configured?,
-              ready: configured?,
-              live: live,
-              api_base: api_base,
-              surface: surface
-            }
+            log.info { "checking health live=#{live} at #{api_base}" }
+            baseline = health_baseline(live)
             return baseline.merge(checked: false) unless live
 
             response = connection.get(health_url)
             baseline.merge(checked: true, model_info: response.body)
           rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'azure_foundry.health')
             baseline.merge(checked: true, ready: false, error: e.class.name, message: e.message)
           end
 
           def readiness(live: false)
+            log.info { "checking readiness live=#{live} at #{api_base}" }
             health(live: live).merge(local: false, remote: true, endpoints: endpoint_manifest).tap do |metadata|
               self.class.registry_publisher.publish_readiness_async(metadata) if live
             end
           end
 
           def list_models
+            log.info { "listing configured deployment models from #{api_base}" }
             models = discover_offerings(live: false).map { |offering| model_info_from_offering(offering) }
             self.class.registry_publisher.publish_models_async(models, readiness: readiness(live: false))
             models
           end
 
           def chat(messages, model:, temperature: nil, max_tokens: nil, tools: {}, tool_prefs: nil, params: {}) # rubocop:disable Metrics/ParameterLists
+            log.info { "chat request model=#{model} messages=#{messages.size}" }
             complete(messages, tools:, temperature:, model: model_info(model, max_tokens:), params:, tool_prefs:)
           end
 
           def stream(messages, model:, temperature: nil, max_tokens: nil, tools: {}, tool_prefs: nil, params: {}, &) # rubocop:disable Metrics/ParameterLists
+            log.info { "stream request model=#{model} messages=#{messages.size}" }
             complete(messages, tools:, temperature:, model: model_info(model, max_tokens:), params:, tool_prefs:, &)
           end
 
           def embed(text, model:, dimensions: nil, input_type: nil)
+            log.info { "embed request model=#{model}" }
             payload = render_embedding_payload(text, model: model_id(model), dimensions:)
             payload[:input_type] = input_type if input_type
             response = connection.post(embedding_url(model:), payload)
@@ -231,6 +233,17 @@ module Legion
             (config.azure_foundry_surface || MODEL_INFERENCE_SURFACE).to_sym
           end
 
+          def health_baseline(live)
+            {
+              provider: :azure_foundry,
+              configured: configured?,
+              ready: configured?,
+              live: live,
+              api_base: api_base,
+              surface: surface
+            }
+          end
+
           def model_info_from_offering(offering)
             capabilities = offering.capabilities.map(&:to_s)
             Legion::Extensions::Llm::Model::Info.new(

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

@@ -6,6 +6,8 @@ module Legion
       module AzureFoundry
         # Builds sanitized lex-llm registry envelopes for Azure Foundry provider state.
         class RegistryEventBuilder
+          include Legion::Logging::Helper
+
           def readiness(readiness)
             registry_event_class.public_send(
               readiness[:ready] ? :available : :unavailable,
@@ -108,6 +110,12 @@ module Legion
           end
 
           def provider_instance
+            configured_node = (::Legion::Settings.dig(:node, :canonical_name) if defined?(::Legion::Settings))
+            value = configured_node.to_s.strip
+            value.empty? ? :azure_foundry : value.to_sym
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true,
+                                operation: 'azure_foundry.registry.provider_instance')
             :azure_foundry
           end
 

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

@@ -6,6 +6,8 @@ module Legion
       module AzureFoundry
         # Best-effort publisher for Azure Foundry provider availability events.
         class RegistryPublisher
+          include Legion::Logging::Helper
+
           APP_ID = 'lex-llm-azure-foundry'
 
           def initialize(builder: RegistryEventBuilder.new)
@@ -13,10 +15,12 @@ module Legion
           end
 
           def publish_readiness_async(readiness)
+            log.info { 'publishing readiness event to llm.registry' }
             schedule { publish_event(@builder.readiness(readiness)) }
           end
 
           def publish_models_async(models, readiness:)
+            log.info { "publishing #{Array(models).size} model event(s) to llm.registry" }
             schedule do
               Array(models).each do |model|
                 publish_event(@builder.model_available(model, readiness:))
@@ -33,10 +37,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: 'azure_foundry.registry.schedule_thread')
             end
           rescue StandardError => e
-            log_publish_failure(e, level: :debug)
+            handle_exception(e, level: :debug, handled: true, operation: 'azure_foundry.registry.schedule')
             false
           end
 
@@ -45,7 +49,7 @@ module Legion
 
             message_class.new(event:, app_id: APP_ID).publish(spool: false)
           rescue StandardError => e
-            log_publish_failure(e)
+            handle_exception(e, level: :warn, handled: true, operation: 'azure_foundry.registry.publish_event')
             false
           end
 
@@ -56,7 +60,9 @@ module Legion
             return true unless ::Legion::Transport::Connection.respond_to?(:session_open?)
 
             ::Legion::Transport::Connection.session_open?
-          rescue StandardError
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true,
+                                operation: 'azure_foundry.registry.publishing_available?')
             false
           end
 
@@ -70,7 +76,8 @@ module Legion
 
             require 'legion/extensions/llm/azure_foundry/transport/messages/registry_event'
             message_class_defined?
-          rescue LoadError
+          rescue LoadError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'azure_foundry.registry.transport_load')
             false
           end
 
@@ -81,18 +88,6 @@ module Legion
           def message_class
             ::Legion::Extensions::Llm::AzureFoundry::Transport::Messages::RegistryEvent
           end
-
-          def log_publish_failure(error, level: :warn)
-            message = "[lex-llm-azure-foundry] 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/azure_foundry/version.rb

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module AzureFoundry
-        VERSION = '0.1.4'
+        VERSION = '0.1.5'
       end
     end
   end

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

@@ -12,6 +12,7 @@ module Legion
       # Azure AI Foundry provider extension namespace.
       module AzureFoundry
         extend ::Legion::Extensions::Core if ::Legion::Extensions.const_defined?(:Core, false)
+        extend Legion::Logging::Helper
 
         PROVIDER_FAMILY = :azure_foundry
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-azure-foundry
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - LegionIO