lex-llm 0.5.3 → 0.6.2

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

@@ -10,6 +10,10 @@ module Legion
           @data = hash.transform_keys(&:to_sym)
         end
 
+        def to_h
+          @data.dup
+        end
+
         def respond_to_missing?(name, include_private = false)
           @data.key?(name.to_sym) || super
         end
@@ -31,6 +35,46 @@ module Legion
         include Legion::Cache::Helper
 
         MODEL_DETAIL_CACHE_SCHEMA_VERSION = 2
+        CAPABILITY_CONFIG_KEYS = %i[
+          capabilities
+          enable_completion
+          enable_embedding
+          enable_embeddings
+          enable_streaming
+          enable_tools
+          enable_functions
+          enable_function_calling
+          enable_thinking
+          enable_reasoning
+          enable_vision
+          enable_structured_output
+          enable_moderation
+          enable_image
+          enable_images
+          enable_image_generation
+          enable_audio_transcription
+          enable_audio_speech
+          enable_audio_generation
+          completion_flag
+          embedding_flag
+          embeddings_flag
+          streaming_flag
+          tool_flag
+          tools_flag
+          functions_flag
+          function_calling_flag
+          thinking_flag
+          reasoning_flag
+          vision_flag
+          structured_output_flag
+          moderation_flag
+          image_flag
+          images_flag
+          image_generation_flag
+          audio_transcription_flag
+          audio_speech_flag
+          audio_generation_flag
+        ].freeze
 
         attr_reader :config, :connection
 
@@ -96,6 +140,7 @@ module Legion
 
         def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, thinking: nil,
                      tool_prefs: nil, &)
+          enforce_model_allowed!(model)
           normalized_temperature = maybe_normalize_temperature(temperature, model)
           log_provider_request(
             messages: messages,
@@ -144,11 +189,14 @@ module Legion
 
           provider_health = health(live:)
           @cached_offerings = Array(list_models(live:, **filters)).filter_map do |model|
+            publish_discovered_model_to_registry(model, provider_health:, live:)
             next unless model_matches_filters?(model, filters)
             next unless model_allowed?(model.id)
 
+            log.debug("[#{slug}] instance=#{provider_instance_id} action=model_discovered model=#{model.id} family=#{model.family}")
             offering_from_model(model, health: provider_health)
           end
+          log.info("[#{slug}] instance=#{provider_instance_id} action=discover_complete model_count=#{Array(@cached_offerings).size}")
           @cached_offerings
         rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
           log.warn("[#{slug}] instance=#{provider_instance_id} unreachable: #{e.message}")
@@ -157,17 +205,45 @@ module Legion
           []
         end
 
+        def publish_discovered_model_to_registry(model, provider_health:, live:)
+          publisher = discovery_registry_publisher
+          return unless publisher.respond_to?(:publish_models_async)
+
+          publisher.publish_models_async([model], readiness: discovery_registry_readiness(provider_health, live:))
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.publish_discovered_model')
+        end
+
+        def discovery_registry_publisher
+          return unless self.class.respond_to?(:registry_publisher)
+
+          self.class.registry_publisher
+        rescue StandardError
+          nil
+        end
+
+        def discovery_registry_readiness(provider_health, live:)
+          {
+            provider: slug.to_sym,
+            configured: configured?,
+            ready: provider_health[:ready] == true,
+            live: live,
+            health: provider_health
+          }
+        end
+
         def health(live: false)
           readiness_data = readiness(live:)
           raw_health = readiness_data[:health] || readiness_data['health'] || {}
           status = health_status(readiness_data, raw_health)
+          latency_ms = (raw_health[:latency_ms] || raw_health['latency_ms'] if raw_health.is_a?(Hash))
           {
             provider: slug.to_sym,
             instance_id: provider_instance_id,
             status:,
             ready: readiness_data[:ready] == true || readiness_data['ready'] == true,
             circuit_state: status == 'healthy' ? 'closed' : 'open',
-            latency_ms: raw_health[:latency_ms] || raw_health['latency_ms'],
+            latency_ms: latency_ms,
             raw: raw_health
           }.compact
         rescue StandardError => e
@@ -184,6 +260,7 @@ module Legion
         end
 
         def embed(text:, model:, dimensions: nil, params: {}, headers: {})
+          enforce_model_allowed!(model)
           payload = Utils.deep_merge(render_embedding_payload(text, model:, dimensions:), params)
           response = @connection.post(embedding_url(model:), payload) do |req|
             req.headers = headers.merge(req.headers) unless headers.empty?
@@ -192,12 +269,14 @@ module Legion
         end
 
         def moderate(input, model:)
+          enforce_model_allowed!(model)
           payload = render_moderation_payload(input, model:)
           response = @connection.post moderation_url, payload
           parse_moderation_response(response, model:)
         end
 
         def paint(prompt, model:, size:, with: nil, mask: nil, params: {}) # rubocop:disable Metrics/ParameterLists
+          enforce_model_allowed!(model)
           validate_paint_inputs!(with:, mask:)
           payload = render_image_payload(prompt, model:, size:, with:, mask:, params:)
           response = @connection.post images_url(with:, mask:), payload
@@ -334,20 +413,44 @@ module Legion
 
         # ── Model allow-list / deny-list filtering ────────────────────────
 
+        # Resolve model_whitelist with specificity cascade:
+        # 1. Instance-level  (config.model_whitelist — extensions.llm.<provider>.instances.<id>.model_whitelist)
+        # 2. Provider-level  (extensions.llm.<provider>.model_whitelist)
+        # 3. Global          (extensions.llm.model_whitelist)
+        # Returns the first non-nil, non-empty value found.
         def model_whitelist
           wl = config.model_whitelist if config.respond_to?(:model_whitelist)
-          wl ||= settings[:model_whitelist] if respond_to?(:settings) && settings.is_a?(Hash)
+          wl ||= instance_setting(:model_whitelist)
           wl ||= runtime_provider_setting(:model_whitelist)
+          wl ||= global_llm_setting(:model_whitelist)
           Array(wl).map { |p| p.to_s.downcase }
         end
 
+        # Resolve model_blacklist with the same specificity cascade as model_whitelist.
         def model_blacklist
           bl = config.model_blacklist if config.respond_to?(:model_blacklist)
-          bl ||= settings[:model_blacklist] if respond_to?(:settings) && settings.is_a?(Hash)
+          bl ||= instance_setting(:model_blacklist)
           bl ||= runtime_provider_setting(:model_blacklist)
+          bl ||= global_llm_setting(:model_blacklist)
           Array(bl).map { |p| p.to_s.downcase }
         end
 
+        # Pull a setting from the instance-level settings hash (if available),
+        # distinct from the config object which is a HashConfig wrapper.
+        def instance_setting(key)
+          config_hash =
+            if instance_variable_defined?(:@settings)
+              @settings
+            elsif respond_to?(:settings)
+              settings
+            else
+              config
+            end
+          config_hash = config_hash.to_h if config_hash.respond_to?(:to_h)
+          config_hash.is_a?(Hash) ? (config_hash[key] || config_hash[key.to_s]) : nil
+        end
+
+        # Provider-level setting: extensions.llm.<provider>.<key>
         def runtime_provider_setting(key)
           return nil unless defined?(Legion::Settings)
 
@@ -363,10 +466,47 @@ module Legion
           nil
         end
 
+        # Global LLM setting: extensions.llm.<key> (lowest specificity)
+        def global_llm_setting(key)
+          return nil unless defined?(Legion::Settings)
+
+          llm_conf = Legion::Settings.dig(:extensions, :llm)
+          llm_conf.is_a?(Hash) ? llm_conf[key] : nil
+        rescue StandardError
+          nil
+        end
+
         def model_allowed?(model_name)
-          name = model_name.to_s.downcase
           wl = model_whitelist
           bl = model_blacklist
+          allowed = self.class.policy_allows?(model_name, whitelist: wl, blacklist: bl)
+
+          unless allowed
+            reason_parts = []
+            reason_parts << 'whitelist' if wl.any?
+            reason_parts << 'blacklist' if bl.any?
+            reason_str = reason_parts.empty? ? 'policy' : reason_parts.join(',')
+            policy_src = if wl.any?
+                           "wl=[#{wl.first(5).join(',')}#{',...' if wl.size > 5}]"
+                         else
+                           'no-whitelist'
+                         end
+            log.debug("[#{self.class.slug}] action=model_rejected name=#{model_name} reason=#{reason_str} #{policy_src}")
+          end
+
+          allowed
+        end
+
+        # Single source of truth for model-policy matching, usable both at runtime
+        # (instance #model_allowed?) and at instance-config build time (provider
+        # extensions choosing a default_model that does not violate the policy).
+        # Substring, case-insensitive: a whitelist permits models containing any
+        # pattern; a blacklist denies models containing any pattern; whitelist is
+        # applied before blacklist. Empty list = no restriction from that side.
+        def self.policy_allows?(model_name, whitelist: [], blacklist: [])
+          name = model_name.to_s.downcase
+          wl = Array(whitelist).map { |p| p.to_s.downcase }
+          bl = Array(blacklist).map { |p| p.to_s.downcase }
 
           return false if wl.any? && wl.none? { |p| name.include?(p) }
           return false if bl.any? && bl.any? { |p| name.include?(p) }
@@ -374,6 +514,65 @@ module Legion
           true
         end
 
+        # Effective whitelist/blacklist for an instance config at build time
+        # (before provider instance exists). Same specificity cascade:
+        # 1. Per-instance  (config hash — extensions.llm.<provider>.instances.<id>.model_whitelist)
+        # 2. Provider-level (extensions.llm.<provider>.model_whitelist)
+        # 3. Global        (extensions.llm.model_whitelist)
+        def self.model_policy(config, provider_family)
+          cfg = config.is_a?(Hash) ? config : {}
+          provider_conf = CredentialSources.setting(:extensions, :llm, provider_family)
+          provider_conf = {} unless provider_conf.is_a?(Hash)
+          global_conf = (::Legion::Settings.dig(:extensions, :llm) if defined?(::Legion::Settings))
+          global_conf = {} unless global_conf.is_a?(Hash)
+
+          {
+            whitelist: resolve_policy_value(cfg, provider_conf, global_conf, :model_whitelist),
+            blacklist: resolve_policy_value(cfg, provider_conf, global_conf, :model_blacklist)
+          }
+        end
+
+        # Resolve a single policy value with instance > provider > global precedence.
+        def self.resolve_policy_value(cfg, provider_conf, global_conf, key)
+          # Instance-level
+          val = cfg[key] || cfg[key.to_s]
+          return val if val && !val.to_s.empty? && (val.is_a?(Array) ? val.any? : true)
+
+          # Provider-level
+          val = provider_conf[key] || provider_conf[key.to_s]
+          return val if val && !val.to_s.empty? && (val.is_a?(Array) ? val.any? : true)
+
+          # Global
+          global_conf[key] || global_conf[key.to_s]
+        end
+
+        # Choose a default_model that never violates the model policy: prefer an
+        # explicitly-configured default when permitted; else a provider fallback when
+        # permitted; else nil, so routing resolves an allowed discovered model rather
+        # than forcing a policy-forbidden default. Keeps a whitelist/blacklist
+        # authoritative over any hardcoded provider default.
+        def self.policy_safe_default_model(configured:, fallback:, whitelist: [], blacklist: [])
+          return configured if configured && !configured.to_s.empty? &&
+                               policy_allows?(configured, whitelist:, blacklist:)
+          return fallback if fallback && !fallback.to_s.empty? &&
+                             policy_allows?(fallback, whitelist:, blacklist:)
+
+          nil
+        end
+
+        # Compliance guard: refuse to dispatch any request for a model excluded by
+        # the configured model_whitelist / model_blacklist. Invoked at every
+        # dispatch entry point (the last line before the model API call) so a
+        # denied model can never reach a provider API, regardless of caller. Fail
+        # closed — raises rather than silently routing elsewhere.
+        def enforce_model_allowed!(model_name)
+          return if model_allowed?(model_name)
+
+          log.warn("[#{slug}] action=model_denied model=#{model_name} instance=#{provider_instance_id} " \
+                   'reason=model_whitelist_or_blacklist')
+          raise ModelNotAllowedError.new(model: model_name, provider: slug)
+        end
+
         # ── Offering defaults ─────────────────────────────────────────────
 
         def offering_transport
@@ -424,7 +623,7 @@ module Legion
           Socket.tcp(uri.host, uri.port, connect_timeout: 1).close
           true
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true, operation: 'llm.provider.url_reachable', url:)
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.url_reachable', url:)
           false
         end
 
@@ -447,7 +646,7 @@ module Legion
 
           cache_local_instance? ? local_cache_get(key) : cache_get(key)
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true, operation: 'llm.provider.model_cache_get', key:)
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.model_cache_get', key:)
           nil
         end
 
@@ -539,6 +738,33 @@ module Legion
 
         private
 
+        def provider_capability_config
+          return {} unless defined?(Legion::Extensions::Llm::CredentialSources)
+
+          raw = Legion::Extensions::Llm::CredentialSources.setting(:extensions, :llm, slug.to_sym)
+          return {} unless raw.respond_to?(:to_h)
+
+          raw.to_h.except(:instances, 'instances')
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: true, operation: "#{slug}.provider_capability_config")
+          {}
+        end
+
+        def instance_capability_config
+          extract_capability_config(config)
+        end
+
+        def model_capability_config(model_id)
+          provider_models = provider_capability_models
+          instance_models = extract_models_config(config)
+          provider_override = provider_models[model_id.to_s] || provider_models[model_id.to_sym] || {}
+          instance_override = instance_models[model_id.to_s] || instance_models[model_id.to_sym] || {}
+          provider_override.to_h.merge(instance_override.to_h)
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: true, operation: "#{slug}.model_capability_config")
+          {}
+        end
+
         def global_prompt_caching_enabled?
           return false unless defined?(Legion::Settings)
 
@@ -577,6 +803,34 @@ module Legion
           raise UnsupportedAttachmentError, "#{name} does not support image references in paint"
         end
 
+        def extract_capability_config(source)
+          return {} unless source
+
+          CAPABILITY_CONFIG_KEYS.each_with_object({}) do |key, result|
+            next unless source.respond_to?(key)
+
+            value = source.public_send(key)
+            result[key] = value unless value.nil?
+          rescue StandardError
+            next
+          end
+        end
+
+        def extract_models_config(source)
+          return {} unless source.respond_to?(:models)
+
+          models = source.models
+          models.respond_to?(:to_h) ? models.to_h : {}
+        rescue StandardError
+          {}
+        end
+
+        def provider_capability_models
+          config = provider_capability_config
+          models = config[:models] || config['models']
+          models.respond_to?(:to_h) ? models.to_h : {}
+        end
+
         def offering_from_model(model, health: {})
           capability_sources = Array(model.capabilities).to_h do |cap|
             [cap.to_sym, { value: true, source: :model_metadata }]
@@ -679,7 +933,11 @@ module Legion
         def health_status(readiness_data, raw_health)
           return 'healthy' if readiness_data[:ready] == true || readiness_data['ready'] == true
 
-          status = raw_health[:status] || raw_health['status'] || raw_health[:state] || raw_health['state']
+          status = if raw_health.is_a?(Hash)
+                     raw_health[:status] || raw_health['status'] || raw_health[:state] || raw_health['state']
+                   else
+                     raw_health
+                   end
           return 'healthy' if %w[ok ready healthy running].include?(status.to_s.downcase)
 
           'unhealthy'

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

@@ -63,12 +63,13 @@ module Legion
         end
 
         def readiness_health(readiness)
+          source = readiness[:health]
           health = {
             ready: readiness[:ready] == true,
             status: readiness[:ready] ? :available : :unavailable,
-            checked: readiness.dig(:health, :checked) != false
+            checked: !source.is_a?(Hash) || source[:checked] != false
           }
-          add_readiness_error(health, readiness[:health])
+          add_readiness_error(health, source)
         end
 
         def add_readiness_error(health, source)
@@ -126,7 +127,7 @@ module Legion
           value = configured_node.to_s.strip
           value.empty? ? provider_family : value.to_sym
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true,
+          handle_exception(e, level: :warn, handled: true,
                               operation: "#{provider_family}.registry.provider_instance")
           provider_family
         end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'concurrent'
+
 module Legion
   module Extensions
     module Llm
@@ -9,6 +11,8 @@ module Legion
       class RegistryPublisher
         include Legion::Logging::Helper
 
+        ASYNC_THREAD_POOL = Concurrent::FixedThreadPool.new(1, fallback_policy: :caller_runs)
+
         attr_reader :provider_family
 
         def initialize(provider_family:, builder: nil)
@@ -21,12 +25,12 @@ module Legion
         end
 
         def publish_readiness_async(readiness)
-          log.info { "publishing readiness event to llm.registry for #{provider_family}" }
+          log.debug { "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}" }
+          log.debug { "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:))
@@ -39,15 +43,14 @@ module Legion
         def schedule(&)
           return false unless publishing_available?
 
-          Thread.new do
-            Thread.current.abort_on_exception = false
+          ASYNC_THREAD_POOL.post do
             yield
           rescue StandardError => e
-            handle_exception(e, level: :debug, handled: true,
+            handle_exception(e, level: :warn, handled: true,
                                 operation: "#{provider_family}.registry.schedule_thread")
           end
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true,
+          handle_exception(e, level: :warn, handled: true,
                               operation: "#{provider_family}.registry.schedule")
           false
         end
@@ -70,7 +73,7 @@ module Legion
 
           ::Legion::Transport::Connection.session_open?
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true,
+          handle_exception(e, level: :warn, handled: true,
                               operation: "#{provider_family}.registry.publishing_available?")
           false
         end
@@ -86,7 +89,7 @@ module Legion
           require 'legion/extensions/llm/transport/messages/registry_event'
           message_class_defined?
         rescue LoadError => e
-          handle_exception(e, level: :debug, handled: true,
+          handle_exception(e, level: :warn, handled: true,
                               operation: "#{provider_family}.registry.transport_load")
           false
         end

data/lib/legion/extensions/llm/routing/model_offering.rb

@@ -159,21 +159,14 @@ module Legion
           end
 
           def normalize_capabilities(value)
-            Array(value).compact.each_with_object([]) do |item, normalized|
-              symbol = item.to_s.downcase.strip.to_sym
-              next if symbol.to_s.empty?
-
-              normalized << symbol
-              alias_symbol = CAPABILITY_ALIASES[symbol]
-              normalized << alias_symbol if alias_symbol
-            end.uniq
+            Legion::Extensions::Llm::Capabilities.normalize(value)
           end
 
           def normalize_capability_sources(value)
             normalize_hash(value).to_h do |capability, source_data|
               normalized_source = normalize_hash(source_data)
               [
-                capability.to_s.downcase.tr('-', '_').to_sym,
+                Legion::Extensions::Llm::Capabilities.canonical(capability),
                 { value: normalized_source[:value], source: normalized_source[:source]&.to_sym }.compact
               ]
             end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Taxonomies
+        TIERS           = %i[direct local fleet cloud frontier].freeze
+        TYPES           = %i[inference embedding image audio].freeze
+        CIRCUIT_STATES  = %i[closed half_open open].freeze
+        HEALTH_KEYS     = %i[circuit_state denied available adjustment].freeze
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.5.3'
+      VERSION = '0.6.2'
     end
   end
 end

data/lib/legion/extensions/llm.rb

@@ -36,6 +36,12 @@ module Legion
       #  unqualified constant lookups resolve via Ruby scope.               #
       # ------------------------------------------------------------------ #
 
+      # --- P1 SSOT: taxonomy enums, capability normalization, inventory writer mixin ---
+      require_relative 'llm/taxonomies'
+      require_relative 'llm/capabilities'
+      require_relative 'llm/inventory/scoped_refresher'
+      require_relative 'llm/inventory/capabilities'
+
       # --- Capability resolution policy (no internal deps) ---
       require_relative 'llm/capability_policy'
 

data/spec/legion/extensions/llm/capabilities_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/capabilities'
+
+RSpec.describe Legion::Extensions::Llm::Capabilities do
+  describe '.normalize' do
+    it 'normalizes :function_calling to :tools' do
+      expect(described_class.normalize([:function_calling])).to include(:tools)
+    end
+
+    it 'normalizes :tool_use to :tools' do
+      expect(described_class.normalize([:tool_use])).to include(:tools)
+    end
+
+    it 'passes through unknown capabilities unchanged' do
+      expect(described_class.normalize([:vision])).to include(:vision)
+    end
+
+    it 'returns frozen array' do
+      expect(described_class.normalize([:tools])).to be_frozen
+    end
+
+    it 'handles nil/empty input gracefully' do
+      expect(described_class.normalize(nil)).to eq([])
+      expect(described_class.normalize([])).to eq([])
+    end
+  end
+
+  describe '.include_all?' do
+    it 'returns true when required caps are a subset of available' do
+      expect(described_class.include_all?(%i[tools vision], [:tools])).to be true
+    end
+
+    it 'returns false when a required cap is missing' do
+      expect(described_class.include_all?([:vision], [:tools])).to be false
+    end
+
+    it 'matches :function_calling against :tools via alias (PR #152 I1)' do
+      expect(described_class.include_all?([:function_calling], [:tools])).to be true
+    end
+  end
+
+  describe '.merge' do
+    it 'merges and deduplicates multiple capability sets' do
+      result = described_class.merge([:tools], %i[vision tools])
+      expect(result.count(:tools)).to eq(1)
+    end
+  end
+end