lex-llm 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5b58678c0d7021662b2ef38d80932bd373e3c462b9d05e1004dfc880b1e6d6f
-  data.tar.gz: 49a88cc742e128df1bd93882585df89e595c9761194da354af6be93bd4bd4c2e
+  metadata.gz: 0ca7422981b9d63c85ebe052990cd12af77c9e625ce7597d67e8161418a94ea3
+  data.tar.gz: 1cd31a58aa6bc9f35a9e8d45c1bed00c05b7dbdcfaaddb81bb29f644787a7703
 SHA512:
-  metadata.gz: 273c724d3b7b2945dea092184c8df80952d6ec0c8c38aefbba966a28de91c43c2862be91ac9e918943a7e2e42b5dde4c7b98826852598c7e82c4dd10bbca26e8
-  data.tar.gz: 68b38d28e88ad07c333ca0f7e94885a3006b1f3fc727f3c2b7206cba5497b42f848927b2d555db5382abac05123b76074572c7ca6834da0de312b2f30fdd3a03
+  metadata.gz: d0de80f09c6820c95b51297bc3a6b0bdebfdaaedb007668c635b670c45668e80c1ed4a9eb0c2cff5db48aef602c1aa4e9f325b734ed63f661fbec4248589aa26
+  data.tar.gz: 8bfed0a1cec4ec06062c6797afed865f7fec9757b7906022dfd04bd9650b2b3bd5bc67c6cda65f3464bc3f8da1c0a59543d573ae30231bcc2874b307a0fb6e85

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.1.9 - 2026-04-30
+
+- Replace Model::Info class with immutable Data.define value object supporting new fields: instance, parameter_count, parameter_size, quantization, size_bytes, modalities_input, modalities_output
+- Add Model::Info.from_hash factory for backward-compatible construction from legacy hash format
+- Add backward-compatible accessors on Model::Info for context_window, max_output_tokens, created_at, knowledge_cutoff, modalities, pricing, type, and legacy capability predicates
+- Add model_allowed? to base Provider with whitelist/blacklist filtering from settings
+- Add multi-host base_url resolution with TLS awareness and reachability probing
+- Add cache tier selection helpers: cache_local_instance?, model_cache_get/set/fetch, cache_instance_key for local vs shared cache routing
+- Add shared transport classes for llm.registry exchange and registry event messages (guarded by defined? for optional legion-transport)
+- Add shared RegistryPublisher parameterized by provider_family for all lex-llm-* gems
+- Add shared RegistryEventBuilder parameterized by provider_family for all lex-llm-* gems
+- Mark Provider.register, .resolve, .for, .providers with @deprecated annotations for future removal in favor of the extension registry
+
+## 0.1.8 - 2026-04-30
+
+- Audit all rescue blocks for handle_exception compliance
+- Add Legion::Logging::Helper to Provider, Chat, and Models for structured exception reporting
+- Replace ad-hoc logger.debug/warn calls in rescue blocks with handle_exception across streaming, chat, models, and provider modules
+- Add require for legion/logging in the main entrypoint
+
 ## 0.1.7 - 2026-04-30
 
 - Add thinking extraction from OpenAI-compatible streaming chunks (reasoning_content, reasoning, think tags)

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

@@ -6,6 +6,7 @@ module Legion
       # Represents a conversation with an AI model
       class Chat
         include Enumerable
+        include Legion::Logging::Helper
 
         attr_reader :model, :messages, :tools, :tool_prefs, :params, :headers, :schema
 
@@ -157,8 +158,8 @@ module Legion
           if @schema && response.content.is_a?(String) && !response.tool_call?
             begin
               response.content = Legion::JSON.parse(response.content, symbolize_names: false)
-            rescue Legion::JSON::ParseError
-              # If parsing fails, keep content as string
+            rescue Legion::JSON::ParseError => e
+              handle_exception(e, level: :warn, handled: true, operation: 'llm.chat.complete')
             end
           end
 

data/lib/legion/extensions/llm/model/info.rb

@@ -4,71 +4,92 @@ module Legion
   module Extensions
     module Llm
       module Model
-        # Information about an AI model's capabilities, pricing, and metadata.
-        class Info
-          attr_reader :id, :name, :provider, :family, :created_at, :context_window, :max_output_tokens,
-                      :knowledge_cutoff, :modalities, :capabilities, :pricing, :metadata
-
-          # Create a default model with assumed capabilities
-          def self.default(model_id, provider)
-            new(
-              id: model_id,
-              name: model_id.tr('-', ' ').capitalize,
-              provider: provider,
-              capabilities: %w[function_calling streaming vision structured_output],
-              modalities: { input: %w[text image], output: %w[text] },
-              metadata: { warning: 'Assuming model exists, capabilities may not be accurate' }
+        Info = Data.define(
+          :id, :name, :provider, :instance, :family,
+          :capabilities, :context_length, :parameter_count,
+          :parameter_size, :quantization, :size_bytes,
+          :modalities_input, :modalities_output, :metadata
+        ) do
+          # rubocop:disable Metrics/ParameterLists, Metrics/PerceivedComplexity
+          def initialize(
+            id:, name: nil, provider: nil, instance: :default,
+            family: nil, capabilities: [], context_length: nil,
+            parameter_count: nil, parameter_size: nil, quantization: nil,
+            size_bytes: nil, modalities_input: [], modalities_output: [],
+            metadata: {}
+          )
+            normalized_family = family.nil? ? nil : family.to_s.downcase.strip
+
+            super(
+              id: id.to_s.strip,
+              name: (name || id).to_s.strip,
+              provider: provider.to_s.downcase.to_sym,
+              instance: (instance || :default).to_s.downcase.to_sym,
+              family: normalized_family,
+              capabilities: normalize_symbols(capabilities),
+              context_length: to_int(context_length),
+              parameter_count: to_int(parameter_count),
+              parameter_size: parameter_size&.to_s&.strip,
+              quantization: quantization&.to_s&.strip,
+              size_bytes: to_int(size_bytes),
+              modalities_input: normalize_symbols(modalities_input),
+              modalities_output: normalize_symbols(modalities_output),
+              metadata: metadata.is_a?(Hash) ? metadata : {}
             )
           end
+          # rubocop:enable Metrics/ParameterLists, Metrics/PerceivedComplexity
 
-          def initialize(data)
-            @id = data[:id]
-            @name = data[:name]
-            @provider = data[:provider]
-            @family = data[:family]
-            @created_at = Utils.to_time(data[:created_at])&.utc
-            @context_window = data[:context_window]
-            @max_output_tokens = data[:max_output_tokens]
-            @knowledge_cutoff = Utils.to_date(data[:knowledge_cutoff])
-            @modalities = Modalities.new(data[:modalities] || {})
-            @capabilities = data[:capabilities] || []
-            @pricing = Pricing.new(data[:pricing] || {})
-            @metadata = data[:metadata] || {}
-          end
+          # ── Capability predicates ─────────────────────────────────────
+
+          def completion? = capabilities.include?(:completion)
+          def embedding?  = capabilities.include?(:embedding)
+          def vision?     = capabilities.include?(:vision)
+          def tools?      = capabilities.include?(:tools)
+          def thinking?   = capabilities.include?(:thinking)
 
           def supports?(capability)
-            capabilities.include?(capability.to_s)
+            capabilities.include?(capability.to_s.downcase.to_sym)
           end
 
-          %w[function_calling structured_output batch reasoning citations streaming].each do |cap|
-            define_method "#{cap}?" do
-              supports?(cap)
-            end
-          end
+          # ── Backward-compatible accessors ─────────────────────────────
+          # These bridge the legacy Model::Info class API used by Models,
+          # OpenAICompatible, and provider gems. They read from metadata
+          # where the old fields were stored.
 
-          def display_name
-            name
+          def context_window
+            context_length || metadata[:context_window]
           end
 
-          def label
-            provider_name = provider_class&.name || provider
-            "#{provider_name} - #{display_name}"
+          def max_output_tokens
+            metadata[:max_output_tokens]
           end
 
           def max_tokens
             max_output_tokens
           end
 
-          def supports_vision?
-            modalities.input.include?('image')
+          def created_at
+            metadata[:created_at]
           end
 
-          def supports_video?
-            modalities.input.include?('video')
+          def knowledge_cutoff
+            metadata[:knowledge_cutoff]
           end
 
-          def supports_functions?
-            function_calling?
+          def modalities
+            Modalities.new(input: modalities_input.map(&:to_s), output: modalities_output.map(&:to_s))
+          end
+
+          def pricing
+            Pricing.new(metadata[:pricing] || {})
+          end
+
+          def display_name
+            name
+          end
+
+          def label
+            "#{provider} - #{display_name}"
           end
 
           def input_price_per_million
@@ -79,13 +100,28 @@ module Legion
             pricing.text_tokens.output
           end
 
-          def provider_class
-            Legion::Extensions::Llm::Provider.resolve provider
+          def supports_vision?
+            vision? || modalities_input.include?(:image)
+          end
+
+          def supports_video?
+            modalities_input.include?(:video)
+          end
+
+          def supports_functions?
+            tools? || capabilities.include?(:function_calling)
+          end
+
+          # Legacy capability predicates (string-based)
+          %w[function_calling structured_output batch reasoning citations streaming].each do |cap|
+            define_method "#{cap}?" do
+              supports?(cap)
+            end
           end
 
           def type
-            output = modalities.output
-            return 'embedding' if output.include?('embeddings')
+            output = modalities_output.map(&:to_s)
+            return 'embedding' if output.include?('embeddings') || embedding?
             return 'moderation' if output.include?('moderation')
             return 'image' if output.include?('image')
             return 'audio' if output.include?('audio')
@@ -94,21 +130,123 @@ module Legion
             'chat'
           end
 
-          def to_h
-            {
-              id: id,
-              name: name,
+          # Factory for assumed-to-exist models without full metadata.
+          def self.default(model_id, provider)
+            new(
+              id: model_id,
+              name: model_id.tr('-', ' ').capitalize,
               provider: provider,
-              family: family,
-              created_at: created_at,
-              context_window: context_window,
-              max_output_tokens: max_output_tokens,
-              knowledge_cutoff: knowledge_cutoff,
-              modalities: modalities.to_h,
-              capabilities: capabilities,
-              pricing: pricing.to_h,
-              metadata: metadata
-            }
+              capabilities: %w[function_calling streaming vision structured_output],
+              modalities_input: %w[text image],
+              modalities_output: %w[text],
+              metadata: { warning: 'Assuming model exists, capabilities may not be accurate' }
+            )
+          end
+
+          # Factory that accepts both legacy and new-style hashes and maps
+          # them to the new struct fields. Handles round-tripping through to_h.
+          def self.from_hash(data)
+            data = data.transform_keys(&:to_sym) if data.is_a?(Hash)
+
+            input_mods, output_mods = extract_modalities(data)
+
+            new(
+              id: data[:id],
+              name: data[:name],
+              provider: data[:provider],
+              instance: data[:instance],
+              family: data[:family],
+              capabilities: data[:capabilities] || [],
+              context_length: data[:context_length] || data[:context_window],
+              parameter_count: data[:parameter_count],
+              parameter_size: data[:parameter_size],
+              quantization: data[:quantization],
+              size_bytes: data[:size_bytes],
+              modalities_input: input_mods,
+              modalities_output: output_mods,
+              metadata: build_metadata(data)
+            )
+          end
+
+          private
+
+          def normalize_symbols(value)
+            Array(value).map { |v| v.to_s.downcase.strip.to_sym }.uniq
+          end
+
+          def to_int(value)
+            return nil if value.nil?
+
+            value.to_i
+          end
+
+          # Class-level helpers for from_hash normalization
+          class << self
+            private
+
+            def extract_modalities(data) # rubocop:disable Metrics/PerceivedComplexity
+              # New-style keys take priority (round-trip from to_h)
+              if data.key?(:modalities_input) || data.key?(:modalities_output)
+                return [Array(data[:modalities_input]), Array(data[:modalities_output])]
+              end
+
+              # Legacy: modalities is a hash or Modalities object
+              modalities_data = data[:modalities]
+              input_mods = if modalities_data.respond_to?(:input)
+                             modalities_data.input
+                           elsif modalities_data.is_a?(Hash)
+                             Array(modalities_data[:input])
+                           else
+                             []
+                           end
+              output_mods = if modalities_data.respond_to?(:output)
+                              modalities_data.output
+                            elsif modalities_data.is_a?(Hash)
+                              Array(modalities_data[:output])
+                            else
+                              []
+                            end
+              [input_mods, output_mods]
+            end
+
+            def build_metadata(data)
+              extra = {}
+              extra[:created_at] = normalize_created_at(data[:created_at]) if data.key?(:created_at)
+              if data.key?(:knowledge_cutoff)
+                extra[:knowledge_cutoff] =
+                  normalize_knowledge_cutoff(data[:knowledge_cutoff])
+              end
+              extra[:max_output_tokens] = data[:max_output_tokens] if data.key?(:max_output_tokens)
+              extra[:pricing] = normalize_pricing(data[:pricing]) if data.key?(:pricing)
+
+              base = data[:metadata] || {}
+              base.merge(extra).compact
+            end
+
+            def normalize_created_at(value)
+              return nil if value.nil?
+              return value if value.is_a?(Time)
+
+              Utils.to_time(value)&.utc
+            rescue StandardError
+              nil
+            end
+
+            def normalize_knowledge_cutoff(value)
+              return nil if value.nil?
+              return value if value.is_a?(Date)
+
+              Utils.to_date(value)
+            rescue StandardError
+              nil
+            end
+
+            def normalize_pricing(value)
+              return nil if value.nil?
+              return value.to_h if value.respond_to?(:to_h)
+
+              value
+            end
           end
         end
       end

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

@@ -35,6 +35,8 @@ module Legion
         ].freeze
 
         class << self
+          include Legion::Logging::Helper
+
           def instance
             @instance ||= new
           end
@@ -49,9 +51,10 @@ module Legion
 
           def read_from_json(file = Legion::Extensions::Llm.config.model_registry_file)
             data = File.exist?(file) ? File.read(file) : '[]'
-            models = Legion::JSON.parse(data, symbolize_names: true).map { |model| Model::Info.new(model) }
+            models = Legion::JSON.parse(data, symbolize_names: true).map { |model| Model::Info.from_hash(model) }
             filter_models(models)
-          rescue Legion::JSON::ParseError
+          rescue Legion::JSON::ParseError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'llm.models.read_from_json')
             []
           end
 
@@ -92,6 +95,8 @@ module Legion
                 result[:models].concat(provider_class.new(config).list_models)
                 result[:fetched_providers] << provider_class.slug
               rescue StandardError => e
+                handle_exception(e, level: :warn, handled: true,
+                                    operation: 'llm.models.fetch_provider_models')
                 result[:failed] << { name: provider_class.name, slug: provider_class.slug, error: e }
               end
             end
@@ -165,14 +170,12 @@ module Legion
               next [] unless provider_slug
 
               (provider_data[:models] || {}).values.map do |model_data|
-                Model::Info.new(models_dev_model_to_info(model_data, provider_slug, provider_key.to_s))
+                Model::Info.from_hash(models_dev_model_to_info(model_data, provider_slug, provider_key.to_s))
               end
             end
             { models: models.reject { |model| model.provider.nil? || model.id.nil? }, fetched: true }
           rescue StandardError => e
-            Legion::Extensions::Llm.logger.warn(
-              "Failed to fetch models.dev (#{e.class}: #{e.message}). Keeping existing."
-            )
+            handle_exception(e, level: :warn, handled: true, operation: 'llm.models.fetch_models_dev')
             {
               models: existing_models.select { |model| model.metadata[:source] == 'models.dev' },
               fetched: false
@@ -264,7 +267,7 @@ module Legion
               if bedrock_model
                 data = bedrock_model.to_h.merge(id: model_id)
                 data[:context_window] = context_override if context_override
-                return Model::Info.new(data)
+                return Model::Info.from_hash(data)
               end
             end
 
@@ -275,7 +278,7 @@ module Legion
             return unless gemini_model
 
             # Return Gemini's models.dev data but with VertexAI as provider
-            Model::Info.new(gemini_model.to_h.merge(provider: 'vertexai'))
+            Model::Info.from_hash(gemini_model.to_h.merge(provider: 'vertexai'))
           end
 
           def index_by_key(models)
@@ -296,7 +299,7 @@ module Legion
             data[:metadata] = provider_model.metadata.merge(data[:metadata] || {})
             data[:capabilities] = (models_dev_model.capabilities + provider_model.capabilities).uniq
             normalize_embedding_modalities(data)
-            Model::Info.new(data)
+            Model::Info.from_hash(data)
           end
 
           def normalize_embedding_modalities(data)
@@ -458,11 +461,11 @@ module Legion
         end
 
         def by_family(family)
-          self.class.new(all.select { |m| m.family == family.to_s })
+          self.class.new(all.select { |m| m.family.to_s == family.to_s })
         end
 
         def by_provider(provider)
-          self.class.new(all.select { |m| m.provider == provider.to_s })
+          self.class.new(all.select { |m| m.provider.to_s == provider.to_s })
         end
 
         def refresh!(remote_only: false)
@@ -477,8 +480,8 @@ module Legion
 
         def find_with_provider(model_id, provider)
           resolved_id = provider_resolved_model_id(Aliases.resolve(model_id, provider), provider)
-          all.find { |m| m.id == resolved_id && m.provider == provider.to_s } ||
-            all.find { |m| m.id == model_id && m.provider == provider.to_s } ||
+          all.find { |m| m.id == resolved_id && m.provider.to_s == provider.to_s } ||
+            all.find { |m| m.id == model_id && m.provider.to_s == provider.to_s } ||
             raise(ModelNotFoundError, "Unknown model: #{model_id} for provider: #{provider}")
         end
 
@@ -504,7 +507,7 @@ module Legion
           return candidates.first if candidates.size == 1
 
           candidates.min_by do |model|
-            index = PROVIDER_PREFERENCE.index(model.provider)
+            index = PROVIDER_PREFERENCE.index(model.provider.to_s)
             index || PROVIDER_PREFERENCE.length
           end
         end

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

@@ -218,14 +218,15 @@ module Legion
             return arguments if arguments.is_a?(Hash)
 
             Legion::JSON.parse(arguments, symbolize_names: false)
-          rescue Legion::JSON::ParseError
+          rescue Legion::JSON::ParseError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.parse_tool_arguments')
             {}
           end
 
           def parse_list_models_response(response, provider, capabilities)
             response.body.fetch('data', []).map do |model|
               critical_capabilities = critical_capabilities_for(capabilities, model)
-              Legion::Extensions::Llm::Model::Info.new(
+              Legion::Extensions::Llm::Model::Info.from_hash(
                 id: model.fetch('id'),
                 name: model['id'],
                 provider: provider,

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

@@ -6,6 +6,7 @@ module Legion
       # Base class for LLM providers.
       class Provider
         include Streaming
+        include Legion::Logging::Helper
 
         attr_reader :config, :connection
 
@@ -131,6 +132,7 @@ module Legion
           response = @connection.get(metadata[:endpoints][:health])
           metadata.merge(ready: configured? && health_ready?(response.body), health: response.body)
         rescue StandardError => e
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.readiness')
           metadata.merge(ready: false, health: { error: e.class.name, message: e.message })
         end
 
@@ -182,6 +184,112 @@ module Legion
           nil
         end
 
+        # ── Model allow-list / deny-list filtering ────────────────────────
+
+        def model_whitelist
+          wl = settings[:model_whitelist] if respond_to?(:settings)
+          Array(wl).map { |p| p.to_s.downcase }
+        end
+
+        def model_blacklist
+          bl = settings[:model_blacklist] if respond_to?(:settings)
+          Array(bl).map { |p| p.to_s.downcase }
+        end
+
+        def model_allowed?(model_name)
+          name = model_name.to_s.downcase
+          wl = model_whitelist
+          bl = model_blacklist
+
+          return false if wl.any? && wl.none? { |p| name.include?(p) }
+          return false if bl.any? && bl.any? { |p| name.include?(p) }
+
+          true
+        end
+
+        # ── Multi-host base_url resolution ────────────────────────────────
+
+        def resolve_base_url
+          urls = Array(config_base_url)
+          @resolve_base_url ||= find_reachable_url(urls) || urls.first
+        end
+
+        def config_base_url
+          respond_to?(:settings) ? settings[:base_url] : nil
+        end
+
+        def find_reachable_url(urls)
+          urls.each do |url|
+            normalized = strip_scheme(url)
+            scheme = tls_enabled? ? 'https' : 'http'
+            full = "#{scheme}://#{normalized}"
+            return full if url_reachable?(full)
+          end
+          nil
+        end
+
+        def strip_scheme(url)
+          url.to_s.sub(%r{^https?://}, '')
+        end
+
+        def url_reachable?(url)
+          require 'uri'
+          require 'socket'
+          uri = URI.parse(url)
+          Socket.tcp(uri.host, uri.port, connect_timeout: 1).close
+          true
+        rescue StandardError
+          false
+        end
+
+        def tls_enabled?
+          tls = respond_to?(:settings) ? settings[:tls] : nil
+          tls.is_a?(Hash) && tls[:enabled] == true
+        end
+
+        # ── Cache helpers with local/shared tier selection ────────────────
+
+        def cache_local_instance?
+          Array(config_base_url).any? do |url|
+            host = url.to_s.downcase
+            host.include?('localhost') || host.include?('127.0.0.1') || host.include?('::1')
+          end
+        end
+
+        def model_cache_get(key)
+          return nil unless defined?(Legion::Cache)
+
+          cache_local_instance? ? local_cache_get(key) : cache_get(key)
+        rescue StandardError
+          nil
+        end
+
+        def model_cache_set(key, value, ttl:)
+          return unless defined?(Legion::Cache)
+
+          cache_local_instance? ? local_cache_set(key, value, ttl: ttl) : cache_set(key, value, ttl: ttl)
+        rescue StandardError => e
+          handle_exception(e, level: :debug, handled: true, operation: 'lex.provider.model_cache_set')
+        end
+
+        def model_cache_fetch(key, ttl:, &)
+          return yield unless defined?(Legion::Cache)
+
+          cache_local_instance? ? local_cache_fetch(key, ttl: ttl, &) : cache_fetch(key, ttl: ttl, &)
+        rescue StandardError
+          yield
+        end
+
+        def cache_instance_key
+          if cache_local_instance?
+            (respond_to?(:instance_id) ? instance_id : :default).to_s
+          else
+            require 'digest'
+            urls = Array(config_base_url).map { |u| strip_scheme(u).downcase.chomp('/') }.sort
+            Digest::SHA256.hexdigest(urls.join('|'))[0, 12]
+          end
+        end
+
         class << self
           def name
             to_s.split('::').last
@@ -223,22 +331,26 @@ module Legion
             configuration_requirements.all? { |req| config.send(req) }
           end
 
+          # @deprecated Use the extension registry instead. Will be removed in 1.0.
           def register(name, provider_class)
             providers[name.to_sym] = provider_class
             Legion::Extensions::Llm::Configuration.register_provider_options(provider_class.configuration_options)
           end
 
+          # @deprecated Use the extension registry instead. Will be removed in 1.0.
           def resolve(name)
             return nil if name.nil?
 
             providers[name.to_sym]
           end
 
+          # @deprecated Use the extension registry instead. Will be removed in 1.0.
           def for(model)
             model_info = Models.find(model)
             resolve model_info.provider
           end
 
+          # @deprecated Use the extension registry instead. Will be removed in 1.0.
           def providers
             @providers ||= {}
           end

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

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Builds sanitized lex-llm registry envelopes for provider state.
+      # Parameterized by `provider_family` so each lex-llm-* gem can reuse this
+      # class without defining its own copy.
+      class RegistryEventBuilder
+        include Legion::Logging::Helper
+
+        attr_reader :provider_family
+
+        def initialize(provider_family:)
+          @provider_family = provider_family.to_s.downcase.to_sym
+        end
+
+        def readiness(readiness)
+          registry_event_class.public_send(
+            readiness[:ready] ? :available : :unavailable,
+            provider_offering(readiness),
+            runtime: runtime_metadata,
+            health: readiness_health(readiness),
+            metadata: readiness_metadata(readiness)
+          )
+        end
+
+        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 provider_offering(readiness)
+          {
+            provider_family: provider_family,
+            provider_instance: provider_instance,
+            transport: :http,
+            model: 'provider-readiness',
+            usage_type: :inference,
+            capabilities: [],
+            health: readiness_health(readiness),
+            metadata: { lex: extension_sym, provider_readiness: true }
+          }
+        end
+
+        def model_offering(model)
+          {
+            provider_family: provider_family,
+            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: extension_sym, model_name: model.name }.compact
+          }
+        end
+
+        def readiness_health(readiness)
+          health = {
+            ready: readiness[:ready] == true,
+            status: readiness[:ready] ? :available : :unavailable,
+            checked: readiness.dig(:health, :checked) != false
+          }
+          add_readiness_error(health, readiness[:health])
+        end
+
+        def add_readiness_error(health, source)
+          error = source.is_a?(Hash) ? source : {}
+          error_class = error[:error] || error['error']
+          error_message = error[:message] || error['message']
+          health[:error_class] = error_class if error_class
+          health[:error] = error_message if error_message
+          health
+        end
+
+        def model_health(readiness)
+          ready = readiness.fetch(:ready, true) == true
+          { ready:, status: ready ? :available : :degraded }
+        end
+
+        def readiness_metadata(readiness)
+          {
+            extension: extension_sym,
+            provider: provider_family,
+            configured: readiness[:configured] == true,
+            live: readiness[:live] == true
+          }
+        end
+
+        def model_metadata(model)
+          { extension: extension_sym, provider: provider_family, model_type: model_type_for(model) }
+        end
+
+        def runtime_metadata
+          { node: provider_instance }
+        end
+
+        def model_limits(model)
+          limits = {}
+          limits[:context_window] = model.context_window if model.respond_to?(:context_window)
+          limits[:max_output_tokens] = model.max_output_tokens if model.respond_to?(:max_output_tokens)
+          limits.compact
+        end
+
+        def usage_type_for(model)
+          model_type_for(model) == 'embedding' ? :embedding : :inference
+        end
+
+        def model_type_for(model)
+          model.respond_to?(:type) ? model.type : 'chat'
+        end
+
+        def extension_sym
+          :"llm_#{provider_family}"
+        end
+
+        def provider_instance
+          configured_node = (::Legion::Settings.dig(:node, :canonical_name) if defined?(::Legion::Settings))
+          value = configured_node.to_s.strip
+          value.empty? ? provider_family : value.to_sym
+        rescue StandardError => e
+          handle_exception(e, level: :debug, handled: true,
+                              operation: "#{provider_family}.registry.provider_instance")
+          provider_family
+        end
+
+        def registry_event_class
+          ::Legion::Extensions::Llm::Routing::RegistryEvent
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Best-effort publisher for LLM provider availability events.
+      # Parameterized by `provider_family` so each lex-llm-* gem can reuse this
+      # class without defining its own copy.
+      class RegistryPublisher
+        include Legion::Logging::Helper
+
+        attr_reader :provider_family
+
+        def initialize(provider_family:, builder: nil)
+          @provider_family = provider_family.to_s.downcase.to_sym
+          @builder = builder || RegistryEventBuilder.new(provider_family: @provider_family)
+        end
+
+        def app_id
+          "lex-llm-#{provider_family}"
+        end
+
+        def publish_readiness_async(readiness)
+          log.info { "publishing readiness event to llm.registry for #{provider_family}" }
+          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 for #{provider_family}" }
+          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
+            handle_exception(e, level: :debug, handled: true,
+                                operation: "#{provider_family}.registry.schedule_thread")
+          end
+        rescue StandardError => e
+          handle_exception(e, level: :debug, handled: true,
+                              operation: "#{provider_family}.registry.schedule")
+          false
+        end
+
+        def publish_event(event)
+          return false unless publishing_available?
+
+          message_class.new(event:, provider_family: provider_family, app_id: app_id).publish(spool: false)
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: true,
+                              operation: "#{provider_family}.registry.publish_event")
+          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 => e
+          handle_exception(e, level: :debug, handled: true,
+                              operation: "#{provider_family}.registry.publishing_available?")
+          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/transport/messages/registry_event'
+          message_class_defined?
+        rescue LoadError => e
+          handle_exception(e, level: :debug, handled: true,
+                              operation: "#{provider_family}.registry.transport_load")
+          false
+        end
+
+        def message_class_defined?
+          defined?(::Legion::Extensions::Llm::Transport::Messages::RegistryEvent)
+        end
+
+        def message_class
+          ::Legion::Extensions::Llm::Transport::Messages::RegistryEvent
+        end
+      end
+    end
+  end
+end

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

@@ -91,8 +91,8 @@ module Legion
           buffer << chunk
           error_data = Legion::JSON.parse(buffer, symbolize_names: false)
           handle_parsed_error(error_data, env)
-        rescue Legion::JSON::ParseError
-          Legion::Extensions::Llm.logger.debug { "Accumulating error chunk: #{chunk}" }
+        rescue Legion::JSON::ParseError => e
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.streaming.handle_failed_response')
         end
 
         def handle_sse(chunk, parser, env, &)
@@ -112,7 +112,7 @@ module Legion
 
           handle_parsed_error(parsed, env)
         rescue Legion::JSON::ParseError => e
-          Legion::Extensions::Llm.logger.debug { "Failed to parse data chunk: #{e.message}" }
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.streaming.handle_data')
         end
 
         def handle_error_event(data, env)
@@ -123,7 +123,7 @@ module Legion
           error_data = Legion::JSON.parse(data, symbolize_names: false)
           [500, error_data['message'] || 'Unknown streaming error']
         rescue Legion::JSON::ParseError => e
-          Legion::Extensions::Llm.logger.debug { "Failed to parse streaming error: #{e.message}" }
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.streaming.parse_streaming_error')
           [500, "Failed to parse error: #{data}"]
         end
 
@@ -133,11 +133,11 @@ module Legion
           ErrorMiddleware.parse_error(provider: self, response: error_response)
         end
 
-        def parse_error_from_json(data, env, error_message)
+        def parse_error_from_json(data, env, _error_message)
           parsed_data = Legion::JSON.parse(data, symbolize_names: false)
           handle_parsed_error(parsed_data, env)
         rescue Legion::JSON::ParseError => e
-          Legion::Extensions::Llm.logger.debug { "#{error_message}: #{e.message}" }
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.streaming.parse_error_from_json')
         end
 
         def build_stream_error_response(parsed_data, env, status)

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+return unless defined?(Legion::Transport::Exchange)
+
+module Legion
+  module Extensions
+    module Llm
+      module Transport
+        module Exchanges
+          # Shared topic exchange for LLM provider availability events.
+          # All lex-llm-* providers publish to the same `llm.registry` exchange.
+          class LlmRegistry < ::Legion::Transport::Exchange
+            def exchange_name
+              'llm.registry'
+            end
+
+            def default_type
+              'topic'
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+return unless defined?(Legion::Transport::Message)
+
+require_relative '../exchanges/llm_registry'
+
+module Legion
+  module Extensions
+    module Llm
+      module Transport
+        module Messages
+          # Publishes lex-llm RegistryEvent envelopes to the shared llm.registry exchange.
+          # Accepts a `provider_family` for constructing the app_id and routing key.
+          class RegistryEvent < ::Legion::Transport::Message
+            def initialize(event:, provider_family: nil, **options)
+              @provider_family = provider_family
+              super(**event.to_h.merge(options))
+            end
+
+            def exchange
+              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] || "lex-llm-#{@provider_family || 'unknown'}"
+            end
+
+            def persistent # rubocop:disable Naming/PredicateMethod
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.1.7'
+      VERSION = '0.1.9'
     end
   end
 end

data/lib/legion/extensions/llm.rb

@@ -8,6 +8,7 @@ require 'faraday'
 require 'faraday/multipart'
 require 'faraday/retry'
 require 'legion/json'
+require 'legion/logging'
 require 'logger'
 require 'marcel'
 require 'ruby_llm/schema'
@@ -30,6 +31,8 @@ module Legion
         'ui' => 'UI'
       )
       loader.ignore("#{__dir__}/llm/version.rb")
+      loader.ignore("#{__dir__}/llm/transport/exchanges")
+      loader.ignore("#{__dir__}/llm/transport/messages")
       loader.push_dir("#{__dir__}/llm", namespace: self)
       loader.setup
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.9
 platform: ruby
 authors:
 - LegionIO
@@ -225,6 +225,8 @@ files:
 - lib/legion/extensions/llm/provider.rb
 - lib/legion/extensions/llm/provider/open_ai_compatible.rb
 - lib/legion/extensions/llm/provider_settings.rb
+- lib/legion/extensions/llm/registry_event_builder.rb
+- lib/legion/extensions/llm/registry_publisher.rb
 - lib/legion/extensions/llm/routing.rb
 - lib/legion/extensions/llm/routing/lane_key.rb
 - lib/legion/extensions/llm/routing/model_offering.rb
@@ -237,7 +239,9 @@ files:
 - lib/legion/extensions/llm/tool.rb
 - lib/legion/extensions/llm/tool_call.rb
 - lib/legion/extensions/llm/transcription.rb
+- lib/legion/extensions/llm/transport/exchanges/llm_registry.rb
 - lib/legion/extensions/llm/transport/fleet_lane.rb
+- lib/legion/extensions/llm/transport/messages/registry_event.rb
 - lib/legion/extensions/llm/utils.rb
 - lib/legion/extensions/llm/version.rb
 homepage: https://github.com/LegionIO/lex-llm