legion-llm 0.9.23 → 0.9.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c8c98a439d2e96bba437e5e8b4bf8c47c01277a4079bd459c7257e2990278c6
-  data.tar.gz: f9344c761ebf18b4c5ab271ac8cb5858ce46f791588ace438726002d2907c70e
+  metadata.gz: 914f95fd880bbb73c043d16612bbf22fc22569455b721fe9052b5ee4c55e83b3
+  data.tar.gz: 0a2f12babcae95cab6c9f2e0ee8b5207c26d998aafcee464d457af7ebea4dc16
 SHA512:
-  metadata.gz: 9574535d0eeca84d522858dd323e8d028994b46b3d3f78a37a8094a4f1a692fbdd68bf24e8a061160b5238a2c3e4f73141e29bf70c6423f18e4b4441937f5417
-  data.tar.gz: 69aa8eccf10beb687b637b7442d9eb8a7bae0d42405fc9cfd47f8c8d5c036b7724df6cb55c10d8264f0701f46f8282f0a44d8622d607a6129a09ab4c39ad2e99
+  metadata.gz: 52a9853e3c2337d19a0e4517d0472143e9aa809dd94363655db76a94ed924041b95b20a1038442053fc8b30f4c035782335a6edc0ad9634cb17e7f6c59c81f4b
+  data.tar.gz: bd2f8b50e52e0653cedcb44c0c18105c212151b64baab5dd62248a456e917bdae8e8347d83d7c8c4dd535da354f00795d938643e94e95ec03657c03d2bfa33a2

data/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Legion LLM Changelog
 
+## [0.9.29] - 2026-05-16
+
+### Added
+- Routing: generated discovery rules now expose `:tools` capability rules for tool-capable models and normalize provider aliases such as `function_calling`/`functions`.
+
+### Changed
+- Routing: automatic routing honors top-level `llm.tier_order` before routing-specific tier priority settings.
+- Routing: stream requests with injected native tools now require both `streaming` and `tools` model capabilities before selecting a target.
+
+### Fixed
+- Router: required model capabilities filter out non-tool-capable candidates instead of selecting a local model that later rejects tool payloads.
+- Executor: streaming provider calls now use the escalation chain, so provider errors like "does not support tools" can move to the next routed model.
+- Executor: synthetic routing requirements no longer make model-only or explicit-provider requests bypass provider inference or registry defaults.
+
+## [0.9.28] - 2026-05-15
+
+### Added
+- API: `/api/llm/models` now surfaces a static `LegionIO` model (`id: legionio`) as the default auto-routing placeholder.
+
+### Changed
+- Routing: `model: "legionio"` clears explicit provider/model/instance/tier routing and sends the request through the router chain using the configured default intent.
+- Routing: default tier priority now includes `direct` between `local` and `fleet`, and discovery-generated rule scores honor `routing.tier_priority`.
+
+### Fixed
+- Prompt dispatch: provider-inferable model-only calls such as `gpt-5.4` infer the provider instead of pairing the model with `llm.default_provider`.
+- Executor: provider-tier lookup failures are logged and return nil instead of silently defaulting to `:cloud`.
+- LexLLMAdapter: optional content-block accessor fallbacks now capture and debug-log probe errors instead of bare-rescuing them.
+- Auto routing: unresolved `legionio` requests now raise a clear provider error instead of falling back to configured defaults.
+- Routing: model-only requests stay on provider inference while explicit provider/instance/tier requests still get registry defaults without requiring rule routing.
+
+## [0.9.27] - 2026-05-15
+
+### Fixed
+- Router/Executor: provider-scoped instance resolution no longer applies a global `llm.default_instance` to models inferred for another provider; invalid explicit instances now fall back to that provider's registered default instance instead of dispatching to an unregistered `provider/instance` pair.
+
+## [0.9.26] - 2026-05-15
+
+### Fixed
+- Discovery: `detect_embedding_from_registry` no longer sets `@can_embed = true` when no model is resolvable — adds `first_embedding_model_for(provider, instance)` as a third fallback scanning the discovered model catalog; returns `false` (allowing legacy probe to run) when all three sources yield nothing (#121)
+- RagContext: `positive_integer` no longer raises `TypeError` when `value` is nil or an empty string — adds empty-string guard before `Kernel#Integer()` call so GAIA advisory `context_window: nil` does not abort the inference pipeline (#122)
+- LexLLMAdapter: `text_part_content` now handles Anthropic-style `[{type:"text", text:"…"}]` content block arrays — flattens them to plain text instead of calling `.to_s` on the array, preventing Ruby array literals from leaking into provider prompts (#123)
+- Embeddings/Discovery: `embedding_config_value` and `embedding_settings` now accept the deprecated plural `"embeddings"` key alongside the canonical singular `"embedding"` key, emitting a deprecation warning; fixes silent misconfiguration when users follow doc examples that used the plural spelling (#124)
+
+## [0.9.25] - 2026-05-14
+
+### Added
+- Router: `TIER_RANK` constant — ordered quality ranking of tiers (local → direct → fleet → openai_compat → cloud → frontier)
+- Router: `explicit_resolution` promoted to public — callable directly from executor without `send`
+- Router: `chain_from_defaults` appends all registered fallback providers after the primary so the chain has real alternatives to escalate to (previously single-entry when a default provider was configured)
+- Executor: `run_escalation_resolution` extracted from escalation loop — encapsulates per-attempt dispatch, error rescue, and `tried[]` tracking
+- Executor: `skip_same_tier!` — on `ContextOverflow`, immediately skips all remaining same-tier candidates and routes to a higher-tier provider with a larger context window
+- Executor: lateral vs. escalation move classification in per-attempt log line (`move=lateral` for same-tier, `move=escalation` for higher-tier)
+
+### Fixed
+- Router: `explicit_resolution` handles nil `provider` and nil `tier` without raising `NoMethodError`
+- Executor: `build_fallback_resolutions` sorts lateral alternatives (same-tier) before escalation candidates (higher-tier) — tries other instances at the same tier before promoting to a more expensive one
+- Executor: deduplication in escalation loop is fully safe — `tried` entry is recorded on all rescue paths and on quality failure
+- EscalationChain: `padded_resolutions` no longer pads the list by repeating the last resolution — only real distinct options are tried
+
+## [0.9.24] - 2026-05-14
+
+### Fixed
+- API: `instance` from POST body was silently dropped — never forwarded into routing hash
+- Executor: Gaia advisory tier assignment no longer overrides explicit `provider`+`instance` from caller
+- Executor: `instance` now passed through `routing_resolution_for` to `Router.resolve`/`resolve_chain`
+- Executor: `build_default_escalation_chain` now passes resolved provider/instance/model — previously ignored them and built a full auto chain, routing to vllm/fleet instead of the requested provider
+- Router: `resolve`/`resolve_chain` accept `instance:` param; short-circuit to `explicit_resolution` when `provider` or `instance` is set (not just `tier`)
+- Router: `explicit_resolution` honors caller-supplied instance instead of always pulling from registry; infers tier from `PROVIDER_TIER` when not explicitly given
+
 ## [0.9.23] - 2026-05-13
 
 ### Added

data/CLAUDE.md

@@ -745,6 +745,26 @@ These rules are enforced across all legion-llm code. Violations will be caught i
 - **Advanced signals**: Budget tracking, GPU utilization monitoring, per-tenant spend limits
 - **Fleet auto-scaling**: Dynamic worker pool sizing based on queue depth and latency
 
+## Provider Registration & Model Resolution
+
+- `discover_instances` in each lex-llm-* must include `default_model` in returned config — it flows to registry metadata via `instance_metadata` in `call/providers.rb`
+- Router resolves models via: `registry_entry_for_provider(provider)` → `registry_default_model(entry)` → `metadata[:default_model]`
+- `enabled: false` on an instance config prevents registration — checked in `register_provider_instance`
+- `PROVIDER_DEFAULT_MODEL` does NOT belong in legion-llm — each provider owns its default in its own extension
+- Inventory calls `native_provider_offerings` (full metadata) and excludes `discovery_offerings` for providers with native adapters
+
+## Metering Spool
+
+- Events spool to `~/.legionio/data/spool/metering/events.jsonl` when AMQP transport is unavailable
+- Thread-safe (SPOOL_MUTEX), capped at `settings[:metering][:spool][:max_events]` (default 10K)
+- `flush_spool` publishes spooled events when transport reconnects; `lex-llm-ledger` actor triggers it
+
+## Health Tracker
+
+- `deny_model(provider:, model:, instance:)` — permanently excludes a model from routing (in-memory, until restart)
+- Config errors (ValidationException, AccessDenied, marketplace) trigger deny instead of circuit breaker
+- Discovery connection failures report `:error` to health tracker — circuit opens after threshold
+
 ---
 
 **Maintained By**: Matthew Iverson (@Esity)

data/lib/legion/llm/api/native/inference.rb

@@ -108,7 +108,7 @@ module Legion
                 id:              request_id,
                 messages:        messages,
                 system:          body[:system],
-                routing:         { provider: provider, model: model },
+                routing:         { provider: provider, model: model, instance: body[:instance] }.compact,
                 tools:           tool_declarations,
                 caller:          effective_caller,
                 conversation_id: conversation_id,

data/lib/legion/llm/api/native/models.rb

@@ -9,6 +9,11 @@ module Legion
         module Models
           extend Legion::Logging::Helper
 
+          AUTO_ROUTING_MODEL_ID = 'legionio'
+          AUTO_ROUTING_MODEL_DISPLAY = 'LegionIO'
+          AUTO_ROUTING_OFFERING_ID = 'legionio:auto:inference:legionio'
+          AUTO_ROUTING_CAPABILITIES = %w[auto_routing chat completion json_schema tools].freeze
+
           def self.registered(app)
             log.debug('[llm][api][models] registering model inventory routes')
 
@@ -18,6 +23,7 @@ module Legion
 
               filters = Legion::LLM::API::Native::Models.request_filters(params)
               offerings = Legion::LLM::Inventory.offerings(filters)
+              offerings = Legion::LLM::API::Native::Models.with_auto_routing_offering(offerings, filters)
 
               json_response({
                               models:    Legion::LLM::API::Native::Models.model_summaries(offerings),
@@ -34,7 +40,9 @@ module Legion
               log.debug("[llm][api][models] action=get_model id=#{model_id}")
               require_llm!
 
-              offerings = Legion::LLM::Inventory.offerings(model: model_id)
+              filters = { model: model_id }
+              offerings = Legion::LLM::Inventory.offerings(filters)
+              offerings = Legion::LLM::API::Native::Models.with_auto_routing_offering(offerings, filters)
               halt json_error('model_not_found', "Model '#{model_id}' not found", status_code: 404) unless offerings.any?
 
               json_response({
@@ -84,11 +92,11 @@ module Legion
             summaries = offerings.group_by { |offering| offering[:model] }.map do |model, rows|
               summarize_model(model, rows)
             end
-            summaries.sort_by { |model| model[:id] }
+            summaries.sort_by { |model| [auto_routing_model?(model[:id]) ? 0 : 1, model[:id]] }
           end
 
           def self.summarize_model(model, offerings)
-            {
+            summary = {
               id:             model.to_s,
               types:          offerings.map { |offering| offering[:type].to_s }.uniq.sort,
               providers:      offerings.map { |offering| offering[:provider_family] }.uniq.sort,
@@ -99,6 +107,12 @@ module Legion
               max_context:    offerings.filter_map { |offering| offering.dig(:limits, :context_window) }.max,
               enabled:        offerings.any? { |offering| offering[:enabled] != false }
             }
+            if auto_routing_model?(model)
+              summary[:display_name] = AUTO_ROUTING_MODEL_DISPLAY
+              summary[:auto_route] = true
+              summary[:default] = true
+            end
+            summary
           end
 
           def self.summary(offerings)
@@ -110,6 +124,64 @@ module Legion
                                         .transform_values(&:size)
             }
           end
+
+          def self.with_auto_routing_offering(offerings, filters = {})
+            return offerings unless auto_routing_offering_matches?(filters)
+            return offerings if offerings.any? { |offering| auto_routing_model?(offering[:model]) }
+
+            [auto_routing_offering, *offerings]
+          end
+
+          def self.auto_routing_offering
+            {
+              id:                    AUTO_ROUTING_OFFERING_ID,
+              offering_id:           AUTO_ROUTING_OFFERING_ID,
+              model:                 AUTO_ROUTING_MODEL_ID,
+              display_name:          AUTO_ROUTING_MODEL_DISPLAY,
+              model_family:          'legionio',
+              canonical_model_alias: AUTO_ROUTING_MODEL_ID,
+              type:                  :inference,
+              provider_family:       'legionio',
+              provider_instance:     'auto',
+              instance_id:           'auto',
+              tier:                  :auto,
+              transport:             :internal,
+              enabled:               true,
+              capabilities:          AUTO_ROUTING_CAPABILITIES,
+              limits:                {},
+              health:                { circuit_state: 'available' },
+              metadata:              { auto_route: true, placeholder: true, display_name: AUTO_ROUTING_MODEL_DISPLAY },
+              routing_metadata:      { strategy: 'auto' },
+              source:                'static'
+            }
+          end
+
+          def self.auto_routing_offering_matches?(filters)
+            normalized = request_filters(filters)
+            type = normalized[:type]
+            return false if type && !type.to_s.empty? && type.to_s != 'inference' && type.to_s != 'chat'
+
+            provider = normalized[:provider]
+            return false if provider && !provider.to_s.empty? && !%w[legionio auto].include?(provider.to_s.downcase)
+
+            instance = normalized[:instance_id]
+            return false if instance && !instance.to_s.empty? && !%w[auto legionio].include?(instance.to_s.downcase)
+
+            model = normalized[:model] || normalized[:offering_id]
+            return false if model && !model.to_s.empty? && !auto_routing_model?(model) && model.to_s != AUTO_ROUTING_OFFERING_ID
+
+            family = normalized[:model_family]
+            return false if family && !family.to_s.empty? && family.to_s.downcase != 'legionio'
+
+            capability = normalized[:capability]
+            return false if capability && !AUTO_ROUTING_CAPABILITIES.include?(capability.to_s)
+
+            true
+          end
+
+          def self.auto_routing_model?(model)
+            model.to_s.strip.downcase == AUTO_ROUTING_MODEL_ID
+          end
         end
       end
     end

data/lib/legion/llm/api/native/tiers.rb

@@ -160,8 +160,12 @@ module Legion
           end
 
           def self.tier_priority
+            return Legion::LLM::Router.tier_priority if defined?(Legion::LLM::Router)
+
             routing_config = Legion::LLM::Settings.value(:routing) || {}
-            Array(routing_config[:tier_priority] || %w[local fleet openai_compat cloud frontier])
+            top_level = Legion::LLM::Settings.value(:tier_order, default: nil)
+            Array(top_level || routing_config[:tier_order] || routing_config[:tier_priority] ||
+                  %w[local direct fleet openai_compat cloud frontier])
           end
 
           def self.privacy_mode?
@@ -232,7 +236,8 @@ module Legion
             return 'unknown' unless tracker
 
             tracker.circuit_state(provider_name.to_sym, instance: instance_name.to_sym).to_s
-          rescue StandardError
+          rescue StandardError => e
+            log.debug "[llm][tiers] action=offering_instance_health provider=#{provider_name} instance=#{instance_name} error=#{e.class} — #{e.message}"
             'unknown'
           end
         end

data/lib/legion/llm/call/embeddings.rb

@@ -122,12 +122,21 @@ module Legion
 
           def resolve_provider
             LLM.embedding_provider ||
-              Legion::LLM::Settings.value(:embedding, :provider)&.to_sym
+              embedding_config_value(:provider)&.to_sym
           end
 
           def resolve_model
             LLM.embedding_model ||
-              Legion::LLM::Settings.value(:embedding, :default_model)
+              embedding_config_value(:default_model)
+          end
+
+          def embedding_config_value(key)
+            v = Legion::LLM::Settings.value(:embedding, key)
+            return v unless v.nil?
+
+            plural = Legion::LLM::Settings.value(:embeddings, key)
+            log.warn "[llm][embeddings] settings key \"embeddings.#{key}\" (plural) is deprecated — rename to \"embedding.#{key}\"" unless plural.nil?
+            plural
           end
 
           def coerce_text(value)

data/lib/legion/llm/call/lex_llm_adapter.rb

@@ -239,12 +239,49 @@ module Legion
         end
 
         def text_part_content(part)
-          return unless part.respond_to?(:transform_keys)
+          return part if part.is_a?(String)
 
-          normalized = part.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
-          return unless normalized[:type].to_s == 'text'
+          if part.respond_to?(:transform_keys)
+            normalized = part.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+            return unless normalized[:type].to_s == 'text'
 
-          normalized[:text].to_s
+            return normalized[:text].to_s
+          end
+
+          # Data structs expose named readers (type/text) without necessarily implementing [].
+          # Try named accessor path first; fall through to [] / fetch for plain hashes/structs.
+          if part.respond_to?(:type) || part.respond_to?(:text)
+            type = (part.respond_to?(:type) ? part.type.to_s : '')
+            text = part.respond_to?(:text) ? part.text : nil
+            return text.to_s if type == 'text' || (type.empty? && !text.nil?)
+
+            return nil
+          end
+
+          return unless part.respond_to?(:[]) || part.respond_to?(:fetch)
+
+          type = (defined_method_access(part, :type) || '').to_s
+          text = defined_method_access(part, :text)
+          text.to_s if type == 'text' || (type.empty? && !text.nil?)
+        end
+
+        def defined_method_access(obj, key)
+          # Prefer named accessor (covers Data structs like Types::ContentBlock).
+          key_sym = key.respond_to?(:to_sym) ? key.to_sym : key
+          return obj.public_send(key_sym) if obj.respond_to?(key_sym)
+
+          str_key = key.to_s
+          obj[key]
+        rescue TypeError, NoMethodError, KeyError => e
+          log.debug "[llm][adapter] action=defined_method_access key=#{key} class=#{obj.class} " \
+                    "fallback=string_key error=#{e.class}: #{e.message}"
+          begin
+            obj[str_key]
+          rescue TypeError, NoMethodError, KeyError => fallback_error
+            log.debug "[llm][adapter] action=defined_method_access key=#{key} class=#{obj.class} " \
+                      "fallback=none error=#{fallback_error.class}: #{fallback_error.message}"
+            nil
+          end
         end
 
         def normalize_message_tool_calls(tool_calls)

data/lib/legion/llm/call/providers.rb

@@ -52,7 +52,8 @@ module Legion
           Legion::Extensions::Llm.constants(false).filter_map do |const_name|
             mod = Legion::Extensions::Llm.const_get(const_name, false)
             provider_module?(mod) ? mod : nil
-          rescue NameError
+          rescue NameError => e
+            log.debug "[llm][providers] action=discover_provider_modules const=#{const_name} error=#{e.class} — #{e.message}"
             nil
           end
         end
@@ -120,7 +121,8 @@ module Legion
           return nil unless provider_module&.const_defined?(:PROVIDER_FAMILY, false)
 
           provider_module::PROVIDER_FAMILY
-        rescue StandardError
+        rescue StandardError => e
+          log.debug "[llm][providers] action=safe_provider_family error=#{e.class} — #{e.message}"
           nil
         end
 

data/lib/legion/llm/context/curator.rb

@@ -9,9 +9,15 @@ module Legion
       class Curator
         include Legion::Logging::Helper
 
-        CURATED_KEY    = :__curated__
-        THINKING_OPEN  = '<thinking>'
-        THINKING_CLOSE = '</thinking>'
+        CURATED_KEY = :__curated__
+
+        # All known provider thinking tag variants.
+        # Anthropic: <thinking>…</thinking>
+        # DeepSeek / Qwen / Ollama / vLLM inline: <think>…</think>
+        THINKING_TAG_PAIRS = [
+          ['<thinking>', '</thinking>'],
+          ['<think>',    '</think>']
+        ].freeze
 
         def initialize(conversation_id:)
           @conversation_id = conversation_id
@@ -76,6 +82,8 @@ module Legion
           return msg if content.length <= max_chars
 
           summary = heuristic_tool_summary(content, tool_name_from(msg))
+          log.debug "[llm][curator] action=distill_tool_result conversation_id=#{@conversation_id} " \
+                    "original_chars=#{content.length} summary_chars=#{summary.length}"
           msg.merge(content: summary, curated: true, original_content: content)
         end
 
@@ -89,6 +97,8 @@ module Legion
 
           return msg if stripped == content || stripped.empty?
 
+          log.debug "[llm][curator] action=strip_thinking conversation_id=#{@conversation_id} " \
+                    "original_chars=#{content.length} stripped_chars=#{stripped.length}"
           msg.merge(content: stripped, curated: true, original_content: content)
         end
 
@@ -192,18 +202,27 @@ module Legion
         end
 
         def strip_thinking_tags(text)
-          result = +''
+          result = text
+          THINKING_TAG_PAIRS.each do |open_tag, close_tag|
+            result = strip_tag_pair(result, open_tag, close_tag)
+          end
+          result
+        end
+
+        def strip_tag_pair(text, open_tag, close_tag)
+          out = +''
           pos = 0
           while pos < text.length
-            open_idx = text.index(THINKING_OPEN, pos)
+            open_idx = text.index(open_tag, pos)
             break unless open_idx
 
-            result << text[pos...open_idx]
-            close_idx = text.index(THINKING_CLOSE, open_idx + THINKING_OPEN.length)
-            pos = close_idx ? close_idx + THINKING_CLOSE.length : text.length
+            out << text[pos...open_idx]
+            close_idx = text.index(close_tag, open_idx + open_tag.length)
+            pos = close_idx ? close_idx + close_tag.length : text.length
           end
-          result << text[pos..] if pos < text.length
-          result
+          out << text[pos..] if pos < text.length
+          # Strip any unclosed open tag left at the end (provider died mid-stream).
+          out.sub(/#{Regexp.escape(open_tag)}.*\z/m, '').strip
         end
 
         def curate_message(msg, assistant_response)
@@ -427,7 +446,8 @@ module Legion
         def curated_payload(entry)
           parsed = Legion::JSON.parse(entry[:content].to_s)
           parsed.is_a?(Hash) ? parsed : {}
-        rescue Legion::JSON::ParseError
+        rescue Legion::JSON::ParseError => e
+          log.debug "[llm][curator] action=curated_payload conversation_id=#{@conversation_id} error=#{e.class} — #{e.message}"
           {}
         end
 

data/lib/legion/llm/discovery/rule_generator.rb

@@ -26,7 +26,15 @@ module Legion
           anthropic: :frontier
         }.freeze
 
-        TIER_WEIGHT = { local: 100, fleet: 80, cloud: 60, frontier: 40 }.freeze
+        DEFAULT_TIER_PRIORITY = %i[local direct fleet openai_compat cloud frontier].freeze
+        CAPABILITY_ALIASES = {
+          function_calling: :tools,
+          functions:        :tools,
+          tool:             :tools,
+          tool_use:         :tools,
+          stream:           :streaming,
+          stream_chat:      :streaming
+        }.freeze
 
         module_function
 
@@ -50,9 +58,12 @@ module Legion
                              extract_field(model_data, 'tier')&.to_sym ||
                              tier
                 capability = embedding_model?(model_data) ? :embed : :chat
-                priority = (TIER_WEIGHT[model_tier] || 80) - order
+                priority = tier_weight(model_tier) - order
                 rules << build_rule(provider, instance_id, model_data, capability, model_tier, priority)
-                rules << build_rule(provider, instance_id, model_data, :stream, model_tier, priority) if capability == :chat
+                if capability == :chat
+                  rules << build_rule(provider, instance_id, model_data, :stream, model_tier, priority) if supports_streaming?(model_data)
+                  rules << build_rule(provider, instance_id, model_data, :tools, model_tier, priority) if supports_tools?(model_data)
+                end
                 order += 1
               end
             end
@@ -91,7 +102,7 @@ module Legion
             next unless default_model
 
             model_data = { name: default_model }
-            priority = TIER_WEIGHT[tier] || 40
+            priority = tier_weight(tier)
             rules << build_rule(provider_name, :default, model_data, :chat, tier, priority)
             rules << build_rule(provider_name, :default, model_data, :stream, tier, priority)
           end
@@ -125,17 +136,71 @@ module Legion
           return nil unless model_data.is_a?(Hash)
 
           caps = model_data[:capabilities] || model_data['capabilities']
-          return caps if caps.is_a?(Array) && caps.any?
+          normalized = normalize_capabilities(caps)
+          return normalized if normalized.any?
 
           nil
         end
 
+        def supports_streaming?(model_data)
+          capabilities = extract_capabilities(model_data)
+          return true if capabilities.nil?
+
+          capabilities.include?(:streaming)
+        end
+
+        def supports_tools?(model_data)
+          capabilities = extract_capabilities(model_data)
+          return false if capabilities.nil?
+
+          capabilities.include?(:tools)
+        end
+
+        def normalize_capabilities(capabilities)
+          Array(capabilities).compact.each_with_object([]) do |capability, normalized|
+            next unless capability.respond_to?(:to_s)
+
+            capability_sym = capability.to_s.downcase.strip.to_sym
+            next if capability_sym.to_s.empty?
+
+            normalized << capability_sym
+            alias_sym = CAPABILITY_ALIASES[capability_sym]
+            normalized << alias_sym if alias_sym
+          end.uniq
+        end
+
         def extract_field(model_data, field)
           return nil unless model_data.is_a?(Hash)
 
           model_data[field] || model_data[field.to_s]
         end
 
+        def tier_weight(tier)
+          tier_sym = tier.respond_to?(:to_sym) ? tier.to_sym : tier
+          index = tier_priority.index(tier_sym)
+          return 0 unless index
+
+          (tier_priority.length - index) * 100
+        end
+
+        def tier_priority
+          configured = Legion::LLM::Settings.value(:tier_order, default: nil)
+          configured = Legion::LLM::Settings.value(:routing, :tier_order, default: nil) if blank_array?(configured)
+          configured = Legion::LLM::Settings.value(:routing, :tier_priority, default: DEFAULT_TIER_PRIORITY) if blank_array?(configured)
+          normalized = Array(configured).filter_map do |tier|
+            tier.to_sym if tier.respond_to?(:to_sym)
+          end
+          normalized = DEFAULT_TIER_PRIORITY if normalized.empty?
+          (normalized + DEFAULT_TIER_PRIORITY).uniq
+        rescue StandardError => e
+          handle_exception(e, level: :warn, handled: true, operation: 'rule_generator.tier_priority')
+          DEFAULT_TIER_PRIORITY
+        end
+
+        def blank_array?(value)
+          Array(value).empty?
+        end
+
         def extension_providers
           ext = Legion::Settings[:extensions]
           return ext[:llm] if ext.is_a?(Hash) && ext[:llm].is_a?(Hash)

data/lib/legion/llm/discovery.rb

@@ -254,11 +254,22 @@ module Legion
           end
           return false unless best
 
-          @embedding_provider = best[:provider]
-          @embedding_model = best.dig(:metadata, :default_model) ||
-                             Settings.value(:embedding, :default_model)
-          @embedding_instance = best[:instance]
-          @can_embed = true
+          provider  = best[:provider]
+          instance  = best[:instance]
+          resolved  = best.dig(:metadata, :default_model) ||
+                      embedding_settings[:default_model] ||
+                      first_embedding_model_for(provider, instance)
+
+          unless resolved.to_s.length.positive?
+            log.debug '[llm][discovery] action=detect_embedding_from_registry no_model_resolved ' \
+                      "provider=#{provider} instance=#{instance} — falling through to legacy probe"
+            return false
+          end
+
+          @embedding_provider = provider
+          @embedding_model    = resolved
+          @embedding_instance = instance
+          @can_embed          = true
           @embedding_fallback_chain = build_registry_embedding_fallback(embedding_instances)
 
           log.info "[llm][discovery] embedding available provider=#{@embedding_provider} " \
@@ -280,6 +291,14 @@ module Legion
           end
         end
 
+        def first_embedding_model_for(provider, instance)
+          embedding_caps = %w[embedding embeddings embed].freeze
+          cached_discovered_models.find do |m|
+            m[:provider].to_s == provider.to_s && m[:instance].to_s == instance.to_s &&
+              Array(m[:capabilities]).any? { |c| embedding_caps.include?(c.to_s) }
+          end&.dig(:model)
+        end
+
         def find_embedding_provider(embedding_settings)
           fallback = Legion::LLM::Settings.config_value(embedding_settings, :provider_fallback, %w[ollama bedrock openai])
           provider_models = Legion::LLM::Settings.config_value(embedding_settings, :provider_models, {})
@@ -396,7 +415,17 @@ module Legion
         end
 
         def embedding_settings
-          Legion::LLM::Settings.config_value(llm_settings, :embedding, {})
+          settings = llm_settings
+          result = Legion::LLM::Settings.config_value(settings, :embedding)
+          return result if result.is_a?(Hash) && !result.empty?
+
+          plural = Legion::LLM::Settings.config_value(settings, :embeddings)
+          if plural.is_a?(Hash) && !plural.empty?
+            log.warn '[llm][discovery] settings key "embeddings" (plural) is deprecated — rename to "embedding" (singular)'
+            return plural
+          end
+
+          result || {}
         end
 
         def providers_settings