lex-llm 0.5.4 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a67345a318fe016e8b7c302f08cc335bf25f1e4605a2b16fd9d95a9c9d6ccd04
-  data.tar.gz: a0d2f7b5998b3a70754cb538515e581cb9a17ae7bc38b72de305159cc486edd5
+  metadata.gz: b1d6f2214c5ae415eab2e51068984dfdfb3cc7a35223439573d550d820bf864d
+  data.tar.gz: 23ba380421192e5320c2060fd89e357d26d2cb7958836697970eaa4bba5746fc
 SHA512:
-  metadata.gz: 0e1d43f8bfc296cc15e1389f153adc134baf7dfa051d5604617126bfbfc558ce02416caf24509521d43448fc05bc43b278c8cf4fb6a197465de10af36489ada5
-  data.tar.gz: 0163f3ab169203405a2081c79712343ad5e36ae76bafaa1c703ac20e30ec46324d584bb69da0ebed064a85f9eafcb054ed8f4cb4395789b516607993e3fee53e
+  metadata.gz: e1fb762ee7588f593a75e81b3a6ebc15f131ba74d0d5a54a6cd030d0367c4e41a1a2240c4287c10de4b7bbf25838f27c7a4ae557f75c67aa0b1e481378f752d8
+  data.tar.gz: 9d29438b9d78732887e081b41b7ee792b2459284d654e80e7c70f12be62fcaa585c3e166213530d7bfa57fd09bc5b9de43e12530daf8a38574172452de30a727

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.6.3 - 2026-06-25
+
+### Fixed
+- `ContentBlock.from_hash` rescues `NoMethodError` when content arrays contain corrupted String elements (serialized `#inspect` output from prior storage bugs) — returns a text block instead of crashing with `undefined method 'transform_keys' for an instance of String`.
+- `ContentBlock.from_hash` normalizes `output_text`/`input_text` types to `:text` via `TEXT_TYPE_ALIASES` so Responses API content blocks are recognized by `text?` and extracted by `Message#text`.
+- `ContentBlock#to_s` returns clean text for all text-type blocks; `#inspect` returns a concise debug representation instead of the full 18-field Data.define dump.
+- `Canonical::Message#to_s` delegates to `#text` to prevent Array#inspect leaking struct internals into string contexts.
+
+## 0.6.2 - 2026-06-20
+
+### Fixed
+- Publish one `llm.registry` model-availability event per discovered model from the shared discovery/filter loop before whitelist/blacklist removes blocked models from routable offerings, preserving shadow-model visibility without polluting inventory.
+
+## 0.6.1 - 2026-06-20
+
+### Fixed
+- Canonicalize routing capabilities in `lex-llm` itself: `embedding` is now the standard singular capability, `reasoning` aliases to `thinking`, and image/audio generation aliases collapse to the router vocabulary used by `Model::Info`, `ModelOffering`, and `CapabilityPolicy`.
+- Standardize `enable_*` / `*_flag` capability overrides in the base provider contract, including provider-level, instance-level, and model-level extraction from shared settings handling.
+
+## 0.6.0 - 2026-06-19
+
+### Added
+- **`Inventory::ScopedRefresher` mixin** — uniform `::Every` actor pattern for catalog writers.
+  Each `lex-llm-*` gem includes this and supplies `scope_key` + `compute_lanes_for_scope`. The mixin
+  handles write-then-delete-orphans, auth-failure cooldown circuit, and idempotent re-tick semantics.
+  Requires legion-llm `>= 0.14.0` (`Inventory.write_lane` / `.delete_lane`).
+- Standard `weight: 100` default in provider settings schema (feeds RANKING v2 `lane_weight`).
+- `ScopedRefresher.compose_id(tier:, provider:, instance:, type:, model:, **)` — canonical 5-part
+  lane id composer. All lane id composition must go through this method; never constructed inline.
+- `:fleet` first-class tier in `Taxonomies::TIERS` enum.
+- `Capabilities.normalize` normalization helper (PR #152 I1).
+
 ## 0.5.4 - 2026-06-17
 
 ### Fixed

data/lib/legion/extensions/llm/canonical/content_block.rb

@@ -6,6 +6,7 @@ module Legion
       module Canonical
         # Typed content block with media_type support per G20a.
         # Ports field vocabulary from Legion::LLM::Types::ContentBlock.
+        # rubocop:disable Lint/ConstantDefinitionInBlock -- required for Data.define block scope
         ContentBlock = ::Data.define(
           :type, :text, :data, :source_type, :media_type,
           :detail, :name, :file_id,
@@ -13,6 +14,8 @@ module Legion
           :source, :start_index, :end_index,
           :code, :message, :cache_control
         ) do
+          TEXT_TYPE_ALIASES = %i[text output_text input_text].freeze
+
           # Build a text content block.
           def self.text(content, cache_control: nil)
             new(
@@ -64,12 +67,17 @@ module Legion
           end
 
           # Build from a Hash (raw provider response or deserialized wire payload).
+          # Rescues NoMethodError from corrupted inputs (e.g. String elements from
+          # prior serialization bugs where ContentBlock#inspect leaked into storage).
           def self.from_hash(source)
             return nil if source.nil?
 
             h = source.transform_keys(&:to_sym)
             type_raw = h.delete(:type)
-            h[:type] = type_raw&.to_sym if type_raw
+            if type_raw
+              type_sym = type_raw.to_sym
+              h[:type] = TEXT_TYPE_ALIASES.include?(type_sym) ? :text : type_sym
+            end
 
             new(
               type: h[:type],
@@ -91,6 +99,10 @@ module Legion
               message: h[:message],
               cache_control: h[:cache_control]
             )
+          rescue NoMethodError => e
+            Legion::Logging.log.warn('[canonical][content_block] from_hash received non-Hash input ' \
+                                     "(#{source.class}): #{e.message}")
+            text(source.to_s)
           end
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
@@ -98,9 +110,22 @@ module Legion
             super.compact
           end
 
+          # Human-readable string — prevents #inspect leaking into user-facing output.
+          def to_s
+            return "[tool_use:#{name}]" if type == :tool_use
+            return '[image]' if type == :image
+
+            text.to_s
+          end
+
+          # Concise inspect — prevents raw Data.define dump in Array#inspect output.
+          def inspect
+            "#<ContentBlock:#{type} #{to_s.slice(0, 80).inspect}>"
+          end
+
           # Whether this block carries textual content.
           def text?
-            type == :text
+            TEXT_TYPE_ALIASES.include?(type)
           end
 
           # Whether this block carries thinking/reasoning content.
@@ -120,6 +145,7 @@ module Legion
         end
 
         ContentBlock::CONTENT_BLOCK_TYPES = %i[text thinking tool_use tool_result image audio video].freeze
+        # rubocop:enable Lint/ConstantDefinitionInBlock
       end
     end
   end

data/lib/legion/extensions/llm/canonical/message.rb

@@ -123,6 +123,11 @@ module Legion
             super.compact
           end
 
+          # Human-readable string — prevents #inspect leaking into user-facing output.
+          def to_s
+            text
+          end
+
           # Minimal provider-facing hash (role + text content).
           def to_provider_hash
             { role: role.to_s, content: text }.compact

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Capability vocabulary normalization. Collapses aliases so provider-specific
+      # capability names (:function_calling from Gemini, :tool_use from Anthropic, :tools
+      # from OpenAI) compare as equal. Used on BOTH sides of request_lane capability
+      # filtering (lane declaration and router request payload) — without this, vocabulary
+      # differences silently mismatch and the router returns no lane.
+      module Capabilities
+        CANONICAL = %i[
+          completion embedding streaming tools vision thinking structured_output
+          moderation image audio_transcription audio_speech responses
+        ].freeze
+
+        ALIASES = {
+          function_calling: :tools,
+          tool_use: :tools,
+          tool_calls: :tools,
+          tool: :tools,
+          functions: :tools,
+          stream: :streaming,
+          stream_chat: :streaming,
+          responses_api: :responses,
+          embeddings: :embedding,
+          embed: :embedding,
+          reasoning: :thinking,
+          image_generation: :image,
+          images: :image,
+          audio_generation: :audio_speech,
+          speech_generation: :audio_speech,
+          transcription: :audio_transcription
+        }.freeze
+
+        module_function
+
+        # Normalize a capability list — collapse aliases, downcase, dedup.
+        def normalize(caps, **)
+          Array(caps).compact.each_with_object([]) do |cap, normalized|
+            next unless cap.respond_to?(:to_s)
+
+            sym = cap.to_s.downcase.strip.tr('-', '_').to_sym
+            next if sym.to_s.empty?
+
+            normalized << canonical(sym)
+          end.uniq.freeze
+        end
+
+        def merge(*sets, **)
+          sets.flat_map { |set| normalize(set) }.uniq.freeze
+        end
+
+        def include_all?(available, required, **)
+          required = normalize(required)
+          return true if required.empty?
+
+          normalized = normalize(available)
+          required.all? { |cap| normalized.include?(cap) }
+        end
+
+        def canonical(capability)
+          sym = capability.to_s.downcase.strip.tr('-', '_').to_sym
+          ALIASES.fetch(sym, sym)
+        end
+      end
+    end
+  end
+end

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

@@ -7,26 +7,30 @@ module Legion
       # Returns both a flat capability list and per-capability source metadata.
       module CapabilityPolicy
         OPTIONAL_CAPABILITIES = %i[
-          streaming tools vision embeddings thinking structured_output image audio_transcription audio_speech
+          completion embedding streaming tools vision thinking structured_output
+          moderation image audio_transcription audio_speech
         ].freeze
 
-        BOOLEAN_ALIASES = {
-          enable_streaming: :streaming,
-          enable_tools: :tools,
-          enable_thinking: :thinking,
-          enable_vision: :vision,
-          enable_embeddings: :embeddings,
-          enable_images: :image,
-          streaming_flag: :streaming,
+        BOOLEAN_ALIASES = OPTIONAL_CAPABILITIES.each_with_object({}) do |capability, result|
+          result[:"enable_#{capability}"] = capability
+          result[:"#{capability}_flag"] = capability
+        end.merge(
+          enable_embeddings: :embedding,
+          embeddings_flag: :embedding,
+          enable_functions: :tools,
+          functions_flag: :tools,
           tool_flag: :tools,
-          tools_flag: :tools,
-          thinking_flag: :thinking,
-          vision_flag: :vision,
-          embedding_flag: :embeddings,
-          embeddings_flag: :embeddings,
-          image_flag: :image,
-          images_flag: :image
-        }.freeze
+          enable_function_calling: :tools,
+          function_calling_flag: :tools,
+          enable_reasoning: :thinking,
+          reasoning_flag: :thinking,
+          enable_images: :image,
+          images_flag: :image,
+          enable_image_generation: :image,
+          image_generation_flag: :image,
+          enable_audio_generation: :audio_speech,
+          audio_generation_flag: :audio_speech
+        ).freeze
 
         module_function
 
@@ -88,7 +92,8 @@ module Legion
 
         def normalized_booleans(value)
           normalize_hash(value).each_with_object({}) do |(key, raw), result|
-            capability = key.to_s.downcase.tr('-', '_').to_sym
+            capability = canonical_capability(key)
+            next if capability.nil?
             next unless OPTIONAL_CAPABILITIES.include?(capability)
             next unless [true, false].include?(raw)
 
@@ -96,6 +101,10 @@ module Legion
           end
         end
 
+        def canonical_capability(key)
+          Legion::Extensions::Llm::Capabilities.normalize([key]).first
+        end
+
         def normalize_hash(value)
           return {} unless value.respond_to?(:to_h)
 

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

@@ -90,7 +90,7 @@ module Legion
 
           ::Legion::Settings.dig(*path)
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true, operation: 'llm.credential_sources.setting',
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.credential_sources.setting',
                               path: path.map(&:to_s))
           nil
         end
@@ -117,7 +117,7 @@ module Legion
           end
           true
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true, operation: 'llm.credential_sources.socket_open',
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.credential_sources.socket_open',
                               host:, port:)
           false
         ensure
@@ -135,7 +135,7 @@ module Legion
           response = conn.get(path)
           response.status >= 200 && response.status < 300
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true, operation: 'llm.credential_sources.http_ok',
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.credential_sources.http_ok',
                               path:)
           false
         ensure
@@ -209,7 +209,7 @@ module Legion
           normalized = host.delete_prefix('[').delete_suffix(']')
           %w[localhost 127.0.0.1 ::1].include?(normalized)
         rescue URI::InvalidURIError => e
-          handle_exception(e, level: :debug, handled: true, operation: 'llm.credential_sources.localhost')
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.credential_sources.localhost')
           false
         end
 
@@ -244,7 +244,7 @@ module Legion
             ::JSON.parse(raw, symbolize_names: true)
           end
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true, operation: 'llm.credential_sources.read_json',
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.credential_sources.read_json',
                               path:)
           {}
         end
@@ -267,7 +267,7 @@ module Legion
 
           exp.to_i > Time.now.to_i
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true, operation: 'llm.credential_sources.token_valid')
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.credential_sources.token_valid')
           true
         end
 

data/lib/legion/extensions/llm/fleet/provider_responder.rb

@@ -169,7 +169,7 @@ module Legion
           def safe_publish_error(envelope, error)
             publish_error(envelope, error)
           rescue StandardError => e
-            handle_exception(e, level: :debug, handled: true,
+            handle_exception(e, level: :warn, handled: true,
                                 operation: 'llm.fleet.provider_responder.safe_publish_error',
                                 error_class: error.class.name)
             nil

data/lib/legion/extensions/llm/fleet/settings.rb

@@ -33,7 +33,7 @@ module Legion
             configured << llm if llm.respond_to?(:key?)
             configured
           rescue StandardError => e
-            handle_exception(e, level: :debug, handled: true, operation: 'llm.fleet.settings.configured')
+            handle_exception(e, level: :warn, handled: true, operation: 'llm.fleet.settings.configured')
             []
           end
 
@@ -54,7 +54,7 @@ module Legion
           def safe_fetch(source, key)
             source[key] || source[key.to_s]
           rescue StandardError => e
-            handle_exception(e, level: :debug, handled: true, operation: 'llm.fleet.settings.safe_fetch',
+            handle_exception(e, level: :warn, handled: true, operation: 'llm.fleet.settings.safe_fetch',
                                 key: key.to_s)
             nil
           end

data/lib/legion/extensions/llm/inventory/capabilities.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative '../capabilities'
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # Inventory-side capability normalization. Every per-gem DiscoveryRefresh actor
+        # calls this from `lanes_from_instance` to coerce offering capabilities into a
+        # canonical symbol list before writing the lane to Inventory. Without this
+        # constant, every actor's guard `return [] unless defined?(...)` fires and the
+        # lane is written with `capabilities: []` — even when the operator declared
+        # `enable_tools: true` / `enable_thinking: true` on the instance and the
+        # provider's CapabilityPolicy correctly resolved them in the offering.
+        #
+        # Delegates to Legion::Extensions::Llm::Capabilities so the alias table
+        # (function_calling/tool_use/tool_calls/tool/functions → tools, etc.) stays
+        # in one place.
+        module Capabilities
+          ALIASES = Legion::Extensions::Llm::Capabilities::ALIASES
+
+          module_function
+
+          def normalize(caps, **)
+            Legion::Extensions::Llm::Capabilities.normalize(caps, **)
+          end
+
+          def merge(*sets, **)
+            Legion::Extensions::Llm::Capabilities.merge(*sets, **)
+          end
+
+          def include_all?(available, required, **)
+            Legion::Extensions::Llm::Capabilities.include_all?(available, required, **)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/inventory/scoped_refresher.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Inventory
+        # Mix into a Legion::Extensions::Llm::*::Actors::DiscoveryRefresh class.
+        # The host class must include Legion::Extensions::Helpers::Lex (auto-injects
+        # log / settings / handle_exception / cache_*) and define:
+        #   - #scope_key          — Hash like { provider: :vllm, instance: instance_id }
+        #   - #compute_lanes_for_scope — Array<Hash> lane fact-sheets (no health, no
+        #                               lane_weight — added by Inventory.write_lane).
+        #                               Each lane MUST set :id via compose_id.
+        #   - #credential_hash    — String identifying the auth credential for this scope
+        #                           (used by the auth-failure cooldown circuit).
+        module ScopedRefresher
+          # Auth-failure cooldown TTL (5 minutes). Operator can fix the credential
+          # and lanes auto-recover on the next tick after expiry.
+          AUTH_COOLDOWN_TTL = 300
+
+          # G22: 5-part lane id composed here and ONLY here. All gem writers MUST call
+          # this helper; Inventory.write_lane rejects any lane with a missing or malformed :id.
+          # Accepts a Hash (or keyword splat) with keys: tier, provider_family, instance_id, type, model.
+          def self.compose_id(lane_fields)
+            t  = lane_fields[:tier]
+            pf = lane_fields[:provider_family]
+            ii = lane_fields[:instance_id]
+            ty = lane_fields[:type]
+            mo = lane_fields[:model]
+            "#{t}:#{pf}:#{ii}:#{ty}:#{mo}"
+          end
+
+          # G7 write-then-delete-orphans: write new lanes FIRST (eliminates zero-results
+          # race window), then delete orphans from the previous scope snapshot.
+          def tick(**)
+            return if auth_cooldown_active?
+
+            new_lanes = safe_compute
+            log.info("[llm][scoped_refresher] action=tick provider=#{scope_key[:provider]} lanes_computed=#{new_lanes ? new_lanes.size : 0}")
+            return unless new_lanes&.any?
+
+            written = 0
+            new_lanes.each do |lane_fact|
+              written += 1 if Legion::LLM::Inventory.write_lane(lane: lane_fact)
+            end
+            log.info("[llm][scoped_refresher] action=tick_complete provider=#{scope_key[:provider]} lanes_computed=#{new_lanes.size} lanes_written=#{written}")
+
+            orphans = (@prev_scope_keys || []) - new_lanes.map { it[:id] }
+            orphans.each { |id| Legion::LLM::Inventory.delete_lane(id: id) }
+
+            @prev_scope_keys = new_lanes.map { it[:id] }
+          end
+
+          private
+
+          # Wraps compute_lanes_for_scope with auth-failure cooldown logic.
+          # If a cooldown key is present from a previous auth failure, skips the
+          # compute entirely (no real call burned). On a new auth failure, writes the
+          # cooldown key with AUTH_COOLDOWN_TTL so subsequent ticks also skip.
+          def safe_compute
+            if auth_cooldown_active?
+              log.warn("[llm][scoped_refresher] action=skip reason=auth_cooldown scope=#{scope_key}")
+              return nil
+            end
+            compute_lanes_for_scope
+          rescue NotImplementedError
+            raise
+          rescue StandardError => e
+            if auth_failure?(error: e)
+              Legion::Cache::Local.set(auth_cooldown_key, 1, ttl: AUTH_COOLDOWN_TTL)
+              handle_exception(e, level: :warn, handled: true,
+                                  operation: 'inventory.scoped_refresher.auth_failure',
+                                  scope: scope_key)
+            else
+              handle_exception(e, level: :warn, handled: true,
+                                  operation: 'inventory.scoped_refresher.compute',
+                                  scope: scope_key)
+            end
+            nil
+          end
+
+          def auth_cooldown_active?
+            !Legion::Cache::Local.get(auth_cooldown_key).nil?
+          rescue StandardError
+            false
+          end
+
+          def auth_cooldown_key
+            "llm_auth_failed:#{credential_hash}"
+          end
+
+          # Default auth-failure predicate. Matches HTTP 401/403 status codes and
+          # common auth-error message patterns. Provider gems may override this if
+          # their error shapes differ (e.g. Bedrock's AccessDeniedException).
+          def auth_failure?(error:, **)
+            return true if error.respond_to?(:status_code) && [401, 403].include?(error.status_code)
+            return true if error.respond_to?(:http_status) && [401, 403].include?(error.http_status)
+
+            error.message&.match?(/unauthorized|invalid[_ ]api[_ ]key|invalid[_ ]credentials|forbidden/i)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -35,7 +35,7 @@ module Legion
               provider: provider.to_s.downcase.to_sym,
               instance: (instance || :default).to_s.downcase.to_sym,
               family: normalized_family,
-              capabilities: normalize_symbols(capabilities),
+              capabilities: normalize_capabilities(capabilities),
               context_length: to_int(context_length),
               parameter_count: to_int(parameter_count),
               parameter_size: parameter_size&.to_s&.strip,
@@ -185,6 +185,17 @@ module Legion
 
           private
 
+          def normalize_capabilities(value)
+            raw = Array(value).compact.filter_map do |cap|
+              next unless cap.respond_to?(:to_s)
+
+              sym = cap.to_s.downcase.strip.tr('-', '_').to_sym
+              sym unless sym.to_s.empty?
+            end
+
+            (raw + Legion::Extensions::Llm::Capabilities.normalize(raw)).uniq.freeze
+          end
+
           def normalize_symbols(value)
             Array(value).compact.each_with_object([]) do |item, normalized|
               symbol = item.to_s.downcase.strip.to_sym